@deserialize/multi-vm-wallet 1.2.441 → 1.3.0

package/utils/evm/smartWallet.ts

@@ -0,0 +1,797 @@
+/**
+ * EVM Smart Wallet Implementation
+ *
+ * Provides Account Abstraction (EIP-4337) and EIP-7702 capabilities to EVMChainWallet.
+ * This class wraps the AA service and provides a clean API for smart wallet features.
+ */
+
+import { Chain, Hex, parseEther, parseUnits, createPublicClient, http, PublicClient } from "viem";
+import { privateKeyToAccount, PrivateKeyAccount } from "viem/accounts";
+import { ModularSigner } from "@zerodev/permissions";
+import { Balance, TransactionResult } from "../types";
+import {
+    SmartWalletOptions,
+    SmartWalletTransactionResult,
+    Call,
+    SessionKeyInfo,
+    SessionKeyPermissionRule,
+    SessionKeyApprovalOptions,
+    SessionKeyUsageOptions,
+    ModuleInstallOptions,
+    ModuleUninstallOptions,
+    MultiSigConfig,
+    RecoveryConfig,
+    PaymasterConfig,
+    SmartAccountInfo,
+    SmartWalletError,
+    SessionKeyError,
+    ModuleError,
+    TransactionError,
+    ModuleType
+} from "./smartWallet.types";
+
+// Import AA service from local aa-service
+import { AccountAbstractionService } from "./aa-service/services/account-abstraction";
+import {
+    createKernelAuthorization,
+    sendSponsoredBatchTransaction
+} from "./aa-service/lib/kernel-account";
+import type {
+    KernelAccountInstance,
+    Call as AACall
+} from "./aa-service/lib/kernel-account";
+import type { SessionKeyPermission } from "./aa-service/lib/kernel-modules";
+
+/**
+ * EVMSmartWallet - Smart wallet capabilities for EVM chains
+ *
+ * Provides:
+ * - EIP-7702 account delegation
+ * - Batch transactions (pay gas once for multiple operations)
+ * - Session keys with granular permissions
+ * - Module management (validators, hooks, executors)
+ * - Gas sponsorship (paymasters)
+ * - Multi-signature support
+ * - Account recovery
+ */
+export class EVMSmartWallet {
+    private aaService: AccountAbstractionService | null = null;
+    private kernelAccount: KernelAccountInstance | null = null;
+    private ownerAccount: PrivateKeyAccount;
+    private chain: Chain;
+    private options: SmartWalletOptions;
+    private sessionAccount: any = null;
+    private paymasterConfig: PaymasterConfig | null = null;
+    private bundlerUrl: string;
+
+    constructor(
+        privateKey: string,
+        chain: Chain,
+        bundlerUrl: string,
+        options: SmartWalletOptions = {}
+    ) {
+        this.ownerAccount = privateKeyToAccount(privateKey as Hex);
+        this.chain = chain;
+        this.bundlerUrl = bundlerUrl;
+        this.options = {
+            entryPointVersion: '0.7',
+            autoInitialize: true,
+            ...options
+        };
+
+        // Set paymaster if provided
+        if (options.paymasterUrl) {
+            this.paymasterConfig = {
+                paymasterUrl: options.paymasterUrl
+            };
+        }
+    }
+
+    // ============================================
+    // Core Methods
+    // ============================================
+
+    /**
+     * Initialize the smart wallet
+     * Creates the Kernel account and sets up delegation if needed
+     */
+    async initialize(): Promise<void> {
+        try {
+            // Initialize AA service singleton with custom bundler URL
+            this.aaService = AccountAbstractionService.getInstance({
+                bundlerProvider: 'custom',
+                customBundlerUrl: this.bundlerUrl
+            });
+
+            // Create Kernel account
+            this.kernelAccount = await this.aaService.createAccount({
+                chain: this.chain,
+                owner: this.ownerAccount,
+                entryPointVersion: this.options.entryPointVersion
+            });
+
+            console.log(`Smart wallet initialized: ${this.kernelAccount.address}`);
+        } catch (error) {
+            throw new SmartWalletError(
+                `Failed to initialize smart wallet: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                'INIT_ERROR'
+            );
+        }
+    }
+
+    /**
+     * Get the smart account address
+     */
+    getAddress(): Hex {
+        if (!this.kernelAccount) {
+            throw new SmartWalletError('Smart wallet not initialized', 'NOT_INITIALIZED');
+        }
+        return this.kernelAccount.address as Hex;
+    }
+
+    /**
+     * Get smart account information
+     */
+    async getAccountInfo(): Promise<SmartAccountInfo> {
+        if (!this.kernelAccount || !this.aaService) {
+            throw new SmartWalletError('Smart wallet not initialized', 'NOT_INITIALIZED');
+        }
+
+        const balance = await this.getBalance();
+        const isDelegated = await this.aaService.isAccountDelegated(
+            this.ownerAccount,
+            this.chain
+        );
+
+        return {
+            address: this.kernelAccount.address as Hex,
+            ownerAddress: this.ownerAccount.address as Hex,
+            chain: this.chain,
+            entryPointVersion: this.options.entryPointVersion!,
+            isDelegated,
+            balance: BigInt(balance.balance.toString())
+        };
+    }
+
+    /**
+     * Get smart account balance
+     */
+    async getBalance(): Promise<Balance> {
+        if (!this.kernelAccount || !this.aaService) {
+            throw new SmartWalletError('Smart wallet not initialized', 'NOT_INITIALIZED');
+        }
+
+        const balance = await this.aaService.getBalance(this.kernelAccount);
+
+        return {
+            balance: balance as any,
+            decimal: 18,
+            formatted: Number(balance) / 1e18
+        };
+    }
+
+    /**
+     * Check if account is delegated
+     */
+    async isAccountDelegated(): Promise<boolean> {
+        if (!this.aaService) {
+            throw new SmartWalletError('Smart wallet not initialized', 'NOT_INITIALIZED');
+        }
+        return await this.aaService.isAccountDelegated(this.ownerAccount, this.chain);
+    }
+
+    // ============================================
+    // Transaction Methods
+    // ============================================
+
+    /**
+     * Send a single transaction via UserOperation
+     *
+     * @param to - Recipient address
+     * @param value - ETH value in wei
+     * @param data - Optional calldata
+     * @returns Transaction result with UserOp hash
+     *
+     * @example
+     * await smartWallet.sendTransaction(
+     *   '0xRecipient',
+     *   parseEther('0.1'),
+     *   '0x'
+     * );
+     */
+    async sendTransaction(
+        to: Hex,
+        value: bigint = 0n,
+        data: Hex = '0x'
+    ): Promise<SmartWalletTransactionResult> {
+        if (!this.kernelAccount || !this.aaService) {
+            throw new SmartWalletError('Smart wallet not initialized', 'NOT_INITIALIZED');
+        }
+
+        try {
+            // Use session account if available, otherwise use kernel account
+            const account = this.sessionAccount || this.kernelAccount;
+
+            const userOpHash = await this.aaService.sendTransaction({
+                account,
+                to,
+                value,
+                data
+            });
+
+            // Wait for receipt
+            const receipt = await this.aaService.waitForReceipt({
+                userOpHash,
+                chain: this.chain
+            });
+
+            return {
+                success: true,
+                userOpHash,
+                transactionHash: receipt.transactionHash
+            };
+        } catch (error) {
+            const errorMsg = error instanceof Error ? error.message : 'Unknown error';
+            return {
+                success: false,
+                userOpHash: '0x' as Hex,
+                error: errorMsg
+            };
+        }
+    }
+
+    /**
+     * Send multiple transactions in a single UserOperation
+     * This is one of the main advantages of smart accounts - pay gas ONLY ONCE!
+     *
+     * @param calls - Array of calls to execute
+     * @returns Transaction result
+     *
+     * @example
+     * await smartWallet.sendBatchTransaction([
+     *   { to: recipient1, value: parseEther('0.1'), data: '0x' },
+     *   { to: recipient2, value: parseEther('0.2'), data: '0x' },
+     *   { to: usdcAddress, value: 0n, data: transferCalldata }
+     * ]);
+     */
+    async sendBatchTransaction(calls: Call[]): Promise<SmartWalletTransactionResult> {
+        if (!this.kernelAccount || !this.aaService) {
+            throw new SmartWalletError('Smart wallet not initialized', 'NOT_INITIALIZED');
+        }
+
+        if (calls.length === 0) {
+            throw new TransactionError('Batch transaction must have at least one call');
+        }
+
+        try {
+            // Convert to AA service Call format
+            const aaCalls: AACall[] = calls.map(call => ({
+                to: call.to,
+                value: call.value,
+                data: call.data
+            }));
+
+            // Use session account if available, otherwise use kernel account
+            const account = this.sessionAccount || this.kernelAccount;
+
+            const userOpHash = await this.aaService.sendBatchTransaction({
+                account,
+                calls: aaCalls
+            });
+
+            // Wait for receipt
+            const receipt = await this.aaService.waitForReceipt({
+                userOpHash,
+                chain: this.chain
+            });
+
+            return {
+                success: true,
+                userOpHash,
+                transactionHash: receipt.transactionHash
+            };
+        } catch (error) {
+            const errorMsg = error instanceof Error ? error.message : 'Unknown error';
+            return {
+                success: false,
+                userOpHash: '0x' as Hex,
+                error: errorMsg
+            };
+        }
+    }
+
+    /**
+     * Prepare a call for batching
+     * Helper method to create Call objects
+     */
+    prepareCall(to: Hex, value: bigint = 0n, data: Hex = '0x'): Call {
+        return { to, value, data };
+    }
+
+    // ============================================
+    // Session Key Methods
+    // ============================================
+
+    /**
+     * Generate a new session key
+     * The private key should be stored securely by the agent
+     *
+     * @returns Session key info with private key, address, and signer
+     *
+     * @example
+     * const sessionKey = await smartWallet.generateSessionKey();
+     * console.log('Address:', sessionKey.address);
+     * // Store sessionKey.privateKey securely
+     */
+    async generateSessionKey(): Promise<SessionKeyInfo> {
+        if (!this.aaService) {
+            throw new SmartWalletError('Smart wallet not initialized', 'NOT_INITIALIZED');
+        }
+        try {
+            return await this.aaService.generateSessionKey();
+        } catch (error) {
+            throw new SessionKeyError(
+                `Failed to generate session key: ${error instanceof Error ? error.message : 'Unknown error'}`
+            );
+        }
+    }
+
+    /**
+     * Recreate session key from stored private key
+     *
+     * @param privateKey - Session key private key
+     * @returns Session key info
+     *
+     * @example
+     * const sessionKey = await smartWallet.recreateSessionKey(storedPrivateKey);
+     */
+    async recreateSessionKey(privateKey: Hex): Promise<SessionKeyInfo> {
+        if (!this.aaService) {
+            throw new SmartWalletError('Smart wallet not initialized', 'NOT_INITIALIZED');
+        }
+        try {
+            return await this.aaService.recreateSessionKey(privateKey);
+        } catch (error) {
+            throw new SessionKeyError(
+                `Failed to recreate session key: ${error instanceof Error ? error.message : 'Unknown error'}`
+            );
+        }
+    }
+
+    /**
+     * Create session key approval (Owner side)
+     * Owner approves a session key with specific permissions
+     *
+     * @param options - Approval options with session key address and permissions
+     * @returns Serialized approval string to share with agent
+     *
+     * @example
+     * const approval = await smartWallet.approveSessionKey({
+     *   sessionKeyAddress: '0x...',
+     *   permissions: [
+     *     smartWallet.createUSDCPermission(USDC_ADDRESS, '100')
+     *   ]
+     * });
+     */
+    async approveSessionKey(options: SessionKeyApprovalOptions): Promise<string> {
+        if (!this.aaService) {
+            throw new SmartWalletError('Smart wallet not initialized', 'NOT_INITIALIZED');
+        }
+        try {
+            return await this.aaService.createSessionKeyApproval({
+                sessionKeyAddress: options.sessionKeyAddress,
+                owner: this.ownerAccount,
+                chain: this.chain,
+                entryPointVersion: this.options.entryPointVersion,
+                useSudoPolicy: options.useSudoPolicy,
+                permissions: options.permissions
+            });
+        } catch (error) {
+            throw new SessionKeyError(
+                `Failed to approve session key: ${error instanceof Error ? error.message : 'Unknown error'}`
+            );
+        }
+    }
+
+    /**
+     * Use session key for transactions (Agent side)
+     * Agent deserializes the approval and can send transactions with session key
+     *
+     * @param options - Session key usage options with approval and signer
+     *
+     * @example
+     * const sessionKey = await smartWallet.recreateSessionKey(privateKey);
+     * await smartWallet.useSessionKey({
+     *   approval,
+     *   sessionKeySigner: sessionKey.signer
+     * });
+     * // Now can send transactions with session key permissions
+     */
+    async useSessionKey(options: SessionKeyUsageOptions): Promise<void> {
+        if (!this.aaService) {
+            throw new SmartWalletError('Smart wallet not initialized', 'NOT_INITIALIZED');
+        }
+        try {
+            this.sessionAccount = await this.aaService.deserializeSessionKey({
+                approval: options.approval,
+                sessionKeySigner: options.sessionKeySigner,
+                chain: this.chain,
+                entryPointVersion: this.options.entryPointVersion
+            });
+        } catch (error) {
+            throw new SessionKeyError(
+                `Failed to use session key: ${error instanceof Error ? error.message : 'Unknown error'}`
+            );
+        }
+    }
+
+    /**
+     * Clear session key (revert to owner account)
+     */
+    clearSessionKey(): void {
+        this.sessionAccount = null;
+    }
+
+    /**
+     * Check if using session key
+     */
+    isUsingSessionKey(): boolean {
+        return this.sessionAccount !== null;
+    }
+
+    /**
+     * Create USDC transfer permission
+     *
+     * @param usdcAddress - USDC contract address
+     * @param maxAmount - Maximum USDC amount (in USDC units, e.g., "10" for 10 USDC)
+     * @returns Permission rule
+     */
+    createUSDCPermission(usdcAddress: Hex, maxAmount: string): SessionKeyPermissionRule {
+        if (!this.aaService) {
+            throw new SmartWalletError('Smart wallet not initialized', 'NOT_INITIALIZED');
+        }
+        return this.aaService.createUSDCTransferPermission(usdcAddress, maxAmount);
+    }
+
+    /**
+     * Create ETH transfer permission
+     *
+     * @param maxValue - Maximum ETH value (in ether units, e.g., "0.1" for 0.1 ETH)
+     * @returns Permission rule
+     */
+    createETHPermission(maxValue: string): SessionKeyPermissionRule {
+        if (!this.aaService) {
+            throw new SmartWalletError('Smart wallet not initialized', 'NOT_INITIALIZED');
+        }
+        return this.aaService.createETHTransferPermission(maxValue);
+    }
+
+    // ============================================
+    // Module Management Methods
+    // ============================================
+
+    /**
+     * Install a module on the smart account
+     *
+     * @param options - Module installation options
+     * @returns Transaction result
+     *
+     * @example
+     * await smartWallet.installModule({
+     *   moduleType: 'validator',
+     *   moduleAddress: '0x...',
+     *   initData: '0x...'
+     * });
+     */
+    async installModule(options: ModuleInstallOptions): Promise<SmartWalletTransactionResult> {
+        if (!this.kernelAccount || !this.aaService) {
+            throw new SmartWalletError('Smart wallet not initialized', 'NOT_INITIALIZED');
+        }
+
+        try {
+            const userOpHash = await this.aaService.installModule({
+                account: this.kernelAccount,
+                moduleType: options.moduleType,
+                moduleAddress: options.moduleAddress,
+                initData: options.initData
+            });
+
+            const receipt = await this.aaService.waitForReceipt({
+                userOpHash,
+                chain: this.chain
+            });
+
+            return {
+                success: true,
+                userOpHash,
+                transactionHash: receipt.transactionHash
+            };
+        } catch (error) {
+            const errorMsg = error instanceof Error ? error.message : 'Unknown error';
+            throw new ModuleError(`Failed to install module: ${errorMsg}`);
+        }
+    }
+
+    /**
+     * Uninstall a module from the smart account
+     *
+     * @param options - Module uninstallation options
+     * @returns Transaction result
+     */
+    async uninstallModule(options: ModuleUninstallOptions): Promise<SmartWalletTransactionResult> {
+        if (!this.kernelAccount || !this.aaService) {
+            throw new SmartWalletError('Smart wallet not initialized', 'NOT_INITIALIZED');
+        }
+
+        try {
+            const userOpHash = await this.aaService.uninstallModule({
+                account: this.kernelAccount,
+                moduleType: options.moduleType,
+                moduleAddress: options.moduleAddress,
+                deInitData: options.deInitData
+            });
+
+            const receipt = await this.aaService.waitForReceipt({
+                userOpHash,
+                chain: this.chain
+            });
+
+            return {
+                success: true,
+                userOpHash,
+                transactionHash: receipt.transactionHash
+            };
+        } catch (error) {
+            const errorMsg = error instanceof Error ? error.message : 'Unknown error';
+            throw new ModuleError(`Failed to uninstall module: ${errorMsg}`);
+        }
+    }
+
+    /**
+     * Check if a module is installed
+     *
+     * @param moduleType - Type of module
+     * @param moduleAddress - Module contract address
+     * @returns Whether the module is installed
+     */
+    async isModuleInstalled(moduleType: ModuleType, moduleAddress: Hex): Promise<boolean> {
+        if (!this.kernelAccount || !this.aaService) {
+            throw new SmartWalletError('Smart wallet not initialized', 'NOT_INITIALIZED');
+        }
+
+        try {
+            return await this.aaService.isModuleInstalled({
+                account: this.kernelAccount,
+                moduleType,
+                moduleAddress
+            });
+        } catch (error) {
+            return false;
+        }
+    }
+
+    /**
+     * Prepare module installation call (for batching)
+     *
+     * @param options - Module installation options
+     * @returns Call object for batch transaction
+     */
+    prepareInstallModule(options: ModuleInstallOptions): Call {
+        if (!this.kernelAccount || !this.aaService) {
+            throw new SmartWalletError('Smart wallet not initialized', 'NOT_INITIALIZED');
+        }
+
+        const aaCall = this.aaService.prepareInstallModule({
+            account: this.kernelAccount,
+            moduleType: options.moduleType,
+            moduleAddress: options.moduleAddress,
+            initData: options.initData
+        });
+
+        return {
+            to: aaCall.to,
+            value: aaCall.value,
+            data: aaCall.data
+        };
+    }
+
+    /**
+     * Prepare module uninstallation call (for batching)
+     *
+     * @param options - Module uninstallation options
+     * @returns Call object for batch transaction
+     */
+    prepareUninstallModule(options: ModuleUninstallOptions): Call {
+        if (!this.kernelAccount || !this.aaService) {
+            throw new SmartWalletError('Smart wallet not initialized', 'NOT_INITIALIZED');
+        }
+
+        const aaCall = this.aaService.prepareUninstallModule({
+            account: this.kernelAccount,
+            moduleType: options.moduleType,
+            moduleAddress: options.moduleAddress,
+            deInitData: options.deInitData
+        });
+
+        return {
+            to: aaCall.to,
+            value: aaCall.value,
+            data: aaCall.data
+        };
+    }
+
+    // ============================================
+    // Advanced Features
+    // ============================================
+
+    /**
+     * Enable multi-signature validation
+     *
+     * @param config - Multi-sig configuration with owners and threshold
+     * @returns Transaction result
+     *
+     * @example
+     * await smartWallet.enableMultiSig({
+     *   owners: [owner1, owner2, owner3],
+     *   threshold: 2 // 2 of 3 required
+     * });
+     */
+    async enableMultiSig(config: MultiSigConfig): Promise<SmartWalletTransactionResult> {
+        if (!this.kernelAccount || !this.aaService) {
+            throw new SmartWalletError('Smart wallet not initialized', 'NOT_INITIALIZED');
+        }
+
+        try {
+            const userOpHash = await this.aaService.installMultiSigValidator({
+                account: this.kernelAccount,
+                owners: config.owners,
+                threshold: config.threshold
+            });
+
+            const receipt = await this.aaService.waitForReceipt({
+                userOpHash,
+                chain: this.chain
+            });
+
+            return {
+                success: true,
+                userOpHash,
+                transactionHash: receipt.transactionHash
+            };
+        } catch (error) {
+            const errorMsg = error instanceof Error ? error.message : 'Unknown error';
+            throw new SmartWalletError(`Failed to enable multi-sig: ${errorMsg}`, 'MULTISIG_ERROR');
+        }
+    }
+
+    /**
+     * Set paymaster for gas sponsorship
+     *
+     * @param paymasterUrl - Paymaster service URL
+     *
+     * @example
+     * smartWallet.setPaymaster('https://api.pimlico.io/v2/sepolia/paymaster');
+     */
+    setPaymaster(paymasterUrl: string, context?: any): void {
+        this.paymasterConfig = {
+            paymasterUrl,
+            context
+        };
+    }
+
+    /**
+     * Clear paymaster (user pays gas)
+     */
+    clearPaymaster(): void {
+        this.paymasterConfig = null;
+    }
+
+    /**
+     * Check if paymaster is configured
+     */
+    hasPaymaster(): boolean {
+        return this.paymasterConfig !== null;
+    }
+
+    /**
+     * Get bundler information
+     */
+    getBundlerInfo(): { provider: string; url: string } {
+        if (!this.aaService) {
+            return {
+                provider: 'custom',
+                url: this.bundlerUrl
+            };
+        }
+        return this.aaService.getBundlerInfo(this.chain);
+    }
+
+    // ============================================
+    // Sponsored Transactions (EIP-7702)
+    // ============================================
+
+    /**
+     * Send sponsored batch transaction where another wallet pays gas fees
+     * Requires smart wallet to be initialized
+     *
+     * @param calls - Array of calls to execute
+     * @param feePayerPrivateKey - Private key of the wallet paying gas fees
+     * @returns Transaction result with userOpHash and transactionHash
+     *
+     * @example
+     * // Send ETH transfer with sponsor paying gas
+     * const result = await smartWallet.sendSponsoredBatchTransaction(
+     *   [{ to: recipient, value: parseEther('0.1') }],
+     *   sponsorPrivateKey
+     * );
+     */
+    async sendSponsoredBatchTransaction(
+        calls: Call[],
+        feePayerPrivateKey: Hex
+    ): Promise<SmartWalletTransactionResult> {
+        if (!this.aaService) {
+            throw new SmartWalletError(
+                'Smart wallet not initialized. Call initialize() first.',
+                'NOT_INITIALIZED'
+            );
+        }
+
+        if (!this.kernelAccount) {
+            throw new SmartWalletError(
+                'Kernel account not found. Smart wallet may not be properly initialized.',
+                'ACCOUNT_NOT_FOUND'
+            );
+        }
+
+        try {
+            // Create authorization for owner wallet
+            const authorization = await createKernelAuthorization({
+                owner: this.ownerAccount,
+                chain: this.chain,
+                bundlerManager: this.aaService.getBundlerManager(this.chain)
+            });
+
+            if (!authorization) {
+                throw new SmartWalletError(
+                    'Failed to create authorization for sponsored transaction',
+                    'AUTHORIZATION_FAILED'
+                );
+            }
+
+            // Send sponsored transaction with feePayer
+            const result = await sendSponsoredBatchTransaction({
+                ownerAuthorization: authorization,
+                calls,
+                feePayerPrivateKey,
+                bundlerUrl: this.bundlerUrl,
+                paymasterUrl: this.paymasterConfig?.paymasterUrl,
+                chain: this.chain,
+                entryPointVersion: this.options.entryPointVersion
+            });
+
+            return {
+                success: true,
+                userOpHash: result.userOpHash,
+                transactionHash: result.transactionHash
+            };
+        } catch (error) {
+            console.error('Sponsored batch transaction failed:', error);
+            return {
+                success: false,
+                userOpHash: '0x' as Hex,
+                error: error instanceof Error ? error.message : 'Unknown error occurred'
+            };
+        }
+    }
+
+    /**
+     * Clear all caches
+     */
+    clearCache(): void {
+        if (this.aaService) {
+            this.aaService.clearCache();
+        }
+        this.kernelAccount = null;
+        this.sessionAccount = null;
+    }
+}