Refactor ENSv2 Plugin

apps/api/.gitignore

@@ -0,0 +1,2 @@
+# deps
+node_modules/

apps/api/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 NameHash
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

apps/api/README.md

@@ -0,0 +1,13 @@
+# ENSNode API
+
+API Server for ENSNode
+
+## Documentation
+
+For detailed documentation and guides, see the [ENSNode Documentation](https://ensnode.io/ensnode).
+
+## License
+
+Licensed under the MIT License, Copyright © 2025-present [NameHash Labs](https://namehashlabs.org).
+
+See [LICENSE](./LICENSE) for more information.

apps/api/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@ensnode/api",
+  "type": "module",
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "dev": "bun run --hot src/index.ts"
+  },
+  "dependencies": {
+    "@ensdomains/ensjs": "^4.0.2",
+    "@ensnode/ponder-schema": "workspace:*",
+    "@ensnode/utils": "workspace:*",
+    "@ponder/client": "catalog:",
+    "@ponder/utils": "catalog:",
+    "bun": "^1.2.2",
+    "drizzle-orm": "catalog:",
+    "hono": "catalog:",
+    "viem": "catalog:"
+  },
+  "devDependencies": {
+    "@ensnode/shared-configs": "workspace:*",
+    "@types/bun": "latest"
+  }
+}

apps/api/src/index.ts

@@ -0,0 +1,21 @@
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+import { proxy } from "hono/proxy";
+
+import v1 from "./v1";
+
+const app = new Hono();
+
+// use cors
+app.use(cors({ origin: "*" }));
+
+// TODO: ENSNode-api should be the exclusive api entrypoint for ENSNode
+// https://hono.dev/examples/proxy
+// - proxy /ponder, /subgraph, /sql/* endpoints to ensindexer
+
+app.route("/api/v1", v1);
+
+export default {
+  port: 3289,
+  fetch: app.fetch,
+};

apps/api/src/lib/db.ts

@@ -0,0 +1,20 @@
+import * as _schema from "@ensnode/ponder-schema";
+import { Table, is } from "drizzle-orm";
+// import { setDatabaseSchema } from "@ponder/client";
+import { drizzle } from "drizzle-orm/node-postgres";
+
+const setDatabaseSchema = <T extends { [name: string]: unknown }>(
+  schema: T,
+  schemaName: string,
+): T => {
+  for (const table of Object.values(schema)) {
+    if (is(table, Table)) {
+      // Use type assertion to fix the TypeScript error
+      (table as any)[Symbol.for("drizzle:Schema")] = schemaName;
+    }
+  }
+  return schema;
+};
+
+export const schema = setDatabaseSchema(_schema, Bun.env.DATABASE_SCHEMA || "public");
+export const db = drizzle(Bun.env.DATABASE_URL, { schema, casing: "snake_case", logger: true });

apps/api/src/lib/get-domain.ts

