@agirails/sdk 2.0.4 → 2.2.1

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)
     );
   }
 
@@ -681,16 +700,18 @@ export class ACTPKernel {
       validateAddress(mediator, 'mediator');
     }
 
-    // Encode resolution proof (128 bytes: 3x uint256 + address)
-    // Kernel contract will decode this in _decodeResolutionProof and disburse funds
+    // Encode resolution proof (128 bytes: 2x uint256 + address + uint256)
+    // AUDIT FIX (2026-02): Contract expects: (uint256, uint256, address, uint256)
+    // = [requesterAmount, providerAmount, mediator, mediatorAmount]
+    // See ACTPKernel.sol _decodeResolutionProof() line 654-655
     const abiCoder = AbiCoder.defaultAbiCoder();
     const proofData = abiCoder.encode(
-      ['uint256', 'uint256', 'uint256', 'address'],
+      ['uint256', 'uint256', 'address', 'uint256'],
       [
         requesterAmount,
         providerAmount,
-        mediatorAmount,
-        mediator || ethers.getAddress('0x0000000000000000000000000000000000000000')
+        mediator || ethers.getAddress('0x0000000000000000000000000000000000000000'),
+        mediatorAmount
       ]
     );
 

package/src/protocol/DIDResolver.ts

@@ -115,7 +115,7 @@ export class DIDResolver {
         network: config.network,
         chainId: config.chainId || networkConfig.chainId,
         rpcUrl: config.rpcUrl || networkConfig.rpcUrl,
-        registryAddress: config.registryAddress || networkConfig.contracts.agentRegistry || ''
+        registryAddress: config.registryAddress || networkConfig.contracts.identityRegistry || ''
       };
     }
 

package/src/protocol/EASHelper.ts

@@ -6,6 +6,7 @@ import {
   IUsedAttestationTracker,
   InMemoryUsedAttestationTracker
 } from '../utils/UsedAttestationTracker';
+import { sdkLogger } from '../utils/Logger';
 
 export interface EASConfig {
   contractAddress: string;
@@ -65,11 +66,7 @@ export class EASHelper {
       //
       // Without persistence, attestation replay protection is lost on process restart,
       // allowing potential double-spend attacks.
-      console.warn(
-        '[SECURITY WARNING] EASHelper: Using in-memory attestation tracker. ' +
-        'Replay protection will be lost on process restart. ' +
-        'For production, provide FileBasedUsedAttestationTracker for persistence.'
-      );
+      sdkLogger.warn('Using in-memory attestation tracker - replay protection lost on restart (use FileBasedUsedAttestationTracker for production)');
     }
     this.attestationTracker = attestationTracker || new InMemoryUsedAttestationTracker();
   }

package/src/protocol/MessageSigner.ts

@@ -10,6 +10,7 @@ import {
   deliveryProofDataFromProof
 } from '../types/eip712';
 import { IReceivedNonceTracker } from '../utils/ReceivedNonceTracker';
+import { sdkLogger } from '../utils/Logger';
 
 // Legacy generic ACTP message types moved to types/eip712.ts
 
