@exponent-labs/exponent-sdk 0.1.8 → 0.9.0

package/src/exponentVaults/vaultTransactionBuilder.ts

@@ -0,0 +1,785 @@
+import {
+  Connection,
+  PublicKey,
+  TransactionInstruction,
+  TransactionMessage,
+  VersionedTransaction,
+  AddressLookupTableAccount,
+  AddressLookupTableProgram,
+  ComputeBudgetProgram,
+  SystemProgram,
+} from "@solana/web3.js"
+import type * as web3 from "@solana/web3.js"
+import type { ExponentPrices } from "@exponent-labs/exponent-vaults-fetcher"
+import type { ExponentVault } from "./vault"
+import { LoopscaleClient } from "./loopscale-client"
+import { createVaultSyncTransaction, type VaultInstruction } from "./vault-interaction"
+import { SQUADS_PROGRAM_ID } from "./syncTransaction"
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Per-step compute budget overrides.
+ *
+ * Each step in the builder can have its own compute settings. When not
+ * provided, the global defaults from {@link VaultTransactionBuilderConfig}
+ * are used instead.
+ *
+ * @example
+ * ```ts
+ * builder.addActions([clmmAction.buyPt(...)], {
+ *   computeUnitLimit: 1_200_000,
+ *   priorityFee: 500,
+ * })
+ * ```
+ */
+export interface StepOptions {
+  /** Human-readable label for this step. Auto-generated if omitted. */
+  label?: string
+  /** Compute unit limit for this step's transaction. */
+  computeUnitLimit?: number
+  /** Heap frame allocation in bytes for this step's transaction. */
+  heapFrameBytes?: number
+  /** Priority fee in microLamports per compute unit. Adds a `setComputeUnitPrice` instruction when > 0. */
+  priorityFee?: number
+}
+
+/**
+ * Configuration for creating a {@link VaultTransactionBuilder}.
+ *
+ * @example
+ * ```ts
+ * const builder = VaultTransactionBuilder.create({
+ *   vault,                            // loaded ExponentVault instance
+ *   connection,                       // Solana RPC connection
+ *   signer: manager.publicKey,        // strategy manager's public key
+ *   vaultPda: squadsVault,            // Squads vault PDA
+ *   pricesAccount,                    // fetched ExponentPrices for oracle refresh
+ * })
+ * ```
+ */
+export interface VaultTransactionBuilderConfig {
+  /** Loaded ExponentVault instance. Provides on-chain state, price IDs, and the vault's address lookup table. */
+  vault: ExponentVault
+  /** Solana RPC connection used for all on-chain reads and transaction sending. */
+  connection: Connection
+  /** The strategy manager's public key. Used as the signer for policy matching and as the fee payer. */
+  signer: PublicKey
+  /** The Squads multisig vault PDA that owns the strategy's assets. */
+  vaultPda: PublicKey
+  /**
+   * Fetched `ExponentPrices` account snapshot.
+   *
+   * Used to build price refresh instructions (via `vault.ixsUpdateStrategyVaultPrices()`).
+   * The price refresh transaction is always emitted as the first TransactionSet, ensuring
+   * oracle prices are fresh when the sync transaction executes in the same slot.
+   *
+   * Fetch this via `ExponentVaultsFetcher.fetchPricesDeserialized()` before creating the builder.
+   */
+  pricesAccount: ExponentPrices
+  /** Default compute unit limit for all steps (default: 1,400,000). Override per-step via {@link StepOptions}. */
+  computeUnitLimit?: number
+  /** Default heap frame allocation in bytes for all steps (default: 262,144 = 256 KB). Override per-step via {@link StepOptions}. */
+  heapFrameBytes?: number
+  /** Squads program ID override. Defaults to the standard Squads V4 program. */
+  squadsProgram?: PublicKey
+  /**
+   * Compute budget overrides for the price refresh transaction.
+   *
+   * The price refresh tx runs oracle update instructions which are typically lighter
+   * than sync transactions. You can lower the CU limit here to save on fees, or
+   * set a priority fee to ensure the refresh lands quickly.
+   *
+   * @example
+   * ```ts
+   * VaultTransactionBuilder.create({
+   *   // ...
+   *   priceRefreshOptions: { computeUnitLimit: 600_000, priorityFee: 100 },
+   * })
+   * ```
+   */
+  priceRefreshOptions?: StepOptions
+}
+
+interface StepConfig {
+  label: string
+  instructions: VaultInstruction[]
+  isLoopscale: boolean
+  options: StepOptions
+}
+
+/**
+ * A group of instructions that will be assembled into a single VersionedTransaction.
+ *
+ * The builder produces an ordered array of TransactionSets: price refresh first,
+ * then optional setup transactions, then one sync transaction per step.
+ */
+export interface TransactionSet {
+  /** Human-readable label identifying this transaction (e.g. "price-refresh", "step-1", "step-1-setup"). */
+  label: string
+  /** All instructions in execution order, including compute budget instructions. */
+  instructions: TransactionInstruction[]
+  /** Extra signers required by this transaction (e.g. a newly generated LP position keypair from CLMM deposits). */
+  signers: web3.Signer[]
+  /** Address lookup table addresses that should be loaded for this transaction's V0 message. */
+  addressLookupTableAddresses: PublicKey[]
+}
+
+/**
+ * Options for {@link VaultTransactionBuildResult.sendJitoBundle}.
+ */
+export interface JitoBundleSendOptions {
+  /** Keypair signers. The first signer is used as the fee payer and Jito tip payer. */
+  signers: web3.Signer[]
+  /** Jito tip amount in lamports. Appended as a transfer instruction to the last transaction. */
+  tipLamports: number
+  /** Commitment level for bundle confirmation (default: "confirmed"). */
+  commitment?: web3.Commitment
+  /** Jito auth key for authenticated block engine endpoints. */
+  jitoAuthKey?: string
+  /**
+   * Custom send function that replaces the default Jito bundle send.
+   *
+   * Receives signed (and co-signed) VersionedTransactions and their labels.
+   * Must return an array of transaction signatures in the same order.
+   * Use this for Surfpool, local validators, or any non-Jito send flow.
+   *
+   * @example
+   * ```ts
+   * result.sendJitoBundle({
+   *   signers: [manager],
+   *   tipLamports: 0,
+   *   customSend: async (txs, labels) => {
+   *     return Promise.all(txs.map(tx => surfpool.sendTransaction(tx)))
+   *   },
+   * })
+   * ```
+   */
+  customSend?: (transactions: VersionedTransaction[], labels: string[]) => Promise<string[]>
+}
+
+/** Result from {@link VaultTransactionBuildResult.sendJitoBundle}. */
+export interface JitoBundleResult {
+  /** Transaction signatures in the same order as the TransactionSets. */
+  signatures: string[]
+  /** Jito bundle ID. Empty string if using customSend or if the mainnet endpoint did not return one. */
+  bundleId: string
+}
+
+/**
+ * The result of calling {@link VaultTransactionBuilder.build}.
+ *
+ * Contains the assembled TransactionSets and provides `sendJitoBundle()` to send them.
+ * Inspect `transactionSets` to review instructions before sending.
+ *
+ * Price refresh and sync transactions must land in the same slot — use `sendJitoBundle()`
+ * for atomic same-slot execution via Jito, or `customSend` for testing environments.
+ *
+ * @example
+ * ```ts
+ * const result = await builder.build()
+ *
+ * // Inspect
+ * console.log(result.labels)  // ["price-refresh", "step-1", "loopscale-step-2"]
+ *
+ * // Send as Jito bundle
+ * await result.sendJitoBundle({ signers: [manager], tipLamports: 10_000 })
+ *
+ * // Or for testing (Surfpool, local validator):
+ * await result.sendJitoBundle({
+ *   signers: [manager], tipLamports: 0,
+ *   customSend: async (txs) => surfpool.sendAll(txs),
+ * })
+ * ```
+ */
+export interface VaultTransactionBuildResult {
+  /** Ordered TransactionSets: price refresh (index 0), then setup + sync per step. */
+  transactionSets: TransactionSet[]
+  /** Deduplicated address lookup table addresses across all TransactionSets. */
+  lookupTableAddresses: PublicKey[]
+  /** Labels for each TransactionSet, in order. */
+  labels: string[]
+  /**
+   * Sign all transactions, append a Jito tip to the last one, and send as an atomic Jito bundle.
+   *
+   * All transactions share the same blockhash and are executed in the same slot.
+   * Loopscale steps are automatically co-signed via an internally created LoopscaleClient.
+   * Non-Loopscale steps are signed normally.
+   *
+   * Use `customSend` for testing environments where Jito is not available.
+   */
+  sendJitoBundle(options: JitoBundleSendOptions): Promise<JitoBundleResult>
+}
+
+// ============================================================================
+// Jito constants
+// ============================================================================
+
+const JITO_TIP_ADDRESSES = [
+  new PublicKey("96gYZGLnJYVFmbjzopPSU6QiEV5fGqZNyN9nmNhvrZU5"),
+  new PublicKey("HFqU5x63VTqvQss8hp11i4wVV8bD44PvwucfZ2bU7gRe"),
+  new PublicKey("Cw8CFyM9FkoMi7K7Crf6HNQqf4uEMzpKw6QNghXLvLkY"),
+  new PublicKey("ADaUMid9yfUytqMBgopwjb2DTLSokTSzL1zt6iGPaS49"),
+  new PublicKey("DfXygSm4jCyNCybVYYK6DwvWqjKee8pbDmJGcLWNDXjh"),
+  new PublicKey("ADuUkR4vqLUMWXxW9gh6D6L8pMSawimctcNZ5pGwDcEt"),
+  new PublicKey("DttWaMuVvTiduZRnguLF7jNxTgiMBZ1hyAumKUiL2KRL"),
+  new PublicKey("3AVi9Tg9Uo68tJfuvoKvqKNWKkC5wPdSSdeBnizKZ6jT"),
+]
+
+const JITO_REGIONAL_URLS = [
+  "https://amsterdam.mainnet.block-engine.jito.wtf",
+  "https://frankfurt.mainnet.block-engine.jito.wtf",
+  "https://ny.mainnet.block-engine.jito.wtf",
+  "https://tokyo.mainnet.block-engine.jito.wtf",
+]
+
+const JITO_MAINNET_URL = "https://mainnet.block-engine.jito.wtf"
+const JITO_BUNDLES_PATH = "/api/v1/bundles"
+const JITO_MAX_RETRIES = 10
+const JITO_RETRY_DELAY_MS = 1000
+
+// ============================================================================
+// VaultTransactionBuilder
+// ============================================================================
+
+/**
+ * Orchestrates strategy vault transaction construction.
+ *
+ * Replaces the per-recipe boilerplate of manually assembling compute budgets,
+ * price refresh instructions, sync transaction wrapping, ALT gathering, and
+ * setup transaction splitting.
+ *
+ * **Lifecycle:** create → add actions → build → sendJitoBundle
+ *
+ * @example Single action
+ * ```ts
+ * const result = await VaultTransactionBuilder
+ *   .create({ vault, connection, signer: manager.publicKey, vaultPda, pricesAccount })
+ *   .addActions([clmmAction.buyPt({ market, ptOutMin, syInMax })])
+ *   .build()
+ *
+ * await result.sendJitoBundle({ signers: [manager], tipLamports: 10_000 })
+ * ```
+ *
+ * @example Multi-step — each addActions() becomes its own sync transaction
+ * ```ts
+ * const result = await VaultTransactionBuilder
+ *   .create({ vault, connection, signer: manager.publicKey, vaultPda, pricesAccount })
+ *   .addActions([kaminoAction.deposit("MAIN", "USDC", amount)])   // sync tx 1
+ *   .addActions([kaminoAction.borrow("MAIN", "SOL", amount)])     // sync tx 2
+ *   .build()
+ *
+ * await result.sendJitoBundle({ signers: [manager], tipLamports: 10_000 })
+ * ```
+ *
+ * @example Mixed Kamino + Loopscale — co-signing handled automatically
+ * ```ts
+ * const result = await VaultTransactionBuilder
+ *   .create({ vault, connection, signer: manager.publicKey, vaultPda, pricesAccount })
+ *   .addActions([kaminoAction.deposit(...)])                        // signed normally
+ *   .addLoopscaleActions([loopscaleAction.createStrategy({ ... })]) // co-signed automatically
+ *   .build()
+ *
+ * // sendJitoBundle auto-creates a LoopscaleClient and co-signs Loopscale steps
+ * await result.sendJitoBundle({ signers: [manager], tipLamports: 10_000 })
+ * ```
+ */
+export class VaultTransactionBuilder {
+  private readonly config: VaultTransactionBuilderConfig
+  private steps: StepConfig[] = []
+  private stepCounter = 0
+
+  private constructor(config: VaultTransactionBuilderConfig) {
+    this.config = config
+  }
+
+  /**
+   * Create a new builder instance.
+   *
+   * @param config - Builder configuration including the vault, connection, signer, and prices.
+   * @returns A new {@link VaultTransactionBuilder} ready for action chaining.
+   */
+  static create(config: VaultTransactionBuilderConfig): VaultTransactionBuilder {
+    return new VaultTransactionBuilder(config)
+  }
+
+  /**
+   * Add vault instructions as a new step.
+   *
+   * Each call creates a **separate Squads sync transaction** with its own policy matching.
+   * This prevents oversized transactions — Solana transactions are limited to 1232 bytes,
+   * and most vault actions (Kamino deposit, CLMM trade, etc.) use many accounts.
+   *
+   * To chain multiple calls, each gets its own sync transaction:
+   * ```ts
+   * builder
+   *   .addActions([kaminoAction.deposit(...)])   // sync tx 1
+   *   .addActions([kaminoAction.borrow(...)])    // sync tx 2
+   * ```
+   *
+   * **Warning:** Passing multiple actions in a single array packs them into one sync
+   * transaction. This can easily exceed the 1232-byte Solana packet limit — the builder
+   * will throw an error at build time if the resulting transaction is oversized.
+   * Only combine actions in one array when you know they fit (e.g., two small instructions).
+   *
+   * @param instructions - Array of VaultInstruction descriptors (from kaminoAction, clmmAction, etc.).
+   * @param options - Optional per-step compute budget overrides and label.
+   * @returns `this` for chaining.
+   */
+  addActions(instructions: VaultInstruction[], options?: StepOptions): this {
+    this.stepCounter++
+    const label = options?.label ?? `step-${this.stepCounter}`
+    this.steps.push({ label, instructions: [...instructions], isLoopscale: false, options: options ?? {} })
+    return this
+  }
+
+  /**
+   * Add Loopscale vault instructions as a new step.
+   *
+   * Each call creates a separate Squads sync transaction, marked for Loopscale co-signing.
+   * At send time, these steps are automatically co-signed via an internally created
+   * LoopscaleClient — no separate configuration needed.
+   *
+   * **Warning:** Passing multiple Loopscale actions in a single array packs them into one
+   * sync transaction. This can exceed the 1232-byte limit — the builder will throw at
+   * build time if oversized. Loopscale transactions are particularly account-heavy;
+   * prefer one action per call.
+   *
+   * @param instructions - Array of Loopscale VaultInstruction descriptors (from loopscaleAction).
+   * @param options - Optional per-step compute budget overrides and label.
+   * @returns `this` for chaining.
+   */
+  addLoopscaleActions(instructions: VaultInstruction[], options?: StepOptions): this {
+    this.stepCounter++
+    const label = options?.label ?? `loopscale-step-${this.stepCounter}`
+    this.steps.push({ label, instructions: [...instructions], isLoopscale: true, options: options ?? {} })
+    return this
+  }
+
+  /**
+   * Build TransactionSets from the configured steps.
+   *
+   * Produces an ordered array of TransactionSets:
+   * 1. **Price refresh** (index 0) — oracle price update instructions
+   * 2. **Setup transactions** — token account creation (only if needed)
+   * 3. **Sync transactions** — one per step, wrapped in Squads sync transaction
+   *
+   * The price refresh must land in the same slot as the sync transactions.
+   * Use `result.sendJitoBundle()` for atomic same-slot execution.
+   *
+   * @returns A {@link VaultTransactionBuildResult} with TransactionSets and a sendJitoBundle method.
+   * @throws If no steps have been configured (call addActions first).
+   * @throws If any assembled transaction exceeds the 1232-byte Solana packet limit.
+   */
+  async build(): Promise<VaultTransactionBuildResult> {
+    if (this.steps.length === 0) {
+      throw new Error("No steps configured. Call addActions() or addLoopscaleActions() before build().")
+    }
+
+    const { vault, connection, signer, vaultPda, pricesAccount } = this.config
+    const squadsProgram = this.config.squadsProgram ?? SQUADS_PROGRAM_ID
+    const defaultCU = this.config.computeUnitLimit ?? 1_400_000
+    const defaultHeap = this.config.heapFrameBytes ?? 256 * 1024
+
+    // 1. Price refresh TransactionSet
+    const priceOpts = this.config.priceRefreshOptions ?? {}
+    const priceIxs = await vault.ixsUpdateStrategyVaultPrices(pricesAccount)
+    const priceSet: TransactionSet = {
+      label: priceOpts.label ?? "price-refresh",
+      instructions: buildComputeBudgetIxs(
+        priceOpts.computeUnitLimit ?? defaultCU,
+        priceOpts.heapFrameBytes ?? defaultHeap,
+        priceOpts.priorityFee,
+      ).concat(priceIxs),
+      signers: [],
+      addressLookupTableAddresses: vault.state.addressLookupTable
+        ? [vault.state.addressLookupTable]
+        : [],
+    }
+
+    // 2. Per-step sync TransactionSets
+    const transactionSets: TransactionSet[] = [priceSet]
+    const allAltAddresses = new Set<string>(
+      priceSet.addressLookupTableAddresses.map((a) => a.toBase58()),
+    )
+
+    for (const step of this.steps) {
+      const syncResult = await createVaultSyncTransaction({
+        instructions: step.instructions,
+        owner: vaultPda,
+        connection,
+        vaultPda,
+        signer,
+        vaultAddress: vault.selfAddress,
+        squadsProgram,
+      })
+
+      if (syncResult.setupInstructions.length > 0) {
+        transactionSets.push({
+          label: `${step.label}-setup`,
+          instructions: [
+            ComputeBudgetProgram.setComputeUnitLimit({ units: 400_000 }),
+            ...syncResult.setupInstructions,
+          ],
+          signers: [],
+          addressLookupTableAddresses: [],
+        })
+      }
+
+      const stepCU = step.options.computeUnitLimit ?? defaultCU
+      const stepHeap = step.options.heapFrameBytes ?? defaultHeap
+
+      const syncSet: TransactionSet = {
+        label: step.label,
+        instructions: [
+          ...buildComputeBudgetIxs(stepCU, stepHeap, step.options.priorityFee),
+          ...syncResult.preInstructions,
+          syncResult.instruction,
+          ...syncResult.postInstructions,
+        ],
+        signers: syncResult.signers,
+        addressLookupTableAddresses: [
+          ...syncResult.addressLookupTableAddresses,
+          ...(vault.state.addressLookupTable ? [vault.state.addressLookupTable] : []),
+        ],
+      }
+      transactionSets.push(syncSet)
+
+      for (const alt of syncSet.addressLookupTableAddresses) {
+        allAltAddresses.add(alt.toBase58())
+      }
+    }
+
+    const lookupTableAddresses = [...allAltAddresses].map((a) => new PublicKey(a))
+
+    // Validate transaction sizes — catch oversized txs early with a clear error
+    const altAccounts = await resolveAltAccounts(connection, lookupTableAddresses)
+    for (const txSet of transactionSets) {
+      const txAltAccounts = altAccounts.filter((alt) =>
+        txSet.addressLookupTableAddresses.some((addr) => addr.equals(alt.key)),
+      )
+      try {
+        const testMsg = new TransactionMessage({
+          payerKey: signer,
+          recentBlockhash: "1".repeat(44),
+          instructions: txSet.instructions,
+        }).compileToV0Message(txAltAccounts)
+        const testTx = new VersionedTransaction(testMsg)
+        const serialized = testTx.serialize()
+        if (serialized.length > 1232) {
+          throw new Error(
+            `Transaction "${txSet.label}" is oversized (${serialized.length} bytes, limit 1232). ` +
+            `This usually means too many actions were packed into a single addActions() call. ` +
+            `Split them into separate addActions() calls so each gets its own sync transaction.`,
+          )
+        }
+      } catch (e) {
+        if (e instanceof Error && e.message.includes("oversized")) throw e
+      }
+    }
+
+    const labels = transactionSets.map((ts) => ts.label)
+
+    // Capture state for sendJitoBundle closure
+    const closedConnection = connection
+    const closedSigner = signer
+    const closedLookupTableAddresses = lookupTableAddresses
+    const closedSteps = this.steps
+
+    return {
+      transactionSets,
+      lookupTableAddresses,
+      labels,
+
+      async sendJitoBundle(options: JitoBundleSendOptions): Promise<JitoBundleResult> {
+        const resolvedAltAccounts = await resolveAltAccounts(closedConnection, closedLookupTableAddresses)
+        const { blockhash, lastValidBlockHeight } = await closedConnection.getLatestBlockhash()
+
+        // Auto-create LoopscaleClient if any step needs co-signing
+        const hasLoopscale = closedSteps.some((s) => s.isLoopscale)
+        let loopscaleClient: LoopscaleClient | undefined
+        if (hasLoopscale) {
+          loopscaleClient = new LoopscaleClient({
+            connection: closedConnection,
+            userWallet: closedSigner,
+          })
+        }
+
+        const allTxs: VersionedTransaction[] = []
+        for (let i = 0; i < transactionSets.length; i++) {
+          const txSet = transactionSets[i]
+          const isLast = i === transactionSets.length - 1
+
+          const instructions = [...txSet.instructions]
+          if (isLast && options.tipLamports > 0) {
+            instructions.push(createJitoTipIx(options.tipLamports, options.signers[0].publicKey))
+          }
+
+          const txAltAccounts = resolvedAltAccounts.filter((alt) =>
+            txSet.addressLookupTableAddresses.some((addr) => addr.equals(alt.key)),
+          )
+
+          const msg = new TransactionMessage({
+            payerKey: options.signers[0].publicKey,
+            recentBlockhash: blockhash,
+            instructions,
+          }).compileToV0Message(txAltAccounts)
+
+          let tx = new VersionedTransaction(msg)
+
+          // Co-sign Loopscale steps, sign everything else normally
+          const step = closedSteps.find((s) => s.label === txSet.label)
+          if (step?.isLoopscale && loopscaleClient) {
+            tx.sign([...options.signers, ...txSet.signers])
+            tx = await loopscaleClient.coSign(tx)
+          } else {
+            tx.sign([...options.signers, ...txSet.signers])
+          }
+
+          allTxs.push(tx)
+        }
+
+        // Custom send escape hatch (for testing)
+        if (options.customSend) {
+          const sigs = await options.customSend(allTxs, labels)
+          return { signatures: sigs, bundleId: "" }
+        }
+
+        const serialized = allTxs.map((tx) => Buffer.from(tx.serialize()))
+        const result = await sendJitoBundleRpc(serialized, options.jitoAuthKey)
+
+        const commitment = options.commitment ?? "confirmed"
+        if (result.signatures.length > 0) {
+          await closedConnection.confirmTransaction(
+            { signature: result.signatures[0], blockhash, lastValidBlockHeight },
+            commitment,
+          ).catch(() => {})
+        }
+
+        return result
+      },
+    }
+  }
+}
+
+// ============================================================================
+// bundleForJito — standalone utility
+// ============================================================================
+
+/**
+ * Package TransactionSets into Jito-compatible unsigned VersionedTransactions.
+ *
+ * All transactions share the same blockhash and a Jito tip instruction is appended
+ * to the last transaction. The returned transactions are **unsigned** — the caller
+ * is responsible for signing (useful for web app flows where a wallet adapter handles signing).
+ *
+ * For a fully managed sign-and-send flow, use {@link VaultTransactionBuildResult.sendJitoBundle} instead.
+ *
+ * @param transactionSets - Ordered TransactionSets from `builder.build()`.
+ * @param params.connection - Solana RPC connection for ALT resolution and blockhash fetching.
+ * @param params.payer - Public key of the fee payer (used in the V0 message header).
+ * @param params.tipLamports - Jito tip amount in lamports, appended to the last transaction.
+ * @param params.lookupTableAddresses - All ALT addresses from the build result.
+ * @returns Unsigned VersionedTransactions ready for wallet signing.
+ */
+export async function bundleForJito(
+  transactionSets: TransactionSet[],
+  params: {
+    connection: Connection
+    payer: PublicKey
+    tipLamports: number
+    lookupTableAddresses: PublicKey[]
+  },
+): Promise<VersionedTransaction[]> {
+  const { connection, payer, tipLamports, lookupTableAddresses } = params
+
+  const altAccounts = await resolveAltAccounts(connection, lookupTableAddresses)
+  const { blockhash } = await connection.getLatestBlockhash()
+
+  const transactions: VersionedTransaction[] = []
+
+  for (let i = 0; i < transactionSets.length; i++) {
+    const txSet = transactionSets[i]
+    const isLast = i === transactionSets.length - 1
+
+    const instructions = [...txSet.instructions]
+    if (isLast && tipLamports > 0) {
+      instructions.push(createJitoTipIx(tipLamports, payer))
+    }
+
+    const txAltAccounts = altAccounts.filter((alt) =>
+      txSet.addressLookupTableAddresses.some((addr) => addr.equals(alt.key)),
+    )
+
+    const messageV0 = new TransactionMessage({
+      payerKey: payer,
+      recentBlockhash: blockhash,
+      instructions,
+    }).compileToV0Message(txAltAccounts)
+
+    transactions.push(new VersionedTransaction(messageV0))
+  }
+
+  return transactions
+}
+
+// ============================================================================
+// Internal helpers
+// ============================================================================
+
+/** Build compute budget instructions: CU limit + heap frame + optional priority fee. */
+function buildComputeBudgetIxs(
+  computeUnitLimit: number,
+  heapFrameBytes: number,
+  priorityFee?: number,
+): TransactionInstruction[] {
+  const ixs = [
+    ComputeBudgetProgram.setComputeUnitLimit({ units: computeUnitLimit }),
+    ComputeBudgetProgram.requestHeapFrame({ bytes: heapFrameBytes }),
+  ]
+  if (priorityFee !== undefined && priorityFee > 0) {
+    ixs.push(ComputeBudgetProgram.setComputeUnitPrice({ microLamports: priorityFee }))
+  }
+  return ixs
+}
+
+/** Fetch and resolve AddressLookupTableAccounts from on-chain, filtering nulls. */
+async function resolveAltAccounts(
+  connection: Connection,
+  addresses: PublicKey[],
+): Promise<AddressLookupTableAccount[]> {
+  const results = await Promise.all(
+    addresses.map((addr) => connection.getAddressLookupTable(addr)),
+  )
+  return results
+    .map((r) => r.value)
+    .filter((v): v is AddressLookupTableAccount => v !== null)
+}
+
+/** Create a Jito tip transfer instruction to a random tip address. */
+function createJitoTipIx(tipLamports: number, payer: PublicKey): TransactionInstruction {
+  const tipReceiver = JITO_TIP_ADDRESSES[Math.floor(Math.random() * JITO_TIP_ADDRESSES.length)]
+  return SystemProgram.transfer({
+    fromPubkey: payer,
+    toPubkey: tipReceiver,
+    lamports: BigInt(Math.floor(tipLamports)),
+  })
+}
+
+// ── Jito bundle sending ──
+
+type JitoRpcResponse = { result?: string; error?: unknown }
+
+/**
+ * Send a bundle of serialized transactions to Jito block engine endpoints.
+ * Fans out to regional endpoints (best-effort) and retries the mainnet endpoint.
+ */
+async function sendJitoBundleRpc(
+  serializedTransactions: Buffer[],
+  authKey?: string,
+): Promise<JitoBundleResult> {
+  if (serializedTransactions.length > 5) {
+    throw new Error("Jito bundles support at most 5 transactions")
+  }
+
+  const signatures = serializedTransactions.map((tx) => {
+    const vtx = VersionedTransaction.deserialize(tx)
+    return Buffer.from(vtx.signatures[0]).toString("base64")
+  })
+
+  const requestBody = {
+    jsonrpc: "2.0",
+    id: 1,
+    method: "sendBundle",
+    params: [serializedTransactions.map((tx) => tx.toString("base64")), { encoding: "base64" }],
+  }
+
+  const headers: Record<string, string> = { "Content-Type": "application/json" }
+  if (authKey) headers["x-jito-auth"] = authKey
+
+  // Fan out to regional endpoints (best-effort, don't await)
+  const regionalPromises = JITO_REGIONAL_URLS.map((url) =>
+    fetch(`${url}${JITO_BUNDLES_PATH}`, { method: "POST", headers, body: JSON.stringify(requestBody) })
+      .catch(() => {}),
+  )
+  Promise.allSettled(regionalPromises)
+
+  // Retry mainnet endpoint
+  for (let attempt = 0; attempt < JITO_MAX_RETRIES; attempt++) {
+    try {
+      const response = await fetch(`${JITO_MAINNET_URL}${JITO_BUNDLES_PATH}`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(requestBody),
+      })
+
+      const data = (await response.json().catch(() => undefined)) as JitoRpcResponse | undefined
+
+      if (response.ok && !data?.error && typeof data?.result === "string") {
+        return { bundleId: data.result, signatures }
+      }
+
+      if (response.status === 400) {
+        return { bundleId: "", signatures }
+      }
+    } catch {}
+
+    await new Promise((r) => setTimeout(r, JITO_RETRY_DELAY_MS))
+  }
+
+  return { bundleId: "", signatures }
+}
+
+// ── ALT auto-extension (reserved for future use) ──
+
+/**
+ * Auto-extend an address lookup table with all unique accounts from the given instructions.
+ * Batches in groups of 30 addresses (Solana limit per extend instruction).
+ * Waits 2 seconds after extension for ALT propagation.
+ *
+ * @internal Not currently wired into any flow. Reserved for when ALT management
+ * needs to be handled by the builder (e.g., oversized Loopscale transactions).
+ */
+async function autoExtendAlt(
+  connection: Connection,
+  lookupTable: PublicKey,
+  authority: web3.Signer,
+  instructions: TransactionInstruction[],
+): Promise<void> {
+  const seen = new Set<string>()
+  const addresses: PublicKey[] = []
+  for (const ix of instructions) {
+    for (const key of [ix.programId, ...ix.keys.map((k) => k.pubkey)]) {
+      const keyStr = key.toBase58()
+      if (!seen.has(keyStr)) {
+        seen.add(keyStr)
+        addresses.push(key)
+      }
+    }
+  }
+
+  for (let i = 0; i < addresses.length; i += 30) {
+    const batch = addresses.slice(i, i + 30)
+    const extendIx = AddressLookupTableProgram.extendLookupTable({
+      payer: authority.publicKey,
+      authority: authority.publicKey,
+      lookupTable,
+      addresses: batch,
+    })
+
+    const { blockhash } = await connection.getLatestBlockhash()
+    const msg = new TransactionMessage({
+      payerKey: authority.publicKey,
+      recentBlockhash: blockhash,
+      instructions: [extendIx],
+    }).compileToV0Message()
+
+    const tx = new VersionedTransaction(msg)
+    tx.sign([authority])
+    await connection.sendRawTransaction(tx.serialize())
+  }
+
+  await new Promise((r) => setTimeout(r, 2000))
+}