refactor: unified polymorphic domain + registry

.changeset/ensnode-sdk-managed-name-api.md

@@ -0,0 +1,10 @@
+---
+"@ensnode/ensnode-sdk": minor
+---
+
+Centralized Managed Name and Root Registry helpers.
+
+- **Removed:** `getEthnamesSubregistryId`, `getEthnamesSubregistryManagedName`, `getBasenamesSubregistryId`, `getBasenamesSubregistryManagedName`, `getLineanamesSubregistryId`, `getLineanamesSubregistryManagedName`.
+- **Added:** `getManagedName(namespace, contract)` — given any contract in the ENSv1 ecosystem, returns its Managed Name, namehash, and concrete ENSv1 Registry. Replaces the per-plugin helpers above. Also exposes `isNameWrapper(namespace, contract)`.
+- **Added:** `getRootRegistryId(namespace)` returns the namespace's primary Root Registry (prefers ENSv2 when defined). `getRootRegistryIds(namespace)` returns every top-level Root Registry — concrete ENSv1 Root, Basenames/Lineanames `base.eth`/`linea.eth` ENSv1VirtualRegistries, and the ENSv2 Root when defined — for consumers that walk the full canonical-set tree.
+- **Added:** `getENSv1RootRegistryId(namespace)`.

.changeset/query-root-nonnull.md

@@ -0,0 +1,5 @@
+---
+"ensapi": minor
+---
+
+`Query.root` is now non-null and returns the namespace's Root Registry — preferring the ENSv2 Root Registry when defined, falling back to the ENSv1 Root Registry.

.changeset/unified-domain-model.md

@@ -0,0 +1,24 @@
+---
+"enssdk": minor
+"@ensnode/ensdb-sdk": minor
+"@ensnode/ensnode-sdk": minor
+"ensindexer": minor
+"ensapi": minor
+---
+
+Unify `v1Domain` + `v2Domain` into a single polymorphic `domain` table discriminated by a `type` enum (`"ENSv1Domain"` | `"ENSv2Domain"`), and make Registry polymorphic across concrete ENSv1 (mainnet Registry, Basenames Registry, Lineanames Registry), ENSv1 Virtual (per-parent-domain virtual Registry managed by each ENSv1 domain that has children), and ENSv2 Registries.
+
+### Breaking schema + id format changes
+
+- `ENSv1DomainId` is now CAIP-shaped: `${ENSv1RegistryId}/${node}` (was `Node`). Every ENSv1 Domain is addressable through a concrete Registry, so bare `node` values no longer identify a Domain by themselves.
+- `RegistryId` is a union of `ENSv1RegistryId`, `ENSv1VirtualRegistryId`, and `ENSv2RegistryId`. New id constructors: `makeENSv1RegistryId`, `makeENSv2RegistryId`, `makeENSv1VirtualRegistryId`, and `makeConcreteRegistryId` (returns `ENSv1RegistryId | ENSv2RegistryId` for callsites that only need to address a concrete Registry contract). `makeENSv1DomainId` now takes `(AccountId, Node)`.
+- `domains` table: replaces `v1_domains` + `v2_domains`. Adds `type`, nullable `tokenId` (non-null iff ENSv2), nullable `node` (non-null iff ENSv1), nullable `rootRegistryOwnerId` (v1 only). `parentId` removed; parent relationships flow through `registryCanonicalDomain` for both v1 and v2.
+- `registries` table: adds `type` enum column and nullable `node` (non-null iff `ENSv1VirtualRegistry`). Unique `(chainId, address)` index becomes a plain index so virtual Registries can share their concrete parent's `(chainId, address)`.
+- `registryCanonicalDomain.domainId` is typed as the unified `DomainId`.
+
+### GraphQL
+
+- `Registry` becomes a GraphQL interface with `ENSv1Registry`, `ENSv1VirtualRegistry`, and `ENSv2Registry` implementations. `ENSv1VirtualRegistry` exposes `node: Node!`.
+- `Domain` interface gains `parent: Domain` (resolved via the canonical-path dataloader); `ENSv1Domain` exposes `node: Node!` and `rootRegistryOwner`; `ENSv2Domain` exposes `tokenId`, `registry`, `subregistry`, `permissions`.
+- `Query.registry(by: { contract })` now DB-looks up the concrete Registry by `(chainId, address, type IN (ENSv1Registry, ENSv2Registry))`. Virtual Registries are not addressable via `AccountId` alone.
+

AGENTS.md

