ENSDb migrations

.changeset/big-impalas-brush.md

@@ -0,0 +1,5 @@
+---
+"ensindexer": minor
+---
+
+Extended `EnsDbClient` with `EnsDbClientMigration` interface implementation.

.changeset/breezy-corners-tickle.md

@@ -0,0 +1,5 @@
+---
+"ensapi": minor
+---
+
+ENSNode GraphQL API: `Registration.start` is now available, indicating the start timestamp of the Registration.

.changeset/clever-chicken-listen.md

@@ -0,0 +1,6 @@
+---
+"ensapi": minor
+"ensindexer": minor
+---
+
+The ENSv2 Plugin can now be safely activated for ENSv1-only namespaces (ex: 'mainnet', 'sepolia').

.changeset/light-ducks-thank.md

@@ -0,0 +1,5 @@
+---
+"ensapi": minor
+---
+
+Introduces integration testing for the ENSv2 Plugin and GraphQL API against the ENSv2 devnet.

.changeset/seven-hands-ask.md

@@ -0,0 +1,5 @@
+---
+"@ensnode/ensnode-sdk": minor
+---
+
+Introduced `EnsDbClientMigration` interface.

.changeset/shy-wolves-judge.md

@@ -0,0 +1,5 @@
+---
+"ensapi": minor
+---
+
+ENSNode GraphQL API: Add `where` filters to all `*.events` connections (`Domain.events`, `Resolver.events`, `Permissions.events`, `Account.events`). Supports filtering by `selector_in`, `timestamp_gte`, `timestamp_lte`, and `from` (where applicable). Also adds `Account.events` field to find events by transaction sender.

.changeset/silly-bats-smell.md

@@ -0,0 +1,5 @@
+---
+"ensindexer": minor
+---
+
+Introduced database migration toolkit based on `drizzle-kit`.

.changeset/wide-chicken-dream.md

@@ -0,0 +1,5 @@
+---
+"ensapi": minor
+---
+
+ENSNode GraphQL API: `Account.events` now provides the set of Events for which this Account is the sender (i.e. `Transaction.from`).

.gitignore

@@ -31,8 +31,9 @@ generated
 .terraform*
 terraform.tfstate*
 
-# CLAUDE.md
+# Claude
 CLAUDE.md
+.claude
 
 # ENSRainbow data
 apps/ensrainbow/data*

apps/ensapi/.env.local.example

@@ -12,12 +12,9 @@ ENSINDEXER_URL=http://localhost:42069
 # It should be in the format of `postgresql://<username>:<password>@<host>:<port>/<database>`
 #
 # See https://ensnode.io/ensindexer/usage/configuration/ for additional information.
+# NOTE that ENSApi does NOT need to define DATABASE_SCHEMA, as it is inferred from the connected ENSIndexer's Config.
 DATABASE_URL=postgresql://dbuser:abcd1234@localhost:5432/my_database
 
-# ENSDb: Database Schema name for ENSIndexer Schema
-# Required. Should match the DATABASE_SCHEMA used by the connected ENSIndexer.
-DATABASE_SCHEMA=public
-
 # ENSApi: RPC Configuration
 # Required. ENSApi requires an HTTP RPC to the connected ENSIndexer's ENS Root Chain, which depends
 # on ENSIndexer's NAMESPACE (ex: mainnet, sepolia, ens-test-env). This ENS Root Chain RPC

apps/ensapi/src/config/config.schema.test.ts

@@ -19,20 +19,12 @@ vi.mock("@/lib/logger", () => ({
     error: vi.fn(),
     info: vi.fn(),
   },
-  makeLogger: vi.fn(() => ({
-    error: vi.fn(),
-    info: vi.fn(),
-    debug: vi.fn(),
-    warn: vi.fn(),
-    trace: vi.fn(),
-  })),
 }));
 
 const VALID_RPC_URL = "https://eth-sepolia.g.alchemy.com/v2/1234";
 
 const BASE_ENV = {
   DATABASE_URL: "postgresql://user:password@localhost:5432/mydb",
-  DATABASE_SCHEMA: "public",
   ENSINDEXER_URL: "http://localhost:42069",
   RPC_URL_1: VALID_RPC_URL,
 } satisfies EnsApiEnvironment;
@@ -58,20 +50,6 @@ const ENSINDEXER_PUBLIC_CONFIG = {
   },
 } satisfies ENSIndexerPublicConfig;
 
