@ensnode/datasources 0.0.0-next-20260603155437 → 0.0.0-next-20260603190454

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 NameHash
+Copyright (c) 2026 NameHash Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { ChainId, NormalizedAddress } from 'enssdk';
 import * as viem from 'viem';
 import { Abi, Address, Chain } from 'viem';
 import * as viem_chains from 'viem/chains';
@@ -3580,6 +3581,137 @@ declare const ThreeDNSToken: readonly [{
     readonly type: "event";
 }];
 
+/**
+ * ENSNamespaceIds encodes the set of identifiers for well-known ENS namespaces.
+ *
+ * Each ENS namespace is a single, unified set of ENS names with a distinct onchain root
+ * Registry (the ensroot Datasource) and the capability of spanning from that root Registry across
+ * other `Datasource`s that may be distributed across multiple chains and offchain resources.
+ *
+ * For example, as of 9-Feb-2025 the canonical ENS namespace on mainnet includes:
+ * - A root Registry on mainnet.
+ * - An onchain Registrar for direct subnames of 'eth' on mainnet.
+ * - An onchain Registry and Registrar for direct subnames of 'base.eth' on Base.
+ * - An onchain Registry and Registrar subregistry for direct subnames of 'linea.eth' on Linea.
+ * - An offchain subregistry for subnames of '.cb.id'.
+ * - An offchain subregistry for subnames of '.uni.eth'.
+ * - Etc..
+ *
+ * Each ENS namespace is logically independent of & isolated from the others, and not exclusively
+ * correlated with a specific L1 chain. For example, the Sepolia testnet ENS namepace
+ * is independent of the canonical ENS namespace on mainnet, and there could be an additional
+ * deployment of the ENS protocol to mainnet, configured with different Datasources, resulting in a
+ * logically isolated set of ENS names.
+ *
+ * 'ens-test-env' represents an ENS namespace running on a local Anvil chain for testing
+ * protocol changes, running deterministic test suites, and local development.
+ * https://github.com/ensdomains/ens-test-env
+ */
+declare const ENSNamespaceIds: {
+    readonly Mainnet: "mainnet";
+    readonly Sepolia: "sepolia";
+    readonly SepoliaV2: "sepolia-v2";
+    readonly EnsTestEnv: "ens-test-env";
+};
+/**
+ * ENSNamespaceId is the derived string union of possible ENS namespace identifiers.
+ */
+type ENSNamespaceId = (typeof ENSNamespaceIds)[keyof typeof ENSNamespaceIds];
+/**
+ * A Datasource describes a set of contracts on a given chain that interact with the ENS protocol.
+ */
+interface Datasource {
+    chain: Chain;
+    contracts: Record<string, ContractConfig>;
+}
+/**
+ * DatasourceNames encodes a unique id for each known Datasource.
+ */
+declare const DatasourceNames: {
+    readonly ENSRoot: "ensroot";
+    readonly Basenames: "basenames";
+    readonly Lineanames: "lineanames";
+    readonly Seaport: "seaport";
+    readonly ThreeDNSOptimism: "threednsOptimism";
+    readonly ThreeDNSBase: "threednsBase";
+    readonly ReverseResolverRoot: "rrRoot";
+    readonly ReverseResolverBase: "rrBase";
+    readonly ReverseResolverLinea: "rrLinea";
+    readonly ReverseResolverOptimism: "rrOptimism";
+    readonly ReverseResolverArbitrum: "rrArbitrum";
+    readonly ReverseResolverScroll: "rrScroll";
+    readonly ENSv2Root: "ENSv2Root";
+};
+type DatasourceName = (typeof DatasourceNames)[keyof typeof DatasourceNames];
+/**
+ * EventFilter specifies a given event's name and arguments to filter that event by.
+ * This type is intentionally a subset of Ponder's `ContractConfig['filter']`.
+ */
+interface EventFilter {
+    event: string;
+    args: Record<string, unknown>;
+}
+/**
+ * Defines the abi, address, and startBlock of a contract relevant to a Datasource.
+ *
+ * A contract is located onchain either by
+ *  1. a single Address in `address`,
+ *  2. a set of Address[] in `address`,
+ *  3. or any contract that emits events as defined in `abi`.
+ *
+ * This type is intentionally a subset of Ponder's ContractConfig.
+ *
+ * @param abi - the ABI of the contract
+ * @param address - (optional) Address of the contract or Address[] of each contract to be indexed
+ * @param startBlock - block number the contract was deployed in
+ */
+type ContractConfig = {
+    readonly abi: Abi;
+    readonly address?: Address | Address[];
+    readonly startBlock: number;
+    readonly endBlock?: number;
+};
+/**
+ * ENSNamespace encodes a set of known Datasources associated with the same ENS namespace.
+ *
+ * The ENSRoot Datasource is required (this formally defines an ENS namespace). All other Datasources
+ * within the ENSNamespace are optional.
+ */
+type ENSNamespace = {
+    [DatasourceNames.ENSRoot]: Datasource;
+} & Partial<Record<Exclude<DatasourceName, "ensroot">, Datasource>>;
+/**
+ * Helper type to extract the datasource type for a specific datasource name across all namespaces.
+ * Returns the union of all possible datasource types for that datasource name, or never if not found.
+ */
+type ExtractDatasourceType<Namespaces extends ENSNamespace, D extends DatasourceName> = Namespaces extends any ? (D extends keyof Namespaces ? Namespaces[D] : never) : never;
+
+/** A query for {@link identifyDatasourceContracts}: an address, optionally scoped to one chain. */
+interface DatasourceIdentifyQuery {
+    /** When set, only consider Datasources deployed on this chain. */
+    chainId?: ChainId;
+    address: NormalizedAddress;
+}
+/** A well-known Datasource contract matched by {@link identifyDatasourceContracts}. */
+interface DatasourceContractMatch {
+    namespace: ENSNamespaceId;
+    datasource: DatasourceName;
+    contract: string;
+    chainId: ChainId;
+    address: NormalizedAddress;
+}
+/**
+ * Finds every well-known contract in `namespaceId`'s Datasources whose address equals
+ * `query.address`, optionally restricted to `query.chainId`.
+ *
+ * Contracts without a fixed address (matched onchain by event only) are skipped — they have no
+ * address to identify. A single address may match multiple contracts, so all matches are returned.
+ *
+ * @param namespaceId - The ENSNamespace identifier (e.g. 'mainnet', 'sepolia', 'ens-test-env')
+ * @param query - The address to identify, optionally scoped to a chain
+ */
+declare const identifyDatasourceContracts: (namespaceId: ENSNamespaceId, query: DatasourceIdentifyQuery) => DatasourceContractMatch[];
+
 declare const AnyRegistrarABI: readonly [{
     readonly anonymous: false;
     readonly inputs: readonly [{
@@ -8438,111 +8570,6 @@ declare const ResolverABI: readonly [{
     readonly type: "function";
 }];
 
-/**
- * ENSNamespaceIds encodes the set of identifiers for well-known ENS namespaces.
- *
- * Each ENS namespace is a single, unified set of ENS names with a distinct onchain root
- * Registry (the ensroot Datasource) and the capability of spanning from that root Registry across
- * other `Datasource`s that may be distributed across multiple chains and offchain resources.
- *
- * For example, as of 9-Feb-2025 the canonical ENS namespace on mainnet includes:
- * - A root Registry on mainnet.
- * - An onchain Registrar for direct subnames of 'eth' on mainnet.
- * - An onchain Registry and Registrar for direct subnames of 'base.eth' on Base.
- * - An onchain Registry and Registrar subregistry for direct subnames of 'linea.eth' on Linea.
- * - An offchain subregistry for subnames of '.cb.id'.
- * - An offchain subregistry for subnames of '.uni.eth'.
- * - Etc..
- *
- * Each ENS namespace is logically independent of & isolated from the others, and not exclusively
- * correlated with a specific L1 chain. For example, the Sepolia testnet ENS namepace
- * is independent of the canonical ENS namespace on mainnet, and there could be an additional
- * deployment of the ENS protocol to mainnet, configured with different Datasources, resulting in a
- * logically isolated set of ENS names.
- *
- * 'ens-test-env' represents an ENS namespace running on a local Anvil chain for testing
- * protocol changes, running deterministic test suites, and local development.
- * https://github.com/ensdomains/ens-test-env
- */
-declare const ENSNamespaceIds: {
-    readonly Mainnet: "mainnet";
-    readonly Sepolia: "sepolia";
-    readonly SepoliaV2: "sepolia-v2";
-    readonly EnsTestEnv: "ens-test-env";
-};
-/**
- * ENSNamespaceId is the derived string union of possible ENS namespace identifiers.
- */
-type ENSNamespaceId = (typeof ENSNamespaceIds)[keyof typeof ENSNamespaceIds];
-/**
- * A Datasource describes a set of contracts on a given chain that interact with the ENS protocol.
- */
-interface Datasource {
-    chain: Chain;
-    contracts: Record<string, ContractConfig>;
-}
-/**
- * DatasourceNames encodes a unique id for each known Datasource.
- */
-declare const DatasourceNames: {
-    readonly ENSRoot: "ensroot";
-    readonly Basenames: "basenames";
-    readonly Lineanames: "lineanames";
-    readonly Seaport: "seaport";
-    readonly ThreeDNSOptimism: "threednsOptimism";
-    readonly ThreeDNSBase: "threednsBase";
-    readonly ReverseResolverRoot: "rrRoot";
-    readonly ReverseResolverBase: "rrBase";
-    readonly ReverseResolverLinea: "rrLinea";
-    readonly ReverseResolverOptimism: "rrOptimism";
-    readonly ReverseResolverArbitrum: "rrArbitrum";
-    readonly ReverseResolverScroll: "rrScroll";
-    readonly ENSv2Root: "ENSv2Root";
-};
-type DatasourceName = (typeof DatasourceNames)[keyof typeof DatasourceNames];
-/**
- * EventFilter specifies a given event's name and arguments to filter that event by.
- * This type is intentionally a subset of Ponder's `ContractConfig['filter']`.
- */
-interface EventFilter {
-    event: string;
-    args: Record<string, unknown>;
-}
-/**
- * Defines the abi, address, and startBlock of a contract relevant to a Datasource.
- *
- * A contract is located onchain either by
- *  1. a single Address in `address`,
- *  2. a set of Address[] in `address`,
- *  3. or any contract that emits events as defined in `abi`.
- *
- * This type is intentionally a subset of Ponder's ContractConfig.
- *
- * @param abi - the ABI of the contract
- * @param address - (optional) Address of the contract or Address[] of each contract to be indexed
- * @param startBlock - block number the contract was deployed in
- */
-type ContractConfig = {
-    readonly abi: Abi;
-    readonly address?: Address | Address[];
-    readonly startBlock: number;
-    readonly endBlock?: number;
-};
-/**
- * ENSNamespace encodes a set of known Datasources associated with the same ENS namespace.
- *
- * The ENSRoot Datasource is required (this formally defines an ENS namespace). All other Datasources
- * within the ENSNamespace are optional.
- */
-type ENSNamespace = {
-    [DatasourceNames.ENSRoot]: Datasource;
-} & Partial<Record<Exclude<DatasourceName, "ensroot">, Datasource>>;
-/**
- * Helper type to extract the datasource type for a specific datasource name across all namespaces.
- * Returns the union of all possible datasource types for that datasource name, or never if not found.
- */
-type ExtractDatasourceType<Namespaces extends ENSNamespace, D extends DatasourceName> = Namespaces extends any ? (D extends keyof Namespaces ? Namespaces[D] : never) : never;
-
 /**
  * The ens-test-env ENSNamespace
  *
@@ -128287,4 +128314,4 @@ declare const getENSRootChain: (namespaceId: ENSNamespaceId) => {
  */
 declare const getENSRootChainId: (namespaceId: ENSNamespaceId) => 1 | 31337 | 11155111;
 
-export { AnyRegistrarABI, AnyRegistrarControllerABI, type ContractConfig, type Datasource, type DatasourceName, DatasourceNames, type ENSNamespace, type ENSNamespaceId, ENSNamespaceIds, ETHRegistrar as ETHRegistrarABI, EnhancedAccessControl as EnhancedAccessControlABI, type EventFilter, type ExtractDatasourceType, L2ReverseRegistrar as L2ReverseRegistrarABI, Registry as RegistryABI, ResolverABI, StandaloneReverseRegistrar as StandaloneReverseRegistrarABI, ThreeDNSToken as ThreeDNSTokenABI, UniversalResolverABI, ensTestEnvChain, getDatasource, getENSNamespace, getENSRootChain, getENSRootChainId, maybeGetDatasource };
+export { AnyRegistrarABI, AnyRegistrarControllerABI, type ContractConfig, type Datasource, type DatasourceContractMatch, type DatasourceIdentifyQuery, type DatasourceName, DatasourceNames, type ENSNamespace, type ENSNamespaceId, ENSNamespaceIds, ETHRegistrar as ETHRegistrarABI, EnhancedAccessControl as EnhancedAccessControlABI, type EventFilter, type ExtractDatasourceType, L2ReverseRegistrar as L2ReverseRegistrarABI, Registry as RegistryABI, ResolverABI, StandaloneReverseRegistrar as StandaloneReverseRegistrarABI, ThreeDNSToken as ThreeDNSTokenABI, UniversalResolverABI, ensTestEnvChain, getDatasource, getENSNamespace, getENSRootChain, getENSRootChainId, identifyDatasourceContracts, maybeGetDatasource };