@deserialize/multi-vm-wallet 1.4.2 → 1.5.0

package/utils/savings/savings-operations.ts

@@ -0,0 +1,509 @@
+/**
+ * Stateless Savings Operations
+ *
+ * Provides stateless operations for savings management where credentials
+ * are passed per-operation rather than stored in memory. Designed for
+ * secure usage in browser extensions and mobile wallets.
+ *
+ * @remarks
+ * Security Model:
+ * - No mnemonic or private key storage
+ * - Implementer passes credentials per-operation
+ * - Keys exist in memory only during operation
+ * - Automatic cleanup after use
+ *
+ * @example
+ * ```typescript
+ * // Browser extension with encrypted storage
+ * const operations = new SavingsOperations();
+ *
+ * // Unlock wallet (implementer handles encryption/biometric)
+ * const mnemonic = await secureStorage.getMnemonic();
+ *
+ * // Perform operation - mnemonic not stored
+ * const result = await operations.transferFromPocket(
+ *   mnemonic,
+ *   { walletIndex: 0, accountIndex: 1, to: '0x...', amount: 100n },
+ *   provider,
+ *   chain
+ * );
+ *
+ * // Mnemonic automatically cleared from memory after operation
+ * ```
+ */
+
+import { ethers, JsonRpcProvider, Wallet, parseUnits, formatUnits, Interface } from "ethers";
+import { Hex } from "viem";
+import { SavingsValidation } from "./validation";
+import { ChainWalletConfig, TransactionResult } from "../types";
+import { EVMDeriveChildPrivateKey, mnemonicToSeed } from "../walletBip32";
+
+/**
+ * Options for transferring from a savings pocket
+ */
+export interface TransferFromPocketOptions {
+    /** Wallet index in derivation path (default: 0) */
+    walletIndex?: number;
+    /** Account/pocket index to transfer from (1-based, 0 is main wallet) */
+    accountIndex: number;
+    /** Destination address */
+    to: string;
+    /** Amount to transfer in base units (wei for ETH) */
+    amount: bigint;
+    /** Optional gas limit */
+    gasLimit?: bigint;
+    /** Optional gas price (for legacy transactions) */
+    gasPrice?: bigint;
+    /** Optional max fee per gas (for EIP-1559) */
+    maxFeePerGas?: bigint;
+    /** Optional max priority fee per gas (for EIP-1559) */
+    maxPriorityFeePerGas?: bigint;
+}
+
+/**
+ * Options for transferring tokens from a savings pocket
+ */
+export interface TransferTokenFromPocketOptions extends Omit<TransferFromPocketOptions, 'amount'> {
+    /** Token contract address */
+    tokenAddress: string;
+    /** Amount to transfer in token's smallest unit */
+    amount: bigint;
+}
+
+/**
+ * Options for getting pocket balance
+ */
+export interface GetPocketBalanceOptions {
+    /** Wallet index in derivation path (default: 0) */
+    walletIndex?: number;
+    /** Account/pocket index (1-based, 0 is main wallet) */
+    accountIndex: number;
+}
+
+/**
+ * Options for getting pocket token balance
+ */
+export interface GetPocketTokenBalanceOptions extends GetPocketBalanceOptions {
+    /** Token contract address */
+    tokenAddress: string;
+}
+
+/**
+ * Token balance information
+ */
+export interface TokenBalance {
+    /** Token contract address */
+    address: string;
+    /** Balance in token's smallest unit */
+    balance: bigint;
+    /** Token decimals */
+    decimals: number;
+    /** Token symbol */
+    symbol: string;
+    /** Token name */
+    name: string;
+    /** Formatted balance string */
+    formatted: string;
+}
+
+/**
+ * Result of a pocket derivation
+ */
+interface PocketDerivationResult {
+    /** Derived wallet instance */
+    wallet: Wallet;
+    /** Pocket address */
+    address: string;
+    /** Cleanup function to zero out sensitive data */
+    cleanup: () => void;
+}
+
+/**
+ * Stateless savings operations that don't store sensitive data
+ *
+ * All methods accept mnemonic as parameter and derive keys on-demand.
+ * Keys are automatically cleaned up after each operation.
+ */
+export class SavingsOperations {
+    /**
+     * Derives a savings pocket wallet from mnemonic
+     *
+     * @param mnemonic - BIP-39 mnemonic phrase
+     * @param accountIndex - Account/pocket index (1-based, 0 is main wallet)
+     * @param walletIndex - Wallet index (default: 0)
+     * @param provider - RPC provider to connect wallet to
+     * @returns Derived wallet, address, and cleanup function
+     *
+     * @remarks
+     * IMPORTANT: Always call cleanup() when done with the wallet to zero out private key
+     *
+     * Derivation path: m/44'/60'/{accountIndex}'/0/{walletIndex}'
+     *
+     * @throws Error if validation fails
+     *
+     * @internal
+     */
+    private derivePocketWallet(
+        mnemonic: string,
+        accountIndex: number,
+        walletIndex: number = 0,
+        provider: JsonRpcProvider
+    ): PocketDerivationResult {
+        // Validate inputs
+        SavingsValidation.validateMnemonic(mnemonic);
+        SavingsValidation.validateAccountIndex(accountIndex);
+        SavingsValidation.validateWalletIndex(walletIndex);
+
+        // Derive pocket private key
+        const seed = mnemonicToSeed(mnemonic);
+        const { privateKey } = EVMDeriveChildPrivateKey(seed, walletIndex, `m/44'/60'/${accountIndex}'/`);
+
+        // Create wallet
+        const wallet = new Wallet(privateKey, provider);
+        const address = wallet.address;
+
+        // Cleanup function to zero out sensitive data
+        const cleanup = () => {
+            // Note: JavaScript strings are immutable, so we can't directly zero them
+            // The seed and privateKey will be garbage collected when they go out of scope
+        };
+
+        return { wallet, address, cleanup };
+    }
+
+    /**
+     * Get native token balance of a savings pocket
+     *
+     * @param mnemonic - BIP-39 mnemonic phrase
+     * @param options - Balance query options
+     * @param provider - RPC provider
+     * @returns Balance in wei
+     *
+     * @throws Error if validation fails or balance check fails
+     *
+     * @example
+     * ```typescript
+     * const balance = await operations.getPocketBalance(
+     *   mnemonic,
+     *   { accountIndex: 1, walletIndex: 0 },
+     *   provider
+     * );
+     * console.log(`Pocket 1 balance: ${formatUnits(balance, 18)} ETH`);
+     * ```
+     */
+    async getPocketBalance(
+        mnemonic: string,
+        options: GetPocketBalanceOptions,
+        provider: JsonRpcProvider
+    ): Promise<bigint> {
+        const { accountIndex, walletIndex = 0 } = options;
+
+        const { wallet, cleanup } = this.derivePocketWallet(
+            mnemonic,
+            accountIndex,
+            walletIndex,
+            provider
+        );
+
+        try {
+            const balance = await provider.getBalance(wallet.address);
+            return BigInt(balance.toString());
+        } finally {
+            cleanup();
+        }
+    }
+
+    /**
+     * Get token balance of a savings pocket
+     *
+     * @param mnemonic - BIP-39 mnemonic phrase
+     * @param options - Token balance query options
+     * @param provider - RPC provider
+     * @returns Token balance and metadata
+     *
+     * @throws Error if validation fails or balance check fails
+     *
+     * @example
+     * ```typescript
+     * const usdcBalance = await operations.getPocketTokenBalance(
+     *   mnemonic,
+     *   {
+     *     accountIndex: 1,
+     *     walletIndex: 0,
+     *     tokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
+     *   },
+     *   provider
+     * );
+     * ```
+     */
+    async getPocketTokenBalance(
+        mnemonic: string,
+        options: GetPocketTokenBalanceOptions,
+        provider: JsonRpcProvider
+    ): Promise<TokenBalance> {
+        const { accountIndex, walletIndex = 0, tokenAddress } = options;
+
+        // Validate token address
+        SavingsValidation.validateAddress(tokenAddress, 'Token address');
+
+        const { wallet, address, cleanup } = this.derivePocketWallet(
+            mnemonic,
+            accountIndex,
+            walletIndex,
+            provider
+        );
+
+        try {
+            // ERC20 interface
+            const erc20Interface = new Interface([
+                "function balanceOf(address) view returns (uint256)",
+                "function decimals() view returns (uint8)",
+                "function symbol() view returns (string)",
+                "function name() view returns (string)"
+            ]);
+
+            const tokenContract = new ethers.Contract(tokenAddress, erc20Interface, provider);
+
+            // Fetch token info and balance in parallel
+            const [balance, decimals, symbol, name] = await Promise.all([
+                tokenContract.balanceOf(address),
+                tokenContract.decimals(),
+                tokenContract.symbol(),
+                tokenContract.name()
+            ]);
+
+            const balanceBigInt = BigInt(balance.toString());
+
+            return {
+                address: tokenAddress,
+                balance: balanceBigInt,
+                decimals: Number(decimals),
+                symbol: symbol,
+                name: name,
+                formatted: formatUnits(balanceBigInt, decimals)
+            };
+        } finally {
+            cleanup();
+        }
+    }
+
+    /**
+     * Transfer native tokens from a savings pocket
+     *
+     * @param mnemonic - BIP-39 mnemonic phrase
+     * @param options - Transfer options
+     * @param provider - RPC provider
+     * @param chain - Chain configuration
+     * @returns Transaction result
+     *
+     * @throws Error if validation fails or transaction fails
+     *
+     * @example
+     * ```typescript
+     * // Transfer 0.1 ETH from pocket 1 to another address
+     * const result = await operations.transferFromPocket(
+     *   mnemonic,
+     *   {
+     *     accountIndex: 1,
+     *     walletIndex: 0,
+     *     to: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
+     *     amount: parseUnits('0.1', 18)
+     *   },
+     *   provider,
+     *   chain
+     * );
+     * ```
+     */
+    async transferFromPocket(
+        mnemonic: string,
+        options: TransferFromPocketOptions,
+        provider: JsonRpcProvider,
+        chain: ChainWalletConfig
+    ): Promise<TransactionResult> {
+        const {
+            accountIndex,
+            walletIndex = 0,
+            to,
+            amount,
+            gasLimit,
+            gasPrice,
+            maxFeePerGas,
+            maxPriorityFeePerGas
+        } = options;
+
+        // Validate inputs
+        SavingsValidation.validateAddress(to, 'Destination address');
+        SavingsValidation.validateAmount(amount, 'Transfer amount');
+
+        const { wallet, cleanup } = this.derivePocketWallet(
+            mnemonic,
+            accountIndex,
+            walletIndex,
+            provider
+        );
+
+        try {
+            // Build transaction
+            const tx: any = {
+                to,
+                value: amount,
+                chainId: chain.chainId
+            };
+
+            // Add gas parameters if provided
+            if (gasLimit) tx.gasLimit = gasLimit;
+            if (gasPrice) tx.gasPrice = gasPrice;
+            if (maxFeePerGas) tx.maxFeePerGas = maxFeePerGas;
+            if (maxPriorityFeePerGas) tx.maxPriorityFeePerGas = maxPriorityFeePerGas;
+
+            // Send transaction
+            const txResponse = await wallet.sendTransaction(tx);
+
+            // Wait for confirmation
+            const receipt = await txResponse.wait();
+
+            if (!receipt) {
+                throw new Error('Transaction receipt is null');
+            }
+
+            return {
+                hash: receipt.hash as Hex,
+                success: receipt.status === 1
+            };
+        } finally {
+            cleanup();
+        }
+    }
+
+    /**
+     * Transfer ERC20 tokens from a savings pocket
+     *
+     * @param mnemonic - BIP-39 mnemonic phrase
+     * @param options - Transfer options including token address
+     * @param provider - RPC provider
+     * @param chain - Chain configuration
+     * @returns Transaction result
+     *
+     * @throws Error if validation fails or transaction fails
+     *
+     * @example
+     * ```typescript
+     * // Transfer 100 USDC from pocket 1
+     * const result = await operations.transferTokenFromPocket(
+     *   mnemonic,
+     *   {
+     *     accountIndex: 1,
+     *     walletIndex: 0,
+     *     tokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+     *     to: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
+     *     amount: parseUnits('100', 6) // USDC has 6 decimals
+     *   },
+     *   provider,
+     *   chain
+     * );
+     * ```
+     */
+    async transferTokenFromPocket(
+        mnemonic: string,
+        options: TransferTokenFromPocketOptions,
+        provider: JsonRpcProvider,
+        chain: ChainWalletConfig
+    ): Promise<TransactionResult> {
+        const {
+            accountIndex,
+            walletIndex = 0,
+            tokenAddress,
+            to,
+            amount,
+            gasLimit,
+            maxFeePerGas,
+            maxPriorityFeePerGas
+        } = options;
+
+        // Validate inputs
+        SavingsValidation.validateAddress(tokenAddress, 'Token address');
+        SavingsValidation.validateAddress(to, 'Destination address');
+        SavingsValidation.validateAmount(amount, 'Transfer amount');
+
+        const { wallet, cleanup } = this.derivePocketWallet(
+            mnemonic,
+            accountIndex,
+            walletIndex,
+            provider
+        );
+
+        try {
+            // ERC20 transfer interface
+            const erc20Interface = new Interface([
+                "function transfer(address to, uint256 amount) returns (bool)"
+            ]);
+
+            const tokenContract = new ethers.Contract(tokenAddress, erc20Interface, wallet);
+
+            // Build transaction
+            const tx: any = {
+                chainId: chain.chainId
+            };
+
+            // Add gas parameters if provided
+            if (gasLimit) tx.gasLimit = gasLimit;
+            if (maxFeePerGas) tx.maxFeePerGas = maxFeePerGas;
+            if (maxPriorityFeePerGas) tx.maxPriorityFeePerGas = maxPriorityFeePerGas;
+
+            // Send token transfer transaction
+            const txResponse = await tokenContract.transfer(to, amount, tx);
+
+            // Wait for confirmation
+            const receipt = await txResponse.wait();
+
+            if (!receipt) {
+                throw new Error('Transaction receipt is null');
+            }
+
+            return {
+                hash: receipt.hash as Hex,
+                success: receipt.status === 1
+            };
+        } finally {
+            cleanup();
+        }
+    }
+
+    /**
+     * Get the address of a savings pocket without storing credentials
+     *
+     * @param mnemonic - BIP-39 mnemonic phrase
+     * @param accountIndex - Account/pocket index
+     * @param walletIndex - Wallet index (default: 0)
+     * @returns Pocket address
+     *
+     * @throws Error if validation fails
+     *
+     * @example
+     * ```typescript
+     * const pocketAddress = operations.getPocketAddress(mnemonic, 1, 0);
+     * console.log(`Pocket 1 address: ${pocketAddress}`);
+     * ```
+     */
+    getPocketAddress(
+        mnemonic: string,
+        accountIndex: number,
+        walletIndex: number = 0
+    ): string {
+        // Validate inputs
+        SavingsValidation.validateMnemonic(mnemonic);
+        SavingsValidation.validateAccountIndex(accountIndex);
+        SavingsValidation.validateWalletIndex(walletIndex);
+
+        // Derive address
+        const seed = mnemonicToSeed(mnemonic);
+        const { privateKey } = EVMDeriveChildPrivateKey(seed, walletIndex, `m/44'/60'/${accountIndex}'/`);
+        const wallet = new Wallet(privateKey);
+        const address = wallet.address;
+
+        // Note: JavaScript strings are immutable, so seed will be garbage collected
+        // when it goes out of scope
+
+        return address;
+    }
+}