-// Mock EnsDbClient - must be defined after ENSINDEXER_PUBLIC_CONFIG since vi.mock is hoisted
-// We'll use a simple class mock and configure it in beforeEach
-const mockGetVersion = vi.fn().mockResolvedValue("1.0.0");
-const mockGetEnsIndexerPublicConfig = vi.fn().mockResolvedValue(ENSINDEXER_PUBLIC_CONFIG);
-const mockGetIndexingStatusSnapshot = vi.fn().mockResolvedValue(null);
-
-vi.mock("@/lib/ensdb-client/ensdb-client", () => ({
-  EnsDbClient: class MockEnsDbClient {
-    getVersion = mockGetVersion;
-    getEnsIndexerPublicConfig = mockGetEnsIndexerPublicConfig;
-    getIndexingStatusSnapshot = mockGetIndexingStatusSnapshot;
-  },
-}));
-
 const mockFetch = vi.fn();
 vi.stubGlobal("fetch", mockFetch);
 
@@ -138,7 +116,6 @@ describe("buildConfigFromEnvironment", () => {
 
     const TEST_ENV: EnsApiEnvironment = {
       DATABASE_URL: BASE_ENV.DATABASE_URL,
-      DATABASE_SCHEMA: BASE_ENV.DATABASE_SCHEMA,
       ENSINDEXER_URL: BASE_ENV.ENSINDEXER_URL,
     };
 

apps/ensapi/src/config/config.schema.ts

@@ -1,5 +1,6 @@
 import packageJson from "@/../package.json" with { type: "json" };
 
+import pRetry from "p-retry";
 import { parse as parseConnectionString } from "pg-connection-string";
 import { prettifyError, ZodError, z } from "zod/v4";
 
@@ -20,7 +21,7 @@ import {
 import { ENSApi_DEFAULT_PORT } from "@/config/defaults";
 import type { EnsApiEnvironment } from "@/config/environment";
 import { invariant_ensIndexerPublicConfigVersionInfo } from "@/config/validations";
-import { EnsDbClient } from "@/lib/ensdb-client/ensdb-client";
+import { fetchENSIndexerConfig } from "@/lib/fetch-ensindexer-config";
 import logger from "@/lib/logger";
 
 export const DatabaseUrlSchema = z.string().refine(
@@ -76,19 +77,6 @@ const EnsApiConfigSchema = z
 
 export type EnsApiConfig = z.infer<typeof EnsApiConfigSchema>;
 
-/**
- * Builds an instance of {@link EnsDbClient} using environment variables.
- *
- * @returns instance of {@link EnsDbClient}
- * @throws Error with formatted validation messages if environment parsing fails
- */
-function buildEnsDbClientFromEnvironment(env: EnsApiEnvironment): EnsDbClient {
-  const databaseUrl = DatabaseUrlSchema.parse(env.DATABASE_URL);
-  const ensIndexerSchemaName = DatabaseSchemaNameSchema.parse(env.DATABASE_SCHEMA);
-
-  return new EnsDbClient(databaseUrl, ensIndexerSchemaName);
-}
-
 /**
  * Builds the EnsApiConfig from an EnsApiEnvironment object, fetching the EnsIndexerPublicConfig.
  *
@@ -97,13 +85,16 @@ function buildEnsDbClientFromEnvironment(env: EnsApiEnvironment): EnsDbClient {
  */
 export async function buildConfigFromEnvironment(env: EnsApiEnvironment): Promise<EnsApiConfig> {
   try {
-    const ensDbClient = buildEnsDbClientFromEnvironment(env);
-
-    const ensIndexerPublicConfig = await ensDbClient.getEnsIndexerPublicConfig();
-
-    if (!ensIndexerPublicConfig) {
-      throw new Error("Failed to load EnsIndexerPublicConfig from ENSDb.");
-    }
+    const ensIndexerUrl = EnsIndexerUrlSchema.parse(env.ENSINDEXER_URL);
+
+    const ensIndexerPublicConfig = await pRetry(() => fetchENSIndexerConfig(ensIndexerUrl), {
+      retries: 3,
+      onFailedAttempt: ({ error, attemptNumber, retriesLeft }) => {
+        logger.info(
+          `ENSIndexer Config fetch attempt ${attemptNumber} failed (${error.message}). ${retriesLeft} retries left.`,
+        );
+      },
+    });
 
     const rpcConfigs = buildRpcConfigsFromEnv(env, ensIndexerPublicConfig.namespace);
 

apps/ensapi/src/config/environment.ts

@@ -15,7 +15,7 @@ import type {
  * their state in `process.env`. This interface is intended to be the source type which then gets
  * mapped/parsed into a structured configuration object like `EnsApiConfig`.
  */
-export type EnsApiEnvironment = DatabaseEnvironment &
+export type EnsApiEnvironment = Omit<DatabaseEnvironment, "DATABASE_SCHEMA"> &
   EnsIndexerUrlEnvironment &
   RpcEnvironment &
   PortEnvironment &

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

@@ -9,8 +9,14 @@ import type {
   DomainId,
   InterpretedName,
   Node,
+  PermissionsId,
+  PermissionsResourceId,
+  PermissionsUserId,
+  RegistrationId,
   RegistryId,
+  RenewalId,
   ResolverId,
+  ResolverRecordsId,
 } from "@ensnode/ensnode-sdk";
 
 import type { context } from "@/graphql-api/context";
@@ -28,7 +34,12 @@ export const builder = new SchemaBuilder<{
     DomainId: { Input: DomainId; Output: DomainId };
     RegistryId: { Input: RegistryId; Output: RegistryId };
     ResolverId: { Input: ResolverId; Output: ResolverId };
-    // PermissionsId: { Input: PermissionsId; Output: PermissionsId };
+    PermissionsId: { Input: PermissionsId; Output: PermissionsId };
+    PermissionsResourceId: { Input: PermissionsResourceId; Output: PermissionsResourceId };
+    PermissionsUserId: { Input: PermissionsUserId; Output: PermissionsUserId };
+    RegistrationId: { Input: RegistrationId; Output: RegistrationId };
+    RenewalId: { Input: RenewalId; Output: RenewalId };
+    ResolverRecordsId: { Input: ResolverRecordsId; Output: ResolverRecordsId };
   };
 
   // the following ensures via typechecker that every t.connection returns a totalCount field

apps/ensapi/src/graphql-api/lib/connection-helpers.ts

@@ -1,7 +1,7 @@
 import { and, asc, desc, gt, lt } from "drizzle-orm";
 import z from "zod/v4";
 
-import { cursors } from "@/graphql-api/schema/cursors";
+import { cursors } from "@/graphql-api/lib/cursors";
 
 type Column = Parameters<typeof lt>[0];
 

apps/ensapi/src/graphql-api/lib/cursors.ts

@@ -0,0 +1,20 @@
+import superjson from "superjson";
+
+/**
+ * It's considered good practice to provide cursors as opaque strings exclusively useful for
+ * paginating sets, so we encode/decode values using base64'd superjson.
+ *
+ * superjson handles BigInt and other non-JSON-native types transparently.
+ */
+export const cursors = {
+  encode: <T>(value: T) => Buffer.from(superjson.stringify(value), "utf8").toString("base64"),
+  decode: <T>(cursor: string): T => {
+    try {
+      return superjson.parse<T>(Buffer.from(cursor, "base64").toString("utf8"));
+    } catch {
+      throw new Error(
+        "Invalid cursor: failed to decode cursor. The cursor may be malformed or from an incompatible query.",
+      );
+    }
+  },
+};

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

@@ -3,7 +3,7 @@ import config from "@/config";
 import { sql } from "drizzle-orm";
 
 import * as schema from "@ensnode/ensnode-schema";
-import { getENSv2RootRegistryId } from "@ensnode/ensnode-sdk";
+import { maybeGetENSv2RootRegistryId } from "@ensnode/ensnode-sdk";
 
 import { db } from "@/lib/db";
 
@@ -22,33 +22,45 @@ import { db } from "@/lib/db";
  */
 const CANONICAL_REGISTRIES_MAX_DEPTH = 16;
 
+const ENSV2_ROOT_REGISTRY_ID = 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.
  *
  * TODO: could this be optimized further, perhaps as a materialized view?
  */
-export const getCanonicalRegistriesCTE = () =>
-  db
+export const getCanonicalRegistriesCTE = () => {
+  // if ENSv2 is not defined, return an empty set with identical structure to below
+  if (!ENSV2_ROOT_REGISTRY_ID) {
+    return db
+      .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");
+  }
+
+  return db
     .select({
       // NOTE: using `id` here to avoid clobbering `registryId` in consuming queries, which would
       // result in '_ is ambiguous' error messages from postgres because drizzle isn't scoping the
       // selection properly. a bit fragile but works for now.
       id: sql<string>`registry_id`.as("id"),
     })
     .from(
-      sql`(
-            WITH RECURSIVE canonical_registries AS (
-              SELECT ${getENSv2RootRegistryId(config.namespace)}::text AS registry_id, 0 AS depth
-              UNION ALL
-              SELECT rcd.registry_id, cr.depth + 1
-              FROM ${schema.registryCanonicalDomain} rcd
-              JOIN ${schema.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
-              WHERE cr.depth < ${CANONICAL_REGISTRIES_MAX_DEPTH}
-            )
-            SELECT registry_id FROM canonical_registries
-          ) AS canonical_registries_cte`,
+      sql`
+      (
+        WITH RECURSIVE canonical_registries AS (
+          SELECT ${ENSV2_ROOT_REGISTRY_ID}::text AS registry_id, 0 AS depth
+          UNION ALL
+          SELECT rcd.registry_id, cr.depth + 1
+          FROM ${schema.registryCanonicalDomain} rcd
+          JOIN ${schema.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
+          WHERE cr.depth < ${CANONICAL_REGISTRIES_MAX_DEPTH}
+        )
+        SELECT registry_id FROM canonical_registries
+      ) AS canonical_registries_cte`,
     )
     .as("canonical_registries");
+};

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

@@ -2,7 +2,7 @@ import { describe, expect, it } from "vitest";
 
 import type { DomainId } from "@ensnode/ensnode-sdk";
 
-import { DomainCursor } from "./domain-cursor";
+import { type DomainCursor, DomainCursors } from "./domain-cursor";
 
 describe("DomainCursor", () => {
   describe("roundtrip encode/decode", () => {
@@ -13,7 +13,7 @@ describe("DomainCursor", () => {
         dir: "ASC",
         value: "example",
       };
-      expect(DomainCursor.decode(DomainCursor.encode(cursor))).toEqual(cursor);
+      expect(DomainCursors.decode(DomainCursors.encode(cursor))).toEqual(cursor);
     });
 
     it("roundtrips with a bigint value (REGISTRATION_TIMESTAMP ordering)", () => {
@@ -23,7 +23,7 @@ describe("DomainCursor", () => {
         dir: "DESC",
         value: 1234567890n,
       };
-      expect(DomainCursor.decode(DomainCursor.encode(cursor))).toEqual(cursor);
+      expect(DomainCursors.decode(DomainCursors.encode(cursor))).toEqual(cursor);
     });
 
     it("roundtrips with a bigint value (REGISTRATION_EXPIRY ordering)", () => {
@@ -33,7 +33,7 @@ describe("DomainCursor", () => {
         dir: "ASC",
         value: 9999999999n,
       };
-      expect(DomainCursor.decode(DomainCursor.encode(cursor))).toEqual(cursor);
+      expect(DomainCursors.decode(DomainCursors.encode(cursor))).toEqual(cursor);
     });
 
     it("roundtrips with a null value", () => {
@@ -43,22 +43,22 @@ describe("DomainCursor", () => {
         dir: "ASC",
         value: null,
       };
-      expect(DomainCursor.decode(DomainCursor.encode(cursor))).toEqual(cursor);
+      expect(DomainCursors.decode(DomainCursors.encode(cursor))).toEqual(cursor);
     });
   });
 
   describe("decode error handling", () => {
     it("throws on garbage input", () => {
-      expect(() => DomainCursor.decode("not-valid-base64!!!")).toThrow("Invalid cursor");
+      expect(() => DomainCursors.decode("not-valid-base64!!!")).toThrow("Invalid cursor");
     });
 
     it("throws on valid base64 but invalid json", () => {
       const notJson = Buffer.from("not json", "utf8").toString("base64");
-      expect(() => DomainCursor.decode(notJson)).toThrow("Invalid cursor");
+      expect(() => DomainCursors.decode(notJson)).toThrow("Invalid cursor");
     });
 
     it("throws on empty string", () => {
-      expect(() => DomainCursor.decode("")).toThrow("Invalid cursor");
+      expect(() => DomainCursors.decode("")).toThrow("Invalid cursor");
     });
   });
 });