@agirails/sdk 2.0.1-beta → 2.0.2

package/dist/protocol/ACTPKernel.d.ts

@@ -1,29 +1,256 @@
-import { Signer, BytesLike } from 'ethers';
+import { Contract, Signer, BytesLike } from 'ethers';
 import { State, Transaction, CreateTransactionParams, DisputeResolution, EconomicParams } from '../types';
+/**
+ * Gas options for transactions
+ */
 interface GasOptions {
     maxFeePerGas?: bigint;
     maxPriorityFeePerGas?: bigint;
 }
+/**
+ * ACTPKernel - Smart contract wrapper
+ * Reference: Yellow Paper §3 (ACTP Kernel Specification)
+ */
 export declare class ACTPKernel {
     private readonly address;
     private contract;
     private readonly gasSettings?;
     constructor(address: string, signer: Signer, gasSettings?: GasOptions);
+    /**
+     * Get kernel contract address
+     */
     getAddress(): string;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Build transaction options with gas settings and estimated gas
+     * V6 Enhancement: Dynamic buffer based on operation type
+     *
+     * SECURITY FIX (C-3): Gas estimation manipulation attack protection
+     * - Enforces operation-specific minimum gas floors (not global 100k)
+     * - Validates gas limit doesn't exceed block gas limit (DoS prevention)
+     * - Uses safe BigInt arithmetic with overflow detection
+     * - Prevents floating-point arithmetic (uses BPS - basis points)
+     */
     private buildTxOptions;
+    /**
+     * 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)
+     */
     createTransaction(params: CreateTransactionParams): Promise<string>;
+    /**
+     * Transition transaction state
+     * Reference: Yellow Paper §3.2
+     */
     transitionState(txId: string, newState: State, proof?: BytesLike): Promise<void>;
+    /**
+     * 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
+     */
     submitQuote(txId: string, quoteHash: string): Promise<void>;
+    /**
+     * 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)
+     */
     linkEscrow(txId: string, escrowContract: string, escrowId: string): Promise<void>;
-    releaseMilestone(txId: string, milestoneId: number, amount: bigint): Promise<void>;
+    /**
+     * Release milestone payment
+     *
+     * SECURITY FIX (CRITICAL-2): Contract ABI has only 2 params (txId, amount), not 3.
+     * The milestoneId is NOT part of the current ACTPKernel V1 contract.
+     * Per ABI: releaseMilestone(bytes32 transactionId, uint256 amount)
+     *
+     * @param txId - Transaction ID (bytes32)
+     * @param amount - Amount to release (uint256)
+     * @deprecated milestoneId parameter - removed as contract doesn't support it
+     */
+    releaseMilestone(txId: string, amount: bigint): Promise<void>;
+    /**
+     * Release full escrow (settle transaction)
+     *
+     * ⚠️ CRITICAL SECURITY WARNING (C-2): Attestation UID Validation Bypass
+     *
+     * **DO NOT call this method directly from your application code!**
+     *
+     * ACTPKernel V1 contract accepts any attestationUID without validation.
+     * A malicious provider can:
+     * - Submit an attestation from a different transaction
+     * - Re-use an old attestation (replay attack)
+     * - Submit a forged attestation with fake delivery proof
+     *
+     * **REQUIRED: Use secure wrapper methods instead:**
+     *
+     * 1. **BeginnerAdapter.completePayment()** (recommended for most users)
+     *    - Automatically verifies attestation before release
+     *    - Validates attestation belongs to this transaction
+     *    - Checks attestation hasn't been used before
+     *    - Handles all state transitions
+     *
+     * 2. **IntermediateAdapter.releaseEscrow()** (for more control)
+     *    - Explicitly requires attestation verification
+     *    - Throws error if attestation invalid or missing
+     *    - Allows custom verification logic
+     *
+     * 3. **Manual verification** (advanced users only):
+     *    ```typescript
+     *    // Step 1: Get transaction details
+     *    const tx = await kernel.getTransaction(txId);
+     *
+     *    // Step 2: Verify attestation if EAS is configured
+     *    if (easHelper && tx.attestationUID && tx.attestationUID !== '0x0...0') {
+     *      const isValid = await easHelper.verifyDeliveryAttestation(
+     *        tx.attestationUID,
+     *        tx.requester
+     *      );
+     *      if (!isValid) {
+     *        throw new Error('Invalid or fraudulent delivery attestation');
+     *      }
+     *    }
+     *
+     *    // Step 3: Only now is it safe to release
+     *    await kernel.releaseEscrow(txId);
+     *    ```
+     *
+     * **Why this matters:**
+     * - Without verification, you risk paying for work never delivered
+     * - Provider can steal funds by re-using attestations from other transactions
+     * - No on-chain enforcement (contract V1 limitation, fixed in V2)
+     *
+     * **For testnet/mainnet deployments:**
+     * - MUST configure easConfig in ACTPClient
+     * - MUST use wrapper methods (Beginner/Intermediate adapters)
+     * - NEVER call this method directly unless attestation verified
+     *
+     * @param txId - Transaction ID to settle
+     * @throws {ValidationError} If txId is invalid
+     * @throws {TransactionRevertedError} If contract reverts
+     *
+     * @see {@link BeginnerAdapter.completePayment} Recommended method with built-in verification
+     * @see {@link IntermediateAdapter.releaseEscrow} Explicit verification method
+     * @see {@link EASHelper.verifyDeliveryAttestation} Manual verification helper
+     */
     releaseEscrow(txId: string): Promise<void>;
+    /**
+     * Get transaction by ID
+     */
     getTransaction(txId: string): Promise<Transaction>;
+    /**
+     * Get economic parameters (fee structure)
+     *
+     * SECURITY FIX (CRITICAL-4): Contract doesn't have getEconomicParams() function.
+     * Must call individual getters: platformFeeBps(), requesterPenaltyBps(), feeRecipient()
+     * Per ACTPKernel.json ABI lines 576-586, 619-630, 351-361
+     */
     getEconomicParams(): Promise<EconomicParams>;
+    /**
+     * Estimate gas for transaction creation
+     */
     estimateCreateTransaction(params: CreateTransactionParams): Promise<bigint>;
+    /**
+     * Raise dispute on delivered transaction
+     * Reference: Yellow Paper §3.4 (Dispute Management)
+     */
     raiseDispute(txId: string, reason: string, evidence: string): Promise<void>;
+    /**
+     * 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
+     */
     resolveDispute(txId: string, resolution: DisputeResolution): Promise<void>;
+    /**
+     * Settle disputed transaction (alias for resolveDispute)
+     */
     settleDispute(txId: string, resolution: DisputeResolution): Promise<void>;
+    /**
+     * 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);
+     * ```
+     */
     anchorAttestation(txId: string, attestationUID: string): Promise<void>;
 }
 export {};

