@agirails/sdk 2.0.0-beta

package/src/protocol/ACTPKernel.ts

@@ -0,0 +1,625 @@
+import { Contract, Signer, BytesLike, ethers, AbiCoder } from 'ethers';
+import ACTPKernelABI from '../abi/ACTPKernel.json';
+import {
+  State,
+  StateMachine,
+  Transaction,
+  CreateTransactionParams,
+  DisputeResolution,
+  EconomicParams
+} from '../types';
+import {
+  TransactionNotFoundError,
+  TransactionRevertedError,
+  InvalidStateTransitionError,
+  ValidationError
+} from '../errors';
+import {
+  validateAddress,
+  validateAmount,
+  validateDeadline,
+  validateDisputeWindow,
+  validateTxId
+} from '../utils/validation';
+
+/**
+ * Gas options for transactions
+ */
+interface GasOptions {
+  maxFeePerGas?: bigint;
+  maxPriorityFeePerGas?: bigint;
+}
+
+/**
+ * ACTPKernel - Smart contract wrapper
+ * Reference: Yellow Paper §3 (ACTP Kernel Specification)
+ */
+export class ACTPKernel {
+  private contract: Contract;
+  private readonly gasSettings?: GasOptions;
+
+  constructor(
+    private readonly address: string,
+    signer: Signer,
+    gasSettings?: GasOptions
+  ) {
+    this.contract = new Contract(address, ACTPKernelABI, signer);
+    this.gasSettings = gasSettings;
+  }
+
+  /**
+   * Get kernel contract address
+   */
+  getAddress(): string {
+    return this.address;
+  }
+
+  /**
+   * 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> = {
+      'createTransaction': 1.15,  // 15% - Simple state initialization
+      'transitionState': 1.20,    // 20% - Standard state change
+      'releaseEscrow': 1.30,      // 30% - Multi-recipient disbursement
+      'raiseDispute': 1.25,       // 25% - Large proof data handling
+      'resolveDispute': 1.30,     // 30% - Complex multi-party settlement
+      'cancelTransaction': 1.15,  // 15% - Simple state change
+      'anchorAttestation': 1.15   // 15% - Simple attestation anchoring
+    };
+
+    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;
+  }
+
+  /**
+   * Create a new transaction
+   * Reference: Yellow Paper §3.4.1
+   *
+   * Contract signature: createTransaction(provider, requester, amount, deadline, disputeWindow, serviceHash)
+   * Returns: bytes32 transactionId (generated by contract)
+   */
+  async createTransaction(params: CreateTransactionParams): Promise<string> {
+    const {
+      provider,
+      requester,
+      amount,
+      deadline,
+      disputeWindow,
+      metadata = '0x0000000000000000000000000000000000000000000000000000000000000000'
+    } = params;
+
+    // Input validation
+    validateAddress(provider, 'provider');
+    validateAddress(requester, 'requester');
+    validateAmount(amount, 'amount');
+    validateDeadline(deadline, 'deadline');
+    validateDisputeWindow(disputeWindow, 'disputeWindow');
+
+    try {
+      // ethers v6: use getFunction() for typed access
+      const createTxFunc = this.contract.getFunction('createTransaction');
+
+      // Contract signature: createTransaction(provider, requester, amount, deadline, disputeWindow, serviceHash)
+      const estimatedGas = await createTxFunc.estimateGas(
+        provider,
+        requester,
+        amount,
+        deadline,
+        disputeWindow,
+        metadata  // serviceHash
+      );
+
+      // Build tx options with gas settings (15% buffer for simple state initialization)
+      const txOptions = this.buildTxOptions(estimatedGas, 'createTransaction');
+
+      // Per ABI: createTransaction returns transactionId directly
+      // Contract signature: function createTransaction(...) external returns (bytes32 transactionId)
+      const tx = await createTxFunc(
+        provider,
+        requester,
+        amount,
+        deadline,
+        disputeWindow,
+        metadata,  // serviceHash
+        txOptions
+      );
+
+      const receipt = await tx.wait(2); // Wait for 2 confirmations (Base L2 reorg safety)
+      if (!receipt) {
+        throw new Error('Transaction receipt not available');
+      }
+
+      // Extract transactionId from TransactionCreated event
+      // Event signature: TransactionCreated(bytes32 indexed transactionId, ...)
+      for (const log of receipt.logs) {
+        try {
+          const parsedLog = this.contract.interface.parseLog({
+            topics: [...log.topics],
+            data: log.data
+          });
+
+          if (parsedLog && parsedLog.name === 'TransactionCreated') {
+            return parsedLog.args.transactionId || parsedLog.args[0];
+          }
+        } catch (e) {
+          // Skip logs that don't match our interface
+          continue;
+        }
+      }
+
+      throw new Error('TransactionCreated event not found in receipt');
+    } catch (error: any) {
+      throw new TransactionRevertedError(error.transactionHash, error.reason || error.message);
+    }
+  }
+
+  /**
+   * Transition transaction state
+   * Reference: Yellow Paper §3.2
+   */
+  async transitionState(
+    txId: string,
+    newState: State,
+    proof: BytesLike = '0x'
+  ): Promise<void> {
+    // Input validation
+    validateTxId(txId, 'txId');
+
+    // Validate transition
+    const currentTx = await this.getTransaction(txId);
+    if (!StateMachine.isValidTransition(currentTx.state, newState)) {
+      const validStates = StateMachine.getNextValidStates(currentTx.state).map((s) =>
+        State[s]
+      );
+      throw new InvalidStateTransitionError(currentTx.state, newState, validStates);
+    }
+
+    try {
+      // ethers v6: use getFunction()
+      const transitionFunc = this.contract.getFunction('transitionState');
+
+      // Estimate gas with safety buffer (20% for standard state transitions)
+      const estimatedGas = await transitionFunc.estimateGas(txId, newState, proof);
+      const txOptions = this.buildTxOptions(estimatedGas, 'transitionState');
+
+      const tx = await transitionFunc(txId, newState, proof, txOptions);
+
+      await tx.wait(2); // Wait for 2 confirmations (Base L2 reorg safety)
+    } catch (error: any) {
+      throw new TransactionRevertedError(error.transactionHash, error.reason || error.message);
+    }
+  }
+
+  /**
+   * Submit quote for transaction (AIP-2)
+   * Reference: AIP-2 §4.1 (Provider workflow)
+   *
+   * Transitions transaction from INITIATED → QUOTED with quote hash stored on-chain
+   *
+   * @param txId - Transaction ID (bytes32)
+   * @param quoteHash - Keccak256 hash of canonical JSON quote message
+   */
+  async submitQuote(txId: string, quoteHash: string): Promise<void> {
+    // Input validation
+    validateTxId(txId, 'txId');
+
+    if (!/^0x[a-fA-F0-9]{64}$/.test(quoteHash)) {
+      throw new ValidationError('quoteHash', 'Must be valid bytes32 hex string');
+    }
+
+    if (quoteHash === '0x0000000000000000000000000000000000000000000000000000000000000000') {
+      throw new ValidationError('quoteHash', 'Cannot be zero hash');
+    }
+
+    // Validate current state is INITIATED
+    const currentTx = await this.getTransaction(txId);
+    if (currentTx.state !== State.INITIATED) {
+      throw new InvalidStateTransitionError(
+        currentTx.state,
+        State.QUOTED,
+        ['INITIATED']
+      );
+    }
+
+    // Encode quote hash as bytes proof
+    const abiCoder = AbiCoder.defaultAbiCoder();
+    const proof = abiCoder.encode(['bytes32'], [quoteHash]);
+
+    // Transition to QUOTED state with quote hash
+    await this.transitionState(txId, State.QUOTED, proof);
+  }
+
+  /**
+   * Link escrow to transaction
+   *
+   * CRITICAL: This is the ONLY way to create escrow per AIP-3 spec.
+   * SDK should NOT call EscrowVault.createEscrow() directly (onlyKernel modifier).
+   *
+   * What happens internally:
+   * 1. ACTPKernel validates transaction state, permissions, deadline
+   * 2. Kernel calls IEscrowValidator(escrowContract).createEscrow(...)
+   * 3. EscrowVault pulls USDC from consumer (must approve USDC first!)
+   * 4. Events emitted: EscrowLinked
+   * 5. **State transition behavior varies** (see below)
+   *
+   * STATE TRANSITION BEHAVIOR:
+   * - **AIP-3 Spec (Source Code)**: Should auto-transition INITIATED/QUOTED → COMMITTED
+   * - **Deployed Contract**: Behavior is INCONSISTENT - sometimes auto-transitions, sometimes doesn't
+   * - **Recommended Practice**: Always check state after linkEscrow() and manually transition if needed
+   *
+   * ```typescript
+   * await client.kernel.linkEscrow(txId, escrowVault, escrowId);
+   * let tx = await client.kernel.getTransaction(txId);
+   * if (tx.state !== State.COMMITTED) {
+   *   await client.kernel.transitionState(txId, State.COMMITTED);
+   * }
+   * ```
+   *
+   * Prerequisites:
+   * - Transaction in INITIATED or QUOTED state
+   * - Consumer has approved USDC to EscrowVault address
+   *   (use EscrowVault.approveToken() before calling this)
+   *
+   * @param txId - Transaction ID (bytes32)
+   * @param escrowContract - EscrowVault contract address
+   * @param escrowId - Unique escrow identifier (bytes32, consumer-generated)
+   * @throws {ValidationError} If inputs invalid
+   * @throws {TransactionRevertedError} If state invalid, deadline passed, or insufficient USDC
+   *
+   * @example
+   * ```typescript
+   * // Step 1: Approve USDC to EscrowVault (NOT to Kernel!)
+   * await client.escrow.approveToken(BASE_SEPOLIA.contracts.usdc, amount);
+   *
+   * // Step 2: Generate unique escrow ID
+   * const escrowId = ethers.id(`escrow-${Date.now()}`);
+   *
+   * // Step 3: Link escrow (creates escrow + auto-transitions to COMMITTED)
+   * await client.kernel.linkEscrow(txId, escrowVaultAddress, escrowId);
+   *
+   * // Step 4: Verify state is COMMITTED (auto-transitioned, no manual call needed)
+   * const tx = await client.kernel.getTransaction(txId);
+   * expect(tx.state).to.equal(State.COMMITTED);
+   * ```
+   *
+   * Reference: Yellow Paper §3.4.2, AIP-3 §3.2 (ACTPKernel.sol lines 244-276)
+   */
+  async linkEscrow(
+    txId: string,
+    escrowContract: string,
+    escrowId: string
+  ): Promise<void> {
+    // Input validation
+    validateTxId(txId, 'txId');
+    validateAddress(escrowContract, 'escrowContract');
+    validateTxId(escrowId, 'escrowId'); // escrowId is also bytes32
+
+    try {
+      // ethers v6: use getFunction()
+      const linkEscrowFunc = this.contract.getFunction('linkEscrow');
+
+      // Estimate gas with safety buffer (20% for linking escrow)
+      const estimatedGas = await linkEscrowFunc.estimateGas(txId, escrowContract, escrowId);
+      const txOptions = this.buildTxOptions(estimatedGas, 'transitionState');
+
+      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);
+    } catch (error: any) {
+      throw new TransactionRevertedError(error.transactionHash, error.reason || error.message);
+    }
+  }
+
+  /**
+   * Release milestone payment
+   */
+  async releaseMilestone(
+    txId: string,
+    milestoneId: number,
+    amount: bigint
+  ): Promise<void> {
+    // Input validation
+    validateTxId(txId, 'txId');
+    validateAmount(amount, 'amount');
+    if (milestoneId < 0) {
+      throw new ValidationError('milestoneId', 'Milestone ID cannot be negative');
+    }
+
+    try {
+      // ethers v6: use getFunction()
+      const releaseMilestoneFunc = this.contract.getFunction('releaseMilestone');
+
+      // Estimate gas with safety buffer (30% for escrow release operations)
+      const estimatedGas = await releaseMilestoneFunc.estimateGas(txId, milestoneId, amount);
+      const txOptions = this.buildTxOptions(estimatedGas, 'releaseEscrow');
+
+      const tx = await releaseMilestoneFunc(txId, milestoneId, amount, txOptions);
+
+      await tx.wait(2); // Wait for 2 confirmations (Base L2 reorg safety)
+    } catch (error: any) {
+      throw new TransactionRevertedError(error.transactionHash, error.reason || error.message);
+    }
+  }
+
+  /**
+   * Release full escrow (settle transaction)
+   *
+   * SECURITY WARNING (V1): ACTPKernel V1 contract accepts any attestationUID without validation.
+   * This means a malicious provider could submit attestation from different transaction.
+   *
+   * To protect against this, you can either:
+   * 1. Use ACTPClient's wrapper method that automatically verifies
+   * 2. Manually verify attestation before calling this method (see EASHelper.verifyDeliveryAttestation)
+   *
+   * Note: Attestation verification is OPTIONAL here because some transactions may not use EAS.
+   * However, for transactions with delivery proofs, consumers SHOULD verify before settling.
+   *
+   * @param txId - Transaction ID to settle
+   * @throws {ValidationError} If txId is invalid
+   * @throws {TransactionRevertedError} If contract reverts
+   */
+  async releaseEscrow(txId: string): Promise<void> {
+    // Input validation
+    validateTxId(txId, 'txId');
+
+    try {
+      // ethers v6: use getFunction()
+      const releaseEscrowFunc = this.contract.getFunction('releaseEscrow');
+
+      // Estimate gas with safety buffer (30% for escrow release operations)
+      const estimatedGas = await releaseEscrowFunc.estimateGas(txId);
+      const txOptions = this.buildTxOptions(estimatedGas, 'releaseEscrow');
+
+      const tx = await releaseEscrowFunc(txId, txOptions);
+
+      await tx.wait(2); // Wait for 2 confirmations (Base L2 reorg safety)
+    } catch (error: any) {
+      throw new TransactionRevertedError(error.transactionHash, error.reason || error.message);
+    }
+  }
+
+  /**
+   * Get transaction by ID
+   */
+  async getTransaction(txId: string): Promise<Transaction> {
+    const txData = await this.contract.getTransaction(txId);
+
+    // Check if transaction exists (createdAt !== 0)
+    if (txData.createdAt === 0 || txData.createdAt === 0n) {
+      throw new TransactionNotFoundError(txId);
+    }
+
+    return {
+      txId: txData.transactionId,
+      requester: txData.requester,
+      provider: txData.provider,
+      amount: txData.amount,
+      state: (typeof txData.state === 'bigint' ? Number(txData.state) : txData.state) as State,
+      createdAt: typeof txData.createdAt === 'bigint' ? Number(txData.createdAt) : txData.createdAt,
+      deadline: typeof txData.deadline === 'bigint' ? Number(txData.deadline) : txData.deadline,
+      disputeWindow: typeof txData.disputeWindow === 'bigint' ? Number(txData.disputeWindow) : txData.disputeWindow,
+      escrowContract: txData.escrowContract,
+      escrowId: txData.escrowId,
+      // Use metadata field (quote hash for QUOTED state) if available, fallback to serviceHash
+      metadata: txData.metadata || txData.serviceHash
+    };
+  }
+
+  /**
+   * Get economic parameters (fee structure)
+   * Fixed: Don't hardcode values, read from contract
+   */
+  async getEconomicParams(): Promise<EconomicParams> {
+    const params = await this.contract.getEconomicParams();
+
+    // Contract returns: (platformFeeBps, requesterPenaltyBps, feeRecipient)
+    return {
+      baseFeeNumerator: Number(params.platformFeeBps || params[0]),
+      baseFeeDenominator: 10000, // BPS is always out of 10000
+      feeRecipient: params.feeRecipient || params[2],
+      requesterPenaltyBps: Number(params.requesterPenaltyBps || params[1]),
+      providerPenaltyBps: 0 // Not in current contract ABI, will be added in future version
+    };
+  }
+
+  /**
+   * Estimate gas for transaction creation
+   */
+  async estimateCreateTransaction(params: CreateTransactionParams): Promise<bigint> {
+    const { provider, requester, amount, deadline, disputeWindow, metadata = '0x0000000000000000000000000000000000000000000000000000000000000000' } = params;
+
+    // ethers v6: use getFunction()
+    const createTxFunc = this.contract.getFunction('createTransaction');
+    return await createTxFunc.estimateGas(
+      provider,
+      requester,
+      amount,
+      deadline,
+      disputeWindow,
+      metadata
+    );
+  }
+
+  /**
+   * Raise dispute on delivered transaction
+   * Reference: Yellow Paper §3.4 (Dispute Management)
+   */
+  async raiseDispute(txId: string, reason: string, evidence: string): Promise<void> {
+    validateTxId(txId, 'txId');
+
+    // Encode dispute proof with reason and evidence (IPFS hash)
+    const abiCoder = AbiCoder.defaultAbiCoder();
+    const proofData = abiCoder.encode(
+      ['string', 'string'],
+      [reason, evidence]
+    );
+
+    try {
+      // ethers v6: use getFunction()
+      const transitionFunc = this.contract.getFunction('transitionState');
+
+      // Estimate gas with safety buffer (25% for large proof data)
+      const estimatedGas = await transitionFunc.estimateGas(
+        txId,
+        State.DISPUTED,
+        proofData
+      );
+
+      const txOptions = this.buildTxOptions(estimatedGas, 'raiseDispute');
+
+      const tx = await transitionFunc(
+        txId,
+        State.DISPUTED,
+        proofData,
+        txOptions
+      );
+
+      await tx.wait(2); // Wait for 2 confirmations (Base L2 reorg safety)
+    } catch (error: any) {
+      throw new TransactionRevertedError(error.transactionHash, error.reason || error.message);
+    }
+  }
+
+  /**
+   * Resolve/settle dispute with payment split
+   * Reference: Yellow Paper §3.4
+   *
+   * Disputes are settled via transitionState(SETTLED, proof) per §3.2
+   * The kernel contract decodes the proof and handles escrow disbursement
+   */
+  async resolveDispute(txId: string, resolution: DisputeResolution): Promise<void> {
+    validateTxId(txId, 'txId');
+
+    const { requesterAmount, providerAmount, mediatorAmount, mediator } = resolution;
+
+    // Validate amounts are non-negative
+    if (requesterAmount < 0n || providerAmount < 0n || mediatorAmount < 0n) {
+      throw new Error('Dispute resolution amounts cannot be negative');
+    }
+
+    // Validate mediator address if mediator amount > 0
+    if (mediatorAmount > 0n) {
+      if (!mediator) {
+        throw new Error('Mediator address required when mediator amount > 0');
+      }
+      validateAddress(mediator, 'mediator');
+    }
+
+    // Encode resolution proof (128 bytes: 3x uint256 + address)
+    // Kernel contract will decode this in _decodeResolutionProof and disburse funds
+    const abiCoder = AbiCoder.defaultAbiCoder();
+    const proofData = abiCoder.encode(
+      ['uint256', 'uint256', 'uint256', 'address'],
+      [
+        requesterAmount,
+        providerAmount,
+        mediatorAmount,
+        mediator || ethers.getAddress('0x0000000000000000000000000000000000000000')
+      ]
+    );
+
+    try {
+      // ethers v6: use getFunction()
+      const transitionFunc = this.contract.getFunction('transitionState');
+
+      // Settle dispute via state transition to SETTLED with resolution proof (30% buffer)
+      const estimatedGas = await transitionFunc.estimateGas(
+        txId,
+        State.SETTLED,
+        proofData
+      );
+
+      const txOptions = this.buildTxOptions(estimatedGas, 'resolveDispute');
+
+      const tx = await transitionFunc(
+        txId,
+        State.SETTLED,
+        proofData,
+        txOptions
+      );
+
+      await tx.wait(2); // Wait for 2 confirmations (Base L2 reorg safety)
+    } catch (error: any) {
+      throw new TransactionRevertedError(error.transactionHash, error.reason || error.message);
+    }
+  }
+
+  /**
+   * Settle disputed transaction (alias for resolveDispute)
+   */
+  async settleDispute(txId: string, resolution: DisputeResolution): Promise<void> {
+    return this.resolveDispute(txId, resolution);
+  }
+
+  /**
+   * Anchor an EAS attestation UID to a transaction (delivery proof)
+   * Reference: AIP-4 (Delivery Proof and EAS Attestation Standard)
+   *
+   * @param txId - Transaction ID
+   * @param attestationUID - EAS attestation UID from provider
+   * @throws {ValidationError} If inputs are invalid
+   * @throws {TransactionRevertedError} If contract reverts
+   *
+   * @example
+   * ```typescript
+   * const easHelper = new EASHelper(signer, easConfig);
+   * const attestation = await easHelper.attestDeliveryProof(proof, recipient);
+   * await kernel.anchorAttestation(txId, attestation.uid);
+   * ```
+   */
+  async anchorAttestation(txId: string, attestationUID: string): Promise<void> {
+    validateTxId(txId, 'txId');
+
+    // Validate attestationUID format (32-byte hex string)
+    if (!attestationUID || !/^0x[a-fA-F0-9]{64}$/.test(attestationUID)) {
+      throw new ValidationError('attestationUID', 'Must be 32-byte hex string (0x...)');
+    }
+
+    try {
+      // ethers v6: use getFunction()
+      const anchorFunc = this.contract.getFunction('anchorAttestation');
+
+      const estimatedGas = await anchorFunc.estimateGas(
+        txId,
+        attestationUID
+      );
+
+      const txOptions = this.buildTxOptions(estimatedGas, 'anchorAttestation');
+
+      const tx = await anchorFunc(
+        txId,
+        attestationUID,
+        txOptions
+      );
+
+      await tx.wait(2); // Wait for 2 confirmations (Base L2 reorg safety)
+    } catch (error: any) {
+      throw new TransactionRevertedError(error.transactionHash, error.reason || error.message);
+    }
+  }
+
+}