ENSv2 Find Domain Ordering Support

.changeset/whole-ways-grin.md

@@ -0,0 +1,5 @@
+---
+"ensapi": minor
+---
+
+ENSv2 GraphQL API: Introduces order criteria for Domain methods, i.e. `Account.domains(order: { by: NAME, dir: ASC })`. The supported Order criteria are `NAME`, `REGISTRATION_TIMESTAMP`, and `REGISTRATION_EXPIRY` in either `ASC` or `DESC` orders, defaulting to `NAME` and `ASC`.

apps/ensapi/package.json

@@ -57,6 +57,7 @@
     "pg-connection-string": "catalog:",
     "pino": "catalog:",
     "ponder-enrich-gql-docs-middleware": "^0.1.3",
+    "superjson": "^2.2.6",
     "viem": "catalog:",
     "zod": "catalog:"
   },

apps/ensapi/src/graphql-api/lib/find-domains/domain-cursor.ts

@@ -0,0 +1,49 @@
+import superjson from "superjson";
+
+import type { DomainId } from "@ensnode/ensnode-sdk";
+
+import type { DomainOrderValue } from "@/graphql-api/lib/find-domains/types";
+import type { DomainsOrderBy } from "@/graphql-api/schema/domain";
+import type { OrderDirection } from "@/graphql-api/schema/order-direction";
+
+/**
+ * Composite Domain cursor for keyset pagination.
+ * Includes the order column value to enable proper tuple comparison without subqueries.
+ *
+ * @dev A composite cursor is required to support stable pagination over the set, regardless of which
+ * column and which direction the set is ordered.
+ */
+export interface DomainCursor {
+  /**
+   * Stable identifier for tiebreaks.
+   */
+  id: DomainId;
+
+  /**
+   * The criteria by which the set is ordered. One of NAME, REGISTRATION_TIMESTAMP, or REGISTRATION_EXPIRY.
+   */
+  by: typeof DomainsOrderBy.$inferType;
+
+  /**
+   * The direction in which the set is ordered, either ASC or DESC.
+   */
+  dir: typeof OrderDirection.$inferType;
+
+  /**
+   * The value of the sort column for this Domain in the set.
+   */
+  value: DomainOrderValue;
+}
+
+/**
+ * Encoding/Decoding helper for Composite DomainCursors.
+ *
+ * @dev it's base64'd (super)json
+ */
+export const DomainCursor = {
+  encode: (cursor: DomainCursor) =>
+    Buffer.from(superjson.stringify(cursor), "utf8").toString("base64"),
+  // TODO: in the future, validate the cursor format matches DomainCursor
+  decode: (cursor: string) =>
+    superjson.parse<DomainCursor>(Buffer.from(cursor, "base64").toString("utf8")),
+};

apps/ensapi/src/graphql-api/lib/find-domains.ts → apps/ensapi/src/graphql-api/lib/find-domains/find-domains-by-labelhash-path.ts

@@ -1,146 +1,9 @@
-import { and, eq, like, Param, sql } from "drizzle-orm";
-import { alias, unionAll } from "drizzle-orm/pg-core";
-import type { Address } from "viem";
+import { Param, sql } from "drizzle-orm";
 
 import * as schema from "@ensnode/ensnode-schema";
-import {
-  type DomainId,
-  type ENSv1DomainId,
-  type ENSv2DomainId,
-  interpretedLabelsToLabelHashPath,
-  type LabelHashPath,
-  type Name,
-  parsePartialInterpretedName,
-} from "@ensnode/ensnode-sdk";
+import type { ENSv1DomainId, ENSv2DomainId, LabelHashPath } from "@ensnode/ensnode-sdk";
 
 import { db } from "@/lib/db";
