Add EnsRainbowBeam app with endpoint for submitting labels

.changeset/config.json

@@ -11,6 +11,7 @@
       "ensrainbow",
       "ensapi",
       "fallback-ensapi",
+      "ensrainbowbeam",
       "enssdk",
       "enscli",
       "enskit",

.changeset/ensapi-omnigraph-labels.md

@@ -0,0 +1,5 @@
+---
+"ensapi": minor
+---
+
+Omnigraph **`Query.labels`** improvements: add a **`LabelHash`** GraphQL scalar (`0x` + 64 lowercase hex, parsed via `parseLabelHash`), rename the input to **`LabelsByLabelHashesInput`** with field **`labelHashes`**, enforce stricter parsing/validation through the scalar layer, normalize mixed-case hex at parse time, cap batch size to **`100`** LabelHashes per request for a round-number limit, and keep development error masking aligned with Yoga defaults while ensuring intentional `GraphQLError`s still surface useful client messages where applicable.

.changeset/ensrainbowbeam-app.md

@@ -0,0 +1,5 @@
+---
+"ensrainbowbeam": minor
+---
+
+Add **`EnsRainbowBeam`** (`apps/ensrainbowbeam`) exposing **`POST /api/discover`**, classifies each submitted label literal against ENSNode via **`labels(by: { labelHashes })`** (with client-side chunking aligned to ENSApi batch limits), emits structured JSON Lines to stdout for future sinks, mirrors other apps’ Dockerfile + Compose service patterns (`docker/services/ensrainbowbeam.yml`), and includes MIT **`LICENSE`** in the app directory ([issue \#2003](https://github.com/namehash/ensnode/issues/2003)).

.changeset/enssdk-omnigraph-codegen.md

@@ -0,0 +1,5 @@
+---
+"enssdk": minor
+---
+
+Regenerate `enssdk/omnigraph` artifacts for the Omnigraph **`LabelHash`** scalar, mapped in `OmnigraphScalars` for typed **`graphql`** documents.

.github/workflows/release.yml

@@ -13,7 +13,7 @@
 #
 # Published artifacts:
 # - NPM packages: @ensnode/* packages published to npm registry with @latest tag
-# - Docker images: ensindexer, ensadmin, ensapi, ensrainbow published to ghcr.io with @latest tag
+# - Docker images: ensindexer, ensadmin, ensapi, ensrainbow, ensrainbowbeam published to ghcr.io with @latest tag
 # - GitHub Release: Created with version tag (e.g., v1.2.3) and autogenerated release notes
 #
 # Version management:
@@ -88,6 +88,7 @@ jobs:
               or .name == "ensadmin"
               or .name == "ensapi"
               or .name == "ensrainbow"
+              or .name == "ensrainbowbeam"
             ))
 
       - name: Filter Published Packages For NPM Packages

.github/workflows/release_preview.yml

@@ -230,7 +230,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        app: [ensindexer, ensadmin, ensapi, ensrainbow]
+        app: [ensindexer, ensadmin, ensapi, ensrainbow, ensrainbowbeam]
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
@@ -342,6 +342,7 @@ jobs:
           docker pull ghcr.io/namehash/ensnode/ensadmin:${{ needs.validate-and-prepare.outputs.docker-tag-base }}-${{ needs.validate-and-prepare.outputs.commit-sha }}
           docker pull ghcr.io/namehash/ensnode/ensapi:${{ needs.validate-and-prepare.outputs.docker-tag-base }}-${{ needs.validate-and-prepare.outputs.commit-sha }}
           docker pull ghcr.io/namehash/ensnode/ensrainbow:${{ needs.validate-and-prepare.outputs.docker-tag-base }}-${{ needs.validate-and-prepare.outputs.commit-sha }}
