@agirails/sdk 2.0.4 → 2.2.1

package/src/types/adapter.ts

@@ -0,0 +1,296 @@
+/**
+ * Adapter types for the ACTP SDK adapter routing system.
+ *
+ * This module defines types and Zod schemas for:
+ * - AdapterMetadata: Capabilities and configuration for each adapter
+ * - PaymentMetadata: Request-level hints for adapter selection
+ * - UnifiedPayParams: Common payment parameters across adapters
+ * - UnifiedPayResult: Common result type for all adapters
+ *
+ * @module types/adapter
+ */
+
+import { z } from 'zod';
+
+// ============================================================================
+// AdapterMetadata - Describes adapter capabilities
+// ============================================================================
+
+/**
+ * Metadata describing an adapter's capabilities.
+ *
+ * CRITICAL: All adapters must respect ACTP state machine:
+ * - No skipping IN_PROGRESS state
+ * - DELIVERED requires proof
+ * - releaseEscrow must be called explicitly (NO auto-settle)
+ */
+export interface AdapterMetadata {
+  /** Unique adapter identifier */
+  id: string;
+
+  /** Human-readable name */
+  name: string;
+
+  /** Whether adapter uses escrow */
+  usesEscrow: boolean;
+
+  /** Whether adapter supports dispute resolution */
+  supportsDisputes: boolean;
+
+  /** Whether adapter requires on-chain identity */
+  requiresIdentity: boolean;
+
+  /** Supported identity types (erc8004, did, ens) */
+  supportedIdentityTypes?: string[];
+
+  /**
+   * Settlement mode:
+   * - 'explicit': caller must call releaseEscrow (REQUIRED for ACTP compliance)
+   * - 'timed': auto-release after dispute window (future, not Phase 1)
+   * - 'atomic': instant settlement, no escrow (x402 protocol)
+   */
+  settlementMode: 'explicit' | 'timed' | 'atomic';
+
+  /** Priority for auto-selection (higher = preferred) */
+  priority: number;
+}
+
+/**
+ * Zod schema for AdapterMetadata runtime validation.
+ */
+export const AdapterMetadataSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  usesEscrow: z.boolean(),
+  supportsDisputes: z.boolean(),
+  requiresIdentity: z.boolean(),
+  supportedIdentityTypes: z.array(z.string()).optional(),
+  settlementMode: z.enum(['explicit', 'timed', 'atomic']),
+  priority: z.number().int().min(0).max(100),
+});
+
+// ============================================================================
+// PaymentMetadata - Request-level hints for adapter selection
+// ============================================================================
+
+/**
+ * Identity information for adapter selection.
+ */
+export interface PaymentIdentity {
+  type: 'erc8004' | 'did' | 'ens' | 'address';
+  value: string;
+}
+
+/**
+ * Payment request metadata for adapter selection.
+ */
+export interface PaymentMetadata {
+  /** Explicitly request specific adapter */
+  preferredAdapter?: string;
+
+  /** Require escrow protection */
+  requiresEscrow?: boolean;
+
+  /** Require dispute resolution capability */
+  requiresDispute?: boolean;
+
+  /** Identity information */
+  identity?: PaymentIdentity;
+
+  /** x402 specific: payment method hint */
+  paymentMethod?: 'x402' | 'actp' | 'auto';
+}
+
+/**
+ * Zod schema for PaymentIdentity runtime validation.
+ */
+export const PaymentIdentitySchema = z.object({
+  type: z.enum(['erc8004', 'did', 'ens', 'address']),
+  value: z.string().min(1),
+});
+
+/**
+ * Zod schema for PaymentMetadata runtime validation.
+ */
+export const PaymentMetadataSchema = z.object({
+  preferredAdapter: z.string().optional(),
+  requiresEscrow: z.boolean().optional(),
+  requiresDispute: z.boolean().optional(),
+  identity: PaymentIdentitySchema.optional(),
+  paymentMethod: z.enum(['x402', 'actp', 'auto']).optional(),
+});
+
+// ============================================================================
+// UnifiedPayParams - Common payment parameters
+// ============================================================================
+
+/**
+ * Unified payment parameters accepted by all adapters.
+ */
+export interface UnifiedPayParams {
+  /** Recipient - address, HTTP endpoint, or ERC-8004 agent ID */
+  to: string;
+
+  /** Amount in human-readable format */
+  amount: string | number;
+
+  /** Deadline (relative like '+24h' or unix timestamp) */
+  deadline?: string | number;
+
+  /** Dispute window in seconds (min 3600, max 30 days) */
+  disputeWindow?: number;
+
+  /** Service description */
+  description?: string;
+
+  /** Adapter selection metadata */
+  metadata?: PaymentMetadata;
+
+  /**
+   * ERC-8004 agent ID (populated when 'to' was resolved from agentId).
+   * Set by AdapterRouter when resolving agent ID to wallet address.
+   * Used for reputation reporting after settlement.
+   */
+  erc8004AgentId?: string;
+}
+
+/**
+ * Minimum dispute window in seconds (1 hour).
+ * Ensures requesters have reasonable time to dispute.
+ */
+const MIN_DISPUTE_WINDOW = 3600;
+
+/**
+ * Maximum dispute window in seconds (30 days).
+ * Prevents excessively long fund locks.
+ */
+const MAX_DISPUTE_WINDOW = 30 * 24 * 3600;
+
+/**
+ * Zod schema for UnifiedPayParams with strict validation.
+ */
+export const UnifiedPayParamsSchema = z.object({
+  to: z.string().min(1),
+  amount: z.union([z.string().min(1), z.number().positive()]),
+  deadline: z.union([z.string(), z.number()]).optional(),
+  disputeWindow: z
+    .number()
+    .int()
+    .min(MIN_DISPUTE_WINDOW)
+    .max(MAX_DISPUTE_WINDOW)
+    .optional(),
+  description: z.string().optional(),
+  metadata: PaymentMetadataSchema.optional(),
+  erc8004AgentId: z.string().optional(),
+});
+
+// ============================================================================
+// UnifiedPayResult - Common result type
+// ============================================================================
+
+/**
+ * Transaction state after payment initiation.
+ *
+ * Note: 'COMMITTED' means funds are locked but work hasn't started.
+ * 'IN_PROGRESS' means provider has acknowledged and started work.
+ */
+export type InitialTransactionState = 'COMMITTED' | 'IN_PROGRESS';
+
+/**
+ * Unified payment result returned by all adapters.
+ *
+ * NOTE: success=true means payment INITIATED, not settled.
+ * Caller must call releaseEscrow() after delivery verification.
+ */
+export interface UnifiedPayResult {
+  /** ACTP transaction ID */
+  txId: string;
+
+  /** Escrow ID (for release) - null for non-escrow adapters */
+  escrowId: string | null;
+
+  /** Adapter that handled the payment */
+  adapter: string;
+
+  /** Current state (COMMITTED, not SETTLED) */
+  state: InitialTransactionState;
+
+  /** Whether payment initiation succeeded */
+  success: boolean;
+
+  /** Amount locked (formatted) */
+  amount: string;
+
+  /** For x402: the HTTP response */
+  response?: Response;
+
+  /** Error message if failed */
+  error?: string;
+
+  /**
+   * IMPORTANT: Payment is NOT complete until you call:
+   * await client.release(result.escrowId)
+   *
+   * Always true for ACTP-compliant adapters.
+   */
+  releaseRequired: boolean;
+
+  /** Provider address (normalized to lowercase) */
+  provider: string;
+
+  /** Requester address (normalized to lowercase) */
+  requester: string;
+
+  /** Deadline as ISO 8601 timestamp */
+  deadline: string;
+
+  /**
+   * ERC-8004 agent ID (if transaction involved ERC-8004 agent).
+   * Use with ReputationReporter.reportSettlement() after release.
+   */
+  erc8004AgentId?: string;
+}
+
+/**
+ * Zod schema for UnifiedPayResult validation.
+ */
+export const UnifiedPayResultSchema = z.object({
+  txId: z.string().min(1),
+  escrowId: z.string().nullable(),
+  adapter: z.string().min(1),
+  state: z.enum(['COMMITTED', 'IN_PROGRESS']),
+  success: z.boolean(),
+  amount: z.string().min(1),
+  response: z.any().optional(),
+  error: z.string().optional(),
+  releaseRequired: z.boolean(),
+  provider: z.string().min(1),
+  requester: z.string().min(1),
+  deadline: z.string().min(1),
+  erc8004AgentId: z.string().optional(),
+});
+
+// ============================================================================
+// Validation Helpers
+// ============================================================================
+
+/**
+ * Validates UnifiedPayParams at runtime.
+ *
+ * @param params - Parameters to validate
+ * @returns Validated params
+ * @throws {z.ZodError} If validation fails
+ */
+export function validatePayParams(params: unknown): UnifiedPayParams {
+  return UnifiedPayParamsSchema.parse(params);
+}
+
+/**
+ * Safe parse for UnifiedPayParams (doesn't throw).
+ *
+ * @param params - Parameters to validate
+ * @returns Result with success flag and data or error
+ */
+export function safeValidatePayParams(params: unknown): z.SafeParseReturnType<unknown, UnifiedPayParams> {
+  return UnifiedPayParamsSchema.safeParse(params);
+}

