@oobe-protocol-labs/synapse-sap-sdk 0.13.0 → 0.14.0

package/src/utils/serialization.ts

@@ -1,98 +0,0 @@
-/**
- * @module utils/serialization
- * @description JSON-safe serialization helpers for on-chain account data.
- *
- * On-chain Anchor account objects contain `PublicKey` and `BN` instances
- * that are not JSON-serializable. These helpers convert them to plain
- * strings (`base58` and decimal `string`) recursively.
- *
- * @category Utils
- * @since v0.1.0
- *
- * @example
- * ```ts
- * import { serializeAccount } from "@synapse-sap/sdk/utils";
- *
- * const raw = await program.account.agent.fetch(pda);
- * const json = serializeAccount(raw);
- * // { authority: "GBL...", totalCalls: "42", ... }
- * ```
- */
-
-import { PublicKey } from "@solana/web3.js";
-import BN from "bn.js";
-
-/**
- * Recursively convert a single value for JSON serialization.
- *
- * - `PublicKey` → base58 string
- * - `BN` → decimal string
- * - `Uint8Array` / `Buffer` → hex string
- * - `Array` → recursed
- * - plain `object` → recursed via {@link serializeAccount}
- * - primitives → identity
- *
- * @name serializeValue
- * @description Transforms a single Anchor-typed value into its JSON-safe equivalent.
- * @param value - The value to serialize.
- * @returns The JSON-safe representation of `value`.
- * @category Utils
- * @since v0.1.0
- * @example
- * ```ts
- * import { serializeValue } from "@synapse-sap/sdk/utils";
- *
- * serializeValue(new PublicKey("11111111111111111111111111111111")); // "1111..."
- * serializeValue(new BN(42)); // "42"
- * ```
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function serializeValue(value: unknown): any {
-  if (value === null || value === undefined) return null;
-  if (value instanceof PublicKey) return value.toBase58();
-  if (BN.isBN(value)) return value.toString();
-  if (value instanceof Uint8Array || Buffer.isBuffer(value))
-    return Buffer.from(value).toString("hex");
-  if (Array.isArray(value)) return value.map(serializeValue);
-  if (typeof value === "object") {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    return serializeAccount(value as Record<string, any>);
-  }
-  return value;
-}
-
-/**
- * Serialize an entire on-chain account object to a JSON-safe shape.
- *
- * Iterates over each key and delegates to {@link serializeValue}.
- * Handles `PublicKey` → base58, `BN` → string, and nested
- * objects / arrays recursively.
- *
- * @name serializeAccount
- * @description Converts all non-primitive fields in an Anchor account record to JSON-safe strings.
- * @param obj - The raw account object returned by `program.account.<name>.fetch()`.
- * @returns A new plain object with all values converted.
- * @category Utils
- * @since v0.1.0
- * @example
- * ```ts
- * import { serializeAccount } from "@synapse-sap/sdk/utils";
- *
- * const raw = await program.account.agent.fetch(pda);
- * const safe = serializeAccount(raw);
- * console.log(JSON.stringify(safe));
- * ```
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function serializeAccount(
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  obj: Record<string, any>,
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-): Record<string, any> {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const result: Record<string, any> = {};
-  for (const [key, value] of Object.entries(obj)) {
-    result[key] = serializeValue(value);
-  }
-  return result;
-}

package/src/utils/validation.ts

@@ -1,36 +0,0 @@
-/**
- * @module utils/validation
- * @description Runtime assertion helpers.
- *
- * @category Utils
- * @since v0.1.0
- */
-
-/**
- * Assert that a condition holds, throwing a descriptive error otherwise.
- *
- * Uses TypeScript’s `asserts condition` return type so the compiler
- * narrows the guarded value after the call.
- *
- * @name assert
- * @description Runtime guard — throws `RangeError` with a `[SAP SDK]` prefix when the condition is falsy.
- * @param condition - The boolean expression to verify.
- * @param message   - Human-readable message included in the thrown error.
- * @throws {RangeError} When `condition` is `false`.
- * @category Utils
- * @since v0.1.0
- * @example
- * ```ts
- * import { assert } from "@synapse-sap/sdk/utils";
- *
- * assert(name.length <= 64, "Agent name exceeds MAX_NAME_LEN");
- * ```
- */
-export function assert(
-  condition: boolean,
-  message: string,
-): asserts condition {
-  if (!condition) {
-    throw new RangeError(`[SAP SDK] ${message}`);
-  }
-}