@@ -0,0 +1,103 @@
+import { sql } from "drizzle-orm";
+
+import { CAIP10AccountId, LabelHash } from "@ensnode/utils/types";
+import { HTTPException } from "hono/http-exception";
+import { hexToBigInt } from "viem";
+import { db, schema } from "./db";
+import { parseName } from "./parse-name";
+
+// TODO: configure this correctly, likely constructing the root registry id from the relevant ens deployment
+const ROOT_REGISTRY = "eip155:11155111:0xc44D7201065190B290Aaaf6efaDFD49d530547A3";
+
+// TODO: de-duplicate these helpers with @ensnode/utils
+const LABEL_HASH_MASK = 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffff00000000n;
+const maskTokenId = (tokenId: bigint) => tokenId & LABEL_HASH_MASK;
+const labelHashToTokenId = (labelHash: LabelHash) => hexToBigInt(labelHash, { size: 32 });
+
+/**
+ * gets a Domain from the tree if it exists using recursive CTE, traversing from RootRegistry
+ */
+export async function getDomainAndPath(name: string) {
+  const tokenIds = parseName(name) // given a set of labelhashes
+    .toReversed() // reverse for path
+    .map((labelHash) => maskTokenId(labelHashToTokenId(labelHash))); // convert to masked bigint tokenId
+
+  if (tokenIds.length === 0) {
+    throw new Error(`getDomainAndPath: name "${name}" did not contain any segments?`);
+  }
+
+  console.log({
+    name,
+    tokenIdsReversed: tokenIds,
+  });
+
+  // https://github.com/drizzle-team/drizzle-orm/issues/1289
+  // https://github.com/drizzle-team/drizzle-orm/issues/1589
+  const rawTokenIdsArray = sql.raw(`ARRAY[${tokenIds.join(", ")}]::numeric[]`);
+
+  const result = await db.execute(sql`
+    WITH RECURSIVE path_traversal AS (
+      -- Base case: Start with RootRegistry
+      SELECT
+        r.id AS "registry_id",
+        NULL::text AS "domain_id",
+        NULL::numeric(78,0) AS "masked_token_id",
+        NULL::numeric(78,0) AS "token_id",
+        NULL::text AS "label",
+        0 AS depth
+        -- ARRAY[]::numeric[] AS traversed_path
+      FROM
+        ${schema.v2_registry} r
+      WHERE
+        r.id = ${ROOT_REGISTRY}
+
+      UNION ALL
+
+      -- Recursive case: Find matching domain
+      SELECT
+        d."subregistry_id" AS "registry_id",
+        d.id AS "domain_id",
+        d."masked_token_id",
+        d."token_id",
+        d.label,
+        pt.depth + 1 AS depth
+        -- pt.traversed_path || d."masked_token_id":  :numeric AS traversed_path
+      FROM
+        path_traversal pt
+      JOIN
+        ${schema.v2_domain} d ON d."registry_id" = pt."registry_id"
+      WHERE
+        d."masked_token_id" = (${rawTokenIdsArray})[pt.depth + 1]
+        AND pt.depth < array_length(${rawTokenIdsArray}, 1)
+    )
+
+    SELECT * FROM path_traversal
+    WHERE domain_id IS NOT NULL -- only return domains, not root registry
+    ORDER BY depth
+  `);
+
+  // TODO: idk type this correctly
+  const rows = result.rows as {
+    registry_id: CAIP10AccountId;
+    domain_id: string;
+    masked_token_id: string;
+    token_id: string;
+    label: string;
+    depth: number;
+  }[];
+
+  // the domain in question was found iff the path has exactly the correct number of nodes
+  const exists = rows.length > 0 && rows.length === tokenIds.length;
+  if (!exists) throw new HTTPException(404, { message: "Domain not found." });
+
+  const lastRow = rows[rows.length - 1]!; // NOTE: must exist given length check above
+  if (lastRow.domain_id === null) throw new Error(`Expected domain_id`);
+
+  // the last element is the node and it exists in the tree
+  return {
+    path: rows,
+    domain: await db.query.v2_domain.findFirst({
+      where: (t, { eq }) => eq(t.id, lastRow.domain_id),
+    }),
+  };
+}

apps/api/src/lib/get-records.ts

@@ -0,0 +1,10 @@
+import { Node } from "@ensnode/utils/types";
+import { db } from "./db";
+
+export async function getResolverRecords(resolverId: string, node: Node) {
+  return await db.query.v2_resolverRecords.findFirst({
+    // TODO: put id generation into @ensnode/utils and re-use it here for faster lookups
+    where: (t, { eq, and }) => and(eq(t.resolverId, resolverId), eq(t.node, node)),
+    with: { addresses: true },
+  });
+}

apps/api/src/lib/parse-name.ts

@@ -0,0 +1,32 @@
+import { LabelHash } from "@ensnode/utils/types";
+import { Hex, isHex } from "viem";
+import { labelhash } from "viem/ens";
+
+// https://github.com/wevm/viem/blob/main/src/utils/ens/encodedLabelToLabelhash.ts
+export function encodedLabelToLabelhash(label: string): Hex | null {
+  if (label.length !== 66) return null;
+  if (label.indexOf("[") !== 0) return null;
+  if (label.indexOf("]") !== 65) return null;
+  const hash = `0x${label.slice(1, 65)}`;
+  if (!isHex(hash)) return null;
+  return hash;
+}
+
+/**
+ * parses a name into labelHash segments. name may contain encoded labelHashes
+ */
+export function parseName(name: string): LabelHash[] {
+  return name.split(".").map((segment) => {
+    const labelHash = segment.startsWith("[")
+      ? encodedLabelToLabelhash(segment)
+      : labelhash(segment);
+
+    if (!labelHash) {
+      throw new Error(
+        `parseName: name "${name}" segment "${segment}" is not a valid encoded labelHash`,
+      );
+    }
+
+    return labelHash;
+  });
+}

apps/api/src/v1.ts

