@exponent-labs/exponent-sdk 0.9.0 → 0.9.2

package/src/exponentVaults/loopscale/helpers.ts

@@ -0,0 +1,172 @@
+import {
+  Connection,
+  PublicKey,
+  TransactionInstruction,
+  TransactionMessage,
+  VersionedMessage,
+  VersionedTransaction,
+} from "@solana/web3.js"
+
+import type {
+  LoopscaleInstructionName,
+  LoopscaleTransactionResponse,
+  LoopscaleVersionedTransactionBatchResponse,
+  LoopscaleVersionedTransactionResponse,
+} from "./types"
+import { LOOPSCALE_DISCRIMINATORS, LOOPSCALE_PROGRAM_ID } from "../policyBuilders"
+
+const DISCRIMINATOR_HEX_TO_NAME = new Map<string, LoopscaleInstructionName>(
+  Object.entries(LOOPSCALE_DISCRIMINATORS).map(([name, discriminator]) => [
+    Buffer.from(discriminator).toString("hex"),
+    name as LoopscaleInstructionName,
+  ]),
+)
+
+function buildTransactionFromResponse(
+  response: LoopscaleVersionedTransactionResponse,
+): VersionedTransaction {
+  const message = VersionedMessage.deserialize(Buffer.from(response.message, "base64"))
+  const transaction = new VersionedTransaction(message)
+  const signerKeys = message.staticAccountKeys.slice(0, message.header.numRequiredSignatures)
+
+  for (const signature of response.signatures) {
+    const signer = new PublicKey(signature.publicKey)
+    const bytes = Buffer.from(signature.signature, "base64")
+    if (bytes.length !== 64) {
+      throw new Error(`Invalid signature for ${signature.publicKey}`)
+    }
+
+    const signerIndex = signerKeys.findIndex((candidate) => candidate.equals(signer))
+    if (signerIndex >= 0) {
+      transaction.signatures[signerIndex] = new Uint8Array(bytes)
+    }
+  }
+
+  return transaction
+}
+
+async function resolveAddressLookupTables(
+  connection: Connection,
+  transaction: VersionedTransaction,
+) {
+  return 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
+    }),
+  )
+}
+
+async function findInstructionByName(
+  connection: Connection,
+  transactions: VersionedTransaction[],
+  name: LoopscaleInstructionName,
+): Promise<TransactionInstruction | null> {
+  for (const transaction of transactions) {
+    const addressLookupTableAccounts = await resolveAddressLookupTables(connection, transaction)
+    const instructions = TransactionMessage.decompile(transaction.message, { addressLookupTableAccounts }).instructions
+    const match = instructions.find((instruction) => identifyLoopscaleInstruction(instruction) === name)
+    if (match) {
+      return match
+    }
+  }
+
+  return null
+}
+
+/**
+ * Identify a Loopscale strategy or loan instruction from its discriminator.
+ *
+ * Returns `null` for non-Loopscale instructions and for unsupported Loopscale
+ * instructions outside the strategies + loans scope of this SDK module.
+ */
+export function identifyLoopscaleInstruction(
+  instruction: TransactionInstruction,
+): LoopscaleInstructionName | null {
+  if (!instruction.programId.equals(LOOPSCALE_PROGRAM_ID)) {
+    return null
+  }
+
+  const discriminator = Buffer.from(instruction.data).subarray(0, 8).toString("hex")
+  return DISCRIMINATOR_HEX_TO_NAME.get(discriminator) ?? null
+}
+
+/**
+ * Deserialize a raw Loopscale transaction response into a `VersionedTransaction`.
+ */
+export function deserializeLoopscaleTransactionResponse(
+  response: LoopscaleVersionedTransactionResponse,
+): VersionedTransaction {
+  return buildTransactionFromResponse(response)
+}
+
+/**
+ * Deserialize a raw Loopscale transaction batch response into `VersionedTransaction`s.
+ */
+export function deserializeLoopscaleTransactionBatchResponse(
+  response: LoopscaleVersionedTransactionBatchResponse,
+): VersionedTransaction[] {
+  return response.map((entry) => deserializeLoopscaleTransactionResponse(entry))
+}
+
+/**
+ * Extract the raw transaction responses from any supported Loopscale transaction response shape.
+ */
+export function getLoopscaleTransactionResponses(
+  response: LoopscaleTransactionResponse,
+): LoopscaleVersionedTransactionResponse[] {
+  if (Array.isArray(response)) {
+    return response
+  }
+
+  if ("transactions" in response) {
+    return response.transactions
+  }
+
+  if ("transaction" in response) {
+    return [response.transaction]
+  }
+
+  return [response]
+}
+
+/**
+ * Extract the strategy PDA created by a Loopscale `createStrategy` response.
+ */
+export async function extractCreatedStrategyAddress(
+  connection: Connection,
+  response: LoopscaleTransactionResponse,
+): Promise<PublicKey> {
+  const transactions = getLoopscaleTransactionResponses(response)
+    .map((entry) => deserializeLoopscaleTransactionResponse(entry))
+  const instruction = await findInstructionByName(connection, transactions, "createStrategy")
+
+  const strategy = instruction?.keys[3]?.pubkey
+  if (!strategy) {
+    throw new Error("Loopscale createStrategy response did not contain a createStrategy instruction")
+  }
+
+  return strategy
+}
+
+/**
+ * Extract the nonce public key used by a Loopscale `createStrategy` response.
+ */
+export async function extractCreatedStrategyNonce(
+  connection: Connection,
+  response: LoopscaleTransactionResponse,
+): Promise<PublicKey> {
+  const transactions = getLoopscaleTransactionResponses(response)
+    .map((entry) => deserializeLoopscaleTransactionResponse(entry))
+  const instruction = await findInstructionByName(connection, transactions, "createStrategy")
+
+  const nonce = instruction?.keys[2]?.pubkey
+  if (!nonce) {
+    throw new Error("Loopscale createStrategy response did not contain the strategy nonce account")
+  }
+
+  return nonce
+}