@@ -175,22 +176,14 @@ export class MessageSigner {
     const nonceValue = BigInt(nonce);
     if (nonceValue < 0xFFFFFFFFn) {
       // Nonce is suspiciously small (< 4 billion = likely sequential)
-      console.warn(
-        `[SECURITY WARNING] Nonce ${nonce} appears to be sequential (value < 2^32). ` +
-        `This makes replay attacks easier. ` +
-        `Use SecureNonce.generateSecureNonce() for cryptographically secure random nonces.`
-      );
+      sdkLogger.warn('Nonce appears sequential - use SecureNonce.generateSecureNonce()', { nonce });
     }
 
     // Check if nonce has all same digits (e.g., 0x111...111 or 0x000...000)
     const hexDigits = nonce.slice(2); // Remove '0x'
     const firstDigit = hexDigits[0];
     if (hexDigits.split('').every(d => d === firstDigit)) {
-      console.warn(
-        `[SECURITY WARNING] Nonce ${nonce} has low entropy (all digits are '${firstDigit}'). ` +
-        `This is NOT cryptographically secure. ` +
-        `Use SecureNonce.generateSecureNonce() instead.`
-      );
+      sdkLogger.warn('Nonce has low entropy - use SecureNonce.generateSecureNonce()', { nonce, repeatedDigit: firstDigit });
     }
 
     // Generic ACTPMessage with payload encoding (backward compatible)
@@ -463,10 +456,11 @@ export class MessageSigner {
         // This prevents cross-chain replay attacks where a message signed for one chain
         // is replayed on another. For now, we just extract the address but log a warning.
         if (this.domain && this.domain.chainId !== chainId) {
-          console.warn(
-            `[SECURITY WARNING] DID chainId (${chainId}) does not match domain chainId (${this.domain.chainId}). ` +
-            `This could indicate a cross-chain replay attempt. DID: ${did}`
-          );
+          sdkLogger.warn('DID chainId mismatch - potential cross-chain replay attempt', {
+            didChainId: chainId,
+            domainChainId: this.domain.chainId,
+            did,
+          });
         }
 
         return address;

package/src/runtime/BlockchainRuntime.ts

@@ -28,6 +28,7 @@ import { ValidationError } from '../errors';
 import { ServiceHash, DisputeWindow } from '../utils/Helpers';
 import { IUsedAttestationTracker, createUsedAttestationTracker } from '../utils/UsedAttestationTracker';
 import { IReceivedNonceTracker, createReceivedNonceTracker } from '../utils/ReceivedNonceTracker';
+import { sdkLogger } from '../utils/Logger';
 
 /**
  * Configuration for BlockchainRuntime
@@ -217,20 +218,17 @@ export class BlockchainRuntime implements IACTPRuntime {
         );
       }
 
-      console.info(
-        `BlockchainRuntime: Connected to ${this.networkConfig.name} (chainId: ${connectedChainId})`
-      );
+      sdkLogger.info(`Connected to ${this.networkConfig.name}`, { chainId: connectedChainId });
     } catch (error) {
       if (error instanceof Error && error.message.includes('Network mismatch')) {
         throw error; // Re-throw our validation error
       }
       // For other errors (e.g., network issues), log warning but continue
       // This allows initialization to proceed even if network check fails temporarily
-      console.warn(
-        `BlockchainRuntime: Could not verify network chainId. ` +
-        `Error: ${error instanceof Error ? error.message : String(error)}. ` +
-        `Proceeding with expected chainId ${this.networkConfig.chainId}.`
-      );
+      sdkLogger.warn('Could not verify network chainId, proceeding with expected value', {
+        error: error instanceof Error ? error.message : String(error),
+        expectedChainId: this.networkConfig.chainId,
+      });
     }
 
     // SECURITY FIX (H-4): Use factory pattern to guarantee domain initialization
@@ -254,10 +252,7 @@ export class BlockchainRuntime implements IACTPRuntime {
         this.attestationTracker
       );
     } else if (this.requireAttestation) {
-      console.warn(
-        '[SECURITY WARNING] BlockchainRuntime: requireAttestation is true but no EAS config provided. ' +
-        'Attestation verification will fail. Please provide easConfig in BlockchainRuntimeConfig.'
-      );
+      sdkLogger.warn('requireAttestation is true but no EAS config provided - attestation verification will fail');
     }
   }
 
@@ -319,11 +314,12 @@ export class BlockchainRuntime implements IACTPRuntime {
           this.reconnectAttempts = attempt + 1;
           const delay = this.baseReconnectDelay * Math.pow(2, attempt);
 
-          console.warn(
-            `Provider connection lost. Attempting reconnection ${attempt + 1}/${this.maxReconnectAttempts} ` +
-            `after ${delay}ms delay... ` +
-            `(Error: ${error instanceof Error ? error.message : String(error)})`
-          );
+          sdkLogger.warn('Provider connection lost, attempting reconnection', {
+            attempt: attempt + 1,
+            maxAttempts: this.maxReconnectAttempts,
+            delayMs: delay,
+            error: error instanceof Error ? error.message : String(error),
+          });
 
           // Wait before next attempt
           await new Promise(resolve => setTimeout(resolve, delay));
@@ -399,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;
@@ -543,7 +541,11 @@ export class BlockchainRuntime implements IACTPRuntime {
         escrowId: tx.escrowId,
         createdAt: Number(tx.createdAt),
         updatedAt: Number(tx.updatedAt),
-        completedAt: 0, // V2: Track via DELIVERED event timestamp
+        // LIMITATION (V2): completedAt requires event indexing to fetch DELIVERED event timestamp.
+        // Currently 0, which means SDK-side dispute window check in releaseEscrow() is bypassed.
+        // On-chain contract still enforces dispute window correctly via _validateSettlementConditions().
+        // V2 will implement EventMonitor to track this properly.
+        completedAt: 0,
         serviceDescription: '', // V2: Decode from on-chain serviceHash
         deliveryProof: '', // V2: Fetch from EAS attestation
         events: [], // V2: Populate via EventMonitor.getTransactionEvents()
@@ -562,9 +564,7 @@ export class BlockchainRuntime implements IACTPRuntime {
   async getAllTransactions(): Promise<MockTransaction[]> {
     // V2: Implement event-based transaction indexing via EventMonitor
     // For now, return empty array as this requires off-chain indexer
-    console.warn(
-      'getAllTransactions() not fully implemented for BlockchainRuntime. Use EventMonitor for event-based queries.'
-    );
+    sdkLogger.warn('getAllTransactions() not implemented - use EventMonitor for event-based queries');
     return [];
   }
 
@@ -604,10 +604,7 @@ export class BlockchainRuntime implements IACTPRuntime {
     if (legacyMatch) {
       // Legacy SDK format - extract txId
       txId = legacyMatch[1];
-      console.warn(
-        `BlockchainRuntime.releaseEscrow: Using legacy escrowId format. ` +
-        `Please update to use txId directly as escrowId.`
-      );
+      sdkLogger.warn('Using legacy escrowId format - please update to use txId directly as escrowId');
     } else {
       // Standard: escrowId = txId
       txId = escrowId;
@@ -658,9 +655,7 @@ export class BlockchainRuntime implements IACTPRuntime {
       // Verify attestation is valid for this transaction
       try {
         await this.easHelper.verifyAndRecordForRelease(txId, attestationUID);
-        console.info(
-          `BlockchainRuntime.releaseEscrow: Attestation ${attestationUID} verified for transaction ${txId}.`
-        );
+        sdkLogger.info('Attestation verified for release', { txId, attestationUID });
       } catch (error) {
         throw new Error(
           `Cannot release escrow: attestation verification failed for transaction ${txId}. ` +
@@ -671,21 +666,16 @@ export class BlockchainRuntime implements IACTPRuntime {
       // Even if not required, verify attestation if provided (best effort)
       try {
         await this.easHelper.verifyAndRecordForRelease(txId, attestationUID);
-        console.info(
-          `BlockchainRuntime.releaseEscrow: Attestation ${attestationUID} verified (optional) for transaction ${txId}.`
-        );
+        sdkLogger.info('Attestation verified (optional)', { txId, attestationUID });
       } catch (error) {
-        console.warn(
-          `BlockchainRuntime.releaseEscrow: Attestation verification failed but not required. ` +
-          `Proceeding with release. Error: ${error instanceof Error ? error.message : String(error)}`
-        );
+        sdkLogger.warn('Attestation verification failed but not required, proceeding', {
+          txId,
+          error: error instanceof Error ? error.message : String(error),
+        });
       }
     } else {
       // No attestation verification
-      console.info(
-        `BlockchainRuntime.releaseEscrow: Settling transaction ${txId}. ` +
-        `Note: Set requireAttestation=true and provide easConfig for additional security.`
-      );
+      sdkLogger.info('Settling transaction without attestation verification', { txId });
     }
 
     // SECURITY FIX (SETTLEMENT-FLOW): Use transitionState(SETTLED) instead of releaseEscrow()
@@ -731,7 +721,7 @@ export class BlockchainRuntime implements IACTPRuntime {
       return '0';
     } catch (error) {
       // If query fails, return 0
-      console.warn('BlockchainRuntime.getEscrowBalance: Query failed', error);
+      sdkLogger.warn('getEscrowBalance query failed', { error: error instanceof Error ? error.message : String(error) });
       return '0';
     }
   }
@@ -773,6 +763,16 @@ export class BlockchainRuntime implements IACTPRuntime {
     return this.networkConfig;
   }
 
+  /**
+   * Maximum transaction amount in USDC (human-readable).
+   *
+   * SECURITY: Limits exposure on unaudited mainnet contracts.
+   * Returns undefined if no limit (testnet).
+   */
+  get maxTransactionAmount(): number | undefined {
+    return this.networkConfig.maxTransactionAmount;
+  }
+
   /**
    * Get ACTPKernel instance (for advanced usage)
    */
@@ -869,11 +869,7 @@ export class BlockchainRuntime implements IACTPRuntime {
 
     // SECURITY FIX (CRITICAL): If it's a raw string (legacy format), hash it
     // This ensures on-chain compatibility with the contract's bytes32 expectation
-    console.warn(
-      'BlockchainRuntime: serviceDescription is not a valid bytes32 hash. ' +
-      'Hashing it now. For best practice, use ServiceHash.hash() before calling createTransaction.'
-    );
-
+    sdkLogger.warn('serviceDescription is not a valid bytes32 hash - hashing now (use ServiceHash.hash() for best practice)');
     return keccak256(toUtf8Bytes(serviceDescription));
   }
 

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;
 }
 
 /**
@@ -199,6 +205,22 @@ export interface IACTPRuntime {
     /** Get current timestamp in seconds */
     now(): number;
   };
