@oobe-protocol-labs/synapse-sap-sdk 0.5.0 → 0.6.0

package/src/utils/network-normalizer.ts

@@ -0,0 +1,240 @@
+/**
+ * @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/rpc-strategy.ts

@@ -0,0 +1,322 @@
+/**
+ * @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;
+}