package/src/exponentVaults/loopscale/index.ts

@@ -0,0 +1,57 @@
+export {
+  LoopscaleClient,
+  deserializeLoopscaleTransactionResponse,
+  deserializeLoopscaleTransactionBatchResponse,
+  extractCreatedStrategyAddress,
+  extractCreatedStrategyNonce,
+  getLoopscaleTransactionResponses,
+  identifyLoopscaleInstruction,
+} from "./client"
+
+export type {
+  AddCollateralArgs,
+  CollateralAllocationUpdateArgs,
+  CollateralParamsUpdateArgs,
+  EditStrategySettingsArgs,
+  ExternalYieldSourceParams,
+  LoopscaleBorrowPrincipalParams,
+  LoopscaleClientConfig,
+  LoopscaleCloseLoanParams,
+  LoopscaleCloseStrategyParams,
+  LoopscaleCreateLoanParams,
+  LoopscaleCreateLoanResponse,
+  LoopscaleCreateStrategyParams,
+  LoopscaleDepositCollateralParams,
+  LoopscaleDepositStrategyParams,
+  LoopscaleExpectedLoanInfo,
+  LoopscaleGetStrategiesParams,
+  LoopscaleInstructionName,
+  LoopscaleLoanInfoParams,
+  LoopscaleLoanInfoResponse,
+  LoopscaleLoanTransactionResponse,
+  LoopscaleMaxQuote,
+  LoopscaleMaxQuoteParams,
+  LoopscaleQuote,
+  LoopscaleQuoteParams,
+  LoopscaleRepayLoanSimpleParams,
+  LoopscaleStrategyInfoResponse,
+  LoopscaleTransactionResponse,
+  LoopscaleTransactionSignature,
+  LoopscaleTransactionsResponse,
+  LoopscaleUpdateStrategyParams,
+  LoopscaleVersionedTransactionBatchResponse,
+  LoopscaleVersionedTransactionResponse,
+  LoopscaleWithdrawCollateralParams,
+  LoopscaleWithdrawStrategyParams,
+  RemoveCollateralArgs,
+  StrategyCollateralUpdates,
+  StrategyDuration,
+  TxnExternalYieldSourceArgs,
+} from "./types"
+
+export type {
+  LoopscaleBuildTransactionsContext,
+  LoopscaleBuiltTransaction,
+  LoopscalePreparedTransaction,
+  LoopscaleVaultPreparationContext,
+} from "./prepared-types"

