@agirails/sdk 2.2.0 → 2.2.2

package/src/erc8004/ReputationReporter.ts

@@ -0,0 +1,472 @@
+/**
+ * ERC-8004 Reputation Reporter
+ *
+ * WRITES to ERC-8004 Reputation Registry after ACTP settlements.
+ *
+ * CRITICAL SECURITY NOTES:
+ * 1. Requires signer (pays gas) - typically the requester
+ * 2. Caller MUST NOT be agent owner (ERC-8004 restriction)
+ * 3. Uses feedbackHash = keccak256(txId) for replay protection
+ * 4. Failures are logged but NEVER block ACTP settlement
+ * 5. Local dedup prevents double-reporting in same session
+ *
+ * WHEN TO CALL:
+ * - reportSettlement(): After successful release() (state = SETTLED)
+ * - reportDispute(): After dispute resolution
+ *
+ * FAILURE HANDLING:
+ * - All methods return null on failure (never throw)
+ * - Settlement/dispute already succeeded - reputation is bonus
+ * - Log warnings for debugging
+ *
+ * @example
+ * ```typescript
+ * const reporter = new ReputationReporter({
+ *   network: 'base-sepolia',
+ *   signer: requesterWallet,
+ * });
+ *
+ * // After successful release
+ * const txHash = await reporter.reportSettlement({
+ *   agentId: '12345',
+ *   txId: result.txId,
+ *   capability: 'code_generation',
+ * });
+ *
+ * if (txHash) {
+ *   console.log('Reputation reported:', txHash);
+ * } else {
+ *   console.warn('Report failed (settlement still succeeded)');
+ * }
+ * ```
+ *
+ * @module erc8004/ReputationReporter
+ */
+
+import { ethers, Signer } from 'ethers';
+import {
+  ERC8004Network,
+  ERC8004_REPUTATION_REGISTRY,
+  ERC8004_REPUTATION_ABI,
+  ACTP_FEEDBACK_TAGS,
+} from '../types/erc8004';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Transaction receipt interface for reputation reports.
+ */
+interface TransactionReceipt {
+  hash: string;
+  blockNumber: number;
+  gasUsed: bigint;
+}
+
+/**
+ * Transaction response interface.
+ */
+interface TransactionResponse {
+  wait(): Promise<TransactionReceipt>;
+}
+
+/**
+ * Interface for ERC-8004 Reputation Registry contract.
+ * Used for testing with mock implementations.
+ */
+export interface IERC8004ReputationRegistry {
+  giveFeedback(
+    agentId: string,
+    value: number,
+    valueDecimals: number,
+    tag1: string,
+    tag2: string,
+    endpoint: string,
+    feedbackURI: string,
+    feedbackHash: string,
+    txOptions?: { gasLimit?: bigint }
+  ): Promise<TransactionResponse>;
+
+  getSummary(
+    agentId: string,
+    clientAddresses: string[],
+    tag1: string,
+    tag2: string
+  ): Promise<[bigint, bigint, number]>;
+
+  revokeLatest(agentId: string, feedbackIndex: bigint): Promise<TransactionResponse>;
+}
+
+/**
+ * Configuration for ReputationReporter.
+ */
+export interface ReputationReporterConfig {
+  /** Target network */
+  network: ERC8004Network;
+
+  /** Signer for transactions (pays gas) */
+  signer: Signer;
+
+  /** Override registry address (optional, for testing) */
+  registryAddress?: string;
+
+  /** Gas limit override (optional) */
+  gasLimit?: bigint;
+
+  /**
+   * Injected contract instance (optional, for testing).
+   * If provided, skips creating a real ethers Contract.
+   * @internal
+   */
+  _testContract?: IERC8004ReputationRegistry;
+}
+
+/**
+ * Parameters for reporting a successful settlement.
+ */
+export interface ReportSettlementParams {
+  /** ERC-8004 agent ID */
+  agentId: string;
+
+  /** ACTP transaction ID (used for replay protection) */
+  txId: string;
+
+  /** Agent capability (e.g., 'code_generation', 'data_analysis') */
+  capability?: string;
+
+  /** Service endpoint (optional) */
+  endpoint?: string;
+
+  /** Link to transaction details (optional, IPFS or HTTPS) */
+  feedbackURI?: string;
+}
+
+/**
+ * Parameters for reporting a dispute resolution.
+ */
+export interface ReportDisputeParams {
+  /** ERC-8004 agent ID */
+  agentId: string;
+
+  /** ACTP transaction ID */
+  txId: string;
+
+  /** true if agent won the dispute, false if requester won */
+  agentWon: boolean;
+
+  /** Agent capability (optional) */
+  capability?: string;
+
+  /** Dispute reason/details (optional, stored as feedbackURI) */
+  reason?: string;
+}
+
+/**
+ * Result of a reputation report.
+ */
+export interface ReportResult {
+  /** Transaction hash */
+  txHash: string;
+
+  /** Block number */
+  blockNumber: number;
+
+  /** Gas used */
+  gasUsed: bigint;
+}
+
+// ============================================================================
+// ReputationReporter
+// ============================================================================
+
+/**
+ * Reporter for submitting ACTP settlement outcomes to ERC-8004 Reputation.
+ *
+ * Designed to never block or fail the main ACTP flow.
+ * All errors are caught and logged, returning null on failure.
+ */
+export class ReputationReporter {
+  private readonly registry: IERC8004ReputationRegistry;
+  private readonly signer: Signer;
+  private readonly network: ERC8004Network;
+  private readonly gasLimit?: bigint;
+
+  /**
+   * Track reported txIds to prevent double-reporting in same session.
+   * Note: This is in-memory only, so restarts allow re-reporting.
+   * On-chain, feedbackHash provides permanent dedup.
+   */
+  private readonly reportedTxIds: Set<string> = new Set();
+
+  constructor(config: ReputationReporterConfig) {
+    this.network = config.network;
+    this.signer = config.signer;
+    this.gasLimit = config.gasLimit;
+
+    // Use injected contract for testing
+    if (config._testContract) {
+      this.registry = config._testContract;
+      return;
+    }
+
+    const registryAddress =
+      config.registryAddress ?? ERC8004_REPUTATION_REGISTRY[config.network];
+
+    if (registryAddress === ethers.ZeroAddress) {
+      console.warn(
+        `[ERC8004] Reputation Registry not deployed on ${config.network}. ` +
+          'Reports will fail.'
+      );
+    }
+
+    this.registry = new ethers.Contract(
+      registryAddress,
+      ERC8004_REPUTATION_ABI,
+      config.signer
+    ) as unknown as IERC8004ReputationRegistry;
+  }
+
+  // ==========================================================================
+  // Public Methods
+  // ==========================================================================
+
+  /**
+   * Report successful ACTP settlement to ERC-8004 Reputation.
+   *
+   * Call this AFTER release() succeeds. Failure here does NOT affect settlement.
+   *
+   * Reports:
+   * - value: 1 (positive feedback)
+   * - valueDecimals: 0 (binary)
+   * - tag1: 'actp_settled'
+   * - tag2: capability
+   * - feedbackHash: keccak256(txId)
+   *
+   * @param params - Settlement details
+   * @returns ReportResult if successful, null if failed
+   */
+  async reportSettlement(params: ReportSettlementParams): Promise<ReportResult | null> {
+    const {
+      agentId,
+      txId,
+      capability = '',
+      endpoint = '',
+      feedbackURI = '',
+    } = params;
+
+    // Local dedup check
+    if (this.reportedTxIds.has(txId)) {
+      console.warn(`[ERC8004] Already reported txId in this session: ${txId}`);
+      return null;
+    }
+
+    try {
+      // Compute feedbackHash for on-chain replay protection
+      const feedbackHash = ethers.keccak256(ethers.toUtf8Bytes(txId));
+
+      // Prepare transaction options
+      const txOptions: { gasLimit?: bigint } = {};
+      if (this.gasLimit) {
+        txOptions.gasLimit = this.gasLimit;
+      }
+
+      // Submit feedback
+      const tx = await this.registry.giveFeedback(
+        agentId,
+        1, // value: 1 = success
+        0, // decimals: 0 (binary)
+        ACTP_FEEDBACK_TAGS.SETTLED, // tag1: 'actp_settled'
+        capability, // tag2: capability
+        endpoint,
+        feedbackURI,
+        feedbackHash,
+        txOptions
+      );
+
+      // Wait for confirmation
+      const receipt = await tx.wait();
+
+      // Mark as reported
+      this.reportedTxIds.add(txId);
+
+      return {
+        txHash: receipt.hash,
+        blockNumber: receipt.blockNumber,
+        gasUsed: receipt.gasUsed,
+      };
+    } catch (error) {
+      // Log but NEVER throw - settlement already succeeded
+      this.logError('reportSettlement', agentId, txId, error);
+      return null;
+    }
+  }
+
+  /**
+   * Report ACTP dispute resolution to ERC-8004 Reputation.
+   *
+   * Call this after dispute is resolved (either party won).
+   *
+   * Reports:
+   * - value: 1 if agent won, -1 if requester won
+   * - valueDecimals: 0 (binary)
+   * - tag1: 'actp_dispute_won' or 'actp_dispute_lost'
+   * - tag2: capability
+   * - feedbackHash: keccak256(txId)
+   *
+   * @param params - Dispute details
+   * @returns ReportResult if successful, null if failed
+   */
+  async reportDispute(params: ReportDisputeParams): Promise<ReportResult | null> {
+    const { agentId, txId, agentWon, capability = '', reason = '' } = params;
+
+    // Local dedup check
+    if (this.reportedTxIds.has(txId)) {
+      console.warn(`[ERC8004] Already reported txId in this session: ${txId}`);
+      return null;
+    }
+
+    try {
+      const feedbackHash = ethers.keccak256(ethers.toUtf8Bytes(txId));
+
+      // Determine value and tag based on outcome
+      const value = agentWon ? 1 : -1;
+      const tag1 = agentWon
+        ? ACTP_FEEDBACK_TAGS.DISPUTE_WON
+        : ACTP_FEEDBACK_TAGS.DISPUTE_LOST;
+
+      const txOptions: { gasLimit?: bigint } = {};
+      if (this.gasLimit) {
+        txOptions.gasLimit = this.gasLimit;
+      }
+
+      const tx = await this.registry.giveFeedback(
+        agentId,
+        value,
+        0, // decimals: 0 (binary)
+        tag1,
+        capability,
+        '', // endpoint
+        reason, // feedbackURI (contains dispute reason)
+        feedbackHash,
+        txOptions
+      );
+
+      const receipt = await tx.wait();
+      this.reportedTxIds.add(txId);
+
+      return {
+        txHash: receipt.hash,
+        blockNumber: receipt.blockNumber,
+        gasUsed: receipt.gasUsed,
+      };
+    } catch (error) {
+      this.logError('reportDispute', agentId, txId, error);
+      return null;
+    }
+  }
+
+  /**
+   * Get reputation summary for an agent.
+   *
+   * This is a READ operation (no gas cost).
+   *
+   * @param agentId - ERC-8004 agent ID
+   * @param tag1 - Filter by tag1 (optional, e.g., 'actp_settled')
+   * @returns Summary if successful, null if failed
+   */
+  async getAgentReputation(
+    agentId: string,
+    tag1?: string
+  ): Promise<{ count: number; score: number } | null> {
+    try {
+      const [count, summaryValue] = await this.registry.getSummary(
+        agentId,
+        [], // clientAddresses (empty = all)
+        tag1 ?? '',
+        '' // tag2
+      );
+
+      return {
+        count: Number(count),
+        score: Number(summaryValue),
+      };
+    } catch (error) {
+      console.error(
+        `[ERC8004] getAgentReputation failed for ${agentId}:`,
+        error instanceof Error ? error.message : error
+      );
+      return null;
+    }
+  }
+
+  /**
+   * Check if a transaction was already reported in this session.
+   *
+   * Note: This is local-only. For on-chain check, you'd need to
+   * query the feedbackHash mapping (not exposed in standard interface).
+   *
+   * @param txId - ACTP transaction ID
+   */
+  isReported(txId: string): boolean {
+    return this.reportedTxIds.has(txId);
+  }
+
+  /**
+   * Clear local dedup cache.
+   * Use when starting new session or for testing.
+   */
+  clearReportedCache(): void {
+    this.reportedTxIds.clear();
+  }
+
+  /**
+   * Get reporter statistics.
+   */
+  getStats(): { network: ERC8004Network; reportedCount: number } {
+    return {
+      network: this.network,
+      reportedCount: this.reportedTxIds.size,
+    };
+  }
+
+  // ==========================================================================
+  // Private Methods
+  // ==========================================================================
+
+  /**
+   * Log error in consistent format.
+   * NEVER throws - errors are informational only.
+   */
+  private logError(
+    method: string,
+    agentId: string,
+    txId: string,
+    error: unknown
+  ): void {
+    const errorMessage =
+      error instanceof Error ? error.message : String(error);
+
+    // Check for common error cases
+    if (errorMessage.includes('insufficient funds')) {
+      console.error(
+        `[ERC8004] ${method} failed for agent ${agentId}: ` +
+          'Insufficient funds for gas. Signer needs ETH/native token.'
+      );
+    } else if (errorMessage.includes('cannot be the agent owner')) {
+      console.error(
+        `[ERC8004] ${method} failed for agent ${agentId}: ` +
+          'Caller is agent owner. ERC-8004 requires different address.'
+      );
+    } else if (errorMessage.includes('user rejected')) {
+      console.warn(
+        `[ERC8004] ${method} cancelled by user for agent ${agentId}`
+      );
+    } else {
+      console.error(
+        `[ERC8004] ${method} failed for agent ${agentId} (tx: ${txId}): ` +
+          errorMessage
+      );
+    }
+  }
+}

