add records resolution

.changeset/omnigraph-resolution-api.md

@@ -0,0 +1,10 @@
+---
+"ensapi": patch
+---
+
+Changes related to **Omnigraph**:
+
+- add `Domain.records` with raw records resolution (`ResolvedRawTextRecord` for text record values)
+- add `Account.primaryName(by: PrimaryNameByInput!)` and `Account.primaryNames(where: AccountPrimaryNamesWhereInput!)`. Primary name lookups accept `coinType` or `chain` (singular) and `coinTypes` or `chains` (plural, `@oneOf`); `ENSIP19Chain` includes `DEFAULT`; `PrimaryNameRecord.name` is a `CanonicalName` with `interpreted` and `beautified`
+- add `UID` cache keys on `ResolvedRecords` (keyed by resolution `InterpretedName`) for graphcache normalization across queries
+- add types-only `Domain.profile` and shared `DomainProfile` preview types (`ProfileAvatar`, `ProfileBanner`, `ProfileWebsite`, `ProfileAddresses`, `ProfileSocials`, etc.). Profile resolution is not wired yet; subfields return null

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/lib/resolution/multichain-primary-name-resolution.ts

@@ -1,20 +1,22 @@
 import { trace } from "@opentelemetry/api";
+import { type Address, type CoinType, evmChainIdToCoinType } 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, resolveReverseByCoinType } 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,43 @@ const getENSIP19SupportedChainIds = () => {
   ]);
 };
 
+/** Coin types corresponding to {@link getENSIP19SupportedChainIds} in the current namespace. */
+export const getENSIP19SupportedCoinTypes = (): CoinType[] =>
+  uniq(getENSIP19SupportedChainIds().map(evmChainIdToCoinType));
+
+export type MultichainPrimaryNameByCoinTypeResolutionResult = Partial<
+  Record<CoinType, ReverseResolutionResult>
+>;
+
+type PrimaryNameResolutionOptions = Parameters<typeof resolveReverseByCoinType>[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) => resolveReverseByCoinType(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`.
  *

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 ChainId,
+  type CoinType,
+  coinTypeReverseLabel,
+  evmChainIdToCoinType,
+  reverseName,
+} from "enssdk";
 import { isAddress, isAddressEqual } from "viem";
 
 import {
   type ResolverRecordsSelection,
-  type ReverseResolutionArgs,
   ReverseResolutionProtocolStep,
   type ReverseResolutionResult,
   TraceableENSProtocol,
@@ -24,45 +30,45 @@ 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.canAccelerate Whether acceleration is currently possible (default: false)
  */
-export async function resolveReverse(
-  address: ReverseResolutionArgs["address"],
-  chainId: ReverseResolutionArgs["chainId"],
-  options: Parameters<typeof resolveForward>[2],
+export async function resolveReverseByCoinType(
+  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 +179,24 @@ export async function resolveReverse(
       ),
   );
 }
+
+/**
+ * Implements ENS Reverse Resolution, including support for 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 options Optional settings
+ * @param options.accelerate Whether to accelerate resolution (default: true)
+ * @param options.canAccelerate Whether acceleration is currently possible (default: false)
+ */
+export async function resolveReverse(
+  address: Address,
+  chainId: ChainId,
+  options: ReverseResolutionOptions,
+): Promise<ReverseResolutionResult> {
+  return resolveReverseByCoinType(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,
@@ -24,11 +26,12 @@ import type {
   RenewalId,
   ResolverId,
   ResolverRecordsId,
+  UID,
 } from "enssdk";
 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,12 +64,15 @@ 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 };
+  UID: { Input: UID; Output: UID };
   InterpretedLabel: { Input: InterpretedLabel; Output: InterpretedLabel };
   BeautifiedName: { Input: BeautifiedName; Output: BeautifiedName };
   BeautifiedLabel: { Input: BeautifiedLabel; Output: BeautifiedLabel };
@@ -82,7 +88,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,