@agirails/sdk 2.0.1-beta → 2.0.3

package/dist/adapters/IntermediateAdapter.d.ts

@@ -0,0 +1,211 @@
+/**
+ * IntermediateAdapter - Balanced API for developers with some protocol knowledge
+ *
+ * Provides more control than BeginnerAdapter while still offering convenience:
+ * - Explicit transaction lifecycle methods
+ * - Direct escrow operations
+ * - State transition control
+ *
+ * Use this adapter when you need fine-grained control but still want
+ * user-friendly input parsing and validation.
+ *
+ * @module adapters/IntermediateAdapter
+ */
+import { BaseAdapter } from './BaseAdapter';
+import { IACTPRuntime } from '../runtime/IACTPRuntime';
+import { MockTransaction, TransactionState } from '../runtime/types/MockState';
+import { EASHelper } from '../protocol/EASHelper';
+/**
+ * Parameters for creating a transaction (intermediate level).
+ *
+ * More explicit than BeginnerPayParams but still with smart defaults.
+ */
+export interface IntermediateTransactionParams {
+    /** Provider's Ethereum address */
+    provider: string;
+    /** Amount in user-friendly format ("100", "100.50", "100 USDC") */
+    amount: string | number;
+    /** Optional: Deadline as relative time ("+24h") or Unix timestamp. Defaults to +24h */
+    deadline?: string | number;
+    /** Optional: Dispute window in seconds. Defaults to 172800 (2 days) */
+    disputeWindow?: number;
+    /** Optional: Service description */
+    serviceDescription?: string;
+}
+/**
+ * IntermediateAdapter - Balanced API for transaction lifecycle control.
+ *
+ * Provides explicit methods for each stage of the ACTP lifecycle:
+ * - `createTransaction()` - Create transaction without escrow
+ * - `linkEscrow()` - Link escrow (auto-transitions to COMMITTED)
+ * - `transitionState()` - Manually transition state
+ * - `releaseEscrow()` - Release funds to provider
+ * - `getEscrowBalance()` - Check escrow balance
+ * - `getTransaction()` - Get transaction details
+ *
+ * @example
+ * ```typescript
+ * const client = await ACTPClient.create({ mode: 'mock' });
+ *
+ * // Create transaction (INITIATED state)
+ * const txId = await client.intermediate.createTransaction({
+ *   provider: '0xProvider123',
+ *   amount: '100',
+ *   deadline: '+7d',
+ * });
+ *
+ * // Link escrow (auto-transitions to COMMITTED)
+ * await client.intermediate.linkEscrow(txId, '100');
+ *
+ * // Provider delivers
+ * await client.intermediate.transitionState(txId, 'DELIVERED');
+ *
+ * // Release funds after dispute window
+ * await client.intermediate.releaseEscrow(escrowId);
+ * ```
+ */
+export declare class IntermediateAdapter extends BaseAdapter {
+    private runtime;
+    private easHelper?;
+    /**
+     * Creates a new IntermediateAdapter instance.
+     *
+     * @param runtime - ACTP runtime implementation (MockRuntime or BlockchainRuntime)
+     * @param requesterAddress - The requester's Ethereum address
+     * @param easHelper - Optional EAS helper for attestation verification (SECURITY FIX C-4)
+     */
+    constructor(runtime: IACTPRuntime, requesterAddress: string, easHelper?: EASHelper | undefined);
+    /**
+     * Create a transaction (INITIATED state, no escrow yet).
+     *
+     * Unlike `beginner.pay()`, this only creates the transaction
+     * without linking escrow. You must call `linkEscrow()` separately.
+     *
+     * @param params - Transaction parameters
+     * @returns Transaction ID
+     * @throws {ValidationError} If inputs are invalid
+     *
+     * @example
+     * ```typescript
+     * const txId = await adapter.createTransaction({
+     *   provider: '0xProvider123',
+     *   amount: '100',
+     *   deadline: '+24h',
+     * });
+     * ```
+     */
+    createTransaction(params: IntermediateTransactionParams): Promise<string>;
+    /**
+     * Link escrow to a transaction.
+     *
+     * Automatically transitions INITIATED or QUOTED → COMMITTED.
+     * Deducts funds from requester and locks in escrow.
+     *
+     * @param txId - Transaction ID
+     * @returns Escrow ID
+     * @throws {Error} If transaction not found or in wrong state
+     *
+     * @example
+     * ```typescript
+     * const escrowId = await adapter.linkEscrow(txId);
+     * ```
+     */
+    linkEscrow(txId: string): Promise<string>;
+    /**
+     * Transition transaction to a new state.
+     *
+     * Validates the transition against the ACTP 8-state machine.
+     *
+     * Valid transitions:
+     * - INITIATED → QUOTED, COMMITTED, CANCELLED
+     * - QUOTED → COMMITTED, CANCELLED
+     * - COMMITTED → IN_PROGRESS, DELIVERED, CANCELLED
+     * - IN_PROGRESS → DELIVERED, CANCELLED
+     * - DELIVERED → SETTLED, DISPUTED
+     * - DISPUTED → SETTLED
+     *
+     * @param txId - Transaction ID
+     * @param newState - Target state
+     * @throws {Error} If transition is invalid
+     *
+     * @example
+     * ```typescript
+     * // Provider marks work as delivered
+     * await adapter.transitionState(txId, 'DELIVERED');
+     * ```
+     */
+    transitionState(txId: string, newState: TransactionState): Promise<void>;
+    /**
+     * Release escrow funds to the provider.
+     *
+     * Can only be called when transaction is in DELIVERED state
+     * and dispute window has expired.
+     *
+     * SECURITY FIX (C-4 + HIGH-5): MANDATORY attestation verification before release.
+     * When EASHelper is available (testnet/mainnet modes), attestation verification
+     * is REQUIRED - not optional. This prevents releasing funds without proper
+     * delivery proof.
+     *
+     * Verifications performed:
+     * - Attestation exists and is not revoked
+     * - Attestation belongs to this transaction (prevents replay attacks)
+     * - Attestation has not been used for a different transaction
+     *
+     * @param escrowId - Escrow ID
+     * @param attestationParams - Attestation verification params (REQUIRED when EASHelper available)
+     * @param attestationParams.txId - Transaction ID (bytes32)
+     * @param attestationParams.attestationUID - Attestation UID (bytes32)
+     * @throws {Error} If escrow not found or dispute window active
+     * @throws {Error} If EASHelper is available but attestationParams not provided (HIGH-5)
+     * @throws {Error} If attestation verification fails
+     *
+     * @example
+     * ```typescript
+     * // With attestation verification (REQUIRED in testnet/mainnet)
+     * await adapter.releaseEscrow(escrowId, {
+     *   txId: '0x...',
+     *   attestationUID: '0x...'
+     * });
+     *
+     * // Mock mode only (no attestation required)
+     * await adapter.releaseEscrow(escrowId);
+     * ```
+     */
+    releaseEscrow(escrowId: string, attestationParams?: {
+        txId: string;
+        attestationUID: string;
+    }): Promise<void>;
+    /**
+     * Get escrow balance.
+     *
+     * Returns formatted balance string (e.g., "100.00 USDC").
+     *
+     * @param escrowId - Escrow ID
+     * @returns Formatted balance
+     * @throws {Error} If escrow not found
+     *
+     * @example
+     * ```typescript
+     * const balance = await adapter.getEscrowBalance(escrowId);
+     * console.log(balance); // "100.00 USDC"
+     * ```
+     */
+    getEscrowBalance(escrowId: string): Promise<string>;
+    /**
+     * Get transaction details.
+     *
+     * Returns the full transaction object from the runtime.
+     *
+     * @param txId - Transaction ID
+     * @returns Transaction object or null if not found
+     *
+     * @example
+     * ```typescript
+     * const tx = await adapter.getTransaction(txId);
+     * console.log('State:', tx?.state);
+     * console.log('Amount:', tx?.amount);
+     * ```
+     */
+    getTransaction(txId: string): Promise<MockTransaction | null>;
+}
+//# sourceMappingURL=IntermediateAdapter.d.ts.map

