@cryptforge/blockchain-evm 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,580 @@
+import { TokenBalance, TransactionOptions, Transaction, TokenTransfer, BlockchainAdapter, ChainData, KeyData } from '@cryptforge/core';
+export { TokenBalance, TokenTransfer, Transaction, TransactionOptions } from '@cryptforge/core';
+
+/**
+ * Interface for blockchain data providers (indexers/explorers).
+ * Implementations fetch wallet data from various sources (Alchemy, Etherscan, etc.)
+ */
+interface BlockchainDataProvider {
+    /**
+     * Get native token balance for an address
+     * @param address - Wallet address
+     * @returns TokenBalance object with native token information
+     */
+    getNativeBalance(address: string): Promise<TokenBalance>;
+    /**
+     * Get all ERC-20 token balances for an address
+     * @param address - Wallet address
+     * @returns Array of token balances with metadata
+     */
+    getTokenBalances(address: string): Promise<TokenBalance[]>;
+    /**
+     * Get balance for a specific ERC-20 token
+     * @param address - Wallet address
+     * @param tokenAddress - Token contract address
+     * @returns Balance in smallest unit as string
+     */
+    getTokenBalance(address: string, tokenAddress: string): Promise<string>;
+    /**
+     * Get all transactions for an address
+     * @param address - Wallet address
+     * @param options - Optional filtering and pagination options
+     * @returns Array of transactions
+     */
+    getTransactions(address: string, options?: TransactionOptions): Promise<Transaction[]>;
+    /**
+     * Get all ERC-20 token transfers for an address
+     * @param address - Wallet address
+     * @param options - Optional filtering and pagination options
+     * @returns Array of token transfers
+     */
+    getTokenTransfers(address: string, options?: TransactionOptions): Promise<TokenTransfer[]>;
+}
+
+/**
+ * Network configuration for a specific blockchain network (mainnet, testnet, etc.)
+ */
+interface NetworkConfig {
+    /** Network name (e.g., "Ethereum Mainnet", "Sonic Testnet") */
+    name: string;
+    /** RPC endpoint URL */
+    rpcUrl: string;
+    /** Block explorer URL (optional) */
+    explorerUrl?: string;
+    /** Chain ID for the network */
+    chainId: number;
+}
+/**
+ * Configuration options for EVM blockchain adapter
+ */
+interface EVMAdapterConfig {
+    /** Chain metadata (name, symbol, CMC ID) */
+    chainData: ChainData;
+    /** BIP44 coin type (default: 60 for Ethereum) */
+    coinType?: number;
+    /** Standard decimals for the chain's native token (default: 18) */
+    standardDecimals?: number;
+    /** Network configurations (mainnet, testnet, custom networks) */
+    networks?: {
+        mainnet?: NetworkConfig;
+        testnet?: NetworkConfig;
+        [key: string]: NetworkConfig | undefined;
+    };
+    /** Default network to use (default: 'mainnet') */
+    defaultNetwork?: string;
+    /** Optional data provider for fetching balances and transactions */
+    dataProvider?: BlockchainDataProvider;
+    /** BIP44 account index (default: 0) */
+    account?: number;
+    /** BIP44 change index (default: 0) */
+    change?: number;
+    /** BIP44 address index (default: 0) */
+    addressIndex?: number;
+}
+/**
+ * Configurable EVM blockchain adapter for CryptForge SDK.
+ * Supports all EVM-compatible blockchains (Ethereum, Sonic, Polygon, BSC, etc.)
+ * Uses ethers.js for key derivation and wallet operations.
+ */
+declare class EVMAdapter implements BlockchainAdapter {
+    readonly chainData: ChainData;
+    readonly standardDecimals: number;
+    private readonly coinType;
+    private readonly account;
+    private readonly change;
+    private readonly addressIndex;
+    private readonly networks;
+    private currentNetworkKey;
+    private dataProvider?;
+    /**
+     * Create a new EVM blockchain adapter
+     * @param config - Chain configuration
+     */
+    constructor(config: EVMAdapterConfig);
+    /**
+     * Get the BIP44 derivation path for this chain
+     * @returns BIP44 path string (e.g., "m/44'/60'/0'/0/0")
+     */
+    private getDerivationPath;
+    /**
+     * Get the current network configuration
+     * @returns Current network configuration, or undefined if no network is configured
+     */
+    getNetwork(): NetworkConfig | undefined;
+    /**
+     * Get the current network key (e.g., 'mainnet', 'testnet')
+     * @returns Current network key
+     */
+    getCurrentNetworkKey(): string;
+    /**
+     * Set the active network
+     * @param networkKey - Network key to switch to (e.g., 'mainnet', 'testnet')
+     * @throws Error if the network key doesn't exist
+     */
+    setNetwork(networkKey: string): void;
+    /**
+     * Get all available network keys
+     * @returns Array of network keys (e.g., ['mainnet', 'testnet'])
+     */
+    getAvailableNetworks(): string[];
+    /**
+     * Check if a network is configured
+     * @param networkKey - Network key to check
+     * @returns True if the network exists
+     */
+    hasNetwork(networkKey: string): boolean;
+    /**
+     * Derive EVM keys from a BIP39 mnemonic.
+     * Uses the BIP44 derivation path specified in the configuration.
+     *
+     * @param mnemonic - BIP39 mnemonic phrase
+     * @returns KeyData with derived keys and address
+     */
+    deriveKeys(mnemonic: string): Promise<KeyData>;
+    /**
+     * Derive keys at a specific address index
+     * @param mnemonic - BIP39 mnemonic phrase
+     * @param addressIndex - Address index in the BIP44 path
+     * @returns KeyData with derived keys
+     */
+    deriveKeysAtIndex(mnemonic: string, addressIndex: number): Promise<KeyData>;
+    /**
+     * Derive keys at a custom derivation path
+     * @param mnemonic - BIP39 mnemonic phrase
+     * @param path - Full BIP44 derivation path
+     * @returns KeyData with derived keys
+     */
+    deriveKeysAtPath(mnemonic: string, path: string): Promise<KeyData>;
+    /**
+     * Get address at a specific index (read-only, no private key)
+     * @param mnemonic - BIP39 mnemonic phrase
+     * @param index - Address index
+     * @returns Address and public key information
+     */
+    getAddressAtIndex(mnemonic: string, index: number): Promise<{
+        address: string;
+        publicKey: string;
+        path: string;
+    }>;
+    /**
+     * Get multiple addresses starting from an index
+     * @param mnemonic - BIP39 mnemonic phrase
+     * @param startIndex - Starting address index
+     * @param count - Number of addresses to generate
+     * @returns Array of addresses with metadata
+     */
+    getAddresses(mnemonic: string, startIndex: number, count: number): Promise<Array<{
+        address: string;
+        path: string;
+        index: number;
+    }>>;
+    /**
+     * Sign a message with a private key
+     * @param privateKey - Private key as Uint8Array
+     * @param message - Message to sign (string or Uint8Array)
+     * @returns Signature
+     */
+    signMessage(privateKey: Uint8Array, message: string | Uint8Array): Promise<{
+        signature: string;
+    }>;
+    /**
+     * Sign a transaction with a private key
+     * @param privateKey - Private key as Uint8Array
+     * @param transaction - Chain-specific transaction object
+     * @returns Signed transaction and signature
+     */
+    signTransaction(privateKey: Uint8Array, transaction: any): Promise<{
+        signedTransaction: any;
+        signature: string;
+    }>;
+    /**
+     * Verify a signature against a public key
+     * @param message - Original message
+     * @param signature - Signature to verify
+     * @param publicKey - Public key (hex string)
+     * @returns True if signature is valid
+     */
+    verifySignature(message: string | Uint8Array, signature: string, publicKey: string): Promise<boolean>;
+    /**
+     * Set or update the data provider
+     * @param provider - The blockchain data provider to use
+     */
+    setDataProvider(provider: BlockchainDataProvider): void;
+    /**
+     * Get the current data provider
+     * @returns The current data provider, or undefined if not set
+     */
+    getDataProvider(): BlockchainDataProvider | undefined;
+    /**
+     * Ensure a data provider is configured
+     * @throws Error if no data provider is set
+     */
+    private ensureProvider;
+    /**
+     * Get native token balance for an address
+     * @param address - Wallet address
+     * @returns TokenBalance object with native token information
+     * @throws Error if no data provider is configured
+     */
+    getNativeBalance(address: string): Promise<TokenBalance>;
+    /**
+     * Get all ERC-20 token balances for an address
+     * @param address - Wallet address
+     * @returns Array of token balances with metadata
+     * @throws Error if no data provider is configured
+     */
+    getTokenBalances(address: string): Promise<TokenBalance[]>;
+    /**
+     * Get balance for a specific ERC-20 token
+     * @param address - Wallet address
+     * @param tokenAddress - Token contract address
+     * @returns Balance in smallest unit as string
+     * @throws Error if no data provider is configured
+     */
+    getTokenBalance(address: string, tokenAddress: string): Promise<string>;
+    /**
+     * Get all transactions for an address
+     * @param address - Wallet address
+     * @param options - Optional filtering and pagination options
+     * @returns Array of transactions
+     * @throws Error if no data provider is configured
+     */
+    getTransactions(address: string, options?: TransactionOptions): Promise<Transaction[]>;
+    /**
+     * Get all ERC-20 token transfers for an address
+     * @param address - Wallet address
+     * @param options - Optional filtering and pagination options
+     * @returns Array of token transfers
+     * @throws Error if no data provider is configured
+     */
+    getTokenTransfers(address: string, options?: TransactionOptions): Promise<TokenTransfer[]>;
+    /**
+     * Validate if an address is a valid ERC-20 token contract
+     * @param tokenAddress - Token contract address
+     * @returns True if valid ERC-20, false otherwise
+     */
+    validateTokenContract(tokenAddress: string): Promise<boolean>;
+    /**
+     * Send native tokens (ETH, S, etc.)
+     * @param params - Transaction parameters including private key
+     * @returns Transaction receipt
+     */
+    sendNativeToken(params: {
+        privateKey: Uint8Array;
+        to: string;
+        amount: string;
+    }): Promise<{
+        hash: string;
+        from: string;
+        to: string;
+        value: string;
+        chainId: number;
+        status: "pending";
+        nonce: number;
+    }>;
+    /**
+     * Send ERC-20 tokens
+     * Private key must be obtained from AuthClient after password verification
+     * @param params - Transaction parameters including private key and token address
+     * @returns Transaction receipt
+     */
+    sendToken(params: {
+        privateKey: Uint8Array;
+        to: string;
+        tokenAddress: string;
+        amount: string;
+    }): Promise<{
+        hash: string;
+        from: string;
+        to: string;
+        value: string;
+        chainId: number;
+        status: "pending";
+        nonce: number;
+    }>;
+    /**
+     * Wait for transaction confirmation and return detailed status
+     * @param hash - Transaction hash
+     * @returns Transaction status update
+     */
+    getTransactionStatus(hash: string): Promise<{
+        hash: string;
+        status: "pending" | "confirmed" | "failed";
+        blockNumber?: number;
+        confirmations?: number;
+        error?: string;
+        gasUsed?: string;
+    }>;
+    private bytesToHex;
+    private hexToBytes;
+}
+
+/**
+ * Configuration for Alchemy provider
+ */
+interface AlchemyProviderConfig {
+    /** Alchemy API key */
+    apiKey: string;
+    /** Network identifier for Portfolio API (e.g., "sonic-mainnet", "eth-mainnet") */
+    network: string;
+    /** RPC URL for direct blockchain queries */
+    rpcUrl: string;
+    /** Native token symbol (e.g., "ETH", "S") */
+    nativeTokenSymbol: string;
+    /** Native token name (e.g., "Ethereum", "Sonic") */
+    nativeTokenName: string;
+    /** Native token decimals (default: 18) */
+    nativeTokenDecimals?: number;
+    /** CoinMarketCap ID for logo URL */
+    cmc_id: number;
+}
+/**
+ * Blockchain data provider using Alchemy Portfolio API.
+ * Fetches wallet balances, transactions, and token data from Alchemy's indexer.
+ *
+ * Uses Alchemy's Portfolio API for token balances and direct RPC for other queries.
+ *
+ * @example
+ * ```typescript
+ * import { AlchemyProvider } from '@cryptforge/blockchain-evm';
+ *
+ * const provider = new AlchemyProvider({
+ *   apiKey: process.env.ALCHEMY_API_KEY!,
+ *   network: "sonic-mainnet",
+ *   rpcUrl: "https://sonic-mainnet.g.alchemy.com/v2/YOUR_API_KEY",
+ * });
+ *
+ * const balance = await provider.getNativeBalance('0x...');
+ * const tokens = await provider.getTokenBalances('0x...');
+ * ```
+ */
+declare class AlchemyProvider implements BlockchainDataProvider {
+    private apiKey;
+    private network;
+    private provider;
+    private nativeTokenSymbol;
+    private nativeTokenName;
+    private nativeTokenDecimals;
+    private cmc_id;
+    constructor(config: AlchemyProviderConfig);
+    /**
+     * Get native token balance (e.g., ETH, S) for an address using RPC
+     */
+    getNativeBalance(address: string): Promise<TokenBalance>;
+    /**
+     * Get all ERC-20 token balances for an address using Alchemy Portfolio API
+     */
+    getTokenBalances(address: string): Promise<TokenBalance[]>;
+    /**
+     * Get balance for a specific ERC-20 token using RPC
+     */
+    getTokenBalance(address: string, tokenAddress: string): Promise<string>;
+    /**
+     * Get all transactions for an address using Alchemy's getAssetTransfers API
+     */
+    getTransactions(address: string, options?: TransactionOptions): Promise<Transaction[]>;
+    /**
+     * Get all ERC-20 token transfers for an address using Alchemy's getAssetTransfers API
+     */
+    getTokenTransfers(address: string, options?: TransactionOptions): Promise<TokenTransfer[]>;
+    /**
+     * Helper method to fetch asset transfers from Alchemy API
+     */
+    private fetchAssetTransfers;
+}
+
+/**
+ * Etherscan provider configuration
+ */
+interface EtherscanProviderConfig {
+    /** Etherscan API key (works across all supported chains) */
+    apiKey: string;
+    /** Chain ID (e.g., 1 for Ethereum, 146 for Sonic, 137 for Polygon) */
+    chainId: number;
+    /** Native token symbol (e.g., "ETH", "S") */
+    nativeTokenSymbol: string;
+    /** Native token name (e.g., "Ethereum", "Sonic") */
+    nativeTokenName: string;
+    /** Native token decimals (default: 18) */
+    nativeTokenDecimals?: number;
+    /** CoinMarketCap ID for logo URL */
+    cmc_id: number;
+    /** Etherscan API V2 base URL (default: https://api.etherscan.io/v2/api) */
+    baseUrl?: string;
+}
+/**
+ * Etherscan-based blockchain data provider
+ * Uses Etherscan API V2 to fetch wallet data and transaction history
+ */
+declare class EtherscanProvider implements BlockchainDataProvider {
+    private apiKey;
+    private chainId;
+    private baseUrl;
+    private nativeTokenSymbol;
+    private nativeTokenName;
+    private nativeTokenDecimals;
+    private cmc_id;
+    /**
+     * Create an Etherscan provider using API V2
+     * @param config - Provider configuration
+     */
+    constructor(config: EtherscanProviderConfig);
+    /**
+     * Get native token balance for an address
+     * @param address - Wallet address
+     * @returns TokenBalance object with native token information
+     */
+    getNativeBalance(address: string): Promise<TokenBalance>;
+    /**
+     * Get all ERC-20 token balances for an address
+     * @param address - Wallet address
+     * @returns Array of token balances with metadata
+     *
+     * Note: This endpoint prefers the Etherscan API Pro endpoint for better performance,
+     * but automatically falls back to a free-tier compatible approach if needed.
+     */
+    getTokenBalances(address: string): Promise<TokenBalance[]>;
+    /**
+     * Free-tier fallback for getTokenBalances
+     * Discovers tokens via transfer history and fetches individual balances
+     * Rate-limited to respect Etherscan free tier limits (3 calls/sec)
+     * @param address - Wallet address
+     * @returns Array of token balances with metadata
+     */
+    private getTokenBalancesFallback;
+    /**
+     * Helper method to add delay (for rate limiting)
+     * @param ms - Milliseconds to delay
+     */
+    private delay;
+    /**
+     * Wrapper for fetch with automatic retry on rate limit
+     * @param url - URL to fetch
+     * @param maxRetries - Maximum number of retries (default: 2)
+     * @returns Response
+     */
+    private fetchWithRetry;
+    /**
+     * Get balance for a specific ERC-20 token
+     * @param address - Wallet address
+     * @param tokenAddress - Token contract address
+     * @returns Balance in smallest unit as string
+     */
+    getTokenBalance(address: string, tokenAddress: string): Promise<string>;
+    /**
+     * Get all transactions for an address
+     * @param address - Wallet address
+     * @param options - Optional filtering and pagination options
+     * @returns Array of transactions
+     */
+    getTransactions(address: string, options?: TransactionOptions): Promise<Transaction[]>;
+    /**
+     * Get all ERC-20 token transfers for an address
+     * @param address - Wallet address
+     * @param options - Optional filtering and pagination options
+     * @returns Array of token transfers
+     */
+    getTokenTransfers(address: string, options?: TransactionOptions): Promise<TokenTransfer[]>;
+}
+
+/**
+ * Pre-configured Ethereum adapter.
+ * Uses standard Ethereum derivation path: m/44'/60'/0'/0/0
+ *
+ * Network Configuration:
+ * - Mainnet: Ethereum Mainnet (Chain ID: 1)
+ * - Testnet: Sepolia (Chain ID: 11155111)
+ *
+ * Note: RPC URLs use Infura. Replace 'YOUR_INFURA_API_KEY' with your actual API key,
+ * or create a custom adapter with your preferred RPC provider.
+ *
+ * @example
+ * ```typescript
+ * import { EthereumAdapter } from '@cryptforge/blockchain-evm';
+ *
+ * // Use pre-configured adapter
+ * setupCryptForgeHandlers({
+ *   blockchainAdapters: {
+ *     Ethereum: EthereumAdapter,
+ *   }
+ * });
+ *
+ * // Get network info
+ * const network = EthereumAdapter.getNetwork(); // mainnet by default
+ * console.log(network?.rpcUrl);
+ *
+ * // Switch to testnet
+ * EthereumAdapter.setNetwork('testnet');
+ * ```
+ *
+ * @example Custom RPC Configuration
+ * ```typescript
+ * import { EVMAdapter } from '@cryptforge/blockchain-evm';
+ *
+ * const CustomEthereum = new EVMAdapter({
+ *   chainData: { name: "Ethereum", symbol: "ETH", cmc_id: 1027 },
+ *   coinType: 60,
+ *   standardDecimals: 18,
+ *   networks: {
+ *     mainnet: {
+ *       name: "Ethereum Mainnet",
+ *       rpcUrl: `https://mainnet.infura.io/v3/${process.env.INFURA_API_KEY}`,
+ *       explorerUrl: "https://etherscan.io",
+ *       chainId: 1,
+ *     },
+ *     testnet: {
+ *       name: "Ethereum Testnet (Sepolia)",
+ *       rpcUrl: `https://sepolia.infura.io/v3/${process.env.INFURA_API_KEY}`,
+ *       explorerUrl: "https://sepolia.etherscan.io",
+ *       chainId: 11155111,
+ *     },
+ *   },
+ * });
+ * ```
+ */
+declare const EthereumAdapter: EVMAdapter;
+
+/**
+ * Pre-configured Sonic adapter.
+ * Sonic is an EVM-compatible Layer 2 blockchain.
+ * Uses standard Ethereum derivation path: m/44'/60'/0'/0/0
+ *
+ * Network Configuration:
+ * - Mainnet: Sonic Mainnet (Chain ID: 146)
+ * - Testnet: Sonic Testnet (Chain ID: 57054)
+ *
+ * @example
+ * ```typescript
+ * import { SonicAdapter } from '@cryptforge/blockchain-evm';
+ *
+ * // Use pre-configured adapter
+ * setupCryptForgeHandlers({
+ *   blockchainAdapters: {
+ *     Sonic: SonicAdapter,
+ *   }
+ * });
+ *
+ * // Get network info
+ * const network = SonicAdapter.getNetwork(); // mainnet by default
+ * console.log(network?.rpcUrl); // "https://rpc.sonic.soniclabs.com"
+ * console.log(network?.chainId); // 146
+ *
+ * // Switch to testnet
+ * SonicAdapter.setNetwork('testnet');
+ * const testnetNetwork = SonicAdapter.getNetwork();
+ * console.log(testnetNetwork?.chainId); // 57054
+ * ```
+ */
+declare const SonicAdapter: EVMAdapter;
+
+export { AlchemyProvider, type AlchemyProviderConfig, type BlockchainDataProvider, EVMAdapter, type EVMAdapterConfig, EthereumAdapter, EtherscanProvider, type EtherscanProviderConfig, type NetworkConfig, SonicAdapter };