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

package/dist/esm/utils/merchant-validator.d.ts

@@ -0,0 +1,176 @@
+/**
+ * @module utils/merchant-validator
+ * @description Standard Synapse merchant middleware for x402 settlement.
+ *
+ * Reads `X-Payment-*` headers from incoming HTTP requests, validates
+ * the escrow on-chain, auto-generates the correct `AccountMeta[]`,
+ * and throws explicit errors (e.g. {@link MissingEscrowAtaError})
+ * instead of letting the program return a generic crash.
+ *
+ * Designed for agents like Syra/Invoica that receive x402 payments.
+ *
+ * @category Utils
+ * @since v0.6.4
+ */
+import { type PublicKey, type Connection, type AccountMeta } from "@solana/web3.js";
+import { BN } from "@coral-xyz/anchor";
+import type { EscrowValidationResult } from "./escrow-validation";
+import type { EscrowAccountData } from "../types";
+/**
+ * @interface ParsedX402Headers
+ * @description Parsed and typed x402 payment headers from incoming HTTP request.
+ * @category Utils
+ * @since v0.6.4
+ */
+export interface ParsedX402Headers {
+    /** x402 protocol identifier — must be "SAP-x402". */
+    readonly protocol: string;
+    /** Escrow PDA address. */
+    readonly escrowPda: PublicKey;
+    /** Agent PDA address. */
+    readonly agentPda: PublicKey;
+    /** Depositor wallet address. */
+    readonly depositorWallet: PublicKey;
+    /** Max calls allowed. */
+    readonly maxCalls: BN;
+    /** Price per call. */
+    readonly pricePerCall: BN;
+    /** SAP program ID. */
+    readonly programId: PublicKey;
+    /** Network identifier. */
+    readonly network: string;
+}
+/**
+ * @interface MerchantValidationResult
+ * @description Complete validation result for merchant-side x402 processing.
+ * @category Utils
+ * @since v0.6.4
+ */
+export interface MerchantValidationResult {
+    /** Whether the escrow is valid and ready for settlement. */
+    readonly valid: boolean;
+    /** Parsed x402 headers. */
+    readonly headers: ParsedX402Headers;
+    /** Full escrow validation result. */
+    readonly escrowValidation: EscrowValidationResult;
+    /** Pre-built AccountMeta[] for settlement TX (empty for SOL escrows). */
+    readonly accountMetas: AccountMeta[];
+    /** All validation errors. */
+    readonly errors: string[];
+}
+/**
+ * @name parseX402Headers
+ * @description Parse and validate x402 headers from an HTTP request.
+ *
+ * @param headers - HTTP headers object (case-insensitive key lookup).
+ * @returns Parsed x402 headers.
+ * @throws {SapValidationError} If required headers are missing or malformed.
+ *
+ * @category Utils
+ * @since v0.6.4
+ */
+export declare function parseX402Headers(headers: Record<string, string | string[] | undefined>): ParsedX402Headers;
+/**
+ * @name SapMerchantValidator
+ * @description Standard Synapse merchant middleware for x402 payment validation.
+ *
+ * Reads `X-Payment-*` headers, validates escrow state on-chain, generates
+ * correct `AccountMeta[]` for SPL token escrows, and throws explicit errors
+ * (e.g. {@link MissingEscrowAtaError}) when ATA accounts are missing.
+ *
+ * @category Utils
+ * @since v0.6.4
+ *
+ * @example
+ * ```ts
+ * const validator = new SapMerchantValidator(connection, fetchEscrow);
+ *
+ * // Express.js integration
+ * app.post("/api/v1/chat", async (req, res) => {
+ *   try {
+ *     const validation = await validator.validateRequest(req.headers, {
+ *       callsToSettle: 1,
+ *     });
+ *
+ *     if (!validation.valid) {
+ *       return res.status(402).json({ errors: validation.errors });
+ *     }
+ *
+ *     // Process request...
+ *
+ *     // Settle payment using pre-built account metas
+ *     await client.escrow.settle(
+ *       validation.headers.depositorWallet,
+ *       1,
+ *       serviceHash,
+ *       validation.accountMetas,
+ *     );
+ *
+ *     res.json({ result: "..." });
+ *   } catch (err) {
+ *     if (err instanceof MissingEscrowAtaError) {
+ *       return res.status(402).json({
+ *         error: err.message,
+ *         side: err.side,
+ *         ata: err.ataAddress,
+ *       });
+ *     }
+ *     throw err;
+ *   }
+ * });
+ * ```
+ */
+export declare class SapMerchantValidator {
+    private readonly connection;
+    private readonly fetchEscrow;
+    /**
+     * @param connection  - Solana RPC connection.
+     * @param fetchEscrow - Callback to fetch escrow account data by PDA.
+     *   Typically `(pda) => client.escrow.fetchByPda(pda).catch(() => null)`.
+     */
+    constructor(connection: Connection, fetchEscrow: (escrowPda: PublicKey) => Promise<EscrowAccountData | null>);
+    /**
+     * @name validateRequest
+     * @description Full validation pipeline for an incoming x402 request.
+     *
+     * Steps:
+     * 1. Parse `X-Payment-*` headers
+     * 2. Fetch escrow on-chain
+     * 3. Validate escrow state (balance, expiry, max calls)
+     * 4. If SPL escrow: validate ATAs exist and mint matches
+     * 5. Build `AccountMeta[]` for settlement TX
+     *
+     * @param headers - HTTP headers from the incoming request.
+     * @param opts
+     * @param opts.callsToSettle     - Number of calls to validate affordability for (default: 1).
+     * @param opts.throwOnMissingAta - Throw {@link MissingEscrowAtaError} instead of returning errors (default: true).
+     *
+     * @returns A complete {@link MerchantValidationResult}.
+     *
+     * @throws {SapValidationError} If headers are missing or malformed.
+     * @throws {MissingEscrowAtaError} If SPL ATAs are missing and `throwOnMissingAta` is true.
+     *
+     * @category Utils
+     * @since v0.6.4
+     */
+    validateRequest(headers: Record<string, string | string[] | undefined>, opts?: {
+        callsToSettle?: number;
+        throwOnMissingAta?: boolean;
+    }): Promise<MerchantValidationResult>;
+    /**
+     * @name validateEscrow
+     * @description Validate escrow from pre-parsed headers (convenience method).
+     * Call this when you've already parsed the headers yourself.
+     *
+     * @param headers - Pre-parsed x402 headers.
+     * @param opts
+     * @returns The escrow validation result with pre-built account metas.
+     *
+     * @category Utils
+     * @since v0.6.4
+     */
+    validateEscrow(headers: ParsedX402Headers, opts?: {
+        callsToSettle?: number;
+    }): Promise<EscrowValidationResult>;
+}
+//# sourceMappingURL=merchant-validator.d.ts.map

