@circle-fin/adapter-ethers-v6 0.0.2-alpha.6

package/index.d.ts

@@ -0,0 +1,2679 @@
+/**
+ * Copyright (c) 2025, Circle Internet Group, Inc. All rights reserved.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { Provider, Signer as Signer$1, Eip1193Provider } from 'ethers';
+import { Abi } from 'abitype';
+import { TransactionInstruction, Signer } from '@solana/web3.js';
+
+/**
+ * @packageDocumentation
+ * @module ChainDefinitions
+ *
+ * This module provides a complete type system for blockchain chain definitions.
+ * It supports both EVM and non‑EVM chains, token configurations, and multiple
+ * versions of the Cross-Chain Transfer Protocol (CCTP). Additionally, utility types
+ * are provided to extract subsets of chains (e.g. chains supporting USDC, EURC, or specific
+ * CCTP versions) from a provided collection.
+ *
+ * All types are fully documented with TSDoc to maximize developer experience.
+ */
+/**
+ * Represents basic information about a currency or token.
+ * @interface Currency
+ * @category Types
+ * @description Provides the essential properties of a cryptocurrency or token.
+ * @example
+ * ```typescript
+ * const ethCurrency: Currency = {
+ *   name: "Ether",
+ *   symbol: "ETH",
+ *   decimals: 18
+ * };
+ * ```
+ */
+interface Currency {
+    /**
+     * The full name of the currency.
+     * @example "Ether", "USDC"
+     */
+    name: string;
+    /**
+     * The symbol or ticker of the currency.
+     * @example "ETH", "USDC"
+     */
+    symbol: string;
+    /**
+     * The number of decimal places for the currency.
+     * @description Defines the divisibility of the currency (e.g., 1 ETH = 10^18 wei).
+     * @example 18 for ETH, 6 for USDC
+     */
+    decimals: number;
+}
+/**
+ * Base information that all chain definitions must include.
+ * @interface BaseChainDefinition
+ * @category Types
+ * @description Provides the common properties shared by all blockchain definitions.
+ * @example
+ * ```typescript
+ * const baseChain: BaseChainDefinition = {
+ *   chain: Blockchain.Ethereum,
+ *   name: "Ethereum",
+ *   nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
+ *   isTestnet: false
+ * };
+ * ```
+ */
+interface BaseChainDefinition {
+    /**
+     * The blockchain identifier from the {@link Blockchain} enum.
+     */
+    chain: Blockchain;
+    /**
+     * The display name of the blockchain.
+     * @example "Ethereum", "Solana", "Avalanche"
+     */
+    name: string;
+    /**
+     * Optional title or alternative name for the blockchain.
+     * @example "Ethereum Mainnet", "Solana Mainnet"
+     */
+    title?: string;
+    /**
+     * Information about the native currency of the blockchain.
+     */
+    nativeCurrency: Currency;
+    /**
+     * Indicates whether this is a testnet or mainnet.
+     * @description Used to differentiate between production and testing environments.
+     */
+    isTestnet: boolean;
+    /**
+     * Template URL for the blockchain explorer to view transactions.
+     * @description URL template with a `\{hash\}` placeholder for transaction hash.
+     * @example "https://etherscan.io/tx/\{hash\}", "https://sepolia.etherscan.io/tx/\{hash\}"
+     */
+    explorerUrl: string;
+    /**
+     * Default RPC endpoints for connecting to the blockchain network.
+     * @description Array of reliable public RPC endpoints that can be used for read and write operations.
+     * The first endpoint in the array is considered the primary endpoint.
+     * @example ["https://cloudflare-eth.com", "https://ethereum.publicnode.com"]
+     */
+    rpcEndpoints: readonly string[];
+    /**
+     * The contract address for EURC.
+     * @description Its presence indicates that EURC is supported.
+     */
+    eurcAddress: string | null;
+    /**
+     * The contract address for USDC.
+     * @description Its presence indicates that USDC is supported.
+     */
+    usdcAddress: string | null;
+    /**
+     * Optional CCTP configuration.
+     * @description If provided, the chain supports CCTP.
+     */
+    cctp: CCTPConfig | null;
+    /**
+     * Optional kit-specific contract addresses for enhanced chain functionality.
+     *
+     * @description When provided, the chain supports additional kit-specific logic in addition
+     * to standard CCTP. This enables hybrid flows where both standard approve/burn/mint
+     * and enhanced custom features are available. When undefined, the chain uses only
+     * the standard CCTP flow.
+     *
+     * The address format varies by blockchain:
+     * - EVM chains: 40-character hexadecimal with 0x prefix (e.g., "0x1234...")
+     * - Solana: Base58-encoded 32-byte address (e.g., "9WzDX...")
+     * - Other chains: Platform-specific address formats
+     *
+     * @example
+     * ```typescript
+     * // EVM chain with bridge contract
+     * const evmChain: ChainDefinition = {
+     *   // ... other properties
+     *   kitContracts: {
+     *     bridge: "0x1234567890abcdef1234567890abcdef12345678"
+     *   }
+     * }
+     *
+     * // Solana chain with bridge contract
+     * const solanaChain: ChainDefinition = {
+     *   // ... other properties
+     *   kitContracts: {
+     *     bridge: "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
+     *   }
+     * }
+     * ```
+     */
+    kitContracts?: KitContracts;
+}
+/**
+ * Represents chain definitions for Ethereum Virtual Machine (EVM) compatible blockchains.
+ * @interface EVMChainDefinition
+ * @extends BaseChainDefinition
+ * @category Types
+ * @description Adds properties specific to EVM chains.
+ * @example
+ * ```typescript
+ * const ethereum: EVMChainDefinition = {
+ *   type: 'evm',
+ *   chain: Blockchain.Ethereum,
+ *   chainId: 1,
+ *   name: 'Ethereum',
+ *   title: 'Ethereum Mainnet',
+ *   nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+ *   isTestnet: false
+ * };
+ * ```
+ */
+interface EVMChainDefinition extends BaseChainDefinition {
+    /**
+     * Discriminator for EVM chains.
+     * @description Used for type narrowing when handling different chain types.
+     */
+    type: 'evm';
+    /**
+     * The unique identifier for the blockchain.
+     * @description Standard EVM chain ID as defined in EIP-155.
+     * @example 1 for Ethereum Mainnet, 137 for Polygon.
+     */
+    chainId: number;
+}
+/**
+ * Represents chain definitions for non-EVM blockchains.
+ * @interface NonEVMChainDefinition
+ * @extends BaseChainDefinition
+ * @category Types
+ * @description Contains properties for blockchains that do not use the EVM.
+ * @example
+ * ```typescript
+ * const solana: NonEVMChainDefinition = {
+ *   type: 'solana',
+ *   chain: Blockchain.Solana,
+ *   name: 'Solana',
+ *   nativeCurrency: { name: 'Solana', symbol: 'SOL', decimals: 9 },
+ *   isTestnet: false
+ * };
+ * ```
+ */
+interface NonEVMChainDefinition extends BaseChainDefinition {
+    /**
+     * Discriminator for non-EVM chains.
+     * @description Identifies the specific blockchain platform.
+     */
+    type: 'algorand' | 'avalanche' | 'solana' | 'aptos' | 'near' | 'stellar' | 'sui' | 'hedera' | 'noble' | 'polkadot';
+}
+/**
+ * The type of chain.
+ * @alias ChainType
+ * @category Types
+ * @description Represents the type of chain.
+ * @example
+ * ```typescript
+ * const chainType: ChainType = 'evm'
+ * ```
+ */
+type ChainType = EVMChainDefinition['type'] | NonEVMChainDefinition['type'];
+/**
+ * Public chain definition type.
+ * @alias ChainDefinition
+ * @category Types
+ * @description Represents either an EVM-based or non-EVM-based blockchain definition.
+ * This type is used by developers to define chain configurations.
+ * @example
+ * ```typescript
+ * // Standard chain with CCTP support only
+ * const ethereumChain: ChainDefinition = {
+ *   type: 'evm',
+ *   chain: Blockchain.Ethereum,
+ *   chainId: 1,
+ *   name: 'Ethereum',
+ *   nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+ *   isTestnet: false,
+ *   explorerUrl: 'https://etherscan.io/tx/{hash}',
+ *   rpcEndpoints: ['https://eth.example.com'],
+ *   eurcAddress: null,
+ *   usdcAddress: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+ *   cctp: {
+ *     domain: 0,
+ *     contracts: {
+ *       v2: {
+ *         type: 'split',
+ *         tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+ *         messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
+ *         confirmations: 65,
+ *         fastConfirmations: 2
+ *       }
+ *     }
+ *   },
+ *   kitContracts: undefined
+ * };
+ *
+ * // Chain with custom contract support (hybrid flow)
+ * const customChain: ChainDefinition = {
+ *   ...ethereumChain,
+ *   kitContracts: {
+ *     bridge: '0x1234567890abcdef1234567890abcdef12345678'
+ *   }
+ * };
+ * ```
+ */
+type ChainDefinition = EVMChainDefinition | NonEVMChainDefinition;
+/**
+ * Chain definition with CCTPv2 configuration.
+ * @alias ChainDefinitionWithCCTPv2
+ * @extends ChainDefinition
+ * @category Types
+ * @description Represents a chain definition that includes CCTPv2 configuration. This is useful for typescript consumers to narrow down the type of chain definition to a chain that supports CCTPv2.
+ * @example
+ * ```typescript
+ * const ethereumWithCCTPv2: ChainDefinitionWithCCTPv2 = {
+ *   ...ethereum,
+ *   cctp: {
+ *     domain: 0,
+ *     contracts: {
+ *       v2: {
+ *         type: 'merged',
+ *         contract: '0x123...'
+ *       }
+ *     }
+ *   }
+ * };
+ * ```
+ */
+type ChainDefinitionWithCCTPv2 = ChainDefinition & {
+    cctp: CCTPConfig & {
+        contracts: {
+            v2: VersionConfig;
+        };
+    };
+    usdcAddress: string;
+};
+/**
+ * Chain identifier that can be used in transfer parameters and factory functions.
+ * This can be either:
+ * - A ChainDefinition object
+ * - A Blockchain enum value (e.g., Blockchain.Ethereum)
+ * - A string literal of the blockchain value (e.g., "Ethereum")
+ */
+type ChainIdentifier = ChainDefinition | Blockchain | `${Blockchain}`;
+interface CCTPSplitConfig {
+    type: 'split';
+    tokenMessenger: string;
+    messageTransmitter: string;
+    confirmations: number;
+}
+interface CCTPMergedConfig {
+    type: 'merged';
+    contract: string;
+    confirmations: number;
+}
+type VersionConfig = CCTPSplitConfig | CCTPMergedConfig;
+type CCTPContracts = Partial<{
+    v1: VersionConfig;
+    v2: VersionConfig & {
+        fastConfirmations: number;
+    };
+}>;
+/**
+ * Configuration for the Cross-Chain Transfer Protocol (CCTP).
+ * @interface CCTPConfig
+ * @category Types
+ * @description Contains the domain and required contract addresses for CCTP support.
+ * @example
+ * ```
+ * const cctpConfig: CCTPConfig = {
+ *   domain: 0,
+ *   contracts: {
+ *     TokenMessenger: '0xabc',
+ *     MessageReceiver: '0xdef'
+ *   }
+ * };
+ * ```
+ */
+interface CCTPConfig {
+    /**
+     * The CCTP domain identifier.
+     */
+    domain: number;
+    /**
+     * The contracts required for CCTP.
+     */
+    contracts: CCTPContracts;
+}
+/**
+ * Available kit contract types for enhanced chain functionality.
+ *
+ * @description Defines the valid contract types that can be deployed on chains
+ * to provide additional features beyond standard CCTP functionality.
+ *
+ * @example
+ * ```typescript
+ * import type { KitContractType } from '@core/chains'
+ *
+ * const contractType: KitContractType = 'bridge' // Valid
+ * const invalidType: KitContractType = 'invalid' // TypeScript error
+ * ```
+ */
+type KitContractType = 'bridge';
+/**
+ * Kit-specific contract addresses for enhanced chain functionality.
+ *
+ * @description Maps contract types to their addresses on a specific chain.
+ * All contract types are optional, allowing chains to selectively support
+ * specific kit features.
+ *
+ * @example
+ * ```typescript
+ * import type { KitContracts } from '@core/chains'
+ *
+ * const contracts: KitContracts = {
+ *   bridge: "0x1234567890abcdef1234567890abcdef12345678"
+ * }
+ *
+ * // Future example with multiple contract types:
+ * const futureContracts: KitContracts = {
+ *   bridge: "0x1234567890abcdef1234567890abcdef12345678",
+ *   // Note: other contract types would be added to KitContractType union
+ *   // customType: "0xabcdef1234567890abcdef1234567890abcdef12"
+ * }
+ * ```
+ */
+type KitContracts = Partial<Record<KitContractType, string>>;
+/**
+ * Enumeration of all blockchains supported by this library.
+ * @enum
+ * @category Enums
+ * @description Provides string identifiers for each supported blockchain.
+ */
+declare enum Blockchain {
+    Algorand = "Algorand",
+    Algorand_Testnet = "Algorand_Testnet",
+    Aptos = "Aptos",
+    Aptos_Testnet = "Aptos_Testnet",
+    Arbitrum = "Arbitrum",
+    Arbitrum_Sepolia = "Arbitrum_Sepolia",
+    Avalanche = "Avalanche",
+    Avalanche_Fuji = "Avalanche_Fuji",
+    Base = "Base",
+    Base_Sepolia = "Base_Sepolia",
+    Celo = "Celo",
+    Celo_Alfajores_Testnet = "Celo_Alfajores_Testnet",
+    Codex = "Codex",
+    Codex_Testnet = "Codex_Testnet",
+    Ethereum = "Ethereum",
+    Ethereum_Sepolia = "Ethereum_Sepolia",
+    Hedera = "Hedera",
+    Hedera_Testnet = "Hedera_Testnet",
+    Linea = "Linea",
+    Linea_Sepolia = "Linea_Sepolia",
+    NEAR = "NEAR",
+    NEAR_Testnet = "NEAR_Testnet",
+    Noble = "Noble",
+    Noble_Testnet = "Noble_Testnet",
+    Optimism = "Optimism",
+    Optimism_Sepolia = "Optimism_Sepolia",
+    Polkadot_Asset_Hub = "Polkadot_Asset_Hub",
+    Polkadot_Westmint = "Polkadot_Westmint",
+    Polygon = "Polygon",
+    Polygon_Amoy_Testnet = "Polygon_Amoy_Testnet",
+    Sei = "Sei",
+    Sei_Testnet = "Sei_Testnet",
+    Solana = "Solana",
+    Solana_Devnet = "Solana_Devnet",
+    Sonic = "Sonic",
+    Sonic_Testnet = "Sonic_Testnet",
+    Stellar = "Stellar",
+    Stellar_Testnet = "Stellar_Testnet",
+    Sui = "Sui",
+    Sui_Testnet = "Sui_Testnet",
+    Unichain = "Unichain",
+    Unichain_Sepolia = "Unichain_Sepolia",
+    World_Chain = "World_Chain",
+    World_Chain_Sepolia = "World_Chain_Sepolia",
+    ZKSync_Era = "ZKSync_Era",
+    ZKSync_Sepolia = "ZKSync_Sepolia"
+}
+
+/**
+ * Core type definitions for blockchain transaction execution and gas estimation.
+ *
+ * This module provides TypeScript interfaces and types for handling blockchain
+ * transactions across different networks, with a focus on EVM-compatible chains
+ * and gas estimation.
+ *
+ * @module types
+ */
+
+/**
+ * Estimated gas information for a blockchain transaction.
+ *
+ * This interface provides a unified way to represent gas costs across different
+ * blockchain networks, supporting both EVM-style gas calculations and other
+ * fee models.
+ *
+ * @interface EstimatedGas
+ * @category Types
+ * @example
+ * ```typescript
+ * // EVM chain example
+ * const evmGas: EstimatedGas = {
+ *   gas: 21000n,
+ *   gasPrice: 1000000000n, // 1 Gwei
+ *   fee: (21000n * 1000000000n).toString() // Total fee in wei
+ * };
+ *
+ * // Solana example
+ * const solanaGas: EstimatedGas = {
+ *   gas: 5000n, // Lamports for compute units
+ *   fee: '5000' // Total fee in Lamports
+ * };
+ * ```
+ */
+interface EstimatedGas {
+    /**
+     * The amount of gas estimated for the transaction.
+     * For EVM chains, this represents the gas units.
+     * For other chains, this might represent compute units or similar metrics.
+     *
+     * @example 21000n, 5000n
+     */
+    gas: bigint;
+    /**
+     * The estimated price per unit of gas.
+     * This is primarily used in EVM chains where gas price is a separate metric.
+     *
+     * @example 1000000000n
+     */
+    gasPrice: bigint;
+    /**
+     * The total estimated fee as a string.
+     * This field is useful for chains where gas/gasPrice isn't the whole story
+     * or when the total fee needs to be represented in a different format.
+     * For EVM chains, this is the total fee in wei (gas * gasPrice).
+     *
+     * @example "21000000000000", "5000"
+     */
+    fee: string;
+}
+/**
+ * Override parameters for EVM gas estimation.
+ *
+ * These parameters allow customization of gas estimation behavior
+ * for EVM-compatible chains.
+ *
+ * @interface EvmEstimateOverrides
+ */
+interface EvmEstimateOverrides {
+    /**
+     * The sender's address for the transaction.
+     * @example "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
+     */
+    from?: string;
+    /**
+     * The value to be sent with the transaction in wei.
+     * @example 1000000000000000000n // 1 ETH
+     */
+    value?: bigint;
+    /**
+     * The block tag to use for estimation.
+     * @example "latest", "safe", "finalized"
+     */
+    blockTag?: 'latest' | 'earliest' | 'pending' | 'safe' | 'finalized';
+    /**
+     * The maximum gas limit for the transaction.
+     * @example 3000000
+     */
+    gasLimit?: number;
+    /**
+     * The maximum fee per gas unit (EIP-1559).
+     * @example 20000000000n // 20 Gwei
+     */
+    maxFeePerGas?: bigint;
+    /**
+     * The maximum priority fee per gas unit (EIP-1559).
+     * @example 1500000000n // 1.5 Gwei
+     */
+    maxPriorityFeePerGas?: bigint;
+}
+/**
+ * Extended override parameters for EVM transaction execution.
+ *
+ * Includes all estimation overrides plus additional parameters
+ * specific to transaction execution.
+ *
+ * @interface EvmExecuteOverrides
+ * @extends EvmEstimateOverrides
+ */
+interface EvmExecuteOverrides extends EvmEstimateOverrides {
+    /**
+     * The nonce to use for the transaction.
+     * If not provided, the current nonce of the sender will be used.
+     * @example 42
+     */
+    nonce?: number;
+}
+/**
+ * Prepared contract execution for EVM chains.
+ *
+ * Represents a prepared contract execution that can be estimated
+ * and executed on EVM-compatible chains.
+ *
+ * @interface EvmPreparedChainRequest
+ */
+interface EvmPreparedChainRequest {
+    /** The type of the prepared execution. */
+    type: 'evm';
+    /**
+     * Estimate the gas cost for the contract execution.
+     *
+     * @param overrides - Optional parameters to override the default estimation behavior
+     * @returns A promise that resolves to the estimated gas information
+     * @throws If the estimation fails
+     */
+    estimate(overrides?: EvmEstimateOverrides): Promise<EstimatedGas>;
+    /**
+     * Execute the prepared contract call.
+     *
+     * @param overrides - Optional parameters to override the default execution behavior
+     * @returns A promise that resolves to the transaction hash
+     * @throws If the execution fails
+     */
+    execute(overrides?: EvmExecuteOverrides): Promise<string>;
+}
+/**
+ * Union type for all supported prepared contract executions.
+ * Currently only supports EVM chains, but can be extended for other chains.
+ */
+type PreparedChainRequest = EvmPreparedChainRequest | SolanaPreparedChainRequest | NoopPreparedChainRequest;
+/**
+ * Parameters for preparing an EVM contract execution.
+ */
+type EvmPreparedChainRequestParams = {
+    /** The type of the prepared execution. */
+    type: 'evm';
+    /** The ABI of the contract. */
+    abi: Abi | string[];
+    /** The address of the contract. */
+    address: `0x${string}`;
+    /** The name of the function to call. */
+    functionName: string;
+    /** The arguments to pass to the function. */
+    args: unknown[];
+    /**
+     * The chain the prepared request should be executed on.
+     */
+    chain: EVMChainDefinition;
+} & Partial<EvmEstimateOverrides>;
+/**
+ * Solana-specific parameters for preparing a transaction.
+ * @interface SolanaPreparedChainRequestParams
+ */
+interface SolanaPreparedChainRequestParams {
+    /**
+     * The array of instructions to include in the transaction.
+     */
+    instructions: TransactionInstruction[];
+    /**
+     * Additional signers besides the Adapter’s wallet (e.g. program-derived authorities).
+     */
+    signers?: Signer[];
+    /**
+     * Optional override for how many compute units this transaction may consume.
+     * If omitted, the network’s default compute budget applies.
+     */
+    computeUnitLimit?: number;
+}
+/**
+ * Solana-specific configuration for transaction estimation.
+ * @interface SolanaEstimateOverrides
+ */
+interface SolanaEstimateOverrides {
+    /** Optional compute unit limit for the transaction. */
+    computeUnitLimit?: number;
+}
+/**
+ * Solana-specific configuration for transaction execution.
+ * @interface SolanaExecuteOverrides
+ * @extends SolanaEstimateOverrides
+ */
+interface SolanaExecuteOverrides extends SolanaEstimateOverrides {
+    /** The commitment level for the transaction. */
+    preflightCommitment?: 'processed' | 'confirmed' | 'finalized';
+    /** The maximum number of retries for the transaction. */
+    maxRetries?: number;
+    /** Whether to skip the preflight check. */
+    skipPreflight?: boolean;
+}
+/**
+ * Solana-specific prepared chain request.
+ * @interface SolanaPreparedChainRequest
+ */
+interface SolanaPreparedChainRequest {
+    /** The type of the chain request. */
+    type: 'solana';
+    /** Estimate the compute units and fee for the transaction. */
+    estimate(overrides?: SolanaEstimateOverrides): Promise<EstimatedGas>;
+    /** Execute the prepared transaction. */
+    execute(overrides?: SolanaExecuteOverrides): Promise<string>;
+}
+/**
+ * No-op prepared chain request for unsupported operations.
+ *
+ * This interface represents a prepared chain request that performs no operation.
+ * It is returned when an action is not supported by the target chain or when
+ * no actual blockchain interaction is required.
+ *
+ * @remarks
+ * The estimate and execute methods return placeholder values since no actual
+ * transaction is performed. This allows the calling code to handle unsupported
+ * operations gracefully without breaking the expected interface contract.
+ *
+ * @example
+ * ```typescript
+ * const noopRequest: NoopPreparedChainRequest = {
+ *   type: 'noop',
+ *   estimate: async () => ({ gasLimit: 0n, gasPrice: 0n, totalFee: 0n }),
+ *   execute: async () => '0x0000000000000000000000000000000000000000000000000000000000000000'
+ * }
+ * ```
+ */
+interface NoopPreparedChainRequest {
+    /** The type of the prepared request. */
+    type: 'noop';
+    /**
+     * Placeholder for the estimate method.
+     * @returns The estimated gas cost.
+     */
+    estimate: () => Promise<EstimatedGas>;
+    /**
+     * Placeholder for the execute method.
+     * @returns The transaction hash.
+     */
+    execute: () => Promise<string>;
+}
+/**
+ * Union type for all supported contract execution parameters.
+ * Currently only supports EVM chains, but can be extended for other chains.
+ */
+type PreparedChainRequestParams = EvmPreparedChainRequestParams | SolanaPreparedChainRequestParams;
+/**
+ * Response from waiting for a transaction to be mined and confirmed on the blockchain.
+ *
+ * @interface WaitForTransactionResponse
+ */
+interface WaitForTransactionResponse {
+    /**
+     * The transaction hash identifier.
+     * @example "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
+     */
+    txHash: string;
+    /**
+     * The final status of the transaction execution.
+     * Indicates whether the transaction was successfully executed or reverted.
+     * @example "success", "reverted"
+     */
+    status: 'success' | 'reverted';
+    /**
+     * The total amount of gas used by all transactions in the block up to and including this transaction.
+     * Represents the cumulative gas consumption within the block.
+     * @example 2100000n
+     */
+    cumulativeGasUsed?: bigint;
+    /**
+     * The amount of gas actually consumed by this specific transaction.
+     * This value is always less than or equal to the gas limit set for the transaction.
+     * @example 21000n
+     */
+    gasUsed?: bigint;
+    /**
+     * The block number where the transaction was mined.
+     * Represents the sequential position of the block in the blockchain.
+     * @example 18500000n
+     */
+    blockNumber?: bigint;
+    /**
+     * The hash of the block containing this transaction.
+     * Provides a unique identifier for the block where the transaction was included.
+     * @example "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
+     */
+    blockHash?: string;
+    /**
+     * The zero-based index position of the transaction within the block.
+     * Indicates the order in which this transaction appears in the block.
+     * @example 5
+     */
+    transactionIndex?: number;
+    /**
+     * The actual gas price paid per unit of gas for this transaction.
+     * For EIP-1559 transactions, this reflects the base fee plus priority fee.
+     * @example 15000000000n // 15 Gwei
+     */
+    effectiveGasPrice?: bigint;
+}
+interface WaitForTransactionConfig {
+    /**
+     * The timeout for the transaction to be mined and confirmed on the blockchain.
+     * @example 10000
+     */
+    timeout?: number | undefined;
+    /**
+     * The number of confirmations to wait for the transaction to be mined and confirmed on the blockchain.
+     * @example 1
+     */
+    confirmations?: number;
+    /**
+     * The maximum supported transaction version for getTransaction.
+     * Defaults to 0 if not provided.
+     * @example 0
+     */
+    maxSupportedTransactionVersion?: number;
+}
+
+/**
+ * Base interface for all action parameter objects.
+ *
+ * Provide a compile-time marker to explicitly identify objects that represent
+ * action parameters (leaf nodes) versus namespace containers that should be
+ * traversed during type recursion.
+ *
+ * @remarks
+ * This marker property exists only at the type level and is stripped away
+ * during compilation. It serves as a deterministic way to identify action
+ * parameter objects without relying on property name heuristics.
+ *
+ * All action parameter objects must extend this interface to be properly
+ * recognized by the recursive utility types in the action system.
+ */
+interface ActionParameters {
+    /**
+     * Compile-time marker identifying this as an action parameter object.
+     *
+     * This property is used by the type system to distinguish between
+     * namespace containers and action parameter definitions. It does not
+     * exist at runtime and is purely for TypeScript's type checking.
+     */
+    readonly __isActionParams: true;
+}
+
+/**
+ * EIP-2612 permit signature parameters for gasless token approvals.
+ *
+ * Contains the signature components and deadline required for permit-based
+ * token spending authorization without requiring separate approval transactions.
+ *
+ * @example
+ * ```typescript
+ * const permitParams: PermitParams = {
+ *   deadline: BigInt(Math.floor(Date.now() / 1000) + 3600), // 1 hour from now
+ *   v: 27,
+ *   r: '0x1234567890abcdef...',
+ *   s: '0xfedcba0987654321...'
+ * }
+ * ```
+ */
+interface PermitParams {
+    /**
+     * Permit expiration timestamp (Unix timestamp in seconds).
+     *
+     * The permit signature becomes invalid after this timestamp.
+     * Must be greater than the current block timestamp.
+     */
+    deadline: bigint;
+    /**
+     * Recovery parameter of the ECDSA signature (27 or 28).
+     *
+     * Used to recover the public key from the signature components.
+     */
+    v: number;
+    /**
+     * R component of the ECDSA signature.
+     *
+     * First 32 bytes of the signature as a hex string.
+     */
+    r: string;
+    /**
+     * S component of the ECDSA signature.
+     *
+     * Second 32 bytes of the signature as a hex string.
+     */
+    s: string;
+}
+/**
+ * Action map for Circle's Cross-Chain Transfer Protocol (CCTP) version 2 operations.
+ *
+ * Define the parameter schemas for CCTP v2 actions that enable native USDC
+ * transfers between supported blockchain networks. Use Circle's attestation
+ * service to verify and complete cross-chain transactions with cryptographic
+ * proof of burn and mint operations.
+ *
+ * @remarks
+ * CCTP v2 represents Circle's native cross-chain transfer protocol that allows
+ * USDC to move between chains without traditional lock-and-mint bridging.
+ * Instead, USDC is burned on the source chain and minted natively on the
+ * destination chain using cryptographic attestations.
+ *
+ * The protocol supports both "slow" (free) and "fast" (fee-based) transfer
+ * modes, with configurable finality thresholds and destination execution
+ * parameters for advanced use cases.
+ *
+ * @example
+ * ```typescript
+ * import type { CCTPv2ActionMap } from '@core/adapter/actions/cctp/v2'
+ * import { mainnet, polygon } from '@core/chains'
+ *
+ * // Deposit and burn USDC for cross-chain transfer
+ * const burnParams: CCTPv2ActionMap['depositForBurn'] = {
+ *   amount: '1000000', // 1 USDC (6 decimals)
+ *   mintRecipient: '0x742d35Cc6634C0532925a3b8D8E5e8d8D8e5e8d8D8e5e8',
+ *   maxFee: '1000', // 0.001 USDC fast fee
+ *   minFinalityThreshold: 65,
+ *   fromChain: mainnet,
+ *   toChain: polygon
+ * }
+ *
+ * // Receive and mint USDC on destination chain
+ * const receiveParams: CCTPv2ActionMap['receiveMessage'] = {
+ *   eventNonce: '0x123abc...',
+ *   attestation: '0xdef456...',
+ *   message: '0x789012...',
+ *   fromChain: mainnet,
+ *   toChain: polygon
+ * }
+ * ```
+ *
+ * @see {@link ChainDefinitionWithCCTPv2} for supported chain definitions
+ */
+interface CCTPv2ActionMap {
+    /**
+     * Initiate a cross-chain USDC transfer by depositing and burning tokens on the source chain.
+     *
+     * Burn USDC tokens on the source chain and generate a message for attestation
+     * by Circle's infrastructure. The burned tokens will be minted on the destination
+     * chain once the attestation is obtained and the receive message is executed.
+     *
+     * @remarks
+     * This action represents the first step in a CCTP cross-chain transfer. After
+     * execution, you must wait for Circle's attestation service to observe the burn
+     * event and provide a cryptographic attestation that can be used to mint the
+     * equivalent amount on the destination chain.
+     *
+     * The `maxFee` parameter enables fast transfers through Circle's fast liquidity
+     * network, where liquidity providers can fulfill transfers immediately in exchange
+     * for a fee. Set to "0" for slower, free transfers that wait for full finality.
+     */
+    depositForBurn: ActionParameters & {
+        /**
+         * Amount of USDC to deposit and burn (in token's smallest unit).
+         *
+         * Specify the amount in the token's atomic units (e.g., for USDC with
+         * 6 decimals, "1000000" represents 1 USDC). This amount will be burned
+         * on the source chain and minted on the destination chain.
+         */
+        amount: bigint;
+        /**
+         * Address of the recipient who will receive minted tokens on the destination chain.
+         *
+         * Provide the destination address as a 32-byte hex string (bytes32 format).
+         */
+        mintRecipient: string;
+        /**
+         * Address authorized to call receiveMessage on the destination chain.
+         *
+         * Restrict who can execute the final minting step on the destination chain.
+         * If not specified or set to bytes32(0), any address can call receiveMessage.
+         * Use this for advanced integrations requiring specific execution control.
+         *
+         * @defaultValue bytes32(0) - allows any address to complete the transfer
+         */
+        destinationCaller?: string;
+        /**
+         * Maximum fee to pay for fast transfer fulfillment.
+         *
+         * Specify the maximum amount (in the same units as `amount`) you're willing
+         * to pay for immediate liquidity. Set to "0" for free transfers that wait
+         * for full chain finality. Higher fees increase the likelihood of fast
+         * fulfillment.
+         */
+        maxFee: bigint;
+        /**
+         * Minimum finality threshold for attestation eligibility.
+         *
+         * Set the number of confirmations required before Circle's attestation
+         * service will observe and attest to the burn event. Higher values
+         * provide stronger finality guarantees but increase transfer time.
+         * Typical values: 1000 for fast transfers, 2000 for maximum security.
+         */
+        minFinalityThreshold: number;
+        /**
+         * Source chain definition where tokens will be burned.
+         */
+        fromChain: ChainDefinitionWithCCTPv2;
+        /**
+         * Destination chain definition where tokens will be minted.
+         */
+        toChain: ChainDefinitionWithCCTPv2;
+    };
+    /**
+     * Complete a cross-chain transfer by receiving and processing an attested message.
+     *
+     * Execute the final step of a CCTP transfer by submitting Circle's attestation
+     * and the original message to mint USDC tokens on the destination chain.
+     * This action consumes the attestation and delivers tokens to the specified
+     * recipient from the original burn operation.
+     *
+     * @remarks
+     * This action must be called after obtaining a valid attestation from Circle's
+     * API for a corresponding `depositForBurn` operation. The attestation proves
+     * that tokens were burned on the source chain and authorizes minting the
+     * equivalent amount on the destination chain.
+     *
+     * The message parameter contains the original burn message data, while the
+     * attestation provides the cryptographic proof. Both must match exactly
+     * with Circle's records for the transaction to succeed.
+     */
+    receiveMessage: ActionParameters & {
+        /**
+         * Unique nonce identifying the specific burn event.
+         *
+         * Provide the event nonce from the MessageSent event emitted by the
+         * depositForBurn transaction. This must be a 0x-prefixed 64-character
+         * hex string representing the 32-byte nonce value.
+         */
+        readonly eventNonce: string;
+        /**
+         * Cryptographic attestation from Circle's infrastructure.
+         *
+         * Submit the attestation obtained from Circle's API that proves the
+         * corresponding burn event occurred and was observed. This must be
+         * a valid 0x-prefixed hex string containing Circle's signature data.
+         */
+        readonly attestation: string;
+        /**
+         * Original message bytes from the source chain burn event.
+         *
+         * Provide the raw message data emitted in the MessageSent event from
+         * the depositForBurn transaction. This 0x-prefixed hex string contains
+         * the encoded transfer details that will be verified against the attestation.
+         */
+        readonly message: string;
+        /**
+         * Source chain definition where the original burn occurred.
+         */
+        readonly fromChain: ChainDefinitionWithCCTPv2;
+        /**
+         * Destination chain definition where tokens will be minted.
+         */
+        readonly toChain: ChainDefinitionWithCCTPv2;
+    };
+    /**
+     * Initiate a cross-chain USDC transfer using a custom bridge contract with preapproval funnel.
+     *
+     * This action combines token approval and burning into a single transaction using
+     * a custom bridge contract that supports preapproval functionality. It provides
+     * enhanced gas efficiency by eliminating separate approval transactions while
+     * maintaining the same developer interface as standard CCTP transfers.
+     *
+     * @remarks
+     * This action is only available on chains that support custom bridge contracts,
+     * as determined by `hasCustomContractSupport(chain, 'bridge')`. The custom bridge
+     * handles token approval internally and supports advanced features like protocol
+     * fees and custom routing logic.
+     *
+     * For basic use cases, this provides the same interface as `depositForBurn`.
+     * For advanced use cases, optional protocol fee parameters enable custom fee
+     * collection and revenue sharing models.
+     *
+     * @example
+     * ```typescript
+     * // Basic usage (same as depositForBurn)
+     * await adapter.action('cctp.v2.customBurn', {
+     *   amount: BigInt('1000000'),
+     *   mintRecipient: '0x...',
+     *   maxFee: BigInt('1000'),
+     *   minFinalityThreshold: 65
+     * })
+     *
+     * // Advanced usage with protocol fees
+     * await adapter.action('cctp.v2.customBurn', {
+     *   amount: BigInt('1000000'),
+     *   mintRecipient: '0x...',
+     *   maxFee: BigInt('1000'),
+     *   minFinalityThreshold: 65,
+     *   protocolFee: BigInt('100'),
+     *   feeRecipient: '0xFeeRecipientAddress'
+     * })
+     * ```
+     */
+    customBurn: ActionParameters & {
+        /**
+         * Amount of USDC to burn (in token's smallest unit).
+         *
+         * Specify the amount in the token's atomic units (e.g., for USDC with
+         * 6 decimals, 1000000n represents 1 USDC). This amount will be burned
+         * on the source chain and minted on the destination chain.
+         */
+        amount: bigint;
+        /**
+         * Address of the recipient who will receive minted tokens on the destination chain.
+         *
+         * Provide the destination address as a 32-byte hex string (bytes32 format).
+         */
+        mintRecipient: string;
+        /**
+         * Address authorized to call receiveMessage on the destination chain.
+         *
+         * Restrict who can execute the final minting step on the destination chain.
+         * If not specified or set to bytes32(0), any address can call receiveMessage.
+         * Use this for advanced integrations requiring specific execution control.
+         *
+         * @defaultValue bytes32(0) - allows any address to complete the transfer
+         */
+        destinationCaller?: string;
+        /**
+         * Maximum fee to pay for fast transfer fulfillment.
+         *
+         * Specify the maximum amount (in the same units as `amount`) you're willing
+         * to pay for immediate liquidity. Set to "0" for free transfers that wait
+         * for full chain finality. Higher fees increase the likelihood of fast
+         * fulfillment.
+         */
+        maxFee: bigint;
+        /**
+         * Minimum finality threshold for attestation eligibility.
+         *
+         * Set the number of confirmations required before Circle's attestation
+         * service will observe and attest to the burn event. Higher values
+         * provide stronger finality guarantees but increase transfer time.
+         * Typical values: 65 for standard transfers, 2000 for maximum security.
+         */
+        minFinalityThreshold: number;
+        /**
+         * Protocol fee amount (in token's smallest unit).
+         *
+         * Additional fee charged by the custom bridge for enhanced functionality.
+         * This fee is separate from the Circle fast transfer fee and is paid to
+         * the specified fee recipient. Enables custom fee collection and revenue
+         * sharing models for bridge operators.
+         *
+         * @defaultValue 0n - no protocol fee for basic usage
+         */
+        protocolFee?: bigint;
+        /**
+         * Address to receive the protocol fee.
+         *
+         * Wallet address where the protocol fee will be sent. This enables
+         * custom fee collection and revenue sharing models for bridge operators.
+         * Only relevant when protocolFee is greater than 0.
+         *
+         * @defaultValue bridge contract address - safe fallback for zero fees
+         */
+        feeRecipient?: string;
+        /**
+         * Source chain definition where tokens will be burned.
+         */
+        fromChain: ChainDefinitionWithCCTPv2;
+        /**
+         * Destination chain definition where tokens will be minted.
+         */
+        toChain: ChainDefinitionWithCCTPv2;
+        /**
+         * Permit parameters for the custom bridge contract.
+         */
+        permitParams?: PermitParams;
+    };
+}
+
+/**
+ * Central registry for Cross-Chain Transfer Protocol (CCTP) action namespaces.
+ *
+ * Define versioned action maps for CCTP operations across different protocol
+ * versions. Each version key represents a specific CCTP implementation with
+ * its own parameter schemas and operational requirements.
+ *
+ * @remarks
+ * CCTP actions enable cross-chain USDC transfers through Circle's native
+ * bridging protocol. Each version namespace contains actions specific to
+ * that protocol iteration, allowing for protocol upgrades while maintaining
+ * backward compatibility in the action system.
+ *
+ * This interface follows the same pattern as other action namespaces but
+ * is organized by protocol version rather than token type.
+ *
+ * @see {@link CCTPv2ActionMap} for version 2 action definitions
+ */
+interface CCTPActionMap {
+    /** CCTP version 2 operations for cross-chain USDC transfers. */
+    readonly v2: CCTPv2ActionMap;
+}
+
+interface TokenActionMap {
+    /**
+     * Set an allowance for a delegate to spend tokens on behalf of the wallet.
+     *
+     * On chains without native allowance support, this may return a noop result
+     * indicating the step can be safely skipped.
+     */
+    approve: ActionParameters & {
+        /**
+         * The contract address of the token.
+         */
+        tokenAddress: string;
+        /**
+         * The address that will be approved to spend the tokens.
+         */
+        delegate: string;
+        /**
+         * The amount of tokens to approve for spending (in token's smallest unit).
+         */
+        amount: bigint;
+    };
+    /**
+     * Check the current allowance between an owner and spender for any token.
+     *
+     * On chains without allowance support, this typically returns the maximum
+     * possible value to indicate unlimited spending capability.
+     */
+    allowance: ActionParameters & {
+        /**
+         * The contract address of the token.
+         */
+        tokenAddress: string;
+        /**
+         * The address of the wallet that owns the tokens. If not provided, it will be
+         * automatically derived from the adapter context.
+         */
+        walletAddress?: string | undefined;
+        /**
+         * The address to check the allowance for.
+         */
+        delegate: string;
+    };
+    /**
+     * Transfer tokens directly from the wallet to another address.
+     */
+    transfer: ActionParameters & {
+        /**
+         * The contract address of the token.
+         */
+        tokenAddress: string;
+        /**
+         * The address to send the tokens to.
+         */
+        to: string;
+        /**
+         * The amount of tokens to transfer (in token's smallest unit).
+         */
+        amount: bigint;
+    };
+    /**
+     * Transfer tokens from one address to another using a pre-approved allowance.
+     *
+     * On chains without allowance support, this may behave differently or throw
+     * an error if the operation is not supported.
+     */
+    transferFrom: ActionParameters & {
+        /**
+         * The contract address of the token.
+         */
+        tokenAddress: string;
+        /**
+         * The address to transfer tokens from (must have given allowance to the caller).
+         */
+        from: string;
+        /**
+         * The address to send the tokens to.
+         */
+        to: string;
+        /**
+         * The amount of tokens to transfer (in token's smallest unit).
+         */
+        amount: bigint;
+    };
+    /**
+     * Get the current token balance for a wallet address.
+     */
+    balanceOf: ActionParameters & {
+        /**
+         * The contract address of the token.
+         */
+        tokenAddress: string;
+        /**
+         * The address to check the balance for. If not provided, it will be
+         * automatically derived from the adapter context.
+         */
+        walletAddress?: string | undefined;
+    };
+}
+
+/**
+ * USDC-specific operations that automatically resolve the token address.
+ *
+ * These include all standard ERC20 operations plus additional safety functions
+ * that USDC supports. The interface provides the same core operations as
+ * {@link TokenActionMap} but without requiring a `tokenAddress` parameter,
+ * plus additional USDC-specific extensions.
+ *
+ * @example
+ * ```typescript
+ * // USDC operations (address auto-resolved)
+ * await adapter.action('usdc.approve', {
+ *   delegate: '0x1234...',
+ *   amount: '1000000' // 1 USDC
+ * })
+ *
+ * // USDC-specific safe allowance functions
+ * await adapter.action('usdc.increaseAllowance', {
+ *   delegate: '0x1234...',
+ *   amount: '500000' // increase by 0.5 USDC
+ * })
+ *
+ * // vs. general token operations (address required)
+ * await adapter.action('token.approve', {
+ *   tokenAddress: '0xA0b86a33E6441c8C1c7C16e4c5e3e5b5e4c5e3e5b5e4c5e',
+ *   delegate: '0x1234...',
+ *   amount: '1000000'
+ * })
+ * ```
+ */
+type BaseUSDCActions = {
+    [K in keyof TokenActionMap]: Omit<TokenActionMap[K], 'tokenAddress'>;
+};
+/**
+ * USDC action map with both standard ERC20 operations and USDC-specific extensions.
+ *
+ * This provides all standard token operations plus additional safety functions
+ * that USDC implements beyond the base ERC20 standard.
+ */
+interface USDCActionMap {
+    /**
+     * Set an allowance for a delegate to spend USDC tokens on behalf of the wallet.
+     *
+     * Automatically uses the USDC contract address for the current chain.
+     * On chains without native allowance support, this may return a noop result.
+     */
+    approve: BaseUSDCActions['approve'];
+    /**
+     * Check the current allowance between an owner and spender for USDC tokens.
+     *
+     * Automatically uses the USDC contract address for the current chain.
+     * This is a read-only operation.
+     */
+    allowance: BaseUSDCActions['allowance'];
+    /**
+     * Safely increase the allowance for a delegate to spend USDC tokens.
+     *
+     * This is a USDC-specific function that provides safer allowance management
+     * compared to direct approve() calls. Automatically uses the USDC contract
+     * address for the current chain.
+     */
+    increaseAllowance: ActionParameters & {
+        /**
+         * The address that will have their allowance increased.
+         */
+        delegate: string;
+        /**
+         * The amount to increase the allowance by (in USDC's smallest unit).
+         */
+        amount: bigint;
+        /**
+         * The chain definition for the current chain.
+         */
+        chain?: ChainDefinition;
+    };
+    /**
+     * Safely decrease the allowance for a delegate to spend USDC tokens.
+     *
+     * This is a USDC-specific function that provides safer allowance management.
+     * Automatically uses the USDC contract address for the current chain.
+     */
+    decreaseAllowance: ActionParameters & {
+        /**
+         * The address that will have their allowance decreased.
+         */
+        delegate: string;
+        /**
+         * The amount to decrease the allowance by (in USDC's smallest unit).
+         */
+        amount: bigint;
+    };
+    /**
+     * Transfer USDC tokens directly from the wallet to another address.
+     *
+     * Automatically uses the USDC contract address for the current chain.
+     */
+    transfer: BaseUSDCActions['transfer'];
+    /**
+     * Transfer USDC tokens from one address to another using a pre-approved allowance.
+     *
+     * Automatically uses the USDC contract address for the current chain.
+     * The caller must have sufficient allowance from the 'from' address.
+     */
+    transferFrom: BaseUSDCActions['transferFrom'];
+    /**
+     * Get the current USDC balance for a wallet address.
+     *
+     * Automatically uses the USDC contract address for the current chain.
+     * This is a read-only operation.
+     */
+    balanceOf: Omit<BaseUSDCActions['balanceOf'], 'tokenAddress'>;
+}
+
+/**
+ * Central registry of all available action namespaces and their operations.
+ *
+ * Define the complete action map structure used throughout the bridging kit.
+ * Each top-level key represents a namespace (e.g., 'token', 'usdc') containing
+ * related operations. The structure supports arbitrary nesting depth through
+ * the recursive utility types provided in this module.
+ *
+ * @remarks
+ * This interface serves as the foundation for type-safe action dispatching
+ * and provides compile-time validation of action keys and payload types.
+ * All action-related utility types derive from this central definition.
+ *
+ * @see {@link ActionKeys} for dot-notation action paths
+ * @see {@link ActionPayload} for extracting payload types
+ */
+interface ActionMap {
+    /** CCTP-specific operations with automatic address resolution. */
+    readonly cctp: CCTPActionMap;
+    /** General token operations requiring explicit token addresses. */
+    readonly token: TokenActionMap;
+    /** USDC-specific operations with automatic address resolution. */
+    readonly usdc: USDCActionMap;
+}
+/**
+ * Determine if a type represents an action parameter object (leaf node).
+ *
+ * Check whether a type extends the ActionParameters interface, which provides
+ * an explicit marker for identifying action parameter objects versus namespace
+ * containers that should be traversed during type recursion.
+ *
+ * @typeParam T - The type to examine for parameter object characteristics
+ *
+ * @remarks
+ * This utility type provides deterministic leaf detection for the recursive
+ * type system. By requiring all action parameter objects to extend the
+ * ActionParameters interface, we eliminate the need for property name
+ * heuristics and make the system more maintainable.
+ *
+ * @see {@link ActionParameters} for the base interface
+ * @see {@link NestedKeys} for usage in path extraction
+ */
+type IsActionParameterObject<T> = T extends ActionParameters ? true : false;
+/**
+ * Recursively extract all nested keys from an object type as dot-notation string literals.
+ *
+ * Traverse object structures of arbitrary depth and generate string literal
+ * types representing all possible paths through the structure using dot
+ * notation. Stop recursion when encountering action parameter objects (leaves).
+ *
+ * @typeParam T - The object type to extract nested keys from
+ *
+ * @remarks
+ * This type is the foundation for generating type-safe action paths in
+ * dot notation. It automatically adapts to changes in the ActionMap
+ * structure and supports unlimited nesting depth for future extensibility.
+ *
+ * The recursion stops when it encounters objects that match the
+ * {@link IsActionParameterObject} criteria, ensuring that only valid
+ * action paths are generated.
+ *
+ * @see {@link ActionKeys} for ActionMap-specific paths
+ * @see {@link NestedValue} for extracting types at specific paths
+ * @see {@link IsActionParameterObject} for leaf detection logic
+ */
+type NestedKeys<T> = {
+    [K in Extract<keyof T, string>]: IsActionParameterObject<T[K]> extends true ? K : T[K] extends object ? `${K}.${NestedKeys<T[K]>}` : never;
+}[Extract<keyof T, string>];
+/**
+ * Recursively extract the value type at a given dot-notation path.
+ *
+ * Navigate through nested object types using a dot-notation string path
+ * and return the type of the value at that location. Parse the path
+ * recursively by splitting on dots and traversing the object structure.
+ *
+ * @typeParam T - The object type to navigate through
+ * @typeParam K - The dot-notation path as a string literal type
+ *
+ * @remarks
+ * This utility type enables type-safe access to deeply nested object
+ * properties using dot notation paths. It forms the foundation for
+ * extracting payload types from action paths in the ActionMap.
+ *
+ * @see {@link ActionPayload} for ActionMap-specific value extraction
+ * @see {@link NestedKeys} for generating valid path types
+ */
+type NestedValue<T, K extends string> = K extends `${infer First}.${infer Rest}` ? First extends keyof T ? NestedValue<T[First], Rest> : never : K extends keyof T ? T[K] : never;
+/**
+ * Union type of all nested action keys in dot notation.
+ *
+ * Generate string literal types for all possible action paths in the
+ * ActionMap structure. Automatically adapt to changes in the ActionMap
+ * and support arbitrary levels of nesting for future extensibility.
+ *
+ * @remarks
+ * This type serves as the canonical source for all valid action identifiers
+ * in the bridging kit. It ensures compile-time validation of action keys
+ * and enables type-safe action dispatching throughout the application.
+ *
+ * @see {@link ActionPayload} for extracting parameter types
+ * @see {@link NamespaceActions} for namespace-specific actions
+ * @see {@link ActionMap} for the underlying structure
+ */
+type ActionKeys = NestedKeys<ActionMap>;
+/**
+ * Extract the payload type for a specific action based on its dot-notation key.
+ *
+ * Resolve the parameter type for any action by providing its complete path
+ * in dot notation. Leverage the recursive NestedValue type to navigate to
+ * the correct payload type regardless of nesting depth. The internal
+ * ActionParameters marker is automatically removed from the result.
+ *
+ * @typeParam T - The action key in dot notation (must extend ActionKeys)
+ *
+ * @remarks
+ * This utility type enables type-safe parameter passing for action
+ * dispatching. It automatically infers the correct parameter shape
+ * based on the action key, providing compile-time validation and
+ * excellent IntelliSense support.
+ *
+ * The internal `__isActionParams` marker used for type system recursion
+ * is automatically omitted from the resulting type, providing clean
+ * parameter objects for consumers.
+ *
+ * @see {@link ActionKeys} for available action identifiers
+ * @see {@link NestedValue} for the underlying path resolution logic
+ */
+type ActionPayload<T extends ActionKeys> = Omit<NestedValue<ActionMap, T>, '__isActionParams'>;
+
+/**
+ * Type-safe action handler function signature for specific action types.
+ *
+ * Defines the contract for functions that process action payloads and return
+ * prepared chain requests. Each handler is strongly typed to accept only the
+ * payload structure corresponding to its specific action key.
+ *
+ * @typeParam TActionKey - The specific action key this handler processes.
+ * @param params - The action payload matching the specified action key.
+ * @returns A promise resolving to a prepared chain request.
+ *
+ * @example
+ * ```typescript
+ * import type { ActionHandler } from '@core/adapter'
+ *
+ * const depositHandler: ActionHandler<'cctp.v2.depositForBurn'> = async (params) => {
+ *   // Handler logic here
+ * }
+ * ```
+ */
+type ActionHandler<TActionKey extends ActionKeys> = (params: ActionPayload<TActionKey>) => Promise<PreparedChainRequest>;
+/**
+ * Type-safe mapping of all available action keys to their corresponding handlers.
+ *
+ * This type defines a registry object where each key is a valid action key
+ * (as defined by {@link ActionKeys}) and each value is an {@link ActionHandler}
+ * capable of processing the payload for that action. This enables strongly-typed
+ * handler registration and lookup for all supported actions in the Stablecoin Kits.
+ *
+ * @remarks
+ * Each handler is typed as {@link ActionHandler<ActionKeys>}, which means the handler
+ * must accept the payload type for the specific action key it is registered under.
+ * This provides type safety for handler registration and execution, but does not
+ * enforce per-key handler parameterization at the type level. For stricter per-key
+ * typing, consider using mapped types or generic registry patterns.
+ *
+ * @example
+ * ```typescript
+ * import type { ActionHandlers } from '@core/adapter'
+ * import type { ActionHandler } from '@core/adapter'
+ *
+ * const handlers: ActionHandlers = {
+ *   'cctp.v2.depositForBurn': async (params) => {
+ *     // params is correctly typed for 'cctp.v2.depositForBurn'
+ *     // ...handler logic...
+ *   },
+ *   'usdc.approve': async (params) => {
+ *     // params is correctly typed for 'usdc.approve'
+ *     // ...handler logic...
+ *   }
+ * }
+ * ```
+ */
+type ActionHandlers = {
+    [K in ActionKeys]?: ActionHandler<K>;
+};
+/**
+ * Type-safe registry for managing and executing blockchain action handlers.
+ *
+ * Provides a centralized system for registering action handlers with full
+ * TypeScript type safety, ensuring that handlers can only be registered
+ * with compatible action keys and payload types. Supports both individual
+ * handler registration and batch registration operations.
+ *
+ * @remarks
+ * The registry uses a Map internally for O(1) lookups and maintains type
+ * safety through generic constraints and careful type assertions. All
+ * type assertions are validated at registration time to ensure runtime
+ * type safety matches compile-time guarantees.
+ */
+declare class ActionRegistry {
+    readonly actionHandlers: Map<ActionKeys, ActionHandler<ActionKeys>>;
+    /**
+     * Register a type-safe action handler for a specific action key.
+     *
+     * Associates an action handler function with its corresponding action key,
+     * ensuring compile-time type safety between the action and its expected
+     * payload structure. The handler will be available for execution via
+     * {@link executeAction}.
+     *
+     * @typeParam TActionKey - The specific action key being registered.
+     * @param action - The action key to register the handler for.
+     * @param handler - The handler function for processing this action type.
+     * @returns Void.
+     *
+     * @throws {Error} When action parameter is not a valid string.
+     * @throws {TypeError} When handler parameter is not a function.
+     *
+     * @example
+     * ```typescript
+     * import { ActionRegistry } from '@core/adapter'
+     * import type { ActionHandler } from '@core/adapter'
+     *
+     * const registry = new ActionRegistry()
+     *
+     * // Register a CCTP deposit handler
+     * const depositHandler: ActionHandler<'cctp.v2.depositForBurn'> = async (params) => {
+     *   console.log('Processing deposit:', params.amount)
+     *   return {
+     *     chainId: params.chainId,
+     *     data: '0x...',
+     *     to: '0x...',
+     *     value: '0'
+     *   }
+     * }
+     *
+     * registry.registerHandler('cctp.v2.depositForBurn', depositHandler)
+     * ```
+     */
+    registerHandler<TActionKey extends ActionKeys>(action: TActionKey, handler: ActionHandler<TActionKey>): void;
+    /**
+     * Register multiple action handlers in a single operation.
+     *
+     * Efficiently register multiple handlers from a record object, where keys
+     * are action identifiers and values are their corresponding handler
+     * functions. Provides a convenient way to bulk-register handlers while
+     * maintaining type safety.
+     *
+     * @param handlers - A record mapping action keys to their handler functions.
+     * @returns Void.
+     *
+     * @throws {Error} When handlers parameter is not a valid object.
+     * @throws {Error} When any individual handler registration fails.
+     *
+     * @example
+     * ```typescript
+     * import { ActionRegistry } from '@core/adapter'
+     * import type { ActionHandler, ActionHandlers } from '@core/adapter'
+     *
+     * const registry = new ActionRegistry()
+     *
+     * // Register multiple handlers at once
+     * const tokenHandlers: ActionHandlers = {
+     *   'token.approve': async (params) => ({
+     *     chainId: params.chainId,
+     *     data: '0x095ea7b3...',
+     *     to: params.tokenAddress,
+     *     value: '0'
+     *   }),
+     *   'token.transfer': async (params) => ({
+     *     chainId: params.chainId,
+     *     data: '0xa9059cbb...',
+     *     to: params.tokenAddress,
+     *     value: '0'
+     *   })
+     * }
+     *
+     * registry.registerHandlers(tokenHandlers)
+     * console.log('Registered multiple token handlers')
+     * ```
+     */
+    registerHandlers(handlers: ActionHandlers): void;
+    /**
+     * Check whether a specific action is supported by this registry.
+     *
+     * Determine if a handler has been registered for the given action key.
+     * Use this method to conditionally execute actions or provide appropriate
+     * error messages when actions are not available.
+     *
+     * @param action - The action key to check for support.
+     * @returns True if the action is supported, false otherwise.
+     *
+     * @throws {Error} When action parameter is not a valid string.
+     *
+     * @example
+     * ```typescript
+     * import { ActionRegistry } from '@core/adapter'
+     *
+     * const registry = new ActionRegistry()
+     *
+     * // Check if actions are supported before attempting to use them
+     * if (registry.supportsAction('token.approve')) {
+     *   console.log('Token approval is supported')
+     * } else {
+     *   console.log('Token approval not available')
+     * }
+     *
+     * // Conditional logic based on support
+     * const action = 'cctp.v2.depositForBurn'
+     * if (registry.supportsAction(action)) {
+     *   // Safe to execute
+     *   console.log(`${action} is available`)
+     * } else {
+     *   console.warn(`${action} is not registered`)
+     * }
+     * ```
+     */
+    supportsAction(action: ActionKeys): boolean;
+    /**
+     * Execute a registered action handler with type-safe parameters.
+     *
+     * Look up and execute the handler associated with the given action key,
+     * passing the provided parameters and returning the resulting prepared
+     * chain request. TypeScript ensures the parameters match the expected
+     * structure for the specified action.
+     *
+     * @typeParam TActionKey - The specific action key being executed.
+     * @param action - The action key identifying which handler to execute.
+     * @param params - The parameters to pass to the action handler.
+     * @returns A promise resolving to the prepared chain request.
+     *
+     * @throws {Error} When action parameter is not a valid string.
+     * @throws {Error} When no handler is registered for the specified action.
+     * @throws {Error} When the handler execution fails.
+     *
+     * @example
+     * ```typescript
+     * import { ActionRegistry } from '@core/adapter'
+     * import type { ChainEnum } from '@core/chains'
+     *
+     * const registry = new ActionRegistry()
+     *
+     * // First register a handler
+     * registry.registerHandler('token.approve', async (params) => ({
+     *   chainId: params.chainId,
+     *   data: '0x095ea7b3...',
+     *   to: params.tokenAddress,
+     *   value: '0'
+     * }))
+     *
+     * // Execute the action with type-safe parameters
+     * const result = await registry.executeAction('token.approve', {
+     *   chainId: ChainEnum.Ethereum,
+     *   tokenAddress: '0xA0b86a33E6441c8C1c7C16e4c5e3e5b5e4c5e3e5b5e4c5e',
+     *   delegate: '0x1234567890123456789012345678901234567890',
+     *   amount: '1000000'
+     * })
+     *
+     * console.log('Transaction prepared:', result.data)
+     * ```
+     */
+    executeAction<TActionKey extends ActionKeys>(action: TActionKey, params: ActionPayload<TActionKey>): Promise<PreparedChainRequest>;
+}
+
+/**
+ * Defines the capabilities of an adapter, including address handling patterns and supported chains.
+ *
+ * @interface AdapterCapabilities
+ * @category Types
+ * @description
+ * This interface helps determine the behavior of an adapter, especially how it handles
+ * address resolution and chain operations. Different adapter types have different
+ * requirements for explicit context in operations.
+ *
+ * @example
+ * ```typescript
+ * // Single address adapter (private key)
+ * const capabilities: AdapterCapabilities = {
+ *   addressContext: 'single',
+ *   supportedChains: [Ethereum, Base, Polygon],
+ *   availableAddresses: ['0x123...']
+ * }
+ *
+ * // Multi-entity adapter (institutional)
+ * const capabilities: AdapterCapabilities = {
+ *   addressContext: 'multi-entity',
+ *   supportedChains: [Ethereum, Base, Solana],
+ *   availableAddresses: undefined // Too many to fetch
+ * }
+ * ```
+ */
+interface AdapterCapabilities {
+    /**
+     * Defines how the adapter handles addresses.
+     *
+     * - `'single'`: Adapter controls exactly one address (e.g., private key adapter)
+     * - `'user-accounts'`: Adapter controls user's personal addresses (e.g., MetaMask)
+     * - `'multi-entity'`: Adapter manages addresses for multiple entities (e.g., Circle Wallets)
+     */
+    addressContext: 'single' | 'user-accounts' | 'multi-entity';
+    /**
+     * List of blockchain networks that this adapter can interact with.
+     * Used for validation and capability discovery.
+     */
+    supportedChains: ChainDefinition[];
+    /**
+     * Available addresses for single and user-accounts adapters.
+     *
+     * - For `single` adapters: Contains exactly one address
+     * - For `user-accounts` adapters: Contains user's available addresses
+     * - For `multi-entity` adapters: Should be undefined (too many addresses to list)
+     *
+     * This is populated during adapter creation to avoid repeated network calls.
+     */
+    availableAddresses?: string[];
+}
+/**
+ * Abstract class defining the standard interface for an adapter that interacts with a specific blockchain.
+ *
+ * A `Adapter` is responsible for encapsulating chain-specific logic necessary to
+ * perform operations like sending transactions, querying balances, or interacting with smart contracts.
+ * Implementations of this class will provide concrete logic for a particular blockchain protocol.
+ *
+ * This abstraction allows the Stablecoin Kits to work with multiple blockchains in a uniform way.
+ *
+ */
+declare abstract class Adapter {
+    /**
+     * The type of the chain.
+     * @example 'evm', 'solana'
+     */
+    abstract chainType: ChainType;
+    /**
+     * Capabilities of this adapter, defining address handling patterns and supported chains.
+     *
+     * This property helps determine how the adapter behaves, especially for address resolution
+     * and chain operations. Different adapter types have different requirements for explicit
+     * context in operations.
+     *
+     * @remarks
+     * This is optional for backward compatibility during the migration period.
+     * New adapters should always define this property.
+     *
+     * @example
+     * ```typescript
+     * // Private key adapter
+     * capabilities = {
+     *   addressContext: 'single',
+     *   supportedChains: [Ethereum, Base],
+     *   availableAddresses: ['0x123...']
+     * }
+     *
+     * // Browser wallet adapter
+     * capabilities = {
+     *   addressContext: 'user-accounts',
+     *   supportedChains: [Ethereum, Base, Polygon],
+     *   availableAddresses: ['0x123...', '0x456...']
+     * }
+     * ```
+     */
+    capabilities?: AdapterCapabilities;
+    /**
+     * Default chain for operations when none is explicitly provided.
+     *
+     * This allows adapters to have sensible defaults for chain operations,
+     * reducing the need for explicit chain specification in every call.
+     * Multi-entity adapters typically don't have a default chain.
+     *
+     * @remarks
+     * This is optional for backward compatibility and because some adapter types
+     * (like multi-entity adapters) may not have meaningful defaults.
+     *
+     * @example
+     * ```typescript
+     * // Private key adapter with default chain
+     * defaultChain = Ethereum
+     *
+     * // Multi-entity adapter (no default)
+     * defaultChain = undefined
+     * ```
+     */
+    defaultChain?: ChainDefinition;
+    /**
+     * Registry of available actions for this adapter.
+     *
+     * The {@link ActionRegistry} provides a catalog of supported operations
+     * (such as token transfers, approvals, etc.) that can be performed by this adapter
+     * on the connected blockchain. This enables dynamic discovery and invocation
+     * of chain-specific or cross-chain actions in a type-safe manner.
+     *
+     * @readonly
+     */
+    readonly actionRegistry: ActionRegistry;
+    /**
+     * Prepares (but does not execute) an action for the connected blockchain.
+     *
+     * This method looks up the appropriate action handler for the given action key
+     * and prepares the transaction request using the provided parameters. The returned
+     * {@link PreparedChainRequest} allows developers to estimate gas costs and execute
+     * the transaction at a later time, enabling pre-flight simulation and deferred execution.
+     *
+     * @remarks
+     * This method does not send any transaction to the network. Instead, it returns a
+     * prepared request object with `estimate()` and `execute()` methods, allowing
+     * developers to inspect, simulate, or submit the transaction as needed.
+     *
+     * @param action - The action key identifying which handler to use for preparation.
+     * @param params - The parameters to pass to the action handler.
+     * @returns A promise that resolves to a {@link PreparedChainRequest} for estimation and execution.
+     */
+    prepareAction<TActionKey extends ActionKeys>(action: TActionKey, params: ActionPayload<TActionKey>): Promise<PreparedChainRequest>;
+    /**
+     * Prepares a transaction for future gas estimation and execution.
+     *
+     * This method should handle any preliminary steps required before a transaction
+     * can be estimated or sent. This might include things like serializing transaction
+     * data, but it should NOT yet send anything to the network.
+     *
+     * The returned object contains two functions:
+     *  - `estimate()`: Asynchronously calculates and returns the {@link EstimatedGas} for the prepared transaction.
+     *  - `execute()`: Asynchronously executes the prepared transaction and returns a promise that resolves
+     *                 with the transaction result (e.g., a transaction hash, receipt, or other chain-specific response).
+     *
+     * @remarks
+     * The specific parameters for `prepare` might vary greatly between chain implementations.
+     * Consider defining a generic type or a base type for `transactionRequest` if common patterns emerge,
+     * or allow `...args: any[]` if extreme flexibility is needed by implementers.
+     * For this abstract definition, we keep it parameter-less, assuming implementations will add specific
+     * parameters as needed for their `prepare` method (e.g. `prepare(txDetails: MyChainTxDetails)`).
+     *
+     * @returns An object containing `estimate` and `execute` methods for the prepared transaction.
+     */
+    abstract prepare(params: PreparedChainRequestParams): Promise<PreparedChainRequest>;
+    /**
+     * Retrieves the public address of the connected wallet.
+     *
+     * This address is used as the default sender for transactions
+     * and interactions initiated by this adapter.
+     *
+     * @returns A promise that resolves to the blockchain address as a string.
+     */
+    abstract getAddress(): Promise<string>;
+    /**
+     * Retrieves the {@link ChainDefinition} object that describes the blockchain
+     * this adapter is configured to interact with.
+     *
+     * This includes information such as the chain ID, name, native currency, etc.,
+     * as defined by the `ChainDefinition` type.
+     *
+     * @returns A promise that resolves to the {@link ChainDefinition} for the current chain.
+     */
+    abstract getChain(): Promise<ChainDefinition>;
+    /**
+     * Switches the adapter to operate on the specified chain.
+     *
+     * This abstract method must be implemented by concrete adapters to handle their specific
+     * chain switching logic. The behavior varies by adapter type:
+     * - **Private key adapters**: Recreate clients with new RPC endpoints
+     * - **Browser wallet adapters**: Request chain switch via EIP-1193 or equivalent
+     * - **Multi-entity adapters**: Typically a no-op (operations are contextual)
+     *
+     * @param chain - The target chain to switch to.
+     * @returns A promise that resolves when the chain switch is complete.
+     * @throws When the chain switching fails or is not supported.
+     *
+     * @remarks
+     * This method is called by `ensureChain()` after validation is complete.
+     * Implementations should focus only on the actual switching logic, not validation.
+     *
+     * @example
+     * ```typescript
+     * // EVM adapter implementation
+     * protected async switchToChain(chain: ChainDefinition): Promise<void> {
+     *   if (chain.type !== 'evm') {
+     *     throw new Error('Only EVM chains supported')
+     *   }
+     *   await this.recreateWalletClient(chain)
+     * }
+     *
+     * // Multi-entity adapter implementation
+     * protected async switchToChain(chain: ChainDefinition): Promise<void> {
+     *   // No-op - operations are contextual
+     *   return
+     * }
+     * ```
+     */
+    abstract switchToChain(chain: ChainDefinition): Promise<void>;
+    /**
+     * Ensures the adapter is operating on the specified chain, switching if necessary.
+     *
+     * This method provides a unified interface for establishing chain preconditions across different adapter types.
+     * The behavior varies based on the adapter's capabilities:
+     * - **Private key adapters**: Recreate clients with new RPC endpoints
+     * - **Browser wallet adapters**: Request chain switch via EIP-1193 or equivalent
+     * - **Multi-entity adapters**: Validate chain support (operations are contextual)
+     *
+     * @param chain - The target chain for operations. If not provided, uses the adapter's defaultChain.
+     * @returns A promise that resolves when the adapter is operating on the specified chain.
+     * @throws When the target chain is not supported or chain switching fails.
+     *
+     * @remarks
+     * This method replaces the pattern of calling `getChain()` to check current chain and then
+     * manually switching. It provides a declarative "ensure this chain" interface for operations.
+     *
+     * **Backward Compatibility**: The default implementation provides basic validation but
+     * doesn't perform actual chain switching. Concrete adapter implementations should override
+     * this method to provide proper chain switching logic.
+     *
+     * @example
+     * ```typescript
+     * // Private key adapter - switches chains seamlessly
+     * await privateKeyAdapter.ensureChain(Base)
+     *
+     * // Browser wallet - requests user to switch chains
+     * await metamaskAdapter.ensureChain(Polygon)
+     *
+     * // Multi-entity adapter - validates chain is supported
+     * await circleWalletsAdapter.ensureChain(Ethereum)
+     * ```
+     */
+    ensureChain(chain?: ChainDefinition): Promise<void>;
+    /**
+     * Validate that the target chain is supported by this adapter.
+     *
+     * @param targetChain - The chain to validate.
+     * @throws Error if the chain is not supported.
+     */
+    validateChainSupport(targetChain: ChainDefinition): void;
+    /**
+     * Waits for a transaction to be mined and confirmed on the blockchain.
+     *
+     * This method should block until the transaction is confirmed on the blockchain.
+     * The response includes comprehensive transaction details for the confirmed transaction.
+     *
+     * @param txHash - The hash of the transaction to wait for.
+     * @param config - Optional configuration for waiting behavior including timeout and confirmations.
+     * @returns Promise resolving to comprehensive transaction details.
+     */
+    abstract waitForTransaction(txHash: string, config?: WaitForTransactionConfig): Promise<WaitForTransactionResponse>;
+    /**
+     * Calculate the total transaction fee including compute cost and buffer for the configured chain.
+     *
+     * This method computes the fee by multiplying the base compute units by the current
+     * fee rate, then adds a configurable buffer to account for fee fluctuations and ensure
+     * transaction success. The buffer is specified in basis points (1 basis point = 0.01%).
+     *
+     * @param baseComputeUnits - The base compute units for the transaction (gas for EVM, compute units for Solana, etc.).
+     * @param bufferBasisPoints - The buffer to add as basis points (e.g., 500 = 5%). Defaults to implementation-specific value.
+     * @returns A promise that resolves to the total transaction fee as a bigint.
+     */
+    abstract calculateTransactionFee(baseComputeUnits: bigint, bufferBasisPoints?: bigint): Promise<EstimatedGas>;
+}
+
+/**
+ * EIP-712 domain structure for typed data signing.
+ *
+ * Represents the domain separator fields as defined by the EIP-712 standard.
+ * Used to prevent signature replay across different domains (contracts, chains, etc).
+ *
+ * @see {@link https://eips.ethereum.org/EIPS/eip-712}
+ *
+ * @example
+ * ```typescript
+ * const domain: EIP712Domain = {
+ *   name: "USD Coin",
+ *   version: "2",
+ *   chainId: 1,
+ *   verifyingContract: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
+ * }
+ * ```
+ */
+interface EIP712Domain {
+    /** Human-readable name of the signing domain (e.g., "USD Coin") */
+    name: string;
+    /** Current major version of the signing domain (e.g., "2") */
+    version: string;
+    /** EVM chain ID where the contract is deployed */
+    chainId: number | bigint;
+    /** Address of the contract that will verify the signature */
+    verifyingContract: `0x${string}`;
+    /** Optional salt for domain separation (as hex string) */
+    salt?: `0x${string}`;
+}
+/**
+ * Field definition for EIP-712 typed data.
+ *
+ * Each field describes a property in a struct, including its name and Solidity type.
+ *
+ * @example
+ * ```typescript
+ * const field: TypedDataField = { name: "owner", type: "address" }
+ * ```
+ */
+interface TypedDataField {
+    /** Name of the struct field */
+    name: string;
+    /** Solidity type of the struct field (e.g., "address", "uint256") */
+    type: string;
+}
+/**
+ * EIP-712 Typed Data structure.
+ *
+ * Represents a fully-typed EIP-712 message, including domain, types, primary type, and message payload.
+ *
+ * @typeParam Types - Mapping of struct names to their field definitions
+ * @typeParam Message - The message payload type
+ *
+ * @example
+ * ```typescript
+ * const typedData: TypedData<typeof types, typeof message> = {
+ *   domain,
+ *   types,
+ *   primaryType: "Permit",
+ *   message
+ * }
+ * ```
+ */
+interface TypedData<Types extends Record<string, TypedDataField[]>, Message extends Record<string, unknown>> {
+    /** EIP-712 domain separator */
+    domain: EIP712Domain;
+    /** Mapping of struct names to their field definitions */
+    types: Types;
+    /** The root struct type being signed (must be a key of `types`) */
+    primaryType: keyof Types & string;
+    /** The message payload to be signed */
+    message: Message;
+}
+
+/**
+ * Core type definitions for EVM-compatible blockchain transaction execution
+ * and gas estimation.
+ *
+ * This module provides TypeScript interfaces and types for handling EVM-compatible
+ * blockchain transactions across different networks.
+ *
+ * @module types
+ */
+
+/**
+ * Parameters for reading a contract function on an EVM-compatible chain.
+ *
+ * @interface ReadContractParams
+ * @example
+ * ```typescript
+ * const params: ReadContractParams = {
+ *   address: '0x1234567890abcdef1234567890abcdef12345678',
+ *   abi: myAbi,
+ *   functionName: 'balanceOf',
+ *   args: ['0xabcdef...']
+ * }
+ * ```
+ */
+interface ReadContractParams {
+    /**
+     * The address of the contract to read from.
+     * @example '0x1234567890abcdef1234567890abcdef12345678'
+     */
+    address: `0x${string}`;
+    /**
+     * The ABI of the contract.
+     */
+    abi: Abi;
+    /**
+     * The name of the function to call.
+     * @example 'balanceOf'
+     */
+    functionName: string;
+    /**
+     * The arguments to pass to the function.
+     * @example ['0xabcdef...']
+     */
+    args: unknown[];
+}
+
+/**
+ * Abstract base class for EVM-compatible blockchain adapters.
+ *
+ * This class extends the generic `Adapter` to provide EVM-specific functionality
+ * for interacting with Ethereum Virtual Machine compatible blockchains. It automatically
+ * registers EVM-specific action handlers during construction and sets the chain type to 'evm'.
+ *
+ * The signTypedData method uses a generic TypedData interface from the signTypedData module,
+ * making it compatible with any EIP-712 standard (EIP-2612, EIP-7597, ERC-3009, etc.) while
+ * maintaining type safety throughout the signing process.
+ */
+declare abstract class EvmAdapter extends Adapter {
+    /**
+     * The type of chain this adapter is for.
+     */
+    chainType: ChainType;
+    /**
+     * The constructor for the EVM adapter.
+     *
+     * @remarks
+     * This constructor registers the action handlers for the EVM adapter.
+     */
+    constructor();
+    /**
+     * Signs EIP-712 typed data using a generic, type-safe interface.
+     *
+     * This method accepts strongly-typed EIP-712 data that works with any standard
+     * (EIP-2612, EIP-7597, ERC-3009, etc.) and delegates to the framework-specific
+     * implementation (viem, ethers, web3.js) for actual signing.
+     *
+     * @typeParam Types - The EIP-712 types definition for the standard being signed
+     * @typeParam Message - The message structure for the standard being signed
+     * @param typedData - The EIP-712 typed data to sign with full type safety
+     * @returns Promise resolving to the signature as a hex string
+     * @throws Error when the wallet client is not available or signing fails
+     *
+     * @example
+     * ```typescript
+     * // Works with any EIP-712 standard
+     * import { buildEIP2612TypedData } from '@core/adapter-evm'
+     *
+     * const typedData = await buildEIP2612TypedData(meta, adapter, options)
+     * const signature = await adapter.signTypedData(typedData)
+     * ```
+     */
+    abstract signTypedData<Types extends Record<string, TypedDataField[]>, Message extends Record<string, unknown>>(typedData: TypedData<Types, Message>): Promise<`0x${string}`>;
+    /**
+     * Fetches the current EIP-2612 nonce for a token owner.
+     *
+     * This method queries the token contract's `nonces(address)` function to get
+     * the current nonce value for permit signatures. It uses the adapter's `prepare`
+     * method to handle the contract interaction, making it framework-agnostic.
+     *
+     * @param tokenAddress - The ERC-20 token contract address
+     * @param ownerAddress - The address of the token owner
+     * @returns Promise resolving to the current nonce value
+     * @throws Error when the contract call fails or the token doesn't support EIP-2612
+     *
+     * @example
+     * ```typescript
+     * // Get current nonce for permit signing
+     * const nonce = await adapter.fetchEIP2612Nonce(
+     *   '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
+     *   '0x123...' // owner address
+     * )
+     * ```
+     */
+    fetchEIP2612Nonce(tokenAddress: `0x${string}`, ownerAddress: `0x${string}`): Promise<bigint>;
+    /**
+     * Read a contract function.
+     *
+     * @typeParam TReturnType - The expected return type of the contract function.
+     * @param params - The parameters for the contract function read.
+     * @returns A promise that resolves to the result of the contract function read.
+     */
+    abstract readContract<TReturnType = unknown>(params: ReadContractParams): Promise<TReturnType>;
+}
+
+/**
+ * @packageDocumentation
+ * @module EthersAdapter
+ *
+ * A concrete EVM adapter implementation backed by the `ethers` library.
+ * It provides functionality for gas estimation, contract interaction,
+ * and transaction execution.
+ */
+/**
+ * Direct client configuration for EthersAdapter using pre-configured Ethers.js clients.
+ * @interface EthersAdapterOptions
+ *
+ * @example
+ * ```typescript
+ * import { JsonRpcProvider, Wallet } from 'ethers'
+ * import type { EthersAdapterOptions } from '@circle-fin/adapter-ethers-v6'
+ *
+ * const options: EthersAdapterOptions = {
+ *   getProvider: ({ chain }) => new JsonRpcProvider('https://...'),
+ *   signer: new Wallet('0xabc...', new JsonRpcProvider('https://...')),
+ * }
+ * ```
+ */
+interface EthersAdapterOptions {
+    /**
+     * Returns a pre-configured Ethers.js Provider for the given chain.
+     */
+    getProvider: (params: {
+        chain: EVMChainDefinition;
+    }) => Provider;
+    /** Ethers.js Signer instance used for signing transactions and messages. */
+    signer: Signer$1;
+}
+/**
+ * Creates a new EthersAdapter instance.
+ *
+ * @param options - Configuration options for the adapter.
+ */
+declare class EthersAdapter extends EvmAdapter {
+    /** The configuration options for this adapter instance. */
+    options: EthersAdapterOptions;
+    /** Cached Ethers Signer instance. */
+    private _signer;
+    /** Cached address of the connected wallet. */
+    private cachedAddress?;
+    /** Cached providers for different chains. */
+    private readonly cachedProviders;
+    /** Cached gas price for the current network. */
+    private cachedGasPrice?;
+    /** Cached chain definition for the connected provider. */
+    private cachedChain;
+    /** The resolved chain definition that this adapter was created for. */
+    private resolvedChain;
+    constructor(options: EthersAdapterOptions);
+    /**
+     * Sets the resolved chain for this adapter.
+     * @internal
+     */
+    setResolvedChain(chain: EVMChainDefinition): void;
+    /**
+     * Switches the adapter to operate on the specified chain.
+     *
+     * This implementation recreates the signer with the new chain configuration.
+     * All validation is handled by the base class ensureChain method.
+     *
+     * @param chain - The target chain to switch to (already validated by base class).
+     * @returns A promise that resolves when the chain switch is complete.
+     * @throws When chain switching fails.
+     */
+    switchToChain(chain: ChainDefinition): Promise<void>;
+    /**
+     * Gets the cached Provider or initializes it from options if not already cached.
+     */
+    getProvider(chain?: EVMChainDefinition): Promise<Provider>;
+    /** Gets the current Signer instance used by the adapter. */
+    getSigner(): Signer$1;
+    /**
+     * Creates a contract instance for the given address, ABI, and wallet.
+     */
+    private createContractInstance;
+    /**
+     * Simulates a contract function call using Ethers v6 `.staticCall`.
+     */
+    private simulateFunctionCall;
+    /**
+     * Estimates the gas required for executing a contract function call.
+     */
+    private estimateGasForFunction;
+    /**
+     * Executes a contract function as a transaction on the blockchain.
+     */
+    private executeTransaction;
+    /**
+     * Prepares a chain request for execution.
+     */
+    prepare(params: EvmPreparedChainRequestParams): Promise<EvmPreparedChainRequest>;
+    /** Gets the address of the connected wallet. */
+    getAddress(): Promise<string>;
+    /** Gets the current chain definition. */
+    getChain(): Promise<ChainDefinition>;
+    /**
+     * Waits for a transaction to be mined and confirmed on the blockchain.
+     */
+    waitForTransaction(txHash: string, config?: WaitForTransactionConfig): Promise<WaitForTransactionResponse>;
+    /**
+     * Calculate the total transaction fee including compute cost and buffer for the configured chain.
+     */
+    calculateTransactionFee(baseComputeUnits: bigint, bufferBasisPoints?: bigint): Promise<EstimatedGas>;
+    /**
+     * Signs EIP-712 typed data using the configured signer.
+     */
+    signTypedData<Types extends Record<string, TypedDataField[]>, Message extends Record<string, unknown>>(typedData: TypedData<Types, Message>): Promise<`0x${string}`>;
+    /** Reads a contract function using Ethers v6. */
+    readContract<TReturnType = unknown>(params: ReadContractParams): Promise<TReturnType>;
+}
+
+/**
+ * Parameters for creating an {@link EthersAdapter} from a private key.
+ *
+ * @interface CreateAdapterFromPrivateKeyParams
+ * @category Types
+ * @description
+ * Defines the configuration required to instantiate an {@link EthersAdapter}
+ * using a raw private key for server-side or programmatic wallet operations.
+ *
+ * This is intended for secure, backend, or automated environments where direct
+ * control of the private key is possible and safe. Do not use this pattern in
+ * browser or client-side code.
+ *
+ * @example
+ * ```typescript
+ * import { createAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
+ * import { Blockchain } from '@core/chains'
+ *
+ * // Using a chain identifier (enum, string, or ChainDefinition)
+ * const adapter = createAdapterFromPrivateKey({
+ *   privateKey: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
+ *   defaultChain: Blockchain.Ethereum,
+ * })
+ *
+ * // Advanced: custom provider logic (e.g., for custom endpoints or retry logic)
+ * const adapter2 = createAdapterFromPrivateKey({
+ *   privateKey: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
+ *   defaultChain: 'Ethereum',
+ *   getProvider: ({ chain }) => new JsonRpcProvider('https://...'),
+ * })
+ * ```
+ *
+ * @remarks
+ * Supported parameter combinations:
+ * - Provide `privateKey` and `defaultChain` (uses default provider logic).
+ * - Optionally provide a custom `getProvider` function for advanced provider instantiation.
+ *
+ * The `privateKey` must be a valid 32-byte hex string prefixed with `0x`.
+ * The `defaultChain` can be a {@link ChainDefinition}, a supported chain enum, or a string literal.
+ * The `getProvider` function, if supplied, receives an object with a `chain` parameter.
+ */
+interface CreateAdapterFromPrivateKeyParams {
+    /**
+     * The private key for wallet operations.
+     * @remarks
+     * Must be a valid 32-byte hex string prefixed with '0x'. This should be:
+     * - A securely generated private key
+     * - Kept confidential and never exposed in client-side code
+     * - Used only in server-side or secure environments
+     *
+     * The private key will be used to sign transactions and authenticate
+     * with the blockchain network.
+     */
+    privateKey: `0x${string}`;
+    /**
+     * The default blockchain network to connect to.
+     * @remarks
+     * Accepts a {@link ChainDefinition}, a supported chain enum, or a string literal representing the chain.
+     * This determines which EVM-compatible network the adapter will operate on by default.
+     * The adapter will use the canonical RPC URL for the specified chain unless a custom provider is supplied.
+     * Examples: `Blockchain.Ethereum`, `'Ethereum'`, or a `ChainDefinition` object.
+     */
+    defaultChain: ChainIdentifier;
+    /**
+     * Optional function to provide a custom Ethers Provider instance.
+     * @remarks
+     * If not provided, a default Provider will be created using the chain's RPC endpoints.
+     * Use this to inject custom provider logic, such as:
+     * - Custom retry or caching strategies
+     * - Enhanced logging or monitoring
+     * - Support for non-standard transports
+     *
+     * @param chain - The chain definition for which to create the provider.
+     * @returns A configured Provider instance.
+     */
+    getProvider?: (params: {
+        chain: ChainDefinition;
+    }) => Provider;
+}
+/**
+ * Creates an EthersAdapter instance from a private key.
+ *
+ * This function creates an EthersAdapter for server-side or programmatic use
+ * by deriving a wallet from the provided private key and connecting it to the specified chain.
+ * It's ideal for automated systems, backend services, or scenarios where you have direct
+ * control over the private key.
+ *
+ * @remarks
+ * The function performs the following operations:
+ * 1. Validates the input parameters at runtime
+ * 2. Resolves the chain identifier to a ChainDefinition
+ * 3. Determines the canonical RPC URL for the specified chain
+ * 4. Creates a JsonRpcProvider using the resolved RPC URL (or a custom provider if getProvider is supplied)
+ * 5. Instantiates a Wallet with the private key and provider
+ * 6. Returns a configured EthersAdapter instance
+ *
+ * The adapter will be ready to use immediately after creation with the
+ * specified provider and wallet active. If a custom provider factory is provided,
+ * those settings will be respected for all operations.
+ *
+ * **Security Warning:** Never use this function in client-side code or expose
+ * private keys in any way. This function is intended for server-side use only.
+ *
+ * @param params - Configuration parameters for creating the adapter
+ * @returns A configured EthersAdapter instance
+ * @throws Error when validation fails or wallet creation fails
+ *
+ * @example
+ * ```typescript
+ * import { createAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
+ * import { Blockchain, Ethereum } from '@core/chains'
+ *
+ * // Using ChainDefinition object
+ * const adapter1 = createAdapterFromPrivateKey({
+ *   privateKey: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
+ *   defaultChain: Ethereum,
+ * })
+ *
+ * // Using Blockchain enum
+ * const adapter2 = createAdapterFromPrivateKey({
+ *   privateKey: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
+ *   defaultChain: Blockchain.Ethereum,
+ * })
+ *
+ * // Using string literal
+ * const adapter3 = createAdapterFromPrivateKey({
+ *   privateKey: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
+ *   defaultChain: 'Ethereum',
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { createAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
+ * import { JsonRpcProvider } from 'ethers'
+ *
+ * // Advanced usage with custom provider logic
+ * const adapter = createAdapterFromPrivateKey({
+ *   privateKey: process.env.PRIVATE_KEY,
+ *   defaultChain: 'Ethereum',
+ *   getProvider: ({ chain }) => new JsonRpcProvider('https://...'),
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Cross-chain transfer using a single adapter
+ * import { createAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
+ * import { BridgingKit } from '@circle-fin/bridging-kit'
+ *
+ * const adapter = createAdapterFromPrivateKey({
+ *   privateKey: process.env.PRIVATE_KEY,
+ *   defaultChain: 'Ethereum',
+ * })
+ *
+ * const kit = new BridgingKit()
+ *
+ * // Use the same adapter for both source and destination
+ * const result = await kit.bridge({
+ *   from: { adapter, chain: 'Ethereum' },
+ *   to: { adapter, chain: 'Base' },
+ *   amount: '100.50'
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { createAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
+ *
+ * // Error handling example
+ * try {
+ *   const adapter = createAdapterFromPrivateKey({
+ *     privateKey: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
+ *     defaultChain: 'Polygon',
+ *   })
+ *
+ *   // Adapter is ready to use immediately
+ *   const balance = await adapter.getBalance()
+ *   console.log('Balance:', balance)
+ * } catch (error) {
+ *   if (error.message.includes('Private key')) {
+ *     console.error('Invalid private key format')
+ *   } else {
+ *     console.error('Failed to create adapter:', error.message)
+ *   }
+ * }
+ * ```
+ */
+declare const createAdapterFromPrivateKey: (params: CreateAdapterFromPrivateKeyParams) => EthersAdapter;
+
+/**
+ * Parameters for creating an {@link EthersAdapter} from an EIP-1193 provider.
+ *
+ * @interface CreateAdapterFromProviderParams
+ * @category Types
+ * @description
+ * Defines the parameters required to instantiate an {@link EthersAdapter} using an EIP-1193-compatible provider
+ * (such as MetaMask, WalletConnect, or any injected browser wallet), and to specify the intended blockchain network.
+ *
+ * @example
+ * ```typescript
+ * import { createAdapterFromProvider } from '@circle-fin/adapter-ethers-v6'
+ *
+ * // Basic usage with injected provider and explicit chain
+ * const adapter = await createAdapterFromProvider({
+ *   provider: window.ethereum,
+ *   chain: 'Ethereum_Sepolia',
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { createAdapterFromProvider } from '@circle-fin/adapter-ethers-v6'
+ * import { JsonRpcProvider } from 'ethers'
+ *
+ * // Advanced: custom provider logic for a specific chain
+ * const adapter = await createAdapterFromProvider({
+ *   provider: window.ethereum,
+ *   chain: 'Base_Sepolia',
+ *   getProvider: ({ chain }) => new JsonRpcProvider('https://...'),
+ * })
+ * ```
+ *
+ * @remarks
+ * Required parameters:
+ * - `provider`: A valid EIP-1193 provider (e.g., MetaMask, WalletConnect, etc.).
+ * - `chain`: The blockchain network to use for the adapter. Accepts a chain identifier string, enum, or chain definition.
+ *
+ * Optional:
+ * - `getProvider`: A custom function to instantiate an Ethers Provider for the specified chain.
+ *   Receives an object with a `chain` property of type {@link EVMChainDefinition}.
+ *
+ * The `chain` parameter determines which network the adapter will operate on, regardless of the wallet's current network.
+ * This enables cross-chain workflows and explicit network targeting.
+ */
+interface CreateAdapterFromProviderParams {
+    /**
+     * The EIP-1193-compatible provider for wallet operations.
+     * @remarks
+     * This should be a valid EIP-1193 provider such as:
+     * - Browser wallet providers (MetaMask, WalletConnect, etc.)
+     * - Custom providers that implement the EIP-1193 standard
+     * - Mobile wallet providers via WalletConnect
+     *
+     * The provider must support the required methods:
+     * - `request()` for making JSON-RPC calls
+     * - `enable()` or equivalent for requesting account access
+     */
+    provider: Eip1193Provider;
+    /**
+     * The blockchain network to use for the adapter.
+     * @remarks
+     * This chain will be used as the intended chain for the adapter.
+     * The adapter will use this chain instead of the wallet's current network.
+     */
+    chain: ChainIdentifier;
+    /**
+     * Optional function to provide a custom Ethers Provider instance.
+     * @remarks
+     * If not provided, a default Provider will be created using the chain's RPC endpoints.
+     * Use this to inject custom provider logic, such as:
+     * - Custom retry or caching strategies
+     * - Enhanced logging or monitoring
+     * - Support for non-standard transports
+     *
+     * @param chain - The chain definition for which to create the provider.
+     * @returns A configured Provider instance.
+     */
+    getProvider?: (params: {
+        chain: EVMChainDefinition;
+    }) => Provider;
+}
+/**
+ * Creates an EthersAdapter instance from an EIP-1193 provider.
+ *
+ * This function creates an EthersAdapter for browser or injected wallet use
+ * by connecting to the provided EIP-1193-compatible provider.
+ * It's ideal for dApps, browser-based integrations, or scenarios where the user controls the wallet.
+ *
+ * @remarks
+ * The function performs the following operations:
+ * 1. Validates the input parameters at runtime
+ * 2. Creates a cached provider factory (or uses a custom one if provided)
+ * 3. Instantiates a BrowserProvider for the injected provider
+ * 4. Requests account access and retrieves the signer
+ * 5. Returns a configured EthersAdapter instance
+ *
+ * The adapter will be ready to use immediately after creation with the
+ * specified provider and signer active. If a custom provider factory is provided,
+ * those settings will be respected for all operations.
+ *
+ * **Supported parameter combinations:**
+ * - Provide `provider` and `chain` (uses default provider logic).
+ * - Provide `provider`, `chain`, and a custom `getProvider` function (for advanced provider instantiation).
+ *
+ * **Security Note:** This function is intended for use with injected/browser wallets.
+ * Do not use in server-side code with private keys.
+ *
+ * @param params - Configuration parameters for creating the adapter. Must include:
+ *   - `provider`: An EIP-1193-compatible provider (e.g., MetaMask, WalletConnect, etc.)
+ *   - `chain`: The blockchain network identifier (string, enum, or ChainDefinition)
+ *   - `getProvider` (optional): A custom function to create a JsonRpcProvider
+ * @returns A configured EthersAdapter instance
+ * @throws Error when validation fails or provider/signing fails
+ *
+ * @example
+ * ```typescript
+ * import { createAdapterFromProvider } from '@circle-fin/adapter-ethers-v6'
+ *
+ * // Basic usage with default provider
+ * const adapter = await createAdapterFromProvider({
+ *   provider: window.ethereum,
+ *   chain: 'Ethereum'
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { createAdapterFromProvider } from '@circle-fin/adapter-ethers-v6'
+ * import { JsonRpcProvider } from 'ethers'
+ *
+ * // Advanced usage with custom provider logic
+ * const adapter = await createAdapterFromProvider({
+ *   provider: window.ethereum,
+ *   chain: 'Ethereum',
+ *   getProvider: ({ chain }) => new JsonRpcProvider('https://...')
+ * })
+ * ```
+ */
+declare const createAdapterFromProvider: (params: CreateAdapterFromProviderParams) => Promise<EthersAdapter>;
+
+export { EthersAdapter, createAdapterFromPrivateKey, createAdapterFromProvider };
+export type { ChainIdentifier, CreateAdapterFromPrivateKeyParams, CreateAdapterFromProviderParams, EthersAdapterOptions };