Refactor/enssdk refactor continued

.changeset/humble-mice-listen.md

@@ -0,0 +1,5 @@
+---
+"enskit": minor
+---
+
+Introduce the enskit/react submodule export for React components and (in the future) hooks.

AGENTS.md

@@ -39,10 +39,11 @@ Runnable commands for validating changes; lint and format with Biome.
 
 - Install dependencies: `pnpm install`
 - Run all tests: `pnpm test`
-- Run tests for a single package/app: `pnpm --filter <package-name> test` (e.g. `pnpm --filter ensapi test`)
+  - Run tests for a single project: `pnpm test --project <project>` (e.g. `pnpm test --project ensapi`)
+  - Run tests for a single file: `pnpm test <path>`
 - Lint and format: `pnpm lint` (fixes where applicable); CI lint: `pnpm lint:ci`
 - Type checking: `pnpm typecheck` (runs typecheck in all workspaces)
-  - Always prefer `pnpm -F <package-name> typecheck` over `tsc`
+  - Always use `pnpm -F <package-name> typecheck`, never call `tsc` or `tsgo` directly
 
 ## Testing
 
@@ -76,7 +77,7 @@ Fail fast and loudly on invalid inputs.
 ## Workflow
 
 - Add a changeset when your PR includes a logical change that should bump versions or be communicated in release notes: https://ensnode.io/docs/contributing/prs#changesets
-- Before declaring work complete, run validation in the affected packages:
-  1. `pnpm -F <affected-packages> typecheck`
+- Before declaring work complete, run validation in the affected project(s):
+  1. `pnpm -F <affected-project> typecheck`
   2. `pnpm lint`
-  3. `pnpm -F <affected-packages> test`
+  3. `pnpm test --project <affected-project> [--project <other-affected-project>]`

apps/ensadmin/src/app/mock/display-identity/page.tsx

@@ -6,7 +6,7 @@ import {
   getEnsManagerAddressDetailsUrl,
 } from "@namehash/namehash-ui";
 import type { Address, ChainId, DefaultableChainId, Name } from "enssdk";
-import { asLowerCaseAddress, DEFAULT_EVM_CHAIN_ID } from "enssdk";
+import { DEFAULT_EVM_CHAIN_ID, toNormalizedAddress } from "enssdk";
 import { useState } from "react";
 import { isAddress } from "viem";
 
@@ -76,7 +76,7 @@ export default function MockDisplayIdentityPage() {
   }
 
   // at a data-model level, we always represent addresses fully in lowercase.
-  selectedAddress = asLowerCaseAddress(selectedAddress);
+  selectedAddress = toNormalizedAddress(selectedAddress);
 
   // fallback to selecting the default name if
   // selectedRawName is an empty string

apps/ensadmin/src/app/mock/registrar-actions/mocks.ts

@@ -1,6 +1,7 @@
+import type { Duration } from "enssdk";
 import { asInterpretedName } from "enssdk";
 
