@agirails/sdk 2.2.3 → 2.3.1

package/src/wallet/aa/BundlerClient.ts

@@ -0,0 +1,273 @@
+/**
+ * BundlerClient — JSON-RPC client for ERC-4337 bundlers.
+ *
+ * Supports Coinbase (primary) and Pimlico (backup) bundlers.
+ * Handles gas estimation, UserOp submission, and receipt polling.
+ * Retry with exponential backoff on transient failures.
+ *
+ * @module wallet/aa/BundlerClient
+ */
+
+import { UserOperationV06 } from './constants';
+import { serializeUserOp } from './UserOpBuilder';
+import { ENTRYPOINT_V06 } from './constants';
+import { sdkLogger } from '../../utils/Logger';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface BundlerConfig {
+  /** Primary bundler URL (Coinbase CDP) */
+  primaryUrl: string;
+  /** Backup bundler URL (Pimlico) */
+  backupUrl?: string;
+  /** Max retry attempts per endpoint */
+  maxRetries?: number;
+  /** Base delay for exponential backoff (ms) */
+  baseDelayMs?: number;
+  /** Timeout for individual requests (ms) */
+  timeoutMs?: number;
+}
+
+export interface UserOpReceipt {
+  /** UserOp hash */
+  userOpHash: string;
+  /** Transaction hash on-chain */
+  transactionHash: string;
+  /** Block number */
+  blockNumber: number;
+  /** Whether the UserOp execution succeeded */
+  success: boolean;
+}
+
+interface JsonRpcResponse<T = unknown> {
+  jsonrpc: string;
+  id: number;
+  result?: T;
+  error?: { code: number; message: string; data?: unknown };
+}
+
+// ============================================================================
+// BundlerClient
+// ============================================================================
+
+export class BundlerClient {
+  private readonly primaryUrl: string;
+  private readonly backupUrl: string | undefined;
+  private readonly maxRetries: number;
+  private readonly baseDelayMs: number;
+  private readonly timeoutMs: number;
+  private requestId = 1;
+
+  constructor(config: BundlerConfig) {
+    this.primaryUrl = config.primaryUrl;
+    this.backupUrl = config.backupUrl;
+    this.maxRetries = config.maxRetries ?? 2;
+    this.baseDelayMs = config.baseDelayMs ?? 1000;
+    this.timeoutMs = config.timeoutMs ?? 30_000;
+  }
+
+  /**
+   * Estimate gas for a UserOp.
+   */
+  async estimateUserOperationGas(
+    userOp: UserOperationV06
+  ): Promise<{ callGasLimit: bigint; verificationGasLimit: bigint; preVerificationGas: bigint }> {
+    const result = await this.callWithFallback<{
+      callGasLimit: string;
+      verificationGasLimit: string;
+      preVerificationGas: string;
+    }>('eth_estimateUserOperationGas', [
+      serializeUserOp(userOp),
+      ENTRYPOINT_V06,
+    ]);
+
+    return {
+      callGasLimit: BigInt(result.callGasLimit),
+      verificationGasLimit: BigInt(result.verificationGasLimit),
+      preVerificationGas: BigInt(result.preVerificationGas),
+    };
+  }
+
+  /**
+   * Submit a signed UserOp to the bundler.
+   * Returns the UserOp hash.
+   */
+  async sendUserOperation(userOp: UserOperationV06): Promise<string> {
+    return this.callWithFallback<string>('eth_sendUserOperation', [
+      serializeUserOp(userOp),
+      ENTRYPOINT_V06,
+    ]);
+  }
+
+  /**
+   * Get the receipt for a submitted UserOp.
+   * Returns null if not yet mined.
+   */
+  async getUserOperationReceipt(
+    userOpHash: string
+  ): Promise<UserOpReceipt | null> {
+    const result = await this.callWithFallback<{
+      userOpHash: string;
+      receipt: {
+        transactionHash: string;
+        blockNumber: string;
+        status: string;
+      };
+      success: boolean;
+    } | null>('eth_getUserOperationReceipt', [userOpHash]);
+
+    if (!result) return null;
+
+    return {
+      userOpHash: result.userOpHash,
+      transactionHash: result.receipt.transactionHash,
+      blockNumber: parseInt(result.receipt.blockNumber, 16),
+      success: result.success,
+    };
+  }
+
+  /**
+   * Wait for UserOp receipt with polling.
+   */
+  async waitForReceipt(
+    userOpHash: string,
+    timeoutMs: number = 60_000,
+    pollIntervalMs: number = 2_000
+  ): Promise<UserOpReceipt> {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+      const receipt = await this.getUserOperationReceipt(userOpHash);
+      if (receipt) return receipt;
+      await sleep(pollIntervalMs);
+    }
+    throw new Error(
+      `UserOp ${userOpHash} not mined after ${timeoutMs}ms. ` +
+        'The transaction may still be pending — check the bundler or block explorer.'
+    );
+  }
+
+  // ==========================================================================
+  // Internal
+  // ==========================================================================
+
+  /**
+   * Call primary, fall back to backup, with retries and backoff.
+   */
+  private async callWithFallback<T>(
+    method: string,
+    params: unknown[]
+  ): Promise<T> {
+    // Try primary
+    try {
+      return await this.callWithRetry<T>(this.primaryUrl, method, params);
+    } catch (primaryError) {
+      if (!this.backupUrl) {
+        throw primaryError;
+      }
+      sdkLogger.warn('Primary bundler failed, trying backup', {
+        method,
+        error: primaryError instanceof Error ? primaryError.message : String(primaryError),
+      });
+    }
+
+    // Try backup
+    return this.callWithRetry<T>(this.backupUrl!, method, params);
+  }
+
+  private async callWithRetry<T>(
+    url: string,
+    method: string,
+    params: unknown[]
+  ): Promise<T> {
+    let lastError: Error | undefined;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      try {
+        return await this.jsonRpc<T>(url, method, params);
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        // Don't retry non-transient errors
+        if (isNonTransient(lastError)) throw lastError;
+        if (attempt < this.maxRetries) {
+          const delay = this.baseDelayMs * Math.pow(2, attempt);
+          sdkLogger.warn('Bundler request failed, retrying', {
+            attempt: attempt + 1,
+            method,
+            delayMs: delay,
+          });
+          await sleep(delay);
+        }
+      }
+    }
+    throw lastError!;
+  }
+
+  private async jsonRpc<T>(
+    url: string,
+    method: string,
+    params: unknown[]
+  ): Promise<T> {
+    const body = JSON.stringify({
+      jsonrpc: '2.0',
+      id: this.requestId++,
+      method,
+      params,
+    });
+
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+
+    try {
+      const response = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body,
+        signal: controller.signal,
+      });
+
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+
+      const json = (await response.json()) as JsonRpcResponse<T>;
+
+      if (json.error) {
+        const err = new Error(
+          `Bundler RPC error ${json.error.code}: ${json.error.message}`
+        );
+        (err as any).code = json.error.code;
+        (err as any).data = json.error.data;
+        throw err;
+      }
+
+      return json.result as T;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Detect non-transient errors that shouldn't be retried.
+ */
+function isNonTransient(error: Error): boolean {
+  const code = (error as any).code;
+  // AA errors from bundler (invalid signature, insufficient funds, etc.)
+  if (typeof code === 'number' && code >= -32700 && code <= -32600) {
+    return true; // JSON-RPC parse/invalid request errors
+  }
+  const msg = error.message.toLowerCase();
+  if (msg.includes('aa') && (msg.includes('invalid') || msg.includes('rejected'))) {
+    return true; // AA validation errors
+  }
+  return false;
+}