@@ -52,6 +52,8 @@ Runnable commands for validating changes; lint and format with Biome.
 - Use `describe`/`it` blocks with `expect` assertions.
 - Use `vi.mock()` for module mocking and `vi.fn()` for function stubs.
 - Each app and package has its own `vitest.config.ts`.
+- Prefer the `await expect(...).resolves.*` format over await-then-expect.
+- Prefer `await expect(...).resolves.toMatchObject({})` over expecting individual properties, if it is more concise.
 
 ## Documentation & DRY
 
@@ -81,3 +83,5 @@ Fail fast and loudly on invalid inputs.
   1. `pnpm -F <affected-project> typecheck`
   2. `pnpm lint`
   3. `pnpm test --project <affected-project> [--project <other-affected-project>]`
+  4. If OpenAPI Specs were affected, run `pnpm generate:openapi`
+  5. If the Omnigraph GraphQL Schema was affected, run `pnpm generate:gqlschema`

apps/ensapi/src/lib/name-tokens/get-indexed-subregistries.ts

@@ -1,13 +1,7 @@
-import { namehashInterpretedName } from "enssdk";
-
-import type { ENSNamespaceId } from "@ensnode/datasources";
+import { DatasourceNames, type ENSNamespaceId } from "@ensnode/datasources";
 import {
-  getBasenamesSubregistryId,
-  getBasenamesSubregistryManagedName,
-  getEthnamesSubregistryId,
-  getEthnamesSubregistryManagedName,
-  getLineanamesSubregistryId,
-  getLineanamesSubregistryManagedName,
+  getManagedName,
+  maybeGetDatasourceContract,
   PluginName,
   type Subregistry,
 } from "@ensnode/ensnode-sdk";
@@ -19,28 +13,18 @@ export function getIndexedSubregistries(
   namespaceId: ENSNamespaceId,
   activePlugins: PluginName[],
 ): Subregistry[] {
-  const indexedSubregistries: Subregistry[] = [];
-
-  if (activePlugins.includes(PluginName.Subgraph)) {
-    indexedSubregistries.push({
-      subregistryId: getEthnamesSubregistryId(namespaceId),
-      node: namehashInterpretedName(getEthnamesSubregistryManagedName(namespaceId)),
-    });
-  }
-
-  if (activePlugins.includes(PluginName.Basenames)) {
-    indexedSubregistries.push({
-      subregistryId: getBasenamesSubregistryId(namespaceId),
-      node: namehashInterpretedName(getBasenamesSubregistryManagedName(namespaceId)),
-    });
-  }
+  return [
+    { plugin: PluginName.Subgraph, datasource: DatasourceNames.ENSRoot },
+    { plugin: PluginName.Basenames, datasource: DatasourceNames.Basenames },
+    { plugin: PluginName.Lineanames, datasource: DatasourceNames.Lineanames },
+  ].flatMap(({ plugin, datasource }): Subregistry[] => {
+    if (!activePlugins.includes(plugin)) return [];
 
-  if (activePlugins.includes(PluginName.Lineanames)) {
-    indexedSubregistries.push({
-      subregistryId: getLineanamesSubregistryId(namespaceId),
-      node: namehashInterpretedName(getLineanamesSubregistryManagedName(namespaceId)),
-    });
-  }
+    const subregistryId = maybeGetDatasourceContract(namespaceId, datasource, "BaseRegistrar");
+    if (!subregistryId) return [];
 
-  return indexedSubregistries;
+    // get the Registrar's Managed Node
+    const { node } = getManagedName(namespaceId, subregistryId);
+    return [{ subregistryId, node }];
+  });
 }

apps/ensapi/src/lib/protocol-acceleration/find-resolver.ts

@@ -19,7 +19,6 @@ import { accountIdEqual, getDatasourceContract, isENSv1Registry } from "@ensnode
 
 import { ensDb } from "@/lib/ensdb/singleton";
 import { withActiveSpanAsync, withSpanAsync } from "@/lib/instrumentation/auto-span";
