@exponent-labs/exponent-sdk 0.9.1 → 0.9.2

package/src/exponentVaults/vault-interaction.ts

@@ -1,5 +1,7 @@
-import { Reserve } from "@exponent-labs/kamino-reserve-deserializer"
+import { BorshCoder, Idl } from "@coral-xyz/anchor"
+import { Fraction, Reserve } from "@exponent-labs/kamino-reserve-deserializer"
 import { fetchKaminoVaultIndex } from "@exponent-labs/exponent-fetcher"
+import { IDL as KaminoVaultIdl } from "@exponent-labs/kamino-vault-idl"
 import { KAMINO_MARKETS, KAMINO_RESERVES, KaminoMarket } from "./kamino-markets"
 import Decimal from "decimal.js"
 import {
@@ -50,6 +52,7 @@ import {
   refreshObligation,
 } from "@exponent-labs/klend-idl/instructions"
 import {
+  AccountLayout,
   TOKEN_PROGRAM_ID,
   NATIVE_MINT,
   getAssociatedTokenAddressSync,
@@ -63,7 +66,18 @@ import {
 } 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 {
+  AccountMeta,
+  AddressLookupTableAccount,
+  Connection,
+  PublicKey,
+  SystemProgram,
+  SYSVAR_INSTRUCTIONS_PUBKEY,
+  SYSVAR_RENT_PUBKEY,
+  TransactionInstruction,
+  TransactionMessage,
+  VersionedTransaction,
+} from "@solana/web3.js"
 import BN from "bn.js"
 
 const KAMINO_FARMS_PROGRAM_ID = new PublicKey("FarmsPZpWu9i7Kky8tPN37rs2TpmMrAZrC7S7vJa91Hr")
@@ -73,6 +87,7 @@ const KAMINO_VAULT_ALLOCATION_STRATEGY_OFFSET = 304
 const KAMINO_VAULT_ALLOCATION_SIZE = 2160
 const KAMINO_VAULT_ALLOCATION_CTOKEN_VAULT_OFFSET = 32
 const KAMINO_VAULT_GLOBAL_CONFIG_SEED = Buffer.from("global_config")
+const KAMINO_VAULT_CODER = new BorshCoder(KaminoVaultIdl as Idl)
 
 // ============================================================================
 // Vault Instruction Types (re-exported from vault-instruction-types.ts)
@@ -306,8 +321,8 @@ export const kaminoVaultAction = {
 
   /**
    * Withdraw Kamino Vault shares back into the vault-owned token account.
-   * When the Kamino Vault currently allocates across multiple reserves,
-   * specify the reserve to disinvest from.
+   * `reserve` is an optional override. When omitted, the SDK plans the
+   * withdraw across the vault's active reserves automatically.
    */
   withdraw(params: {
     vault: PublicKey
@@ -403,54 +418,7 @@ export interface VaultSyncTransactionResult {
   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,
-  autoManagePositions = false,
-  setupContext,
-}: {
+type CreateVaultSyncTransactionParams = {
   instructions: VaultInstruction[]
   owner: PublicKey
   connection: Connection
@@ -469,8 +437,66 @@ export async function createVaultSyncTransaction({
   autoManagePositions?: boolean
   /** Optional shared setup context — when provided, setup state (tracked accounts, positions) is shared across calls, preventing duplicate setup instructions. */
   setupContext?: StrategySetupContext
-}): Promise<VaultSyncTransactionResult> {
+}
+
+/**
+ * Build one or more vault sync transactions from high-level instruction descriptors.
+ *
+ * This is the plural companion to {@link createVaultSyncTransaction}. Most
+ * calls return a single result. Smart Kamino Vault withdraws can expand into
+ * multiple reserve-specific sync transactions when the wrapper needs to split
+ * an oversized withdraw across sequential chunks.
+ */
+export async function createVaultSyncTransactions(
+  params: CreateVaultSyncTransactionParams,
+): Promise<VaultSyncTransactionResult[]> {
+  return buildVaultSyncTransactionResults(params, true)
+}
+
+/**
+ * Build exactly one vault sync transaction and return its wrapped instruction set.
+ *
+ * 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.
+ *
+ * When a smart Kamino Vault withdraw expands beyond one sync transaction, this
+ * singular helper throws and asks the caller to use
+ * {@link createVaultSyncTransactions} or {@link VaultTransactionBuilder}.
+ */
+export async function createVaultSyncTransaction(
+  params: CreateVaultSyncTransactionParams,
+): Promise<VaultSyncTransactionResult> {
+  const results = await buildVaultSyncTransactionResults(params, false)
+  return results[0]!
+}
+
+async function buildVaultSyncTransactionResults(
+  {
+    instructions,
+    owner,
+    connection,
+    policyPda,
+    vaultPda,
+    signer,
+    accountIndex = 0,
+    constraintIndices,
+    vaultAddress,
+    leadingAccounts,
+    preHookAccounts,
+    postHookAccounts,
+    squadsProgram = SQUADS_PROGRAM_ID,
+    autoManagePositions = false,
+    setupContext,
+  }: CreateVaultSyncTransactionParams,
+  splitOversizedKaminoVaultWithdraw: boolean,
+): Promise<VaultSyncTransactionResult[]> {
   vaultPda ??= owner
+
   const resolvedSetupContext = setupContext ?? createStrategySetupContext({
     connection,
     env: LOCAL_ENV,
@@ -486,7 +512,8 @@ export async function createVaultSyncTransaction({
     postHookAccounts,
     autoManagePositions,
   })
-  const { setupInstructions, syncInstructions, preInstructions, postInstructions, signers, addressLookupTableAddresses } = await buildVaultInstructions(
+
+  const buckets = await buildVaultInstructions(
     instructions,
     owner,
     connection,
@@ -502,10 +529,149 @@ export async function createVaultSyncTransaction({
     autoManagePositions,
     resolvedSetupContext,
   )
+
   const setupStatePriceRefreshInstructions = setupContext
     ? []
     : await buildSetupStatePriceRefreshInstructions(resolvedSetupContext)
 
+  const fullResult = await buildWrappedVaultSyncTransactionResult({
+    connection,
+    policyPda,
+    vaultPda,
+    signer,
+    accountIndex,
+    constraintIndices,
+    vaultAddress,
+    leadingAccounts,
+    preHookAccounts,
+    postHookAccounts,
+    squadsProgram,
+    syncInstructions: buckets.syncInstructions,
+    setupInstructions: buckets.setupInstructions,
+    preInstructions: [...setupStatePriceRefreshInstructions, ...buckets.preInstructions],
+    postInstructions: buckets.postInstructions,
+    signers: buckets.signers,
+    addressLookupTableAddresses: buckets.addressLookupTableAddresses,
+  })
+
+  const isPlannerExpandedKaminoVaultWithdraw =
+    instructions.length === 1
+    && instructions[0]?.action === KaminoVaultAction.WITHDRAW
+    && !(instructions[0] as KaminoVaultWithdrawInstruction).reserve
+    && buckets.syncInstructions.length > 1
+
+  if (!isPlannerExpandedKaminoVaultWithdraw) {
+    return [fullResult]
+  }
+
+  if (await vaultSyncResultFitsInSingleTransaction({
+    connection,
+    payer: signer,
+    result: fullResult,
+  })) {
+    return [fullResult]
+  }
+
+  if (!splitOversizedKaminoVaultWithdraw) {
+    throw new Error(
+      "Kamino Vault withdraw expands beyond one sync transaction; use createVaultSyncTransactions() or VaultTransactionBuilder.",
+    )
+  }
+
+  if (buckets.preInstructions.length > 0 || buckets.postInstructions.length > 0) {
+    throw new Error(
+      "Kamino Vault withdraw chunking only supports sync-only actions; use explicit reserve overrides if you need custom refresh handling.",
+    )
+  }
+
+  const splitResults: VaultSyncTransactionResult[] = []
+  for (const [index, syncInstruction] of buckets.syncInstructions.entries()) {
+    const chunkConstraintIndices = constraintIndices
+      ? constraintIndices.length === buckets.syncInstructions.length
+        ? [constraintIndices[index]!]
+        : constraintIndices.length === 1
+          ? constraintIndices
+          : (() => {
+            throw new Error(
+              "constraintIndices must contain either one entry or one entry per generated sync instruction when splitting a Kamino Vault withdraw.",
+            )
+          })()
+      : undefined
+
+    const chunkResult = await buildWrappedVaultSyncTransactionResult({
+      connection,
+      policyPda,
+      vaultPda,
+      signer,
+      accountIndex,
+      constraintIndices: chunkConstraintIndices,
+      vaultAddress,
+      leadingAccounts,
+      preHookAccounts,
+      postHookAccounts,
+      squadsProgram,
+      syncInstructions: [syncInstruction],
+      setupInstructions: index === 0 ? buckets.setupInstructions : [],
+      preInstructions: index === 0 ? [...setupStatePriceRefreshInstructions] : [],
+      postInstructions: [],
+      signers: buckets.signers,
+      addressLookupTableAddresses: buckets.addressLookupTableAddresses,
+    })
+
+    const chunkFits = await vaultSyncResultFitsInSingleTransaction({
+      connection,
+      payer: signer,
+      result: chunkResult,
+    })
+    if (!chunkFits) {
+      throw new Error(
+        `Kamino Vault withdraw chunk ${index + 1} still exceeds one sync transaction; use explicit reserve overrides or smaller steps.`,
+      )
+    }
+
+    splitResults.push(chunkResult)
+  }
+
+  return splitResults
+}
+
+async function buildWrappedVaultSyncTransactionResult({
+  connection,
+  policyPda,
+  vaultPda,
+  signer,
+  accountIndex,
+  constraintIndices,
+  vaultAddress,
+  leadingAccounts,
+  preHookAccounts,
+  postHookAccounts,
+  squadsProgram,
+  syncInstructions,
+  setupInstructions,
+  preInstructions,
+  postInstructions,
+  signers,
+  addressLookupTableAddresses,
+}: {
+  connection: Connection
+  policyPda?: PublicKey
+  vaultPda: PublicKey
+  signer: PublicKey
+  accountIndex: number
+  constraintIndices?: number[]
+  vaultAddress?: PublicKey
+  leadingAccounts?: PublicKey[] | AccountMeta[]
+  preHookAccounts?: PublicKey[] | AccountMeta[]
+  postHookAccounts?: PublicKey[] | AccountMeta[]
+  squadsProgram: PublicKey
+  syncInstructions: TransactionInstruction[]
+  setupInstructions: TransactionInstruction[]
+  preInstructions: TransactionInstruction[]
+  postInstructions: TransactionInstruction[]
+  signers: web3.Signer[]
+  addressLookupTableAddresses: PublicKey[]
+}): Promise<VaultSyncTransactionResult> {
   let resolvedPolicyPda = policyPda
   let resolvedConstraintIndices = constraintIndices
   if (!resolvedPolicyPda) {
@@ -517,14 +683,12 @@ export async function createVaultSyncTransaction({
     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
@@ -550,7 +714,7 @@ export async function createVaultSyncTransaction({
 
   return {
     setupInstructions,
-    preInstructions: [...setupStatePriceRefreshInstructions, ...preInstructions],
+    preInstructions,
     instruction,
     postInstructions,
     signers,
@@ -558,6 +722,38 @@ export async function createVaultSyncTransaction({
   }
 }
 
+async function vaultSyncResultFitsInSingleTransaction(params: {
+  connection: Connection
+  payer: PublicKey
+  result: VaultSyncTransactionResult
+}): Promise<boolean> {
+  try {
+    const altAccounts = await resolveVaultSyncAltAccounts(
+      params.connection,
+      params.result.addressLookupTableAddresses,
+    )
+    const message = new TransactionMessage({
+      payerKey: params.payer,
+      recentBlockhash: PublicKey.default.toBase58(),
+      instructions: [...params.result.preInstructions, params.result.instruction, ...params.result.postInstructions],
+    }).compileToV0Message(altAccounts)
+
+    return new VersionedTransaction(message).serialize().length <= 1232
+  } catch {
+    return false
+  }
+}
+
+async function resolveVaultSyncAltAccounts(
+  connection: Connection,
+  addresses: PublicKey[],
+): Promise<AddressLookupTableAccount[]> {
+  const lookupTables = await Promise.all(addresses.map((address) => connection.getAddressLookupTable(address)))
+  return lookupTables
+    .map((entry) => entry.value)
+    .filter((entry): entry is AddressLookupTableAccount => entry !== null)
+}
+
 // ============================================================================
 // Internal: Instruction Assembly
 // ============================================================================
@@ -1698,10 +1894,32 @@ const KAMINO_VAULT_EVENT_AUTHORITY = emitEventAuthority(KAMINO_VAULT_PROGRAM_ID)
 const KAMINO_FARM_USER_STATE_SIZE = 920
 const KAMINO_STAKE_ALL_AMOUNT = new BN("18446744073709551615")
 
+type KaminoVaultIndex = Awaited<ReturnType<typeof fetchKaminoVaultIndex>>
+
+type KaminoVaultDecodedState = {
+  tokenAvailable: BN
+  sharesIssued: BN
+  pendingFeesSf: BN
+  allocations: Array<{
+    reserve: PublicKey
+    ctokenAllocation: BN
+  }>
+}
+
+type KaminoVaultResolvedReserve = KaminoVaultIndex["reserves"][number] & {
+  account: Reserve
+  investedLiquidityAmount: Decimal
+  availableLiquidityToWithdraw: Decimal
+}
+
 type KaminoVaultContext = {
-  index: Awaited<ReturnType<typeof fetchKaminoVaultIndex>>
+  index: Omit<KaminoVaultIndex, "reserves"> & {
+    reserves: KaminoVaultResolvedReserve[]
+  }
   tokenAta: PublicKey
   sharesAta: PublicKey
+  sharesBalance: BN
+  state: KaminoVaultDecodedState
 }
 
 type KaminoFarmContext = {
@@ -1720,6 +1938,10 @@ function toBn(value: BN | bigint | number): BN {
   return new BN(value.toString())
 }
 
+function minBn(lhs: BN, rhs: BN): BN {
+  return lhs.lte(rhs) ? lhs : rhs
+}
+
 function encodeU64InstructionData(discriminator: Buffer, value: BN | bigint | number): Buffer {
   return Buffer.concat([discriminator, toBn(value).toArrayLike(Buffer, "le", 8)])
 }
@@ -1814,6 +2036,151 @@ function resolveKaminoVaultTrackedPriceId(params: {
   return { __kind: "Multiply", priceIds: [...reservePriceIds, params.sharePriceId] }
 }
 
+type KaminoVaultWithdrawPlanningSnapshot = {
+  sharesBalance: BN
+  tokenAvailable: BN
+  sharesIssued: BN
+  pendingFeesSf: BN
+  reserves: Array<{
+    reserveAddress: PublicKey
+    investedLiquidityAmount: Decimal
+    availableLiquidityToWithdraw: Decimal
+  }>
+}
+
+type KaminoVaultWithdrawPlanningLeg = {
+  reserveAddress: PublicKey
+  sharesAmount: BN
+}
+
+function decodeKaminoVaultState(data: Buffer): KaminoVaultDecodedState {
+  const decoded = KAMINO_VAULT_CODER.accounts.decode("VaultState", data) as {
+    token_available: BN
+    shares_issued: BN
+    pending_fees_sf: BN
+    vault_allocation_strategy: Array<{
+      reserve: PublicKey
+      ctoken_allocation: BN
+    }>
+  }
+
+  return {
+    tokenAvailable: decoded.token_available,
+    sharesIssued: decoded.shares_issued,
+    pendingFeesSf: decoded.pending_fees_sf,
+    allocations: decoded.vault_allocation_strategy
+      .filter((allocation) => !allocation.reserve.equals(PublicKey.default))
+      .map((allocation) => ({
+        reserve: allocation.reserve,
+        ctokenAllocation: allocation.ctoken_allocation,
+      })),
+  }
+}
+
+function calculateKaminoVaultTokensPerShareFromSnapshot(
+  snapshot: KaminoVaultWithdrawPlanningSnapshot,
+): Decimal {
+  if (snapshot.sharesIssued.isZero()) {
+    return new Decimal(0)
+  }
+
+  const investedTotal = snapshot.reserves.reduce(
+    (total, reserve) => total.add(reserve.investedLiquidityAmount),
+    new Decimal(0),
+  )
+  const pendingFees = new Fraction(snapshot.pendingFeesSf).toDecimal()
+  const currentVaultAum = new Decimal(snapshot.tokenAvailable.toString())
+    .add(investedTotal)
+    .sub(pendingFees)
+
+  if (currentVaultAum.lte(0)) {
+    return new Decimal(0)
+  }
+
+  return currentVaultAum.div(snapshot.sharesIssued.toString())
+}
+
+function planKaminoVaultWithdrawLegsFromSnapshot(params: {
+  sharesAmount: BN
+  reserve?: PublicKey
+  snapshot: KaminoVaultWithdrawPlanningSnapshot
+}): KaminoVaultWithdrawPlanningLeg[] {
+  if (params.reserve) {
+    return [{ reserveAddress: params.reserve, sharesAmount: params.sharesAmount }]
+  }
+
+  const actualSharesToWithdraw = minBn(params.sharesAmount, params.snapshot.sharesBalance)
+  if (actualSharesToWithdraw.isZero()) {
+    throw new Error("Cannot withdraw zero Kamino Vault shares")
+  }
+
+  if (params.snapshot.reserves.length === 0) {
+    throw new Error("Kamino Vault has no active reserves to anchor a reserve-specific withdraw instruction")
+  }
+
+  const withdrawAllShares = params.sharesAmount.gte(params.snapshot.sharesBalance)
+  const tokensPerShare = calculateKaminoVaultTokensPerShareFromSnapshot(params.snapshot)
+  if (tokensPerShare.lte(0)) {
+    throw new Error("Kamino Vault has zero share price; cannot plan a withdraw")
+  }
+
+  const tokensToWithdraw = new Decimal(actualSharesToWithdraw.toString()).mul(tokensPerShare)
+  const availableTokens = new Decimal(params.snapshot.tokenAvailable.toString())
+
+  if (tokensToWithdraw.lte(availableTokens)) {
+    return [{
+      reserveAddress: params.snapshot.reserves[0]!.reserveAddress,
+      sharesAmount: withdrawAllShares ? params.snapshot.sharesBalance : actualSharesToWithdraw,
+    }]
+  }
+
+  let tokensRemaining = tokensToWithdraw
+  const plannedLegs: KaminoVaultWithdrawPlanningLeg[] = []
+  const sortedReserves = [...params.snapshot.reserves].sort((lhs, rhs) =>
+    rhs.availableLiquidityToWithdraw.comparedTo(lhs.availableLiquidityToWithdraw),
+  )
+
+  for (const [index, reserve] of sortedReserves.entries()) {
+    const legCapacity = reserve.availableLiquidityToWithdraw.add(index === 0 ? availableTokens : 0)
+    if (legCapacity.lte(0)) {
+      continue
+    }
+
+    const tokensForLeg = Decimal.min(tokensRemaining, legCapacity)
+    if (tokensForLeg.lte(0)) {
+      continue
+    }
+
+    const sharesForLeg = withdrawAllShares
+      ? params.snapshot.sharesBalance
+      : new BN(tokensForLeg.div(tokensPerShare).floor().toFixed(0))
+    if (sharesForLeg.isZero()) {
+      continue
+    }
+
+    plannedLegs.push({
+      reserveAddress: reserve.reserveAddress,
+      sharesAmount: sharesForLeg,
+    })
+
+    tokensRemaining = tokensRemaining.sub(tokensForLeg)
+    if (tokensRemaining.lte(0)) {
+      break
+    }
+  }
+
+  if (plannedLegs.length === 0) {
+    throw new Error("Unable to plan a Kamino Vault withdraw across the vault's active reserves")
+  }
+
+  return plannedLegs
+}
+
+export const __kaminoVaultTesting = {
+  calculateKaminoVaultTokensPerShareFromSnapshot,
+  planKaminoVaultWithdrawLegsFromSnapshot,
+}
+
 async function resolveKaminoVaultContext(
   vaultAddress: PublicKey,
   setupContext: StrategySetupContext,
@@ -1833,6 +2200,7 @@ async function resolveKaminoVaultContext(
     throw new Error(`Kamino vault account not found: ${vaultAddress.toBase58()}`)
   }
 
+  const decodedVaultState = decodeKaminoVaultState(Buffer.from(vaultInfo.data))
   const decodedReserves = reserveInfos.map((reserveInfo, index) => {
     if (!reserveInfo?.data) {
       throw new Error(`Missing Kamino reserve account ${reserveAddresses[index]!.toBase58()}`)
@@ -1844,6 +2212,7 @@ async function resolveKaminoVaultContext(
   )
   const normalizedReserves = reserveAddresses.map((reserveAddress, index) => {
     const reserveAccount = decodedReserves[index]!
+    const allocation = decodedVaultState.allocations[index]
     const rawReserve = rawIndex.reserves[index] as typeof rawIndex.reserves[number] & {
       reserve?: PublicKey
       marketAddress?: PublicKey
@@ -1866,6 +2235,13 @@ async function resolveKaminoVaultContext(
       [Buffer.from("lma"), reserveAccount.lendingMarket.toBuffer()],
       KAMINO_LENDING_PROGRAM_ID,
     )
+    const investedLiquidityAmount = allocation
+      ? new Decimal(allocation.ctokenAllocation.toString()).mul(reserveAccount.getCollateralExchangeRate())
+      : new Decimal(0)
+    const availableLiquidityToWithdraw = Decimal.min(
+      investedLiquidityAmount,
+      reserveAccount.getLiquidityAvailableAmount(),
+    )
 
     return {
       reserveAddress,
@@ -1886,6 +2262,9 @@ async function resolveKaminoVaultContext(
       reserveCollateralMint: rawReserve.reserveCollateralMint ?? reserveAccount.collateral.mintPubkey,
       reserveCollateralTokenProgram:
         rawReserve.reserveCollateralTokenProgram ?? collateralMintInfos[index]?.owner ?? PublicKey.default,
+      account: reserveAccount,
+      investedLiquidityAmount,
+      availableLiquidityToWithdraw,
     }
   })
   const index = {
@@ -1901,7 +2280,11 @@ async function resolveKaminoVaultContext(
   }
   const tokenAta = getAssociatedTokenAddressSync(index.tokenMint, setupContext.owner, true, index.tokenProgram)
   const sharesAta = getAssociatedTokenAddressSync(index.sharesMint, setupContext.owner, true, index.sharesTokenProgram)
-  return { index, tokenAta, sharesAta }
+  const sharesAtaInfo = await setupContext.connection.getAccountInfo(sharesAta)
+  const sharesBalance = sharesAtaInfo?.data
+    ? new BN(AccountLayout.decode(sharesAtaInfo.data).amount.toString())
+    : new BN(0)
+  return { index, tokenAta, sharesAta, sharesBalance, state: decodedVaultState }
 }
 
 async function queueKaminoVaultSharesTracking(params: {
@@ -2060,36 +2443,76 @@ function buildKaminoVaultDepositInstruction(params: {
   })
 }
 
-function resolveKaminoVaultWithdrawReserve(
+function resolveExplicitKaminoVaultWithdrawReserve(
   ix: KaminoVaultWithdrawInstruction,
   vaultContext: KaminoVaultContext,
 ): KaminoVaultContext["index"]["reserves"][number] {
-  if (ix.reserve) {
-    const reserve = vaultContext.index.reserves.find((entry) => entry.reserveAddress.equals(ix.reserve!))
-    if (!reserve) {
-      throw new Error(
-        `Kamino Vault ${ix.vault.toBase58()} does not use reserve ${ix.reserve.toBase58()}`,
-      )
-    }
-    return reserve
+  if (!ix.reserve) {
+    throw new Error("reserve is required when resolving an explicit Kamino Vault withdraw reserve")
   }
 
-  if (vaultContext.index.reserves.length !== 1) {
+  const reserve = vaultContext.index.reserves.find((entry) => entry.reserveAddress.equals(ix.reserve))
+  if (!reserve) {
     throw new Error(
-      `Kamino Vault ${ix.vault.toBase58()} uses ${vaultContext.index.reserves.length} reserves; specify withdraw.reserve`,
+      `Kamino Vault ${ix.vault.toBase58()} does not use reserve ${ix.reserve.toBase58()}`,
     )
   }
 
-  return vaultContext.index.reserves[0]!
+  return reserve
+}
+
+function planKaminoVaultWithdrawLegs(
+  ix: KaminoVaultWithdrawInstruction,
+  vaultContext: KaminoVaultContext,
+): Array<{
+  reserve: KaminoVaultContext["index"]["reserves"][number]
+  sharesAmount: BN
+}> {
+  if (ix.reserve) {
+    return [{
+      reserve: resolveExplicitKaminoVaultWithdrawReserve(ix, vaultContext),
+      sharesAmount: ix.sharesAmount,
+    }]
+  }
+
+  const plannedLegs = planKaminoVaultWithdrawLegsFromSnapshot({
+    sharesAmount: ix.sharesAmount,
+    snapshot: {
+      sharesBalance: vaultContext.sharesBalance,
+      tokenAvailable: vaultContext.state.tokenAvailable,
+      sharesIssued: vaultContext.state.sharesIssued,
+      pendingFeesSf: vaultContext.state.pendingFeesSf,
+      reserves: vaultContext.index.reserves.map((reserve) => ({
+        reserveAddress: reserve.reserveAddress,
+        investedLiquidityAmount: reserve.investedLiquidityAmount,
+        availableLiquidityToWithdraw: reserve.availableLiquidityToWithdraw,
+      })),
+    },
+  })
+
+  return plannedLegs.map((leg) => {
+    const reserve = vaultContext.index.reserves.find((entry) => entry.reserveAddress.equals(leg.reserveAddress))
+    if (!reserve) {
+      throw new Error(
+        `Kamino Vault ${ix.vault.toBase58()} does not use reserve ${leg.reserveAddress.toBase58()}`,
+      )
+    }
+
+    return {
+      reserve,
+      sharesAmount: leg.sharesAmount,
+    }
+  })
 }
 
 function buildKaminoVaultWithdrawInstruction(params: {
   owner: PublicKey
   ix: KaminoVaultWithdrawInstruction
+  reserve: KaminoVaultContext["index"]["reserves"][number]
+  sharesAmount: BN
   vaultContext: KaminoVaultContext
   validationAccounts?: AccountMeta[]
 }): TransactionInstruction {
-  const reserve = resolveKaminoVaultWithdrawReserve(params.ix, params.vaultContext)
   const [globalConfig] = PublicKey.findProgramAddressSync(
     [KAMINO_VAULT_GLOBAL_CONFIG_SEED],
     KAMINO_VAULT_PROGRAM_ID,
@@ -2112,13 +2535,13 @@ function buildKaminoVaultWithdrawInstruction(params: {
       { pubkey: KAMINO_VAULT_EVENT_AUTHORITY, isSigner: false, isWritable: false },
       { pubkey: KAMINO_VAULT_PROGRAM_ID, isSigner: false, isWritable: false },
       { pubkey: params.ix.vault, isSigner: false, isWritable: true },
-      { pubkey: reserve.reserveAddress, isSigner: false, isWritable: true },
-      { pubkey: reserve.ctokenVault, isSigner: false, isWritable: true },
-      { pubkey: reserve.marketAddress, isSigner: false, isWritable: false },
-      { pubkey: reserve.lendingMarketAuthority, isSigner: false, isWritable: false },
-      { pubkey: reserve.reserveLiquiditySupply, isSigner: false, isWritable: true },
-      { pubkey: reserve.reserveCollateralMint, isSigner: false, isWritable: true },
-      { pubkey: reserve.reserveCollateralTokenProgram, isSigner: false, isWritable: false },
+      { pubkey: params.reserve.reserveAddress, isSigner: false, isWritable: true },
+      { pubkey: params.reserve.ctokenVault, isSigner: false, isWritable: true },
+      { pubkey: params.reserve.marketAddress, isSigner: false, isWritable: false },
+      { pubkey: params.reserve.lendingMarketAuthority, isSigner: false, isWritable: false },
+      { pubkey: params.reserve.reserveLiquiditySupply, isSigner: false, isWritable: true },
+      { pubkey: params.reserve.reserveCollateralMint, isSigner: false, isWritable: true },
+      { pubkey: params.reserve.reserveCollateralTokenProgram, isSigner: false, isWritable: false },
       { pubkey: SYSVAR_INSTRUCTIONS_PUBKEY, isSigner: false, isWritable: false },
       { pubkey: KAMINO_VAULT_EVENT_AUTHORITY, isSigner: false, isWritable: false },
       { pubkey: KAMINO_VAULT_PROGRAM_ID, isSigner: false, isWritable: false },
@@ -2129,7 +2552,7 @@ function buildKaminoVaultWithdrawInstruction(params: {
       })),
       ...(params.validationAccounts ?? []),
     ],
-    data: encodeU64InstructionData(KAMINO_VAULT_DISCRIMINATORS.withdraw, params.ix.sharesAmount),
+    data: encodeU64InstructionData(KAMINO_VAULT_DISCRIMINATORS.withdraw, params.sharesAmount),
   })
 }
 
@@ -2193,12 +2616,17 @@ async function buildKaminoVaultInstruction(
     return
   }
 
-  buckets.syncInstructions.push(buildKaminoVaultWithdrawInstruction({
-    owner: setupContext.owner,
-    ix,
-    vaultContext,
-    validationAccounts,
-  }))
+  const withdrawLegs = planKaminoVaultWithdrawLegs(ix, vaultContext)
+  for (const leg of withdrawLegs) {
+    buckets.syncInstructions.push(buildKaminoVaultWithdrawInstruction({
+      owner: setupContext.owner,
+      ix,
+      reserve: leg.reserve,
+      sharesAmount: leg.sharesAmount,
+      vaultContext,
+      validationAccounts,
+    }))
+  }
 }
 
 function getOptionalReadonlyAccountMeta(account: PublicKey | null, placeholderProgram: PublicKey): AccountMeta {