@deserialize/multi-vm-wallet 1.3.1 → 1.3.3

package/utils/savings/savings-manager.ts

@@ -0,0 +1,271 @@
+/**
+ * Savings Manager
+ *
+ * Core logic for managing BIP-44 derived savings accounts.
+ * Provides security-first operations that always derive addresses from account indices.
+ *
+ * Security Model:
+ * - NEVER trust stored addresses without verification
+ * - ALWAYS derive addresses from accountIndex for transactions
+ * - Provide verification and audit tools for tamper detection
+ */
+
+import { Hex } from "viem";
+import { EVMVM } from "../evm/evm";
+import { SVMVM } from "../svm/svm";
+import { VM } from "../vm";
+import {
+    SavingsAccount,
+    AddressVerificationResult,
+    SavingsAuditResult,
+    TransferToSavingsOptions,
+    WithdrawFromSavingsOptions
+} from "./types";
+
+// ============================================
+// SavingsManager Class
+// ============================================
+
+/**
+ * Manages BIP-44 derived savings accounts
+ *
+ * This class provides:
+ * 1. Account derivation from BIP-44 account indices
+ * 2. Address verification to prevent database tampering
+ * 3. Transaction builders for deposits and withdrawals
+ * 4. Batch auditing of stored addresses
+ */
+export class SavingsManager {
+    private vm: VM<any, any, any>;
+
+    constructor(vm: VM<any, any, any>) {
+        this.vm = vm;
+    }
+
+    /**
+     * Create a new savings account by deriving from account index
+     *
+     * @param accountIndex - BIP-44 account index (1+ for savings, 0 is main wallet)
+     * @returns SavingsAccount with derived private key and address
+     *
+     * @example
+     * const savingsAccount = manager.createSavingsAccount(1); // First savings account
+     * console.log(savingsAccount.address); // Derived address
+     * console.log(savingsAccount.derivationPath); // m/44'/60'/1'/0/0
+     */
+    createSavingsAccount(accountIndex: number): SavingsAccount {
+        if (accountIndex < 0) {
+            throw new Error("Account index must be non-negative");
+        }
+
+        const derived = this.vm.deriveSavingsAccount(accountIndex);
+
+        // For EVM, the address is a string (Hex)
+        // For SVM, the address is a PublicKey
+        let addressHex: Hex;
+        let privateKeyHex: Hex;
+
+        if (this.vm instanceof EVMVM) {
+            addressHex = derived.address as Hex;
+            privateKeyHex = (derived.privateKey as string).startsWith('0x')
+                ? derived.privateKey as Hex
+                : `0x${derived.privateKey}` as Hex;
+        } else if (this.vm instanceof SVMVM) {
+            // For SVM, convert PublicKey to base58 string
+            addressHex = derived.address.toBase58() as Hex;
+            // For SVM, convert Keypair secret key to hex
+            const keypair = derived.privateKey as any;
+            privateKeyHex = `0x${Buffer.from(keypair.secretKey).toString('hex')}` as Hex;
+        } else {
+            throw new Error("Unsupported VM type");
+        }
+
+        return {
+            accountIndex,
+            privateKey: privateKeyHex,
+            address: addressHex,
+            derivationPath: derived.derivationPath
+        };
+    }
+
+    /**
+     * Verify a stored address matches the derived address for an account index
+     *
+     * Security: This prevents database tampering attacks where an attacker
+     * modifies stored addresses to redirect funds.
+     *
+     * @param accountIndex - The account index to verify
+     * @param storedAddress - The address from storage/database
+     * @returns Verification result with validity flag and details
+     *
+     * @example
+     * const result = manager.verifySavingsAddress(1, storedAddress);
+     * if (!result.isValid) {
+     *     console.error("Address mismatch! Possible tampering:", result.error);
+     * }
+     */
+    verifySavingsAddress(accountIndex: number, storedAddress: Hex): AddressVerificationResult {
+        try {
+            const derived = this.createSavingsAccount(accountIndex);
+
+            const isValid = derived.address.toLowerCase() === storedAddress.toLowerCase();
+
+            return {
+                accountIndex,
+                storedAddress,
+                derivedAddress: derived.address,
+                isValid,
+                error: isValid ? undefined : "Address mismatch - stored address does not match derived address"
+            };
+        } catch (error: any) {
+            return {
+                accountIndex,
+                storedAddress,
+                derivedAddress: "0x0" as Hex,
+                isValid: false,
+                error: `Verification failed: ${error.message}`
+            };
+        }
+    }
+
+    /**
+     * Audit multiple savings addresses at once
+     *
+     * Useful for batch verification of all stored savings addresses.
+     *
+     * @param addresses - Map of accountIndex to stored address
+     * @returns Audit result with summary and per-address details
+     *
+     * @example
+     * const addresses = new Map([
+     *     [1, "0xabc..."],
+     *     [2, "0xdef..."]
+     * ]);
+     * const audit = manager.auditSavingsAddresses(addresses);
+     * console.log(`Valid: ${audit.valid}/${audit.total}`);
+     */
+    auditSavingsAddresses(addresses: Map<number, Hex>): SavingsAuditResult {
+        const results: AddressVerificationResult[] = [];
+
+        for (const [accountIndex, storedAddress] of addresses.entries()) {
+            const result = this.verifySavingsAddress(accountIndex, storedAddress);
+            results.push(result);
+        }
+
+        const valid = results.filter(r => r.isValid).length;
+        const invalid = results.filter(r => !r.isValid).length;
+
+        return {
+            total: results.length,
+            valid,
+            invalid,
+            allValid: invalid === 0,
+            results,
+            timestamp: new Date()
+        };
+    }
+
+    /**
+     * Build transaction parameters for depositing to savings
+     *
+     * Security: Always derives the destination address from accountIndex.
+     * Optional expectedAddress parameter allows tamper detection.
+     *
+     * @param accountIndex - Savings account to deposit to
+     * @param amount - Amount to transfer (in base units)
+     * @param options - Optional security and priority settings
+     * @returns Transaction parameters (to, value, data)
+     *
+     * @example
+     * const txParams = manager.buildDepositTransaction(1, parseEther("1.0"), {
+     *     expectedAddress: storedAddress // Verify it matches derived
+     * });
+     */
+    buildDepositTransaction(
+        accountIndex: number,
+        amount: bigint,
+        options?: TransferToSavingsOptions
+    ): { to: Hex; value: bigint; data?: Hex } {
+        const savingsAccount = this.createSavingsAccount(accountIndex);
+
+        // Security check: if expectedAddress provided, verify it matches
+        if (options?.expectedAddress) {
+            const verification = this.verifySavingsAddress(accountIndex, options.expectedAddress);
+            if (!verification.isValid) {
+                throw new Error(
+                    `Security check failed: Expected address ${options.expectedAddress} ` +
+                    `does not match derived address ${savingsAccount.address}. ` +
+                    `Possible database tampering detected.`
+                );
+            }
+        }
+
+        return {
+            to: savingsAccount.address,
+            value: amount,
+            data: undefined // Simple native transfer
+        };
+    }
+
+    /**
+     * Build transaction parameters for withdrawing from savings
+     *
+     * Security: Uses the derived private key for signing.
+     * Optional expectedAddress parameter verifies the source address.
+     *
+     * @param accountIndex - Savings account to withdraw from
+     * @param to - Destination address
+     * @param amount - Amount to transfer (in base units)
+     * @param options - Optional security and priority settings
+     * @returns Transaction parameters and private key for signing
+     *
+     * @example
+     * const { privateKey, tx } = manager.buildWithdrawalTransaction(
+     *     1, destinationAddress, parseEther("0.5")
+     * );
+     * // Use privateKey to sign the transaction
+     */
+    buildWithdrawalTransaction(
+        accountIndex: number,
+        to: Hex,
+        amount: bigint,
+        options?: WithdrawFromSavingsOptions
+    ): { privateKey: Hex; from: Hex; to: Hex; value: bigint; data?: Hex } {
+        const savingsAccount = this.createSavingsAccount(accountIndex);
+
+        // Security check: if expectedAddress provided, verify it matches
+        if (options?.expectedAddress) {
+            const verification = this.verifySavingsAddress(accountIndex, options.expectedAddress);
+            if (!verification.isValid) {
+                throw new Error(
+                    `Security check failed: Expected address ${options.expectedAddress} ` +
+                    `does not match derived address ${savingsAccount.address}. ` +
+                    `Possible database tampering detected.`
+                );
+            }
+        }
+
+        return {
+            privateKey: savingsAccount.privateKey,
+            from: savingsAccount.address,
+            to,
+            value: amount,
+            data: undefined // Simple native transfer
+        };
+    }
+
+    /**
+     * Get savings account details without exposing private key
+     *
+     * @param accountIndex - The account index
+     * @returns Public account information (address and derivation path only)
+     */
+    getSavingsAccountInfo(accountIndex: number): Omit<SavingsAccount, 'privateKey'> {
+        const account = this.createSavingsAccount(accountIndex);
+        return {
+            accountIndex: account.accountIndex,
+            address: account.address,
+            derivationPath: account.derivationPath
+        };
+    }
+}

