@agirails/sdk 2.0.4 → 2.2.1

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
 // =============================================================================
@@ -217,6 +231,75 @@ export type {
   PriceCalculation,
 } from './level1';
 
+// =============================================================================
+// Storage Layer (AIP-7 §4) - Hybrid IPFS + Arweave
+// =============================================================================
+
+// Storage clients
+export { FilebaseClient } from './storage/FilebaseClient';
+export { ArweaveClient } from './storage/ArweaveClient';
+
+// Archive bundle builder
+export {
+  ArchiveBundleBuilder,
+  computeContentHash,
+  validateArchiveBundle,
+} from './storage/ArchiveBundleBuilder';
+
+// Storage types
+export type {
+  FilebaseConfig,
+  ArweaveConfig,
+  IrysCurrency,
+  IrysNetwork,
+  ArchiveBundle,
+  ArchiveChainId,
+  ArchiveFinalState,
+  ArchiveParticipants,
+  ArchiveReferences,
+  ArchiveHashes,
+  ArchiveSignatures,
+  ArchiveAttestation,
+  ArchiveSettlement,
+  EscrowRelease,
+  ArchiveTags,
+  IPFSUploadResult,
+  ArweaveUploadResult,
+  DownloadResult,
+} from './storage/types';
+
+// 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
 // =============================================================================
@@ -241,4 +324,18 @@ export {
   DisputeRaisedError,
   ServiceConfigError,
   AgentLifecycleError,
+  // Storage errors (AIP-7)
+  StorageError,
+  StorageAuthenticationError,
+  StorageRateLimitError,
+  UploadTimeoutError,
+  DownloadTimeoutError,
+  ContentNotFoundError,
+  FileSizeLimitExceededError,
+  InvalidCIDError,
+  ArweaveUploadError,
+  ArweaveDownloadError,
+  ArweaveTimeoutError,
+  InvalidArweaveTxIdError,
+  InsufficientBalanceError as StorageInsufficientBalanceError,
 } from './errors';

package/src/level0/provide.ts

@@ -12,6 +12,7 @@ import { JobHandler } from '../level1/types/Job';
 import { ProvideOptions } from '../level1/types/Options';
 import { Provider } from './Provider';
 import { serviceDirectory } from './ServiceDirectory';
+import { sdkLogger } from '../utils/Logger';
 
 /**
  * Provide a service
@@ -83,7 +84,7 @@ export function provide(
     // Register in service directory after agent has started and has an address
     serviceDirectory.register(service, agent.address);
   }).catch((error) => {
-    console.error(`Failed to start provider for ${service}:`, error);
+    sdkLogger.error(`Failed to start provider for ${service}`, { error: error instanceof Error ? error.message : String(error) });
   });
 
   // Return Provider interface (adapter over Agent)

package/src/level1/Agent.ts

@@ -1232,7 +1232,7 @@ export class Agent extends EventEmitter {
         result, // Include original result for convenience
       });
 
-      // Transition transaction to DELIVERED state
+      // Transition transaction through IN_PROGRESS → DELIVERED states
       if (this._client) {
         // Store delivery proof by directly accessing MockRuntime's state
         // This is a workaround - in production, we'd use a proper method
@@ -1246,8 +1246,18 @@ export class Agent extends EventEmitter {
           });
         }
 
-        // Transition to DELIVERED (escrow was already linked in pollForJobs)
-        await this._client.runtime.transitionState(job.id, 'DELIVERED');
+        // AUDIT FIX (2026-02): Must transition through IN_PROGRESS before DELIVERED
+        // Contract rejects COMMITTED → DELIVERED direct transition
+        await this._client.runtime.transitionState(job.id, 'IN_PROGRESS');
+
+        // Encode dispute window proof for DELIVERED transition
+        // Use transaction's disputeWindow from metadata, fallback to 2 days (172800s) per Options.ts default
+        const disputeWindowSeconds = job.metadata?.disputeWindow || 172800;
+        const abiCoder = ethers.AbiCoder.defaultAbiCoder();
+        const disputeWindowProof = abiCoder.encode(['uint256'], [disputeWindowSeconds]);
+
+        // Transition to DELIVERED with dispute window proof
+        await this._client.runtime.transitionState(job.id, 'DELIVERED', disputeWindowProof);
       }
 
       // SECURITY FIX (C-2): Remove from active jobs on SUCCESS