package/src/exponentVaults/loopscale/prepared-transactions.ts

@@ -0,0 +1,435 @@
+import {
+  AddressLookupTableProgram,
+  ComputeBudgetProgram,
+  PublicKey,
+  TransactionInstruction,
+  TransactionMessage,
+  VersionedTransaction,
+} from "@solana/web3.js"
+
+import {
+  resolveConstraintIndices,
+  resolveHookAccounts,
+  resolvePolicyMatchForVault,
+} from "../policyMatcher"
+import { wrapInstructionsInSyncTransaction } from "../syncTransaction"
+import {
+  createVaultSyncTransaction,
+  type LoopscaleInstruction,
+  loopscaleAction,
+} from "../vault-interaction"
+import {
+  deserializeLoopscaleTransactionResponse,
+  getLoopscaleTransactionResponses,
+  identifyLoopscaleInstruction,
+} from "./helpers"
+import type {
+  LoopscalePreparedTransaction,
+  LoopscaleVaultPreparationContext,
+} from "./prepared-types"
+import type {
+  LoopscaleTransactionResponse,
+} from "./types"
+
+type SupportedPreparedInstructionName =
+  | "borrowPrincipal"
+  | "closeLoan"
+  | "closeStrategy"
+  | "createLoan"
+  | "createStrategy"
+  | "depositCollateral"
+  | "depositStrategy"
+  | "repayPrincipal"
+  | "updateStrategy"
+  | "updateWeightMatrix"
+  | "withdrawCollateral"
+  | "withdrawStrategy"
+
+const LOOPSCALE_WRAPPERS: Record<
+  SupportedPreparedInstructionName,
+  (instruction: TransactionInstruction) => LoopscaleInstruction
+> = {
+  borrowPrincipal: (instruction) => loopscaleAction.borrowPrincipal({ instruction }),
+  closeLoan: (instruction) => loopscaleAction.closeLoan({ instruction }),
+  closeStrategy: (instruction) => loopscaleAction.closeStrategy({ instruction }),
+  createLoan: (instruction) => loopscaleAction.createLoan({ instruction }),
+  createStrategy: (instruction) => loopscaleAction.createStrategy({ instruction }),
+  depositCollateral: (instruction) => loopscaleAction.depositCollateral({ instruction }),
+  depositStrategy: (instruction) => loopscaleAction.depositStrategy({ instruction }),
+  repayPrincipal: (instruction) => loopscaleAction.repayPrincipal({ instruction }),
+  updateStrategy: (instruction) => loopscaleAction.updateStrategy({ instruction }),
+  updateWeightMatrix: (instruction) => loopscaleAction.updateWeightMatrix({ instruction }),
+  withdrawCollateral: (instruction) => loopscaleAction.withdrawCollateral({ instruction }),
+  withdrawStrategy: (instruction) => loopscaleAction.withdrawStrategy({ instruction }),
+}
+
+async function decompileTransaction(
+  context: LoopscaleVaultPreparationContext,
+  transaction: VersionedTransaction,
+): Promise<TransactionInstruction[]> {
+  const addressLookupTableAccounts = await Promise.all(
+    transaction.message.addressTableLookups.map(async (lookup) => {
+      const result = await context.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 }).instructions
+}
+
+function wrapLoopscaleInstruction(instruction: TransactionInstruction): LoopscaleInstruction {
+  const name = identifyLoopscaleInstruction(instruction)
+  if (!name) {
+    throw new Error("Encountered a non-Loopscale or unsupported Loopscale instruction in a sync segment")
+  }
+
+  if (!(name in LOOPSCALE_WRAPPERS)) {
+    throw new Error(`Loopscale instruction ${name} is not supported through Exponent CPI execution`)
+  }
+
+  return LOOPSCALE_WRAPPERS[name as SupportedPreparedInstructionName](instruction)
+}
+
+function getLoopscaleInstructionSegment(instructions: TransactionInstruction[]): {
+  firstLoopscaleIndex: number
+  lastLoopscaleIndex: number
+} | null {
+  const loopscaleIndices = instructions
+    .map((instruction, index) => identifyLoopscaleInstruction(instruction) !== null ? index : -1)
+    .filter((index) => index !== -1)
+
+  if (loopscaleIndices.length === 0) {
+    return null
+  }
+
+  return {
+    firstLoopscaleIndex: loopscaleIndices[0]!,
+    lastLoopscaleIndex: loopscaleIndices[loopscaleIndices.length - 1]!,
+  }
+}
+
+function splitLoopscaleInstructions(
+  instructions: TransactionInstruction[],
+  segment: { firstLoopscaleIndex: number; lastLoopscaleIndex: number },
+): {
+  prefixInstructions: TransactionInstruction[]
+  syncInstructions: LoopscaleInstruction[]
+  suffixInstructions: TransactionInstruction[]
+} {
+  const syncInstructions: LoopscaleInstruction[] = []
+  const prefixInstructions: TransactionInstruction[] = []
+  const suffixInstructions: TransactionInstruction[] = []
+
+  for (let index = 0; index < instructions.length; index += 1) {
+    const instruction = instructions[index]!
+    const name = identifyLoopscaleInstruction(instruction)
+    const isInsideSyncSegment = index >= segment.firstLoopscaleIndex && index <= segment.lastLoopscaleIndex
+
+    if (isInsideSyncSegment) {
+      if (name === null) {
+        throw new Error(
+          "Loopscale response contains non-Loopscale instructions interleaved within the sync segment",
+        )
+      }
+
+      syncInstructions.push(wrapLoopscaleInstruction(instruction))
+      continue
+    }
+
+    if (index < segment.firstLoopscaleIndex) {
+      prefixInstructions.push(instruction)
+      continue
+    }
+
+    suffixInstructions.push(instruction)
+  }
+
+  return { prefixInstructions, syncInstructions, suffixInstructions }
+}
+
+function mergeLookupTableAddresses(
+  left: readonly PublicKey[],
+  right: readonly PublicKey[],
+): PublicKey[] {
+  const seen = new Set<string>()
+  const merged = [...left, ...right]
+
+  return merged.filter((address) => {
+    const key = address.toBase58()
+    if (seen.has(key)) {
+      return false
+    }
+    seen.add(key)
+    return true
+  })
+}
+
+function isComputeBudgetInstruction(instruction: TransactionInstruction): boolean {
+  return instruction.programId.equals(ComputeBudgetProgram.programId)
+}
+
+function isIgnorableLoopscaleTopLevelInstruction(
+  instruction: TransactionInstruction,
+): boolean {
+  return instruction.programId.equals(AddressLookupTableProgram.programId)
+}
+
+function getExtraSignerKeys(
+  instruction: TransactionInstruction,
+  signer: PublicKey,
+): PublicKey[] {
+  return instruction.keys
+    .filter((key) => key.isSigner && !key.pubkey.equals(signer))
+    .map((key) => key.pubkey)
+}
+
+function instructionNeedsVaultWrapping(
+  instruction: TransactionInstruction,
+  context: LoopscaleVaultPreparationContext,
+): boolean {
+  const extraSignerKeys = getExtraSignerKeys(instruction, context.signer)
+  if (extraSignerKeys.length === 0) {
+    return false
+  }
+
+  const allVaultSignerKeys = extraSignerKeys.every((key) => key.equals(context.vaultPda))
+  if (!allVaultSignerKeys) {
+    throw new Error(
+      `Loopscale response contains a top-level instruction with unsupported signer requirements: ${extraSignerKeys
+        .map((key) => key.toBase58())
+        .join(", ")}`,
+    )
+  }
+
+  return true
+}
+
+async function wrapVaultSignedInstructions(
+  instructions: TransactionInstruction[],
+  context: LoopscaleVaultPreparationContext,
+): Promise<TransactionInstruction> {
+  let resolvedPolicyPda = context.policyPda
+  let resolvedConstraintIndices = context.constraintIndices
+
+  if (!resolvedPolicyPda) {
+    if (!context.vaultAddress) {
+      throw new Error(
+        "Loopscale top-level vault-signed instructions require either context.policyPda or context.vaultAddress",
+      )
+    }
+
+    const match = await resolvePolicyMatchForVault(
+      context.connection,
+      context.vaultAddress,
+      context.signer,
+      instructions,
+    )
+    resolvedPolicyPda = match.policyPda
+    resolvedConstraintIndices ??= match.constraintIndices
+  } else {
+    resolvedConstraintIndices ??= await resolveConstraintIndices(
+      context.connection,
+      resolvedPolicyPda,
+      instructions,
+    )
+  }
+
+  let resolvedLeadingAccounts = context.leadingAccounts
+  let resolvedPreHookAccounts = context.preHookAccounts
+  let resolvedPostHookAccounts = context.postHookAccounts
+  if (
+    context.vaultAddress
+    && (!resolvedLeadingAccounts || !resolvedPreHookAccounts || !resolvedPostHookAccounts)
+  ) {
+    const hooks = await resolveHookAccounts(
+      context.connection,
+      resolvedPolicyPda,
+      context.vaultAddress,
+      context.signer,
+    )
+    resolvedLeadingAccounts ??= hooks.leadingAccounts
+    resolvedPreHookAccounts ??= hooks.preHookAccounts
+    resolvedPostHookAccounts ??= hooks.postHookAccounts
+  }
+
+  return wrapInstructionsInSyncTransaction({
+    policyPda: resolvedPolicyPda,
+    vaultPda: context.vaultPda,
+    signer: context.signer,
+    instructions,
+    accountIndex: context.accountIndex,
+    constraintIndices: resolvedConstraintIndices,
+    leadingAccounts: resolvedLeadingAccounts,
+    preHookAccounts: resolvedPreHookAccounts,
+    postHookAccounts: resolvedPostHookAccounts,
+    squadsProgram: context.squadsProgram,
+  })
+}
+
+async function prepareTopLevelInstructions({
+  instructions,
+  context,
+  rawLookupTableAddresses,
+}: {
+  instructions: TransactionInstruction[]
+  context: LoopscaleVaultPreparationContext
+  rawLookupTableAddresses: PublicKey[]
+}): Promise<LoopscalePreparedTransaction[]> {
+  const preparedTransactions: LoopscalePreparedTransaction[] = []
+  let pendingComputeInstructions: TransactionInstruction[] = []
+  let currentInstructions: TransactionInstruction[] = []
+  let currentMode: "standalone" | "wrapped" | null = null
+
+  const flush = async () => {
+    if (currentInstructions.length === 0) {
+      pendingComputeInstructions = []
+      currentMode = null
+      return
+    }
+
+    if (currentMode === "standalone") {
+      preparedTransactions.push({
+        setupInstructions: [],
+        instructions: [...pendingComputeInstructions, ...currentInstructions],
+        signers: [],
+        addressLookupTableAddresses: rawLookupTableAddresses,
+        requiresLoopscaleCoSign: false,
+      })
+    } else {
+      const wrappedInstruction = await wrapVaultSignedInstructions(currentInstructions, context)
+      preparedTransactions.push({
+        setupInstructions: [],
+        instructions: [...pendingComputeInstructions, wrappedInstruction],
+        signers: [],
+        addressLookupTableAddresses: [],
+        requiresLoopscaleCoSign: false,
+      })
+    }
+
+    pendingComputeInstructions = []
+    currentInstructions = []
+    currentMode = null
+  }
+
+  for (const instruction of instructions) {
+    if (isIgnorableLoopscaleTopLevelInstruction(instruction)) {
+      continue
+    }
+
+    if (isComputeBudgetInstruction(instruction)) {
+      pendingComputeInstructions.push(instruction)
+      continue
+    }
+
+    const nextMode = instructionNeedsVaultWrapping(instruction, context) ? "wrapped" : "standalone"
+    if (currentMode && currentMode !== nextMode) {
+      await flush()
+    }
+
+    currentMode = nextMode
+    currentInstructions.push(instruction)
+  }
+
+  await flush()
+  return preparedTransactions
+}
+
+/**
+ * Internal adapter used by `LoopscaleClient.prepareVaultTransactions(...)`.
+ *
+ * It converts raw Loopscale responses into manager-ready transaction pieces:
+ * standalone top-level transactions, wrapped top-level vault-signed
+ * transactions, or wrapped Loopscale sync transactions.
+ */
+export async function prepareLoopscaleVaultTransactions({
+  response,
+  context,
+}: {
+  response: LoopscaleTransactionResponse
+  context: LoopscaleVaultPreparationContext
+}): Promise<LoopscalePreparedTransaction[]> {
+  const rawResponses = getLoopscaleTransactionResponses(response)
+  const preparedTransactions: LoopscalePreparedTransaction[] = []
+
+  for (const rawResponse of rawResponses) {
+    const rawTransaction = deserializeLoopscaleTransactionResponse(rawResponse)
+    const instructions = await decompileTransaction(context, rawTransaction)
+    const segment = getLoopscaleInstructionSegment(instructions)
+    const rawLookupTableAddresses = rawTransaction.message.addressTableLookups.map((lookup) => lookup.accountKey)
+
+    if (!segment) {
+      preparedTransactions.push(
+        ...(await prepareTopLevelInstructions({
+          instructions,
+          context,
+          rawLookupTableAddresses,
+        })),
+      )
+      continue
+    }
+
+    const {
+      prefixInstructions,
+      syncInstructions,
+      suffixInstructions,
+    } = splitLoopscaleInstructions(instructions, segment)
+    const syncResult = await createVaultSyncTransaction({
+      instructions: syncInstructions,
+      owner: context.vaultPda,
+      connection: context.connection,
+      policyPda: context.policyPda,
+      vaultPda: context.vaultPda,
+      signer: context.signer,
+      accountIndex: context.accountIndex,
+      constraintIndices: context.constraintIndices,
+      vaultAddress: context.vaultAddress,
+      leadingAccounts: context.leadingAccounts,
+      preHookAccounts: context.preHookAccounts,
+      postHookAccounts: context.postHookAccounts,
+      squadsProgram: context.squadsProgram,
+      autoManagePositions: false,
+    })
+
+    const prefixComputeInstructions = prefixInstructions.filter(isComputeBudgetInstruction)
+    const prefixNonComputeInstructions = prefixInstructions.filter(
+      (instruction) => !isComputeBudgetInstruction(instruction),
+    )
+
+    preparedTransactions.push(
+      ...(await prepareTopLevelInstructions({
+        instructions: prefixNonComputeInstructions,
+        context,
+        rawLookupTableAddresses,
+      })),
+    )
+
+    preparedTransactions.push({
+      setupInstructions: syncResult.setupInstructions,
+      instructions: [
+        ...prefixComputeInstructions,
+        ...syncResult.preInstructions,
+        syncResult.instruction,
+        ...syncResult.postInstructions,
+      ],
+      signers: syncResult.signers,
+      addressLookupTableAddresses: mergeLookupTableAddresses(
+        syncResult.addressLookupTableAddresses,
+        rawLookupTableAddresses,
+      ),
+      requiresLoopscaleCoSign: true,
+    })
+
+    preparedTransactions.push(
+      ...(await prepareTopLevelInstructions({
+        instructions: suffixInstructions,
+        context,
+        rawLookupTableAddresses,
+      })),
+    )
+  }
+
+  return preparedTransactions
+}