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

package/src/utils/network-normalizer.ts

@@ -1,240 +0,0 @@
-/**
- * @module utils/network-normalizer
- * @description Network identifier normalization for x402 payment headers.
- *
- * Solves the canonical-string mismatch between SAP clients and servers:
- * some providers accept `solana:mainnet-beta` while others require
- * the genesis-hash form `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`.
- *
- * This module provides a single source of truth for normalizing
- * network identifiers so that both clients and agents canonicalize
- * before comparing. Catches the Kamiyo "sap network mismatch" error
- * at the SDK level.
- *
- * @category Utils
- * @since v0.6.0
- */
-
-import { SapNetwork, type SapNetworkId } from "../constants/network";
-
-// ═══════════════════════════════════════════════════════════════════
-//  Canonical Mapping
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * Bidirectional alias map: for every known network string, stores the
- * canonical SapNetworkId it resolves to, plus all known aliases.
- */
-const NETWORK_ALIASES: ReadonlyMap<string, SapNetworkId> = new Map([
-  // ── Mainnet ───────────────────────────────
-  // Canonical: genesis-hash form
-  ["solana:mainnet-beta", SapNetwork.SOLANA_MAINNET],
-  ["solana:mainnet", SapNetwork.SOLANA_MAINNET],
-  ["mainnet-beta", SapNetwork.SOLANA_MAINNET],
-  ["mainnet", SapNetwork.SOLANA_MAINNET],
-  ["solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", SapNetwork.SOLANA_MAINNET_GENESIS],
-  ["5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", SapNetwork.SOLANA_MAINNET_GENESIS],
-
-  // ── Devnet ────────────────────────────────
-  ["solana:devnet", SapNetwork.SOLANA_DEVNET_NAMED],
-  ["devnet", SapNetwork.SOLANA_DEVNET_NAMED],
-  ["solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1", SapNetwork.SOLANA_DEVNET],
-  ["EtWTRABZaYq6iMfeYKouRu166VU2xqa1", SapNetwork.SOLANA_DEVNET],
-]);
-
-/**
- * Mainnet equivalence set: all strings that refer to Solana mainnet-beta,
- * regardless of format.
- */
-const MAINNET_EQUIVALENTS = new Set<string>([
-  SapNetwork.SOLANA_MAINNET,
-  SapNetwork.SOLANA_MAINNET_GENESIS,
-  "solana:mainnet",
-  "mainnet-beta",
-  "mainnet",
-  "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
-]);
-
-/**
- * Devnet equivalence set.
- */
-const DEVNET_EQUIVALENTS = new Set<string>([
-  SapNetwork.SOLANA_DEVNET,
-  SapNetwork.SOLANA_DEVNET_NAMED,
-  "devnet",
-  "EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
-]);
-
-// ═══════════════════════════════════════════════════════════════════
-//  Public API
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * @name normalizeNetworkId
- * @description Normalize a raw network identifier string to its canonical
- * {@link SapNetworkId} form.
- *
- * Handles:
- *   - Case-insensitive matching
- *   - Stripping whitespace
- *   - Resolving genesis-hash vs. cluster-name aliases
- *   - Unknown strings are returned as-is (passthrough)
- *
- * @param raw - Raw network identifier string from headers, env vars, or config.
- * @returns The canonical {@link SapNetworkId}, or the trimmed input if unknown.
- *
- * @category Utils
- * @since v0.6.0
- *
- * @example
- * ```ts
- * import { normalizeNetworkId } from "@synapse-sap/sdk";
- *
- * normalizeNetworkId("solana:mainnet-beta");
- * // → "solana:mainnet-beta"
- *
- * normalizeNetworkId("5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp");
- * // → "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"
- *
- * normalizeNetworkId("  MAINNET  ");
- * // → "solana:mainnet-beta"
- * ```
- */
-export function normalizeNetworkId(raw: string): SapNetworkId | string {
-  const trimmed = raw.trim();
-  // Exact match first
-  const exact = NETWORK_ALIASES.get(trimmed);
-  if (exact) return exact;
-
-  // Case-insensitive lookup
-  const lower = trimmed.toLowerCase();
-  for (const [alias, canonical] of NETWORK_ALIASES) {
-    if (alias.toLowerCase() === lower) return canonical;
-  }
-
-  // Passthrough for unknown networks (custom chains, etc.)
-  return trimmed;
-}
-
-/**
- * @name isNetworkEquivalent
- * @description Check if two network identifier strings refer to the same network,
- * even if they use different formats (cluster-name vs. genesis-hash).
- *
- * This is the key function that prevents the Kamiyo "sap network mismatch"
- * error — instead of comparing strings literally, we compare their
- * canonical equivalence class.
- *
- * @param a - First network identifier.
- * @param b - Second network identifier.
- * @returns `true` if both identifiers refer to the same Solana network.
- *
- * @category Utils
- * @since v0.6.0
- *
- * @example
- * ```ts
- * import { isNetworkEquivalent } from "@synapse-sap/sdk";
- *
- * isNetworkEquivalent("solana:mainnet-beta", "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp");
- * // → true
- *
- * isNetworkEquivalent("solana:devnet", "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1");
- * // → true
- *
- * isNetworkEquivalent("solana:mainnet-beta", "solana:devnet");
- * // → false
- * ```
- */
-export function isNetworkEquivalent(a: string, b: string): boolean {
-  const normA = a.trim();
-  const normB = b.trim();
-
-  // Fast path: identical strings
-  if (normA === normB) return true;
-
-  // Check if both are in the same equivalence set
-  if (MAINNET_EQUIVALENTS.has(normA) && MAINNET_EQUIVALENTS.has(normB)) return true;
-  if (DEVNET_EQUIVALENTS.has(normA) && DEVNET_EQUIVALENTS.has(normB)) return true;
-
-  // Case-insensitive match
-  const lowerA = normA.toLowerCase();
-  const lowerB = normB.toLowerCase();
-  if (lowerA === lowerB) return true;
-
-  // Resolve both to canonical and compare
-  const canonA = normalizeNetworkId(normA);
-  const canonB = normalizeNetworkId(normB);
-
-  if (canonA === canonB) return true;
-
-  // Final check: both resolve to the same equivalence set
-  if (MAINNET_EQUIVALENTS.has(canonA) && MAINNET_EQUIVALENTS.has(canonB)) return true;
-  if (DEVNET_EQUIVALENTS.has(canonA) && DEVNET_EQUIVALENTS.has(canonB)) return true;
-
-  return false;
-}
-
-/**
- * @name getNetworkGenesisHash
- * @description Get the genesis-hash form of a network identifier.
- * Returns the genesis-hash variant for known networks, or the input as-is.
- *
- * Useful for agents that require the genesis-hash form (Kamiyo, Helius x402).
- *
- * @param networkId - Any network identifier.
- * @returns The genesis-hash form, or the input if unknown.
- *
- * @category Utils
- * @since v0.6.0
- */
-export function getNetworkGenesisHash(networkId: string): string {
-  const norm = normalizeNetworkId(networkId);
-  if (MAINNET_EQUIVALENTS.has(networkId) || MAINNET_EQUIVALENTS.has(norm)) {
-    return SapNetwork.SOLANA_MAINNET_GENESIS;
-  }
-  if (DEVNET_EQUIVALENTS.has(networkId) || DEVNET_EQUIVALENTS.has(norm)) {
-    return SapNetwork.SOLANA_DEVNET;
-  }
-  return norm;
-}
-
-/**
- * @name getNetworkClusterName
- * @description Get the cluster-name form of a network identifier.
- * Returns the human-readable cluster name for known networks.
- *
- * Useful for providers that accept cluster names (Coinbase, Phantom).
- *
- * @param networkId - Any network identifier.
- * @returns The cluster-name form, or the input if unknown.
- *
- * @category Utils
- * @since v0.6.0
- */
-export function getNetworkClusterName(networkId: string): string {
-  const norm = normalizeNetworkId(networkId);
-  if (MAINNET_EQUIVALENTS.has(networkId) || MAINNET_EQUIVALENTS.has(norm)) {
-    return SapNetwork.SOLANA_MAINNET;
-  }
-  if (DEVNET_EQUIVALENTS.has(networkId) || DEVNET_EQUIVALENTS.has(norm)) {
-    return SapNetwork.SOLANA_DEVNET_NAMED;
-  }
-  return norm;
-}
-
-/**
- * @name isKnownNetwork
- * @description Check if a network identifier is recognized by the SDK.
- *
- * @param networkId - The network identifier to check.
- * @returns `true` if the identifier maps to a known Solana network.
- *
- * @category Utils
- * @since v0.6.0
- */
-export function isKnownNetwork(networkId: string): boolean {
-  const trimmed = networkId.trim();
-  return MAINNET_EQUIVALENTS.has(trimmed) || DEVNET_EQUIVALENTS.has(trimmed) ||
-    NETWORK_ALIASES.has(trimmed);
-}

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;
-}