@agirails/sdk 2.2.0 → 2.2.2

package/src/ACTPClient.ts

@@ -45,7 +45,14 @@ import { BlockchainRuntime } from './runtime/BlockchainRuntime';
 import { IACTPRuntime, IMockRuntime } from './runtime/IACTPRuntime';
 import { BasicAdapter } from './adapters/BasicAdapter';
 import { StandardAdapter } from './adapters/StandardAdapter';
+import { AdapterRegistry } from './adapters/AdapterRegistry';
+import { AdapterRouter } from './adapters/AdapterRouter';
+import { IAdapter, TransactionStatus } from './adapters/IAdapter';
+import { UnifiedPayParams, UnifiedPayResult } from './types/adapter';
 import { EASHelper, EASConfig } from './protocol/EASHelper';
+import { ERC8004Bridge } from './erc8004/ERC8004Bridge';
+import { ReputationReporter } from './erc8004/ReputationReporter';
+import { ERC8004Network } from './types/erc8004';
 import { getNetwork } from './config/networks';
 
 // ============================================================================
@@ -435,6 +442,27 @@ export class ACTPClient {
    */
   public readonly easHelper?: EASHelper;
 
+  /**
+   * Adapter registry for managing available adapters.
+   *
+   * Used internally by the router but exposed for custom adapter registration.
+   */
+  private readonly registry: AdapterRegistry;
+
+  /**
+   * Adapter router for intelligent adapter selection.
+   *
+   * Selects the best adapter based on payment parameters and metadata.
+   */
+  private readonly router: AdapterRouter;
+
+  /**
+   * ERC-8004 Reputation Reporter (testnet/mainnet only).
+   * Used to report settlement outcomes to ERC-8004 Reputation Registry.
+   * @internal
+   */
+  private readonly reputationReporter?: ReputationReporter;
+
   /**
    * Private constructor - use ACTPClient.create() factory method.
    */
@@ -442,13 +470,22 @@ export class ACTPClient {
     runtime: IACTPRuntime,
     requesterAddress: string,
     info: ACTPClientInfo,
-    easHelper?: EASHelper
+    easHelper?: EASHelper,
+    erc8004Bridge?: ERC8004Bridge,
+    reputationReporter?: ReputationReporter
   ) {
     this.runtime = runtime;
     this.info = info;
     this.easHelper = easHelper;
+    this.reputationReporter = reputationReporter;
     this.basic = new BasicAdapter(runtime, requesterAddress, easHelper);
     this.standard = new StandardAdapter(runtime, requesterAddress, easHelper);
+
+    // Initialize registry and router
+    this.registry = new AdapterRegistry();
+    this.registry.register(this.basic);
+    this.registry.register(this.standard);
+    this.router = new AdapterRouter(this.registry, erc8004Bridge);
   }
 
   // ==========================================================================
@@ -505,6 +542,8 @@ export class ACTPClient {
     let runtime: IACTPRuntime;
     let stateDirectory: string | undefined;
     let easHelper: EASHelper | undefined;
+    let erc8004Bridge: ERC8004Bridge | undefined;
+    let reputationReporter: ReputationReporter | undefined;
 
     // If custom runtime provided, use it directly
     if (config.runtime) {
@@ -577,6 +616,23 @@ export class ACTPClient {
           if (config.easConfig) {
             easHelper = blockchainRuntime.getEASHelper();
           }
+
+          // 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({
+            network: erc8004Network,
+            rpcUrl,
+          });
+
+          // ERC-8004 REPUTATION: Create reporter for settlement outcome reporting
+          // Reports successful settlements and dispute outcomes to Reputation Registry
+          reputationReporter = new ReputationReporter({
+            network: erc8004Network,
+            signer,
+          });
+
           break;
         }
 
@@ -598,7 +654,8 @@ export class ACTPClient {
     };
 
     // SECURITY FIX (C-4): Pass EASHelper to adapters for attestation verification
-    return new ACTPClient(runtime, normalizedAddress, info, easHelper);
+    // ERC-8004: Pass bridge for agent ID resolution, reporter for settlement outcomes
+    return new ACTPClient(runtime, normalizedAddress, info, easHelper, erc8004Bridge, reputationReporter);
   }
 
   // ==========================================================================
@@ -787,4 +844,263 @@ export class ACTPClient {
 
     return this.runtime.getBalance(address);
   }
