2003 add new 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/deploy_ensnode_blue_green.yml

@@ -28,6 +28,7 @@ jobs:
       ENSINDEXER_DOCKER_IMAGE: "ghcr.io/namehash/ensnode/ensindexer:${{ inputs.tag }}"
       ENSAPI_DOCKER_IMAGE: "ghcr.io/namehash/ensnode/ensapi:${{ inputs.tag }}"
       ENSRAINBOW_DOCKER_IMAGE: "ghcr.io/namehash/ensnode/ensrainbow:${{ inputs.tag }}"
+      ENSRAINBOWBEAM_DOCKER_IMAGE: "ghcr.io/namehash/ensnode/ensrainbowbeam:${{ inputs.tag }}"
       ENSADMIN_DOCKER_IMAGE: "ghcr.io/namehash/ensnode/ensadmin:${{ inputs.tag }}"
       RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}
       RAILWAY_PROJECT_ID: ${{ secrets.RAILWAY_PROJECT_ID }}
@@ -45,6 +46,7 @@ jobs:
           docker manifest inspect ${{ env.ENSINDEXER_DOCKER_IMAGE }} || { echo "Given docker image does not exist: ${{ env.ENSINDEXER_DOCKER_IMAGE }}"; exit 1; }
           docker manifest inspect ${{ env.ENSAPI_DOCKER_IMAGE }} || { echo "Given docker image does not exist: ${{ env.ENSAPI_DOCKER_IMAGE }}"; exit 1; }
           docker manifest inspect ${{ env.ENSRAINBOW_DOCKER_IMAGE }} || { echo "Given docker image does not exist: ${{ env.ENSRAINBOW_DOCKER_IMAGE }}"; exit 1; }
+          docker manifest inspect ${{ env.ENSRAINBOWBEAM_DOCKER_IMAGE }} || { echo "Given docker image does not exist: ${{ env.ENSRAINBOWBEAM_DOCKER_IMAGE }}"; exit 1; }
           docker manifest inspect ${{ env.ENSADMIN_DOCKER_IMAGE }} || { echo "Given docker image does not exist: ${{ env.ENSADMIN_DOCKER_IMAGE }}"; exit 1; }
 
       - name: Print switch target
@@ -76,6 +78,8 @@ jobs:
               echo "ENSRAINBOW_SVC_ID="${{ secrets.GREEN_ENSRAINBOW_SVC_ID }} >> "$GITHUB_ENV"
               #ENSRAINBOW SEARCHLIGHT
               echo "ENSRAINBOW_SEARCHLIGHT_SVC_ID="${{ secrets.GREEN_ENSRAINBOW_SEARCHLIGHT_SVC_ID }} >> "$GITHUB_ENV"
+              #ENSRAINBOWBEAM
+              echo "ENSRAINBOWBEAM_SVC_ID="${{ secrets.GREEN_ENSRAINBOWBEAM_SVC_ID }} >> "$GITHUB_ENV"
               #ENSADMIN
               echo "ENSADMIN_SVC_ID="${{ secrets.GREEN_ENSADMIN_SVC_ID }} >> "$GITHUB_ENV"
               echo "SLACK_TITLE=':large_green_circle: GREEN environment is now having new ENSNode version - '"${{ env.TAG }} >> "$GITHUB_ENV"
@@ -102,6 +106,8 @@ jobs:
               echo "ENSRAINBOW_SVC_ID="${{ secrets.BLUE_ENSRAINBOW_SVC_ID }} >> "$GITHUB_ENV"
               #ENSRAINBOW SEARCHLIGHT
               echo "ENSRAINBOW_SEARCHLIGHT_SVC_ID="${{ secrets.BLUE_ENSRAINBOW_SEARCHLIGHT_SVC_ID }} >> "$GITHUB_ENV"
+              #ENSRAINBOWBEAM
+              echo "ENSRAINBOWBEAM_SVC_ID="${{ secrets.BLUE_ENSRAINBOWBEAM_SVC_ID }} >> "$GITHUB_ENV"
               #ENSADMIN
               echo "ENSADMIN_SVC_ID="${{ secrets.BLUE_ENSADMIN_SVC_ID }} >> "$GITHUB_ENV"
               echo "SLACK_TITLE=':large_blue_circle: BLUE environment is now having new ENSNode version - '"${{ env.TAG }} >> "$GITHUB_ENV"