package/src/types/erc8004.ts

@@ -0,0 +1,293 @@
+/**
+ * ERC-8004 Trustless Agents - SDK Types
+ *
+ * Types and constants for ERC-8004 integration.
+ *
+ * SECURITY NOTES:
+ * - Identity Registry is read-only (safe, no gas)
+ * - Reputation Registry writes require gas (requester pays)
+ * - Replay protection via feedbackHash = keccak256(txId)
+ * - ERC-8004 restriction: feedback submitter ≠ agent owner
+ *
+ * @see https://eips.ethereum.org/EIPS/eip-8004
+ * @module types/erc8004
+ */
+
+// ============================================================================
+// Networks
+// ============================================================================
+
+/**
+ * Networks with ERC-8004 registry deployments.
+ */
+export type ERC8004Network = 'ethereum' | 'base' | 'base-sepolia';
+
+// ============================================================================
+// Identity Types (from Identity Registry)
+// ============================================================================
+
+/**
+ * Agent identity resolved from ERC-8004 Identity Registry.
+ */
+export interface ERC8004Agent {
+  /** ERC-8004 agent ID (uint256 as string) */
+  agentId: string;
+
+  /** Owner address (EOA that controls the NFT) */
+  owner: string;
+
+  /** Payment wallet address (checksummed) */
+  wallet: string;
+
+  /** Agent URI (IPFS or HTTPS, points to metadata JSON) */
+  agentURI: string;
+
+  /** Parsed metadata from agentURI (may be undefined if fetch fails) */
+  metadata?: ERC8004AgentMetadata;
+
+  /** Network where agent is registered */
+  network: ERC8004Network;
+}
+
+/**
+ * Agent metadata schema from ERC-8004 agentURI.
+ *
+ * Standard fields defined by ERC-8004, plus arbitrary extensions.
+ */
+export interface ERC8004AgentMetadata {
+  /** Human-readable agent name */
+  name?: string;
+
+  /** Agent description */
+  description?: string;
+
+  /** Agent avatar/logo URL */
+  image?: string;
+
+  /** Wallet address for receiving payments (overrides owner) */
+  paymentAddress?: string;
+
+  /** Alternative field name for payment address */
+  wallet?: string;
+
+  /** List of agent capabilities */
+  capabilities?: string[];
+
+  /** Service endpoints */
+  endpoints?: {
+    api?: string;
+    webhook?: string;
+  };
+
+  /** Allow arbitrary extensions */
+  [key: string]: unknown;
+}
+
+// ============================================================================
+// Reputation Types (from Reputation Registry)
+// ============================================================================
+
+/**
+ * Feedback entry for ERC-8004 Reputation Registry.
+ *
+ * For ACTP settlements, we use binary values:
+ * - value: 1 (success) or -1 (dispute lost)
+ * - valueDecimals: 0 (no fractional part)
+ */
+export interface ReputationFeedback {
+  /** ERC-8004 agent ID */
+  agentId: string;
+
+  /**
+   * Feedback value.
+   * For ACTP: 1 = successful settlement, -1 = dispute lost
+   */
+  value: number;
+
+  /**
+   * Decimal precision for value.
+   * For ACTP: always 0 (binary)
+   */
+  valueDecimals: number;
+
+  /**
+   * Primary tag for categorization.
+   * ACTP uses: 'actp_settled', 'actp_dispute_won', 'actp_dispute_lost'
+   */
+  tag1: string;
+
+  /**
+   * Secondary tag for filtering.
+   * ACTP uses: capability (e.g., 'code_generation', 'data_analysis')
+   */
+  tag2: string;
+
+  /** Service endpoint (optional) */
+  endpoint?: string;
+
+  /** Link to detailed feedback (optional, IPFS or HTTPS) */
+  feedbackURI?: string;
+
+  /**
+   * Hash for replay protection.
+   * ACTP uses: keccak256(txId)
+   */
+  feedbackHash: string;
+}
+
+/**
+ * Aggregated reputation summary for an agent.
+ */
+export interface ReputationSummary {
+  /** ERC-8004 agent ID */
+  agentId: string;
+
+  /** Total feedback count */
+  feedbackCount: number;
+
+  /** Count of positive feedback (value > 0) */
+  positiveCount: number;
+
+  /** Count of negative feedback (value < 0) */
+  negativeCount: number;
+
+  /** Aggregated score (sum of values) */
+  score: number;
+}
+
+// ============================================================================
+// Errors
+// ============================================================================
+
+/**
+ * ERC-8004 error codes.
+ */
+export enum ERC8004ErrorCode {
+  // Identity errors
+  AGENT_NOT_FOUND = 'AGENT_NOT_FOUND',
+  INVALID_AGENT_ID = 'INVALID_AGENT_ID',
+  WALLET_NOT_FOUND = 'WALLET_NOT_FOUND',
+  METADATA_FETCH_FAILED = 'METADATA_FETCH_FAILED',
+
+  // Reputation errors
+  REPORT_FAILED = 'REPORT_FAILED',
+  ALREADY_REPORTED = 'ALREADY_REPORTED',
+  NOT_AUTHORIZED = 'NOT_AUTHORIZED',
+
+  // Network errors
+  NETWORK_ERROR = 'NETWORK_ERROR',
+  INVALID_NETWORK = 'INVALID_NETWORK',
+}
+
+/**
+ * Custom error for ERC-8004 operations.
+ */
+export class ERC8004Error extends Error {
+  constructor(
+    message: string,
+    public readonly code: ERC8004ErrorCode,
+    public readonly agentId?: string,
+    public readonly cause?: Error
+  ) {
+    super(message);
+    this.name = 'ERC8004Error';
+
+    // Maintain proper stack trace in V8
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, ERC8004Error);
+    }
+  }
+}
+
+// ============================================================================
+// Registry Addresses
+// ============================================================================
+
+/**
+ * ERC-8004 Identity Registry addresses per network.
+ *
+ * Canonical CREATE2 addresses from: https://github.com/erc-8004/erc-8004-contracts
+ * Vanity prefix 0x8004 ensures same address across all EVM chains.
+ */
+export const ERC8004_IDENTITY_REGISTRY: Record<ERC8004Network, string> = {
+  ethereum: '0x8004A169FB4a3325136EB29fA0ceB6D2e539a432', // Ethereum Mainnet
+  base: '0x8004A169FB4a3325136EB29fA0ceB6D2e539a432', // Base Mainnet
+  'base-sepolia': '0x8004A818BFB912233c491871b3d84c89A494BD9e', // Base Sepolia
+};
+
+/**
+ * ERC-8004 Reputation Registry addresses per network.
+ *
+ * Canonical CREATE2 addresses from: https://github.com/erc-8004/erc-8004-contracts
+ * Vanity prefix 0x8004 ensures same address across all EVM chains.
+ */
+export const ERC8004_REPUTATION_REGISTRY: Record<ERC8004Network, string> = {
+  ethereum: '0x8004BAa17C55a88189AE136b182e5fdA19dE9b63', // Ethereum Mainnet
+  base: '0x8004BAa17C55a88189AE136b182e5fdA19dE9b63', // Base Mainnet
+  'base-sepolia': '0x8004B663056A597Dffe9eCcC1965A193B7388713', // Base Sepolia
+};
+
+// ============================================================================
+// ABI Fragments (minimal, view-only for Bridge)
+// ============================================================================
+
+/**
+ * Minimal ABI for ERC-8004 Identity Registry.
+ * Only includes view functions needed by ERC8004Bridge.
+ */
+export const ERC8004_IDENTITY_ABI = [
+  'function ownerOf(uint256 agentId) view returns (address)',
+  'function getAgentURI(uint256 agentId) view returns (string)',
+  'function balanceOf(address owner) view returns (uint256)',
+  'function tokenOfOwnerByIndex(address owner, uint256 index) view returns (uint256)',
+] as const;
+
+/**
+ * Minimal ABI for ERC-8004 Reputation Registry.
+ * Includes both read and write functions.
+ */
+export const ERC8004_REPUTATION_ABI = [
+  // Write
+  'function giveFeedback(uint256 agentId, int128 value, uint8 valueDecimals, string tag1, string tag2, string endpoint, string feedbackURI, bytes32 feedbackHash) external',
+  'function revokeLatest(uint256 agentId, uint64 feedbackIndex) external',
+  // Read
+  'function getSummary(uint256 agentId, address[] clientAddresses, string tag1, string tag2) view returns (uint256 count, int256 summaryValue, uint8 summaryValueDecimals)',
+  'function readFeedback(uint256 agentId, uint64 feedbackIndex) view returns (tuple(int128 value, uint8 valueDecimals, string tag1, string tag2, bool isRevoked, uint64 feedbackIndex))',
+] as const;
+
+// ============================================================================
+// Default RPC URLs
+// ============================================================================
+
+/**
+ * Default RPC URLs for each network.
+ * Used when no custom RPC is provided.
+ */
+export const ERC8004_DEFAULT_RPC: Record<ERC8004Network, string> = {
+  ethereum: 'https://eth.llamarpc.com',
+  base: 'https://mainnet.base.org',
+  'base-sepolia': 'https://sepolia.base.org',
+};
+
+// ============================================================================
+// ACTP-specific constants
+// ============================================================================
+
+/**
+ * ACTP feedback tags for ERC-8004 Reputation.
+ */
+export const ACTP_FEEDBACK_TAGS = {
+  /** Successful settlement */
+  SETTLED: 'actp_settled',
+
+  /** Agent won dispute */
+  DISPUTE_WON: 'actp_dispute_won',
+
+  /** Agent lost dispute (requester won) */
+  DISPUTE_LOST: 'actp_dispute_lost',
+} as const;
+
+/**
+ * Type for ACTP feedback tags.
+ */
+export type ACTPFeedbackTag = (typeof ACTP_FEEDBACK_TAGS)[keyof typeof ACTP_FEEDBACK_TAGS];