package/utils/savings/smart-savings.ts

@@ -0,0 +1,184 @@
+/**
+ * Smart Savings Manager
+ *
+ * Handles upgrading savings accounts to EIP-7702 smart accounts.
+ * Enables advanced features like locked savings, spend & save, and periodic savings.
+ *
+ * Architecture:
+ * 1. Take a basic SavingsAccount (BIP-44 derived)
+ * 2. Create an EVMSmartWallet instance from its private key
+ * 3. Initialize with EIP-7702 delegation
+ * 4. Return a SmartSavingsAccount with full AA capabilities
+ */
+
+import { Chain } from "viem/chains";
+import { EVMSmartWallet } from "../evm/smartWallet";
+import { SmartWalletOptions } from "../evm/aa-service";
+import { ChainWalletConfig } from "../types";
+import { SavingsAccount, SmartSavingsAccount } from "./types";
+
+// ============================================
+// SmartSavingsManager Class
+// ============================================
+
+/**
+ * Manages EIP-7702 smart savings accounts
+ *
+ * This class provides:
+ * 1. Upgrade from basic savings account to smart account
+ * 2. Full Account Abstraction capabilities
+ * 3. Access to Kernel modules (lock, hooks, session keys)
+ * 4. Sponsored transactions via paymaster
+ */
+export class SmartSavingsManager {
+    private chainConfig: ChainWalletConfig;
+
+    constructor(chainConfig: ChainWalletConfig) {
+        this.chainConfig = chainConfig;
+
+        // Validate AA support
+        if (!chainConfig.aaSupport?.enabled) {
+            throw new Error(
+                "Smart savings requires Account Abstraction (AA) support.\n" +
+                "Your chain config must include aaSupport configuration with:\n" +
+                "- bundlerUrl\n" +
+                "- entryPoints\n" +
+                "- kernelImplementations"
+            );
+        }
+    }
+
+    /**
+     * Upgrade a savings account to a smart account with EIP-7702 delegation
+     *
+     * This enables advanced features:
+     * - Lock modules for time-locked savings
+     * - Hooks for spend & save
+     * - Session keys for periodic savings
+     * - Sponsored transactions via paymaster
+     *
+     * @param savingsAccount - The basic savings account to upgrade
+     * @param options - Optional smart wallet configuration
+     * @returns SmartSavingsAccount with EVMSmartWallet instance
+     *
+     * @example
+     * const basicSavings = wallet.deriveSavingsAccount(1);
+     * const smartSavings = await smartSavingsManager.upgradeSavingsToSmartAccount(basicSavings);
+     * await smartSavings.smartWallet.installModule({ ... });
+     */
+    async upgradeSavingsToSmartAccount(
+        savingsAccount: SavingsAccount,
+        options?: SmartWalletOptions
+    ): Promise<SmartSavingsAccount> {
+        // Merge options with chain config
+        const mergedOptions: SmartWalletOptions = {
+            ...options,
+            aaConfig: this.chainConfig.aaSupport,
+            bundlerUrl: options?.bundlerUrl || this.chainConfig.aaSupport?.bundlerUrl,
+            paymasterUrl: options?.paymasterUrl || this.chainConfig.aaSupport?.paymasterUrl,
+            entryPointVersion: options?.entryPointVersion || this.chainConfig.aaSupport?.entryPoints?.[0]?.version
+        };
+
+        // Validate bundlerUrl
+        if (!mergedOptions.bundlerUrl) {
+            throw new Error(
+                "bundlerUrl is required for smart savings.\n" +
+                "Provide it via upgradeSavingsToSmartAccount options or chain config."
+            );
+        }
+
+        // Create viem chain object
+        const chain: Chain = {
+            id: this.chainConfig.chainId,
+            name: this.chainConfig.name,
+            nativeCurrency: {
+                name: this.chainConfig.nativeToken.name,
+                symbol: this.chainConfig.nativeToken.symbol,
+                decimals: this.chainConfig.nativeToken.decimals
+            },
+            rpcUrls: {
+                default: {
+                    http: [this.chainConfig.rpcUrl]
+                }
+            },
+            blockExplorers: {
+                default: {
+                    name: this.chainConfig.name + " Explorer",
+                    url: this.chainConfig.explorerUrl
+                }
+            },
+            testnet: this.chainConfig.testnet || false
+        };
+
+        // Create EVMSmartWallet instance from savings account private key
+        const smartWallet = new EVMSmartWallet(
+            savingsAccount.privateKey,
+            chain,
+            mergedOptions
+        );
+
+        // Note: Initialization (createAuthorization) is optional
+        // User can call smartWallet.initialize() separately if needed
+        // For now, we return uninitialized smart wallet
+        const isInitialized = false;
+
+        return {
+            ...savingsAccount,
+            smartWallet,
+            isInitialized
+        };
+    }
+
+    /**
+     * Upgrade and initialize a savings account in one step
+     *
+     * This is a convenience method that both upgrades and initializes.
+     *
+     * @param savingsAccount - The basic savings account to upgrade
+     * @param options - Optional smart wallet configuration
+     * @returns Initialized SmartSavingsAccount ready for transactions
+     *
+     * @example
+     * const basicSavings = wallet.deriveSavingsAccount(1);
+     * const smartSavings = await smartSavingsManager.upgradeSavingsAndInitialize(basicSavings);
+     * // smartSavings is now ready for smart transactions
+     */
+    async upgradeSavingsAndInitialize(
+        savingsAccount: SavingsAccount,
+        options?: SmartWalletOptions
+    ): Promise<SmartSavingsAccount> {
+        // First upgrade
+        const smartSavings = await this.upgradeSavingsToSmartAccount(savingsAccount, options);
+
+        // Then initialize
+        await smartSavings.smartWallet.initialize();
+
+        // Update initialization status
+        smartSavings.isInitialized = true;
+
+        return smartSavings;
+    }
+
+    /**
+     * Check if a savings account can be upgraded to smart account
+     *
+     * @returns true if chain supports AA and has required configuration
+     */
+    canUpgradeToSmartAccount(): boolean {
+        return !!(
+            this.chainConfig.aaSupport?.enabled &&
+            this.chainConfig.aaSupport?.bundlerUrl &&
+            this.chainConfig.aaSupport?.entryPoints &&
+            this.chainConfig.aaSupport?.entryPoints.length > 0
+        );
+    }
+
+    /**
+     * Get the chain configuration
+     *
+     * @returns ChainWalletConfig
+     */
+    getChainConfig(): ChainWalletConfig {
+        return this.chainConfig;
+    }
+}

