@deserialize/multi-vm-wallet 1.2.441 → 1.3.0

package/utils/evm/aa-service/lib/session-keys.ts

@@ -0,0 +1,389 @@
+/**
+ * EIP-7702 Session Keys Utilities
+ *
+ * Utilities for creating and managing session keys with ZeroDev's permission system.
+ * This uses the NEW EIP-7702 pattern, not the legacy smart account pattern.
+ *
+ * Key differences from legacy pattern:
+ * - Uses `eip7702Account` instead of `address`
+ * - Uses `addressToEmptyAccount` for permission validator creation
+ * - Passes `sessionKeySigner` to `deserializePermissionAccount`
+ * - No sudo validator needed, only permission plugin
+ */
+
+import { Hex, Address, createPublicClient, http, parseAbi, parseUnits, parseEther } from 'viem';
+import { Chain } from 'viem/chains';
+import { PrivateKeyAccount, privateKeyToAccount, generatePrivateKey } from 'viem/accounts';
+import {
+    createKernelAccount,
+    createKernelAccountClient,
+    addressToEmptyAccount,
+    // serializePermissionAccount,
+    // deserializePermissionAccount
+} from '@zerodev/sdk';
+import { toECDSASigner } from '@zerodev/permissions/signers';
+import { toPermissionValidator, ModularSigner } from '@zerodev/permissions';
+import { toSudoPolicy, toCallPolicy, CallPolicyVersion } from '@zerodev/permissions/policies';
+import { getEntryPoint, KERNEL_V3_3 } from '@zerodev/sdk/constants';
+
+// ============================================
+// Types
+// ============================================
+
+export interface SessionKeyPermissionRule {
+    target: Hex;
+    abi: any[];
+    functionName: string;
+    args?: any[];
+}
+
+export interface CreateSessionKeyApprovalOptions {
+    sessionKeyAddress: Address;
+    owner: PrivateKeyAccount;
+    chain: Chain;
+    entryPointVersion?: '0.6' | '0.7';
+    useSudoPolicy?: boolean;
+    permissions?: SessionKeyPermissionRule[];
+}
+
+export interface SessionKeyInfo {
+    privateKey: Hex;
+    address: Address;
+    signer: ModularSigner;
+}
+
+export interface DeserializedSessionKey {
+    account: any;
+    client: any;
+}
+
+// ============================================
+// Session Key Generation
+// ============================================
+
+/**
+ * Generate a new session key
+ *
+ * Creates a new keypair for use as a session key.
+ * The private key should be stored securely and shared with the agent.
+ * The address should be shared with the owner for approval.
+ *
+ * @returns Session key info including private key, address, and signer
+ *
+ * @example
+ * const sessionKey = await generateSessionKey();
+ * console.log("Share this address with owner:", sessionKey.address);
+ * console.log("Keep this private key secure:", sessionKey.privateKey);
+ */
+export async function generateSessionKey(): Promise<SessionKeyInfo> {
+    const sessionPrivateKey = generatePrivateKey();
+    const sessionKeyAccount = privateKeyToAccount(sessionPrivateKey);
+    const sessionKeySigner = await toECDSASigner({
+        signer: sessionKeyAccount as any,
+    });
+
+    return {
+        privateKey: sessionPrivateKey,
+        address: sessionKeyAccount.address,
+        signer: sessionKeySigner
+    };
+}
+
+/**
+ * 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
+ * const sessionKey = await recreateSessionKey(storedPrivateKey);
+ */
+export async function recreateSessionKey(privateKey: Hex): Promise<SessionKeyInfo> {
+    const sessionKeyAccount = privateKeyToAccount(privateKey);
+    const sessionKeySigner = await toECDSASigner({
+        signer: sessionKeyAccount as any,
+    });
+
+    return {
+        privateKey,
+        address: sessionKeyAccount.address,
+        signer: sessionKeySigner
+    };
+}
+
+// ============================================
+// Owner Side: Create Approval
+// ============================================
+
+/**
+ * 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
+ * const approval = await createSessionKeyApproval({
+ *     sessionKeyAddress: '0x...', // Agent's session key address
+ *     owner: ownerAccount,
+ *     chain: sepolia,
+ *     permissions: [{
+ *         target: USDC_ADDRESS,
+ *         abi: parseAbi(['function transfer(address to, uint256 amount)']),
+ *         functionName: 'transfer',
+ *         args: [null, { condition: 3, value: parseUnits('10', 6) }]
+ *     }]
+ * });
+ * // Share approval with agent
+ */
+export async function createSessionKeyApproval(
+    options: CreateSessionKeyApprovalOptions
+): Promise<string> {
+    const {
+        sessionKeyAddress,
+        owner,
+        chain,
+        entryPointVersion = '0.7',
+        useSudoPolicy = false,
+        permissions = []
+    } = options;
+
+    const publicClient = createPublicClient({
+        chain,
+        transport: http()
+    });
+
+    const entryPoint = getEntryPoint(entryPointVersion);
+
+    // Create "empty account" from just the session key address
+    // This is the KEY difference from legacy pattern!
+    const emptyAccount = addressToEmptyAccount(sessionKeyAddress);
+    const emptySessionKeySigner = await toECDSASigner({
+        signer: emptyAccount
+    });
+
+    // Create permission plugin
+    let policies: any[];
+
+    if (useSudoPolicy || permissions.length === 0) {
+        // Sudo policy - unrestricted access
+        policies = [toSudoPolicy({})];
+    } else {
+        // Call policy - restricted access
+        const callPermissions = permissions.map(perm => ({
+            target: perm.target,
+            abi: perm.abi,
+            functionName: perm.functionName,
+            args: perm.args || []
+        }));
+
+        policies = [
+            toCallPolicy({
+                policyVersion: CallPolicyVersion.V0_0_5,
+                permissions: callPermissions
+            })
+        ];
+    }
+
+    const permissionPlugin = await toPermissionValidator(publicClient as any, {
+        entryPoint,
+        signer: emptySessionKeySigner,
+        policies,
+        kernelVersion: KERNEL_V3_3,
+    });
+
+    // Create kernel account with eip7702Account (NOT address!)
+    const sessionKeyAccount = await createKernelAccount(publicClient as any, {
+        entryPoint,
+        eip7702Account: owner as any,  // ← EIP-7702 pattern
+        plugins: {
+            regular: permissionPlugin,
+        },
+        kernelVersion: KERNEL_V3_3,
+        // NO address parameter!
+    });
+
+    // Serialize approval (no private key in approval)
+    // TODO: serializePermissionAccount not available in @zerodev/sdk yet
+    // const approval = await serializePermissionAccount(sessionKeyAccount);
+    const approval = JSON.stringify({ sessionKeyAccount: 'placeholder' });
+
+    return approval;
+}
+
+// ============================================
+// Agent Side: Use Session Key
+// ============================================
+
+/**
+ * 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 approval - Approval string from owner
+ * @param sessionKeySigner - Session key signer (created from private key)
+ * @param chain - Chain to use
+ * @param entryPointVersion - EntryPoint version
+ * @returns Deserialized session key account
+ *
+ * @example
+ * // Agent deserializes with private key
+ * const sessionKey = await recreateSessionKey(storedPrivateKey);
+ * const account = await deserializeSessionKey({
+ *     approval,
+ *     sessionKeySigner: sessionKey.signer,
+ *     chain: sepolia
+ * });
+ */
+export async function deserializeSessionKey(options: {
+    approval: string;
+    sessionKeySigner: ModularSigner;
+    chain: Chain;
+    entryPointVersion?: '0.6' | '0.7';
+}): Promise<any> {
+    const {
+        approval,
+        sessionKeySigner,
+        chain,
+        entryPointVersion = '0.7'
+    } = options;
+
+    const publicClient = createPublicClient({
+        chain,
+        transport: http()
+    });
+
+    const entryPoint = getEntryPoint(entryPointVersion);
+
+    // Deserialize WITH the session key signer
+    // This is the 5-parameter version (not 4!)
+    // TODO: deserializePermissionAccount not available in @zerodev/sdk yet
+    // const sessionKeyAccount = await deserializePermissionAccount(
+    //     publicClient,
+    //     entryPoint,
+    //     KERNEL_V3_3,
+    //     approval,
+    //     sessionKeySigner  // ← Must pass the signer!
+    // );
+
+    // Placeholder until SDK is available
+    const sessionKeyAccount = null;
+
+    return sessionKeyAccount;
+}
+
+/**
+ * Create kernel client for session key
+ *
+ * Creates a client for sending transactions with the session key.
+ *
+ * @param account - Deserialized session key account
+ * @param chain - Chain to use
+ * @param bundlerUrl - Bundler RPC URL
+ * @param paymasterUrl - Optional paymaster URL for gas sponsorship
+ * @returns Kernel account client
+ *
+ * @example
+ * const client = createSessionKeyClient({
+ *     account: sessionKeyAccount,
+ *     chain: sepolia,
+ *     bundlerUrl: 'https://api.pimlico.io/...'
+ * });
+ */
+export function createSessionKeyClient(options: {
+    account: any;
+    chain: Chain;
+    bundlerUrl: string;
+    paymasterUrl?: string;
+}): any {
+    const {
+        account,
+        chain,
+        bundlerUrl,
+        paymasterUrl
+    } = options;
+
+    const clientOptions: any = {
+        account,
+        chain,
+        bundlerTransport: http(bundlerUrl)
+    };
+
+    // Add paymaster if provided
+    if (paymasterUrl) {
+        // Note: Paymaster client creation would go here
+        // For now, just the basic client
+    }
+
+    const kernelClient = createKernelAccountClient(clientOptions);
+
+    return kernelClient;
+}
+
+// ============================================
+// Convenience Functions
+// ============================================
+
+/**
+ * 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 = createUSDCTransferPermission(
+ *     '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238',
+ *     '10' // Max 10 USDC
+ * );
+ */
+export function createUSDCTransferPermission(
+    usdcAddress: Hex,
+    maxAmount: string
+): SessionKeyPermissionRule {
+    return {
+        target: usdcAddress,
+        abi: parseAbi(['function transfer(address to, uint256 amount) returns (bool)']) as any,
+        functionName: 'transfer',
+        args: [
+            null, // Any recipient
+            {
+                condition: 3, // LESS_THAN_OR_EQUAL
+                value: parseUnits(maxAmount, 6) // USDC has 6 decimals
+            }
+        ]
+    };
+}
+
+/**
+ * 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 = createETHTransferPermission('0.1'); // Max 0.1 ETH
+ */
+export function createETHTransferPermission(maxValue: string): SessionKeyPermissionRule {
+    return {
+        target: '0x0000000000000000000000000000000000000000' as Hex, // Native token
+        abi: [],
+        functionName: '',
+        args: [
+            {
+                condition: 3, // LESS_THAN_OR_EQUAL
+                value: parseEther(maxValue)
+            }
+        ]
+    };
+}

