@agirails/sdk 2.3.0 → 2.3.3

package/src/wallet/aa/PaymasterClient.ts

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

package/src/wallet/aa/TransactionBatcher.ts

@@ -0,0 +1,240 @@
+/**
+ * TransactionBatcher — Encodes ACTP multi-call batches.
+ *
+ * An ACTP payment requires 3 contract calls:
+ *   1. USDC.approve(escrowVault, amount)
+ *   2. ACTPKernel.createTransaction(provider, requester, amount, deadline, disputeWindow, serviceHash, agentId)
+ *   3. ACTPKernel.linkEscrow(txId, escrowVault, escrowId)
+ *
+ * TransactionBatcher encodes all 3 as SmartWalletCall[] for executeBatch.
+ * It pre-computes the txId using the same keccak256 formula as the contract.
+ *
+ * @module wallet/aa/TransactionBatcher
+ */
+
+import { ethers } from 'ethers';
+import { SmartWalletCall } from './constants';
+import { ServiceDescriptor } from '../../types/agent';
+
+// ============================================================================
+// ABI fragments — minimal for encoding only
+// ============================================================================
+
+const ERC20_APPROVE_ABI = [
+  'function approve(address spender, uint256 amount)',
+];
+
+const ACTP_KERNEL_ABI = [
+  'function createTransaction(address provider, address requester, uint256 amount, uint256 deadline, uint256 disputeWindow, bytes32 serviceHash, uint256 agentId)',
+  'function linkEscrow(bytes32 txId, address escrowVault, bytes32 escrowId)',
+];
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface ACTPBatchParams {
+  /** Provider address */
+  provider: string;
+  /** Requester address (= Smart Wallet address) */
+  requester: string;
+  /** Amount in USDC wei (e.g., "1000000" for 1 USDC) */
+  amount: string;
+  /** Unix timestamp deadline */
+  deadline: number;
+  /** Dispute window in seconds */
+  disputeWindow: number;
+  /** Service hash (bytes32) */
+  serviceHash: string;
+  /** ERC-8004 agent ID (0 if none) */
+  agentId: string;
+  /** Current ACTP nonce for the requester (from ACTPKernel.requesterNonces) */
+  actpNonce: bigint;
+  /** Contract addresses */
+  contracts: {
+    usdc: string;
+    actpKernel: string;
+    escrowVault: string;
+  };
+}
+
+export interface ACTPBatchResult {
+  /** Encoded SmartWalletCall[] ready for executeBatch */
+  calls: SmartWalletCall[];
+  /** Pre-computed transaction ID */
+  txId: string;
+}
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+/**
+ * Pre-compute ACTP transaction ID.
+ *
+ * Matches ACTPKernel.sol:
+ *   transactionId = keccak256(abi.encodePacked(requester, provider, amount, serviceHash, nonce))
+ */
+export function computeTransactionId(
+  requester: string,
+  provider: string,
+  amount: string,
+  serviceHash: string,
+  nonce: bigint
+): string {
+  return ethers.keccak256(
+    ethers.solidityPacked(
+      ['address', 'address', 'uint256', 'bytes32', 'uint256'],
+      [requester, provider, BigInt(amount), serviceHash, nonce]
+    )
+  );
+}
+
+/**
+ * Build the 3-call ACTP payment batch.
+ *
+ * Returns SmartWalletCall[] for executeBatch and the pre-computed txId.
+ */
+export function buildACTPPayBatch(params: ACTPBatchParams): ACTPBatchResult {
+  const amount = BigInt(params.amount);
+
+  // Pre-compute txId
+  const txId = computeTransactionId(
+    params.requester,
+    params.provider,
+    params.amount,
+    params.serviceHash,
+    params.actpNonce
+  );
+
+  const erc20Iface = new ethers.Interface(ERC20_APPROVE_ABI);
+  const kernelIface = new ethers.Interface(ACTP_KERNEL_ABI);
+
+  // Call 1: USDC.approve(escrowVault, amount)
+  const approveData = erc20Iface.encodeFunctionData('approve', [
+    params.contracts.escrowVault,
+    amount,
+  ]);
+
+  // Call 2: ACTPKernel.createTransaction(...)
+  const createTxData = kernelIface.encodeFunctionData('createTransaction', [
+    params.provider,
+    params.requester,
+    amount,
+    params.deadline,
+    params.disputeWindow,
+    params.serviceHash,
+    BigInt(params.agentId || '0'),
+  ]);
+
+  // Call 3: ACTPKernel.linkEscrow(txId, escrowVault, escrowId)
+  // escrowId = txId (ACTP standard)
+  const linkEscrowData = kernelIface.encodeFunctionData('linkEscrow', [
+    txId,
+    params.contracts.escrowVault,
+    txId,
+  ]);
+
+  const calls: SmartWalletCall[] = [
+    { target: params.contracts.usdc, value: 0n, data: approveData },
+    { target: params.contracts.actpKernel, value: 0n, data: createTxData },
+    { target: params.contracts.actpKernel, value: 0n, data: linkEscrowData },
+  ];
+
+  return { calls, txId };
+}
+
+/**
+ * ABI fragment for AgentRegistry.registerAgent.
+ *
+ * Matches IAgentRegistry.sol:
+ *   registerAgent(string endpoint, ServiceDescriptor[] serviceDescriptors)
+ *
+ * ServiceDescriptor = (bytes32, string, string, uint256, uint256, uint256, string)
+ */
+const AGENT_REGISTRY_ABI = [
+  'function registerAgent(string endpoint, (bytes32 serviceTypeHash, string serviceType, string schemaURI, uint256 minPrice, uint256 maxPrice, uint256 avgCompletionTime, string metadataCID)[] serviceDescriptors)',
+];
+
+/**
+ * Build a register-agent batch for AgentRegistry.
+ *
+ * Used for bootstrap registration (gasless even before registration — chicken-and-egg).
+ *
+ * @param agentRegistryAddress - AgentRegistry contract address
+ * @param endpoint - Agent webhook / IPFS gateway URL
+ * @param serviceDescriptors - At least 1 service descriptor (contract requirement)
+ */
+export function buildRegisterAgentBatch(
+  agentRegistryAddress: string,
+  endpoint: string,
+  serviceDescriptors: ServiceDescriptor[]
+): SmartWalletCall[] {
+  if (serviceDescriptors.length === 0) {
+    throw new Error('At least one service descriptor is required for registration');
+  }
+
+  const iface = new ethers.Interface(AGENT_REGISTRY_ABI);
+
+  // Convert to contract format (bigint fields already correct)
+  const descriptors = serviceDescriptors.map(sd => ({
+    serviceTypeHash: sd.serviceTypeHash,
+    serviceType: sd.serviceType,
+    schemaURI: sd.schemaURI,
+    minPrice: sd.minPrice,
+    maxPrice: sd.maxPrice,
+    avgCompletionTime: sd.avgCompletionTime,
+    metadataCID: sd.metadataCID,
+  }));
+
+  const data = iface.encodeFunctionData('registerAgent', [endpoint, descriptors]);
+
+  return [
+    { target: agentRegistryAddress, value: 0n, data },
+  ];
+}
+
+/**
+ * Build a MockUSDC mint call (testnet only).
+ */
+export function buildTestnetMintBatch(
+  mockUsdcAddress: string,
+  recipient: string,
+  amount: string
+): SmartWalletCall[] {
+  const iface = new ethers.Interface([
+    'function mint(address to, uint256 amount)',
+  ]);
+  const data = iface.encodeFunctionData('mint', [recipient, BigInt(amount)]);
+
+  return [
+    { target: mockUsdcAddress, value: 0n, data },
+  ];
+}
+
+/**
+ * Build a combined register + mint batch for testnet init.
+ *
+ * Single UserOp: register on AgentRegistry + mint test USDC.
+ * Both are bootstrap-allowed (gasless without prior registration).
+ */
+export function buildTestnetInitBatch(params: {
+  agentRegistryAddress: string;
+  endpoint: string;
+  serviceDescriptors: ServiceDescriptor[];
+  mockUsdcAddress: string;
+  recipient: string;
+  mintAmount: string;
+}): SmartWalletCall[] {
+  const registerCalls = buildRegisterAgentBatch(
+    params.agentRegistryAddress,
+    params.endpoint,
+    params.serviceDescriptors
+  );
+  const mintCalls = buildTestnetMintBatch(
+    params.mockUsdcAddress,
+    params.recipient,
+    params.mintAmount
+  );
+  return [...registerCalls, ...mintCalls];
+}