+
+  /**
+   * Maximum transaction amount in USDC (human-readable, e.g., 100 = $100).
+   *
+   * SECURITY: Limits exposure on unaudited contracts.
+   * Returns undefined if no limit is enforced (testnet/mock mode).
+   *
+   * @example
+   * ```typescript
+   * const limit = runtime.maxTransactionAmount;
+   * if (limit && amount > limit) {
+   *   throw new Error(`Amount exceeds limit of $${limit}`);
+   * }
+   * ```
+   */
+  maxTransactionAmount?: number;
 }
 
 /**

package/src/runtime/MockRuntime.ts

@@ -199,23 +199,27 @@ export class DisputeWindowActiveError extends Error {
 /**
  * Valid state transitions for the ACTP 8-state machine.
  *
+ * AUDIT FIX (2026-02): Synced with on-chain ACTPKernel contract.
+ *
  * State machine:
  * - INITIATED -> QUOTED (optional), COMMITTED, CANCELLED
  * - QUOTED -> COMMITTED, CANCELLED
- * - COMMITTED -> IN_PROGRESS (optional), DELIVERED, CANCELLED
+ * - COMMITTED -> IN_PROGRESS, CANCELLED (cannot skip to DELIVERED)
  * - IN_PROGRESS -> DELIVERED, CANCELLED
  * - DELIVERED -> SETTLED, DISPUTED
- * - DISPUTED -> SETTLED
+ * - DISPUTED -> SETTLED, CANCELLED (admin/pauser emergency)
  * - SETTLED (terminal)
  * - CANCELLED (terminal)
  */
 const VALID_TRANSITIONS: Record<TransactionState, TransactionState[]> = {
   INITIATED: ['QUOTED', 'COMMITTED', 'CANCELLED'],
   QUOTED: ['COMMITTED', 'CANCELLED'],
-  COMMITTED: ['IN_PROGRESS', 'DELIVERED', 'CANCELLED'],
+  // AUDIT FIX: Cannot skip IN_PROGRESS - must transition through it
+  COMMITTED: ['IN_PROGRESS', 'CANCELLED'],
   IN_PROGRESS: ['DELIVERED', 'CANCELLED'],
   DELIVERED: ['SETTLED', 'DISPUTED'],
-  DISPUTED: ['SETTLED'],
+  // AUDIT FIX: DISPUTED can also be CANCELLED by admin/pauser
+  DISPUTED: ['SETTLED', 'CANCELLED'],
   SETTLED: [], // Terminal state
   CANCELLED: [], // Terminal state
 };
