@exponent-labs/exponent-sdk 0.9.0 → 0.9.2

package/src/exponentVaults/loopscale/client.ts

@@ -0,0 +1,808 @@
+/**
+ * Loopscale manager flow:
+ *
+ * 1. Call a raw Loopscale endpoint such as `createStrategy(...)`,
+ *    `createLoan(...)`, or `borrowPrincipal(...)`.
+ * 2. Hand the raw response back to this client.
+ * 3. Choose one of two paths:
+ *    - `prepareVaultTransactions(...)` when you want appendable instruction
+ *      pieces you can compose with your own transaction building logic.
+ *    - `buildVaultTransactions(...)` when you want locally signed
+ *      `VersionedTransaction`s that are ready for optional Loopscale
+ *      co-signing and then `connection.sendTransaction(...)`.
+ * 4. Call `coSign(...)` only on returned transactions where
+ *    `requiresLoopscaleCoSign === true`.
+ *
+ * This distinction is intentional:
+ *
+ * - Wrapped Loopscale sync transactions require Loopscale MPC because they
+ *   represent Loopscale-authored flows that expect Loopscale's signature.
+ * - Setup transactions and other top-level non-Loopscale transactions must
+ *   stay local. They are constructed by the SDK to make the manager flow
+ *   complete, but they are not Loopscale-signed transactions and should not
+ *   be sent to Loopscale's MPC endpoint.
+ *
+ * In other words, `requiresLoopscaleCoSign` is not a convenience flag. It is
+ * the contract that tells the caller which transactions belong to Loopscale's
+ * signing domain and which ones do not.
+ *
+ * Example:
+ *
+ * ```ts
+ * const client = new LoopscaleClient({
+ *   connection,
+ *   userWallet: squadsVault,
+ *   payer: squadsVault,
+ * })
+ *
+ * const response = await client.createStrategy({
+ *   principalMint,
+ *   lender: squadsVault,
+ *   amount: 0,
+ * })
+ *
+ * const builtTransactions = await client.buildVaultTransactions({
+ *   response,
+ *   context: {
+ *     connection,
+ *     signer: manager.publicKey,
+ *     signers: [manager],
+ *     vaultPda: squadsVault,
+ *     vaultAddress,
+ *     squadsProgram,
+ *   },
+ * })
+ *
+ * for (const built of builtTransactions) {
+ *   const transaction = built.requiresLoopscaleCoSign
+ *     ? await client.coSign(built.transaction)
+ *     : built.transaction
+ *
+ *   await connection.sendTransaction(transaction, { skipPreflight: false })
+ * }
+ * ```
+ */
+import {
+  AddressLookupTableAccount,
+  Connection,
+  PublicKey,
+  TransactionMessage,
+  type TransactionInstruction,
+  type Signer,
+  VersionedTransaction,
+} from "@solana/web3.js"
+
+import type {
+  LoopscaleBorrowPrincipalParams,
+  LoopscaleClientConfig,
+  LoopscaleCloseLoanParams,
+  LoopscaleCloseStrategyParams,
+  LoopscaleCreateLoanParams,
+  LoopscaleCreateLoanResponse,
+  LoopscaleCreateStrategyParams,
+  LoopscaleDepositCollateralParams,
+  LoopscaleDepositStrategyParams,
+  LoopscaleGetStrategiesParams,
+  LoopscaleLoanInfoParams,
+  LoopscaleLoanInfoResponse,
+  LoopscaleLoanTransactionResponse,
+  LoopscaleMaxQuote,
+  LoopscaleMaxQuoteParams,
+  LoopscaleQuote,
+  LoopscaleQuoteParams,
+  LoopscaleRepayLoanSimpleParams,
+  LoopscaleStrategyInfoResponse,
+  LoopscaleTransactionResponse,
+  LoopscaleTransactionsResponse,
+  LoopscaleUpdateStrategyParams,
+  LoopscaleVersionedTransactionBatchResponse,
+  LoopscaleVersionedTransactionResponse,
+  LoopscaleWithdrawCollateralParams,
+  LoopscaleWithdrawStrategyParams,
+} from "./types"
+import type {
+  LoopscaleBuildTransactionsContext,
+  LoopscaleBuiltTransaction,
+  LoopscalePreparedTransaction,
+  LoopscaleVaultPreparationContext,
+} from "./prepared-types"
+import {
+  deserializeLoopscaleTransactionBatchResponse,
+  deserializeLoopscaleTransactionResponse,
+  extractCreatedStrategyAddress,
+  extractCreatedStrategyNonce,
+  getLoopscaleTransactionResponses,
+  identifyLoopscaleInstruction,
+} from "./helpers"
+import { prepareLoopscaleVaultTransactions } from "./prepared-transactions"
+
+const LOOPSCALE_API_BASE_URL = "https://tars.loopscale.com/v1"
+
+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} is too large for a JSON number`)
+    return Number(value)
+  }
+
+  if (!Number.isInteger(value) || value < 0) {
+    throw new Error(`${field} must be a non-negative integer`)
+  }
+
+  return value
+}
+
+function hasSignature(signature: Uint8Array): boolean {
+  return signature.some((value) => value !== 0)
+}
+
+function withPayerHeader(
+  headers: Record<string, string>,
+  payer: string | undefined,
+): Record<string, string> {
+  if (!payer) return headers
+  return { ...headers, payer }
+}
+
+function mergeCoSignedTransaction(
+  transaction: VersionedTransaction,
+  coSignedTransaction: VersionedTransaction,
+): VersionedTransaction {
+  const left = Buffer.from(transaction.message.serialize())
+  const right = Buffer.from(coSignedTransaction.message.serialize())
+  if (!left.equals(right)) {
+    throw new Error("Loopscale returned a different transaction message; refusing to merge signatures")
+  }
+
+  const signerKeys = coSignedTransaction.message.staticAccountKeys
+    .slice(0, coSignedTransaction.message.header.numRequiredSignatures)
+  const inputSignerKeys = transaction.message.staticAccountKeys
+    .slice(0, transaction.message.header.numRequiredSignatures)
+
+  for (let index = 0; index < inputSignerKeys.length; index += 1) {
+    const inputSignature = transaction.signatures[index]
+    if (!hasSignature(inputSignature)) continue
+
+    const signerIndex = signerKeys.findIndex((candidate) => candidate.equals(inputSignerKeys[index]!))
+    if (signerIndex >= 0 && !hasSignature(coSignedTransaction.signatures[signerIndex]!)) {
+      coSignedTransaction.signatures[signerIndex] = inputSignature
+    }
+  }
+
+  return coSignedTransaction
+}
+
+function dedupeLookupTableAccounts(
+  lookupTableAccounts: AddressLookupTableAccount[],
+): AddressLookupTableAccount[] {
+  const seen = new Set<string>()
+  return lookupTableAccounts.filter((account) => {
+    const key = account.key.toBase58()
+    if (seen.has(key)) {
+      return false
+    }
+    seen.add(key)
+    return true
+  })
+}
+
+function dedupeSigners(signers: Signer[]): Signer[] {
+  const seen = new Set<string>()
+  return signers.filter((signer) => {
+    const key = signer.publicKey.toBase58()
+    if (seen.has(key)) {
+      return false
+    }
+    seen.add(key)
+    return true
+  })
+}
+
+async function resolveLookupTableAccounts(
+  connection: Connection,
+  addresses: readonly PublicKey[],
+): Promise<AddressLookupTableAccount[]> {
+  const results = await Promise.all(
+    addresses.map((address) => connection.getAddressLookupTable(address)),
+  )
+
+  return dedupeLookupTableAccounts(
+    results
+      .map((result) => result.value)
+      .filter((value): value is AddressLookupTableAccount => value !== null),
+  )
+}
+
+async function buildSignedTransaction(
+  connection: Connection,
+  signer: PublicKey,
+  instructions: readonly TransactionInstruction[],
+  lookupTableAddresses: readonly PublicKey[],
+  signers: Signer[],
+): Promise<VersionedTransaction> {
+  const addressLookupTableAccounts = await resolveLookupTableAccounts(connection, lookupTableAddresses)
+  const { blockhash } = await connection.getLatestBlockhash("confirmed")
+  const message = new TransactionMessage({
+    payerKey: signer,
+    recentBlockhash: blockhash,
+    instructions: [...instructions],
+  }).compileToV0Message(addressLookupTableAccounts)
+
+  const transaction = new VersionedTransaction(message)
+  transaction.sign(dedupeSigners(signers))
+  return transaction
+}
+
+/**
+ * Thin docs-aligned Loopscale client for strategies, loans, and related query endpoints.
+ *
+ * Transaction methods intentionally return the raw Loopscale response shapes
+ * instead of derived sync-action bundles. Use
+ * {@link LoopscaleClient.prepareVaultTransactions} when you need appendable
+ * transaction pieces, or {@link LoopscaleClient.buildVaultTransactions} when
+ * you want locally signed transactions that are ready for optional
+ * `client.coSign(...)` and `connection.sendTransaction(...)`.
+ *
+ * Refinancing and other lock/unlock maintenance flows remain intentionally
+ * excluded. The client only covers strategies, loans, and cleanup endpoints
+ * that can be represented as raw transaction responses.
+ *
+ * Typical usage:
+ *
+ * - Query Loopscale data through the read methods on this client.
+ * - Build raw Loopscale transactions through the strategy and loan methods.
+ * - Turn raw responses into appendable instruction pieces with
+ *   {@link LoopscaleClient.prepareVaultTransactions}.
+ * - Or compile ready-to-send transactions with
+ *   {@link LoopscaleClient.buildVaultTransactions}.
+ * - Call {@link LoopscaleClient.coSign} only for transactions flagged with
+ *   `requiresLoopscaleCoSign`.
+ */
+export class LoopscaleClient {
+  private readonly connection: Connection
+  private readonly baseUrl: string
+  private readonly userWallet: string
+  private readonly payer: string
+  private readonly debug: boolean
+
+  constructor(config: LoopscaleClientConfig) {
+    this.connection = config.connection
+    this.baseUrl = config.baseUrl ?? LOOPSCALE_API_BASE_URL
+    this.userWallet = toBase58(config.userWallet)
+    this.payer = toBase58(config.payer ?? config.userWallet)
+    this.debug = config.debug ?? false
+  }
+
+  /**
+   * Load Loopscale quotes for a principal/collateral pair.
+   */
+  async getQuotes(params: LoopscaleQuoteParams): Promise<LoopscaleQuote[]> {
+    const body: Record<string, unknown> = {
+      durationType: params.durationType,
+      duration: params.duration,
+      principal: toBase58(params.principal),
+      collateral: params.collateral.map(toBase58),
+      limit: params.limit ?? 10,
+      offset: params.offset ?? 0,
+    }
+
+    if (params.minPrincipalAmount !== undefined) {
+      body.minPrincipalAmount = toSafeNumber(params.minPrincipalAmount, "minPrincipalAmount")
+    }
+
+    return this.post<LoopscaleQuote[]>("/markets/quote", body, {
+      "user-wallet": this.userWallet,
+    })
+  }
+
+  /**
+   * Load the best quote for one or more specific collateral assets.
+   */
+  async getMaxQuote(params: LoopscaleMaxQuoteParams): Promise<LoopscaleMaxQuote[]> {
+    return this.post<LoopscaleMaxQuote[]>("/markets/quote/max", {
+      durationType: params.durationType,
+      duration: params.duration,
+      principalMint: toBase58(params.principalMint),
+      collateralFilter: params.collateralFilter.map((item) => ({
+        amount: toSafeNumber(item.amount, "amount"),
+        assetData: item.assetData,
+      })),
+    }, {
+      "user-wallet": this.userWallet,
+    })
+  }
+
+  /**
+   * Load Loopscale loan positions.
+   */
+  async getLoanInfo(params: LoopscaleLoanInfoParams): Promise<LoopscaleLoanInfoResponse> {
+    return this.post<LoopscaleLoanInfoResponse>("/markets/loans/info", params)
+  }
+
+  /**
+   * Load Loopscale lending strategies.
+   */
+  async getStrategies(params: LoopscaleGetStrategiesParams): Promise<LoopscaleStrategyInfoResponse> {
+    return this.post<LoopscaleStrategyInfoResponse>("/markets/strategy/infos", params)
+  }
+
+  /**
+   * Build a raw Loopscale `createStrategy` transaction batch.
+   */
+  async createStrategy(
+    params: LoopscaleCreateStrategyParams,
+  ): Promise<LoopscaleVersionedTransactionBatchResponse> {
+    const body: Record<string, unknown> = {
+      principalMint: toBase58(params.principalMint),
+      lender: toBase58(params.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
+
+    return this.post<LoopscaleVersionedTransactionBatchResponse>(
+      "/markets/strategy/create",
+      body,
+      { payer: this.payer },
+    )
+  }
+
+  /**
+   * Build a raw Loopscale `depositStrategy` transaction.
+   */
+  async depositStrategy(
+    params: LoopscaleDepositStrategyParams,
+  ): Promise<LoopscaleVersionedTransactionResponse> {
+    return this.post<LoopscaleVersionedTransactionResponse>("/markets/strategy/deposit", {
+      strategy: toBase58(params.strategy),
+      amount: toSafeNumber(params.amount, "amount"),
+    }, withPayerHeader({
+      "User-Wallet": this.userWallet,
+    }, this.payer))
+  }
+
+  /**
+   * Build a raw Loopscale `withdrawStrategy` transaction.
+   */
+  async withdrawStrategy(
+    params: LoopscaleWithdrawStrategyParams,
+  ): Promise<LoopscaleVersionedTransactionResponse> {
+    return this.post<LoopscaleVersionedTransactionResponse>("/markets/strategy/withdraw", {
+      strategy: toBase58(params.strategy),
+      amount: toSafeNumber(params.amount, "amount"),
+      withdrawAll: params.withdrawAll,
+    }, withPayerHeader({
+      "User-Wallet": this.userWallet,
+    }, this.payer))
+  }
+
+  /**
+   * Build a raw Loopscale `closeStrategy` transaction.
+   */
+  async closeStrategy(
+    params: LoopscaleCloseStrategyParams,
+  ): Promise<LoopscaleVersionedTransactionResponse> {
+    return this.post<LoopscaleVersionedTransactionResponse>(
+      `/markets/strategy/close/${toBase58(params.strategy)}`,
+      undefined,
+      { payer: this.payer },
+    )
+  }
+
+  /**
+   * Build raw Loopscale `updateStrategy` transactions.
+   */
+  async updateStrategy(
+    params: LoopscaleUpdateStrategyParams,
+  ): Promise<LoopscaleVersionedTransactionBatchResponse> {
+    const body: Record<string, unknown> = {
+      strategy: toBase58(params.strategy),
+    }
+
+    if (params.collateralTerms) body.collateralTerms = params.collateralTerms
+    if (params.updateParams) body.updateParams = params.updateParams
+
+    return this.post<LoopscaleVersionedTransactionBatchResponse>(
+      "/markets/strategy/update",
+      body,
+      withPayerHeader({
+        "User-Wallet": this.userWallet,
+      }, this.payer),
+    )
+  }
+
+  /**
+   * Build a raw Loopscale `createLoan` transaction.
+   */
+  async createLoan(
+    params: LoopscaleCreateLoanParams,
+  ): Promise<LoopscaleCreateLoanResponse> {
+    const body: Record<string, unknown> = {
+      borrower: toBase58(params.borrower),
+      depositCollateral: params.depositCollateral.map((item) => ({
+        collateralAmount: toSafeNumber(item.collateralAmount, "collateralAmount"),
+        collateralAssetData: item.collateralAssetData,
+      })),
+      principalRequested: params.principalRequested.map((item) => ({
+        ledgerIndex: item.ledgerIndex,
+        principalAmount: toSafeNumber(item.principalAmount, "principalAmount"),
+        principalMint: toBase58(item.principalMint),
+        strategy: toBase58(item.strategy),
+        durationIndex: item.durationIndex,
+        expectedLoanValues: item.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
+
+    return this.post<LoopscaleCreateLoanResponse>(
+      "/markets/creditbook/create",
+      body,
+      { payer: this.payer },
+    )
+  }
+
+  /**
+   * Build a raw Loopscale `borrowPrincipal` transaction.
+   *
+   * The published OpenAPI schema currently documents a single serialized
+   * transaction response, but live responses can also return a wrapped
+   * `transactions` array with `expectedLoanInfo` when Loopscale inserts
+   * additional internal maintenance steps.
+   */
+  async borrowPrincipal(
+    params: LoopscaleBorrowPrincipalParams,
+  ): Promise<LoopscaleLoanTransactionResponse> {
+    const body: Record<string, unknown> = {
+      loan: toBase58(params.loan),
+      borrowParams: {
+        amount: toSafeNumber(params.borrowParams.amount, "amount"),
+        duration: params.borrowParams.durationIndex,
+      },
+      strategy: toBase58(params.strategy),
+    }
+
+    if (params.borrowParams.expectedLoanValues) {
+      body.borrowParams = {
+        ...body.borrowParams as Record<string, unknown>,
+        expectedLoanValues: params.borrowParams.expectedLoanValues,
+      }
+    }
+    if (params.refinanceParams) body.refinanceParams = params.refinanceParams
+    if (params.isLoop !== undefined) body.isLoop = params.isLoop
+
+    return this.post<LoopscaleLoanTransactionResponse>(
+      "/markets/creditbook/borrow",
+      body,
+      { payer: this.payer },
+    )
+  }
+
+  /**
+   * Build a raw Loopscale `depositCollateral` transaction.
+   */
+  async depositCollateral(
+    params: LoopscaleDepositCollateralParams,
+  ): Promise<LoopscaleVersionedTransactionResponse> {
+    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.post<LoopscaleVersionedTransactionResponse>(
+      "/markets/creditbook/collateral/deposit",
+      body,
+      withPayerHeader({
+        "user-wallet": this.userWallet,
+      }, this.payer),
+    )
+  }
+
+  /**
+   * Build a raw Loopscale `withdrawCollateral` transaction.
+   *
+   * Full collateral removal can trigger internal loan-maintenance instructions,
+   * so callers should accept either a single serialized transaction or a wrapped
+   * `transactions` array.
+   */
+  async withdrawCollateral(
+    params: LoopscaleWithdrawCollateralParams,
+  ): Promise<LoopscaleLoanTransactionResponse> {
+    const body: Record<string, unknown> = {
+      loan: toBase58(params.loan),
+      collateralMint: toBase58(params.collateralMint),
+      amount: toSafeNumber(params.amount, "amount"),
+      collateralIndex: params.collateralIndex,
+      expectedLoanValues: params.expectedLoanValues,
+    }
+
+    if (params.assetIndexGuidance) body.assetIndexGuidance = params.assetIndexGuidance
+
+    return this.post<LoopscaleLoanTransactionResponse>(
+      "/markets/creditbook/collateral/withdraw",
+      body,
+      withPayerHeader({
+        "user-wallet": this.userWallet,
+      }, this.payer),
+    )
+  }
+
+  /**
+   * Build a raw Loopscale `repay_simple` transaction response.
+   */
+  async repayLoanSimple(
+    params: LoopscaleRepayLoanSimpleParams,
+  ): Promise<LoopscaleTransactionsResponse> {
+    return this.post<LoopscaleTransactionsResponse>(
+      "/markets/creditbook/repay_simple",
+      {
+        loan: toBase58(params.loan),
+        repayParams: {
+          amount: toSafeNumber(params.repayParams.amount, "amount"),
+          ledgerIndex: params.repayParams.ledgerIndex,
+          repayAll: params.repayParams.repayAll,
+        },
+        strategy: toBase58(params.strategy),
+      },
+      { payer: this.payer },
+    )
+  }
+
+  /**
+   * Build a raw Loopscale `close_loan` transaction response.
+   */
+  async closeLoan(
+    params: LoopscaleCloseLoanParams,
+  ): Promise<LoopscaleLoanTransactionResponse> {
+    return this.post<LoopscaleLoanTransactionResponse>(
+      "/markets/creditbook/close_loan",
+      { loan: toBase58(params.loan) },
+      { "user-wallet": this.userWallet },
+    )
+  }
+
+  /**
+   * Convert a raw Loopscale response into manager-ready vault transaction pieces.
+   *
+   * This is the lower-level, appendable "lego" API.
+   *
+   * Each returned entry represents one manager-facing transaction:
+   * send `setupInstructions` first when present, then send the main
+   * `instructions`. Wrapped sync transactions are already flattened into one
+   * instruction list, so callers do not need to manually inspect the raw
+   * Loopscale response to figure out which instructions should be wrapped.
+   *
+   * Use this when you want to compose Loopscale output with your own custom
+   * transaction building logic.
+   */
+  async prepareVaultTransactions({
+    response,
+    context,
+  }: {
+    response: LoopscaleTransactionResponse
+    context: LoopscaleVaultPreparationContext
+  }): Promise<LoopscalePreparedTransaction[]> {
+    return prepareLoopscaleVaultTransactions({ response, context })
+  }
+
+  /**
+   * Build locally signed transactions from a raw Loopscale response.
+   *
+   * This is the simplest manager-facing API.
+   *
+   * The returned transactions are ready for:
+   * 1. `await client.coSign(tx)` when `requiresLoopscaleCoSign === true`
+   * 2. `connection.sendTransaction(tx)`
+   *
+   * The co-signing flag is deliberately per-transaction, not global. A single
+   * Loopscale response can produce:
+   *
+   * - local setup transactions that must be sent as-is,
+   * - local top-level transactions that do not belong to Loopscale's signing
+   *   domain,
+   * - one wrapped Loopscale sync transaction that does require Loopscale MPC.
+   *
+   * The client returns all of them in send order and marks only the wrapped
+   * Loopscale transaction for MPC co-signing. This is the correct boundary:
+   * callers should not guess which transactions need Loopscale's signature.
+   *
+   * The first signer in `context.signers` must match `context.signer`, since
+   * that signer is used as the fee payer for the compiled transactions.
+   */
+  async buildVaultTransactions({
+    response,
+    context,
+  }: {
+    response: LoopscaleTransactionResponse
+    context: LoopscaleBuildTransactionsContext
+  }): Promise<LoopscaleBuiltTransaction[]> {
+    const feePayer = context.signers[0]
+    if (!feePayer) {
+      throw new Error("buildVaultTransactions requires at least one signer")
+    }
+
+    if (!feePayer.publicKey.equals(context.signer)) {
+      throw new Error("buildVaultTransactions requires signers[0] to match context.signer")
+    }
+
+    const preparedTransactions = await this.prepareVaultTransactions({ response, context })
+    const builtTransactions: LoopscaleBuiltTransaction[] = []
+
+    for (const preparedTransaction of preparedTransactions) {
+      if (preparedTransaction.setupInstructions.length > 0) {
+        const setupTransaction = await buildSignedTransaction(
+          context.connection,
+          context.signer,
+          preparedTransaction.setupInstructions,
+          [],
+          context.signers,
+        )
+
+        builtTransactions.push({
+          transaction: setupTransaction,
+          requiresLoopscaleCoSign: false,
+        })
+      }
+
+      const mainTransaction = await buildSignedTransaction(
+        context.connection,
+        context.signer,
+        preparedTransaction.instructions,
+        preparedTransaction.addressLookupTableAddresses,
+        [...context.signers, ...preparedTransaction.signers],
+      )
+
+      builtTransactions.push({
+        transaction: mainTransaction,
+        requiresLoopscaleCoSign: preparedTransaction.requiresLoopscaleCoSign,
+      })
+    }
+
+    return builtTransactions
+  }
+
+  /**
+   * Co-sign a prepared transaction with Loopscale's back-end signer.
+   *
+   * This uses Loopscale's public MPC co-signing endpoint. The returned
+   * transaction is required to keep the exact same message as the locally
+   * signed input, and any local signatures that are missing from the response
+   * are copied back onto the returned transaction before it is handed to the
+   * caller.
+   *
+   * Only call this for transactions flagged with
+   * `requiresLoopscaleCoSign === true`. Transactions not flagged that way do
+   * not belong to Loopscale's signing domain and should be sent directly.
+   */
+  async coSign(transaction: VersionedTransaction): Promise<VersionedTransaction> {
+    const serializedTransaction = Buffer.from(transaction.serialize()).toString("base64")
+    const data = await this.post<{
+      batches: Array<{
+        transactions: Array<{
+          identifier: string
+          transaction: string
+          transactionType: number
+        }>
+      }>
+    }>("/mpc/txns/gen", {
+      batches: [{
+        transactions: [{
+          identifier: "loopscale-cosign",
+          transaction: serializedTransaction,
+          transactionType: 1,
+        }],
+      }],
+    })
+
+    const transactionEntry = data.batches?.[0]?.transactions?.[0]
+    if (!transactionEntry) {
+      throw new Error("Loopscale MPC co-signing returned no transaction")
+    }
+
+    const coSignedTransaction = VersionedTransaction.deserialize(
+      Buffer.from(transactionEntry.transaction, "base64"),
+    )
+
+    return mergeCoSignedTransaction(transaction, coSignedTransaction)
+  }
+
+  /**
+   * Extract the strategy PDA from a `createStrategy` response using the client's connection.
+   */
+  async extractCreatedStrategyAddress(
+    response: LoopscaleTransactionResponse,
+  ): Promise<PublicKey> {
+    return extractCreatedStrategyAddress(this.connection, response)
+  }
+
+  /**
+   * Extract the strategy nonce from a `createStrategy` response using the client's connection.
+   */
+  async extractCreatedStrategyNonce(
+    response: LoopscaleTransactionResponse,
+  ): Promise<PublicKey> {
+    return extractCreatedStrategyNonce(this.connection, response)
+  }
+
+  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 !== undefined) {
+        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 += 1) {
+      response = await fetch(url, {
+        method: "POST",
+        headers,
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+      })
+
+      if (response.status === 429 && attempt < maxRetries) {
+        const delayMs = 2_000 * (attempt + 1)
+        if (this.debug) {
+          console.log(`  RATE LIMITED (429), retrying in ${delayMs}ms (attempt ${attempt + 1}/${maxRetries})...`)
+        }
+        await new Promise((resolve) => setTimeout(resolve, delayMs))
+        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
+  }
+}
+
+export {
+  deserializeLoopscaleTransactionBatchResponse,
+  deserializeLoopscaleTransactionResponse,
+  extractCreatedStrategyAddress,
+  extractCreatedStrategyNonce,
+  getLoopscaleTransactionResponses,
+  identifyLoopscaleInstruction,
+}