@deserialize/multi-vm-wallet 1.5.11 → 1.5.21

package/MULTI_CHAIN_SAVINGS_USAGE.md

@@ -0,0 +1,428 @@
+# Multi-Chain Savings Manager - Usage Guide
+
+**Status**: ✅ **Implementation Complete**
+**Date**: 2026-02-02
+
+---
+
+## 🎉 What's Been Implemented
+
+Following the same pattern as EVM/SVM VM classes, we've implemented a complete multi-chain savings manager system:
+
+### Files Created
+
+```
+utils/savings/
+├── savings-manager.ts       # Abstract base class
+├── evm-savings.ts           # EVM implementation (Ethereum, Polygon, BSC, etc.)
+├── svm-savings.ts           # Solana implementation
+├── multi-chain-savings.ts   # Multi-chain orchestrator
+└── index.ts                 # Updated exports
+```
+
+### Architecture
+
+```typescript
+// Abstract base (like VM class)
+abstract class SavingsManager<AddressType, ClientType, WalletClientType>
+
+↓
+
+// EVM implementation
+EVMSavingsManager extends SavingsManager<Hex, PublicClient, WalletClient>
+
+// Solana implementation
+SVMSavingsManager extends SavingsManager<PublicKey, Connection, Keypair>
+
+↓
+
+// Multi-chain orchestrator
+MultiChainSavingsManager (manages both EVM and SVM)
+```
+
+---
+
+## 📖 Usage Examples
+
+### Example 1: Single EVM Chain (Ethereum)
+
+```typescript
+import { EVMSavingsManager } from './utils/savings';
+
+const manager = new EVMSavingsManager(
+    mnemonic,
+    {
+        chainId: 1,
+        name: 'ethereum',
+        rpcUrl: 'https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY'
+    },
+    0  // wallet index
+);
+
+// Get pocket 0
+const pocket = manager.getPocket(0);
+console.log('Pocket address:', pocket.address);
+console.log('Derivation path:', pocket.derivationPath);
+
+// Get balances for pocket 0
+const balances = await manager.getPocketBalance(0, [
+    '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'  // USDC
+]);
+
+console.log('Native ETH:', balances[0].balance.formatted);
+console.log('USDC:', balances[1].balance.formatted);
+
+// Transfer 0.1 ETH to pocket 0
+await manager.transferToPocket(walletClient, 0, '0.1');
+
+// Transfer from pocket back to main wallet
+await manager.sendToMainWallet(0, 100000000n, 'native');
+
+// Cleanup
+manager.dispose();
+```
+
+---
+
+### Example 2: Solana (SVM)
+
+```typescript
+import { SVMSavingsManager } from './utils/savings';
+import { Keypair } from '@solana/web3.js';
+
+const manager = new SVMSavingsManager(
+    mnemonic,
+    'https://api.mainnet-beta.solana.com',
+    0  // wallet index
+);
+
+// Get pocket 0
+const pocket = manager.getPocket(0);
+console.log('Pocket address:', pocket.address.toBase58());
+console.log('Derivation path:', pocket.derivationPath);
+
+// Get balances for pocket 0
+const balances = await manager.getPocketBalance(0, [
+    'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'  // USDC on Solana
+]);
+
+console.log('Native SOL:', balances[0].balance.formatted);
+console.log('USDC:', balances[1].balance.formatted);
+
+// Transfer 1 SOL to pocket 0
+const mainWalletKeypair = manager.getMainWallet().privateKey;
+await manager.transferToPocket(mainWalletKeypair, 0, 1000000000n);  // 1 SOL
+
+// Transfer SPL token
+await manager.transferTokenToPocket(
+    mainWalletKeypair,
+    { address: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', decimals: 6 },
+    0,
+    1000000n  // 1 USDC
+);
+
+// Cleanup
+manager.dispose();
+```
+
+---
+
+### Example 3: Multi-Chain (The Full Power!)
+
+```typescript
+import { MultiChainSavingsManager } from './utils/savings';
+
+// Create manager with multiple chains
+const manager = new MultiChainSavingsManager(
+    mnemonic,
+    [
+        // EVM chains
+        {
+            id: 'ethereum',
+            type: 'EVM',
+            config: {
+                chainId: 1,
+                name: 'ethereum',
+                rpcUrl: 'https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY'
+            }
+        },
+        {
+            id: 'polygon',
+            type: 'EVM',
+            config: {
+                chainId: 137,
+                name: 'polygon',
+                rpcUrl: 'https://polygon-mainnet.g.alchemy.com/v2/YOUR_KEY'
+            }
+        },
+        {
+            id: 'bsc',
+            type: 'EVM',
+            config: {
+                chainId: 56,
+                name: 'bsc',
+                rpcUrl: 'https://bsc-dataseed1.binance.org'
+            }
+        },
+        // Solana
+        {
+            id: 'solana',
+            type: 'SVM',
+            config: {
+                rpcUrl: 'https://api.mainnet-beta.solana.com'
+            }
+        }
+    ],
+    0  // wallet index
+);
+
+// Get pocket addresses (notice EVM chains share addresses!)
+const ethAddress = manager.getPocketAddress('ethereum', 0);
+const polyAddress = manager.getPocketAddress('polygon', 0);
+const bscAddress = manager.getPocketAddress('bsc', 0);
+const solAddress = manager.getPocketAddress('solana', 0);
+
+console.log('Ethereum pocket 0:', ethAddress);
+console.log('Polygon pocket 0:', polyAddress);
+console.log('BSC pocket 0:', bscAddress);
+console.log('Solana pocket 0:', solAddress);
+
+console.log('ETH === Polygon?', ethAddress === polyAddress);  // true!
+console.log('ETH === BSC?', ethAddress === bscAddress);      // true!
+console.log('ETH === Solana?', ethAddress === solAddress);    // false (different chain)
+
+// Get balances across all chains for pocket 0
+const balances = await manager.getPocketBalanceAcrossChains(
+    0,  // pocket index
+    new Map([
+        ['ethereum', ['0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48']],  // USDC on Ethereum
+        ['polygon', ['0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174']],   // USDC on Polygon
+        ['bsc', ['0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d']],       // USDC on BSC
+        ['solana', ['EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v']]    // USDC on Solana
+    ])
+);
+
+// Display balances by chain
+balances.forEach(chainBalance => {
+    console.log(`\n${chainBalance.chainId.toUpperCase()}:`);
+    console.log(`  Address: ${chainBalance.address}`);
+    chainBalance.balances.forEach(bal => {
+        const tokenName = bal.token === 'native' ? 'Native' : 'USDC';
+        console.log(`  ${tokenName}: ${bal.balance.formatted}`);
+    });
+});
+
+// Get all pockets (0, 1, 2) balances across all chains
+const allBalances = await manager.getAllPocketsBalanceAcrossChains(
+    [0, 1, 2],  // pocket indices
+    new Map([
+        ['ethereum', ['0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48']],
+        ['polygon', ['0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174']],
+        ['solana', ['EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v']]
+    ])
+);
+
+// Display total across all pockets and chains
+for (const [pocketIndex, chainBalances] of allBalances) {
+    console.log(`\nPocket ${pocketIndex}:`);
+    chainBalances.forEach(cb => {
+        console.log(`  ${cb.chainId}: ${cb.balances.length} tokens`);
+    });
+}
+
+// Advanced: Get specific chain manager for direct operations
+const ethManager = manager.getEVMManager('ethereum');
+await ethManager.transferToPocket(ethWalletClient, 0, '0.1');
+
+const solManager = manager.getSVMManager('solana');
+await solManager.transferToPocket(solKeypair, 0, 1000000000n);
+
+// Cleanup all chains
+manager.dispose();
+```
+
+---
+
+## 🔑 Key Features
+
+### 1. EVM Address Sharing ✅
+All EVM-compatible chains (Ethereum, Polygon, BSC, Arbitrum, Optimism, etc.) share the same addresses because they all use BIP-44 coin type 60.
+
+```typescript
+// Same pocket, same address across all EVM chains
+const ethPocket = manager.getPocketAddress('ethereum', 0);
+const polyPocket = manager.getPocketAddress('polygon', 0);
+// ethPocket === polyPocket ✅
+```
+
+### 2. Solana Has Different Addresses ✅
+Solana uses BIP-44 coin type 501, so it generates different addresses.
+
+```typescript
+const ethPocket = manager.getPocketAddress('ethereum', 0);   // 0x...
+const solPocket = manager.getPocketAddress('solana', 0);     // Different!
+```
+
+### 3. Memory Management ✅
+Following the VM pattern, all managers support proper cleanup:
+
+```typescript
+// Clear specific pocket
+manager.clearPocket(0);
+
+// Clear all pockets
+manager.clearAllPockets();
+
+// Clear all RPC clients
+manager.clearAllClients();
+
+// Dispose everything (clear mnemonic + all data)
+manager.dispose();
+```
+
+### 4. Lazy RPC Client Creation ✅
+RPC clients are created on-demand and can be garbage collected:
+
+```typescript
+// Client created when first accessed
+const balance = await manager.getPocketBalance(...);
+
+// Clear client to free memory
+manager.clearClient();  // Single chain
+manager.clearAllClients();  // Multi-chain
+```
+
+---
+
+## 🏗️ Architecture Highlights
+
+### Follows VM Pattern Exactly
+
+```typescript
+// VM Pattern
+abstract class VM<AddressType, PrivateKeyType, ConnectionType> { }
+class EVMVM extends VM<string, string, PublicClient> { }
+class SVMVM extends VM<PublicKey, Keypair, Connection> { }
+
+// Savings Pattern (Same Structure!)
+abstract class SavingsManager<AddressType, ClientType, WalletClientType> { }
+class EVMSavingsManager extends SavingsManager<Hex, PublicClient, WalletClient> { }
+class SVMSavingsManager extends SavingsManager<PublicKey, Connection, Keypair> { }
+```
+
+### Type Safety
+
+All managers are fully typed with generics:
+- **AddressType**: `Hex` for EVM, `PublicKey` for Solana
+- **ClientType**: `PublicClient` for EVM, `Connection` for Solana
+- **WalletClientType**: `WalletClient` for EVM, `Keypair` for Solana
+
+---
+
+## 📊 Comparison: Single-Chain vs Multi-Chain
+
+### Before (Old Pattern)
+```typescript
+// Old: Single chain only
+const manager = new BaseSavingsManager(mnemonic, 0, ethConfig);
+const pocket = manager.getPocket(0);
+const balances = await manager.getPocketTokenBalance([usdc], 0);
+```
+
+### After (New Pattern)
+```typescript
+// New: Single chain (still works the same)
+const manager = new EVMSavingsManager(mnemonic, ethConfig, 0);
+const pocket = manager.getPocket(0);
+const balances = await manager.getPocketBalance(0, [usdc]);
+
+// OR Multi-chain (new capability!)
+const multiManager = new MultiChainSavingsManager(mnemonic, [
+    { id: 'ethereum', type: 'EVM', config: ethConfig },
+    { id: 'polygon', type: 'EVM', config: polyConfig },
+    { id: 'solana', type: 'SVM', config: { rpcUrl: '...' } }
+], 0);
+
+// Query all chains at once
+const allBalances = await multiManager.getPocketBalanceAcrossChains(0, tokensByChain);
+```
+
+---
+
+## 🎯 Migration Guide
+
+### Old Code (Legacy Manager)
+```typescript
+import { SavingsManager } from './utils/savings';
+
+const manager = new SavingsManager(mnemonic, ethConfig, 0);
+```
+
+**Status**: ✅ Still works! Legacy exports maintained for backward compatibility.
+
+### New Code (Multi-Chain)
+```typescript
+import { EVMSavingsManager, SVMSavingsManager, MultiChainSavingsManager } from './utils/savings';
+
+// Single EVM chain
+const evmManager = new EVMSavingsManager(mnemonic, ethConfig, 0);
+
+// Single Solana chain
+const svmManager = new SVMSavingsManager(mnemonic, rpcUrl, 0);
+
+// Multi-chain
+const multiManager = new MultiChainSavingsManager(mnemonic, chains, 0);
+```
+
+---
+
+## 🧪 Testing Checklist
+
+- [x] Abstract base class created
+- [x] EVM implementation complete
+- [x] Solana implementation complete
+- [x] Multi-chain orchestrator complete
+- [x] Exports updated
+- [x] Build successful (no TypeScript errors in savings module)
+- [ ] Unit tests (TODO)
+- [ ] Integration tests (TODO)
+- [ ] End-to-end tests (TODO)
+
+---
+
+## 📝 Next Steps (Optional)
+
+1. **Add Unit Tests**
+   - Test pocket derivation
+   - Test balance queries
+   - Test transfers
+
+2. **Add Integration Tests**
+   - Test with real RPC endpoints (testnet)
+   - Test cross-chain operations
+
+3. **Performance Optimizations**
+   - Implement balance caching
+   - Batch RPC requests
+   - Add rate limiting helpers
+
+4. **Additional Features**
+   - Pocket discovery (scan for pockets with balances)
+   - Transaction history per pocket
+   - USD value aggregation (with price feeds)
+
+---
+
+## 🎉 Summary
+
+✅ **Complete multi-chain savings manager implemented**
+- Follows EVM/SVM VM pattern exactly
+- Supports all EVM chains + Solana
+- EVM chains share addresses (coin type 60)
+- Solana has different addresses (coin type 501)
+- Full type safety with generics
+- Memory management and disposal patterns
+- Lazy RPC client creation
+- Backward compatible with legacy code
+
+**Ready to use!** 🚀