package/utils/evm/aa-service/lib/type.ts

@@ -0,0 +1,236 @@
+/**
+ * Smart Wallet Types
+ *
+ * Type definitions for EVM smart wallet functionality using Account Abstraction (EIP-4337)
+ * and EIP-7702 delegation features.
+ */
+
+import { Chain, Hex, SignAuthorizationReturnType } from "viem";
+import { PrivateKeyAccount } from "viem/accounts";
+import { ModularSigner } from "@zerodev/permissions";
+import { EntryPointVersion as ViemEntryPointVersion } from "viem/account-abstraction";
+import { BundlerManager } from "../services/bundler";
+import { ModuleType } from "./kernel-modules";
+import { SessionKeyPermissionRule } from "./session-keys";
+
+// ============================================
+// Types
+// ============================================
+
+export type KernelVersion = '0.3.3';
+export type EntryPointVersion = '0.6' | '0.7';
+
+/**
+ * Single call/operation in a transaction
+ */
+export interface Call {
+    /** Target contract address */
+    to: Hex;
+    /** ETH value to send (optional, defaults to 0) */
+    value?: bigint;
+    /** Calldata (optional, defaults to '0x') */
+    data?: Hex;
+}
+/**
+ * Batch transaction configuration
+ */
+export interface BatchTransactionConfig {
+    kernelAccount: KernelAccountInstance;
+    bundlerManager: BundlerManager;
+    authorization?: SignAuthorizationReturnType;
+    calls: Call[];
+}
+
+/**
+ * Single transaction configuration (convenience)
+ */
+export interface SingleTransactionConfig {
+    kernelAccount: KernelAccountInstance;
+    bundlerManager: BundlerManager;
+    authorization?: SignAuthorizationReturnType;
+    to: Hex;
+    value?: bigint;
+    data?: Hex;
+}
+
+export interface KernelAccountConfig {
+    chain: Chain;
+    owner: PrivateKeyAccount;
+    bundlerManager: BundlerManager;
+    entryPointVersion?: EntryPointVersion;
+    kernelVersion?: KernelVersion;
+}
+
+export interface KernelAccountInstance {
+    account: any; // The kernel account from ZeroDev
+    address: string;
+    owner: PrivateKeyAccount;
+    chain: Chain;
+    entryPoint: {
+        address: Hex;
+        version: EntryPointVersion;
+    };
+}
+// ============================================
+// Configuration Types
+// ============================================
+
+
+
+
+
+export interface SmartWalletOptions {
+    /** Bundler URL for submitting UserOperations */
+    bundlerUrl?: string;
+    /** Paymaster URL for gas sponsorship (optional) */
+    paymasterUrl?: string;
+    /** EntryPoint version to use (default: '0.7') */
+    entryPointVersion?: EntryPointVersion;
+    /** Auto-initialize on extend (default: true) */
+    autoInitialize?: boolean;
+}
+
+// ============================================
+// Transaction Types
+// ============================================
+
+
+
+export interface SmartWalletTransactionResult {
+    /** Whether the transaction succeeded */
+    success: boolean;
+    /** UserOperation hash */
+    userOpHash: Hex;
+    /** Transaction hash (after bundler execution) */
+    transactionHash?: string;
+    /** Error message if failed */
+    error?: string;
+}
+
+export interface GasEstimate {
+    /** Estimated gas for UserOperation */
+    callGasLimit: bigint;
+    /** Estimated verification gas */
+    verificationGasLimit: bigint;
+    /** Estimated pre-verification gas */
+    preVerificationGas: bigint;
+    /** Total estimated gas */
+    total: bigint;
+}
+
+
+
+
+export interface SessionKeyApprovalOptions {
+    /** Session key address to approve */
+    sessionKeyAddress: Hex;
+    /** Permission rules for the session key */
+    permissions?: SessionKeyPermissionRule[];
+    /** Use unrestricted sudo policy (not recommended for production) */
+    useSudoPolicy?: boolean;
+}
+
+export interface SessionKeyUsageOptions {
+    /** Serialized approval from owner */
+    approval: string;
+    /** Session key signer */
+    sessionKeySigner: ModularSigner;
+}
+
+// ============================================
+// Module Types
+// ============================================
+
+export interface ModuleInstallOptions {
+    /** Type of module to install */
+    moduleType: ModuleType;
+    /** Module contract address */
+    moduleAddress: Hex;
+    /** Initialization data for the module */
+    initData?: Hex;
+}
+
+export interface ModuleUninstallOptions {
+    /** Type of module to uninstall */
+    moduleType: ModuleType;
+    /** Module contract address */
+    moduleAddress: Hex;
+    /** De-initialization data for the module */
+    deInitData?: Hex;
+}
+
+
+// ============================================
+// Advanced Feature Types
+// ============================================
+
+export interface MultiSigConfig {
+    /** List of owner addresses */
+    owners: Hex[];
+    /** Number of signatures required (threshold) */
+    threshold: number;
+}
+
+export interface RecoveryConfig {
+    /** Guardian addresses for account recovery */
+    guardians: Hex[];
+    /** Recovery delay in seconds */
+    recoveryDelay?: number;
+}
+
+export interface PaymasterConfig {
+    /** Paymaster URL for sponsored transactions */
+    paymasterUrl: string;
+    /** Paymaster context (optional, provider-specific) */
+    context?: any;
+}
+
+export interface SmartAccountInfo {
+    /** Smart account address */
+    address: Hex;
+    /** Owner EOA address */
+    ownerAddress: Hex;
+    /** Chain information */
+    chain: Chain;
+    /** EntryPoint version */
+    entryPointVersion: EntryPointVersion;
+    /** Whether account is delegated (EIP-7702) */
+    isDelegated: boolean;
+    /** Current balance in wei */
+    balance: bigint;
+}
+
+// ============================================
+// Error Types
+// ============================================
+
+export class SmartWalletError extends Error {
+    code: string;
+
+    constructor(message: string, code: string = 'SMART_WALLET_ERROR') {
+        super(message);
+        this.name = 'SmartWalletError';
+        this.code = code;
+    }
+}
+
+export class SessionKeyError extends SmartWalletError {
+    constructor(message: string) {
+        super(message, 'SESSION_KEY_ERROR');
+        this.name = 'SessionKeyError';
+    }
+}
+
+export class ModuleError extends SmartWalletError {
+    constructor(message: string) {
+        super(message, 'MODULE_ERROR');
+        this.name = 'ModuleError';
+    }
+}
+
+export class TransactionError extends SmartWalletError {
+    constructor(message: string) {
+        super(message, 'TRANSACTION_ERROR');
+        this.name = 'TransactionError';
+    }
+}