@kestrelfi/lyc-sdk 1.0.1

package/dist/shared/common/src/utils/index.js

@@ -0,0 +1,38 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./accounts"), exports);
+__exportStar(require("./data"), exports);
+__exportStar(require("./compat"), exports);
+__exportStar(require("./cpi"), exports);
+__exportStar(require("./instruction"), exports);
+__exportStar(require("./numbers"), exports);
+__exportStar(require("./rpc"), exports);
+__exportStar(require("./jsonRpcFetch"), exports);
+__exportStar(require("./asyncConcurrency"), exports);
+__exportStar(require("./anchor"), exports);
+__exportStar(require("./solana"), exports);
+__exportStar(require("./transaction"), exports);
+__exportStar(require("./transactionSplitter"), exports);
+__exportStar(require("./txAccountCoverage"), exports);
+__exportStar(require("./jito"), exports);
+__exportStar(require("./general"), exports);
+__exportStar(require("./retry"), exports);
+__exportStar(require("./token"), exports);
+__exportStar(require("./timeSeries"), exports);
+__exportStar(require("./metadata"), exports);
+__exportStar(require("./json"), exports);
+__exportStar(require("./priorityFee"), exports);

package/dist/shared/common/src/utils/instruction.d.ts

@@ -0,0 +1,74 @@
+import { BN } from "@anchor-lang/core";
+import { Address, type Instruction, type TransactionSigner, Rpc, SolanaRpcApi } from "@solana/kit";
+import { type BaseAccountClient } from "../services/baseAccountClient";
+import type { TransactionCacheInvalidation } from "../types/general";
+import { CustomAccountMeta } from "../types";
+export declare function setComputeUnitLimitIx(maxComputeUnits: number): Instruction;
+export declare function setComputeUnitPriceIx(microLamports: number): Instruction;
+/**
+ * Request a larger BPF heap for the transaction (default is 32 KiB).
+ * Use for instructions that chain many CPIs and allocate temporary `Vec`s
+ * (e.g. burn-with-unwind through Perena + Kamino).
+ *
+ * @param bytes - Must be a multiple of 1024; Solana allows up to 256 KiB.
+ */
+export declare function requestHeapFrameIx(bytes: number): Instruction;
+/**
+ * Scans accounts for required ATAs, checks which ones exist on-chain in a
+ * single batched RPC call, and returns idempotent create-ATA instructions
+ * for any that are missing.
+ *
+ * @param rpc - Solana RPC client
+ * @param payer - Fee payer for ATA creation
+ * @param accounts - Account metas to scan (from CpiData, etc.)
+ * @returns Create-ATA instructions and SPL ATA cache invalidations for each new ATA
+ */
+export declare function getCreateAtaInstructions(rpc: Rpc<SolanaRpcApi>, payer: Address, accounts: CustomAccountMeta[]): Promise<{
+    instructions: Instruction[];
+    postSuccessCacheInvalidations: TransactionCacheInvalidation[];
+}>;
+export interface GetCreateAtaIxIfNeededOptions {
+    /**
+     * When set, {@link BaseAccountClient#splAtaExists} is used instead of a one-off
+     * `fetchMaybeToken` RPC read (shared cache + consistent behavior with program SDKs).
+     */
+    accountClient?: BaseAccountClient;
+}
+export interface CreateAtaIxIfNeededResult {
+    instruction: Instruction | null;
+    postSuccessCacheInvalidations: TransactionCacheInvalidation[];
+}
+/**
+ * Checks if an ATA exists on-chain and returns a create-ATA instruction if it
+ * doesn't.
+ *
+ * @param rpc - Solana RPC client (used for the default existence check unless overridden)
+ * @param payer - Fee payer for ATA creation
+ * @param mint - Token mint address
+ * @param owner - Owner of the ATA
+ * @param tokenProgram - Token program (defaults to TOKEN_PROGRAM_ADDRESS)
+ * @param options - Optional account client for SPL ATA existence (otherwise uses RPC read)
+ */
+export declare function getCreateAtaIxIfNeeded(rpc: Rpc<SolanaRpcApi>, payer: Address | TransactionSigner, mint: Address, owner: Address, tokenProgram?: Address, options?: GetCreateAtaIxIfNeededOptions): Promise<CreateAtaIxIfNeededResult>;
+export interface WrapSolInstructionsResult {
+    instructions: Instruction[];
+    postSuccessCacheInvalidations: TransactionCacheInvalidation[];
+}
+/**
+ * Returns instructions to wrap SOL into WSOL for a given wallet.
+ *
+ * Creates the WSOL ATA (idempotent), transfers SOL into it, and syncs the
+ * native balance so the token account reflects the deposited lamports.
+ */
+export declare function getWrapSolInstructions(rpc: Rpc<SolanaRpcApi>, owner: Address, payer: TransactionSigner, lamports: BN, createAtaOptions?: GetCreateAtaIxIfNeededOptions): Promise<WrapSolInstructionsResult>;
+/**
+ * Returns instruction to unwrap WSOL back into SOL for a given wallet.
+ *
+ * Closes the WSOL token account, sending all lamports (including the wrapped
+ * SOL balance and the rent-exempt reserve) to the specified destination.
+ *
+ * @param owner - Wallet that owns the WSOL ATA (must be a TransactionSigner to authorize the close)
+ * @param destination - Address to receive the unwrapped SOL (defaults to the owner's address)
+ * @returns Instructions to include in a transaction
+ */
+export declare function getUnwrapSolInstruction(owner: TransactionSigner, destination?: Address): Promise<Instruction>;