package/utils/savings/types.ts

@@ -0,0 +1,135 @@
+/**
+ * Savings Pocket Types
+ *
+ * Type definitions for the savings pocket feature that allows users to create
+ * multiple savings accounts derived from their seed phrase using BIP-44 account indices.
+ */
+
+import { Hex } from "viem";
+import { EVMSmartWallet } from "../evm/smartWallet";
+
+/**
+ * Savings account derived from BIP-44 account index
+ */
+export interface SavingsAccount {
+    /** Account index used for derivation (m/44'/60'/accountIndex'/0/0) */
+    accountIndex: number;
+    /** Derived private key for this savings account */
+    privateKey: Hex;
+    /** Derived address for this savings account */
+    address: Hex;
+    /** Full BIP-44 derivation path */
+    derivationPath: string;
+}
+
+/**
+ * Savings account upgraded to EIP-7702 smart account
+ */
+export interface SmartSavingsAccount extends SavingsAccount {
+    /** Smart wallet instance for advanced features */
+    smartWallet: EVMSmartWallet;
+    /** Whether the account has been initialized on-chain */
+    isInitialized: boolean;
+}
+
+/**
+ * Options for transferring to savings
+ */
+export interface TransferToSavingsOptions {
+    /** Expected address for verification (prevents tampering) */
+    expectedAddress?: Hex;
+    /** Transaction priority for gas estimation */
+    priority?: 'low' | 'medium' | 'high';
+    /** Whether to use smart account features (requires 7702 upgrade) */
+    useSmartAccount?: boolean;
+}
+
+/**
+ * Options for withdrawing from savings
+ */
+export interface WithdrawFromSavingsOptions {
+    /** Expected source address for verification */
+    expectedAddress?: Hex;
+    /** Transaction priority */
+    priority?: 'low' | 'medium' | 'high';
+    /** Whether to use smart account features */
+    useSmartAccount?: boolean;
+}
+
+/**
+ * Result of address verification
+ */
+export interface AddressVerificationResult {
+    /** Account index that was verified */
+    accountIndex: number;
+    /** Stored address that was checked */
+    storedAddress: Hex;
+    /** Derived address from account index */
+    derivedAddress: Hex;
+    /** Whether addresses match */
+    isValid: boolean;
+    /** Error message if invalid */
+    error?: string;
+}
+
+/**
+ * Result of batch address audit
+ */
+export interface SavingsAuditResult {
+    /** Total number of addresses audited */
+    total: number;
+    /** Number of valid addresses */
+    valid: number;
+    /** Number of invalid addresses */
+    invalid: number;
+    /** Whether all addresses are valid */
+    allValid: boolean;
+    /** Detailed results per address */
+    results: AddressVerificationResult[];
+    /** Timestamp of audit */
+    timestamp: Date;
+}
+
+/**
+ * Lock module configuration for locked savings
+ */
+export interface LockModuleConfig {
+    /** Lock duration in seconds */
+    lockDuration: number;
+    /** Lock end timestamp (computed) */
+    lockedUntil: number;
+    /** Whether early withdrawal is allowed with penalty */
+    allowEarlyWithdrawal?: boolean;
+    /** Penalty percentage for early withdrawal (0-100) */
+    earlyWithdrawalPenalty?: number;
+}
+
+/**
+ * Periodic savings session configuration
+ */
+export interface PeriodicSavingsConfig {
+    /** Amount to save each period */
+    amount: number;
+    /** Savings frequency */
+    frequency: 'daily' | 'weekly' | 'monthly';
+    /** Destination account index */
+    savingsAccountIndex: number;
+    /** Optional end date for recurring savings */
+    endDate?: Date;
+    /** Maximum number of executions */
+    maxExecutions?: number;
+}
+
+/**
+ * Spend and save hook configuration
+ */
+export interface SpendAndSaveConfig {
+    /** Percentage of spending to save (0-100) */
+    savePercentage: number;
+    /** Destination savings account index */
+    savingsAccountIndex: number;
+    /** Minimum transaction amount to trigger saving */
+    minTransactionAmount?: number;
+    /** Maximum amount to save per transaction */
+    maxSaveAmount?: number;
+}

