@agirails/sdk 2.2.0 → 2.2.2

package/src/adapters/AdapterRouter.ts

@@ -0,0 +1,417 @@
+/**
+ * AdapterRouter - Intelligent adapter selection with guard-rails.
+ *
+ * The router selects the best adapter for each payment based on:
+ * - Explicit adapter preference
+ * - Required capabilities (escrow, disputes, identity)
+ * - Recipient type (address vs HTTP endpoint)
+ * - Adapter priority
+ *
+ * SECURITY: All parameters are validated before selection.
+ * SECURITY: All adapters must enforce explicit release (no auto-settle).
+ *
+ * @module adapters/AdapterRouter
+ */
+
+import { AdapterRegistry } from './AdapterRegistry';
+import { IAdapter } from './IAdapter';
+import {
+  UnifiedPayParams,
+  UnifiedPayParamsSchema,
+  safeValidatePayParams,
+} from '../types/adapter';
+import { ValidationError } from './BaseAdapter';
+import { ERC8004Bridge } from '../erc8004/ERC8004Bridge';
+
+/**
+ * Result of adapter selection with potential ERC-8004 resolution.
+ */
+export interface AdapterSelectionResult {
+  /** Selected adapter */
+  adapter: IAdapter;
+
+  /** Resolved payment parameters (with wallet instead of agentId) */
+  resolvedParams: UnifiedPayParams;
+
+  /** Whether an ERC-8004 agent ID was resolved */
+  wasAgentIdResolved: boolean;
+}
+
+/**
+ * AdapterRouter - Intelligent adapter selection with guard-rails.
+ *
+ * Selection logic (in order):
+ * 1. Validate params (throws if invalid)
+ * 2. Explicit adapter requested -> use it
+ * 3. Escrow/dispute required -> StandardAdapter
+ * 4. HTTP endpoint + no escrow -> X402Adapter (when available)
+ * 5. ERC-8004 identity -> ERC8004Adapter (when available)
+ * 6. Default -> First adapter that can handle (by priority)
+ *
+ * @example
+ * ```typescript
+ * const registry = new AdapterRegistry();
+ * registry.register(basicAdapter);
+ * registry.register(standardAdapter);
+ *
+ * const router = new AdapterRouter(registry);
+ *
+ * // Auto-select best adapter
+ * const adapter = router.select({ to: '0x...', amount: '100' });
+ *
+ * // Explicit adapter request
+ * const adapter = router.select({
+ *   to: '0x...',
+ *   amount: '100',
+ *   metadata: { preferredAdapter: 'standard' }
+ * });
+ * ```
+ */
+export class AdapterRouter {
+  private erc8004Bridge?: ERC8004Bridge;
+
+  /**
+   * Creates a new AdapterRouter instance.
+   *
+   * @param registry - AdapterRegistry containing available adapters
+   * @param erc8004Bridge - Optional ERC-8004 bridge for agent ID resolution
+   */
+  constructor(
+    private registry: AdapterRegistry,
+    erc8004Bridge?: ERC8004Bridge
+  ) {
+    this.erc8004Bridge = erc8004Bridge;
+  }
+
+  /**
+   * Set the ERC-8004 bridge for agent ID resolution.
+   *
+   * @param bridge - ERC8004Bridge instance
+   */
+  setERC8004Bridge(bridge: ERC8004Bridge): void {
+    this.erc8004Bridge = bridge;
+  }
+
+  /**
+   * Select the best adapter for the given payment parameters.
+   *
+   * @param params - Unified payment parameters
+   * @returns The selected adapter
+   * @throws {ValidationError} If params are invalid
+   * @throws {Error} If no suitable adapter found
+   *
+   * @example
+   * ```typescript
+   * const adapter = router.select({
+   *   to: '0xProvider...',
+   *   amount: '100',
+   * });
+   * const result = await adapter.pay(params);
+   * ```
+   */
+  select(params: UnifiedPayParams): IAdapter {
+    // GUARD-RAIL: Validate all params first
+    this.validateParams(params);
+
+    const metadata = params.metadata || {};
+
+    // 1. Explicit adapter requested
+    if (metadata.preferredAdapter) {
+      const adapter = this.registry.get(metadata.preferredAdapter);
+      if (!adapter) {
+        throw new Error(
+          `Preferred adapter '${metadata.preferredAdapter}' not found. ` +
+            `Available adapters: ${this.registry.getIds().join(', ') || 'none'}`
+        );
+      }
+      // Verify adapter can handle these params
+      adapter.validate(params);
+      return adapter;
+    }
+
+    // 2. Escrow/dispute required -> STRICT enforcement
+    if (metadata.requiresEscrow || metadata.requiresDispute) {
+      // First try standard adapter
+      const standard = this.registry.get('standard');
+      if (standard && standard.canHandle(params)) {
+        return standard;
+      }
+
+      // Find any adapter that meets the capability requirements
+      const compatibleAdapters = this.registry.getByPriority().filter((adapter) => {
+        const meta = adapter.metadata;
+        const meetsEscrow = !metadata.requiresEscrow || meta.usesEscrow;
+        const meetsDispute = !metadata.requiresDispute || meta.supportsDisputes;
+        return meetsEscrow && meetsDispute && adapter.canHandle(params);
+      });
+
+      if (compatibleAdapters.length > 0) {
+        return compatibleAdapters[0];
+      }
+
+      // STRICT: No compatible adapter found - throw error instead of falling through
+      const requirements = [];
+      if (metadata.requiresEscrow) requirements.push('escrow');
+      if (metadata.requiresDispute) requirements.push('dispute resolution');
+      throw new Error(
+        `No adapter found that supports required capabilities: ${requirements.join(', ')}. ` +
+          `Available adapters: ${this.registry.getIds().join(', ') || 'none'}`
+      );
+    }
+
+    // 3. HTTP endpoint -> x402 (when registered)
+    // NOTE: X402Adapter is ATOMIC (usesEscrow: false) - instant payment, no escrow.
+    // Route HTTPS endpoints to x402 for fire-and-forget API payments.
+    // If caller needs escrow protection, they should use ACTP with address, not URL.
+    if (this.isHttpEndpoint(params.to)) {
+      const x402 = this.registry.get('x402');
+      if (x402 && x402.canHandle(params)) {
+        return x402;
+      }
+      // HTTP endpoints without x402 adapter will fall through
+      // and likely fail with basic/standard adapters
+    }
+
+    // 4. ERC-8004 identity -> erc8004 (when registered)
+    if (metadata.identity?.type === 'erc8004') {
+      const erc8004 = this.registry.get('erc8004');
+      if (erc8004 && erc8004.canHandle(params)) {
+        return erc8004;
+      }
+    }
+
+    // 5. Find first adapter that can handle it (by priority)
+    for (const adapter of this.registry.getByPriority()) {
+      if (adapter.canHandle(params)) {
+        return adapter;
+      }
+    }
+
+    // 6. Default to basic as last resort
+    const basic = this.registry.get('basic');
+    if (basic) {
+      // Try to use basic even if canHandle returned false
+      // Let it fail with a proper error message during pay()
+      return basic;
+    }
+
+    throw new Error(
+      `No suitable adapter found for params. ` +
+        `Available adapters: ${this.registry.getIds().join(', ') || 'none'}`
+    );
+  }
+
+  /**
+   * Validate payment parameters with Zod schema.
+   *
+   * GUARD-RAIL: Performs strict validation before any adapter selection.
+   *
+   * @param params - Parameters to validate
+   * @throws {ValidationError} If params are invalid
+   */
+  private validateParams(params: UnifiedPayParams): void {
+    const result = safeValidatePayParams(params);
+
+    if (!result.success) {
+      const issues = result.error.issues
+        .map((i) => `${i.path.join('.')}: ${i.message}`)
+        .join('; ');
+      throw new ValidationError(`Invalid payment params: ${issues}`);
+    }
+
+    // Additional security checks
+
+    // Check for path traversal attempts in 'to' field
+    if (typeof params.to === 'string') {
+      if (params.to.includes('..')) {
+        throw new ValidationError(
+          'Invalid recipient: path traversal characters not allowed'
+        );
+      }
+
+      // Check for script injection attempts
+      if (params.to.includes('<') || params.to.includes('>')) {
+        throw new ValidationError(
+          'Invalid recipient: HTML/script characters not allowed'
+        );
+      }
+
+      // Check for null bytes
+      if (params.to.includes('\0')) {
+        throw new ValidationError(
+          'Invalid recipient: null bytes not allowed'
+        );
+      }
+    }
+
+    // Validate description if provided
+    if (params.description) {
+      if (params.description.length > 1000) {
+        throw new ValidationError(
+          'Description too long: maximum 1000 characters'
+        );
+      }
+    }
+  }
+
+  /**
+   * Check if a string is an HTTP/HTTPS endpoint.
+   *
+   * @param to - Recipient string to check
+   * @returns True if it's an HTTP endpoint
+   */
+  private isHttpEndpoint(to: string): boolean {
+    try {
+      const url = new URL(to);
+      return url.protocol === 'http:' || url.protocol === 'https:';
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Get all adapters that can handle the given params.
+   *
+   * Useful for debugging or letting users choose from multiple options.
+   *
+   * @param params - Payment parameters
+   * @returns Array of adapters that can handle params
+   */
+  getCompatibleAdapters(params: UnifiedPayParams): IAdapter[] {
+    this.validateParams(params);
+    return this.registry.getAll().filter((adapter) => {
+      try {
+        return adapter.canHandle(params);
+      } catch {
+        return false;
+      }
+    });
+  }
+
+  /**
+   * Check if any adapter can handle the given params.
+   *
+   * @param params - Payment parameters
+   * @returns True if at least one adapter can handle
+   */
+  canHandle(params: UnifiedPayParams): boolean {
+    try {
+      this.validateParams(params);
+      return this.getCompatibleAdapters(params).length > 0;
+    } catch {
+      return false;
+    }
+  }
+
+  // ==========================================================================
+  // ERC-8004 Agent ID Resolution
+  // ==========================================================================
+
+  /**
+   * Select adapter AND resolve ERC-8004 agent IDs.
+   *
+   * This is the recommended method for payment flows. It:
+   * 1. Checks if `to` is an ERC-8004 agent ID (numeric string)
+   * 2. If so, resolves it to a wallet address via ERC8004Bridge
+   * 3. Stores the original agentId in erc8004AgentId field
+   * 4. Selects the appropriate adapter
+   *
+   * @param params - Unified payment parameters
+   * @returns Selection result with resolved params
+   * @throws {ValidationError} If params invalid or agent not found
+   *
+   * @example
+   * ```typescript
+   * const { adapter, resolvedParams } = await router.selectAndResolve({
+   *   to: '12345',  // ERC-8004 agent ID
+   *   amount: '100',
+   * });
+   *
+   * // resolvedParams.to is now the wallet address
+   * // resolvedParams.erc8004AgentId is '12345'
+   * const result = await adapter.pay(resolvedParams);
+   * ```
+   */
+  async selectAndResolve(params: UnifiedPayParams): Promise<AdapterSelectionResult> {
+    // Check if 'to' is an ERC-8004 agent ID
+    if (this.isERC8004AgentId(params.to)) {
+      if (!this.erc8004Bridge) {
+        throw new ValidationError(
+          `Cannot resolve ERC-8004 agent ID '${params.to}': ` +
+            'ERC-8004 resolution requires testnet or mainnet mode. ' +
+            'Use a wallet address (0x...) in mock mode, or switch to testnet/mainnet.'
+        );
+      }
+
+      try {
+        // Resolve agent ID to wallet address
+        const wallet = await this.erc8004Bridge.getAgentWallet(params.to);
+
+        // Create resolved params with wallet and stored agentId
+        const resolvedParams: UnifiedPayParams = {
+          ...params,
+          to: wallet,
+          erc8004AgentId: params.to,
+        };
+
+        // Select adapter for resolved params
+        const adapter = this.select(resolvedParams);
+
+        return {
+          adapter,
+          resolvedParams,
+          wasAgentIdResolved: true,
+        };
+      } catch (error) {
+        // Re-throw with clearer message
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        throw new ValidationError(
+          `Failed to resolve ERC-8004 agent '${params.to}': ${errorMsg}`
+        );
+      }
+    }
+
+    // Not an agent ID - proceed normally
+    const adapter = this.select(params);
+    return {
+      adapter,
+      resolvedParams: params,
+      wasAgentIdResolved: false,
+    };
+  }
+
+  /**
+   * Check if a string looks like an ERC-8004 agent ID.
+   *
+   * Agent IDs are numeric strings (uint256) that are:
+   * - NOT Ethereum addresses (0x-prefixed)
+   * - NOT URLs (http/https)
+   * - Valid as BigInt in range [0, 2^256)
+   *
+   * @param to - Recipient string to check
+   * @returns True if it looks like an agent ID
+   */
+  isERC8004AgentId(to: string): boolean {
+    if (!to || typeof to !== 'string') {
+      return false;
+    }
+
+    // Not an Ethereum address
+    if (to.startsWith('0x')) {
+      return false;
+    }
+
+    // Not a URL
+    if (to.includes('://') || to.startsWith('http')) {
+      return false;
+    }
+
+    // Must be a valid uint256
+    try {
+      const bn = BigInt(to);
+      return bn >= 0n && bn < 2n ** 256n;
+    } catch {
+      return false;
+    }
+  }
+}

package/src/adapters/BaseAdapter.ts

@@ -470,4 +470,29 @@ export abstract class BaseAdapter {
     const formattedDecimal = roundedCents.toString().padStart(2, '0');
     return `${wholePart}.${formattedDecimal} USDC`;
   }
+
+  /**
+   * Encode dispute window as ABI-encoded proof for DELIVERED transition.
+   *
+   * This helper centralizes proof encoding to prevent drift between
+   * adapters and ensures consistency with on-chain expectations.
+   *
+   * @param disputeWindowSeconds - Dispute window in seconds
+   * @returns ABI-encoded bytes32 proof
+   *
+   * @example
+   * ```typescript
+   * // Encode 2-hour dispute window
+   * const proof = this.encodeDisputeWindowProof(7200);
+   * await runtime.transitionState(txId, 'DELIVERED', proof);
+   * ```
+   */
+  protected encodeDisputeWindowProof(disputeWindowSeconds: number): string {
+    // Lazy import to avoid circular dependency issues
+    const { ethers } = require('ethers');
+    return ethers.AbiCoder.defaultAbiCoder().encode(
+      ['uint256'],
+      [disputeWindowSeconds]
+    );
+  }
 }

package/src/adapters/BasicAdapter.ts

@@ -16,6 +16,12 @@
 import { BaseAdapter, ValidationError } from './BaseAdapter';
 import { IACTPRuntime } from '../runtime/IACTPRuntime';
 import { EASHelper } from '../protocol/EASHelper';
+import { IAdapter, TransactionStatus } from './IAdapter';
+import {
+  AdapterMetadata,
+  UnifiedPayParams,
+  UnifiedPayResult,
+} from '../types/adapter';
 
 /**
  * Parameters for creating a simple payment.
@@ -70,6 +76,8 @@ export interface BasicPayResult {
  *
  * All complexity is hidden behind smart defaults.
  *
+ * Implements IAdapter for router integration.
+ *
  * @example
  * ```typescript
  * const client = await ACTPClient.create({ mode: 'mock' });
@@ -89,7 +97,19 @@ export interface BasicPayResult {
  * }
  * ```
  */
-export class BasicAdapter extends BaseAdapter {
+export class BasicAdapter extends BaseAdapter implements IAdapter {
+  /**
+   * Adapter metadata for router selection.
+   */
+  public readonly metadata: AdapterMetadata = {
+    id: 'basic',
+    name: 'Basic Adapter',
+    usesEscrow: true,
+    supportsDisputes: true,
+    requiresIdentity: false,
+    settlementMode: 'timed', // Auto-release after dispute window
+    priority: 50, // Default priority
+  };
   /**
    * Creates a new BasicAdapter instance.
    *
@@ -123,19 +143,20 @@ export class BasicAdapter extends BaseAdapter {
    * - Cannot pay yourself
    *
    * @param params - Payment parameters
+   * @param agentId - Optional ERC-8004 agent ID (for reputation reporting)
    * @returns User-friendly payment result
    * @throws {ValidationError} If inputs are invalid
    *
    * @example
    * ```typescript
-   * const result = await adapter.pay({
+   * const result = await adapter.payBasic({
    *   to: '0xProvider123',
    *   amount: '100.50',
    *   deadline: '+7d', // Optional: 7 days from now
    * });
    * ```
    */
-  async pay(params: BasicPayParams): Promise<BasicPayResult> {
+  async payBasic(params: BasicPayParams, agentId?: string): Promise<BasicPayResult> {
     // Validate and parse inputs
     const provider = this.validateAddress(params.to, 'to');
     const amount = this.parseAmount(params.amount);
@@ -173,6 +194,7 @@ export class BasicAdapter extends BaseAdapter {
       amount: amount.toString(),
       deadline,
       disputeWindow,
+      agentId, // ERC-8004 agent ID for reputation reporting
     });
 
     // Link escrow (auto-transitions to COMMITTED)
@@ -239,4 +261,178 @@ export class BasicAdapter extends BaseAdapter {
       canDispute: tx.state === 'DELIVERED' && tx.completedAt !== null && tx.completedAt + tx.disputeWindow > now,
     };
   }
+
+  // ==========================================================================
+  // IAdapter Implementation
+  // ==========================================================================
+
+  /**
+   * Execute payment through this adapter.
+   *
+   * This is the IAdapter-compatible pay() method that returns UnifiedPayResult.
+   * For the legacy BasicPayResult API, use payBasic().
+   *
+   * @param params - Unified payment parameters
+   * @returns Promise resolving to unified payment result
+   */
+  async pay(params: UnifiedPayParams): Promise<UnifiedPayResult> {
+    // Validate using IAdapter validate()
+    this.validate(params);
+
+    // Map to BasicPayParams
+    const basicParams: BasicPayParams = {
+      to: params.to,
+      amount: params.amount,
+      deadline: params.deadline,
+      disputeWindow: params.disputeWindow,
+    };
+
+    // Call existing payBasic() with optional agentId
+    const result = await this.payBasic(basicParams, params.erc8004AgentId);
+
+    // Map to UnifiedPayResult
+    return {
+      txId: result.txId,
+      escrowId: result.txId, // In ACTP, escrowId === txId
+      adapter: this.metadata.id,
+      state: 'COMMITTED',
+      success: true,
+      amount: result.amount,
+      releaseRequired: true, // ACTP requires explicit release()
+      provider: result.provider,
+      requester: result.requester,
+      deadline: result.deadline,
+      erc8004AgentId: params.erc8004AgentId,
+    };
+  }
+
+  /**
+   * Check if this adapter can handle the given parameters.
+   *
+   * BasicAdapter can handle any Ethereum address recipient.
+   *
+   * @param params - Payment parameters to check
+   * @returns True if params have a valid Ethereum address
+   */
+  canHandle(params: UnifiedPayParams): boolean {
+    // BasicAdapter handles Ethereum addresses only
+    if (typeof params.to !== 'string') {
+      return false;
+    }
+
+    // Check if it's an Ethereum address (0x-prefixed hex)
+    return /^0x[a-fA-F0-9]{40}$/.test(params.to);
+  }
+
+  /**
+   * Validate parameters before execution.
+   *
+   * @param params - Parameters to validate
+   * @throws {ValidationError} If params are invalid
+   */
+  validate(params: UnifiedPayParams): void {
+    // Validate address
+    this.validateAddress(params.to, 'to');
+
+    // Validate amount (will throw if invalid)
+    this.parseAmount(params.amount);
+
+    // Validate deadline if provided
+    if (params.deadline !== undefined) {
+      this.parseDeadline(params.deadline);
+    }
+
+    // Validate dispute window if provided
+    if (params.disputeWindow !== undefined) {
+      this.validateDisputeWindow(params.disputeWindow);
+    }
+  }
+
+  /**
+   * Get transaction status by ID.
+   *
+   * Returns TransactionStatus with action hints.
+   *
+   * @param txId - Transaction ID
+   * @returns Promise resolving to transaction status
+   */
+  async getStatus(txId: string): Promise<TransactionStatus> {
+    const tx = await this.runtime.getTransaction(txId);
+
+    if (!tx) {
+      throw new Error(`Transaction ${txId} not found`);
+    }
+
+    const now = this.runtime.time.now();
+    const disputeWindowEnds = tx.completedAt
+      ? tx.completedAt + tx.disputeWindow
+      : undefined;
+
+    return {
+      state: tx.state as TransactionStatus['state'],
+      canStartWork: tx.state === 'COMMITTED',
+      canDeliver: tx.state === 'IN_PROGRESS',
+      canRelease:
+        tx.state === 'DELIVERED' &&
+        disputeWindowEnds !== undefined &&
+        now >= disputeWindowEnds,
+      canDispute:
+        tx.state === 'DELIVERED' &&
+        disputeWindowEnds !== undefined &&
+        now < disputeWindowEnds,
+      amount: this.formatAmount(tx.amount),
+      deadline: new Date(tx.deadline * 1000).toISOString(),
+      disputeWindowEnds: disputeWindowEnds
+        ? new Date(disputeWindowEnds * 1000).toISOString()
+        : undefined,
+      provider: tx.provider,
+      requester: tx.requester,
+    };
+  }
+
+  /**
+   * Transition to IN_PROGRESS state (provider starts work).
+   *
+   * @param txId - Transaction ID
+   */
+  async startWork(txId: string): Promise<void> {
+    await this.runtime.transitionState(txId, 'IN_PROGRESS');
+  }
+
+  /**
+   * Transition to DELIVERED state (provider completes work).
+   *
+   * When no proof is provided, fetches the transaction's actual disputeWindow
+   * and encodes it as proof. This ensures consistency with the dispute window
+   * specified at transaction creation time.
+   *
+   * @param txId - Transaction ID
+   * @param proof - Optional delivery proof (ABI-encoded dispute window).
+   *                If not provided, uses transaction's disputeWindow.
+   */
+  async deliver(txId: string, proof?: string): Promise<void> {
+    let deliveryProof = proof;
+
+    if (!deliveryProof) {
+      // Fetch transaction to get its actual disputeWindow
+      const tx = await this.runtime.getTransaction(txId);
+      if (!tx) {
+        throw new Error(`Transaction ${txId} not found`);
+      }
+      // Use transaction's disputeWindow, not a default
+      deliveryProof = this.encodeDisputeWindowProof(tx.disputeWindow);
+    }
+
+    await this.runtime.transitionState(txId, 'DELIVERED', deliveryProof);
+  }
+
+  /**
+   * Release escrow funds (EXPLICIT settlement).
+   *
+   * @param escrowId - Escrow ID (usually same as txId)
+   * @param attestationUID - Optional attestation UID for verification
+   */
+  async release(escrowId: string, attestationUID?: string): Promise<void> {
+    await this.runtime.releaseEscrow(escrowId, attestationUID);
+  }
 }