@kestrelfi/lyc-sdk 1.0.1

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

@@ -0,0 +1,585 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransactionError = exports.HEAVY_CPI_COMPUTE_UNIT_LIMIT_MULTIPLIER = exports.DEFAULT_COMPUTE_UNIT_LIMIT_MULTIPLIER = void 0;
+exports.computeUnitLimitFromSimulation = computeUnitLimitFromSimulation;
+exports.buildTransactionMessage = buildTransactionMessage;
+exports.simulateTransaction = simulateTransaction;
+exports.signSendAndConfirmTransaction = signSendAndConfirmTransaction;
+const kit_1 = require("@solana/kit");
+const instruction_1 = require("./instruction");
+const lutManager_1 = require("../services/lutManager");
+const general_1 = require("./general");
+const constants_1 = require("../constants");
+const jito_1 = require("./jito");
+const jsonRpcFetch_1 = require("./jsonRpcFetch");
+const retry_1 = require("./retry");
+const rpc_1 = require("./rpc");
+const priorityFee_1 = require("./priorityFee");
+const transactionSplitter_1 = require("./transactionSplitter");
+const MAX_COMPUTE_UNIT_LIMIT = 1400000;
+/** Default headroom over simulated CU usage for typical operator transactions. */
+exports.DEFAULT_COMPUTE_UNIT_LIMIT_MULTIPLIER = 1.1;
+/**
+ * Headroom for txs with deep CPI stacks (Jupiter + external liquidity mint/deposit).
+ * Simulation often undershoots on-chain usage by more than 10%.
+ */
+exports.HEAVY_CPI_COMPUTE_UNIT_LIMIT_MULTIPLIER = 1.2;
+function computeUnitLimitFromSimulation(unitsConsumed, multiplier = exports.DEFAULT_COMPUTE_UNIT_LIMIT_MULTIPLIER) {
+    if (!(unitsConsumed > 0) || !(multiplier > 0)) {
+        return MAX_COMPUTE_UNIT_LIMIT;
+    }
+    return Math.min(MAX_COMPUTE_UNIT_LIMIT, Math.ceil(unitsConsumed * multiplier));
+}
+/** Distinct writable account addresses across `instructions`. */
+function collectWritableAccounts(instructions) {
+    const seen = new Set();
+    const out = [];
+    for (const ix of instructions) {
+        for (const acc of ix.accounts ?? []) {
+            // Account flags: 1 = writable in Kit's `IAccountMeta` (signer is bit 0).
+            const role = acc.role;
+            if (role != null && (role & 1) === 1) {
+                const addr = acc.address;
+                if (!seen.has(addr)) {
+                    seen.add(addr);
+                    out.push(addr);
+                }
+            }
+        }
+    }
+    return out;
+}
+async function signTransactionsWithSigners(transactions, signers) {
+    let signedTransactions = [...transactions];
+    const modifyingSigners = signers.filter(kit_1.isTransactionModifyingSigner);
+    const partialSigners = signers.filter(kit_1.isTransactionPartialSigner);
+    for (const signer of modifyingSigners) {
+        signedTransactions = [...(await signer.modifyAndSignTransactions(signedTransactions))];
+    }
+    for (const signer of partialSigners) {
+        const signatures = await signer.signTransactions(signedTransactions);
+        signedTransactions = signedTransactions.map((transaction, index) => ({
+            ...transaction,
+            signatures: {
+                ...transaction.signatures,
+                ...signatures[index],
+            },
+        }));
+    }
+    for (const transaction of signedTransactions) {
+        (0, kit_1.assertIsFullySignedTransaction)(transaction);
+    }
+    return signedTransactions;
+}
+/**
+ * Error thrown when a transaction simulation or on-chain execution fails.
+ * Carries the raw Solana program logs so callers (e.g. NestJS services)
+ * can log them through their own structured logger instead of dumping
+ * to stdout via `console.error`.
+ */
+class TransactionError extends Error {
+    constructor(message, programLogs = []) {
+        super(programLogs.length ? `${message}\n\nProgram logs:\n${programLogs.join("\n")}` : message);
+        this.name = "TransactionError";
+        this.programLogs = programLogs;
+    }
+}
+exports.TransactionError = TransactionError;
+function logProgramLogsLineByLine(logs, label = "Program logs") {
+    if (!logs.length) {
+        console.error(`${label}: (no logs returned)`);
+        return;
+    }
+    console.error(`${label} (${logs.length} lines):`);
+    logs.forEach((line, index) => {
+        console.error(`[${index}] ${line}`);
+    });
+}
+async function resolvePriorityFeeMicroLamports(rpc, transactionMessage, writableAccounts, options) {
+    if (options?.computeUnitPriceMicroLamports !== undefined) {
+        return options.computeUnitPriceMicroLamports;
+    }
+    if (options?.priorityFeeSetting === undefined) {
+        return undefined;
+    }
+    const estimateMessage = (0, kit_1.appendTransactionMessageInstructions)([(0, instruction_1.setComputeUnitLimitIx)(MAX_COMPUTE_UNIT_LIMIT)], transactionMessage);
+    const estimateTransaction = (0, kit_1.getBase64EncodedWireTransaction)((0, kit_1.compileTransaction)(estimateMessage));
+    return (0, priorityFee_1.getPriorityFeeEstimate)(rpc, estimateTransaction, writableAccounts, options.priorityFeeSetting);
+}
+function getComputeBudgetInstructions(computeUnitLimit, priorityFeeMicroLamports) {
+    return priorityFeeMicroLamports === undefined
+        ? [(0, instruction_1.setComputeUnitLimitIx)(computeUnitLimit)]
+        : [(0, instruction_1.setComputeUnitPriceIx)(priorityFeeMicroLamports), (0, instruction_1.setComputeUnitLimitIx)(computeUnitLimit)];
+}
+/**
+ * Build a transaction message from instructions with embedded signers.
+ *
+ * @param rpc - Solana RPC client
+ * @param feePayer - Fee payer with TransactionSigner (signer will be embedded)
+ * @param instructions - Instructions to include
+ * @param lookupTableAddresses - Optional lookup tables for compression
+ * @param additionalSigners - Optional additional signers beyond fee payer
+ * @param blockhash - Optional blockhash (fetched if not provided)
+ */
+async function buildTransactionMessage(rpc, feePayer, instructions, lookupTableAddresses, additionalSigners, blockhash) {
+    const blockhashInfo = blockhash ??
+        (await rpc.getLatestBlockhash({ commitment: "confirmed" }).send()).value;
+    let transactionMessage = (0, kit_1.pipe)((0, kit_1.createTransactionMessage)({ version: 0 }), (tx) => (0, kit_1.setTransactionMessageFeePayerSigner)(feePayer, tx), (tx) => (0, kit_1.setTransactionMessageLifetimeUsingBlockhash)(blockhashInfo, tx), (tx) => (0, kit_1.appendTransactionMessageInstructions)(instructions, tx));
+    // Attach all signers (fee payer + additional) to instruction accounts that need them
+    const allSigners = [feePayer, ...(additionalSigners ?? [])];
+    transactionMessage = (0, kit_1.addSignersToTransactionMessage)(allSigners, transactionMessage);
+    if (lookupTableAddresses?.length) {
+        const lutInputs = await lutManager_1.lutManager.getLookupTableInputs(rpc, (0, general_1.deduplicateAccounts)(lookupTableAddresses));
+        const lookupTables = {};
+        for (const lut of lutInputs) {
+            lookupTables[lut.address] = [...lut.addresses];
+        }
+        transactionMessage = (0, kit_1.compressTransactionMessageUsingAddressLookupTables)(transactionMessage, lookupTables);
+    }
+    return transactionMessage;
+}
+/**
+ * Simulate a transaction message without requiring real signatures.
+ *
+ * Compiles the message into a wire-format transaction (with placeholder
+ * signatures), sends it to `simulateTransaction` with signature verification
+ * disabled, and validates the same recent blockhash that will be signed and
+ * sent if simulation succeeds.
+ *
+ * @param rpc - Solana RPC client
+ * @param transactionMessage - A compilable transaction message (with embedded signers)
+ */
+async function simulateTransaction(rpc, transactionMessage) {
+    const compiledTransaction = (0, kit_1.compileTransaction)(transactionMessage);
+    const base64EncodedTransaction = (0, kit_1.getBase64EncodedWireTransaction)(compiledTransaction);
+    const { value: { err, logs, unitsConsumed }, } = await rpc
+        .simulateTransaction(base64EncodedTransaction, {
+        encoding: "base64",
+        sigVerify: false,
+        replaceRecentBlockhash: false,
+        commitment: "confirmed",
+    })
+        .send();
+    return {
+        err: err,
+        logs: logs ?? [],
+        unitsConsumed: unitsConsumed ?? 0n,
+    };
+}
+/**
+ * Build, sign, send, and confirm a transaction using embedded signers.
+ *
+ * Use this with instructions that have TransactionSigner objects embedded
+ * in their accounts.
+ *
+ * @param rpc - Solana RPC client
+ * @param payer - Fee payer with TransactionSigner
+ * @param instructionsOrPlan - Kit Instructions or a composed transaction plan
+ *                             (with embedded signers)
+ * @param options - Optional configuration
+ * @returns Transaction signature
+ *
+ * @example
+ * ```typescript
+ * const sig = await signSendAndConfirmTransaction(rpc, payer, [
+ *   computeBudgetIx,
+ *   transferIx,
+ * ]);
+ * ```
+ */
+async function signSendAndConfirmTransaction(rpc, payer, instructionsOrPlan, options) {
+    const instructions = Array.isArray(instructionsOrPlan)
+        ? instructionsOrPlan
+        : instructionsOrPlan.instructions;
+    const lookupTables = Array.isArray(instructionsOrPlan)
+        ? options?.lookupTables
+        : (options?.lookupTables ?? instructionsOrPlan.lookupTables);
+    const segmentLengths = Array.isArray(instructionsOrPlan)
+        ? undefined
+        : instructionsOrPlan.segmentLengths;
+    const freshBinSegments = Array.isArray(instructionsOrPlan)
+        ? undefined
+        : instructionsOrPlan.freshBinSegments;
+    const filteredLuts = lookupTables?.filter((x) => x !== constants_1.DEFAULT_PUBLIC_KEY);
+    // Build transaction message with embedded signers
+    const transactionMessage = await buildTransactionMessage(rpc, payer, instructions, filteredLuts, options?.additionalSigners);
+    // Reserve room for compute-budget instructions added after this measurement.
+    // Also route to the split path whenever the plan declares
+    // `freshBinSegments`, since those boundaries only take effect there.
+    const txBytes = (0, transactionSplitter_1.measureTxBytes)(transactionMessage);
+    const maxUnaugmentedTxBytes = transactionSplitter_1.SOLANA_TX_SIZE_LIMIT - jito_1.BUNDLE_INJECTED_IX_RESERVED_BYTES;
+    const mustSplit = txBytes > maxUnaugmentedTxBytes || options?.forceJitoBundle || !!freshBinSegments?.length;
+    if (mustSplit) {
+        if (options?.sendOversizedAsSequentialTransactions) {
+            return signSendAndConfirmSplitSequentially(rpc, payer, instructions, filteredLuts, options, segmentLengths, freshBinSegments);
+        }
+        return _signSendAndConfirmBundle(rpc, payer, instructions, filteredLuts, options, segmentLengths, freshBinSegments);
+    }
+    // ── Single-transaction happy path ──
+    // Resolve the caller's explicit price or provider-routed priority level. If
+    // neither is provided, the transaction carries no compute-unit-price instruction.
+    const writableAccounts = collectWritableAccounts(instructions);
+    const priorityFeeMicroLamports = await resolvePriorityFeeMicroLamports(rpc, transactionMessage, writableAccounts, options);
+    // Simulate with the max CU limit and, when requested, the chosen priority
+    // fee. Matching the final compute-budget instructions keeps preflight costs
+    // consistent with the on-chain transaction.
+    const simMessage = (0, kit_1.appendTransactionMessageInstructions)(getComputeBudgetInstructions(MAX_COMPUTE_UNIT_LIMIT, priorityFeeMicroLamports), transactionMessage);
+    const simulation = await simulateTransaction(rpc, simMessage);
+    if (simulation.err) {
+        if (!options?.hideFailureInfo) {
+            console.error("Simulation failed:", simulation.err);
+            logProgramLogsLineByLine(simulation.logs, "Simulation logs");
+        }
+        const errStr = JSON.stringify(simulation.err, (_, v) => typeof v === "bigint" ? v.toString() : v);
+        throw new TransactionError(`Transaction simulation failed: ${errStr}`, simulation.logs);
+    }
+    // Append the measured CU limit (with headroom) and the optional priority fee.
+    const computeUnits = computeUnitLimitFromSimulation(Number(simulation.unitsConsumed), options?.computeUnitLimitMultiplier ?? exports.DEFAULT_COMPUTE_UNIT_LIMIT_MULTIPLIER);
+    const finalMessage = (0, kit_1.appendTransactionMessageInstructions)(getComputeBudgetInstructions(computeUnits, priorityFeeMicroLamports), transactionMessage);
+    // Sign with embedded signers
+    const signedTx = await (0, kit_1.signTransactionMessageWithSigners)(finalMessage);
+    // Send transaction
+    const base64EncodedTransaction = (0, kit_1.getBase64EncodedWireTransaction)(signedTx);
+    const signature = (0, kit_1.getSignatureFromTransaction)(signedTx);
+    await rpc
+        .sendTransaction(base64EncodedTransaction, {
+        encoding: "base64",
+        skipPreflight: true,
+    })
+        .send();
+    // Confirm transaction at the specified commitment level
+    try {
+        await confirmTransaction(rpc, signature, "confirmed");
+        options?.onSuccess?.();
+        return signature;
+    }
+    catch (error) {
+        // Before declaring failure, ask the RPC for the on-chain truth. The
+        // confirmation loop can fail for reasons unrelated to the tx itself
+        // (timeout, upstream provider returning "All providers failed", etc.),
+        // and in those cases the tx may have actually landed.
+        let logs = [];
+        let landedSuccessfully = false;
+        try {
+            const info = await rpc
+                .getTransaction(signature, { commitment: "confirmed", encoding: "base64" })
+                .send();
+            if (info) {
+                logs = (info.meta?.logMessages ?? []);
+                if (info.meta?.err == null) {
+                    landedSuccessfully = true;
+                }
+            }
+        }
+        catch {
+            // Best-effort lookup; if this also fails, we fall through and throw.
+        }
+        if (landedSuccessfully) {
+            console.warn(`Confirmation polling failed for signature ${signature} but the transaction landed on-chain; treating as success. Reason: ${error instanceof Error ? error.message : String(error)}`);
+            options?.onSuccess?.();
+            return signature;
+        }
+        if (!options?.hideFailureInfo) {
+            console.error("Transaction failed:", error);
+            logProgramLogsLineByLine(logs, "Transaction logs");
+        }
+        throw new TransactionError(`Transaction failed: ${error}`, logs);
+    }
+}
+/**
+ * Build and sign one split bin.
+ */
+async function signSplitBin(rpc, payer, bin, lookupTables, additionalSigners, blockhash, priorityFeeMicroLamports) {
+    const msg = await buildTransactionMessage(rpc, payer, bin, lookupTables, additionalSigners, blockhash);
+    const finalMsg = (0, kit_1.appendTransactionMessageInstructions)(getComputeBudgetInstructions(MAX_COMPUTE_UNIT_LIMIT, priorityFeeMicroLamports), msg);
+    const signed = await (0, kit_1.signTransactionMessageWithSigners)(finalMsg);
+    return {
+        wireB64: (0, kit_1.getBase64EncodedWireTransaction)(signed),
+        signature: (0, kit_1.getSignatureFromTransaction)(signed),
+    };
+}
+/**
+ * Split an oversize instruction list into multiple transactions and submit
+ * them atomically as a Jito bundle. If Jito is disabled (`jitoTipLamports === 0`),
+ * throws instead of bundling.
+ *
+ * Bundle simulation runs through the RPC's `simulateBundle` (instead of a
+ * per-bin `simulateTransaction`) so intra-bundle dependencies — e.g. a
+ * refresh ix in bin 0 that the rebalance ix in bin 1 relies on — are honored
+ * by the simulator the same way they are by atomic bundle execution. The
+ * simulation skips signature verification but validates the same shared
+ * blockhash that is retained for final signing.
+ */
+async function _signSendAndConfirmBundle(rpc, payer, instructions, lookupTables, options, segmentLengths, freshBinSegments) {
+    const tipLamports = options?.jitoTipLamports ?? jito_1.DEFAULT_JITO_TIP_LAMPORTS;
+    if (tipLamports === 0) {
+        throw new TransactionError("Transaction exceeds the Solana size limit and Jito bundling is disabled. " +
+            "Set jitoTipLamports > 0 to enable bundle fallback.");
+    }
+    // Fetch one blockhash and reuse it for every tx in the bundle. This
+    // avoids redundant RPC calls during splitting + per-bin build, and
+    // ensures the whole bundle shares a single liveness window.
+    const { value: blockhash } = (await rpc
+        .getLatestBlockhash({ commitment: "confirmed" })
+        .send());
+    // Split instructions, reserving headroom for the compute-unit-limit ix
+    // that gets appended to every bin and the Jito tip ix that gets appended
+    // to one bin. Without reservation, a near-full bin would overflow 1232
+    // bytes once those are injected.
+    const { bins } = await (0, transactionSplitter_1.splitIntoTransactionBins)(rpc, payer, instructions, {
+        lookupTables,
+        additionalSigners: options?.additionalSigners,
+        blockhash,
+        reservedBytes: jito_1.BUNDLE_INJECTED_IX_RESERVED_BYTES,
+        segmentLengths,
+        freshBinSegments,
+    });
+    if (bins.length === 0) {
+        throw new TransactionError("Bundle build produced 0 bins; cannot attach Jito tip.");
+    }
+    // Build each bin's transaction message once; we'll reuse it for both the
+    // pre-signing simulation and the final signing pass.
+    const messages = [];
+    for (const bin of bins) {
+        messages.push(await buildTransactionMessage(rpc, payer, bin, lookupTables, options?.additionalSigners, blockhash));
+    }
+    // Append the Jito tip ix AFTER LUT compression in `buildTransactionMessage`.
+    // If we appended it before compression and any supplied LUT contained the
+    // tip account, it would be moved into the LUT-loaded address set. Jito's
+    // bundle validator only inspects *static* account keys for tip accounts and
+    // rejects with "Bundles must write lock at least one tip account to be
+    // eligible for the auction" otherwise.
+    //
+    // Pick the smallest tx to carry the tip so a bin already near the 1232-byte
+    // wire limit isn't pushed over by the extra ~81 bytes of tip-transfer ix.
+    const tipBinIdx = messages
+        .map((m, i) => ({ i, bytes: (0, transactionSplitter_1.measureTxBytes)(m) }))
+        .reduce((a, b) => (a.bytes <= b.bytes ? a : b)).i;
+    const tipAccount = (0, jito_1.getRandomTipAccount)();
+    const tipIx = (0, jito_1.buildTipInstruction)(payer, tipAccount, tipLamports);
+    messages[tipBinIdx] = (0, kit_1.appendTransactionMessageInstructions)([tipIx], messages[tipBinIdx]);
+    console.log(`[bundle] attached ${tipLamports} lamport tip to tx[${tipBinIdx}] (smallest of ${messages.length}) → ${tipAccount}`);
+    const priorityFeeMicroLamports = await Promise.all(messages.map((message, index) => resolvePriorityFeeMicroLamports(rpc, message, collectWritableAccounts(bins[index]), options)));
+    // Phase 1: encode each bin with a max CU limit and run a single bundle-level
+    // simulation. `compileTransaction` stamps placeholder signatures, while
+    // `skipSigVerify` lets the simulator validate the real shared blockhash
+    // before the wallet signs.
+    const simEncodedTxs = [];
+    for (let i = 0; i < messages.length; i += 1) {
+        const simMsg = (0, kit_1.appendTransactionMessageInstructions)(getComputeBudgetInstructions(MAX_COMPUTE_UNIT_LIMIT, priorityFeeMicroLamports[i]), messages[i]);
+        const compiled = (0, kit_1.compileTransaction)(simMsg);
+        simEncodedTxs.push((0, kit_1.getBase64EncodedWireTransaction)(compiled));
+    }
+    const rpcUrl = (0, rpc_1.getMainnetRpcUrl)();
+    const simResult = await (0, jito_1.simulateBundle)(rpcUrl, simEncodedTxs, {
+        replaceRecentBlockhash: false,
+    });
+    const failingIdx = simResult.transactionResults.findIndex((r) => r.err != null);
+    if (simResult.summary !== "succeeded" || failingIdx >= 0) {
+        const idx = failingIdx >= 0 ? failingIdx : 0;
+        const failed = simResult.transactionResults[idx];
+        if (!options?.hideFailureInfo) {
+            console.error(`Bundle simulation failed at tx[${idx}] of ${bins.length}.`);
+            console.error("Summary:", JSON.stringify(simResult.summary, null, 2));
+            simResult.transactionResults.forEach((r, i) => {
+                const tag = i === idx ? "  ← FAILED" : i < idx ? "  (succeeded)" : "  (not run)";
+                console.error(`\n── tx[${i}]${tag} (unitsConsumed=${r.unitsConsumed ?? "—"}) ──`);
+                if (r.err != null)
+                    console.error("  err:", JSON.stringify(r.err));
+                logProgramLogsLineByLine(r.logs ?? [], `tx[${i}] bundle simulation logs`);
+            });
+            // Fall back to a single-tx `simulateTransaction` on the failing bin —
+            // it returns longer logs than `simulateBundle` (which truncates at
+            // ~16 lines). Skips the intra-bundle effects from preceding bins, so
+            // dependent failures (e.g. PriceIsStale when bin 0 was supposed to
+            // refresh) surface here instead. Best-effort; we keep the original
+            // error.
+            //
+            // Uses direct JSON-RPC instead of Kit's typed `rpc.simulateTransaction`
+            // wrapper because the latter has thrown "Do not know how to serialize
+            // a BigInt" on this code path — the raw fetch route gives us a
+            // bigint-safe replacer in `jsonRpcFetchOnce`'s body builder.
+            try {
+                const failedSimMsg = (0, kit_1.appendTransactionMessageInstructions)(getComputeBudgetInstructions(MAX_COMPUTE_UNIT_LIMIT, priorityFeeMicroLamports[idx]), messages[idx]);
+                const failedB64 = (0, kit_1.getBase64EncodedWireTransaction)((0, kit_1.compileTransaction)(failedSimMsg));
+                const standalone = await (0, jsonRpcFetch_1.jsonRpcFetchOnce)(rpcUrl, "simulateTransaction", [
+                    failedB64,
+                    {
+                        encoding: "base64",
+                        sigVerify: false,
+                        replaceRecentBlockhash: false,
+                        commitment: "confirmed",
+                    },
+                ]);
+                console.error(`\n── tx[${idx}] standalone simulateTransaction (full logs, no preceding-bin effects) ──`);
+                if (standalone.value.err != null)
+                    console.error("  err:", JSON.stringify(standalone.value.err, (_, v) => typeof v === "bigint" ? v.toString() : v));
+                const logs = standalone.value.logs ?? [];
+                logProgramLogsLineByLine(logs, `tx[${idx}] standalone simulation logs`);
+            }
+            catch (err) {
+                console.error("  (standalone fallback failed:", err instanceof Error ? err.message : String(err), ")");
+            }
+        }
+        const errStr = JSON.stringify(failed?.err ?? simResult.summary, (_, v) => typeof v === "bigint" ? v.toString() : v);
+        throw new TransactionError(`Bundle simulation failed at tx[${idx}]: ${errStr}`, failed?.logs ?? []);
+    }
+    // Phase 2: stamp each bin with its measured CU + 10% headroom while retaining
+    // the blockhash validated by simulation, then compile and batch-sign them.
+    // Browser wallets expose
+    // `signTransactions`, and using it here preserves the intended multi-tx
+    // approval flow for bundles instead of requesting one signature at a time.
+    // Fall back to MAX_COMPUTE_UNIT_LIMIT if the simulator didn't report a
+    // unitsConsumed value (some endpoints omit it on edge cases).
+    const finalTransactions = [];
+    for (let i = 0; i < messages.length; i += 1) {
+        const measured = simResult.transactionResults[i]?.unitsConsumed;
+        const cu = measured && measured > 0 ? Math.ceil(measured * 1.1) : MAX_COMPUTE_UNIT_LIMIT;
+        const withCu = (0, kit_1.appendTransactionMessageInstructions)(getComputeBudgetInstructions(cu, priorityFeeMicroLamports[i]), messages[i]);
+        const finalMsg = (0, kit_1.setTransactionMessageLifetimeUsingBlockhash)(blockhash, withCu);
+        finalTransactions.push((0, kit_1.compileTransaction)(finalMsg));
+    }
+    const signedTransactions = await signTransactionsWithSigners(finalTransactions, [
+        payer,
+        ...(options?.additionalSigners ?? []),
+    ]);
+    const base64Txs = signedTransactions.map(kit_1.getBase64EncodedWireTransaction);
+    const lastSignature = (0, kit_1.getSignatureFromTransaction)(signedTransactions[signedTransactions.length - 1]);
+    // Submit and confirm the bundle through the user's own RPC endpoint
+    // (Helius, Ironforge, etc.). These providers proxy Jito bundle methods,
+    // avoiding the global rate limit on Jito's public block engine.
+    try {
+        console.log(`[bundle] sending via ${(0, rpc_1.redactRpcUrlForLog)(rpcUrl)}`);
+        const bundleId = await (0, jito_1.sendBundle)(rpcUrl, base64Txs);
+        await (0, jito_1.confirmBundle)(rpcUrl, bundleId);
+        options?.onSuccess?.();
+        // Last bin carries the tip; signature matches what landed on-chain.
+        return lastSignature;
+    }
+    catch (error) {
+        if (error instanceof jito_1.JitoBundleError) {
+            throw new TransactionError(`Jito bundle failed: ${error.message}`);
+        }
+        throw error;
+    }
+}
+/**
+ * Same bin-packing as {@link signSendAndConfirmBundle}, but no tip and each
+ * bin is sent and confirmed via normal RPC (for environments without Jito).
+ */
+async function signSendAndConfirmSplitSequentially(rpc, payer, instructions, lookupTables, options, segmentLengths, freshBinSegments) {
+    const { value: splitBlockhash } = (await rpc
+        .getLatestBlockhash({ commitment: "confirmed" })
+        .send());
+    const { bins } = await (0, transactionSplitter_1.splitIntoTransactionBins)(rpc, payer, instructions, {
+        lookupTables,
+        additionalSigners: options?.additionalSigners,
+        blockhash: splitBlockhash,
+        reservedBytes: jito_1.BUNDLE_INJECTED_IX_RESERVED_BYTES,
+        segmentLengths,
+        freshBinSegments,
+    });
+    let lastSignature;
+    for (const [binIndex, bin] of bins.entries()) {
+        const { value: blockhash } = (await rpc
+            .getLatestBlockhash({ commitment: "confirmed" })
+            .send());
+        const transactionMessage = await buildTransactionMessage(rpc, payer, bin, lookupTables, options?.additionalSigners, blockhash);
+        const priorityFeeMicroLamports = await resolvePriorityFeeMicroLamports(rpc, transactionMessage, collectWritableAccounts(bin), options);
+        const simMsg = (0, kit_1.appendTransactionMessageInstructions)(getComputeBudgetInstructions(MAX_COMPUTE_UNIT_LIMIT, priorityFeeMicroLamports), transactionMessage);
+        const simulation = await simulateTransaction(rpc, simMsg);
+        if (simulation.err) {
+            if (!options?.hideFailureInfo) {
+                console.error(`Simulation failed for split bin ${binIndex}:`, simulation.err);
+                logProgramLogsLineByLine(simulation.logs, `split bin ${binIndex} simulation logs`);
+            }
+            const errStr = JSON.stringify(simulation.err, (_, v) => typeof v === "bigint" ? v.toString() : v);
+            throw new TransactionError(`Split bin ${binIndex} simulation failed: ${errStr}`, simulation.logs);
+        }
+        const { wireB64, signature } = await signSplitBin(rpc, payer, bin, lookupTables, options?.additionalSigners, blockhash, priorityFeeMicroLamports);
+        await rpc
+            .sendTransaction(wireB64, {
+            encoding: "base64",
+            skipPreflight: true,
+        })
+            .send();
+        try {
+            await confirmTransaction(rpc, signature, "confirmed");
+        }
+        catch (error) {
+            const logs = await fetchTransactionLogsWithRetry(rpc, signature);
+            if (!options?.hideFailureInfo) {
+                console.error(`Transaction failed for split bin ${binIndex}:`, signature, error);
+                logProgramLogsLineByLine(logs, `split bin ${binIndex} transaction logs`);
+            }
+            throw new TransactionError(`Transaction failed: ${error}`, logs);
+        }
+        lastSignature = signature;
+    }
+    options?.onSuccess?.();
+    return lastSignature;
+}
+async function fetchTransactionLogsWithRetry(rpc, signature) {
+    for (let attempt = 0; attempt < 10; attempt += 1) {
+        try {
+            const info = await rpc
+                .getTransaction(signature, { commitment: "confirmed", encoding: "base64" })
+                .send();
+            const logs = (info?.meta?.logMessages ?? []);
+            if (logs.length > 0)
+                return logs;
+        }
+        catch {
+            // Best-effort log retrieval; retry below.
+        }
+        await new Promise((resolve) => setTimeout(resolve, 500));
+    }
+    return [];
+}
+/**
+ * Wait for a transaction to be confirmed at the specified commitment level.
+ *
+ * @param rpc - Solana RPC client
+ * @param signature - Transaction signature to confirm
+ * @param commitment - Commitment level to wait for
+ * @param timeoutMs - Maximum time to wait (default: 60000ms)
+ */
+async function confirmTransaction(rpc, signature, commitment, timeoutMs = 60000) {
+    const startTime = Date.now();
+    const pollIntervalMs = 500;
+    while (Date.now() - startTime < timeoutMs) {
+        let status = null;
+        try {
+            const response = await rpc.getSignatureStatuses([signature]).send();
+            status = response.value[0];
+        }
+        catch (err) {
+            // Transient upstream RPC failures during confirmation polling (e.g.
+            // Ironforge returning "All providers failed", DNS hiccups, 429s) must
+            // not declare the transaction failed — the tx may already have landed.
+            // Keep polling until we get a real status or the timeout elapses.
+            if (!(0, retry_1.isTransientNetworkError)(err))
+                throw err;
+        }
+        if (status !== null) {
+            // Check if transaction failed
+            if (status.err) {
+                // Use replacer to handle BigInt values in error objects
+                const errStr = JSON.stringify(status.err, (_, v) => typeof v === "bigint" ? v.toString() : v);
+                throw new Error(`Transaction failed: ${errStr}`);
+            }
+            // Check if we've reached the desired commitment level
+            const confirmationStatus = status.confirmationStatus;
+            if (confirmationStatus === commitment ||
+                (commitment === "processed" && confirmationStatus) ||
+                (commitment === "confirmed" &&
+                    (confirmationStatus === "confirmed" || confirmationStatus === "finalized")) ||
+                (commitment === "finalized" && confirmationStatus === "finalized")) {
+                return;
+            }
+        }
+        // Wait before polling again
+        await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+    }
+    throw new Error(`Transaction confirmation timeout after ${timeoutMs}ms`);
+}

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