package/src/erc8004/index.ts

@@ -0,0 +1,61 @@
+/**
+ * ERC-8004 Trustless Agents Integration
+ *
+ * Provides integration with ERC-8004 standard for:
+ * - Agent identity resolution (Identity Registry)
+ * - Reputation reporting (Reputation Registry)
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   ERC8004Bridge,
+ *   ReputationReporter,
+ *   ERC8004Error,
+ * } from '@agirails/sdk/erc8004';
+ *
+ * // Read agent info
+ * const bridge = new ERC8004Bridge({ network: 'base-sepolia' });
+ * const agent = await bridge.resolveAgent('12345');
+ *
+ * // Report settlement
+ * const reporter = new ReputationReporter({
+ *   network: 'base-sepolia',
+ *   signer: wallet,
+ * });
+ * await reporter.reportSettlement({ agentId: '12345', txId });
+ * ```
+ *
+ * @module erc8004
+ */
+
+// Bridge (read-only)
+export { ERC8004Bridge } from './ERC8004Bridge';
+export type { ERC8004BridgeConfig } from './ERC8004Bridge';
+
+// Reporter (write)
+export { ReputationReporter } from './ReputationReporter';
+export type {
+  ReputationReporterConfig,
+  ReportSettlementParams,
+  ReportDisputeParams,
+  ReportResult,
+} from './ReputationReporter';
+
+// Re-export types from types/erc8004
+export type {
+  ERC8004Network,
+  ERC8004Agent,
+  ERC8004AgentMetadata,
+  ReputationFeedback,
+  ReputationSummary,
+  ACTPFeedbackTag,
+} from '../types/erc8004';
+
+export {
+  ERC8004Error,
+  ERC8004ErrorCode,
+  ERC8004_IDENTITY_REGISTRY,
+  ERC8004_REPUTATION_REGISTRY,
+  ERC8004_DEFAULT_RPC,
+  ACTP_FEEDBACK_TAGS,
+} from '../types/erc8004';

