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

package/src/utils/priority-fee.ts

@@ -1,325 +0,0 @@
-/**
- * @module utils/priority-fee
- * @description Compute budget and priority fee utilities for SAP transactions.
- *
- * Solana transactions that include a priority fee (via the Compute Budget program)
- * land faster because validators prefer higher-fee transactions. This module
- * provides a clean, composable API for building priority-fee instructions
- * that can be prepended to any Anchor method builder via `.preInstructions()`.
- *
- * Typical use: x402 settlement transactions where the receiving agent's RPC
- * has a short confirmation window (e.g., 30 seconds).
- *
- * @category Utils
- * @since v0.6.2
- *
- * @example
- * ```ts
- * import { buildPriorityFeeIxs, DEFAULT_SETTLE_PRIORITY } from "@synapse-sap/sdk";
- *
- * // Append to any Anchor method builder:
- * await program.methods
- *   .settleCalls(calls, hash)
- *   .accounts({ ... })
- *   .preInstructions(buildPriorityFeeIxs({ priorityFeeMicroLamports: 5000 }))
- *   .rpc({ skipPreflight: true });
- * ```
- */
-
-import {
-  ComputeBudgetProgram,
-  type TransactionInstruction,
-} from "@solana/web3.js";
-
-// ═══════════════════════════════════════════════════════════════════
-//  Constants
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * Default priority fee for settlement transactions (in microlamports).
- * 5000 µL ≈ 0.0005 SOL per 200k CU — fast enough for most agent RPCs.
- *
- * @since v0.6.2
- */
-export const DEFAULT_SETTLE_PRIORITY_FEE = 5_000;
-
-/**
- * Default compute unit limit for settlement transactions.
- * `settle_calls` uses ~60k CU; 100k provides a safe margin.
- *
- * @since v0.6.2
- */
-export const DEFAULT_SETTLE_COMPUTE_UNITS = 100_000;
-
-/**
- * Default compute unit limit for batch settlement transactions.
- * `settle_batch` with 10 entries uses ~200k CU; 300k provides margin.
- *
- * @since v0.6.2
- */
-export const DEFAULT_BATCH_SETTLE_COMPUTE_UNITS = 300_000;
-
-/**
- * Per-settlement CU cost observed for `settle_batch` (sha256 of the
- * service hash, dedup scan, volume-curve math, account writes).
- *
- * @since v0.11.0
- * @internal
- */
-const BATCH_SETTLE_CU_PER_ENTRY = 25_000;
-
-/**
- * Fixed CU overhead for a `settle_batch` transaction independent of
- * the entry count (signature verify, account loads, transfer, event).
- *
- * @since v0.11.0
- * @internal
- */
-const BATCH_SETTLE_CU_BASE = 60_000;
-
-/**
- * Hard ceiling — Solana caps a single instruction at 1.4M CU. We
- * stay below that so a transaction with extra preInstructions
- * (priority-fee, ATA creation) still fits.
- *
- * @since v0.11.0
- * @internal
- */
-const BATCH_SETTLE_CU_MAX = 1_200_000;
-
-/**
- * @name computeBatchSettleCu
- * @description Compute the CU limit needed by `settle_batch` for a
- * given entry count. Returned value is safe to pass to
- * `ComputeBudgetProgram.setComputeUnitLimit`.
- *
- * Formula: `60_000 + n * 25_000`, clamped to 1.2M.
- *
- * @param entryCount - Number of settlements in the batch (1..N).
- * @returns CU limit suitable for `setComputeUnitLimit`.
- *
- * @example
- * ```ts
- * const cu = computeBatchSettleCu(20); // 560_000
- * ```
- *
- * @category Utils
- * @since v0.11.0
- */
-export function computeBatchSettleCu(entryCount: number): number {
-  if (!Number.isFinite(entryCount) || entryCount <= 0) {
-    return DEFAULT_BATCH_SETTLE_COMPUTE_UNITS;
-  }
-  const raw = BATCH_SETTLE_CU_BASE + Math.ceil(entryCount) * BATCH_SETTLE_CU_PER_ENTRY;
-  return Math.min(raw, BATCH_SETTLE_CU_MAX);
-}
-
-// ═══════════════════════════════════════════════════════════════════
-//  Types
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * @interface PriorityFeeConfig
- * @description Configuration for building compute budget instructions.
- * @category Utils
- * @since v0.6.2
- */
-export interface PriorityFeeConfig {
-  /**
-   * Priority fee in microlamports per compute unit.
-   * Higher values = faster confirmation.
-   *
-   * Common values:
-   * - `1000` — low priority (~0.0001 SOL)
-   * - `5000` — medium priority (~0.0005 SOL) ← recommended for settle
-   * - `50000` — high priority (~0.005 SOL)
-   * - `0` — no priority fee (default Solana behavior)
-   *
-   * @default 0
-   */
-  readonly priorityFeeMicroLamports?: number;
-
-  /**
-   * Maximum compute units the transaction may consume.
-   * Setting an explicit limit avoids overpaying for unused CU.
-   *
-   * @default 200_000 (Solana default)
-   */
-  readonly computeUnits?: number;
-}
-
-/**
- * @interface SettleOptions
- * @description Options for x402 settlement transactions.
- * Controls priority fees, compute budget, and RPC behavior
- * to optimize confirmation speed for time-sensitive settlements.
- *
- * @category Registries
- * @since v0.6.2
- *
- * @example
- * ```ts
- * // Fast settlement with priority fee
- * const receipt = await x402.settle(depositor, 1, "data", {
- *   priorityFeeMicroLamports: 5000,
- *   computeUnits: 100_000,
- *   skipPreflight: true,
- * });
- *
- * // Use the convenience preset
- * import { FAST_SETTLE_OPTIONS } from "@synapse-sap/sdk";
- * const receipt = await x402.settle(depositor, 1, "data", FAST_SETTLE_OPTIONS);
- * ```
- */
-export interface SettleOptions extends PriorityFeeConfig {
-  /**
-   * Skip Solana simulation before submitting.
-   * Saves ~400ms but loses pre-flight error detection.
-   *
-   * Recommended for settlements where the escrow state
-   * has already been pre-fetched and validated.
-   *
-   * @default false
-   */
-  readonly skipPreflight?: boolean;
-
-  /**
-   * Transaction commitment level override.
-   * Uses the provider's default when omitted.
-   *
-   * - `"processed"` — fastest, least reliable
-   * - `"confirmed"` — balanced (recommended)
-   * - `"finalized"` — slowest, most reliable
-   */
-  readonly commitment?: "processed" | "confirmed" | "finalized";
-
-  /**
-   * Maximum number of RPC retry attempts.
-   * @default provider default (usually 3)
-   */
-  readonly maxRetries?: number;
-}
-
-// ═══════════════════════════════════════════════════════════════════
-//  Presets
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * Recommended preset for fast x402 settlements.
- * Priority fee 5000 µL, 100k CU, skip preflight, confirmed commitment.
- *
- * @since v0.6.2
- */
-export const FAST_SETTLE_OPTIONS: Readonly<SettleOptions> = Object.freeze({
-  priorityFeeMicroLamports: DEFAULT_SETTLE_PRIORITY_FEE,
-  computeUnits: DEFAULT_SETTLE_COMPUTE_UNITS,
-  skipPreflight: true,
-  commitment: "confirmed",
-});
-
-/**
- * Recommended preset for fast batch settlements.
- * Priority fee 5000 µL, 300k CU, skip preflight, confirmed commitment.
- *
- * @since v0.6.2
- */
-export const FAST_BATCH_SETTLE_OPTIONS: Readonly<SettleOptions> = Object.freeze({
-  priorityFeeMicroLamports: DEFAULT_SETTLE_PRIORITY_FEE,
-  computeUnits: DEFAULT_BATCH_SETTLE_COMPUTE_UNITS,
-  skipPreflight: true,
-  commitment: "confirmed",
-});
-
-// ═══════════════════════════════════════════════════════════════════
-//  Builder
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * @name buildPriorityFeeIxs
- * @description Build compute budget instructions for priority fee transactions.
- *
- * Returns an array of 0–2 `TransactionInstruction`s:
- * - `SetComputeUnitPrice` (if `priorityFeeMicroLamports > 0`)
- * - `SetComputeUnitLimit` (if `computeUnits` provided)
- *
- * The returned array is designed to be passed directly to
- * Anchor's `.preInstructions()` builder method.
- *
- * @param config - Priority fee configuration.
- * @returns Array of compute budget instructions (may be empty).
- *
- * @category Utils
- * @since v0.6.2
- *
- * @example
- * ```ts
- * const ixs = buildPriorityFeeIxs({
- *   priorityFeeMicroLamports: 5000,
- *   computeUnits: 100_000,
- * });
- *
- * await program.methods
- *   .settleCalls(calls, hash)
- *   .accounts({ ... })
- *   .preInstructions(ixs)
- *   .rpc({ skipPreflight: true });
- * ```
- */
-export function buildPriorityFeeIxs(
-  config?: PriorityFeeConfig,
-): TransactionInstruction[] {
-  if (!config) return [];
-
-  const ixs: TransactionInstruction[] = [];
-
-  const fee = config.priorityFeeMicroLamports ?? 0;
-  if (fee > 0) {
-    ixs.push(
-      ComputeBudgetProgram.setComputeUnitPrice({
-        microLamports: fee,
-      }),
-    );
-  }
-
-  const cu = config.computeUnits;
-  if (cu !== undefined && cu > 0) {
-    ixs.push(
-      ComputeBudgetProgram.setComputeUnitLimit({
-        units: cu,
-      }),
-    );
-  }
-
-  return ixs;
-}
-
-/**
- * @name buildRpcOptions
- * @description Build Anchor `.rpc()` options from {@link SettleOptions}.
- *
- * @param opts - Settle options.
- * @returns Options object suitable for Anchor `.rpc(opts)`.
- *
- * @category Utils
- * @since v0.6.2
- * @internal
- */
-export function buildRpcOptions(
-  opts?: SettleOptions,
-): Record<string, unknown> | undefined {
-  if (!opts) return undefined;
-
-  const rpcOpts: Record<string, unknown> = {};
-
-  if (opts.skipPreflight !== undefined) {
-    rpcOpts.skipPreflight = opts.skipPreflight;
-  }
-  if (opts.commitment !== undefined) {
-    rpcOpts.commitment = opts.commitment;
-  }
-  if (opts.maxRetries !== undefined) {
-    rpcOpts.maxRetries = opts.maxRetries;
-  }
-
-  return Object.keys(rpcOpts).length > 0 ? rpcOpts : undefined;
-}

