@agirails/sdk 2.5.2 → 2.5.4

package/src/types/state.ts

@@ -1,87 +0,0 @@
-/**
- * ACTP State Machine
- * Reference: Yellow Paper §3.2
- */
-
-export enum State {
-  INITIATED = 0,
-  QUOTED = 1,
-  COMMITTED = 2,
-  IN_PROGRESS = 3,
-  DELIVERED = 4,
-  SETTLED = 5,
-  DISPUTED = 6,
-  CANCELLED = 7
-}
-
-export class StateMachine {
-  /**
-   * Valid state transitions per Yellow Paper §3.2.2
-   *
-   * SECURITY FIX (AUDIT-2026-02): State machine must match ACTPKernel contract exactly
-   *
-   * Per on-chain ACTPKernel contract:
-   * - COMMITTED must go through IN_PROGRESS before DELIVERED (cannot skip)
-   * - DISPUTED can transition to SETTLED or CANCELLED (admin/pauser can cancel disputes)
-   * - IN_PROGRESS can transition to DELIVERED or CANCELLED (not DISPUTED)
-   */
-  private static readonly TRANSITIONS: Record<State, State[]> = {
-    [State.INITIATED]: [State.QUOTED, State.COMMITTED, State.CANCELLED], // Allow direct INITIATED → COMMITTED (AIP-3)
-    [State.QUOTED]: [State.COMMITTED, State.CANCELLED],
-    // AUDIT FIX: COMMITTED cannot skip to DELIVERED - must go through IN_PROGRESS first
-    [State.COMMITTED]: [State.IN_PROGRESS, State.CANCELLED],
-    // IN_PROGRESS can transition to DELIVERED or CANCELLED
-    [State.IN_PROGRESS]: [State.DELIVERED, State.CANCELLED],
-    [State.DELIVERED]: [State.SETTLED, State.DISPUTED],
-    // AUDIT FIX: DISPUTED can also transition to CANCELLED (admin/pauser emergency cancellation)
-    [State.DISPUTED]: [State.SETTLED, State.CANCELLED],
-    [State.SETTLED]: [], // Terminal state
-    [State.CANCELLED]: [] // Terminal state
-  };
-
-  /**
-   * Check if state transition is valid
-   */
-  static isValidTransition(from: State, to: State): boolean {
-    return this.TRANSITIONS[from]?.includes(to) ?? false;
-  }
-
-  /**
-   * Check if state is terminal (no further transitions)
-   */
-  static isTerminalState(state: State): boolean {
-    return state === State.SETTLED || state === State.CANCELLED;
-  }
-
-  /**
-   * Get human-readable state name
-   */
-  static getStateName(state: State): string {
-    return State[state];
-  }
-
-  /**
-   * Get all valid next states from current state
-   */
-  static getNextValidStates(currentState: State): State[] {
-    return this.TRANSITIONS[currentState] || [];
-  }
-
-  /**
-   * Validate state transition or throw error
-   */
-  static validateTransition(from: State, to: State): void {
-    if (!this.isValidTransition(from, to)) {
-      const validStates = this.getNextValidStates(from)
-        .map(s => State[s])
-        .join(', ');
-
-      throw new Error(
-        `Invalid state transition: ${State[from]} → ${State[to]}. ` +
-        `Valid transitions from ${State[from]}: ${validStates || 'none (terminal state)'}`
-      );
-    }
-  }
-}
-
-

package/src/types/transaction.ts

@@ -1,69 +0,0 @@
-import { State } from './state';
-
-/**
- * ACTP Transaction
- * Reference: Yellow Paper §3.1
- */
-export interface Transaction {
-  txId: string;
-  requester: string;
-  provider: string;
-  amount: bigint;
-  state: State;
-  createdAt: number;
-  updatedAt: number;
-  deadline: number;
-  disputeWindow: number;
-  escrowContract: string;
-  escrowId: string;
-  serviceHash: string;
-  attestationUID: string;
-  metadata: string;
-  platformFeeBpsLocked: number;
-  /**
-   * ERC-8004 agent token ID (optional).
-   * 0 or undefined = not an ERC-8004 agent.
-   * See ADR-001 for architectural rationale.
-   */
-  agentId?: string;
-}
-
-/**
- * Parameters for creating a new transaction
- */
-export interface CreateTransactionParams {
-  provider: string;
-  requester: string;
-  amount: bigint;
-  deadline: number;
-  disputeWindow: number;
-  metadata?: string;
-  /**
-   * ERC-8004 agent token ID (optional).
-   * Set to 0 or omit if provider is not registered in ERC-8004 Identity Registry.
-   * See ADR-001 for architectural rationale.
-   */
-  agentId?: string;
-}
-
-/**
- * Dispute resolution split
- */
-export interface DisputeResolution {
-  requesterAmount: bigint;
-  providerAmount: bigint;
-  mediatorAmount: bigint;
-  mediator?: string;
-}
-
-/**
- * Economic parameters (fee structure)
- */
-export interface EconomicParams {
-  baseFeeNumerator: number;
-  baseFeeDenominator: number;
-  feeRecipient: string;
-  requesterPenaltyBps: number;
-  providerPenaltyBps: number;
-}
-