package/dist/shared/common/src/utils/instruction.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setComputeUnitLimitIx = setComputeUnitLimitIx;
+exports.setComputeUnitPriceIx = setComputeUnitPriceIx;
+exports.requestHeapFrameIx = requestHeapFrameIx;
+exports.getCreateAtaInstructions = getCreateAtaInstructions;
+exports.getCreateAtaIxIfNeeded = getCreateAtaIxIfNeeded;
+exports.getWrapSolInstructions = getWrapSolInstructions;
+exports.getUnwrapSolInstruction = getUnwrapSolInstruction;
+const compute_budget_1 = require("@solana-program/compute-budget");
+const token_1 = require("@solana-program/token");
+const system_1 = require("@solana-program/system");
+const baseAccountClient_1 = require("../services/baseAccountClient");
+const solana_1 = require("./solana");
+const pda_1 = require("./accounts/pda");
+const rpc_1 = require("./accounts/rpc");
+const mints_1 = require("../services/mints");
+function setComputeUnitLimitIx(maxComputeUnits) {
+    return (0, compute_budget_1.getSetComputeUnitLimitInstruction)({
+        units: maxComputeUnits,
+    });
+}
+function setComputeUnitPriceIx(microLamports) {
+    return (0, compute_budget_1.getSetComputeUnitPriceInstruction)({
+        microLamports,
+    });
+}
+/**
+ * Request a larger BPF heap for the transaction (default is 32 KiB).
+ * Use for instructions that chain many CPIs and allocate temporary `Vec`s
+ * (e.g. burn-with-unwind through Perena + Kamino).
+ *
+ * @param bytes - Must be a multiple of 1024; Solana allows up to 256 KiB.
+ */
+function requestHeapFrameIx(bytes) {
+    return (0, compute_budget_1.getRequestHeapFrameInstruction)({ bytes });
+}
+/**
+ * Scans accounts for required ATAs, checks which ones exist on-chain in a
+ * single batched RPC call, and returns idempotent create-ATA instructions
+ * for any that are missing.
+ *
+ * @param rpc - Solana RPC client
+ * @param payer - Fee payer for ATA creation
+ * @param accounts - Account metas to scan (from CpiData, etc.)
+ * @returns Create-ATA instructions and SPL ATA cache invalidations for each new ATA
+ */
+async function getCreateAtaInstructions(rpc, payer, accounts) {
+    // Collect unique accounts that are marked as required ATAs
+    const requiredAtas = accounts.filter((x) => x.isRequiredAta);
+    if (!requiredAtas.length) {
+        return { instructions: [], postSuccessCacheInvalidations: [] };
+    }
+    const { existsByAddress } = await (0, rpc_1.allAccountsExist)(rpc, requiredAtas.map((account) => account.address));
+    const payerSigner = (0, solana_1.createSignerFromAddress)(payer);
+    const instructions = [];
+    const postSuccessCacheInvalidations = [];
+    for (const account of requiredAtas) {
+        if (!existsByAddress.get(account.address)) {
+            const seeds = account.isRequiredAta;
+            instructions.push((0, token_1.getCreateAssociatedTokenIdempotentInstruction)({
+                payer: payerSigner,
+                ata: account.address,
+                owner: seeds.owner,
+                mint: seeds.mint,
+                tokenProgram: seeds.tokenProgram,
+            }));
+            postSuccessCacheInvalidations.push({ client: baseAccountClient_1.SPL_ATA_CACHE_CATEGORY, ata: account.address });
+        }
+    }
+    return { instructions, postSuccessCacheInvalidations };
+}
+/**
+ * Checks if an ATA exists on-chain and returns a create-ATA instruction if it
+ * doesn't.
+ *
+ * @param rpc - Solana RPC client (used for the default existence check unless overridden)
+ * @param payer - Fee payer for ATA creation
+ * @param mint - Token mint address
+ * @param owner - Owner of the ATA
+ * @param tokenProgram - Token program (defaults to TOKEN_PROGRAM_ADDRESS)
+ * @param options - Optional account client for SPL ATA existence (otherwise uses RPC read)
+ */
+async function getCreateAtaIxIfNeeded(rpc, payer, mint, owner, tokenProgram = token_1.TOKEN_PROGRAM_ADDRESS, options) {
+    const ata = await (0, pda_1.getAtaAddress)(mint, owner, tokenProgram);
+    const exists = options?.accountClient !== undefined
+        ? await options.accountClient.splAtaExists(ata)
+        : (await (0, token_1.fetchMaybeToken)(rpc, ata)).exists;
+    if (exists) {
+        return { instruction: null, postSuccessCacheInvalidations: [] };
+    }
+    const payerSigner = (0, solana_1.isTransactionSigner)(payer) ? payer : (0, solana_1.createSignerFromAddress)(payer);
+    const instruction = (0, token_1.getCreateAssociatedTokenIdempotentInstruction)({
+        payer: payerSigner,
+        ata,
+        owner,
+        mint,
+        tokenProgram,
+    });
+    return {
+        instruction,
+        postSuccessCacheInvalidations: [{ client: baseAccountClient_1.SPL_ATA_CACHE_CATEGORY, ata }],
+    };
+}
+/**
+ * Returns instructions to wrap SOL into WSOL for a given wallet.
+ *
+ * Creates the WSOL ATA (idempotent), transfers SOL into it, and syncs the
+ * native balance so the token account reflects the deposited lamports.
+ */
+async function getWrapSolInstructions(rpc, owner, payer, lamports, createAtaOptions) {
+    const solMint = mints_1.mints.get("SOL");
+    const solMintAddress = solMint.address;
+    const ata = await (0, pda_1.getAtaAddress)(solMintAddress, owner);
+    const { instruction: createAtaIx, postSuccessCacheInvalidations } = await getCreateAtaIxIfNeeded(rpc, payer, solMintAddress, owner, token_1.TOKEN_PROGRAM_ADDRESS, createAtaOptions);
+    const instructions = [];
+    if (createAtaIx)
+        instructions.push(createAtaIx);
+    instructions.push((0, system_1.getTransferSolInstruction)({
+        source: payer,
+        destination: ata,
+        amount: BigInt(lamports.toString()),
+    }), (0, token_1.getSyncNativeInstruction)({ account: ata }));
+    return { instructions, postSuccessCacheInvalidations };
+}
+/**
+ * Returns instruction to unwrap WSOL back into SOL for a given wallet.
+ *
+ * Closes the WSOL token account, sending all lamports (including the wrapped
+ * SOL balance and the rent-exempt reserve) to the specified destination.
+ *
+ * @param owner - Wallet that owns the WSOL ATA (must be a TransactionSigner to authorize the close)
+ * @param destination - Address to receive the unwrapped SOL (defaults to the owner's address)
+ * @returns Instructions to include in a transaction
+ */
+async function getUnwrapSolInstruction(owner, destination) {
+    const solMint = mints_1.mints.get("SOL");
+    if (!solMint)
+        throw new Error("WSOL mint not found in registry");
+    const solMintAddress = solMint.address;
+    const ata = await (0, pda_1.getAtaAddress)(solMintAddress, owner.address);
+    return (0, token_1.getCloseAccountInstruction)({
+        account: ata,
+        destination: destination ?? owner.address,
+        owner,
+    });
+}