@@ -0,0 +1,56 @@
+import { encodeLabelhash } from "@ensdomains/ensjs/utils";
+import { uint256ToHex32 } from "@ensnode/utils/subname-helpers";
+import { replaceBigInts } from "@ponder/utils";
+import { Hono } from "hono";
+import { namehash } from "viem";
+
+import { getDomainAndPath } from "./lib/get-domain.js";
+
+const app = new Hono();
+
+/**
+ * Finds a Domain by its `name` in the nametree.
+ */
+app.get("/domain/:name", async (c) => {
+  const nameParam = c.req.param("name");
+
+  // fetches a domain by name and the concrete path in the nametree
+  const { domain, path } = await getDomainAndPath(nameParam);
+
+  // identify any unknown labels in the name
+  const unknownSegments = path.filter((segment) => segment.label === undefined);
+
+  // TODO: attempt heal with ENSRainbow batch
+  const knownOrEncodedSegments = (await Promise.all(unknownSegments)).reduce<
+    Record<string, string>
+  >((memo, segment) => {
+    memo[segment.token_id] === encodeLabelhash(uint256ToHex32(BigInt(segment.token_id)));
+    return memo;
+  }, {});
+
+  // construct the domain's name to the best of our abilities
+  const name = path
+    // reverse to name-order
+    .toReversed()
+    // return known label or ens rainbow result
+    .map((segment) => segment.label ?? knownOrEncodedSegments[segment.token_id])
+    // join into name
+    .join(".");
+
+  const node = namehash(name);
+
+  // TODO: type this when we're more confident in what we want
+  const result = {
+    domain: {
+      ...domain,
+      // add constructed name and node to domain response
+      name,
+      node,
+    },
+    path,
+  };
+
+  return c.json(replaceBigInts(result, (v) => String(v)));
+});
+
+export default app;

apps/api/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "@ensnode/shared-configs/tsconfig.ponder.json",
+  "include": ["./**/*.ts"],
+  "exclude": ["node_modules"],
+  "compilerOptions": {
+    "strict": true,
+    "jsx": "react-jsx",
+    "jsxImportSource": "hono/jsx"
+  }
+}

apps/ensindexer/package.json

@@ -25,11 +25,12 @@
   "dependencies": {
     "@ensdomains/ensjs": "^4.0.2",
     "@ensnode/ens-deployments": "workspace:*",
-    "@ensnode/utils": "workspace:*",
     "@ensnode/ensrainbow-sdk": "workspace:*",
     "@ensnode/ponder-metadata": "workspace:*",
     "@ensnode/ponder-schema": "workspace:*",
     "@ensnode/ponder-subgraph": "workspace:*",
+    "@ensnode/utils": "workspace:*",
+    "caip": "^1.1.1",
     "hono": "catalog:",
     "ponder": "catalog:",
     "ts-deepmerge": "^7.0.2",

apps/ensindexer/ponder.config.ts

@@ -9,7 +9,7 @@ import * as ethPlugin from "./src/plugins/eth/ponder.plugin";
 import * as lineaEthPlugin from "./src/plugins/linea/ponder.plugin";
 
 ////////
-// First, generate AllPluginConfigs type representing the merged types of each plugin's `config`,
+// Generate AllPluginConfigs type representing the merged types of each plugin's `config`,
 // so ponder's typechecking of the indexing handlers and their event arguments is correct.
 ////////
 
@@ -18,31 +18,33 @@ const ALL_PLUGINS = [ethPlugin, baseEthPlugin, lineaEthPlugin, ensV2Plugin] as c
 type AllPluginConfigs = MergedTypes<(typeof ALL_PLUGINS)[number]["config"]>;
 
 ////////
-// Next, filter ALL_PLUGINS by those that are available and that the user has activated.
+// Filter ALL_PLUGINS by those that are 'available' (i.e. defined by the SELECTED_DEPLOYMENT_CONFIG)
 ////////
 
-// the available PluginNames are those that the selected ENS Deployment defines as available
 const availablePluginNames = Object.keys(SELECTED_DEPLOYMENT_CONFIG) as PluginName[];
 
-// filter the set of available plugins by those that are 'active' in the env
+////////
+// Filter ALL_PLUGINS by those that are 'active' in the env (i.e. via ACTIVE_PLUGINS)
+////////
+
 const activePlugins = getActivePlugins(ALL_PLUGINS, availablePluginNames);
 
 ////////
-// Next, merge the plugins' configs into a single ponder config and activate their handlers.
+// Merge the plugins' configs into a single ponder config.
 ////////
 
-// merge the resulting configs
 const activePluginsMergedConfig = activePlugins
   .map((plugin) => plugin.config)
   .reduce((acc, val) => deepMergeRecursive(acc, val), {}) as AllPluginConfigs;
 
-// load indexing handlers from the active plugins into the runtime
+////////
+// 'activate' each plugin, registering its indexing handlers with ponder
+////////
+
 activePlugins.forEach((plugin) => plugin.activate());
 
 ////////
-// Finally, return the merged config for ponder to use for type inference and runtime behavior.
+// Finally, return the merged config (typed as AllPluginConfigs) for ponder.
 ////////
 
-// The type of the default export is a merge of all active plugin configs
-// configs so that each plugin can be correctly typechecked
 export default activePluginsMergedConfig;