@exponent-labs/exponent-sdk 0.9.0 → 0.9.2

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

@@ -0,0 +1,73 @@
+import type {
+  AccountMeta,
+  Connection,
+  PublicKey,
+  Signer,
+  TransactionInstruction,
+  VersionedTransaction,
+} from "@solana/web3.js"
+
+/**
+ * Context required to turn a raw Loopscale response into manager-ready vault
+ * transaction pieces through `LoopscaleClient.prepareVaultTransactions(...)`.
+ */
+export interface LoopscaleVaultPreparationContext {
+  /** Solana RPC connection used to resolve raw Loopscale lookup tables. */
+  connection: Connection
+  /** Manager or caller public key that will sign and pay for the prepared transaction. */
+  signer: PublicKey
+  /** Squads vault PDA that owns the managed assets. */
+  vaultPda: PublicKey
+  /** Optional vault PDA used for automatic policy and hook resolution. */
+  vaultAddress?: PublicKey
+  /** Optional explicit policy PDA. */
+  policyPda?: PublicKey
+  /** Optional explicit Squads constraint indices. */
+  constraintIndices?: number[]
+  /** Squads account index. Defaults to `0` when omitted. */
+  accountIndex?: number
+  /** Optional leading policy accounts. */
+  leadingAccounts?: PublicKey[] | AccountMeta[]
+  /** Optional pre-hook accounts. */
+  preHookAccounts?: PublicKey[] | AccountMeta[]
+  /** Optional post-hook accounts. */
+  postHookAccounts?: PublicKey[] | AccountMeta[]
+  /** Squads program override. */
+  squadsProgram?: PublicKey
+}
+
+/**
+ * Context required to compile prepared Loopscale vault transactions into
+ * locally signed `VersionedTransaction`s through
+ * `LoopscaleClient.buildVaultTransactions(...)`.
+ */
+export interface LoopscaleBuildTransactionsContext extends LoopscaleVaultPreparationContext {
+  /** Signing keypairs used to locally sign the returned transactions. */
+  signers: Signer[]
+}
+
+/**
+ * Appendable transaction pieces derived from a raw Loopscale response.
+ *
+ * This is the return type for `LoopscaleClient.prepareVaultTransactions(...)`.
+ *
+ * Send `setupInstructions` first when present, then send `instructions`.
+ * `requiresLoopscaleCoSign` tells callers whether the main transaction still
+ * needs `client.coSign(...)` before broadcasting.
+ */
+export interface LoopscalePreparedTransaction {
+  setupInstructions: TransactionInstruction[]
+  instructions: TransactionInstruction[]
+  signers: Signer[]
+  addressLookupTableAddresses: PublicKey[]
+  requiresLoopscaleCoSign: boolean
+}
+
+/**
+ * Locally signed transaction returned by
+ * `LoopscaleClient.buildVaultTransactions(...)`.
+ */
+export interface LoopscaleBuiltTransaction {
+  transaction: VersionedTransaction
+  requiresLoopscaleCoSign: boolean
+}

package/src/exponentVaults/loopscale/types.ts

