@agirails/sdk 2.3.0 → 2.3.3

package/src/ACTPClient.ts

@@ -54,6 +54,10 @@ import { ERC8004Bridge } from './erc8004/ERC8004Bridge';
 import { ReputationReporter } from './erc8004/ReputationReporter';
 import { ERC8004Network } from './types/erc8004';
 import { getNetwork } from './config/networks';
+import { IWalletProvider } from './wallet/IWalletProvider';
+import { EOAWalletProvider } from './wallet/EOAWalletProvider';
+import { AutoWalletProvider } from './wallet/AutoWalletProvider';
+import { sdkLogger } from './utils/Logger';
 
 // ============================================================================
 // Security: Path Validation
@@ -70,6 +74,33 @@ import { getNetwork } from './config/networks';
  * @param stateDirectory - The directory path to validate
  * @throws Error if path is unsafe
  */
+/**
+ * Check if an agent is registered on AgentRegistry.
+ * Lightweight read-only check — no signer needed.
+ *
+ * Uses minimal ABI fragment to avoid importing the full AgentRegistry class.
+ * Checks registeredAt field of AgentProfile struct (> 0 means registered).
+ */
+async function checkRegistration(
+  provider: ethers.JsonRpcProvider,
+  registryAddress: string,
+  agentAddress: string
+): Promise<boolean> {
+  const contract = new ethers.Contract(
+    registryAddress,
+    [
+      'function getAgent(address agentAddress) view returns ' +
+      '(tuple(address agentAddress, string did, string endpoint, bytes32[] serviceTypes, ' +
+      'uint256 stakedAmount, uint256 reputationScore, uint256 totalTransactions, ' +
+      'uint256 disputedTransactions, uint256 totalVolumeUSDC, uint256 registeredAt, ' +
+      'uint256 updatedAt, bool isActive, bytes32 configHash, string configCID, bool listed))',
+    ],
+    provider
+  );
+  const profile = await contract.getAgent(agentAddress);
+  return profile.registeredAt > 0n;
+}
+
 function validateStateDirectory(stateDirectory: string): void {
   // Check for path traversal characters
   if (stateDirectory.includes('..')) {
@@ -174,9 +205,24 @@ export interface ACTPClientConfig {
    * This address is used as the "from" address for all transactions
    * created through this client instance.
    *
+   * When wallet is 'auto', this is auto-derived from the Smart Wallet
+   * and does NOT need to be provided.
+   *
    * @example '0x1111111111111111111111111111111111111111'
    */
-  requesterAddress: string;
+  requesterAddress?: string;
+
+  /**
+   * AIP-12: Wallet mode.
+   *
+   * - 'auto': CoinbaseSmartWallet + gas sponsorship (Tier 1, recommended).
+   *           Requires CDP_API_KEY env var. Agent address = Smart Wallet address.
+   * - undefined: EOA wallet from privateKey (Tier 2, backward compatible).
+   *
+   * When 'auto', requesterAddress is derived from the Smart Wallet
+   * and does not need to be provided.
+   */
+  wallet?: 'auto';
 
   /**
    * Optional: Project root directory for mock state file storage.
@@ -263,6 +309,7 @@ export interface ACTPClientConfig {
     actpKernel?: string;
     escrowVault?: string;
     usdc?: string;
+    agentRegistry?: string;
   };
 
   /**
@@ -319,6 +366,8 @@ export interface ACTPClientInfo {
   address: string;
   /** State directory (mock mode only) */
   stateDirectory?: string;
+  /** Wallet tier ('auto' = Smart Wallet, 'eoa' = EOA, undefined = mock) */
+  walletTier?: 'auto' | 'eoa';
 }
 
 // ============================================================================
@@ -463,6 +512,13 @@ export class ACTPClient {
    */
   private readonly reputationReporter?: ReputationReporter;
 
+  /**
+   * AIP-12: Wallet provider (Tier 1 Auto or Tier 2 EOA).
+   * Only set in testnet/mainnet modes.
+   * @internal
+   */
+  private readonly walletProvider?: IWalletProvider;
+
   /**
    * Private constructor - use ACTPClient.create() factory method.
    */
@@ -472,13 +528,16 @@ export class ACTPClient {
     info: ACTPClientInfo,
     easHelper?: EASHelper,
     erc8004Bridge?: ERC8004Bridge,
-    reputationReporter?: ReputationReporter
+    reputationReporter?: ReputationReporter,
+    walletProvider?: IWalletProvider,
+    contractAddresses?: { usdc: string; actpKernel: string; escrowVault: string }
   ) {
     this.runtime = runtime;
     this.info = info;
     this.easHelper = easHelper;
     this.reputationReporter = reputationReporter;
-    this.basic = new BasicAdapter(runtime, requesterAddress, easHelper);
+    this.walletProvider = walletProvider;
+    this.basic = new BasicAdapter(runtime, requesterAddress, easHelper, walletProvider, contractAddresses);
     this.standard = new StandardAdapter(runtime, requesterAddress, easHelper);
 
     // Initialize registry and router
@@ -527,31 +586,45 @@ export class ACTPClient {
    * ```
    */
   static async create(config: ACTPClientConfig): Promise<ACTPClient> {
-    // Validate requester address
-    if (!config.requesterAddress) {
-      throw new Error('requesterAddress is required');
-    }
-
-    if (!/^0x[a-fA-F0-9]{40}$/.test(config.requesterAddress)) {
-      throw new Error(
-        `Invalid requesterAddress: "${config.requesterAddress}". ` +
-          'Must be a valid Ethereum address (0x-prefixed, 40 hex chars)'
-      );
-    }
-
     let runtime: IACTPRuntime;
     let stateDirectory: string | undefined;
     let easHelper: EASHelper | undefined;
     let erc8004Bridge: ERC8004Bridge | undefined;
     let reputationReporter: ReputationReporter | undefined;
+    let walletProvider: IWalletProvider | undefined;
+    let requesterAddress: string;
+    let contractAddresses: { usdc: string; actpKernel: string; escrowVault: string } | undefined;
 
     // If custom runtime provided, use it directly
     if (config.runtime) {
+      // Custom runtime: requesterAddress is mandatory
+      if (!config.requesterAddress) {
+        throw new Error('requesterAddress is required when providing a custom runtime');
+      }
+      if (!/^0x[a-fA-F0-9]{40}$/.test(config.requesterAddress)) {
+        throw new Error(
+          `Invalid requesterAddress: "${config.requesterAddress}". ` +
+            'Must be a valid Ethereum address (0x-prefixed, 40 hex chars)'
+        );
+      }
+      requesterAddress = config.requesterAddress;
       runtime = config.runtime;
     } else {
       // Initialize runtime based on mode
       switch (config.mode) {
         case 'mock': {
+          // Mock mode: requesterAddress is mandatory
+          if (!config.requesterAddress) {
+            throw new Error('requesterAddress is required for mock mode');
+          }
+          if (!/^0x[a-fA-F0-9]{40}$/.test(config.requesterAddress)) {
+            throw new Error(
+              `Invalid requesterAddress: "${config.requesterAddress}". ` +
+                'Must be a valid Ethereum address (0x-prefixed, 40 hex chars)'
+            );
+          }
+          requesterAddress = config.requesterAddress;
+
           // SECURITY FIX: Enhanced path validation to prevent path traversal attacks
           if (config.stateDirectory) {
             validateStateDirectory(config.stateDirectory);
@@ -576,14 +649,12 @@ export class ACTPClient {
 
           // Map mode to network config
           const network = config.mode === 'testnet' ? 'base-sepolia' : 'base-mainnet';
+          const networkConfig = getNetwork(network);
 
           // Default RPC URL from network config if not provided
-          // This makes Level0/Agent usable on testnet without forcing users to pass rpcUrl explicitly.
-          const rpcUrl = config.rpcUrl ?? getNetwork(network).rpcUrl;
+          const rpcUrl = config.rpcUrl ?? networkConfig.rpcUrl;
 
-          // Optional persistent state directory can be used for:
-          // - mock mode state (mock-state.json)
-          // - blockchain mode safety state (e.g., used-attestation replay protection)
+          // Optional persistent state directory
           if (config.stateDirectory) {
             validateStateDirectory(config.stateDirectory);
           }
@@ -592,6 +663,100 @@ export class ACTPClient {
           const provider = new ethers.JsonRpcProvider(rpcUrl);
           const signer = new ethers.Wallet(config.privateKey, provider);
 
+          // ====================================================================
+          // AIP-12: Wallet Provider Selection
+          // ====================================================================
+          if (config.wallet === 'auto') {
+            // Tier 1: CoinbaseSmartWallet + gasless transactions
+            if (!networkConfig.aa) {
+              throw new Error(
+                `AA configuration not available for ${config.mode} mode. ` +
+                  'Check that networks.ts has aa config for this network.'
+              );
+            }
+
+            // Validate that bundler/paymaster URLs have actual API keys
+            const cdpBundlerUrl = networkConfig.aa.bundlerUrls.coinbase;
+            const hasPimlico = !!networkConfig.aa.bundlerUrls.pimlico;
+            if (cdpBundlerUrl.endsWith('/') && !hasPimlico) {
+              throw new Error(
+                'CDP_API_KEY is required for gas-sponsored transactions.\n\n' +
+                'Set up your API key:\n' +
+                '  1. Visit https://portal.cdp.coinbase.com/\n' +
+                '  2. Create a new API key\n' +
+                '  3. export CDP_API_KEY="your-key-here"\n\n' +
+                'Or set PIMLICO_API_KEY as an alternative bundler/paymaster.\n' +
+                'Or use wallet: undefined for traditional EOA transactions (requires ETH for gas).'
+              );
+            }
+
+            const autoWallet = await AutoWalletProvider.create({
+              signer,
+              provider,
+              chainId: networkConfig.chainId,
+              actpKernelAddress: config.contracts?.actpKernel ?? networkConfig.contracts.actpKernel,
+              bundler: {
+                primaryUrl: networkConfig.aa.bundlerUrls.coinbase,
+                backupUrl: networkConfig.aa.bundlerUrls.pimlico,
+              },
+              paymaster: {
+                primaryUrl: networkConfig.aa.paymasterUrls.coinbase,
+                backupUrl: networkConfig.aa.paymasterUrls.pimlico,
+              },
+            });
+
+            // Check AgentRegistry — gasless only for registered agents
+            const smartWalletAddress = autoWallet.getAddress();
+            const agentRegistryAddress = config.contracts?.agentRegistry
+              ?? networkConfig.contracts.agentRegistry;
+
+            let isRegistered = false;
+            if (agentRegistryAddress) {
+              try {
+                isRegistered = await checkRegistration(
+                  provider, agentRegistryAddress, smartWalletAddress
+                );
+              } catch {
+                // Registry check failed (e.g. RPC down) — allow AA anyway.
+                // Rationale: don't punish legit registered agents for infra issues.
+                // Paymaster contract allowlist + rate limits prevent abuse.
+                isRegistered = true;
+                sdkLogger.warn('AgentRegistry check failed, proceeding with AA wallet');
+              }
+            } else {
+              // No registry deployed — skip check (early testnet)
+              isRegistered = true;
+            }
+
+            if (isRegistered) {
+              walletProvider = autoWallet;
+              requesterAddress = smartWalletAddress;
+            } else {
+              // Not registered — fall back to EOA with warning
+              sdkLogger.warn(
+                'Agent not registered on AgentRegistry. ' +
+                'Falling back to EOA wallet (gas not sponsored). ' +
+                'Run "actp register" for gas-free transactions.'
+              );
+              walletProvider = new EOAWalletProvider(signer, networkConfig.chainId);
+              // Force signer.address — config.requesterAddress may be the Smart Wallet
+              // address (set by `actp init --wallet auto`), which would be wrong for EOA.
+              requesterAddress = signer.address;
+            }
+          } else {
+            // Tier 2: EOA Wallet (backward compatible)
+            walletProvider = new EOAWalletProvider(signer, networkConfig.chainId);
+            requesterAddress = config.requesterAddress ?? signer.address;
+          }
+
+          // Validate derived/provided address
+          if (!/^0x[a-fA-F0-9]{40}$/.test(requesterAddress)) {
+            throw new Error(
+              `Invalid requesterAddress: "${requesterAddress}". ` +
+                'Must be a valid Ethereum address (0x-prefixed, 40 hex chars)'
+            );
+          }
+
           const requireAttestation = config.requireAttestation ?? Boolean(config.easConfig);
 
           // Create BlockchainRuntime
@@ -618,7 +783,6 @@ export class ACTPClient {
           }
 
           // ERC-8004 INTEGRATION: Create bridge for agent ID resolution
-          // Maps network to ERC8004Network ('base-sepolia' or 'base')
           const erc8004Network: ERC8004Network =
             config.mode === 'testnet' ? 'base-sepolia' : 'base';
           erc8004Bridge = new ERC8004Bridge({
@@ -627,12 +791,18 @@ export class ACTPClient {
           });
 
           // ERC-8004 REPUTATION: Create reporter for settlement outcome reporting
-          // Reports successful settlements and dispute outcomes to Reputation Registry
           reputationReporter = new ReputationReporter({
             network: erc8004Network,
             signer,
           });
 
+          // AIP-12: Contract addresses for AA batched payments
+          contractAddresses = {
+            usdc: config.contracts?.usdc ?? networkConfig.contracts.usdc,
+            actpKernel: config.contracts?.actpKernel ?? networkConfig.contracts.actpKernel,
+            escrowVault: config.contracts?.escrowVault ?? networkConfig.contracts.escrowVault,
+          };
+
           break;
         }
 
@@ -645,17 +815,20 @@ export class ACTPClient {
     }
 
     // Normalize address to lowercase for consistency
-    const normalizedAddress = config.requesterAddress.toLowerCase();
+    const normalizedAddress = requesterAddress.toLowerCase();
 
     const info: ACTPClientInfo = {
       mode: config.mode,
       address: normalizedAddress,
       stateDirectory,
+      walletTier: walletProvider?.getWalletInfo().tier,
     };
 
-    // SECURITY FIX (C-4): Pass EASHelper to adapters for attestation verification
-    // ERC-8004: Pass bridge for agent ID resolution, reporter for settlement outcomes
-    const client = new ACTPClient(runtime, normalizedAddress, info, easHelper, erc8004Bridge, reputationReporter);
+    // Pass wallet provider and contract addresses to constructor
+    const client = new ACTPClient(
+      runtime, normalizedAddress, info, easHelper,
+      erc8004Bridge, reputationReporter, walletProvider, contractAddresses
+    );
 
     // Drift detection: non-blocking check for AGIRAILS.md sync status
     if (config.mode !== 'mock') {
@@ -1044,7 +1217,7 @@ export class ACTPClient {
         })
         .then((result) => {
           if (result) {
-            console.log(
+            sdkLogger.info(
               `[ERC8004] Settlement reported for agent ${agentId}: ${result.txHash}`
             );
           }
@@ -1113,6 +1286,19 @@ export class ACTPClient {
     return this.reputationReporter;
   }
 
+  /**
+   * AIP-12: Get the wallet provider instance.
+   *
+   * Only available in testnet/mainnet modes.
+   * Returns undefined in mock mode.
+   *
+   * Use this for advanced operations like checking wallet info,
+   * or sending custom batched transactions.
+   */
+  getWalletProvider(): IWalletProvider | undefined {
+    return this.walletProvider;
+  }
+
   /**
    * Non-blocking drift detection for AGIRAILS.md config.
    * Checks if local AGIRAILS.md matches on-chain config hash.
@@ -1149,17 +1335,17 @@ export class ACTPClient {
       const { frontmatter } = parseMd(content);
       const isTemplate = !frontmatter.config_hash;
 
-      const onChainState = await registryClient.getConfig(config.requesterAddress);
+      const onChainState = await registryClient.getConfig(config.requesterAddress ?? this.info.address);
       const ZERO_HASH = '0x' + '0'.repeat(64);
 
       if (onChainState.configHash === ZERO_HASH) {
         if (isTemplate) {
-          console.info('[AGIRAILS] AGIRAILS.md loaded (template mode). Run "actp publish" to register and sync on-chain.');
+          sdkLogger.info('[AGIRAILS] AGIRAILS.md loaded (template mode). Run "actp publish" to register and sync on-chain.');
         } else {
-          console.warn('[AGIRAILS] Config not published on-chain. Run: actp publish');
+          sdkLogger.warn('[AGIRAILS] Config not published on-chain. Run: actp publish');
         }
       } else if (onChainState.configHash !== localHash) {
-        console.warn('[AGIRAILS] Local AGIRAILS.md differs from on-chain. Run: actp diff');
+        sdkLogger.warn('[AGIRAILS] Local AGIRAILS.md differs from on-chain. Run: actp diff');
       }
     } catch {
       // Silently ignore — drift detection is best-effort

package/src/adapters/AdapterRouter.ts

@@ -17,7 +17,6 @@ import { AdapterRegistry } from './AdapterRegistry';
 import { IAdapter } from './IAdapter';
 import {
   UnifiedPayParams,
-  UnifiedPayParamsSchema,
   safeValidatePayParams,
 } from '../types/adapter';
 import { ValidationError } from './BaseAdapter';

package/src/adapters/BasicAdapter.ts

@@ -22,6 +22,8 @@ import {
   UnifiedPayParams,
   UnifiedPayResult,
 } from '../types/adapter';
+import { IWalletProvider } from '../wallet/IWalletProvider';
+import { ethers } from 'ethers';
 
 /**
  * Parameters for creating a simple payment.
@@ -116,11 +118,15 @@ export class BasicAdapter extends BaseAdapter implements IAdapter {
    * @param runtime - ACTP runtime implementation (MockRuntime or BlockchainRuntime)
    * @param requesterAddress - The requester's Ethereum address
    * @param easHelper - Optional EAS helper for attestation verification (SECURITY FIX C-4)
+   * @param walletProvider - Optional wallet provider for AA batched payments
+   * @param contractAddresses - Optional contract addresses for batched payment encoding
    */
   constructor(
     private runtime: IACTPRuntime,
     requesterAddress: string,
-    private easHelper?: EASHelper
+    private easHelper?: EASHelper,
+    private walletProvider?: IWalletProvider,
+    private contractAddresses?: { usdc: string; actpKernel: string; escrowVault: string }
   ) {
     super(requesterAddress);
   }
@@ -187,6 +193,40 @@ export class BasicAdapter extends BaseAdapter implements IAdapter {
       );
     }
 
+    // ====================================================================
+    // AIP-12: Batched payment via AA wallet (1 UserOp = 3 on-chain calls)
+    // ====================================================================
+    if (this.walletProvider?.payACTPBatched && this.contractAddresses) {
+      const serviceHash = ethers.ZeroHash;
+      const result = await this.walletProvider.payACTPBatched({
+        provider,
+        requester,
+        amount: amount.toString(),
+        deadline,
+        disputeWindow,
+        serviceHash,
+        agentId: agentId || '0',
+        contracts: this.contractAddresses,
+      });
+
+      if (!result.success) {
+        throw new Error(`Batched payment UserOp failed: ${result.hash}`);
+      }
+
+      return {
+        txId: result.txId,
+        provider,
+        requester,
+        amount: this.formatAmount(amount),
+        deadline: new Date(deadline * 1000).toISOString(),
+        state: 'COMMITTED',
+      };
+    }
+
+    // ====================================================================
+    // Legacy flow: sequential on-chain calls (EOA / mock)
+    // ====================================================================
+
     // Create transaction
     const txId = await this.runtime.createTransaction({
       provider,