package/src/types/index.ts

@@ -9,6 +9,9 @@ export * from './message';
 export * from './eip712';
 export * from './agent';
 export * from './did';
+export * from './adapter';
+export * from './x402';
+export * from './erc8004';
 // Note: storage and archive types are not yet implemented in this version
 // export * from './storage';
 // export * from './archive';

package/src/types/state.ts

@@ -18,22 +18,23 @@ export class StateMachine {
   /**
    * Valid state transitions per Yellow Paper §3.2.2
    *
-   * SECURITY FIX (CRITICAL-1): State machine must match ACTPKernel contract exactly
-   * Per CLAUDE.md §Architecture Overview - ACTP Protocol State Machine:
-   * - COMMITTED can transition to IN_PROGRESS, DELIVERED, or CANCELLED
+   * SECURITY FIX (AUDIT-2026-02): State machine must match ACTPKernel contract exactly
+   *
+   * Per on-chain ACTPKernel contract:
+   * - COMMITTED must go through IN_PROGRESS before DELIVERED (cannot skip)
+   * - DISPUTED can transition to SETTLED or CANCELLED (admin/pauser can cancel disputes)
    * - IN_PROGRESS can transition to DELIVERED or CANCELLED (not DISPUTED)
-   * - DISPUTED can only transition to SETTLED (not CANCELLED)
    */
   private static readonly TRANSITIONS: Record<State, State[]> = {
     [State.INITIATED]: [State.QUOTED, State.COMMITTED, State.CANCELLED], // Allow direct INITIATED → COMMITTED (AIP-3)
     [State.QUOTED]: [State.COMMITTED, State.CANCELLED],
-    // SECURITY FIX (CRITICAL-1): Add DELIVERED (can skip IN_PROGRESS)
-    [State.COMMITTED]: [State.IN_PROGRESS, State.DELIVERED, State.CANCELLED],
-    // SECURITY FIX (CRITICAL-1): Remove DISPUTED, add CANCELLED
+    // AUDIT FIX: COMMITTED cannot skip to DELIVERED - must go through IN_PROGRESS first
+    [State.COMMITTED]: [State.IN_PROGRESS, State.CANCELLED],
+    // IN_PROGRESS can transition to DELIVERED or CANCELLED
     [State.IN_PROGRESS]: [State.DELIVERED, State.CANCELLED],
     [State.DELIVERED]: [State.SETTLED, State.DISPUTED],
-    // SECURITY FIX (CRITICAL-1): Remove CANCELLED (disputes resolve to SETTLED only)
-    [State.DISPUTED]: [State.SETTLED],
+    // AUDIT FIX: DISPUTED can also transition to CANCELLED (admin/pauser emergency cancellation)
+    [State.DISPUTED]: [State.SETTLED, State.CANCELLED],
     [State.SETTLED]: [], // Terminal state
     [State.CANCELLED]: [] // Terminal state
   };

package/src/types/transaction.ts

@@ -20,6 +20,12 @@ export interface Transaction {
   attestationUID: string;
   metadata: string;
   platformFeeBpsLocked: number;
+  /**
+   * ERC-8004 agent token ID (optional).
+   * 0 or undefined = not an ERC-8004 agent.
+   * See ADR-001 for architectural rationale.
+   */
+  agentId?: string;
 }
 
 /**
@@ -32,6 +38,12 @@ export interface CreateTransactionParams {
   deadline: number;
   disputeWindow: number;
   metadata?: string;
+  /**
+   * ERC-8004 agent token ID (optional).
+   * Set to 0 or omit if provider is not registered in ERC-8004 Identity Registry.
+   * See ADR-001 for architectural rationale.
+   */
+  agentId?: string;
 }
 
 /**