@t402/wdk 2.0.0 → 2.3.0

package/dist/cjs/index.d.ts

@@ -1,5 +1,5 @@
 import { Address } from 'viem';
-import { ClientEvmSigner, BridgeSigner, Usdt0Bridge } from '@t402/evm';
+import { ClientEvmSigner, Usdt0Bridge, BridgeSigner } from '@t402/evm';
 export { BridgeQuote, BridgeSigner, LAYERZERO_ENDPOINT_IDS, USDT0_OFT_ADDRESSES, Usdt0Bridge, getBridgeableChains, supportsBridging } from '@t402/evm';
 
 /**
@@ -660,8 +660,7 @@ declare function createWDKSigner(wdk: WDKInstance, chain: string, accountIndex?:
  */
 declare class MockWDKSigner implements ClientEvmSigner {
     readonly address: Address;
-    private _privateKey;
-    constructor(address: Address, privateKey: `0x${string}`);
+    constructor(address: Address, _privateKey: `0x${string}`);
     signTypedData(_message: {
         domain: Record<string, unknown>;
         types: Record<string, unknown>;
@@ -706,8 +705,6 @@ declare class MockWDKSigner implements ClientEvmSigner {
  */
 declare class T402WDK {
     private _wdk;
-    private _config;
-    private _options;
     private _normalizedChains;
     private _seedPhrase;
     private _signerCache;
@@ -863,7 +860,7 @@ declare class T402WDK {
      * @param preferredToken - Preferred token ("USDT0" | "USDC")
      * @throws {BalanceError} If balance aggregation fails
      */
-    findBestChainForPayment(amount: bigint, preferredToken?: "USDT0" | "USDC"): Promise<{
+    findBestChainForPayment(amount: bigint, preferredToken?: 'USDT0' | 'USDC'): Promise<{
         chain: string;
         token: string;
         balance: bigint;
@@ -943,7 +940,7 @@ declare class T402WDK {
 /**
  * Default chain configurations
  */
-declare const DEFAULT_CHAINS: Record<string, Omit<NormalizedChainConfig, "provider">>;
+declare const DEFAULT_CHAINS: Record<string, Omit<NormalizedChainConfig, 'provider'>>;
 /**
  * Default RPC endpoints (public endpoints, may have rate limits)
  */
@@ -1099,9 +1096,9 @@ declare class SignerError extends WDKError {
  * Error thrown for signing operations
  */
 declare class SigningError extends WDKError {
-    readonly operation: "signTypedData" | "signMessage";
+    readonly operation: 'signTypedData' | 'signMessage';
     constructor(code: WDKErrorCode, message: string, options: {
-        operation: "signTypedData" | "signMessage";
+        operation: 'signTypedData' | 'signMessage';
         cause?: Error;
         context?: Record<string, unknown>;
     });
@@ -1232,7 +1229,7 @@ declare class WdkBridge {
     /**
      * Get or create a bridge instance for a chain
      */
-    private getBridge;
+    getBridge(chain: string, signer: WDKSigner): Usdt0Bridge;
     /**
      * Check if a chain supports USDT0 bridging
      */
@@ -1282,4 +1279,380 @@ declare class WdkBridge {
  */
 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 };
+/**
+ * Hardware wallet type definitions for T402 WDK
+ */
+
+/**
+ * Supported hardware wallet types
+ */
+type HardwareWalletType = 'ledger' | 'trezor';
+/**
+ * Hardware wallet device status
+ */
+type DeviceStatus = 'disconnected' | 'connecting' | 'connected' | 'locked' | 'unlocked' | 'app_closed' | 'ready';
+/**
+ * Hardware wallet connection options
+ */
+interface HardwareWalletConnectionOptions {
+    /** Transport type for Ledger (default: "webusb") */
+    transport?: 'webusb' | 'webhid' | 'bluetooth';
+    /** Account index for HD derivation (default: 0) */
+    accountIndex?: number;
+    /** Custom derivation path (default: m/44'/60'/0'/0/{accountIndex}) */
+    derivationPath?: string;
+    /** Timeout for connection in milliseconds (default: 30000) */
+    timeout?: number;
+}
+/**
+ * Hardware wallet device info
+ */
+interface HardwareWalletDeviceInfo {
+    /** Wallet type */
+    type: HardwareWalletType;
+    /** Device model (e.g., "Nano S", "Nano X", "Model T") */
+    model?: string;
+    /** Firmware version */
+    firmwareVersion?: string;
+    /** Whether the device is locked */
+    isLocked: boolean;
+    /** Current device status */
+    status: DeviceStatus;
+}
+/**
+ * Hardware wallet signer interface
+ */
+interface HardwareWalletSigner {
+    /** Get wallet address */
+    readonly address: Address;
+    /** Wallet type */
+    readonly walletType: HardwareWalletType;
+    /** Device info */
+    readonly deviceInfo: HardwareWalletDeviceInfo;
+    /** Whether the signer is connected */
+    readonly isConnected: boolean;
+    /**
+     * Connect to the hardware wallet
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the hardware wallet
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Sign EIP-712 typed data
+     */
+    signTypedData(params: {
+        domain: Record<string, unknown>;
+        types: Record<string, unknown>;
+        primaryType: string;
+        message: Record<string, unknown>;
+    }): Promise<`0x${string}`>;
+    /**
+     * Sign a personal message
+     */
+    signMessage(message: string | Uint8Array): Promise<`0x${string}`>;
+    /**
+     * Get all available addresses (for account selection)
+     * @param count Number of addresses to retrieve
+     * @param startIndex Starting index
+     */
+    getAddresses?(count: number, startIndex?: number): Promise<Address[]>;
+}
+/**
+ * Ledger-specific options
+ */
+interface LedgerOptions extends HardwareWalletConnectionOptions {
+    /** Whether to scramble key for privacy (default: true) */
+    scrambleKey?: boolean;
+    /** App name on the Ledger (default: "Ethereum") */
+    appName?: string;
+}
+/**
+ * Trezor-specific options
+ */
+interface TrezorOptions extends HardwareWalletConnectionOptions {
+    /** Manifest for Trezor Connect (required) */
+    manifest: {
+        email: string;
+        appUrl: string;
+    };
+    /** Whether to use popup for interactions (default: true) */
+    popup?: boolean;
+    /** Debug mode */
+    debug?: boolean;
+}
+/**
+ * Error codes for hardware wallet operations
+ */
+declare enum HardwareWalletErrorCode {
+    DEVICE_NOT_FOUND = "DEVICE_NOT_FOUND",
+    CONNECTION_FAILED = "CONNECTION_FAILED",
+    DEVICE_LOCKED = "DEVICE_LOCKED",
+    APP_NOT_OPEN = "APP_NOT_OPEN",
+    TRANSPORT_ERROR = "TRANSPORT_ERROR",
+    USER_REJECTED = "USER_REJECTED",
+    SIGNING_FAILED = "SIGNING_FAILED",
+    INVALID_DATA = "INVALID_DATA",
+    NOT_SUPPORTED = "NOT_SUPPORTED",
+    TIMEOUT = "TIMEOUT",
+    UNKNOWN_ERROR = "UNKNOWN_ERROR"
+}
+/**
+ * Hardware wallet error
+ */
+declare class HardwareWalletError extends Error {
+    readonly code: HardwareWalletErrorCode;
+    readonly walletType: HardwareWalletType;
+    readonly cause?: Error;
+    constructor(code: HardwareWalletErrorCode, message: string, walletType: HardwareWalletType, cause?: Error);
+}
+
+/**
+ * Ledger Hardware Wallet Signer for T402 WDK
+ *
+ * Provides T402-compatible signing using Ledger hardware wallets.
+ * Supports Nano S, Nano S Plus, Nano X, and Stax devices.
+ *
+ * @example
+ * ```typescript
+ * import { LedgerSigner } from '@t402/wdk';
+ *
+ * const ledger = new LedgerSigner({ accountIndex: 0 });
+ * await ledger.connect();
+ *
+ * // Get address
+ * console.log('Address:', ledger.address);
+ *
+ * // Sign typed data for T402 payment
+ * const signature = await ledger.signTypedData(typedData);
+ * ```
+ */
+
+/**
+ * Ledger hardware wallet signer
+ */
+declare class LedgerSigner implements HardwareWalletSigner {
+    readonly walletType: "ledger";
+    private _address;
+    private _transport;
+    private _eth;
+    private _options;
+    private _status;
+    private _deviceInfo;
+    constructor(options?: LedgerOptions);
+    /**
+     * Get the wallet address
+     */
+    get address(): Address;
+    /**
+     * Get device info
+     */
+    get deviceInfo(): HardwareWalletDeviceInfo;
+    /**
+     * Check if connected
+     */
+    get isConnected(): boolean;
+    /**
+     * Get the derivation path
+     */
+    get derivationPath(): string;
+    /**
+     * Connect to the Ledger device
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the Ledger device
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Sign EIP-712 typed data
+     *
+     * Note: Requires Ethereum app version 1.6.0+ for EIP-712 support
+     */
+    signTypedData(params: {
+        domain: Record<string, unknown>;
+        types: Record<string, unknown>;
+        primaryType: string;
+        message: Record<string, unknown>;
+    }): Promise<`0x${string}`>;
+    /**
+     * Sign a personal message
+     */
+    signMessage(message: string | Uint8Array): Promise<`0x${string}`>;
+    /**
+     * Get multiple addresses for account selection
+     */
+    getAddresses(count?: number, startIndex?: number): Promise<Address[]>;
+    /**
+     * Get the appropriate transport module based on options
+     */
+    private _getTransportModule;
+    /**
+     * Wrap errors in HardwareWalletError
+     */
+    private _wrapError;
+}
+/**
+ * Create a Ledger signer and connect
+ */
+declare function createLedgerSigner(options?: LedgerOptions): Promise<LedgerSigner>;
+
+/**
+ * Trezor Hardware Wallet Signer for T402 WDK
+ *
+ * Provides T402-compatible signing using Trezor hardware wallets.
+ * Supports Trezor One, Model T, and Safe 3 devices.
+ *
+ * @example
+ * ```typescript
+ * import { TrezorSigner } from '@t402/wdk';
+ *
+ * const trezor = new TrezorSigner({
+ *   manifest: {
+ *     email: 'developer@example.com',
+ *     appUrl: 'https://example.com'
+ *   }
+ * });
+ * await trezor.connect();
+ *
+ * // Get address
+ * console.log('Address:', trezor.address);
+ *
+ * // Sign typed data for T402 payment
+ * const signature = await trezor.signTypedData(typedData);
+ * ```
+ */
+
+/**
+ * Trezor hardware wallet signer
+ */
+declare class TrezorSigner implements HardwareWalletSigner {
+    readonly walletType: "trezor";
+    private _address;
+    private _options;
+    private _status;
+    private _deviceInfo;
+    private _initialized;
+    constructor(options: TrezorOptions);
+    /**
+     * Get the wallet address
+     */
+    get address(): Address;
+    /**
+     * Get device info
+     */
+    get deviceInfo(): HardwareWalletDeviceInfo;
+    /**
+     * Check if connected
+     */
+    get isConnected(): boolean;
+    /**
+     * Get the derivation path
+     */
+    get derivationPath(): string;
+    /**
+     * Initialize Trezor Connect
+     */
+    private _initTrezorConnect;
+    /**
+     * Connect to the Trezor device
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the Trezor device
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Sign EIP-712 typed data
+     */
+    signTypedData(params: {
+        domain: Record<string, unknown>;
+        types: Record<string, unknown>;
+        primaryType: string;
+        message: Record<string, unknown>;
+    }): Promise<`0x${string}`>;
+    /**
+     * Sign a personal message
+     */
+    signMessage(message: string | Uint8Array): Promise<`0x${string}`>;
+    /**
+     * Get multiple addresses for account selection
+     */
+    getAddresses(count?: number, startIndex?: number): Promise<Address[]>;
+    /**
+     * Convert EIP-712 types to Trezor format
+     */
+    private _convertTypesToTrezorFormat;
+    /**
+     * Wrap errors in HardwareWalletError
+     */
+    private _wrapError;
+}
+/**
+ * Create a Trezor signer and connect
+ */
+declare function createTrezorSigner(options: TrezorOptions): Promise<TrezorSigner>;
+
+/**
+ * Hardware Wallet Support for T402 WDK
+ *
+ * This module provides hardware wallet integration for T402 payments,
+ * supporting Ledger and Trezor devices.
+ *
+ * @example Ledger
+ * ```typescript
+ * import { LedgerSigner, createLedgerSigner } from '@t402/wdk';
+ *
+ * // Create and connect
+ * const ledger = await createLedgerSigner({ accountIndex: 0 });
+ * console.log('Address:', ledger.address);
+ *
+ * // Sign T402 payment
+ * const signature = await ledger.signTypedData(paymentData);
+ *
+ * // Disconnect when done
+ * await ledger.disconnect();
+ * ```
+ *
+ * @example Trezor
+ * ```typescript
+ * import { TrezorSigner, createTrezorSigner } from '@t402/wdk';
+ *
+ * // Create and connect (manifest required)
+ * const trezor = await createTrezorSigner({
+ *   manifest: {
+ *     email: 'developer@example.com',
+ *     appUrl: 'https://example.com'
+ *   }
+ * });
+ * console.log('Address:', trezor.address);
+ *
+ * // Sign T402 payment
+ * const signature = await trezor.signTypedData(paymentData);
+ *
+ * // Disconnect when done
+ * await trezor.disconnect();
+ * ```
+ */
+
+/**
+ * Detect available hardware wallets
+ *
+ * Note: This function checks for WebUSB/WebHID support and
+ * doesn't actually probe for devices.
+ */
+declare function detectHardwareWalletSupport(): {
+    ledger: {
+        webusb: boolean;
+        webhid: boolean;
+        bluetooth: boolean;
+    };
+    trezor: boolean;
+};
+/**
+ * Check if hardware wallet signing is supported in the current environment
+ */
+declare function isHardwareWalletSupported(): boolean;
+
+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 DeviceStatus, type EvmChainConfig, type HardwareWalletConnectionOptions, type HardwareWalletDeviceInfo, HardwareWalletError, HardwareWalletErrorCode, type HardwareWalletSigner, type HardwareWalletType, type LedgerOptions, LedgerSigner, MockWDKSigner, type NormalizedChainConfig, RPCError, type RetryConfig, SignerError, SigningError, type T402BalanceCacheConfig, T402WDK, type T402WDKConfig, type T402WDKOptions, type T402WDKSigner, TTLCache, type TokenBalance, type TokenInfo, TransactionError, type TrezorOptions, TrezorSigner, type TypedDataDomain, type TypedDataTypes, USDC_ADDRESSES, USDT0_ADDRESSES, USDT_LEGACY_ADDRESSES, type WDKAccount, type WDKConstructor, WDKError, WDKErrorCode, WDKInitializationError, type WDKInstance, WDKSigner, WdkBridge, createDirectBridge, createLedgerSigner, createTrezorSigner, createWDKSigner, detectHardwareWalletSupport, getChainFromNetwork, getChainId, getNetworkFromChain, getPreferredToken, getUsdt0Chains, hasErrorCode, isHardwareWalletSupported, isWDKError, normalizeChainConfig, withRetry, withTimeout, wrapError };