@@ -0,0 +1,85 @@
+/**
+ * Greedy bin-packing splitter for instruction lists that exceed the Solana
+ * transaction wire limit (1232 bytes).
+ *
+ * Instructions are packed left-to-right (preserving caller order) into the
+ * fewest bins where each bin compiles to a valid-sized transaction. The
+ * result is an ordered array of instruction arrays, each of which can be
+ * independently built into a v0 `TransactionMessage`.
+ */
+import type { Address, Blockhash, CompilableTransactionMessage, Instruction, Rpc, SolanaRpcApi, TransactionSigner } from "@solana/kit";
+/**
+ * Solana's maximum serialized transaction size in bytes. The base64 encoding
+ * inflates this to ~1644 chars, but we measure the decoded wire bytes via
+ * Kit's `compileTransaction` + `getBase64EncodedWireTransaction` and compare
+ * against the decoded length.
+ */
+export declare const SOLANA_TX_SIZE_LIMIT = 1232;
+/**
+ * Measure the wire size of a compilable transaction message in bytes.
+ */
+export declare function measureTxBytes(msg: CompilableTransactionMessage): number;
+export interface SplitResult {
+    /** Ordered instruction bins; each bin fits in one tx. */
+    bins: Instruction[][];
+}
+export interface SplitOptions {
+    lookupTables?: Address[];
+    additionalSigners?: TransactionSigner[];
+    /**
+     * Shared blockhash to use when compiling each candidate. Passing a stable
+     * blockhash avoids a per-iteration `getLatestBlockhash` RPC call and keeps
+     * every bin's size measurement consistent with what downstream signing
+     * will actually produce.
+     */
+    blockhash?: Readonly<{
+        blockhash: Blockhash;
+        lastValidBlockHeight: bigint;
+    }>;
+    /**
+     * Bytes to reserve below {@link SOLANA_TX_SIZE_LIMIT} for instructions
+     * injected _after_ splitting (e.g. a compute-unit-limit ix on every bin
+     * and a Jito tip ix on one bin). Default 0 means pack tight to the limit.
+     */
+    reservedBytes?: number;
+    /**
+     * When set, positive lengths must sum to `instructions.length`; each slice is
+     * kept intact when packing. Same field as `TransactionPlan.segmentLengths`.
+     * When omitted, each instruction is packed independently.
+     */
+    segmentLengths?: number[];
+    /**
+     * Segment indices (0-based, into the segments produced by `segmentLengths`)
+     * that must always start a fresh bin. The current bin — if non-empty — is
+     * flushed before the segment is appended, even if the segment would have
+     * fit alongside it.
+     *
+     * Use case: a CPI whose on-chain check encodes a position-relative index
+     * (e.g. Kamino's flash-borrow records `borrowInstructionIndex` for the
+     * matching repay) needs the segment to land at a predictable index inside
+     * its own tx. Marking that segment as a forced boundary keeps its index
+     * stable regardless of how the preceding segments pack.
+     */
+    freshBinSegments?: number[];
+}
+/**
+ * Turn a flat instruction list into indivisible segments for bin-packing.
+ *
+ * @throws If lengths are invalid or do not partition `instructions`.
+ */
+export declare function buildInstructionSegments(instructions: Instruction[], segmentLengths?: number[]): Instruction[][];
+/**
+ * Split an instruction list into the minimum number of ordered bins where
+ * each bin compiles to a transaction within the wire-size limit (minus
+ * `reservedBytes` of headroom for post-split instruction injection).
+ *
+ * Preserves instruction ordering: segments and instructions are never
+ * reordered across bins. Each bin is measured by actually compiling a v0
+ * message with the provided fee payer + ALTs, so the measurement accounts for
+ * signatures, account tables, and compact-u16 encoding exactly.
+ *
+ * Throws if:
+ * - A single segment cannot fit in one tx (even alone).
+ * - The total bins exceed `MAX_BUNDLE_TRANSACTIONS` (Jito's 5-tx limit).
+ */
+export declare function splitIntoTransactionBins(rpc: Rpc<SolanaRpcApi>, payer: TransactionSigner, instructions: Instruction[], options?: SplitOptions): Promise<SplitResult>;