@agirails/sdk 2.2.3 → 2.3.1

package/src/level0/request.ts

@@ -14,6 +14,7 @@ import { NoProviderFoundError, TimeoutError, ValidationError } from '../errors';
 import { safeJSONParse, validateServiceName, isValidAddress } from '../utils/security';
 import { Logger } from '../utils/Logger';
 import { ethers } from 'ethers';
+import { resolvePrivateKey } from '../wallet/keystore';
 
 /**
  * Request a service
@@ -61,7 +62,6 @@ export async function request(
   service: string,
   options: RequestOptions
 ): Promise<RequestResult> {
-  // SECURITY FIX (H-2): Validate service name to prevent injection
   const validatedService = validateServiceName(service);
 
   const logger = new Logger({ source: 'request' });
@@ -75,12 +75,8 @@ export async function request(
     });
   }
 
-  // SECURITY FIX (RPCURL): Use rpcUrl from options or fallback to network default
-  // This allows Level0 request() to work with testnet/mainnet without requiring
-  // explicit rpcUrl if user is okay with public RPC endpoints.
   let rpcUrl = options.rpcUrl;
   if (!rpcUrl && (options.network === 'testnet' || options.network === 'mainnet')) {
-    // Import getNetwork to get default rpcUrl from network config
     const { getNetwork } = await import('../config/networks');
     const networkName = options.network === 'testnet' ? 'base-sepolia' : 'base-mainnet';
     const networkConfig = getNetwork(networkName);
@@ -88,27 +84,27 @@ export async function request(
     logger.info(`Using default RPC URL for ${networkName}: ${rpcUrl}`);
   }
 
-  // Create ACTP client
+  const resolvedKey = await resolveKeyIfNeeded(options.wallet, options.network, options.stateDirectory);
+  const resolvedAddress = resolvedKey
+    ? new ethers.Wallet(resolvedKey).address.toLowerCase()
+    : undefined;
+
   const client = await ACTPClient.create({
     mode: options.network === 'testnet' ? 'testnet' : options.network === 'mainnet' ? 'mainnet' : 'mock',
-    requesterAddress: getRequesterAddress(options.wallet),
+    requesterAddress: resolvedAddress || getRequesterAddress(options.wallet),
     stateDirectory: options.stateDirectory,
-    privateKey: getPrivateKey(options.wallet),
+    privateKey: resolvedKey || getPrivateKey(options.wallet),
     rpcUrl,
   });
 
-  // Calculate deadline
   const deadline = calculateDeadline(options.deadline, options.timeout);
-
-  // Create transaction with service metadata
   const startTime = Date.now();
 
   try {
-    const requesterAddress = getRequesterAddress(options.wallet);
+    const requesterAddress = resolvedAddress || getRequesterAddress(options.wallet);
     const amountWei = (options.budget * 1_000_000).toString(); // Convert to USDC wei (6 decimals)
 
     // In mock mode, ensure requester has enough funds
-    // This is a convenience feature for testing - won't exist in production
     if (client.runtime && 'mintTokens' in client.runtime) {
       const mockRuntime = client.runtime as any;
       const balance = await mockRuntime.getBalance(requesterAddress);
@@ -122,30 +118,19 @@ export async function request(
       }
     }
 
-    // ARCHITECTURE FIX: Service metadata handling
-    // - MockRuntime: Store plaintext for provider matching and input extraction
-    // - BlockchainRuntime: Hashes plaintext internally before sending on-chain
-    //
-    // Provider needs plaintext to:
-    // 1. Match service name to handler (findServiceHandler)
-    // 2. Extract input data for job execution (extractJobInput)
-    //
-    // On-chain storage uses bytes32 hash (BlockchainRuntime.validateServiceHash handles this)
     const serviceMetadata = JSON.stringify({
       service: validatedService,
       input: options.input,
       timestamp: Date.now(),
     });
 
-    // Create transaction with structured metadata
-    // MockRuntime stores as-is, BlockchainRuntime hashes for on-chain
     const txId = await client.runtime.createTransaction({
       provider,
       requester: requesterAddress,
       amount: amountWei,
       deadline,
-      disputeWindow: options.disputeWindow ?? 172800, // Default 2 days
-      serviceDescription: serviceMetadata, // Structured JSON for provider parsing
+      disputeWindow: options.disputeWindow ?? 172800,
+      serviceDescription: serviceMetadata,
     });
 
     // Call onProgress if provided
@@ -187,12 +172,8 @@ export async function request(
       attempts++;
     }
 
-    // Check if we got a result
     if (!tx || (tx.state !== 'DELIVERED' && tx.state !== 'SETTLED')) {
-      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
+      // Auto-cancel on timeout if still in early state
       if (tx && (tx.state === 'INITIATED' || tx.state === 'COMMITTED')) {
         try {
           logger.warn('Transaction timed out, cancelling to release funds', {
@@ -200,8 +181,6 @@ export async function request(
             state: tx.state,
           });
 
-          // ACTUALLY CANCEL THE TRANSACTION
-          // Check if runtime has cancelTransaction method
           if ('cancelTransaction' in client.runtime) {
             await (client.runtime as any).cancelTransaction(txId);
             logger.info('Transaction cancelled successfully', { txId });
@@ -211,7 +190,6 @@ export async function request(
             (error as any).wasCancelled = true;
             throw error;
           } else {
-            // Fallback: Transition to CANCELLED state
             await client.runtime.transitionState(txId, 'CANCELLED');
             logger.info('Transaction cancelled successfully (via transitionState)', { txId });
 
@@ -222,7 +200,6 @@ export async function request(
           }
         } catch (cancelError) {
           logger.error('Failed to cancel timed-out transaction', { txId }, cancelError as Error);
-          // Continue with original timeout error
         }
       }
 
@@ -232,13 +209,8 @@ export async function request(
       throw error;
     }
 
-    // SECURITY FIX (C-3): Safe JSON parsing with schema validation
-    // Extract result from delivery proof
     let deliveredResult: any = {};
     if (tx.deliveryProof) {
-      // Define expected schema for delivery proof
-      // NOTE: 'type' field with value 'delivery.proof' is the unique wrapper marker
-      // (set by ProofGenerator.generateDeliveryProof) that handlers won't naturally return
       const DELIVERY_PROOF_SCHEMA: Record<string, string> = {
         result: 'any',
         data: 'any',
@@ -247,28 +219,18 @@ export async function request(
         timestamp: 'number',
         contentHash: 'string',
         txId: 'string',
-        type: 'string',  // Unique marker: 'delivery.proof'
+        type: 'string',
       };
 
-      // Use safeJSONParse with schema validation which:
-      // 1. Validates JSON structure
-      // 2. Removes __proto__, constructor, prototype properties
-      // 3. Prevents prototype pollution attacks
-      // 4. Validates against expected schema
-      // 5. Checks size limits to prevent DoS
-      // 6. Returns null if parsing fails
       const parsed = safeJSONParse(tx.deliveryProof, DELIVERY_PROOF_SCHEMA);
 
       if (parsed !== null) {
         deliveredResult = parsed;
       } else {
-        // If parsing failed, treat as plain text (but don't execute or eval)
         deliveredResult = { data: tx.deliveryProof };
         logger.warn('Failed to parse delivery proof as JSON', { txId });
       }
     } else if (options.network === 'testnet' || options.network === 'mainnet') {
-      // KNOWN LIMITATION: BlockchainRuntime doesn't fetch deliveryProof from IPFS yet
-      // Result will be empty until this is implemented
       logger.warn(
         'Delivery proof retrieval not yet implemented for testnet/mainnet. ' +
         'Result may be empty. Use ACTPClient with manual proof handling for production.',
@@ -276,17 +238,11 @@ export async function request(
       );
     }
 
-    // SECURITY FIX (CRITICAL-2): Release escrow only after proper validation
-    // For mock mode, auto-release is safe. For testnet/mainnet, require attestation.
     if (tx.state === 'DELIVERED' && tx.escrowId) {
-      // Wait for dispute window to expire
       const disputeWindowEnd = (tx.completedAt ?? 0) + tx.disputeWindow;
       const currentTime = client.runtime.time.now();
 
       if (currentTime >= disputeWindowEnd) {
-        // SECURITY FIX (CRITICAL-2): Only auto-release in mock mode
-        // For real networks, the requester should manually verify and release
-        // or use attestation-based verification
         const isMockMode = options.network !== 'testnet' && options.network !== 'mainnet';
 
         if (isMockMode) {
@@ -353,6 +309,20 @@ export async function request(
   }
 }
 
+/**
+ * Resolve private key from keystore if wallet is auto/undefined and network is testnet/mainnet.
+ * Returns undefined if wallet is explicitly set (caller should use getPrivateKey instead).
+ */
+async function resolveKeyIfNeeded(
+  wallet?: 'auto' | 'connect' | string | { privateKey: string },
+  network?: string,
+  stateDirectory?: string
+): Promise<string | undefined> {
+  if (wallet && wallet !== 'auto') return undefined; // explicit wallet, skip auto-detect
+  if (network !== 'testnet' && network !== 'mainnet') return undefined;
+  return resolvePrivateKey(stateDirectory);
+}
+
 /**
  * Find provider for service
  *
@@ -381,23 +351,10 @@ function findProvider(
   return providers[0];
 }
 
-/**
- * Get requester address from wallet option
- *
- * SECURITY FIX (HIGH): Properly derive addresses from private keys using ethers
- * Never fabricate addresses or use partial key slices as addresses.
- *
- * @param wallet - Wallet configuration
- * @returns Ethereum address
- * @throws {ValidationError} If address format is invalid
- */
 function getRequesterAddress(
   wallet?: 'auto' | 'connect' | string | { privateKey: string }
 ): string {
-  // For mock mode only: generate deterministic address
-  // This is only safe because mock mode doesn't involve real funds
   if (!wallet || wallet === 'auto') {
-    // Create a valid Ethereum address (40 hex chars) - ONLY for mock mode
     const hex = Buffer.from('requester').toString('hex');
     return '0x' + hex.padEnd(40, '0');
   }
@@ -407,15 +364,12 @@ function getRequesterAddress(
   }
 
   if (typeof wallet === 'string') {
-    // SECURITY FIX (HIGH): Validate address format
     if (!isValidAddress(wallet)) {
       throw new ValidationError('wallet', `Invalid Ethereum address format: ${wallet}`);
     }
     return wallet.toLowerCase();
   }
 
-  // SECURITY FIX (HIGH): Derive address from private key using ethers
-  // This is the correct way to get address from a private key
   try {
     const walletInstance = new ethers.Wallet(wallet.privateKey);
     return walletInstance.address.toLowerCase();
@@ -424,15 +378,6 @@ function getRequesterAddress(
   }
 }
 
-/**
- * Get private key from wallet option
- *
- * SECURITY FIX (HIGH): Validate private key format before use
- *
- * @param wallet - Wallet configuration
- * @returns Private key or undefined
- * @throws {ValidationError} If private key format is invalid
- */
 function getPrivateKey(
   wallet?: 'auto' | 'connect' | string | { privateKey: string }
 ): string | undefined {
@@ -440,12 +385,8 @@ function getPrivateKey(
     return undefined;
   }
 
-  // If wallet is a string that looks like a private key (0x + 64 hex chars), use it
-  // Otherwise treat it as an address and return undefined
   if (typeof wallet === 'string') {
-    // Check if it looks like a private key (0x + 64 hex chars)
     if (/^0x[0-9a-fA-F]{64}$/.test(wallet)) {
-      // Validate by trying to create a wallet
       try {
         new ethers.Wallet(wallet);
         return wallet;
@@ -453,11 +394,9 @@ function getPrivateKey(
         throw new ValidationError('wallet', 'Invalid private key format');
       }
     }
-    // It's an address, not a private key
     return undefined;
   }
 
-  // Validate private key format
   if (wallet.privateKey) {
     try {
       new ethers.Wallet(wallet.privateKey);

package/src/level1/Agent.ts

@@ -13,12 +13,13 @@ import * as os from 'os';
 import * as fs from 'fs';
 import { ethers } from 'ethers';
 import { ACTPClient } from '../ACTPClient';
+import { resolvePrivateKey } from '../wallet/keystore';
 import { Job, JobHandler, JobContext } from './types/Job';
 import { RequestOptions, RequestResult, NetworkOption } from './types/Options';
 import { PricingStrategy } from './pricing/PricingStrategy';
 import { AgentLifecycleError, ServiceConfigError, ValidationError } from '../errors';
 import { validateServiceName, validatePath, LRUCache } from '../utils/security';
-import { Logger } from '../utils/Logger';
+import { Logger, sdkLogger } from '../utils/Logger';
 import { ServiceHash } from '../utils/Helpers';
 import { Semaphore } from '../utils/Semaphore';
 import { ProofGenerator } from '../protocol/ProofGenerator';
@@ -386,12 +387,8 @@ export class Agent extends EventEmitter {
     this.emit('starting');
 
     try {
-      // SECURITY FIX (RPCURL): Use rpcUrl from config or fallback to network default
-      // This allows Agent to work with testnet/mainnet without requiring explicit rpcUrl
-      // if user is okay with public RPC endpoints.
       let rpcUrl = this.config.rpcUrl;
       if (!rpcUrl && (this.network === 'testnet' || this.network === 'mainnet')) {
-        // Import getNetwork to get default rpcUrl from network config
         const { getNetwork } = await import('../config/networks');
         const networkName = this.network === 'testnet' ? 'base-sepolia' : 'base-mainnet';
         const networkConfig = getNetwork(networkName);
@@ -399,16 +396,14 @@ export class Agent extends EventEmitter {
         this.logger.info(`Using default RPC URL for ${networkName}: ${rpcUrl}`);
       }
 
-      // Initialize ACTP client
       this._client = await ACTPClient.create({
         mode: this.network === 'testnet' ? 'testnet' : this.network === 'mainnet' ? 'mainnet' : 'mock',
-        requesterAddress: this.address || this.generateAddress(),
+        requesterAddress: this.address || await this.generateAddress(),
         stateDirectory: this.config.stateDirectory,
-        privateKey: this.getPrivateKey(),
+        privateKey: await this.getPrivateKey(),
         rpcUrl,
       });
 
-      // Start polling for jobs
       this.startPolling();
 
       this._status = 'running';
@@ -1316,21 +1311,21 @@ export class Agent extends EventEmitter {
       log: {
         debug: (message: string, meta?: any) => {
           if (agent.config.logging?.level === 'debug') {
-            console.debug(`[${job.id}] ${message}`, meta);
+            sdkLogger.debug(`[${job.id}] ${message}`, meta);
           }
         },
         info: (message: string, meta?: any) => {
           if (['debug', 'info'].includes(agent.config.logging?.level || 'info')) {
-            console.info(`[${job.id}] ${message}`, meta);
+            sdkLogger.info(`[${job.id}] ${message}`, meta);
           }
         },
         warn: (message: string, meta?: any) => {
           if (['debug', 'info', 'warn'].includes(agent.config.logging?.level || 'info')) {
-            console.warn(`[${job.id}] ${message}`, meta);
+            sdkLogger.warn(`[${job.id}] ${message}`, meta);
           }
         },
         error: (message: string, meta?: any) => {
-          console.error(`[${job.id}] ${message}`, meta);
+          sdkLogger.error(`[${job.id}] ${message}`, meta);
         },
       },
 
@@ -1371,15 +1366,8 @@ export class Agent extends EventEmitter {
     }
   }
 
-  /**
-   * Generate address based on wallet configuration
-   *
-   * SECURITY FIX (HIGH): For testnet/mainnet, MUST derive from private key.
-   * For mock mode, can use deterministic address for convenience.
-   */
-  private generateAddress(): string {
-    // If wallet has private key, ALWAYS derive address from it
-    const privateKey = this.getPrivateKey();
+  private async generateAddress(): Promise<string> {
+    const privateKey = await this.getPrivateKey();
     if (privateKey) {
       try {
         const wallet = new ethers.Wallet(privateKey);
@@ -1389,33 +1377,31 @@ export class Agent extends EventEmitter {
       }
     }
 
-    // For non-mock networks, require a valid private key or address
     if (this.network === 'testnet' || this.network === 'mainnet') {
       throw new ValidationError(
         'wallet',
-        `${this.network} mode requires a valid private key or address in wallet configuration`
+        `${this.network} mode requires a valid private key or address in wallet configuration.\n` +
+        'Run "actp init" to generate a keystore, or set ACTP_PRIVATE_KEY env var.'
       );
     }
 
-    // For mock mode only: generate deterministic address from agent name
-    // This is safe because mock mode doesn't involve real funds
     return `0x${Buffer.from(this.name).toString('hex').padEnd(40, '0').slice(0, 40)}`;
   }
 
-  /**
-   * Get private key from configuration
-   *
-   * SECURITY FIX (HIGH): Validate private key format before use
-   */
-  private getPrivateKey(): string | undefined {
-    if (!this.config.wallet || this.config.wallet === 'auto' || this.config.wallet === 'connect') {
+  private async getPrivateKey(): Promise<string | undefined> {
+    if (!this.config.wallet || this.config.wallet === 'auto') {
+      if (this.network === 'testnet' || this.network === 'mainnet') {
+        return resolvePrivateKey(this.config.stateDirectory);
+      }
+      return undefined;
+    }
+
+    if (this.config.wallet === 'connect') {
       return undefined;
     }
 
     if (typeof this.config.wallet === 'string') {
-      // Check if it looks like a private key (0x + 64 hex chars)
       if (/^0x[0-9a-fA-F]{64}$/.test(this.config.wallet)) {
-        // Validate by trying to create a wallet
         try {
           new ethers.Wallet(this.config.wallet);
           return this.config.wallet;
@@ -1423,11 +1409,9 @@ export class Agent extends EventEmitter {
           throw new ValidationError('wallet', 'Invalid private key format');
         }
       }
-      // It's an address, not a private key
       return undefined;
     }
 
-    // Validate private key format
     if (this.config.wallet.privateKey) {
       try {
         new ethers.Wallet(this.config.wallet.privateKey);

package/src/protocol/ACTPKernel.ts

@@ -37,14 +37,25 @@ interface GasOptions {
 export class ACTPKernel {
   private contract: Contract;
   private readonly gasSettings?: GasOptions;
+  /**
+   * Number of block confirmations to wait after each state-changing tx.
+   * Default: 2 (Base L2 reorg safety — ~4-6 s on Base's 2 s blocks).
+   * Set to 1 for faster feedback on testnet; never set to 0 in production.
+   */
+  private readonly confirmations: number;
 
   constructor(
     private readonly address: string,
     signer: Signer,
-    gasSettings?: GasOptions
+    gasSettings?: GasOptions,
+    confirmations: number = 2
   ) {
+    if (confirmations < 1) {
+      throw new Error(`confirmations must be >= 1, got ${confirmations}`);
+    }
     this.contract = new Contract(address, ACTPKernelABI, signer);
     this.gasSettings = gasSettings;
+    this.confirmations = confirmations;
   }
 
   /**
@@ -213,7 +224,7 @@ export class ACTPKernel {
         txOptions
       );
 
-      const receipt = await tx.wait(2); // Wait for 2 confirmations (Base L2 reorg safety)
+      const receipt = await tx.wait(this.confirmations);
       if (!receipt) {
         throw new Error('Transaction receipt not available');
       }
@@ -280,7 +291,7 @@ export class ACTPKernel {
 
       const tx = await transitionFunc(txId, newState, proof, txOptions);
 
-      await tx.wait(2); // Wait for 2 confirmations (Base L2 reorg safety)
+      await tx.wait(this.confirmations);
     } catch (error: any) {
       throw new TransactionRevertedError(error.transactionHash, error.reason || error.message);
     }
@@ -400,8 +411,7 @@ export class ACTPKernel {
 
       const tx = await linkEscrowFunc(txId, escrowContract, escrowId, txOptions);
 
-      // Wait for 2 confirmations to ensure state is updated on RPC nodes (Base Sepolia reorg safety)
-      await tx.wait(2);
+      await tx.wait(this.confirmations);
     } catch (error: any) {
       throw new TransactionRevertedError(error.transactionHash, error.reason || error.message);
     }
@@ -437,7 +447,7 @@ export class ACTPKernel {
 
       const tx = await releaseMilestoneFunc(txId, amount, txOptions);
 
-      await tx.wait(2); // Wait for 2 confirmations (Base L2 reorg safety)
+      await tx.wait(this.confirmations);
     } catch (error: any) {
       throw new TransactionRevertedError(error.transactionHash, error.reason || error.message);
     }
@@ -521,7 +531,7 @@ export class ACTPKernel {
 
       const tx = await releaseEscrowFunc(txId, txOptions);
 
-      await tx.wait(2); // Wait for 2 confirmations (Base L2 reorg safety)
+      await tx.wait(this.confirmations);
     } catch (error: any) {
       throw new TransactionRevertedError(error.transactionHash, error.reason || error.message);
     }
@@ -669,7 +679,7 @@ export class ACTPKernel {
         txOptions
       );
 
-      await tx.wait(2); // Wait for 2 confirmations (Base L2 reorg safety)
+      await tx.wait(this.confirmations);
     } catch (error: any) {
       throw new TransactionRevertedError(error.transactionHash, error.reason || error.message);
     }
@@ -735,7 +745,7 @@ export class ACTPKernel {
         txOptions
       );
 
-      await tx.wait(2); // Wait for 2 confirmations (Base L2 reorg safety)
+      await tx.wait(this.confirmations);
     } catch (error: any) {
       throw new TransactionRevertedError(error.transactionHash, error.reason || error.message);
     }
@@ -789,7 +799,7 @@ export class ACTPKernel {
         txOptions
       );
 
-      await tx.wait(2); // Wait for 2 confirmations (Base L2 reorg safety)
+      await tx.wait(this.confirmations);
     } catch (error: any) {
       throw new TransactionRevertedError(error.transactionHash, error.reason || error.message);
     }

package/src/protocol/EventMonitor.ts

@@ -4,6 +4,20 @@ import { State, Transaction } from '../types';
 /**
  * EventMonitor - Listen to blockchain events
  *
+ * ## Confirmation Policy
+ *
+ * Events received by EventMonitor are already confirmed. ACTPKernel waits
+ * for N block confirmations (default 2, configurable via `confirmations`
+ * parameter in BlockchainRuntimeConfig) before returning from state-changing
+ * operations. On Base L2 (~2 s blocks), the default means events arrive
+ * ~4-6 s after submission and are safe from reorgs.
+ *
+ * Confirmation flow:
+ *   User calls ACTPKernel.createTransaction()
+ *     → tx.wait(confirmations) blocks until N confirmations
+ *     → Event emitted (already confirmed)
+ *     → EventMonitor receives event (instant)
+ *
  * SECURITY FIX (EVENT-MONITOR): Corrected event parameter order to match ABI.
  * Per ACTPKernel.json, TransactionCreated signature is:
  *   (bytes32 indexed transactionId, address indexed requester, address indexed provider, uint256 amount, bytes32 serviceHash)