+          docker pull ghcr.io/namehash/ensnode/ensrainbowbeam:${{ needs.validate-and-prepare.outputs.docker-tag-base }}-${{ needs.validate-and-prepare.outputs.commit-sha }}
           \`\`\`
 
           "

.github/workflows/release_snapshot.yml

@@ -12,7 +12,7 @@
 #
 # Published artifacts:
 # - NPM packages: All @ensnode/* packages published with @next tag
-# - Docker images: ensindexer, ensadmin, ensapi, ensrainbow published with @next tag
+# - Docker images: ensindexer, ensadmin, ensapi, ensrainbow, ensrainbowbeam published with @next tag
 # - No GitHub releases or tags are created
 #
 # Version behavior:
@@ -96,7 +96,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        app: [ensindexer, ensadmin, ensrainbow, ensapi]
+        app: [ensindexer, ensadmin, ensrainbow, ensapi, ensrainbowbeam]
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6

apps/ensapi/src/omnigraph-api/builder.ts

@@ -11,6 +11,7 @@ import type {
   Hex,
   InterpretedLabel,
   InterpretedName,
+  LabelHash,
   Node,
   NormalizedAddress,
   PermissionsId,
@@ -60,6 +61,7 @@ export type BuilderScalars = {
   BigInt: { Input: bigint; Output: bigint };
   Address: { Input: NormalizedAddress; Output: NormalizedAddress };
   Hex: { Input: Hex; Output: Hex };
+  LabelHash: { Input: LabelHash; Output: LabelHash };
   ChainId: { Input: ChainId; Output: ChainId };
   CoinType: { Input: CoinType; Output: CoinType };
   Node: { Input: Node; Output: Node };

apps/ensapi/src/omnigraph-api/schema/label.integration.test.ts

@@ -0,0 +1,121 @@
+import {
+  asInterpretedLabel,
+  encodeLabelHash,
+  type InterpretedLabel,
+  type LabelHash,
+  labelhashInterpretedLabel,
+  parseLabelHash,
+} from "enssdk";
+import { describe, expect, it } from "vitest";
+
+import { LABELS_BY_LABELHASH_MAX } from "@/omnigraph-api/schema/label";
+import { request } from "@/test/integration/graphql-utils";
+import { gql } from "@/test/integration/omnigraph-api-client";
+
+type LabelsByLabelHashResult = {
+  labels: Array<{ hash: LabelHash; interpreted: InterpretedLabel }>;
+};
+
+const LabelsByLabelHash = gql`
+  query LabelsByLabelHash($labelHashes: [LabelHash!]!) {
+    labels(by: { labelHashes: $labelHashes }) {
+      hash
+      interpreted
+    }
+  }
+`;
+
+// 'eth' is always seeded in the devnet fixture as a healed label
+const ETH_LABEL_HASH: LabelHash = labelhashInterpretedLabel(asInterpretedLabel("eth"));
+
+// a LabelHash that should not exist in the index (deterministic dummy bytes)
+const ABSENT_LABEL_HASH = parseLabelHash(`0x${"ff".repeat(32)}`);
+
+describe("Query.labels", () => {
+  it("returns a healed label entry for a known LabelHash", async () => {
+    await expect(
+      request<LabelsByLabelHashResult>(LabelsByLabelHash, { labelHashes: [ETH_LABEL_HASH] }),
+    ).resolves.toMatchObject({
+      labels: [{ hash: ETH_LABEL_HASH, interpreted: "eth" }],
+    });
+  });
+
+  it("accepts non-normalized (mixed-case hex) LabelHash variables and resolves matches", async () => {
+    const uppercaseVariable = ETH_LABEL_HASH.toUpperCase();
+    expect(parseLabelHash(uppercaseVariable)).toBe(ETH_LABEL_HASH);
+
+    await expect(
+      request<LabelsByLabelHashResult>(LabelsByLabelHash, {
+        labelHashes: [uppercaseVariable as LabelHash],
+      }),
+    ).resolves.toMatchObject({
+      labels: [{ hash: ETH_LABEL_HASH, interpreted: "eth" }],
+    });
+  });
+
+  it("omits LabelHashes that are not present in the index", async () => {
+    await expect(
+      request<LabelsByLabelHashResult>(LabelsByLabelHash, { labelHashes: [ABSENT_LABEL_HASH] }),
+    ).resolves.toEqual({ labels: [] });
+  });
+
+  it("returns only the present labels when input mixes present and absent LabelHashes", async () => {
+    await expect(
+      request<LabelsByLabelHashResult>(LabelsByLabelHash, {
+        labelHashes: [ETH_LABEL_HASH, ABSENT_LABEL_HASH],
+      }),
+    ).resolves.toMatchObject({
+      labels: [{ hash: ETH_LABEL_HASH }],
+    });
+  });
+
+  it("dedupes repeated input LabelHashes", async () => {
+    await expect(
+      request<LabelsByLabelHashResult>(LabelsByLabelHash, {
+        labelHashes: [ETH_LABEL_HASH, ETH_LABEL_HASH, ETH_LABEL_HASH],
+      }),
+    ).resolves.toMatchObject({
+      labels: [{ hash: ETH_LABEL_HASH }],
+    });
+  });
+
+  it("returns an empty list when input is empty", async () => {
+    await expect(request(LabelsByLabelHash, { labelHashes: [] })).resolves.toEqual({ labels: [] });
+  });
+
+  it("classifies returned labels: 'eth' is healed (interpreted !== encodeLabelHash(hash))", async () => {
+    const { labels } = await request<LabelsByLabelHashResult>(LabelsByLabelHash, {
+      labelHashes: [ETH_LABEL_HASH],
+    });
+
+    expect(labels).toHaveLength(1);
+    expect(labels[0].interpreted).not.toEqual(encodeLabelHash(ETH_LABEL_HASH));
+  });
+
+  it("rejects junk strings that cannot be parsed as LabelHashes", async () => {
+    await expect(
+      request(LabelsByLabelHash, {
+        labelHashes: ["not-even-hex"],
+      }),
+    ).rejects.toThrow(/Invalid labelHash/i);
+  });
+
+  it("rejects hex values that are not exactly 32 bytes", async () => {
+    await expect(
+      request(LabelsByLabelHash, {
+        labelHashes: ["0x00"],
+      }),
+    ).rejects.toThrow(/Invalid labelHash/i);
+  });
+
+  it("rejects requests over the maximum allowed LabelHash count", async () => {
+    const labelHashes: LabelHash[] = [];
+    for (let i = 0; i <= LABELS_BY_LABELHASH_MAX; i++) {
+      labelHashes.push(parseLabelHash(`0x${i.toString(16).padStart(64, "0")}`));
+    }
+
+    await expect(request(LabelsByLabelHash, { labelHashes })).rejects.toThrow(
+      /Too many LabelHashes/i,
+    );
+  });
+});

apps/ensapi/src/omnigraph-api/schema/label.ts

@@ -11,7 +11,7 @@ LabelRef.implement({
     hash: t.field({
       description:
         "The Label's LabelHash\n(@see https://ensnode.io/docs/reference/terminology#labels-labelhashes-labelhash-function)",
-      type: "Hex",
+      type: "LabelHash",
       nullable: false,
       resolve: (parent) => parent.labelHash,
     }),
@@ -28,3 +28,26 @@ LabelRef.implement({
     }),
   }),
 });
+
+//////////
+// Inputs
+//////////
+
+/**
+ * Maximum number of LabelHashes accepted per `Query.labels` request.
+ *
+ * Caps the resolver's `inArray` query so a single GraphQL request cannot enumerate
+ * the entire `label` table.
+ */
+export const LABELS_BY_LABELHASH_MAX = 100;
+
+export const LabelsByLabelHashesInput = builder.inputType("LabelsByLabelHashesInput", {
+  description: "Look up Labels by a batch of LabelHashes.",
+  fields: (t) => ({
+    labelHashes: t.field({
+      type: ["LabelHash"],
+      required: true,
+      description: `LabelHashes to look up. Up to ${LABELS_BY_LABELHASH_MAX} LabelHashes per request (each normalized to lowercase at parse time). LabelHashes absent from the index are omitted from the result.`,
+    }),
+  }),
+});

apps/ensapi/src/omnigraph-api/schema/query.ts

@@ -1,7 +1,9 @@
 import config from "@/config";
 
 import { type ResolveCursorConnectionArgs, resolveCursorConnection } from "@pothos/plugin-relay";
+import { inArray } from "drizzle-orm";
 import { makeConcreteRegistryId, makePermissionsId, makeResolverId } from "enssdk";
+import { createGraphQLError } from "graphql-yoga";
 
 import { getRootRegistryId } from "@ensnode/ensnode-sdk";
 
@@ -25,6 +27,11 @@ import {
   DomainsOrderInput,
   DomainsWhereInput,
 } from "@/omnigraph-api/schema/domain";
+import {
+  LABELS_BY_LABELHASH_MAX,
+  LabelRef,
+  LabelsByLabelHashesInput,
+} from "@/omnigraph-api/schema/label";
 import { PermissionsIdInput, PermissionsRef } from "@/omnigraph-api/schema/permissions";
 import { RegistrationInterfaceRef } from "@/omnigraph-api/schema/registration";
 import { RegistryIdInput, RegistryInterfaceRef } from "@/omnigraph-api/schema/registry";
@@ -140,6 +147,41 @@ builder.queryType({
       },
     }),
 
+    /////////////////////////
+    // Find Labels by Hashes
+    /////////////////////////
+    labels: t.field({
+      description:
+        "Look up Labels in the index by a batch of LabelHashes. " +
+        "Each returned Label exposes its `hash` and `interpreted` representation, where " +
+        "`interpreted` is the Encoded LabelHash for unhealed/unknown labels and a normalized " +
+        "literal for healed labels. LabelHashes that are not present in the index are simply " +
+        "omitted from the result.",
+      type: [LabelRef],
+      nullable: false,
+      args: { by: t.arg({ type: LabelsByLabelHashesInput, required: true }) },
+      resolve: async (_parent, { by }) => {
+        if (by.labelHashes.length === 0) return [];
+
+        if (by.labelHashes.length > LABELS_BY_LABELHASH_MAX) {
+          // Use `createGraphQLError` so the client-facing validation message survives Yoga's
+          // default `maskError`, which (correctly) hides plain `Error` instances as
+          // "Unexpected error.".
+          throw createGraphQLError(
+            `Too many LabelHashes: received ${by.labelHashes.length}, max ${LABELS_BY_LABELHASH_MAX}.`,
+            { extensions: { code: "BAD_USER_INPUT" } },
+          );
+        }
+
+        const dedupedHashes = Array.from(new Set(by.labelHashes));
+
+        return ensDb
+          .select()
+          .from(ensIndexerSchema.label)
+          .where(inArray(ensIndexerSchema.label.labelHash, dedupedHashes));
+      },
+    }),
+
     /////////////////////////////////////
     // Get Account by Id or Address
     /////////////////////////////////////

apps/ensapi/src/omnigraph-api/schema/scalars.ts

@@ -7,12 +7,14 @@ import {
   type Hex,
   isInterpretedLabel,
   isInterpretedName,
+  type LabelHash,
   type Name,
   type Node,
   type NormalizedAddress,
   type PermissionsId,
   type PermissionsResourceId,
   type PermissionsUserId,
+  parseLabelHash,
   type RegistrationId,
   type RegistryId,
   type RenewalId,
@@ -61,6 +63,13 @@ builder.scalarType("Hex", {
       .parse(value),
 });
 
+builder.scalarType("LabelHash", {
+  description:
+    "LabelHash represents enssdk#LabelHash: a 32-byte (64 hex digit) value, `0x`-prefixed and lowercased.",
+  serialize: (value: LabelHash) => value,
+  parseValue: (value) => parseLabelHash(z.coerce.string().parse(value)),
+});
+
 builder.scalarType("ChainId", {
   description: "ChainId represents a enssdk#ChainId.",
   serialize: (value: ChainId) => value,

apps/ensapi/src/omnigraph-api/yoga.ts

@@ -2,7 +2,7 @@
 // import { maxDepthPlugin } from "@escape.tech/graphql-armor-max-depth";
 // import { maxTokensPlugin } from "@escape.tech/graphql-armor-max-tokens";
 
-import { createYoga } from "graphql-yoga";
+import { createYoga, maskError } from "graphql-yoga";
 
 import { makeLogger } from "@/lib/logger";
 import { context } from "@/omnigraph-api/context";
@@ -16,6 +16,25 @@ export const yoga = createYoga({
   context,
   // CORS is handled by the Hono middleware in app.ts
   cors: false,
+  // Error masking:
+  // - Production: use Yoga defaults so internal details are not exposed to clients.
+  // - Non-production: still apply the same masked client payload, but log the **original**
+  //   error server-side first. This makes debugging much easier than only seeing the masked
+  //   message, while keeping the client-facing behavior aligned with production.
+  //
+  // Motivation: some resolvers intentionally throw `GraphQLError` (e.g. validation for
+  // `Query.labels`), but other code paths may throw plain `Error`. Yoga's default `maskError`
+  // maps unknown errors to a generic "Unexpected error." on the client; logging here ensures
+  // the real stack/message is still visible in local/staging logs.
+  maskedErrors:
+    process.env.NODE_ENV === "production"
+      ? true
+      : {
+          maskError(error, message, isDev) {
+            logger.error(error);
+            return maskError(error, message, isDev);
+          },
+        },
   graphiql: {
     defaultQuery: `query DomainsByOwner {
   account(by: { address: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266" }) {