@@ -337,6 +341,14 @@ export class MockRuntime implements IACTPRuntime {
     };
   }
 
+  /**
+   * Maximum transaction amount - no limit in mock mode.
+   *
+   * Mock mode is for testing, so we don't enforce limits.
+   * Real blockchain runtimes may have limits for security.
+   */
+  readonly maxTransactionAmount: number | undefined = undefined;
+
   /**
    * Load events from persisted state file.
    *
@@ -439,6 +451,7 @@ export class MockRuntime implements IACTPRuntime {
         serviceDescription: params.serviceDescription ?? '',
         deliveryProof: null,
         events: [],
+        agentId: params.agentId,
       };
 
       // Record event
@@ -452,6 +465,7 @@ export class MockRuntime implements IACTPRuntime {
           provider: params.provider,
           amount: params.amount,
           deadline: params.deadline,
+          agentId: params.agentId,
         },
       };
 
@@ -468,14 +482,54 @@ export class MockRuntime implements IACTPRuntime {
   /**
    * Gets a transaction by ID.
    *
+   * AUTO-RELEASE: If transaction is DELIVERED and dispute window has passed,
+   * automatically settles the transaction (lazy auto-release).
+   *
    * @param txId - Transaction ID
    * @returns Promise resolving to the transaction or null if not found
    */
   async getTransaction(txId: string): Promise<MockTransaction | null> {
+    // First, check if auto-settle is needed
+    await this.autoSettleIfReady(txId);
+    
+    // Then return the (possibly updated) transaction
     const state = this.stateManager.loadState();
     return state.transactions[txId] ?? null;
   }
 
