@agirails/sdk 2.2.3 → 2.3.1

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,

package/src/adapters/X402Adapter.ts

@@ -35,6 +35,7 @@ import {
   X402Error,
   X402ErrorCode,
   X402Network,
+  X402FeeBreakdown,
   isValidX402Network,
 } from '../types/x402';
 
@@ -46,14 +47,33 @@ import {
 export type FetchFunction = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 
 /**
- * Transfer function for atomic payments.
- * 
+ * Transfer function for atomic payments (legacy direct transfer).
+ *
  * @param to - Recipient address
  * @param amount - Amount in USDC wei (string)
  * @returns Transaction hash as proof
  */
 export type TransferFunction = (to: string, amount: string) => Promise<string>;
 
+/**
+ * Approve function for USDC allowance (used with X402Relay).
+ *
+ * @param spender - Spender address (relay contract)
+ * @param amount - Amount in USDC wei (string)
+ * @returns Transaction hash
+ */
+export type ApproveFunction = (spender: string, amount: string) => Promise<string>;
+
+/**
+ * Relay pay function — calls X402Relay.payWithFee().
+ *
+ * @param provider - Provider address
+ * @param grossAmount - Gross USDC amount (string)
+ * @param serviceId - Service identifier (bytes32 hex)
+ * @returns Transaction hash
+ */
+export type RelayPayFunction = (provider: string, grossAmount: string, serviceId: string) => Promise<string>;
+
 /** Supported HTTP methods for x402 requests */
 export type X402HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
 
@@ -76,12 +96,15 @@ export interface X402PayParams extends UnifiedPayParams {
 
 /**
  * Configuration options for X402Adapter.
+ *
+ * For fee-enabled payments via X402Relay, provide relayAddress + approveFn + relayPayFn.
+ * Without relay config, falls back to legacy direct transfer (no platform fee).
  */
 export interface X402AdapterConfig {
   /** Expected network for validation (must match server's X-Payment-Network) */
   expectedNetwork: X402Network;
 
-  /** Transfer function for atomic payments (required) */
+  /** Transfer function for direct atomic payments (legacy fallback) */
   transferFn: TransferFunction;
 
   /** Request timeout in milliseconds (default: 30000) */
@@ -92,6 +115,20 @@ export interface X402AdapterConfig {
 
   /** Default headers to include in all requests */
   defaultHeaders?: Record<string, string>;
+
+  // --- X402Relay fee-splitting (optional, recommended) ---
+
+  /** X402Relay contract address for on-chain fee splitting */
+  relayAddress?: string;
+
+  /** USDC approve function — required when relayAddress is set */
+  approveFn?: ApproveFunction;
+
+  /** Relay payWithFee function — required when relayAddress is set */
+  relayPayFn?: RelayPayFunction;
+
+  /** Platform fee in basis points (default: 100 = 1%). Read-only display hint. */
+  platformFeeBps?: number;
 }
 
 /**
@@ -104,6 +141,7 @@ interface AtomicPaymentRecord {
   amount: string;
   timestamp: number;
   endpoint: string;
+  feeBreakdown?: X402FeeBreakdown;
 }
 
 // ============================================================================
@@ -287,15 +325,15 @@ export class X402Adapter extends BaseAdapter implements IAdapter {
       );
     }
 
-    // Step 6: ATOMIC PAYMENT - direct transfer, no escrow
-    const txHash = await this.executeAtomicPayment(paymentHeaders);
+    // Step 6: ATOMIC PAYMENT - via relay (with fee) or direct transfer (legacy)
+    const { txHash, feeBreakdown } = await this.executeAtomicPayment(paymentHeaders);
 
     // Step 7: Retry with proof (same method/headers/body + payment proof)
     const serviceResponse = await this.retryWithProof(
-      endpoint, 
-      txHash, 
-      method, 
-      requestHeaders, 
+      endpoint,
+      txHash,
+      method,
+      requestHeaders,
       requestBody,
       contentType
     );
@@ -308,6 +346,7 @@ export class X402Adapter extends BaseAdapter implements IAdapter {
       amount: paymentHeaders.amount,
       timestamp: now,
       endpoint,
+      feeBreakdown,
     });
 
     // Step 9: Return result - DONE! No release needed.
@@ -323,6 +362,7 @@ export class X402Adapter extends BaseAdapter implements IAdapter {
       provider: paymentHeaders.paymentAddress.toLowerCase(),
       requester: this.requesterAddress.toLowerCase(),
       deadline: new Date(paymentHeaders.deadline * 1000).toISOString(),
+      feeBreakdown,
     };
   }
 
@@ -562,20 +602,58 @@ export class X402Adapter extends BaseAdapter implements IAdapter {
   }
 
   /**
-   * Execute atomic payment - direct transfer to provider.
+   * Execute atomic payment with fee splitting via X402Relay (if configured),
+   * or direct transfer as legacy fallback.
    *
-   * This is the key difference from ACTP:
-   * - No escrow
-   * - No state machine
-   * - Just transfer and done
+   * Relay flow: approve relay → relay.payWithFee(provider, gross, serviceId)
+   * Legacy flow: transferFn(provider, amount) — no fee extraction
    */
-  private async executeAtomicPayment(headers: X402PaymentHeaders): Promise<string> {
+  private async executeAtomicPayment(headers: X402PaymentHeaders): Promise<{
+    txHash: string;
+    feeBreakdown?: X402FeeBreakdown;
+  }> {
     try {
+      // Relay path: on-chain fee splitting
+      if (this.config.relayAddress && this.config.approveFn && this.config.relayPayFn) {
+        const grossAmount = headers.amount;
+        const feeBps = this.config.platformFeeBps ?? 100;
+        const MIN_FEE = 50_000n; // $0.05 USDC
+
+        // Calculate fee: max(gross * bps / 10000, MIN_FEE)
+        const grossBig = BigInt(grossAmount);
+        const bpsFee = (grossBig * BigInt(feeBps)) / 10_000n;
+        const fee = bpsFee > MIN_FEE ? bpsFee : MIN_FEE;
+        const providerNet = grossBig - fee;
+
+        // 1. Approve relay for gross amount
+        await this.config.approveFn(this.config.relayAddress, grossAmount);
+
+        // 2. Call relay.payWithFee
+        const serviceId = headers.serviceId ?? '0x' + '0'.repeat(64);
+        const txHash = await this.config.relayPayFn(
+          headers.paymentAddress,
+          grossAmount,
+          serviceId
+        );
+
+        return {
+          txHash,
+          feeBreakdown: {
+            grossAmount,
+            providerNet: providerNet.toString(),
+            platformFee: fee.toString(),
+            feeBps,
+            estimated: true,
+          },
+        };
+      }
+
+      // Legacy path: direct transfer, no fee
       const txHash = await this.transferFn(
         headers.paymentAddress,
         headers.amount
       );
-      return txHash;
+      return { txHash };
     } catch (error) {
       throw new X402Error(
         `Atomic payment failed: ${error instanceof Error ? error.message : 'Unknown error'}`,

package/src/adapters/index.ts

@@ -23,7 +23,15 @@ export {
 } from './BaseAdapter';
 export { BasicAdapter, BasicPayParams, BasicPayResult } from './BasicAdapter';
 export { StandardAdapter, StandardTransactionParams } from './StandardAdapter';
-export { X402Adapter, X402AdapterConfig, FetchFunction } from './X402Adapter';
+export {
+  X402Adapter,
+  X402AdapterConfig,
+  X402PayParams,
+  X402HttpMethod,
+  FetchFunction,
+  ApproveFunction,
+  RelayPayFunction,
+} from './X402Adapter';
 export { AdapterRegistry } from './AdapterRegistry';
 export { AdapterRouter, AdapterSelectionResult } from './AdapterRouter';
 export {

package/src/cli/commands/diff.ts

@@ -0,0 +1,141 @@
+/**
+ * Diff Command - Compare local AGIRAILS.md with on-chain config
+ *
+ * Shows sync status between local file and AgentRegistry state.
+ * Terraform-style: never auto-overwrites, just shows differences.
+ *
+ * @module cli/commands/diff
+ */
+
+import { Command } from 'commander';
+import { Output, ExitCode } from '../utils/output';
+import { mapError } from '../utils/client';
+import { resolve } from 'path';
+import { ethers } from 'ethers';
+import { diff } from '../../config/syncOperations';
+import { getNetwork } from '../../config/networks';
+
+// ============================================================================
+// Command Definition
+// ============================================================================
+
+export function createDiffCommand(): Command {
+  const cmd = new Command('diff')
+    .description('Compare local AGIRAILS.md with on-chain config')
+    .argument('[path]', 'Path to AGIRAILS.md', './AGIRAILS.md')
+    .option('-n, --network <network>', 'Network (base-sepolia | base-mainnet)', 'base-sepolia')
+    .option('-a, --address <address>', 'Agent address to compare with')
+    .option('--json', 'Output as JSON')
+    .option('-q, --quiet', 'Output only sync status')
+    .action(async (path, options) => {
+      const output = new Output(
+        options.json ? 'json' : options.quiet ? 'quiet' : 'human'
+      );
+
+      try {
+        await runDiff(path, options, output);
+      } catch (error) {
+        const structuredError = mapError(error);
+        output.errorResult({
+          code: structuredError.code,
+          message: structuredError.message,
+          details: structuredError.details,
+        });
+        process.exit(ExitCode.ERROR);
+      }
+    });
+
+  return cmd;
+}
+
+// ============================================================================
+// Implementation
+// ============================================================================
+
+interface DiffCommandOptions {
+  network: string;
+  address?: string;
+}
+
+async function runDiff(
+  filePath: string,
+  options: DiffCommandOptions,
+  output: Output
+): Promise<void> {
+  const resolvedPath = resolve(filePath);
+
+  // Determine agent address
+  let agentAddress = options.address;
+  if (!agentAddress) {
+    const privateKey = process.env.ACTP_PRIVATE_KEY || process.env.PRIVATE_KEY;
+    if (!privateKey) {
+      output.error('Agent address required. Use --address or set ACTP_PRIVATE_KEY env var.');
+      process.exit(ExitCode.INVALID_INPUT);
+    }
+    agentAddress = new ethers.Wallet(privateKey).address;
+  }
+
+  const networkConfig = getNetwork(options.network);
+  if (!networkConfig.contracts.agentRegistry) {
+    output.error(`AgentRegistry not deployed on ${options.network}`);
+    process.exit(ExitCode.ERROR);
+  }
+
+  const spinner = output.spinner('Comparing local and on-chain config...');
+
+  try {
+    const provider = new ethers.JsonRpcProvider(networkConfig.rpcUrl);
+
+    const result = await diff({
+      path: resolvedPath,
+      agentAddress,
+      registryAddress: networkConfig.contracts.agentRegistry,
+      provider,
+    });
+
+    spinner.stop(true);
+
+    output.result(
+      {
+        status: result.status,
+        inSync: result.inSync,
+        localHash: result.localHash,
+        onChainHash: result.onChainHash,
+        onChainCID: result.onChainCID || null,
+        hasLocalFile: result.hasLocalFile,
+        hasOnChainConfig: result.hasOnChainConfig,
+        network: options.network,
+        agent: agentAddress,
+      },
+      { quietKey: 'status' }
+    );
+
+    output.blank();
+
+    // Human-friendly status messages
+    switch (result.status) {
+      case 'in-sync':
+        output.success('Local and on-chain configs are in sync.');
+        break;
+      case 'local-ahead':
+        output.warning('Local changes not yet published. Run: actp publish');
+        break;
+      case 'remote-ahead':
+        output.warning('On-chain config is newer. Run: actp pull');
+        break;
+      case 'diverged':
+        output.warning('Local and on-chain configs have diverged.');
+        output.print('  Resolve by running: actp publish (to push local) or actp pull --force (to accept remote)');
+        break;
+      case 'no-local':
+        output.info('No local AGIRAILS.md found. Run: actp pull');
+        break;
+      case 'no-remote':
+        output.info('No config published on-chain. Run: actp publish');
+        break;
+    }
+  } catch (error) {
+    spinner.stop(false);
+    throw error;
+  }
+}