package/src/wallet/aa/DualNonceManager.ts

@@ -0,0 +1,163 @@
+/**
+ * DualNonceManager — Manages both EntryPoint and ACTP nonces.
+ *
+ * ERC-4337 UserOps need two independent nonces:
+ *   1. EntryPoint nonce — anti-replay for the UserOp itself
+ *   2. ACTP nonce — used to compute deterministic txId
+ *
+ * This manager uses a sequential mutex queue to ensure:
+ *   - Only one UserOp is in-flight at a time
+ *   - ACTP nonce increments only on confirmed receipt
+ *   - On failure, next call re-reads from chain
+ *
+ * @module wallet/aa/DualNonceManager
+ */
+
+import { ethers } from 'ethers';
+import { ENTRYPOINT_V06 } from './constants';
+import { sdkLogger } from '../../utils/Logger';
+
+// ============================================================================
+// ABI fragments
+// ============================================================================
+
+const ENTRYPOINT_NONCE_ABI = [
+  'function getNonce(address sender, uint192 key) view returns (uint256)',
+];
+
+const ACTP_KERNEL_NONCE_ABI = [
+  'function requesterNonces(address requester) view returns (uint256)',
+];
+
+// ============================================================================
+// Mutex
+// ============================================================================
+
+class Mutex {
+  private locked = false;
+  private queue: (() => void)[] = [];
+
+  async acquire(): Promise<void> {
+    if (!this.locked) {
+      this.locked = true;
+      return;
+    }
+    return new Promise<void>((resolve) => {
+      this.queue.push(resolve);
+    });
+  }
+
+  release(): void {
+    if (this.queue.length > 0) {
+      const next = this.queue.shift()!;
+      next();
+    } else {
+      this.locked = false;
+    }
+  }
+}
+
+// ============================================================================
+// DualNonceManager
+// ============================================================================
+
+export class DualNonceManager {
+  private readonly provider: ethers.JsonRpcProvider;
+  private readonly senderAddress: string;
+  private readonly actpKernelAddress: string;
+  private readonly mutex = new Mutex();
+
+  /** Locally cached ACTP nonce — undefined means "re-read from chain" */
+  private cachedActpNonce: bigint | undefined;
+
+  constructor(
+    provider: ethers.JsonRpcProvider,
+    senderAddress: string,
+    actpKernelAddress: string
+  ) {
+    this.provider = provider;
+    this.senderAddress = senderAddress;
+    this.actpKernelAddress = actpKernelAddress;
+  }
+
+  /**
+   * Execute a callback while holding the nonce mutex.
+   *
+   * The callback receives current nonces and must return whether
+   * the operation succeeded (to decide ACTP nonce increment).
+   *
+   * @param fn Callback receiving { entryPointNonce, actpNonce }
+   * @param incrementsActpNonce Whether success increments the ACTP nonce
+   */
+  async enqueue<T>(
+    fn: (nonces: { entryPointNonce: bigint; actpNonce: bigint }) => Promise<{
+      result: T;
+      success: boolean;
+    }>,
+    incrementsActpNonce: boolean = true
+  ): Promise<T> {
+    await this.mutex.acquire();
+    try {
+      // Read nonces
+      const entryPointNonce = await this.readEntryPointNonce();
+      const actpNonce = this.cachedActpNonce ?? await this.readActpNonce();
+
+      sdkLogger.info('Nonces acquired', {
+        entryPointNonce: entryPointNonce.toString(),
+        actpNonce: actpNonce.toString(),
+      });
+
+      const { result, success } = await fn({ entryPointNonce, actpNonce });
+
+      if (success && incrementsActpNonce) {
+        this.cachedActpNonce = actpNonce + 1n;
+      } else if (!success) {
+        // Reset cache on failure — next call re-reads from chain
+        this.cachedActpNonce = undefined;
+      }
+
+      return result;
+    } catch (error) {
+      // Reset on error
+      this.cachedActpNonce = undefined;
+      throw error;
+    } finally {
+      this.mutex.release();
+    }
+  }
+
+  /**
+   * Read current EntryPoint nonce for the sender.
+   * Key 0 is the default key for CoinbaseSmartWallet.
+   */
+  private async readEntryPointNonce(): Promise<bigint> {
+    const entryPoint = new ethers.Contract(
+      ENTRYPOINT_V06,
+      ENTRYPOINT_NONCE_ABI,
+      this.provider
+    );
+    return await entryPoint.getNonce(this.senderAddress, 0);
+  }
+
+  /**
+   * Read current ACTP nonce for the requester.
+   * requesterNonces is public on ACTPKernel.
+   */
+  private async readActpNonce(): Promise<bigint> {
+    const kernel = new ethers.Contract(
+      this.actpKernelAddress,
+      ACTP_KERNEL_NONCE_ABI,
+      this.provider
+    );
+    const nonce = await kernel.requesterNonces(this.senderAddress);
+    this.cachedActpNonce = nonce;
+    return nonce;
+  }
+
+  /**
+   * Invalidate cached ACTP nonce (forces re-read on next operation).
+   */
+  invalidateCache(): void {
+    this.cachedActpNonce = undefined;
+  }
+}

