@t402/wdk 2.0.0

package/dist/cjs/index.d.ts

@@ -0,0 +1,1285 @@
+import { Address } from 'viem';
+import { ClientEvmSigner, BridgeSigner, Usdt0Bridge } from '@t402/evm';
+export { BridgeQuote, BridgeSigner, LAYERZERO_ENDPOINT_IDS, USDT0_OFT_ADDRESSES, Usdt0Bridge, getBridgeableChains, supportsBridging } from '@t402/evm';
+
+/**
+ * Type definitions for T402 WDK integration
+ */
+
+/**
+ * EVM chain configuration
+ */
+interface EvmChainConfig {
+    /** RPC endpoint URL */
+    provider: string;
+    /** Chain ID */
+    chainId: number;
+    /** CAIP-2 network identifier */
+    network: string;
+}
+/**
+ * T402 WDK configuration options
+ */
+interface T402WDKConfig {
+    /** Ethereum mainnet configuration */
+    ethereum?: EvmChainConfig | string;
+    /** Arbitrum One configuration */
+    arbitrum?: EvmChainConfig | string;
+    /** Base mainnet configuration */
+    base?: EvmChainConfig | string;
+    /** Ink mainnet configuration */
+    ink?: EvmChainConfig | string;
+    /** Berachain mainnet configuration */
+    berachain?: EvmChainConfig | string;
+    /** Unichain mainnet configuration */
+    unichain?: EvmChainConfig | string;
+    /** Polygon mainnet configuration */
+    polygon?: EvmChainConfig | string;
+    /** Custom chains */
+    [key: string]: EvmChainConfig | string | undefined;
+}
+/**
+ * Normalized chain configuration
+ */
+interface NormalizedChainConfig {
+    provider: string;
+    chainId: number;
+    network: string;
+    name: string;
+}
+/**
+ * Token balance information
+ */
+interface TokenBalance {
+    /** Token contract address */
+    token: Address;
+    /** Token symbol */
+    symbol: string;
+    /** Balance in smallest units */
+    balance: bigint;
+    /** Formatted balance (human-readable) */
+    formatted: string;
+    /** Decimals */
+    decimals: number;
+}
+/**
+ * Chain balance information
+ */
+interface ChainBalance {
+    /** Chain name (e.g., "arbitrum") */
+    chain: string;
+    /** CAIP-2 network identifier */
+    network: string;
+    /** Native token balance */
+    native: bigint;
+    /** Token balances */
+    tokens: TokenBalance[];
+}
+/**
+ * Aggregated balance across all chains
+ */
+interface AggregatedBalance {
+    /** Total USDT0 balance across all chains */
+    totalUsdt0: bigint;
+    /** Total USDC balance across all chains */
+    totalUsdc: bigint;
+    /** Per-chain balances */
+    chains: ChainBalance[];
+}
+/**
+ * Bridge parameters for cross-chain transfers
+ */
+interface BridgeParams {
+    /** Source chain name */
+    fromChain: string;
+    /** Destination chain name */
+    toChain: string;
+    /** Amount to bridge in smallest units */
+    amount: bigint;
+    /** Recipient address (optional, defaults to same wallet on target chain) */
+    recipient?: Address;
+}
+/**
+ * Bridge result
+ */
+interface BridgeResult {
+    /** Transaction hash on source chain */
+    txHash: string;
+    /** Estimated time for bridge completion in seconds */
+    estimatedTime: number;
+}
+/**
+ * EIP-712 typed data domain
+ */
+interface TypedDataDomain {
+    name: string;
+    version: string;
+    chainId: number;
+    verifyingContract: Address;
+}
+/**
+ * EIP-712 typed data types
+ */
+type TypedDataTypes = Record<string, Array<{
+    name: string;
+    type: string;
+}>>;
+/**
+ * T402 Signer interface for WDK
+ * Compatible with @t402/core signer requirements
+ */
+interface T402WDKSigner {
+    /** Get wallet address */
+    readonly address: Address;
+    /** Sign EIP-712 typed data */
+    signTypedData(params: {
+        domain: TypedDataDomain;
+        types: TypedDataTypes;
+        primaryType: string;
+        message: Record<string, unknown>;
+    }): Promise<`0x${string}`>;
+    /** Sign a message */
+    signMessage?(message: string | Uint8Array): Promise<`0x${string}`>;
+    /** Get token balance */
+    getTokenBalance?(tokenAddress: Address): Promise<bigint>;
+}
+/**
+ * WDK Account interface (matches @tetherto/wdk account structure)
+ */
+interface WDKAccount {
+    getAddress(): Promise<string>;
+    getBalance(): Promise<bigint>;
+    getTokenBalance(tokenAddress: string): Promise<bigint>;
+    signMessage(message: string): Promise<string>;
+    signTypedData(params: {
+        domain: Record<string, unknown>;
+        types: Record<string, unknown>;
+        primaryType: string;
+        message: Record<string, unknown>;
+    }): Promise<string>;
+    sendTransaction(params: {
+        to: string;
+        value?: bigint | string;
+        data?: string;
+    }): Promise<string>;
+    estimateGas(params: {
+        to: string;
+        value?: bigint | string;
+        data?: string;
+    }): Promise<bigint>;
+}
+/**
+ * WDK instance interface (matches @tetherto/wdk structure)
+ */
+interface WDKInstance {
+    registerWallet<T>(name: string, manager: T, config: Record<string, unknown>): WDKInstance;
+    registerProtocol<T>(name: string, protocol: T): WDKInstance;
+    getAccount(chain: string, index: number): Promise<WDKAccount>;
+    executeProtocol(name: string, params: Record<string, unknown>): Promise<{
+        txHash: string;
+    }>;
+}
+/**
+ * WDK constructor type
+ */
+interface WDKConstructor {
+    new (seedPhrase: string): WDKInstance;
+    getRandomSeedPhrase(): string;
+}
+/**
+ * Balance cache configuration for T402WDK
+ */
+interface T402BalanceCacheConfig {
+    /** Whether caching is enabled (default: true) */
+    enabled?: boolean;
+    /** TTL for native balance in milliseconds (default: 15000 = 15 seconds) */
+    nativeBalanceTTL?: number;
+    /** TTL for token balance in milliseconds (default: 30000 = 30 seconds) */
+    tokenBalanceTTL?: number;
+    /** TTL for aggregated balances in milliseconds (default: 60000 = 60 seconds) */
+    aggregatedBalanceTTL?: number;
+    /** Maximum cache entries (default: 500) */
+    maxSize?: number;
+}
+/**
+ * Extended T402 WDK configuration with cache options
+ */
+interface T402WDKOptions {
+    /** Balance cache configuration */
+    cache?: T402BalanceCacheConfig;
+}
+
+/**
+ * TTL Cache implementation for balance caching
+ *
+ * Provides a generic cache with configurable TTL (Time To Live) for
+ * reducing RPC calls and improving performance.
+ */
+/**
+ * Cache configuration options
+ */
+interface CacheConfig {
+    /** Default TTL in milliseconds (default: 30000 = 30 seconds) */
+    defaultTTL: number;
+    /** Maximum number of entries (default: 1000) */
+    maxSize: number;
+    /** Whether to refresh TTL on access (default: false) */
+    refreshOnAccess: boolean;
+}
+/**
+ * Default cache configuration
+ */
+declare const DEFAULT_CACHE_CONFIG: CacheConfig;
+/**
+ * Generic TTL cache implementation
+ *
+ * @example
+ * ```typescript
+ * const cache = new TTLCache<bigint>({ defaultTTL: 60000 });
+ *
+ * // Set with default TTL
+ * cache.set('balance:arbitrum:0x123', 1000000n);
+ *
+ * // Set with custom TTL
+ * cache.set('balance:ethereum:0x456', 2000000n, 120000);
+ *
+ * // Get value (returns undefined if expired)
+ * const balance = cache.get('balance:arbitrum:0x123');
+ *
+ * // Check if key exists and is not expired
+ * if (cache.has('balance:arbitrum:0x123')) {
+ *   // Use cached value
+ * }
+ * ```
+ */
+declare class TTLCache<T> {
+    private _cache;
+    private _config;
+    private _cleanupInterval;
+    constructor(config?: Partial<CacheConfig>);
+    /**
+     * Get a value from the cache
+     *
+     * @param key - Cache key
+     * @returns The cached value or undefined if not found/expired
+     */
+    get(key: string): T | undefined;
+    /**
+     * Set a value in the cache
+     *
+     * @param key - Cache key
+     * @param value - Value to cache
+     * @param ttl - TTL in milliseconds (optional, uses default if not provided)
+     */
+    set(key: string, value: T, ttl?: number): void;
+    /**
+     * Check if a key exists and is not expired
+     *
+     * @param key - Cache key
+     * @returns true if key exists and is not expired
+     */
+    has(key: string): boolean;
+    /**
+     * Delete a key from the cache
+     *
+     * @param key - Cache key
+     * @returns true if key was deleted
+     */
+    delete(key: string): boolean;
+    /**
+     * Delete all keys matching a prefix
+     *
+     * @param prefix - Key prefix to match
+     * @returns Number of keys deleted
+     */
+    deleteByPrefix(prefix: string): number;
+    /**
+     * Clear all entries from the cache
+     */
+    clear(): void;
+    /**
+     * Get the number of entries in the cache (including expired)
+     */
+    get size(): number;
+    /**
+     * Get the number of valid (non-expired) entries
+     */
+    get validSize(): number;
+    /**
+     * Get all valid keys
+     */
+    keys(): string[];
+    /**
+     * Get remaining TTL for a key in milliseconds
+     *
+     * @param key - Cache key
+     * @returns Remaining TTL in ms, or -1 if not found/expired
+     */
+    getTTL(key: string): number;
+    /**
+     * Update TTL for an existing key
+     *
+     * @param key - Cache key
+     * @param ttl - New TTL in milliseconds
+     * @returns true if key exists and TTL was updated
+     */
+    touch(key: string, ttl?: number): boolean;
+    /**
+     * Get or set a value using a factory function
+     *
+     * @param key - Cache key
+     * @param factory - Function to create value if not cached
+     * @param ttl - TTL in milliseconds (optional)
+     * @returns The cached or newly created value
+     */
+    getOrSet(key: string, factory: () => Promise<T>, ttl?: number): Promise<T>;
+    /**
+     * Get cache statistics
+     */
+    getStats(): CacheStats;
+    /**
+     * Stop the cleanup interval
+     */
+    dispose(): void;
+    /**
+     * Start periodic cleanup of expired entries
+     */
+    private _startCleanup;
+    /**
+     * Remove all expired entries
+     */
+    private _removeExpired;
+    /**
+     * Evict oldest entries to make room
+     */
+    private _evictOldest;
+}
+/**
+ * Cache statistics
+ */
+interface CacheStats {
+    /** Total entries including expired */
+    totalSize: number;
+    /** Valid (non-expired) entries */
+    validSize: number;
+    /** Expired entries pending cleanup */
+    expiredSize: number;
+    /** Maximum cache size */
+    maxSize: number;
+    /** Default TTL in milliseconds */
+    defaultTTL: number;
+    /** Time until oldest entry expires (ms) */
+    oldestExpiryMs: number;
+    /** Time until newest entry expires (ms) */
+    newestExpiryMs: number;
+}
+/**
+ * Balance cache configuration
+ */
+interface BalanceCacheConfig {
+    /** Whether caching is enabled (default: true) */
+    enabled: boolean;
+    /** TTL for native balance in milliseconds (default: 15000 = 15 seconds) */
+    nativeBalanceTTL: number;
+    /** TTL for token balance in milliseconds (default: 30000 = 30 seconds) */
+    tokenBalanceTTL: number;
+    /** TTL for aggregated balances in milliseconds (default: 60000 = 60 seconds) */
+    aggregatedBalanceTTL: number;
+    /** Maximum cache entries (default: 500) */
+    maxSize: number;
+}
+/**
+ * Default balance cache configuration
+ */
+declare const DEFAULT_BALANCE_CACHE_CONFIG: BalanceCacheConfig;
+/**
+ * Specialized balance cache for WDK
+ *
+ * Provides separate TTL settings for different balance types
+ * and convenient methods for balance-specific caching.
+ *
+ * @example
+ * ```typescript
+ * const cache = new BalanceCache({
+ *   tokenBalanceTTL: 60000, // 1 minute for token balances
+ * });
+ *
+ * // Cache token balance
+ * cache.setTokenBalance('arbitrum', '0xUSDT', '0xWallet', 1000000n);
+ *
+ * // Get cached balance (returns undefined if expired)
+ * const balance = cache.getTokenBalance('arbitrum', '0xUSDT', '0xWallet');
+ *
+ * // Or use getOrFetch pattern
+ * const balance = await cache.getOrFetchTokenBalance(
+ *   'arbitrum',
+ *   '0xUSDT',
+ *   '0xWallet',
+ *   async () => await signer.getTokenBalance('0xUSDT')
+ * );
+ * ```
+ */
+declare class BalanceCache {
+    private _cache;
+    private _aggregatedCache;
+    private _config;
+    constructor(config?: Partial<BalanceCacheConfig>);
+    /**
+     * Check if caching is enabled
+     */
+    get enabled(): boolean;
+    /**
+     * Get cache configuration
+     */
+    get config(): BalanceCacheConfig;
+    /**
+     * Get cached native balance
+     */
+    getNativeBalance(chain: string, address: string): bigint | undefined;
+    /**
+     * Set native balance in cache
+     */
+    setNativeBalance(chain: string, address: string, balance: bigint): void;
+    /**
+     * Get or fetch native balance
+     */
+    getOrFetchNativeBalance(chain: string, address: string, fetcher: () => Promise<bigint>): Promise<bigint>;
+    /**
+     * Get cached token balance
+     */
+    getTokenBalance(chain: string, token: string, address: string): bigint | undefined;
+    /**
+     * Set token balance in cache
+     */
+    setTokenBalance(chain: string, token: string, address: string, balance: bigint): void;
+    /**
+     * Get or fetch token balance
+     */
+    getOrFetchTokenBalance(chain: string, token: string, address: string, fetcher: () => Promise<bigint>): Promise<bigint>;
+    /**
+     * Get cached aggregated balance
+     */
+    getAggregatedBalance<T>(key: string): T | undefined;
+    /**
+     * Set aggregated balance in cache
+     */
+    setAggregatedBalance<T>(key: string, value: T): void;
+    /**
+     * Get or fetch aggregated balance
+     */
+    getOrFetchAggregatedBalance<T>(key: string, fetcher: () => Promise<T>): Promise<T>;
+    /**
+     * Invalidate all balances for a chain
+     */
+    invalidateChain(chain: string): number;
+    /**
+     * Invalidate all balances for an address
+     */
+    invalidateAddress(address: string): number;
+    /**
+     * Invalidate specific token balance
+     */
+    invalidateTokenBalance(chain: string, token: string, address: string): boolean;
+    /**
+     * Clear all caches
+     */
+    clear(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): BalanceCacheStats;
+    /**
+     * Dispose of cache resources
+     */
+    dispose(): void;
+    private _nativeKey;
+    private _tokenKey;
+    private _aggregatedKey;
+}
+/**
+ * Balance cache statistics
+ */
+interface BalanceCacheStats {
+    balanceCache: CacheStats;
+    aggregatedCache: CacheStats;
+    config: BalanceCacheConfig;
+}
+
+/**
+ * WDK Signer implementation for T402 payments
+ *
+ * This signer wraps the Tether WDK account to provide a T402-compatible
+ * signing interface for EVM chains.
+ */
+
+/**
+ * WDK Signer for T402 EVM payments
+ *
+ * Implements the ClientEvmSigner interface from @t402/evm,
+ * wrapping a Tether WDK account for signing operations.
+ *
+ * @example
+ * ```typescript
+ * import { T402WDK } from '@t402/wdk';
+ *
+ * const wdk = new T402WDK(seedPhrase, { arbitrum: 'https://arb1.arbitrum.io/rpc' });
+ * const signer = await wdk.getSigner('arbitrum');
+ *
+ * // Use with T402 client
+ * const client = createT402HTTPClient({
+ *   signers: [{ scheme: 'exact', signer }]
+ * });
+ * ```
+ */
+declare class WDKSigner implements ClientEvmSigner {
+    private _wdk;
+    private _chain;
+    private _accountIndex;
+    private _account;
+    private _address;
+    private _timeoutMs;
+    /**
+     * Create a new WDK signer
+     *
+     * @param wdk - The WDK instance
+     * @param chain - Chain name (e.g., "arbitrum", "ethereum")
+     * @param accountIndex - HD wallet account index (default: 0)
+     * @param timeoutMs - Timeout for operations in milliseconds (default: 30000)
+     */
+    constructor(wdk: WDKInstance, chain: string, accountIndex?: number, timeoutMs?: number);
+    /**
+     * Get the wallet address
+     * Throws if signer is not initialized
+     */
+    get address(): Address;
+    /**
+     * Check if the signer is initialized
+     */
+    get isInitialized(): boolean;
+    /**
+     * Initialize the signer by fetching the account
+     * Must be called before using the signer
+     *
+     * @throws {SignerError} If account fetch fails
+     */
+    initialize(): Promise<void>;
+    /**
+     * Get the underlying WDK account
+     * Initializes if not already done
+     *
+     * @throws {SignerError} If initialization fails
+     */
+    private getAccount;
+    /**
+     * Sign EIP-712 typed data for T402 payments
+     *
+     * This is the primary signing method used by T402 for EIP-3009
+     * transferWithAuthorization payments.
+     *
+     * @throws {SigningError} If signing fails
+     */
+    signTypedData(message: {
+        domain: Record<string, unknown>;
+        types: Record<string, unknown>;
+        primaryType: string;
+        message: Record<string, unknown>;
+    }): Promise<`0x${string}`>;
+    /**
+     * Sign a personal message
+     *
+     * @throws {SigningError} If signing fails
+     */
+    signMessage(message: string | Uint8Array): Promise<`0x${string}`>;
+    /**
+     * Get the chain name
+     */
+    getChain(): string;
+    /**
+     * Get the chain ID
+     */
+    getChainId(): number;
+    /**
+     * Get the account index
+     */
+    getAccountIndex(): number;
+    /**
+     * Get native token balance (ETH, etc.)
+     *
+     * @throws {BalanceError} If balance fetch fails
+     */
+    getBalance(): Promise<bigint>;
+    /**
+     * Get ERC20 token balance
+     *
+     * @throws {BalanceError} If balance fetch fails
+     */
+    getTokenBalance(tokenAddress: Address): Promise<bigint>;
+    /**
+     * Estimate gas for a transaction
+     *
+     * @throws {TransactionError} If gas estimation fails
+     */
+    estimateGas(params: {
+        to: Address;
+        value?: bigint;
+        data?: string;
+    }): Promise<bigint>;
+    /**
+     * Send a transaction (for advanced use cases)
+     *
+     * @throws {TransactionError} If transaction fails
+     */
+    sendTransaction(params: {
+        to: Address;
+        value?: bigint;
+        data?: string;
+    }): Promise<{
+        hash: `0x${string}`;
+    }>;
+}
+/**
+ * Create an initialized WDK signer
+ *
+ * This async factory function creates and initializes a WDK signer,
+ * ensuring the address is available immediately.
+ *
+ * @throws {SignerError} If initialization fails
+ *
+ * @example
+ * ```typescript
+ * const signer = await createWDKSigner(wdkInstance, 'arbitrum');
+ * console.log('Address:', signer.address); // Works immediately
+ * ```
+ */
+declare function createWDKSigner(wdk: WDKInstance, chain: string, accountIndex?: number, timeoutMs?: number): Promise<WDKSigner>;
+/**
+ * Mock WDK signer for testing purposes
+ *
+ * Implements the same interface but uses a fixed private key
+ * for deterministic testing.
+ */
+declare class MockWDKSigner implements ClientEvmSigner {
+    readonly address: Address;
+    private _privateKey;
+    constructor(address: Address, privateKey: `0x${string}`);
+    signTypedData(_message: {
+        domain: Record<string, unknown>;
+        types: Record<string, unknown>;
+        primaryType: string;
+        message: Record<string, unknown>;
+    }): Promise<`0x${string}`>;
+    signMessage(_message: string | Uint8Array): Promise<`0x${string}`>;
+}
+
+/**
+ * T402WDK - Main class for T402 integration with Tether WDK
+ *
+ * Provides a high-level API for:
+ * - Multi-chain wallet management
+ * - T402-compatible signers
+ * - Balance aggregation
+ * - Cross-chain bridging (USDT0)
+ */
+
+/**
+ * T402WDK - Tether WDK integration for T402 payments
+ *
+ * @example
+ * ```typescript
+ * import { T402WDK } from '@t402/wdk';
+ *
+ * // Initialize with seed phrase
+ * const seedPhrase = T402WDK.generateSeedPhrase();
+ * const wdk = new T402WDK(seedPhrase, {
+ *   arbitrum: 'https://arb1.arbitrum.io/rpc',
+ *   base: 'https://mainnet.base.org'
+ * });
+ *
+ * // Get signer for T402 payments
+ * const signer = await wdk.getSigner('arbitrum');
+ *
+ * // Use with T402 client
+ * const client = createT402HTTPClient({
+ *   signers: [{ scheme: 'exact', signer }]
+ * });
+ * ```
+ */
+declare class T402WDK {
+    private _wdk;
+    private _config;
+    private _options;
+    private _normalizedChains;
+    private _seedPhrase;
+    private _signerCache;
+    private _balanceCache;
+    private _initializationError;
+    private static _WDK;
+    private static _WalletManagerEvm;
+    private static _BridgeUsdt0Evm;
+    /**
+     * Register the Tether WDK modules
+     *
+     * This must be called before creating T402WDK instances if you want
+     * to use the actual WDK. Otherwise, a mock implementation is used.
+     *
+     * @throws {WDKInitializationError} If registration fails
+     *
+     * @example
+     * ```typescript
+     * import WDK from '@tetherto/wdk';
+     * import WalletManagerEvm from '@tetherto/wdk-wallet-evm';
+     * import BridgeUsdt0Evm from '@tetherto/wdk-protocol-bridge-usdt0-evm';
+     *
+     * T402WDK.registerWDK(WDK, WalletManagerEvm, BridgeUsdt0Evm);
+     * ```
+     */
+    static registerWDK(WDK: WDKConstructor, WalletManagerEvm?: unknown, BridgeUsdt0Evm?: unknown): void;
+    /**
+     * Check if WDK is registered
+     */
+    static isWDKRegistered(): boolean;
+    /**
+     * Check if wallet manager is registered
+     */
+    static isWalletManagerRegistered(): boolean;
+    /**
+     * Check if bridge protocol is registered
+     */
+    static isBridgeRegistered(): boolean;
+    /**
+     * Generate a new random seed phrase
+     *
+     * @throws {WDKInitializationError} If WDK is not registered
+     * @returns A new BIP-39 mnemonic seed phrase
+     */
+    static generateSeedPhrase(): string;
+    /**
+     * Create a new T402WDK instance
+     *
+     * @param seedPhrase - BIP-39 mnemonic seed phrase
+     * @param config - Chain configuration (RPC endpoints)
+     * @param options - Additional options (cache configuration, etc.)
+     * @throws {WDKInitializationError} If seed phrase is invalid
+     */
+    constructor(seedPhrase: string, config?: T402WDKConfig, options?: T402WDKOptions);
+    /**
+     * Add default chain configurations for common chains
+     */
+    private _addDefaultChainsIfNeeded;
+    /**
+     * Initialize the underlying WDK instance
+     */
+    private _initializeWDK;
+    /**
+     * Get the underlying WDK instance
+     *
+     * @throws {WDKInitializationError} If WDK is not initialized
+     */
+    get wdk(): WDKInstance;
+    /**
+     * Check if WDK is properly initialized
+     */
+    get isInitialized(): boolean;
+    /**
+     * Get initialization error if any
+     */
+    get initializationError(): Error | null;
+    /**
+     * Get all configured chains
+     */
+    getConfiguredChains(): string[];
+    /**
+     * Get chain configuration
+     */
+    getChainConfig(chain: string): NormalizedChainConfig | undefined;
+    /**
+     * Check if a chain is configured
+     */
+    isChainConfigured(chain: string): boolean;
+    /**
+     * Get a T402-compatible signer for a chain
+     *
+     * @param chain - Chain name (e.g., "arbitrum", "ethereum")
+     * @param accountIndex - HD wallet account index (default: 0)
+     * @throws {ChainError} If chain is not configured
+     * @throws {SignerError} If signer creation fails
+     * @returns An initialized WDKSigner
+     */
+    getSigner(chain: string, accountIndex?: number): Promise<WDKSigner>;
+    /**
+     * Clear the signer cache
+     * Useful for forcing re-initialization of signers
+     */
+    clearSignerCache(): void;
+    /**
+     * Get wallet address for a chain
+     *
+     * @param chain - Chain name
+     * @param accountIndex - HD wallet account index (default: 0)
+     * @throws {ChainError} If chain is not configured
+     * @throws {SignerError} If address fetch fails
+     */
+    getAddress(chain: string, accountIndex?: number): Promise<Address>;
+    /**
+     * Get USDT0 balance for a chain
+     *
+     * Uses cache if enabled to reduce RPC calls.
+     *
+     * @throws {BalanceError} If balance fetch fails
+     */
+    getUsdt0Balance(chain: string, accountIndex?: number): Promise<bigint>;
+    /**
+     * Get USDC balance for a chain
+     *
+     * Uses cache if enabled to reduce RPC calls.
+     *
+     * @throws {BalanceError} If balance fetch fails
+     */
+    getUsdcBalance(chain: string, accountIndex?: number): Promise<bigint>;
+    /**
+     * Get all token balances for a chain
+     *
+     * Uses cache if enabled to reduce RPC calls.
+     *
+     * @throws {ChainError} If chain is not configured
+     * @throws {BalanceError} If balance fetch fails
+     */
+    getChainBalances(chain: string, accountIndex?: number): Promise<ChainBalance>;
+    /**
+     * Get aggregated balances across all configured chains
+     *
+     * @param accountIndex - HD wallet account index (default: 0)
+     * @param options - Options for balance aggregation
+     */
+    getAggregatedBalances(accountIndex?: number, options?: {
+        continueOnError?: boolean;
+    }): Promise<AggregatedBalance>;
+    /**
+     * Find the best chain for a payment
+     *
+     * Looks for the chain with sufficient balance, prioritizing USDT0.
+     *
+     * @param amount - Required amount in smallest units
+     * @param preferredToken - Preferred token ("USDT0" | "USDC")
+     * @throws {BalanceError} If balance aggregation fails
+     */
+    findBestChainForPayment(amount: bigint, preferredToken?: "USDT0" | "USDC"): Promise<{
+        chain: string;
+        token: string;
+        balance: bigint;
+    } | null>;
+    /**
+     * Bridge USDT0 between chains
+     *
+     * Uses LayerZero OFT for cross-chain transfers.
+     *
+     * @param params - Bridge parameters
+     * @throws {BridgeError} If bridge is not available or fails
+     * @returns Bridge result with transaction hash
+     */
+    bridgeUsdt0(params: BridgeParams): Promise<BridgeResult>;
+    /**
+     * Get chains that support USDT0
+     */
+    getUsdt0Chains(): string[];
+    /**
+     * Get chains that support USDT0 bridging
+     *
+     * Returns configured chains that have LayerZero OFT bridge support.
+     */
+    getBridgeableChains(): string[];
+    /**
+     * Check if bridging is supported between two chains
+     */
+    canBridge(fromChain: string, toChain: string): boolean;
+    /**
+     * Get all possible bridge destinations from a chain
+     */
+    getBridgeDestinations(fromChain: string): string[];
+    /**
+     * Check if balance caching is enabled
+     */
+    get isCacheEnabled(): boolean;
+    /**
+     * Get cache configuration
+     */
+    getCacheConfig(): BalanceCacheConfig;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): BalanceCacheStats;
+    /**
+     * Invalidate all cached balances
+     *
+     * Call this after sending transactions to ensure fresh balance data.
+     */
+    invalidateBalanceCache(): void;
+    /**
+     * Invalidate cached balances for a specific chain
+     *
+     * @param chain - Chain name to invalidate
+     * @returns Number of cache entries invalidated
+     */
+    invalidateChainCache(chain: string): number;
+    /**
+     * Invalidate cached balances for a specific address
+     *
+     * @param address - Address to invalidate (case-insensitive)
+     * @returns Number of cache entries invalidated
+     */
+    invalidateAddressCache(address: string): number;
+    /**
+     * Dispose of cache resources
+     *
+     * Call this when the T402WDK instance is no longer needed.
+     */
+    dispose(): void;
+}
+
+/**
+ * Chain configuration and token addresses for T402 WDK
+ */
+
+/**
+ * Default chain configurations
+ */
+declare const DEFAULT_CHAINS: Record<string, Omit<NormalizedChainConfig, "provider">>;
+/**
+ * Default RPC endpoints (public endpoints, may have rate limits)
+ */
+declare const DEFAULT_RPC_ENDPOINTS: Record<string, string>;
+/**
+ * USDT0 token addresses by chain
+ * USDT0 is Tether's omnichain token with EIP-3009 support
+ */
+declare const USDT0_ADDRESSES: Record<string, Address>;
+/**
+ * USDC token addresses by chain
+ */
+declare const USDC_ADDRESSES: Record<string, Address>;
+/**
+ * Legacy USDT addresses (no EIP-3009 support)
+ */
+declare const USDT_LEGACY_ADDRESSES: Record<string, Address>;
+/**
+ * All supported tokens per chain with metadata
+ */
+interface TokenInfo {
+    address: Address;
+    symbol: string;
+    name: string;
+    decimals: number;
+    /** Whether token supports EIP-3009 (gasless transfers) */
+    supportsEIP3009: boolean;
+}
+declare const CHAIN_TOKENS: Record<string, TokenInfo[]>;
+/**
+ * Normalize chain configuration from string or object
+ */
+declare function normalizeChainConfig(chainName: string, config: string | EvmChainConfig): NormalizedChainConfig;
+/**
+ * Get CAIP-2 network ID from chain name
+ */
+declare function getNetworkFromChain(chain: string): string;
+/**
+ * Get chain name from CAIP-2 network ID
+ */
+declare function getChainFromNetwork(network: string): string | undefined;
+/**
+ * Get chain ID from chain name
+ */
+declare function getChainId(chain: string): number;
+/**
+ * Get all chains that support USDT0
+ */
+declare function getUsdt0Chains(): string[];
+/**
+ * Get preferred token for a chain (USDT0 > USDC > USDT)
+ */
+declare function getPreferredToken(chain: string): TokenInfo | undefined;
+
+/**
+ * Error classes for T402 WDK integration
+ *
+ * Provides structured error handling with error codes for
+ * programmatic error handling and debugging.
+ */
+/**
+ * Error codes for WDK operations
+ */
+declare enum WDKErrorCode {
+    WDK_NOT_REGISTERED = 1001,
+    WDK_NOT_INITIALIZED = 1002,
+    INVALID_SEED_PHRASE = 1003,
+    WALLET_MANAGER_NOT_REGISTERED = 1004,
+    CHAIN_NOT_CONFIGURED = 2001,
+    CHAIN_NOT_SUPPORTED = 2002,
+    INVALID_CHAIN_CONFIG = 2003,
+    UNKNOWN_CHAIN_ID = 2004,
+    SIGNER_NOT_INITIALIZED = 3001,
+    ACCOUNT_FETCH_FAILED = 3002,
+    ADDRESS_FETCH_FAILED = 3003,
+    SIGN_TYPED_DATA_FAILED = 4001,
+    SIGN_MESSAGE_FAILED = 4002,
+    INVALID_TYPED_DATA = 4003,
+    INVALID_MESSAGE = 4004,
+    USER_REJECTED_SIGNATURE = 4005,
+    BALANCE_FETCH_FAILED = 5001,
+    TOKEN_BALANCE_FETCH_FAILED = 5002,
+    INVALID_TOKEN_ADDRESS = 5003,
+    TRANSACTION_FAILED = 6001,
+    GAS_ESTIMATION_FAILED = 6002,
+    INSUFFICIENT_BALANCE = 6003,
+    TRANSACTION_REVERTED = 6004,
+    TRANSACTION_TIMEOUT = 6005,
+    BRIDGE_NOT_AVAILABLE = 7001,
+    BRIDGE_NOT_SUPPORTED = 7002,
+    BRIDGE_FAILED = 7003,
+    INSUFFICIENT_BRIDGE_FEE = 7004,
+    RPC_ERROR = 8001,
+    RPC_TIMEOUT = 8002,
+    RPC_RATE_LIMITED = 8003,
+    RPC_CONNECTION_FAILED = 8004,
+    UNKNOWN_ERROR = 9999
+}
+/**
+ * Base error class for WDK operations
+ */
+declare class WDKError extends Error {
+    readonly code: WDKErrorCode;
+    readonly cause?: Error;
+    readonly context?: Record<string, unknown>;
+    constructor(code: WDKErrorCode, message: string, options?: {
+        cause?: Error;
+        context?: Record<string, unknown>;
+    });
+    /**
+     * Create a JSON-serializable representation
+     */
+    toJSON(): Record<string, unknown>;
+    /**
+     * Check if error is retryable
+     */
+    isRetryable(): boolean;
+}
+/**
+ * Error thrown when WDK is not properly initialized
+ */
+declare class WDKInitializationError extends WDKError {
+    constructor(message: string, options?: {
+        cause?: Error;
+        context?: Record<string, unknown>;
+    });
+}
+/**
+ * Error thrown for chain-related issues
+ */
+declare class ChainError extends WDKError {
+    readonly chain?: string;
+    constructor(code: WDKErrorCode, message: string, options?: {
+        chain?: string;
+        cause?: Error;
+        context?: Record<string, unknown>;
+    });
+}
+/**
+ * Error thrown for signer-related issues
+ */
+declare class SignerError extends WDKError {
+    readonly chain?: string;
+    readonly address?: string;
+    constructor(code: WDKErrorCode, message: string, options?: {
+        chain?: string;
+        address?: string;
+        cause?: Error;
+        context?: Record<string, unknown>;
+    });
+}
+/**
+ * Error thrown for signing operations
+ */
+declare class SigningError extends WDKError {
+    readonly operation: "signTypedData" | "signMessage";
+    constructor(code: WDKErrorCode, message: string, options: {
+        operation: "signTypedData" | "signMessage";
+        cause?: Error;
+        context?: Record<string, unknown>;
+    });
+}
+/**
+ * Error thrown for balance operations
+ */
+declare class BalanceError extends WDKError {
+    readonly chain?: string;
+    readonly token?: string;
+    constructor(code: WDKErrorCode, message: string, options?: {
+        chain?: string;
+        token?: string;
+        cause?: Error;
+        context?: Record<string, unknown>;
+    });
+}
+/**
+ * Error thrown for transaction operations
+ */
+declare class TransactionError extends WDKError {
+    readonly chain?: string;
+    readonly txHash?: string;
+    constructor(code: WDKErrorCode, message: string, options?: {
+        chain?: string;
+        txHash?: string;
+        cause?: Error;
+        context?: Record<string, unknown>;
+    });
+}
+/**
+ * Error thrown for bridge operations
+ */
+declare class BridgeError extends WDKError {
+    readonly fromChain?: string;
+    readonly toChain?: string;
+    constructor(code: WDKErrorCode, message: string, options?: {
+        fromChain?: string;
+        toChain?: string;
+        cause?: Error;
+        context?: Record<string, unknown>;
+    });
+}
+/**
+ * Error thrown for RPC-related issues
+ */
+declare class RPCError extends WDKError {
+    readonly endpoint?: string;
+    readonly rpcCode?: number;
+    constructor(code: WDKErrorCode, message: string, options?: {
+        endpoint?: string;
+        rpcCode?: number;
+        cause?: Error;
+        context?: Record<string, unknown>;
+    });
+}
+/**
+ * Wrap an unknown error into a WDKError
+ */
+declare function wrapError(error: unknown, defaultCode?: WDKErrorCode, defaultMessage?: string, context?: Record<string, unknown>): WDKError;
+/**
+ * Type guard to check if an error is a WDKError
+ */
+declare function isWDKError(error: unknown): error is WDKError;
+/**
+ * Type guard to check if an error has a specific code
+ */
+declare function hasErrorCode(error: unknown, code: WDKErrorCode): boolean;
+/**
+ * Retry configuration
+ */
+interface RetryConfig {
+    /** Maximum number of retries */
+    maxRetries: number;
+    /** Base delay in milliseconds */
+    baseDelay: number;
+    /** Maximum delay in milliseconds */
+    maxDelay: number;
+    /** Whether to use exponential backoff */
+    exponentialBackoff: boolean;
+}
+/**
+ * Default retry configuration
+ */
+declare const DEFAULT_RETRY_CONFIG: RetryConfig;
+/**
+ * Execute an async function with retry logic
+ */
+declare function withRetry<T>(fn: () => Promise<T>, config?: Partial<RetryConfig>): Promise<T>;
+/**
+ * Timeout wrapper for async operations
+ */
+declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, operation?: string): Promise<T>;
+
+/**
+ * USDT0 Bridge integration for T402 WDK
+ *
+ * Provides cross-chain USDT0 transfers using:
+ * 1. Tether WDK bridge protocol (if available)
+ * 2. Direct LayerZero OFT integration (fallback)
+ */
+
+/**
+ * Extended bridge result with quote information
+ */
+interface BridgeQuoteResult extends BridgeResult {
+    /** Native fee in wei */
+    nativeFee: bigint;
+    /** Minimum amount to receive */
+    minAmountToReceive: bigint;
+}
+/**
+ * WDK Bridge wrapper for USDT0 cross-chain transfers
+ *
+ * This class provides a high-level API for bridging USDT0 between chains.
+ * It automatically handles:
+ * - Fee estimation
+ * - Token approval
+ * - Transaction execution
+ * - Receipt handling
+ */
+declare class WdkBridge {
+    private bridges;
+    /**
+     * Create bridge signer adapter from WDK signer
+     */
+    private createBridgeSigner;
+    /**
+     * Get or create a bridge instance for a chain
+     */
+    private getBridge;
+    /**
+     * Check if a chain supports USDT0 bridging
+     */
+    static supportsBridging(chain: string): boolean;
+    /**
+     * Get all chains that support USDT0 bridging
+     */
+    static getBridgeableChains(): string[];
+    /**
+     * Get supported destinations from a source chain
+     */
+    static getSupportedDestinations(fromChain: string): string[];
+}
+/**
+ * Create a direct USDT0 bridge (without WDK)
+ *
+ * Use this when you have a viem wallet client and want to bridge directly.
+ *
+ * @example
+ * ```typescript
+ * import { createDirectBridge } from '@t402/wdk';
+ * import { createWalletClient, http } from 'viem';
+ * import { arbitrum } from 'viem/chains';
+ *
+ * const walletClient = createWalletClient({
+ *   chain: arbitrum,
+ *   transport: http('https://arb1.arbitrum.io/rpc'),
+ *   account: privateKeyToAccount(privateKey),
+ * });
+ *
+ * const bridge = createDirectBridge(walletClient, 'arbitrum');
+ *
+ * const quote = await bridge.quote({
+ *   fromChain: 'arbitrum',
+ *   toChain: 'ethereum',
+ *   amount: 100_000000n,
+ *   recipient: walletClient.account.address,
+ * });
+ *
+ * const result = await bridge.send({
+ *   fromChain: 'arbitrum',
+ *   toChain: 'ethereum',
+ *   amount: 100_000000n,
+ *   recipient: walletClient.account.address,
+ * });
+ * ```
+ */
+declare function createDirectBridge(signer: BridgeSigner, chain: string): Usdt0Bridge;
+
+export { type AggregatedBalance, BalanceCache, type BalanceCacheConfig, type BalanceCacheStats, BalanceError, BridgeError, type BridgeParams, type BridgeQuoteResult, type BridgeResult, CHAIN_TOKENS, type CacheConfig, type CacheStats, type ChainBalance, ChainError, DEFAULT_BALANCE_CACHE_CONFIG, DEFAULT_CACHE_CONFIG, DEFAULT_CHAINS, DEFAULT_RETRY_CONFIG, DEFAULT_RPC_ENDPOINTS, type EvmChainConfig, MockWDKSigner, type NormalizedChainConfig, RPCError, type RetryConfig, SignerError, SigningError, type T402BalanceCacheConfig, T402WDK, type T402WDKConfig, type T402WDKOptions, type T402WDKSigner, TTLCache, type TokenBalance, type TokenInfo, TransactionError, type TypedDataDomain, type TypedDataTypes, USDC_ADDRESSES, USDT0_ADDRESSES, USDT_LEGACY_ADDRESSES, type WDKAccount, type WDKConstructor, WDKError, WDKErrorCode, WDKInitializationError, type WDKInstance, WDKSigner, WdkBridge, createDirectBridge, createWDKSigner, getChainFromNetwork, getChainId, getNetworkFromChain, getPreferredToken, getUsdt0Chains, hasErrorCode, isWDKError, normalizeChainConfig, withRetry, withTimeout, wrapError };