@oobe-protocol-labs/synapse-sap-sdk 0.6.2 → 0.7.0

package/src/utils/escrow-validation.ts

@@ -0,0 +1,301 @@
+/**
+ * @module utils/escrow-validation
+ * @description Server-side escrow validation pipeline.
+ *
+ * Provides typed helpers to validate escrow state before settlement
+ * and to build the correct SPL `AccountMeta[]` for token escrows.
+ *
+ * @category Utils
+ * @since v0.6.4
+ */
+
+import {
+  PublicKey,
+  type Connection,
+  type AccountMeta,
+} from "@solana/web3.js";
+import { BN } from "@coral-xyz/anchor";
+import { findATA } from "./rpc-strategy";
+import { deriveAgent, deriveEscrow } from "../pda";
+import { SapError } from "../errors";
+import type { EscrowAccountData } from "../types";
+
+// ═══════════════════════════════════════════════════════════════════
+//  Types
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * @interface SplAccountMeta
+ * @description Typed SPL account metadata for escrow operations.
+ * @category Utils
+ * @since v0.6.4
+ */
+export interface SplAccountMeta {
+  /** Account role in the escrow pipeline. */
+  readonly kind: "escrowAta" | "depositorAta" | "tokenMint" | "tokenProgram";
+  /** Account public key. */
+  readonly pubkey: PublicKey;
+  /** Whether this account is writable. */
+  readonly writable: boolean;
+}
+
+/**
+ * @interface EscrowValidationResult
+ * @description Result of server-side escrow state validation.
+ * @category Utils
+ * @since v0.6.4
+ */
+export interface EscrowValidationResult {
+  /** Whether the escrow is valid for settlement. */
+  readonly valid: boolean;
+  /** Escrow account data (if found). */
+  readonly escrow: EscrowAccountData | null;
+  /** Escrow PDA address. */
+  readonly escrowPda: PublicKey;
+  /** Agent PDA address. */
+  readonly agentPda: PublicKey;
+  /** Whether this is an SPL token escrow (vs SOL). */
+  readonly isSplEscrow: boolean;
+  /** Generated SPL account metas (empty for SOL escrows). */
+  readonly splAccounts: SplAccountMeta[];
+  /** Validation errors (empty when valid). */
+  readonly errors: string[];
+}
+
+// ═══════════════════════════════════════════════════════════════════
+//  Error
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * @name MissingEscrowAtaError
+ * @description Thrown when an SPL escrow operation is missing required
+ * Associated Token Accounts.
+ * @category Errors
+ * @since v0.6.4
+ */
+export class MissingEscrowAtaError extends SapError {
+  /** The ATA address that is missing. */
+  readonly ataAddress: string;
+  /** Which side is missing: depositor or escrow. */
+  readonly side: "depositor" | "escrow";
+
+  constructor(ataAddress: string, side: "depositor" | "escrow") {
+    super(
+      `Missing ${side} ATA: ${ataAddress}. ` +
+        `Settlement mode is Escrow/SPL but the Associated Token Account does not exist. ` +
+        `The ${side} must create the ATA before escrow operations.`,
+      "SAP_MISSING_ESCROW_ATA",
+    );
+    this.name = "MissingEscrowAtaError";
+    this.ataAddress = ataAddress;
+    this.side = side;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════
+//  Validation
+// ═══════════════════════════════════════════════════════════════════
+
+/** Standard SPL Token program ID. */
+const TOKEN_PROGRAM_ID_STR = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
+
+/**
+ * @name validateEscrowState
+ * @description Validates that an escrow is in a correct state for settlement.
+ *
+ * Checks:
+ * - Escrow PDA exists on-chain
+ * - If SPL: depositor ATA exists, escrow ATA exists, token mint matches
+ * - Balance >= requested settlement amount
+ * - Escrow is not expired
+ * - Max calls not exceeded
+ *
+ * @param connection  - Solana RPC connection.
+ * @param agentWallet - The agent's wallet public key.
+ * @param depositorWallet - The depositor's wallet public key.
+ * @param fetchEscrow - Callback to fetch escrow data (avoids coupling to SapProgram).
+ * @param opts
+ * @param opts.callsToSettle - Number of calls to validate affordability for.
+ *
+ * @returns A detailed {@link EscrowValidationResult}.
+ *
+ * @category Utils
+ * @since v0.6.4
+ *
+ * @example
+ * ```ts
+ * const result = await validateEscrowState(
+ *   connection,
+ *   agentWallet,
+ *   depositorWallet,
+ *   (pda) => client.escrow.fetchByPda(pda),
+ *   { callsToSettle: 5 },
+ * );
+ *
+ * if (!result.valid) {
+ *   console.error("Escrow validation failed:", result.errors);
+ * }
+ * ```
+ */
+export async function validateEscrowState(
+  connection: Connection,
+  agentWallet: PublicKey,
+  depositorWallet: PublicKey,
+  fetchEscrow: (escrowPda: PublicKey) => Promise<EscrowAccountData | null>,
+  opts?: { callsToSettle?: number },
+): Promise<EscrowValidationResult> {
+  const [agentPda] = deriveAgent(agentWallet);
+  const [escrowPda] = deriveEscrow(agentPda, depositorWallet);
+  const errors: string[] = [];
+
+  // 1. Fetch escrow
+  const escrow = await fetchEscrow(escrowPda);
+  if (!escrow) {
+    return {
+      valid: false,
+      escrow: null,
+      escrowPda,
+      agentPda,
+      isSplEscrow: false,
+      splAccounts: [],
+      errors: [`Escrow not found at ${escrowPda.toBase58()}`],
+    };
+  }
+
+  // 2. Check expiry
+  if (escrow.expiresAt.gt(new BN(0))) {
+    const now = Math.floor(Date.now() / 1000);
+    if (escrow.expiresAt.lt(new BN(now))) {
+      errors.push(`Escrow expired at ${escrow.expiresAt.toString()}`);
+    }
+  }
+
+  // 3. Check balance / calls
+  const callsToSettle = opts?.callsToSettle ?? 1;
+  const costForCalls = escrow.pricePerCall.mul(new BN(callsToSettle));
+  if (escrow.balance.lt(costForCalls)) {
+    errors.push(
+      `Insufficient balance: ${escrow.balance.toString()} < ${costForCalls.toString()} (${callsToSettle} calls × ${escrow.pricePerCall.toString()})`,
+    );
+  }
+
+  // 4. Check max calls
+  if (escrow.maxCalls.gt(new BN(0))) {
+    const remaining = escrow.maxCalls.sub(escrow.totalCallsSettled);
+    if (remaining.lt(new BN(callsToSettle))) {
+      errors.push(
+        `Max calls exceeded: ${remaining.toString()} remaining but needs ${callsToSettle}`,
+      );
+    }
+  }
+
+  // 5. Determine if SPL
+  const isSplEscrow =
+    escrow.tokenMint !== null &&
+    escrow.tokenMint.toBase58() !== "11111111111111111111111111111111";
+
+  // 6. Build SPL accounts (if SPL escrow)
+  const splAccounts: SplAccountMeta[] = [];
+  if (isSplEscrow) {
+    const mint = escrow.tokenMint!;
+    const depositorAta = findATA(depositorWallet, mint);
+    const escrowAta = findATA(escrowPda, mint);
+
+    // Verify depositor ATA exists
+    const depositorAtaInfo = await connection.getAccountInfo(depositorAta);
+    if (!depositorAtaInfo) {
+      errors.push(`Depositor ATA does not exist: ${depositorAta.toBase58()}`);
+    }
+
+    // Verify escrow ATA exists
+    const escrowAtaInfo = await connection.getAccountInfo(escrowAta);
+    if (!escrowAtaInfo) {
+      errors.push(`Escrow ATA does not exist: ${escrowAta.toBase58()}`);
+    }
+
+    // Verify mint matches
+    if (depositorAtaInfo) {
+      // SPL token account data: bytes 0-32 = mint
+      const ataMint = depositorAtaInfo.data.subarray(0, 32);
+      if (Buffer.from(ataMint).toString("hex") !== mint.toBuffer().toString("hex")) {
+        errors.push(`Depositor ATA mint mismatch: expected ${mint.toBase58()}`);
+      }
+    }
+
+    splAccounts.push(
+      { kind: "depositorAta", pubkey: depositorAta, writable: true },
+      { kind: "escrowAta", pubkey: escrowAta, writable: true },
+      { kind: "tokenMint", pubkey: mint, writable: false },
+      { kind: "tokenProgram", pubkey: new PublicKey(TOKEN_PROGRAM_ID_STR), writable: false },
+    );
+  }
+
+  return {
+    valid: errors.length === 0,
+    escrow,
+    escrowPda,
+    agentPda,
+    isSplEscrow,
+    splAccounts,
+    errors,
+  };
+}
+
+/**
+ * @name attachSplAccounts
+ * @description Build the typed `SplAccountMeta[]` for an SPL token escrow operation.
+ * Does NOT validate existence — use {@link validateEscrowState} for full validation.
+ *
+ * @param escrowPda      - The escrow PDA address.
+ * @param depositorWallet - The depositor's wallet public key.
+ * @param tokenMint      - The SPL token mint.
+ * @returns An array of typed {@link SplAccountMeta} for SPL escrow operations.
+ *
+ * @category Utils
+ * @since v0.6.4
+ *
+ * @example
+ * ```ts
+ * const splMetas = attachSplAccounts(escrowPda, depositorWallet, usdcMint);
+ *
+ * // Convert to Anchor-compatible AccountMeta[]
+ * const accountMetas = splMetas.map(m => ({
+ *   pubkey: m.pubkey,
+ *   isWritable: m.writable,
+ *   isSigner: false,
+ * }));
+ *
+ * await client.escrow.settle(depositor, calls, hash, accountMetas);
+ * ```
+ */
+export function attachSplAccounts(
+  escrowPda: PublicKey,
+  depositorWallet: PublicKey,
+  tokenMint: PublicKey,
+): SplAccountMeta[] {
+  return [
+    { kind: "depositorAta", pubkey: findATA(depositorWallet, tokenMint), writable: true },
+    { kind: "escrowAta", pubkey: findATA(escrowPda, tokenMint), writable: true },
+    { kind: "tokenMint", pubkey: tokenMint, writable: false },
+    { kind: "tokenProgram", pubkey: new PublicKey(TOKEN_PROGRAM_ID_STR), writable: false },
+  ];
+}
+
+/**
+ * @name toAccountMetas
+ * @description Convert typed {@link SplAccountMeta} to Anchor-compatible
+ * `AccountMeta[]` for use with `.remainingAccounts()`.
+ *
+ * @param splMetas - Array of typed SPL account metas.
+ * @returns `AccountMeta[]` compatible with Anchor's `remainingAccounts`.
+ *
+ * @category Utils
+ * @since v0.6.4
+ */
+export function toAccountMetas(splMetas: SplAccountMeta[]): AccountMeta[] {
+  return splMetas.map((m) => ({
+    pubkey: m.pubkey,
+    isWritable: m.writable,
+    isSigner: false,
+  }));
+}

package/src/utils/index.ts

@@ -71,3 +71,31 @@ export type {
   PriorityFeeConfig,
   SettleOptions,
 } from "./priority-fee";
+
+// ── v0.6.4  Escrow Validation & Merchant Middleware ──
+export {
+  validateEscrowState,
+  attachSplAccounts,
+  toAccountMetas,
+  MissingEscrowAtaError,
+} from "./escrow-validation";
+export type {
+  SplAccountMeta,
+  EscrowValidationResult,
+} from "./escrow-validation";
+
+export {
+  SapMerchantValidator,
+  parseX402Headers,
+} from "./merchant-validator";
+export type {
+  ParsedX402Headers,
+  MerchantValidationResult,
+} from "./merchant-validator";
+
+export { getX402DirectPayments } from "./x402-direct";
+export type {
+  X402DirectPayment,
+  SettlementPayload,
+  GetX402DirectOptions,
+} from "./x402-direct";

package/src/utils/merchant-validator.ts

@@ -0,0 +1,359 @@
+/**
+ * @module utils/merchant-validator
+ * @description Standard Synapse merchant middleware for x402 settlement.
+ *
+ * Reads `X-Payment-*` headers from incoming HTTP requests, validates
+ * the escrow on-chain, auto-generates the correct `AccountMeta[]`,
+ * and throws explicit errors (e.g. {@link MissingEscrowAtaError})
+ * instead of letting the program return a generic crash.
+ *
+ * Designed for agents like Syra/Invoica that receive x402 payments.
+ *
+ * @category Utils
+ * @since v0.6.4
+ */
+
+import {
+  type PublicKey,
+  type Connection,
+  type AccountMeta,
+} from "@solana/web3.js";
+import { PublicKey as PK } from "@solana/web3.js";
+import { BN } from "@coral-xyz/anchor";
+import {
+  validateEscrowState,
+  toAccountMetas,
+  MissingEscrowAtaError,
+} from "./escrow-validation";
+import type {
+  EscrowValidationResult,
+} from "./escrow-validation";
+import { SapValidationError } from "../errors";
+import type { EscrowAccountData } from "../types";
+
+// ═══════════════════════════════════════════════════════════════════
+//  Types
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * @interface ParsedX402Headers
+ * @description Parsed and typed x402 payment headers from incoming HTTP request.
+ * @category Utils
+ * @since v0.6.4
+ */
+export interface ParsedX402Headers {
+  /** x402 protocol identifier — must be "SAP-x402". */
+  readonly protocol: string;
+  /** Escrow PDA address. */
+  readonly escrowPda: PublicKey;
+  /** Agent PDA address. */
+  readonly agentPda: PublicKey;
+  /** Depositor wallet address. */
+  readonly depositorWallet: PublicKey;
+  /** Max calls allowed. */
+  readonly maxCalls: BN;
+  /** Price per call. */
+  readonly pricePerCall: BN;
+  /** SAP program ID. */
+  readonly programId: PublicKey;
+  /** Network identifier. */
+  readonly network: string;
+}
+
+/**
+ * @interface MerchantValidationResult
+ * @description Complete validation result for merchant-side x402 processing.
+ * @category Utils
+ * @since v0.6.4
+ */
+export interface MerchantValidationResult {
+  /** Whether the escrow is valid and ready for settlement. */
+  readonly valid: boolean;
+  /** Parsed x402 headers. */
+  readonly headers: ParsedX402Headers;
+  /** Full escrow validation result. */
+  readonly escrowValidation: EscrowValidationResult;
+  /** Pre-built AccountMeta[] for settlement TX (empty for SOL escrows). */
+  readonly accountMetas: AccountMeta[];
+  /** All validation errors. */
+  readonly errors: string[];
+}
+
+// ═══════════════════════════════════════════════════════════════════
+//  Header parsing
+// ═══════════════════════════════════════════════════════════════════
+
+/** Required x402 headers. */
+const REQUIRED_HEADERS = [
+  "X-Payment-Protocol",
+  "X-Payment-Escrow",
+  "X-Payment-Agent",
+  "X-Payment-Depositor",
+  "X-Payment-MaxCalls",
+  "X-Payment-PricePerCall",
+  "X-Payment-Program",
+  "X-Payment-Network",
+] as const;
+
+/**
+ * @name parseX402Headers
+ * @description Parse and validate x402 headers from an HTTP request.
+ *
+ * @param headers - HTTP headers object (case-insensitive key lookup).
+ * @returns Parsed x402 headers.
+ * @throws {SapValidationError} If required headers are missing or malformed.
+ *
+ * @category Utils
+ * @since v0.6.4
+ */
+export function parseX402Headers(
+  headers: Record<string, string | string[] | undefined>,
+): ParsedX402Headers {
+  // Normalize to case-insensitive
+  const normalized = new Map<string, string>();
+  for (const [key, value] of Object.entries(headers)) {
+    const val = Array.isArray(value) ? value[0] : value;
+    if (val !== undefined) {
+      normalized.set(key.toLowerCase(), val);
+    }
+  }
+
+  // Validate required headers present
+  const missing: string[] = [];
+  for (const h of REQUIRED_HEADERS) {
+    if (!normalized.has(h.toLowerCase())) {
+      missing.push(h);
+    }
+  }
+  if (missing.length > 0) {
+    throw new SapValidationError(
+      `Missing required x402 headers: ${missing.join(", ")}`,
+      "x402-headers",
+    );
+  }
+
+  const get = (key: string): string => normalized.get(key.toLowerCase())!;
+
+  // Validate protocol
+  const protocol = get("X-Payment-Protocol");
+  if (protocol !== "SAP-x402") {
+    throw new SapValidationError(
+      `Invalid X-Payment-Protocol: "${protocol}" (expected "SAP-x402")`,
+      "X-Payment-Protocol",
+    );
+  }
+
+  // Parse PublicKeys
+  let escrowPda: PublicKey;
+  let agentPda: PublicKey;
+  let depositorWallet: PublicKey;
+  let programId: PublicKey;
+  try {
+    escrowPda = new PK(get("X-Payment-Escrow"));
+    agentPda = new PK(get("X-Payment-Agent"));
+    depositorWallet = new PK(get("X-Payment-Depositor"));
+    programId = new PK(get("X-Payment-Program"));
+  } catch {
+    throw new SapValidationError(
+      "Malformed public key in x402 headers",
+      "x402-headers",
+    );
+  }
+
+  // Parse numeric values
+  const maxCallsStr = get("X-Payment-MaxCalls");
+  const pricePerCallStr = get("X-Payment-PricePerCall");
+  let maxCalls: BN;
+  let pricePerCall: BN;
+  try {
+    maxCalls = new BN(maxCallsStr);
+    pricePerCall = new BN(pricePerCallStr);
+  } catch {
+    throw new SapValidationError(
+      "Invalid numeric value in X-Payment-MaxCalls or X-Payment-PricePerCall",
+      "x402-headers",
+    );
+  }
+
+  return {
+    protocol,
+    escrowPda,
+    agentPda,
+    depositorWallet,
+    maxCalls,
+    pricePerCall,
+    programId,
+    network: get("X-Payment-Network"),
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════
+//  Merchant Validator
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * @name SapMerchantValidator
+ * @description Standard Synapse merchant middleware for x402 payment validation.
+ *
+ * Reads `X-Payment-*` headers, validates escrow state on-chain, generates
+ * correct `AccountMeta[]` for SPL token escrows, and throws explicit errors
+ * (e.g. {@link MissingEscrowAtaError}) when ATA accounts are missing.
+ *
+ * @category Utils
+ * @since v0.6.4
+ *
+ * @example
+ * ```ts
+ * const validator = new SapMerchantValidator(connection, fetchEscrow);
+ *
+ * // Express.js integration
+ * app.post("/api/v1/chat", async (req, res) => {
+ *   try {
+ *     const validation = await validator.validateRequest(req.headers, {
+ *       callsToSettle: 1,
+ *     });
+ *
+ *     if (!validation.valid) {
+ *       return res.status(402).json({ errors: validation.errors });
+ *     }
+ *
+ *     // Process request...
+ *
+ *     // Settle payment using pre-built account metas
+ *     await client.escrow.settle(
+ *       validation.headers.depositorWallet,
+ *       1,
+ *       serviceHash,
+ *       validation.accountMetas,
+ *     );
+ *
+ *     res.json({ result: "..." });
+ *   } catch (err) {
+ *     if (err instanceof MissingEscrowAtaError) {
+ *       return res.status(402).json({
+ *         error: err.message,
+ *         side: err.side,
+ *         ata: err.ataAddress,
+ *       });
+ *     }
+ *     throw err;
+ *   }
+ * });
+ * ```
+ */
+export class SapMerchantValidator {
+  private readonly connection: Connection;
+  private readonly fetchEscrow: (
+    escrowPda: PublicKey,
+  ) => Promise<EscrowAccountData | null>;
+
+  /**
+   * @param connection  - Solana RPC connection.
+   * @param fetchEscrow - Callback to fetch escrow account data by PDA.
+   *   Typically `(pda) => client.escrow.fetchByPda(pda).catch(() => null)`.
+   */
+  constructor(
+    connection: Connection,
+    fetchEscrow: (
+      escrowPda: PublicKey,
+    ) => Promise<EscrowAccountData | null>,
+  ) {
+    this.connection = connection;
+    this.fetchEscrow = fetchEscrow;
+  }
+
+  /**
+   * @name validateRequest
+   * @description Full validation pipeline for an incoming x402 request.
+   *
+   * Steps:
+   * 1. Parse `X-Payment-*` headers
+   * 2. Fetch escrow on-chain
+   * 3. Validate escrow state (balance, expiry, max calls)
+   * 4. If SPL escrow: validate ATAs exist and mint matches
+   * 5. Build `AccountMeta[]` for settlement TX
+   *
+   * @param headers - HTTP headers from the incoming request.
+   * @param opts
+   * @param opts.callsToSettle     - Number of calls to validate affordability for (default: 1).
+   * @param opts.throwOnMissingAta - Throw {@link MissingEscrowAtaError} instead of returning errors (default: true).
+   *
+   * @returns A complete {@link MerchantValidationResult}.
+   *
+   * @throws {SapValidationError} If headers are missing or malformed.
+   * @throws {MissingEscrowAtaError} If SPL ATAs are missing and `throwOnMissingAta` is true.
+   *
+   * @category Utils
+   * @since v0.6.4
+   */
+  async validateRequest(
+    headers: Record<string, string | string[] | undefined>,
+    opts?: {
+      callsToSettle?: number;
+      throwOnMissingAta?: boolean;
+    },
+  ): Promise<MerchantValidationResult> {
+    // 1. Parse headers
+    const parsed = parseX402Headers(headers);
+
+    // 2. Validate escrow state
+    const escrowValidation = await validateEscrowState(
+      this.connection,
+      parsed.agentPda,       // agentWallet derived inside validate
+      parsed.depositorWallet,
+      this.fetchEscrow,
+      { callsToSettle: opts?.callsToSettle ?? 1 },
+    );
+
+    // 3. Check for ATA errors and optionally throw
+    const throwOnMissingAta = opts?.throwOnMissingAta !== false;
+    if (throwOnMissingAta && escrowValidation.isSplEscrow) {
+      for (const error of escrowValidation.errors) {
+        if (error.includes("Depositor ATA does not exist")) {
+          const ataAddr = error.split(": ")[1] ?? "unknown";
+          throw new MissingEscrowAtaError(ataAddr, "depositor");
+        }
+        if (error.includes("Escrow ATA does not exist")) {
+          const ataAddr = error.split(": ")[1] ?? "unknown";
+          throw new MissingEscrowAtaError(ataAddr, "escrow");
+        }
+      }
+    }
+
+    // 4. Build account metas
+    const accountMetas = toAccountMetas(escrowValidation.splAccounts);
+
+    return {
+      valid: escrowValidation.valid,
+      headers: parsed,
+      escrowValidation,
+      accountMetas,
+      errors: escrowValidation.errors,
+    };
+  }
+
+  /**
+   * @name validateEscrow
+   * @description Validate escrow from pre-parsed headers (convenience method).
+   * Call this when you've already parsed the headers yourself.
+   *
+   * @param headers - Pre-parsed x402 headers.
+   * @param opts
+   * @returns The escrow validation result with pre-built account metas.
+   *
+   * @category Utils
+   * @since v0.6.4
+   */
+  async validateEscrow(
+    headers: ParsedX402Headers,
+    opts?: { callsToSettle?: number },
+  ): Promise<EscrowValidationResult> {
+    return validateEscrowState(
+      this.connection,
+      headers.agentPda,
+      headers.depositorWallet,
+      this.fetchEscrow,
+      opts,
+    );
+  }
+}