package/src/wallet/aa/PaymasterClient.ts

@@ -0,0 +1,173 @@
+/**
+ * PaymasterClient — Gas sponsorship via ERC-7677 paymasters.
+ *
+ * Fallback chain: Coinbase CDP (primary) → Pimlico (backup).
+ * Both implement ERC-7677 pm_getPaymasterStubData / pm_getPaymasterData.
+ *
+ * The paymaster fills the `paymasterAndData` field of the UserOp,
+ * which the EntryPoint uses to debit gas from the paymaster instead
+ * of the sender's ETH balance.
+ *
+ * @module wallet/aa/PaymasterClient
+ */
+
+import { UserOperationV06 } from './constants';
+import { serializeUserOp } from './UserOpBuilder';
+import { ENTRYPOINT_V06 } from './constants';
+import { sdkLogger } from '../../utils/Logger';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface PaymasterConfig {
+  /** Primary paymaster URL (Coinbase CDP) */
+  primaryUrl: string;
+  /** Backup paymaster URL (Pimlico) */
+  backupUrl?: string;
+  /** Chain ID (8453 for Base Mainnet, 84532 for Sepolia) */
+  chainId: number;
+  /** Request timeout (ms) */
+  timeoutMs?: number;
+}
+
+interface JsonRpcResponse<T = unknown> {
+  jsonrpc: string;
+  id: number;
+  result?: T;
+  error?: { code: number; message: string; data?: unknown };
+}
+
+// ============================================================================
+// PaymasterClient
+// ============================================================================
+
+export class PaymasterClient {
+  private readonly primaryUrl: string;
+  private readonly backupUrl: string | undefined;
+  private readonly chainId: number;
+  private readonly timeoutMs: number;
+  private requestId = 1;
+
+  constructor(config: PaymasterConfig) {
+    this.primaryUrl = config.primaryUrl;
+    this.backupUrl = config.backupUrl;
+    this.chainId = config.chainId;
+    this.timeoutMs = config.timeoutMs ?? 15_000;
+  }
+
+  /**
+   * Get stub paymaster data for gas estimation.
+   *
+   * Returns approximate paymasterAndData that the bundler can use
+   * for gas estimation (exact values come from getPaymasterData).
+   */
+  async getPaymasterStubData(
+    userOp: UserOperationV06
+  ): Promise<{ paymasterAndData: string }> {
+    return this.callWithFallback<{ paymasterAndData: string }>(
+      'pm_getPaymasterStubData',
+      [
+        serializeUserOp(userOp),
+        ENTRYPOINT_V06,
+        '0x' + this.chainId.toString(16),
+        {}, // context
+      ]
+    );
+  }
+
+  /**
+   * Get final paymaster data for the signed UserOp.
+   *
+   * This is called after gas estimation with final gas values.
+   * Returns the paymaster signature that goes into paymasterAndData.
+   */
+  async getPaymasterData(
+    userOp: UserOperationV06
+  ): Promise<{ paymasterAndData: string }> {
+    return this.callWithFallback<{ paymasterAndData: string }>(
+      'pm_getPaymasterData',
+      [
+        serializeUserOp(userOp),
+        ENTRYPOINT_V06,
+        '0x' + this.chainId.toString(16),
+        {}, // context
+      ]
+    );
+  }
+
+  // ==========================================================================
+  // Internal
+  // ==========================================================================
+
+  private async callWithFallback<T>(
+    method: string,
+    params: unknown[]
+  ): Promise<T> {
+    try {
+      return await this.jsonRpc<T>(this.primaryUrl, method, params);
+    } catch (primaryError) {
+      if (!this.backupUrl) {
+        throw new Error(
+          `Gas sponsorship unavailable: ${primaryError instanceof Error ? primaryError.message : String(primaryError)}. ` +
+            'No backup paymaster configured.'
+        );
+      }
+      sdkLogger.warn('Primary paymaster failed, trying backup', {
+        method,
+        error: primaryError instanceof Error ? primaryError.message : String(primaryError),
+      });
+    }
+
+    try {
+      return await this.jsonRpc<T>(this.backupUrl!, method, params);
+    } catch (backupError) {
+      throw new Error(
+        'Gas sponsorship temporarily unavailable — both Coinbase and Pimlico paymasters failed. ' +
+          'Please retry later. ' +
+          `Primary: ${backupError instanceof Error ? backupError.message : String(backupError)}`
+      );
+    }
+  }
+
+  private async jsonRpc<T>(
+    url: string,
+    method: string,
+    params: unknown[]
+  ): Promise<T> {
+    const body = JSON.stringify({
+      jsonrpc: '2.0',
+      id: this.requestId++,
+      method,
+      params,
+    });
+
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+
+    try {
+      const response = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body,
+        signal: controller.signal,
+      });
+
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+
+      const json = (await response.json()) as JsonRpcResponse<T>;
+
+      if (json.error) {
+        throw new Error(
+          `Paymaster RPC error ${json.error.code}: ${json.error.message}`
+        );
+      }
+
+      return json.result as T;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+}