@deserialize/multi-vm-wallet 1.5.11 → 1.5.21

package/utils/savings/multi-chain-savings.ts

@@ -0,0 +1,458 @@
+/**
+ * Multi-Chain Savings Manager
+ *
+ * Orchestrates savings across multiple blockchain networks (EVM and Solana)
+ * Provides unified interface for managing savings pockets across chains
+ */
+
+import { EVMSavingsManager } from "./evm-savings";
+import { SVMSavingsManager } from "./svm-savings";
+import { ChainWalletConfig, Balance } from "../types";
+import { Hex } from "viem";
+import { PublicKey } from "@solana/web3.js";
+
+/**
+ * Chain type identifier
+ */
+export type ChainType = 'EVM' | 'SVM';
+
+/**
+ * Chain configuration for multi-chain manager
+ */
+export interface ChainConfig {
+    /** Unique identifier for the chain (e.g., "ethereum", "polygon", "solana") */
+    id: string;
+    /** Chain type (EVM or SVM) */
+    type: ChainType;
+    /** Chain-specific configuration */
+    config: ChainWalletConfig | { rpcUrl: string };
+}
+
+/**
+ * Pocket balance information for a specific chain
+ */
+export interface PocketBalance {
+    /** Chain identifier */
+    chainId: string;
+    /** Chain type */
+    chainType: ChainType;
+    /** Pocket index */
+    pocketIndex: number;
+    /** Pocket address (string format for compatibility) */
+    address: string;
+    /** Token balances */
+    balances: {
+        /** Token address or 'native' */
+        token: string;
+        /** Balance information */
+        balance: Balance;
+    }[];
+}
+
+/**
+ * Multi-Chain Savings Manager
+ *
+ * Manages savings pockets across multiple blockchain networks.
+ * - EVM chains (Ethereum, Polygon, BSC, etc.) share the same addresses (coin type 60)
+ * - Solana has different addresses (coin type 501)
+ *
+ * @example
+ * ```typescript
+ * const manager = new MultiChainSavingsManager(
+ *   mnemonic,
+ *   [
+ *     { id: 'ethereum', type: 'EVM', config: ethConfig },
+ *     { id: 'polygon', type: 'EVM', config: polyConfig },
+ *     { id: 'solana', type: 'SVM', config: { rpcUrl: '...' } }
+ *   ],
+ *   0  // wallet index
+ * );
+ *
+ * // Get pocket address on Ethereum
+ * const ethAddress = manager.getPocketAddress('ethereum', 0);
+ *
+ * // Get pocket address on Polygon (same as Ethereum!)
+ * const polyAddress = manager.getPocketAddress('polygon', 0);
+ * console.log(ethAddress === polyAddress); // true
+ *
+ * // Get balances across all chains
+ * const balances = await manager.getPocketBalanceAcrossChains(0, tokensByChain);
+ * ```
+ */
+export class MultiChainSavingsManager {
+    private mnemonic: string;
+    private walletIndex: number;
+
+    // Separate managers by chain type
+    private evmManagers: Map<string, EVMSavingsManager> = new Map();
+    private svmManagers: Map<string, SVMSavingsManager> = new Map();
+
+    // Track chain configs
+    private chainConfigs: Map<string, ChainConfig> = new Map();
+
+    /**
+     * Create a new MultiChainSavingsManager
+     *
+     * @param mnemonic - BIP-39 mnemonic phrase
+     * @param chains - Array of chain configurations
+     * @param walletIndex - Wallet index in derivation path (default: 0)
+     */
+    constructor(
+        mnemonic: string,
+        chains: ChainConfig[],
+        walletIndex: number = 0
+    ) {
+        if (!mnemonic || typeof mnemonic !== 'string') {
+            throw new Error('Mnemonic must be a non-empty string');
+        }
+        if (!Array.isArray(chains) || chains.length === 0) {
+            throw new Error('Chains array must be non-empty');
+        }
+
+        this.mnemonic = mnemonic;
+        this.walletIndex = walletIndex;
+
+        // Initialize managers for each chain
+        for (const chain of chains) {
+            this.addChain(chain);
+        }
+    }
+
+    /**
+     * Add a new chain to the manager
+     *
+     * @param chain - Chain configuration
+     */
+    addChain(chain: ChainConfig): void {
+        if (!chain.id || !chain.type) {
+            throw new Error('Chain must have id and type');
+        }
+
+        if (this.chainConfigs.has(chain.id)) {
+            throw new Error(`Chain with id '${chain.id}' already exists`);
+        }
+
+        this.chainConfigs.set(chain.id, chain);
+
+        if (chain.type === 'EVM') {
+            const manager = new EVMSavingsManager(
+                this.mnemonic,
+                chain.config as ChainWalletConfig,
+                this.walletIndex
+            );
+            this.evmManagers.set(chain.id, manager);
+        } else if (chain.type === 'SVM') {
+            const config = chain.config as { rpcUrl: string };
+            if (!config.rpcUrl) {
+                throw new Error(`SVM chain '${chain.id}' must have rpcUrl in config`);
+            }
+            const manager = new SVMSavingsManager(
+                this.mnemonic,
+                config.rpcUrl,
+                this.walletIndex
+            );
+            this.svmManagers.set(chain.id, manager);
+        } else {
+            throw new Error(`Unknown chain type: ${chain.type}`);
+        }
+    }
+
+    /**
+     * Remove a chain from the manager
+     *
+     * @param chainId - Chain identifier to remove
+     */
+    removeChain(chainId: string): void {
+        if (this.evmManagers.has(chainId)) {
+            this.evmManagers.get(chainId)?.dispose();
+            this.evmManagers.delete(chainId);
+        }
+        if (this.svmManagers.has(chainId)) {
+            this.svmManagers.get(chainId)?.dispose();
+            this.svmManagers.delete(chainId);
+        }
+        this.chainConfigs.delete(chainId);
+    }
+
+    /**
+     * Get list of all chain IDs
+     *
+     * @returns Array of chain identifiers
+     */
+    getChains(): string[] {
+        return Array.from(this.chainConfigs.keys());
+    }
+
+    /**
+     * Get chain configuration
+     *
+     * @param chainId - Chain identifier
+     * @returns Chain configuration
+     */
+    getChainConfig(chainId: string): ChainConfig {
+        const config = this.chainConfigs.get(chainId);
+        if (!config) {
+            throw new Error(`Chain not found: ${chainId}`);
+        }
+        return config;
+    }
+
+    /**
+     * Get pocket address for a specific chain
+     *
+     * @param chainId - Chain identifier
+     * @param pocketIndex - Pocket index
+     * @returns Pocket address as string
+     */
+    getPocketAddress(chainId: string, pocketIndex: number): string {
+        const chain = this.getChainConfig(chainId);
+
+        if (chain.type === 'EVM') {
+            const manager = this.evmManagers.get(chainId)!;
+            return manager.getPocket(pocketIndex).address;
+        } else {
+            const manager = this.svmManagers.get(chainId)!;
+            return manager.getPocket(pocketIndex).address.toBase58();
+        }
+    }
+
+    /**
+     * Get main wallet address for a specific chain
+     *
+     * @param chainId - Chain identifier
+     * @returns Main wallet address as string
+     */
+    getMainWalletAddress(chainId: string): string {
+        const chain = this.getChainConfig(chainId);
+
+        if (chain.type === 'EVM') {
+            const manager = this.evmManagers.get(chainId)!;
+            return manager.getMainWalletAddress();
+        } else {
+            const manager = this.svmManagers.get(chainId)!;
+            return manager.getMainWalletAddress().toBase58();
+        }
+    }
+
+    /**
+     * Get pocket balance for a specific chain
+     *
+     * @param chainId - Chain identifier
+     * @param pocketIndex - Pocket index
+     * @param tokens - Array of token addresses to query
+     * @returns Pocket balance information
+     */
+    async getPocketBalance(
+        chainId: string,
+        pocketIndex: number,
+        tokens: string[]
+    ): Promise<PocketBalance> {
+        const chain = this.getChainConfig(chainId);
+
+        if (chain.type === 'EVM') {
+            const manager = this.evmManagers.get(chainId)!;
+            const balances = await manager.getPocketBalance(pocketIndex, tokens);
+            const pocket = manager.getPocket(pocketIndex);
+
+            return {
+                chainId,
+                chainType: 'EVM',
+                pocketIndex,
+                address: pocket.address,
+                balances: balances.map(b => ({
+                    token: b.address === 'native' ? 'native' : b.address,
+                    balance: b.balance
+                }))
+            };
+        } else {
+            const manager = this.svmManagers.get(chainId)!;
+            const balances = await manager.getPocketBalance(pocketIndex, tokens);
+            const pocket = manager.getPocket(pocketIndex);
+
+            return {
+                chainId,
+                chainType: 'SVM',
+                pocketIndex,
+                address: pocket.address.toBase58(),
+                balances: balances.map(b => ({
+                    token: b.address === 'native' ? 'native' : b.address.toBase58(),
+                    balance: b.balance
+                }))
+            };
+        }
+    }
+
+    /**
+     * Get pocket balance across multiple chains
+     *
+     * @param pocketIndex - Pocket index
+     * @param tokensByChain - Map of chain IDs to token addresses
+     * @returns Array of pocket balances per chain
+     */
+    async getPocketBalanceAcrossChains(
+        pocketIndex: number,
+        tokensByChain: Map<string, string[]>
+    ): Promise<PocketBalance[]> {
+        const promises: Promise<PocketBalance>[] = [];
+
+        for (const [chainId, tokens] of tokensByChain) {
+            promises.push(this.getPocketBalance(chainId, pocketIndex, tokens));
+        }
+
+        return await Promise.all(promises);
+    }
+
+    /**
+     * Get balances for multiple pockets across multiple chains
+     *
+     * @param pocketIndices - Array of pocket indices
+     * @param tokensByChain - Map of chain IDs to token addresses
+     * @returns Map of pocket indices to their balances across chains
+     */
+    async getAllPocketsBalanceAcrossChains(
+        pocketIndices: number[],
+        tokensByChain: Map<string, string[]>
+    ): Promise<Map<number, PocketBalance[]>> {
+        const results = new Map<number, PocketBalance[]>();
+
+        // Fetch all pockets in parallel
+        await Promise.all(
+            pocketIndices.map(async (pocketIndex) => {
+                const balances = await this.getPocketBalanceAcrossChains(
+                    pocketIndex,
+                    tokensByChain
+                );
+                results.set(pocketIndex, balances);
+            })
+        );
+
+        return results;
+    }
+
+    /**
+     * Get EVM manager for a chain (for advanced operations)
+     *
+     * @param chainId - Chain identifier
+     * @returns EVMSavingsManager instance
+     * @throws Error if chain is not EVM or not found
+     */
+    getEVMManager(chainId: string): EVMSavingsManager {
+        const manager = this.evmManagers.get(chainId);
+        if (!manager) {
+            throw new Error(`EVM chain not found: ${chainId}`);
+        }
+        return manager;
+    }
+
+    /**
+     * Get SVM manager for a chain (for advanced operations)
+     *
+     * @param chainId - Chain identifier
+     * @returns SVMSavingsManager instance
+     * @throws Error if chain is not SVM or not found
+     */
+    getSVMManager(chainId: string): SVMSavingsManager {
+        const manager = this.svmManagers.get(chainId);
+        if (!manager) {
+            throw new Error(`SVM chain not found: ${chainId}`);
+        }
+        return manager;
+    }
+
+    /**
+     * Check if a chain is EVM-compatible
+     *
+     * @param chainId - Chain identifier
+     * @returns true if chain is EVM
+     */
+    isEVMChain(chainId: string): boolean {
+        return this.evmManagers.has(chainId);
+    }
+
+    /**
+     * Check if a chain is Solana (SVM)
+     *
+     * @param chainId - Chain identifier
+     * @returns true if chain is SVM
+     */
+    isSVMChain(chainId: string): boolean {
+        return this.svmManagers.has(chainId);
+    }
+
+    /**
+     * Get all EVM chain IDs
+     *
+     * @returns Array of EVM chain identifiers
+     */
+    getEVMChains(): string[] {
+        return Array.from(this.evmManagers.keys());
+    }
+
+    /**
+     * Get all SVM chain IDs
+     *
+     * @returns Array of SVM chain identifiers
+     */
+    getSVMChains(): string[] {
+        return Array.from(this.svmManagers.keys());
+    }
+
+    /**
+     * Clear a specific pocket across all chains
+     *
+     * @param pocketIndex - Pocket index to clear
+     */
+    clearPocket(pocketIndex: number): void {
+        for (const manager of this.evmManagers.values()) {
+            manager.clearPocket(pocketIndex);
+        }
+        for (const manager of this.svmManagers.values()) {
+            manager.clearPocket(pocketIndex);
+        }
+    }
+
+    /**
+     * Clear all pockets across all chains
+     */
+    clearAllPockets(): void {
+        for (const manager of this.evmManagers.values()) {
+            manager.clearAllPockets();
+        }
+        for (const manager of this.svmManagers.values()) {
+            manager.clearAllPockets();
+        }
+    }
+
+    /**
+     * Clear all RPC clients across all chains
+     */
+    clearAllClients(): void {
+        for (const manager of this.evmManagers.values()) {
+            manager.clearClient();
+        }
+        for (const manager of this.svmManagers.values()) {
+            manager.clearClient();
+        }
+    }
+
+    /**
+     * Dispose all managers and clear all sensitive data
+     *
+     * @remarks
+     * After calling dispose(), this manager instance should not be used.
+     */
+    dispose(): void {
+        for (const manager of this.evmManagers.values()) {
+            manager.dispose();
+        }
+        for (const manager of this.svmManagers.values()) {
+            manager.dispose();
+        }
+
+        this.evmManagers.clear();
+        this.svmManagers.clear();
+        this.chainConfigs.clear();
+
+        (this as any).mnemonic = '';
+    }
+}

