Feat/tokenscope

.changeset/six-pillows-pump.md

@@ -0,0 +1,7 @@
+---
+"@ensnode/ensnode-schema": minor
+"@ensnode/datasources": minor
+"ensindexer": minor
+---
+
+Initial launch of ENS TokenScope with support for indexing Seaport sales.

.github/workflows/test_ci.yml

@@ -59,7 +59,7 @@ jobs:
           # We use private RPC URLs from GitHub Secrets to avoid rate limits.
           # Public RPC URLs are used as fallbacks for repository forks
           # that don't have the relevant secrets configured.
-          PLUGINS: subgraph,basenames,lineanames,threedns,reverse-resolvers,referrals
+          PLUGINS: subgraph,basenames,lineanames,threedns,reverse-resolvers,referrals,tokenscope
           RPC_URL_1: ${{ secrets.MAINNET_RPC_URL || 'https://eth.drpc.org' }}
           RPC_URL_10: ${{ secrets.OPTIMISM_RPC_URL || 'https://optimism.drpc.org' }}
           RPC_URL_8453: ${{ secrets.BASE_RPC_URL || 'https://base.drpc.org' }}

apps/ensadmin/src/lib/chains.ts

@@ -1,4 +1,4 @@
-import { Datasource, type ENSNamespaceId, getENSNamespace } from "@ensnode/datasources";
+import { type Datasource, type ENSNamespaceId, getENSNamespace } from "@ensnode/datasources";
 import { type Chain } from "viem";
 import { anvil } from "viem/chains";
 

apps/ensindexer/.env.local.example

@@ -40,6 +40,7 @@ PORT=42069
 # === ENS Namespace: Mainnet ===
 # Ethereum Mainnet
 # - required if the configured namespace is mainnet
+# - required by plugins: subgraph, reverse-resolvers, referrals, tokenscope
 RPC_URL_1=
 RPC_REQUEST_RATE_LIMIT_1=500
 
@@ -71,6 +72,7 @@ RPC_REQUEST_RATE_LIMIT_534352=500
 # === ENS Namespace: Sepolia ===
 # Ethereum Sepolia (public testnet)
 # - required if the configured namespace is sepolia
+# - required by plugins: subgraph, reverse-resolvers, referrals, tokenscope
 RPC_URL_11155111=
 RPC_REQUEST_RATE_LIMIT_11155111=500
 
@@ -102,6 +104,7 @@ RPC_REQUEST_RATE_LIMIT_534351=500
 # === ENS Namespace: Holesky ===
 # Ethereum Holesky (public testnet)
 # - required if the configured namespace is holesky
+# - required by plugins: subgraph, reverse-resolvers, referrals
 RPC_URL_17000=
 RPC_REQUEST_RATE_LIMIT_17000=500
 
@@ -145,7 +148,7 @@ NAMESPACE=mainnet
 # - for subgraph-compatible indexing, the only valid configuration is `PLUGINS=subgraph`.
 # - for protocol acceleration of primary name lookups (reverse resolution), enable the
 # reverse-resolvers plugin.
-PLUGINS=subgraph,basenames,lineanames,threedns,reverse-resolvers,referrals
+PLUGINS=subgraph,basenames,lineanames,threedns,reverse-resolvers,referrals,tokenscope
 
 # ENSRainbow service URL
 # Required. This is the URL of the ENSRainbow server that ENSIndexer will use to heal

apps/ensindexer/package.json

@@ -43,6 +43,7 @@
     "@opentelemetry/sdk-trace-node": "^2.0.1",
     "@opentelemetry/semantic-conventions": "^1.34.0",
     "@types/dns-packet": "^5.6.5",
+    "caip": "^1.1.1",
     "date-fns": "catalog:",
     "deepmerge-ts": "^7.1.5",
     "dns-packet": "^5.6.1",

apps/ensindexer/src/lib/currencies.ts