package/dist/protocol/ACTPKernel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ACTPKernel.d.ts","sourceRoot":"","sources":["../../src/protocol/ACTPKernel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,MAAM,EAAE,SAAS,EAAoB,MAAM,QAAQ,CAAC;AAEvE,OAAO,EACL,KAAK,EAEL,WAAW,EACX,uBAAuB,EACvB,iBAAiB,EACjB,cAAc,EACf,MAAM,UAAU,CAAC;AAkBlB,UAAU,UAAU;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAMD,qBAAa,UAAU;IAKnB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJ1B,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAa;gBAGvB,OAAO,EAAE,MAAM,EAChC,MAAM,EAAE,MAAM,EACd,WAAW,CAAC,EAAE,UAAU;IAS1B,UAAU,IAAI,MAAM;IASpB,OAAO,CAAC,sBAAsB;IAkB9B,OAAO,CAAC,cAAc;IAwBhB,iBAAiB,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC;IA+EnE,eAAe,CACnB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,KAAK,EACf,KAAK,GAAE,SAAgB,GACtB,OAAO,CAAC,IAAI,CAAC;IAsCV,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqF3D,UAAU,CACd,IAAI,EAAE,MAAM,EACZ,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IA0BV,gBAAgB,CACpB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC;IAyCV,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAuB1C,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IA4BlD,iBAAiB,IAAI,OAAO,CAAC,cAAc,CAAC;IAgB5C,yBAAyB,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC;IAmB3E,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA2C3E,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IA4D1E,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBzE,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CA+B7E"}
+{"version":3,"file":"ACTPKernel.d.ts","sourceRoot":"","sources":["../../src/protocol/ACTPKernel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAoB,MAAM,QAAQ,CAAC;AAEvE,OAAO,EACL,KAAK,EAEL,WAAW,EACX,uBAAuB,EACvB,iBAAiB,EACjB,cAAc,EACf,MAAM,UAAU,CAAC;AAelB;;GAEG;AACH,UAAU,UAAU;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;GAGG;AACH,qBAAa,UAAU;IAKnB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJ1B,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAa;gBAGvB,OAAO,EAAE,MAAM,EAChC,MAAM,EAAE,MAAM,EACd,WAAW,CAAC,EAAE,UAAU;IAM1B;;OAEG;IACH,UAAU,IAAI,MAAM;IAIpB;;;;;;;OAOG;IACH,WAAW,IAAI,QAAQ;IAIvB;;;;OAIG;IACH,OAAO,CAAC,sBAAsB;IAc9B;;;;;;;;;OASG;IACH,OAAO,CAAC,cAAc;IA8DtB;;;;;;OAMG;IACG,iBAAiB,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC;IAkFzE;;;OAGG;IACG,eAAe,CACnB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,KAAK,EACf,KAAK,GAAE,SAAgB,GACtB,OAAO,CAAC,IAAI,CAAC;IA6BhB;;;;;;;;OAQG;IACG,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA8BjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsDG;IACG,UAAU,CACd,IAAI,EAAE,MAAM,EACZ,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IAuBhB;;;;;;;;;;OAUG;IACG,gBAAgB,CACpB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC;IAsBhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+DG;IACG,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBhD;;OAEG;IACG,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IA6CxD;;;;;;OAMG;IACG,iBAAiB,IAAI,OAAO,CAAC,cAAc,CAAC;IAmBlD;;OAEG;IACG,yBAAyB,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC;IAejF;;;OAGG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoCjF;;;;;;OAMG;IACG,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAyDhF;;OAEG;IACG,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/E;;;;;;;;;;;;;;;OAeG;IACG,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CA+B7E"}