@exponent-labs/exponent-sdk 0.9.1 → 0.9.3

package/src/exponentVaults/vaultTransactionBuilder.ts

@@ -1,927 +0,0 @@
-import {
-  AddressLookupTableProgram,
-  Connection,
-  PublicKey,
-  TransactionInstruction,
-  TransactionMessage,
-  VersionedTransaction,
-  AddressLookupTableAccount,
-  ComputeBudgetProgram,
-} 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"
-import type { LoopscaleTransactionResponse } from "./loopscale"
-import {
-  buildSetupStatePriceRefreshInstructions,
-  createVaultSyncTransaction,
-  createStrategySetupContext,
-  type VaultInstruction,
-} from "./vault-interaction"
-import { SQUADS_PROGRAM_ID } from "./syncTransaction"
-import { LOCAL_ENV } from "../environment"
-
-const SCOPE_PROGRAM_ID = new PublicKey("HFn8GnPADiny6XqUoWE8uRPPxb29ikn4yTuPa9MF2fWJ")
-
-// ============================================================================
-// 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
-}
-
-/** Label-only options for raw Loopscale response steps. */
-export interface LoopscaleStepOptions {
-  /** Human-readable label for this Loopscale step. Auto-generated if omitted. */
-  label?: string
-}
-
-/** Optional Loopscale client config used by the builder for preparation and MPC co-signing. */
-export interface VaultTransactionBuilderLoopscaleConfig {
-  /** Override the Loopscale API base URL. */
-  baseUrl?: string
-  /** Enable verbose Loopscale request/response logging. */
-  debug?: boolean
-}
-
-/**
- * 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
- *   autoManagePositions: true,        // optional, defaults to true
- *   pricesAccount,                    // optional prefetched ExponentPrices snapshot
- * })
- * ```
- */
-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
-  /** Optional vault PDA override. Defaults to `vault.state.squadsVault`. */
-  vaultPda?: PublicKey
-  /** Optional extra lookup tables to include alongside the vault-managed tables. */
-  lookupTableAddresses?: PublicKey[]
-  /**
-   * Fetched `ExponentPrices` account snapshot (optional).
-   *
-   * When provided, the builder reuses this snapshot to assemble same-transaction
-   * `UpdatePrice` instructions for any setup or sync transaction that can hit
-   * AUM recalculation. When omitted, the builder fetches the current prices
-   * account automatically.
-   */
-  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
-  /** Automatically manage new Kamino/CLMM/yield position tracking for manager flows. Defaults to `true`. */
-  autoManagePositions?: boolean
-  /** Squads program ID override. Defaults to the standard Squads V4 program. */
-  squadsProgram?: PublicKey
-  /** Optional Loopscale client config used when preparing and co-signing Loopscale transactions. */
-  loopscale?: VaultTransactionBuilderLoopscaleConfig
-}
-
-type StepConfig =
-  | {
-    kind: "instructions"
-    label: string
-    instructions: VaultInstruction[]
-    options: StepOptions
-  }
-  | {
-    kind: "loopscale-response"
-    label: string
-    response: LoopscaleTransactionResponse
-    options: LoopscaleStepOptions
-  }
-
-/**
- * A group of instructions that will be assembled into a single VersionedTransaction.
- *
- * The builder produces an ordered array of TransactionSets: optional setup
- * transactions, then one sync transaction per step. Same-transaction Exponent
- * price refreshes are injected directly into any set that can hit AUM
- * recalculation.
- */
-export interface TransactionSet {
-  /** Human-readable label identifying this transaction (e.g. "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[]
-  /** Whether this transaction needs Loopscale MPC co-signing before broadcast. */
-  coSignWithLoopscale?: boolean
-}
-
-/**
- * Options for {@link VaultTransactionBuildResult.send}.
- */
-export interface SendOptions {
-  /** Keypair signers. The first signer is used as the fee payer. */
-  signers: web3.Signer[]
-  /** Commitment level for transaction confirmation (default: "confirmed"). */
-  commitment?: web3.Commitment
-}
-
-/** Result from {@link VaultTransactionBuildResult.send}. */
-export interface SendResult {
-  /** Transaction signatures in the same order as the TransactionSets. */
-  signatures: string[]
-  /**
-   * Non-null when an ephemeral address lookup table was created to fit all
-   * accounts into the transactions. The caller can deactivate and close it
-   * to reclaim rent when they no longer need it.
-   *
-   * Cleanup requires two steps (Solana constraint):
-   * 1. `AddressLookupTableProgram.deactivateLookupTable({ lookupTable: address, authority })`
-   * 2. After ~one epoch, `AddressLookupTableProgram.closeLookupTable({ lookupTable: address, authority, recipient: authority })`
-   */
-  ephemeralAlt: { address: PublicKey; authority: PublicKey } | null
-}
-
-/**
- * The result of calling {@link VaultTransactionBuilder.build}.
- *
- * Contains the assembled TransactionSets and a `send()` method for sequential execution.
- * Loopscale co-signing is handled automatically.
- *
- * @example
- * ```ts
- * const result = await builder.build()
- *
- * // Inspect
- * console.log(result.labels)  // ["step-1", "loopscale-step-2"]
- *
- * // Send sequentially
- * await result.send({ signers: [manager] })
- * ```
- */
-export interface VaultTransactionBuildResult {
-  /** Ordered TransactionSets: setup + sync per step, with same-tx price refresh injected as needed. */
-  transactionSets: TransactionSet[]
-  /** Deduplicated address lookup table addresses across all TransactionSets. */
-  lookupTableAddresses: PublicKey[]
-  /** Labels for each TransactionSet, in order. */
-  labels: string[]
-  /**
-   * Send transactions sequentially via regular RPC.
-   *
-   * Each transaction is built, signed (and co-signed for Loopscale steps),
-   * sent via `connection.sendTransaction()`, and confirmed before proceeding
-   * to the next one. Suitable for most operations.
-   *
-   * **Note:** Does not guarantee atomicity — if a later transaction fails,
-   * earlier ones have already landed.
-   */
-  send(options: SendOptions): Promise<SendResult>
-}
-
-// ============================================================================
-// VaultTransactionBuilder
-// ============================================================================
-
-/**
- * Orchestrates strategy vault transaction construction.
- *
- * Replaces the per-recipe boilerplate of manually assembling compute budgets,
- * sync transaction wrapping, ALT gathering, setup transaction splitting, and
- * forward-looking Kamino/CLMM/yield position tracking.
- *
- * **Lifecycle:** create → add actions → build → send()
- *
- * @example Single action
- * ```ts
- * const result = await VaultTransactionBuilder
- *   .create({ vault, connection, signer: manager.publicKey })
- *   .addActions([clmmAction.buyPt({ market, ptOutMin, syInMax })])
- *   .build()
- *
- * await result.send({ signers: [manager] })
- * ```
- *
- * @example Multi-step — each addActions() becomes its own sync transaction
- * ```ts
- * const result = await VaultTransactionBuilder
- *   .create({ vault, connection, signer: manager.publicKey })
- *   .addActions([kaminoAction.deposit("MAIN", "USDC", amount)])   // sync tx 1
- *   .addActions([kaminoAction.borrow("MAIN", "SOL", amount)])     // sync tx 2
- *   .build()
- *
- * await result.send({ signers: [manager] })
- * ```
- *
- * @example Mixed Kamino + Loopscale — co-signing handled automatically
- * ```ts
- * const loopscaleDeposit = await loopscale.depositStrategy({ ... })
- *
- * const result = await VaultTransactionBuilder
- *   .create({ vault, connection, signer: manager.publicKey })
- *   .addActions([kaminoAction.deposit(...)])                        // signed normally
- *   .addLoopscaleResponse(loopscaleDeposit)                         // co-signed automatically
- *   .build()
- *
- * // send() auto-creates a LoopscaleClient for Loopscale co-signing
- * await result.send({ signers: [manager] })
- * ```
- */
-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, and signer.
-   * @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({ kind: "instructions", label, instructions: [...instructions], options: options ?? {} })
-    return this
-  }
-
-  /**
-   * Add a raw Loopscale response as a new step.
-   *
-   * The builder will flatten the response into manager-facing transactions,
-   * preserving Loopscale-signed segments while keeping local setup/top-level
-   * transactions outside the Loopscale signing domain.
-   *
-   * @param response - Raw Loopscale response returned by {@link LoopscaleClient}.
-   * Only `label` is supported for Loopscale steps. Compute overrides are
-   * preserved on the raw Loopscale response and are not applied by the
-   * builder.
-   *
-   * @param options - Optional step label.
-   * @returns `this` for chaining.
-   */
-  addLoopscaleResponse(response: LoopscaleTransactionResponse, options?: LoopscaleStepOptions): this {
-    this.stepCounter++
-    const label = options?.label ?? `loopscale-step-${this.stepCounter}`
-    this.steps.push({ kind: "loopscale-response", label, response, options: options ?? {} })
-    return this
-  }
-
-  /**
-   * Build TransactionSets from the configured steps.
-   *
-   * Produces an ordered array of TransactionSets:
-   * 1. **Setup transactions** — token account creation / builder-managed setup (only if needed)
-   * 2. **Sync transactions** — one per step, wrapped in Squads sync transaction
-   *
-   * Same-transaction `UpdatePrice` instructions are injected directly into any
-   * setup or sync set that can hit AUM recalculation.
-   *
-   * Use `result.send()` for sequential execution.
-   *
-   * @returns A {@link VaultTransactionBuildResult} with TransactionSets and a send 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 addLoopscaleResponse() before build().")
-    }
-
-    const { vault, connection, signer, pricesAccount } = this.config
-    const vaultPda = this.config.vaultPda ?? vault.state.squadsVault
-    const extraLookupTableAddresses = this.config.lookupTableAddresses ?? []
-    const autoManagePositions = this.config.autoManagePositions ?? true
-    const squadsProgram = this.config.squadsProgram ?? SQUADS_PROGRAM_ID
-    const defaultCU = this.config.computeUnitLimit ?? 1_400_000
-    const defaultHeap = this.config.heapFrameBytes ?? 256 * 1024
-
-    const transactionSets: TransactionSet[] = []
-    const allAltAddresses = new Set<string>(
-      [
-        ...(vault.state.addressLookupTable ? [vault.state.addressLookupTable.toBase58()] : []),
-        ...extraLookupTableAddresses.map((address) => address.toBase58()),
-      ],
-    )
-
-    // Share a single setup context across all steps so that tracked accounts,
-    // positions, and orderbooks carry over — preventing duplicate setup txs.
-    const sharedSetupContext = createStrategySetupContext({
-      connection,
-      env: LOCAL_ENV,
-      owner: vaultPda,
-      signer,
-      vaultAddress: vault.selfAddress,
-      vaultPda,
-      accountIndex: 0,
-      squadsProgram,
-      autoManagePositions,
-      pricesAccount,
-    })
-    let loopscaleClient: LoopscaleClient | undefined
-
-    for (const step of this.steps) {
-      if (step.kind === "loopscale-response") {
-        loopscaleClient ??= createBuilderLoopscaleClient({
-          connection,
-          vaultPda,
-          loopscale: this.config.loopscale,
-        })
-
-        const preparedTransactions = await loopscaleClient.prepareVaultTransactions({
-          response: step.response,
-          context: {
-            connection,
-            signer,
-            vaultPda,
-            vaultAddress: vault.selfAddress,
-            squadsProgram,
-          },
-        })
-        const stepPriceRefreshIxs = await buildSetupStatePriceRefreshInstructions(sharedSetupContext)
-
-        for (const [preparedIndex, preparedTransaction] of preparedTransactions.entries()) {
-          const txLabel = preparedTransactions.length === 1
-            ? step.label
-            : `${step.label}-${preparedIndex + 1}`
-
-          if (preparedTransaction.setupInstructions.length > 0) {
-            const setupAltAddresses = mergeAddressLookupTableAddresses(
-              extraLookupTableAddresses,
-              vault.state.addressLookupTable ? [vault.state.addressLookupTable] : [],
-            )
-            const setupSet: TransactionSet = {
-              label: `${txLabel}-setup`,
-              instructions: [
-                ComputeBudgetProgram.setComputeUnitLimit({ units: defaultCU }),
-                ...preparedTransaction.setupInstructions,
-              ],
-              signers: [],
-              addressLookupTableAddresses: setupAltAddresses,
-              coSignWithLoopscale: false,
-            }
-            if (touchesManagedVaultPrograms(setupSet.instructions, vault.programId, squadsProgram)) {
-              setupSet.instructions = insertAfterLeadingComputeBudgetAndScopeInstructions(
-                setupSet.instructions,
-                stepPriceRefreshIxs,
-              )
-            }
-            transactionSets.push(setupSet)
-            for (const alt of setupSet.addressLookupTableAddresses) {
-              allAltAddresses.add(alt.toBase58())
-            }
-          }
-
-          const shouldInjectLocalLoopscalePriceRefresh = (
-            !preparedTransaction.requiresLoopscaleCoSign
-            && touchesManagedVaultPrograms(preparedTransaction.instructions, vault.programId, squadsProgram)
-          )
-          const loopscaleSet: TransactionSet = {
-            label: txLabel,
-            instructions: preparedTransaction.instructions,
-            signers: preparedTransaction.signers,
-            addressLookupTableAddresses: shouldInjectLocalLoopscalePriceRefresh
-              ? mergeAddressLookupTableAddresses(
-                preparedTransaction.addressLookupTableAddresses,
-                extraLookupTableAddresses,
-                vault.state.addressLookupTable ? [vault.state.addressLookupTable] : [],
-              )
-              : mergeAddressLookupTableAddresses(
-                preparedTransaction.addressLookupTableAddresses,
-                extraLookupTableAddresses,
-              ),
-            coSignWithLoopscale: preparedTransaction.requiresLoopscaleCoSign,
-          }
-          if (shouldInjectLocalLoopscalePriceRefresh) {
-            loopscaleSet.instructions = insertAfterLeadingComputeBudgetAndScopeInstructions(
-              loopscaleSet.instructions,
-              stepPriceRefreshIxs,
-            )
-          }
-          transactionSets.push(loopscaleSet)
-
-          for (const alt of loopscaleSet.addressLookupTableAddresses) {
-            allAltAddresses.add(alt.toBase58())
-          }
-        }
-        continue
-      }
-
-      const stepCU = step.options.computeUnitLimit ?? defaultCU
-      const stepHeap = step.options.heapFrameBytes ?? defaultHeap
-      const syncResult = await createVaultSyncTransaction({
-        instructions: step.instructions,
-        owner: vaultPda,
-        connection,
-        vaultPda,
-        signer,
-        vaultAddress: vault.selfAddress,
-        squadsProgram,
-        autoManagePositions,
-        setupContext: sharedSetupContext,
-      })
-
-      const stepPriceRefreshIxs = await buildSetupStatePriceRefreshInstructions(sharedSetupContext)
-
-      if (syncResult.setupInstructions.length > 0) {
-        const setupSet: TransactionSet = {
-          label: `${step.label}-setup`,
-          instructions: [
-            ComputeBudgetProgram.setComputeUnitLimit({ units: defaultCU }),
-            ...syncResult.setupInstructions,
-          ],
-          signers: [],
-          addressLookupTableAddresses: mergeAddressLookupTableAddresses(
-            syncResult.addressLookupTableAddresses,
-            extraLookupTableAddresses,
-            vault.state.addressLookupTable ? [vault.state.addressLookupTable] : [],
-          ),
-          coSignWithLoopscale: false,
-        }
-        if (shouldInjectPriceRefresh(setupSet, vault.programId, squadsProgram)) {
-          setupSet.instructions = insertAfterLeadingComputeBudgetAndScopeInstructions(
-            setupSet.instructions,
-            stepPriceRefreshIxs,
-          )
-        }
-        transactionSets.push(setupSet)
-        for (const alt of setupSet.addressLookupTableAddresses) {
-          allAltAddresses.add(alt.toBase58())
-        }
-      }
-
-      const syncSet: TransactionSet = {
-        label: step.label,
-        instructions: [
-          ...buildComputeBudgetIxs(stepCU, stepHeap, step.options.priorityFee),
-          ...syncResult.preInstructions,
-          syncResult.instruction,
-          ...syncResult.postInstructions,
-        ],
-        signers: syncResult.signers,
-        addressLookupTableAddresses: mergeAddressLookupTableAddresses(
-          syncResult.addressLookupTableAddresses,
-          extraLookupTableAddresses,
-          vault.state.addressLookupTable ? [vault.state.addressLookupTable] : [],
-        ),
-        coSignWithLoopscale: false,
-      }
-      if (shouldInjectPriceRefresh(syncSet, vault.programId, squadsProgram)) {
-        syncSet.instructions = insertAfterLeadingComputeBudgetAndScopeInstructions(
-          syncSet.instructions,
-          stepPriceRefreshIxs,
-        )
-      }
-      transactionSets.push(syncSet)
-
-      for (const alt of syncSet.addressLookupTableAddresses) {
-        allAltAddresses.add(alt.toBase58())
-      }
-    }
-
-    const lookupTableAddresses = [...allAltAddresses].map((a) => new PublicKey(a))
-
-    // Resolve the vault's persistent ALT to determine which account keys it
-    // already covers. Any keys NOT covered will need an ephemeral ALT.
-    const persistentAltAccounts = await resolveAltAccounts(connection, lookupTableAddresses)
-    const persistentAltKeys = new Set<string>()
-    for (const alt of persistentAltAccounts) {
-      for (const addr of alt.state.addresses) {
-        persistentAltKeys.add(addr.toBase58())
-      }
-    }
-
-    // Collect every unique account key referenced by any transaction set.
-    const allUniqueKeys = collectUniqueAccountKeys(transactionSets, signer)
-    const ephemeralAltEntries = allUniqueKeys.filter((k) => !persistentAltKeys.has(k.toBase58()))
-
-    // Validate transaction sizes. When an ephemeral ALT will be created,
-    // skip validation here — send() will validate after ALT activation.
-    if (ephemeralAltEntries.length === 0) {
-      validateTransactionSizes(transactionSets, persistentAltAccounts, signer)
-    }
-
-    const labels = transactionSets.map((ts) => ts.label)
-
-    // Capture state for send() closure
-    const closedConnection = connection
-    const closedSigner = signer
-    const closedVaultPda = vaultPda
-    const closedLookupTableAddresses = lookupTableAddresses
-    const closedLoopscaleConfig = this.config.loopscale
-
-    return {
-      transactionSets,
-      lookupTableAddresses,
-      labels,
-
-      async send(options: SendOptions): Promise<SendResult> {
-        const commitment = options.commitment ?? "confirmed"
-        const payer = options.signers[0]
-
-        // ── Ephemeral ALT creation ───────────────────────────────────────
-        let ephemeralAlt: { address: PublicKey; authority: PublicKey } | null = null
-        let ephemeralAltAccount: AddressLookupTableAccount | undefined
-
-        if (ephemeralAltEntries.length > 0) {
-          const slot = await closedConnection.getSlot("processed")
-          const recentSlot = Math.max(slot - 1, 0)
-          const [createIx, altAddress] = AddressLookupTableProgram.createLookupTable({
-            authority: payer.publicKey,
-            payer: payer.publicKey,
-            recentSlot,
-          })
-
-          // Chunk extend instructions — each can hold ~20 addresses safely
-          const extendChunks = chunkArray(ephemeralAltEntries, 20)
-          const extendIxs = extendChunks.map((chunk) =>
-            AddressLookupTableProgram.extendLookupTable({
-              lookupTable: altAddress,
-              authority: payer.publicKey,
-              payer: payer.publicKey,
-              addresses: chunk,
-            }),
-          )
-
-          // Send create + first extend in one transaction
-          const altSetupIxs: TransactionInstruction[] = [createIx, extendIxs[0]!]
-          await sendAndConfirmTransaction(closedConnection, altSetupIxs, [payer], commitment)
-
-          // Send remaining extend chunks if any
-          for (let i = 1; i < extendIxs.length; i++) {
-            await sendAndConfirmTransaction(closedConnection, [extendIxs[i]!], [payer], commitment)
-          }
-
-          // Wait for ALT entries to become active (usable in the slot AFTER extension)
-          await waitForSlotAdvance(closedConnection, slot, "processed")
-
-          // Resolve the ephemeral ALT account for use in transactions
-          const resolved = await closedConnection.getAddressLookupTable(altAddress)
-          if (!resolved.value) {
-            throw new Error(`Ephemeral ALT ${altAddress.toBase58()} not found after creation`)
-          }
-          ephemeralAltAccount = resolved.value
-          ephemeralAlt = { address: altAddress, authority: payer.publicKey }
-        }
-
-        // ── Resolve all ALT accounts (persistent + ephemeral) ────────────
-        const resolvedAltAccounts = await resolveAltAccounts(closedConnection, closedLookupTableAddresses)
-        if (ephemeralAltAccount) {
-          resolvedAltAccounts.push(ephemeralAltAccount)
-        }
-
-        // If we skipped build-time validation, validate now with the full ALT set
-        if (ephemeralAltEntries.length > 0) {
-          validateTransactionSizes(transactionSets, resolvedAltAccounts, closedSigner, ephemeralAltAccount)
-        }
-
-        // ── Auto-create LoopscaleClient if any step needs co-signing ─────
-        const hasLoopscale = transactionSets.some((txSet) => txSet.coSignWithLoopscale)
-        let loopscaleClient: LoopscaleClient | undefined
-        if (hasLoopscale) {
-          loopscaleClient = createBuilderLoopscaleClient({
-            connection: closedConnection,
-            vaultPda: closedVaultPda,
-            loopscale: closedLoopscaleConfig,
-          })
-        }
-
-        // ── Send transactions ────────────────────────────────────────────
-        const signatures: string[] = []
-        for (const txSet of transactionSets) {
-          const { blockhash, lastValidBlockHeight } = await closedConnection.getLatestBlockhash()
-
-          // Include the ephemeral ALT for every transaction set
-          const txAltAccounts = resolvedAltAccounts.filter((alt) =>
-            txSet.addressLookupTableAddresses.some((addr) => addr.equals(alt.key))
-            || (ephemeralAltAccount && alt.key.equals(ephemeralAltAccount.key)),
-          )
-
-          const msg = new TransactionMessage({
-            payerKey: payer.publicKey,
-            recentBlockhash: blockhash,
-            instructions: txSet.instructions,
-          }).compileToV0Message(txAltAccounts)
-
-          let tx = new VersionedTransaction(msg)
-          if (txSet.coSignWithLoopscale && loopscaleClient) {
-            tx.sign([...options.signers, ...txSet.signers])
-            tx = await loopscaleClient.coSign(tx)
-          } else {
-            tx.sign([...options.signers, ...txSet.signers])
-          }
-
-          const sig = await closedConnection.sendTransaction(tx)
-          await closedConnection.confirmTransaction(
-            { signature: sig, blockhash, lastValidBlockHeight },
-            commitment,
-          )
-          signatures.push(sig)
-        }
-
-        return { signatures, ephemeralAlt }
-      },
-
-    }
-  }
-}
-
-// ============================================================================
-// 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
-}
-
-function insertAfterLeadingComputeBudgetAndScopeInstructions(
-  instructions: TransactionInstruction[],
-  extraInstructions: TransactionInstruction[],
-): TransactionInstruction[] {
-  if (extraInstructions.length === 0) {
-    return instructions
-  }
-
-  let insertIndex = 0
-  while (
-    insertIndex < instructions.length
-    && instructions[insertIndex]?.programId.equals(ComputeBudgetProgram.programId)
-  ) {
-    insertIndex += 1
-  }
-
-  while (
-    insertIndex < instructions.length
-    && instructions[insertIndex]?.programId.equals(SCOPE_PROGRAM_ID)
-  ) {
-    insertIndex += 1
-  }
-
-  return [
-    ...instructions.slice(0, insertIndex),
-    ...extraInstructions,
-    ...instructions.slice(insertIndex),
-  ]
-}
-
-function shouldInjectPriceRefresh(
-  txSet: TransactionSet,
-  programId: PublicKey,
-  squadsProgram: PublicKey,
-): boolean {
-  if (!txSet.label.endsWith("-setup")) {
-    return true
-  }
-
-  return txSet.instructions.some((instruction) =>
-    instruction.programId.equals(programId) || instruction.programId.equals(squadsProgram),
-  )
-}
-
-function touchesManagedVaultPrograms(
-  instructions: TransactionInstruction[],
-  programId: PublicKey,
-  squadsProgram: PublicKey,
-): boolean {
-  return instructions.some((instruction) =>
-    instruction.programId.equals(programId) || instruction.programId.equals(squadsProgram),
-  )
-}
-
-function mergeAddressLookupTableAddresses(
-  ...addressGroups: Array<readonly PublicKey[]>
-): PublicKey[] {
-  const seen = new Set<string>()
-  const merged: PublicKey[] = []
-
-  for (const group of addressGroups) {
-    for (const address of group) {
-      const key = address.toBase58()
-      if (seen.has(key)) continue
-      seen.add(key)
-      merged.push(address)
-    }
-  }
-
-  return merged
-}
-
-function createBuilderLoopscaleClient(params: {
-  connection: Connection
-  vaultPda: PublicKey
-  loopscale?: VaultTransactionBuilderLoopscaleConfig
-}): LoopscaleClient {
-  return new LoopscaleClient({
-    connection: params.connection,
-    userWallet: params.vaultPda,
-    baseUrl: params.loopscale?.baseUrl,
-    debug: params.loopscale?.debug,
-  })
-}
-
-/** 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)
-}
-
-/** Collect all unique account keys referenced across all transaction sets. */
-function collectUniqueAccountKeys(
-  transactionSets: TransactionSet[],
-  signer: PublicKey,
-): PublicKey[] {
-  const seen = new Set<string>()
-  const keys: PublicKey[] = []
-
-  const add = (pubkey: PublicKey) => {
-    const str = pubkey.toBase58()
-    if (!seen.has(str)) {
-      seen.add(str)
-      keys.push(pubkey)
-    }
-  }
-
-  add(signer)
-  for (const txSet of transactionSets) {
-    for (const ix of txSet.instructions) {
-      add(ix.programId)
-      for (const key of ix.keys) {
-        add(key.pubkey)
-      }
-    }
-  }
-
-  return keys
-}
-
-/** Validate that every transaction set can serialize within the 1232-byte limit. */
-function validateTransactionSizes(
-  transactionSets: TransactionSet[],
-  altAccounts: AddressLookupTableAccount[],
-  signer: PublicKey,
-  extraAlt?: AddressLookupTableAccount,
-): void {
-  for (const txSet of transactionSets) {
-    const txAltAccounts = altAccounts.filter((alt) =>
-      txSet.addressLookupTableAddresses.some((addr) => addr.equals(alt.key)),
-    )
-    if (extraAlt && !txAltAccounts.some((a) => a.key.equals(extraAlt.key))) {
-      txAltAccounts.push(extraAlt)
-    }
-    try {
-      const testMsg = new TransactionMessage({
-        payerKey: signer,
-        recentBlockhash: PublicKey.default.toBase58(),
-        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) {
-        const ixCount = txSet.instructions.length
-        const altCount = txAltAccounts.length
-        const accountCount = txSet.instructions.reduce((sum, ix) => sum + ix.keys.length, 0)
-        throw new Error(
-          `Transaction "${txSet.label}" failed to serialize: ${e.message}. ` +
-          `Transaction has ${ixCount} instructions, ${accountCount} account keys, ` +
-          `and ${altCount} address lookup table(s). ` +
-          `Try splitting actions into separate addActions() calls.`,
-        )
-      }
-      throw e
-    }
-  }
-}
-
-/** Split an array into chunks of the given size. */
-function chunkArray<T>(arr: T[], size: number): T[][] {
-  const chunks: T[][] = []
-  for (let i = 0; i < arr.length; i += size) {
-    chunks.push(arr.slice(i, i + size))
-  }
-  return chunks
-}
-
-/** Build, sign, send, and confirm a simple transaction. */
-async function sendAndConfirmTransaction(
-  connection: Connection,
-  instructions: TransactionInstruction[],
-  signers: web3.Signer[],
-  commitment: web3.Commitment,
-): Promise<string> {
-  const { blockhash, lastValidBlockHeight } = await connection.getLatestBlockhash(commitment)
-  const msg = new TransactionMessage({
-    payerKey: signers[0]!.publicKey,
-    recentBlockhash: blockhash,
-    instructions,
-  }).compileToV0Message()
-  const tx = new VersionedTransaction(msg)
-  tx.sign(signers)
-  const sig = await connection.sendTransaction(tx)
-  await connection.confirmTransaction({ signature: sig, blockhash, lastValidBlockHeight }, commitment)
-  return sig
-}
-
-/** Poll until the current slot advances past the target slot. */
-async function waitForSlotAdvance(
-  connection: Connection,
-  targetSlot: number,
-  commitment: web3.Commitment = "processed",
-): Promise<void> {
-  for (let i = 0; i < 60; i++) {
-    const currentSlot = await connection.getSlot(commitment)
-    if (currentSlot > targetSlot) return
-    await new Promise((r) => setTimeout(r, 400))
-  }
-  throw new Error("Timed out waiting for slot to advance after ephemeral ALT creation")
-}