package/src/types/x402.ts

@@ -1,251 +0,0 @@
-/**
- * X402 Protocol Types and Constants
- *
- * Defines types for the HTTP 402 Payment Required protocol implementation.
- * X402 enables atomic, instant API payments - NO escrow, NO state machine.
- *
- * Key difference from ACTP:
- * - ACTP: escrow → state machine → disputes → explicit release
- * - x402: atomic payment → instant settlement → done
- *
- * Flow:
- * 1. Client requests protected HTTPS endpoint → gets 402 response
- * 2. Parse X-Payment-* headers (address, amount, network, deadline)
- * 3. Execute atomic USDC transfer to provider (no escrow!)
- * 4. Retry request with tx hash as proof
- * 5. Return response - payment complete, no release needed
- *
- * Use x402 for: Simple API calls, instant delivery, low-value transactions
- * Use ACTP for: Complex services, dispute protection, high-value transactions
- *
- * @module types/x402
- */
-
-// ============================================================================
-// X402 Header Constants
-// ============================================================================
-
-/**
- * Standard X402 payment headers sent in 402 responses.
- *
- * These headers inform the client how to pay for the requested resource.
- */
-export const X402_HEADERS = {
-  /** Indicates payment is required (must be "true") */
-  REQUIRED: 'x-payment-required',
-  /** Provider's wallet address (0x-prefixed) */
-  ADDRESS: 'x-payment-address',
-  /** Amount in USDC wei (6 decimals) */
-  AMOUNT: 'x-payment-amount',
-  /** Network identifier (base-mainnet or base-sepolia) */
-  NETWORK: 'x-payment-network',
-  /** Token type (currently only USDC) */
-  TOKEN: 'x-payment-token',
-  /** Unix timestamp deadline for payment */
-  DEADLINE: 'x-payment-deadline',
-  /** Optional: Dispute window in seconds */
-  DISPUTE_WINDOW: 'x-dispute-window',
-  /** Optional: Service identifier for tracking */
-  SERVICE_ID: 'x-service-id',
-} as const;
-
-/**
- * Proof headers sent when retrying with payment.
- *
- * After creating an ACTP transaction, the client includes these
- * headers to prove payment was made.
- */
-export const X402_PROOF_HEADERS = {
-  /** ACTP transaction ID (bytes32 hex) */
-  TX_ID: 'x-payment-tx-id',
-  /** ACTP escrow ID (bytes32 hex) */
-  ESCROW_ID: 'x-payment-escrow-id',
-} as const;
-
-// ============================================================================
-// X402 Types
-// ============================================================================
-
-/** Supported networks for x402 payments */
-export type X402Network = 'base-mainnet' | 'base-sepolia';
-
-/** Supported tokens (currently only USDC) */
-export type X402Token = 'USDC';
-
-/**
- * Parsed payment headers from HTTP 402 response.
- *
- * Contains all information needed to create an ACTP transaction
- * for the requested resource.
- */
-export interface X402PaymentHeaders {
-  /** Whether payment is required (always true for valid 402) */
-  required: boolean;
-
-  /** Provider's wallet address (0x-prefixed, 42 chars) */
-  paymentAddress: string;
-
-  /** Amount in USDC wei (6 decimals, as string) */
-  amount: string;
-
-  /** Target network */
-  network: X402Network;
-
-  /** Token type */
-  token: X402Token;
-
-  /** Unix timestamp deadline for accepting payment */
-  deadline: number;
-
-  /** Optional: Dispute window in seconds */
-  disputeWindow?: number;
-
-  /** Optional: Service identifier for tracking/debugging */
-  serviceId?: string;
-}
-
-// ============================================================================
-// X402 Error Handling
-// ============================================================================
-
-/**
- * Error codes for X402 protocol failures.
- *
- * Used to identify specific error types and enable proper error handling.
- */
-export enum X402ErrorCode {
-  /** Response status was not 402 */
-  NOT_402_RESPONSE = 'NOT_402_RESPONSE',
-
-  /** Required X-Payment-* headers are missing */
-  MISSING_HEADERS = 'MISSING_HEADERS',
-
-  /** X-Payment-Amount is invalid (not a number, negative, etc.) */
-  INVALID_AMOUNT = 'INVALID_AMOUNT',
-
-  /** X-Payment-Address is not a valid Ethereum address */
-  INVALID_ADDRESS = 'INVALID_ADDRESS',
-
-  /** X-Payment-Network is not a recognized network */
-  INVALID_NETWORK = 'INVALID_NETWORK',
-
-  /** Server's network doesn't match client's expected network */
-  NETWORK_MISMATCH = 'NETWORK_MISMATCH',
-
-  /** Failed to create ACTP transaction or link escrow */
-  PAYMENT_FAILED = 'PAYMENT_FAILED',
-
-  /** Retry request with proof headers failed */
-  RETRY_FAILED = 'RETRY_FAILED',
-
-  /** X-Payment-Deadline has already passed */
-  DEADLINE_PASSED = 'DEADLINE_PASSED',
-
-  /** HTTPS protocol required but HTTP used */
-  INSECURE_PROTOCOL = 'INSECURE_PROTOCOL',
-}
-
-/**
- * Custom error for X402 protocol failures.
- *
- * Provides structured error information for debugging and error handling.
- *
- * @example
- * ```typescript
- * try {
- *   await x402Adapter.pay({ to: 'https://api.example.com', amount: '10' });
- * } catch (error) {
- *   if (error instanceof X402Error) {
- *     if (error.code === X402ErrorCode.NETWORK_MISMATCH) {
- *       console.error('Wrong network:', error.message);
- *     }
- *   }
- * }
- * ```
- */
-export class X402Error extends Error {
-  public readonly name = 'X402Error';
-
-  /**
-   * Creates a new X402Error.
-   *
-   * @param message - Human-readable error message
-   * @param code - Error code for programmatic handling
-   * @param response - Optional HTTP response that triggered the error
-   */
-  constructor(
-    message: string,
-    public readonly code: X402ErrorCode,
-    public readonly response?: Response
-  ) {
-    super(message);
-
-    // Maintains proper stack trace in V8 environments
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, X402Error);
-    }
-  }
-
-  /**
-   * Creates a detailed error message with code.
-   */
-  toString(): string {
-    return `X402Error [${this.code}]: ${this.message}`;
-  }
-}
-
-// ============================================================================
-// Fee Types
-// ============================================================================
-
-/**
- * Fee breakdown for x402 payments routed through X402Relay.
- *
- * Shows how the gross amount was split between provider and platform.
- * Fee = max(grossAmount * feeBps / 10000, MIN_FEE).
- *
- * NOTE: This is a client-side **estimate** computed from the configured
- * platformFeeBps. The on-chain X402Relay contract is the source of truth.
- * If an admin updates the relay's fee rate, this estimate may diverge
- * from the actual on-chain split until the SDK config is refreshed.
- */
-export interface X402FeeBreakdown {
-  /** Total amount from the 402 header (USDC wei, 6 decimals) */
-  grossAmount: string;
-
-  /** Estimated amount provider received: grossAmount - platformFee */
-  providerNet: string;
-
-  /** Estimated amount treasury received: max(feeBps%, $0.05) */
-  platformFee: string;
-
-  /** Fee rate used for estimate (basis points, e.g. 100 = 1%) */
-  feeBps: number;
-
-  /** True — this is a client-side estimate, not read from chain */
-  estimated: true;
-}
-
-// ============================================================================
-// Type Guards
-// ============================================================================
-
-/**
- * Type guard to check if an error is an X402Error.
- *
- * @param error - Error to check
- * @returns True if error is X402Error
- */
-export function isX402Error(error: unknown): error is X402Error {
-  return error instanceof X402Error;
-}
-
-/**
- * Validates that a network string is a valid X402Network.
- *
- * @param network - Network string to validate
- * @returns True if valid X402Network
- */
-export function isValidX402Network(network: string): network is X402Network {
-  return network === 'base-mainnet' || network === 'base-sepolia';
-}