@ensnode/ensdb-sdk 1.13.0 → 1.14.0

package/dist/{index-CVAtPcO6.d.ts → index-DdrIzPaZ.d.ts}

@@ -1,15 +1,16 @@
 import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
 import * as drizzle_orm from 'drizzle-orm';
 import * as ponder from 'ponder';
-import { DomainId, RegistryId, InterpretedLabel, PermissionsId, PermissionsResourceId, PermissionsUserId, RegistrationId, RenewalId, ResolverId, ResolverRecordsId, InterpretedName } from 'enssdk';
+import { DomainId, RegistryId, InterpretedName, LabelHashPath, InterpretedLabel, PermissionsId, PermissionsResourceId, PermissionsUserId, RegistrationId, RenewalId, ResolverId, ResolverRecordsId } from 'enssdk';
 
 /**
  * The ENSv2 Schema
  *
  * While the initial approach was a highly materialized view of the ENS protocol, abstracting away
  * as many on-chain details as possible, in practice—due to the sheer complexity of the protocol at
- * resolution-time—it becomes more or less impossible to appropriately materialize the canonical
- * namegraph.
+ * resolution-time—full materialization of resolution behavior is impractical. The canonical
+ * nametree, however, is materialized inline via synchronous handler-side cascades; see
+ * `Domain.canonical*` fields and `canonicality-db-helpers.ts`.
  *
  * As a result, this schema takes a balanced approach. It mimics on-chain state as closely as possible,
  * with the obvious exception of materializing specific state that must trivially filterable. Then,
@@ -24,7 +25,7 @@ import { DomainId, RegistryId, InterpretedLabel, PermissionsId, PermissionsResou
  * in ENSApi. The current obvious exception is that `domain.ownerId` for ENSv1 Domains is the
  * _materialized_ _effective_ owner. ENSv1 includes a diverse number of ways to 'own' a domain,
  * including the ENSv1 Registry, various Registrars, and the NameWrapper. The ENSv1 indexing logic
- * within this ENSv2 plugin materializes the effective owner to simplify this aspect of ENS and
+ * within this Unigraph plugin materializes the effective owner to simplify this aspect of ENS and
  * enable efficient queries against `domain.ownerId`.
  *
  * When necessary, all datamodels are shared or polymorphic between ENSv1 and ENSv2, including
@@ -34,10 +35,12 @@ import { DomainId, RegistryId, InterpretedLabel, PermissionsId, PermissionsResou
  * guarantees (for example, ENSv1 BaseRegistrar Registrations may have a gracePeriod, but ENSv2
  * Registry Registrations do not).
  *
- * Instead of materializing a Domain's name at any point, we maintain an internal rainbow table of
- * labelHash -> InterpretedLabel (the Label entity). This ensures that regardless of how or when a
- * new label is encountered onchain, all Domains that use that label are automatically healed at
- * resolution-time.
+ * The `Label` entity (labelHash → InterpretedLabel) remains the source of truth for label values.
+ * Canonical-tree fields on `Domain` (`canonicalName`, `canonicalLabelHashPath`, `canonicalPath`,
+ * `canonicalDepth`, `canonicalNode`) are materialized inline by the handlers in
+ * `canonicality-db-helpers.ts`. Label heals propagate to `canonicalName` via a GIN-indexed bulk
+ * UPDATE outside Ponder's cache; cascade round-trips are bounded to events that already pay a
+ * flush (canonicality flip, heal of an unknown label).
  *
  * ENSv1 and ENSv2 both fit the Registry → Domain → (Sub)Registry → Domain → ... namegraph model.
  * For ENSv1, each domain that has children implicitly owns a "virtual" Registry (a row of type
@@ -55,7 +58,7 @@ import { DomainId, RegistryId, InterpretedLabel, PermissionsId, PermissionsResou
  * for fresh ENSv1 virtual registries on first wire-up) or a single recursive-CTE batch UPDATE
  * otherwise (see `canonicality-db-helpers.ts`).
  *
- * Note also that the Protocol Acceleration plugin is a hard requirement for the ENSv2 plugin. This
+ * Note also that the Protocol Acceleration plugin is a hard requirement for the Unigraph plugin. This
  * allows us to rely on the shared logic for indexing:
  *   a) ENSv1RegistryOld -> ENSv1Registry migration status
  *   b) Domain-Resolver Relations for both ENSv1 and ENSv2 Domains
@@ -964,6 +967,152 @@ declare const domain: ponder.OnchainTable<{
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        canonicalName: ponder.PgColumn<{
+            name: "canonicalName";
+            tableName: "domains";
+            dataType: "string";
+            columnType: "PgText";
+            data: InterpretedName;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: InterpretedName;
+        }>;
+        canonicalLabelHashPath: ponder.PgColumn<{
+            name: "canonicalLabelHashPath";
+            tableName: "domains";
+            dataType: "array";
+            columnType: "PgArray";
+            data: LabelHashPath;
+            driverParam: string | string[];
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: drizzle_orm.Column<{
+                name: "";
+                tableName: "domains";
+                dataType: "string";
+                columnType: "PgHex";
+                data: `0x${string}`;
+                driverParam: string;
+                notNull: false;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            size: undefined;
+            baseBuilder: ponder.PgColumnBuilder<{
+                name: "";
+                dataType: "string";
+                columnType: "PgHex";
+                data: `0x${string}`;
+                driverParam: string;
+                enumValues: undefined;
+                generated: undefined;
+            }, {}, {
+                generated: undefined;
+            }, drizzle_orm.ColumnBuilderExtraConfig>;
+            $type: LabelHashPath;
+        }>;
+        canonicalPath: ponder.PgColumn<{
+            name: "canonicalPath";
+            tableName: "domains";
+            dataType: "array";
+            columnType: "PgArray";
+            data: DomainId[];
+            driverParam: string | string[];
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: drizzle_orm.Column<{
+                name: "";
+                tableName: "domains";
+                dataType: "string";
+                columnType: "PgText";
+                data: string;
+                driverParam: string;
+                notNull: false;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            size: undefined;
+            baseBuilder: ponder.PgColumnBuilder<{
+                name: "";
+                dataType: "string";
+                columnType: "PgText";
+                data: string;
+                enumValues: [string, ...string[]];
+                driverParam: string;
+            }, {}, {}, drizzle_orm.ColumnBuilderExtraConfig>;
+            $type: DomainId[];
+        }>;
+        canonicalDepth: ponder.PgColumn<{
+            name: "canonicalDepth";
+            tableName: "domains";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        canonicalNode: ponder.PgColumn<{
+            name: "canonicalNode";
+            tableName: "domains";
+            dataType: "string";
+            columnType: "PgHex";
+            data: `0x${string}`;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: `0x${string}`;
+        }>;
     };
     extra: {
         byType: drizzle_orm_pg_core.IndexBuilder;
@@ -971,6 +1120,11 @@ declare const domain: ponder.OnchainTable<{
         bySubregistry: drizzle_orm_pg_core.IndexBuilder;
         byOwner: drizzle_orm_pg_core.IndexBuilder;
         byLabelHash: drizzle_orm_pg_core.IndexBuilder;
+        byCanonicalNameExact: drizzle_orm_pg_core.IndexBuilder;
+        byCanonicalNameFuzzy: drizzle_orm_pg_core.IndexBuilder;
+        byCanonicalLabelHashPath: drizzle_orm_pg_core.IndexBuilder;
+        byCanonicalNode: drizzle_orm_pg_core.IndexBuilder;
+        byCanonicalDepth: drizzle_orm_pg_core.IndexBuilder;
     };
     dialect: "pg";
 }>;
@@ -1047,7 +1201,7 @@ declare const registration: ponder.OnchainTable<{
             tableName: "registrations";
             dataType: "string";
             columnType: "PgEnumColumn";
-            data: "BaseRegistrar" | "NameWrapper" | "ThreeDNS" | "ENSv2RegistryRegistration" | "ENSv2RegistryReservation";
+            data: "NameWrapper" | "BaseRegistrar" | "ThreeDNS" | "ENSv2RegistryRegistration" | "ENSv2RegistryReservation";
             driverParam: string;
             notNull: true;
             hasDefault: false;
@@ -1918,7 +2072,8 @@ declare const label: ponder.OnchainTable<{
         }>;
     };
     extra: {
-        byInterpreted: drizzle_orm_pg_core.IndexBuilder;
+        byInterpretedExact: drizzle_orm_pg_core.IndexBuilder;
+        byInterpretedFuzzy: drizzle_orm_pg_core.IndexBuilder;
     };
     dialect: "pg";
 }>;
@@ -1957,7 +2112,7 @@ declare const label_relations: drizzle_orm.Relations<"labels", {
  * pattern matcher recover the key from event args. See the helper module's block comment for the
  * full rationale.
  *
- * The ensv2 plugin depends on the Protocol Acceleration plugin in order to piggyback on this
+ * The Unigraph plugin depends on the Protocol Acceleration plugin in order to piggyback on this
  * Registry migration logic.
  */
 declare const migratedNodeByParent: ponder.OnchainTable<{

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { EnsDbPublicConfig, IndexingMetadataContext, IndexingMetadataContextInitialized, Unvalidated } from '@ensnode/ensnode-sdk';
 export { IndexingMetadataContext, IndexingMetadataContextInitialized, IndexingMetadataContextStatusCodes, IndexingMetadataContextUninitialized } from '@ensnode/ensnode-sdk';
 import { NodePgDatabase } from 'drizzle-orm/node-postgres';
-import { a as abstractEnsIndexerSchema } from './index-CVAtPcO6.js';
+import { a as abstractEnsIndexerSchema } from './index-DdrIzPaZ.js';
 import { e as ensNodeSchema } from './index-BHoa233Z.js';
 import 'drizzle-orm/pg-core';
 import 'drizzle-orm';

package/dist/index.js

@@ -264,7 +264,43 @@ var domain = onchainTable(
     // If this is an ENSv1Domain, may have a `rootRegistryOwner`, otherwise null.
     rootRegistryOwnerId: t.hex().$type(),
     // Whether this Domain is part of the canonical nametree. Mirrors the parent Registry's flag.
-    canonical: t.boolean().notNull().default(false)
+    canonical: t.boolean().notNull().default(false),
+    /**
+     * Materialized Canonical Name, NULL iff `canonical = false`.
+     * Maintained by `canonicality-db-helpers.ts`.
+     *
+     * @example "vitalik.eth"
+     */
+    canonicalName: t.text().$type(),
+    /**
+     * Materialized Canonical LabelHashPath, NULL iff `canonical = false`.
+     * Maintained by `canonicality-db-helpers.ts`.
+     *
+     * @dev Note that LabelHashPaths are in traversal-order (i.e. [labelhash("eth"), labelhash("vitalik")]).
+     */
+    canonicalLabelHashPath: t.hex().array().$type(),
+    /**
+     * Materialized Canonical Domain Path, NULL iff `canonical = false`.
+     * Maintained by `canonicality-db-helpers.ts`.
+     *
+     * @dev Note that canonicalPath is in traversal-order (i.e. ["eth"'s DomainId, "vitalik"'s DomainId]).
+     */
+    canonicalPath: t.text().array().$type(),
+    /**
+     * Materialized Canonical Depth, NULL iff `canonical = false`.
+     * Maintained by `canonicality-db-helpers.ts`.
+     *
+     * @dev The depth of this Domain in the Canonical Nametree i.e. the number of Labels in its Canonical Name.
+     * @example "eth" depth 1, "vitalik.eth" depth 2, etc
+     */
+    canonicalDepth: t.integer(),
+    /**
+     * Materialized Canonical Node, NULL iff `canonical = false`.
+     * Maintained by `canonicality-db-helpers.ts`.
+     *
+     * @dev the computed Node (via `namehash`) of this Domain's Canonical Name.
+     */
+    canonicalNode: t.hex().$type()
     // NOTE: Domain-Resolver Relations tracked via Protocol Acceleration plugin
   }),
   (t) => ({
@@ -272,7 +308,18 @@ var domain = onchainTable(
     byRegistry: index().on(t.registryId),
     bySubregistry: index().on(t.subregistryId).where(sql`${t.subregistryId} IS NOT NULL`),
     byOwner: index().on(t.ownerId),
-    byLabelHash: index().on(t.labelHash)
+    byLabelHash: index().on(t.labelHash),
+    // hash index avoids the btree 8191-byte row-size hazard for spam names
+    byCanonicalNameExact: index().using("hash", t.canonicalName),
+    // GIN trigram index for substring / similarity queries (inline `gin_trgm_ops` via `sql`
+    // because passing it through `.op()` gets dropped by Ponder)
+    byCanonicalNameFuzzy: index().using("gin", sql`${t.canonicalName} gin_trgm_ops`),
+    // GIN containment for `cascadeLabelHeal`'s `canonical_label_hash_path @> ARRAY[lh]` lookup
+    byCanonicalLabelHashPath: index().using("gin", t.canonicalLabelHashPath),
+    // hash index for resolver-record → canonical-domain joins
+    byCanonicalNode: index().using("hash", t.canonicalNode),
+    // btree for ORDER BY canonical_depth (typeahead and DEPTH-ordered browse)
+    byCanonicalDepth: index().on(t.canonicalDepth)
   })
 );
 var relations_domain = relations(domain, ({ one, many }) => ({
@@ -520,7 +567,12 @@ var label = onchainTable(
     interpreted: t.text().notNull().$type()
   }),
   (t) => ({
-    byInterpreted: index().on(t.interpreted)
+    // hash index avoids the btree 8191-byte row-size hazard for spam labels (a single label can
+    // exceed btree's leaf-size limit)
+    byInterpretedExact: index().using("hash", t.interpreted),
+    // GIN trigram index for substring / similarity queries (inline `gin_trgm_ops` via `sql`
+    // because passing it through `.op()` gets dropped by Ponder)
+    byInterpretedFuzzy: index().using("gin", sql`${t.interpreted} gin_trgm_ops`)
   })
 );
 var label_relations = relations(label, ({ many }) => ({