@agirails/sdk 2.5.3 → 2.5.5

package/src/wallet/aa/BundlerClient.ts

@@ -1,274 +0,0 @@
-/**
- * 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 dataStr = json.error.data ? ` | data: ${JSON.stringify(json.error.data)}` : '';
-        const err = new Error(
-          `Bundler RPC error ${json.error.code}: ${json.error.message}${dataStr}`
-        );
-        (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

@@ -1,173 +0,0 @@
-/**
- * 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 (added in v2).
-   * Older deployments may not expose this — fall back to 0n.
-   */
-  private async readActpNonce(): Promise<bigint> {
-    try {
-      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;
-    } catch {
-      // Older ACTPKernel deployments don't expose requesterNonces.
-      // Return 0n — registration doesn't need it, and payment batches
-      // will fail at the contract level anyway if nonces are wrong.
-      sdkLogger.warn('requesterNonces not available on ACTPKernel — using 0 (older deployment?)');
-      this.cachedActpNonce = 0n;
-      return 0n;
-    }
-  }
-
-  /**
-   * Invalidate cached ACTP nonce (forces re-read on next operation).
-   */
-  invalidateCache(): void {
-    this.cachedActpNonce = undefined;
-  }
-}

package/src/wallet/aa/PaymasterClient.ts

@@ -1,174 +0,0 @@
-/**
- * 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) {
-        const dataStr = json.error.data ? ` | data: ${JSON.stringify(json.error.data)}` : '';
-        throw new Error(
-          `Paymaster RPC error ${json.error.code}: ${json.error.message}${dataStr}`
-        );
-      }
-
-      return json.result as T;
-    } finally {
-      clearTimeout(timeout);
-    }
-  }
-}