feat(ensapi): add forward and reverse resolution to Omnigraph

.changeset/omnigraph-resolution-api.md

@@ -0,0 +1,9 @@
+---
+"ensapi": patch
+---
+
+Changes related to **Omnigraph**:
+
+- add `Domain.resolve { records, trace, acceleration, profile? }` for forward resolution driven by the GraphQL selection set
+- add `Account.resolve { primaryName(by: ...), primaryNames(where: ...) }` for reverse (ENSIP-19 primary name) resolution with `@oneOf` inputs (`coinType`/`chain`, `coinTypes`/`chains`)
+- add `PrimaryNameRecord.resolve { records, ... }` for forward resolution of the resolved primary name

apps/ensapi/package.json

@@ -23,6 +23,7 @@
   },
   "dependencies": {
     "@ensdomains/ensjs": "^4.0.2",
+    "@ensdomains/address-encoder": "^1.1.2",
     "@ensnode/datasources": "workspace:*",
     "@ensnode/ensdb-sdk": "workspace:*",
     "@ensnode/ensnode-sdk": "workspace:*",

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

@@ -1,24 +1,45 @@
+import type { Duration } from "enssdk";
+
 import {
   hasOmnigraphApiConfigSupport,
   hasOmnigraphApiIndexingStatusSupport,
 } from "@ensnode/ensnode-sdk";
 
 import di from "@/di";
+import { errorResponse } from "@/lib/handlers/error-response";
 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";
+
+/**
+ * The maximum distance (in seconds) from the current time to the latest indexed block
+ * for a chain to be considered "realtime" and thus eligible for protocol acceleration.
+ */
+const MAX_REALTIME_DISTANCE_TO_ACCELERATE: Duration = 600; // 10 minutes
 
-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);
   // 503 if Omnigraph API is not available due to config prerequisites not met
   if (!configPrerequisite.supported) {
-    return c.text(`Service Unavailable: ${configPrerequisite.reason}`, 503);
+    return errorResponse(c, `Service Unavailable: ${configPrerequisite.reason}`, 503);
   }
 
   // 503 if indexing status snapshot is not available yet
   if (c.var.indexingStatus instanceof Error) {
-    return c.text(`Service Unavailable: Indexing Status Snapshot is not available yet`, 503);
+    return errorResponse(
+      c,
+      "Service Unavailable: Indexing Status Snapshot is not available yet",
+      503,
+    );
   }
 
   // 503 if omnigraph API not available due to indexing status prerequisites not met