package/src/utils/volume-curve.ts

@@ -1,131 +0,0 @@
-/**
- * @module volume-curve
- * @description Client-side mirror of the on-chain `calculate_settle_amount`
- * function from `programs/synapse-agent-sap/src/instructions/escrow_v2.rs`.
- *
- * Used by {@link EscrowV2Module.settle} to pre-compute the settlement
- * `amount` so it can chain `createPendingSettlement` in the same transaction
- * as `settleCallsV2` (DisputeWindow flow). Keeping the math in one place
- * here ensures the SDK stays byte-for-byte aligned with the program; if the
- * on-chain curve algorithm ever changes, this file is the single source of
- * truth on the client.
- *
- * @category Utilities
- * @since v0.13.0
- * @packageDocumentation
- */
-
-import { BN } from "@coral-xyz/anchor";
-import type { VolumeCurveBreakpoint } from "../types/common";
-
-const U64_MAX = new BN("18446744073709551615");
-
-function checkedMul(a: BN, b: BN): BN {
-  const r = a.mul(b);
-  if (r.gt(U64_MAX)) {
-    throw new Error(
-      `volume-curve: u64 overflow on multiply (${a.toString()} * ${b.toString()})`,
-    );
-  }
-  return r;
-}
-
-function checkedAdd(a: BN, b: BN): BN {
-  const r = a.add(b);
-  if (r.gt(U64_MAX)) {
-    throw new Error(
-      `volume-curve: u64 overflow on add (${a.toString()} + ${b.toString()})`,
-    );
-  }
-  return r;
-}
-
-/**
- * @function calculateSettleAmount
- * @description Compute the lamport (or token base-unit) amount the on-chain
- * `settle_calls_v2` handler will charge for `calls` calls, given the escrow's
- * `pricePerCall`, `volumeCurve`, and the current settled+pending counter.
- *
- * Mirrors the exact algorithm of `calculate_settle_amount` in
- * `escrow_v2.rs` (v0.7+):
- *
- * ```rust
- * if curve.is_empty() { calls * base_price } else { walk-the-curve }
- * ```
- *
- * Walks the curve from `cursor = totalCallsBefore` and at each cursor
- * position picks the breakpoint price whose `afterCalls` threshold the
- * cursor has passed. Calls are charged at the active price up to the next
- * threshold, then the cursor advances and the loop repeats until all
- * `calls` are accounted for.
- *
- * @param basePrice - Escrow's `pricePerCall` (BN, u64 lamports/base-units).
- * @param curve - The escrow's `volumeCurve` array (may be empty).
- * @param totalCallsBefore - `escrow.totalCallsSettled + escrow.pendingCalls`
- *   AT THE MOMENT `settleCallsV2` runs on-chain.
- * @param calls - Number of calls being settled in this batch.
- * @returns The amount the on-chain handler will compute (BN, u64).
- *
- * @example
- * ```ts
- * import { calculateSettleAmount } from "@oobe-protocol-labs/synapse-sap-sdk";
- *
- * const amount = calculateSettleAmount(
- *   escrow.pricePerCall,
- *   escrow.volumeCurve,
- *   escrow.totalCallsSettled.add(escrow.pendingCalls),
- *   new BN(5),
- * );
- * ```
- *
- * @since v0.13.0
- */
-export function calculateSettleAmount(
-  basePrice: BN,
-  curve: VolumeCurveBreakpoint[],
-  totalCallsBefore: BN,
-  calls: BN,
-): BN {
-  if (calls.isZero()) return new BN(0);
-  if (!curve || curve.length === 0) {
-    return checkedMul(calls, basePrice);
-  }
-
-  let amount = new BN(0);
-  let remaining = calls.clone();
-  let cursor = totalCallsBefore.clone();
-
-  while (remaining.gtn(0)) {
-    let currentPrice = basePrice;
-    let nextThreshold: BN | null = null;
-
-    for (const bp of curve) {
-      const threshold = new BN(bp.afterCalls);
-      if (cursor.gte(threshold)) {
-        currentPrice = bp.pricePerCall;
-      } else {
-        nextThreshold = threshold;
-        break;
-      }
-    }
-
-    let callsAtPrice: BN;
-    if (nextThreshold) {
-      const room = nextThreshold.sub(cursor);
-      callsAtPrice = BN.min(remaining, room.isNeg() ? new BN(0) : room);
-      if (callsAtPrice.isZero()) {
-        // Defensive: shouldn't happen because cursor < nextThreshold by
-        // the `else` branch above, but guard anyway.
-        callsAtPrice = remaining;
-      }
-    } else {
-      callsAtPrice = remaining;
-    }
-
-    amount = checkedAdd(amount, checkedMul(callsAtPrice, currentPrice));
-    remaining = remaining.sub(callsAtPrice);
-    cursor = cursor.add(callsAtPrice);
-  }
-
-  return amount;
-}

