@agirails/sdk 2.0.0-beta

package/src/protocol/EASHelper.ts

@@ -0,0 +1,197 @@
+import { Contract, Signer, AbiCoder, zeroPadValue } from 'ethers';
+import { DeliveryProof } from '../types';
+import { deliveryProofDataFromProof } from '../types/eip712';
+
+export interface EASConfig {
+  contractAddress: string;
+  deliveryProofSchemaId: string;
+}
+
+export interface AttestationResponse {
+  uid: string;
+  transactionHash: string;
+}
+
+/**
+ * EASHelper - utility wrapper for Ethereum Attestation Service interactions
+ */
+const EAS_ABI = [
+  'event Attested(address indexed attester, bytes32 indexed uid, bytes32 indexed schema)',
+  'function attest(tuple(bytes32 schema, tuple(address recipient, uint64 expirationTime, bool revocable, bytes32 refUID, bytes data) data) request) external returns (bytes32)',
+  'function revoke(tuple(bytes32 schema, bytes32 uid) request) external returns (bytes32)',
+  'function getAttestation(bytes32 uid) external view returns (tuple(bytes32 uid, bytes32 schema, address recipient, address attester, uint64 time, uint64 expirationTime, bool revocable, bytes32 refUID, bytes data, uint32 bump))'
+];
+
+export class EASHelper {
+  private readonly eas: Contract;
+
+  constructor(signer: Signer, private readonly config: EASConfig) {
+    this.eas = new Contract(config.contractAddress, EAS_ABI, signer);
+  }
+
+  /**
+   * Create an attestation for a delivery proof. Returns the attestation UID and transaction hash.
+   */
+  async attestDeliveryProof(
+    proof: DeliveryProof,
+    recipient: string,
+    options?: { expirationTime?: number; revocable?: boolean }
+  ): Promise<AttestationResponse> {
+    const { expirationTime = 0, revocable = true } = options || {};
+    const proofData = deliveryProofDataFromProof(proof);
+
+    const abiCoder = AbiCoder.defaultAbiCoder();
+    const encodedData = abiCoder.encode(
+      ['bytes32', 'bytes32', 'uint256', 'string', 'uint256', 'string'],
+      [
+        proofData.txId,
+        proofData.contentHash,
+        proofData.timestamp,
+        proofData.deliveryUrl || '',
+        proofData.size,
+        proofData.mimeType
+      ]
+    );
+
+    const tx = await this.eas.attest({
+      schema: this.config.deliveryProofSchemaId,
+      data: {
+        recipient,
+        expirationTime,
+        revocable,
+        refUID: proof.txId,
+        data: encodedData
+      }
+    });
+
+    const receipt = await tx.wait();
+    // ethers v6: events → logs, and logs are parsed differently
+    const attestedLog = receipt?.logs?.find((log: any) => {
+      try {
+        const parsed = this.eas.interface.parseLog(log);
+        return parsed?.name === 'Attested';
+      } catch {
+        return false;
+      }
+    });
+
+    const uid = attestedLog
+      ? this.eas.interface.parseLog(attestedLog)?.args?.uid
+      : zeroPadValue('0x00', 32);
+
+    return {
+      uid,
+      transactionHash: receipt.transactionHash
+    };
+  }
+
+  /**
+   * Revoke a previously issued attestation by UID.
+   */
+  async revokeAttestation(uid: string): Promise<string> {
+    const tx = await this.eas.revoke({
+      schema: this.config.deliveryProofSchemaId,
+      uid
+    });
+    const receipt = await tx.wait();
+    return receipt.transactionHash;
+  }
+
+  /**
+   * Fetch attestation data from the EAS contract.
+   */
+  async getAttestation(uid: string) {
+    return await this.eas.getAttestation(uid);
+  }
+
+  /**
+   * Verify that a delivery attestation belongs to the specified transaction.
+   *
+   * SECURITY: ACTPKernel V1 accepts any bytes32 as attestationUID without validation.
+   * This means a malicious provider could submit attestation from Transaction A
+   * for Transaction B. This method provides SDK-side protection by verifying:
+   *
+   * 1. Attestation exists and is not revoked
+   * 2. Attestation uses the canonical delivery schema UID
+   * 3. Attestation's txId matches the expected transaction ID
+   * 4. Attestation has not expired
+   *
+   * @param txId - Expected transaction ID (bytes32)
+   * @param attestationUID - Attestation UID to verify (bytes32)
+   * @returns true if attestation is valid for this transaction, false otherwise
+   * @throws Error if attestation is revoked, expired, schema mismatch, or txId mismatch
+   */
+  async verifyDeliveryAttestation(
+    txId: string,
+    attestationUID: string
+  ): Promise<boolean> {
+    // 1. Fetch attestation from EAS contract
+    const attestation = await this.eas.getAttestation(attestationUID);
+
+    // 2. Check if attestation exists (uid should match)
+    if (attestation.uid !== attestationUID) {
+      throw new Error(`Attestation not found: ${attestationUID}`);
+    }
+
+    // 3. Check schema UID matches canonical delivery schema (B2 blocker fix)
+    // This prevents accepting attestations from unrelated EAS schemas
+    if (attestation.schema !== this.config.deliveryProofSchemaId) {
+      throw new Error(
+        `Schema UID mismatch: expected canonical delivery schema ${this.config.deliveryProofSchemaId}, ` +
+        `got ${attestation.schema}. Attestation may be from a different schema!`
+      );
+    }
+
+    // 4. Check revocation - EAS uses revocationTime field (not revoked boolean)
+    // revocationTime = 0 means not revoked
+    // revocationTime > 0 means revoked at that timestamp
+    // NOTE: attestation.revoked field does NOT exist! (see genetic-memory.md)
+    const isRevoked = attestation.revocationTime > 0n;
+    if (isRevoked) {
+      throw new Error(
+        `Attestation has been revoked: ${attestationUID} (revoked at timestamp ${attestation.revocationTime})`
+      );
+    }
+
+    // 5. Check expiration
+    // expirationTime = 0 means no expiration
+    // expirationTime > 0 means expires at that timestamp
+    if (attestation.expirationTime > 0n) {
+      const now = Math.floor(Date.now() / 1000);
+      if (Number(attestation.expirationTime) < now) {
+        throw new Error(
+          `Attestation has expired: ${attestationUID} (expired at ${attestation.expirationTime})`
+        );
+      }
+    }
+
+    // 6. Decode attestation data to extract txId
+    // Schema: bytes32 txId, bytes32 contentHash, uint256 timestamp, string deliveryUrl, uint256 size, string mimeType
+    let attestedTxId: string;
+    try {
+      const abiCoder = AbiCoder.defaultAbiCoder();
+      const decoded = abiCoder.decode(
+        ['bytes32', 'bytes32', 'uint256', 'string', 'uint256', 'string'],
+        attestation.data
+      );
+      attestedTxId = decoded[0]; // First field is txId
+    } catch (error: any) {
+      throw new Error(
+        `Attestation data format mismatch: cannot decode attestation ${attestationUID}. ` +
+        `Expected AIP-4 delivery proof schema format. ` +
+        `Original error: ${error.message}`
+      );
+    }
+
+    // 7. Verify attestation txId matches expected transaction ID
+    if (attestedTxId !== txId) {
+      throw new Error(
+        `Attestation txId mismatch: expected ${txId}, got ${attestedTxId}. ` +
+        `Provider may be attempting to use attestation from different transaction!`
+      );
+    }
+
+    // All checks passed
+    return true;
+  }
+}