package/dist/esm/utils/merchant-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merchant-validator.d.ts","sourceRoot":"","sources":["../../../src/utils/merchant-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,WAAW,EACjB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,EAAE,EAAE,MAAM,mBAAmB,CAAC;AAMvC,OAAO,KAAK,EACV,sBAAsB,EACvB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAMlD;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,0BAA0B;IAC1B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,yBAAyB;IACzB,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,gCAAgC;IAChC,QAAQ,CAAC,eAAe,EAAE,SAAS,CAAC;IACpC,yBAAyB;IACzB,QAAQ,CAAC,QAAQ,EAAE,EAAE,CAAC;IACtB,sBAAsB;IACtB,QAAQ,CAAC,YAAY,EAAE,EAAE,CAAC;IAC1B,sBAAsB;IACtB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,0BAA0B;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,2BAA2B;IAC3B,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IACpC,qCAAqC;IACrC,QAAQ,CAAC,gBAAgB,EAAE,sBAAsB,CAAC;IAClD,yEAAyE;IACzE,QAAQ,CAAC,YAAY,EAAE,WAAW,EAAE,CAAC;IACrC,6BAA6B;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;CAC3B;AAkBD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,GACrD,iBAAiB,CA6EnB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IACxC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAEW;IAEvC;;;;OAIG;gBAED,UAAU,EAAE,UAAU,EACtB,WAAW,EAAE,CACX,SAAS,EAAE,SAAS,KACjB,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAMxC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,eAAe,CACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,EACtD,IAAI,CAAC,EAAE;QACL,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,iBAAiB,CAAC,EAAE,OAAO,CAAC;KAC7B,GACA,OAAO,CAAC,wBAAwB,CAAC;IAwCpC;;;;;;;;;;;OAWG;IACG,cAAc,CAClB,OAAO,EAAE,iBAAiB,EAC1B,IAAI,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,GAChC,OAAO,CAAC,sBAAsB,CAAC;CASnC"}

package/dist/esm/utils/merchant-validator.js

@@ -15,7 +15,7 @@
 import { PublicKey as PK } from "@solana/web3.js";
 import { BN } from "@coral-xyz/anchor";
 import { validateEscrowState, toAccountMetas, MissingEscrowAtaError, } from "./escrow-validation";
-import { SapValidationError } from "../errors";
+import { SapValidationError } from "../errors/index";
 // ═══════════════════════════════════════════════════════════════════
 //  Header parsing
 // ═══════════════════════════════════════════════════════════════════

package/dist/esm/utils/merchant-validator.js.map

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

package/dist/esm/utils/network-normalizer.d.ts

@@ -0,0 +1,120 @@
+/**
+ * @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 { type SapNetworkId } from "../constants/network";
+/**
+ * @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 declare function normalizeNetworkId(raw: string): SapNetworkId | string;
+/**
+ * @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 declare function isNetworkEquivalent(a: string, b: string): boolean;
+/**
+ * @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 declare function getNetworkGenesisHash(networkId: string): string;
+/**
+ * @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 declare function getNetworkClusterName(networkId: string): string;
+/**
+ * @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 declare function isKnownNetwork(networkId: string): boolean;
+//# sourceMappingURL=network-normalizer.d.ts.map

package/dist/esm/utils/network-normalizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"network-normalizer.d.ts","sourceRoot":"","sources":["../../../src/utils/network-normalizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAc,KAAK,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAsDrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,GAAG,MAAM,CAcrE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CA2BjE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAS/D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAS/D;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAIzD"}

package/dist/esm/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/esm/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"}