-import { makeLogger } from "@/lib/logger";
-
-const logger = makeLogger("find-domains");
-
-const MAX_DEPTH = 16;
-
-interface DomainFilter {
-  name?: Name | undefined | null;
-  owner?: Address | undefined | null;
-}
-
-/**
- * Find Domains by Canonical Name.
- *
- * @throws if neither `name` or `owner` are provided
- * @throws if `name` is provided but is not a valid Partial InterpretedName
- *
- * ## Terminology:
- *
- * - a 'Canonical Domain' is a Domain connected to either the ENSv1 Root or the ENSv2 Root. All ENSv1
- *  Domains are Canonical Domains, but an ENSv2 Domain may not be Canonical, for example if it exists
- *  in a disjoint nametree or its Registry does not declare a Canonical Domain.
- * - a 'Partial InterpretedName' is a partial InterpretedName (ex: 'examp', 'example.', 'sub1.sub2.paren')
- *
- * ## Background:
- *
- * Materializing the set of Canonical Names in ENSv2 is non-trivial and more or less impossible
- * within the confines of Ponder's cache semantics. Additionally retroactive label healing (due to
- * new labels being discovered on-chain) is likely impossible within those constraints as well. If we
- * were to implement a naive cache-unfriendly version of canonical name materialization, indexing time
- * would increase dramatically.
- *
- * The overall user story we're trying to support is 'autocomplete' or 'search (my) domains'. More
- * specifically, given a partial InterpretedName as input (ex: 'examp', 'example.', 'sub1.sub2.paren'),
- * produce a set of Domains addressable by the provided partial InterpretedName.
- *
- * While complicated to do so, it is more correct to perform this calculation at query-time rather
- * than at index-time, given the constraints above.
- *
- * ## Algorithm
- *
- * 1. parse Partial InterpretedName into concrete path and partial fragment
- *   i.e. for a `name` like "sub1.sub2.paren":
- *    - concrete = ["sub1", "sub2"]
- *    - partial = 'paren'
- * 2. validate inputs
- * 3. for both v1Domains and v2Domains
- *   a. construct a subquery that filters the set of Domains to those with the specific concrete path
- *   b. if provided, filter the head domains of that path by `partial`
- *   c. if provided, filter the leaf domains of that path by `owner`
- * 4. construct a union of the two result sets and return
- */
-export function findDomains({ name, owner }: DomainFilter) {
-  // NOTE: if name is not provided, parse empty string to simplify control-flow, validity checked below
-  // NOTE: throws if name is not a Partial InterpretedName
-  const { concrete, partial } = parsePartialInterpretedName(name || "");
-
-  // validate depth to prevent arbitrary recursion in CTEs
-  if (concrete.length > MAX_DEPTH) {
-    throw new Error(`Invariant(findDomains): Name depth exceeds maximum of ${MAX_DEPTH} labels.`);
-  }
-
-  logger.debug({ input: { name, owner, concrete, partial } });
-
-  // a name input is valid if it was parsed to something other than just empty string
-  const validName = concrete.length > 0 || partial !== "";
-  const validOwner = !!owner;
-
-  // Invariant: one of name or owner must be provided
-  // TODO: maybe this should be zod...
-  if (!validName && !validOwner) {
-    throw new Error(`Invariant(findDomains): One of 'name' or 'owner' must be provided.`);
-  }
-
-  const labelHashPath = interpretedLabelsToLabelHashPath(concrete);
-
-  // compose subquery by concrete LabelHashPath
-  const v1DomainsByLabelHashPathQuery = v1DomainsByLabelHashPath(labelHashPath);
-  const v2DomainsByLabelHashPathQuery = v2DomainsByLabelHashPath(labelHashPath);
-
-  // alias for the head domains (to get its labelHash for partial matching)
-  const v1HeadDomain = alias(schema.v1Domain, "v1HeadDomain");
-  const v2HeadDomain = alias(schema.v2Domain, "v2HeadDomain");
-
-  // join on leafId (the autocomplete result), filter by owner and partial
-  const v1Domains = db
-    .select({ id: sql<DomainId>`${schema.v1Domain.id}`.as("id") })
-    .from(schema.v1Domain)
-    .innerJoin(
-      v1DomainsByLabelHashPathQuery,
-      eq(schema.v1Domain.id, v1DomainsByLabelHashPathQuery.leafId),
-    )
-    .innerJoin(v1HeadDomain, eq(v1HeadDomain.id, v1DomainsByLabelHashPathQuery.headId))
-    .leftJoin(schema.label, eq(schema.label.labelHash, v1HeadDomain.labelHash))
-    .where(
-      and(
-        owner ? eq(schema.v1Domain.ownerId, owner) : undefined,
-        // TODO: determine if it's necessary to additionally escape user input for LIKE operator
-        // Note: if label is NULL (unlabeled domain), LIKE returns NULL and filters out the row.
-        // This is intentional - we can't match partial text against unknown labels.
-        partial ? like(schema.label.interpreted, `${partial}%`) : undefined,
-      ),
-    );
-
-  // join on leafId (the autocomplete result), filter by owner and partial
-  const v2Domains = db
-    .select({ id: sql<DomainId>`${schema.v2Domain.id}`.as("id") })
-    .from(schema.v2Domain)
-    .innerJoin(
-      v2DomainsByLabelHashPathQuery,
-      eq(schema.v2Domain.id, v2DomainsByLabelHashPathQuery.leafId),
-    )
-    .innerJoin(v2HeadDomain, eq(v2HeadDomain.id, v2DomainsByLabelHashPathQuery.headId))
-    .leftJoin(schema.label, eq(schema.label.labelHash, v2HeadDomain.labelHash))
-    .where(
-      and(
-        owner ? eq(schema.v2Domain.ownerId, owner) : undefined,
-        // TODO: determine if it's necessary to additionally escape user input for LIKE operator
-        // Note: if label is NULL (unlabeled domain), LIKE returns NULL and filters out the row.
-        // This is intentional - we can't match partial text against unknown labels.
-        partial ? like(schema.label.interpreted, `${partial}%`) : undefined,
-      ),
-    );
-
-  // union the two subqueries and return
-  return db.$with("domains").as(unionAll(v1Domains, v2Domains));
-}
 
 /**
  * Compose a query for v1Domains that have the specified children path.
@@ -157,7 +20,7 @@ export function findDomains({ name, owner }: DomainFilter) {
  * Algorithm: Start from the deepest child (leaf) and traverse UP to find the head.
  * This is more efficient than starting from all domains and traversing down.
  */
