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

package/dist/esm/utils/priority-fee.js

@@ -0,0 +1,209 @@
+/**
+ * @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, } 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) {
+    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);
+}
+// ═══════════════════════════════════════════════════════════════════
+//  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 = 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 = 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) {
+    if (!config)
+        return [];
+    const ixs = [];
+    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) {
+    if (!opts)
+        return undefined;
+    const rpcOpts = {};
+    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;
+}
+//# sourceMappingURL=priority-fee.js.map

package/dist/esm/utils/priority-fee.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"priority-fee.js","sourceRoot":"","sources":["../../../src/utils/priority-fee.ts"],"names":[],"mappings":"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"}

package/dist/esm/utils/rpc-strategy.d.ts

@@ -0,0 +1,172 @@
+/**
+ * @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";
+/**
+ * @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;
+}
+/**
+ * @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 declare function getRpcUrl(config?: Partial<RpcConfig>, cluster?: string): string;
+/**
+ * @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 declare function getFallbackRpcUrl(config?: Partial<RpcConfig>, cluster?: string): string;
+/**
+ * @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 declare function createDualConnection(config: Partial<RpcConfig>, cluster?: string): DualConnection;
+/**
+ * @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 declare function findATA(owner: PublicKey, mint: PublicKey, programId?: PublicKey): PublicKey;
+/**
+ * @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 declare function classifyAnchorError(errorCode: number): string;
+/**
+ * @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 declare function extractAnchorErrorCode(err: unknown): number | null;
+//# sourceMappingURL=rpc-strategy.d.ts.map

package/dist/esm/utils/rpc-strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc-strategy.d.ts","sourceRoot":"","sources":["../../../src/utils/rpc-strategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,UAAU,EACV,KAAK,UAAU,EACf,SAAS,EACT,KAAK,oBAAoB,EAC1B,MAAM,iBAAiB,CAAC;AAMzB;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,yDAAyD;IACzD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,wBAAwB;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;CAClC;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;CAC/B;AAiBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CACvB,MAAM,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,EAC3B,OAAO,GAAE,MAAuB,GAC/B,MAAM,CASR;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,EAC3B,OAAO,GAAE,MAAuB,GAC/B,MAAM,CAWR;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,OAAO,CAAC,SAAS,CAAC,EAC1B,OAAO,GAAE,MAAuB,GAC/B,cAAc,CAShB;AAMD;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,oDAAoD;IACpD,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B,uCAAuC;IACvC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,qDAAqD;IACrD,QAAQ,CAAC,WAAW,CAAC,EAAE,oBAAoB,CAAC;CAC7C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,OAAO,CACrB,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,SAAS,EACf,SAAS,GAAE,SAAwE,GAClF,SAAS,CAUX;AAiCD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAK7D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAyBlE"}

package/dist/esm/utils/rpc-strategy.js

@@ -0,0 +1,231 @@
+/**
+ * @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, PublicKey, } from "@solana/web3.js";
+// ═══════════════════════════════════════════════════════════════════
+//  Default Public RPCs
+// ═══════════════════════════════════════════════════════════════════
+/** Well-known public fallback RPCs by cluster. */
+const PUBLIC_RPCS = {
+    "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, cluster = "mainnet-beta") {
+    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, cluster = "mainnet-beta") {
+    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, cluster = "mainnet-beta") {
+    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 }),
+    };
+}
+/**
+ * @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, mint, programId = new PublicKey("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA")) {
+    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 = {
+    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) {
+    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) {
+    if (err == null || typeof err !== "object")
+        return null;
+    // Direct code property
+    const direct = err.code;
+    if (typeof direct === "number")
+        return direct;
+    // Nested Anchor format: error.error.errorCode.number
+    const nested = err.error;
+    if (nested && typeof nested === "object") {
+        const errorCode = nested.errorCode;
+        if (errorCode && typeof errorCode === "object") {
+            const num = errorCode.number;
+            if (typeof num === "number")
+                return num;
+        }
+    }
+    // AnchorError pattern: { logs: [...], error: { errorCode: { number } } }
+    const msg = err.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;
+}
+//# sourceMappingURL=rpc-strategy.js.map

package/dist/esm/utils/rpc-strategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc-strategy.js","sourceRoot":"","sources":["../../../src/utils/rpc-strategy.ts"],"names":[],"mappings":"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"}