Add EnsRainbowBeam app with endpoint for submitting labels

.changeset/config.json

@@ -11,6 +11,7 @@
       "ensrainbow",
       "ensapi",
       "fallback-ensapi",
+      "ens-labels-collector",
       "enssdk",
       "enscli",
       "enskit",

.changeset/ens-labels-collector-app.md

@@ -0,0 +1,11 @@
+---
+"ens-labels-collector": minor
+"ensapi": minor
+"enssdk": minor
+---
+
+Add `apps/ens-labels-collector` and a new `Query.labels` Omnigraph field to support label submission collection (issue [#2003](https://github.com/namehash/ensnode/issues/2003)).
+
+- **New app `apps/ens-labels-collector`**: Hono server exposing `POST /api/submissions` that accepts `{ labels: string[], callerAddress: Address }`, classifies each label against ENSNode's index via the typed `enssdk/omnigraph` client, and emits a structured JSON line per submission to stdout. For each submitted raw label the collector computes both the literal labelhash and (when normalizable to a different value) the normalized labelhash, then assigns one of three statuses per label: `unknown_in_index` (referenced in the index but unhealed), `healed_in_index`, or `absent_from_index`. Persistent storage, batched on-chain emission, and a caller-leaderboard are explicitly deferred to follow-up work; the JSON log shape is the future row shape so adding a sink later is mechanical.
+- **New ENSApi `Query.labels(by: { hashes: [Hex!]! }): [Label!]!`**: batch lookup of `Label` rows by `LabelHash`. Hashes that are not present in the index are simply omitted from the result. Capped at 200 hashes per request.
+- **`enssdk/omnigraph`**: regenerated GraphQL introspection so the new `Query.labels` field is available to the typed `graphql(...)` client.

apps/ens-labels-collector/.env.local.example

@@ -0,0 +1,6 @@
+# Port the ens-labels-collector HTTP server listens on.
+PORT=4444
+
+# Base URL of an ENSNode (ENSApi) instance that exposes the Omnigraph GraphQL endpoint.
+# The collector calls `${ENSNODE_URL}/api/omnigraph` to classify submitted labels.
+ENSNODE_URL=http://localhost:4334

apps/ens-labels-collector/Dockerfile

@@ -0,0 +1,16 @@
+FROM node:24-slim AS base
+ENV PNPM_HOME="/pnpm"
+ENV PATH="$PNPM_HOME:$PATH"
+RUN corepack enable
+WORKDIR /app
+
+FROM base AS deps
+COPY . .
+RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm install --frozen-lockfile
+
+FROM deps AS runner
+WORKDIR /app/apps/ens-labels-collector
+ENV NODE_ENV=production
+EXPOSE 4444
+
+CMD ["pnpm", "start"]

apps/ens-labels-collector/README.md

@@ -0,0 +1,50 @@
+# ens-labels-collector
+
+Receives ENS Label submissions from external callers, classifies each label against ENSNode's
+indexed Label table, and (for now) emits a structured JSON line per submission to stdout.
+
+The app is intentionally minimal; persistent storage, batched on-chain emission, and a
+caller-leaderboard are explicitly deferred to follow-up work (see GitHub issue
+[#2003](https://github.com/namehash/ensnode/issues/2003)). The submission JSONL shape is the
+future row shape so adding a sink later is mechanical.
+
+## Endpoints
+
+- `GET /health` — liveness probe; always returns `{ message: "ok" }`.
+- `POST /api/submissions` — accepts `{ labels: string[], callerAddress: Address }` and
+  responds with per-label classification (`unknown_in_index` / `healed_in_index` /
+  `absent_from_index`).
+
+## How label classification works
+
+For each submitted raw label the collector:
+
+1. Computes `labelhashLiteralLabel(rawLabel)`.
+2. If the label is normalizable AND the normalized form differs from the raw label, also
+   computes `labelhashLiteralLabel(normalizedLabel)`.
+3. Sends every distinct labelhash to ENSNode via the typed `enssdk/omnigraph` client using
+   the `labels(by: { hashes })` query.
+4. Classifies each submitted label:
+   - `unknown_in_index` — at least one of its hashes is present in the index but not yet
+     healed (i.e. `interpreted` is the encoded labelhash form). These are the interesting
+     submissions for future on-chain emission.
+   - `healed_in_index` — at least one of its hashes is present in the index and all
+     returned hits are already healed.
+   - `absent_from_index` — none of its hashes are present in the index.
+
+## Configuration
+
+| Env var | Required | Description |
+|---------|----------|-------------|
+| `PORT` | no (default `4444`) | HTTP listen port. |
+| `ENSNODE_URL` | yes | Base URL of an ENSNode (ENSApi) instance with Omnigraph at `/api/omnigraph`. |
+
+See `.env.local.example` for a local-development template.
+
+## Development
+
+```bash
+pnpm -F ens-labels-collector dev
+pnpm -F ens-labels-collector typecheck
+pnpm -F ens-labels-collector test
+```

apps/ens-labels-collector/package.json

@@ -0,0 +1,38 @@
+{
+  "private": true,
+  "name": "ens-labels-collector",
+  "version": "1.10.1",
+  "type": "module",
+  "description": "Collects ENS Label submissions and classifies them against ENSNode's Omnigraph index",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/namehash/ensnode.git",
+    "directory": "apps/ens-labels-collector"
+  },
+  "homepage": "https://github.com/namehash/ensnode/tree/main/apps/ens-labels-collector",
+  "scripts": {
+    "start": "tsx src/index.ts",
+    "dev": "tsx watch --env-file ./.env.local src/index.ts",
+    "test": "vitest",
+    "lint": "biome check --write .",
+    "lint:ci": "biome ci",
+    "typecheck": "tsgo --noEmit"
+  },
+  "dependencies": {
+    "@ensnode/ensnode-sdk": "workspace:*",
+    "@hono/node-server": "catalog:",
+    "enssdk": "workspace:*",
+    "graphql": "^16.11.0",
+    "hono": "catalog:",
+    "viem": "catalog:",
+    "zod": "catalog:"
+  },
+  "devDependencies": {
+    "@ensnode/shared-configs": "workspace:*",
+    "@types/node": "catalog:",
+    "tsx": "^4.19.3",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  }
+}

apps/ens-labels-collector/src/app.ts

@@ -0,0 +1,21 @@
+import { Hono } from "hono";
+
+import { healthHandler } from "@/handlers/health";
+import { submissionsHandler } from "@/handlers/submissions";
+import { errorResponse } from "@/lib/error-response";
+
+const app = new Hono();
+
+app.get("/health", healthHandler);
+
+app.post("/api/submissions", submissionsHandler);
+
+app.notFound((c) => errorResponse(c, { message: "Not Found", status: 404 }));
+
+app.onError((error, c) => {
+  console.error("[ens-labels-collector] unhandled error", error);
+  // Do not leak the underlying error message to clients; respond with a generic 500.
+  return errorResponse(c, { message: "Internal Server Error", status: 500 });
+});
+
+export default app;

apps/ens-labels-collector/src/config.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+
+import { OptionalPortNumberSchema } from "@ensnode/ensnode-sdk/internal";
+
+/**
+ * Default port for the ens-labels-collector HTTP server. Used when `PORT` env var is unset.
+ */
+export const ENS_LABELS_COLLECTOR_DEFAULT_PORT = 4444;
+
+const ConfigSchema = z.object({
+  PORT: OptionalPortNumberSchema.default(ENS_LABELS_COLLECTOR_DEFAULT_PORT),
+  ENSNODE_URL: z.string().url(),
+});
+
+const parsed = ConfigSchema.parse(process.env);
+
+/**
+ * Process configuration parsed from `process.env` at module load.
+ *
+ * Throws (via Zod) if any required env var is missing or invalid.
+ */
+export const config = {
+  port: parsed.PORT,
+  ensNodeUrl: parsed.ENSNODE_URL,
+};
+
+export type Config = typeof config;

apps/ens-labels-collector/src/handlers/health.ts

@@ -0,0 +1,5 @@
+import type { Context } from "hono";
+
+export function healthHandler(c: Context) {
+  return c.json({ message: "ok" });
+}