@@ -0,0 +1,149 @@
+import {
+  base,
+  baseSepolia,
+  holesky,
+  linea,
+  lineaSepolia,
+  mainnet,
+  optimism,
+  sepolia,
+} from "viem/chains";
+
+import { AccountId, ChainId, accountIdEqual } from "@ensnode/ensnode-sdk";
+import { Address, zeroAddress } from "viem";
+
+/**
+ * Identifiers for supported currencies.
+ *
+ * TODO: Add support for WETH
+ */
+export const CurrencyIds = {
+  ETH: "ETH",
+  USDC: "USDC",
+  DAI: "DAI",
+} as const;
+
+export type CurrencyId = (typeof CurrencyIds)[keyof typeof CurrencyIds];
+
+export interface Price {
+  currency: CurrencyId;
+
+  /**
+   * The amount of the currency in the smallest unit of the currency. (see
+   * decimals of the CurrencyConfig for the currency).
+   *
+   * Guaranteed to be non-negative.
+   */
+  amount: bigint;
+}
+
+export interface CurrencyInfo {
+  id: CurrencyId;
+  name: string;
+  decimals: number;
+}
+
+const currencyInfo: Record<CurrencyId, CurrencyInfo> = {
+  [CurrencyIds.ETH]: {
+    id: CurrencyIds.ETH,
+    name: "Ethereum",
+    decimals: 18,
+  },
+  [CurrencyIds.USDC]: {
+    id: CurrencyIds.USDC,
+    name: "USDC",
+    decimals: 6,
+  },
+  [CurrencyIds.DAI]: {
+    id: CurrencyIds.DAI,
+    name: "Dai Stablecoin",
+    decimals: 18,
+  },
+};
+
+export const getCurrencyInfo = (currencyId: CurrencyId): CurrencyInfo => currencyInfo[currencyId];
+
+// NOTE: this mapping currently only considers the subset of chains where we have
+// supported token issuing contracts.
+const KNOWN_CURRENCY_CONTRACTS: Record<ChainId, Record<CurrencyId, Address>> = {
+  /** mainnet namespace */
+  [mainnet.id]: {
+    [CurrencyIds.ETH]: zeroAddress,
+    [CurrencyIds.USDC]: "0xA0b86a33E6417c5Dd4Baf8C54e5de49E293E9169",
+    [CurrencyIds.DAI]: "0x6B175474E89094C44Da98b954EedeAC495271d0F",
+  },
+  [base.id]: {
+    [CurrencyIds.ETH]: zeroAddress,
+    [CurrencyIds.USDC]: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+    [CurrencyIds.DAI]: "0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb",
+  },
+  [optimism.id]: {
+    [CurrencyIds.ETH]: zeroAddress,
+    [CurrencyIds.USDC]: "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
+    [CurrencyIds.DAI]: "0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1",
+  },
+  [linea.id]: {
+    [CurrencyIds.ETH]: zeroAddress,
+    [CurrencyIds.USDC]: "0x176211869cA2b568f2A7D4EE941E073a821EE1ff",
+    [CurrencyIds.DAI]: "0x4AF15ec2A0BD43Db75dd04E62FAA3B8EF36b00d5",
+  },
+
+  /** sepolia namespace */
+  [sepolia.id]: {
+    [CurrencyIds.ETH]: zeroAddress,
+    [CurrencyIds.USDC]: "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
+    [CurrencyIds.DAI]: "0x3e622317f8C93f7328350cF0B56d9eD4C620C5d6",
+  },
+  [baseSepolia.id]: {
+    [CurrencyIds.ETH]: zeroAddress,
+    [CurrencyIds.USDC]: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+    [CurrencyIds.DAI]: "0x7368C6C68a4b2b68F90DB2e8F5E3b8E1E5e4F5c7",
+  },
+  [lineaSepolia.id]: {
+    [CurrencyIds.ETH]: zeroAddress,
+    [CurrencyIds.USDC]: "0x176211869cA2b568f2A7D4EE941E073a821EE1ff",
+    [CurrencyIds.DAI]: "0x4AF15ec2A0BD43Db75dd04E62FAA3B8EF36b00d5",
+  },
+
+  /** holesky namespace */
+  [holesky.id]: {
+    [CurrencyIds.ETH]: zeroAddress,
+    [CurrencyIds.USDC]: "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
+    [CurrencyIds.DAI]: "0x3e622317f8C93f7328350cF0B56d9eD4C620C5d6",
+  },
+} as const;
+
+/**
+ * Gets the supported currency contracts for a given chain as a Record<CurrencyId, AccountId>
+ *
+ * @param chainId - The chain ID to get supported currency contracts for
+ * @returns a record of currency ids to AccountIds for the given chain
+ */
+const getSupportedCurrencyContractsForChain = (chainId: ChainId): Record<CurrencyId, AccountId> => {
+  return Object.fromEntries(
+    Object.entries(KNOWN_CURRENCY_CONTRACTS[chainId] ?? {}).map(([currencyId, address]) => [
+      currencyId,
+      { chainId, address },
+    ]),
+  ) as Record<CurrencyId, AccountId>;
+};
+
+/**
+ * Gets the currency id for the given contract
+ *
+ * @param contract - The AccountId of the contract to get the currency id for
+ * @returns the currency id for the given contract in the specified namespace, or
+ *          null if the contract is not a supported currency contract in the
+ *          specified namespace
+ */
+export const getCurrencyIdForContract = (contract: AccountId): CurrencyId | null => {
+  const supportedCurrencyContracts = getSupportedCurrencyContractsForChain(contract.chainId);
+
+  const found = Object.entries(supportedCurrencyContracts).find(([, accountId]) =>
+    accountIdEqual(accountId, contract),
+  );
+
+  if (!found) return null;
+
+  return found[0] as CurrencyId;
+};

