@agirails/sdk 2.0.1-beta → 2.0.2

package/dist/protocol/EscrowVault.js

@@ -9,6 +9,25 @@ const EscrowVault_json_1 = __importDefault(require("../abi/EscrowVault.json"));
 const ERC20_json_1 = __importDefault(require("../abi/ERC20.json"));
 const errors_1 = require("../errors");
 const validation_1 = require("../utils/validation");
+/**
+ * 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()`)
+ *
+ * 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
+ *
+ * Reference: AIP-3 §3.2 (Escrow Linking Workflow), lines 258-336
+ */
 class EscrowVault {
     constructor(address, signer, gasSettings) {
         this.address = address;
@@ -16,17 +35,43 @@ class EscrowVault {
         this.contract = new ethers_1.Contract(address, EscrowVault_json_1.default, 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
+     */
     getGasBufferMultiplier(operation) {
         const buffers = {
-            'releaseEscrow': 1.30,
-            'approveToken': 1.20
+            'approveToken': 1.20 // 20% - Standard ERC20 approval
         };
-        return buffers[operation] || 1.20;
+        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
+     *
+     * SECURITY FIX (NEW-C-1): Gas estimation manipulation attack protection
+     * - Enforces minimum gas floor regardless of estimate
+     * - Uses safe BigInt arithmetic with overflow detection
+     */
     buildTxOptions(estimatedGas, operation = 'default') {
+        // 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 = {
-            gasLimit: (estimatedGas * BigInt(Math.round(bufferMultiplier * 100))) / 100n
+            gasLimit
         };
         if (this.gasSettings?.maxFeePerGas) {
             options.maxFeePerGas = this.gasSettings.maxFeePerGas;
@@ -36,22 +81,63 @@ class EscrowVault {
         }
         return options;
     }
+    /**
+     * Get escrow vault address
+     */
     getAddress() {
         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() {
+        return this.contract;
+    }
+    /**
+     * 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, amount) {
         (0, validation_1.validateAddress)(tokenAddress, 'tokenAddress');
         (0, validation_1.validateAmount)(amount, 'amount');
         const tokenContract = new ethers_1.Contract(tokenAddress, ERC20_json_1.default, 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();
@@ -61,50 +147,53 @@ class EscrowVault {
             throw new errors_1.TransactionRevertedError(error.transactionHash, `Token approval failed: ${error.reason || error.message}`);
         }
     }
+    /**
+     * Get escrow details
+     */
     async getEscrow(escrowId) {
+        (0, validation_1.validateTxId)(escrowId, 'escrowId');
         const escrowData = await this.contract.escrows(escrowId);
         return {
             escrowId,
-            kernel: escrowData.kernel,
-            txId: escrowData.txId,
-            token: escrowData.token,
+            requester: escrowData.requester,
+            provider: escrowData.provider,
             amount: escrowData.amount,
-            beneficiary: escrowData.beneficiary,
-            createdAt: 0,
-            released: escrowData.released
+            releasedAmount: escrowData.releasedAmount,
+            active: escrowData.active
         };
     }
+    /**
+     * Get escrow remaining balance (amount - releasedAmount)
+     */
     async getEscrowBalance(escrowId) {
-        const escrow = await this.getEscrow(escrowId);
-        return escrow.amount;
+        (0, validation_1.validateTxId)(escrowId, 'escrowId');
+        return await this.contract.remaining(escrowId);
     }
-    async releaseEscrow(escrowId, recipients, amounts) {
+    /**
+     * @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)
+     */
+    async releaseEscrow(escrowId, _recipients, _amounts) {
         (0, validation_1.validateTxId)(escrowId, 'escrowId');
-        if (recipients.length !== amounts.length) {
-            throw new errors_1.ValidationError('recipients/amounts', 'Recipients and amounts length mismatch');
-        }
-        if (recipients.length === 0) {
-            throw new errors_1.ValidationError('recipients', 'Must provide at least one recipient');
-        }
-        recipients.forEach((recipient, i) => {
-            (0, validation_1.validateAddress)(recipient, `recipients[${i}]`);
-            (0, validation_1.validateAmount)(amounts[i], `amounts[${i}]`);
-        });
-        try {
-            const disburseFunc = this.contract.getFunction('disburse');
-            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) {
-            throw new errors_1.TransactionRevertedError(error.transactionHash, error.reason || error.message);
-        }
+        throw new errors_1.ValidationError('EscrowVault.releaseEscrow', 'Escrow payouts are performed by ACTPKernel (onlyKernel). ' +
+            'Use BlockchainRuntime.releaseEscrow(txId, attestationUID?) or ACTPKernel.transitionState(txId, SETTLED).');
     }
+    /**
+     * Check token balance
+     */
     async getTokenBalance(tokenAddress, account) {
         const tokenContract = new ethers_1.Contract(tokenAddress, ERC20_json_1.default, this.signer);
         return await tokenContract.balanceOf(account);
     }
+    /**
+     * Check token allowance
+     */
     async getTokenAllowance(tokenAddress, owner, spender) {
         const tokenContract = new ethers_1.Contract(tokenAddress, ERC20_json_1.default, this.signer);
         return await tokenContract.allowance(owner, spender);

package/dist/protocol/EscrowVault.js.map

@@ -1 +1 @@
-{"version":3,"file":"EscrowVault.js","sourceRoot":"","sources":["../../src/protocol/EscrowVault.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"EscrowVault.js","sourceRoot":"","sources":["../../src/protocol/EscrowVault.ts"],"names":[],"mappings":"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"}

package/dist/protocol/EventMonitor.d.ts

@@ -1,18 +1,62 @@
 import { Contract } from 'ethers';
 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 declare class EventMonitor {
     private readonly kernelContract;
     constructor(kernelContract: Contract, _escrowContract: Contract);
+    /**
+     * Watch transaction state changes
+     * Returns cleanup function to stop watching
+     */
     watchTransaction(txId: string, callback: (state: State) => void): () => void;
+    /**
+     * Wait for specific state
+     */
     waitForState(txId: string, targetState: State, timeoutMs?: number): Promise<void>;
+    /**
+     * 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).
+     */
     getTransactionHistory(address: string, role?: 'requester' | 'provider'): Promise<Transaction[]>;
+    /**
+     * 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)
+     */
     onTransactionCreated(callback: (tx: {
         txId: string;
-        provider: string;
         requester: string;
+        provider: string;
         amount: bigint;
+        serviceHash?: string;
     }) => void): () => void;
+    /**
+     * Subscribe to state change events
+     */
     onStateChanged(callback: (txId: string, from: State, to: State) => void): () => void;
+    /**
+     * Subscribe to escrow release events
+     */
     onEscrowReleased(callback: (txId: string, amount: bigint) => void): () => void;
 }
 //# sourceMappingURL=EventMonitor.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"EventMonitor.d.ts","sourceRoot":"","sources":["../../src/protocol/EventMonitor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAY,MAAM,QAAQ,CAAC;AAC5C,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAK9C,qBAAa,YAAY;IAErB,OAAO,CAAC,QAAQ,CAAC,cAAc;gBAAd,cAAc,EAAE,QAAQ,EACzC,eAAe,EAAE,QAAQ;IAO3B,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,MAAM,IAAI;IAkBtE,YAAY,CAChB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,KAAK,EAClB,SAAS,GAAE,MAAc,GACxB,OAAO,CAAC,IAAI,CAAC;IAqBV,qBAAqB,CACzB,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,WAAW,GAAG,UAAwB,GAC3C,OAAO,CAAC,WAAW,EAAE,CAAC;IAwCzB,oBAAoB,CAClB,QAAQ,EAAE,CAAC,EAAE,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,GAC5F,MAAM,IAAI;IAuBb,cAAc,CACZ,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,KAAK,IAAI,GACvD,MAAM,IAAI;IAiBb,gBAAgB,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;CAa/E"}
+{"version":3,"file":"EventMonitor.d.ts","sourceRoot":"","sources":["../../src/protocol/EventMonitor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAY,MAAM,QAAQ,CAAC;AAC5C,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE9C;;;;;;;;GAQG;AACH,qBAAa,YAAY;IAErB,OAAO,CAAC,QAAQ,CAAC,cAAc;gBAAd,cAAc,EAAE,QAAQ,EACzC,eAAe,EAAE,QAAQ;IAG3B;;;OAGG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,MAAM,IAAI;IAe5E;;OAEG;IACG,YAAY,CAChB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,KAAK,EAClB,SAAS,GAAE,MAAc,GACxB,OAAO,CAAC,IAAI,CAAC;IAiBhB;;;;;;;;;;;;;OAaG;IACG,qBAAqB,CACzB,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,WAAW,GAAG,UAAwB,GAC3C,OAAO,CAAC,WAAW,EAAE,CAAC;IA6CzB;;;;;;OAMG;IACH,oBAAoB,CAClB,QAAQ,EAAE,CAAC,EAAE,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,GAClH,MAAM,IAAI;IAqBb;;OAEG;IACH,cAAc,CACZ,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,KAAK,IAAI,GACvD,MAAM,IAAI;IAcb;;OAEG;IACH,gBAAgB,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;CAa/E"}

package/dist/protocol/EventMonitor.js

@@ -2,20 +2,37 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EventMonitor = void 0;
 const types_1 = require("../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.
+ */
 class EventMonitor {
     constructor(kernelContract, _escrowContract) {
         this.kernelContract = kernelContract;
     }
+    /**
+     * Watch transaction state changes
+     * Returns cleanup function to stop watching
+     */
     watchTransaction(txId, callback) {
         const filter = this.kernelContract.filters.StateTransitioned(txId);
         const listener = (_eventTxId, _from, to) => {
             callback(to);
         };
         this.kernelContract.on(filter, listener);
+        // Return cleanup function
         return () => {
             this.kernelContract.off(filter, listener);
         };
     }
+    /**
+     * Wait for specific state
+     */
     async waitForState(txId, targetState, timeoutMs = 60000) {
         return new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
@@ -31,42 +48,78 @@ 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).
+     */
     async getTransactionHistory(address, role = 'requester') {
+        // TransactionCreated event signature per ABI:
+        // (bytes32 indexed transactionId, address indexed requester, address indexed provider, uint256 amount, bytes32 serviceHash)
+        // Filter format: TransactionCreated(txId, requester, provider)
         const filter = role === 'requester'
-            ? this.kernelContract.filters.TransactionCreated(null, null, address)
-            : this.kernelContract.filters.TransactionCreated(null, address, null);
+            ? this.kernelContract.filters.TransactionCreated(null, address, null) // Match requester (2nd indexed param)
+            : this.kernelContract.filters.TransactionCreated(null, null, address); // Match provider (3rd indexed param)
         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.args?.transactionId;
-            const txData = await this.kernelContract.transactions(txId);
+            // 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);
             return {
-                txId: txData.transactionId,
+                txId: txData.transactionId || txId,
                 requester: txData.requester,
                 provider: txData.provider,
                 amount: txData.amount,
-                state: txData.state,
+                state: (typeof txData.state === 'bigint' ? Number(txData.state) : txData.state),
                 createdAt: Number(txData.createdAt),
+                updatedAt: Number(txData.updatedAt),
                 deadline: Number(txData.deadline),
                 disputeWindow: Number(txData.disputeWindow),
                 escrowContract: txData.escrowContract,
                 escrowId: txData.escrowId,
-                metadata: txData.serviceHash
+                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)
             };
         }));
     }
+    /**
+     * 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)
+     */
     onTransactionCreated(callback) {
         const filter = this.kernelContract.filters.TransactionCreated();
-        const listener = async (txId, provider, requester, amount) => {
-            callback({ txId, provider, requester, amount });
+        // Event signature per ABI: (txId, requester, provider, amount, serviceHash)
+        const listener = async (txId, requester, provider, amount, serviceHash) => {
+            callback({ txId, requester, provider, amount, serviceHash });
         };
         this.kernelContract.on(filter, listener);
         return () => {
             this.kernelContract.off(filter, listener);
         };
     }
+    /**
+     * Subscribe to state change events
+     */
     onStateChanged(callback) {
         const filter = this.kernelContract.filters.StateTransitioned();
         const listener = (txId, from, to) => {
@@ -77,6 +130,9 @@ class EventMonitor {
             this.kernelContract.off(filter, listener);
         };
     }
+    /**
+     * Subscribe to escrow release events
+     */
     onEscrowReleased(callback) {
         const filter = this.kernelContract.filters.EscrowReleased();
         const listener = (txId, amount) => {

package/dist/protocol/EventMonitor.js.map

@@ -1 +1 @@
-{"version":3,"file":"EventMonitor.js","sourceRoot":"","sources":["../../src/protocol/EventMonitor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"EventMonitor.js","sourceRoot":"","sources":["../../src/protocol/EventMonitor.ts"],"names":[],"mappings":"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"}

package/dist/protocol/MessageSigner.d.ts

@@ -1,23 +1,137 @@
 import { Signer } from 'ethers';
 import { ACTPMessage, DeliveryProof } from '../types';
-import { QuoteRequestData, QuoteResponseData, DeliveryProofData } from '../types/eip712';
+import { EIP712Domain, QuoteRequestData, QuoteResponseData, DeliveryProofData } from '../types/eip712';
 import { IReceivedNonceTracker } from '../utils/ReceivedNonceTracker';
+/**
+ * MessageSigner - Cryptographic signing for ACTP messages with EIP-712
+ * 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 declare class MessageSigner {
     private readonly signer;
     private readonly nonceTracker?;
     private domain;
-    constructor(signer: Signer, nonceTracker?: IReceivedNonceTracker | undefined);
+    /**
+     * 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();
+    /**
+     * 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 create(signer: Signer, kernelAddress: string, options?: {
+        chainId?: number;
+        nonceTracker?: IReceivedNonceTracker;
+    }): Promise<MessageSigner>;
+    /**
+     * Check if domain is initialized
+     * @returns true if domain has been initialized
+     */
+    isDomainInitialized(): boolean;
+    /**
+     * Get the current domain (throws if not initialized)
+     * @returns Current EIP-712 domain
+     * @throws Error if domain not initialized
+     */
+    getDomain(): EIP712Domain;
+    /**
+     * Initialize EIP-712 domain (must be called before signing)
+     * @param kernelAddress - Address of ACTP Kernel contract
+     * @param chainId - Optional chainId (defaults to signer's chainId or 84532 for Base Sepolia)
+     */
     initDomain(kernelAddress: string, chainId?: number): Promise<void>;
+    /**
+     * 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
+     */
     signMessage(message: ACTPMessage): Promise<string>;
+    /**
+     * Sign typed QuoteRequest message
+     */
     signQuoteRequest(data: QuoteRequestData): Promise<string>;
+    /**
+     * Sign typed QuoteResponse message
+     */
     signQuoteResponse(data: QuoteResponseData): Promise<string>;
+    /**
+     * Sign typed DeliveryProof message
+     */
     signDeliveryProof(data: DeliveryProofData): Promise<string>;
+    /**
+     * Convenience helper to sign a DeliveryProof generated by ProofGenerator
+     */
     signGeneratedDeliveryProof(proof: DeliveryProof): Promise<string>;
+    /**
+     * Verify message signature using EIP-712
+     * Uses generic ACTPMessage types (backward compatible)
+     *
+     * V4 Security: If nonceTracker is configured, validates nonce for replay protection
+     */
     verifySignature(message: ACTPMessage, signature: string): Promise<boolean>;
+    /**
+     * Verify signature and throw if invalid
+     * V4 Security: Throws specific error for nonce replay detection
+     */
     verifySignatureOrThrow(message: ACTPMessage, signature: string): Promise<void>;
+    /**
+     * Canonicalize payload to deterministic string (recursively sorted keys)
+     * Prevents JSON serialization ambiguity across different JS runtimes
+     * Recursively handles nested objects and arrays
+     */
     private canonicalizePayload;
+    /**
+     * Recursively sort object keys for deterministic JSON encoding
+     */
     private recursiveSort;
+    /**
+     * 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)
+     */
     private didToAddress;
+    /**
+     * 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;
 }
 //# sourceMappingURL=MessageSigner.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"MessageSigner.d.ts","sourceRoot":"","sources":["../../src/protocol/MessageSigner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAoB,MAAM,QAAQ,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEtD,OAAO,EAGL,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EAElB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAwBtE,qBAAa,aAAa;IAItB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC;IAJhC,OAAO,CAAC,MAAM,CAA6B;gBAGxB,MAAM,EAAE,MAAM,EACd,YAAY,CAAC,EAAE,qBAAqB,YAAA;IAQjD,UAAU,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoClE,WAAW,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAqClD,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC;IAazD,iBAAiB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC;IAa3D,iBAAiB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC;IAa3D,0BAA0B,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC;IAWjE,eAAe,CAAC,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAuD1E,sBAAsB,CAAC,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiDpF,OAAO,CAAC,mBAAmB;IAO3B,OAAO,CAAC,aAAa;IA8BrB,OAAO,CAAC,YAAY;IAgBpB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;CAOtC"}
+{"version":3,"file":"MessageSigner.d.ts","sourceRoot":"","sources":["../../src/protocol/MessageSigner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAoB,MAAM,QAAQ,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEtD,OAAO,EACL,YAAY,EAEZ,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EAElB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAkBtE;;;;;;;GAOG;AACH,qBAAa,aAAa;IAUtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC;IAVhC,OAAO,CAAC,MAAM,CAA6B;IAE3C;;;;;OAKG;IACH,OAAO;IAKP;;;;;;;;;;;;;;;;;;;;OAoBG;WACU,MAAM,CACjB,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE;QACR,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,YAAY,CAAC,EAAE,qBAAqB,CAAC;KACtC,GACA,OAAO,CAAC,aAAa,CAAC;IAMzB;;;OAGG;IACH,mBAAmB,IAAI,OAAO;IAI9B;;;;OAIG;IACH,SAAS,IAAI,YAAY;IASzB;;;;OAIG;IACG,UAAU,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA+BxE;;;;;;;;OAQG;IACG,WAAW,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAsExD;;OAEG;IACG,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC;IAY/D;;OAEG;IACG,iBAAiB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC;IAYjE;;OAEG;IACG,iBAAiB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC;IAYjE;;OAEG;IACG,0BAA0B,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC;IAKvE;;;;;OAKG;IACG,eAAe,CAAC,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAqDhF;;;OAGG;IACG,sBAAsB,CAAC,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA4CpF;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;IAI3B;;OAEG;IACH,OAAO,CAAC,aAAa;IA0BrB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,YAAY;IA8DpB;;;;;;;OAOG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;CAatC"}