package/dist/adapters/IntermediateAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IntermediateAdapter.d.ts","sourceRoot":"","sources":["../../src/adapters/IntermediateAdapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,WAAW,EAAmD,MAAM,eAAe,CAAC;AAC7F,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAC/E,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;GAIG;AACH,MAAM,WAAW,6BAA6B;IAC5C,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IAEjB,mEAAmE;IACnE,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IAExB,uFAAuF;IACvF,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAE3B,uEAAuE;IACvE,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,oCAAoC;IACpC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,mBAAoB,SAAQ,WAAW;IAShD,OAAO,CAAC,OAAO;IAEf,OAAO,CAAC,SAAS,CAAC;IAVpB;;;;;;OAMG;gBAEO,OAAO,EAAE,YAAY,EAC7B,gBAAgB,EAAE,MAAM,EAChB,SAAS,CAAC,uBAAW;IAK/B;;;;;;;;;;;;;;;;;;OAkBG;IACG,iBAAiB,CAAC,MAAM,EAAE,6BAA6B,GAAG,OAAO,CAAC,MAAM,CAAC;IA6B/E;;;;;;;;;;;;;;OAcG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAW/C;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACG,aAAa,CACjB,QAAQ,EAAE,MAAM,EAChB,iBAAiB,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,GAC3D,OAAO,CAAC,IAAI,CAAC;IAgDhB;;;;;;;;;;;;;;OAcG;IACG,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAKzD;;;;;;;;;;;;;;OAcG;IACG,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;CAGpE"}