package/src/wallet/aa/UserOpBuilder.ts

@@ -0,0 +1,246 @@
+/**
+ * UserOpBuilder — Constructs ERC-4337 v0.6 UserOperations.
+ *
+ * Builds UserOps for CoinbaseSmartWallet:
+ * - Encodes executeBatch(Call[]) as callData
+ * - Adds initCode for first-time wallet deployment
+ * - Signs with owner's private key (EIP-191 over UserOp hash)
+ *
+ * Uses ethers v6 for ABI encoding (no viem dependency yet — see Phase 2 note).
+ * viem+permissionless will be added if needed for paymaster integration.
+ *
+ * @module wallet/aa/UserOpBuilder
+ */
+
+import { ethers } from 'ethers';
+import {
+  UserOperationV06,
+  SmartWalletCall,
+  ENTRYPOINT_V06,
+  SMART_WALLET_FACTORY,
+  DEFAULT_WALLET_NONCE,
+} from './constants';
+
+const abiCoder = ethers.AbiCoder.defaultAbiCoder();
+
+// ============================================================================
+// ABI fragments
+// ============================================================================
+
+/** CoinbaseSmartWallet.executeBatch(Call[]) */
+const EXECUTE_BATCH_ABI = [
+  'function executeBatch((address target, uint256 value, bytes data)[] calls)',
+];
+
+/** CoinbaseSmartWalletFactory.createAccount(bytes[],uint256) */
+const FACTORY_CREATE_ABI = [
+  'function createAccount(bytes[] owners, uint256 nonce)',
+];
+
+/** CoinbaseSmartWalletFactory.getAddress(bytes[],uint256) */
+const FACTORY_GET_ADDRESS_ABI = [
+  'function getAddress(bytes[] owners, uint256 nonce) view returns (address)',
+];
+
+// Typed factory interface to avoid ethers v6 getAddress() collision
+const FACTORY_ABI = [
+  ...FACTORY_CREATE_ABI,
+  ...FACTORY_GET_ADDRESS_ABI,
+];
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+/**
+ * Compute the counterfactual Smart Wallet address for a given signer.
+ *
+ * This address is deterministic (CREATE2) and can be computed off-chain
+ * without deploying the wallet.
+ */
+export async function computeSmartWalletAddress(
+  signerAddress: string,
+  provider: ethers.JsonRpcProvider,
+  nonce: bigint = DEFAULT_WALLET_NONCE
+): Promise<string> {
+  const factory = new ethers.Contract(
+    SMART_WALLET_FACTORY,
+    FACTORY_ABI,
+    provider
+  );
+  // CoinbaseSmartWallet encodes owners as bytes[] — EOA address is abi.encode(address)
+  const ownerBytes = abiCoder.encode(['address'], [signerAddress]);
+  // Use getFunction to avoid collision with ethers v6 BaseContract.getAddress()
+  const fn = factory.getFunction('getAddress');
+  return await fn([ownerBytes], nonce);
+}
+
+/**
+ * Build initCode for first-time wallet deployment.
+ *
+ * initCode = factory address + createAccount calldata
+ * When the wallet already exists, pass '0x' as initCode.
+ */
+export function buildInitCode(
+  signerAddress: string,
+  nonce: bigint = DEFAULT_WALLET_NONCE
+): string {
+  const iface = new ethers.Interface(FACTORY_CREATE_ABI);
+  const ownerBytes = abiCoder.encode(['address'], [signerAddress]);
+  const calldata = iface.encodeFunctionData('createAccount', [
+    [ownerBytes],
+    nonce,
+  ]);
+  // initCode = factory address (20 bytes) + calldata
+  return SMART_WALLET_FACTORY + calldata.slice(2);
+}
+
+/**
+ * Encode executeBatch calldata from an array of calls.
+ */
+export function encodeExecuteBatch(calls: SmartWalletCall[]): string {
+  const iface = new ethers.Interface(EXECUTE_BATCH_ABI);
+  return iface.encodeFunctionData('executeBatch', [
+    calls.map((c) => ({
+      target: c.target,
+      value: c.value,
+      data: c.data,
+    })),
+  ]);
+}
+
+/**
+ * Build a full UserOperation (unsigned).
+ *
+ * Gas limits and paymasterAndData must be filled by the caller
+ * (via BundlerClient.estimateGas and PaymasterClient.sponsor).
+ */
+export function buildUserOp(params: {
+  sender: string;
+  nonce: bigint;
+  calls: SmartWalletCall[];
+  isFirstDeploy: boolean;
+  signerAddress: string;
+}): UserOperationV06 {
+  const callData = encodeExecuteBatch(params.calls);
+  const initCode = params.isFirstDeploy
+    ? buildInitCode(params.signerAddress)
+    : '0x';
+
+  return {
+    sender: params.sender,
+    nonce: params.nonce,
+    initCode,
+    callData,
+    // Placeholder values — filled by gas estimation
+    callGasLimit: 0n,
+    verificationGasLimit: 0n,
+    preVerificationGas: 0n,
+    maxFeePerGas: 0n,
+    maxPriorityFeePerGas: 0n,
+    paymasterAndData: '0x',
+    signature: '0x',
+  };
+}
+
+/**
+ * Compute the UserOperation hash for signing (v0.6).
+ *
+ * hash = keccak256(abi.encode(
+ *   keccak256(pack(userOp)),
+ *   entryPoint,
+ *   chainId
+ * ))
+ */
+export function getUserOpHash(
+  userOp: UserOperationV06,
+  chainId: number
+): string {
+  // Pack all fields except signature
+  const packed = abiCoder.encode(
+    [
+      'address',   // sender
+      'uint256',   // nonce
+      'bytes32',   // keccak256(initCode)
+      'bytes32',   // keccak256(callData)
+      'uint256',   // callGasLimit
+      'uint256',   // verificationGasLimit
+      'uint256',   // preVerificationGas
+      'uint256',   // maxFeePerGas
+      'uint256',   // maxPriorityFeePerGas
+      'bytes32',   // keccak256(paymasterAndData)
+    ],
+    [
+      userOp.sender,
+      userOp.nonce,
+      ethers.keccak256(userOp.initCode),
+      ethers.keccak256(userOp.callData),
+      userOp.callGasLimit,
+      userOp.verificationGasLimit,
+      userOp.preVerificationGas,
+      userOp.maxFeePerGas,
+      userOp.maxPriorityFeePerGas,
+      ethers.keccak256(userOp.paymasterAndData),
+    ]
+  );
+
+  const packedHash = ethers.keccak256(packed);
+
+  return ethers.keccak256(
+    abiCoder.encode(
+      ['bytes32', 'address', 'uint256'],
+      [packedHash, ENTRYPOINT_V06, chainId]
+    )
+  );
+}
+
+/**
+ * Sign a UserOperation with the owner's private key.
+ *
+ * CoinbaseSmartWallet expects the signature to be:
+ *   abi.encode(SignatureWrapper(0, abi.encodePacked(r,s,v)))
+ *
+ * where ownerIndex=0 for single-owner wallets.
+ */
+export async function signUserOp(
+  userOp: UserOperationV06,
+  signer: ethers.Wallet,
+  chainId: number
+): Promise<string> {
+  const hash = getUserOpHash(userOp, chainId);
+  // ethers signMessage adds EIP-191 prefix. CoinbaseSmartWallet expects raw ECDSA.
+  // We use signingKey.sign() for raw signature over the hash bytes.
+  const sig = signer.signingKey.sign(hash);
+  // Pack r + s + v
+  const rawSig = ethers.concat([sig.r, sig.s, new Uint8Array([sig.v])]);
+
+  // CoinbaseSmartWallet SignatureWrapper: abi.encode(uint256 ownerIndex, bytes signatureData)
+  return abiCoder.encode(
+    ['uint256', 'bytes'],
+    [0, rawSig]
+  );
+}
+
+/**
+ * Serialize UserOp for JSON-RPC (bundler API).
+ * Converts bigints to hex strings.
+ */
+export function serializeUserOp(userOp: UserOperationV06): Record<string, string> {
+  return {
+    sender: userOp.sender,
+    nonce: toHex(userOp.nonce),
+    initCode: userOp.initCode,
+    callData: userOp.callData,
+    callGasLimit: toHex(userOp.callGasLimit),
+    verificationGasLimit: toHex(userOp.verificationGasLimit),
+    preVerificationGas: toHex(userOp.preVerificationGas),
+    maxFeePerGas: toHex(userOp.maxFeePerGas),
+    maxPriorityFeePerGas: toHex(userOp.maxPriorityFeePerGas),
+    paymasterAndData: userOp.paymasterAndData,
+    signature: userOp.signature,
+  };
+}
+
+function toHex(n: bigint): string {
+  return '0x' + n.toString(16);
+}