@exponent-labs/exponent-sdk 0.1.8 → 0.9.1

package/src/exponentVaults/vault-instruction-types.ts

@@ -0,0 +1,493 @@
+import { PublicKey, TransactionInstruction } from "@solana/web3.js"
+import { SwapDirection } from "../client/clmm"
+import { KAMINO_RESERVES, KaminoMarket } from "./kamino-markets"
+import BN from "bn.js"
+
+// ============================================================================
+// Vault Instruction Types
+// ============================================================================
+
+type KaminoReserves = typeof KAMINO_RESERVES
+
+/** Actions that can be performed through the vault instruction builder. */
+export enum VaultAction {
+  INIT_USER_METADATA = "INIT_USER_METADATA",
+  INIT_OBLIGATION = "INIT_OBLIGATION",
+  DEPOSIT = "DEPOSIT",
+  WITHDRAW = "WITHDRAW",
+  BORROW = "BORROW",
+  REPAY = "REPAY",
+}
+
+/** A market-level instruction (no specific reserve needed). */
+export type MarketInstruction = {
+  action: VaultAction.INIT_USER_METADATA | VaultAction.INIT_OBLIGATION
+  market: KaminoMarket
+}
+
+/** A reserve-level instruction with an amount. */
+export type ReserveInstruction = {
+  action: VaultAction.DEPOSIT | VaultAction.WITHDRAW | VaultAction.BORROW | VaultAction.REPAY
+  market: KaminoMarket
+  asset: string
+  amount: BN
+}
+
+// ============================================================================
+// Kamino Vault Instruction Types
+// ============================================================================
+
+/** Actions that can be performed on a direct Kamino Vault position. */
+export enum KaminoVaultAction {
+  DEPOSIT = "KAMINO_VAULT_DEPOSIT",
+  WITHDRAW = "KAMINO_VAULT_WITHDRAW",
+}
+
+type KaminoVaultInstructionBase = {
+  action: KaminoVaultAction
+  vault: PublicKey
+}
+
+/** Deposit the vault-owned token account into a Kamino Vault and mint shares. */
+export type KaminoVaultDepositInstruction = KaminoVaultInstructionBase & {
+  action: KaminoVaultAction.DEPOSIT
+  amount: BN
+}
+
+/** Withdraw Kamino Vault shares back into the vault-owned token account. */
+export type KaminoVaultWithdrawInstruction = KaminoVaultInstructionBase & {
+  action: KaminoVaultAction.WITHDRAW
+  sharesAmount: BN
+  /** Required when the Kamino Vault currently allocates across multiple reserves. */
+  reserve?: PublicKey
+}
+
+export type KaminoVaultInstruction =
+  | KaminoVaultDepositInstruction
+  | KaminoVaultWithdrawInstruction
+
+// ============================================================================
+// Kamino Farm Instruction Types
+// ============================================================================
+
+/** Actions that can be performed on a direct Kamino Farm position. */
+export enum KaminoFarmAction {
+  INITIALIZE_USER = "KAMINO_FARM_INITIALIZE_USER",
+  STAKE = "KAMINO_FARM_STAKE",
+  UNSTAKE = "KAMINO_FARM_UNSTAKE",
+  WITHDRAW_UNSTAKED_DEPOSITS = "KAMINO_FARM_WITHDRAW_UNSTAKED_DEPOSITS",
+  HARVEST_REWARD = "KAMINO_FARM_HARVEST_REWARD",
+}
+
+type KaminoFarmInstructionBase = {
+  action: KaminoFarmAction
+  farmState: PublicKey
+  /**
+   * Optional delegatee used to derive the Farm `user_state`.
+   * Defaults to the managed vault owner when omitted.
+   */
+  delegatee?: PublicKey
+}
+
+/** Initialize the Farm `user_state` PDA for the vault owner or delegatee. */
+export type KaminoFarmInitializeUserInstruction = KaminoFarmInstructionBase & {
+  action: KaminoFarmAction.INITIALIZE_USER
+}
+
+/** Stake tokens from the vault-owned ATA into the Farm. */
+export type KaminoFarmStakeInstruction = KaminoFarmInstructionBase & {
+  action: KaminoFarmAction.STAKE
+  amount: BN | "ALL"
+}
+
+/** Unstake a scaled share amount from the Farm. */
+export type KaminoFarmUnstakeInstruction = KaminoFarmInstructionBase & {
+  action: KaminoFarmAction.UNSTAKE
+  stakeSharesScaled: BN
+}
+
+/** Withdraw matured unstaked deposits back into the vault-owned ATA. */
+export type KaminoFarmWithdrawUnstakedDepositsInstruction = KaminoFarmInstructionBase & {
+  action: KaminoFarmAction.WITHDRAW_UNSTAKED_DEPOSITS
+}
+
+/** Harvest a single Farm reward into a vault-owned reward ATA. */
+export type KaminoFarmHarvestRewardInstruction = KaminoFarmInstructionBase & {
+  action: KaminoFarmAction.HARVEST_REWARD
+  rewardIndex: number
+}
+
+export type KaminoFarmInstruction =
+  | KaminoFarmInitializeUserInstruction
+  | KaminoFarmStakeInstruction
+  | KaminoFarmUnstakeInstruction
+  | KaminoFarmWithdrawUnstakedDepositsInstruction
+  | KaminoFarmHarvestRewardInstruction
+
+// ============================================================================
+// Orderbook Instruction Types
+// ============================================================================
+
+/** Orderbook trade direction */
+export enum OrderbookTradeDirection {
+  BUY_PT = "BUY_PT",
+  SELL_PT = "SELL_PT",
+  BUY_YT = "BUY_YT",
+  SELL_YT = "SELL_YT",
+}
+
+/** Offer options for limit orders (currently only FillOrKill supported) */
+export type OrderbookOfferOption = "FillOrKill"
+
+/** Actions that can be performed on the Exponent Orderbook */
+export enum OrderbookAction {
+  POST_OFFER = "POST_OFFER",
+  MARKET_OFFER = "MARKET_OFFER",
+  REMOVE_OFFER = "REMOVE_OFFER",
+  WITHDRAW_FUNDS = "WITHDRAW_FUNDS",
+}
+
+export type OrderbookInstructionMode = "wrapper" | "raw"
+
+/** Base instruction type for all orderbook operations */
+interface OrderbookInstructionBase {
+  action: OrderbookAction
+  orderbook: PublicKey
+  mode?: OrderbookInstructionMode
+}
+
+/** Post a limit order on the orderbook */
+export interface OrderbookPostOfferInstruction extends OrderbookInstructionBase {
+  action: OrderbookAction.POST_OFFER
+  direction: OrderbookTradeDirection
+  priceApy: number
+  amount: bigint
+  offerOption?: OrderbookOfferOption
+  expirySeconds?: number
+}
+
+/** Execute a market order on the orderbook */
+export interface OrderbookMarketOfferInstruction extends OrderbookInstructionBase {
+  action: OrderbookAction.MARKET_OFFER
+  direction: OrderbookTradeDirection
+  maxPriceApy: number
+  amount: bigint
+  minAmountOut: bigint
+  virtualOffer?: boolean
+}
+
+/** Cancel an existing limit order */
+export interface OrderbookRemoveOfferInstruction extends OrderbookInstructionBase {
+  action: OrderbookAction.REMOVE_OFFER
+  offerIdx: number
+}
+
+/** Withdraw funds from user escrow */
+export interface OrderbookWithdrawFundsInstruction extends OrderbookInstructionBase {
+  action: OrderbookAction.WITHDRAW_FUNDS
+  ptAmount?: bigint | null
+  ytAmount?: bigint | null
+  syAmount?: bigint | null
+}
+
+/** A single orderbook instruction */
+export type OrderbookInstruction =
+  | OrderbookPostOfferInstruction
+  | OrderbookMarketOfferInstruction
+  | OrderbookRemoveOfferInstruction
+  | OrderbookWithdrawFundsInstruction
+
+// ============================================================================
+// Core Instruction Types (Strip/Merge)
+// ============================================================================
+
+/** Actions that can be performed on Exponent Core */
+export enum CoreAction {
+  STRIP = "STRIP",
+  MERGE = "MERGE",
+  WITHDRAW_YT = "WITHDRAW_YT",
+  DEPOSIT_YT = "DEPOSIT_YT",
+  INITIALIZE_YIELD_POSITION = "INITIALIZE_YIELD_POSITION",
+}
+
+/** Base instruction type for all core operations */
+interface CoreInstructionBase {
+  action: CoreAction
+  vault: PublicKey
+}
+
+/** Strip LST into PT + YT */
+export interface CoreStripInstruction extends CoreInstructionBase {
+  action: CoreAction.STRIP
+  /** Amount of base token (LST) to strip */
+  amountBase: bigint
+}
+
+/** Merge PT + YT into LST */
+export interface CoreMergeInstruction extends CoreInstructionBase {
+  action: CoreAction.MERGE
+  /** Amount of PT/YT to merge (must have equal amounts of both) */
+  amountPy: bigint
+}
+
+/** Withdraw YT from the tracked yield position back into the YT token account */
+export interface CoreWithdrawYtInstruction extends CoreInstructionBase {
+  action: CoreAction.WITHDRAW_YT
+  amountYt: bigint
+}
+
+/** Deposit YT from the YT token account back into the tracked yield position */
+export interface CoreDepositYtInstruction extends CoreInstructionBase {
+  action: CoreAction.DEPOSIT_YT
+  amountYt: bigint
+}
+
+/** Initialize yield position for a vault (owner = Squads vault) */
+export interface CoreInitializeYieldPositionInstruction extends CoreInstructionBase {
+  action: CoreAction.INITIALIZE_YIELD_POSITION
+}
+
+/** A single core instruction */
+export type CoreInstruction =
+  | CoreStripInstruction
+  | CoreMergeInstruction
+  | CoreWithdrawYtInstruction
+  | CoreDepositYtInstruction
+  | CoreInitializeYieldPositionInstruction
+
+// ============================================================================
+// Standard Program Instruction Types (mint_sy / redeem_sy)
+// ============================================================================
+
+export enum SyAction {
+  MINT = "MINT_SY",
+  REDEEM = "REDEEM_SY",
+}
+
+interface SyInstructionBase {
+  action: SyAction
+  vault: PublicKey
+}
+
+export interface SyMintInstruction extends SyInstructionBase {
+  action: SyAction.MINT
+  amountBase: bigint
+}
+
+export interface SyRedeemInstruction extends SyInstructionBase {
+  action: SyAction.REDEEM
+  amountSy: bigint
+}
+
+export type SyInstruction = SyMintInstruction | SyRedeemInstruction
+
+// ============================================================================
+// Titan Instruction Types
+// ============================================================================
+
+export enum TitanAction {
+  SWAP = "SWAP",
+}
+
+/** A pre-built Titan swap instruction to wrap in a sync transaction. */
+export interface TitanSwapInstruction {
+  action: TitanAction.SWAP
+  /** The raw Titan SwapRouteV2 TransactionInstruction (from Titan's router API) */
+  instruction: TransactionInstruction
+  /** ALT addresses returned by Titan's router for this route. */
+  addressLookupTableAddresses?: PublicKey[]
+}
+
+// ============================================================================
+// Loopscale Instruction Types
+// ============================================================================
+
+/** Actions for Loopscale interactions (loans = borrower side, strategies = lender side). */
+export enum LoopscaleAction {
+  CREATE_LOAN = "LOOPSCALE_CREATE_LOAN",
+  DEPOSIT_COLLATERAL = "LOOPSCALE_DEPOSIT_COLLATERAL",
+  BORROW_PRINCIPAL = "LOOPSCALE_BORROW_PRINCIPAL",
+  REPAY_PRINCIPAL = "LOOPSCALE_REPAY_PRINCIPAL",
+  WITHDRAW_COLLATERAL = "LOOPSCALE_WITHDRAW_COLLATERAL",
+  CLOSE_LOAN = "LOOPSCALE_CLOSE_LOAN",
+  UPDATE_WEIGHT_MATRIX = "LOOPSCALE_UPDATE_WEIGHT_MATRIX",
+  CREATE_STRATEGY = "LOOPSCALE_CREATE_STRATEGY",
+  DEPOSIT_STRATEGY = "LOOPSCALE_DEPOSIT_STRATEGY",
+  WITHDRAW_STRATEGY = "LOOPSCALE_WITHDRAW_STRATEGY",
+  CLOSE_STRATEGY = "LOOPSCALE_CLOSE_STRATEGY",
+  UPDATE_STRATEGY = "LOOPSCALE_UPDATE_STRATEGY",
+  LOCK_LOAN = "LOOPSCALE_LOCK_LOAN",
+  UNLOCK_LOAN = "LOOPSCALE_UNLOCK_LOAN",
+  REFINANCE_LEDGER = "LOOPSCALE_REFINANCE_LEDGER",
+}
+
+/** A pre-built Loopscale instruction (loan or strategy) to wrap in a sync transaction. */
+export interface LoopscaleInstruction {
+  action: LoopscaleAction
+  /** The raw Loopscale TransactionInstruction (from Loopscale API or local builder) */
+  instruction: TransactionInstruction
+}
+
+// ============================================================================
+// CLMM Instruction Types
+// ============================================================================
+
+/** Actions that can be performed on the Exponent CLMM (Concentrated Liquidity Market Maker). */
+export enum ClmmAction {
+  /** Create a new LP position with a specified tick range. Generates keypair internally. */
+  DEPOSIT_LIQUIDITY = "CLMM_DEPOSIT_LIQUIDITY",
+  /** Add more liquidity to an existing LP position. */
+  ADD_LIQUIDITY = "CLMM_ADD_LIQUIDITY",
+  /** Remove liquidity from an LP position and receive PT + SY. */
+  WITHDRAW_LIQUIDITY = "CLMM_WITHDRAW_LIQUIDITY",
+  /** Low-level PT/SY swap. Prefer buyPt/sellPt for directional trades. */
+  TRADE_PT = "CLMM_TRADE_PT",
+  /** Buy PT with SY on the CLMM. */
+  BUY_PT = "CLMM_BUY_PT",
+  /** Sell PT for SY on the CLMM. */
+  SELL_PT = "CLMM_SELL_PT",
+  /** Buy YT with SY on the CLMM. */
+  BUY_YT = "CLMM_BUY_YT",
+  /** Sell YT for SY on the CLMM. */
+  SELL_YT = "CLMM_SELL_YT",
+  /** Claim farm emissions from an LP position. */
+  CLAIM_FARM_EMISSION = "CLMM_CLAIM_FARM_EMISSION",
+}
+
+/** Base type for all CLMM instructions. */
+interface ClmmInstructionBase {
+  action: ClmmAction
+  /** The CLMM MarketThree account address. */
+  market: PublicKey
+}
+
+/** Create a new LP position on the CLMM. The lpPosition keypair is generated internally for good UX. */
+export interface ClmmDepositLiquidityInstruction extends ClmmInstructionBase {
+  action: ClmmAction.DEPOSIT_LIQUIDITY
+  /** Maximum amount of PT to deposit. */
+  ptInIntent: bigint
+  /** Maximum amount of SY to deposit. */
+  syInIntent: bigint
+  /** Lower tick boundary (APY value). */
+  lowerTickKey: number
+  /** Upper tick boundary (APY value). */
+  upperTickKey: number
+}
+
+/** Add liquidity to an existing LP position. */
+export interface ClmmAddLiquidityInstruction extends ClmmInstructionBase {
+  action: ClmmAction.ADD_LIQUIDITY
+  /** The existing LpPosition account public key. */
+  lpPosition: PublicKey
+  /** Maximum amount of PT to add. */
+  ptInIntent: bigint
+  /** Maximum amount of SY to add. */
+  syInIntent: bigint
+}
+
+/** Withdraw liquidity from an LP position. */
+export interface ClmmWithdrawLiquidityInstruction extends ClmmInstructionBase {
+  action: ClmmAction.WITHDRAW_LIQUIDITY
+  /** The LpPosition account to withdraw from. */
+  lpPosition: PublicKey
+  /** Amount of liquidity (LP units) to remove. */
+  lpIn: bigint
+  /** Minimum PT to receive (slippage protection). */
+  minPtOut: bigint
+  /** Minimum SY to receive (slippage protection). */
+  minSyOut: bigint
+}
+
+/** Low-level PT/SY swap on the CLMM. Prefer buyPt/sellPt for directional trades. */
+export interface ClmmTradePtInstruction extends ClmmInstructionBase {
+  action: ClmmAction.TRADE_PT
+  /** Amount of the input token. */
+  traderAmount: bigint
+  /** Minimum output amount (slippage protection). */
+  outConstraint: bigint
+  /** Swap direction: SyToPt or PtToSy. */
+  swapDirection: SwapDirection
+  /** Optional price limit (ln implied APY). */
+  lnImpliedApyLimit?: number
+}
+
+/** Buy PT with SY on the CLMM. */
+export interface ClmmBuyPtInstruction extends ClmmInstructionBase {
+  action: ClmmAction.BUY_PT
+  /** Amount of SY to spend. */
+  amountSy: bigint
+  /** Minimum PT to receive (slippage protection). */
+  outConstraint: bigint
+  /** Optional price limit (ln implied APY). */
+  lnImpliedApyLimit?: number
+}
+
+/** Sell PT for SY on the CLMM. */
+export interface ClmmSellPtInstruction extends ClmmInstructionBase {
+  action: ClmmAction.SELL_PT
+  /** Amount of PT to sell. */
+  amountPt: bigint
+  /** Minimum SY to receive (slippage protection). */
+  outConstraint: bigint
+  /** Optional price limit (ln implied APY). */
+  lnImpliedApyLimit?: number
+}
+
+/** Buy YT with SY on the CLMM. */
+export interface ClmmBuyYtInstruction extends ClmmInstructionBase {
+  action: ClmmAction.BUY_YT
+  /** Minimum amount of YT to receive. */
+  ytOut: bigint
+  /** Maximum amount of SY to spend. */
+  maxSyIn: bigint
+  /** Optional price limit (ln implied APY). */
+  lnImpliedApyLimit?: number
+}
+
+/** Sell YT for SY on the CLMM. */
+export interface ClmmSellYtInstruction extends ClmmInstructionBase {
+  action: ClmmAction.SELL_YT
+  /** Amount of YT to sell. */
+  ytIn: bigint
+  /** Minimum SY to receive (slippage protection). */
+  minSyOut: bigint
+  /** Optional price limit (ln implied APY). */
+  lnImpliedApyLimit?: number
+}
+
+/** Claim farm emissions from an LP position. */
+export interface ClmmClaimFarmEmissionInstruction extends ClmmInstructionBase {
+  action: ClmmAction.CLAIM_FARM_EMISSION
+  /** The LpPosition account to claim from. */
+  lpPosition: PublicKey
+  /** Index of the farm to claim from. */
+  farmIndex: number
+}
+
+/** A single CLMM instruction. */
+export type ClmmInstruction =
+  | ClmmDepositLiquidityInstruction
+  | ClmmAddLiquidityInstruction
+  | ClmmWithdrawLiquidityInstruction
+  | ClmmTradePtInstruction
+  | ClmmBuyPtInstruction
+  | ClmmSellPtInstruction
+  | ClmmBuyYtInstruction
+  | ClmmSellYtInstruction
+  | ClmmClaimFarmEmissionInstruction
+
+/** A single vault instruction — pass an array of these to `createVaultSyncTransaction`. */
+export type VaultInstruction =
+  | MarketInstruction
+  | ReserveInstruction
+  | KaminoVaultInstruction
+  | KaminoFarmInstruction
+  | OrderbookInstruction
+  | CoreInstruction
+  | SyInstruction
+  | TitanSwapInstruction
+  | ClmmInstruction
+  | LoopscaleInstruction
+
+// Re-export KaminoReserves for use in action builders
+export type { KaminoReserves }