@agirails/sdk 2.0.3 → 2.2.0

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/level0/request.ts

@@ -164,7 +164,6 @@ export async function request(
 
     let tx = await client.runtime.getTransaction(txId);
     let attempts = 0;
-    let timedOut = false;
 
     while (tx && tx.state !== 'DELIVERED' && tx.state !== 'SETTLED' && attempts < maxAttempts) {
       // Check for terminal states that indicate failure
@@ -190,7 +189,7 @@ export async function request(
 
     // Check if we got a result
     if (!tx || (tx.state !== 'DELIVERED' && tx.state !== 'SETTLED')) {
-      timedOut = true;
+      const _timedOut = true; // Flag for potential future use
 
       // SECURITY FIX (H-3): Auto-cancel transaction on timeout if still in early state
       // This prevents funds from being locked indefinitely if provider never responds

package/src/level1/Agent.ts

@@ -14,10 +14,10 @@ import * as fs from 'fs';
 import { ethers } from 'ethers';
 import { ACTPClient } from '../ACTPClient';
 import { Job, JobHandler, JobContext } from './types/Job';
-import { ProvideOptions, RequestOptions, RequestResult, NetworkOption } from './types/Options';
+import { RequestOptions, RequestResult, NetworkOption } from './types/Options';
 import { PricingStrategy } from './pricing/PricingStrategy';
 import { AgentLifecycleError, ServiceConfigError, ValidationError } from '../errors';
-import { validateServiceName, validatePath, isValidAddress, LRUCache } from '../utils/security';
+import { validateServiceName, validatePath, LRUCache } from '../utils/security';
 import { Logger } from '../utils/Logger';
 import { ServiceHash } from '../utils/Helpers';
 import { Semaphore } from '../utils/Semaphore';
@@ -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

package/src/level1/pricing/PriceCalculator.ts

@@ -214,7 +214,7 @@ function estimateUnits(job: Job, unit: string): number {
  *
  * @internal
  */
-function estimateApiCost(api: string, job: Job): number {
+function estimateApiCost(_api: string, _job: Job): number {
   // MVP: Returns 0 (API costs tracked externally by agent)
   // V2: Integrate with OpenAI/Anthropic pricing APIs
 

package/src/level1/types/Options.ts

@@ -4,7 +4,7 @@
  * @packageDocumentation
  */
 
-import { JobHandler, Job } from './Job';
+import { Job } from './Job';
 
 /**
  * Wallet configuration options

package/src/protocol/ACTPKernel.ts

@@ -681,16 +681,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
 
@@ -157,7 +158,7 @@ export class MessageSigner {
       );
     }
 
-    const { type, version, from, to, timestamp, nonce, signature, ...payload } = message;
+    const { type, version, from, to, timestamp, nonce, signature: _sig, ...payload } = message;
 
     // SECURITY FIX (H-3): Validate nonce format (must be bytes32)
     if (!nonce || !/^0x[a-fA-F0-9]{64}$/.test(nonce)) {
@@ -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/protocol/ProofGenerator.ts

@@ -230,6 +230,7 @@ export class ProofGenerator {
           throw new Error('Response body is not readable');
         }
 
+        // eslint-disable-next-line no-constant-condition
         while (true) {
           const { done, value } = await reader.read();
 

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));
@@ -543,7 +539,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 +562,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 +602,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 +653,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 +664,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 +719,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 +761,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 +867,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));
   }
 
@@ -892,7 +886,7 @@ export class BlockchainRuntime implements IACTPRuntime {
    * @param params - Transaction parameters
    * @returns Estimated gas limit and cost in wei
    */
-  async estimateCreateTransactionGas(params: CreateTransactionParams): Promise<{
+  async estimateCreateTransactionGas(_params: CreateTransactionParams): Promise<{
     gasLimit: bigint;
     gasCostWei: bigint;
     gasCostGwei: string;
@@ -921,7 +915,7 @@ export class BlockchainRuntime implements IACTPRuntime {
    * @param txId - Transaction ID
    * @returns Estimated gas limit and cost
    */
-  async estimateLinkEscrowGas(txId: string): Promise<{
+  async estimateLinkEscrowGas(_txId: string): Promise<{
     gasLimit: bigint;
     gasCostWei: bigint;
     gasCostGwei: string;
@@ -949,7 +943,7 @@ export class BlockchainRuntime implements IACTPRuntime {
    * @param newState - Target state
    * @returns Estimated gas limit and cost
    */
-  async estimateTransitionGas(txId: string, newState: string): Promise<{
+  async estimateTransitionGas(_txId: string, _newState: string): Promise<{
     gasLimit: bigint;
     gasCostWei: bigint;
     gasCostGwei: string;

package/src/runtime/IACTPRuntime.ts

@@ -199,6 +199,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

@@ -25,8 +25,6 @@ import {
   MockEscrow,
   MockEvent,
   TransactionState,
-  TransactionStateValue,
-  MOCK_STATE_DEFAULTS,
 } from './types/MockState';
 import { IACTPRuntime, CreateTransactionParams } from './IACTPRuntime';
 
@@ -201,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
 };
@@ -339,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.
    *

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'