@@ -0,0 +1,466 @@
+import type { Connection, PublicKey } from "@solana/web3.js"
+
+/**
+ * Configuration for creating a {@link LoopscaleClient}.
+ *
+ * Import the runtime client from `client.ts` or the package barrel.
+ */
+export interface LoopscaleClientConfig {
+  /** Solana RPC connection used for transaction decoding helpers. */
+  connection: Connection
+  /** Default wallet address used for `user-wallet` / `User-Wallet` headers. */
+  userWallet: PublicKey | string
+  /** Optional default fee payer for Loopscale transaction endpoints. Defaults to `userWallet`. */
+  payer?: PublicKey | string
+  /** Base URL for the Loopscale API. */
+  baseUrl?: string
+  /** Enable verbose request/response logging. */
+  debug?: boolean
+}
+
+/**
+ * Signature metadata returned by Loopscale for a versioned transaction message.
+ */
+export interface LoopscaleTransactionSignature {
+  /** Base58 public key of the signer. */
+  publicKey: string
+  /** Base64-encoded 64-byte ed25519 signature. */
+  signature: string
+}
+
+/**
+ * Raw versioned transaction response returned by most Loopscale transaction endpoints.
+ */
+export interface LoopscaleVersionedTransactionResponse {
+  /** Base64-encoded versioned transaction message. */
+  message: string
+  /** Pre-signed signatures already attached by Loopscale. */
+  signatures: LoopscaleTransactionSignature[]
+}
+
+/**
+ * Raw batch transaction response returned by multi-transaction Loopscale endpoints.
+ */
+export type LoopscaleVersionedTransactionBatchResponse = LoopscaleVersionedTransactionResponse[]
+
+/**
+ * Minimal post-transaction loan snapshot returned by some Loopscale loan endpoints.
+ */
+export interface LoopscaleExpectedLoanInfo {
+  loan?: {
+    address?: string
+    [key: string]: unknown
+  }
+  [key: string]: unknown
+}
+
+/**
+ * Multi-transaction loan response returned by some Loopscale loan endpoints.
+ */
+export interface LoopscaleTransactionsResponse {
+  /** One or more serialized transactions returned by Loopscale. */
+  transactions: LoopscaleVersionedTransactionResponse[]
+  /** Optional post-transaction loan snapshot. */
+  expectedLoanInfo?: LoopscaleExpectedLoanInfo
+}
+
+/**
+ * Raw loan transaction response returned by CPI-compatible loan endpoints.
+ */
+export type LoopscaleLoanTransactionResponse =
+  | LoopscaleVersionedTransactionResponse
+  | LoopscaleTransactionsResponse
+
+/**
+ * Raw response returned by Loopscale loan creation.
+ */
+export interface LoopscaleCreateLoanResponse {
+  /** Serialized transaction used to create the loan. */
+  transaction: LoopscaleVersionedTransactionResponse
+  /** Derived loan PDA created by the returned transaction. */
+  loanAddress: string
+}
+
+/**
+ * Union of all raw Loopscale transaction response families supported by the SDK.
+ */
+export type LoopscaleTransactionResponse =
+  | LoopscaleVersionedTransactionResponse
+  | LoopscaleVersionedTransactionBatchResponse
+  | LoopscaleTransactionsResponse
+  | LoopscaleCreateLoanResponse
+
+/**
+ * Request params for `POST /markets/quote`.
+ */
+export interface LoopscaleQuoteParams {
+  durationType: number
+  duration: number
+  principal: PublicKey | string
+  collateral: Array<PublicKey | string>
+  limit?: number
+  offset?: number
+  minPrincipalAmount?: bigint | number
+}
+
+/**
+ * Response item returned by `POST /markets/quote`.
+ */
+export interface LoopscaleQuote {
+  apy: number
+  ltv: number
+  liquidationThreshold: number
+  maxPrincipalAvailable: number
+  sumPrincipalAvailable?: number
+  [key: string]: unknown
+}
+
+/**
+ * Request params for `POST /markets/quote/max`.
+ */
+export interface LoopscaleMaxQuoteParams {
+  durationType: number
+  duration: number
+  principalMint: PublicKey | string
+  collateralFilter: Array<{
+    amount: bigint | number
+    assetData: { Spl: { mint: string } } | { Orca: { positionMint: string; whirlpool: string } }
+  }>
+}
+
+/**
+ * Quote item returned by `POST /markets/quote/max`.
+ */
+export interface LoopscaleMaxQuote {
+  apy: number
+  strategy: string
+  collateralIdentifier: string
+  ltv: number
+  lqt: number
+  amount: number
+}
+
+/**
+ * Request params for `POST /markets/loans/info`.
+ *
+ * This matches the documented request body. The observed response is a single
+ * object with `totalCount` and `loanInfos`.
+ */
+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[]
+}
+
+/**
+ * Response returned by `POST /markets/loans/info`.
+ */
+export interface LoopscaleLoanInfoResponse {
+  totalCount: number
+  principalMints?: string[]
+  collateralMints?: string[]
+  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
+  }>
+}
+
+/**
+ * Request params for `POST /markets/strategy/infos`.
+ */
+export interface LoopscaleGetStrategiesParams {
+  userAddress?: string
+  addresses?: string[]
+  principalMints?: string[]
+  page?: number
+  pageSize?: number
+}
+
+/**
+ * Response returned by `POST /markets/strategy/infos`.
+ */
+export interface LoopscaleStrategyInfoResponse {
+  strategies: Array<{
+    strategy: {
+      address: string
+      principalMint: string
+      tokenBalance: number
+      currentDeployedAmount: number
+      outstandingInterestAmount: number
+      [key: string]: unknown
+    }
+    externalYieldInfo?: {
+      apy: number
+      [key: string]: unknown
+    }
+    [key: string]: unknown
+  }>
+  total: number
+}
+
+/**
+ * Strategy create request for `POST /markets/strategy/create`.
+ */
+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
+}
+
+/**
+ * Strategy deposit request for `POST /markets/strategy/deposit`.
+ */
+export interface LoopscaleDepositStrategyParams {
+  strategy: PublicKey | string
+  amount: bigint | number
+}
+
+/**
+ * Strategy withdraw request for `POST /markets/strategy/withdraw`.
+ */
+export interface LoopscaleWithdrawStrategyParams {
+  strategy: PublicKey | string
+  amount: bigint | number
+  withdrawAll: boolean
+}
+
+/**
+ * Strategy close request for `POST /markets/strategy/close/{strategy}`.
+ */
+export interface LoopscaleCloseStrategyParams {
+  strategy: PublicKey | string
+}
+
+/**
+ * External yield source configuration used by Loopscale strategy endpoints.
+ */
+export interface ExternalYieldSourceParams {
+  newExternalYieldSource: number
+}
+
+/**
+ * Strategy create args for initializing external yield state through Loopscale.
+ */
+export interface TxnExternalYieldSourceArgs extends ExternalYieldSourceParams {
+  createExternalYieldAccount: boolean
+}
+
+/**
+ * Duration tuple used by strategy collateral configuration.
+ */
+export interface StrategyDuration {
+  duration: number
+  durationType: number
+}
+
+/**
+ * Strategy collateral add args.
+ */
+export interface AddCollateralArgs {
+  durationsAndApys?: Record<string, string>
+  externalMarketInformationAddress?: string
+  marketInformation?: Record<string, unknown>
+}
+
+/**
+ * Strategy collateral remove args.
+ */
+export interface RemoveCollateralArgs {
+  durations: StrategyDuration[]
+  removeFromMarketInformation: boolean
+}
+
+/**
+ * Strategy collateral param update args.
+ */
+export interface CollateralParamsUpdateArgs {
+  ltvUpdate?: Record<string, unknown>
+  apyUpdate?: Record<string, string>
+}
+
+/**
+ * Strategy allocation update args.
+ */
+export interface CollateralAllocationUpdateArgs {
+  assetIdentifier: string
+  maxAllocationPct: string
+}
+
+/**
+ * Strategy collateral update payload for `POST /markets/strategy/update`.
+ */
+export interface StrategyCollateralUpdates {
+  addCollateral?: Record<string, AddCollateralArgs>
+  removeCollateral?: Record<string, RemoveCollateralArgs>
+  updateCollateral?: Record<string, CollateralParamsUpdateArgs>
+  updateAssetAllocation?: CollateralAllocationUpdateArgs[]
+}
+
+/**
+ * Strategy settings update payload for `POST /markets/strategy/update`.
+ */
+export interface EditStrategySettingsArgs {
+  originationsEnabled?: boolean
+  liquidityBuffer?: number
+  interestFee?: number
+  originationFee?: number
+  principalFee?: number
+  originationCap?: number
+  externalYieldSource?: ExternalYieldSourceParams
+}
+
+/**
+ * Strategy update request for `POST /markets/strategy/update`.
+ */
+export interface LoopscaleUpdateStrategyParams {
+  strategy: PublicKey | string
+  collateralTerms?: StrategyCollateralUpdates
+  updateParams?: EditStrategySettingsArgs
+}
+
+/**
+ * Loan create request for `POST /markets/creditbook/create`.
+ */
+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
+}
+
+/**
+ * Loan borrow request for `POST /markets/creditbook/borrow`.
+ */
+export interface LoopscaleBorrowPrincipalParams {
+  loan: PublicKey | string
+  borrowParams: {
+    amount: bigint | number
+    durationIndex: number
+    expectedLoanValues?: { expectedApy?: number; expectedLqt?: number[] }
+  }
+  strategy: PublicKey | string
+  refinanceParams?: { ledgerIndex: number; durationIndex: number }
+  isLoop?: boolean
+}
+
+/**
+ * Loan collateral deposit request for `POST /markets/creditbook/collateral/deposit`.
+ */
+export interface LoopscaleDepositCollateralParams {
+  loan: PublicKey | string
+  depositMint: PublicKey | string
+  amount: bigint | number
+  assetType: number
+  assetIdentifier: PublicKey | string
+  assetIndexGuidance?: number[]
+  expectedLoanValues?: { expectedApy?: number; expectedLqt?: number[] }
+}
+
+/**
+ * Loan collateral withdraw request for `POST /markets/creditbook/collateral/withdraw`.
+ */
+export interface LoopscaleWithdrawCollateralParams {
+  loan: PublicKey | string
+  collateralMint: PublicKey | string
+  amount: bigint | number
+  collateralIndex: number
+  expectedLoanValues: { expectedApy?: number; expectedLqt?: number[] }
+  assetIndexGuidance?: number[]
+}
+
+/**
+ * Loan simple repay request for `POST /markets/creditbook/repay_simple`.
+ */
+export interface LoopscaleRepayLoanSimpleParams {
+  loan: PublicKey | string
+  repayParams: {
+    amount: bigint | number
+    ledgerIndex: number
+    repayAll: boolean
+  }
+  strategy: PublicKey | string
+}
+
+/**
+ * Loan close request for `POST /markets/creditbook/close_loan`.
+ */
+export interface LoopscaleCloseLoanParams {
+  loan: PublicKey | string
+}
+
+/**
+ * Supported Loopscale strategy + loan instruction names recognized by the SDK.
+ */
+export type LoopscaleInstructionName =
+  | "createLoan"
+  | "depositCollateral"
+  | "borrowPrincipal"
+  | "repayPrincipal"
+  | "withdrawCollateral"
+  | "closeLoan"
+  | "updateWeightMatrix"
+  | "lockLoan"
+  | "unlockLoan"
+  | "createStrategy"
+  | "depositStrategy"
+  | "withdrawStrategy"
+  | "closeStrategy"
+  | "updateStrategy"
+  | "refinanceLedger"