@deserialize/multi-vm-wallet 1.2.293 → 1.3.0

package/utils/evm/SMART_WALLET_EXAMPLES.ts.bak

@@ -0,0 +1,591 @@
+/**
+ * Smart Wallet Usage Examples
+ *
+ * Comprehensive examples demonstrating all smart wallet features
+ */
+
+import { EVMChainWallet } from "./evm";
+import { parseEther, parseUnits, encodeFunctionData, parseAbi } from "viem";
+import { ChainWalletConfig } from "../types";
+
+// ============================================
+// Example 1: Basic Smart Wallet Setup
+// ============================================
+
+async function example1_BasicSetup() {
+    console.log("\n=== Example 1: Basic Setup ===\n");
+
+    // Create regular EVM wallet
+    const config: ChainWalletConfig = {
+        name: "Sepolia",
+        chainId: 11155111,
+        rpcUrl: "https://sepolia.infura.io/v3/YOUR_INFURA_KEY",
+        explorerUrl: "https://sepolia.etherscan.io",
+        nativeToken: {
+            name: "Ethereum",
+            symbol: "ETH",
+            decimals: 18,
+            address: "native"
+        }
+    };
+
+    const privateKey = "0x..."; // Your private key
+    const evmWallet = new EVMChainWallet(config, privateKey, 0);
+
+    console.log("EOA Address:", evmWallet.address);
+
+    // Extend with smart wallet capabilities
+    const smartWallet = await evmWallet.extend({
+        bundlerProvider: "pimlico",
+        apiKey: process.env.PIMLICO_API_KEY!
+    });
+
+    console.log("Smart Wallet Address:", smartWallet.getAddress());
+
+    // Get account info
+    const info = await smartWallet.getAccountInfo();
+    console.log("Account Info:", {
+        address: info.address,
+        owner: info.ownerAddress,
+        chain: info.chain.name,
+        delegated: info.isDelegated,
+        balance: info.balance.toString()
+    });
+}
+
+// ============================================
+// Example 2: Single Transaction
+// ============================================
+
+async function example2_SingleTransaction(smartWallet: any) {
+    console.log("\n=== Example 2: Single Transaction ===\n");
+
+    const recipient = "0x742d35Cc6634C0532925a3b844Bc454e4438f44e";
+    const amount = parseEther("0.01");
+
+    const result = await smartWallet.sendTransaction(recipient, amount);
+
+    if (result.success) {
+        console.log("✅ Transaction successful!");
+        console.log("UserOp Hash:", result.userOpHash);
+        console.log("Transaction Hash:", result.transactionHash);
+    } else {
+        console.error("❌ Transaction failed:", result.error);
+    }
+}
+
+// ============================================
+// Example 3: Batch Transactions
+// ============================================
+
+async function example3_BatchTransactions(smartWallet: any) {
+    console.log("\n=== Example 3: Batch Transactions ===\n");
+
+    // Send ETH to multiple recipients in ONE transaction
+    const recipients = [
+        "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
+        "0x5B38Da6a701c568545dCfcB03FcB875f56beddC4",
+        "0xAb8483F64d9C6d1EcF9b849Ae677dD3315835cb2"
+    ];
+
+    const calls = recipients.map((recipient, i) =>
+        smartWallet.prepareCall(
+            recipient,
+            parseEther(`0.0${i + 1}`) // 0.01, 0.02, 0.03 ETH
+        )
+    );
+
+    console.log(`Sending to ${recipients.length} recipients in one transaction...`);
+
+    const result = await smartWallet.sendBatchTransaction(calls);
+
+    if (result.success) {
+        console.log("✅ Batch transaction successful!");
+        console.log("Transaction Hash:", result.transactionHash);
+        console.log("💰 Gas saved: ~80% compared to individual transactions");
+    } else {
+        console.error("❌ Batch transaction failed:", result.error);
+    }
+}
+
+// ============================================
+// Example 4: Batch with Contract Interactions
+// ============================================
+
+async function example4_BatchWithContracts(smartWallet: any) {
+    console.log("\n=== Example 4: Batch with Contracts ===\n");
+
+    const USDC_ADDRESS = "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238"; // Sepolia USDC
+    const recipient = "0x742d35Cc6634C0532925a3b844Bc454e4438f44e";
+
+    // Prepare USDC transfer calldata
+    const transferCalldata = encodeFunctionData({
+        abi: parseAbi(["function transfer(address to, uint256 amount)"]),
+        functionName: "transfer",
+        args: [recipient, parseUnits("10", 6)] // 10 USDC
+    });
+
+    // Batch: Send ETH + Send USDC in one transaction
+    const calls = [
+        smartWallet.prepareCall(recipient, parseEther("0.01")),
+        smartWallet.prepareCall(USDC_ADDRESS, 0n, transferCalldata)
+    ];
+
+    console.log("Sending ETH + USDC in one transaction...");
+
+    const result = await smartWallet.sendBatchTransaction(calls);
+
+    if (result.success) {
+        console.log("✅ Batch successful!");
+        console.log("Sent 0.01 ETH + 10 USDC in one transaction");
+    }
+}
+
+// ============================================
+// Example 5: Session Keys - Complete Workflow
+// ============================================
+
+async function example5_SessionKeys(smartWallet: any) {
+    console.log("\n=== Example 5: Session Keys ===\n");
+
+    // STEP 1: Agent generates session key
+    console.log("Step 1: Agent generates session key");
+    const sessionKey = await smartWallet.generateSessionKey();
+
+    console.log("Session Key Address:", sessionKey.address);
+    console.log("Session Key Private Key:", sessionKey.privateKey);
+    console.log("⚠️  Store private key securely!");
+
+    // STEP 2: Owner approves session key with permissions
+    console.log("\nStep 2: Owner approves session key");
+
+    const USDC_ADDRESS = "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238";
+
+    const approval = await smartWallet.approveSessionKey({
+        sessionKeyAddress: sessionKey.address,
+        permissions: [
+            // Max 100 USDC per transfer
+            smartWallet.createUSDCPermission(USDC_ADDRESS, "100"),
+            // Max 0.1 ETH per transfer
+            smartWallet.createETHPermission("0.1")
+        ]
+    });
+
+    console.log("✅ Session key approved!");
+    console.log("Approval string length:", approval.length);
+    console.log("Share this approval with the agent →", approval.substring(0, 50) + "...");
+
+    // STEP 3: Agent uses session key
+    console.log("\nStep 3: Agent uses session key");
+
+    // Recreate session key from private key
+    const recreatedKey = await smartWallet.recreateSessionKey(sessionKey.privateKey);
+
+    // Use the session key
+    await smartWallet.useSessionKey({
+        approval,
+        sessionKeySigner: recreatedKey.signer
+    });
+
+    console.log("✅ Now using session key");
+    console.log("Session key active:", smartWallet.isUsingSessionKey());
+
+    // Agent can now send transactions within limits
+    const recipient = "0x742d35Cc6634C0532925a3b844Bc454e4438f44e";
+
+    const result = await smartWallet.sendTransaction(
+        recipient,
+        parseEther("0.05") // Within 0.1 ETH limit
+    );
+
+    if (result.success) {
+        console.log("✅ Transaction sent with session key!");
+    }
+
+    // STEP 4: Clear session key
+    smartWallet.clearSessionKey();
+    console.log("\nSession key cleared:", !smartWallet.isUsingSessionKey());
+}
+
+// ============================================
+// Example 6: Session Keys - Sudo Mode
+// ============================================
+
+async function example6_SessionKeysSudo(smartWallet: any) {
+    console.log("\n=== Example 6: Session Keys (Sudo Mode) ===\n");
+
+    const sessionKey = await smartWallet.generateSessionKey();
+
+    // Approve with unrestricted sudo access
+    // ⚠️  Only use for testing or trusted agents!
+    const approval = await smartWallet.approveSessionKey({
+        sessionKeyAddress: sessionKey.address,
+        useSudoPolicy: true // Unrestricted access
+    });
+
+    console.log("✅ Session key approved with SUDO access");
+    console.log("⚠️  This session key has UNRESTRICTED access!");
+
+    await smartWallet.useSessionKey({
+        approval,
+        sessionKeySigner: sessionKey.signer
+    });
+
+    console.log("Session key can now perform any transaction");
+}
+
+// ============================================
+// Example 7: Module Management
+// ============================================
+
+async function example7_ModuleManagement(smartWallet: any) {
+    console.log("\n=== Example 7: Module Management ===\n");
+
+    const validatorAddress = "0x..."; // Your validator module address
+
+    // Check if module is installed
+    const isInstalled = await smartWallet.isModuleInstalled(
+        "validator",
+        validatorAddress
+    );
+
+    console.log("Module installed:", isInstalled);
+
+    if (!isInstalled) {
+        // Install module
+        console.log("Installing module...");
+
+        const result = await smartWallet.installModule({
+            moduleType: "validator",
+            moduleAddress: validatorAddress,
+            initData: "0x" // Module-specific init data
+        });
+
+        if (result.success) {
+            console.log("✅ Module installed!");
+        }
+    } else {
+        // Uninstall module
+        console.log("Uninstalling module...");
+
+        const result = await smartWallet.uninstallModule({
+            moduleType: "validator",
+            moduleAddress: validatorAddress
+        });
+
+        if (result.success) {
+            console.log("✅ Module uninstalled!");
+        }
+    }
+}
+
+// ============================================
+// Example 8: Batch Module Operations
+// ============================================
+
+async function example8_BatchModules(smartWallet: any) {
+    console.log("\n=== Example 8: Batch Module Operations ===\n");
+
+    const validator1 = "0x...";
+    const validator2 = "0x...";
+    const hook1 = "0x...";
+
+    // Install multiple modules in one transaction
+    const calls = [
+        smartWallet.prepareInstallModule({
+            moduleType: "validator",
+            moduleAddress: validator1
+        }),
+        smartWallet.prepareInstallModule({
+            moduleType: "validator",
+            moduleAddress: validator2
+        }),
+        smartWallet.prepareInstallModule({
+            moduleType: "hook",
+            moduleAddress: hook1
+        })
+    ];
+
+    console.log("Installing 3 modules in one transaction...");
+
+    const result = await smartWallet.sendBatchTransaction(calls);
+
+    if (result.success) {
+        console.log("✅ All modules installed!");
+    }
+}
+
+// ============================================
+// Example 9: Multi-Signature
+// ============================================
+
+async function example9_MultiSignature(smartWallet: any) {
+    console.log("\n=== Example 9: Multi-Signature ===\n");
+
+    const owner1 = "0x742d35Cc6634C0532925a3b844Bc454e4438f44e";
+    const owner2 = "0x5B38Da6a701c568545dCfcB03FcB875f56beddC4";
+    const owner3 = "0xAb8483F64d9C6d1EcF9b849Ae677dD3315835cb2";
+
+    // Enable 2-of-3 multi-sig
+    const result = await smartWallet.enableMultiSig({
+        owners: [owner1, owner2, owner3],
+        threshold: 2 // Require 2 signatures
+    });
+
+    if (result.success) {
+        console.log("✅ Multi-sig enabled!");
+        console.log("Threshold: 2 of 3 owners required");
+    }
+}
+
+// ============================================
+// Example 10: Gas Sponsorship (Paymaster)
+// ============================================
+
+async function example10_Paymaster(smartWallet: any) {
+    console.log("\n=== Example 10: Gas Sponsorship ===\n");
+
+    const paymasterUrl = "https://api.pimlico.io/v2/sepolia/paymaster";
+
+    // Enable paymaster
+    smartWallet.setPaymaster(paymasterUrl);
+
+    console.log("✅ Paymaster enabled");
+    console.log("Has paymaster:", smartWallet.hasPaymaster());
+
+    // User doesn't pay gas!
+    const result = await smartWallet.sendTransaction(
+        "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
+        parseEther("0.01")
+    );
+
+    if (result.success) {
+        console.log("✅ Transaction sponsored! User paid $0 in gas");
+    }
+
+    // Disable paymaster
+    smartWallet.clearPaymaster();
+    console.log("Paymaster disabled");
+}
+
+// ============================================
+// Example 11: Check Account Status
+// ============================================
+
+async function example11_AccountStatus(smartWallet: any) {
+    console.log("\n=== Example 11: Account Status ===\n");
+
+    // Get full account info
+    const info = await smartWallet.getAccountInfo();
+
+    console.log("Account Information:");
+    console.log("  Address:", info.address);
+    console.log("  Owner:", info.ownerAddress);
+    console.log("  Chain:", info.chain.name, `(${info.chain.id})`);
+    console.log("  EntryPoint:", info.entryPointVersion);
+    console.log("  Delegated:", info.isDelegated);
+    console.log("  Balance:", info.balance.toString(), "wei");
+
+    // Get balance
+    const balance = await smartWallet.getBalance();
+    console.log("\nBalance:", balance.formatted, "ETH");
+
+    // Check delegation
+    const isDelegated = await smartWallet.isAccountDelegated();
+    console.log("Account delegated:", isDelegated);
+
+    // Get bundler info
+    const bundlerInfo = smartWallet.getBundlerInfo();
+    console.log("\nBundler:");
+    console.log("  Provider:", bundlerInfo.provider);
+    console.log("  URL:", bundlerInfo.url);
+
+    // Check session key status
+    console.log("\nSession key active:", smartWallet.isUsingSessionKey());
+
+    // Check paymaster status
+    console.log("Paymaster enabled:", smartWallet.hasPaymaster());
+}
+
+// ============================================
+// Example 12: Dual Mode (EOA + Smart Wallet)
+// ============================================
+
+async function example12_DualMode() {
+    console.log("\n=== Example 12: Dual Mode ===\n");
+
+    const config: ChainWalletConfig = {
+        name: "Sepolia",
+        chainId: 11155111,
+        rpcUrl: "https://sepolia.infura.io/v3/YOUR_INFURA_KEY",
+        explorerUrl: "https://sepolia.etherscan.io",
+        nativeToken: {
+            name: "Ethereum",
+            symbol: "ETH",
+            decimals: 18,
+            address: "native"
+        }
+    };
+
+    const privateKey = "0x...";
+    const evmWallet = new EVMChainWallet(config, privateKey, 0);
+
+    // Enable smart wallet
+    const smartWallet = await evmWallet.extend({
+        bundlerProvider: "pimlico",
+        apiKey: process.env.PIMLICO_API_KEY!
+    });
+
+    console.log("EOA Address:", evmWallet.address);
+    console.log("Smart Wallet Address:", smartWallet.getAddress());
+
+    // Both modes work simultaneously!
+
+    // Use regular EOA for simple transfers
+    console.log("\n1. Using EOA (regular transaction):");
+    await evmWallet.transferNative("0x...", 0.01);
+    console.log("✅ EOA transaction sent");
+
+    // Use smart wallet for batch operations
+    console.log("\n2. Using Smart Wallet (batched UserOp):");
+    const calls = [
+        smartWallet.prepareCall("0x...", parseEther("0.01")),
+        smartWallet.prepareCall("0x...", parseEther("0.02"))
+    ];
+    await smartWallet.sendBatchTransaction(calls);
+    console.log("✅ Smart wallet batch sent");
+
+    // Use regular EOA for swaps
+    console.log("\n3. Using EOA (swap):");
+    await evmWallet.swap(
+        { address: "0xTokenIn", name: "TokenIn", symbol: "TKN", decimals: 18 },
+        "0xTokenOut",
+        1
+    );
+    console.log("✅ EOA swap executed");
+
+    console.log("\n✨ Both EOA and Smart Wallet work together!");
+}
+
+// ============================================
+// Example 13: Error Handling
+// ============================================
+
+async function example13_ErrorHandling(smartWallet: any) {
+    console.log("\n=== Example 13: Error Handling ===\n");
+
+    try {
+        const result = await smartWallet.sendTransaction(
+            "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
+            parseEther("1000") // Insufficient balance
+        );
+
+        if (result.success) {
+            console.log("✅ Success:", result.transactionHash);
+        } else {
+            console.log("❌ Transaction failed:", result.error);
+
+            // Handle specific errors
+            if (result.error?.includes("insufficient funds")) {
+                console.log("→ Account needs more ETH");
+            } else if (result.error?.includes("AA23")) {
+                console.log("→ UserOperation validation failed");
+            } else if (result.error?.includes("AA21")) {
+                console.log("→ UserOperation expired");
+            }
+        }
+    } catch (error: any) {
+        console.error("Unexpected error:", error.message);
+    }
+}
+
+// ============================================
+// Example 14: Automated Trading Bot
+// ============================================
+
+async function example14_TradingBot(smartWallet: any) {
+    console.log("\n=== Example 14: Automated Trading Bot ===\n");
+
+    // Generate session key for bot
+    const sessionKey = await smartWallet.generateSessionKey();
+
+    console.log("Bot session key:", sessionKey.address);
+
+    // Owner approves with trading limits
+    const approval = await smartWallet.approveSessionKey({
+        sessionKeyAddress: sessionKey.address,
+        permissions: [
+            smartWallet.createUSDCPermission(
+                "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
+                "1000" // Max 1000 USDC per trade
+            ),
+            smartWallet.createETHPermission("1.0") // Max 1 ETH per trade
+        ]
+    });
+
+    console.log("✅ Trading bot approved with limits");
+
+    // Bot uses session key
+    const botKey = await smartWallet.recreateSessionKey(sessionKey.privateKey);
+    await smartWallet.useSessionKey({
+        approval,
+        sessionKeySigner: botKey.signer
+    });
+
+    // Bot executes trades
+    console.log("\n🤖 Bot executing automated trades...");
+
+    const dexAddress = "0x..."; // DEX router address
+    const swapCalldata = "0x..."; // Swap transaction data
+
+    const result = await smartWallet.sendTransaction(dexAddress, 0n, swapCalldata);
+
+    if (result.success) {
+        console.log("✅ Bot trade executed:", result.transactionHash);
+    }
+
+    console.log("\n💡 Bot can trade within limits without owner approval!");
+}
+
+// ============================================
+// Main Runner
+// ============================================
+
+async function runAllExamples() {
+    console.log("🚀 Smart Wallet Examples\n");
+
+    try {
+        // await example1_BasicSetup();
+
+        // Note: Uncomment individual examples to run them
+        // Make sure to provide valid private keys and API keys
+
+        console.log("\n✅ All examples completed!");
+        console.log("\nTo run an example:");
+        console.log("1. Uncomment the example in runAllExamples()");
+        console.log("2. Set your private key and API key");
+        console.log("3. Run: npx tsx SMART_WALLET_EXAMPLES.ts");
+    } catch (error) {
+        console.error("Error:", error);
+    }
+}
+
+// Uncomment to run
+// runAllExamples();
+
+export {
+    example1_BasicSetup,
+    example2_SingleTransaction,
+    example3_BatchTransactions,
+    example4_BatchWithContracts,
+    example5_SessionKeys,
+    example6_SessionKeysSudo,
+    example7_ModuleManagement,
+    example8_BatchModules,
+    example9_MultiSignature,
+    example10_Paymaster,
+    example11_AccountStatus,
+    example12_DualMode,
+    example13_ErrorHandling,
+    example14_TradingBot
+};

