@zofai/zo-sdk 0.1.92

package/src/interfaces/base.ts

@@ -0,0 +1,838 @@
+/**
+ * Base interfaces for all SDK implementations
+ * This file defines the common contracts that all LP token SDKs must implement
+ */
+
+import type { KioskClient, KioskOwnerCap } from '@mysten/kiosk'
+import type { SuiClient } from '@mysten/sui/client'
+import type { Transaction, TransactionObjectArgument } from '@mysten/sui/transactions'
+import type { PriceFeed } from '@pythnetwork/pyth-sui-js'
+
+import type { IConsts, LPToken, Network } from '../consts'
+
+// Common data interfaces
+export interface IBaseMarketValuationInfo {
+  marketCap: number
+  price: number
+  supply: number
+  apr?: number
+}
+
+export interface IBaseMarketInfo {
+  lpSupply: string
+  positionId: string
+  vaultId: string
+  symbolId: string
+  lpSupplyWithDecimals: number
+  referralId?: string
+  orderId?: string
+  rebaseFeeModel?: string
+  apr?: string
+}
+
+export interface IBaseVaultInfo {
+  liquidity: number
+  reservedAmount: number
+  unrealisedReservingFeeAmount: number
+  accReservingRate: number
+  enabled: boolean
+  weight: number
+  lastUpdate: number
+  reservingFeeModel: IBaseReservingFeeModel
+  priceConfig: {
+    maxInterval: number
+    maxConfidence: number
+    precision: number
+    feeder: string
+  }
+}
+
+export interface IBaseReservingFeeModel {
+  multiplier: number
+}
+
+export interface IBaseFundingFeeModel {
+  multiplier: number
+  max: number
+}
+
+export interface IBaseRebaseFeeModel {
+  base: number
+  multiplier: number
+  /** Exponent for rebase fee curve (default 1 = linear when not set on chain) */
+  exponent?: number
+}
+
+export interface IBaseSymbolInfo {
+  objectId: string
+  openingSize: number
+  openingAmount: number
+  accFundingRate: number
+  realisedPnl: number
+  unrealisedFundingFeeValue: number
+  openEnabled: boolean
+  liquidateEnabled: boolean
+  decreaseEnabled: boolean
+  lastUpdate: number
+  fundingFeeModel: IBaseFundingFeeModel
+  long: boolean
+  priceConfig: {
+    maxInterval: number
+    maxConfidence: number
+    precision: number
+    feeder: string
+  }
+}
+
+export interface IBasePositionInfo {
+  id: string
+  long: boolean
+  owner: string
+  version: number
+  collateralToken: string
+  indexToken: string
+  collateralAmount: number
+  positionAmount: number
+  reservedAmount: number
+  positionSize: number
+  lastFundingRate: number
+  lastReservingRate: number
+  reservingFeeAmount: number
+  fundingFeeValue: number
+  closed: boolean
+  openTimestamp: number
+}
+
+export type IBaseOrderType = 'OPEN_POSITION' | 'DECREASE_POSITION' | 'OPEN_MARKET' | 'DECREASE_MARKET'
+export interface IBaseOrderInfo {
+  id: string
+  capId: string
+  executed: boolean
+  owner: string
+  collateralToken: string
+  indexToken: string
+  feeToken: string
+  collateralPriceThreshold: number
+  feeAmount: bigint
+  long: boolean
+  indexPrice: number
+  // New optional fields for upgraded Move structs
+  indexPriceThreshold?: number
+  referrer?: string
+  scardId?: string
+  scardRebateRate?: number
+  openOrder?: {
+    reserveAmount: bigint
+    collateralAmount: bigint
+    openAmount: bigint
+    // PositionConfig from OpenMarketOrder
+    positionConfig?: IBasePositionConfig
+  }
+  decreaseOrder?: {
+    decreaseAmount: bigint
+    takeProfit: boolean
+  }
+  orderType: IBaseOrderType
+  createdAt: number
+  v11Order?: boolean
+  orderVersion?: string
+}
+
+export interface IBasePositionConfig {
+  decreaseFeeBps: number
+  liquidationBonus: number
+  liquidationThreshold: number
+  maxLeverage: number
+  minHoldingDuration: number
+  openFeeBps: number
+  maxReservedMultiplier: number
+  minCollateralValue: number
+}
+
+export interface IBasePositionCapInfo {
+  positionCapId: string
+  symbol0: string
+  symbol1: string
+  long: boolean
+}
+
+export interface IBaseOrderCapInfo {
+  orderCapId: string
+  symbol0: string
+  symbol1: string
+  long: boolean
+  positionId: string | null
+}
+
+export interface IBaseHistory {
+  owner: string
+  txid: string
+  id: string
+  created: number
+  eventName: string
+  indexToken: string
+  direction: string
+  collateralAmount: number
+  collateralPrice: number
+  indexPrice: number
+  pnl: number
+  positionId: string
+  volume: number
+  fee: number
+  network: string
+}
+
+export interface IBasePagination {
+  total: number
+  page: number
+  limit: number
+  pages: number
+}
+
+export interface IBaseHistoryResponse {
+  histories: IBaseHistory[]
+  pagination: IBasePagination
+}
+
+export interface IBaseStaked {
+  credentials: IBaseCredential[]
+  amount: bigint
+  claimable: bigint
+}
+
+export interface IBaseStakePool {
+  id: string
+  enabled: boolean
+  lastUpdatedTime: number
+  stakedAmount: bigint
+  reward: bigint
+  startTime: number
+  endTime: number
+  accRewardPerShare: bigint
+  lockDuration: number
+}
+
+export interface IBaseCredential {
+  id: string
+  lockUntil: number
+  accRewardPerShare: bigint
+  amount: bigint
+  claimable: bigint
+}
+
+// Abstract base interfaces for SDK implementations
+export interface IBaseDataAPI {
+  readonly network: Network
+  readonly provider: SuiClient
+  readonly apiEndpoint: string
+  readonly connectionURL: string
+  readonly lpToken: LPToken
+  readonly consts: IConsts
+
+  // Core valuation methods
+  valuateVaults: (tx: Transaction) => any
+  valuateSymbols: (tx: Transaction) => any
+  valuate: (tx: Transaction) => { vaultsValuation: any, symbolsValuation: any }
+  valuateMarket: () => Promise<IBaseMarketValuationInfo>
+
+  // Fee methods
+  fundingFeeRate: (indexToken: string, long: boolean, sender?: string) => Promise<number>
+  rebaseFeeRate: (collateralToken: string, increase: boolean, amount: number, sender?: string) => Promise<number>
+  reservingFeeRate: (collateralToken: string, amount: number, sender?: string) => Promise<number>
+
+  // Market data methods
+  getMarketInfo: () => Promise<IBaseMarketInfo>
+  getVaultInfo: (vault: string) => Promise<IBaseVaultInfo>
+  getSymbolInfo: (tokenId: string, long: boolean) => Promise<IBaseSymbolInfo>
+  getPositionConfig: (indexToken: string, long: boolean) => Promise<IBasePositionConfig>
+  getRebaseFeeModel: () => Promise<IBaseRebaseFeeModel>
+  getOpenPositions: (batchSize: number, symbol: string) => Promise<IBasePositionInfo[]>
+
+  // User data methods
+  getPositionCapInfoList: (owner: string) => Promise<IBasePositionCapInfo[]>
+  getPositionInfoList: (positionCapInfoList: IBasePositionCapInfo[], owner: string, batchSize?: number) => Promise<IBasePositionInfo[]>
+  getOrderCapInfoList: (owner: string) => Promise<IBaseOrderCapInfo[]>
+  getOrderInfoList: (orderCapInfoList: IBaseOrderCapInfo[], owner: string, batchSize?: number) => Promise<IBaseOrderInfo[]>
+  getHistory: (trader: string, page: number, limit: number, orderType?: string, symbol?: string) => Promise<IBaseHistoryResponse>
+
+  // Staking methods
+  getStaked: (owner: string) => Promise<IBaseStaked>
+  getStakePool: () => Promise<IBaseStakePool>
+
+  // Referral methods
+  hasReferral: (referree: string) => Promise<boolean>
+  getReferralData: (referree: string) => Promise<any>
+
+  // Oracle methods
+  getOraclePrice: (tokenId: string) => Promise<PriceFeed>
+  getOraclePrices: (tokens: string[]) => Promise<PriceFeed[]>
+  subOraclePrices: (tokens: string[], callback: (price: PriceFeed) => void) => Promise<() => void>
+  initOracleTxb: (tokens: string[], tx?: Transaction) => Promise<Transaction>
+
+  // Utility methods
+  validateCache: () => void
+}
+
+export interface IBaseAPI {
+  // LP operations
+  deposit: (
+    coin: string,
+    coinObjects: string[],
+    amount: number,
+    minAmountOut?: number,
+    referralAddress?: string,
+    sender?: string,
+    sponsoredTx?: boolean,
+    suiCoinObjectsForPythUpdate?: string[],
+  ) => Promise<Transaction>
+
+  withdraw: (
+    coin: string,
+    lpCoinObjects: string[],
+    amount: number,
+    minAmountOut?: number,
+    sponsoredTx?: boolean,
+    suiCoinObjectsForPythUpdate?: string[],
+  ) => Promise<Transaction>
+
+  swap: (
+    fromToken: string,
+    toToken: string,
+    fromAmount: bigint,
+    fromCoinObjects: string[],
+  ) => Promise<Transaction>
+
+  // Staking
+  stake: (
+    lpCoinObjects: string[],
+    amount: bigint,
+    pool: string,
+    tx?: Transaction
+  ) => Transaction
+
+  unstake: (
+    credentials: IBaseCredential[],
+    amount: bigint,
+    pool: string,
+    tx?: Transaction
+  ) => Transaction
+
+  // Trading operations
+  openPosition: (
+    collateralToken: string,
+    indexToken: string,
+    size: bigint,
+    collateralAmount: bigint,
+    coinObjects: string[],
+    long: boolean,
+    reserveAmount: bigint,
+    indexPrice: number,
+    collateralPrice: number,
+    isLimitOrder?: boolean,
+    isIocOrder?: boolean,
+    pricesSlippage?: number,
+    collateralSlippage?: number,
+    relayerFee?: bigint,
+    referralAddress?: string,
+    sender?: string,
+    sponsoredTx?: boolean,
+    suiCoinObjectsForPythUpdate?: string[],
+  ) => Promise<Transaction>
+
+  // Trading operations
+  openPositionWithCoin?: (
+    collateralToken: string,
+    indexToken: string,
+    size: bigint,
+    coinObj: TransactionObjectArgument,
+    long: boolean,
+    reserveAmount: bigint,
+    indexPrice: number,
+    collateralPrice: number,
+    isLimitOrder?: boolean,
+    isIocOrder?: boolean,
+    pricesSlippage?: number,
+    collateralSlippage?: number,
+    relayerFee?: bigint,
+    referralAddress?: string,
+    sender?: string,
+    tx?: Transaction,
+    sponsoredTx?: boolean,
+    suiCoinObjectsForPythUpdate?: string[],
+  ) => Promise<Transaction>
+
+  decreasePosition: (
+    pcpId: string,
+    collateralToken: string,
+    indexToken: string,
+    amount: bigint,
+    long: boolean,
+    indexPrice: number,
+    collateralPrice: number,
+    isTriggerOrder?: boolean,
+    isTakeProfitOrder?: boolean,
+    isIocOrder?: boolean,
+    pricesSlippage?: number,
+    collateralSlippage?: number,
+    relayerFee?: bigint,
+    coinObjects?: string[],
+    sponsoredTx?: boolean,
+    suiCoinObjectsForPythUpdate?: string[],
+  ) => Promise<Transaction>
+
+  decreaseMultiPositions: (
+    positions: Array<{
+      pcpId: string
+      collateralToken: string
+      indexToken: string
+      amount: bigint
+      long: boolean
+      indexPrice: number
+      collateralPrice: number
+      isTriggerOrder?: boolean
+      isTakeProfitOrder?: boolean
+      isIocOrder?: boolean
+      pricesSlippage?: number
+      collateralSlippage?: number
+      relayerFee?: bigint
+      coinObjects?: string[]
+    }>,
+    tx?: Transaction,
+    sponsoredTx?: boolean,
+    suiCoinObjectsForPythUpdate?: string[],
+  ) => Promise<Transaction>
+
+  openPositionV2?: (
+    collateralToken: string,
+    indexToken: string,
+    size: bigint,
+    collateralAmount: bigint,
+    coinObjects: string[],
+    long: boolean,
+    reserveAmount: bigint,
+    indexPrice: number,
+    collateralPrice: number,
+    isLimitOrder?: boolean,
+    isIocOrder?: boolean,
+    pricesSlippage?: number,
+    collateralSlippage?: number,
+    relayerFee?: bigint,
+    referralAddress?: string,
+    sender?: string,
+    sponsoredTx?: boolean,
+    suiCoinObjectsForPythUpdate?: string[],
+  ) => Promise<Transaction>
+
+  // Trading operations
+  openPositionWithCoinV2?: (
+    collateralToken: string,
+    indexToken: string,
+    size: bigint,
+    coinObj: TransactionObjectArgument,
+    long: boolean,
+    reserveAmount: bigint,
+    indexPrice: number,
+    collateralPrice: number,
+    isLimitOrder?: boolean,
+    isIocOrder?: boolean,
+    pricesSlippage?: number,
+    collateralSlippage?: number,
+    relayerFee?: bigint,
+    referralAddress?: string,
+    sender?: string,
+    tx?: Transaction,
+    sponsoredTx?: boolean,
+    suiCoinObjectsForPythUpdate?: string[],
+  ) => Promise<Transaction>
+
+  decreasePositionV2?: (
+    pcpId: string,
+    collateralToken: string,
+    indexToken: string,
+    amount: bigint,
+    long: boolean,
+    indexPrice: number,
+    collateralPrice: number,
+    isTriggerOrder?: boolean,
+    isTakeProfitOrder?: boolean,
+    isIocOrder?: boolean,
+    pricesSlippage?: number,
+    collateralSlippage?: number,
+    relayerFee?: bigint,
+    coinObjects?: string[],
+    sponsoredTx?: boolean,
+    suiCoinObjectsForPythUpdate?: string[],
+  ) => Promise<Transaction>
+
+  decreaseMultiPositionsV2?: (
+    positions: Array<{
+      pcpId: string
+      collateralToken: string
+      indexToken: string
+      amount: bigint
+      long: boolean
+      indexPrice: number
+      collateralPrice: number
+      isTriggerOrder?: boolean
+      isTakeProfitOrder?: boolean
+      isIocOrder?: boolean
+      pricesSlippage?: number
+      collateralSlippage?: number
+      relayerFee?: bigint
+      coinObjects?: string[]
+    }>,
+    tx?: Transaction,
+    sponsoredTx?: boolean,
+    suiCoinObjectsForPythUpdate?: string[],
+    feeObjects?: TransactionObjectArgument[],
+  ) => Promise<Transaction>
+
+  pledgeInPosition: (
+    pcpId: string,
+    collateralToken: string,
+    indexToken: string,
+    amount: number,
+    coinObjects: string[],
+    long: boolean,
+    sponsoredTx?: boolean,
+    suiCoinObjectsForPythUpdate?: string[],
+  ) => Promise<Transaction>
+
+  redeemFromPosition: (
+    pcpId: string,
+    collateralToken: string,
+    indexToken: string,
+    amount: number,
+    long: boolean,
+    sponsoredTx?: boolean,
+    suiCoinObjectsForPythUpdate?: string[],
+  ) => Promise<Transaction>
+
+  cancelOrder: (
+    orderCapId: string,
+    collateralToken: string,
+    indexToken: string,
+    long: boolean,
+    type: string,
+    isV11Order?: boolean
+  ) => Transaction
+
+  cancelMultiOrders: (
+    orders: Array<{
+      orderCapId: string
+      collateralToken: string
+      indexToken: string
+      long: boolean
+      type: string
+      isV11Order?: boolean
+    }>,
+    tx?: Transaction
+  ) => Transaction
+
+  clearClosedPosition: (
+    pcpId: string,
+    collateralToken: string,
+    indexToken: string,
+    long: boolean,
+    tx: Transaction,
+  ) => void
+
+  clearOpenPositionOrder: (
+    orderCapId: string,
+    collateralToken: string,
+    indexToken: string,
+    long: boolean,
+    tx: Transaction,
+    isV11Order?: boolean
+  ) => void
+
+  clearDecreasePositionOrder: (
+    orderCapId: string,
+    collateralToken: string,
+    indexToken: string,
+    long: boolean,
+    tx: Transaction,
+    isV11Order?: boolean
+  ) => void
+
+  clearOpenMarketOrder?: (
+    orderCapId: string,
+    collateralToken: string,
+    indexToken: string,
+    long: boolean,
+    tx: Transaction,
+    isV11Order?: boolean
+  ) => void
+
+  clearDecreaseMarketOrder?: (
+    orderCapId: string,
+    collateralToken: string,
+    indexToken: string,
+    long: boolean,
+    tx: Transaction,
+    isV11Order?: boolean
+  ) => void
+
+  // S Card operations
+  openPositionWithSCard: (
+    collateralToken: string,
+    indexToken: string,
+    size: bigint,
+    collateralAmount: bigint,
+    coinObjects: string[],
+    long: boolean,
+    reserveAmount: bigint,
+    indexPrice: number,
+    collateralPrice: number,
+    kioskClient: KioskClient,
+    kioskCap: KioskOwnerCap,
+    scard: string,
+    isLimitOrder?: boolean,
+    isIocOrder?: boolean,
+    pricesSlippage?: number,
+    collateralSlippage?: number,
+    relayerFee?: bigint,
+    referralAddress?: string,
+    sender?: string,
+    sponsoredTx?: boolean,
+    suiCoinObjectsForPythUpdate?: string[],
+  ) => Promise<Transaction>
+
+  // S Card operations
+  openPositionWithCoinAndSCard?: (
+    collateralToken: string,
+    indexToken: string,
+    size: bigint,
+    coinObj: TransactionObjectArgument,
+    long: boolean,
+    reserveAmount: bigint,
+    indexPrice: number,
+    collateralPrice: number,
+    kioskClient: KioskClient,
+    kioskCap: KioskOwnerCap,
+    scard: string,
+    isLimitOrder?: boolean,
+    isIocOrder?: boolean,
+    pricesSlippage?: number,
+    collateralSlippage?: number,
+    relayerFee?: bigint,
+    referralAddress?: string,
+    sender?: string,
+    tx?: Transaction,
+    sponsoredTx?: boolean,
+    suiCoinObjectsForPythUpdate?: string[],
+  ) => Promise<Transaction>
+
+  decreasePositionWithSCard: (
+    pcpId: string,
+    collateralToken: string,
+    indexToken: string,
+    amount: bigint,
+    long: boolean,
+    indexPrice: number,
+    collateralPrice: number,
+    kioskClient: KioskClient,
+    kioskCap: KioskOwnerCap,
+    scard: string,
+    isTriggerOrder?: boolean,
+    isTakeProfitOrder?: boolean,
+    isIocOrder?: boolean,
+    pricesSlippage?: number,
+    collateralSlippage?: number,
+    relayerFee?: bigint,
+    coinObjects?: string[],
+    sponsoredTx?: boolean,
+    suiCoinObjectsForPythUpdate?: string[],
+  ) => Promise<Transaction>
+
+  decreaseMultiPositionsWithSCard: (
+    positions: Array<{
+      pcpId: string
+      collateralToken: string
+      indexToken: string
+      amount: bigint
+      long: boolean
+      indexPrice: number
+      collateralPrice: number
+      isTriggerOrder?: boolean
+      isTakeProfitOrder?: boolean
+      isIocOrder?: boolean
+      pricesSlippage?: number
+      collateralSlippage?: number
+      relayerFee?: bigint
+      coinObjects?: string[]
+    }>,
+    kioskClient: KioskClient,
+    kioskCap: KioskOwnerCap,
+    scard: string,
+    tx?: Transaction,
+    sponsoredTx?: boolean,
+    suiCoinObjectsForPythUpdate?: string[],
+  ) => Promise<Transaction>
+
+  openPositionWithSCardV2?: (
+    collateralToken: string,
+    indexToken: string,
+    size: bigint,
+    collateralAmount: bigint,
+    coinObjects: string[],
+    long: boolean,
+    reserveAmount: bigint,
+    indexPrice: number,
+    collateralPrice: number,
+    kioskClient: KioskClient,
+    kioskCap: KioskOwnerCap,
+    scard: string,
+    isLimitOrder?: boolean,
+    isIocOrder?: boolean,
+    pricesSlippage?: number,
+    collateralSlippage?: number,
+    relayerFee?: bigint,
+    referralAddress?: string,
+    sender?: string,
+    sponsoredTx?: boolean,
+    suiCoinObjectsForPythUpdate?: string[],
+  ) => Promise<Transaction>
+
+  // S Card operations
+  openPositionWithCoinAndSCardV2?: (
+    collateralToken: string,
+    indexToken: string,
+    size: bigint,
+    coinObj: TransactionObjectArgument,
+    long: boolean,
+    reserveAmount: bigint,
+    indexPrice: number,
+    collateralPrice: number,
+    kioskClient: KioskClient,
+    kioskCap: KioskOwnerCap,
+    scard: string,
+    isLimitOrder?: boolean,
+    isIocOrder?: boolean,
+    pricesSlippage?: number,
+    collateralSlippage?: number,
+    relayerFee?: bigint,
+    referralAddress?: string,
+    sender?: string,
+    tx?: Transaction,
+    sponsoredTx?: boolean,
+    suiCoinObjectsForPythUpdate?: string[],
+  ) => Promise<Transaction>
+
+  decreasePositionWithSCardV2?: (
+    pcpId: string,
+    collateralToken: string,
+    indexToken: string,
+    amount: bigint,
+    long: boolean,
+    indexPrice: number,
+    collateralPrice: number,
+    kioskClient: KioskClient,
+    kioskCap: KioskOwnerCap,
+    scard: string,
+    isTriggerOrder?: boolean,
+    isTakeProfitOrder?: boolean,
+    isIocOrder?: boolean,
+    pricesSlippage?: number,
+    collateralSlippage?: number,
+    relayerFee?: bigint,
+    coinObjects?: string[],
+    sponsoredTx?: boolean,
+    suiCoinObjectsForPythUpdate?: string[],
+  ) => Promise<Transaction>
+
+  decreaseMultiPositionsWithSCardV2?: (
+    positions: Array<{
+      pcpId: string
+      collateralToken: string
+      indexToken: string
+      amount: bigint
+      long: boolean
+      indexPrice: number
+      collateralPrice: number
+      isTriggerOrder?: boolean
+      isTakeProfitOrder?: boolean
+      isIocOrder?: boolean
+      pricesSlippage?: number
+      collateralSlippage?: number
+      relayerFee?: bigint
+      coinObjects?: string[]
+    }>,
+    kioskClient: KioskClient,
+    kioskCap: KioskOwnerCap,
+    scard: string,
+    tx?: Transaction,
+    sponsoredTx?: boolean,
+    suiCoinObjectsForPythUpdate?: string[],
+    feeObjects?: TransactionObjectArgument[],
+  ) => Promise<Transaction>
+
+  claimTokenFromSCard: (
+    token: string,
+    coinObjects: string[],
+    kioskClient: KioskClient,
+    kioskCap: KioskOwnerCap,
+    scard: string,
+  ) => Transaction
+
+  // Miscellaneous
+  addReferral: (
+    referrer: string,
+    tx?: Transaction
+  ) => Transaction
+
+  // Admin operations
+  adminUpdatePriceFeed: (
+    collateralToken: string,
+    indexToken: string
+  ) => Promise<Transaction>
+
+  adminSettlePosition: (
+    positionId: string,
+    owner: string,
+    collateralToken: string,
+    indexToken: string,
+    long: boolean,
+  ) => Transaction
+
+  adminDecreasePosition: (
+    positionId: string,
+    owner: string,
+    collateralToken: string,
+    indexToken: string,
+    positionAmount: number,
+    amount: bigint,
+    long: boolean,
+    collateralPrice?: number,
+    collateralSlippage?: number,
+    relayerFee?: bigint
+  ) => Transaction
+
+  adminClearClosedPosition: (
+    positionId: string,
+    owner: string,
+    collateralToken: string,
+    indexToken: string,
+    long: boolean,
+    tx: Transaction
+  ) => void
+}
+
+// Factory interface for creating SDK instances
+export interface ISDKFactory {
+  createDataAPI: (
+    network: Network,
+    provider: SuiClient,
+    apiEndpoint: string,
+    connectionURL: string,
+    lpToken: LPToken
+  ) => IBaseDataAPI
+
+  createAPI: (
+    network: Network,
+    provider: SuiClient,
+    apiEndpoint: string,
+    connectionURL: string,
+    lpToken: LPToken
+  ) => IBaseAPI
+}