+  /**
+   * Auto-settle a transaction if dispute window has passed.
+   *
+   * This implements "lazy auto-release" - when anyone checks a transaction
+   * that is DELIVERED with expired dispute window, it automatically settles.
+   *
+   * @param txId - Transaction ID to check
+   */
+  private async autoSettleIfReady(txId: string): Promise<void> {
+    const state = this.stateManager.loadState();
+    const tx = state.transactions[txId];
+    
+    if (!tx) return;
+    if (tx.state !== 'DELIVERED') return;
+    if (tx.completedAt === null) return;
+    
+    const currentTime = state.blockchain.currentTime;
+    const disputeWindowEnd = tx.completedAt + tx.disputeWindow;
+    
+    // Dispute window still active - don't auto-settle
+    if (currentTime < disputeWindowEnd) return;
+    
+    // Dispute window passed - auto-settle!
+    // Find the escrow and release it
+    if (tx.escrowId) {
+      try {
+        await this.releaseEscrow(tx.escrowId);
+      } catch {
+        // Already settled or other issue - ignore
+      }
+    }
+  }
+
   /**
    * Gets all transactions.
    *

package/src/runtime/types/MockState.ts

@@ -14,10 +14,13 @@
  * ACTP Transaction State enum matching the smart contract states.
  *
  * State machine:
- * - INITIATED (0) -> QUOTED (1, optional) -> COMMITTED (2) -> IN_PROGRESS (3, optional)
+ * - INITIATED (0) -> QUOTED (1, optional) -> COMMITTED (2) -> IN_PROGRESS (3, mandatory)
  *                 -> DELIVERED (4) -> SETTLED (5)
- * - Dispute path: DELIVERED -> DISPUTED (6) -> SETTLED
+ * - Dispute path: DELIVERED -> DISPUTED (6) -> SETTLED or CANCELLED (admin)
  * - Cancel path: Any pre-DELIVERED state -> CANCELLED (7)
+ *
+ * AUDIT FIX (2026-02): IN_PROGRESS is now mandatory per contract. Direct
+ * COMMITTED -> DELIVERED transitions are rejected on-chain.
  */
 export type TransactionState =
   | 'INITIATED'
@@ -111,6 +114,13 @@ export interface MockTransaction {
 
   /** List of events emitted during transaction lifecycle */
   events: MockEvent[];
+
+  /**
+   * ERC-8004 agent ID (optional).
+   * If set, can be used for reputation reporting after settlement.
+   * Stored as string representation of uint256.
+   */
+  agentId?: string;
 }
 
 /**