@exponent-labs/exponent-sdk 0.1.8 → 0.9.0

package/src/exponentVaults/vault-interaction.ts

@@ -0,0 +1,3479 @@
+import { Reserve } from "@exponent-labs/kamino-reserve-deserializer"
+import { KAMINO_MARKETS, KAMINO_RESERVES, KaminoMarket } from "./kamino-markets"
+import Decimal from "decimal.js"
+import { getKaminoLendObligation, getKaminoUserMetadata, getKaminoFarmsObligationFarm } from "./../../../kamino-lend-standard/src/constants"
+import { KAMINO_LENDING_PROGRAM_ID } from "./policyBuilders"
+import { Obligation } from "@exponent-labs/klend-idl/accounts"
+import { bigintU256ToString } from "@exponent-labs/precise-number"
+import { Orderbook } from "../orderbook/orderbook"
+import { MarketThree } from "../marketThree"
+import { uniqueRemainingAccounts } from "../utils"
+import { SwapDirection } from "../client/clmm"
+import * as exponentClmm from "../client/clmm"
+import * as exponentVaults from "../client/vaults"
+import { OfferType, offerOptions, amount as createAmount } from "../client/orderbook"
+import { LOCAL_ENV, Environment } from "../environment"
+import { Vault } from "../vault"
+import { YtPosition } from "../ytPosition"
+import { ExponentVault as StrategyVault } from "./vault"
+import type { ExponentPrice, ExponentPrices } from "@exponent-labs/exponent-vaults-fetcher"
+
+import {
+  depositReserveLiquidityAndObligationCollateralV2,
+  withdrawObligationCollateralAndRedeemReserveCollateralV2,
+  borrowObligationLiquidityV2,
+  repayObligationLiquidityV2,
+  initObligation,
+  initObligationFarmsForReserve,
+  initUserMetadata,
+  refreshReserve,
+  refreshObligation,
+} from "@exponent-labs/klend-idl/instructions"
+import {
+  TOKEN_PROGRAM_ID,
+  NATIVE_MINT,
+  getAssociatedTokenAddressSync,
+  createAssociatedTokenAccountIdempotentInstruction,
+} from "@solana/spl-token"
+import { wrapInstructionsInSyncTransaction, SQUADS_PROGRAM_ID } from "./syncTransaction"
+import {
+  resolveConstraintIndices,
+  resolveHookAccounts,
+  resolvePolicyMatchForVault,
+} from "./policyMatcher"
+import { buildScopeRefreshInstructions } from "./scope-refresh"
+import * as web3 from "@solana/web3.js"
+import { AccountMeta, Connection, PublicKey, SystemProgram, SYSVAR_INSTRUCTIONS_PUBKEY, SYSVAR_RENT_PUBKEY, TransactionInstruction } from "@solana/web3.js"
+import BN from "bn.js"
+
+const KAMINO_FARMS_PROGRAM_ID = new PublicKey("FarmsPZpWu9i7Kky8tPN37rs2TpmMrAZrC7S7vJa91Hr")
+
+// ============================================================================
+// Vault Instruction Types
+// ============================================================================
+
+type KaminoReserves = typeof KAMINO_RESERVES
+
+/** Actions that can be performed through the vault instruction builder. */
+export enum VaultAction {
+  INIT_USER_METADATA = "INIT_USER_METADATA",
+  INIT_OBLIGATION = "INIT_OBLIGATION",
+  DEPOSIT = "DEPOSIT",
+  WITHDRAW = "WITHDRAW",
+  BORROW = "BORROW",                      
+  REPAY = "REPAY",
+}
+
+/** A market-level instruction (no specific reserve needed). */
+export type MarketInstruction = {
+  action: VaultAction.INIT_USER_METADATA | VaultAction.INIT_OBLIGATION
+  market: KaminoMarket
+}
+
+/** A reserve-level instruction with an amount. */
+export type ReserveInstruction = {
+  action: VaultAction.DEPOSIT | VaultAction.WITHDRAW | VaultAction.BORROW | VaultAction.REPAY
+  market: KaminoMarket
+  asset: string
+  amount: BN
+}
+
+// ============================================================================
+// Orderbook Instruction Types
+// ============================================================================
+
+/** Orderbook trade direction */
+export enum OrderbookTradeDirection {
+  BUY_PT = "BUY_PT",
+  SELL_PT = "SELL_PT",
+  BUY_YT = "BUY_YT",
+  SELL_YT = "SELL_YT",
+}
+
+/** Offer options for limit orders (currently only FillOrKill supported) */
+export type OrderbookOfferOption = "FillOrKill"
+
+/** Actions that can be performed on the Exponent Orderbook */
+export enum OrderbookAction {
+  POST_OFFER = "POST_OFFER",
+  MARKET_OFFER = "MARKET_OFFER",
+  REMOVE_OFFER = "REMOVE_OFFER",
+  WITHDRAW_FUNDS = "WITHDRAW_FUNDS",
+}
+
+export type OrderbookInstructionMode = "wrapper" | "raw"
+
+/** Base instruction type for all orderbook operations */
+interface OrderbookInstructionBase {
+  action: OrderbookAction
+  orderbook: PublicKey
+  mode?: OrderbookInstructionMode
+}
+
+/** Post a limit order on the orderbook */
+export interface OrderbookPostOfferInstruction extends OrderbookInstructionBase {
+  action: OrderbookAction.POST_OFFER
+  direction: OrderbookTradeDirection
+  priceApy: number
+  amount: bigint
+  offerIdx: number
+  offerOption?: OrderbookOfferOption
+  virtualOffer?: boolean
+  expirySeconds?: number
+}
+
+/** Execute a market order on the orderbook */
+export interface OrderbookMarketOfferInstruction extends OrderbookInstructionBase {
+  action: OrderbookAction.MARKET_OFFER
+  direction: OrderbookTradeDirection
+  maxPriceApy: number
+  amount: bigint
+  minAmountOut: bigint
+  virtualOffer?: boolean
+}
+
+/** Cancel an existing limit order */
+export interface OrderbookRemoveOfferInstruction extends OrderbookInstructionBase {
+  action: OrderbookAction.REMOVE_OFFER
+  offerIdx: number
+}
+
+/** Withdraw funds from user escrow */
+export interface OrderbookWithdrawFundsInstruction extends OrderbookInstructionBase {
+  action: OrderbookAction.WITHDRAW_FUNDS
+  ptAmount?: bigint | null
+  ytAmount?: bigint | null
+  syAmount?: bigint | null
+}
+
+/** A single orderbook instruction */
+export type OrderbookInstruction =
+  | OrderbookPostOfferInstruction
+  | OrderbookMarketOfferInstruction
+  | OrderbookRemoveOfferInstruction
+  | OrderbookWithdrawFundsInstruction
+
+// ============================================================================
+// Core Instruction Types (Strip/Merge)
+// ============================================================================
+
+/** Actions that can be performed on Exponent Core */
+export enum CoreAction {
+  STRIP = "STRIP",
+  MERGE = "MERGE",
+  WITHDRAW_YT = "WITHDRAW_YT",
+  DEPOSIT_YT = "DEPOSIT_YT",
+  INITIALIZE_YIELD_POSITION = "INITIALIZE_YIELD_POSITION",
+}
+
+/** Base instruction type for all core operations */
+interface CoreInstructionBase {
+  action: CoreAction
+  vault: PublicKey
+}
+
+/** Strip LST into PT + YT */
+export interface CoreStripInstruction extends CoreInstructionBase {
+  action: CoreAction.STRIP
+  /** Amount of base token (LST) to strip */
+  amountBase: bigint
+}
+
+/** Merge PT + YT into LST */
+export interface CoreMergeInstruction extends CoreInstructionBase {
+  action: CoreAction.MERGE
+  /** Amount of PT/YT to merge (must have equal amounts of both) */
+  amountPy: bigint
+}
+
+/** Withdraw YT from the tracked yield position back into the YT token account */
+export interface CoreWithdrawYtInstruction extends CoreInstructionBase {
+  action: CoreAction.WITHDRAW_YT
+  amountYt: bigint
+}
+
+/** Deposit YT from the YT token account back into the tracked yield position */
+export interface CoreDepositYtInstruction extends CoreInstructionBase {
+  action: CoreAction.DEPOSIT_YT
+  amountYt: bigint
+}
+
+/** Initialize yield position for a vault (owner = Squads vault) */
+export interface CoreInitializeYieldPositionInstruction extends CoreInstructionBase {
+  action: CoreAction.INITIALIZE_YIELD_POSITION
+}
+
+/** A single core instruction */
+export type CoreInstruction =
+  | CoreStripInstruction
+  | CoreMergeInstruction
+  | CoreWithdrawYtInstruction
+  | CoreDepositYtInstruction
+  | CoreInitializeYieldPositionInstruction
+
+// ============================================================================
+// Standard Program Instruction Types (mint_sy / redeem_sy)
+// ============================================================================
+
+export enum SyAction {
+  MINT = "MINT_SY",
+  REDEEM = "REDEEM_SY",
+}
+
+interface SyInstructionBase {
+  action: SyAction
+  vault: PublicKey
+}
+
+export interface SyMintInstruction extends SyInstructionBase {
+  action: SyAction.MINT
+  amountBase: bigint
+}
+
+export interface SyRedeemInstruction extends SyInstructionBase {
+  action: SyAction.REDEEM
+  amountSy: bigint
+}
+
+export type SyInstruction = SyMintInstruction | SyRedeemInstruction
+
+// ============================================================================
+// Titan Instruction Types
+// ============================================================================
+
+export enum TitanAction {
+  SWAP = "SWAP",
+}
+
+/** A pre-built Titan swap instruction to wrap in a sync transaction. */
+export interface TitanSwapInstruction {
+  action: TitanAction.SWAP
+  /** The raw Titan SwapRouteV2 TransactionInstruction (from Titan's router API) */
+  instruction: TransactionInstruction
+}
+
+// ============================================================================
+// Loopscale Instruction Types
+// ============================================================================
+
+/** Actions for Loopscale interactions (loans = borrower side, strategies = lender side). */
+export enum LoopscaleAction {
+  CREATE_LOAN = "LOOPSCALE_CREATE_LOAN",
+  DEPOSIT_COLLATERAL = "LOOPSCALE_DEPOSIT_COLLATERAL",
+  BORROW_PRINCIPAL = "LOOPSCALE_BORROW_PRINCIPAL",
+  REPAY_PRINCIPAL = "LOOPSCALE_REPAY_PRINCIPAL",
+  WITHDRAW_COLLATERAL = "LOOPSCALE_WITHDRAW_COLLATERAL",
+  CLOSE_LOAN = "LOOPSCALE_CLOSE_LOAN",
+  UPDATE_WEIGHT_MATRIX = "LOOPSCALE_UPDATE_WEIGHT_MATRIX",
+  CREATE_STRATEGY = "LOOPSCALE_CREATE_STRATEGY",
+  DEPOSIT_STRATEGY = "LOOPSCALE_DEPOSIT_STRATEGY",
+  WITHDRAW_STRATEGY = "LOOPSCALE_WITHDRAW_STRATEGY",
+  CLOSE_STRATEGY = "LOOPSCALE_CLOSE_STRATEGY",
+  UPDATE_STRATEGY = "LOOPSCALE_UPDATE_STRATEGY",
+  LOCK_LOAN = "LOOPSCALE_LOCK_LOAN",
+  UNLOCK_LOAN = "LOOPSCALE_UNLOCK_LOAN",
+  REFINANCE_LEDGER = "LOOPSCALE_REFINANCE_LEDGER",
+}
+
+/** A pre-built Loopscale instruction (loan or strategy) to wrap in a sync transaction. */
+export interface LoopscaleInstruction {
+  action: LoopscaleAction
+  /** The raw Loopscale TransactionInstruction (from Loopscale API or local builder) */
+  instruction: TransactionInstruction
+}
+
+// ============================================================================
+// CLMM Instruction Types
+// ============================================================================
+
+/** Actions that can be performed on the Exponent CLMM (Concentrated Liquidity Market Maker). */
+export enum ClmmAction {
+  /** Create a new LP position with a specified tick range. Generates keypair internally. */
+  DEPOSIT_LIQUIDITY = "CLMM_DEPOSIT_LIQUIDITY",
+  /** Add more liquidity to an existing LP position. */
+  ADD_LIQUIDITY = "CLMM_ADD_LIQUIDITY",
+  /** Remove liquidity from an LP position and receive PT + SY. */
+  WITHDRAW_LIQUIDITY = "CLMM_WITHDRAW_LIQUIDITY",
+  /** Low-level PT/SY swap. Prefer buyPt/sellPt for directional trades. */
+  TRADE_PT = "CLMM_TRADE_PT",
+  /** Buy PT with SY on the CLMM. */
+  BUY_PT = "CLMM_BUY_PT",
+  /** Sell PT for SY on the CLMM. */
+  SELL_PT = "CLMM_SELL_PT",
+  /** Buy YT with SY on the CLMM. */
+  BUY_YT = "CLMM_BUY_YT",
+  /** Sell YT for SY on the CLMM. */
+  SELL_YT = "CLMM_SELL_YT",
+  /** Claim farm emissions from an LP position. */
+  CLAIM_FARM_EMISSION = "CLMM_CLAIM_FARM_EMISSION",
+}
+
+/** Base type for all CLMM instructions. */
+interface ClmmInstructionBase {
+  action: ClmmAction
+  /** The CLMM MarketThree account address. */
+  market: PublicKey
+}
+
+/** Create a new LP position on the CLMM. The lpPosition keypair is generated internally for good UX. */
+export interface ClmmDepositLiquidityInstruction extends ClmmInstructionBase {
+  action: ClmmAction.DEPOSIT_LIQUIDITY
+  /** Maximum amount of PT to deposit. */
+  ptInIntent: bigint
+  /** Maximum amount of SY to deposit. */
+  syInIntent: bigint
+  /** Lower tick boundary (APY value). */
+  lowerTickKey: number
+  /** Upper tick boundary (APY value). */
+  upperTickKey: number
+}
+
+/** Add liquidity to an existing LP position. */
+export interface ClmmAddLiquidityInstruction extends ClmmInstructionBase {
+  action: ClmmAction.ADD_LIQUIDITY
+  /** The existing LpPosition account public key. */
+  lpPosition: PublicKey
+  /** Maximum amount of PT to add. */
+  ptInIntent: bigint
+  /** Maximum amount of SY to add. */
+  syInIntent: bigint
+}
+
+/** Withdraw liquidity from an LP position. */
+export interface ClmmWithdrawLiquidityInstruction extends ClmmInstructionBase {
+  action: ClmmAction.WITHDRAW_LIQUIDITY
+  /** The LpPosition account to withdraw from. */
+  lpPosition: PublicKey
+  /** Amount of liquidity (LP units) to remove. */
+  lpIn: bigint
+  /** Minimum PT to receive (slippage protection). */
+  minPtOut: bigint
+  /** Minimum SY to receive (slippage protection). */
+  minSyOut: bigint
+}
+
+/** Low-level PT/SY swap on the CLMM. Prefer buyPt/sellPt for directional trades. */
+export interface ClmmTradePtInstruction extends ClmmInstructionBase {
+  action: ClmmAction.TRADE_PT
+  /** Amount of the input token. */
+  traderAmount: bigint
+  /** Minimum output amount (slippage protection). */
+  outConstraint: bigint
+  /** Swap direction: SyToPt or PtToSy. */
+  swapDirection: SwapDirection
+  /** Optional price limit (ln implied APY). */
+  lnImpliedApyLimit?: number
+}
+
+/** Buy PT with SY on the CLMM. */
+export interface ClmmBuyPtInstruction extends ClmmInstructionBase {
+  action: ClmmAction.BUY_PT
+  /** Amount of SY to spend. */
+  amountSy: bigint
+  /** Minimum PT to receive (slippage protection). */
+  outConstraint: bigint
+  /** Optional price limit (ln implied APY). */
+  lnImpliedApyLimit?: number
+}
+
+/** Sell PT for SY on the CLMM. */
+export interface ClmmSellPtInstruction extends ClmmInstructionBase {
+  action: ClmmAction.SELL_PT
+  /** Amount of PT to sell. */
+  amountPt: bigint
+  /** Minimum SY to receive (slippage protection). */
+  outConstraint: bigint
+  /** Optional price limit (ln implied APY). */
+  lnImpliedApyLimit?: number
+}
+
+/** Buy YT with SY on the CLMM. */
+export interface ClmmBuyYtInstruction extends ClmmInstructionBase {
+  action: ClmmAction.BUY_YT
+  /** Minimum amount of YT to receive. */
+  ytOut: bigint
+  /** Maximum amount of SY to spend. */
+  maxSyIn: bigint
+  /** Optional price limit (ln implied APY). */
+  lnImpliedApyLimit?: number
+}
+
+/** Sell YT for SY on the CLMM. */
+export interface ClmmSellYtInstruction extends ClmmInstructionBase {
+  action: ClmmAction.SELL_YT
+  /** Amount of YT to sell. */
+  ytIn: bigint
+  /** Minimum SY to receive (slippage protection). */
+  minSyOut: bigint
+  /** Optional price limit (ln implied APY). */
+  lnImpliedApyLimit?: number
+}
+
+/** Claim farm emissions from an LP position. */
+export interface ClmmClaimFarmEmissionInstruction extends ClmmInstructionBase {
+  action: ClmmAction.CLAIM_FARM_EMISSION
+  /** The LpPosition account to claim from. */
+  lpPosition: PublicKey
+  /** Index of the farm to claim from. */
+  farmIndex: number
+}
+
+/** A single CLMM instruction. */
+export type ClmmInstruction =
+  | ClmmDepositLiquidityInstruction
+  | ClmmAddLiquidityInstruction
+  | ClmmWithdrawLiquidityInstruction
+  | ClmmTradePtInstruction
+  | ClmmBuyPtInstruction
+  | ClmmSellPtInstruction
+  | ClmmBuyYtInstruction
+  | ClmmSellYtInstruction
+  | ClmmClaimFarmEmissionInstruction
+
+/** A single vault instruction — pass an array of these to `createVaultSyncTransaction`. */
+export type VaultInstruction =
+  | MarketInstruction
+  | ReserveInstruction
+  | OrderbookInstruction
+  | CoreInstruction
+  | SyInstruction
+  | TitanSwapInstruction
+  | ClmmInstruction
+  | LoopscaleInstruction
+
+// ============================================================================
+// Kamino Action Builders
+// ============================================================================
+
+/**
+ * Builder for Kamino Lending (KLend) vault action descriptors.
+ *
+ * Each method returns a `VaultInstruction` that describes what to do.
+ * Pass these to `createVaultSyncTransaction` which resolves them into
+ * raw Solana instructions, handles refresh ordering, and wraps them
+ * in a Squads sync transaction.
+ *
+ * @example
+ * ```ts
+ * import { kaminoAction, KaminoMarket, createVaultSyncTransaction } from "@exponent-labs/exponent-sdk"
+ *
+ * const syncTx = await createVaultSyncTransaction({
+ *   instructions: [
+ *     kaminoAction.initUserMetadata(KaminoMarket.MAIN),
+ *     kaminoAction.initObligation(KaminoMarket.MAIN),
+ *     kaminoAction.deposit(KaminoMarket.MAIN, "USDC", new BN(1_000_000)),
+ *   ],
+ *   owner: vaultPda,
+ *   connection,
+ *   policyPda,
+ *   vaultPda,
+ *   signer: walletPublicKey,
+ * })
+ * ```
+ */
+export const kaminoAction = {
+  /**
+   * Initialize Kamino user metadata for a market.
+   * No-ops if the account already exists on-chain.
+   * @param market - The Kamino lending market
+   */
+  initUserMetadata(market: KaminoMarket): MarketInstruction {
+    return { action: VaultAction.INIT_USER_METADATA, market }
+  },
+
+  /**
+   * Initialize a Kamino obligation for a market.
+   * No-ops if the account already exists on-chain.
+   * @param market - The Kamino lending market
+   */
+  initObligation(market: KaminoMarket): MarketInstruction {
+    return { action: VaultAction.INIT_OBLIGATION, market }
+  },
+
+  /**
+   * Deposit collateral into a Kamino reserve.
+   * Automatically prepends refreshReserve + refreshObligation instructions.
+   * @param market - The Kamino lending market
+   * @param asset - The reserve asset (e.g. "USDC", "SOL")
+   * @param amount - Amount in the asset's native units
+   */
+  deposit<M extends KaminoMarket>(market: M, asset: keyof KaminoReserves[M], amount: BN): ReserveInstruction {
+    return { action: VaultAction.DEPOSIT, market, asset: asset as string, amount }
+  },
+
+  /**
+   * Withdraw collateral from a Kamino reserve.
+   * @param market - The Kamino lending market
+   * @param asset - The reserve asset (e.g. "USDC", "SOL")
+   * @param amount - Amount in the asset's native units
+   */
+  withdraw<M extends KaminoMarket>(market: M, asset: keyof KaminoReserves[M], amount: BN): ReserveInstruction {
+    return { action: VaultAction.WITHDRAW, market, asset: asset as string, amount }
+  },
+
+  /**
+   * Borrow from a Kamino reserve.
+   * @param market - The Kamino lending market
+   * @param asset - The reserve asset (e.g. "USDC", "SOL")
+   * @param amount - Amount in the asset's native units
+   */
+  borrow<M extends KaminoMarket>(market: M, asset: keyof KaminoReserves[M], amount: BN): ReserveInstruction {
+    return { action: VaultAction.BORROW, market, asset: asset as string, amount }
+  },
+
+  /**
+   * Repay a borrow on a Kamino reserve.
+   * @param market - The Kamino lending market
+   * @param asset - The reserve asset (e.g. "USDC", "SOL")
+   * @param amount - Amount in the asset's native units
+   */
+  repay<M extends KaminoMarket>(market: M, asset: keyof KaminoReserves[M], amount: BN): ReserveInstruction {
+    return { action: VaultAction.REPAY, market, asset: asset as string, amount }
+  },
+}
+
+// ============================================================================
+// Sync Transaction Builder
+// ============================================================================
+
+/**
+ * Result of building a vault sync transaction.
+ *
+ * Refresh instructions (refreshReserve, refreshObligation, refreshFarms) are
+ * permissionless and must be sent as top-level instructions — KLend's
+ * `check_refresh` validates them by introspecting the instruction sysvar,
+ * which only contains top-level instructions. Instructions that require the
+ * Squads vault signature (init, deposit, withdraw, etc.) go inside the sync
+ * transaction.
+ *
+ * `check_refresh` requires farm refresh instructions both BEFORE and AFTER
+ * the deposit instruction. Send as:
+ * `[...setupInstructions, ...preInstructions, instruction, ...postInstructions]`
+ */
+export interface VaultSyncTransactionResult {
+  /** Setup instructions that must run before any refresh/sync instructions */
+  setupInstructions: TransactionInstruction[]
+  /** Permissionless instructions that must be top-level before the sync tx */
+  preInstructions: TransactionInstruction[]
+  /** The Squads sync transaction instruction (wraps vault-signed instructions) */
+  instruction: TransactionInstruction
+  /** Permissionless instructions that must be top-level after the sync tx (farm refreshes) */
+  postInstructions: TransactionInstruction[]
+  /** Extra signers required by the transaction (e.g., new LP position keypair from CLMM deposit). */
+  signers: web3.Signer[]
+  /** ALT addresses that should be loaded and included in the versioned transaction's lookup tables. */
+  addressLookupTableAddresses: PublicKey[]
+}
+
+/**
+ * Build vault instructions and wrap them in a Squads sync transaction.
+ *
+ * Takes high-level `VaultInstruction` descriptors (built with `kamino.*`),
+ * resolves them to raw Solana instructions, then separates them:
+ * - Permissionless refresh instructions → `preInstructions` (top-level)
+ * - Vault-signed instructions → `instruction` (Squads sync transaction)
+ *
+ * KLend's `check_refresh` requires refreshReserve to be a top-level instruction
+ * so it can be found via the instruction sysvar.
+ *
+ * @returns `{ setupInstructions, preInstructions, instruction, postInstructions, signers, addressLookupTableAddresses }`
+ *
+ * @example
+ * ```ts
+ * const { setupInstructions, preInstructions, instruction, postInstructions, signers, addressLookupTableAddresses } = await createVaultSyncTransaction({
+ *   instructions: [
+ *     kamino.initUserMetadata(KaminoMarket.MAIN),
+ *     kamino.initObligation(KaminoMarket.MAIN),
+ *     kamino.deposit(KaminoMarket.MAIN, "USDC", new BN(1_000_000)),
+ *   ],
+ *   owner: vaultPda,
+ *   connection,
+ *   policyPda,
+ *   vaultPda,
+ *   signer: wallet.publicKey,
+ *   vaultAddress: VAULT_ADDRESS,
+ * })
+ * // Send: [...setupInstructions, ...preInstructions, instruction, ...postInstructions]
+ * ```
+ */
+export async function createVaultSyncTransaction({
+  instructions,
+  owner,
+  connection,
+  policyPda,
+  vaultPda,
+  signer,
+  accountIndex = 0,
+  constraintIndices,
+  vaultAddress,
+  leadingAccounts,
+  preHookAccounts,
+  postHookAccounts,
+  squadsProgram = SQUADS_PROGRAM_ID,
+}: {
+  instructions: VaultInstruction[]
+  owner: PublicKey
+  connection: Connection
+  policyPda?: PublicKey
+  vaultPda: PublicKey
+  signer: PublicKey
+  accountIndex?: number
+  constraintIndices?: number[]
+  /** ExponentStrategyVault PDA — used to auto-resolve hook accounts from the on-chain policy */
+  vaultAddress?: PublicKey
+  leadingAccounts?: PublicKey[] | AccountMeta[]
+  preHookAccounts?: PublicKey[] | AccountMeta[]
+  postHookAccounts?: PublicKey[] | AccountMeta[]
+  squadsProgram?: PublicKey
+}): Promise<VaultSyncTransactionResult> {
+  const { setupInstructions, syncInstructions, preInstructions, postInstructions, signers, addressLookupTableAddresses } = await buildVaultInstructions(
+    instructions,
+    owner,
+    connection,
+    signer,
+    policyPda,
+    vaultPda,
+    accountIndex,
+    vaultAddress,
+    leadingAccounts,
+    preHookAccounts,
+    postHookAccounts,
+    squadsProgram,
+  )
+
+  let resolvedPolicyPda = policyPda
+  let resolvedConstraintIndices = constraintIndices
+  if (!resolvedPolicyPda) {
+    if (!vaultAddress) {
+      throw new Error("vaultAddress is required when policyPda is not provided")
+    }
+    const match = await resolvePolicyMatchForVault(connection, vaultAddress, signer, syncInstructions)
+    resolvedPolicyPda = match.policyPda
+    resolvedConstraintIndices ??= match.constraintIndices
+  }
+
+  // Auto-resolve constraint indices when not explicitly provided
+  resolvedConstraintIndices ??= await resolveConstraintIndices(
+    connection,
+    resolvedPolicyPda,
+    syncInstructions,
+  )
+
+  // Auto-resolve policy prefix and hook accounts when not explicitly provided
+  let resolvedLeadingAccounts = leadingAccounts
+  let resolvedPreHookAccounts = preHookAccounts
+  let resolvedPostHookAccounts = postHookAccounts
+  if (vaultAddress && (!leadingAccounts || !preHookAccounts || !postHookAccounts)) {
+    const hooks = await resolveHookAccounts(connection, resolvedPolicyPda, vaultAddress, signer)
+    resolvedLeadingAccounts ??= hooks.leadingAccounts
+    resolvedPreHookAccounts ??= hooks.preHookAccounts
+    resolvedPostHookAccounts ??= hooks.postHookAccounts
+  }
+
+  const instruction = wrapInstructionsInSyncTransaction({
+    policyPda: resolvedPolicyPda,
+    vaultPda,
+    signer,
+    instructions: syncInstructions,
+    squadsProgram,
+    accountIndex,
+    constraintIndices: resolvedConstraintIndices,
+    leadingAccounts: resolvedLeadingAccounts,
+    preHookAccounts: resolvedPreHookAccounts,
+    postHookAccounts: resolvedPostHookAccounts,
+  })
+
+  return { setupInstructions, preInstructions, instruction, postInstructions, signers, addressLookupTableAddresses }
+}
+
+// ============================================================================
+// Internal: Instruction Assembly
+// ============================================================================
+
+/** KLend farm modes — collateral for deposit/withdraw, debt for borrow/repay. */
+const FARM_COLLATERAL = 0
+const FARM_DEBT = 1
+
+/** Accumulated instruction buckets passed through action builders. */
+interface InstructionBuckets {
+  setupInstructions: TransactionInstruction[]
+  syncInstructions: TransactionInstruction[]
+  preInstructions: TransactionInstruction[]
+  postInstructions: TransactionInstruction[]
+  signers: web3.Signer[]
+  addressLookupTableAddresses: PublicKey[]
+}
+
+function isOrderbookInstruction(ix: VaultInstruction): ix is OrderbookInstruction {
+  return Object.values(OrderbookAction).includes(ix.action as OrderbookAction)
+}
+
+function isCoreInstruction(ix: VaultInstruction): ix is CoreInstruction {
+  return Object.values(CoreAction).includes(ix.action as CoreAction)
+}
+
+function isSyInstruction(ix: VaultInstruction): ix is SyInstruction {
+  return Object.values(SyAction).includes(ix.action as SyAction)
+}
+
+function isTitanInstruction(ix: VaultInstruction): ix is TitanSwapInstruction {
+  return Object.values(TitanAction).includes(ix.action as TitanAction)
+}
+
+function isClmmInstruction(ix: VaultInstruction): ix is ClmmInstruction {
+  return Object.values(ClmmAction).includes(ix.action as ClmmAction)
+}
+
+function isLoopscaleInstruction(ix: VaultInstruction): ix is LoopscaleInstruction {
+  return Object.values(LoopscaleAction).includes(ix.action as LoopscaleAction)
+}
+
+/** Cache for loaded vaults to avoid redundant fetches */
+const vaultCache = new Map<string, Vault>()
+
+const TITAN_INPUT_MINT_ACCOUNT_INDEX = 2
+const TITAN_INPUT_TOKEN_ACCOUNT_INDEX = 3
+const TITAN_OUTPUT_MINT_ACCOUNT_INDEX = 4
+const TITAN_OUTPUT_TOKEN_ACCOUNT_INDEX = 5
+const TITAN_INPUT_TOKEN_PROGRAM_ACCOUNT_INDEX = 6
+const TITAN_OUTPUT_TOKEN_PROGRAM_ACCOUNT_INDEX = 7
+const YIELD_POSITION_BASE_SIZE = 124
+const YIELD_POSITION_TRACKER_SIZE = 40
+
+type SimplePriceLookup = {
+  priceId: bigint
+  price: Decimal
+}
+
+type StrategySetupState = {
+  strategyVault: StrategyVault
+  prices: ExponentPrices
+  nextStrategyPositionIndex: number
+  trackedOrderbooks: Set<string>
+  trackedYieldVaults: Set<string>
+  tokenEntryAccountByMint: Map<string, string>
+  tokenPositionIndexByMint: Map<string, number>
+  trackedTokenAccounts: Set<string>
+  existingAccounts: Map<string, boolean>
+}
+
+type StrategySetupContext = {
+  connection: Connection
+  env: Environment
+  owner: PublicKey
+  signer: PublicKey
+  vaultAddress?: PublicKey
+  policyPda?: PublicKey
+  vaultPda?: PublicKey
+  accountIndex: number
+  squadsProgram: PublicKey
+  leadingAccounts?: PublicKey[] | AccountMeta[]
+  preHookAccounts?: PublicKey[] | AccountMeta[]
+  postHookAccounts?: PublicKey[] | AccountMeta[]
+  statePromise?: Promise<StrategySetupState | null>
+}
+
+function createStrategySetupContext({
+  connection,
+  env,
+  owner,
+  signer,
+  vaultAddress,
+  policyPda,
+  vaultPda,
+  accountIndex = 0,
+  squadsProgram = SQUADS_PROGRAM_ID,
+  leadingAccounts,
+  preHookAccounts,
+  postHookAccounts,
+}: {
+  connection: Connection
+  env: Environment
+  owner: PublicKey
+  signer: PublicKey
+  vaultAddress?: PublicKey
+  policyPda?: PublicKey
+  vaultPda?: PublicKey
+  accountIndex?: number
+  squadsProgram?: PublicKey
+  leadingAccounts?: PublicKey[] | AccountMeta[]
+  preHookAccounts?: PublicKey[] | AccountMeta[]
+  postHookAccounts?: PublicKey[] | AccountMeta[]
+}): StrategySetupContext {
+  return {
+    connection,
+    env,
+    owner,
+    signer,
+    vaultAddress,
+    policyPda,
+    vaultPda,
+    accountIndex,
+    squadsProgram,
+    leadingAccounts,
+    preHookAccounts,
+    postHookAccounts,
+  }
+}
+
+async function loadStrategySetupState(context: StrategySetupContext): Promise<StrategySetupState | null> {
+  if (!context.vaultAddress) {
+    return null
+  }
+
+  if (!context.statePromise) {
+    context.statePromise = (async () => {
+      const strategyVault = await StrategyVault.load({
+        env: context.env,
+        connection: context.connection,
+        address: context.vaultAddress!,
+      })
+      const prices = await strategyVault.fetcher.fetchExponentPrices()
+
+      const trackedOrderbooks = new Set<string>()
+      const trackedYieldVaults = new Set<string>()
+      const tokenEntryAccountByMint = new Map<string, string>()
+      const tokenPositionIndexByMint = new Map<string, number>()
+      const trackedTokenAccounts = new Set<string>()
+
+      for (const entry of strategyVault.state.tokenEntries) {
+        tokenEntryAccountByMint.set(entry.mint.toBase58(), entry.tokenSquadsAccount.toBase58())
+        trackedTokenAccounts.add(entry.tokenSquadsAccount.toBase58())
+      }
+
+      for (const [index, position] of strategyVault.state.strategyPositions.entries()) {
+        if ("orderbook" in position && position.orderbook?.[0]) {
+          trackedOrderbooks.add(position.orderbook[0].orderbook.toBase58())
+          continue
+        }
+        if ("yieldPosition" in position && position.yieldPosition?.[0]) {
+          trackedYieldVaults.add(position.yieldPosition[0].vault.toBase58())
+          continue
+        }
+        if ("tokenAccount" in position && position.tokenAccount?.[0]) {
+          const entry = position.tokenAccount[0]
+          tokenPositionIndexByMint.set(entry.tokenMint.toBase58(), index)
+          for (const balance of entry.balances) {
+            trackedTokenAccounts.add(balance.tokenAccount.toBase58())
+          }
+        }
+      }
+
+      return {
+        strategyVault,
+        prices,
+        nextStrategyPositionIndex: strategyVault.state.strategyPositions.length,
+        trackedOrderbooks,
+        trackedYieldVaults,
+        tokenEntryAccountByMint,
+        tokenPositionIndexByMint,
+        trackedTokenAccounts,
+        existingAccounts: new Map<string, boolean>(),
+      }
+    })()
+  }
+
+  return context.statePromise
+}
+
+function findSimplePrice(
+  prices: ExponentPrices,
+  priceMint: PublicKey,
+  underlyingMint: PublicKey,
+): SimplePriceLookup | null {
+  for (const entry of prices.prices) {
+    if (!entry) continue
+    if (!entry.priceMint.equals(priceMint) || !entry.underlyingMint.equals(underlyingMint)) {
+      continue
+    }
+
+    return {
+      priceId: entry.priceId,
+      price: exponentPriceToDecimal(entry),
+    }
+  }
+
+  return null
+}
+
+function exponentPriceToDecimal(entry: ExponentPrice): Decimal {
+  const raw = entry.price[0]
+  if (!Array.isArray(raw)) {
+    throw new Error(`Invalid Exponent price format for ${entry.priceId.toString()}`)
+  }
+  return new Decimal(bigintU256ToString(raw.map((value) => BigInt(value.toString()))))
+}
+
+async function accountExists(
+  state: StrategySetupState,
+  connection: Connection,
+  address: PublicKey,
+): Promise<boolean> {
+  const cacheKey = address.toBase58()
+  const cached = state.existingAccounts.get(cacheKey)
+  if (cached !== undefined) {
+    return cached
+  }
+
+  const exists = (await connection.getAccountInfo(address)) !== null
+  state.existingAccounts.set(cacheKey, exists)
+  return exists
+}
+
+async function maybeCreateOwnedAtaSetupInstruction({
+  state,
+  connection,
+  payer,
+  owner,
+  mint,
+  tokenProgram,
+  tokenAccount,
+}: {
+  state: StrategySetupState
+  connection: Connection
+  payer: PublicKey
+  owner: PublicKey
+  mint: PublicKey
+  tokenProgram: PublicKey
+  tokenAccount: PublicKey
+}): Promise<TransactionInstruction | null> {
+  if (await accountExists(state, connection, tokenAccount)) {
+    return null
+  }
+
+  const expectedAta = getAssociatedTokenAddressSync(mint, owner, true, tokenProgram)
+  if (!expectedAta.equals(tokenAccount)) {
+    return null
+  }
+
+  state.existingAccounts.set(tokenAccount.toBase58(), true)
+  return createAssociatedTokenAccountIdempotentInstruction(payer, tokenAccount, owner, mint, tokenProgram)
+}
+
+async function ensureOrderbookPositionSetup(
+  orderbook: Orderbook,
+  buckets: InstructionBuckets,
+  setupContext: StrategySetupContext,
+) {
+  const state = await loadStrategySetupState(setupContext)
+  if (!state) {
+    return
+  }
+
+  const orderbookKey = orderbook.selfAddress.toBase58()
+  if (state.trackedOrderbooks.has(orderbookKey)) {
+    return
+  }
+
+  const ptPrice = findSimplePrice(
+    state.prices,
+    orderbook.mintPt,
+    state.strategyVault.state.underlyingMint,
+  )
+  if (!ptPrice) {
+    throw new Error(
+      `Missing Exponent price for orderbook setup (${orderbook.selfAddress.toBase58()})`,
+    )
+  }
+
+  buckets.setupInstructions.push(
+    state.strategyVault.ixWrapperManageVaultSettings({
+      manager: setupContext.signer,
+      actions: [
+        exponentVaults.vaultSettingsAction("AddOrderbookEntry", [{
+          orderbook: orderbook.selfAddress,
+          // Legacy field retained for layout compatibility. Order ownership is
+          // derived from live orderbook state during AUM calculation.
+          userEscrowIdx: 0,
+          mint: orderbook.vault.mintSy,
+          offerIdxVec: [],
+          priceIdPt: exponentVaults.priceId("Simple", { priceId: ptPrice.priceId }),
+          baseMint: state.strategyVault.state.underlyingMint,
+        }]),
+      ],
+      remainingAccounts: [
+        { pubkey: orderbook.selfAddress, isSigner: false, isWritable: false },
+        { pubkey: orderbook.state.vault, isSigner: false, isWritable: false },
+      ],
+    }),
+  )
+
+  state.trackedOrderbooks.add(orderbookKey)
+  state.nextStrategyPositionIndex += 1
+}
+
+async function ensureYieldPositionSetup(
+  coreVault: Vault,
+  buckets: InstructionBuckets,
+  setupContext: StrategySetupContext,
+) {
+  const state = await loadStrategySetupState(setupContext)
+  if (!state) {
+    return
+  }
+
+  const coreVaultKey = coreVault.selfAddress.toBase58()
+  if (state.trackedYieldVaults.has(coreVaultKey)) {
+    return
+  }
+
+  const ptPrice = findSimplePrice(
+    state.prices,
+    coreVault.mintPt,
+    state.strategyVault.state.underlyingMint,
+  )
+  if (!ptPrice) {
+    throw new Error(`Missing Exponent price for core vault setup (${coreVault.selfAddress.toBase58()})`)
+  }
+
+  const yieldPosition = coreVault.pda.yieldPosition({ owner: setupContext.owner, vault: coreVault.selfAddress })
+  if (!(await accountExists(state, setupContext.connection, yieldPosition))) {
+    const requiredLamports = await setupContext.connection.getMinimumBalanceForRentExemption(
+      YIELD_POSITION_BASE_SIZE + (coreVault.state.emissions.length * YIELD_POSITION_TRACKER_SIZE),
+    )
+    const ownerLamports = await setupContext.connection.getBalance(setupContext.owner)
+    if (ownerLamports < requiredLamports) {
+      buckets.setupInstructions.push(
+        SystemProgram.transfer({
+          fromPubkey: setupContext.signer,
+          toPubkey: setupContext.owner,
+          lamports: requiredLamports - ownerLamports,
+        }),
+      )
+    }
+
+    const initializeYieldPositionIx = coreVault.ixInitializeYieldPosition({ owner: setupContext.owner })
+    try {
+      buckets.setupInstructions.push(
+        await wrapVaultSignedSetupInstruction({
+          instruction: initializeYieldPositionIx,
+          setupContext,
+        }),
+      )
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error)
+      throw new Error(
+        `Failed to auto-initialize yield position ${yieldPosition.toBase58()} for ${coreVault.selfAddress.toBase58()}: ${reason}`,
+      )
+    }
+    state.existingAccounts.set(yieldPosition.toBase58(), true)
+  }
+
+  buckets.setupInstructions.push(
+    state.strategyVault.ixWrapperManageVaultSettings({
+      manager: setupContext.signer,
+      actions: [
+        exponentVaults.vaultSettingsAction("AddYieldPositionEntry", {
+          yieldPosition,
+          vault: coreVault.selfAddress,
+          priceIdPt: exponentVaults.priceId("Simple", { priceId: ptPrice.priceId }),
+        }),
+      ],
+      remainingAccounts: [
+        { pubkey: coreVault.selfAddress, isSigner: false, isWritable: false },
+        { pubkey: yieldPosition, isSigner: false, isWritable: false },
+      ],
+    }),
+  )
+
+  state.trackedYieldVaults.add(coreVaultKey)
+  state.nextStrategyPositionIndex += 1
+}
+
+async function wrapVaultSignedSetupInstruction({
+  instruction,
+  setupContext,
+}: {
+  instruction: TransactionInstruction
+  setupContext: StrategySetupContext
+}): Promise<TransactionInstruction> {
+  if (!setupContext.vaultPda) {
+    throw new Error("vaultPda is required to auto-wrap setup instructions")
+  }
+
+  let resolvedPolicyPda = setupContext.policyPda
+  let constraintIndices: number[]
+  if (!resolvedPolicyPda) {
+    if (!setupContext.vaultAddress) {
+      throw new Error("vaultAddress is required when policyPda is not provided")
+    }
+    const match = await resolvePolicyMatchForVault(
+      setupContext.connection,
+      setupContext.vaultAddress,
+      setupContext.signer,
+      [instruction],
+    )
+    resolvedPolicyPda = match.policyPda
+    constraintIndices = match.constraintIndices
+  } else {
+    constraintIndices = await resolveConstraintIndices(
+      setupContext.connection,
+      resolvedPolicyPda,
+      [instruction],
+    )
+  }
+
+  let resolvedLeadingAccounts = setupContext.leadingAccounts
+  let resolvedPreHookAccounts = setupContext.preHookAccounts
+  let resolvedPostHookAccounts = setupContext.postHookAccounts
+  if (
+    setupContext.vaultAddress
+    && (!resolvedLeadingAccounts || !resolvedPreHookAccounts || !resolvedPostHookAccounts)
+  ) {
+    const hooks = await resolveHookAccounts(
+      setupContext.connection,
+      resolvedPolicyPda,
+      setupContext.vaultAddress,
+      setupContext.signer,
+    )
+    resolvedLeadingAccounts ??= hooks.leadingAccounts
+    resolvedPreHookAccounts ??= hooks.preHookAccounts
+    resolvedPostHookAccounts ??= hooks.postHookAccounts
+  }
+
+  return wrapInstructionsInSyncTransaction({
+    policyPda: resolvedPolicyPda,
+    vaultPda: setupContext.vaultPda,
+    signer: setupContext.signer,
+    instructions: [instruction],
+    squadsProgram: setupContext.squadsProgram,
+    accountIndex: setupContext.accountIndex,
+    constraintIndices,
+    leadingAccounts: resolvedLeadingAccounts,
+    preHookAccounts: resolvedPreHookAccounts,
+    postHookAccounts: resolvedPostHookAccounts,
+  })
+}
+
+async function ensureTrackedTokenAccountSetup({
+  tokenMint,
+  tokenAccount,
+  tokenProgram,
+  buckets,
+  setupContext,
+}: {
+  tokenMint: PublicKey
+  tokenAccount: PublicKey
+  tokenProgram: PublicKey
+  buckets: InstructionBuckets
+  setupContext: StrategySetupContext
+}) {
+  const state = await loadStrategySetupState(setupContext)
+  if (!state) {
+    return
+  }
+
+  const tokenMintKey = tokenMint.toBase58()
+  const tokenAccountKey = tokenAccount.toBase58()
+  const tokenEntryAccount = state.tokenEntryAccountByMint.get(tokenMintKey)
+  if (tokenEntryAccount) {
+    if (tokenEntryAccount !== tokenAccountKey) {
+      throw new Error(
+        `Mint ${tokenMintKey} is tracked as a token entry on ${tokenEntryAccount}; use that account instead of ${tokenAccountKey}`,
+      )
+    }
+    state.trackedTokenAccounts.add(tokenAccountKey)
+    return
+  }
+
+  if (state.trackedTokenAccounts.has(tokenAccountKey)) {
+    return
+  }
+
+  const price = findSimplePrice(
+    state.prices,
+    tokenMint,
+    state.strategyVault.state.underlyingMint,
+  )
+  if (!price) {
+    throw new Error(`Missing Exponent price for token position setup (${tokenMint.toBase58()})`)
+  }
+
+  const maybeAtaIx = await maybeCreateOwnedAtaSetupInstruction({
+    state,
+    connection: setupContext.connection,
+    payer: setupContext.signer,
+    owner: setupContext.owner,
+    mint: tokenMint,
+    tokenProgram,
+    tokenAccount,
+  })
+  if (maybeAtaIx) {
+    buckets.setupInstructions.push(maybeAtaIx)
+  }
+
+  const positionIndex = state.tokenPositionIndexByMint.get(tokenMintKey)
+  if (positionIndex === undefined) {
+    buckets.setupInstructions.push(
+      state.strategyVault.ixWrapperManageVaultSettings({
+        manager: setupContext.signer,
+        actions: [
+          exponentVaults.vaultSettingsAction("AddTokenAccountEntry", [{
+            tokenMint,
+            balances: [{
+              tokenAccount,
+              mint: tokenMint,
+              priceId: exponentVaults.priceId("Simple", { priceId: price.priceId }),
+            }],
+          }]),
+        ],
+        remainingAccounts: [
+          { pubkey: tokenAccount, isSigner: false, isWritable: false },
+        ],
+      }),
+    )
+    state.tokenPositionIndexByMint.set(tokenMintKey, state.nextStrategyPositionIndex)
+    state.nextStrategyPositionIndex += 1
+  } else {
+    buckets.setupInstructions.push(
+      state.strategyVault.ixWrapperManagerUpdatePosition({
+        manager: setupContext.signer,
+        update: {
+          __kind: "AddTokenAccountBalance",
+          tokenMint,
+          balance: {
+            tokenAccount,
+            mint: tokenMint,
+            priceId: exponentVaults.priceId("Simple", { priceId: price.priceId }),
+          },
+        },
+        remainingAccounts: [
+          { pubkey: tokenAccount, isSigner: false, isWritable: false },
+        ],
+      }),
+    )
+  }
+
+  state.trackedTokenAccounts.add(tokenAccountKey)
+}
+
+async function buildVaultInstructions(
+  instructions: VaultInstruction[],
+  owner: PublicKey,
+  connection: Connection,
+  signer: PublicKey,
+  policyPda: PublicKey,
+  vaultPda: PublicKey,
+  accountIndex: number,
+  vaultAddress?: PublicKey,
+  leadingAccounts?: PublicKey[] | AccountMeta[],
+  preHookAccounts?: PublicKey[] | AccountMeta[],
+  postHookAccounts?: PublicKey[] | AccountMeta[],
+  squadsProgram: PublicKey = SQUADS_PROGRAM_ID,
+): Promise<InstructionBuckets> {
+  const buckets: InstructionBuckets = {
+    setupInstructions: [],
+    syncInstructions: [],
+    preInstructions: [],
+    postInstructions: [],
+    signers: [],
+    addressLookupTableAddresses: [],
+  }
+  const setupContext = createStrategySetupContext({
+    connection,
+    env: LOCAL_ENV,
+    owner,
+    signer,
+    vaultAddress,
+    policyPda,
+    vaultPda,
+    accountIndex,
+    squadsProgram,
+    leadingAccounts,
+    preHookAccounts,
+    postHookAccounts,
+  })
+
+  for (const ix of instructions) {
+    if (isOrderbookInstruction(ix)) {
+      await buildOrderbookInstruction(ix, owner, connection, buckets, setupContext)
+      continue
+    }
+
+    if (isCoreInstruction(ix)) {
+      await buildCoreInstruction(ix, owner, connection, buckets, setupContext)
+      continue
+    }
+
+    if (isSyInstruction(ix)) {
+      await buildSyInstruction(ix, owner, connection, buckets, setupContext)
+      continue
+    }
+
+    if (isTitanInstruction(ix)) {
+      await buildTitanInstruction(ix, buckets, setupContext)
+      continue
+    }
+
+    if (isLoopscaleInstruction(ix)) {
+      await buildLoopscaleInstruction(ix, buckets, setupContext)
+      continue
+    }
+
+    if (isClmmInstruction(ix)) {
+      await buildClmmInstruction(ix, owner, connection, buckets, setupContext)
+      continue
+    }
+
+    switch (ix.action) {
+      case VaultAction.INIT_USER_METADATA:
+        await buildInitUserMetadata(owner, connection, buckets)
+        break
+      case VaultAction.INIT_OBLIGATION:
+        await buildInitObligation(ix, owner, connection, buckets)
+        break
+      case VaultAction.DEPOSIT:
+        await buildDeposit(ix, owner, connection, signer, buckets)
+        break
+      case VaultAction.WITHDRAW:
+        await buildWithdraw(ix, owner, connection, signer, buckets)
+        break
+      case VaultAction.BORROW:
+        await buildBorrow(ix, owner, connection, signer, buckets)
+        break
+      case VaultAction.REPAY:
+        await buildRepay(ix, owner, connection, signer, buckets)
+        break
+    }
+  }
+
+  return buckets
+}
+
+async function buildTitanInstruction(
+  ix: TitanSwapInstruction,
+  buckets: InstructionBuckets,
+  setupContext: StrategySetupContext,
+): Promise<void> {
+  const inputMint = ix.instruction.keys[TITAN_INPUT_MINT_ACCOUNT_INDEX]?.pubkey
+  const inputTokenAccount = ix.instruction.keys[TITAN_INPUT_TOKEN_ACCOUNT_INDEX]?.pubkey
+  const outputMint = ix.instruction.keys[TITAN_OUTPUT_MINT_ACCOUNT_INDEX]?.pubkey
+  const outputTokenAccount = ix.instruction.keys[TITAN_OUTPUT_TOKEN_ACCOUNT_INDEX]?.pubkey
+  const inputTokenProgram = ix.instruction.keys[TITAN_INPUT_TOKEN_PROGRAM_ACCOUNT_INDEX]?.pubkey
+  const outputTokenProgram = ix.instruction.keys[TITAN_OUTPUT_TOKEN_PROGRAM_ACCOUNT_INDEX]?.pubkey
+
+  if (
+    !inputMint
+    || !inputTokenAccount
+    || !outputMint
+    || !outputTokenAccount
+    || !inputTokenProgram
+    || !outputTokenProgram
+  ) {
+    throw new Error("Titan SwapRouteV2 instruction is missing expected token accounts")
+  }
+
+  await ensureTrackedTokenAccountSetup({
+    tokenMint: inputMint,
+    tokenAccount: inputTokenAccount,
+    tokenProgram: inputTokenProgram,
+    buckets,
+    setupContext,
+  })
+  await ensureTrackedTokenAccountSetup({
+    tokenMint: outputMint,
+    tokenAccount: outputTokenAccount,
+    tokenProgram: outputTokenProgram,
+    buckets,
+    setupContext,
+  })
+
+  buckets.syncInstructions.push(ix.instruction)
+}
+
+// Loopscale account indices per instruction (from the Loopscale IDL)
+const LOOPSCALE_DEPOSIT_COLLATERAL_MINT_INDEX = 6
+const LOOPSCALE_DEPOSIT_COLLATERAL_BORROWER_TA_INDEX = 4
+const LOOPSCALE_DEPOSIT_COLLATERAL_TOKEN_PROGRAM_INDEX = 9
+const LOOPSCALE_BORROW_PRINCIPAL_MINT_INDEX = 6
+const LOOPSCALE_BORROW_PRINCIPAL_BORROWER_TA_INDEX = 7
+const LOOPSCALE_BORROW_PRINCIPAL_TOKEN_PROGRAM_INDEX = 10
+const LOOPSCALE_REPAY_PRINCIPAL_MINT_INDEX = 6
+const LOOPSCALE_REPAY_PRINCIPAL_BORROWER_TA_INDEX = 7
+const LOOPSCALE_REPAY_PRINCIPAL_TOKEN_PROGRAM_INDEX = 10
+const LOOPSCALE_WITHDRAW_COLLATERAL_MINT_INDEX = 7
+const LOOPSCALE_WITHDRAW_COLLATERAL_BORROWER_TA_INDEX = 4
+const LOOPSCALE_WITHDRAW_COLLATERAL_TOKEN_PROGRAM_INDEX = 8
+const LOOPSCALE_DEPOSIT_STRATEGY_MINT_INDEX = 4
+const LOOPSCALE_DEPOSIT_STRATEGY_LENDER_TA_INDEX = 6
+const LOOPSCALE_DEPOSIT_STRATEGY_TOKEN_PROGRAM_INDEX = 8
+const LOOPSCALE_WITHDRAW_STRATEGY_MINT_INDEX = 4
+const LOOPSCALE_WITHDRAW_STRATEGY_LENDER_TA_INDEX = 6
+const LOOPSCALE_WITHDRAW_STRATEGY_TOKEN_PROGRAM_INDEX = 9
+
+/** Build a single Loopscale instruction (loan or strategy). Extracts token accounts for tracking. */
+async function buildLoopscaleInstruction(
+  ix: LoopscaleInstruction,
+  buckets: InstructionBuckets,
+  setupContext: StrategySetupContext,
+): Promise<void> {
+  switch (ix.action) {
+    case LoopscaleAction.DEPOSIT_COLLATERAL: {
+      const tokenMint = ix.instruction.keys[LOOPSCALE_DEPOSIT_COLLATERAL_MINT_INDEX]?.pubkey
+      const tokenAccount = ix.instruction.keys[LOOPSCALE_DEPOSIT_COLLATERAL_BORROWER_TA_INDEX]?.pubkey
+      const tokenProgram = ix.instruction.keys[LOOPSCALE_DEPOSIT_COLLATERAL_TOKEN_PROGRAM_INDEX]?.pubkey
+      if (!tokenMint || !tokenAccount || !tokenProgram) {
+        throw new Error("Loopscale deposit_collateral instruction is missing expected token accounts")
+      }
+      await ensureTrackedTokenAccountSetup({ tokenMint, tokenAccount, tokenProgram, buckets, setupContext })
+      break
+    }
+    case LoopscaleAction.BORROW_PRINCIPAL: {
+      const tokenMint = ix.instruction.keys[LOOPSCALE_BORROW_PRINCIPAL_MINT_INDEX]?.pubkey
+      const tokenAccount = ix.instruction.keys[LOOPSCALE_BORROW_PRINCIPAL_BORROWER_TA_INDEX]?.pubkey
+      const tokenProgram = ix.instruction.keys[LOOPSCALE_BORROW_PRINCIPAL_TOKEN_PROGRAM_INDEX]?.pubkey
+      if (!tokenMint || !tokenAccount || !tokenProgram) {
+        throw new Error("Loopscale borrow_principal instruction is missing expected token accounts")
+      }
+      await ensureTrackedTokenAccountSetup({ tokenMint, tokenAccount, tokenProgram, buckets, setupContext })
+      break
+    }
+    case LoopscaleAction.REPAY_PRINCIPAL: {
+      const tokenMint = ix.instruction.keys[LOOPSCALE_REPAY_PRINCIPAL_MINT_INDEX]?.pubkey
+      const tokenAccount = ix.instruction.keys[LOOPSCALE_REPAY_PRINCIPAL_BORROWER_TA_INDEX]?.pubkey
+      const tokenProgram = ix.instruction.keys[LOOPSCALE_REPAY_PRINCIPAL_TOKEN_PROGRAM_INDEX]?.pubkey
+      if (!tokenMint || !tokenAccount || !tokenProgram) {
+        throw new Error("Loopscale repay_principal instruction is missing expected token accounts")
+      }
+      await ensureTrackedTokenAccountSetup({ tokenMint, tokenAccount, tokenProgram, buckets, setupContext })
+      break
+    }
+    case LoopscaleAction.WITHDRAW_COLLATERAL: {
+      const tokenMint = ix.instruction.keys[LOOPSCALE_WITHDRAW_COLLATERAL_MINT_INDEX]?.pubkey
+      const tokenAccount = ix.instruction.keys[LOOPSCALE_WITHDRAW_COLLATERAL_BORROWER_TA_INDEX]?.pubkey
+      const tokenProgram = ix.instruction.keys[LOOPSCALE_WITHDRAW_COLLATERAL_TOKEN_PROGRAM_INDEX]?.pubkey
+      if (!tokenMint || !tokenAccount || !tokenProgram) {
+        throw new Error("Loopscale withdraw_collateral instruction is missing expected token accounts")
+      }
+      await ensureTrackedTokenAccountSetup({ tokenMint, tokenAccount, tokenProgram, buckets, setupContext })
+      break
+    }
+    // create_loan, close_loan, and update_weight_matrix have no token accounts to track —
+    // the on-chain hook handles TrackLoopscaleLoan/UntrackLoopscaleLoan mutations.
+    // update_weight_matrix only has 3 accounts (bs_auth, borrower, loan).
+    case LoopscaleAction.DEPOSIT_STRATEGY: {
+      const tokenMint = ix.instruction.keys[LOOPSCALE_DEPOSIT_STRATEGY_MINT_INDEX]?.pubkey
+      const tokenAccount = ix.instruction.keys[LOOPSCALE_DEPOSIT_STRATEGY_LENDER_TA_INDEX]?.pubkey
+      const tokenProgram = ix.instruction.keys[LOOPSCALE_DEPOSIT_STRATEGY_TOKEN_PROGRAM_INDEX]?.pubkey
+      if (!tokenMint || !tokenAccount || !tokenProgram) {
+        throw new Error("Loopscale deposit_strategy instruction is missing expected token accounts")
+      }
+      await ensureTrackedTokenAccountSetup({ tokenMint, tokenAccount, tokenProgram, buckets, setupContext })
+      break
+    }
+    case LoopscaleAction.WITHDRAW_STRATEGY: {
+      const tokenMint = ix.instruction.keys[LOOPSCALE_WITHDRAW_STRATEGY_MINT_INDEX]?.pubkey
+      const tokenAccount = ix.instruction.keys[LOOPSCALE_WITHDRAW_STRATEGY_LENDER_TA_INDEX]?.pubkey
+      const tokenProgram = ix.instruction.keys[LOOPSCALE_WITHDRAW_STRATEGY_TOKEN_PROGRAM_INDEX]?.pubkey
+      if (!tokenMint || !tokenAccount || !tokenProgram) {
+        throw new Error("Loopscale withdraw_strategy instruction is missing expected token accounts")
+      }
+      await ensureTrackedTokenAccountSetup({ tokenMint, tokenAccount, tokenProgram, buckets, setupContext })
+      break
+    }
+    // create_strategy and close_strategy have no token accounts to track
+  }
+
+  buckets.syncInstructions.push(ix.instruction)
+}
+
+/** Build a single orderbook instruction (uses LOCAL_ENV for Orderbook.load) */
+async function buildOrderbookInstruction(
+  ix: OrderbookInstruction,
+  owner: PublicKey,
+  connection: Connection,
+  buckets: InstructionBuckets,
+  setupContext?: StrategySetupContext,
+  env: Environment = LOCAL_ENV,
+): Promise<void> {
+  const cacheKey = ix.orderbook.toBase58()
+  let orderbook = orderbookCache.get(cacheKey)
+  if (!orderbook) {
+    orderbook = await Orderbook.load(env, connection, ix.orderbook)
+    orderbookCache.set(cacheKey, orderbook)
+  }
+
+  switch (ix.action) {
+    case OrderbookAction.POST_OFFER:
+      await buildPostOffer(ix, orderbook, owner, setupContext?.signer ?? owner, buckets, setupContext)
+      break
+    case OrderbookAction.MARKET_OFFER:
+      await buildMarketOffer(ix, orderbook, owner, setupContext?.signer ?? owner, buckets, setupContext)
+      break
+    case OrderbookAction.REMOVE_OFFER:
+      await buildRemoveOffer(ix, orderbook, owner, buckets)
+      break
+    case OrderbookAction.WITHDRAW_FUNDS:
+      await buildWithdrawFunds(ix, orderbook, owner, buckets)
+      break
+  }
+}
+
+// ============================================================================
+// Action Builders (one per VaultAction)
+// ============================================================================
+
+async function buildInitUserMetadata(
+  owner: PublicKey,
+  connection: Connection,
+  { syncInstructions }: InstructionBuckets,
+) {
+  const userMetadata = getKaminoUserMetadata(owner, KAMINO_LENDING_PROGRAM_ID)
+  const userMetadataAccount = await connection.getAccountInfo(userMetadata)
+  if (userMetadataAccount) return
+
+  syncInstructions.push(
+    initUserMetadata(
+      { userLookupTable: PublicKey.default },
+      {
+        owner,
+        feePayer: owner,
+        userMetadata,
+        referrerUserMetadata: KAMINO_LENDING_PROGRAM_ID,
+        rent: SYSVAR_RENT_PUBKEY,
+        systemProgram: SystemProgram.programId,
+      },
+    ),
+  )
+}
+
+async function buildInitObligation(
+  ix: MarketInstruction,
+  owner: PublicKey,
+  connection: Connection,
+  { syncInstructions }: InstructionBuckets,
+) {
+  const lendingMarket = KAMINO_MARKETS[ix.market]
+  const obligation = getKaminoLendObligation(owner, lendingMarket, KAMINO_LENDING_PROGRAM_ID)
+  const userMetadata = getKaminoUserMetadata(owner, KAMINO_LENDING_PROGRAM_ID)
+  const obligationAccount = await connection.getAccountInfo(obligation)
+  if (obligationAccount) return
+
+  syncInstructions.push(
+    initObligation(
+      { args: { tag: 0, id: 0 } },
+      {
+        obligationOwner: owner,
+        feePayer: owner,
+        obligation,
+        lendingMarket,
+        seed1Account: SystemProgram.programId,
+        seed2Account: SystemProgram.programId,
+        ownerUserMetadata: userMetadata,
+        rent: SYSVAR_RENT_PUBKEY,
+        systemProgram: SystemProgram.programId,
+      },
+    ),
+  )
+}
+
+async function buildDeposit(
+  ix: ReserveInstruction,
+  owner: PublicKey,
+  connection: Connection,
+  signer: PublicKey,
+  { setupInstructions, syncInstructions, preInstructions, postInstructions }: InstructionBuckets,
+) {
+  const ctx = await resolveReserveContext(ix, owner, connection)
+  const refreshes = await buildRefreshInstructions({
+    ...ctx, owner, farmMode: FARM_COLLATERAL, signer, connection, needsScopeRefresh: false,
+  })
+
+  const isSOL = ctx.reserveAccount.liquidity.mintPubkey.equals(NATIVE_MINT)
+  const userSourceLiquidity = getAssociatedTokenAddressSync(
+    ctx.reserveAccount.liquidity.mintPubkey, owner, true, ctx.reserveAccount.liquidity.tokenProgram,
+  )
+
+  if (isSOL) {
+    setupInstructions.push(
+      createAssociatedTokenAccountIdempotentInstruction(
+        signer, userSourceLiquidity, owner, NATIVE_MINT, TOKEN_PROGRAM_ID,
+      ),
+    )
+  }
+
+  preInstructions.push(...refreshes.preInstructions)
+  postInstructions.push(...refreshes.postInstructions)
+
+  syncInstructions.push(
+    depositReserveLiquidityAndObligationCollateralV2(
+      { liquidityAmount: ix.amount },
+      {
+        depositAccounts: {
+          owner,
+          obligation: ctx.obligation,
+          lendingMarket: ctx.lendingMarket,
+          lendingMarketAuthority: ctx.lendingMarketAuthority,
+          reserve: ctx.reservePubkey,
+          reserveLiquidityMint: ctx.reserveAccount.liquidity.mintPubkey,
+          reserveLiquiditySupply: ctx.reserveAccount.liquidity.supplyVault,
+          reserveCollateralMint: ctx.reserveAccount.collateral.mintPubkey,
+          reserveDestinationDepositCollateral: ctx.reserveAccount.collateral.supplyVault,
+          userSourceLiquidity,
+          placeholderUserDestinationCollateral: owner,
+          collateralTokenProgram: TOKEN_PROGRAM_ID,
+          liquidityTokenProgram: ctx.reserveAccount.liquidity.tokenProgram,
+          instructionSysvarAccount: SYSVAR_INSTRUCTIONS_PUBKEY,
+        },
+        farmsAccounts: refreshes.farmsAccounts,
+        farmsProgram: KAMINO_FARMS_PROGRAM_ID,
+      },
+    ),
+  )
+}
+
+async function buildWithdraw(
+  ix: ReserveInstruction,
+  owner: PublicKey,
+  connection: Connection,
+  signer: PublicKey,
+  { setupInstructions, syncInstructions, preInstructions, postInstructions }: InstructionBuckets,
+) {
+  const ctx = await resolveReserveContext(ix, owner, connection)
+  const refreshes = await buildRefreshInstructions({
+    ...ctx, owner, farmMode: FARM_COLLATERAL, signer, connection, needsScopeRefresh: true,
+  })
+
+  const isSOL = ctx.reserveAccount.liquidity.mintPubkey.equals(NATIVE_MINT)
+  const userDestinationLiquidity = getAssociatedTokenAddressSync(
+    ctx.reserveAccount.liquidity.mintPubkey, owner, true, ctx.reserveAccount.liquidity.tokenProgram,
+  )
+
+  preInstructions.push(...refreshes.scopeRefreshInstructions)
+  if (isSOL) {
+    setupInstructions.push(
+      createAssociatedTokenAccountIdempotentInstruction(
+        signer, userDestinationLiquidity, owner, NATIVE_MINT, TOKEN_PROGRAM_ID,
+      ),
+    )
+  }
+  preInstructions.push(...refreshes.preInstructions)
+  postInstructions.push(...refreshes.postInstructions)
+
+  // Convert liquidity amount → collateral amount using the reserve's exchange rate
+  const exchangeRate = ctx.reserveAccount.getCollateralExchangeRate()
+  if (exchangeRate.isZero()) throw new Error(`Reserve ${ctx.reservePubkey.toBase58()} has zero exchange rate`)
+  const collateralAmount = new BN(
+    new Decimal(ix.amount.toString()).div(exchangeRate).floor().toString()
+  )
+
+  syncInstructions.push(
+    withdrawObligationCollateralAndRedeemReserveCollateralV2(
+      { collateralAmount },
+      {
+        withdrawAccounts: {
+          owner,
+          obligation: ctx.obligation,
+          lendingMarket: ctx.lendingMarket,
+          lendingMarketAuthority: ctx.lendingMarketAuthority,
+          withdrawReserve: ctx.reservePubkey,
+          reserveLiquidityMint: ctx.reserveAccount.liquidity.mintPubkey,
+          reserveSourceCollateral: ctx.reserveAccount.collateral.supplyVault,
+          reserveCollateralMint: ctx.reserveAccount.collateral.mintPubkey,
+          reserveLiquiditySupply: ctx.reserveAccount.liquidity.supplyVault,
+          userDestinationLiquidity,
+          placeholderUserDestinationCollateral: owner,
+          collateralTokenProgram: TOKEN_PROGRAM_ID,
+          liquidityTokenProgram: ctx.reserveAccount.liquidity.tokenProgram,
+          instructionSysvarAccount: SYSVAR_INSTRUCTIONS_PUBKEY,
+        },
+        farmsAccounts: refreshes.farmsAccounts,
+        farmsProgram: KAMINO_FARMS_PROGRAM_ID,
+      },
+    ),
+  )
+}
+
+async function buildBorrow(
+  ix: ReserveInstruction,
+  owner: PublicKey,
+  connection: Connection,
+  signer: PublicKey,
+  { setupInstructions, syncInstructions, preInstructions, postInstructions }: InstructionBuckets,
+) {
+  const ctx = await resolveReserveContext(ix, owner, connection)
+  const refreshes = await buildRefreshInstructions({
+    ...ctx, owner, farmMode: FARM_DEBT, signer, connection, needsScopeRefresh: true,
+  })
+
+  const isSOL = ctx.reserveAccount.liquidity.mintPubkey.equals(NATIVE_MINT)
+  const userDestinationLiquidity = getAssociatedTokenAddressSync(
+    ctx.reserveAccount.liquidity.mintPubkey, owner, true, ctx.reserveAccount.liquidity.tokenProgram,
+  )
+
+  preInstructions.push(...refreshes.scopeRefreshInstructions)
+
+  setupInstructions.push(
+    createAssociatedTokenAccountIdempotentInstruction(
+      signer, userDestinationLiquidity, owner,
+      ctx.reserveAccount.liquidity.mintPubkey, ctx.reserveAccount.liquidity.tokenProgram,
+    ),
+  )
+  preInstructions.push(...refreshes.preInstructions)
+  postInstructions.push(...refreshes.postInstructions)
+
+  syncInstructions.push(
+    borrowObligationLiquidityV2(
+      { liquidityAmount: ix.amount },
+      {
+        borrowAccounts: {
+          owner,
+          obligation: ctx.obligation,
+          lendingMarket: ctx.lendingMarket,
+          lendingMarketAuthority: ctx.lendingMarketAuthority,
+          borrowReserve: ctx.reservePubkey,
+          borrowReserveLiquidityMint: ctx.reserveAccount.liquidity.mintPubkey,
+          reserveSourceLiquidity: ctx.reserveAccount.liquidity.supplyVault,
+          borrowReserveLiquidityFeeReceiver: ctx.reserveAccount.liquidity.feeVault,
+          userDestinationLiquidity,
+          referrerTokenState: null,
+          tokenProgram: ctx.reserveAccount.liquidity.tokenProgram,
+          instructionSysvarAccount: SYSVAR_INSTRUCTIONS_PUBKEY,
+        },
+        farmsAccounts: refreshes.farmsAccounts,
+        farmsProgram: KAMINO_FARMS_PROGRAM_ID,
+      },
+    ),
+  )
+}
+
+async function buildRepay(
+  ix: ReserveInstruction,
+  owner: PublicKey,
+  connection: Connection,
+  signer: PublicKey,
+  { setupInstructions, syncInstructions, preInstructions, postInstructions }: InstructionBuckets,
+) {
+  const ctx = await resolveReserveContext(ix, owner, connection)
+  const refreshes = await buildRefreshInstructions({
+    ...ctx, owner, farmMode: FARM_DEBT, signer, connection, needsScopeRefresh: false,
+  })
+
+  const isSOL = ctx.reserveAccount.liquidity.mintPubkey.equals(NATIVE_MINT)
+  const userSourceLiquidity = getAssociatedTokenAddressSync(
+    ctx.reserveAccount.liquidity.mintPubkey, owner, true, ctx.reserveAccount.liquidity.tokenProgram,
+  )
+
+  if (isSOL) {
+    setupInstructions.push(
+      createAssociatedTokenAccountIdempotentInstruction(
+        signer, userSourceLiquidity, owner, NATIVE_MINT, TOKEN_PROGRAM_ID,
+      ),
+    )
+  }
+
+  preInstructions.push(...refreshes.preInstructions)
+  postInstructions.push(...refreshes.postInstructions)
+
+  syncInstructions.push(
+    repayObligationLiquidityV2(
+      { liquidityAmount: ix.amount },
+      {
+        repayAccounts: {
+          owner,
+          obligation: ctx.obligation,
+          lendingMarket: ctx.lendingMarket,
+          repayReserve: ctx.reservePubkey,
+          reserveLiquidityMint: ctx.reserveAccount.liquidity.mintPubkey,
+          reserveDestinationLiquidity: ctx.reserveAccount.liquidity.supplyVault,
+          userSourceLiquidity,
+          tokenProgram: ctx.reserveAccount.liquidity.tokenProgram,
+          instructionSysvarAccount: SYSVAR_INSTRUCTIONS_PUBKEY,
+        },
+        farmsAccounts: refreshes.farmsAccounts,
+        lendingMarketAuthority: ctx.lendingMarketAuthority,
+        farmsProgram: KAMINO_FARMS_PROGRAM_ID,
+      },
+    ),
+  )
+}
+
+// ============================================================================
+// Shared Helpers
+// ============================================================================
+
+/** Resolved on-chain context for a reserve-level operation. */
+interface ReserveContext {
+  reservePubkey: PublicKey
+  reserveAccount: Reserve
+  obligation: PublicKey
+  lendingMarket: PublicKey
+  lendingMarketAuthority: PublicKey
+}
+
+interface KaminoV2FarmsAccounts {
+  obligationFarmUserState?: PublicKey
+  reserveFarmState?: PublicKey
+}
+
+async function resolveReserveContext(
+  ix: ReserveInstruction,
+  owner: PublicKey,
+  connection: Connection,
+): Promise<ReserveContext> {
+  const lendingMarket = KAMINO_MARKETS[ix.market]
+  const reserveEntry = (KAMINO_RESERVES[ix.market] as Record<string, { pubkey: PublicKey; mint: PublicKey }>)[ix.asset]
+  const reservePubkey = reserveEntry?.pubkey
+  if (!reservePubkey) throw new Error(`Unknown reserve: ${ix.market}/${ix.asset}`)
+
+  const reserveAccount = await Reserve.fetch(connection, reservePubkey)
+  if (!reserveAccount) throw new Error(`Reserve not found: ${reservePubkey.toBase58()}`)
+
+  const obligation = getKaminoLendObligation(owner, lendingMarket, KAMINO_LENDING_PROGRAM_ID)
+  const [lendingMarketAuthority] = PublicKey.findProgramAddressSync(
+    [Buffer.from("lma"), lendingMarket.toBuffer()],
+    KAMINO_LENDING_PROGRAM_ID,
+  )
+
+  return { reservePubkey, reserveAccount, obligation, lendingMarket, lendingMarketAuthority }
+}
+
+/**
+ * Build the freshness and farm-setup instructions required before direct KLend operations.
+ *
+ * @param farmMode - FARM_COLLATERAL (deposit/withdraw) or FARM_DEBT (borrow/repay)
+ * @param needsScopeRefresh - true for borrow/withdraw (ALL_CHECKS), false for deposit/repay (NONE)
+ */
+async function buildRefreshInstructions({
+  reservePubkey, reserveAccount, lendingMarket, lendingMarketAuthority,
+  obligation, owner, farmMode, signer, connection, needsScopeRefresh,
+}: {
+  reservePubkey: PublicKey
+  reserveAccount: Reserve
+  lendingMarket: PublicKey
+  lendingMarketAuthority: PublicKey
+  obligation: PublicKey
+  owner: PublicKey
+  farmMode: number
+  signer: PublicKey
+  connection: Connection
+  needsScopeRefresh: boolean
+}): Promise<{
+  scopeRefreshInstructions: TransactionInstruction[]
+  preInstructions: TransactionInstruction[]
+  postInstructions: TransactionInstruction[]
+  farmsAccounts: KaminoV2FarmsAccounts
+}> {
+  const pre: TransactionInstruction[] = []
+  const post: TransactionInstruction[] = []
+  const defaultKey = PublicKey.default
+
+  const oracleOrSentinel = (key: PublicKey) =>
+    key.equals(defaultKey) ? KAMINO_LENDING_PROGRAM_ID : key
+
+  // Determine farm state based on mode (collateral vs debt)
+  const farmState = farmMode === FARM_COLLATERAL ? reserveAccount.farmCollateral : reserveAccount.farmDebt
+  const hasFarm = !farmState.equals(defaultKey)
+  let obligationFarmUserState: PublicKey | undefined
+  if (hasFarm) {
+    obligationFarmUserState = getKaminoFarmsObligationFarm(obligation, farmState, KAMINO_FARMS_PROGRAM_ID)
+  }
+  const farmsAccounts: KaminoV2FarmsAccounts = hasFarm
+    ? {
+        obligationFarmUserState,
+        reserveFarmState: farmState,
+      }
+    : {}
+
+  // 1. Init obligation farms (if needed, before all refreshes)
+  if (hasFarm) {
+    const farmUserStateAccount = await connection.getAccountInfo(obligationFarmUserState!)
+    if (!farmUserStateAccount) {
+      pre.push(
+        initObligationFarmsForReserve(
+          { mode: farmMode },
+          {
+            payer: signer,
+            owner,
+            obligation,
+            lendingMarketAuthority,
+            reserve: reservePubkey,
+            reserveFarmState: farmState,
+            obligationFarm: obligationFarmUserState!,
+            lendingMarket,
+            farmsProgram: KAMINO_FARMS_PROGRAM_ID,
+            rent: SYSVAR_RENT_PUBKEY,
+            systemProgram: SystemProgram.programId,
+          },
+        ),
+      )
+    }
+  }
+
+  // 2. Refresh ALL active reserves in the obligation + the operation reserve.
+  // KLend's refreshObligation requires every reserve passed as a remaining
+  // account to have been refreshed in the same transaction.
+  // IMPORTANT: The operation reserve's refreshReserve MUST be the last one
+  // pushed (position -3 from the sync tx) because check_refresh looks for it there.
+  const obligationState = await Obligation.fetch(connection, obligation)
+  const otherReservePubkeys: PublicKey[] = []
+  if (obligationState) {
+    for (const d of obligationState.deposits) {
+      if (!d.depositReserve.equals(defaultKey) && !d.depositReserve.equals(reservePubkey)) {
+        otherReservePubkeys.push(d.depositReserve)
+      }
+    }
+    for (const b of obligationState.borrows) {
+      if (!b.borrowReserve.equals(defaultKey) && !b.borrowReserve.equals(reservePubkey)) {
+        otherReservePubkeys.push(b.borrowReserve)
+      }
+    }
+  }
+
+  // Fetch all other reserve accounts (needed for refreshReserve and optionally Scope refresh)
+  const otherReserves: { pubkey: PublicKey; account: Reserve }[] = []
+  for (const rPubkey of otherReservePubkeys) {
+    const rAccount = await Reserve.fetch(connection, rPubkey)
+    if (!rAccount) continue
+    otherReserves.push({ pubkey: rPubkey, account: rAccount })
+  }
+
+  // Scope refreshPriceList — only needed for operations that check ALL_CHECKS
+  // (borrow/withdraw). Must be the FIRST instructions in the transaction
+  // (after ComputeBudget) because the Scope program validates ordering.
+  const allReserves = [...otherReserves, { pubkey: reservePubkey, account: reserveAccount }]
+  const scopeRefreshIxs = needsScopeRefresh
+    ? await buildScopeRefreshInstructions(connection, allReserves)
+    : []
+
+  // Refresh other reserves first (order doesn't matter for these)
+  for (const { pubkey: rPubkey, account: rAccount } of otherReserves) {
+    const ti = rAccount.config.tokenInfo
+    pre.push(
+      refreshReserve({
+        reserve: rPubkey,
+        lendingMarket,
+        pythOracle: oracleOrSentinel(ti.pythConfiguration.price),
+        switchboardPriceOracle: oracleOrSentinel(ti.switchboardConfiguration.priceAggregator),
+        switchboardTwapOracle: oracleOrSentinel(ti.switchboardConfiguration.twapAggregator),
+        scopePrices: oracleOrSentinel(ti.scopeConfiguration.priceFeed),
+      }),
+    )
+  }
+
+  // Refresh the operation reserve LAST — must be at position -3 from the sync tx
+  const ti = reserveAccount.config.tokenInfo
+  pre.push(
+    refreshReserve({
+      reserve: reservePubkey,
+      lendingMarket,
+      pythOracle: oracleOrSentinel(ti.pythConfiguration.price),
+      switchboardPriceOracle: oracleOrSentinel(ti.switchboardConfiguration.priceAggregator),
+      switchboardTwapOracle: oracleOrSentinel(ti.switchboardConfiguration.twapAggregator),
+      scopePrices: oracleOrSentinel(ti.scopeConfiguration.priceFeed),
+    }),
+  )
+
+  // 3. RefreshObligation — pass all active reserves as remaining accounts.
+  const refreshObligationIx = refreshObligation({ lendingMarket, obligation })
+  if (obligationState) {
+    const depositReserves = obligationState.deposits
+      .map(d => d.depositReserve)
+      .filter(r => !r.equals(defaultKey))
+    const borrowReserves = obligationState.borrows
+      .map(b => b.borrowReserve)
+      .filter(r => !r.equals(defaultKey))
+    for (const reserve of [...depositReserves, ...borrowReserves]) {
+      refreshObligationIx.keys.push({ pubkey: reserve, isSigner: false, isWritable: false })
+    }
+  }
+  pre.push(refreshObligationIx)
+
+  return {
+    scopeRefreshInstructions: scopeRefreshIxs,
+    preInstructions: pre,
+    postInstructions: post,
+    farmsAccounts,
+  }
+}
+
+// ============================================================================
+// Orderbook Action Builders
+// ============================================================================
+
+/**
+ * Builder for Exponent Orderbook vault action descriptors.
+ *
+ * Each method returns an `OrderbookInstruction` that describes what to do.
+ * Pass these to `createVaultSyncTransaction` which resolves them into
+ * raw Solana instructions and wraps them in a Squads sync transaction.
+ *
+ * @example
+ * ```ts
+ * import { orderbookAction, createVaultSyncTransaction, OrderbookTradeDirection } from "@exponent-labs/exponent-sdk"
+ *
+ * const { instruction, preInstructions } = await createVaultSyncTransaction({
+ *   instructions: [
+ *     orderbookAction.postOffer({
+ *       orderbook: ORDERBOOK_ADDRESS,
+ *       direction: OrderbookTradeDirection.BUY_PT,
+ *       priceApy: 0.10,
+ *       amount: 1_000_000n,
+ *     }),
+ *   ],
+ *   owner: squadsVault,
+ *   connection,
+ *   policyPda,
+ *   vaultPda: squadsVault,
+ *   signer: walletPublicKey,
+ * })
+ * ```
+ */
+export const orderbookAction = {
+  /**
+   * Post a limit order on the orderbook.
+   * @param params - Order parameters
+   * @param params.offerIdx - Required offer index for position tracking. Must be unique per trader.
+   */
+  postOffer(params: {
+    orderbook: PublicKey
+    direction: OrderbookTradeDirection
+    priceApy: number
+    amount: bigint
+    /** Required offer index for position tracking. Must be unique per trader. */
+    offerIdx: number
+    offerOption?: OrderbookOfferOption
+    virtualOffer?: boolean
+    expirySeconds?: number
+    mode?: OrderbookInstructionMode
+  }): OrderbookPostOfferInstruction {
+    return {
+      action: OrderbookAction.POST_OFFER,
+      orderbook: params.orderbook,
+      mode: params.mode,
+      direction: params.direction,
+      priceApy: params.priceApy,
+      amount: params.amount,
+      offerIdx: params.offerIdx,
+      offerOption: params.offerOption,
+      virtualOffer: params.virtualOffer,
+      expirySeconds: params.expirySeconds,
+    }
+  },
+
+  /**
+   * Execute a market order on the orderbook.
+   * @param params - Order parameters
+   */
+  marketOffer(params: {
+    orderbook: PublicKey
+    direction: OrderbookTradeDirection
+    maxPriceApy: number
+    amount: bigint
+    minAmountOut: bigint
+    virtualOffer?: boolean
+    mode?: OrderbookInstructionMode
+  }): OrderbookMarketOfferInstruction {
+    return {
+      action: OrderbookAction.MARKET_OFFER,
+      orderbook: params.orderbook,
+      mode: params.mode,
+      direction: params.direction,
+      maxPriceApy: params.maxPriceApy,
+      amount: params.amount,
+      minAmountOut: params.minAmountOut,
+      virtualOffer: params.virtualOffer,
+    }
+  },
+
+  /**
+   * Cancel an existing limit order.
+   * @param params - Cancel parameters
+   */
+  removeOffer(params: {
+    orderbook: PublicKey
+    offerIdx: number
+  }): OrderbookRemoveOfferInstruction {
+    return {
+      action: OrderbookAction.REMOVE_OFFER,
+      orderbook: params.orderbook,
+      offerIdx: params.offerIdx,
+    }
+  },
+
+  /**
+   * Withdraw funds from user escrow to token accounts.
+   * @param params - Withdraw parameters (null amounts = withdraw max)
+   */
+  withdrawFunds(params: {
+    orderbook: PublicKey
+    ptAmount?: bigint | null
+    ytAmount?: bigint | null
+    syAmount?: bigint | null
+  }): OrderbookWithdrawFundsInstruction {
+    return {
+      action: OrderbookAction.WITHDRAW_FUNDS,
+      orderbook: params.orderbook,
+      ptAmount: params.ptAmount,
+      ytAmount: params.ytAmount,
+      syAmount: params.syAmount,
+    }
+  },
+}
+
+export const syAction = {
+  mint(params: {
+    vault: PublicKey
+    amountBase: bigint
+  }): SyMintInstruction {
+    return {
+      action: SyAction.MINT,
+      vault: params.vault,
+      amountBase: params.amountBase,
+    }
+  },
+
+  redeem(params: {
+    vault: PublicKey
+    amountSy: bigint
+  }): SyRedeemInstruction {
+    return {
+      action: SyAction.REDEEM,
+      vault: params.vault,
+      amountSy: params.amountSy,
+    }
+  },
+}
+
+// ============================================================================
+// Core Action Builders (Strip/Merge)
+// ============================================================================
+
+/**
+ * Builder for Exponent Core strip/merge action descriptors.
+ *
+ * Each method returns a `CoreInstruction` that describes what to do.
+ * Pass these to `createVaultSyncTransaction` which resolves them into
+ * raw Solana instructions and wraps them in a Squads sync transaction.
+ *
+ * @example
+ * ```ts
+ * import { coreAction, createVaultSyncTransaction } from "@exponent-labs/exponent-sdk"
+ *
+ * const { instruction, preInstructions } = await createVaultSyncTransaction({
+ *   instructions: [
+ *     coreAction.strip({
+ *       vault: VAULT_ADDRESS,
+ *       amountBase: 1_000_000_000n, // 1 SOL worth
+ *     }),
+ *   ],
+ *   owner: squadsVault,
+ *   connection,
+ *   policyPda,
+ *   vaultPda: squadsVault,
+ *   signer: walletPublicKey,
+ * })
+ * ```
+ */
+export const coreAction = {
+  /**
+   * Strip LST (base token) into PT + YT.
+   * @param params - Strip parameters
+   */
+  strip(params: {
+    /** The Exponent vault address */
+    vault: PublicKey
+    /** Amount of base token (LST) to strip - in base token units */
+    amountBase: bigint
+  }): CoreStripInstruction {
+    return {
+      action: CoreAction.STRIP,
+      vault: params.vault,
+      amountBase: params.amountBase,
+    }
+  },
+
+  /**
+   * Merge PT + YT into LST (base token).
+   * Requires equal amounts of PT and YT.
+   * @param params - Merge parameters
+   */
+  merge(params: {
+    /** The Exponent vault address */
+    vault: PublicKey
+    /** Amount of PT/YT to merge (must have equal amounts of both) */
+    amountPy: bigint
+  }): CoreMergeInstruction {
+    return {
+      action: CoreAction.MERGE,
+      vault: params.vault,
+      amountPy: params.amountPy,
+    }
+  },
+
+  /**
+   * Withdraw YT from the tracked yield position into the owner's YT token account.
+   * Useful before wrapper_merge, which consumes YT from the token account.
+   */
+  withdrawYt(params: {
+    /** The Exponent vault address */
+    vault: PublicKey
+    /** Amount of YT to withdraw */
+    amountYt: bigint
+  }): CoreWithdrawYtInstruction {
+    return {
+      action: CoreAction.WITHDRAW_YT,
+      vault: params.vault,
+      amountYt: params.amountYt,
+    }
+  },
+
+  /**
+   * Deposit YT from the owner's YT token account back into the tracked yield position.
+   * Use this to ensure idle YT continues earning yield.
+   */
+  depositYt(params: {
+    /** The Exponent vault address */
+    vault: PublicKey
+    /** Amount of YT to deposit */
+    amountYt: bigint
+  }): CoreDepositYtInstruction {
+    return {
+      action: CoreAction.DEPOSIT_YT,
+      vault: params.vault,
+      amountYt: params.amountYt,
+    }
+  },
+
+  /**
+   * Initialize yield position for the Squads vault (owner).
+   * Required before buying YT or depositing YT.
+   */
+  initializeYieldPosition(params: { vault: PublicKey }): CoreInitializeYieldPositionInstruction {
+    return {
+      action: CoreAction.INITIALIZE_YIELD_POSITION,
+      vault: params.vault,
+    }
+  },
+}
+
+/**
+ * Convert trade direction to OfferType used by the orderbook program.
+ */
+function directionToOfferType(direction: OrderbookTradeDirection): OfferType {
+  switch (direction) {
+    case OrderbookTradeDirection.BUY_PT:
+    case OrderbookTradeDirection.SELL_YT:
+      return OfferType.SellYt
+    case OrderbookTradeDirection.SELL_PT:
+    case OrderbookTradeDirection.BUY_YT:
+      return OfferType.BuyYt
+  }
+}
+
+/**
+ * Build orderbook instructions and wrap them in a Squads sync transaction.
+ *
+ * Takes high-level `OrderbookInstruction` descriptors (built with `orderbookAction.*`),
+ * loads the orderbook SDK, resolves them to raw Solana instructions, and wraps them
+ * in a Squads sync transaction.
+ *
+ * @returns `{ setupInstructions, preInstructions, instruction, postInstructions }` — include all in your transaction
+ *
+ * @example
+ * ```ts
+ * const { setupInstructions, preInstructions, instruction, postInstructions } = await createOrderbookSyncTransaction({
+ *   instructions: [
+ *     orderbookAction.postOffer({
+ *       orderbook: ORDERBOOK_ADDRESS,
+ *       direction: OrderbookTradeDirection.BUY_PT,
+ *       priceApy: 0.10,
+ *       amount: 1_000_000n,
+ *     }),
+ *   ],
+ *   owner: squadsVault,
+ *   connection,
+ *   policyPda,
+ *   vaultPda: squadsVault,
+ *   signer: wallet.publicKey,
+ *   vaultAddress: VAULT_ADDRESS,
+ * })
+ * // Send: [...setupInstructions, ...preInstructions, instruction, ...postInstructions]
+ * ```
+ */
+export async function createOrderbookSyncTransaction({
+  instructions,
+  owner,
+  connection,
+  policyPda,
+  vaultPda,
+  signer,
+  accountIndex = 0,
+  constraintIndices,
+  vaultAddress,
+  leadingAccounts,
+  preHookAccounts,
+  postHookAccounts,
+  squadsProgram = SQUADS_PROGRAM_ID,
+  env = LOCAL_ENV,
+}: {
+  instructions: OrderbookInstruction[]
+  owner: PublicKey
+  connection: Connection
+  policyPda?: PublicKey
+  vaultPda: PublicKey
+  signer: PublicKey
+  accountIndex?: number
+  constraintIndices?: number[]
+  /** ExponentStrategyVault PDA — used to auto-resolve hook accounts from the on-chain policy */
+  vaultAddress?: PublicKey
+  leadingAccounts?: PublicKey[] | AccountMeta[]
+  preHookAccounts?: PublicKey[] | AccountMeta[]
+  postHookAccounts?: PublicKey[] | AccountMeta[]
+  squadsProgram?: PublicKey
+  env?: Environment
+}): Promise<VaultSyncTransactionResult> {
+  const { setupInstructions, syncInstructions, preInstructions, postInstructions, signers, addressLookupTableAddresses } = await buildOrderbookInstructions(
+    instructions,
+    owner,
+    connection,
+    signer,
+    policyPda,
+    vaultPda,
+    accountIndex,
+    vaultAddress,
+    leadingAccounts,
+    preHookAccounts,
+    postHookAccounts,
+    squadsProgram,
+    env,
+  )
+
+  let resolvedPolicyPda = policyPda
+  let resolvedConstraintIndices = constraintIndices
+  if (!resolvedPolicyPda) {
+    if (!vaultAddress) {
+      throw new Error("vaultAddress is required when policyPda is not provided")
+    }
+    const match = await resolvePolicyMatchForVault(connection, vaultAddress, signer, syncInstructions)
+    resolvedPolicyPda = match.policyPda
+    resolvedConstraintIndices ??= match.constraintIndices
+  }
+
+  // Auto-resolve constraint indices when not explicitly provided
+  resolvedConstraintIndices ??= await resolveConstraintIndices(
+    connection,
+    resolvedPolicyPda,
+    syncInstructions,
+  )
+
+  // Auto-resolve policy prefix and hook accounts when not explicitly provided
+  let resolvedLeadingAccounts = leadingAccounts
+  let resolvedPreHookAccounts = preHookAccounts
+  let resolvedPostHookAccounts = postHookAccounts
+  if (vaultAddress && (!leadingAccounts || !preHookAccounts || !postHookAccounts)) {
+    const hooks = await resolveHookAccounts(connection, resolvedPolicyPda, vaultAddress, signer)
+    resolvedLeadingAccounts ??= hooks.leadingAccounts
+    resolvedPreHookAccounts ??= hooks.preHookAccounts
+    resolvedPostHookAccounts ??= hooks.postHookAccounts
+  }
+
+  const instruction = wrapInstructionsInSyncTransaction({
+    policyPda: resolvedPolicyPda,
+    vaultPda,
+    signer,
+    instructions: syncInstructions,
+    squadsProgram,
+    accountIndex,
+    constraintIndices: resolvedConstraintIndices,
+    leadingAccounts: resolvedLeadingAccounts,
+    preHookAccounts: resolvedPreHookAccounts,
+    postHookAccounts: resolvedPostHookAccounts,
+  })
+
+  return { setupInstructions, preInstructions, instruction, postInstructions, signers, addressLookupTableAddresses }
+}
+
+/** Cache for loaded orderbooks to avoid redundant fetches */
+const orderbookCache = new Map<string, Orderbook>()
+
+/**
+ * Build raw Solana instructions from orderbook action descriptors.
+ */
+async function buildOrderbookInstructions(
+  instructions: OrderbookInstruction[],
+  owner: PublicKey,
+  connection: Connection,
+  signer: PublicKey,
+  policyPda: PublicKey,
+  vaultPda: PublicKey,
+  accountIndex: number,
+  vaultAddress: PublicKey | undefined,
+  leadingAccounts: PublicKey[] | AccountMeta[] | undefined,
+  preHookAccounts: PublicKey[] | AccountMeta[] | undefined,
+  postHookAccounts: PublicKey[] | AccountMeta[] | undefined,
+  squadsProgram: PublicKey,
+  env: Environment,
+): Promise<InstructionBuckets> {
+  const buckets: InstructionBuckets = {
+    setupInstructions: [],
+    syncInstructions: [],
+    preInstructions: [],
+    postInstructions: [],
+    signers: [],
+    addressLookupTableAddresses: [],
+  }
+  const setupContext = createStrategySetupContext({
+    connection,
+    env,
+    owner,
+    signer,
+    vaultAddress,
+    policyPda,
+    vaultPda,
+    accountIndex,
+    squadsProgram,
+    leadingAccounts,
+    preHookAccounts,
+    postHookAccounts,
+  })
+
+  for (const ix of instructions) {
+    await buildOrderbookInstruction(ix, owner, connection, buckets, setupContext, env)
+  }
+
+  return buckets
+}
+
+async function buildPostOffer(
+  ix: OrderbookPostOfferInstruction,
+  orderbook: Orderbook,
+  owner: PublicKey,
+  setupPayer: PublicKey,
+  buckets: InstructionBuckets,
+  setupContext?: StrategySetupContext,
+) {
+  const offerType = directionToOfferType(ix.direction)
+  const option = ix.offerOption ?? "FillOrKill"
+
+  if (setupContext) {
+    await ensureOrderbookPositionSetup(orderbook, buckets, setupContext)
+    await ensureTrackedTokenAccountSetup({
+      tokenMint: orderbook.vault.mintSy,
+      tokenAccount: getAssociatedTokenAddressSync(orderbook.vault.mintSy, owner, true, TOKEN_PROGRAM_ID),
+      tokenProgram: TOKEN_PROGRAM_ID,
+      buckets,
+      setupContext,
+    })
+    await ensureTrackedTokenAccountSetup({
+      tokenMint: orderbook.mintPt,
+      tokenAccount: getAssociatedTokenAddressSync(orderbook.mintPt, owner, true, TOKEN_PROGRAM_ID),
+      tokenProgram: TOKEN_PROGRAM_ID,
+      buckets,
+      setupContext,
+    })
+    await ensureTrackedTokenAccountSetup({
+      tokenMint: orderbook.mintYt,
+      tokenAccount: getAssociatedTokenAddressSync(orderbook.mintYt, owner, true, TOKEN_PROGRAM_ID),
+      tokenProgram: TOKEN_PROGRAM_ID,
+      buckets,
+      setupContext,
+    })
+    await ensureYieldPositionSetup(orderbook.vault, buckets, setupContext)
+  }
+
+  if (ix.mode === "raw") {
+    buckets.syncInstructions.push(
+      orderbook.ixPostOffer({
+        trader: owner,
+        price: ix.priceApy,
+        amount: ix.amount,
+        offerType,
+        offerOption: offerOptions(option, [false]),
+        virtualOffer: ix.virtualOffer ?? false,
+        expirySeconds: ix.expirySeconds ?? 3600,
+        mintSy: orderbook.vault.mintSy,
+        offerIdx: ix.offerIdx,
+      }),
+    )
+    return
+  }
+
+  const { ix: postOfferIx, setupIxs } = await orderbook.ixWrapperPostOffer({
+    trader: owner,
+    setupPayer,
+    price: ix.priceApy,
+    amount: ix.amount,
+    offerType,
+    offerOption: offerOptions(option, [false]),
+    virtualOffer: ix.virtualOffer ?? false,
+    expirySeconds: ix.expirySeconds ?? 3600,
+    mintSy: orderbook.vault.mintSy,
+    offerIdx: ix.offerIdx,
+  })
+
+  buckets.preInstructions.push(...setupIxs)
+  buckets.syncInstructions.push(postOfferIx)
+}
+
+async function buildMarketOffer(
+  ix: OrderbookMarketOfferInstruction,
+  orderbook: Orderbook,
+  owner: PublicKey,
+  setupPayer: PublicKey,
+  buckets: InstructionBuckets,
+  setupContext?: StrategySetupContext,
+) {
+  const offerType = directionToOfferType(ix.direction)
+
+  if (setupContext) {
+    await ensureOrderbookPositionSetup(orderbook, buckets, setupContext)
+    await ensureTrackedTokenAccountSetup({
+      tokenMint: orderbook.vault.mintSy,
+      tokenAccount: getAssociatedTokenAddressSync(orderbook.vault.mintSy, owner, true, TOKEN_PROGRAM_ID),
+      tokenProgram: TOKEN_PROGRAM_ID,
+      buckets,
+      setupContext,
+    })
+    await ensureTrackedTokenAccountSetup({
+      tokenMint: orderbook.mintPt,
+      tokenAccount: getAssociatedTokenAddressSync(orderbook.mintPt, owner, true, TOKEN_PROGRAM_ID),
+      tokenProgram: TOKEN_PROGRAM_ID,
+      buckets,
+      setupContext,
+    })
+    await ensureTrackedTokenAccountSetup({
+      tokenMint: orderbook.mintYt,
+      tokenAccount: getAssociatedTokenAddressSync(orderbook.mintYt, owner, true, TOKEN_PROGRAM_ID),
+      tokenProgram: TOKEN_PROGRAM_ID,
+      buckets,
+      setupContext,
+    })
+    await ensureYieldPositionSetup(orderbook.vault, buckets, setupContext)
+  }
+
+  if (ix.mode === "raw") {
+    buckets.syncInstructions.push(
+      orderbook.ixMarketOffer({
+        trader: owner,
+        maxPriceApy: ix.maxPriceApy,
+        amount: ix.amount,
+        minAmountOut: ix.minAmountOut,
+        offerType,
+        virtualOffer: ix.virtualOffer ?? false,
+        mintSy: orderbook.vault.mintSy,
+      }),
+    )
+    return
+  }
+
+  const { ix: marketOfferIx, setupIxs } = await orderbook.ixWrapperMarketOffer({
+    trader: owner,
+    setupPayer,
+    maxPriceApy: ix.maxPriceApy,
+    amount: ix.amount,
+    offerType,
+    minAmountOut: ix.minAmountOut,
+    virtualOffer: ix.virtualOffer ?? false,
+    mintSy: orderbook.vault.mintSy,
+  })
+
+  buckets.preInstructions.push(...setupIxs)
+  buckets.syncInstructions.push(marketOfferIx)
+}
+
+async function buildRemoveOffer(
+  ix: OrderbookRemoveOfferInstruction,
+  orderbook: Orderbook,
+  owner: PublicKey,
+  { syncInstructions }: InstructionBuckets,
+) {
+  const removeOfferIx = await orderbook.ixWrapperRemoveOffer({
+    trader: owner,
+    offerIdx: ix.offerIdx,
+    mintSy: orderbook.vault.mintSy,
+  })
+
+  syncInstructions.push(removeOfferIx)
+}
+
+async function buildWithdrawFunds(
+  ix: OrderbookWithdrawFundsInstruction,
+  orderbook: Orderbook,
+  owner: PublicKey,
+  { syncInstructions }: InstructionBuckets,
+) {
+  // Convert bigint | null | undefined to Amount type
+  const toAmount = (value: bigint | null | undefined) => {
+    if (value === null || value === undefined) {
+      return createAmount("All")
+    }
+    return createAmount("Some", [value])
+  }
+
+  const withdrawFundsIx = await orderbook.ixWrapperWithdrawFunds({
+    trader: owner,
+    mintSy: orderbook.vault.mintSy,
+    ptAmount: toAmount(ix.ptAmount),
+    ytAmount: toAmount(ix.ytAmount),
+    syAmount: toAmount(ix.syAmount),
+  })
+
+  syncInstructions.push(withdrawFundsIx)
+}
+
+// ============================================================================
+// Core Instruction Builders (Strip/Merge)
+// ============================================================================
+
+/** Build a single core instruction (strip/merge) */
+async function buildCoreInstruction(
+  ix: CoreInstruction,
+  owner: PublicKey,
+  connection: Connection,
+  buckets: InstructionBuckets,
+  setupContext?: StrategySetupContext,
+): Promise<void> {
+  const cacheKey = ix.vault.toBase58()
+  let vault = vaultCache.get(cacheKey)
+  if (!vault) {
+    vault = await Vault.load(LOCAL_ENV, connection, ix.vault)
+    vaultCache.set(cacheKey, vault)
+  }
+
+  const isInitializeYieldPosition = ix.action === CoreAction.INITIALIZE_YIELD_POSITION
+
+  if (setupContext && !isInitializeYieldPosition) {
+    await ensureTrackedTokenAccountSetup({
+      tokenMint: vault.mintPt,
+      tokenAccount: getAssociatedTokenAddressSync(vault.mintPt, setupContext.owner, true, TOKEN_PROGRAM_ID),
+      tokenProgram: TOKEN_PROGRAM_ID,
+      buckets,
+      setupContext,
+    })
+    await ensureYieldPositionSetup(vault, buckets, setupContext)
+    if (ix.action === CoreAction.WITHDRAW_YT) {
+      await ensureTrackedTokenAccountSetup({
+        tokenMint: vault.mintYt,
+        tokenAccount: getAssociatedTokenAddressSync(vault.mintYt, setupContext.owner, true, TOKEN_PROGRAM_ID),
+        tokenProgram: TOKEN_PROGRAM_ID,
+        buckets,
+        setupContext,
+      })
+    }
+  }
+
+  switch (ix.action) {
+    case CoreAction.STRIP:
+      await buildStrip(ix, vault, owner, setupContext?.signer ?? owner, buckets)
+      break
+    case CoreAction.MERGE:
+      await buildMerge(ix, vault, owner, setupContext?.signer ?? owner, buckets)
+      break
+    case CoreAction.WITHDRAW_YT:
+      await buildWithdrawYt(ix, vault, owner, setupContext?.signer ?? owner, buckets)
+      break
+    case CoreAction.DEPOSIT_YT:
+      await buildDepositYt(ix, vault, owner, buckets)
+      break
+    case CoreAction.INITIALIZE_YIELD_POSITION:
+      await buildInitializeYieldPosition(ix, vault, owner, buckets)
+      break
+  }
+}
+
+async function buildInitializeYieldPosition(
+  ix: CoreInitializeYieldPositionInstruction,
+  vault: Vault,
+  owner: PublicKey,
+  { syncInstructions }: InstructionBuckets,
+) {
+  const initIx = vault.ixInitializeYieldPosition({ owner })
+  syncInstructions.push(initIx)
+}
+
+async function buildStrip(
+  ix: CoreStripInstruction,
+  vault: Vault,
+  owner: PublicKey,
+  payer: PublicKey,
+  { syncInstructions, preInstructions }: InstructionBuckets,
+) {
+  const sySrc = getAssociatedTokenAddressSync(vault.mintSy, owner, true, TOKEN_PROGRAM_ID)
+  const ptDst = getAssociatedTokenAddressSync(vault.mintPt, owner, true, TOKEN_PROGRAM_ID)
+  const ytDst = getAssociatedTokenAddressSync(vault.mintYt, owner, true, TOKEN_PROGRAM_ID)
+
+  preInstructions.push(
+    createAssociatedTokenAccountIdempotentInstruction(payer, sySrc, owner, vault.mintSy),
+    createAssociatedTokenAccountIdempotentInstruction(payer, ptDst, owner, vault.mintPt),
+    createAssociatedTokenAccountIdempotentInstruction(payer, ytDst, owner, vault.mintYt),
+  )
+
+  const stripIx = await vault.ixStripFromBase({
+    owner,
+    amountBase: ix.amountBase,
+    sySrc,
+    ptDst,
+    ytDst,
+  })
+
+  // Strip instruction needs vault signature
+  syncInstructions.push(stripIx)
+}
+
+async function buildMerge(
+  ix: CoreMergeInstruction,
+  vault: Vault,
+  owner: PublicKey,
+  payer: PublicKey,
+  { syncInstructions, preInstructions }: InstructionBuckets,
+) {
+  const { ixs, setupIxs } = await vault.ixMergeToBase({
+    owner,
+    payer,
+    amountPy: ix.amountPy,
+  })
+
+  // Setup instructions (ATA creation) go in preInstructions
+  preInstructions.push(...setupIxs)
+  // Merge instructions need vault signature
+  syncInstructions.push(...ixs)
+}
+
+async function buildWithdrawYt(
+  ix: CoreWithdrawYtInstruction,
+  vault: Vault,
+  owner: PublicKey,
+  payer: PublicKey,
+  { syncInstructions, preInstructions }: InstructionBuckets,
+) {
+  const ytDst = getAssociatedTokenAddressSync(vault.mintYt, owner, true, TOKEN_PROGRAM_ID)
+  preInstructions.push(
+    createAssociatedTokenAccountIdempotentInstruction(payer, ytDst, owner, vault.mintYt),
+  )
+
+  const ytPosition = await YtPosition.loadByOwner(LOCAL_ENV, vault.connection, owner, vault)
+  syncInstructions.push(
+    ytPosition.ixWithdrawYt({
+      amount: ix.amountYt,
+      ytDst,
+    }),
+  )
+}
+
+async function buildDepositYt(
+  ix: CoreDepositYtInstruction,
+  vault: Vault,
+  owner: PublicKey,
+  { syncInstructions }: InstructionBuckets,
+) {
+  const ytSrc = getAssociatedTokenAddressSync(vault.mintYt, owner, true, TOKEN_PROGRAM_ID)
+  const ytPosition = await YtPosition.loadByOwner(LOCAL_ENV, vault.connection, owner, vault)
+  syncInstructions.push(
+    ytPosition.ixDepositYt({
+      amount: ix.amountYt,
+      ytSrc,
+    }),
+  )
+}
+
+async function buildSyInstruction(
+  ix: SyInstruction,
+  owner: PublicKey,
+  connection: Connection,
+  buckets: InstructionBuckets,
+  setupContext?: StrategySetupContext,
+): Promise<void> {
+  const cacheKey = ix.vault.toBase58()
+  let vault = vaultCache.get(cacheKey)
+  if (!vault) {
+    vault = await Vault.load(LOCAL_ENV, connection, ix.vault)
+    vaultCache.set(cacheKey, vault)
+  }
+
+  if (!setupContext) {
+    throw new Error("SY actions require a strategy setup context")
+  }
+
+  const setupState = await loadStrategySetupState(setupContext)
+  if (!setupState) {
+    throw new Error("SY actions require a strategy vault context")
+  }
+
+  const trackedBaseTokenAccount = setupState.tokenEntryAccountByMint.get(vault.flavor.mintBase.toBase58())
+  const baseTokenAccount = trackedBaseTokenAccount
+    ? new PublicKey(trackedBaseTokenAccount)
+    : getAssociatedTokenAddressSync(vault.flavor.mintBase, owner, true, vault.flavor.baseTokenProgram)
+  const syTokenAccount = getAssociatedTokenAddressSync(vault.mintSy, owner, true, TOKEN_PROGRAM_ID)
+
+  await ensureTrackedTokenAccountSetup({
+    tokenMint: vault.mintSy,
+    tokenAccount: syTokenAccount,
+    tokenProgram: TOKEN_PROGRAM_ID,
+    buckets,
+    setupContext,
+  })
+
+  if (!setupState.trackedTokenAccounts.has(baseTokenAccount.toBase58())) {
+    throw new Error(
+      `Base mint ${vault.flavor.mintBase.toBase58()} must be tracked on the strategy vault before using mint_sy/redeem_sy`,
+    )
+  }
+
+  switch (ix.action) {
+    case SyAction.MINT:
+      buckets.syncInstructions.push(
+        await vault.flavor.ixMintSy({
+          amountBase: ix.amountBase.toString(),
+          depositor: owner,
+          depositorBaseTokenAccount: baseTokenAccount,
+          depositorSyTokenAccount: syTokenAccount,
+        }),
+      )
+      break
+    case SyAction.REDEEM:
+      buckets.syncInstructions.push(
+        await vault.flavor.ixRedeemSy({
+          amountSy: ix.amountSy.toString(),
+          redeemer: owner,
+          redeemerBaseTokenAccount: baseTokenAccount,
+          redeemerSyTokenAccount: syTokenAccount,
+        }),
+      )
+      break
+  }
+}
+
+/**
+ * Builder for Titan swap vault action descriptors.
+ *
+ * Since Titan swap instructions contain complex routing data from Titan's API,
+ * you pass a pre-built `TransactionInstruction` and we wrap it in a sync transaction.
+ *
+ * @example
+ * ```ts
+ * import { titanAction, createVaultSyncTransaction } from "@exponent-labs/exponent-sdk"
+ *
+ * const { setupInstructions, instruction } = await createVaultSyncTransaction({
+ *   instructions: [titanAction.swap({ instruction: titanSwapIx })],
+ *   owner: squadsVault,
+ *   connection,
+ *   policyPda,
+ *   vaultPda: squadsVault,
+ *   signer: wallet.publicKey,
+ *   vaultAddress: VAULT_ADDRESS,
+ * })
+ * ```
+ */
+export const titanAction = {
+  /**
+   * Wrap a Titan SwapRouteV2 instruction for vault execution.
+   * @param params.instruction - Pre-built TransactionInstruction from Titan's router API
+   */
+  swap(params: { instruction: TransactionInstruction }): TitanSwapInstruction {
+    return { action: TitanAction.SWAP, instruction: params.instruction }
+  },
+}
+
+// ============================================================================
+// Loopscale Action Builder
+// ============================================================================
+
+/**
+ * Builder for Loopscale vault action descriptors.
+ *
+ * Loans (BORROWER side): create/close loan, deposit/withdraw collateral, borrow/repay principal.
+ * Strategies (LENDER side): create/close strategy, deposit/withdraw into strategy.
+ *
+ * Since Loopscale instructions come from the Loopscale API (which also
+ * handles `bs_auth` co-signing), you pass pre-built `TransactionInstruction`s
+ * and we wrap them in a sync transaction.
+ *
+ * @example
+ * ```ts
+ * import { loopscaleAction, createVaultSyncTransaction } from "@exponent-labs/exponent-sdk"
+ *
+ * const { instruction } = await createVaultSyncTransaction({
+ *   instructions: [
+ *     loopscaleAction.createLoan({ instruction: createLoanIx }),
+ *     loopscaleAction.depositCollateral({ instruction: depositIx }),
+ *     loopscaleAction.borrowPrincipal({ instruction: borrowIx }),
+ *   ],
+ *   owner: squadsSettings,
+ *   connection,
+ *   policyPda,
+ *   vaultPda: squadsVault,
+ *   signer: wallet.publicKey,
+ *   vaultAddress,
+ * })
+ * ```
+ */
+export const loopscaleAction = {
+  createLoan(params: { instruction: TransactionInstruction }): LoopscaleInstruction {
+    return { action: LoopscaleAction.CREATE_LOAN, instruction: params.instruction }
+  },
+  depositCollateral(params: { instruction: TransactionInstruction }): LoopscaleInstruction {
+    return { action: LoopscaleAction.DEPOSIT_COLLATERAL, instruction: params.instruction }
+  },
+  borrowPrincipal(params: { instruction: TransactionInstruction }): LoopscaleInstruction {
+    return { action: LoopscaleAction.BORROW_PRINCIPAL, instruction: params.instruction }
+  },
+  repayPrincipal(params: { instruction: TransactionInstruction }): LoopscaleInstruction {
+    return { action: LoopscaleAction.REPAY_PRINCIPAL, instruction: params.instruction }
+  },
+  withdrawCollateral(params: { instruction: TransactionInstruction }): LoopscaleInstruction {
+    return { action: LoopscaleAction.WITHDRAW_COLLATERAL, instruction: params.instruction }
+  },
+  closeLoan(params: { instruction: TransactionInstruction }): LoopscaleInstruction {
+    return { action: LoopscaleAction.CLOSE_LOAN, instruction: params.instruction }
+  },
+  /** Assign collateral fractions to ledgers (BORROWER side). Must call before borrow_principal. */
+  updateWeightMatrix(params: { instruction: TransactionInstruction }): LoopscaleInstruction {
+    return { action: LoopscaleAction.UPDATE_WEIGHT_MATRIX, instruction: params.instruction }
+  },
+  createStrategy(params: { instruction: TransactionInstruction }): LoopscaleInstruction {
+    return { action: LoopscaleAction.CREATE_STRATEGY, instruction: params.instruction }
+  },
+  depositStrategy(params: { instruction: TransactionInstruction }): LoopscaleInstruction {
+    return { action: LoopscaleAction.DEPOSIT_STRATEGY, instruction: params.instruction }
+  },
+  withdrawStrategy(params: { instruction: TransactionInstruction }): LoopscaleInstruction {
+    return { action: LoopscaleAction.WITHDRAW_STRATEGY, instruction: params.instruction }
+  },
+  closeStrategy(params: { instruction: TransactionInstruction }): LoopscaleInstruction {
+    return { action: LoopscaleAction.CLOSE_STRATEGY, instruction: params.instruction }
+  },
+  /** Configure collateral terms on a strategy (LENDER side). */
+  updateStrategy(params: { instruction: TransactionInstruction }): LoopscaleInstruction {
+    return { action: LoopscaleAction.UPDATE_STRATEGY, instruction: params.instruction }
+  },
+  /** Lock loan before borrow_principal (BORROWER side). Must be in same tx as unlock. */
+  lockLoan(params: { instruction: TransactionInstruction }): LoopscaleInstruction {
+    return { action: LoopscaleAction.LOCK_LOAN, instruction: params.instruction }
+  },
+  /** Unlock loan after borrow_principal (BORROWER side). Runs health check. */
+  unlockLoan(params: { instruction: TransactionInstruction }): LoopscaleInstruction {
+    return { action: LoopscaleAction.UNLOCK_LOAN, instruction: params.instruction }
+  },
+  /** Refinance a loan ledger from one strategy to another (BORROWER side). */
+  refinanceLedger(params: { instruction: TransactionInstruction }): LoopscaleInstruction {
+    return { action: LoopscaleAction.REFINANCE_LEDGER, instruction: params.instruction }
+  },
+}
+
+// ============================================================================
+// CLMM Action Builder
+// ============================================================================
+
+/**
+ * Builder for Exponent CLMM vault action descriptors.
+ *
+ * Each method returns a `VaultInstruction` descriptor. Pass these to
+ * `createVaultSyncTransaction` which resolves them into raw Solana
+ * instructions, wraps them in a Squads sync transaction, and returns
+ * any extra signers (e.g., the new LP position keypair from deposit).
+ *
+ * @example
+ * ```ts
+ * import { clmmAction, createVaultSyncTransaction } from "@exponent-labs/exponent-sdk"
+ *
+ * const result = await createVaultSyncTransaction({
+ *   instructions: [
+ *     clmmAction.depositLiquidity({
+ *       market: CLMM_MARKET,
+ *       ptInIntent: 1_000_000n,
+ *       syInIntent: 1_000_000n,
+ *       lowerTickKey: 500,
+ *       upperTickKey: 1500,
+ *     }),
+ *   ],
+ *   owner: squadsVault,
+ *   connection,
+ *   vaultPda: squadsVault,
+ *   signer: wallet.publicKey,
+ *   vaultAddress: VAULT_ADDRESS,
+ * })
+ * // result.signers contains the generated LP position keypair
+ * ```
+ */
+export const clmmAction = {
+  /**
+   * Create a new LP position on the CLMM with a specified tick range.
+   * The LP position keypair is generated internally — retrieve it from
+   * `result.signers[0]` after calling `createVaultSyncTransaction`.
+   *
+   * @param params.market - CLMM MarketThree account address
+   * @param params.ptInIntent - Maximum PT to deposit
+   * @param params.syInIntent - Maximum SY to deposit
+   * @param params.lowerTickKey - Lower tick boundary (APY value)
+   * @param params.upperTickKey - Upper tick boundary (APY value)
+   */
+  depositLiquidity(params: {
+    market: PublicKey
+    ptInIntent: bigint
+    syInIntent: bigint
+    lowerTickKey: number
+    upperTickKey: number
+  }): ClmmDepositLiquidityInstruction {
+    return { action: ClmmAction.DEPOSIT_LIQUIDITY, ...params }
+  },
+
+  /**
+   * Add liquidity to an existing LP position.
+   *
+   * @param params.market - CLMM MarketThree account address
+   * @param params.lpPosition - Existing LpPosition account public key
+   * @param params.ptInIntent - Maximum PT to add
+   * @param params.syInIntent - Maximum SY to add
+   */
+  addLiquidity(params: {
+    market: PublicKey
+    lpPosition: PublicKey
+    ptInIntent: bigint
+    syInIntent: bigint
+  }): ClmmAddLiquidityInstruction {
+    return { action: ClmmAction.ADD_LIQUIDITY, ...params }
+  },
+
+  /**
+   * Withdraw liquidity from an LP position, receiving PT + SY.
+   *
+   * @param params.market - CLMM MarketThree account address
+   * @param params.lpPosition - LpPosition account to withdraw from
+   * @param params.lpIn - Amount of liquidity (LP units) to remove
+   * @param params.minPtOut - Minimum PT to receive (slippage protection)
+   * @param params.minSyOut - Minimum SY to receive (slippage protection)
+   */
+  withdrawLiquidity(params: {
+    market: PublicKey
+    lpPosition: PublicKey
+    lpIn: bigint
+    minPtOut: bigint
+    minSyOut: bigint
+  }): ClmmWithdrawLiquidityInstruction {
+    return { action: ClmmAction.WITHDRAW_LIQUIDITY, ...params }
+  },
+
+  /**
+   * Low-level PT/SY swap on the CLMM. Prefer {@link buyPt} / {@link sellPt}
+   * for directional trades.
+   *
+   * @param params.market - CLMM MarketThree account address
+   * @param params.traderAmount - Amount of the input token
+   * @param params.outConstraint - Minimum output amount (slippage protection)
+   * @param params.swapDirection - `SwapDirection.SyToPt` or `SwapDirection.PtToSy`
+   * @param params.lnImpliedApyLimit - Optional price limit (ln implied APY)
+   */
+  tradePt(params: {
+    market: PublicKey
+    traderAmount: bigint
+    outConstraint: bigint
+    swapDirection: SwapDirection
+    lnImpliedApyLimit?: number
+  }): ClmmTradePtInstruction {
+    return { action: ClmmAction.TRADE_PT, ...params }
+  },
+
+  /**
+   * Buy PT with SY on the CLMM.
+   *
+   * @param params.market - CLMM MarketThree account address
+   * @param params.amountSy - Amount of SY to spend
+   * @param params.outConstraint - Minimum PT to receive (slippage protection)
+   * @param params.lnImpliedApyLimit - Optional price limit (ln implied APY)
+   */
+  buyPt(params: {
+    market: PublicKey
+    amountSy: bigint
+    outConstraint: bigint
+    lnImpliedApyLimit?: number
+  }): ClmmBuyPtInstruction {
+    return { action: ClmmAction.BUY_PT, ...params }
+  },
+
+  /**
+   * Sell PT for SY on the CLMM.
+   *
+   * @param params.market - CLMM MarketThree account address
+   * @param params.amountPt - Amount of PT to sell
+   * @param params.outConstraint - Minimum SY to receive (slippage protection)
+   * @param params.lnImpliedApyLimit - Optional price limit (ln implied APY)
+   */
+  sellPt(params: {
+    market: PublicKey
+    amountPt: bigint
+    outConstraint: bigint
+    lnImpliedApyLimit?: number
+  }): ClmmSellPtInstruction {
+    return { action: ClmmAction.SELL_PT, ...params }
+  },
+
+  /**
+   * Buy YT with SY on the CLMM.
+   *
+   * @param params.market - CLMM MarketThree account address
+   * @param params.ytOut - Minimum YT to receive
+   * @param params.maxSyIn - Maximum SY to spend
+   * @param params.lnImpliedApyLimit - Optional price limit (ln implied APY)
+   */
+  buyYt(params: {
+    market: PublicKey
+    ytOut: bigint
+    maxSyIn: bigint
+    lnImpliedApyLimit?: number
+  }): ClmmBuyYtInstruction {
+    return { action: ClmmAction.BUY_YT, ...params }
+  },
+
+  /**
+   * Sell YT for SY on the CLMM.
+   *
+   * @param params.market - CLMM MarketThree account address
+   * @param params.ytIn - Amount of YT to sell
+   * @param params.minSyOut - Minimum SY to receive (slippage protection)
+   * @param params.lnImpliedApyLimit - Optional price limit (ln implied APY)
+   */
+  sellYt(params: {
+    market: PublicKey
+    ytIn: bigint
+    minSyOut: bigint
+    lnImpliedApyLimit?: number
+  }): ClmmSellYtInstruction {
+    return { action: ClmmAction.SELL_YT, ...params }
+  },
+
+  /**
+   * Claim farm emissions from an LP position.
+   *
+   * @param params.market - CLMM MarketThree account address
+   * @param params.lpPosition - LpPosition account to claim from
+   * @param params.farmIndex - Index of the farm emission to claim
+   */
+  claimFarmEmission(params: {
+    market: PublicKey
+    lpPosition: PublicKey
+    farmIndex: number
+  }): ClmmClaimFarmEmissionInstruction {
+    return { action: ClmmAction.CLAIM_FARM_EMISSION, ...params }
+  },
+}
+
+// Re-export SwapDirection for CLMM consumers
+export { SwapDirection }
+
+// ============================================================================
+// Internal: CLMM Instruction Resolution
+// ============================================================================
+
+/** Cache for loaded MarketThree instances to avoid redundant fetches. */
+const marketThreeCache = new Map<string, MarketThree>()
+
+/**
+ * Resolve a high-level CLMM action descriptor into raw Solana instructions.
+ * Loads the MarketThree from cache, derives token accounts from the vault
+ * owner, and delegates to the appropriate sub-builder.
+ */
+async function buildClmmInstruction(
+  ix: ClmmInstruction,
+  owner: PublicKey,
+  connection: Connection,
+  buckets: InstructionBuckets,
+  setupContext?: StrategySetupContext,
+  env: Environment = LOCAL_ENV,
+): Promise<void> {
+  const cacheKey = ix.market.toBase58()
+  let market = marketThreeCache.get(cacheKey)
+  if (!market) {
+    market = await MarketThree.load(env, connection, ix.market)
+    marketThreeCache.set(cacheKey, market)
+  }
+
+  // Ensure PT and SY token accounts are tracked (needed by all CLMM actions)
+  if (setupContext) {
+    await ensureTrackedTokenAccountSetup({
+      tokenMint: market.mintPt,
+      tokenAccount: getAssociatedTokenAddressSync(market.mintPt, owner, true, TOKEN_PROGRAM_ID),
+      tokenProgram: TOKEN_PROGRAM_ID,
+      buckets,
+      setupContext,
+    })
+    await ensureTrackedTokenAccountSetup({
+      tokenMint: market.mintSy,
+      tokenAccount: getAssociatedTokenAddressSync(market.mintSy, owner, true, TOKEN_PROGRAM_ID),
+      tokenProgram: TOKEN_PROGRAM_ID,
+      buckets,
+      setupContext,
+    })
+  }
+
+  // Include the CLMM market's ALT so callers can compress remaining accounts
+  buckets.addressLookupTableAddresses.push(market.addressLookupTable)
+
+  switch (ix.action) {
+    case ClmmAction.DEPOSIT_LIQUIDITY:
+      buildClmmDepositLiquidity(ix, market, owner, buckets)
+      break
+    case ClmmAction.ADD_LIQUIDITY:
+      buildClmmAddLiquidity(ix, market, owner, buckets)
+      break
+    case ClmmAction.WITHDRAW_LIQUIDITY:
+      buildClmmWithdrawLiquidity(ix, market, owner, buckets)
+      break
+    case ClmmAction.TRADE_PT:
+      buildClmmTradePt(ix, market, owner, buckets)
+      break
+    case ClmmAction.BUY_PT:
+      buildClmmBuyPt(ix, market, owner, buckets)
+      break
+    case ClmmAction.SELL_PT:
+      buildClmmSellPt(ix, market, owner, buckets)
+      break
+    case ClmmAction.BUY_YT:
+      await buildClmmBuyYt(ix, market, owner, buckets, setupContext)
+      break
+    case ClmmAction.SELL_YT:
+      await buildClmmSellYt(ix, market, owner, buckets, setupContext)
+      break
+    case ClmmAction.CLAIM_FARM_EMISSION:
+      buildClmmClaimFarmEmission(ix, market, owner, buckets)
+      break
+  }
+}
+
+/**
+ * Create a new LP position. Generates the keypair internally and adds it
+ * to `buckets.signers` so consumers can include it in the transaction.
+ */
+function buildClmmDepositLiquidity(
+  ix: ClmmDepositLiquidityInstruction,
+  market: MarketThree,
+  owner: PublicKey,
+  buckets: InstructionBuckets,
+): void {
+  const ptSrc = getAssociatedTokenAddressSync(market.mintPt, owner, true, TOKEN_PROGRAM_ID)
+  const sySrc = getAssociatedTokenAddressSync(market.mintSy, owner, true, TOKEN_PROGRAM_ID)
+
+  const { ix: depositIx, signers: lpPositionKeypair } = market.ixDepositLiquidity({
+    depositor: owner,
+    ptInIntent: ix.ptInIntent,
+    syInIntent: ix.syInIntent,
+    lowerTickKey: ix.lowerTickKey,
+    upperTickKey: ix.upperTickKey,
+    ptSrc,
+    sySrc,
+  })
+
+  buckets.syncInstructions.push(depositIx)
+  buckets.signers.push(lpPositionKeypair)
+}
+
+/** Add liquidity to an existing LP position. */
+function buildClmmAddLiquidity(
+  ix: ClmmAddLiquidityInstruction,
+  market: MarketThree,
+  owner: PublicKey,
+  buckets: InstructionBuckets,
+): void {
+  const ptSrc = getAssociatedTokenAddressSync(market.mintPt, owner, true, TOKEN_PROGRAM_ID)
+  const sySrc = getAssociatedTokenAddressSync(market.mintSy, owner, true, TOKEN_PROGRAM_ID)
+
+  const remainingAccounts = uniqueRemainingAccounts([
+    ...market.cpiSyAccounts.depositSy,
+    ...market.cpiSyAccounts.withdrawSy,
+    ...market.cpiCoreAccounts.stripSy,
+    ...market.cpiSyAccounts.getPositionState,
+  ])
+
+  const addLiqIx = exponentClmm.createAddLiquidityInstruction(
+    {
+      owner,
+      market: market.selfAddress,
+      ticks: market.ticksKey,
+      lpPosition: ix.lpPosition,
+      tokenPtSrc: ptSrc,
+      tokenSySrc: sySrc,
+      tokenPtEscrow: market.tokenPtEscrow,
+      tokenSyEscrow: market.tokenSyEscrow,
+      addressLookupTable: market.addressLookupTable,
+      tokenProgram: TOKEN_PROGRAM_ID,
+      syProgram: market.syProgram,
+      instructionsSysvar: SYSVAR_INSTRUCTIONS_PUBKEY,
+      systemProgram: SystemProgram.programId,
+      rent: SYSVAR_RENT_PUBKEY,
+      eventAuthority: market.eventAuthority,
+      program: exponentClmm.EXPONENTCLMM_PROGRAM_ID,
+    },
+    {
+      maxSyInToAdd: ix.syInIntent,
+      maxPtInToAdd: ix.ptInIntent,
+      lowerTickKeyOptional: null,
+      upperTickKeyOptional: null,
+    },
+  )
+  addLiqIx.keys.push(...remainingAccounts)
+
+  buckets.syncInstructions.push(addLiqIx)
+}
+
+/** Remove liquidity from an LP position. */
+function buildClmmWithdrawLiquidity(
+  ix: ClmmWithdrawLiquidityInstruction,
+  market: MarketThree,
+  owner: PublicKey,
+  buckets: InstructionBuckets,
+): void {
+  const { ixs } = market.ixWithdrawLiquidity({
+    withdrawer: owner,
+    lpPosition: ix.lpPosition,
+    lpIn: ix.lpIn,
+    minPtOut: ix.minPtOut,
+    minSyOut: ix.minSyOut,
+  })
+
+  buckets.syncInstructions.push(...ixs)
+}
+
+/** Low-level PT/SY swap. */
+function buildClmmTradePt(
+  ix: ClmmTradePtInstruction,
+  market: MarketThree,
+  owner: PublicKey,
+  buckets: InstructionBuckets,
+): void {
+  const { ixs } = market.ixTradePt({
+    trader: owner,
+    traderAmount: ix.traderAmount,
+    outConstraint: ix.outConstraint,
+    swapDirection: ix.swapDirection,
+    lnImpliedApyLimit: ix.lnImpliedApyLimit,
+  })
+
+  buckets.syncInstructions.push(...ixs)
+}
+
+/** Buy PT with SY. */
+function buildClmmBuyPt(
+  ix: ClmmBuyPtInstruction,
+  market: MarketThree,
+  owner: PublicKey,
+  buckets: InstructionBuckets,
+): void {
+  const { ixs } = market.ixBuyPt({
+    trader: owner,
+    amountSy: ix.amountSy,
+    outConstraint: ix.outConstraint,
+    lnImpliedApyLimit: ix.lnImpliedApyLimit,
+  })
+
+  buckets.syncInstructions.push(...ixs)
+}
+
+/** Sell PT for SY. */
+function buildClmmSellPt(
+  ix: ClmmSellPtInstruction,
+  market: MarketThree,
+  owner: PublicKey,
+  buckets: InstructionBuckets,
+): void {
+  const { ixs } = market.ixSellPt({
+    trader: owner,
+    amountPt: ix.amountPt,
+    outConstraint: ix.outConstraint,
+    lnImpliedApyLimit: ix.lnImpliedApyLimit,
+  })
+
+  buckets.syncInstructions.push(...ixs)
+}
+
+/** Buy YT with SY. Also ensures YT token account is tracked. */
+async function buildClmmBuyYt(
+  ix: ClmmBuyYtInstruction,
+  market: MarketThree,
+  owner: PublicKey,
+  buckets: InstructionBuckets,
+  setupContext?: StrategySetupContext,
+): Promise<void> {
+  // YT operations need the YT token account tracked
+  if (setupContext) {
+    await ensureTrackedTokenAccountSetup({
+      tokenMint: market.mintYt,
+      tokenAccount: getAssociatedTokenAddressSync(market.mintYt, owner, true, TOKEN_PROGRAM_ID),
+      tokenProgram: TOKEN_PROGRAM_ID,
+      buckets,
+      setupContext,
+    })
+  }
+
+  const { ixs, setupIxs } = market.ixBuyYt({
+    trader: owner,
+    ytOut: ix.ytOut,
+    maxSyIn: ix.maxSyIn,
+    lnImpliedApyLimit: ix.lnImpliedApyLimit,
+  })
+
+  buckets.setupInstructions.push(...setupIxs)
+  buckets.syncInstructions.push(...ixs)
+}
+
+/** Sell YT for SY. Also ensures YT token account is tracked. */
+async function buildClmmSellYt(
+  ix: ClmmSellYtInstruction,
+  market: MarketThree,
+  owner: PublicKey,
+  buckets: InstructionBuckets,
+  setupContext?: StrategySetupContext,
+): Promise<void> {
+  // YT operations need the YT token account tracked
+  if (setupContext) {
+    await ensureTrackedTokenAccountSetup({
+      tokenMint: market.mintYt,
+      tokenAccount: getAssociatedTokenAddressSync(market.mintYt, owner, true, TOKEN_PROGRAM_ID),
+      tokenProgram: TOKEN_PROGRAM_ID,
+      buckets,
+      setupContext,
+    })
+  }
+
+  const { ixs, setupIxs } = market.ixSellYt({
+    trader: owner,
+    ytIn: ix.ytIn,
+    minSyOut: ix.minSyOut,
+    lnImpliedApyLimit: ix.lnImpliedApyLimit,
+  })
+
+  buckets.setupInstructions.push(...setupIxs)
+  buckets.syncInstructions.push(...ixs)
+}
+
+/**
+ * Claim farm emissions from an LP position. Reads the farm info from the
+ * loaded market state and builds the instruction directly.
+ */
+function buildClmmClaimFarmEmission(
+  ix: ClmmClaimFarmEmissionInstruction,
+  market: MarketThree,
+  owner: PublicKey,
+  buckets: InstructionBuckets,
+): void {
+  const farm = market.state.lpFarm.farmEmissions[ix.farmIndex]
+  if (!farm) {
+    throw new Error(`Farm at index ${ix.farmIndex} not found on CLMM market ${ix.market.toBase58()}`)
+  }
+
+  const tokenDst = getAssociatedTokenAddressSync(farm.mint, owner, true, TOKEN_PROGRAM_ID)
+  const tokenFarm = getAssociatedTokenAddressSync(farm.mint, ix.market, true, TOKEN_PROGRAM_ID)
+
+  const claimIx = exponentClmm.createClaimFarmEmissionInstruction(
+    {
+      owner,
+      market: ix.market,
+      ticks: market.ticksKey,
+      lpPosition: ix.lpPosition,
+      tokenDst,
+      mint: farm.mint,
+      tokenFarm,
+      tokenProgram: TOKEN_PROGRAM_ID,
+      eventAuthority: market.eventAuthority,
+      program: exponentClmm.EXPONENTCLMM_PROGRAM_ID,
+    },
+    {
+      amount: exponentClmm.amount("All"),
+    },
+  )
+
+  // Setup: ensure destination ATA exists
+  buckets.setupInstructions.push(
+    createAssociatedTokenAccountIdempotentInstruction(owner, tokenDst, owner, farm.mint),
+  )
+  buckets.syncInstructions.push(claimIx)
+}