-import { lazyProxy } from "@/lib/lazy";
 
 type FindResolverResult =
   | {
@@ -37,12 +36,6 @@ const NULL_RESULT: FindResolverResult = {
 
 const tracer = trace.getTracer("find-resolver");
 
-// lazyProxy defers construction until first use so that this module can be
-// imported without env vars being present (e.g. during OpenAPI generation).
-const ensv1RegistryOld = lazyProxy(() =>
-  getDatasourceContract(config.namespace, DatasourceNames.ENSRoot, "ENSv1RegistryOld"),
-);
-
 /**
  * Identifies `name`'s active resolver in `registry`.
  *
@@ -202,6 +195,11 @@ async function findResolverWithIndex(
         "domainResolverRelation.findMany",
         {},
         async () => {
+          const ENSv1RegistryOld = getDatasourceContract(
+            config.namespace,
+            DatasourceNames.ENSRoot,
+            "ENSv1RegistryOld",
+          );
           // the current ENS Root Chain Registry is actually ENSRegistryWithFallback: if a node
           // doesn't exist in its own storage, it directs the lookup to RegistryOld. We must encode
           // this logic here, so that the active resolver of unmigrated nodes can be correctly identified.
@@ -215,8 +213,8 @@ async function findResolverWithIndex(
                   // OR, if the registry is the ENS Root Registry, also include records from RegistryOld
                   isENSv1Registry(config.namespace, registry)
                     ? and(
-                        eq(t.chainId, ensv1RegistryOld.chainId),
-                        eq(t.address, ensv1RegistryOld.address),
+                        eq(t.chainId, ENSv1RegistryOld.chainId),
+                        eq(t.address, ENSv1RegistryOld.address),
                       )
                     : undefined,
                 ),

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

@@ -245,7 +245,8 @@ async function _resolveForward<SELECTION extends ResolverRecordsSelection>(
                 TraceableENSProtocol.ForwardResolution,
                 ForwardResolutionProtocolStep.AccelerateKnownOffchainLookupResolver,
                 {},
-                () => _resolveForward(name, selection, { ...options, registry: bridgesTo }),
+                () =>
+                  _resolveForward(name, selection, { ...options, registry: bridgesTo.registry }),
               );
             }
 

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

@@ -1,23 +1,18 @@
 import DataLoader from "dataloader";
 import { getUnixTime } from "date-fns";
-import type { CanonicalPath, ENSv1DomainId, ENSv2DomainId } from "enssdk";
+import type { CanonicalPath, DomainId } from "enssdk";
 
-import { getV1CanonicalPath, getV2CanonicalPath } from "./lib/get-canonical-path";
+import { getCanonicalPath } from "./lib/get-canonical-path";
 
 /**
  * A Promise.catch handler that provides the thrown error as a resolved value, useful for Dataloaders.
  */
 const errorAsValue = (error: unknown) =>
   error instanceof Error ? error : new Error(String(error));
 
-const createV1CanonicalPathLoader = () =>
-  new DataLoader<ENSv1DomainId, CanonicalPath | null>(async (domainIds) =>
-    Promise.all(domainIds.map((id) => getV1CanonicalPath(id).catch(errorAsValue))),
-  );
-
-const createV2CanonicalPathLoader = () =>
-  new DataLoader<ENSv2DomainId, CanonicalPath | null>(async (domainIds) =>
-    Promise.all(domainIds.map((id) => getV2CanonicalPath(id).catch(errorAsValue))),
+const createCanonicalPathLoader = () =>
+  new DataLoader<DomainId, CanonicalPath | Error | null>(async (domainIds) =>
+    Promise.all(domainIds.map((id) => getCanonicalPath(id).catch(errorAsValue))),
   );
 
 /**
@@ -28,7 +23,6 @@ const createV2CanonicalPathLoader = () =>
 export const context = () => ({
   now: BigInt(getUnixTime(new Date())),
   loaders: {
-    v1CanonicalPath: createV1CanonicalPathLoader(),
-    v2CanonicalPath: createV2CanonicalPathLoader(),
+    canonicalPath: createCanonicalPathLoader(),
   },
 });

apps/ensapi/src/omnigraph-api/lib/find-domains/canonical-registries-cte.ts

@@ -2,45 +2,43 @@ import config from "@/config";
 
 import { sql } from "drizzle-orm";
 
-import { maybeGetENSv2RootRegistryId } from "@ensnode/ensnode-sdk";
+import { getRootRegistryIds } from "@ensnode/ensnode-sdk";
 
 import { ensDb, ensIndexerSchema } from "@/lib/ensdb/singleton";
-import { lazy } from "@/lib/lazy";
 
 /**
- * The maximum depth to traverse the ENSv2 namegraph in order to construct the set of Canonical
- * Registries.
+ * The maximum depth to traverse the namegraph in order to construct the set of Canonical Registries.
  *
- * Note that the set of Canonical Registries in the ENSv2 Namegraph is a _tree_, enforced by the
- * requirement that each Registry maintain a reverse-pointer to its Canonical Domain, a form of
- * 'edge authentication': if the reverse-pointer doesn't agree with the forward-pointer, the edge
- * is not traversed, making cycles within the direced graph impossible.
+ * The CTE walks `domain.subregistryId` forward from every Root Registry. `subregistryId` is the
+ * source-of-truth forward pointer, so no separate edge-authentication is needed — a Registry is
+ * canonical iff it is reachable via a chain of live forward pointers from a Root.
  *
- * So while technically not necessary, including the depth constraint avoids the possibility of an
- * infinite runaway query in the event that the indexed namegraph is somehow corrupted or otherwise
- * introduces a canonical cycle.
+ * The reachable set is a DAG, not a tree: aliased subregistries let multiple parent Domains
+ * declare the same child Registry, so the same row can appear at multiple depths during recursion.
+ * The outer projection dedupes via `SELECT DISTINCT`; `MAX_DEPTH` bounds runaway recursion if the
+ * graph is corrupted.
  */
 const CANONICAL_REGISTRIES_MAX_DEPTH = 16;
 
-// lazy() defers construction until first use so that this module can be
-// imported without env vars being present (e.g. during OpenAPI generation).
-const getENSV2RootRegistryId = lazy(() => maybeGetENSv2RootRegistryId(config.namespace));
-
 /**
- * Builds a recursive CTE that traverses from the ENSv2 Root Registry to construct a set of all
- * Canonical Registries. A Canonical Registry is an ENSv2 Registry that is the Root Registry or the
- * (sub)Registry of a Domain in a Canonical Registry.
+ * Builds a recursive CTE that traverses forward from every top-level Root Registry configured for
+ * the namespace (the ENSv1 Root Registry, the Basenames and Lineanames ENSv1VirtualRegistries when
+ * configured, and the ENSv2 Root Registry when defined — see {@link getRootRegistryIds}) to
+ * construct a set of all Canonical Registries.
+ *
+ * A Canonical Registry is one whose Domains are resolvable under the primary resolution pipeline.
+ * This includes both the ENSv2 subtree and every ENSv1 subtree: Universal Resolver v2 falls back
+ * to ENSv1 at resolution time for names not (yet) present in ENSv2, so ENSv1 Domains remain
+ * canonical from a resolution perspective.
  *
  * TODO: could this be optimized further, perhaps as a materialized view?
  */
 export const getCanonicalRegistriesCTE = () => {
-  // if ENSv2 is not defined, return an empty set with identical structure to below
-  if (!getENSV2RootRegistryId()) {
-    return ensDb
-      .select({ id: sql<string>`registry_id`.as("id") })
-      .from(sql`(SELECT NULL::text AS registry_id WHERE FALSE) AS canonical_registries_cte`)
-      .as("canonical_registries");
-  }
+  const roots = getRootRegistryIds(config.namespace);
+
+  const rootsUnion = roots
+    .map((root) => sql`SELECT ${root}::text AS registry_id, 0 AS depth`)
+    .reduce((acc, part, i) => (i === 0 ? part : sql`${acc} UNION ALL ${part}`));
 
   return ensDb
     .select({
@@ -53,15 +51,18 @@ export const getCanonicalRegistriesCTE = () => {
       sql`
       (
         WITH RECURSIVE canonical_registries AS (
-          SELECT ${getENSV2RootRegistryId()}::text AS registry_id, 0 AS depth
+          ${rootsUnion}
           UNION ALL
-          SELECT rcd.registry_id, cr.depth + 1
-          FROM ${ensIndexerSchema.registryCanonicalDomain} rcd
-          JOIN ${ensIndexerSchema.v2Domain} parent ON parent.id = rcd.domain_id AND parent.subregistry_id = rcd.registry_id
-          JOIN canonical_registries cr ON cr.registry_id = parent.registry_id
+          SELECT d.subregistry_id AS registry_id, cr.depth + 1
+          FROM canonical_registries cr
+          JOIN ${ensIndexerSchema.domain} d ON d.registry_id = cr.registry_id
+
+          -- Filter nulls at the recursive step so Domains without a subregistry don't
+          -- emit null rows into the CTE and don't spawn dead-end recursion branches.
           WHERE cr.depth < ${CANONICAL_REGISTRIES_MAX_DEPTH}
+            AND d.subregistry_id IS NOT NULL
         )
-        SELECT registry_id FROM canonical_registries
+        SELECT DISTINCT registry_id FROM canonical_registries
       ) AS canonical_registries_cte`,
     )
     .as("canonical_registries");