-import { type Duration, type NamedRegistrarAction } from "@ensnode/ensnode-sdk";
+import { type NamedRegistrarAction } from "@ensnode/ensnode-sdk";
 
 export const registrationWithReferral = {
   action: {

apps/ensadmin/src/components/indexing-status/backfill-status.tsx

@@ -4,6 +4,7 @@
  */
 
 import { AbsoluteTime } from "@namehash/namehash-ui";
+import type { UnixTimestamp } from "enssdk";
 import { Clock } from "lucide-react";
 
 import {
@@ -12,7 +13,6 @@ import {
   getTimestampForLowestOmnichainStartBlock,
   type RealtimeIndexingStatusProjection,
   sortChainStatusesByStartBlockAsc,
-  type UnixTimestamp,
 } from "@ensnode/ensnode-sdk";
 
 import {

apps/ensadmin/src/components/indexing-status/projection-info.tsx

@@ -1,11 +1,9 @@
 "use client";
 
 import { formatRelativeTime, RelativeTime, useNow } from "@namehash/namehash-ui";
-import type { UnixTimestamp } from "enssdk";
+import type { Duration, UnixTimestamp } from "enssdk";
 import { InfoIcon } from "lucide-react";
 
-import type { Duration } from "@ensnode/ensnode-sdk";
-
 import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
 
 /**

apps/ensadmin/src/components/indexing-status/use-indexing-status-with-swr.ts

@@ -2,6 +2,7 @@
 
 import { useNow } from "@namehash/namehash-ui";
 import { secondsToMilliseconds } from "date-fns";
+import type { Duration } from "enssdk";
 import { useCallback, useMemo } from "react";
 
 import {
@@ -15,7 +16,6 @@ import {
 import {
   CrossChainIndexingStatusSnapshotOmnichain,
   createRealtimeIndexingStatusProjection,
-  Duration,
   type IndexingStatusRequest,
   IndexingStatusResponseCodes,
   IndexingStatusResponseOk,

apps/ensapi/package.json

@@ -67,7 +67,6 @@
     "@ensnode/shared-configs": "workspace:*",
     "@types/node": "catalog:",
     "@types/prismjs": "^1.26.6",
-    "@urql/introspection": "^1.2.1",
     "chalk": "^5.6.2",
     "graphql-request": "^7.4.0",
     "pino-pretty": "^13.1.2",

apps/ensapi/src/handlers/api/explore/name-tokens-api.ts

@@ -2,8 +2,7 @@ import config from "@/config";
 
 import {
   asInterpretedName,
-  ENS_ROOT,
-  getParentNameFQDN,
+  getParentInterpretedName,
   type Node,
   namehashInterpretedName,
 } from "enssdk";
@@ -70,9 +69,10 @@ app.openapi(getNameTokensRoute, async (c) => {
 
   if (request.name !== undefined) {
     const name = asInterpretedName(request.name);
+    const parentName = getParentInterpretedName(name);
 
-    // return 404 when the requested name was the ENS Root
-    if (name === ENS_ROOT) {
+    // return 404 when the requested name was the ENS Root (which does not have a parent)
+    if (parentName === null) {
       return c.json(
         serializeNameTokensResponse(
           makeNameTokensNotIndexedResponse(
@@ -83,7 +83,7 @@ app.openapi(getNameTokensRoute, async (c) => {
       );
     }
 
-    const parentNode = namehashInterpretedName(getParentNameFQDN(name));
+    const parentNode = namehashInterpretedName(parentName);
     const subregistry = indexedSubregistries.find((s) => s.node === parentNode);
 
     // Return 404 response with error code for Name Tokens Not Indexed when

apps/ensapi/src/handlers/api/explore/registrar-actions-api.routes.ts

@@ -6,8 +6,8 @@ import {
   RegistrarActionsOrders,
 } from "@ensnode/ensnode-sdk";
 import {
-  makeLowercaseAddressSchema,
   makeNodeSchema,
+  makeNormalizedAddressSchema,
   makePositiveIntegerSchema,
   makeUnixTimestampSchema,
 } from "@ensnode/ensnode-sdk/internal";
@@ -51,7 +51,7 @@ export const registrarActionsQuerySchema = z
       .describe("Filter to only include actions with referrals")
       .openapi({ default: false }),
 
-    decodedReferrer: makeLowercaseAddressSchema("decodedReferrer")
+    decodedReferrer: makeNormalizedAddressSchema("decodedReferrer")
       .optional()
       .describe("Filter by decoded referrer address"),
 

apps/ensapi/src/handlers/api/meta/realtime-api.routes.ts

@@ -1,7 +1,7 @@
 import { createRoute, z } from "@hono/zod-openapi";
 import { minutesToSeconds } from "date-fns";
+import type { Duration } from "enssdk";
 
-import type { Duration } from "@ensnode/ensnode-sdk";
 import { makeDurationSchema } from "@ensnode/ensnode-sdk/internal";
 
 import { params } from "@/lib/handlers/params.schema";

apps/ensapi/src/handlers/api/meta/realtime-api.test.ts

@@ -1,9 +1,9 @@
+import type { UnixTimestamp } from "enssdk";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import {
   type CrossChainIndexingStatusSnapshot,
   createRealtimeIndexingStatusProjection,
-  type UnixTimestamp,
 } from "@ensnode/ensnode-sdk";
 
 import { createApp } from "@/lib/hono-factory";

apps/ensapi/src/handlers/api/resolution/resolution-api.ts

@@ -1,5 +1,6 @@
+import type { Duration } from "enssdk";
+
 import type {
-  Duration,
   ResolvePrimaryNameResponse,
   ResolvePrimaryNamesResponse,
   ResolveRecordsResponse,

apps/ensapi/src/handlers/ensanalytics/ensanalytics-api-v1.routes.ts

@@ -8,7 +8,7 @@ import {
   makeReferrerMetricsEditionsArraySchema,
 } from "@namehash/ens-referrals/v1/internal";
 
-import { makeLowercaseAddressSchema } from "@ensnode/ensnode-sdk/internal";
+import { makeNormalizedAddressSchema } from "@ensnode/ensnode-sdk/internal";
 
 export const basePath = "/v1/ensanalytics";
 
@@ -39,7 +39,7 @@ const referrerLeaderboardPageQuerySchema = z.object({
 
 // Referrer address parameter schema
 const referrerAddressSchema = z.object({
-  referrer: makeLowercaseAddressSchema("Referrer address").describe("Referrer Ethereum address"),
+  referrer: makeNormalizedAddressSchema("Referrer address").describe("Referrer Ethereum address"),
 });
 
 // Editions query parameter schema

apps/ensapi/src/handlers/ensanalytics/ensanalytics-api.routes.ts

@@ -1,7 +1,7 @@
 import { createRoute, z } from "@hono/zod-openapi";
 import { REFERRERS_PER_LEADERBOARD_PAGE_MAX } from "@namehash/ens-referrals";
 
-import { makeLowercaseAddressSchema } from "@ensnode/ensnode-sdk/internal";
+import { makeNormalizedAddressSchema } from "@ensnode/ensnode-sdk/internal";
 
 export const basePath = "/ensanalytics";
 
@@ -28,7 +28,7 @@ const paginationQuerySchema = z.object({
 
 // Referrer address parameter schema
 const referrerAddressSchema = z.object({
-  referrer: makeLowercaseAddressSchema("Referrer address").describe("Referrer Ethereum address"),
+  referrer: makeNormalizedAddressSchema("Referrer address").describe("Referrer Ethereum address"),
 });
 
 export const getReferrerLeaderboardRoute = createRoute({

apps/ensapi/src/handlers/subgraph/subgraph-api.ts

@@ -1,13 +1,14 @@
 import config from "@/config";
 
+import type { Duration } from "enssdk";
 import { createDocumentationMiddleware } from "ponder-enrich-gql-docs-middleware";
 
 // FIXME: use the import from:
 // import { ensIndexerSchema } from "@/lib/ensdb/singleton";
 // Once the lazy proxy implemented for `ensIndexerSchema` export is improved
 // to support Drizzle ORM in `ponder-subgraph` package.
 import * as ensIndexerSchema from "@ensnode/ensdb-sdk/ensindexer-abstract";
-import { type Duration, hasSubgraphApiConfigSupport } from "@ensnode/ensnode-sdk";
+import { hasSubgraphApiConfigSupport } from "@ensnode/ensnode-sdk";
 import { subgraphGraphQLMiddleware } from "@ensnode/ponder-subgraph";
 
 import { createApp } from "@/lib/hono-factory";

apps/ensapi/src/lib/ensanalytics/referrer-leaderboard/closeout.ts

@@ -1,8 +1,8 @@
 import type { ReferralProgramRules } from "@namehash/ens-referrals/v1";
 import { minutesToSeconds } from "date-fns";
-import type { UnixTimestamp } from "enssdk";
+import type { Duration, UnixTimestamp } from "enssdk";
 
-import { addDuration, type Duration } from "@ensnode/ensnode-sdk";
+import { addDuration } from "@ensnode/ensnode-sdk";
 
 /**
  * Duration after which we assume a closed edition is safe from chain reorganizations.

apps/ensapi/src/lib/ensanalytics/referrer-leaderboard/database-v1.ts

@@ -5,7 +5,7 @@ import {
   type ReferrerMetrics,
 } from "@namehash/ens-referrals/v1";
 import { and, asc, count, desc, eq, gte, isNotNull, lte, ne, sql, sum } from "drizzle-orm";
-import { type Address, stringifyAccountId } from "enssdk";
+import { type NormalizedAddress, stringifyAccountId } from "enssdk";
 import { zeroAddress } from "viem";
 
 import { deserializeDuration, priceEth } from "@ensnode/ensnode-sdk";
@@ -77,7 +77,7 @@ export const getReferrerMetrics = async (
     // 2. `totalIncrementalDuration` is guaranteed to be non-null as it is the sum of non-null bigint values
     // 3. `totalRevenueContribution` is guaranteed to be non-null due to COALESCE with 0
     interface NonNullRecord {
-      referrer: Address;
+      referrer: NormalizedAddress;
       totalReferrals: number;
       totalIncrementalDuration: string;
       totalRevenueContribution: string;
@@ -144,7 +144,7 @@ export const getReferralEvents = async (rules: ReferralProgramRules): Promise<Re
     // 3. `total` is guaranteed non-null by COALESCE with 0
     interface NonNullRecord {
       id: string;
-      referrer: Address;
+      referrer: NormalizedAddress;
       timestamp: bigint;
       incrementalDuration: bigint;
       total: string;

apps/ensapi/src/lib/ensanalytics/referrer-leaderboard/database.ts

@@ -4,7 +4,7 @@ import {
   type ReferrerMetrics,
 } from "@namehash/ens-referrals";
 import { and, count, desc, eq, gte, isNotNull, lte, ne, sql, sum } from "drizzle-orm";
-import { type Address, stringifyAccountId } from "enssdk";
+import { type NormalizedAddress, stringifyAccountId } from "enssdk";
 import { zeroAddress } from "viem";
 
 import { deserializeDuration } from "@ensnode/ensnode-sdk";
@@ -76,7 +76,7 @@ export const getReferrerMetrics = async (
     // 2. `totalIncrementalDuration` is guaranteed to be non-null as it is the sum of non-null bigint values
     // 3. `totalRevenueContribution` is guaranteed to be non-null due to COALESCE with 0
     interface NonNullRecord {
-      referrer: Address;
+      referrer: NormalizedAddress;
       totalReferrals: number;
       totalIncrementalDuration: string;
       totalRevenueContribution: string;

apps/ensapi/src/lib/handlers/params.schema.ts

@@ -5,7 +5,7 @@ import { isSelectionEmpty, type ResolverRecordsSelection } from "@ensnode/ensnod
 import {
   makeCoinTypeStringSchema,
   makeDefaultableChainIdStringSchema,
-  makeLowercaseAddressSchema,
+  makeNormalizedAddressSchema,
 } from "@ensnode/ensnode-sdk/internal";
 
 const excludingDefaultChainId = z
@@ -36,7 +36,7 @@ const name = z
 
 const trace = z.optional(boolstring).default(false).openapi({ default: false });
 const accelerate = z.optional(boolstring).default(false).openapi({ default: false });
-const address = makeLowercaseAddressSchema();
+const address = makeNormalizedAddressSchema();
 const defaultableChainId = makeDefaultableChainIdStringSchema();
 const coinType = makeCoinTypeStringSchema();
 

apps/ensapi/src/lib/name-tokens/find-name-tokens-for-domain.ts

@@ -1,7 +1,7 @@
 import config from "@/config";
 
 import { eq } from "drizzle-orm/sql";
-import { type AccountId, asInterpretedName, type Node } from "enssdk";
+import { type AccountId, asInterpretedName, type Node, type UnixTimestamp } from "enssdk";
 
 import {
   bigIntToNumber,
@@ -11,7 +11,6 @@ import {
   type NFTMintStatus,
   parseAssetId,
   type RegisteredNameTokens,
-  type UnixTimestamp,
 } from "@ensnode/ensnode-sdk";
 
 import { ensDb, ensIndexerSchema } from "@/lib/ensdb/singleton";

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

@@ -8,9 +8,7 @@ import {
   asInterpretedName,
   type DomainId,
   getNameHierarchy,
-  type Name,
-  type Node,
-  type NormalizedName,
+  type InterpretedName,
   namehashInterpretedName,
 } from "enssdk";
 import { isAddressEqual, type PublicClient, toHex, zeroAddress } from "viem";
@@ -29,7 +27,7 @@ type FindResolverResult =
       activeResolver: null;
       requiresWildcardSupport: undefined;
     }
-  | { activeName: Name; requiresWildcardSupport: boolean; activeResolver: Address };
+  | { activeName: InterpretedName; requiresWildcardSupport: boolean; activeResolver: Address };
 
 const NULL_RESULT: FindResolverResult = {
   activeName: null,
@@ -62,7 +60,7 @@ export async function findResolver({
   publicClient,
 }: {
   registry: AccountId;
-  name: NormalizedName;
+  name: InterpretedName;
   accelerate: boolean;
   canAccelerate: boolean;
   publicClient: PublicClient;
@@ -94,7 +92,7 @@ export async function findResolver({
  */
 async function findResolverWithUniversalResolver(
   publicClient: PublicClient,
-  name: Name,
+  name: InterpretedName,
 ): Promise<FindResolverResult> {
   return withActiveSpanAsync(
     tracer,
@@ -147,7 +145,8 @@ async function findResolverWithUniversalResolver(
       }
 
       // UniversalResolver returns the offset in bytes within the DNS Encoded Name where the activeName begins
-      const activeName: Name = bytesToPacket(dnsEncodedNameBytes.slice(offset));
+      // Invariant: the decoded name is a LiteralName that must conform to InterpretedName
+      const activeName = asInterpretedName(bytesToPacket(dnsEncodedNameBytes.slice(offset)));
 
       return {
         activeName,
@@ -175,7 +174,7 @@ async function findResolverWithUniversalResolver(
  */
 async function findResolverWithIndex(
   registry: AccountId,
-  name: NormalizedName,
+  name: InterpretedName,
 ): Promise<FindResolverResult> {
   return withActiveSpanAsync(
     tracer,
@@ -194,7 +193,7 @@ async function findResolverWithIndex(
 
       // 2. compute domainId of each node
       // NOTE: this is currently ENSv1-specific
-      const nodes = names.map((name) => namehashInterpretedName(asInterpretedName(name)) as Node);
+      const nodes = names.map((name) => namehashInterpretedName(name));
       const domainIds = nodes as DomainId[];
 
       // 3. for each domain, find its associated resolver in the selected registry