package/utils/evm/aa-service/index.ts

@@ -0,0 +1,85 @@
+/**
+ * Main Export File
+ *
+ * Easy imports for using the Account Abstraction services
+ */
+
+// Singleton Service (Primary Interface)
+export { AccountAbstractionService } from './services/account-abstraction';
+export type {
+    AAServiceConfig,
+    CreateAccountOptions,
+    SendTransactionOptions,
+    SendBatchTransactionOptions,
+    WaitForReceiptOptions
+} from './services/account-abstraction';
+
+export * from './lib/type'
+
+// Bundler Services (Advanced Usage)
+export {
+    BundlerManager,
+    createBundlerManager,
+    createBundlerService
+} from './services/bundler';
+export type { BundlerConfig, BundlerService } from './services/bundler';
+
+// Kernel Account Utilities (Advanced Usage)
+export {
+    createKernel7702Account,
+    createKernelAuthorization,
+    sendKernelTransaction,
+    sendBatchTransaction,
+    waitForKernelReceipt,
+    sendSponsoredBatchTransaction
+} from './lib/kernel-account';
+
+
+// Module Management (ERC-7579)
+export {
+    // Prepare functions (for batching)
+    prepareInstallModule,
+    prepareUninstallModule,
+    prepareInstallSessionKey,
+    prepareRevokeSessionKey,
+    prepareInstallMultiSigValidator,
+    // Execute functions (immediate execution)
+    installModule,
+    uninstallModule,
+    isModuleInstalled,
+    createSessionKey,
+    revokeSessionKey,
+    installMultiSigValidator,
+    MODULE_TYPE_IDS
+} from './lib/kernel-modules';
+export type {
+    ModuleType,
+    InstallModuleConfig,
+    UninstallModuleConfig,
+    ModuleStatus,
+    SessionKeyPermission,
+    CreateSessionKeyConfig
+} from './lib/kernel-modules';
+
+// EIP-7702 Session Keys (NEW Pattern)
+export {
+    generateSessionKey,
+    recreateSessionKey,
+    createSessionKeyApproval,
+    deserializeSessionKey,
+    createSessionKeyClient,
+    createUSDCTransferPermission,
+    createETHTransferPermission
+} from './lib/session-keys';
+export type {
+    SessionKeyInfo,
+    SessionKeyPermissionRule,
+    CreateSessionKeyApprovalOptions,
+    DeserializedSessionKey
+} from './lib/session-keys';
+
+// Account Adapters (ZeroDev Integration)
+export {
+    adaptZeroDevAccount,
+    adaptSessionKeyAccount
+} from './lib/account-adapter';