+
+  // ==========================================================================
+  // Unified Payment API (Router-based)
+  // ==========================================================================
+
+  /**
+   * Unified pay method - auto-selects the best adapter.
+   *
+   * This is the recommended way to initiate payments. The router
+   * intelligently selects the appropriate adapter based on:
+   * - Explicit adapter preference (metadata.preferredAdapter)
+   * - Required capabilities (escrow, disputes)
+   * - Recipient type (address vs HTTP endpoint)
+   *
+   * IMPORTANT: Returns with state=COMMITTED, NOT settled.
+   * You MUST call the lifecycle methods to complete:
+   *
+   * ```typescript
+   * const result = await client.pay({ to, amount });
+   * // ... provider does work ...
+   * await client.startWork(result.txId);
+   * await client.deliver(result.txId);
+   * // ... after dispute window ...
+   * await client.release(result.escrowId!);  // EXPLICIT release
+   * ```
+   *
+   * @param params - Unified payment parameters
+   * @returns Promise resolving to unified payment result
+   * @throws {ValidationError} If params are invalid
+   * @throws {Error} If no suitable adapter found
+   *
+   * @example
+   * ```typescript
+   * // Simple payment (uses basic adapter by default)
+   * const result = await client.pay({
+   *   to: '0xProvider...',
+   *   amount: '100',
+   * });
+   *
+   * // Require escrow (prefers standard adapter)
+   * const result = await client.pay({
+   *   to: '0xProvider...',
+   *   amount: '100',
+   *   metadata: { requiresEscrow: true }
+   * });
+   *
+   * // Explicit adapter selection
+   * const result = await client.pay({
+   *   to: '0xProvider...',
+   *   amount: '100',
+   *   metadata: { preferredAdapter: 'standard' }
+   * });
+   * ```
+   */
+  async pay(params: UnifiedPayParams): Promise<UnifiedPayResult> {
+    // Use selectAndResolve to auto-resolve ERC-8004 agent IDs to wallet addresses
+    const { adapter, resolvedParams } = await this.router.selectAndResolve(params);
+    return adapter.pay(resolvedParams);
+  }
+
+  /**
+   * Get transaction status by ID.
+   *
+   * Returns current state plus action hints indicating
+   * what operations are available.
+   *
+   * @param txId - Transaction ID
+   * @returns Promise resolving to transaction status
+   * @throws {Error} If transaction not found
+   *
+   * @example
+   * ```typescript
+   * const status = await client.getStatus(txId);
+   * if (status.canRelease) {
+   *   await client.release(txId);
+   * }
+   * ```
+   */
+  async getStatus(txId: string): Promise<TransactionStatus> {
+    // Use standard adapter for status - it has access to all tx details
+    return this.standard.getStatus(txId);
+  }
+
+  /**
+   * Transition to IN_PROGRESS state (provider starts work).
+   *
+   * Must be called by provider after accepting the transaction.
+   * ACTP requires this explicit transition before delivery.
+   *
+   * @param txId - Transaction ID
+   * @throws {Error} If transaction not found or wrong state
+   *
+   * @example
+   * ```typescript
+   * // Provider acknowledges and starts work
+   * await client.startWork(txId);
+   * ```
+   */
+  async startWork(txId: string): Promise<void> {
+    await this.runtime.transitionState(txId, 'IN_PROGRESS');
+  }
+
+  /**
+   * Transition to DELIVERED state (provider completes work).
+   *
+   * When no disputeWindowSeconds is provided, uses the transaction's actual
+   * disputeWindow from creation time. This ensures consistency and prevents
+   * mismatches between transaction creation and delivery.
+   *
+   * @param txId - Transaction ID
+   * @param disputeWindowSeconds - Optional dispute window override in seconds.
+   *                               If not provided, uses transaction's disputeWindow.
+   * @throws {Error} If transaction not found or wrong state
+   *
+   * @example
+   * ```typescript
+   * // Use transaction's disputeWindow (recommended)
+   * await client.deliver(txId);
+   *
+   * // Override with custom dispute window (use with caution)
+   * await client.deliver(txId, 7200);
+   * ```
+   */
+  async deliver(txId: string, disputeWindowSeconds?: number): Promise<void> {
+    // Fetch transaction
+    const tx = await this.runtime.getTransaction(txId);
+    if (!tx) {
+      throw new Error(`Transaction ${txId} not found`);
+    }
+
+    // First ensure we're in IN_PROGRESS state
+    if (tx.state === 'COMMITTED') {
+      await this.runtime.transitionState(txId, 'IN_PROGRESS');
+    }
+
+    // Use provided disputeWindow or fall back to transaction's disputeWindow
+    const effectiveDisputeWindow = disputeWindowSeconds ?? tx.disputeWindow;
+
+    // Encode dispute window as proof
+    const proof = ethers.AbiCoder.defaultAbiCoder().encode(
+      ['uint256'],
+      [effectiveDisputeWindow]
+    );
+
+    await this.runtime.transitionState(txId, 'DELIVERED', proof);
+  }
+
+  /**
+   * Release escrow funds (EXPLICIT settlement).
+   *
+   * MUST be called after dispute window expires or requester approves.
+   * This is the ONLY way to settle - NO auto-settle.
+   *
+   * If ERC-8004 agent ID was set during transaction creation, this method
+   * also reports the settlement to the ERC-8004 Reputation Registry.
+   * Reputation reporting is non-blocking - failures don't affect settlement.
+   *
+   * @param escrowId - Escrow ID (usually same as txId)
+   * @param attestationUID - Optional attestation UID for verification
+   * @throws {Error} If escrow not found or dispute window active
+   *
+   * @example
+   * ```typescript
+   * // After dispute window expires
+   * await client.release(result.escrowId!);
+   * // Transaction is now SETTLED
+   * // If ERC-8004 agent, reputation is automatically reported
+   * ```
+   */
+  async release(escrowId: string, attestationUID?: string): Promise<void> {
+    // In ACTP, escrowId === txId
+    const txId = escrowId;
+
+    // Get transaction to find agentId (for reputation reporting)
+    const tx = await this.runtime.getTransaction(txId);
+    const agentId = tx?.agentId;
+
+    // Release escrow (this is the critical operation)
+    await this.runtime.releaseEscrow(escrowId, attestationUID);
+
+    // ERC-8004 REPUTATION: Report settlement if agent ID exists
+    // Non-blocking - fire and forget (settlement already succeeded)
+    if (this.reputationReporter && agentId && agentId !== '0') {
+      // Don't await - reputation reporting shouldn't block the release
+      this.reputationReporter
+        .reportSettlement({
+          agentId,
+          txId,
+        })
+        .then((result) => {
+          if (result) {
+            console.log(
+              `[ERC8004] Settlement reported for agent ${agentId}: ${result.txHash}`
+            );
+          }
+        })
+        .catch(() => {
+          // Errors already logged by reporter - silently ignore here
+        });
+    }
+  }
+
+  /**
+   * Register a custom adapter.
+   *
+   * Allows adding custom payment adapters (e.g., x402, ERC-8004)
+   * that will be considered during router selection.
+   *
+   * @param adapter - Adapter to register
+   *
+   * @example
+   * ```typescript
+   * // Register a custom x402 adapter
+   * client.registerAdapter(new X402Adapter(client.runtime, requesterAddress));
+   * ```
+   */
+  registerAdapter(adapter: IAdapter): void {
+    this.registry.register(adapter);
+  }
+
+  /**
+   * Get all registered adapter IDs.
+   *
+   * @returns Array of adapter IDs
+   *
+   * @example
+   * ```typescript
+   * const adapters = client.getRegisteredAdapters();
+   * console.log(adapters); // ['basic', 'standard', 'x402']
+   * ```
+   */
+  getRegisteredAdapters(): string[] {
+    return this.registry.getIds();
+  }
+
+  /**
+   * Get the ERC-8004 Reputation Reporter instance.
+   *
+   * Only available in testnet/mainnet modes. Returns undefined in mock mode.
+   * Use this for manual reputation reporting or checking stats.
+   *
+   * @returns ReputationReporter instance or undefined
+   *
+   * @example
+   * ```typescript
+   * const reporter = client.getReputationReporter();
+   * if (reporter) {
+   *   // Check if already reported
+   *   const reported = reporter.isReported(txId);
+   *
+   *   // Get agent reputation
+   *   const rep = await reporter.getAgentReputation('12345');
+   *   console.log(`Agent has ${rep?.count} reviews, score: ${rep?.score}`);
+   * }
+   * ```
+   */
+  getReputationReporter(): ReputationReporter | undefined {
+    return this.reputationReporter;
+  }
 }