package/src/utils/x402-direct.ts

@@ -1,370 +0,0 @@
-/**
- * @module utils/x402-direct
- * @description Recognize x402 direct SPL token payments on an agent's ATA
- * by scanning transaction history and filtering for x402 patterns.
- *
- * @category Utils
- * @since v0.6.4
- */
-
-import {
-  type Connection,
-  PublicKey,
-  type ParsedTransactionWithMeta,
-  type ConfirmedSignatureInfo,
-} from "@solana/web3.js";
-import { sha256 } from "../utils";
-
-// ═══════════════════════════════════════════════════════════════════
-//  Types
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * @interface SettlementPayload
- * @description Settlement metadata from the merchant's PAYMENT-RESPONSE.
- * @category Utils
- * @since v0.6.4
- */
-export interface SettlementPayload {
-  /** SHA-256 service hash. */
-  readonly serviceHash: string;
-  /** Resource identifier. */
-  readonly resource: string;
-  /** Agent wallet (base58). */
-  readonly agentWallet: string;
-  /** Depositor wallet (base58). */
-  readonly depositorWallet: string;
-  /** Amount in smallest unit. */
-  readonly amount: string;
-  /** Service timestamp. */
-  readonly timestamp: number;
-}
-
-/**
- * @interface X402DirectPayment
- * @description A recognized x402 direct SPL transfer on an agent's ATA.
- * @category Utils
- * @since v0.6.4
- */
-export interface X402DirectPayment {
-  /** Transaction signature. */
-  readonly signature: string;
-  /** Transfer amount (in smallest token unit). */
-  readonly amount: bigint;
-  /** Source ATA (payer). */
-  readonly payerAta: PublicKey;
-  /** Destination ATA (payTo / agent). */
-  readonly payeeAta: PublicKey;
-  /** Token mint used for transfer. */
-  readonly mint: PublicKey;
-  /** Memo data (if a Memo instruction was included). */
-  readonly memo: string | null;
-  /** Matched settlement payload (if server-side verification is available). */
-  readonly settlement: SettlementPayload | null;
-  /** Block time (unix seconds). */
-  readonly blockTime: number | null;
-  /** Slot number. */
-  readonly slot: number;
-}
-
-/**
- * @interface GetX402DirectOptions
- * @description Options for {@link getX402DirectPayments}.
- * @category Utils
- * @since v0.6.4
- */
-export interface GetX402DirectOptions {
-  /** Max signatures to scan (default: 100). */
-  readonly limit?: number;
-  /** Only return transfers from this specific payer. */
-  readonly filterPayer?: PublicKey;
-  /** Known settlements from server-side PAYMENT-RESPONSE logs.
-   *  Used for deterministic hash matching. */
-  readonly knownSettlements?: SettlementPayload[];
-  /** Only include payments that match x402 memo prefix. Default: false. */
-  readonly requireMemo?: boolean;
-  /** Scan before this TX signature (pagination). */
-  readonly before?: string;
-  /** Scan after this TX signature (pagination). */
-  readonly until?: string;
-}
-
-// ═══════════════════════════════════════════════════════════════════
-//  Core
-// ═══════════════════════════════════════════════════════════════════
-
-/** Recognized x402 memo prefixes. */
-const X402_MEMO_PREFIXES = ["x402:", "SAP-x402:", "x402-direct:"];
-
-/**
- * @name extractSplTransfer
- * @description Extract SPL Token transfer details from a parsed transaction.
- *
- * Looks for `transfer` or `transferChecked` inner instructions on the
- * Token Program and returns source/dest/amount/mint.
- *
- * @internal
- */
-function extractSplTransfer(
-  tx: ParsedTransactionWithMeta,
-  payToAta: PublicKey,
-): {
-  amount: bigint;
-  source: PublicKey;
-  destination: PublicKey;
-  mint: PublicKey;
-} | null {
-  if (!tx.meta?.innerInstructions && !tx.transaction.message.instructions) {
-    return null;
-  }
-
-  // Check all instructions (outer + inner)
-  const allIxs = [
-    ...tx.transaction.message.instructions,
-    ...(tx.meta?.innerInstructions?.flatMap((g) => g.instructions) ?? []),
-  ];
-
-  for (const ix of allIxs) {
-    // Only process parsed instructions with known program
-    if (!("parsed" in ix) || !("program" in ix)) continue;
-    const parsed = ix as { parsed: Record<string, unknown>; program: string };
-
-    if (parsed.program !== "spl-token") continue;
-
-    const info = parsed.parsed as {
-      type?: string;
-      info?: {
-        source?: string;
-        destination?: string;
-        amount?: string;
-        tokenAmount?: { amount?: string };
-        mint?: string;
-        authority?: string;
-      };
-    };
-
-    if (
-      info.type !== "transfer" &&
-      info.type !== "transferChecked"
-    ) {
-      continue;
-    }
-
-    const transferInfo = info.info;
-    if (!transferInfo?.source || !transferInfo?.destination) continue;
-
-    // Check destination matches our payTo ATA
-    const destPk = new PublicKey(transferInfo.destination);
-    if (!destPk.equals(payToAta)) continue;
-
-    const amountStr =
-      transferInfo.amount ?? transferInfo.tokenAmount?.amount ?? "0";
-
-    return {
-      amount: BigInt(amountStr),
-      source: new PublicKey(transferInfo.source),
-      destination: destPk,
-      mint: transferInfo.mint ? new PublicKey(transferInfo.mint) : destPk, // fallback
-    };
-  }
-
-  return null;
-}
-
-/**
- * @name extractMemo
- * @description Extract memo data from a parsed transaction.
- * @internal
- */
-function extractMemo(tx: ParsedTransactionWithMeta): string | null {
-  const allIxs = [
-    ...tx.transaction.message.instructions,
-    ...(tx.meta?.innerInstructions?.flatMap((g) => g.instructions) ?? []),
-  ];
-
-  for (const ix of allIxs) {
-    if (!("parsed" in ix) || !("program" in ix)) continue;
-    const parsed = ix as { parsed: unknown; program: string };
-    if (parsed.program === "spl-memo" && typeof parsed.parsed === "string") {
-      return parsed.parsed;
-    }
-  }
-
-  // Also check log messages for memo
-  if (tx.meta?.logMessages) {
-    for (const log of tx.meta.logMessages) {
-      if (log.startsWith("Program log: Memo")) {
-        const memoMatch = log.match(/Memo \(len \d+\): "(.*?)"/);
-        if (memoMatch?.[1]) return memoMatch[1];
-      }
-    }
-  }
-
-  return null;
-}
-
-/**
- * @name matchesX402Pattern
- * @description Check if a transfer matches an x402 payment pattern.
- *
- * Matches if:
- * - A memo with recognized x402 prefix is present, OR
- * - The transfer matches a known settlement payload (deterministic hash), OR
- * - `requireMemo` is false (any SPL transfer to the ATA is included)
- *
- * @internal
- */
-function matchesX402Pattern(
-  transfer: { amount: bigint; source: PublicKey },
-  memo: string | null,
-  knownSettlements: SettlementPayload[],
-  requireMemo: boolean,
-): SettlementPayload | true | false {
-  // 1. Check memo prefix
-  if (memo) {
-    for (const prefix of X402_MEMO_PREFIXES) {
-      if (memo.startsWith(prefix)) return true;
-    }
-    // Try base64 JSON parse for embedded x402 payload
-    try {
-      const decoded = Buffer.from(memo, "base64").toString("utf-8");
-      const parsed = JSON.parse(decoded);
-      if (parsed.protocol === "x402" || parsed.protocol === "SAP-x402") {
-        return true;
-      }
-    } catch {
-      // Not base64 JSON — ignore
-    }
-  }
-
-  // 2. Match against known settlements (deterministic hash)
-  for (const settlement of knownSettlements) {
-    const expected = BigInt(settlement.amount);
-    if (transfer.amount !== expected) continue;
-
-    // Deterministic hash: sha256(agentWallet + depositor + amount + timestamp)
-    const hashInput =
-      settlement.agentWallet +
-      settlement.depositorWallet +
-      settlement.amount +
-      settlement.timestamp.toString();
-    const expectedHash = Buffer.from(sha256(hashInput)).toString("hex");
-    const serviceHash = settlement.serviceHash;
-
-    if (expectedHash === serviceHash) return settlement;
-  }
-
-  // 3. If requireMemo is false, accept any SPL transfer to the ATA
-  if (!requireMemo) return true;
-
-  return false;
-}
-
-/**
- * @name getX402DirectPayments
- * @description Scan an agent's ATA for x402 direct payments.
- *
- * Fetches recent transaction signatures for the given `payTo` ATA,
- * inspects each transaction for SPL token transfers, and filters
- * for x402 payment patterns (memo prefix, settlement hash match, etc.).
- *
- * @param connection - Solana RPC connection.
- * @param payToAta   - The agent's receiving ATA (e.g. USDC ATA of Syra).
- * @param opts       - Filter and pagination options.
- * @returns Array of recognized x402 direct payments, newest first.
- *
- * @category Utils
- * @since v0.6.4
- *
- * @example
- * ```ts
- * import { getX402DirectPayments, findATA } from "@oobe-protocol-labs/synapse-sap-sdk";
- *
- * const USDC_MINT = new PublicKey("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");
- * const payToAta = findATA(agentWallet, USDC_MINT);
- *
- * const payments = await getX402DirectPayments(connection, payToAta, {
- *   limit: 50,
- *   knownSettlements: savedSettlements, // from your API PAYMENT-RESPONSE logs
- * });
- *
- * for (const p of payments) {
- *   console.log(`${p.signature}: ${p.amount} from ${p.payerAta.toBase58()}`);
- *   if (p.settlement) {
- *     console.log(`  Matched settlement: ${p.settlement.serviceHash}`);
- *   }
- * }
- * ```
- */
-export async function getX402DirectPayments(
-  connection: Connection,
-  payToAta: PublicKey,
-  opts?: GetX402DirectOptions,
-): Promise<X402DirectPayment[]> {
-  const limit = opts?.limit ?? 100;
-  const knownSettlements = opts?.knownSettlements ?? [];
-  const requireMemo = opts?.requireMemo ?? false;
-
-  // 1. Fetch signatures
-  const sigOpts: {
-    limit: number;
-    before?: string;
-    until?: string;
-  } = { limit };
-  if (opts?.before) sigOpts.before = opts.before;
-  if (opts?.until) sigOpts.until = opts.until;
-
-  const sigs: ConfirmedSignatureInfo[] =
-    await connection.getSignaturesForAddress(payToAta, sigOpts);
-
-  if (sigs.length === 0) return [];
-
-  // 2. Fetch transactions (batch with getParsedTransactions if available)
-  const txs = await connection.getParsedTransactions(
-    sigs.map((s) => s.signature),
-    { maxSupportedTransactionVersion: 0 },
-  );
-
-  // 3. Extract and filter
-  const results: X402DirectPayment[] = [];
-
-  for (let i = 0; i < txs.length; i++) {
-    const tx = txs[i];
-    if (!tx) continue;
-
-    // Extract SPL transfer to our ATA
-    const transfer = extractSplTransfer(tx, payToAta);
-    if (!transfer) continue;
-
-    // Filter by payer if specified
-    if (opts?.filterPayer && !transfer.source.equals(opts.filterPayer)) {
-      continue;
-    }
-
-    // Extract memo
-    const memo = extractMemo(tx);
-
-    // Match x402 pattern
-    const match = matchesX402Pattern(
-      transfer,
-      memo,
-      knownSettlements,
-      requireMemo,
-    );
-    if (match === false) continue;
-
-    results.push({
-      signature: sigs[i]!.signature,
-      amount: transfer.amount,
-      payerAta: transfer.source,
-      payeeAta: transfer.destination,
-      mint: transfer.mint,
-      memo,
-      settlement: typeof match === "object" ? match : null,
-      blockTime: tx.blockTime ?? null,
-      slot: tx.slot,
-    });
-  }
-
-  return results;
-}