package/src/index.ts

@@ -64,6 +64,20 @@ export {
   StandardTransactionParams,
 } from './adapters/StandardAdapter';
 
+export { AdapterRegistry } from './adapters/AdapterRegistry';
+
+export {
+  AdapterRouter,
+  AdapterSelectionResult,
+} from './adapters/AdapterRouter';
+
+export {
+  IAdapter,
+  TransactionStatus,
+  AdapterTransactionState,
+  isAdapter,
+} from './adapters/IAdapter';
+
 // =============================================================================
 // Runtime Layer - Protocol Implementation
 // =============================================================================
@@ -257,6 +271,35 @@ export type {
 // Storage constants
 export { ARCHIVE_BUNDLE_TYPE } from './storage/types';
 
+// =============================================================================
+// ERC-8004 Integration
+// =============================================================================
+
+export {
+  ERC8004Bridge,
+  ReputationReporter,
+  ERC8004Error,
+  ERC8004ErrorCode,
+  ERC8004_IDENTITY_REGISTRY,
+  ERC8004_REPUTATION_REGISTRY,
+  ERC8004_DEFAULT_RPC,
+  ACTP_FEEDBACK_TAGS,
+} from './erc8004';
+
+export type {
+  ERC8004BridgeConfig,
+  ReputationReporterConfig,
+  ReportSettlementParams,
+  ReportDisputeParams,
+  ReportResult,
+  ERC8004Network,
+  ERC8004Agent,
+  ERC8004AgentMetadata,
+  ReputationFeedback,
+  ReputationSummary,
+  ACTPFeedbackTag,
+} from './erc8004';
+
 // =============================================================================
 // Enhanced Error Exports
 // =============================================================================

package/src/protocol/ACTPKernel.ts

@@ -161,7 +161,7 @@ export class ACTPKernel {
    * Create a new transaction
    * Reference: Yellow Paper §3.4.1
    *
-   * Contract signature: createTransaction(provider, requester, amount, deadline, disputeWindow, serviceHash)
+   * Contract signature: createTransaction(provider, requester, amount, deadline, disputeWindow, serviceHash, agentId)
    * Returns: bytes32 transactionId (generated by contract)
    */
   async createTransaction(params: CreateTransactionParams): Promise<string> {
@@ -171,7 +171,8 @@ export class ACTPKernel {
       amount,
       deadline,
       disputeWindow,
-      metadata = '0x0000000000000000000000000000000000000000000000000000000000000000'
+      metadata = '0x0000000000000000000000000000000000000000000000000000000000000000',
+      agentId = '0'  // Default to 0 (not an ERC-8004 agent)
     } = params;
 
     // Input validation
@@ -185,14 +186,15 @@ export class ACTPKernel {
       // ethers v6: use getFunction() for typed access
       const createTxFunc = this.contract.getFunction('createTransaction');
 
-      // Contract signature: createTransaction(provider, requester, amount, deadline, disputeWindow, serviceHash)
+      // Contract signature: createTransaction(provider, requester, amount, deadline, disputeWindow, serviceHash, agentId)
       const estimatedGas = await createTxFunc.estimateGas(
         provider,
         requester,
         amount,
         deadline,
         disputeWindow,
-        metadata  // serviceHash
+        metadata,  // serviceHash
+        BigInt(agentId)  // ERC-8004 agent ID (0 = not an agent)
       );
 
       // Build tx options with gas settings (15% buffer for simple state initialization)
@@ -207,6 +209,7 @@ export class ACTPKernel {
         deadline,
         disputeWindow,
         metadata,  // serviceHash
+        BigInt(agentId),  // ERC-8004 agent ID
         txOptions
       );
 
@@ -549,6 +552,11 @@ export class ACTPKernel {
       throw new TransactionNotFoundError(txId);
     }
 
+    // Parse agentId - convert BigInt to string, 0n means "not an ERC-8004 agent"
+    const agentIdValue = typeof txData.agentId === 'bigint'
+      ? txData.agentId.toString()
+      : txData.agentId?.toString();
+
     return {
       txId: txData.transactionId,
       requester: txData.requester,
@@ -568,7 +576,9 @@ export class ACTPKernel {
       platformFeeBpsLocked:
         typeof txData.platformFeeBpsLocked === 'bigint'
           ? Number(txData.platformFeeBpsLocked)
-          : txData.platformFeeBpsLocked
+          : txData.platformFeeBpsLocked,
+      // ERC-8004 agent ID (undefined or '0' means not an ERC-8004 agent)
+      agentId: agentIdValue && agentIdValue !== '0' ? agentIdValue : undefined
     };
   }
 
@@ -602,7 +612,15 @@ export class ACTPKernel {
    * Estimate gas for transaction creation
    */
   async estimateCreateTransaction(params: CreateTransactionParams): Promise<bigint> {
-    const { provider, requester, amount, deadline, disputeWindow, metadata = '0x0000000000000000000000000000000000000000000000000000000000000000' } = params;
+    const {
+      provider,
+      requester,
+      amount,
+      deadline,
+      disputeWindow,
+      metadata = '0x0000000000000000000000000000000000000000000000000000000000000000',
+      agentId = '0'
+    } = params;
 
     // ethers v6: use getFunction()
     const createTxFunc = this.contract.getFunction('createTransaction');
@@ -612,7 +630,8 @@ export class ACTPKernel {
       amount,
       deadline,
       disputeWindow,
-      metadata
+      metadata,
+      BigInt(agentId)
     );
   }
 

package/src/runtime/BlockchainRuntime.ts

@@ -395,6 +395,8 @@ export class BlockchainRuntime implements IACTPRuntime {
       // SECURITY FIX (CRITICAL): serviceDescription should be a bytes32 hash
       // If caller passes raw string, it will fail on-chain. Basic/Standard API now hash before calling.
       metadata: this.validateServiceHash(params.serviceDescription),
+      // ERC-8004 agent ID - pass through if provided (see ADR-001)
+      agentId: params.agentId,
     });
 
     return txId;

package/src/runtime/IACTPRuntime.ts

@@ -29,6 +29,12 @@ export interface CreateTransactionParams {
   disputeWindow?: number;
   /** Service description or metadata hash */
   serviceDescription?: string;
+  /**
+   * ERC-8004 agent ID (optional).
+   * If set, enables reputation reporting after settlement.
+   * Stored in transaction for later use by ReputationReporter.
+   */
+  agentId?: string;
 }
 
 /**