@@ -27,7 +48,7 @@ app.use(async (c, next) => {
   );
 
   if (!indexingStatusPrerequisite.supported) {
-    return c.text(`Service Unavailable: ${indexingStatusPrerequisite.reason}`, 503);
+    return errorResponse(c, `Service Unavailable: ${indexingStatusPrerequisite.reason}`, 503);
   }
 
   await next();

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

@@ -9,8 +9,8 @@ import {
 
 import { createApp } from "@/lib/hono-factory";
 import { resolveForward } from "@/lib/resolution/forward-resolution";
-import { resolvePrimaryNames } from "@/lib/resolution/multichain-primary-name-resolution";
-import { resolveReverse } from "@/lib/resolution/reverse-resolution";
+import { resolvePrimaryNamesByChainIds } from "@/lib/resolution/multichain-primary-name-resolution";
+import { resolveReverseByChainId } from "@/lib/resolution/reverse-resolution";
 import { runWithTrace } from "@/lib/tracing/tracing-api";
 import { canAccelerateMiddleware } from "@/middleware/can-accelerate.middleware";
 import { indexingStatusMiddleware } from "@/middleware/indexing-status.middleware";
@@ -90,7 +90,7 @@ app.openapi(resolvePrimaryNameRoute, async (c) => {
   const canAccelerate = c.var.canAccelerate;
 
   const { result, trace } = await runWithTrace(() =>
-    resolveReverse(address, chainId, { accelerate, canAccelerate }),
+    resolveReverseByChainId(address, chainId, { accelerate, canAccelerate }),
   );
 
   const response = {
@@ -118,7 +118,7 @@ app.openapi(resolvePrimaryNamesRoute, async (c) => {
   const { chainIds, trace: showTrace, accelerate } = c.req.valid("query");
   const canAccelerate = c.var.canAccelerate;
   const { result, trace } = await runWithTrace(() =>
-    resolvePrimaryNames(address, chainIds, { accelerate, canAccelerate }),
+    resolvePrimaryNamesByChainIds(address, chainIds, { accelerate, canAccelerate }),
   );
 
   const response = {

apps/ensapi/src/lib/resolution/multichain-primary-name-resolution.ts

@@ -1,20 +1,22 @@
 import { trace } from "@opentelemetry/api";
+import type { Address, CoinType } from "enssdk";
 import { mainnet } from "viem/chains";
 
 import { DatasourceNames, maybeGetDatasource } from "@ensnode/datasources";
 import {
   type MultichainPrimaryNameResolutionArgs,
   type MultichainPrimaryNameResolutionResult,
+  type ReverseResolutionResult,
   uniq,
 } from "@ensnode/ensnode-sdk";
 
 import di from "@/di";
 import { withActiveSpanAsync } from "@/lib/instrumentation/auto-span";
-import { resolveReverse } from "@/lib/resolution/reverse-resolution";
+import { resolveReverse, resolveReverseByChainId } from "@/lib/resolution/reverse-resolution";
 
 const tracer = trace.getTracer("multichain-primary-name-resolution");
 
-const getENSIP19SupportedChainIds = () => {
+export const getENSIP19SupportedChainIds = () => {
   return uniq([
     // always include Mainnet, because its chainId corresponds to the ENS Root Chain's coinType,
     // regardless of the current namespace
@@ -34,6 +36,36 @@ const getENSIP19SupportedChainIds = () => {
   ]);
 };
 
+export type MultichainPrimaryNameByCoinTypeResolutionResult = Partial<
+  Record<CoinType, ReverseResolutionResult>
+>;
+
+type PrimaryNameResolutionOptions = Parameters<typeof resolveReverse>[2];
+
+/**
+ * Batch-resolves an address' primary name for each requested coin type.
+ *
+ * @see https://docs.ens.domains/ensip/19
+ */
+export async function resolvePrimaryNamesByCoinTypes(
+  address: Address,
+  coinTypes: CoinType[],
+  options: PrimaryNameResolutionOptions,
+): Promise<MultichainPrimaryNameByCoinTypeResolutionResult> {
+  const names = await withActiveSpanAsync(
+    tracer,
+    "resolvePrimaryNamesByCoinTypes",
+    { address },
+    () => Promise.all(coinTypes.map((coinType) => resolveReverse(address, coinType, options))),
+  );
+
+  return coinTypes.reduce((memo, coinType, i) => {
+    // biome-ignore lint/style/noNonNullAssertion: names[i] guaranteed to be defined
+    memo[coinType] = names[i]!;
+    return memo;
+  }, {} as MultichainPrimaryNameByCoinTypeResolutionResult);
+}
+
 /**
  * Implements batch resolution of an address' Primary Name across the provided `chainIds`.
  *
@@ -46,17 +78,19 @@ const getENSIP19SupportedChainIds = () => {
  * @param options.accelerate Whether acceleration is requested (default: true)
  * @param options.canAccelerate Whether acceleration is currently possible (default: false)
  */
-export async function resolvePrimaryNames(
+export async function resolvePrimaryNamesByChainIds(
   address: MultichainPrimaryNameResolutionArgs["address"],
   chainIds: MultichainPrimaryNameResolutionArgs["chainIds"] = getENSIP19SupportedChainIds(),
-  options: Parameters<typeof resolveReverse>[2],
+  options: Parameters<typeof resolveReverseByChainId>[2],
 ): Promise<MultichainPrimaryNameResolutionResult> {
-  // parallel reverseResolve
-  const names = await withActiveSpanAsync(tracer, "resolvePrimaryNames", { address }, () =>
-    Promise.all(chainIds.map((chainId) => resolveReverse(address, chainId, options))),
+  const names = await withActiveSpanAsync(
+    tracer,
+    "resolvePrimaryNamesByChainIds",
+    { address },
+    () =>
+      Promise.all(chainIds.map((chainId) => resolveReverseByChainId(address, chainId, options))),
   );
 
-  // key results by chainId
   return chainIds.reduce((memo, chainId, i) => {
     // biome-ignore lint/style/noNonNullAssertion: names[i] guaranteed to be defined
     memo[chainId] = names[i]!;

apps/ensapi/src/lib/resolution/reverse-resolution.ts

@@ -1,10 +1,16 @@
 import { SpanStatusCode, trace } from "@opentelemetry/api";
-import { coinTypeReverseLabel, evmChainIdToCoinType, reverseName } from "enssdk";
+import {
+  type Address,
+  type CoinType,
+  coinTypeReverseLabel,
+  type DefaultableChainId,
+  evmChainIdToCoinType,
+  reverseName,
+} from "enssdk";
 import { isAddress, isAddressEqual } from "viem";
 
 import {
   type ResolverRecordsSelection,
-  type ReverseResolutionArgs,
   ReverseResolutionProtocolStep,
   type ReverseResolutionResult,
   TraceableENSProtocol,
@@ -24,45 +30,44 @@ export const REVERSE_RESOLUTION_SELECTION = {
 
 const tracer = trace.getTracer("reverse-resolution");
 
+type ReverseResolutionOptions = Parameters<typeof resolveForward>[2];
+
 /**
- * Implements ENS Reverse Resolution, including support for ENSIP-19 L2 Primary Names.
+ * Implements ENS Reverse Resolution for a specific coin type, including ENSIP-19 L2 Primary Names.
  *
  * @see https://docs.ens.domains/ensip/19/#algorithm
  *
- * The DEFAULT_EVM_CHAIN_ID (0) is a valid chainId in this context.
- *
  * @param address the adddress whose Primary Name to resolve
- * @param chainId the chainId within which to resolve the address' Primary Name
+ * @param coinType the coinType within which to resolve the address' Primary Name
  * @param options Optional settings
- * @param options.accelerate Whether to accelerate resolution (default: true)
+ * @param options.accelerate Whether to attempt accelerated resolution (default: true)
  * @param options.canAccelerate Whether acceleration is currently possible (default: false)
  */
 export async function resolveReverse(
-  address: ReverseResolutionArgs["address"],
-  chainId: ReverseResolutionArgs["chainId"],
-  options: Parameters<typeof resolveForward>[2],
+  address: Address,
+  coinType: CoinType,
+  options: ReverseResolutionOptions,
 ): Promise<ReverseResolutionResult> {
   const { accelerate = true } = options;
 
   // trace for external consumers
   return withProtocolStep(
     TraceableENSProtocol.ReverseResolution,
     ReverseResolutionProtocolStep.Operation,
-    { address, chainId, accelerate },
+    { address, coinType, accelerate },
     (protocolTracingSpan) =>
       // trace for internal metrics
       withActiveSpanAsync(
         tracer,
-        `resolveReverse(${address}, chainId: ${chainId})`,
-        { address, chainId, accelerate },
+        `resolveReverseByCoinType(${address}, coinType: ${coinType})`,
+        { address, coinType, accelerate },
         async (span) => {
           /////////////////////////////////////////////////////////
           // Reverse Resolution
           // https://docs.ens.domains/ensip/19/#algorithm
           /////////////////////////////////////////////////////////
 
           // Steps 1-3 — Resolve coinType-specific name record
-          const coinType = evmChainIdToCoinType(chainId);
           const _reverseName = reverseName(address, coinType);
           const { name } = await withProtocolStep(
             TraceableENSProtocol.ReverseResolution,
@@ -173,3 +178,18 @@ export async function resolveReverse(
       ),
   );
 }
+
+/**
+ * Thin `chainId` wrapper around {@link resolveReverse} for callers at the REST API boundary.
+ *
+ * @param address The address whose primary name to resolve.
+ * @param chainId The EVM chain id for the reverse lookup. `0` is valid as the ENSIP-19 default chain id.
+ * @param options Optional resolution settings.
+ */
+export async function resolveReverseByChainId(
+  address: Address,
+  chainId: DefaultableChainId,
+  options: ReverseResolutionOptions,
+): Promise<ReverseResolutionResult> {
+  return resolveReverse(address, evmChainIdToCoinType(chainId), options);
+}

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

@@ -12,8 +12,10 @@ import type {
   CoinType,
   DomainId,
   Hex,
+  InterfaceId,
   InterpretedLabel,
   InterpretedName,
+  JsonValue,
   Node,
   NormalizedAddress,
   PermissionsId,
@@ -28,7 +30,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, {
@@ -61,10 +63,12 @@ const createSpan = createOpenTelemetryWrapper(tracer, {
 export type BuilderScalars = {
   ID: { Input: string; Output: string };
   BigInt: { Input: bigint; Output: bigint };
+  JSON: { Input: JsonValue; Output: JsonValue };
   Address: { Input: NormalizedAddress; Output: NormalizedAddress };
   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 +86,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 di from "@/di";
+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) => {
@@ -24,9 +28,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 di from "@/di";
 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,
@@ -102,7 +102,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,