package/utils/savings/savings-manager.ts

@@ -0,0 +1,189 @@
+/**
+ * Abstract Base Savings Manager
+ *
+ * Base class for managing multi-pocket savings accounts across different chains.
+ * Similar to the VM<AddressType, PrivateKeyType, ConnectionType> pattern.
+ *
+ * @template AddressType - Address format (Hex for EVM, PublicKey for SVM)
+ * @template ClientType - RPC client type (PublicClient for EVM, Connection for SVM)
+ * @template WalletClientType - Wallet client type (WalletClient for EVM, Keypair for SVM)
+ */
+
+import { SavingsValidation } from "./validation";
+
+export interface Pocket<AddressType> {
+    privateKey: any;
+    address: AddressType;
+    derivationPath: string;
+    index: number;
+}
+
+/**
+ * Abstract base class for chain-specific savings managers
+ *
+ * Follows the same pattern as VM class:
+ * - Abstract base with generic types
+ * - Concrete implementations for each chain type (EVM, SVM)
+ * - Shared memory management and disposal patterns
+ */
+export abstract class SavingsManager<
+    AddressType,
+    ClientType,
+    WalletClientType
+> {
+    protected mnemonic: string;
+    protected walletIndex: number;
+    protected disposed: boolean = false;
+
+    // Abstract properties (must be implemented by subclasses)
+    abstract coinType: number;
+    abstract derivationPathBase: string;
+
+    // Pocket cache: Map<pocketIndex, Pocket>
+    protected pockets: Map<number, Pocket<AddressType>> = new Map();
+
+    /**
+     * Create a new SavingsManager
+     *
+     * @param mnemonic - BIP-39 mnemonic phrase
+     * @param walletIndex - Wallet index in derivation path (default: 0)
+     */
+    constructor(mnemonic: string, walletIndex: number = 0) {
+        SavingsValidation.validateMnemonic(mnemonic);
+        SavingsValidation.validateWalletIndex(walletIndex);
+
+        this.mnemonic = mnemonic;
+        this.walletIndex = walletIndex;
+    }
+
+    // Abstract methods (must be implemented by subclasses)
+
+    /**
+     * Derive a savings pocket at the specified account index
+     *
+     * @param accountIndex - Account index for the pocket (0-based)
+     * @returns Pocket object with privateKey, address, derivationPath, and index
+     */
+    abstract derivePocket(accountIndex: number): Pocket<AddressType>;
+
+    /**
+     * Get the main wallet credentials
+     *
+     * @returns Main wallet object with privateKey, address, and derivationPath
+     */
+    abstract getMainWallet(): {
+        privateKey: any;
+        address: AddressType;
+        derivationPath: string;
+    };
+
+    /**
+     * Create an RPC client for this chain
+     *
+     * @param rpcUrl - RPC endpoint URL
+     * @returns Chain-specific RPC client
+     */
+    abstract createClient(rpcUrl: string): ClientType;
+
+    // Shared methods (implemented in base class)
+
+    /**
+     * Get or create a savings pocket at the specified index
+     *
+     * @param accountIndex - The pocket index (0-based)
+     * @returns Pocket object
+     * @throws Error if validation fails or VM is disposed
+     */
+    getPocket(accountIndex: number): Pocket<AddressType> {
+        this.checkNotDisposed();
+        SavingsValidation.validateAccountIndex(accountIndex);
+
+        if (!this.pockets.has(accountIndex)) {
+            return this.derivePocket(accountIndex);
+        }
+        return this.pockets.get(accountIndex)!;
+    }
+
+    /**
+     * Clear a specific pocket's cached private key from memory
+     *
+     * @param accountIndex - Index of the pocket to clear
+     */
+    clearPocket(accountIndex: number): void {
+        SavingsValidation.validateAccountIndex(accountIndex);
+
+        if (this.pockets.has(accountIndex)) {
+            const pocket = this.pockets.get(accountIndex)!;
+
+            // Attempt to clear the private key
+            // Note: JavaScript strings are immutable, so this only clears our reference
+            (pocket as any).privateKey = '';
+
+            // Remove from cache
+            this.pockets.delete(accountIndex);
+        }
+    }
+
+    /**
+     * Clear all cached pocket private keys from memory
+     *
+     * @remarks
+     * Call this method when:
+     * - User locks the wallet
+     * - Application goes to background (mobile)
+     * - Extension popup closes (browser extension)
+     * - Session ends
+     */
+    clearAllPockets(): void {
+        for (const [_, pocket] of this.pockets.entries()) {
+            // Attempt to clear the private key
+            (pocket as any).privateKey = '';
+        }
+
+        // Clear the map
+        this.pockets.clear();
+    }
+
+    /**
+     * Clear all sensitive data from memory
+     *
+     * @remarks
+     * IMPORTANT: After calling dispose(), the manager instance should not be used.
+     * JavaScript strings are immutable, so this method can only clear references.
+     * The actual memory will be cleared by garbage collection.
+     */
+    dispose(): void {
+        if (this.disposed) {
+            return; // Already disposed
+        }
+
+        // Clear all cached pockets
+        this.clearAllPockets();
+
+        // Attempt to clear mnemonic
+        (this as any).mnemonic = '';
+
+        this.disposed = true;
+    }
+
+    /**
+     * Check if manager has been disposed
+     *
+     * @returns true if dispose() has been called
+     */
+    isDisposed(): boolean {
+        return this.disposed || !this.mnemonic || this.mnemonic === '';
+    }
+
+    /**
+     * Throw error if manager has been disposed
+     *
+     * @throws Error if manager is disposed
+     * @protected
+     */
+    protected checkNotDisposed(): void {
+        if (this.isDisposed()) {
+            throw new Error('SavingsManager has been disposed. Create a new instance to perform operations.');
+        }
+    }
+}