Add EnsRainbowBeam app with endpoint for submitting labels

.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,37 @@
+{
+  "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": {
+    "@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,20 @@
+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);
+  return errorResponse(c, { error });
+});
+
+export default app;

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

@@ -0,0 +1,43 @@
+import { z } from "zod";
+
+const ConfigSchema = z.object({
+  PORT: z
+    .string()
+    .optional()
+    .transform((value) => (value === undefined ? 4444 : Number.parseInt(value, 10)))
+    .pipe(z.number().int().min(1).max(65535)),
+  ENSNODE_URL: z.string().url(),
+});
+
+export type Config = {
+  port: number;
+  ensNodeUrl: string;
+};
+
+let cachedConfig: Config | undefined;
+
+/**
+ * Parses the process environment into a {@link Config}.
+ *
+ * Memoized so repeated calls return the same instance and validation only runs once.
+ * Throws (via Zod) if any required env var is missing or invalid.
+ */
+export function getConfig(env: NodeJS.ProcessEnv = process.env): Config {
+  if (cachedConfig) return cachedConfig;
+
+  const parsed = ConfigSchema.parse(env);
+
+  cachedConfig = {
+    port: parsed.PORT,
+    ensNodeUrl: parsed.ENSNODE_URL,
+  };
+
+  return cachedConfig;
+}
+
+/**
+ * Resets the memoized config. Test-only.
+ */
+export function resetConfigCacheForTesting(): void {
+  cachedConfig = undefined;
+}

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" });
+}