package/dist/shared/common/src/utils/jito.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Minimal Jito bundle client.
+ *
+ * Submits bundles via the user's own RPC endpoint rather than Jito's public
+ * block engine. Premium Solana RPC providers (Helius, Ironforge, Triton, etc.)
+ * proxy the Jito JSON-RPC methods (`sendBundle`, `getBundleStatuses`,
+ * `simulateBundle`) through their authenticated endpoint. This avoids the
+ * public Jito endpoint's global rate limit (error `-32097` / HTTP 429).
+ *
+ * Reference implementation: `EXAMPLE/solauto-sdk/src/utils/jitoUtils.ts`,
+ * which routes the same calls through the user's Umi RPC endpoint
+ * (Ironforge).
+ *
+ * Helius sendBundle docs: https://helius.mintlify.app/api-reference/sender/sendbundle
+ */
+import type { Address, Instruction, TransactionSigner } from "@solana/kit";
+/** Max transactions per Jito bundle. */
+export declare const MAX_BUNDLE_TRANSACTIONS = 5;
+/** Default tip when the caller doesn't specify one. */
+export declare const DEFAULT_JITO_TIP_LAMPORTS = 2000000;
+export declare class JitoBundleError extends Error {
+    readonly bundleId?: string | undefined;
+    constructor(message: string, bundleId?: string | undefined);
+}
+/**
+ * Static Jito tip accounts. Hardcoded to avoid a network call to
+ * `getTipAccounts` on every bundle — the list rarely changes.
+ *
+ * Exported so tests can lock in the canonical list against the Jito docs
+ * and catch any future typo. Verify against:
+ * https://docs.jito.wtf/lowlatencytxnsend/#response-example-tips
+ */
+export declare const JITO_TIP_ACCOUNTS: readonly Address[];
+/**
+ * Conservative upper bound (in wire bytes) for the instructions we inject
+ * into each bundle tx _after_ bin-packing: a setComputeUnitLimit ix and,
+ * Used by the splitter to reserve headroom so post-split injection never
+ * overflows the 1232-byte transaction limit. The tip transfer is injected
+ * only into the smallest bin in the bundle, which is typically far from
+ * the size limit, so we don't reserve for it here.
+ *
+ * Breakdown (worst case, ComputeBudget program not in any LUT):
+ *   • ComputeBudget program key                                        = 32 B
+ *   • setComputeUnitLimit ix header + 5 B data                         ≈ 13 B
+ *   • setComputeUnitPrice ix header + 9 B data                         ≈ 17 B
+ * Rounded up to 64 B to cover compact-u16 edge cases.
+ */
+export declare const BUNDLE_INJECTED_IX_RESERVED_BYTES = 64;
+/** Pick one of the 8 Jito tip accounts at random. */
+export declare function getRandomTipAccount(): Address;
+/** Build a SOL transfer instruction to a Jito tip account. */
+export declare function buildTipInstruction(payer: TransactionSigner, tipAccount: Address, lamports: number): Instruction;
+/**
+ * Submit a bundle of base64-encoded signed transactions to Jito via the
+ * caller's RPC endpoint. Returns the `bundle_id` for status polling.
+ *
+ * Helius expects `[base64Txs, { encoding: "base64" }]`; Ironforge and the
+ * raw Jito block engine accept the same shape and fall back to base58 when
+ * encoding is omitted. Using base64 everywhere matches the wire format we
+ * already produce via `getBase64EncodedWireTransaction`.
+ */
+export declare function sendBundle(rpcUrl: string, base64Txs: string[]): Promise<string>;
+export interface BundleSimulationTxResult {
+    /** Tx-level error object, or null on success. */
+    err: object | null;
+    /** Program logs emitted during this tx (may be empty on signature-only failures). */
+    logs: string[];
+    /** Compute units consumed by this tx; absent if the tx errored before CU accounting. */
+    unitsConsumed?: number;
+    /** Tx-level return data, opaque to callers. */
+    returnData?: unknown;
+}
+export interface BundleSimulationResult {
+    /** "succeeded" string when every tx passed; an object containing `failed` otherwise. */
+    summary: "succeeded" | {
+        failed: {
+            error: unknown;
+            txSignature?: string;
+        };
+    };
+    /** Per-tx outcome, in the same order as the bundle's `encodedTransactions`. */
+    transactionResults: BundleSimulationTxResult[];
+}
+/**
+ * Atomically simulate a bundle of base64-encoded transactions through the
+ * caller's RPC endpoint. Mirrors the Jito BlockEngine `simulateBundle` shape,
+ * which Helius/Ironforge/Triton proxy.
+ *
+ * Set `skipSigVerify=true` and `replaceRecentBlockhash=true` (defaults) to
+ * simulate _before_ signing — the simulator stamps placeholder signatures and
+ * substitutes a fresh blockhash, letting us measure per-tx compute units and
+ * verify the bundle composes correctly without paying the signing round trip
+ * twice.
+ *
+ * Unlike running `simulateTransaction` per bin, this preserves the
+ * intra-bundle sequencing — a refresh ix in tx 0 is observable to tx 1 — so
+ * bundles whose sub-txs depend on each other can be validated without false
+ * positives from bin-isolation.
+ */
+export declare function simulateBundle(rpcUrl: string, base64Txs: string[], options?: {
+    skipSigVerify?: boolean;
+    replaceRecentBlockhash?: boolean;
+}): Promise<BundleSimulationResult>;
+/**
+ * Poll `getBundleStatuses` until the bundle confirms or fails.
+ *
+ * Mirrors the solauto reference: a `null` entry means Jito hasn't seen the
+ * bundle yet (keep polling); only `err` with an `Err` key is a failure; a
+ * `confirmation_status` of "confirmed" or "finalized" means success.
+ */
+export declare function confirmBundle(rpcUrl: string, bundleId: string, timeoutMs?: number): Promise<{
+    slot: number;
+}>;