apps/ensindexer/src/lib/datasource-helpers.ts

@@ -0,0 +1,38 @@
+import {
+  DatasourceName,
+  ENSNamespaceId,
+  getENSNamespace,
+  maybeGetDatasource,
+} from "@ensnode/datasources";
+import { AccountId, ChainId, uniq } from "@ensnode/ensnode-sdk";
+
+/**
+ * Gets the AccountId for the contract in the specified namespace, datasource, and
+ * contract name, or undefined if it is not defined or is not a single AccountId.
+ *
+ * This is useful when you want to retrieve the AccountId for a contract by its name
+ * where it may or may not actually be defined for the given namespace and datasource.
+ *
+ * @param namespaceId - The ENSNamespace identifier (e.g. 'mainnet', 'sepolia', 'holesky',
+ *                      'ens-test-env')
+ * @param datasourceName - The name of the Datasource to search for contractName in
+ * @param contractName - The name of the contract to retrieve
+ * @returns The AccountId of the contract with the given namespace, datasource,
+ *          and contract name, or undefined if it is not found or is not a single AccountId
+ */
+export const maybeGetDatasourceContract = (
+  namespaceId: ENSNamespaceId,
+  datasourceName: DatasourceName,
+  contractName: string,
+): AccountId | undefined => {
+  const datasource = maybeGetDatasource(namespaceId, datasourceName);
+  if (!datasource) return undefined;
+
+  const address = datasource.contracts[contractName]?.address;
+  if (address === undefined || Array.isArray(address)) return undefined;
+
+  return {
+    chainId: datasource.chain.id,
+    address,
+  };
+};

apps/ensindexer/src/lib/ponder-helpers.ts

@@ -11,7 +11,6 @@ import { Address, PublicClient } from "viem";
 import * as z from "zod/v4";
 
 import { ContractConfig } from "@ensnode/datasources";
-import { EnsRainbowApiClient } from "@ensnode/ensrainbow-sdk";
 import type { BlockInfo, PonderStatus } from "@ensnode/ponder-metadata";
 
 import { ENSIndexerConfig } from "@/config/types";

apps/ensindexer/src/lib/tokenscope/assets.ts

@@ -0,0 +1,14 @@
+/**
+ * An enum representing the possible CAIP-19 Asset Namespace values.
+ */
+export const AssetNamespaces = {
+  ERC721: "erc721",
+  ERC1155: "erc1155",
+} as const;
+
+export type AssetNamespace = (typeof AssetNamespaces)[keyof typeof AssetNamespaces];
+
+/**
+ * A uint256 value that identifies a specific token within an NFT contract.
+ */
+export type TokenId = bigint;

apps/ensindexer/src/lib/tokenscope/sales.ts

@@ -0,0 +1,24 @@
+import { AccountId, Node } from "@ensnode/ensnode-sdk";
+import { Address, Hex } from "viem";
+
+import { Price } from "@/lib/currencies";
+import { AssetNamespace, TokenId } from "@/lib/tokenscope/assets";
+
+export interface SupportedNFT {
+  assetNamespace: AssetNamespace;
+  contract: AccountId;
+  tokenId: TokenId;
+  domainId: Node;
+}
+
+export interface SupportedPayment {
+  price: Price;
+}
+
+export interface SupportedSale {
+  orderHash: Hex;
+  nft: SupportedNFT;
+  payment: SupportedPayment;
+  seller: Address;
+  buyer: Address;
+}