package/dist/adapters/IntermediateAdapter.js

@@ -0,0 +1,260 @@
+"use strict";
+/**
+ * IntermediateAdapter - Balanced API for developers with some protocol knowledge
+ *
+ * Provides more control than BeginnerAdapter while still offering convenience:
+ * - Explicit transaction lifecycle methods
+ * - Direct escrow operations
+ * - State transition control
+ *
+ * Use this adapter when you need fine-grained control but still want
+ * user-friendly input parsing and validation.
+ *
+ * @module adapters/IntermediateAdapter
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IntermediateAdapter = void 0;
+const BaseAdapter_1 = require("./BaseAdapter");
+/**
+ * IntermediateAdapter - Balanced API for transaction lifecycle control.
+ *
+ * Provides explicit methods for each stage of the ACTP lifecycle:
+ * - `createTransaction()` - Create transaction without escrow
+ * - `linkEscrow()` - Link escrow (auto-transitions to COMMITTED)
+ * - `transitionState()` - Manually transition state
+ * - `releaseEscrow()` - Release funds to provider
+ * - `getEscrowBalance()` - Check escrow balance
+ * - `getTransaction()` - Get transaction details
+ *
+ * @example
+ * ```typescript
+ * const client = await ACTPClient.create({ mode: 'mock' });
+ *
+ * // Create transaction (INITIATED state)
+ * const txId = await client.intermediate.createTransaction({
+ *   provider: '0xProvider123',
+ *   amount: '100',
+ *   deadline: '+7d',
+ * });
+ *
+ * // Link escrow (auto-transitions to COMMITTED)
+ * await client.intermediate.linkEscrow(txId, '100');
+ *
+ * // Provider delivers
+ * await client.intermediate.transitionState(txId, 'DELIVERED');
+ *
+ * // Release funds after dispute window
+ * await client.intermediate.releaseEscrow(escrowId);
+ * ```
+ */
+class IntermediateAdapter extends BaseAdapter_1.BaseAdapter {
+    /**
+     * Creates a new IntermediateAdapter instance.
+     *
+     * @param runtime - ACTP runtime implementation (MockRuntime or BlockchainRuntime)
+     * @param requesterAddress - The requester's Ethereum address
+     * @param easHelper - Optional EAS helper for attestation verification (SECURITY FIX C-4)
+     */
+    constructor(runtime, requesterAddress, easHelper) {
+        super(requesterAddress);
+        this.runtime = runtime;
+        this.easHelper = easHelper;
+    }
+    /**
+     * Create a transaction (INITIATED state, no escrow yet).
+     *
+     * Unlike `beginner.pay()`, this only creates the transaction
+     * without linking escrow. You must call `linkEscrow()` separately.
+     *
+     * @param params - Transaction parameters
+     * @returns Transaction ID
+     * @throws {ValidationError} If inputs are invalid
+     *
+     * @example
+     * ```typescript
+     * const txId = await adapter.createTransaction({
+     *   provider: '0xProvider123',
+     *   amount: '100',
+     *   deadline: '+24h',
+     * });
+     * ```
+     */
+    async createTransaction(params) {
+        const provider = this.validateAddress(params.provider, 'provider');
+        const amount = this.parseAmount(params.amount);
+        const currentTime = this.runtime.time.now();
+        const deadline = this.parseDeadline(params.deadline, currentTime);
+        // SECURITY FIX (L-1): Validate dispute window bounds
+        const disputeWindow = this.validateDisputeWindow(params.disputeWindow);
+        const requester = this.requesterAddress;
+        // Validation
+        if (requester.toLowerCase() === provider.toLowerCase()) {
+            throw new BaseAdapter_1.ValidationError('Cannot create transaction with yourself as provider');
+        }
+        if (deadline <= currentTime) {
+            throw new BaseAdapter_1.ValidationError('Deadline must be in the future');
+        }
+        return this.runtime.createTransaction({
+            provider,
+            requester,
+            amount: amount.toString(),
+            deadline,
+            disputeWindow,
+            serviceDescription: params.serviceDescription,
+        });
+    }
+    /**
+     * Link escrow to a transaction.
+     *
+     * Automatically transitions INITIATED or QUOTED → COMMITTED.
+     * Deducts funds from requester and locks in escrow.
+     *
+     * @param txId - Transaction ID
+     * @returns Escrow ID
+     * @throws {Error} If transaction not found or in wrong state
+     *
+     * @example
+     * ```typescript
+     * const escrowId = await adapter.linkEscrow(txId);
+     * ```
+     */
+    async linkEscrow(txId) {
+        const tx = await this.runtime.getTransaction(txId);
+        if (!tx) {
+            throw new Error(`Transaction ${txId} not found`);
+        }
+        // Use the transaction's amount (already in correct format)
+        return this.runtime.linkEscrow(txId, tx.amount);
+    }
+    /**
+     * Transition transaction to a new state.
+     *
+     * Validates the transition against the ACTP 8-state machine.
+     *
+     * Valid transitions:
+     * - INITIATED → QUOTED, COMMITTED, CANCELLED
+     * - QUOTED → COMMITTED, CANCELLED
+     * - COMMITTED → IN_PROGRESS, DELIVERED, CANCELLED
+     * - IN_PROGRESS → DELIVERED, CANCELLED
+     * - DELIVERED → SETTLED, DISPUTED
+     * - DISPUTED → SETTLED
+     *
+     * @param txId - Transaction ID
+     * @param newState - Target state
+     * @throws {Error} If transition is invalid
+     *
+     * @example
+     * ```typescript
+     * // Provider marks work as delivered
+     * await adapter.transitionState(txId, 'DELIVERED');
+     * ```
+     */
+    async transitionState(txId, newState) {
+        return this.runtime.transitionState(txId, newState);
+    }
+    /**
+     * Release escrow funds to the provider.
+     *
+     * Can only be called when transaction is in DELIVERED state
+     * and dispute window has expired.
+     *
+     * SECURITY FIX (C-4 + HIGH-5): MANDATORY attestation verification before release.
+     * When EASHelper is available (testnet/mainnet modes), attestation verification
+     * is REQUIRED - not optional. This prevents releasing funds without proper
+     * delivery proof.
+     *
+     * Verifications performed:
+     * - Attestation exists and is not revoked
+     * - Attestation belongs to this transaction (prevents replay attacks)
+     * - Attestation has not been used for a different transaction
+     *
+     * @param escrowId - Escrow ID
+     * @param attestationParams - Attestation verification params (REQUIRED when EASHelper available)
+     * @param attestationParams.txId - Transaction ID (bytes32)
+     * @param attestationParams.attestationUID - Attestation UID (bytes32)
+     * @throws {Error} If escrow not found or dispute window active
+     * @throws {Error} If EASHelper is available but attestationParams not provided (HIGH-5)
+     * @throws {Error} If attestation verification fails
+     *
+     * @example
+     * ```typescript
+     * // With attestation verification (REQUIRED in testnet/mainnet)
+     * await adapter.releaseEscrow(escrowId, {
+     *   txId: '0x...',
+     *   attestationUID: '0x...'
+     * });
+     *
+     * // Mock mode only (no attestation required)
+     * await adapter.releaseEscrow(escrowId);
+     * ```
+     */
+    async releaseEscrow(escrowId, attestationParams) {
+        // Determine whether the underlying runtime requires attestation.
+        // BlockchainRuntime exposes isAttestationRequired(), but it's not part of the generic interface.
+        const runtimeAny = this.runtime;
+        const runtimeSupportsAttestationFlag = typeof runtimeAny?.isAttestationRequired === 'function';
+        const attestationRequired = runtimeSupportsAttestationFlag
+            ? Boolean(runtimeAny.isAttestationRequired())
+            : Boolean(this.easHelper);
+        if (attestationRequired && !attestationParams) {
+            throw new Error('Attestation verification is REQUIRED for escrow release. ' +
+                'Provide attestationParams: { txId: string, attestationUID: string }.');
+        }
+        // If caller provided attestation params, ensure they match the escrow/tx being released.
+        if (attestationParams) {
+            // Support legacy escrowId format "escrow-{txId}-{timestamp}".
+            // Standard is escrowId === txId.
+            const legacyMatch = escrowId.match(/^escrow-(.+)-\d+$/);
+            const txIdFromEscrowId = legacyMatch ? legacyMatch[1] : escrowId;
+            if (txIdFromEscrowId.toLowerCase() !== attestationParams.txId.toLowerCase()) {
+                throw new Error(`Attestation txId (${attestationParams.txId}) does not match escrow/txId (${txIdFromEscrowId}). ` +
+                    `Refusing to release escrow with mismatched attestation.`);
+            }
+            // If runtime does NOT handle attestation internally but EASHelper exists, verify here.
+            // Otherwise, pass attestationUID down so BlockchainRuntime can enforce/record.
+            if (!runtimeSupportsAttestationFlag && this.easHelper) {
+                await this.easHelper.verifyAndRecordForRelease(attestationParams.txId, attestationParams.attestationUID);
+            }
+        }
+        return this.runtime.releaseEscrow(escrowId, attestationParams?.attestationUID);
+    }
+    /**
+     * Get escrow balance.
+     *
+     * Returns formatted balance string (e.g., "100.00 USDC").
+     *
+     * @param escrowId - Escrow ID
+     * @returns Formatted balance
+     * @throws {Error} If escrow not found
+     *
+     * @example
+     * ```typescript
+     * const balance = await adapter.getEscrowBalance(escrowId);
+     * console.log(balance); // "100.00 USDC"
+     * ```
+     */
+    async getEscrowBalance(escrowId) {
+        const balance = await this.runtime.getEscrowBalance(escrowId);
+        return this.formatAmount(balance);
+    }
+    /**
+     * Get transaction details.
+     *
+     * Returns the full transaction object from the runtime.
+     *
+     * @param txId - Transaction ID
+     * @returns Transaction object or null if not found
+     *
+     * @example
+     * ```typescript
+     * const tx = await adapter.getTransaction(txId);
+     * console.log('State:', tx?.state);
+     * console.log('Amount:', tx?.amount);
+     * ```
+     */
+    async getTransaction(txId) {
+        return this.runtime.getTransaction(txId);
+    }
+}
+exports.IntermediateAdapter = IntermediateAdapter;
+//# sourceMappingURL=IntermediateAdapter.js.map

