@agirails/sdk 2.0.0 → 2.0.1-beta

package/src/protocol/EscrowVault.ts

@@ -20,19 +20,15 @@ interface GasOptions {
 /**
  * EscrowVault - Escrow contract wrapper
  *
- * IMPORTANT:
- * - Escrow creation happens atomically inside `ACTPKernel.linkEscrow()`.
- * - Payout/refund functions are `onlyKernel` on-chain and MUST NOT be called by users.
- *
- * This module provides:
- * - Helper methods for USDC approvals (requester → EscrowVault allowance)
- * - Read-only access to escrow state (`escrows()` / `remaining()`)
+ * IMPORTANT: Per AIP-3 specification, escrow creation happens atomically
+ * inside ACTPKernel.linkEscrow(). This module provides read-only access
+ * to escrow state and helper methods for USDC approvals.
  *
  * Workflow (per AIP-3):
  * 1. Consumer approves USDC to EscrowVault address (use approveToken)
  * 2. Consumer calls ACTPKernel.linkEscrow(txId, escrowVault, escrowId)
- * 3. Kernel internally calls IEscrowValidator.createEscrow(escrowId, requester, provider, amount)
- * 4. Escrow pulls USDC from requester
+ * 3. Kernel internally calls EscrowVault.createEscrow() (onlyKernel modifier)
+ * 4. Escrow pulls USDC from consumer and auto-transitions to COMMITTED
  *
  * Reference: AIP-3 §3.2 (Escrow Linking Workflow), lines 258-336
  */
@@ -56,6 +52,7 @@ export class EscrowVault {
    */
   private getGasBufferMultiplier(operation: string): number {
     const buffers: Record<string, number> = {
+      'releaseEscrow': 1.30,     // 30% - Multi-recipient disbursement
       'approveToken': 1.20       // 20% - Standard ERC20 approval
     };
 
@@ -65,35 +62,12 @@ export class EscrowVault {
   /**
    * Build transaction options with gas settings and estimated gas
    * V6 Enhancement: Dynamic buffer based on operation type
-   *
-   * SECURITY FIX (NEW-C-1): Gas estimation manipulation attack protection
-   * - Enforces minimum gas floor regardless of estimate
-   * - Uses safe BigInt arithmetic with overflow detection
    */
   private buildTxOptions(estimatedGas: bigint, operation: string = 'default'): any {
-    // SECURITY FIX (NEW-C-1): Minimum gas floor to prevent manipulation
-    // Malicious contracts could return artificially low gas estimates
-    const MIN_GAS_FLOOR = 100000n;
-    const safeEstimate = estimatedGas > MIN_GAS_FLOOR ? estimatedGas : MIN_GAS_FLOOR;
-
     const bufferMultiplier = this.getGasBufferMultiplier(operation);
 
-    // SECURITY FIX (NEW-H-1): Safe BigInt arithmetic with overflow check
-    // Use 10000 denominator to avoid floating point precision issues
-    const bufferNumerator = BigInt(Math.floor(bufferMultiplier * 10000));
-    const bufferDenominator = 10000n;
-    const gasLimit = (safeEstimate * bufferNumerator) / bufferDenominator;
-
-    // Overflow detection: result should always be >= original estimate
-    if (gasLimit < safeEstimate) {
-      throw new Error(
-        `Gas calculation overflow detected for operation ${operation}. ` +
-        `Estimate: ${safeEstimate}, Buffer: ${bufferMultiplier}x, Result: ${gasLimit}`
-      );
-    }
-
     const options: any = {
-      gasLimit
+      gasLimit: (estimatedGas * BigInt(Math.round(bufferMultiplier * 100))) / 100n
     };
 
     if (this.gasSettings?.maxFeePerGas) {
@@ -113,18 +87,6 @@ export class EscrowVault {
     return this.address;
   }
 
-  /**
-   * Get the underlying ethers Contract instance.
-   *
-   * SECURITY FIX (C-3): Provides public access to contract for EventMonitor
-   * instead of accessing private field via bracket notation.
-   *
-   * @returns ethers Contract instance
-   */
-  getContract(): Contract {
-    return this.contract;
-  }
-
   /**
    * Approve USDC token for escrow creation
    *
@@ -189,48 +151,68 @@ export class EscrowVault {
    * Get escrow details
    */
   async getEscrow(escrowId: string): Promise<Escrow> {
-    validateTxId(escrowId, 'escrowId');
     const escrowData = await this.contract.escrows(escrowId);
 
     return {
       escrowId,
-      requester: escrowData.requester,
-      provider: escrowData.provider,
+      kernel: escrowData.kernel,
+      txId: escrowData.txId,
+      token: escrowData.token,
       amount: escrowData.amount,
-      releasedAmount: escrowData.releasedAmount,
-      active: escrowData.active
+      beneficiary: escrowData.beneficiary,
+      createdAt: 0, // Not exposed in minimal ABI
+      released: escrowData.released
     };
   }
 
   /**
-   * Get escrow remaining balance (amount - releasedAmount)
+   * Get escrow balance
    */
   async getEscrowBalance(escrowId: string): Promise<bigint> {
-    validateTxId(escrowId, 'escrowId');
-    return await this.contract.remaining(escrowId);
+    const escrow = await this.getEscrow(escrowId);
+    return escrow.amount;
   }
 
   /**
-   * @deprecated
-   *
-   * Payouts/refunds are executed by ACTPKernel (on-chain) as part of state transitions.
-   * EscrowVault disbursement methods are `onlyKernel` and cannot be called by EOAs.
-   *
-   * Use:
-   * - `BlockchainRuntime.releaseEscrow(txId, attestationUID?)` (recommended)
-   * - or `ACTPKernel.transitionState(txId, State.SETTLED, proof)` (advanced)
+   * Release escrow to recipients
+   * Note: Only callable by authorized kernel
    */
   async releaseEscrow(
     escrowId: string,
-    _recipients: string[],
-    _amounts: bigint[]
+    recipients: string[],
+    amounts: bigint[]
   ): Promise<void> {
+    // Input validation
     validateTxId(escrowId, 'escrowId');
-    throw new ValidationError(
-      'EscrowVault.releaseEscrow',
-      'Escrow payouts are performed by ACTPKernel (onlyKernel). ' +
-        'Use BlockchainRuntime.releaseEscrow(txId, attestationUID?) or ACTPKernel.transitionState(txId, SETTLED).'
-    );
+
+    if (recipients.length !== amounts.length) {
+      throw new ValidationError('recipients/amounts', 'Recipients and amounts length mismatch');
+    }
+
+    if (recipients.length === 0) {
+      throw new ValidationError('recipients', 'Must provide at least one recipient');
+    }
+
+    // Validate each recipient and amount
+    recipients.forEach((recipient, i) => {
+      validateAddress(recipient, `recipients[${i}]`);
+      validateAmount(amounts[i], `amounts[${i}]`);
+    });
+
+    try {
+      // ethers v6: use getFunction()
+      const disburseFunc = this.contract.getFunction('disburse');
+
+      // Estimate gas with safety buffer (30% for multi-recipient disbursement)
+      const estimatedGas = await disburseFunc.estimateGas(escrowId, recipients, amounts);
+      const txOptions = this.buildTxOptions(estimatedGas, 'releaseEscrow');
+
+      const tx = await disburseFunc(escrowId, recipients, amounts, txOptions);
+
+      await tx.wait();
+    } catch (error: any) {
+      throw new TransactionRevertedError(error.transactionHash, error.reason || error.message);
+    }
   }
 
   /**

package/src/protocol/EventMonitor.ts

@@ -3,12 +3,6 @@ import { State, Transaction } from '../types';
 
 /**
  * EventMonitor - Listen to blockchain events
- *
- * 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)
- *
- * Previous code had requester/provider swapped which caused wrong filter results.
  */
 export class EventMonitor {
   constructor(
@@ -61,29 +55,18 @@ export class EventMonitor {
 
   /**
    * Get all transactions for an address
-   *
-   * SECURITY FIX (EVENT-MONITOR): Corrected filter parameter order.
-   * Per ACTPKernel.json ABI, TransactionCreated event signature is:
-   *   (bytes32 indexed transactionId, address indexed requester, address indexed provider, uint256 amount, bytes32 serviceHash)
-   *
-   * Filter order: TransactionCreated(txId, requester, provider)
-   * - To filter by requester: (null, address, null)
-   * - To filter by provider: (null, null, address)
-   *
-   * SECURITY FIX (EVENT-MONITOR): Use getTransaction() instead of transactions()
-   * The kernel contract exposes getTransaction(bytes32) not transactions(bytes32).
+   * Fixed: Correct filter parameters (txId, provider, requester, amount)
    */
   async getTransactionHistory(
     address: string,
     role: 'requester' | 'provider' = 'requester'
   ): Promise<Transaction[]> {
-    // TransactionCreated event signature per ABI:
-    // (bytes32 indexed transactionId, address indexed requester, address indexed provider, uint256 amount, bytes32 serviceHash)
-    // Filter format: TransactionCreated(txId, requester, provider)
+    // TransactionCreated event signature: (bytes32 indexed txId, address indexed provider, address indexed requester, uint256 amount)
+    // Filter format: TransactionCreated(txId, provider, requester)
     const filter =
       role === 'requester'
-        ? this.kernelContract.filters.TransactionCreated(null, address, null) // Match requester (2nd indexed param)
-        : this.kernelContract.filters.TransactionCreated(null, null, address); // Match provider (3rd indexed param)
+        ? this.kernelContract.filters.TransactionCreated(null, null, address) // Match requester
+        : this.kernelContract.filters.TransactionCreated(null, address, null); // Match provider
 
     const events = await this.kernelContract.queryFilter(filter);
 
@@ -94,28 +77,20 @@ export class EventMonitor {
           throw new Error('Event does not contain args (not an EventLog)');
         }
         const txId = (event as EventLog).args?.transactionId;
-
-        // SECURITY FIX: Use getTransaction() - the actual ABI function
-        // Previous code called transactions(txId) which doesn't exist in ABI
-        const txData = await this.kernelContract.getTransaction(txId);
+        const txData = await this.kernelContract.transactions(txId);
 
         return {
-          txId: txData.transactionId || txId,
+          txId: txData.transactionId,
           requester: txData.requester,
           provider: txData.provider,
           amount: txData.amount,
-          state: (typeof txData.state === 'bigint' ? Number(txData.state) : txData.state) as State,
+          state: txData.state as State,
           createdAt: Number(txData.createdAt),
-          updatedAt: Number(txData.updatedAt),
           deadline: Number(txData.deadline),
           disputeWindow: Number(txData.disputeWindow),
           escrowContract: txData.escrowContract,
           escrowId: txData.escrowId,
-          serviceHash: txData.serviceHash,
-          attestationUID: txData.attestationUID,
-          // Use metadata field (quote hash for QUOTED state) if available, fallback to serviceHash
-          metadata: txData.metadata || txData.serviceHash,
-          platformFeeBpsLocked: Number(txData.platformFeeBpsLocked)
+          metadata: txData.serviceHash
         };
       })
     );
@@ -123,25 +98,21 @@ export class EventMonitor {
 
   /**
    * Subscribe to transaction creation events
-   *
-   * SECURITY FIX (EVENT-MONITOR): Corrected event parameter order.
-   * Per ACTPKernel.json ABI:
-   *   TransactionCreated(bytes32 indexed transactionId, address indexed requester, address indexed provider, uint256 amount, bytes32 serviceHash)
+   * Fixed: Correct event parameter order (txId, provider, requester, amount)
    */
   onTransactionCreated(
-    callback: (tx: { txId: string; requester: string; provider: string; amount: bigint; serviceHash?: string }) => void
+    callback: (tx: { txId: string; provider: string; requester: string; amount: bigint }) => void
   ): () => void {
     const filter = this.kernelContract.filters.TransactionCreated();
 
-    // Event signature per ABI: (txId, requester, provider, amount, serviceHash)
+    // Event signature: TransactionCreated(bytes32 indexed txId, address indexed provider, address indexed requester, uint256 amount)
     const listener = async (
       txId: string,
-      requester: string,
       provider: string,
-      amount: bigint,
-      serviceHash?: string
+      requester: string,
+      amount: bigint
     ) => {
-      callback({ txId, requester, provider, amount, serviceHash });
+      callback({ txId, provider, requester, amount });
     };
 
     this.kernelContract.on(filter, listener);

package/src/protocol/MessageSigner.ts

@@ -32,79 +32,15 @@ interface SignerWithTypedData extends Signer {
  * Reference: Yellow Paper §11.4.2
  *
  * V4 Security Enhancement: Optional nonce replay protection via ReceivedNonceTracker
- *
- * IMPORTANT: Use MessageSigner.create() factory method to ensure domain is initialized.
  */
 export class MessageSigner {
   private domain: EIP712Domain | null = null;
 
-  /**
-   * SECURITY FIX (H-5): Private constructor - MUST use MessageSigner.create() factory method
-   *
-   * This ensures EIP-712 domain is ALWAYS initialized before use (prevents race conditions).
-   * Direct construction would allow calling sign/verify without domain initialization.
-   */
-  private constructor(
+  constructor(
     private readonly signer: Signer,
     private readonly nonceTracker?: IReceivedNonceTracker
   ) {}
 
-  /**
-   * SECURITY FIX (H-4): Factory method to create MessageSigner with guaranteed domain initialization
-   *
-   * This factory ensures the EIP-712 domain is always properly initialized before use.
-   * Prevents the common bug of calling sign/verify without initializing domain first.
-   *
-   * @param signer - Ethers signer for signing messages
-   * @param kernelAddress - Address of ACTP Kernel contract (for domain separation)
-   * @param options - Optional configuration (chainId, nonceTracker)
-   * @returns Promise resolving to initialized MessageSigner
-   *
-   * @example
-   * ```typescript
-   * const messageSigner = await MessageSigner.create(
-   *   signer,
-   *   KERNEL_ADDRESS,
-   *   { chainId: 84532 }
-   * );
-   * const signature = await messageSigner.signMessage(message);
-   * ```
-   */
-  static async create(
-    signer: Signer,
-    kernelAddress: string,
-    options?: {
-      chainId?: number;
-      nonceTracker?: IReceivedNonceTracker;
-    }
-  ): Promise<MessageSigner> {
-    const messageSigner = new MessageSigner(signer, options?.nonceTracker);
-    await messageSigner.initDomain(kernelAddress, options?.chainId);
-    return messageSigner;
-  }
-
-  /**
-   * Check if domain is initialized
-   * @returns true if domain has been initialized
-   */
-  isDomainInitialized(): boolean {
-    return this.domain !== null;
-  }
-
-  /**
-   * Get the current domain (throws if not initialized)
-   * @returns Current EIP-712 domain
-   * @throws Error if domain not initialized
-   */
-  getDomain(): EIP712Domain {
-    if (!this.domain) {
-      throw new Error(
-        'Domain not initialized. Use MessageSigner.create() factory or call initDomain() first.'
-      );
-    }
-    return this.domain;
-  }
-
   /**
    * Initialize EIP-712 domain (must be called before signing)
    * @param kernelAddress - Address of ACTP Kernel contract
@@ -131,10 +67,8 @@ export class MessageSigner {
       }
     }
 
-    // SECURITY FIX (H-6): Standardize domain name to 'AGIRAILS' for brand consistency
-    // Note: This change requires coordination with any existing signed messages
     this.domain = {
-      name: 'AGIRAILS',
+      name: 'ACTP',
       version: '1.0',
       chainId: resolvedChainId,
       verifyingContract: kernelAddress
@@ -144,55 +78,17 @@ export class MessageSigner {
   /**
    * Sign ACTP message using EIP-712 typed data
    * Uses ECDSA (secp256k1) with domain separation per Yellow Paper §11.4.2
-   *
-   * SECURITY FIX (H-3): Validates nonce format and warns about sequential nonces
-   *
+   * 
    * Generic ACTPMessage format (backward compatible).
    * For strict typed AIP messages, use signQuoteRequest/signQuoteResponse/signDeliveryProof
    */
   async signMessage(message: ACTPMessage): Promise<string> {
     if (!this.domain) {
-      throw new Error(
-        'Domain not initialized. Use MessageSigner.create() factory or call initDomain() first.'
-      );
+      throw new Error('Domain not initialized. Call initDomain() first.');
     }
 
     const { type, version, from, to, timestamp, nonce, signature, ...payload } = message;
 
-    // SECURITY FIX (H-3): Validate nonce format (must be bytes32)
-    if (!nonce || !/^0x[a-fA-F0-9]{64}$/.test(nonce)) {
-      throw new Error(
-        `Invalid nonce format: "${nonce}". ` +
-        `Nonce MUST be a bytes32 hex string (0x + 64 hex chars). ` +
-        `Use SecureNonce.generateSecureNonce() to generate cryptographically secure nonces. ` +
-        `Never use sequential integers (1, 2, 3...) or timestamps as nonces.`
-      );
-    }
-
-    // SECURITY FIX (H-3): Warn about sequential nonces (low entropy)
-    // Sequential nonces like 0x0000...0001, 0x0000...0002 are weak
-    // Check if nonce has low entropy (e.g., last 8 bytes are zero, or all same digits)
-    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.`
-      );
-    }
-
-    // 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.`
-      );
-    }
-
     // Generic ACTPMessage with payload encoding (backward compatible)
     const abiCoder = AbiCoder.defaultAbiCoder();
     const payloadBytes = abiCoder.encode(
@@ -225,9 +121,7 @@ export class MessageSigner {
    */
   async signQuoteRequest(data: QuoteRequestData): Promise<string> {
     if (!this.domain) {
-      throw new Error(
-        'Domain not initialized. Use MessageSigner.create() factory or call initDomain() first.'
-      );
+      throw new Error('Domain not initialized. Call initDomain() first.');
     }
 
     const messageTypes = getMessageTypes('quote.request');
@@ -240,9 +134,7 @@ export class MessageSigner {
    */
   async signQuoteResponse(data: QuoteResponseData): Promise<string> {
     if (!this.domain) {
-      throw new Error(
-        'Domain not initialized. Use MessageSigner.create() factory or call initDomain() first.'
-      );
+      throw new Error('Domain not initialized. Call initDomain() first.');
     }
 
     const messageTypes = getMessageTypes('quote.response');
@@ -255,9 +147,7 @@ export class MessageSigner {
    */
   async signDeliveryProof(data: DeliveryProofData): Promise<string> {
     if (!this.domain) {
-      throw new Error(
-        'Domain not initialized. Use MessageSigner.create() factory or call initDomain() first.'
-      );
+      throw new Error('Domain not initialized. Call initDomain() first.');
     }
 
     const messageTypes = getMessageTypes('delivery.proof');
@@ -281,9 +171,7 @@ export class MessageSigner {
    */
   async verifySignature(message: ACTPMessage, signature: string): Promise<boolean> {
     if (!this.domain) {
-      throw new Error(
-        'Domain not initialized. Use MessageSigner.create() factory or call initDomain() first.'
-      );
+      throw new Error('Domain not initialized. Call initDomain() first.');
     }
 
     const { type, version, from, to, timestamp, nonce, signature: _, ...payload } = message;
@@ -420,97 +308,29 @@ export class MessageSigner {
 
   /**
    * Convert DID to Ethereum address
-   *
-   * SECURITY FIX (DID-FORMAT): Handles both DID formats:
-   * - Legacy: did:ethr:<address>
-   * - Canonical (EIP-3770): did:ethr:<chainId>:<address>
-   *
-   * Examples:
-   * - "did:ethr:0x1234...abcd" → "0x1234...abcd"
-   * - "did:ethr:84532:0x1234...abcd" → "0x1234...abcd"
-   * - "0x1234...abcd" → "0x1234...abcd" (raw address passthrough)
+   * MVP: Simple did:ethr → address conversion
    */
   private didToAddress(did: string): string {
-    // Check for DID format first
-    const DID_PREFIX = 'did:ethr:';
-    if (did.startsWith(DID_PREFIX)) {
-      const remainder = did.slice(DID_PREFIX.length);
-
-      // Check if it's canonical format: did:ethr:<chainId>:<address>
-      // chainId is numeric, address starts with 0x
-      const parts = remainder.split(':');
-
-      if (parts.length === 2) {
-        // Canonical format: did:ethr:<chainId>:<address>
-        const [chainIdStr, address] = parts;
-        const chainId = parseInt(chainIdStr, 10);
-
-        if (isNaN(chainId)) {
-          throw new Error(
-            `Invalid DID format: ${did}. ` +
-            `Expected did:ethr:<chainId>:<address> but chainId "${chainIdStr}" is not a number.`
-          );
-        }
-
-        if (!ethers.isAddress(address)) {
-          throw new Error(
-            `Invalid DID format: ${did}. ` +
-            `Expected did:ethr:<chainId>:<address> but "${address}" is not a valid Ethereum address.`
-          );
-        }
-
-        // SECURITY: Optionally validate chainId matches domain chainId
-        // 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}`
-          );
-        }
-
-        return address;
-      } else if (parts.length === 1 && ethers.isAddress(parts[0])) {
-        // Legacy format: did:ethr:<address>
-        return parts[0];
-      } else {
-        throw new Error(
-          `Invalid DID format: ${did}. ` +
-          `Expected did:ethr:<address> or did:ethr:<chainId>:<address>.`
-        );
-      }
+    if (did.startsWith('did:ethr:')) {
+      return did.replace('did:ethr:', '');
     }
 
-    // If already an address (raw 0x format), return as-is
+    // If already an address, return as-is
     if (ethers.isAddress(did)) {
       return did;
     }
 
-    throw new Error(
-      `Invalid DID format: ${did}. ` +
-      `Expected Ethereum address (0x...) or DID (did:ethr:...).`
-    );
+    throw new Error(`Invalid DID format: ${did}`);
   }
 
   /**
    * Convert Ethereum address to DID
-   *
-   * SECURITY FIX (DID-FORMAT): Now generates canonical DID format
-   * with chainId when domain is initialized: did:ethr:<chainId>:<address>
-   *
-   * Falls back to legacy format if domain not initialized.
    */
   addressToDID(address: string): string {
     if (!ethers.isAddress(address)) {
       throw new Error(`Invalid Ethereum address: ${address}`);
     }
 
-    // Use canonical format with chainId if domain is initialized
-    if (this.domain && this.domain.chainId) {
-      return `did:ethr:${this.domain.chainId}:${address}`;
-    }
-
-    // Fallback to legacy format (backward compatible)
     return `did:ethr:${address}`;
   }
 }