package/dist/shared/common/src/utils/jito.js

@@ -0,0 +1,178 @@
+"use strict";
+/**
+ * Minimal Jito bundle client.
+ *
+ * Submits bundles via the user's own RPC endpoint rather than Jito's public
+ * block engine. Premium Solana RPC providers (Helius, Ironforge, Triton, etc.)
+ * proxy the Jito JSON-RPC methods (`sendBundle`, `getBundleStatuses`,
+ * `simulateBundle`) through their authenticated endpoint. This avoids the
+ * public Jito endpoint's global rate limit (error `-32097` / HTTP 429).
+ *
+ * Reference implementation: `EXAMPLE/solauto-sdk/src/utils/jitoUtils.ts`,
+ * which routes the same calls through the user's Umi RPC endpoint
+ * (Ironforge).
+ *
+ * Helius sendBundle docs: https://helius.mintlify.app/api-reference/sender/sendbundle
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUNDLE_INJECTED_IX_RESERVED_BYTES = exports.JITO_TIP_ACCOUNTS = exports.JitoBundleError = exports.DEFAULT_JITO_TIP_LAMPORTS = exports.MAX_BUNDLE_TRANSACTIONS = void 0;
+exports.getRandomTipAccount = getRandomTipAccount;
+exports.buildTipInstruction = buildTipInstruction;
+exports.sendBundle = sendBundle;
+exports.simulateBundle = simulateBundle;
+exports.confirmBundle = confirmBundle;
+const system_1 = require("@solana-program/system");
+const general_1 = require("./general");
+const jsonRpcFetch_1 = require("./jsonRpcFetch");
+/** Max transactions per Jito bundle. */
+exports.MAX_BUNDLE_TRANSACTIONS = 5;
+/** Default tip when the caller doesn't specify one. */
+exports.DEFAULT_JITO_TIP_LAMPORTS = 2000000;
+class JitoBundleError extends Error {
+    constructor(message, bundleId) {
+        super(message);
+        this.bundleId = bundleId;
+        this.name = "JitoBundleError";
+    }
+}
+exports.JitoBundleError = JitoBundleError;
+/**
+ * Static Jito tip accounts. Hardcoded to avoid a network call to
+ * `getTipAccounts` on every bundle — the list rarely changes.
+ *
+ * Exported so tests can lock in the canonical list against the Jito docs
+ * and catch any future typo. Verify against:
+ * https://docs.jito.wtf/lowlatencytxnsend/#response-example-tips
+ */
+exports.JITO_TIP_ACCOUNTS = [
+    "96gYZGLnJYVFmbjzopPSU6QiEV5fGqZNyN9nmNhvrZU5",
+    "HFqU5x63VTqvQss8hp11i4wVV8bD44PvwucfZ2bU7gRe",
+];
+/**
+ * Conservative upper bound (in wire bytes) for the instructions we inject
+ * into each bundle tx _after_ bin-packing: a setComputeUnitLimit ix and,
+ * Used by the splitter to reserve headroom so post-split injection never
+ * overflows the 1232-byte transaction limit. The tip transfer is injected
+ * only into the smallest bin in the bundle, which is typically far from
+ * the size limit, so we don't reserve for it here.
+ *
+ * Breakdown (worst case, ComputeBudget program not in any LUT):
+ *   • ComputeBudget program key                                        = 32 B
+ *   • setComputeUnitLimit ix header + 5 B data                         ≈ 13 B
+ *   • setComputeUnitPrice ix header + 9 B data                         ≈ 17 B
+ * Rounded up to 64 B to cover compact-u16 edge cases.
+ */
+exports.BUNDLE_INJECTED_IX_RESERVED_BYTES = 64;
+/** Pick one of the 8 Jito tip accounts at random. */
+function getRandomTipAccount() {
+    return exports.JITO_TIP_ACCOUNTS[Math.floor(Math.random() * exports.JITO_TIP_ACCOUNTS.length)];
+}
+/** Build a SOL transfer instruction to a Jito tip account. */
+function buildTipInstruction(payer, tipAccount, lamports) {
+    return (0, system_1.getTransferSolInstruction)({
+        source: payer,
+        destination: tipAccount,
+        amount: BigInt(lamports),
+    });
+}
+/**
+ * Submit a bundle of base64-encoded signed transactions to Jito via the
+ * caller's RPC endpoint. Returns the `bundle_id` for status polling.
+ *
+ * Helius expects `[base64Txs, { encoding: "base64" }]`; Ironforge and the
+ * raw Jito block engine accept the same shape and fall back to base58 when
+ * encoding is omitted. Using base64 everywhere matches the wire format we
+ * already produce via `getBase64EncodedWireTransaction`.
+ */
+async function sendBundle(rpcUrl, base64Txs) {
+    if (base64Txs.length > exports.MAX_BUNDLE_TRANSACTIONS) {
+        throw new JitoBundleError(`Bundle has ${base64Txs.length} transactions, max is ${exports.MAX_BUNDLE_TRANSACTIONS}`);
+    }
+    try {
+        return await (0, jsonRpcFetch_1.jsonRpcFetchOnce)(rpcUrl, "sendBundle", [
+            base64Txs,
+            { encoding: "base64" },
+        ]);
+    }
+    catch (e) {
+        throw new JitoBundleError(`sendBundle failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+/**
+ * Atomically simulate a bundle of base64-encoded transactions through the
+ * caller's RPC endpoint. Mirrors the Jito BlockEngine `simulateBundle` shape,
+ * which Helius/Ironforge/Triton proxy.
+ *
+ * Set `skipSigVerify=true` and `replaceRecentBlockhash=true` (defaults) to
+ * simulate _before_ signing — the simulator stamps placeholder signatures and
+ * substitutes a fresh blockhash, letting us measure per-tx compute units and
+ * verify the bundle composes correctly without paying the signing round trip
+ * twice.
+ *
+ * Unlike running `simulateTransaction` per bin, this preserves the
+ * intra-bundle sequencing — a refresh ix in tx 0 is observable to tx 1 — so
+ * bundles whose sub-txs depend on each other can be validated without false
+ * positives from bin-isolation.
+ */
+async function simulateBundle(rpcUrl, base64Txs, options = {}) {
+    const { skipSigVerify = true, replaceRecentBlockhash = true } = options;
+    if (base64Txs.length > exports.MAX_BUNDLE_TRANSACTIONS) {
+        throw new JitoBundleError(`Bundle has ${base64Txs.length} transactions, max is ${exports.MAX_BUNDLE_TRANSACTIONS}`);
+    }
+    try {
+        // `preExecutionAccountsConfigs` and `postExecutionAccountsConfigs` are
+        // required fields (one entry per tx) on Jito's BlockEngine and on
+        // proxying providers (Helius). We don't read pre/post account state, so
+        // each entry is left as `null`.
+        const accountsConfigs = base64Txs.map(() => null);
+        // Some endpoints return `{ context, value: { ... } }` (Helius) and others
+        // return the result directly (raw Jito). Normalize by unwrapping `value`
+        // when present.
+        const raw = await (0, jsonRpcFetch_1.jsonRpcFetchOnce)(rpcUrl, "simulateBundle", [
+            { encodedTransactions: base64Txs },
+            {
+                preExecutionAccountsConfigs: accountsConfigs,
+                postExecutionAccountsConfigs: accountsConfigs,
+                skipSigVerify,
+                replaceRecentBlockhash,
+                transactionEncoding: "base64",
+            },
+        ]);
+        return "value" in raw && raw.value ? raw.value : raw;
+    }
+    catch (e) {
+        throw new JitoBundleError(`simulateBundle failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+/**
+ * Poll `getBundleStatuses` until the bundle confirms or fails.
+ *
+ * Mirrors the solauto reference: a `null` entry means Jito hasn't seen the
+ * bundle yet (keep polling); only `err` with an `Err` key is a failure; a
+ * `confirmation_status` of "confirmed" or "finalized" means success.
+ */
+async function confirmBundle(rpcUrl, bundleId, timeoutMs = 60000) {
+    const pollIntervalMs = 1000;
+    const startTime = Date.now();
+    while (Date.now() - startTime < timeoutMs) {
+        await (0, general_1.sleep)(pollIntervalMs);
+        let result;
+        try {
+            result = await (0, jsonRpcFetch_1.jsonRpcFetchOnce)(rpcUrl, "getBundleStatuses", [[bundleId]]);
+        }
+        catch (e) {
+            console.warn(`[Jito] getBundleStatuses error: ${e instanceof Error ? e.message : String(e)}`);
+            continue;
+        }
+        const entry = result.value?.[0];
+        if (!entry)
+            continue;
+        if (entry.err != null && "Err" in entry.err) {
+            throw new JitoBundleError(`Bundle ${bundleId} failed: ${JSON.stringify(entry.err)}`, bundleId);
+        }
+        if (entry.confirmation_status === "confirmed" || entry.confirmation_status === "finalized") {
+            return { slot: entry.slot };
+        }
+    }
+    throw new JitoBundleError(`Bundle ${bundleId} confirmation timeout after ${timeoutMs}ms`, bundleId);
+}

package/dist/shared/common/src/utils/json.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Recursively converts `bigint` values to decimal strings so values with
+ * on-chain raw amounts are JSON-serializable.
+ */
+export declare function serializeForJson<T>(value: T): unknown;

package/dist/shared/common/src/utils/json.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeForJson = serializeForJson;
+/**
+ * Recursively converts `bigint` values to decimal strings so values with
+ * on-chain raw amounts are JSON-serializable.
+ */
+function serializeForJson(value) {
+    if (typeof value === "bigint") {
+        return value.toString();
+    }
+    if (value === null || value === undefined) {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => serializeForJson(item));
+    }
+    if (typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [
+            key,
+            serializeForJson(entry),
+        ]));
+    }
+    return value;
+}

