@exponent-labs/exponent-sdk 0.1.7 → 0.9.0

package/src/exponentVaults/loopscale-client.ts

@@ -0,0 +1,1373 @@
+import {
+  type AccountMeta,
+  type Commitment,
+  type Finality,
+  type SendOptions,
+  type Signer,
+  ComputeBudgetProgram,
+  Connection,
+  PublicKey,
+  SystemProgram,
+  TransactionInstruction,
+  TransactionMessage,
+  VersionedMessage,
+  VersionedTransaction,
+} from "@solana/web3.js"
+
+import { LOOPSCALE_DISCRIMINATORS, LOOPSCALE_PROGRAM_ID } from "./policyBuilders"
+import { type LoopscaleInstruction, LoopscaleAction, loopscaleAction, createVaultSyncTransaction } from "./vault-interaction"
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const LOOPSCALE_API_BASE_URL = "https://tars.loopscale.com/v1"
+const BS_AUTH = new PublicKey("CyNKPfqsSLAejjZtEeNG3pR4SkPhSPHXdGhuNTyudrNs")
+const ASSOCIATED_TOKEN_PROGRAM_ID = new PublicKey("ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL")
+
+// ============================================================================
+// Types — Config
+// ============================================================================
+
+export interface LoopscaleClientConfig {
+  connection: Connection
+  /** Wallet address sent as `user-wallet` / `payer` header to the Loopscale API. */
+  userWallet: PublicKey | string
+  /** Loopscale API base URL (default: https://tars.loopscale.com/v1). */
+  baseUrl?: string
+  /** Known bs_auth public key (default: CyNKPf...). */
+  bsAuth?: PublicKey
+  /** Use Luke's batch-based MPC endpoint for co-signing (default: true). */
+  useMpcCoSign?: boolean
+  /** Log request/response details to console. */
+  debug?: boolean
+}
+
+// ============================================================================
+// Types — API params
+// ============================================================================
+
+export interface LoopscaleQuoteParams {
+  durationType: number
+  duration: number
+  principal: PublicKey | string
+  collateral: (PublicKey | string)[]
+  limit?: number
+  offset?: number
+}
+
+export interface LoopscaleCreateStrategyParams {
+  principalMint: PublicKey | string
+  lender: PublicKey | string
+  amount: bigint | number
+  originationsEnabled?: boolean
+  liquidityBuffer?: number
+  interestFee?: number
+  originationFee?: number
+  originationCap?: number
+  collateralTerms?: Array<{
+    apy: number
+    indices: Array<{ collateralIndex: number; durationIndex: number }>
+  }>
+  marketInformation?: PublicKey | string
+  externalYieldSourceArgs?: TxnExternalYieldSourceArgs
+}
+
+export interface LoopscaleDepositStrategyParams {
+  strategy: PublicKey | string
+  amount: bigint | number
+}
+
+export interface LoopscaleWithdrawStrategyParams {
+  strategy: PublicKey | string
+  amount: bigint | number
+  withdrawAll: boolean
+}
+
+export interface LoopscaleCloseStrategyParams {
+  strategy: PublicKey | string
+}
+
+export interface ExternalYieldSourceParams {
+  newExternalYieldSource: number
+}
+
+export interface TxnExternalYieldSourceArgs extends ExternalYieldSourceParams {
+  createExternalYieldAccount: boolean
+}
+
+export interface StrategyDuration {
+  duration: number
+  durationType: number
+}
+
+export interface AddCollateralArgs {
+  durationsAndApys?: Record<string, string>
+  externalMarketInformationAddress?: string
+  marketInformation?: Record<string, unknown>
+}
+
+export interface RemoveCollateralArgs {
+  durations: StrategyDuration[]
+  removeFromMarketInformation: boolean
+}
+
+export interface CollateralParamsUpdateArgs {
+  ltvUpdate?: Record<string, unknown>
+  apyUpdate?: Record<string, string>
+}
+
+export interface CollateralAllocationUpdateArgs {
+  assetIdentifier: string
+  maxAllocationPct: string
+}
+
+export interface StrategyCollateralUpdates {
+  addCollateral?: Record<string, AddCollateralArgs>
+  removeCollateral?: Record<string, RemoveCollateralArgs>
+  updateCollateral?: Record<string, CollateralParamsUpdateArgs>
+  updateAssetAllocation?: CollateralAllocationUpdateArgs[]
+}
+
+export interface EditStrategySettingsArgs {
+  originationsEnabled?: boolean
+  liquidityBuffer?: number
+  interestFee?: number
+  originationFee?: number
+  principalFee?: number
+  originationCap?: number
+  externalYieldSource?: ExternalYieldSourceParams
+}
+
+export interface LoopscaleUpdateStrategyParams {
+  strategy: PublicKey | string
+  collateralTerms?: StrategyCollateralUpdates
+  updateParams?: EditStrategySettingsArgs
+}
+
+export interface LoopscaleBorrowPrincipalParams {
+  /** Borrower / vault address (also the payer for ATA creation). */
+  borrower: PublicKey | string
+  /** Existing loan with collateral already deposited. */
+  loan: PublicKey | string
+  /** Strategy supplying principal liquidity. */
+  strategy: PublicKey | string
+  /** MarketInformation account for the borrow strategy. */
+  marketInformation: PublicKey | string
+  /** Mint of the borrowed asset. */
+  principalMint: PublicKey | string
+  /** Amount of principal to borrow (lamports). */
+  amount: bigint | number
+  /** Duration index (0=1day, 1=1week, 2=1month, 3=3months, 4=5min). */
+  durationIndex: number
+  /** Byte buffer consumed by sync_risk_matrices + validate_loan_health. */
+  assetIndexGuidance: number[]
+  /** Oracle remaining accounts for health check (MarketInformation + oracle pubkeys). */
+  healthCheckAccounts: AccountMeta[]
+  expectedApy?: bigint | number
+  /** Expected liquidation thresholds per collateral index [5 entries]. */
+  expectedLqt?: number[]
+  /** Keep result as wSOL instead of unwrapping (default: false). */
+  skipSolUnwrap?: boolean
+}
+
+export interface LoopscaleRepayLoanParams {
+  loan: PublicKey | string
+  repayParams: Array<{
+    amount: bigint | number
+    ledgerIndex: number
+    repayAll: boolean
+  }>
+  collateralWithdrawalParams?: Array<{
+    amount: bigint | number
+    collateralMint: PublicKey | string
+  }>
+  closeIfPossible?: boolean
+}
+
+export interface LoopscaleCloseLoanParams {
+  loan: PublicKey | string
+}
+
+export interface LoopscaleCreateLoanParams {
+  borrower: PublicKey | string
+  depositCollateral: Array<{
+    collateralAmount: bigint | number
+    collateralAssetData: { Spl: { mint: string } } | { Orca: { positionMint: string; whirlpool: string } }
+  }>
+  principalRequested: Array<{
+    ledgerIndex: number
+    principalAmount: bigint | number
+    principalMint: PublicKey | string
+    strategy: PublicKey | string
+    durationIndex: number
+    expectedLoanValues?: { expectedApy?: number; expectedLqt?: number[] }
+  }>
+  assetIndexGuidance?: number[]
+  loanNonce?: string
+  isLoop?: boolean
+}
+
+export interface LoopscaleApiBorrowPrincipalParams {
+  loan: PublicKey | string
+  borrowParams: {
+    amount: bigint | number
+    durationIndex: number
+    expectedLoanValues?: { expectedApy?: number; expectedLqt?: number[] }
+  }
+  strategy: PublicKey | string
+  refinanceParams?: { ledgerIndex: number; durationIndex: number }
+  isLoop?: boolean
+}
+
+export interface LoopscaleDepositCollateralParams {
+  loan: PublicKey | string
+  depositMint: PublicKey | string
+  amount: bigint | number
+  assetType: number
+  assetIdentifier: PublicKey | string
+  assetIndexGuidance?: number[]
+  expectedLoanValues?: { expectedApy?: number; expectedLqt?: number[] }
+}
+
+export interface LoopscaleWithdrawCollateralParams {
+  loan: PublicKey | string
+  collateralMint: PublicKey | string
+  amount: bigint | number
+  collateralIndex: number
+  expectedLoanValues?: { expectedApy?: number; expectedLqt?: number[] }
+  assetIndexGuidance?: number[]
+}
+
+export interface LoopscaleRefinanceLoanParams {
+  loan: PublicKey | string
+  oldStrategy: PublicKey | string
+  newStrategy: PublicKey | string
+  refinanceParams: { ledgerIndex: number; durationIndex: number }
+}
+
+// ── Data query types ──
+
+export interface LoopscaleMaxQuoteParams {
+  durationType: number
+  duration: number
+  principalMint: PublicKey | string
+  collateralFilter: Array<{
+    amount: bigint | number
+    assetData: { Spl: { mint: string } } | { Orca: { positionMint: string; whirlpool: string } }
+  }>
+}
+
+export interface LoopscaleMaxQuote {
+  apy: number
+  strategy: string
+  collateralIdentifier: string
+  ltv: number
+  lqt: number
+  amount: number
+}
+
+export interface LoopscaleLoanInfoParams {
+  loanAddresses?: string[]
+  lenders?: string[]
+  borrowers?: string[]
+  filterType?: number
+  principalMints?: string[]
+  collateralMints?: string[]
+  orderFundingType?: number
+  page?: number
+  pageSize?: number
+  sortDirection?: number
+  sortType?: number
+  assetTypes?: number
+  excludeCollateralIdentifiers?: string[]
+  excludePrincipalMints?: string[]
+}
+
+export interface LoopscaleLoanInfoResponse {
+  totalCount: number
+  loanInfos: Array<{
+    loan: { address: string; loanStatus: number; borrower: string; startTime: number; [key: string]: unknown }
+    loanType: number
+    ledgers: Array<{ ledgerIndex: number; strategy: string; principalMint: string; principalDue: number; interestOutstanding: number; apy: number; endTime: number; [key: string]: unknown }>
+    collateral: Array<{ assetMint: string; amount: number; assetType: number; [key: string]: unknown }>
+    [key: string]: unknown
+  }>
+}
+
+export interface LoopscaleGetStrategiesParams {
+  userAddress?: string
+  addresses?: string[]
+  principalMints?: string[]
+  page?: number
+  pageSize?: number
+}
+
+export interface LoopscaleStrategyInfoResponse {
+  strategies: Array<{
+    strategy: { address: string; principalMint: string; tokenBalance: number; currentDeployedAmount: number; outstandingInterestAmount: number; [key: string]: unknown }
+    externalYieldInfo?: { apy: number }
+  }>
+  total: number
+}
+
+export interface LoopscaleCollateralHoldersParams {
+  mints: string[]
+  pdas?: boolean
+}
+
+export interface LoopscaleCollateralHolder {
+  collateralMint: string
+  totalDeposits: number
+  userDeposits: Record<string, number>
+}
+
+export interface LoopscaleHistoricalCollateralHoldersParams {
+  mint: string
+  rangeStart?: number
+  rangeEnd?: number
+  pdas?: boolean
+}
+
+export interface LoopscaleHistoricalCollateralHolder {
+  collateralMint: string
+  rangeStart: number
+  rangeEnd: number
+  userDepositSeconds: Record<string, number>
+}
+
+export interface LoopscaleVaultDepositorsParams {
+  vaultAddresses?: string[]
+  principalMints?: string[]
+}
+
+export interface LoopscaleVaultDepositor {
+  vaultAddress: string
+  userDeposits: Array<{ userAddress: string; amountSupplied: string }>
+}
+
+export interface LoopscaleVaultInfoParams {
+  vaultAddresses?: string[]
+  vaultIdentifiers?: string[]
+  principalMints?: string[]
+  includeRewards?: boolean
+  page: number
+  pageSize: number
+}
+
+export interface LoopscaleVaultInfoResponse {
+  lendVaults: Array<{
+    vault: { address: string; vaultIdentifier: string; principalMint: string; lpMint: string }
+    vaultMetadata: { name: string; description: string; managerName: string; depositCap: number }
+    vaultStrategy: { strategy: { address: string; tokenBalance: number; currentDeployedAmount: number; [key: string]: unknown } }
+    [key: string]: unknown
+  }>
+  total: number
+}
+
+export interface LoopscaleLoopInfoParams {
+  loopVaults?: string[]
+  tags?: string[]
+}
+
+export interface LoopscaleLoopVaultInfo {
+  collateralMint: string
+  principalMint: string
+  collateralDeposited: number
+  collateralApyPct: number
+  maxLeverage: number
+  name: string
+  maxLeveragedApyPct: number
+  principalAmountAvailable: number
+  [key: string]: unknown
+}
+
+// ============================================================================
+// Types — Results
+// ============================================================================
+
+export interface LoopscaleGeneratedInstruction {
+  name: LoopscaleInstructionName | null
+  instruction: TransactionInstruction
+}
+
+export interface LoopscaleGeneratedInstructionBundle {
+  transaction: VersionedTransaction
+  instructions: TransactionInstruction[]
+  loopscaleInstructions: LoopscaleGeneratedInstruction[]
+}
+
+export interface LoopscaleTxResult {
+  /** Loopscale instructions wrapped via loopscaleAction.* — ready for createVaultSyncTransaction. */
+  syncActions: LoopscaleInstruction[]
+  /** Non-Loopscale instructions that belong outside the sync tx (compute budget, etc.). */
+  topLevelInstructions: TransactionInstruction[]
+  /** Raw decompiled bundle. */
+  raw: LoopscaleGeneratedInstructionBundle
+}
+
+export interface LoopscaleStrategyBatch {
+  /** Loopscale instructions wrapped via loopscaleAction.* — ready for createVaultSyncTransaction. */
+  syncActions: LoopscaleInstruction[]
+  /** Non-Loopscale instructions that belong outside the sync tx (compute budget, oracles, etc.). */
+  topLevelInstructions: TransactionInstruction[]
+  /** Setup instructions returned by Loopscale that should not be wrapped in the sync tx. */
+  setupInstructions: TransactionInstruction[]
+  /** Raw decompiled batch. */
+  raw: LoopscaleGeneratedInstructionBundle
+}
+
+export interface LoopscaleStrategyBatchesResult {
+  batches: LoopscaleStrategyBatch[]
+}
+
+export interface LoopscaleStrategyResult extends LoopscaleStrategyBatchesResult {
+  strategyAddress: PublicKey
+  noncePublicKey: PublicKey
+}
+
+export interface LoopscaleUpdateStrategyResult extends LoopscaleStrategyBatchesResult {}
+
+export interface LoopscaleCreateLoanResult extends LoopscaleTxResult {
+  loanAddress: PublicKey
+}
+
+export interface VaultExecutionContext {
+  owner: PublicKey
+  vaultPda: PublicKey
+  signer: PublicKey
+  signers: Signer[]
+  vaultAddress?: PublicKey
+  accountIndex?: number
+  policyPda?: PublicKey
+  constraintIndices?: number[]
+  leadingAccounts?: PublicKey[] | AccountMeta[]
+  preHookAccounts?: PublicKey[] | AccountMeta[]
+  postHookAccounts?: PublicKey[] | AccountMeta[]
+  squadsProgram?: PublicKey
+  addressLookupTableAccounts?: import("@solana/web3.js").AddressLookupTableAccount[]
+  prependInstructions?: TransactionInstruction[]
+  sendOptions?: SendOptions
+  commitment?: Commitment
+}
+
+export interface BatchExecutionResult {
+  batchIndex: number
+  signature: string
+  logs: string[] | null
+  error: unknown
+}
+
+export interface ExecutionResult {
+  error: unknown
+  results: BatchExecutionResult[]
+}
+
+export interface ClassifiedInstructions {
+  /** Loopscale instructions to wrap in sync tx. */
+  loopscale: LoopscaleGeneratedInstruction[]
+  /** Compute budget, oracles, etc. for outer tx. */
+  topLevel: TransactionInstruction[]
+  /** ATA creation etc. — safe to skip. */
+  setup: TransactionInstruction[]
+}
+
+export interface LoopscaleQuote {
+  apy: number
+  ltv: number
+  liquidationThreshold: number
+  maxPrincipalAvailable: number
+  strategy?: string
+  [key: string]: unknown
+}
+
+// ============================================================================
+// Discriminator helpers
+// ============================================================================
+
+type LoopscaleInstructionName =
+  | "createLoan"
+  | "depositCollateral"
+  | "borrowPrincipal"
+  | "repayPrincipal"
+  | "withdrawCollateral"
+  | "closeLoan"
+  | "updateWeightMatrix"
+  | "lockLoan"
+  | "unlockLoan"
+  | "createStrategy"
+  | "depositStrategy"
+  | "withdrawStrategy"
+  | "closeStrategy"
+  | "updateStrategy"
+  | "refinanceLedger"
+
+const DISCRIMINATOR_HEX_TO_NAME = new Map<string, LoopscaleInstructionName>(
+  Object.entries(LOOPSCALE_DISCRIMINATORS).map(([name, buf]) => [
+    Buffer.from(buf).toString("hex"),
+    name as LoopscaleInstructionName,
+  ]),
+)
+
+const NAME_TO_ACTION_WRAPPER: Record<LoopscaleInstructionName, (ix: TransactionInstruction) => LoopscaleInstruction> = {
+  createLoan: (ix) => loopscaleAction.createLoan({ instruction: ix }),
+  depositCollateral: (ix) => loopscaleAction.depositCollateral({ instruction: ix }),
+  borrowPrincipal: (ix) => loopscaleAction.borrowPrincipal({ instruction: ix }),
+  repayPrincipal: (ix) => loopscaleAction.repayPrincipal({ instruction: ix }),
+  withdrawCollateral: (ix) => loopscaleAction.withdrawCollateral({ instruction: ix }),
+  closeLoan: (ix) => loopscaleAction.closeLoan({ instruction: ix }),
+  updateWeightMatrix: (ix) => loopscaleAction.updateWeightMatrix({ instruction: ix }),
+  createStrategy: (ix) => loopscaleAction.createStrategy({ instruction: ix }),
+  depositStrategy: (ix) => loopscaleAction.depositStrategy({ instruction: ix }),
+  withdrawStrategy: (ix) => loopscaleAction.withdrawStrategy({ instruction: ix }),
+  closeStrategy: (ix) => loopscaleAction.closeStrategy({ instruction: ix }),
+  updateStrategy: (ix) => loopscaleAction.updateStrategy({ instruction: ix }),
+  lockLoan: (ix) => loopscaleAction.lockLoan({ instruction: ix }),
+  unlockLoan: (ix) => loopscaleAction.unlockLoan({ instruction: ix }),
+  refinanceLedger: (ix) => loopscaleAction.refinanceLedger({ instruction: ix }),
+}
+
+interface LoopscaleLegacyTransactionEntry {
+  message: string
+  signatures: Array<{ publicKey: string; signature: string }>
+}
+
+// ============================================================================
+// Internal helpers
+// ============================================================================
+
+function toBase58(value: PublicKey | string): string {
+  return typeof value === "string" ? value : value.toBase58()
+}
+
+function toSafeNumber(value: bigint | number, field: string): number {
+  if (typeof value === "bigint") {
+    if (value < 0n) throw new Error(`${field} must be non-negative`)
+    if (value > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error(`${field} too large for JSON integer`)
+    return Number(value)
+  }
+  if (!Number.isInteger(value) || value < 0) throw new Error(`${field} must be a non-negative integer`)
+  return value
+}
+
+function isEmptySignature(sig: Uint8Array): boolean {
+  return sig.every((b) => b === 0)
+}
+
+function identifyInstruction(ix: TransactionInstruction): LoopscaleInstructionName | null {
+  if (!ix.programId.equals(LOOPSCALE_PROGRAM_ID)) return null
+  const hex = Buffer.from(ix.data).subarray(0, 8).toString("hex")
+  return DISCRIMINATOR_HEX_TO_NAME.get(hex) ?? null
+}
+
+async function decompileInstructions(
+  connection: Connection,
+  transaction: VersionedTransaction,
+): Promise<TransactionInstruction[]> {
+  const lookupTableAccounts = await Promise.all(
+    transaction.message.addressTableLookups.map(async (lookup) => {
+      const result = await connection.getAddressLookupTable(lookup.accountKey)
+      if (!result.value) {
+        throw new Error(`Missing lookup table ${lookup.accountKey.toBase58()}`)
+      }
+      return result.value
+    }),
+  )
+  return TransactionMessage.decompile(transaction.message, { addressLookupTableAccounts: lookupTableAccounts }).instructions
+}
+
+function buildTxFromLegacyEntry(entry: {
+  message: string
+  signatures: Array<{ publicKey: string; signature: string }>
+}): VersionedTransaction {
+  const message = VersionedMessage.deserialize(Buffer.from(entry.message, "base64"))
+  const tx = new VersionedTransaction(message)
+  const signerKeys = message.staticAccountKeys.slice(0, message.header.numRequiredSignatures)
+
+  for (const sig of entry.signatures) {
+    const pubkey = new PublicKey(sig.publicKey)
+    const sigBytes = Buffer.from(sig.signature, "base64")
+    if (sigBytes.length !== 64) throw new Error(`Invalid signature for ${pubkey.toBase58()}`)
+    const idx = signerKeys.findIndex((k) => k.equals(pubkey))
+    if (idx >= 0) tx.signatures[idx] = new Uint8Array(sigBytes)
+  }
+  return tx
+}
+
+function mergeInputSignatures(
+  resultTx: VersionedTransaction,
+  inputTx: VersionedTransaction,
+): VersionedTransaction {
+  const signerKeys = resultTx.message.staticAccountKeys.slice(0, resultTx.message.header.numRequiredSignatures)
+  const inputKeys = inputTx.message.staticAccountKeys
+  const inputNumSigners = inputTx.message.header.numRequiredSignatures
+
+  for (let i = 0; i < inputNumSigners; i++) {
+    const inputSig = inputTx.signatures[i]
+    if (isEmptySignature(inputSig)) continue
+    const resultIdx = signerKeys.findIndex((key) => key.equals(inputKeys[i]))
+    if (resultIdx < 0) continue
+    if (isEmptySignature(resultTx.signatures[resultIdx])) {
+      resultTx.signatures[resultIdx] = inputSig
+    }
+  }
+  return resultTx
+}
+
+function ensureMessageMatches(a: VersionedTransaction, b: VersionedTransaction): void {
+  const am = Buffer.from(a.message.serialize())
+  const bm = Buffer.from(b.message.serialize())
+  if (!am.equals(bm)) {
+    throw new Error("Loopscale returned a different transaction message; refusing to merge")
+  }
+}
+
+// ============================================================================
+// LoopscaleClient
+// ============================================================================
+
+export class LoopscaleClient {
+  private readonly connection: Connection
+  private readonly baseUrl: string
+  private readonly userWallet: string
+  private readonly bsAuth: PublicKey
+  private readonly useMpcCoSign: boolean
+  private readonly debug: boolean
+  private vaultCtx: VaultExecutionContext | null = null
+
+  constructor(config: LoopscaleClientConfig) {
+    this.connection = config.connection
+    this.baseUrl = config.baseUrl ?? LOOPSCALE_API_BASE_URL
+    this.userWallet = toBase58(config.userWallet)
+    this.bsAuth = config.bsAuth ?? BS_AUTH
+    this.useMpcCoSign = config.useMpcCoSign ?? true
+    this.debug = config.debug ?? false
+  }
+
+  // ── Vault execution context ──
+
+  setVaultContext(ctx: VaultExecutionContext): void {
+    this.vaultCtx = ctx
+  }
+
+  private requireVaultContext(): VaultExecutionContext {
+    if (!this.vaultCtx) {
+      throw new Error("LoopscaleClient: call setVaultContext() before executeBatches/executeSyncTx")
+    }
+    return this.vaultCtx
+  }
+
+  async executeBatches(batches: LoopscaleStrategyBatch[]): Promise<ExecutionResult> {
+    const ctx = this.requireVaultContext()
+    const commitment = ctx.commitment ?? "confirmed"
+    const results: BatchExecutionResult[] = []
+
+    for (const [batchIndex, batch] of batches.entries()) {
+      const result = batch.syncActions.length === 0
+        ? await this.executePrebuiltBatch(batch, batchIndex, commitment)
+        : await this.executeSyncBatch(batch, batchIndex, ctx, commitment)
+
+      results.push(result)
+      if (result.error) {
+        return { error: result.error, results }
+      }
+    }
+
+    return { error: null, results }
+  }
+
+  async executeSyncTx(syncActions: LoopscaleInstruction[]): Promise<BatchExecutionResult> {
+    const ctx = this.requireVaultContext()
+    const commitment = ctx.commitment ?? "confirmed"
+    return this.executeSyncBatch(
+      { syncActions, topLevelInstructions: [], setupInstructions: [] },
+      0, ctx, commitment,
+    )
+  }
+
+  private async executePrebuiltBatch(
+    batch: LoopscaleStrategyBatch,
+    batchIndex: number,
+    commitment: Commitment,
+  ): Promise<BatchExecutionResult> {
+    const ctx = this.requireVaultContext()
+    const tx = batch.raw.transaction
+    const signerKeys = tx.message.staticAccountKeys.slice(0, tx.message.header.numRequiredSignatures)
+    const available = new Map(ctx.signers.map((s) => [s.publicKey.toBase58(), s]))
+    const local = signerKeys.map((k) => available.get(k.toBase58())).filter((s): s is Signer => Boolean(s))
+
+    if (local.length > 0) tx.sign(local)
+
+    const missing = signerKeys.filter((_, i) => tx.signatures[i]?.every((b) => b === 0))
+    if (missing.length > 0) {
+      throw new Error(`batch ${batchIndex + 1}: missing signer(s): ${missing.map((k) => k.toBase58()).join(", ")}`)
+    }
+
+    return { batchIndex, ...(await this.sendAndConfirm(tx, ctx.sendOptions, { commitment })) }
+  }
+
+  private async executeSyncBatch(
+    batch: Pick<LoopscaleStrategyBatch, "syncActions" | "topLevelInstructions" | "setupInstructions">,
+    batchIndex: number,
+    ctx: VaultExecutionContext,
+    commitment: Commitment,
+  ): Promise<BatchExecutionResult> {
+    const syncResult = await createVaultSyncTransaction({
+      instructions: batch.syncActions,
+      owner: ctx.owner,
+      connection: this.connection,
+      policyPda: ctx.policyPda,
+      vaultPda: ctx.vaultPda,
+      signer: ctx.signer,
+      accountIndex: ctx.accountIndex,
+      constraintIndices: ctx.constraintIndices,
+      vaultAddress: ctx.vaultAddress,
+      leadingAccounts: ctx.leadingAccounts,
+      preHookAccounts: ctx.preHookAccounts,
+      postHookAccounts: ctx.postHookAccounts,
+      squadsProgram: ctx.squadsProgram,
+    })
+
+    if (syncResult.setupInstructions.length > 0) {
+      throw new Error(`batch ${batchIndex + 1}: unexpected sync setupInstructions (${syncResult.setupInstructions.length})`)
+    }
+
+    const { blockhash, lastValidBlockHeight } = await this.connection.getLatestBlockhash(commitment)
+    const msg = new TransactionMessage({
+      payerKey: ctx.signers[0]!.publicKey,
+      recentBlockhash: blockhash,
+      instructions: [
+        ...(ctx.prependInstructions ?? []),
+        ...batch.topLevelInstructions,
+        ...syncResult.preInstructions,
+        syncResult.instruction,
+        ...syncResult.postInstructions,
+      ],
+    }).compileToV0Message(ctx.addressLookupTableAccounts ?? [])
+
+    let tx = new VersionedTransaction(msg)
+    tx.sign([...ctx.signers, ...syncResult.signers])
+    tx = await this.coSign(tx)
+
+    return {
+      batchIndex,
+      ...(await this.sendAndConfirm(tx, ctx.sendOptions, { commitment, blockhash, lastValidBlockHeight })),
+    }
+  }
+
+  private async sendAndConfirm(
+    tx: VersionedTransaction,
+    sendOptions: SendOptions | undefined,
+    confirmation: { commitment: Commitment; blockhash?: string; lastValidBlockHeight?: number },
+  ): Promise<{ signature: string; logs: string[] | null; error: unknown }> {
+    const signature = await this.connection.sendTransaction(tx, sendOptions)
+
+    if (confirmation.blockhash && confirmation.lastValidBlockHeight !== undefined) {
+      try {
+        await this.connection.confirmTransaction({
+          signature,
+          blockhash: confirmation.blockhash,
+          lastValidBlockHeight: confirmation.lastValidBlockHeight,
+        }, confirmation.commitment)
+      } catch (err) {
+        if (this.debug) console.warn(`[LoopscaleClient] confirmTransaction failed for ${signature}:`, err)
+      }
+    } else {
+      for (let attempt = 0; attempt < 60; attempt += 1) {
+        const statuses = await this.connection.getSignatureStatuses([signature])
+        const s = statuses.value[0]
+        if (s?.err || s?.confirmationStatus === "confirmed" || s?.confirmationStatus === "finalized") break
+        await new Promise((r) => setTimeout(r, 1_000))
+      }
+    }
+
+    const finality: Finality = confirmation.commitment === "finalized" ? "finalized" : "confirmed"
+    for (let attempt = 0; attempt < 20; attempt += 1) {
+      const txResult = await this.connection.getTransaction(signature, {
+        commitment: finality,
+        maxSupportedTransactionVersion: 0,
+      })
+      if (txResult) {
+        return { signature, logs: txResult.meta?.logMessages ?? null, error: txResult.meta?.err ?? null }
+      }
+      await new Promise((r) => setTimeout(r, 500))
+    }
+
+    return { signature, logs: null, error: `Transaction ${signature} not found after confirmation timeout` }
+  }
+
+  // ── Data ──
+
+  async getQuotes(params: LoopscaleQuoteParams): Promise<LoopscaleQuote[]> {
+    const body = {
+      durationType: params.durationType,
+      duration: params.duration,
+      principal: toBase58(params.principal),
+      collateral: params.collateral.map(toBase58),
+      limit: params.limit ?? 10,
+      offset: params.offset ?? 0,
+    }
+    return this.post<LoopscaleQuote[]>("/markets/quote", body, { "user-wallet": this.userWallet })
+  }
+
+  async getMaxQuote(params: LoopscaleMaxQuoteParams): Promise<LoopscaleMaxQuote[]> {
+    const body = {
+      durationType: params.durationType,
+      duration: params.duration,
+      principalMint: toBase58(params.principalMint),
+      collateralFilter: params.collateralFilter.map((f) => ({
+        amount: toSafeNumber(f.amount, "amount"),
+        assetData: f.assetData,
+      })),
+    }
+    return this.post<LoopscaleMaxQuote[]>("/markets/quote/max", body, { "user-wallet": this.userWallet })
+  }
+
+  async getLoanInfo(params: LoopscaleLoanInfoParams): Promise<LoopscaleLoanInfoResponse> {
+    return this.post<LoopscaleLoanInfoResponse>("/markets/loans/info", params, { "user-wallet": this.userWallet })
+  }
+
+  async getStrategies(params: LoopscaleGetStrategiesParams): Promise<LoopscaleStrategyInfoResponse> {
+    return this.post<LoopscaleStrategyInfoResponse>("/markets/strategy/infos", params, { "user-wallet": this.userWallet })
+  }
+
+  async getCollateralHolders(params: LoopscaleCollateralHoldersParams): Promise<LoopscaleCollateralHolder[]> {
+    return this.post<LoopscaleCollateralHolder[]>("/markets/collateral/holders", params)
+  }
+
+  async getHistoricalCollateralHolders(params: LoopscaleHistoricalCollateralHoldersParams): Promise<LoopscaleHistoricalCollateralHolder[]> {
+    return this.post<LoopscaleHistoricalCollateralHolder[]>("/markets/collateral/holders/historical", params)
+  }
+
+  async getVaultDepositors(params: LoopscaleVaultDepositorsParams): Promise<LoopscaleVaultDepositor[]> {
+    return this.post<LoopscaleVaultDepositor[]>("/markets/lending_vaults/deposits", params)
+  }
+
+  async getVaultInfo(params: LoopscaleVaultInfoParams): Promise<LoopscaleVaultInfoResponse> {
+    return this.post<LoopscaleVaultInfoResponse>("/markets/lending_vaults/info", params)
+  }
+
+  async getLoopInfo(params: LoopscaleLoopInfoParams): Promise<Record<string, LoopscaleLoopVaultInfo>> {
+    return this.post<Record<string, LoopscaleLoopVaultInfo>>("/markets/loop/info", params)
+  }
+
+  // ── Strategy (LENDER side) ──
+
+  async createStrategy(params: LoopscaleCreateStrategyParams): Promise<LoopscaleStrategyResult> {
+    const lender = toBase58(params.lender)
+    const body: Record<string, unknown> = {
+      principalMint: toBase58(params.principalMint),
+      lender,
+      amount: toSafeNumber(params.amount, "amount"),
+    }
+    if (params.originationsEnabled !== undefined) body.originationsEnabled = params.originationsEnabled
+    if (params.liquidityBuffer !== undefined) body.liquidityBuffer = params.liquidityBuffer
+    if (params.interestFee !== undefined) body.interestFee = params.interestFee
+    if (params.originationFee !== undefined) body.originationFee = params.originationFee
+    if (params.originationCap !== undefined) body.originationCap = params.originationCap
+    if (params.collateralTerms) body.collateralTerms = params.collateralTerms
+    if (params.marketInformation) body.marketInformation = toBase58(params.marketInformation)
+    if (params.externalYieldSourceArgs) body.externalYieldSourceArgs = params.externalYieldSourceArgs
+
+    const entries = await this.post<LoopscaleLegacyTransactionEntry[]>(
+      "/markets/strategy/create", body, { payer: this.userWallet },
+    )
+
+    if (!Array.isArray(entries) || entries.length === 0) {
+      throw new Error("Loopscale strategy/create returned no transactions")
+    }
+
+    const batches = await this.parseStrategyBatches(entries)
+    const createBatch = batches.find((batch) => batch.raw.loopscaleInstructions.some((g) => g.name === "createStrategy"))
+    const createIx = createBatch?.raw.loopscaleInstructions.find((g) => g.name === "createStrategy")
+    if (!createIx) throw new Error("Loopscale strategy/create did not return a createStrategy instruction")
+    const strategyAddress = createIx.instruction.keys[3]?.pubkey
+    const noncePublicKey = createIx.instruction.keys[2]?.pubkey
+    if (!strategyAddress || !noncePublicKey) {
+      throw new Error("Invalid createStrategy account layout from API")
+    }
+
+    if (this.debug) {
+      console.log(`[LoopscaleClient] createStrategy: strategy=${strategyAddress.toBase58()}, batches=${batches.length}`)
+    }
+
+    return { batches, strategyAddress, noncePublicKey }
+  }
+
+  async depositStrategy(params: LoopscaleDepositStrategyParams): Promise<LoopscaleTxResult> {
+    const body = {
+      strategy: toBase58(params.strategy),
+      amount: toSafeNumber(params.amount, "amount"),
+    }
+    return this.fetchAndClassifySingleTx("/markets/strategy/deposit", body, {
+      "User-Wallet": this.userWallet,
+      payer: this.userWallet,
+    })
+  }
+
+  async withdrawStrategy(params: LoopscaleWithdrawStrategyParams): Promise<LoopscaleTxResult> {
+    const body = {
+      strategy: toBase58(params.strategy),
+      amount: toSafeNumber(params.amount, "amount"),
+      withdrawAll: params.withdrawAll,
+    }
+    return this.fetchAndClassifySingleTx("/markets/strategy/withdraw", body, {
+      "User-Wallet": this.userWallet,
+      payer: this.userWallet,
+    })
+  }
+
+  async closeStrategy(params: LoopscaleCloseStrategyParams): Promise<LoopscaleTxResult> {
+    const strategy = toBase58(params.strategy)
+    return this.fetchAndClassifySingleTx(`/markets/strategy/close/${strategy}`, undefined, {
+      payer: this.userWallet,
+    })
+  }
+
+  async updateStrategy(params: LoopscaleUpdateStrategyParams): Promise<LoopscaleUpdateStrategyResult> {
+    const body: Record<string, unknown> = { strategy: toBase58(params.strategy) }
+    if (params.collateralTerms) body.collateralTerms = params.collateralTerms
+    if (params.updateParams) body.updateParams = params.updateParams
+
+    const entries = await this.post<LoopscaleLegacyTransactionEntry[]>(
+      "/markets/strategy/update", body, { "User-Wallet": this.userWallet, payer: this.userWallet },
+    )
+
+    if (!Array.isArray(entries) || entries.length === 0) {
+      throw new Error("Loopscale strategy/update returned no transactions")
+    }
+
+    const batches = await this.parseStrategyBatches(entries)
+
+    if (this.debug) {
+      console.log(`[LoopscaleClient] updateStrategy: batches=${batches.length}`)
+    }
+
+    return { batches }
+  }
+
+  // ── Loan (BORROWER side) ──
+
+  /**
+   * Build a standalone borrow_principal instruction (no lock/unlock needed).
+   * Requires collateral to already be deposited in the loan.
+   */
+  buildBorrowPrincipalInstruction(params: LoopscaleBorrowPrincipalParams): TransactionInstruction {
+    const borrower = new PublicKey(toBase58(params.borrower))
+    const loan = new PublicKey(toBase58(params.loan))
+    const strategy = new PublicKey(toBase58(params.strategy))
+    const marketInformation = new PublicKey(toBase58(params.marketInformation))
+    const principalMint = new PublicKey(toBase58(params.principalMint))
+    const amount = typeof params.amount === "bigint" ? params.amount : BigInt(params.amount)
+
+    const guidance = params.assetIndexGuidance
+    const duration = params.durationIndex
+    const expectedApy = params.expectedApy !== undefined
+      ? (typeof params.expectedApy === "bigint" ? params.expectedApy : BigInt(params.expectedApy))
+      : 0n
+    const expectedLqt = params.expectedLqt ?? [0, 0, 0, 0, 0]
+    const skipSolUnwrap = params.skipSolUnwrap ?? false
+
+    // Serialize instruction data: discriminator + amount + guidance_vec + duration + expected_loan_values + skip_sol_unwrap
+    const dataSize = 8 + 8 + 4 + guidance.length + 1 + 8 + 20 + 1
+    const data = Buffer.alloc(dataSize)
+    let offset = 0
+    Buffer.from(LOOPSCALE_DISCRIMINATORS.borrowPrincipal).copy(data, 0); offset += 8
+    data.writeBigUInt64LE(amount, offset); offset += 8
+    data.writeUInt32LE(guidance.length, offset); offset += 4
+    for (const b of guidance) { data.writeUInt8(b, offset); offset += 1 }
+    data.writeUInt8(duration, offset); offset += 1
+    data.writeBigUInt64LE(expectedApy, offset); offset += 8
+    for (let i = 0; i < 5; i++) { data.writeUInt32LE(expectedLqt[i] ?? 0, offset); offset += 4 }
+    data.writeUInt8(skipSolUnwrap ? 1 : 0, offset); offset += 1
+
+    const TOKEN_PROGRAM_ID = new PublicKey("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA")
+    const [borrowerTa] = PublicKey.findProgramAddressSync(
+      [borrower.toBuffer(), TOKEN_PROGRAM_ID.toBuffer(), principalMint.toBuffer()],
+      ASSOCIATED_TOKEN_PROGRAM_ID,
+    )
+    const [strategyTa] = PublicKey.findProgramAddressSync(
+      [strategy.toBuffer(), TOKEN_PROGRAM_ID.toBuffer(), principalMint.toBuffer()],
+      ASSOCIATED_TOKEN_PROGRAM_ID,
+    )
+    const eventAuthority = PublicKey.findProgramAddressSync(
+      [Buffer.from("__event_authority")],
+      LOOPSCALE_PROGRAM_ID,
+    )[0]
+
+    const ix = new TransactionInstruction({
+      programId: LOOPSCALE_PROGRAM_ID,
+      keys: [
+        { pubkey: this.bsAuth, isSigner: true, isWritable: false },
+        { pubkey: borrower, isSigner: true, isWritable: true },
+        { pubkey: borrower, isSigner: true, isWritable: false },
+        { pubkey: loan, isSigner: false, isWritable: true },
+        { pubkey: strategy, isSigner: false, isWritable: true },
+        { pubkey: marketInformation, isSigner: false, isWritable: true },
+        { pubkey: principalMint, isSigner: false, isWritable: false },
+        { pubkey: borrowerTa, isSigner: false, isWritable: true },
+        { pubkey: strategyTa, isSigner: false, isWritable: true },
+        { pubkey: ASSOCIATED_TOKEN_PROGRAM_ID, isSigner: false, isWritable: false },
+        { pubkey: TOKEN_PROGRAM_ID, isSigner: false, isWritable: false },
+        { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+        { pubkey: eventAuthority, isSigner: false, isWritable: false },
+        { pubkey: LOOPSCALE_PROGRAM_ID, isSigner: false, isWritable: false },
+        ...params.healthCheckAccounts,
+      ],
+      data,
+    })
+
+    return ix
+  }
+
+  /**
+   * Build a standalone borrow_principal wrapped as a LoopscaleInstruction for sync tx.
+   * Requires collateral to already be deposited in the loan.
+   */
+  buildBorrowPrincipalAction(params: LoopscaleBorrowPrincipalParams): LoopscaleInstruction {
+    return loopscaleAction.borrowPrincipal({ instruction: this.buildBorrowPrincipalInstruction(params) })
+  }
+
+  async repayLoan(params: LoopscaleRepayLoanParams): Promise<LoopscaleTxResult> {
+    const body: Record<string, unknown> = {
+      loan: toBase58(params.loan),
+      repayParams: params.repayParams.map((p) => ({
+        amount: toSafeNumber(p.amount, "repayAmount"),
+        ledgerIndex: p.ledgerIndex,
+        repayAll: p.repayAll,
+      })),
+      collateralWithdrawalParams: (params.collateralWithdrawalParams ?? []).map((p) => ({
+        amount: toSafeNumber(p.amount, "withdrawAmount"),
+        collateralMint: toBase58(p.collateralMint),
+      })),
+    }
+    if (params.closeIfPossible !== undefined) body.closeIfPossible = params.closeIfPossible
+
+    return this.fetchAndClassifyWrappedTx("/markets/creditbook/repay", body, { "user-wallet": this.userWallet })
+  }
+
+  async closeLoan(params: LoopscaleCloseLoanParams): Promise<LoopscaleTxResult> {
+    const body = { loan: toBase58(params.loan) }
+    return this.fetchAndClassifyWrappedTx("/markets/creditbook/close_loan", body, { "user-wallet": this.userWallet })
+  }
+
+  async createLoan(params: LoopscaleCreateLoanParams): Promise<LoopscaleCreateLoanResult> {
+    const body: Record<string, unknown> = {
+      borrower: toBase58(params.borrower),
+      depositCollateral: params.depositCollateral.map((c) => ({
+        collateralAmount: toSafeNumber(c.collateralAmount, "collateralAmount"),
+        collateralAssetData: c.collateralAssetData,
+      })),
+      principalRequested: params.principalRequested.map((p) => ({
+        ledgerIndex: p.ledgerIndex,
+        principalAmount: toSafeNumber(p.principalAmount, "principalAmount"),
+        principalMint: toBase58(p.principalMint),
+        strategy: toBase58(p.strategy),
+        durationIndex: p.durationIndex,
+        expectedLoanValues: p.expectedLoanValues ?? { expectedApy: 0, expectedLqt: [0, 0, 0, 0, 0] },
+      })),
+    }
+    if (params.assetIndexGuidance) body.assetIndexGuidance = params.assetIndexGuidance
+    if (params.loanNonce) body.loanNonce = params.loanNonce
+    if (params.isLoop !== undefined) body.isLoop = params.isLoop
+
+    const headers = { payer: this.userWallet }
+
+    const data = await this.post<{
+      transaction: { message: string; signatures: Array<{ publicKey: string; signature: string }> }
+      loanAddress: string
+    }>("/markets/creditbook/create", body, headers)
+
+    const tx = buildTxFromLegacyEntry(data.transaction)
+    const instructions = await decompileInstructions(this.connection, tx)
+    const classified = this.classifyInstructions(instructions)
+    const syncActions = this.buildSyncActions(classified.loopscale)
+    const raw = this.buildRawBundle(tx, instructions, classified.loopscale)
+    const loanAddress = new PublicKey(data.loanAddress)
+
+    if (this.debug) {
+      console.log(`[LoopscaleClient] createLoan: loan=${loanAddress.toBase58()}, syncActions=${syncActions.length}`)
+    }
+
+    return { syncActions, topLevelInstructions: classified.topLevel, raw, loanAddress }
+  }
+
+  async apiBorrowPrincipal(params: LoopscaleApiBorrowPrincipalParams): Promise<LoopscaleTxResult> {
+    const borrowParams: Record<string, unknown> = {
+      amount: toSafeNumber(params.borrowParams.amount, "amount"),
+      duration: params.borrowParams.durationIndex,
+    }
+    if (params.borrowParams.expectedLoanValues) {
+      borrowParams.expectedLoanValues = params.borrowParams.expectedLoanValues
+    }
+    const body: Record<string, unknown> = {
+      loan: toBase58(params.loan),
+      borrowParams,
+      strategy: toBase58(params.strategy),
+    }
+    if (params.refinanceParams) body.refinanceParams = params.refinanceParams
+    if (params.isLoop !== undefined) body.isLoop = params.isLoop
+
+    return this.fetchAndClassifySingleTx("/markets/creditbook/borrow", body, { payer: this.userWallet })
+  }
+
+  async depositCollateral(params: LoopscaleDepositCollateralParams): Promise<LoopscaleTxResult> {
+    const body: Record<string, unknown> = {
+      loan: toBase58(params.loan),
+      depositMint: toBase58(params.depositMint),
+      amount: toSafeNumber(params.amount, "amount"),
+      assetType: params.assetType,
+      assetIdentifier: toBase58(params.assetIdentifier),
+    }
+    if (params.assetIndexGuidance) body.assetIndexGuidance = params.assetIndexGuidance
+    if (params.expectedLoanValues) body.expectedLoanValues = params.expectedLoanValues
+
+    return this.fetchAndClassifySingleTx("/markets/creditbook/collateral/deposit", body, {
+      "user-wallet": this.userWallet,
+      payer: this.userWallet,
+    })
+  }
+
+  async withdrawCollateral(params: LoopscaleWithdrawCollateralParams): Promise<LoopscaleTxResult> {
+    const body: Record<string, unknown> = {
+      loan: toBase58(params.loan),
+      collateralMint: toBase58(params.collateralMint),
+      amount: toSafeNumber(params.amount, "amount"),
+      collateralIndex: params.collateralIndex,
+    }
+    if (params.expectedLoanValues) body.expectedLoanValues = params.expectedLoanValues
+    if (params.assetIndexGuidance) body.assetIndexGuidance = params.assetIndexGuidance
+
+    return this.fetchAndClassifySingleTx("/markets/creditbook/collateral/withdraw", body, {
+      "user-wallet": this.userWallet,
+      payer: this.userWallet,
+    })
+  }
+
+  async refinanceLoan(params: LoopscaleRefinanceLoanParams): Promise<LoopscaleTxResult> {
+    const body = {
+      loan: toBase58(params.loan),
+      oldStrategy: toBase58(params.oldStrategy),
+      newStrategy: toBase58(params.newStrategy),
+      refinanceParams: params.refinanceParams,
+    }
+    return this.fetchAndClassifyWrappedTx("/markets/creditbook/refinance", body, {
+      "user-wallet": this.userWallet,
+    })
+  }
+
+  // ── Co-signing ──
+
+  async coSign(transaction: VersionedTransaction): Promise<VersionedTransaction> {
+    const serializedTx = Buffer.from(transaction.serialize()).toString("base64")
+    const serializedMsg = Buffer.from(transaction.message.serialize()).toString("base64")
+
+    if (this.useMpcCoSign) {
+      const body = {
+        batches: [{
+          transactions: [{
+            identifier: "loopscale-cosign",
+            transaction: serializedTx,
+            transactionType: 1,
+          }],
+        }],
+      }
+
+      const data = await this.post<{
+        batches: Array<{ transactions: Array<{ identifier: string; transaction: string; transactionType: number }> }>
+      }>("/mpc/txns/gen", body)
+
+      const txEntry = data.batches?.[0]?.transactions?.[0]
+      if (!txEntry) throw new Error("Loopscale MPC co-signing returned no transaction")
+
+      const resultTx = VersionedTransaction.deserialize(Buffer.from(txEntry.transaction, "base64"))
+      ensureMessageMatches(resultTx, transaction)
+      return mergeInputSignatures(resultTx, transaction)
+    }
+
+    // Legacy endpoint
+    const body = [{ transaction: serializedTx, message: serializedMsg }]
+    const entries = await this.post<Array<{ message: string; signatures: Array<{ publicKey: string; signature: string }> }>>(
+      "/markets/txn/gen", body, { "user-wallet": this.userWallet },
+    )
+
+    if (!entries?.[0]) throw new Error("Loopscale co-signing returned no entries")
+    const resultTx = buildTxFromLegacyEntry(entries[0])
+    ensureMessageMatches(resultTx, transaction)
+    return mergeInputSignatures(resultTx, transaction)
+  }
+
+  // ── Instruction helpers ──
+
+  classifyInstructions(instructions: TransactionInstruction[]): ClassifiedInstructions {
+    const loopscale: LoopscaleGeneratedInstruction[] = []
+    const topLevel: TransactionInstruction[] = []
+    const setup: TransactionInstruction[] = []
+
+    for (const ix of instructions) {
+      if (ix.programId.equals(LOOPSCALE_PROGRAM_ID)) {
+        loopscale.push({ name: identifyInstruction(ix), instruction: ix })
+      } else if (ix.programId.equals(ComputeBudgetProgram.programId)) {
+        topLevel.push(ix)
+      } else if (ix.programId.equals(ASSOCIATED_TOKEN_PROGRAM_ID)) {
+        setup.push(ix)
+      } else {
+        // Oracle feeds, system program, etc. — top level
+        topLevel.push(ix)
+      }
+    }
+
+    return { loopscale, topLevel, setup }
+  }
+
+  static identifyInstruction(ix: TransactionInstruction): LoopscaleInstructionName | null {
+    return identifyInstruction(ix)
+  }
+
+  // ── Private helpers ──
+
+  private buildSyncActions(loopscaleIxs: LoopscaleGeneratedInstruction[]): LoopscaleInstruction[] {
+    return loopscaleIxs
+      .filter((g) => g.name !== null)
+      .map((g) => {
+        const wrapper = NAME_TO_ACTION_WRAPPER[g.name!]
+        return wrapper(g.instruction)
+      })
+  }
+
+  private buildRawBundle(
+    transaction: VersionedTransaction,
+    instructions: TransactionInstruction[],
+    loopscaleInstructions: LoopscaleGeneratedInstruction[],
+  ): LoopscaleGeneratedInstructionBundle {
+    return { transaction, instructions, loopscaleInstructions }
+  }
+
+  private toSingleTxResult(batch: LoopscaleStrategyBatch): LoopscaleTxResult {
+    return {
+      syncActions: batch.syncActions,
+      topLevelInstructions: batch.topLevelInstructions,
+      raw: batch.raw,
+    }
+  }
+
+  private async parseTransactionEntry(entry: LoopscaleLegacyTransactionEntry): Promise<LoopscaleStrategyBatch> {
+    const tx = buildTxFromLegacyEntry(entry)
+    const instructions = await decompileInstructions(this.connection, tx)
+    const classified = this.classifyInstructions(instructions)
+    const syncActions = this.buildSyncActions(classified.loopscale)
+    const raw = this.buildRawBundle(tx, instructions, classified.loopscale)
+
+    return {
+      syncActions,
+      topLevelInstructions: classified.topLevel,
+      setupInstructions: classified.setup,
+      raw,
+    }
+  }
+
+  private async parseStrategyBatches(entries: LoopscaleLegacyTransactionEntry[]): Promise<LoopscaleStrategyBatch[]> {
+    return Promise.all(entries.map((entry) => this.parseTransactionEntry(entry)))
+  }
+
+  private async fetchAndClassifyWrappedTx(
+    path: string,
+    body: unknown,
+    headers: Record<string, string>,
+  ): Promise<LoopscaleTxResult> {
+    const data = await this.post<{
+      transactions: LoopscaleLegacyTransactionEntry[]
+      expectedLoanInfo?: unknown
+    }>(path, body, headers)
+
+    if (!data.transactions?.length) {
+      throw new Error(`Loopscale ${path} returned no transactions`)
+    }
+
+    if (data.transactions.length > 1) {
+      throw new Error(
+        `Loopscale ${path} returned ${data.transactions.length} transactions — expected 1. ` +
+        `Multi-transaction responses (e.g. from setupIxs) are not supported.`,
+      )
+    }
+
+    const batch = await this.parseTransactionEntry(data.transactions[0])
+
+    if (this.debug) {
+      console.log(
+        `[LoopscaleClient] ${path}: syncActions=${batch.syncActions.length}, topLevel=${batch.topLevelInstructions.length}`,
+      )
+    }
+
+    return this.toSingleTxResult(batch)
+  }
+
+  private async fetchAndClassifySingleTx(
+    path: string,
+    body: unknown,
+    headers: Record<string, string>,
+  ): Promise<LoopscaleTxResult> {
+    const entry = await this.post<LoopscaleLegacyTransactionEntry>(
+      path, body, headers,
+    )
+
+    const batch = await this.parseTransactionEntry(entry)
+
+    if (this.debug) {
+      console.log(
+        `[LoopscaleClient] ${path}: syncActions=${batch.syncActions.length}, topLevel=${batch.topLevelInstructions.length}`,
+      )
+    }
+
+    return this.toSingleTxResult(batch)
+  }
+
+  private async post<T>(
+    path: string,
+    body?: unknown,
+    extraHeaders?: Record<string, string>,
+  ): Promise<T> {
+    const url = `${this.baseUrl}${path}`
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+      ...extraHeaders,
+    }
+
+    if (this.debug) {
+      console.log(`\n[LoopscaleClient] POST ${url}`)
+      if (body) console.log(`  body: ${JSON.stringify(body, null, 2).split("\n").slice(0, 10).join("\n")}...`)
+    }
+
+    let response: Response | undefined
+    const maxRetries = 3
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      response = await fetch(url, {
+        method: "POST",
+        headers,
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+      })
+
+      if (response.status === 429 && attempt < maxRetries) {
+        const delay = 2000 * (attempt + 1)
+        if (this.debug) console.log(`  RATE LIMITED (429), retrying in ${delay}ms (attempt ${attempt + 1}/${maxRetries})...`)
+        await new Promise((r) => setTimeout(r, delay))
+        continue
+      }
+      break
+    }
+
+    if (!response!.ok) {
+      const text = await response!.text()
+      if (this.debug) console.log(`  ERROR ${response!.status}: ${text}`)
+      throw new Error(`Loopscale API ${path} failed (${response!.status}): ${text}`)
+    }
+
+    const data = await response!.json() as T
+
+    if (this.debug) {
+      console.log(`  OK ${response!.status}`)
+    }
+
+    return data
+  }
+}