package/dist/adapters/IntermediateAdapter.js.map

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

package/dist/adapters/StandardAdapter.d.ts

@@ -0,0 +1,211 @@
+/**
+ * StandardAdapter - Balanced API for developers with some protocol knowledge
+ *
+ * Provides more control than BasicAdapter while still offering convenience:
+ * - Explicit transaction lifecycle methods
+ * - Direct escrow operations
+ * - State transition control
+ *
+ * Use this adapter when you need fine-grained control but still want
+ * user-friendly input parsing and validation.
+ *
+ * @module adapters/StandardAdapter
+ */
+import { BaseAdapter } from './BaseAdapter';
+import { IACTPRuntime } from '../runtime/IACTPRuntime';
+import { MockTransaction, TransactionState } from '../runtime/types/MockState';
+import { EASHelper } from '../protocol/EASHelper';
+/**
+ * Parameters for creating a transaction (standard level).
+ *
+ * More explicit than BasicPayParams but still with smart defaults.
+ */
+export interface StandardTransactionParams {
+    /** Provider's Ethereum address */
+    provider: string;
+    /** Amount in user-friendly format ("100", "100.50", "100 USDC") */
+    amount: string | number;
+    /** Optional: Deadline as relative time ("+24h") or Unix timestamp. Defaults to +24h */
+    deadline?: string | number;
+    /** Optional: Dispute window in seconds. Defaults to 172800 (2 days) */
+    disputeWindow?: number;
+    /** Optional: Service description */
+    serviceDescription?: string;
+}
+/**
+ * StandardAdapter - Balanced API for transaction lifecycle control.
+ *
+ * Provides explicit methods for each stage of the ACTP lifecycle:
+ * - `createTransaction()` - Create transaction without escrow
+ * - `linkEscrow()` - Link escrow (auto-transitions to COMMITTED)
+ * - `transitionState()` - Manually transition state
+ * - `releaseEscrow()` - Release funds to provider
+ * - `getEscrowBalance()` - Check escrow balance
+ * - `getTransaction()` - Get transaction details
+ *
+ * @example
+ * ```typescript
+ * const client = await ACTPClient.create({ mode: 'mock' });
+ *
+ * // Create transaction (INITIATED state)
+ * const txId = await client.standard.createTransaction({
+ *   provider: '0xProvider123',
+ *   amount: '100',
+ *   deadline: '+7d',
+ * });
+ *
+ * // Link escrow (auto-transitions to COMMITTED)
+ * await client.standard.linkEscrow(txId, '100');
+ *
+ * // Provider delivers
+ * await client.standard.transitionState(txId, 'DELIVERED');
+ *
+ * // Release funds after dispute window
+ * await client.standard.releaseEscrow(escrowId);
+ * ```
+ */
+export declare class StandardAdapter extends BaseAdapter {
+    private runtime;
+    private easHelper?;
+    /**
+     * Creates a new StandardAdapter instance.
+     *
+     * @param runtime - ACTP runtime implementation (MockRuntime or BlockchainRuntime)
+     * @param requesterAddress - The requester's Ethereum address
+     * @param easHelper - Optional EAS helper for attestation verification (SECURITY FIX C-4)
+     */
+    constructor(runtime: IACTPRuntime, requesterAddress: string, easHelper?: EASHelper | undefined);
+    /**
+     * Create a transaction (INITIATED state, no escrow yet).
+     *
+     * Unlike `basic.pay()`, this only creates the transaction
+     * without linking escrow. You must call `linkEscrow()` separately.
+     *
+     * @param params - Transaction parameters
+     * @returns Transaction ID
+     * @throws {ValidationError} If inputs are invalid
+     *
+     * @example
+     * ```typescript
+     * const txId = await adapter.createTransaction({
+     *   provider: '0xProvider123',
+     *   amount: '100',
+     *   deadline: '+24h',
+     * });
+     * ```
+     */
+    createTransaction(params: StandardTransactionParams): Promise<string>;
+    /**
+     * Link escrow to a transaction.
+     *
+     * Automatically transitions INITIATED or QUOTED → COMMITTED.
+     * Deducts funds from requester and locks in escrow.
+     *
+     * @param txId - Transaction ID
+     * @returns Escrow ID
+     * @throws {Error} If transaction not found or in wrong state
+     *
+     * @example
+     * ```typescript
+     * const escrowId = await adapter.linkEscrow(txId);
+     * ```
+     */
+    linkEscrow(txId: string): Promise<string>;
+    /**
+     * Transition transaction to a new state.
+     *
+     * Validates the transition against the ACTP 8-state machine.
+     *
+     * Valid transitions:
+     * - INITIATED → QUOTED, COMMITTED, CANCELLED
+     * - QUOTED → COMMITTED, CANCELLED
+     * - COMMITTED → IN_PROGRESS, DELIVERED, CANCELLED
+     * - IN_PROGRESS → DELIVERED, CANCELLED
+     * - DELIVERED → SETTLED, DISPUTED
+     * - DISPUTED → SETTLED
+     *
+     * @param txId - Transaction ID
+     * @param newState - Target state
+     * @throws {Error} If transition is invalid
+     *
+     * @example
+     * ```typescript
+     * // Provider marks work as delivered
+     * await adapter.transitionState(txId, 'DELIVERED');
+     * ```
+     */
+    transitionState(txId: string, newState: TransactionState): Promise<void>;
+    /**
+     * Release escrow funds to the provider.
+     *
+     * Can only be called when transaction is in DELIVERED state
+     * and dispute window has expired.
+     *
+     * SECURITY FIX (C-4 + HIGH-5): MANDATORY attestation verification before release.
+     * When EASHelper is available (testnet/mainnet modes), attestation verification
+     * is REQUIRED - not optional. This prevents releasing funds without proper
+     * delivery proof.
+     *
+     * Verifications performed:
+     * - Attestation exists and is not revoked
+     * - Attestation belongs to this transaction (prevents replay attacks)
+     * - Attestation has not been used for a different transaction
+     *
+     * @param escrowId - Escrow ID
+     * @param attestationParams - Attestation verification params (REQUIRED when EASHelper available)
+     * @param attestationParams.txId - Transaction ID (bytes32)
+     * @param attestationParams.attestationUID - Attestation UID (bytes32)
+     * @throws {Error} If escrow not found or dispute window active
+     * @throws {Error} If EASHelper is available but attestationParams not provided (HIGH-5)
+     * @throws {Error} If attestation verification fails
+     *
+     * @example
+     * ```typescript
+     * // With attestation verification (REQUIRED in testnet/mainnet)
+     * await adapter.releaseEscrow(escrowId, {
+     *   txId: '0x...',
+     *   attestationUID: '0x...'
+     * });
+     *
+     * // Mock mode only (no attestation required)
+     * await adapter.releaseEscrow(escrowId);
+     * ```
+     */
+    releaseEscrow(escrowId: string, attestationParams?: {
+        txId: string;
+        attestationUID: string;
+    }): Promise<void>;
+    /**
+     * Get escrow balance.
+     *
+     * Returns formatted balance string (e.g., "100.00 USDC").
+     *
+     * @param escrowId - Escrow ID
+     * @returns Formatted balance
+     * @throws {Error} If escrow not found
+     *
+     * @example
+     * ```typescript
+     * const balance = await adapter.getEscrowBalance(escrowId);
+     * console.log(balance); // "100.00 USDC"
+     * ```
+     */
+    getEscrowBalance(escrowId: string): Promise<string>;
+    /**
+     * Get transaction details.
+     *
+     * Returns the full transaction object from the runtime.
+     *
+     * @param txId - Transaction ID
+     * @returns Transaction object or null if not found
+     *
+     * @example
+     * ```typescript
+     * const tx = await adapter.getTransaction(txId);
+     * console.log('State:', tx?.state);
+     * console.log('Amount:', tx?.amount);
+     * ```
+     */
+    getTransaction(txId: string): Promise<MockTransaction | null>;
+}
+//# sourceMappingURL=StandardAdapter.d.ts.map