@agirails/sdk 2.2.3 → 2.3.1

package/src/wallet/AutoWalletProvider.ts

@@ -0,0 +1,294 @@
+/**
+ * AutoWalletProvider — Tier 1 (Auto) wallet implementation.
+ *
+ * Creates a CoinbaseSmartWallet with gas-sponsored transactions:
+ *   1. Load/generate local encrypted key
+ *   2. Derive Smart Wallet address (counterfactual CREATE2)
+ *   3. Check AgentRegistry registration
+ *   4. Build UserOp with executeBatch
+ *   5. Get paymaster sponsorship (Coinbase → Pimlico fallback)
+ *   6. Submit via bundler
+ *
+ * If agent is NOT registered, falls back to EOA behavior with a warning.
+ *
+ * @module wallet/AutoWalletProvider
+ */
+
+import { ethers } from 'ethers';
+import {
+  IWalletProvider,
+  TransactionRequest,
+  TransactionReceipt,
+  WalletInfo,
+  BatchedPayParams,
+  BatchedPayResult,
+} from './IWalletProvider';
+import { computeSmartWalletAddress } from './aa/UserOpBuilder';
+import {
+  buildUserOp,
+  signUserOp,
+} from './aa/UserOpBuilder';
+import { SmartWalletCall } from './aa/constants';
+import { BundlerClient } from './aa/BundlerClient';
+import { PaymasterClient } from './aa/PaymasterClient';
+import { DualNonceManager } from './aa/DualNonceManager';
+import { buildACTPPayBatch } from './aa/TransactionBatcher';
+import { sdkLogger } from '../utils/Logger';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface AutoWalletConfig {
+  /** Ethers signer (the EOA that owns the Smart Wallet) */
+  signer: ethers.Wallet;
+  /** Ethers provider */
+  provider: ethers.JsonRpcProvider;
+  /** Chain ID */
+  chainId: number;
+  /** ACTPKernel contract address (for ACTP nonce reads) */
+  actpKernelAddress: string;
+  /** Bundler configuration */
+  bundler: {
+    primaryUrl: string;
+    backupUrl?: string;
+  };
+  /** Paymaster configuration */
+  paymaster: {
+    primaryUrl: string;
+    backupUrl?: string;
+  };
+}
+
+// ============================================================================
+// AutoWalletProvider
+// ============================================================================
+
+export class AutoWalletProvider implements IWalletProvider {
+  private readonly signer: ethers.Wallet;
+  private readonly provider: ethers.JsonRpcProvider;
+  private readonly chainId: number;
+  private readonly bundler: BundlerClient;
+  private readonly paymaster: PaymasterClient;
+  private readonly nonceManager: DualNonceManager;
+  private smartWalletAddress: string = '';
+  private isDeployed: boolean = false;
+
+  private constructor(
+    config: AutoWalletConfig,
+    smartWalletAddress: string,
+    isDeployed: boolean
+  ) {
+    this.signer = config.signer;
+    this.provider = config.provider;
+    this.chainId = config.chainId;
+    this.smartWalletAddress = smartWalletAddress;
+    this.isDeployed = isDeployed;
+
+    this.bundler = new BundlerClient({
+      primaryUrl: config.bundler.primaryUrl,
+      backupUrl: config.bundler.backupUrl,
+    });
+
+    this.paymaster = new PaymasterClient({
+      primaryUrl: config.paymaster.primaryUrl,
+      backupUrl: config.paymaster.backupUrl,
+      chainId: config.chainId,
+    });
+
+    this.nonceManager = new DualNonceManager(
+      config.provider,
+      smartWalletAddress,
+      config.actpKernelAddress
+    );
+  }
+
+  /**
+   * Factory method — computes counterfactual address and checks deployment.
+   */
+  static async create(config: AutoWalletConfig): Promise<AutoWalletProvider> {
+    const signerAddress = config.signer.address;
+    const smartWalletAddress = await computeSmartWalletAddress(
+      signerAddress,
+      config.provider
+    );
+
+    // Check if wallet is already deployed
+    const code = await config.provider.getCode(smartWalletAddress);
+    const isDeployed = code !== '0x';
+
+    sdkLogger.info('AutoWalletProvider initialized', {
+      signer: signerAddress,
+      smartWallet: smartWalletAddress,
+      deployed: isDeployed,
+    });
+
+    return new AutoWalletProvider(config, smartWalletAddress, isDeployed);
+  }
+
+  getAddress(): string {
+    return this.smartWalletAddress;
+  }
+
+  async sendTransaction(tx: TransactionRequest): Promise<TransactionReceipt> {
+    return this.sendBatchTransaction([tx]);
+  }
+
+  async sendBatchTransaction(
+    txs: TransactionRequest[]
+  ): Promise<TransactionReceipt> {
+    if (txs.length === 0) {
+      throw new Error('sendBatchTransaction requires at least one transaction');
+    }
+
+    // Convert to SmartWalletCall[]
+    const calls: SmartWalletCall[] = txs.map((tx) => ({
+      target: tx.to,
+      value: tx.value ? BigInt(tx.value) : 0n,
+      data: tx.data,
+    }));
+
+    // Use nonce manager for sequential ordering
+    // Note: We don't know if this specific batch increments ACTP nonce
+    // (that's handled at the ACTPClient level), so pass false here.
+    // The caller (ACTPClient.payBatched) manages ACTP nonce tracking.
+    return this.nonceManager.enqueue(
+      async ({ entryPointNonce }) => {
+        const receipt = await this.submitUserOp(calls, entryPointNonce);
+        return { result: receipt, success: receipt.success };
+      },
+      false // ACTP nonce management is done at ACTPClient level
+    );
+  }
+
+  getWalletInfo(): WalletInfo {
+    return {
+      address: this.smartWalletAddress,
+      tier: 'auto',
+      supportsBatching: true,
+      gasSponsored: true,
+      chainId: this.chainId,
+    };
+  }
+
+  /**
+   * Get the DualNonceManager (for ACTPClient to use for ACTP-aware batching).
+   */
+  getNonceManager(): DualNonceManager {
+    return this.nonceManager;
+  }
+
+  /**
+   * Check if the Smart Wallet is deployed on-chain.
+   */
+  getIsDeployed(): boolean {
+    return this.isDeployed;
+  }
+
+  /**
+   * Execute a batched ACTP payment atomically.
+   *
+   * Builds approve + createTransaction + linkEscrow as a single UserOp.
+   * Manages ACTP nonce inside the mutex queue for concurrent safety.
+   */
+  async payACTPBatched(params: BatchedPayParams): Promise<BatchedPayResult> {
+    return this.nonceManager.enqueue(
+      async ({ entryPointNonce, actpNonce }) => {
+        const batch = buildACTPPayBatch({
+          ...params,
+          actpNonce,
+        });
+
+        const receipt = await this.submitUserOp(batch.calls, entryPointNonce);
+
+        return {
+          result: {
+            txId: batch.txId,
+            hash: receipt.hash,
+            success: receipt.success,
+          },
+          success: receipt.success,
+        };
+      },
+      true // Increment ACTP nonce on success
+    );
+  }
+
+  // ==========================================================================
+  // Internal
+  // ==========================================================================
+
+  /**
+   * Build, sponsor, sign, and submit a UserOp.
+   */
+  private async submitUserOp(
+    calls: SmartWalletCall[],
+    entryPointNonce: bigint
+  ): Promise<TransactionReceipt> {
+    const signerAddress = this.signer.address;
+
+    // 1. Build unsigned UserOp
+    const userOp = buildUserOp({
+      sender: this.smartWalletAddress,
+      nonce: entryPointNonce,
+      calls,
+      isFirstDeploy: !this.isDeployed,
+      signerAddress,
+    });
+
+    // 2. Get fee data
+    const feeData = await this.provider.getFeeData();
+    userOp.maxFeePerGas = feeData.maxFeePerGas ?? 2_000_000_000n;
+    userOp.maxPriorityFeePerGas = feeData.maxPriorityFeePerGas ?? 1_000_000_000n;
+
+    // 3. Get stub paymaster data (for gas estimation)
+    const stubData = await this.paymaster.getPaymasterStubData(userOp);
+    userOp.paymasterAndData = stubData.paymasterAndData;
+
+    // 4. Dummy signature for gas estimation
+    userOp.signature = dummySignature();
+
+    // 5. Estimate gas
+    const gasEstimate = await this.bundler.estimateUserOperationGas(userOp);
+    userOp.callGasLimit = gasEstimate.callGasLimit;
+    userOp.verificationGasLimit = gasEstimate.verificationGasLimit;
+    userOp.preVerificationGas = gasEstimate.preVerificationGas;
+
+    // 6. Get final paymaster data (with real gas values)
+    const finalPaymaster = await this.paymaster.getPaymasterData(userOp);
+    userOp.paymasterAndData = finalPaymaster.paymasterAndData;
+
+    // 7. Sign
+    userOp.signature = await signUserOp(userOp, this.signer, this.chainId);
+
+    // 8. Submit
+    const userOpHash = await this.bundler.sendUserOperation(userOp);
+    sdkLogger.info('UserOp submitted', { userOpHash });
+
+    // 9. Wait for receipt
+    const receipt = await this.bundler.waitForReceipt(userOpHash);
+
+    // Mark as deployed after first successful UserOp
+    if (!this.isDeployed && receipt.success) {
+      this.isDeployed = true;
+    }
+
+    return {
+      hash: receipt.transactionHash,
+      success: receipt.success,
+    };
+  }
+}
+
+/**
+ * Dummy signature for gas estimation.
+ * CoinbaseSmartWallet expects abi.encode(uint256 ownerIndex, bytes sig)
+ * where sig is 65 bytes (r,s,v).
+ */
+function dummySignature(): string {
+  const dummySig = '0x' + 'ff'.repeat(65);
+  return ethers.AbiCoder.defaultAbiCoder().encode(
+    ['uint256', 'bytes'],
+    [0, dummySig]
+  );
+}

