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

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

@@ -1,205 +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 { 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

@@ -1 +0,0 @@
-{"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

@@ -1,179 +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";
-/**
- * @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

@@ -1 +0,0 @@
-{"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"}