package/src/utils/rpc-strategy.ts

@@ -1,322 +0,0 @@
-/**
- * @module utils/rpc-strategy
- * @description Dual-connection RPC strategy and idempotent ATA creation.
- *
- * Solves two interoperability problems:
- *
- * 1. **WebSocket 400 loop**: Some authenticated RPCs reject WebSocket
- *    connections for SPL token operations. This module exposes a
- *    dual-connection strategy: primary RPC for SAP program calls,
- *    fallback public RPC for token operations.
- *
- * 2. **Idempotent ATA creation**: Wraps `getOrCreateAssociatedTokenAccount`
- *    with retries so "account already exists" doesn't surface as a
- *    hard error.
- *
- * @category Utils
- * @since v0.6.0
- */
-
-import {
-  Connection,
-  type Commitment,
-  PublicKey,
-  type TransactionSignature,
-} from "@solana/web3.js";
-
-// ═══════════════════════════════════════════════════════════════════
-//  RPC Strategy Types
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * @interface RpcConfig
- * @description Configuration for dual-connection RPC strategy.
- * @category Utils
- * @since v0.6.0
- */
-export interface RpcConfig {
-  /** Primary RPC URL (for SAP program calls). */
-  readonly primaryUrl: string;
-  /** Fallback RPC URL (for SPL token ops, public RPCs). */
-  readonly fallbackUrl?: string;
-  /** Commitment level. */
-  readonly commitment?: Commitment;
-}
-
-/**
- * @interface DualConnection
- * @description Dual RPC connections: primary for SAP, fallback for tokens.
- * @category Utils
- * @since v0.6.0
- */
-export interface DualConnection {
-  /** Primary connection for SAP program calls. */
-  readonly primary: Connection;
-  /** Fallback connection for SPL token operations. */
-  readonly fallback: Connection;
-}
-
-// ═══════════════════════════════════════════════════════════════════
-//  Default Public RPCs
-// ═══════════════════════════════════════════════════════════════════
-
-/** Well-known public fallback RPCs by cluster. */
-const PUBLIC_RPCS: Record<string, string> = {
-  "mainnet-beta": "https://api.mainnet-beta.solana.com",
-  devnet: "https://api.devnet.solana.com",
-  localnet: "http://localhost:8899",
-};
-
-// ═══════════════════════════════════════════════════════════════════
-//  Public API
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * @name getRpcUrl
- * @description Get the primary RPC URL from environment or config.
- *
- * Resolution order:
- *   1. Explicit `config.primaryUrl`
- *   2. `SOLANA_RPC_URL` env var
- *   3. Cluster-appropriate public RPC
- *
- * @param config - Optional RPC configuration.
- * @param cluster - Cluster hint (defaults to "mainnet-beta").
- * @returns The resolved primary RPC URL.
- *
- * @category Utils
- * @since v0.6.0
- */
-export function getRpcUrl(
-  config?: Partial<RpcConfig>,
-  cluster: string = "mainnet-beta",
-): string {
-  if (config?.primaryUrl) return config.primaryUrl;
-
-  // Environment variable
-  const envUrl =
-    typeof process !== "undefined" ? process.env?.SOLANA_RPC_URL : undefined;
-  if (envUrl) return envUrl;
-
-  return PUBLIC_RPCS[cluster] ?? PUBLIC_RPCS["mainnet-beta"]!;
-}
-
-/**
- * @name getFallbackRpcUrl
- * @description Get the fallback RPC URL for SPL token operations.
- *
- * This avoids the WebSocket-400 loop when the primary RPC is
- * an authenticated endpoint that rejects token-related WebSocket
- * subscriptions.
- *
- * @param config - Optional RPC configuration.
- * @param cluster - Cluster hint (defaults to "mainnet-beta").
- * @returns The resolved fallback RPC URL.
- *
- * @category Utils
- * @since v0.6.0
- */
-export function getFallbackRpcUrl(
-  config?: Partial<RpcConfig>,
-  cluster: string = "mainnet-beta",
-): string {
-  if (config?.fallbackUrl) return config.fallbackUrl;
-
-  // Env fallback
-  const envUrl =
-    typeof process !== "undefined"
-      ? process.env?.SOLANA_FALLBACK_RPC_URL
-      : undefined;
-  if (envUrl) return envUrl;
-
-  return PUBLIC_RPCS[cluster] ?? PUBLIC_RPCS["mainnet-beta"]!;
-}
-
-/**
- * @name createDualConnection
- * @description Create a dual-connection pair: primary for SAP program calls,
- * fallback for SPL token operations.
- *
- * @param config - RPC configuration.
- * @param cluster - Cluster hint.
- * @returns A {@link DualConnection} with both connections.
- *
- * @category Utils
- * @since v0.6.0
- *
- * @example
- * ```ts
- * const { primary, fallback } = createDualConnection({
- *   primaryUrl: "https://my-rpc.example.com",
- * }, "mainnet-beta");
- *
- * // Use primary for SAP calls
- * const provider = new AnchorProvider(primary, wallet, {});
- *
- * // Use fallback for SPL token account creation
- * const ata = await getOrCreateATA(fallback, mint, owner);
- * ```
- */
-export function createDualConnection(
-  config: Partial<RpcConfig>,
-  cluster: string = "mainnet-beta",
-): DualConnection {
-  const commitment = config.commitment ?? "confirmed";
-  const primaryUrl = getRpcUrl(config, cluster);
-  const fallbackUrl = getFallbackRpcUrl(config, cluster);
-
-  return {
-    primary: new Connection(primaryUrl, { commitment }),
-    fallback: new Connection(fallbackUrl, { commitment }),
-  };
-}
-
-// ═══════════════════════════════════════════════════════════════════
-//  Idempotent ATA Creation
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * @interface AtaResult
- * @description Result of idempotent ATA creation attempt.
- * @category Utils
- * @since v0.6.0
- */
-export interface AtaResult {
-  /** The ATA public key (exists or newly created). */
-  readonly address: PublicKey;
-  /** Whether the ATA already existed. */
-  readonly existed: boolean;
-  /** Transaction signature (only if newly created). */
-  readonly txSignature?: TransactionSignature;
-}
-
-/**
- * @name findATA
- * @description Derive the Associated Token Account address.
- * Uses the standard ATA PDA derivation without importing the full
- * `@solana/spl-token` package.
- *
- * @param owner - The token account owner.
- * @param mint - The token mint.
- * @param programId - Token program ID (defaults to TOKEN_PROGRAM_ID).
- * @returns The derived ATA public key.
- *
- * @category Utils
- * @since v0.6.0
- */
-export function findATA(
-  owner: PublicKey,
-  mint: PublicKey,
-  programId: PublicKey = new PublicKey("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"),
-): PublicKey {
-  const ASSOCIATED_TOKEN_PROGRAM_ID = new PublicKey(
-    "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL",
-  );
-
-  const [ata] = PublicKey.findProgramAddressSync(
-    [owner.toBuffer(), programId.toBuffer(), mint.toBuffer()],
-    ASSOCIATED_TOKEN_PROGRAM_ID,
-  );
-  return ata;
-}
-
-// ═══════════════════════════════════════════════════════════════════
-//  Error Classification
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * Anchor error code to friendly message mapping.
- * Converts cryptic Anchor errors into actionable messages.
- */
-const ANCHOR_ERROR_MESSAGES: Record<number, string> = {
-  6000: "Agent already registered for this wallet",
-  6001: "Agent not found — register first",
-  6002: "Name exceeds maximum length (64 bytes)",
-  6003: "Description exceeds maximum length (256 bytes)",
-  6004: "Too many capabilities (max 10)",
-  6005: "Too many pricing tiers (max 5)",
-  6006: "Too many protocols (max 5)",
-  6007: "Feedback score out of range (0-1000)",
-  6008: "Unauthorized — only the agent owner can perform this action",
-  6009: "Escrow expired",
-  6010: "Insufficient escrow balance",
-  6011: "Max calls exceeded",
-  6012: "Invalid settlement — calls must be > 0",
-  6013: "Escrow not empty — withdraw balance before closing",
-  6014: "Invalid token program — make sure you passed TOKEN_PROGRAM_ID as the 3rd remaining account",
-  6015: "Vault already initialized",
-  6016: "Session already exists",
-  6017: "Session closed — cannot write to closed session",
-  6018: "Data exceeds maximum write size (750 bytes)",
-  6019: "Ring buffer overflow — seal before writing more",
-};
-
-/**
- * @name classifyAnchorError
- * @description Convert an Anchor error code into a friendly, actionable message.
- *
- * @param errorCode - The numeric Anchor error code.
- * @returns A human-readable error message, or a generic message for unknown codes.
- *
- * @category Utils
- * @since v0.6.0
- *
- * @example
- * ```ts
- * try {
- *   await client.escrow.create(...);
- * } catch (err) {
- *   const code = extractAnchorErrorCode(err);
- *   if (code !== null) {
- *     console.error(classifyAnchorError(code));
- *   }
- * }
- * ```
- */
-export function classifyAnchorError(errorCode: number): string {
-  return (
-    ANCHOR_ERROR_MESSAGES[errorCode] ??
-    `Unknown SAP program error (code ${errorCode}). Check the IDL for details.`
-  );
-}
-
-/**
- * @name extractAnchorErrorCode
- * @description Attempt to extract an Anchor error code from an Error object.
- *
- * Anchor errors typically have the structure `{ code: number, msg: string }`.
- * This function handles both the direct `error.code` pattern and the
- * `error.error.errorCode.number` nested pattern.
- *
- * @param err - The caught error object.
- * @returns The numeric error code, or `null` if not an Anchor error.
- *
- * @category Utils
- * @since v0.6.0
- */
-export function extractAnchorErrorCode(err: unknown): number | null {
-  if (err == null || typeof err !== "object") return null;
-
-  // Direct code property
-  const direct = (err as Record<string, unknown>).code;
-  if (typeof direct === "number") return direct;
-
-  // Nested Anchor format: error.error.errorCode.number
-  const nested = (err as Record<string, unknown>).error;
-  if (nested && typeof nested === "object") {
-    const errorCode = (nested as Record<string, unknown>).errorCode;
-    if (errorCode && typeof errorCode === "object") {
-      const num = (errorCode as Record<string, unknown>).number;
-      if (typeof num === "number") return num;
-    }
-  }
-
-  // AnchorError pattern: { logs: [...], error: { errorCode: { number } } }
-  const msg = (err as Error).message;
-  if (typeof msg === "string") {
-    const match = msg.match(/custom program error:\s*0x([0-9a-fA-F]+)/);
-    if (match?.[1]) return parseInt(match[1], 16);
-  }
-
-  return null;
-}