package/src/protocol/EscrowVault.ts

@@ -0,0 +1,237 @@
+import { Contract, Signer } from 'ethers';
+import EscrowVaultABI from '../abi/EscrowVault.json';
+import ERC20ABI from '../abi/ERC20.json';
+import { Escrow } from '../types';
+import { TransactionRevertedError, ValidationError } from '../errors';
+import {
+  validateAddress,
+  validateAmount,
+  validateTxId
+} from '../utils/validation';
+
+/**
+ * Gas options for transactions
+ */
+interface GasOptions {
+  maxFeePerGas?: bigint;
+  maxPriorityFeePerGas?: bigint;
+}
+
+/**
+ * EscrowVault - Escrow contract wrapper
+ *
+ * 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 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
+ */
+export class EscrowVault {
+  private contract: Contract;
+  private readonly gasSettings?: GasOptions;
+
+  constructor(
+    private readonly address: string,
+    private readonly signer: Signer,
+    gasSettings?: GasOptions
+  ) {
+    this.contract = new Contract(address, EscrowVaultABI, signer);
+    this.gasSettings = gasSettings;
+  }
+
+  /**
+   * Get gas buffer multiplier based on operation complexity
+   * V6 Security Enhancement: Operation-specific gas buffers
+   * Reference: SDK_SECURITY_ANALYSIS-Ultra-Think.md Lines 326-337
+   */
+  private getGasBufferMultiplier(operation: string): number {
+    const buffers: Record<string, number> = {
+      'releaseEscrow': 1.30,     // 30% - Multi-recipient disbursement
+      'approveToken': 1.20       // 20% - Standard ERC20 approval
+    };
+
+    return buffers[operation] || 1.20; // Default 20% for unknown operations
+  }
+
+  /**
+   * Build transaction options with gas settings and estimated gas
+   * V6 Enhancement: Dynamic buffer based on operation type
+   */
+  private buildTxOptions(estimatedGas: bigint, operation: string = 'default'): any {
+    const bufferMultiplier = this.getGasBufferMultiplier(operation);
+
+    const options: any = {
+      gasLimit: (estimatedGas * BigInt(Math.round(bufferMultiplier * 100))) / 100n
+    };
+
+    if (this.gasSettings?.maxFeePerGas) {
+      options.maxFeePerGas = this.gasSettings.maxFeePerGas;
+    }
+    if (this.gasSettings?.maxPriorityFeePerGas) {
+      options.maxPriorityFeePerGas = this.gasSettings.maxPriorityFeePerGas;
+    }
+
+    return options;
+  }
+
+  /**
+   * Get escrow vault address
+   */
+  getAddress(): string {
+    return this.address;
+  }
+
+  /**
+   * Approve USDC token for escrow creation
+   *
+   * IMPORTANT: Call this BEFORE ACTPKernel.linkEscrow()
+   * The consumer must approve EscrowVault to pull USDC when linkEscrow() is called
+   *
+   * @param tokenAddress - USDC contract address
+   * @param amount - Amount to approve (in USDC wei, 6 decimals)
+   * @throws {ValidationError} If inputs are invalid
+   * @throws {TransactionRevertedError} If approval fails
+   *
+   * @example
+   * ```typescript
+   * // Approve 100 USDC for escrow
+   * const amount = ethers.parseUnits('100', 6);
+   * await client.escrow.approveToken(BASE_SEPOLIA.contracts.usdc, amount);
+   *
+   * // Now call linkEscrow via Kernel
+   * const escrowId = ethers.id(`escrow-${Date.now()}`);
+   * await client.kernel.linkEscrow(txId, escrowVault, escrowId);
+   * ```
+   */
+  async approveToken(tokenAddress: string, amount: bigint): Promise<void> {
+    validateAddress(tokenAddress, 'tokenAddress');
+    validateAmount(amount, 'amount');
+
+    const tokenContract = new Contract(tokenAddress, ERC20ABI, this.signer);
+
+    try {
+      // Check current allowance
+      const currentAllowance = await tokenContract.allowance(
+        await this.signer.getAddress(),
+        this.address
+      );
+
+      // Only approve if needed
+      if (currentAllowance < amount) {
+        const approveFunc = tokenContract.getFunction('approve');
+
+        // USDC-compatible approval pattern:
+        // If any residual allowance exists, reset to zero first
+        if (currentAllowance > 0n) {
+          const resetGas = await approveFunc.estimateGas(this.address, 0);
+          const resetTx = await approveFunc(this.address, 0, this.buildTxOptions(resetGas, 'approveToken'));
+          await resetTx.wait();
+        }
+
+        // Now set the new allowance
+        const approveGas = await approveFunc.estimateGas(this.address, amount);
+        const approveTx = await approveFunc(this.address, amount, this.buildTxOptions(approveGas, 'approveToken'));
+        await approveTx.wait();
+      }
+    } catch (error: any) {
+      throw new TransactionRevertedError(
+        error.transactionHash,
+        `Token approval failed: ${error.reason || error.message}`
+      );
+    }
+  }
+
+  /**
+   * Get escrow details
+   */
+  async getEscrow(escrowId: string): Promise<Escrow> {
+    const escrowData = await this.contract.escrows(escrowId);
+
+    return {
+      escrowId,
+      kernel: escrowData.kernel,
+      txId: escrowData.txId,
+      token: escrowData.token,
+      amount: escrowData.amount,
+      beneficiary: escrowData.beneficiary,
+      createdAt: 0, // Not exposed in minimal ABI
+      released: escrowData.released
+    };
+  }
+
+  /**
+   * Get escrow balance
+   */
+  async getEscrowBalance(escrowId: string): Promise<bigint> {
+    const escrow = await this.getEscrow(escrowId);
+    return escrow.amount;
+  }
+
+  /**
+   * Release escrow to recipients
+   * Note: Only callable by authorized kernel
+   */
+  async releaseEscrow(
+    escrowId: string,
+    recipients: string[],
+    amounts: bigint[]
+  ): Promise<void> {
+    // Input validation
+    validateTxId(escrowId, 'escrowId');
+
+    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);
+    }
+  }
+
+  /**
+   * Check token balance
+   */
+  async getTokenBalance(tokenAddress: string, account: string): Promise<bigint> {
+    const tokenContract = new Contract(tokenAddress, ERC20ABI, this.signer);
+    return await tokenContract.balanceOf(account);
+  }
+
+  /**
+   * Check token allowance
+   */
+  async getTokenAllowance(
+    tokenAddress: string,
+    owner: string,
+    spender: string
+  ): Promise<bigint> {
+    const tokenContract = new Contract(tokenAddress, ERC20ABI, this.signer);
+    return await tokenContract.allowance(owner, spender);
+  }
+}

