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`** distinct LabelHashes per request (after deduplication) for a round-number limit aligned with the `inArray` workload, and keep development error masking aligned with Yoga defaults while ensuring intentional `GraphQLError`s still surface useful client messages where applicable.

.changeset/ensrainbow-sdk-beam-client.md

@@ -0,0 +1,5 @@
+---
+"@ensnode/ensrainbow-sdk": minor
+---
+
+Add a light **EnsRainbowBeam** HTTP client (`EnsRainbowBeamClient`): `health()` and `discover()` against EnsRainbowBeam, client-side validation aligned with the server, `EnsRainbowBeamHttpError` for non-2xx responses with optional `{ message, details }` parsing, and subpath export `@ensnode/ensrainbow-sdk/ensrainbowbeam-client`.

.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,142 @@
+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 digits) LabelHash variables and resolves matches", async () => {
+    // Lowercase `0x` prefix only; uppercase `0X` is rejected (see enssdk `parseLabelHash`).
+    const mixedCaseVariable = `0x${ETH_LABEL_HASH.slice(2)
+      .split("")
+      .map((c, i) => (i % 2 === 0 ? c.toUpperCase() : c))
+      .join("")}` as LabelHash;
+    expect(parseLabelHash(mixedCaseVariable)).toBe(ETH_LABEL_HASH);
+
+    await expect(
+      request<LabelsByLabelHashResult>(LabelsByLabelHash, {
+        labelHashes: [mixedCaseVariable],
+      }),
+    ).resolves.toMatchObject({
+      labels: [{ hash: ETH_LABEL_HASH, interpreted: "eth" }],
+    });
+  });
+
+  it("rejects uppercase 0X hex prefix", async () => {
+    const badPrefix = `0X${ETH_LABEL_HASH.slice(2)}`;
+    await expect(request(LabelsByLabelHash, { labelHashes: [badPrefix] })).rejects.toThrow(
+      /Invalid labelHash/i,
+    );
+  });
+
+  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 distinct 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 distinct LabelHashes/i,
+    );
+  });
+
+  it("allows input with duplicate LabelHashes when the distinct count is within the max", async () => {
+    await expect(
+      request<LabelsByLabelHashResult>(LabelsByLabelHash, {
+        labelHashes: [ETH_LABEL_HASH, ETH_LABEL_HASH, ETH_LABEL_HASH],
+      }),
+    ).resolves.toMatchObject({
+      labels: [{ hash: ETH_LABEL_HASH, interpreted: "eth" }],
+    });
+  });
+});

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

@@ -1,3 +1,5 @@
+import { OMNIGRAPH_LABELS_BY_LABELHASH_MAX } from "enssdk";
+
 import type { ensIndexerSchema } from "@/lib/ensdb/singleton";
 import { builder } from "@/omnigraph-api/builder";
 
@@ -11,7 +13,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 +30,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 = OMNIGRAPH_LABELS_BY_LABELHASH_MAX;
+
+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. After deduplication, at most ${LABELS_BY_LABELHASH_MAX} distinct 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 [];
+
+        const dedupedHashes = Array.from(new Set(by.labelHashes));
+
+        if (dedupedHashes.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 distinct LabelHashes: received ${dedupedHashes.length}, max ${LABELS_BY_LABELHASH_MAX}.`,
+            { extensions: { code: "BAD_USER_INPUT" } },
+          );
+        }
+
+        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,18 +7,21 @@ 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,
   type ResolverId,
   type ResolverRecordsId,
 } from "enssdk";
+import { createGraphQLError } from "graphql-yoga";
 import { isHex, size } from "viem";
 import { z } from "zod/v4";
 
@@ -61,6 +64,20 @@ 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) => {
+    try {
+      return parseLabelHash(z.coerce.string().parse(value));
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      throw createGraphQLError(message, { extensions: { code: "BAD_USER_INPUT" } });
+    }
+  },
+});
+
 builder.scalarType("ChainId", {
   description: "ChainId represents a enssdk#ChainId.",
   serialize: (value: ChainId) => value,