package/utils/svm/svm.ts

@@ -2,7 +2,7 @@ import { Connection, Keypair, PublicKey, Transaction, VersionedTransaction } fro
 import { SVMDeriveChildPrivateKey } from "../walletBip32";
 import { VM } from "../vm";
 import { ChainWallet } from "../IChainWallet";
-import { Balance, ChainWalletConfig, UserTokenBalance, TokenInfo, TransactionResult, NFT, FeePayerOptions } from "../types";
+import { Balance, ChainWalletConfig, UserTokenBalance, TokenInfo, TransactionResult, NFT } from "../types";
 import {
     getSvmNativeBalance,
     getTokenBalance,
@@ -76,6 +76,33 @@ export class SVMVM extends VM<PublicKey, Keypair, Connection> {
         const privateKey = SVMDeriveChildPrivateKey(_seed, index, derivationPath);
         return { privateKey, index };
     }
+
+    /**
+     * Derive a savings account using BIP-44 account index
+     *
+     * Uses the pattern: m/44'/501'/accountIndex'/0/0
+     * - Main wallet: m/44'/501'/0'/0/0 (account index 0)
+     * - Savings 1: m/44'/501'/1'/0/0 (account index 1)
+     * - Savings 2: m/44'/501'/2'/0/0 (account index 2)
+     *
+     * @param accountIndex - The BIP-44 account index (0 for main, 1+ for savings)
+     * @returns Object containing privateKey (Keypair), address (PublicKey), and derivation path
+     */
+    deriveSavingsAccount(accountIndex: number): { privateKey: Keypair; address: PublicKey; derivationPath: string } {
+        // Use fixed address index 0 for savings accounts
+        // Vary only the account index (3rd position in BIP-44)
+        const derivationPath = `m/44'/501'/${accountIndex}'/0/0`;
+
+        // Derive the keypair using the account index in the path
+        const keypair = SVMDeriveChildPrivateKey(this.seed, 0, `m/44'/501'/${accountIndex}'/0/`);
+
+        return {
+            privateKey: keypair,
+            address: keypair.publicKey,
+            derivationPath
+        };
+    }
+
     static fromMnemonic(mnemonic: string): VM<PublicKey, Keypair, Connection> {
         const seed = VM.mnemonicToSeed(mnemonic)
         return new SVMVM(seed)
@@ -117,56 +144,38 @@ export class SVMChainWallet extends ChainWallet<PublicKey, Keypair, Connection>
         return nfts
     }
 
-    async transferNative(to: PublicKey, amount: number, feePayerOptions?: FeePayerOptions): Promise<TransactionResult> {
+    async transferNative(to: PublicKey, amount: number): Promise<TransactionResult> {
         // Implement native transfer logic here
-        let feePayerKeypair: Keypair | undefined;
-
-        if (feePayerOptions) {
-            // Convert feePayer private key to Keypair
-            feePayerKeypair = Keypair.fromSecretKey(base58.decode(feePayerOptions.privateKey));
-        }
-
         const transaction = await getTransferNativeTransaction(
             this.privateKey,
             to,
             amount,
-            this.connection!,
-            feePayerKeypair
+            this.connection!
         );
 
         const hash = await SVMVM.signAndSendTransaction(
             transaction,
             this.connection!,
-            this.privateKey,
-            feePayerKeypair ? { feePayerSigner: feePayerKeypair } : undefined
+            this.privateKey
         );
 
         return { success: true, hash };
     }
 
-    async transferToken(token: TokenInfo, to: PublicKey, amount: number, feePayerOptions?: FeePayerOptions): Promise<TransactionResult> {
+    async transferToken(token: TokenInfo, to: PublicKey, amount: number): Promise<TransactionResult> {
         // Implement token transfer logic here
-        let feePayerKeypair: Keypair | undefined;
-
-        if (feePayerOptions) {
-            // Convert feePayer private key to Keypair
-            feePayerKeypair = Keypair.fromSecretKey(base58.decode(feePayerOptions.privateKey));
-        }
-
         const transaction = await getTransferTokenTransaction(
             this.privateKey,
             new PublicKey(to),
             token,
             amount,
-            this.connection!,
-            feePayerKeypair
+            this.connection!
         );
 
         const hash = await SVMVM.signAndSendTransaction(
             transaction,
             this.connection!,
-            this.privateKey,
-            feePayerKeypair ? { feePayerSigner: feePayerKeypair } : undefined
+            this.privateKey
         );
 
         return { success: true, hash };