package/dist/shared/common/src/utils/jsonRpcFetch.d.ts

@@ -0,0 +1,21 @@
+/** Thrown when the JSON-RPC error should be retried (rate limits, transient HTTP, transport). */
+export declare class JsonRpcTransientError extends Error {
+    readonly suggestedDelayMs?: number | undefined;
+    constructor(message: string, suggestedDelayMs?: number | undefined);
+}
+/**
+ * Serialize async work and enforce a minimum gap (ms) between the end of one
+ * invocation and the start of the next. Use `minIntervalMs === 0` to disable.
+ */
+export declare function createMinIntervalThrottle(minIntervalMs: number): <T>(fn: () => Promise<T>) => Promise<T>;
+/**
+ * One JSON-RPC 2.0 POST. Uses raw `fetch` so response JSON matches RPC wire
+ * shape (e.g. Helius webhooks) without SDK bigint coercion.
+ */
+export declare function jsonRpcFetchOnce<T>(rpcUrl: string, method: string, params: unknown[]): Promise<T>;
+export type JsonRpcThrottle = <T>(fn: () => Promise<T>) => Promise<T>;
+/**
+ * JSON-RPC call with throttling + exponential backoff on {@link JsonRpcTransientError}.
+ */
+export declare function jsonRpcFetchWithRetries<T>(throttle: JsonRpcThrottle, rpcUrl: string, method: string, params: unknown[], maxAttempts: number, baseDelayMs: number): Promise<T>;
+export type JsonRpcCall = <T>(method: string, params: unknown[]) => Promise<T>;