@deserialize/multi-vm-wallet 1.2.441 → 1.3.0

package/dist/evm/aa-service/services/account-abstraction.d.ts

@@ -0,0 +1,614 @@
+/**
+ * Account Abstraction Service (Singleton)
+ *
+ * Centralized service for managing Kernel accounts, bundlers, and transactions.
+ * Use this singleton across your application for consistent AA operations.
+ *
+ * Usage:
+ *   const aaService = AccountAbstractionService.getInstance({
+ *     bundlerProvider: 'pimlico',
+ *     apiKey: env.pimlicoApiKey
+ *   });
+ *
+ *   const account = await aaService.createAccount(sepolia, owner);
+ *   const txHash = await aaService.sendTransaction({ account, to, value });
+ */
+import { Chain, Hex } from 'viem';
+import { PrivateKeyAccount } from 'viem/accounts';
+import { SignAuthorizationReturnType } from 'viem';
+import { BundlerManager } from './bundler';
+import { KernelAccountInstance, EntryPointVersion, Call } from '../lib/kernel-account';
+import { ModuleType, SessionKeyPermission } from '../lib/kernel-modules';
+import { SessionKeyInfo, SessionKeyPermissionRule } from '../lib/session-keys';
+import { ModularSigner } from '@zerodev/permissions';
+export interface AAServiceConfig {
+    bundlerProvider: 'pimlico' | 'etherspot' | 'custom';
+    apiKey?: string;
+    customBundlerUrl?: string;
+}
+export interface CreateAccountOptions {
+    chain: Chain;
+    owner: PrivateKeyAccount;
+    entryPointVersion?: EntryPointVersion;
+}
+export interface SendTransactionOptions {
+    account: KernelAccountInstance;
+    to: Hex;
+    value?: bigint;
+    data?: Hex;
+    authorization?: SignAuthorizationReturnType;
+}
+export interface SendBatchTransactionOptions {
+    account: KernelAccountInstance;
+    calls: Call[];
+    authorization?: SignAuthorizationReturnType;
+}
+export interface WaitForReceiptOptions {
+    userOpHash: Hex;
+    chain: Chain;
+}
+export declare class AccountAbstractionService {
+    private static instance;
+    private bundlerManager;
+    private accountCache;
+    private authorizationCache;
+    private publicClientCache;
+    /**
+     * Private constructor (singleton pattern)
+     */
+    private constructor();
+    /**
+     * Get singleton instance
+     */
+    static getInstance(config?: AAServiceConfig): AccountAbstractionService;
+    /**
+     * Reset singleton instance (useful for testing or reconfiguration)
+     */
+    static reset(): void;
+    /**
+     * Update bundler configuration (creates new bundler manager)
+     */
+    updateBundlerConfig(config: AAServiceConfig): void;
+    /**
+     * Create a Kernel 7702 account
+     */
+    createAccount(options: CreateAccountOptions): Promise<KernelAccountInstance>;
+    /**
+     * Get cached account (if exists)
+     */
+    getCachedAccount(chain: Chain, owner: PrivateKeyAccount, entryPointVersion?: EntryPointVersion): KernelAccountInstance | undefined;
+    /**
+     * Check if account is already delegated to Kernel
+     */
+    isAccountDelegated(owner: PrivateKeyAccount, chain: Chain): Promise<boolean>;
+    /**
+     * Create EIP-7702 authorization (if needed)
+     */
+    createAuthorization(options: {
+        owner: PrivateKeyAccount;
+        chain: Chain;
+    }): Promise<SignAuthorizationReturnType | undefined>;
+    /**
+     * Prepare a call (for batching)
+     *
+     * Returns a Call object that can be included in a batch transaction.
+     * Use this to prepare any transfer or contract interaction for batching.
+     *
+     * @example
+     * // Prepare multiple calls
+     * const calls = [
+     *     aaService.prepareCall({ to: recipient1, value: parseEther('0.1') }),
+     *     aaService.prepareCall({ to: recipient2, value: parseEther('0.2') }),
+     *     aaService.prepareCall({ to: contractAddress, data: encodedData })
+     * ];
+     * await aaService.sendBatchTransaction({ account, calls });
+     */
+    prepareCall(options: {
+        to: Hex;
+        value?: bigint;
+        data?: Hex;
+    }): Call;
+    /**
+     * Prepare a contract call (for batching)
+     *
+     * Helper for preparing contract interactions with type-safe encoding.
+     *
+     * @example
+     * import { parseAbi, encodeFunctionData } from 'viem';
+     *
+     * const call = aaService.prepareContractCall({
+     *     to: USDC_ADDRESS,
+     *     data: encodeFunctionData({
+     *         abi: parseAbi(['function transfer(address to, uint256 amount)']),
+     *         functionName: 'transfer',
+     *         args: [recipient, parseUnits('100', 6)]
+     *     })
+     * });
+     */
+    prepareContractCall(options: {
+        to: Hex;
+        data: Hex;
+        value?: bigint;
+    }): Call;
+    /**
+     * Send a transaction using Kernel account (execute immediately)
+     *
+     * For batching multiple operations, use prepareCall() + sendBatchTransaction() instead.
+     *
+     * @example
+     * // Single transaction
+     * await aaService.sendTransaction({
+     *     account,
+     *     to: recipient,
+     *     value: parseEther('0.1')
+     * });
+     *
+     * // For batching, use prepareCall instead:
+     * const calls = [
+     *     aaService.prepareCall({ to: recipient1, value: parseEther('0.1') }),
+     *     aaService.prepareCall({ to: recipient2, value: parseEther('0.2') })
+     * ];
+     * await aaService.sendBatchTransaction({ account, calls });
+     */
+    sendTransaction(options: SendTransactionOptions): Promise<Hex>;
+    /**
+     * Wait for transaction receipt
+     */
+    waitForReceipt(options: WaitForReceiptOptions): Promise<any>;
+    /**
+     * Send transaction and wait for receipt (convenience method)
+     */
+    sendTransactionAndWait(options: SendTransactionOptions): Promise<{
+        userOpHash: Hex;
+        receipt: any;
+    }>;
+    /**
+     * Send batch transaction (RECOMMENDED for smart accounts)
+     *
+     * Sends multiple calls in a single UserOperation, paying gas ONLY ONCE.
+     * This is one of the main advantages of smart accounts over EOAs.
+     *
+     * Use prepare*() methods to create Call objects for batching:
+     * - prepareCall() - for transfers and contract interactions
+     * - prepareInstallModule() - for module installations
+     * - prepareInstallSessionKey() - for session keys
+     * - prepareInstallMultiSigValidator() - for multi-sig
+     * - etc.
+     *
+     * @example
+     * // Send ETH to 3 recipients in one transaction
+     * const calls = [
+     *     aaService.prepareCall({ to: '0xRecipient1', value: parseEther('0.01') }),
+     *     aaService.prepareCall({ to: '0xRecipient2', value: parseEther('0.02') }),
+     *     aaService.prepareCall({ to: '0xRecipient3', value: parseEther('0.03') })
+     * ];
+     * await aaService.sendBatchTransaction({ account, calls });
+     *
+     * @example
+     * // Mix transfers, contract calls, and module installations
+     * const calls = [
+     *     aaService.prepareCall({ to: recipient, value: parseEther('0.1') }),
+     *     aaService.prepareContractCall({ to: USDC, data: transferData }),
+     *     aaService.prepareInstallSessionKey({ account, sessionKeyAddress, permissions })
+     * ];
+     * await aaService.sendBatchTransaction({ account, calls });
+     *
+     * @example
+     * // Install multiple modules at once
+     * const calls = [
+     *     aaService.prepareInstallSessionKey({ account, ... }),
+     *     aaService.prepareInstallMultiSigValidator({ account, ... }),
+     *     aaService.prepareInstallModule({ account, moduleType: 'hook', ... })
+     * ];
+     * await aaService.sendBatchTransaction({ account, calls });
+     */
+    sendBatchTransaction(options: SendBatchTransactionOptions): Promise<Hex>;
+    /**
+     * Send batch transaction and wait for receipt (convenience method)
+     *
+     * Same as sendBatchTransaction but waits for confirmation.
+     */
+    sendBatchTransactionAndWait(options: SendBatchTransactionOptions): Promise<{
+        userOpHash: Hex;
+        receipt: any;
+    }>;
+    /**
+     * Get account balance
+     */
+    getBalance(account: KernelAccountInstance): Promise<bigint>;
+    /**
+     * Get or create public client for standard RPC calls
+     * (bundler clients don't support standard eth_* methods)
+     */
+    private getPublicClient;
+    /**
+     * Get bundler information
+     */
+    getBundlerInfo(chain: Chain): {
+        provider: string;
+        url: string;
+    };
+    /**
+     * Get bundler client directly (advanced usage)
+     */
+    getBundlerClient(chain: Chain): any;
+    /**
+     * Get bundler manager (advanced usage)
+     */
+    getBundlerManager(chain: Chain): BundlerManager;
+    /**
+     * Clear all caches
+     */
+    clearCache(): void;
+    /**
+     * Prepare module installation call (for batching)
+     *
+     * Returns a Call object that can be included in a batch transaction.
+     * This allows you to install multiple modules in a single UserOperation.
+     *
+     * @example
+     * // Batch install multiple modules
+     * const calls = [
+     *     aaService.prepareInstallModule({
+     *         account,
+     *         moduleType: 'validator',
+     *         moduleAddress: SESSION_KEY_VALIDATOR
+     *     }),
+     *     aaService.prepareInstallModule({
+     *         account,
+     *         moduleType: 'hook',
+     *         moduleAddress: SPENDING_LIMIT_HOOK
+     *     })
+     * ];
+     * await aaService.sendBatchTransaction({ account, calls });
+     */
+    prepareInstallModule(options: {
+        account: KernelAccountInstance;
+        moduleType: ModuleType;
+        moduleAddress: Hex;
+        initData?: Hex;
+    }): Call;
+    /**
+     * Install a module on an account (execute immediately)
+     *
+     * For batching multiple modules, use prepareInstallModule instead.
+     *
+     * @example
+     * // Install a single module
+     * await aaService.installModule({
+     *     account,
+     *     moduleType: 'validator',
+     *     moduleAddress: SESSION_KEY_VALIDATOR_ADDRESS,
+     *     initData: encodedPermissions
+     * });
+     */
+    installModule(options: {
+        account: KernelAccountInstance;
+        moduleType: ModuleType;
+        moduleAddress: Hex;
+        initData?: Hex;
+    }): Promise<Hex>;
+    /**
+     * Prepare module uninstallation call (for batching)
+     *
+     * Returns a Call object that can be included in a batch transaction.
+     *
+     * @example
+     * // Batch uninstall multiple modules
+     * const calls = [
+     *     aaService.prepareUninstallModule({ account, moduleType: 'validator', moduleAddress: '0x...' }),
+     *     aaService.prepareUninstallModule({ account, moduleType: 'hook', moduleAddress: '0x...' })
+     * ];
+     * await aaService.sendBatchTransaction({ account, calls });
+     */
+    prepareUninstallModule(options: {
+        account: KernelAccountInstance;
+        moduleType: ModuleType;
+        moduleAddress: Hex;
+        deInitData?: Hex;
+    }): Call;
+    /**
+     * Uninstall a module from an account (execute immediately)
+     *
+     * For batching, use prepareUninstallModule instead.
+     *
+     * @example
+     * await aaService.uninstallModule({
+     *     account,
+     *     moduleType: 'validator',
+     *     moduleAddress: SESSION_KEY_VALIDATOR_ADDRESS
+     * });
+     */
+    uninstallModule(options: {
+        account: KernelAccountInstance;
+        moduleType: ModuleType;
+        moduleAddress: Hex;
+        deInitData?: Hex;
+    }): Promise<Hex>;
+    /**
+     * Check if a module is installed
+     *
+     * @example
+     * const isInstalled = await aaService.isModuleInstalled({
+     *     account,
+     *     moduleType: 'validator',
+     *     moduleAddress: SESSION_KEY_VALIDATOR_ADDRESS
+     * });
+     */
+    isModuleInstalled(options: {
+        account: KernelAccountInstance;
+        moduleType: ModuleType;
+        moduleAddress: Hex;
+    }): Promise<boolean>;
+    /**
+     * Prepare session key installation call (for batching)
+     *
+     * Returns a Call object that can be batched with other operations.
+     *
+     * @example
+     * // Batch install session key with multi-sig
+     * const calls = [
+     *     aaService.prepareInstallSessionKey({ account, sessionKeyAddress, permissions }),
+     *     aaService.prepareInstallMultiSigValidator({ account, owners, threshold: 2 })
+     * ];
+     * await aaService.sendBatchTransaction({ account, calls });
+     */
+    prepareInstallSessionKey(options: {
+        account: KernelAccountInstance;
+        sessionKeyAddress: Hex;
+        permissions: SessionKeyPermission[];
+    }): Call;
+    /**
+     * Create and install a session key for automated operations (execute immediately)
+     *
+     * Perfect for use cases like:
+     * - Recurring payments
+     * - Automated savings
+     * - Subscription management
+     * - DCA (Dollar Cost Averaging)
+     *
+     * For batching with other operations, use prepareInstallSessionKey instead.
+     *
+     * @example
+     * // Create session key for monthly savings
+     * const sessionKey = privateKeyToAccount('0x...');
+     *
+     * await aaService.createSessionKey({
+     *     account,
+     *     sessionKeyAddress: sessionKey.address,
+     *     permissions: [{
+     *         target: USDC_ADDRESS,
+     *         functionSelector: '0xa9059cbb', // transfer(address,uint256)
+     *         maxValuePerUse: parseUnits('100', 6), // Max 100 USDC
+     *         validUntil: Date.now() + 30 * 24 * 60 * 60 * 1000, // 30 days
+     *         maxUses: 1 // Once per month
+     *     }]
+     * });
+     */
+    createSessionKey(options: {
+        account: KernelAccountInstance;
+        sessionKeyAddress: Hex;
+        permissions: SessionKeyPermission[];
+    }): Promise<Hex>;
+    /**
+     * Prepare session key revocation call (for batching)
+     *
+     * Returns a Call object that can be batched with other operations.
+     *
+     * @example
+     * // Batch revoke multiple session keys
+     * const calls = [
+     *     aaService.prepareRevokeSessionKey({ account, sessionKeyAddress: key1 }),
+     *     aaService.prepareRevokeSessionKey({ account, sessionKeyAddress: key2 })
+     * ];
+     * await aaService.sendBatchTransaction({ account, calls });
+     */
+    prepareRevokeSessionKey(options: {
+        account: KernelAccountInstance;
+        sessionKeyAddress: Hex;
+    }): Call;
+    /**
+     * Revoke a session key (execute immediately)
+     *
+     * For batching, use prepareRevokeSessionKey instead.
+     *
+     * @example
+     * await aaService.revokeSessionKey({
+     *     account,
+     *     sessionKeyAddress: sessionKey.address
+     * });
+     */
+    revokeSessionKey(options: {
+        account: KernelAccountInstance;
+        sessionKeyAddress: Hex;
+    }): Promise<Hex>;
+    /**
+     * Prepare multi-sig validator installation call (for batching)
+     *
+     * Returns a Call object that can be batched with other operations.
+     *
+     * @example
+     * // Batch install multi-sig with session key
+     * const calls = [
+     *     aaService.prepareInstallMultiSigValidator({ account, owners, threshold: 2 }),
+     *     aaService.prepareInstallSessionKey({ account, sessionKeyAddress, permissions })
+     * ];
+     * await aaService.sendBatchTransaction({ account, calls });
+     */
+    prepareInstallMultiSigValidator(options: {
+        account: KernelAccountInstance;
+        owners: Hex[];
+        threshold: number;
+    }): Call;
+    /**
+     * Install a multi-signature validator (execute immediately)
+     *
+     * For batching, use prepareInstallMultiSigValidator instead.
+     *
+     * @example
+     * await aaService.installMultiSigValidator({
+     *     account,
+     *     owners: [owner1, owner2, owner3],
+     *     threshold: 2 // 2 of 3 required
+     * });
+     */
+    installMultiSigValidator(options: {
+        account: KernelAccountInstance;
+        owners: Hex[];
+        threshold: number;
+    }): Promise<Hex>;
+    /**
+     * Generate a new session key
+     *
+     * Creates a new keypair for use as a session key with EIP-7702 accounts.
+     * The private key should be stored securely and shared with the agent.
+     * The address should be shared with the owner for approval.
+     *
+     * This uses the NEW EIP-7702 pattern, not the legacy module-based pattern.
+     *
+     * @returns Session key info including private key, address, and signer
+     *
+     * @example
+     * // Agent generates session key
+     * const sessionKey = await aaService.generateSessionKey();
+     * console.log("Share this address with owner:", sessionKey.address);
+     * console.log("Keep this private key secure:", sessionKey.privateKey);
+     * // Store sessionKey.privateKey securely for later use
+     */
+    generateSessionKey(): Promise<SessionKeyInfo>;
+    /**
+     * Recreate session key from private key
+     *
+     * Recreates a session key signer from a stored private key.
+     *
+     * @param privateKey - The session key private key
+     * @returns Session key info
+     *
+     * @example
+     * // Agent recreates session key from storage
+     * const sessionKey = await aaService.recreateSessionKey(storedPrivateKey);
+     */
+    recreateSessionKey(privateKey: Hex): Promise<SessionKeyInfo>;
+    /**
+     * Create session key approval (Owner side)
+     *
+     * The owner calls this to create an approval for a session key address.
+     * This uses the NEW EIP-7702 pattern with addressToEmptyAccount.
+     *
+     * @param options - Configuration options
+     * @returns Serialized approval string to share with the agent
+     *
+     * @example
+     * // Owner approves session key with USDC transfer restrictions
+     * const approval = await aaService.createSessionKeyApproval({
+     *     sessionKeyAddress: '0x...', // Agent's session key address
+     *     owner: ownerAccount,
+     *     chain: sepolia,
+     *     permissions: [
+     *         aaService.createUSDCTransferPermission(USDC_ADDRESS, '10') // Max 10 USDC
+     *     ]
+     * });
+     * // Share approval with agent
+     *
+     * @example
+     * // Owner approves session key with sudo (unrestricted) access
+     * const approval = await aaService.createSessionKeyApproval({
+     *     sessionKeyAddress: agentSessionKey.address,
+     *     owner: ownerAccount,
+     *     chain: sepolia,
+     *     useSudoPolicy: true
+     * });
+     */
+    createSessionKeyApproval(options: {
+        sessionKeyAddress: Hex;
+        owner: PrivateKeyAccount;
+        chain: Chain;
+        entryPointVersion?: '0.6' | '0.7';
+        useSudoPolicy?: boolean;
+        permissions?: SessionKeyPermissionRule[];
+    }): Promise<string>;
+    /**
+     * Deserialize session key account (Agent side)
+     *
+     * The agent calls this to reconstruct the session key account from the approval.
+     * This requires BOTH the approval AND the session key signer.
+     *
+     * @param options - Deserialization options
+     * @returns Deserialized session key account
+     *
+     * @example
+     * // Agent deserializes with private key
+     * const sessionKey = await aaService.recreateSessionKey(storedPrivateKey);
+     * const account = await aaService.deserializeSessionKey({
+     *     approval,
+     *     sessionKeySigner: sessionKey.signer,
+     *     chain: sepolia
+     * });
+     */
+    deserializeSessionKey(options: {
+        approval: string;
+        sessionKeySigner: ModularSigner;
+        chain: Chain;
+        entryPointVersion?: '0.6' | '0.7';
+    }): Promise<any>;
+    /**
+     * Create kernel client for session key
+     *
+     * Creates a client for sending transactions with the session key.
+     *
+     * @param options - Client options
+     * @returns Kernel account client
+     *
+     * @example
+     * // Agent creates client for session key
+     * const sessionKey = await aaService.recreateSessionKey(storedPrivateKey);
+     * const account = await aaService.deserializeSessionKey({
+     *     approval,
+     *     sessionKeySigner: sessionKey.signer,
+     *     chain: sepolia
+     * });
+     * const client = aaService.createSessionKeyClient({
+     *     account,
+     *     chain: sepolia,
+     *     bundlerUrl: 'https://api.pimlico.io/...'
+     * });
+     */
+    createSessionKeyClient(options: {
+        account: any;
+        chain: Chain;
+        bundlerUrl: string;
+        paymasterUrl?: string;
+    }): any;
+    /**
+     * Create USDC transfer permission rule
+     *
+     * Helper to create a permission rule for USDC transfers with a maximum amount.
+     *
+     * @param usdcAddress - USDC contract address
+     * @param maxAmount - Maximum USDC amount (in USDC units, e.g., "10" for 10 USDC)
+     * @returns Permission rule
+     *
+     * @example
+     * const rule = aaService.createUSDCTransferPermission(
+     *     '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238', // Sepolia USDC
+     *     '10' // Max 10 USDC
+     * );
+     */
+    createUSDCTransferPermission(usdcAddress: Hex, maxAmount: string): SessionKeyPermissionRule;
+    /**
+     * Create ETH transfer permission rule
+     *
+     * Helper to create a permission rule for ETH transfers with a maximum value.
+     *
+     * @param maxValue - Maximum ETH value (in ether units, e.g., "0.1" for 0.1 ETH)
+     * @returns Permission rule
+     *
+     * @example
+     * const rule = aaService.createETHTransferPermission('0.1'); // Max 0.1 ETH
+     */
+    createETHTransferPermission(maxValue: string): SessionKeyPermissionRule;
+    private getAccountCacheKey;
+    private getAuthorizationCacheKey;
+}
+export default AccountAbstractionService;
+export type { SessionKeyInfo, SessionKeyPermissionRule } from '../lib/session-keys';