-function v1DomainsByLabelHashPath(labelHashPath: LabelHashPath) {
+export function v1DomainsByLabelHashPath(labelHashPath: LabelHashPath) {
   // If no concrete path, return all domains (leaf = head = self)
   // Postgres will optimize this simple subquery when joined
   if (labelHashPath.length === 0) {
@@ -232,7 +95,7 @@ function v1DomainsByLabelHashPath(labelHashPath: LabelHashPath) {
  * Algorithm: Start from the deepest child (leaf) and traverse UP via registryCanonicalDomain.
  * For v2, parent relationship is: domain.registryId -> registryCanonicalDomain -> parent domainId
  */
-function v2DomainsByLabelHashPath(labelHashPath: LabelHashPath) {
+export function v2DomainsByLabelHashPath(labelHashPath: LabelHashPath) {
   // If no concrete path, return all domains (leaf = head = self)
   // Postgres will optimize this simple subquery when joined
   if (labelHashPath.length === 0) {

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

@@ -0,0 +1,144 @@
+import { type ResolveCursorConnectionArgs, resolveCursorConnection } from "@pothos/plugin-relay";
+import { and } from "drizzle-orm";
+
+import type { context as createContext } from "@/graphql-api/context";
+import { rejectAnyErrors } from "@/graphql-api/lib/reject-any-errors";
+import { DEFAULT_CONNECTION_ARGS } from "@/graphql-api/schema/constants";
+import {
+  DOMAINS_DEFAULT_ORDER_BY,
+  DOMAINS_DEFAULT_ORDER_DIR,
+  DomainInterfaceRef,
+  type DomainsOrderBy,
+} from "@/graphql-api/schema/domain";
+import { db } from "@/lib/db";
+import { makeLogger } from "@/lib/logger";
+
+import { DomainCursor } from "./domain-cursor";
+import { cursorFilter, findDomains, isEffectiveDesc, orderFindDomains } from "./find-domains";
+import type {
+  DomainOrderValue,
+  DomainWithOrderValue,
+  FindDomainsOrderArg,
+  FindDomainsResult,
+  FindDomainsWhereArg,
+} from "./types";
+
+const logger = makeLogger("find-domains-resolver");
+
+/**
+ * Extract the order value from a findDomains result row based on the orderBy field.
+ */
+function getOrderValueFromResult(
+  result: FindDomainsResult,
+  orderBy: typeof DomainsOrderBy.$inferType,
+): DomainOrderValue {
+  switch (orderBy) {
+    case "NAME":
+      return result.headLabel;
+    case "REGISTRATION_TIMESTAMP":
+      return result.registrationTimestamp;
+    case "REGISTRATION_EXPIRY":
+      return result.registrationExpiry;
+  }
+}
+
+/**
+ * Shared GraphQL API resolver for domains connection queries, used by Query.domains and
+ * Account.domains.
+ *
+ * @param context - The GraphQL Context, required for Dataloader access
+ * @param args - The GraphQL Args object (via t.connection) + FindDomains-specific args (where, order)
+ */
+export function resolveFindDomains(
+  context: ReturnType<typeof createContext>,
+  {
+    where,
+    order,
+    ...connectionArgs
+  }: {
+    // `where` MUST be provided, we don't currently allow iterating over the full set of domains
+    where: FindDomainsWhereArg;
+    // `order` MAY be provided; defaults are used otherwise
+    order?: FindDomainsOrderArg | undefined | null;
+
+    // these resolver arguments are from t.connection
+    first?: number | null;
+    last?: number | null;
+    before?: string | null;
+    after?: string | null;
+  },
+) {
+  const orderBy = order?.by ?? DOMAINS_DEFAULT_ORDER_BY;
+  const orderDir = order?.dir ?? DOMAINS_DEFAULT_ORDER_DIR;
+
+  return resolveCursorConnection(
+    {
+      ...DEFAULT_CONNECTION_ARGS,
+      args: connectionArgs,
+      toCursor: (domain: DomainWithOrderValue) =>
+        DomainCursor.encode({
+          id: domain.id,
+          by: orderBy,
+          dir: orderDir,
+          value: domain.__orderValue,
+        }),
+    },
+    async ({ before, after, limit, inverted }: ResolveCursorConnectionArgs) => {
+      // identify whether the effective sort direction is descending
+      const effectiveDesc = isEffectiveDesc(orderDir, inverted);
+
+      // construct query for relevant domains
+      const domains = findDomains(where);
+
+      // build order clauses
+      const orderClauses = orderFindDomains(domains, orderBy, orderDir, inverted);
+
+      // decode cursors for keyset pagination
+      const beforeCursor = before ? DomainCursor.decode(before) : undefined;
+      const afterCursor = after ? DomainCursor.decode(after) : undefined;
+
+      // build query with pagination constraints
+      const query = db
+        .with(domains)
+        .select()
+        .from(domains)
+        .where(
+          and(
+            beforeCursor
+              ? cursorFilter(domains, beforeCursor, orderBy, orderDir, "before", effectiveDesc)
+              : undefined,
+            afterCursor
+              ? cursorFilter(domains, afterCursor, orderBy, orderDir, "after", effectiveDesc)
+              : undefined,
+          ),
+        )
+        .orderBy(...orderClauses)
+        .limit(limit);
+
+      // log the generated SQL for debugging
+      logger.debug({ sql: query.toSQL() });
+
+      // execute query
+      const results = await query;
+
+      // load Domain entities via dataloader
+      const loadedDomains = await rejectAnyErrors(
+        DomainInterfaceRef.getDataloader(context).loadMany(results.map((result) => result.id)),
+      );
+
+      // map results by id for faster order value lookup
+      const orderValueById = new Map(
+        results.map((r) => [r.id, getOrderValueFromResult(r, orderBy)]),
+      );
+
+      // inject order values into each result so that it can be encoded into the cursor
+      // (see DomainCursor for more information)
+      return loadedDomains.map((domain): DomainWithOrderValue => {
+        const __orderValue = orderValueById.get(domain.id);
+        if (__orderValue === undefined) throw new Error(`Never: guaranteed to be DomainOrderValue`);
+
+        return { ...domain, __orderValue };
+      });
+    },
+  );
+}