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

package/dist/types/utils/priority-fee.d.ts

@@ -0,0 +1,205 @@
+/**
+ * @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 { type TransactionInstruction } from "@solana/web3.js";
+/**
+ * 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 declare const DEFAULT_SETTLE_PRIORITY_FEE = 5000;
+/**
+ * Default compute unit limit for settlement transactions.
+ * `settle_calls` uses ~60k CU; 100k provides a safe margin.
+ *
+ * @since v0.6.2
+ */
+export declare const DEFAULT_SETTLE_COMPUTE_UNITS = 100000;
+/**
+ * Default compute unit limit for batch settlement transactions.
+ * `settle_batch` with 10 entries uses ~200k CU; 300k provides margin.
+ *
+ * @since v0.6.2
+ */
+export declare const DEFAULT_BATCH_SETTLE_COMPUTE_UNITS = 300000;
+/**
+ * @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 declare function computeBatchSettleCu(entryCount: number): number;
+/**
+ * @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;
+}
+/**
+ * Recommended preset for fast x402 settlements.
+ * Priority fee 5000 µL, 100k CU, skip preflight, confirmed commitment.
+ *
+ * @since v0.6.2
+ */
+export declare const FAST_SETTLE_OPTIONS: Readonly<SettleOptions>;
+/**
+ * Recommended preset for fast batch settlements.
+ * Priority fee 5000 µL, 300k CU, skip preflight, confirmed commitment.
+ *
+ * @since v0.6.2
+ */
+export declare const FAST_BATCH_SETTLE_OPTIONS: Readonly<SettleOptions>;
+/**
+ * @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 declare function buildPriorityFeeIxs(config?: PriorityFeeConfig): TransactionInstruction[];
+/**
+ * @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 declare function buildRpcOptions(opts?: SettleOptions): Record<string, unknown> | undefined;
+//# sourceMappingURL=priority-fee.d.ts.map

package/dist/types/utils/priority-fee.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"priority-fee.d.ts","sourceRoot":"","sources":["../../../src/utils/priority-fee.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,iBAAiB,CAAC;AAMzB;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,OAAQ,CAAC;AAEjD;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,SAAU,CAAC;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,kCAAkC,SAAU,CAAC;AA8B1D;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAM/D;AAMD;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAE3C;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,aAAc,SAAQ,iBAAiB;IACtD;;;;;;;;OAQG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IAEjC;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,WAAW,GAAG,WAAW,GAAG,WAAW,CAAC;IAE9D;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAMD;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,aAAa,CAKtD,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAAC,aAAa,CAK5D,CAAC;AAMH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,CAAC,EAAE,iBAAiB,GACzB,sBAAsB,EAAE,CAwB1B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,IAAI,CAAC,EAAE,aAAa,GACnB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAgBrC"}

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

@@ -0,0 +1,179 @@
+/**
+ * @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;
+export interface SafeRpcOptions {
+    readonly rpcOpts?: Parameters<typeof Object>[0];
+    readonly maxAttempts?: number;
+    readonly skipRetry?: boolean;
+    readonly idempotencyHint?: string;
+}
+export declare function safeRpc(builder: any, label: string, opts?: SafeRpcOptions): Promise<TransactionSignature>;
+//# sourceMappingURL=rpc-strategy.d.ts.map

package/dist/types/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;AAazB;;;;;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;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IAChD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAGD,wBAAsB,OAAO,CAC3B,OAAO,EAAE,GAAG,EACZ,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,cAAc,GACpB,OAAO,CAAC,oBAAoB,CAAC,CAqD/B"}