@ethereum-entity-registry/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,479 @@
+import { Address, WalletClient, PublicClient, Abi, Hex } from 'viem';
+import { Client, gql } from '@urql/core';
+import { PropsWithChildren } from 'react';
+import * as _tanstack_react_query from '@tanstack/react-query';
+import { UseMutationOptions, UseQueryResult } from '@tanstack/react-query';
+
+type SupportedChainId = 1 | 11155111 | 8453 | 84532 | 31337;
+type ChainConfig = {
+    registry?: `0x${string}`;
+    indexer?: string;
+};
+declare const config: Record<SupportedChainId, ChainConfig>;
+
+type Identifier = {
+    id: `0x${string}`;
+    namespace: string;
+    canonicalString: string;
+    owner: Address | null;
+    accountAddress: Address | null;
+    claimedAt: bigint | null;
+    revokedAt: bigint | null;
+    createdAt: bigint;
+};
+type IdentifierAlias = {
+    id: string;
+    aliasId: `0x${string}`;
+    primaryId: `0x${string}`;
+    linkedAt: bigint;
+};
+type Page<T> = {
+    items: T[];
+    totalCount: number;
+    pageInfo: {
+        hasNextPage: boolean;
+        endCursor?: string;
+    };
+};
+type IdentifierFilter = {
+    id?: string;
+    id_in?: string[];
+    namespace?: string;
+    owner?: string;
+    owner_in?: string[];
+    accountAddress?: string;
+};
+type AliasFilter = {
+    aliasId?: string;
+    primaryId?: string;
+    primaryId_in?: string[];
+};
+type QueryVariables<TFilter> = {
+    where?: TFilter;
+    orderBy?: string;
+    orderDirection?: "asc" | "desc";
+    limit?: number;
+    after?: string;
+};
+type RegistryStats = {
+    totalIdentifiers: number;
+    totalOwners: number;
+};
+type StatsResponse = {
+    data: RegistryStats;
+};
+type IndexerBase = {
+    client: Client;
+    gql: typeof gql;
+    baseUrl: string;
+    identifier: {
+        get: (id: `0x${string}`) => Promise<Identifier | null>;
+        query: (variables?: QueryVariables<IdentifierFilter>) => Promise<Page<Identifier> | null>;
+    };
+    alias: {
+        query: (variables?: QueryVariables<AliasFilter>) => Promise<Page<IdentifierAlias> | null>;
+    };
+    stats: () => Promise<RegistryStats>;
+};
+type Indexer = IndexerBase & {
+    extend<T>(extension: IndexerExtension<T>): Indexer & T;
+};
+type IndexerExtension<T> = (indexer: Indexer) => T;
+declare function createIndexer(chainId: SupportedChainId): Indexer;
+
+type IdentifierState = {
+    id: `0x${string}`;
+    depositAddress: Address;
+    owner: Address | null;
+    balance: bigint | null;
+};
+type ChainDeployments$1 = {
+    EntityRegistry: {
+        address: string;
+        abi: unknown;
+    };
+    beaconProxyBytecode?: string;
+};
+declare function createRegistryMethods(wallet: WalletClient | undefined, publicClient: PublicClient, deployments: ChainDeployments$1): {
+    /**
+     * Get the registered owner of an identifier (resolves through aliases).
+     * Returns null if unclaimed.
+     */
+    ownerOf: (id: `0x${string}`) => Promise<Address | null>;
+    /**
+     * Get the deterministic account address for an identifier.
+     */
+    predictAddress: (id: `0x${string}`) => Promise<Address>;
+    /**
+     * Claim ownership of an identifier with an oracle proof.
+     *
+     * @example
+     * sdk.registry.claim("github.com/org/repo", proof)
+     * sdk.registry.claim("example.com", proof)
+     * sdk.registry.claim("github:org/repo", proof)
+     */
+    claim: (input: string, proof: `0x${string}`) => Promise<{
+        hash: `0x${string}`;
+    }>;
+    /**
+     * Revoke ownership of an identifier.
+     *
+     * @example
+     * sdk.registry.revoke("github.com/org/repo")
+     * sdk.registry.revoke("example.com")
+     */
+    revoke: (input: string) => Promise<{
+        hash: `0x${string}`;
+    }>;
+    /**
+     * Link alias identifiers to a primary identifier.
+     */
+    linkIds: (primaryId: `0x${string}`, aliasIds: `0x${string}`[]) => Promise<{
+        hash: `0x${string}`;
+    }>;
+    /**
+     * Unlink alias identifiers from their primary.
+     */
+    unlinkIds: (primaryId: `0x${string}`, aliasIds: `0x${string}`[]) => Promise<{
+        hash: `0x${string}`;
+    }>;
+    /**
+     * Deploy the IdentityAccount proxy for an identifier (permissionless).
+     */
+    deployAccount: (id: `0x${string}`) => Promise<{
+        hash: `0x${string}`;
+    }>;
+    /**
+     * Admin: set or replace the verifier for a namespace.
+     */
+    setVerifier: (namespace: string, verifier: Address) => Promise<{
+        hash: `0x${string}`;
+    }>;
+    /**
+     * Compute the deterministic identifier for a namespace + canonical string.
+     */
+    toId: (namespace: string, canonicalString: string) => `0x${string}`;
+    /**
+     * Check whether the IdentityAccount for an identifier has been deployed.
+     * Returns false if the deposit address has no code (not yet deployed).
+     * The registry deploys it automatically during claim(), but funders can
+     * send tokens before it's deployed — the address is always the same.
+     */
+    isAccountDeployed: (id: `0x${string}`) => Promise<boolean>;
+    /**
+     * Resolve the full state of an identifier: owner, deposit address, and
+     * ERC-20 balance — all in a single parallel batch of RPC calls.
+     *
+     * @example
+     * const state = await sdk.registry.resolveIdentifier("github", "org/repo", tokenAddress)
+     * // state.depositAddress — where funders should send tokens
+     * // state.owner          — null if unclaimed
+     * // state.balance        — claimable token balance at the deposit address
+     */
+    resolveIdentifier: (namespace: string, rawCanonicalString: string, token?: Address) => Promise<IdentifierState>;
+    /**
+     * Resolve any free-form identifier string to its on-chain state.
+     * Accepts namespace:value, URLs, and domain names.
+     *
+     * @example
+     * sdk.registry.resolve("github:org/repo")
+     * sdk.registry.resolve("github.com/org/repo")
+     * sdk.registry.resolve("https://github.com/org/repo")
+     * sdk.registry.resolve("dns:example.com")
+     * sdk.registry.resolve("www.example.com")
+     * sdk.registry.resolve("npm:package-name")
+     * sdk.registry.resolve("npmjs.com/package/foo")
+     */
+    resolve: (input: string, token?: Address) => Promise<IdentifierState>;
+};
+
+type ChainDeployments = {
+    IdentityAccount: {
+        abi: unknown;
+    };
+};
+declare function createAccountMethods(wallet: WalletClient | undefined, publicClient: PublicClient, deployments: ChainDeployments): {
+    /**
+     * Execute an arbitrary call through an IdentityAccount.
+     * Only the registered owner of the identifier can call this.
+     */
+    execute: (accountAddress: Address, target: Address, data: `0x${string}`, value?: bigint) => Promise<{
+        hash: `0x${string}`;
+    }>;
+    /**
+     * Encode an ERC-20 transfer from the identity account to a recipient.
+     *
+     * @example
+     * const { target, data } = sdk.account.encodeERC20Transfer(tokenAddress, recipient, amount);
+     * await sdk.account.execute(accountAddress, target, data);
+     */
+    encodeERC20Transfer: (token: Address, to: Address, amount: bigint) => {
+        target: `0x${string}`;
+        data: `0x${string}`;
+    };
+    /**
+     * Encode a Splits Warehouse withdrawal to pull tokens owed to the identity account.
+     *
+     * @example
+     * const { target, data } = sdk.account.encodeWarehouseWithdraw(warehouseAddress, accountAddress, tokenAddress);
+     * await sdk.account.execute(accountAddress, target, data);
+     */
+    encodeWarehouseWithdraw: (warehouse: Address, owner: Address, token: Address) => {
+        target: `0x${string}`;
+        data: `0x${string}`;
+    };
+    /**
+     * Encode an ERC-721 transfer from the identity account.
+     *
+     * @example
+     * const { target, data } = sdk.account.encodeERC721Transfer(nftAddress, accountAddress, recipient, tokenId);
+     * await sdk.account.execute(accountAddress, target, data);
+     */
+    encodeERC721Transfer: (nft: Address, from: Address, to: Address, tokenId: bigint) => {
+        target: `0x${string}`;
+        data: `0x${string}`;
+    };
+};
+
+/**
+ * Execute a transaction and extract a specific event from the logs.
+ */
+declare function writeAndParse<T>(wallet: WalletClient, hash: `0x${string}`, abi: Abi, eventName: string): Promise<T>;
+/**
+ * Execute a transaction without parsing events, just wait for confirmation.
+ */
+declare function writeAndWait(wallet: WalletClient, hash: `0x${string}`): Promise<{
+    hash: `0x${string}`;
+}>;
+
+type EntityRegistryProviderProps<T extends EntityRegistrySDK> = PropsWithChildren<{
+    client?: WalletClient;
+    defaultChain?: SupportedChainId;
+}>;
+declare function EntityRegistryProvider<T extends EntityRegistrySDK = EntityRegistrySDK>({ children, client, defaultChain, }: EntityRegistryProviderProps<T>): React.ReactNode;
+declare function useEntityRegistrySDK<T extends EntityRegistrySDK = EntityRegistrySDK>(): {
+    sdk: T | null;
+};
+
+declare const INVALIDATION_TIMEOUT_MS = 3000;
+declare function useInvalidate(): (queryKeys: unknown[][]) => void;
+
+type QueryOptions$1 = {
+    enabled?: boolean;
+    refetchInterval?: number;
+};
+declare function useOwnerOf(id: `0x${string}` | undefined, opts?: QueryOptions$1): UseQueryResult<Address | null>;
+declare function usePredictAddress(id: `0x${string}` | undefined, opts?: QueryOptions$1): UseQueryResult<Address | null>;
+declare function useToId(namespace: string | undefined, canonicalString: string | undefined, opts?: QueryOptions$1): UseQueryResult<`0x${string}` | null>;
+declare function useClaim(opts?: UseMutationOptions<{
+    hash: `0x${string}`;
+}, Error, {
+    input: string;
+    proof: `0x${string}`;
+}>): _tanstack_react_query.UseMutationResult<{
+    hash: `0x${string}`;
+}, Error, {
+    input: string;
+    proof: `0x${string}`;
+}, unknown>;
+declare function useRevoke(opts?: UseMutationOptions<{
+    hash: `0x${string}`;
+}, Error, {
+    input: string;
+}>): _tanstack_react_query.UseMutationResult<{
+    hash: `0x${string}`;
+}, Error, {
+    input: string;
+}, unknown>;
+declare function useLinkIds(opts?: UseMutationOptions<{
+    hash: `0x${string}`;
+}, Error, {
+    primaryId: `0x${string}`;
+    aliasIds: `0x${string}`[];
+}>): _tanstack_react_query.UseMutationResult<{
+    hash: `0x${string}`;
+}, Error, {
+    primaryId: `0x${string}`;
+    aliasIds: `0x${string}`[];
+}, unknown>;
+declare function useUnlinkIds(opts?: UseMutationOptions<{
+    hash: `0x${string}`;
+}, Error, {
+    primaryId: `0x${string}`;
+    aliasIds: `0x${string}`[];
+}>): _tanstack_react_query.UseMutationResult<{
+    hash: `0x${string}`;
+}, Error, {
+    primaryId: `0x${string}`;
+    aliasIds: `0x${string}`[];
+}, unknown>;
+declare function useDeployAccount(opts?: UseMutationOptions<{
+    hash: `0x${string}`;
+}, Error, {
+    id: `0x${string}`;
+}>): _tanstack_react_query.UseMutationResult<{
+    hash: `0x${string}`;
+}, Error, {
+    id: `0x${string}`;
+}, unknown>;
+
+declare function useExecute(opts?: UseMutationOptions<{
+    hash: `0x${string}`;
+}, Error, {
+    accountAddress: Address;
+    target: Address;
+    data: `0x${string}`;
+    value?: bigint;
+}>): _tanstack_react_query.UseMutationResult<{
+    hash: `0x${string}`;
+}, Error, {
+    accountAddress: Address;
+    target: Address;
+    data: `0x${string}`;
+    value?: bigint;
+}, unknown>;
+
+type QueryOptions = {
+    enabled?: boolean;
+    refetchInterval?: number;
+};
+declare function useIdentifiers(variables?: QueryVariables<IdentifierFilter>, opts?: QueryOptions): UseQueryResult<Page<Identifier> | null>;
+declare function useIdentifier(id: `0x${string}` | undefined, opts?: QueryOptions): UseQueryResult<Identifier | null>;
+declare function useAliases(variables?: QueryVariables<AliasFilter>, opts?: QueryOptions): UseQueryResult<Page<IdentifierAlias> | null>;
+declare function useRegistryStats(opts?: QueryOptions): UseQueryResult<RegistryStats | null>;
+
+type TokenConfig = {
+    address: Address;
+    symbol: string;
+    name: string;
+    decimals: number;
+    logoURI?: string;
+};
+/**
+ * Native ETH address per ERC-7528 standard
+ * Used throughout the system to represent native ETH
+ */
+declare const NATIVE_TOKEN = "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE";
+declare const isNativeToken: (token?: string) => boolean;
+/**
+ * Native ETH token config
+ */
+declare const ETH_TOKEN: TokenConfig;
+/**
+ * Get all available tokens for a chain
+ */
+declare function getTokens(chainId: number): TokenConfig[];
+/**
+ * Get a token by symbol for a chain
+ */
+declare function getToken(chainId: number, symbol: string): TokenConfig | undefined;
+/**
+ * Get a token by address for a chain
+ */
+declare function getTokenByAddress(chainId: number, address: Address): TokenConfig | undefined;
+/**
+ * Get token addresses for a chain (useful for indexer)
+ */
+declare function getTokenAddresses(chainId: number): Address[];
+
+/**
+ * Default canonicalisation: lowercase, trim whitespace, strip trailing slash.
+ * Baseline for all namespaces (github, dns).
+ * The contract does not enforce any normalisation — consistency is the caller's
+ * responsibility.
+ */
+declare function canonicalise(value: string): string;
+/**
+ * Derive the bytes32 identifier for a (namespace, canonicalString) pair.
+ * Matches: keccak256(abi.encode(namespace, canonicalString))
+ *
+ * This is a pure local computation — no RPC call required.
+ */
+declare function toId(namespace: string, canonicalString: string): Hex;
+/**
+ * Format namespace + canonicalString into a human-readable identifier string.
+ * e.g. formatIdentifier("github", "org/repo") → "github:org/repo"
+ */
+declare function formatIdentifier(namespace: string, canonicalString: string): string;
+/**
+ * Parse a colon-separated identifier string into its parts.
+ * e.g. parseIdentifier("github:org/repo") → { namespace: "github", canonicalString: "org/repo" }
+ */
+declare function parseIdentifier(identifier: string): {
+    namespace: string;
+    canonicalString: string;
+};
+type ParsedUrl = {
+    namespace: string;
+    canonicalString: string;
+    /** The normalised form, suitable for display: e.g. "github:org/repo" */
+    formatted: string;
+};
+/**
+ * Parse a free-form URL or handle into a registry identifier.
+ *
+ * Accepts all of the following for a GitHub repo:
+ *   github.com/org/repo
+ *   https://github.com/org/repo
+ *   https://www.github.com/org/repo/tree/main  (extra path segments ignored)
+ *
+ * Accepts all of the following for a DNS domain:
+ *   example.com
+ *   https://example.com
+ *   https://www.example.com/some/path          (path ignored)
+ *
+ * Throws if the input cannot be mapped to a known namespace.
+ */
+declare function parseUrl(input: string): ParsedUrl;
+/**
+ * Parse any free-form identifier string into namespace + canonicalString.
+ *
+ * Handles all of these forms:
+ *   github:org/repo          → namespace:value  (explicit prefix)
+ *   dns:example.com          → namespace:value
+ *   npm:package-name         → namespace:value
+ *   github.com/org/repo      → URL-style
+ *   https://github.com/...   → URL-style
+ *   www.example.com          → URL-style
+ */
+declare function parseAnyIdentifier(input: string): {
+    namespace: string;
+    canonicalString: string;
+};
+/**
+ * Derive the beacon address from the registry address.
+ *
+ * The beacon is deployed with `new UpgradeableBeacon(...)` as the first
+ * contract created in the EntityRegistry constructor. Per EIP-161, a new
+ * contract starts with nonce=1, so the beacon address is the CREATE address
+ * of (registryAddress, nonce=1).
+ *
+ * This is a pure local computation — no RPC call required.
+ */
+declare function deriveBeaconAddress(registryAddress: Address): Address;
+/**
+ * Compute the deterministic deposit address for any identifier.
+ * This is a pure local computation — no RPC call required.
+ *
+ * The address is stable whether or not the escrow proxy has been deployed,
+ * and does NOT change if the escrow implementation is upgraded via the beacon.
+ *
+ * @param id               bytes32 identifier from toId()
+ * @param registryAddress  deployed EntityRegistry address
+ * @param beaconProxyBytecode  creation bytecode of OpenZeppelin BeaconProxy
+ *                             (available as deployments.beaconProxyBytecode)
+ */
+declare function resolveDepositAddress(id: Hex, registryAddress: Address, beaconProxyBytecode: Hex): Address;
+
+declare class EntityRegistrySDK {
+    #private;
+    registry: ReturnType<typeof createRegistryMethods>;
+    account: ReturnType<typeof createAccountMethods>;
+    constructor(wallet?: WalletClient, defaultChain?: SupportedChainId);
+    get wallet(): WalletClient | undefined;
+    get publicClient(): PublicClient;
+    get chainId(): SupportedChainId;
+    get indexer(): Indexer | null;
+}
+
+export { type AliasFilter, ETH_TOKEN, EntityRegistryProvider, EntityRegistrySDK, INVALIDATION_TIMEOUT_MS, type Identifier, type IdentifierAlias, type IdentifierFilter, type IdentifierState, type Indexer, type IndexerExtension, NATIVE_TOKEN, type Page, type ParsedUrl, type QueryVariables, type RegistryStats, type StatsResponse, type SupportedChainId, type TokenConfig, canonicalise, config, createIndexer, deriveBeaconAddress, formatIdentifier, getToken, getTokenAddresses, getTokenByAddress, getTokens, isNativeToken, parseAnyIdentifier, parseIdentifier, parseUrl, resolveDepositAddress, toId, useAliases, useClaim, useDeployAccount, useEntityRegistrySDK, useExecute, useIdentifier, useIdentifiers, useInvalidate, useLinkIds, useOwnerOf, usePredictAddress, useRegistryStats, useRevoke, useToId, useUnlinkIds, writeAndParse, writeAndWait };