@deserialize/multi-vm-wallet 1.2.293 → 1.3.0

package/dist/evm/smartWallet.js

@@ -0,0 +1,675 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EVMSmartWallet = void 0;
+const accounts_1 = require("viem/accounts");
+const smartWallet_types_1 = require("./smartWallet.types");
+// Import AA service from local aa-service
+const account_abstraction_1 = require("./aa-service/services/account-abstraction");
+const kernel_account_1 = require("./aa-service/lib/kernel-account");
+/**
+ * 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
+ */
+class EVMSmartWallet {
+    aaService = null;
+    kernelAccount = null;
+    ownerAccount;
+    chain;
+    options;
+    sessionAccount = null;
+    paymasterConfig = null;
+    bundlerUrl;
+    constructor(privateKey, chain, bundlerUrl, options = {}) {
+        this.ownerAccount = (0, accounts_1.privateKeyToAccount)(privateKey);
+        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() {
+        try {
+            // Initialize AA service singleton with custom bundler URL
+            this.aaService = account_abstraction_1.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 smartWallet_types_1.SmartWalletError(`Failed to initialize smart wallet: ${error instanceof Error ? error.message : 'Unknown error'}`, 'INIT_ERROR');
+        }
+    }
+    /**
+     * Get the smart account address
+     */
+    getAddress() {
+        if (!this.kernelAccount) {
+            throw new smartWallet_types_1.SmartWalletError('Smart wallet not initialized', 'NOT_INITIALIZED');
+        }
+        return this.kernelAccount.address;
+    }
+    /**
+     * Get smart account information
+     */
+    async getAccountInfo() {
+        if (!this.kernelAccount || !this.aaService) {
+            throw new smartWallet_types_1.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,
+            ownerAddress: this.ownerAccount.address,
+            chain: this.chain,
+            entryPointVersion: this.options.entryPointVersion,
+            isDelegated,
+            balance: BigInt(balance.balance.toString())
+        };
+    }
+    /**
+     * Get smart account balance
+     */
+    async getBalance() {
+        if (!this.kernelAccount || !this.aaService) {
+            throw new smartWallet_types_1.SmartWalletError('Smart wallet not initialized', 'NOT_INITIALIZED');
+        }
+        const balance = await this.aaService.getBalance(this.kernelAccount);
+        return {
+            balance: balance,
+            decimal: 18,
+            formatted: Number(balance) / 1e18
+        };
+    }
+    /**
+     * Check if account is delegated
+     */
+    async isAccountDelegated() {
+        if (!this.aaService) {
+            throw new smartWallet_types_1.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, value = 0n, data = '0x') {
+        if (!this.kernelAccount || !this.aaService) {
+            throw new smartWallet_types_1.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',
+                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) {
+        if (!this.kernelAccount || !this.aaService) {
+            throw new smartWallet_types_1.SmartWalletError('Smart wallet not initialized', 'NOT_INITIALIZED');
+        }
+        if (calls.length === 0) {
+            throw new smartWallet_types_1.TransactionError('Batch transaction must have at least one call');
+        }
+        try {
+            // Convert to AA service Call format
+            const aaCalls = 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',
+                error: errorMsg
+            };
+        }
+    }
+    /**
+     * Prepare a call for batching
+     * Helper method to create Call objects
+     */
+    prepareCall(to, value = 0n, data = '0x') {
+        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() {
+        if (!this.aaService) {
+            throw new smartWallet_types_1.SmartWalletError('Smart wallet not initialized', 'NOT_INITIALIZED');
+        }
+        try {
+            return await this.aaService.generateSessionKey();
+        }
+        catch (error) {
+            throw new smartWallet_types_1.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) {
+        if (!this.aaService) {
+            throw new smartWallet_types_1.SmartWalletError('Smart wallet not initialized', 'NOT_INITIALIZED');
+        }
+        try {
+            return await this.aaService.recreateSessionKey(privateKey);
+        }
+        catch (error) {
+            throw new smartWallet_types_1.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) {
+        if (!this.aaService) {
+            throw new smartWallet_types_1.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 smartWallet_types_1.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) {
+        if (!this.aaService) {
+            throw new smartWallet_types_1.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 smartWallet_types_1.SessionKeyError(`Failed to use session key: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    /**
+     * Clear session key (revert to owner account)
+     */
+    clearSessionKey() {
+        this.sessionAccount = null;
+    }
+    /**
+     * Check if using session key
+     */
+    isUsingSessionKey() {
+        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, maxAmount) {
+        if (!this.aaService) {
+            throw new smartWallet_types_1.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) {
+        if (!this.aaService) {
+            throw new smartWallet_types_1.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) {
+        if (!this.kernelAccount || !this.aaService) {
+            throw new smartWallet_types_1.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 smartWallet_types_1.ModuleError(`Failed to install module: ${errorMsg}`);
+        }
+    }
+    /**
+     * Uninstall a module from the smart account
+     *
+     * @param options - Module uninstallation options
+     * @returns Transaction result
+     */
+    async uninstallModule(options) {
+        if (!this.kernelAccount || !this.aaService) {
+            throw new smartWallet_types_1.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 smartWallet_types_1.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, moduleAddress) {
+        if (!this.kernelAccount || !this.aaService) {
+            throw new smartWallet_types_1.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) {
+        if (!this.kernelAccount || !this.aaService) {
+            throw new smartWallet_types_1.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) {
+        if (!this.kernelAccount || !this.aaService) {
+            throw new smartWallet_types_1.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) {
+        if (!this.kernelAccount || !this.aaService) {
+            throw new smartWallet_types_1.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 smartWallet_types_1.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, context) {
+        this.paymasterConfig = {
+            paymasterUrl,
+            context
+        };
+    }
+    /**
+     * Clear paymaster (user pays gas)
+     */
+    clearPaymaster() {
+        this.paymasterConfig = null;
+    }
+    /**
+     * Check if paymaster is configured
+     */
+    hasPaymaster() {
+        return this.paymasterConfig !== null;
+    }
+    /**
+     * Get bundler information
+     */
+    getBundlerInfo() {
+        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, feePayerPrivateKey) {
+        if (!this.aaService) {
+            throw new smartWallet_types_1.SmartWalletError('Smart wallet not initialized. Call initialize() first.', 'NOT_INITIALIZED');
+        }
+        if (!this.kernelAccount) {
+            throw new smartWallet_types_1.SmartWalletError('Kernel account not found. Smart wallet may not be properly initialized.', 'ACCOUNT_NOT_FOUND');
+        }
+        try {
+            // Create authorization for owner wallet
+            const authorization = await (0, kernel_account_1.createKernelAuthorization)({
+                owner: this.ownerAccount,
+                chain: this.chain,
+                bundlerManager: this.aaService.getBundlerManager(this.chain)
+            });
+            if (!authorization) {
+                throw new smartWallet_types_1.SmartWalletError('Failed to create authorization for sponsored transaction', 'AUTHORIZATION_FAILED');
+            }
+            // Send sponsored transaction with feePayer
+            const result = await (0, kernel_account_1.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',
+                error: error instanceof Error ? error.message : 'Unknown error occurred'
+            };
+        }
+    }
+    /**
+     * Clear all caches
+     */
+    clearCache() {
+        if (this.aaService) {
+            this.aaService.clearCache();
+        }
+        this.kernelAccount = null;
+        this.sessionAccount = null;
+    }
+}
+exports.EVMSmartWallet = EVMSmartWallet;
+//# sourceMappingURL=smartWallet.js.map