add records resolution

.changeset/omnigraph-resolution-api.md

@@ -0,0 +1,5 @@
+---
+"ensapi": patch
+---
+
+**Omnigraph**: add live ENS resolution fields — `Domain.records` for forward resolution (texts, addresses, contenthash, pubkey, ABI, interfaces, and related record types) and `Account.primaryNames` for ENSIP-19 multichain primary names. Record types to resolve are selected via the GraphQL field selection on `records`; both fields accept an optional `disableAcceleration` argument.

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

@@ -1,13 +1,25 @@
+import type { Duration } from "enssdk";
+
 import {
   hasOmnigraphApiConfigSupport,
   hasOmnigraphApiIndexingStatusSupport,
 } from "@ensnode/ensnode-sdk";
 
 import di from "@/di";
 import { createApp } from "@/lib/hono-factory";
+import { canAccelerateMiddleware } from "@/middleware/can-accelerate.middleware";
 import { indexingStatusMiddleware } from "@/middleware/indexing-status.middleware";
+import { makeIsRealtimeMiddleware } from "@/middleware/is-realtime.middleware";
+
+const MAX_REALTIME_DISTANCE_TO_ACCELERATE: Duration = 60;
 
-const app = createApp({ middlewares: [indexingStatusMiddleware] });
+const app = createApp({
+  middlewares: [
+    indexingStatusMiddleware,
+    makeIsRealtimeMiddleware("omnigraph-api", MAX_REALTIME_DISTANCE_TO_ACCELERATE),
+    canAccelerateMiddleware,
+  ],
+});
 
 app.use(async (c, next) => {
   const configPrerequisite = hasOmnigraphApiConfigSupport(di.context.stackInfo.ensIndexer);

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

@@ -12,6 +12,7 @@ import type {
   CoinType,
   DomainId,
   Hex,
+  InterfaceId,
   InterpretedLabel,
   InterpretedName,
   Node,
@@ -28,7 +29,7 @@ import type {
 import { getNamedType } from "graphql";
 import superjson from "superjson";
 
-import type { context } from "@/omnigraph-api/context";
+import type { Context } from "@/omnigraph-api/context";
 
 const tracer = trace.getTracer("graphql");
 const createSpan = createOpenTelemetryWrapper(tracer, {
@@ -65,6 +66,7 @@ export type BuilderScalars = {
   Hex: { Input: Hex; Output: Hex };
   ChainId: { Input: ChainId; Output: ChainId };
   CoinType: { Input: CoinType; Output: CoinType };
+  InterfaceId: { Input: InterfaceId; Output: InterfaceId };
   Node: { Input: Node; Output: Node };
   InterpretedName: { Input: InterpretedName; Output: InterpretedName };
   InterpretedLabel: { Input: InterpretedLabel; Output: InterpretedLabel };
@@ -82,7 +84,7 @@ export type BuilderScalars = {
 };
 
 export const builder = new SchemaBuilder<{
-  Context: ReturnType<typeof context>;
+  Context: Context;
   Scalars: BuilderScalars;
 
   // the following ensures via typechecker that every t.connection returns a totalCount field

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

@@ -4,6 +4,10 @@ import { inArray } from "drizzle-orm";
 import type { DomainId, RegistryId } from "enssdk";
 
 import { ensDb, ensIndexerSchema } from "@/lib/ensdb/singleton";
+import type { CanAccelerateMiddlewareVariables } from "@/middleware/can-accelerate.middleware";
+
+/** Server context passed from Hono into GraphQL Yoga via `yoga.fetch(request, serverContext)`. */
+export type OmnigraphYogaServerContext = CanAccelerateMiddlewareVariables;
 
 const createRegistryParentDomainLoader = () =>
   new DataLoader<RegistryId, DomainId | null>(async (registryIds) => {
@@ -23,9 +27,12 @@ const createRegistryParentDomainLoader = () =>
  *
  * @dev make sure that anything that is per-request (like dataloaders) are newly created in this fn
  */
-export const context = () => ({
+export const createOmnigraphContext = (serverContext: OmnigraphYogaServerContext) => ({
   now: BigInt(getUnixTime(new Date())),
   loaders: {
     registryParentDomain: createRegistryParentDomainLoader(),
   },
+  canAccelerate: serverContext.canAccelerate,
 });
+
+export type Context = ReturnType<typeof createOmnigraphContext>;

apps/ensapi/src/omnigraph-api/lib/find-domains/find-domains-resolver.ts

@@ -6,7 +6,7 @@ import type { NormalizedAddress, RegistryId } from "enssdk";
 import { ensDb, ensIndexerSchema } from "@/lib/ensdb/singleton";
 import { withActiveSpanAsync } from "@/lib/instrumentation/auto-span";
 import { makeLogger } from "@/lib/logger";
-import type { context as createContext } from "@/omnigraph-api/context";
+import type { Context } from "@/omnigraph-api/context";
 import { DomainCursors } from "@/omnigraph-api/lib/find-domains/domain-cursor";
 import {
   cursorFilter,
@@ -101,7 +101,7 @@ function getDefaultOrder(where: DomainsWhere | undefined | null): DomainsOrderVa
  * @param args - Compound `where` filter, optional ordering, and relay connection args
  */
 export function resolveFindDomains(
-  context: ReturnType<typeof createContext>,
+  context: Context,
   {
     where,
     order,

apps/ensapi/src/omnigraph-api/lib/resolution/build-records-selection.test.ts

@@ -0,0 +1,176 @@
+import {
+  type GraphQLFieldConfigMap,
+  GraphQLInt,
+  GraphQLList,
+  GraphQLNonNull,
+  GraphQLObjectType,
+  type GraphQLResolveInfo,
+  GraphQLScalarType,
+  GraphQLString,
+  Kind,
+  parse,
+} from "graphql";
+import { describe, expect, it } from "vitest";
+
+import {
+  buildRecordsSelectionFromResolveInfo,
+  EMPTY_RECORDS_SELECTION_MESSAGE,
+} from "@/omnigraph-api/lib/resolution/build-records-selection";
+import {
+  RECORDS_SELECTION_PARAMETRIC_FIELDS,
+  RECORDS_SELECTION_SIMPLE_FIELDS,
+} from "@/omnigraph-api/lib/resolution/records-selection-config";
+
+const stringListArg = new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(GraphQLString)));
+const intListArg = new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(GraphQLInt)));
+
+const mockBigIntArg = new GraphQLNonNull(
+  new GraphQLScalarType({
+    name: "BigInt",
+    serialize: String,
+    parseValue: (value) => BigInt(value as string | number | bigint),
+    parseLiteral(ast) {
+      if (ast.kind === Kind.STRING || ast.kind === Kind.INT) return BigInt(ast.value);
+      throw new Error("BigInt literal must be a string or integer");
+    },
+  }),
+);
+
+function buildMockResolvedRecordsType() {
+  const fields: Record<string, { type: typeof GraphQLString; args?: Record<string, unknown> }> = {};
+
+  for (const { graphqlField } of RECORDS_SELECTION_SIMPLE_FIELDS) {
+    fields[graphqlField] = { type: GraphQLString };
+  }
+
+  for (const { graphqlField, argName } of RECORDS_SELECTION_PARAMETRIC_FIELDS) {
+    const argType =
+      argName === "coinTypes"
+        ? intListArg
+        : argName === "contentTypeMask"
+          ? mockBigIntArg
+          : stringListArg;
+    fields[graphqlField] = { type: GraphQLString, args: { [argName]: { type: argType } } };
+  }
+
+  return new GraphQLObjectType({
+    name: "ResolvedRecords",
+    fields: fields as GraphQLFieldConfigMap<unknown, unknown>,
+  });
+}
+
+const ResolvedRecordsType = buildMockResolvedRecordsType();
+
+function parseRecordsFieldNode(subselection: string) {
+  const document = parse(`{ records { ${subselection} } }`);
+  const operation = document.definitions[0];
+  if (operation.kind !== "OperationDefinition") throw new Error("expected operation");
+
+  const recordsField = operation.selectionSet.selections[0];
+  if (recordsField.kind !== "Field") throw new Error("expected field");
+
+  return recordsField;
+}
+
+function mockResolveInfo(
+  fieldNodes: ReturnType<typeof parseRecordsFieldNode>[],
+  variableValues: Record<string, unknown> = {},
+): GraphQLResolveInfo {
+  return {
+    fieldNodes,
+    fragments: {},
+    returnType: ResolvedRecordsType,
+    variableValues,
+  } as unknown as GraphQLResolveInfo;
+}
+
+function resolveInfoForRecordsSubselection(subselection: string): GraphQLResolveInfo {
+  return mockResolveInfo([parseRecordsFieldNode(subselection)]);
+}
+
+/** Simulates GraphQL passing multiple AST field nodes for the same `records` resolver. */
+function resolveInfoForMultipleRecordsFieldNodes(...subselections: string[]): GraphQLResolveInfo {
+  return mockResolveInfo(subselections.map(parseRecordsFieldNode));
+}
+
+describe("buildRecordsSelectionFromResolveInfo", () => {
+  it.each(RECORDS_SELECTION_SIMPLE_FIELDS)(
+    "selects $graphqlField as $recordsSelectionKey",
+    ({ graphqlField, recordsSelectionKey }) => {
+      const info = resolveInfoForRecordsSubselection(graphqlField);
+      expect(buildRecordsSelectionFromResolveInfo(info)).toEqual({ [recordsSelectionKey]: true });
+    },
+  );
+
+  it.each([
+    {
+      subselection: 'texts(keys: ["description"])',
+      expected: { texts: ["description"] },
+    },
+    {
+      subselection: "addresses(coinTypes: [60])",
+      expected: { addresses: [60] },
+    },
+    {
+      subselection: 'abi(contentTypeMask: "1")',
+      expected: { abi: 1n },
+    },
+    {
+      subselection: 'interfaces(ids: ["0x01020304"])',
+      expected: { interfaces: ["0x01020304"] },
+    },
+  ])("parses parametric field: $subselection", ({ subselection, expected }) => {
+    const info = resolveInfoForRecordsSubselection(subselection);
+    expect(buildRecordsSelectionFromResolveInfo(info)).toEqual(expected);
+  });
+
+  it("builds combined selection across simple and parametric fields", () => {
+    const info = resolveInfoForRecordsSubselection(`
+      reverseName
+      contenthash
+      texts(keys: ["avatar", "description"])
+      addresses(coinTypes: [60])
+      abi(contentTypeMask: "1")
+    `);
+
+    expect(buildRecordsSelectionFromResolveInfo(info)).toEqual({
+      name: true,
+      contenthash: true,
+      texts: ["avatar", "description"],
+      addresses: [60],
+      abi: 1n,
+    });
+  });
+
+  it("ignores __typename", () => {
+    const info = resolveInfoForRecordsSubselection("__typename reverseName");
+    expect(buildRecordsSelectionFromResolveInfo(info)).toEqual({ name: true });
+  });
+
+  it("merges selections from multiple field nodes", () => {
+    const info = resolveInfoForMultipleRecordsFieldNodes(
+      'texts(keys: ["description"])',
+      "addresses(coinTypes: [60])",
+    );
+
+    expect(buildRecordsSelectionFromResolveInfo(info)).toEqual({
+      texts: ["description"],
+      addresses: [60],
+    });
+  });
+
+  it("throws when selection is empty", () => {
+    const info = resolveInfoForRecordsSubselection("__typename");
+    expect(() => buildRecordsSelectionFromResolveInfo(info)).toThrow(
+      EMPTY_RECORDS_SELECTION_MESSAGE,
+    );
+  });
+
+  it("throws when only unknown fields are selected", () => {
+    const info = resolveInfoForRecordsSubselection("unknownField");
+
+    expect(() => buildRecordsSelectionFromResolveInfo(info)).toThrow(
+      EMPTY_RECORDS_SELECTION_MESSAGE,
+    );
+  });
+});

apps/ensapi/src/omnigraph-api/lib/resolution/build-records-selection.ts

@@ -0,0 +1,104 @@
+import {
+  type FieldNode,
+  GraphQLError,
+  type GraphQLResolveInfo,
+  getArgumentValues,
+  getNamedType,
+  isObjectType,
+  Kind,
+  type SelectionSetNode,
+} from "graphql";
+
+import { isSelectionEmpty, type ResolverRecordsSelection } from "@ensnode/ensnode-sdk";
+
+import {
+  getParametricRecordsSelectionField,
+  getSimpleRecordsSelectionField,
+} from "@/omnigraph-api/lib/resolution/records-selection-config";
+
+export const EMPTY_RECORDS_SELECTION_MESSAGE = "Records selection cannot be empty.";
+
+/** Recursively flatten a GraphQL selection set into Field nodes (expanding fragments). */
+function collectFieldNodes(
+  graphqlSelectionSet: SelectionSetNode,
+  info: GraphQLResolveInfo,
+): FieldNode[] {
+  const fields: FieldNode[] = [];
+
+  for (const graphqlSelection of graphqlSelectionSet.selections) {
+    if (graphqlSelection.kind === "Field") {
+      if (graphqlSelection.name.value === "__typename") continue;
+      fields.push(graphqlSelection);
+    } else if (graphqlSelection.kind === "InlineFragment") {
+      fields.push(...collectFieldNodes(graphqlSelection.selectionSet, info));
+    } else if (graphqlSelection.kind === "FragmentSpread") {
+      const fragment = info.fragments[graphqlSelection.name.value];
+      if (fragment) fields.push(...collectFieldNodes(fragment.selectionSet, info));
+    }
+  }
+
+  return fields;
+}
+
+/**
+ * Builds a {@link ResolverRecordsSelection} from the GraphQL field selection on `Domain.records`.
+ *
+ * GraphQL clients express *what* to resolve via a field selection set (e.g. `records { texts(...) }`).
+ * The ENS resolution layer expects a flat {@link ResolverRecordsSelection} instead — this function
+ * translates between the two.
+ */
+export function buildRecordsSelectionFromResolveInfo(
+  info: GraphQLResolveInfo,
+): ResolverRecordsSelection {
+  // GraphQL may pass multiple AST field nodes for the same resolver when the client splits
+  // `records { ... }` across inline fragments (common on the `Domain` interface). Merge their
+  // GraphQL selection lists so we don't drop subselections on fieldNodes[1], fieldNodes[2], etc.
+  const graphqlSelections = info.fieldNodes.flatMap((node) => node.selectionSet?.selections ?? []);
+
+  if (graphqlSelections.length === 0) {
+    throw new GraphQLError(EMPTY_RECORDS_SELECTION_MESSAGE);
+  }
+
+  // collectFieldNodes expects a SelectionSetNode; wrap the merged GraphQL selections into one.
+  const mergedGraphqlSelectionSet: SelectionSetNode = {
+    kind: Kind.SELECTION_SET,
+    selections: graphqlSelections,
+  };
+
+  const returnType = getNamedType(info.returnType);
+  if (!isObjectType(returnType)) {
+    throw new GraphQLError("Return type must be an object type.");
+  }
+
+  // Output for resolveForward(), e.g. { texts: ["description"], addresses: [60] }.
+  const recordsSelection: ResolverRecordsSelection = {};
+
+  // Walk every GraphQL child field under `records` (skipping __typename, expanding fragments).
+  for (const childField of collectFieldNodes(mergedGraphqlSelectionSet, info)) {
+    const graphqlField = childField.name.value;
+
+    // Simple GraphQL fields (contenthash, pubkey, …) map 1:1 to a boolean in recordsSelection.
+    const simple = getSimpleRecordsSelectionField(graphqlField);
+    if (simple) {
+      recordsSelection[simple.recordsSelectionKey] = true;
+      continue;
+    }
+
+    // Parametric GraphQL fields (texts, addresses, …) carry args we copy into recordsSelection.
+    const parametric = getParametricRecordsSelectionField(graphqlField);
+    if (!parametric) continue;
+
+    const fieldDef = returnType.getFields()[graphqlField];
+    if (!fieldDef) continue;
+
+    const args = getArgumentValues(fieldDef, childField, info.variableValues);
+    parametric.applyToRecordsSelection(recordsSelection, args);
+  }
+
+  // GraphQL query selected only __typename or unknown fields — nothing to resolve.
+  if (isSelectionEmpty(recordsSelection)) {
+    throw new GraphQLError(EMPTY_RECORDS_SELECTION_MESSAGE);
+  }
+
+  return recordsSelection;
+}