package/src/abi/ACTPKernel.json

@@ -328,6 +328,11 @@
         "name": "serviceHash",
         "type": "bytes32",
         "internalType": "bytes32"
+      },
+      {
+        "name": "agentId",
+        "type": "uint256",
+        "internalType": "uint256"
       }
     ],
     "outputs": [
@@ -477,6 +482,11 @@
             "name": "platformFeeBpsLocked",
             "type": "uint16",
             "internalType": "uint16"
+          },
+          {
+            "name": "agentId",
+            "type": "uint256",
+            "internalType": "uint256"
           }
         ]
       }
@@ -1328,6 +1338,12 @@
         "type": "uint256",
         "indexed": false,
         "internalType": "uint256"
+      },
+      {
+        "name": "agentId",
+        "type": "uint256",
+        "indexed": false,
+        "internalType": "uint256"
       }
     ],
     "anonymous": false

package/src/adapters/AdapterRegistry.ts

@@ -0,0 +1,173 @@
+/**
+ * AdapterRegistry - Central registry for payment adapters.
+ *
+ * Manages the collection of available adapters and provides
+ * methods for registration, lookup, and priority-based retrieval.
+ *
+ * @module adapters/AdapterRegistry
+ */
+
+import { IAdapter } from './IAdapter';
+
+/**
+ * AdapterRegistry - Central registry for managing available adapters.
+ *
+ * The registry maintains a collection of adapters indexed by their ID.
+ * It provides methods for:
+ * - Registration and unregistration
+ * - Lookup by ID
+ * - Priority-sorted retrieval
+ *
+ * @example
+ * ```typescript
+ * const registry = new AdapterRegistry();
+ *
+ * // Register adapters
+ * registry.register(basicAdapter);
+ * registry.register(standardAdapter);
+ *
+ * // Lookup by ID
+ * const adapter = registry.get('basic');
+ *
+ * // Get all adapters sorted by priority
+ * const adapters = registry.getByPriority();
+ * ```
+ */
+export class AdapterRegistry {
+  /**
+   * Internal map of adapters by ID.
+   */
+  private adapters: Map<string, IAdapter> = new Map();
+
+  /**
+   * Register an adapter.
+   *
+   * If an adapter with the same ID already exists, it will be replaced.
+   *
+   * @param adapter - Adapter to register
+   *
+   * @example
+   * ```typescript
+   * registry.register(new BasicAdapter(runtime, requesterAddress));
+   * ```
+   */
+  register(adapter: IAdapter): void {
+    if (!adapter.metadata?.id) {
+      throw new Error('Cannot register adapter without metadata.id');
+    }
+    this.adapters.set(adapter.metadata.id, adapter);
+  }
+
+  /**
+   * Unregister an adapter by ID.
+   *
+   * @param id - Adapter ID to remove
+   * @returns True if adapter was found and removed, false otherwise
+   *
+   * @example
+   * ```typescript
+   * const removed = registry.unregister('custom-adapter');
+   * ```
+   */
+  unregister(id: string): boolean {
+    return this.adapters.delete(id);
+  }
+
+  /**
+   * Get an adapter by ID.
+   *
+   * @param id - Adapter ID to look up
+   * @returns The adapter or undefined if not found
+   *
+   * @example
+   * ```typescript
+   * const adapter = registry.get('standard');
+   * if (adapter) {
+   *   await adapter.pay(params);
+   * }
+   * ```
+   */
+  get(id: string): IAdapter | undefined {
+    return this.adapters.get(id);
+  }
+
+  /**
+   * Get all registered adapters.
+   *
+   * Returns adapters in insertion order.
+   *
+   * @returns Array of all registered adapters
+   *
+   * @example
+   * ```typescript
+   * const all = registry.getAll();
+   * console.log(`${all.length} adapters registered`);
+   * ```
+   */
+  getAll(): IAdapter[] {
+    return Array.from(this.adapters.values());
+  }
+
+  /**
+   * Check if an adapter is registered.
+   *
+   * @param id - Adapter ID to check
+   * @returns True if adapter is registered
+   *
+   * @example
+   * ```typescript
+   * if (registry.has('x402')) {
+   *   console.log('x402 adapter available');
+   * }
+   * ```
+   */
+  has(id: string): boolean {
+    return this.adapters.has(id);
+  }
+
+  /**
+   * Get adapters sorted by priority (highest first).
+   *
+   * Higher priority adapters are tried first during selection.
+   *
+   * @returns Array of adapters sorted by priority descending
+   *
+   * @example
+   * ```typescript
+   * const byPriority = registry.getByPriority();
+   * // byPriority[0] has highest priority
+   * ```
+   */
+  getByPriority(): IAdapter[] {
+    return this.getAll().sort(
+      (a, b) => b.metadata.priority - a.metadata.priority
+    );
+  }
+
+  /**
+   * Get the number of registered adapters.
+   *
+   * @returns Number of adapters
+   */
+  get size(): number {
+    return this.adapters.size;
+  }
+
+  /**
+   * Get all adapter IDs.
+   *
+   * @returns Array of adapter IDs
+   */
+  getIds(): string[] {
+    return Array.from(this.adapters.keys());
+  }
+
+  /**
+   * Clear all registered adapters.
+   *
+   * Primarily useful for testing.
+   */
+  clear(): void {
+    this.adapters.clear();
+  }
+}