package/src/protocol/EventMonitor.ts

@@ -0,0 +1,161 @@
+import { Contract, EventLog } from 'ethers';
+import { State, Transaction } from '../types';
+
+/**
+ * EventMonitor - Listen to blockchain events
+ */
+export class EventMonitor {
+  constructor(
+    private readonly kernelContract: Contract,
+    _escrowContract: Contract
+  ) {}
+
+  /**
+   * Watch transaction state changes
+   * Returns cleanup function to stop watching
+   */
+  watchTransaction(txId: string, callback: (state: State) => void): () => void {
+    const filter = this.kernelContract.filters.StateTransitioned(txId);
+
+    const listener = (_eventTxId: string, _from: number, to: number) => {
+      callback(to as State);
+    };
+
+    this.kernelContract.on(filter, listener);
+
+    // Return cleanup function
+    return () => {
+      this.kernelContract.off(filter, listener);
+    };
+  }
+
+  /**
+   * Wait for specific state
+   */
+  async waitForState(
+    txId: string,
+    targetState: State,
+    timeoutMs: number = 60000
+  ): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        cleanup();
+        reject(new Error(`Timeout waiting for state ${State[targetState]}`));
+      }, timeoutMs);
+
+      const cleanup = this.watchTransaction(txId, (state) => {
+        if (state === targetState) {
+          clearTimeout(timer);
+          cleanup();
+          resolve();
+        }
+      });
+    });
+  }
+
+  /**
+   * Get all transactions for an address
+   * Fixed: Correct filter parameters (txId, provider, requester, amount)
+   */
+  async getTransactionHistory(
+    address: string,
+    role: 'requester' | 'provider' = 'requester'
+  ): Promise<Transaction[]> {
+    // 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, null, address) // Match requester
+        : this.kernelContract.filters.TransactionCreated(null, address, null); // Match provider
+
+    const events = await this.kernelContract.queryFilter(filter);
+
+    return Promise.all(
+      events.map(async (event) => {
+        // ethers v6: EventLog has args, Log does not
+        if (!('args' in event)) {
+          throw new Error('Event does not contain args (not an EventLog)');
+        }
+        const txId = (event as EventLog).args?.transactionId;
+        const txData = await this.kernelContract.transactions(txId);
+
+        return {
+          txId: txData.transactionId,
+          requester: txData.requester,
+          provider: txData.provider,
+          amount: txData.amount,
+          state: txData.state as State,
+          createdAt: Number(txData.createdAt),
+          deadline: Number(txData.deadline),
+          disputeWindow: Number(txData.disputeWindow),
+          escrowContract: txData.escrowContract,
+          escrowId: txData.escrowId,
+          metadata: txData.serviceHash
+        };
+      })
+    );
+  }
+
+  /**
+   * Subscribe to transaction creation events
+   * Fixed: Correct event parameter order (txId, provider, requester, amount)
+   */
+  onTransactionCreated(
+    callback: (tx: { txId: string; provider: string; requester: string; amount: bigint }) => void
+  ): () => void {
+    const filter = this.kernelContract.filters.TransactionCreated();
+
+    // Event signature: TransactionCreated(bytes32 indexed txId, address indexed provider, address indexed requester, uint256 amount)
+    const listener = async (
+      txId: string,
+      provider: string,
+      requester: string,
+      amount: bigint
+    ) => {
+      callback({ txId, provider, requester, amount });
+    };
+
+    this.kernelContract.on(filter, listener);
+
+    return () => {
+      this.kernelContract.off(filter, listener);
+    };
+  }
+
+  /**
+   * Subscribe to state change events
+   */
+  onStateChanged(
+    callback: (txId: string, from: State, to: State) => void
+  ): () => void {
+    const filter = this.kernelContract.filters.StateTransitioned();
+
+    const listener = (txId: string, from: number, to: number) => {
+      callback(txId, from as State, to as State);
+    };
+
+    this.kernelContract.on(filter, listener);
+
+    return () => {
+      this.kernelContract.off(filter, listener);
+    };
+  }
+
+  /**
+   * Subscribe to escrow release events
+   */
+  onEscrowReleased(callback: (txId: string, amount: bigint) => void): () => void {
+    const filter = this.kernelContract.filters.EscrowReleased();
+
+    const listener = (txId: string, amount: bigint) => {
+      callback(txId, amount);
+    };
+
+    this.kernelContract.on(filter, listener);
+
+    return () => {
+      this.kernelContract.off(filter, listener);
+    };
+  }
+}
+