@agirails/sdk 2.3.0 → 2.3.3

package/src/wallet/IWalletProvider.ts

@@ -0,0 +1,133 @@
+/**
+ * IWalletProvider — Wallet abstraction for ACTP SDK.
+ *
+ * Enables pluggable wallet implementations:
+ * - EOAWalletProvider (Tier 2): Direct ethers.Wallet signing
+ * - AutoWalletProvider (Tier 1): CoinbaseSmartWallet + Paymaster (gasless)
+ *
+ * @module wallet/IWalletProvider
+ */
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Low-level transaction request.
+ * Plain strings only — no ethers or viem types at the interface boundary.
+ */
+export interface TransactionRequest {
+  /** Target contract address (0x-prefixed) */
+  to: string;
+  /** Calldata (0x-prefixed hex) */
+  data: string;
+  /** ETH value in wei (decimal string). Defaults to "0". */
+  value?: string;
+}
+
+/**
+ * Transaction receipt returned after submission.
+ */
+export interface TransactionReceipt {
+  /** Transaction hash (EOA) or UserOp hash (AA) */
+  hash: string;
+  /** Whether the transaction succeeded */
+  success: boolean;
+}
+
+/**
+ * Wallet tier — determines gas behavior.
+ */
+export type WalletTier = 'auto' | 'eoa';
+
+/**
+ * Information about the wallet provider.
+ */
+export interface WalletInfo {
+  /** The account address used for ACTP transactions */
+  address: string;
+  /** Wallet tier */
+  tier: WalletTier;
+  /** Whether this wallet supports atomic batching (AA = true, EOA = false) */
+  supportsBatching: boolean;
+  /** Whether gas is sponsored (AA with paymaster = true) */
+  gasSponsored: boolean;
+  /** Chain ID */
+  chainId: number;
+}
+
+/**
+ * Result of a batched ACTP payment via AA wallet.
+ */
+export interface BatchedPayResult {
+  /** Pre-computed ACTP transaction ID (bytes32) */
+  txId: string;
+  /** Transaction hash from the UserOp */
+  hash: string;
+  /** Whether the UserOp succeeded */
+  success: boolean;
+}
+
+/**
+ * Parameters for batched ACTP payment.
+ */
+export interface BatchedPayParams {
+  provider: string;
+  requester: string;
+  amount: string;
+  deadline: number;
+  disputeWindow: number;
+  serviceHash: string;
+  agentId: string;
+  contracts: {
+    usdc: string;
+    actpKernel: string;
+    escrowVault: string;
+  };
+}
+
+// ============================================================================
+// Interface
+// ============================================================================
+
+/**
+ * Wallet provider interface.
+ *
+ * All methods use plain strings (no ethers/viem types) to keep the
+ * interface decoupled from any specific library.
+ */
+export interface IWalletProvider {
+  /**
+   * Get the account address used as requester in ACTP transactions.
+   * For AA wallets this is the Smart Wallet address (not the signer EOA).
+   */
+  getAddress(): string;
+
+  /**
+   * Send a single transaction.
+   */
+  sendTransaction(tx: TransactionRequest): Promise<TransactionReceipt>;
+
+  /**
+   * Send multiple transactions atomically (AA) or sequentially (EOA).
+   *
+   * AA wallets batch all calls into a single UserOp.
+   * EOA wallets execute them one by one and return the last receipt.
+   */
+  sendBatchTransaction(txs: TransactionRequest[]): Promise<TransactionReceipt>;
+
+  /**
+   * Get wallet metadata.
+   */
+  getWalletInfo(): WalletInfo;
+
+  /**
+   * Execute a batched ACTP payment atomically (approve + createTx + linkEscrow).
+   *
+   * Only available on AA wallets (supportsBatching: true).
+   * Handles ACTP nonce management internally via the DualNonceManager mutex.
+   *
+   * Returns undefined if batched payments are not supported.
+   */
+  payACTPBatched?(params: BatchedPayParams): Promise<BatchedPayResult>;
+}

package/src/wallet/aa/BundlerClient.ts

@@ -0,0 +1,274 @@
+/**
+ * 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

@@ -0,0 +1,173 @@
+/**
+ * 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;
+  }
+}