@agirails/sdk 2.0.1-beta → 2.0.2

package/src/adapters/IntermediateAdapter.ts

@@ -0,0 +1,316 @@
+/**
+ * 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, ValidationError, DEFAULT_DISPUTE_WINDOW_SECONDS } 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 class IntermediateAdapter extends 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(
+    private runtime: IACTPRuntime,
+    requesterAddress: string,
+    private easHelper?: EASHelper
+  ) {
+    super(requesterAddress);
+  }
+
+  /**
+   * 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: IntermediateTransactionParams): Promise<string> {
+    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 ValidationError('Cannot create transaction with yourself as provider');
+    }
+
+    if (deadline <= currentTime) {
+      throw new 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: string): Promise<string> {
+    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: string, newState: TransactionState): Promise<void> {
+    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: string,
+    attestationParams?: { txId: string; attestationUID: string }
+  ): Promise<void> {
+    // Determine whether the underlying runtime requires attestation.
+    // BlockchainRuntime exposes isAttestationRequired(), but it's not part of the generic interface.
+    const runtimeAny = this.runtime as any;
+    const runtimeSupportsAttestationFlag =
+      typeof runtimeAny?.isAttestationRequired === 'function';
+
+    const attestationRequired: boolean = 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: string): Promise<string> {
+    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: string): Promise<MockTransaction | null> {
+    return this.runtime.getTransaction(txId);
+  }
+}

package/src/adapters/index.ts

@@ -0,0 +1,25 @@
+/**
+ * Adapter Layer - Bridges user-friendly API to protocol-level SDK
+ *
+ * This module exports all adapter classes and types for the Three-Level API:
+ * - BaseAdapter: Abstract base with shared utilities
+ * - BeginnerAdapter: High-level, opinionated API
+ * - IntermediateAdapter: Balanced control API
+ *
+ * @module adapters
+ */
+
+export {
+  BaseAdapter,
+  ValidationError,
+  DEFAULT_DISPUTE_WINDOW_SECONDS,
+  DEFAULT_DEADLINE_SECONDS,
+  MIN_AMOUNT_WEI,
+  MAX_DEADLINE_HOURS,
+  MAX_DEADLINE_DAYS,
+} from './BaseAdapter';
+export { BeginnerAdapter, BeginnerPayParams, BeginnerPayResult } from './BeginnerAdapter';
+export { IntermediateAdapter, IntermediateTransactionParams } from './IntermediateAdapter';
+
+// Re-export runtime interface for convenience
+export { IACTPRuntime, CreateTransactionParams } from '../runtime/IACTPRuntime';

package/src/builders/DeliveryProofBuilder.ts

@@ -19,9 +19,10 @@ import { AIP4DeliveryProofTypes, AIP4DeliveryProofData, EIP712Domain } from '../
 
 /**
  * AGIRAILS Delivery Schema UID (Base Sepolia)
- * TODO: Update after schema deployment
+ * Deployed 2025-11-23 - AIP-4 delivery proof schema
+ * Schema: bytes32 txId, string resultCID, bytes32 resultHash, uint256 deliveredAt
  */
-export const AGIRAILS_DELIVERY_SCHEMA_UID = '0x0000000000000000000000000000000000000000000000000000000000000000'; // PENDING
+export const AGIRAILS_DELIVERY_SCHEMA_UID = '0x1b0ebdf0bd20c28ec9d5362571ce8715a55f46e81c3de2f9b0d8e1b95fb5ffce';
 
 /**
  * Delivery proof build parameters

package/src/cli/commands/balance.ts

@@ -0,0 +1,110 @@
+/**
+ * Balance Command - Check USDC balance
+ *
+ * Shows the USDC balance for the current user or a specified address.
+ *
+ * @module cli/commands/balance
+ */
+
+import { Command } from 'commander';
+import { Output, ExitCode } from '../utils/output';
+import { createClient, mapError } from '../utils/client';
+import { loadConfig } from '../utils/config';
+
+// ============================================================================
+// Command Definition
+// ============================================================================
+
+export function createBalanceCommand(): Command {
+  const cmd = new Command('balance')
+    .description('Check USDC balance')
+    .argument('[address]', 'Address to check (defaults to your address)')
+    .option('--json', 'Output as JSON')
+    .option('-q, --quiet', 'Output only the balance amount')
+    .action(async (address, options) => {
+      const output = new Output(
+        options.json ? 'json' : options.quiet ? 'quiet' : 'human'
+      );
+
+      try {
+        await runBalance(address, output);
+      } catch (error) {
+        const structuredError = mapError(error);
+        output.errorResult({
+          code: structuredError.code,
+          message: structuredError.message,
+          details: structuredError.details,
+        });
+        process.exit(ExitCode.ERROR);
+      }
+    });
+
+  return cmd;
+}
+
+// ============================================================================
+// Implementation
+// ============================================================================
+
+async function runBalance(
+  address: string | undefined,
+  output: Output
+): Promise<void> {
+  // Load config to get default address
+  const config = loadConfig();
+
+  // Use specified address or default to config address
+  const targetAddress = address || config.address;
+
+  // Validate address format
+  if (!/^0x[a-fA-F0-9]{40}$/.test(targetAddress)) {
+    throw new Error(
+      `Invalid address format: "${targetAddress}"\n` +
+        'Expected 0x-prefixed 40-character hex string.'
+    );
+  }
+
+  // Create client and get balance
+  const client = await createClient();
+  const balanceWei = await client.getBalance(targetAddress.toLowerCase());
+
+  // Format balance
+  const balanceFormatted = formatUsdc(balanceWei);
+  const isOwnAddress = targetAddress.toLowerCase() === config.address.toLowerCase();
+
+  output.result(
+    {
+      address: targetAddress,
+      balance: `${balanceFormatted} USDC`,
+      balanceWei,
+      isYou: isOwnAddress,
+    },
+    { quietKey: 'balance' }
+  );
+
+  // Additional info in human mode
+  if (balanceWei === '0') {
+    output.blank();
+    output.warning('Balance is zero.');
+    if (config.mode === 'mock') {
+      output.print('  Mint tokens: actp mint ' + targetAddress + ' 1000');
+    }
+  }
+}
+
+/**
+ * Format USDC amount from wei to decimal with commas
+ */
+function formatUsdc(weiAmount: string): string {
+  const amount = BigInt(weiAmount);
+  const whole = amount / 1_000_000n;
+  const decimal = amount % 1_000_000n;
+  const decimalStr = decimal.toString().padStart(6, '0').slice(0, 2);
+
+  // Add thousands separators
+  const wholeFormatted = whole.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+
+  return `${wholeFormatted}.${decimalStr}`;
+}
+
+export { runBalance };