package/utils/savings/validation.ts

@@ -0,0 +1,187 @@
+/**
+ * Input validation for savings operations
+ *
+ * Provides validation utilities to prevent invalid inputs from reaching
+ * cryptographic operations or blockchain transactions.
+ */
+
+import { Hex } from "viem";
+
+/**
+ * Validation utilities for savings operations
+ */
+export class SavingsValidation {
+    /**
+     * Validate BIP-44 account index
+     *
+     * @param index - Account index to validate
+     * @throws Error if index is invalid
+     *
+     * @remarks
+     * BIP-44 account indices must be:
+     * - Integer values
+     * - Non-negative
+     * - Less than or equal to 2^31-1 (0x7FFFFFFF)
+     *
+     * @example
+     * ```typescript
+     * SavingsValidation.validateAccountIndex(0);     // ✓ Valid
+     * SavingsValidation.validateAccountIndex(100);   // ✓ Valid
+     * SavingsValidation.validateAccountIndex(-1);    // ✗ Throws error
+     * SavingsValidation.validateAccountIndex(2.5);   // ✗ Throws error
+     * ```
+     */
+    static validateAccountIndex(index: number): void {
+        if (!Number.isInteger(index)) {
+            throw new Error(`Account index must be an integer, got: ${index}`);
+        }
+        if (index < 0) {
+            throw new Error(`Account index must be non-negative, got: ${index}`);
+        }
+        if (index > 0x7FFFFFFF) { // BIP-44 max hardened index (2^31-1)
+            throw new Error(`Account index exceeds BIP-44 maximum (2147483647), got: ${index}`);
+        }
+    }
+
+    /**
+     * Validate wallet index
+     *
+     * @param index - Wallet index to validate
+     * @throws Error if index is invalid
+     */
+    static validateWalletIndex(index: number): void {
+        if (!Number.isInteger(index)) {
+            throw new Error(`Wallet index must be an integer, got: ${index}`);
+        }
+        if (index < 0) {
+            throw new Error(`Wallet index must be non-negative, got: ${index}`);
+        }
+        if (index > 0x7FFFFFFF) {
+            throw new Error(`Wallet index exceeds maximum (2147483647), got: ${index}`);
+        }
+    }
+
+    /**
+     * Validate amount (bigint)
+     *
+     * @param amount - Amount to validate
+     * @param label - Label for error message (default: "Amount")
+     * @throws Error if amount is invalid
+     *
+     * @example
+     * ```typescript
+     * SavingsValidation.validateAmount(1000n, 'Transfer amount');  // ✓ Valid
+     * SavingsValidation.validateAmount(0n, 'Transfer amount');     // ✗ Throws error
+     * SavingsValidation.validateAmount(-100n, 'Transfer amount');  // ✗ Throws error
+     * ```
+     */
+    static validateAmount(amount: bigint, label: string = 'Amount'): void {
+        if (typeof amount !== 'bigint') {
+            throw new Error(`${label} must be a bigint, got: ${typeof amount}`);
+        }
+        if (amount <= 0n) {
+            throw new Error(`${label} must be positive, got: ${amount}`);
+        }
+    }
+
+    /**
+     * Validate Ethereum address format
+     *
+     * @param address - Address to validate
+     * @param label - Label for error message (default: "Address")
+     * @throws Error if address format is invalid
+     *
+     * @example
+     * ```typescript
+     * SavingsValidation.validateAddress('0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb');  // ✓ Valid
+     * SavingsValidation.validateAddress('0xinvalid');                                   // ✗ Throws error
+     * SavingsValidation.validateAddress('742d35Cc6634C0532925a3b844Bc9e7595f0bEb');    // ✗ Throws error (no 0x)
+     * ```
+     */
+    static validateAddress(address: string, label: string = 'Address'): void {
+        if (typeof address !== 'string') {
+            throw new Error(`${label} must be a string, got: ${typeof address}`);
+        }
+        if (!/^0x[a-fA-F0-9]{40}$/.test(address)) {
+            throw new Error(`${label} has invalid format. Expected 0x followed by 40 hex characters, got: ${address}`);
+        }
+    }
+
+    /**
+     * Validate mnemonic phrase
+     *
+     * @param mnemonic - Mnemonic to validate
+     * @throws Error if mnemonic is invalid
+     *
+     * @remarks
+     * Performs basic validation:
+     * - Must be a non-empty string
+     * - Must have 12, 15, 18, 21, or 24 words (BIP-39 standard)
+     * - Does NOT validate checksum (implementer should use bip39 library for that)
+     */
+    static validateMnemonic(mnemonic: string): void {
+        if (typeof mnemonic !== 'string') {
+            throw new Error(`Mnemonic must be a string, got: ${typeof mnemonic}`);
+        }
+
+        const trimmed = mnemonic.trim();
+        if (trimmed.length === 0) {
+            throw new Error('Mnemonic cannot be empty');
+        }
+
+        const words = trimmed.split(/\s+/);
+        const validWordCounts = [12, 15, 18, 21, 24];
+
+        if (!validWordCounts.includes(words.length)) {
+            throw new Error(
+                `Mnemonic must have 12, 15, 18, 21, or 24 words (BIP-39 standard), got: ${words.length} words`
+            );
+        }
+    }
+
+    /**
+     * Validate chain ID
+     *
+     * @param chainId - Chain ID to validate
+     * @throws Error if chain ID is invalid
+     */
+    static validateChainId(chainId: number): void {
+        if (!Number.isInteger(chainId)) {
+            throw new Error(`Chain ID must be an integer, got: ${chainId}`);
+        }
+        if (chainId <= 0) {
+            throw new Error(`Chain ID must be positive, got: ${chainId}`);
+        }
+    }
+
+    /**
+     * Validate string amount (for parsing)
+     *
+     * @param amount - String amount to validate
+     * @param label - Label for error message
+     * @throws Error if amount string is invalid
+     */
+    static validateAmountString(amount: string, label: string = 'Amount'): void {
+        if (typeof amount !== 'string') {
+            throw new Error(`${label} must be a string, got: ${typeof amount}`);
+        }
+
+        const trimmed = amount.trim();
+        if (trimmed.length === 0) {
+            throw new Error(`${label} cannot be empty`);
+        }
+
+        // Check if it's a valid number string
+        if (!/^-?\d+(\.\d+)?$/.test(trimmed)) {
+            throw new Error(`${label} has invalid format, got: ${amount}`);
+        }
+
+        const parsed = parseFloat(trimmed);
+        if (isNaN(parsed)) {
+            throw new Error(`${label} cannot be parsed as number, got: ${amount}`);
+        }
+        if (parsed <= 0) {
+            throw new Error(`${label} must be positive, got: ${amount}`);
+        }
+    }
+}