@@ -155,6 +161,8 @@ jobs:
           update_service_image  ${RAILWAY_ENVIRONMENT_ID} ${ENSRAINBOW_SVC_ID}              ${{ env.ENSRAINBOW_DOCKER_IMAGE }}
           #ENSRAINBOW SEARCHLIGHT
           update_service_image  ${RAILWAY_ENVIRONMENT_ID} ${ENSRAINBOW_SEARCHLIGHT_SVC_ID}  ${{ env.ENSRAINBOW_DOCKER_IMAGE }}
+          #ENSRAINBOWBEAM
+          update_service_image  ${RAILWAY_ENVIRONMENT_ID} ${ENSRAINBOWBEAM_SVC_ID}          ${{ env.ENSRAINBOWBEAM_DOCKER_IMAGE }}
           #ENSADMIN
           update_service_image  ${RAILWAY_ENVIRONMENT_ID} ${ENSADMIN_SVC_ID}                ${{ env.ENSADMIN_DOCKER_IMAGE }}
 
@@ -216,6 +224,8 @@ jobs:
           redeploy_service  ${RAILWAY_ENVIRONMENT_ID} ${ENSRAINBOW_SVC_ID}
           #ENSRAINBOW SEARCHLIGHT
           redeploy_service  ${RAILWAY_ENVIRONMENT_ID} ${ENSRAINBOW_SEARCHLIGHT_SVC_ID}
+          #ENSRAINBOWBEAM
+          redeploy_service  ${RAILWAY_ENVIRONMENT_ID} ${ENSRAINBOWBEAM_SVC_ID}
           #ENSADMIN
           redeploy_service  ${RAILWAY_ENVIRONMENT_ID} ${ENSADMIN_SVC_ID}
 

.github/workflows/deploy_ensnode_yellow.yml

@@ -20,6 +20,7 @@ jobs:
       ENSINDEXER_DOCKER_IMAGE: "ghcr.io/namehash/ensnode/ensindexer:${{ inputs.tag }}"
       ENSAPI_DOCKER_IMAGE: "ghcr.io/namehash/ensnode/ensapi:${{ inputs.tag }}"
       ENSRAINBOW_DOCKER_IMAGE: "ghcr.io/namehash/ensnode/ensrainbow:${{ inputs.tag }}"
+      ENSRAINBOWBEAM_DOCKER_IMAGE: "ghcr.io/namehash/ensnode/ensrainbowbeam:${{ inputs.tag }}"
       ENSADMIN_DOCKER_IMAGE: "ghcr.io/namehash/ensnode/ensadmin:${{ inputs.tag }}"
       # Terraform related envs
 
@@ -55,6 +56,7 @@ jobs:
           docker manifest inspect ${{ env.ENSINDEXER_DOCKER_IMAGE }} || { echo "Given docker image does not exist: ${{ env.ENSINDEXER_DOCKER_IMAGE }}"; exit 1; }
           docker manifest inspect ${{ env.ENSAPI_DOCKER_IMAGE }} || { echo "Given docker image does not exist: ${{ env.ENSAPI_DOCKER_IMAGE }}"; exit 1; }
           docker manifest inspect ${{ env.ENSRAINBOW_DOCKER_IMAGE }} || { echo "Given docker image does not exist: ${{ env.ENSRAINBOW_DOCKER_IMAGE }}"; exit 1; }
+          docker manifest inspect ${{ env.ENSRAINBOWBEAM_DOCKER_IMAGE }} || { echo "Given docker image does not exist: ${{ env.ENSRAINBOWBEAM_DOCKER_IMAGE }}"; exit 1; }
           docker manifest inspect ${{ env.ENSADMIN_DOCKER_IMAGE }} || { echo "Given docker image does not exist: ${{ env.ENSADMIN_DOCKER_IMAGE }}"; exit 1; }
 
       - name: Setup Terraform

.github/workflows/deploy_switch_ensnode_environment.yml

@@ -92,6 +92,10 @@ jobs:
           # ENSRAINBOW SEARCHLIGHT
           redis-cli -u $REDIS_URL SET traefik/http/routers/ensrainbow-searchlight-api-router/service "${TARGET_ENVIRONMENT}-ensrainbow-searchlight-api"
 
+          # ENSRAINBOWBEAM
+          # NOTE: Router/service names must match Traefik IaC (likely in namehash-tf-iac-live).
+          redis-cli -u $REDIS_URL SET traefik/http/routers/ensrainbowbeam-api-router/service "${TARGET_ENVIRONMENT}-ensrainbowbeam-api"
+
       - name: Promote ENSAdmin Vercel Deployment
         uses: ./.github/actions/promote_vercel_deployment
         with:

.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.`,
+    }),
+  }),
+});