@agirails/sdk 2.3.0 → 2.3.1

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);
+}

package/src/wallet/aa/constants.ts

@@ -0,0 +1,60 @@
+/**
+ * Account Abstraction constants for CoinbaseSmartWallet on Base.
+ *
+ * EntryPoint v0.6 — CoinbaseSmartWallet hardcodes this version.
+ * Factory address is canonical across all Base networks.
+ *
+ * @module wallet/aa/constants
+ */
+
+/** ERC-4337 EntryPoint v0.6 (canonical, all EVM chains) */
+export const ENTRYPOINT_V06 = '0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789';
+
+/** CoinbaseSmartWallet factory (canonical, all Base networks) */
+export const SMART_WALLET_FACTORY = '0xBA5ED110eFDBa3D005bfC882d75358ACBbB85842';
+
+/** Default nonce for first Smart Wallet per owner */
+export const DEFAULT_WALLET_NONCE = 0n;
+
+/**
+ * UserOperation v0.6 struct — 11 unpacked fields.
+ * CoinbaseSmartWallet does NOT support v0.7 packed format.
+ */
+export interface UserOperationV06 {
+  sender: string;
+  nonce: bigint;
+  initCode: string;
+  callData: string;
+  callGasLimit: bigint;
+  verificationGasLimit: bigint;
+  preVerificationGas: bigint;
+  maxFeePerGas: bigint;
+  maxPriorityFeePerGas: bigint;
+  paymasterAndData: string;
+  signature: string;
+}
+
+/**
+ * CoinbaseSmartWallet Call struct for executeBatch.
+ */
+export interface SmartWalletCall {
+  target: string;
+  value: bigint;
+  data: string;
+}
+
+/**
+ * Gas estimation result from bundler.
+ */
+export interface GasEstimate {
+  callGasLimit: bigint;
+  verificationGasLimit: bigint;
+  preVerificationGas: bigint;
+}
+
+/**
+ * Paymaster sponsorship response.
+ */
+export interface PaymasterResponse {
+  paymasterAndData: string;
+}