package/src/wallet/EOAWalletProvider.ts

@@ -0,0 +1,69 @@
+/**
+ * EOAWalletProvider — Tier 2 (BYOW) wallet implementation.
+ *
+ * Wraps an ethers.Wallet for traditional EOA signing.
+ * sendBatchTransaction() executes calls sequentially (no atomic batching).
+ * This is the backward-compatible path for agents that don't register.
+ *
+ * @module wallet/EOAWalletProvider
+ */
+
+import { ethers } from 'ethers';
+import {
+  IWalletProvider,
+  TransactionRequest,
+  TransactionReceipt,
+  WalletInfo,
+} from './IWalletProvider';
+
+export class EOAWalletProvider implements IWalletProvider {
+  private readonly wallet: ethers.Wallet;
+  private readonly chainId: number;
+
+  constructor(wallet: ethers.Wallet, chainId: number) {
+    this.wallet = wallet;
+    this.chainId = chainId;
+  }
+
+  getAddress(): string {
+    return this.wallet.address;
+  }
+
+  async sendTransaction(tx: TransactionRequest): Promise<TransactionReceipt> {
+    const response = await this.wallet.sendTransaction({
+      to: tx.to,
+      data: tx.data,
+      value: tx.value ? BigInt(tx.value) : 0n,
+    });
+    const receipt = await response.wait();
+    return {
+      hash: receipt!.hash,
+      success: receipt!.status === 1,
+    };
+  }
+
+  async sendBatchTransaction(txs: TransactionRequest[]): Promise<TransactionReceipt> {
+    if (txs.length === 0) {
+      throw new Error('sendBatchTransaction requires at least one transaction');
+    }
+
+    let lastReceipt: TransactionReceipt | undefined;
+    for (const tx of txs) {
+      lastReceipt = await this.sendTransaction(tx);
+      if (!lastReceipt.success) {
+        return lastReceipt; // Fail fast
+      }
+    }
+    return lastReceipt!;
+  }
+
+  getWalletInfo(): WalletInfo {
+    return {
+      address: this.wallet.address,
+      tier: 'eoa',
+      supportsBatching: false,
+      gasSponsored: false,
+      chainId: this.chainId,
+    };
+  }
+}

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