@zofai/zo-sdk 0.1.93 → 0.1.95

package/src/implementations/ZLPDataAPI.ts

@@ -15,6 +15,7 @@ import type {
   IBaseHistoryResponse,
   IBaseOrderType,
   IBaseStaked,
+  ISwapFeeBreakdown,
   IZLPCredential,
   IZLPDataAPI,
   IZLPFundingFeeModel,
@@ -37,6 +38,20 @@ import type {
 } from '../interfaces'
 import { joinSymbol, parseSymbolKey, parseValue, suiSymbolToSymbol } from '../utils'
 
+interface SwapImpactConfig {
+  id: string
+  enabled: boolean
+  impactMultiplier: number
+  maxImpactRate: number
+}
+
+interface EmaVolatilityFeeConfig {
+  id: string
+  enabled: boolean
+  multiplier: number
+  maxFeeRate: number
+}
+
 export class ZLPDataAPI extends BaseDataAPI implements IZLPDataAPI {
   constructor(
     network: Network,
@@ -223,7 +238,7 @@ export class ZLPDataAPI extends BaseDataAPI implements IZLPDataAPI {
         price,
         marketInfo.lpSupplyWithDecimals,
         Date.now() / 1000,
-        oiState && oiState.enabled ? oiState.model : undefined,
+        oiState && oiState.enabled ? oiState : undefined,
         pairedInfo.openingSize,
       )
       return fundingFeeDelta + deltaSize
@@ -382,6 +397,165 @@ export class ZLPDataAPI extends BaseDataAPI implements IZLPDataAPI {
     }
   }
 
+  public async calculateSwapFeeBreakdown(fromToken: string, toToken: string, fromAmount: number): Promise<ISwapFeeBreakdown> {
+    const timestamp = Date.now() / 1000
+
+    const fromDecimals = this.consts.coins[fromToken]?.decimals
+    const toDecimals = this.consts.coins[toToken]?.decimals
+    if (fromDecimals === undefined || toDecimals === undefined) {
+      throw new Error(`Unknown token decimals for swap: ${fromToken} -> ${toToken}`)
+    }
+
+    const fromFeed = await this.getOraclePrice(fromToken)
+    const toFeed = await this.getOraclePrice(toToken)
+    const fromPrice = fromFeed.getPriceUnchecked().getPriceAsNumberUnchecked()
+    const toPrice = toFeed.getPriceUnchecked().getPriceAsNumberUnchecked()
+
+    const swapValue = (fromAmount * fromPrice) / (10 ** fromDecimals)
+    const totalVaultsValue = await this.#getTotalVaultsValueUsd(timestamp)
+
+    const rebaseFeeInRate = await this.rebaseFeeRate(fromToken, true, fromAmount)
+    const rebaseFeeInValue = swapValue * rebaseFeeInRate
+
+    // Estimate out-amount by notional value (ignoring price impact / spread / fees).
+    const estimatedToAmount = toPrice !== 0
+      ? (swapValue * (10 ** toDecimals)) / toPrice
+      : 0
+    const rebaseFeeOutRate = await this.rebaseFeeRate(toToken, false, estimatedToAmount)
+    const rebaseFeeOutValue = swapValue * rebaseFeeOutRate
+
+    const swapImpactCfg = await this.#getSwapImpactConfig()
+    const swapImpactFeeValue = swapImpactCfg?.enabled
+      ? ZLPDataAPI.#computeSwapImpactFeeValue(swapValue, totalVaultsValue, swapImpactCfg.impactMultiplier, swapImpactCfg.maxImpactRate)
+      : 0
+
+    const emaCfg = await this.#getEmaVolatilityFeeConfig()
+    const emaVolatilityFeeValue = emaCfg?.enabled
+      ? ZLPDataAPI.#computeEmaVolatilityFeeValue(
+          swapValue,
+          ZLPDataAPI.#maxEmaDivergenceRate(fromFeed, toFeed),
+          emaCfg.multiplier,
+          emaCfg.maxFeeRate,
+        )
+      : 0
+
+    const totalFeeValue = rebaseFeeInValue + rebaseFeeOutValue + swapImpactFeeValue + emaVolatilityFeeValue
+    const totalFeeRate = swapValue !== 0 ? totalFeeValue / swapValue : 0
+
+    return {
+      swapValue,
+      totalVaultsValue,
+      rebaseFeeInRate,
+      rebaseFeeOutRate,
+      rebaseFeeInValue,
+      rebaseFeeOutValue,
+      swapImpactFeeValue,
+      emaVolatilityFeeValue,
+      totalFeeValue,
+      totalFeeRate,
+    }
+  }
+
+  async #getTotalVaultsValueUsd(timestamp: number): Promise<number> {
+    const vaultKeys = Object.keys(this.consts.zoCore.vaults)
+    const vaultValues = await Promise.all(vaultKeys.map(async (vault) => {
+      const vaultInfo = await this.getVaultInfo(vault)
+      const reservingFeeDelta = ZLPDataAPI.calculateVaultReservingFee(vaultInfo, vaultInfo.reservingFeeModel, timestamp)
+      const totalVaultAmount = reservingFeeDelta + vaultInfo.liquidity + vaultInfo.reservedAmount
+      const oraclePrice = (await this.getOraclePrice(vault)).getPriceUnchecked().getPriceAsNumberUnchecked()
+      const { decimals } = this.consts.coins[vault]
+      return totalVaultAmount * oraclePrice / (10 ** decimals)
+    }))
+    return vaultValues.reduce((acc, curr) => acc + curr, 0)
+  }
+
+  async #getSwapImpactConfig(): Promise<SwapImpactConfig | null> {
+    const raw = await this.#getMarketDynamicFieldObjectByKeySuffix(this.consts.zoCore.market, 'SwapImpactConfigKey')
+    if (!raw)
+      return null
+    return ZLPDataAPI.#parseSwapImpactConfig(raw)
+  }
+
+  async #getEmaVolatilityFeeConfig(): Promise<EmaVolatilityFeeConfig | null> {
+    const raw = await this.#getMarketDynamicFieldObjectByKeySuffix(this.consts.zoCore.market, 'EmaVolatilityFeeConfigKey')
+    if (!raw)
+      return null
+    return ZLPDataAPI.#parseEmaVolatilityFeeConfig(raw)
+  }
+
+  async #getMarketDynamicFieldObjectByKeySuffix(parentId: string, keyTypeSuffix: string): Promise<any | null> {
+    let cursor: string | null | undefined
+    let hasNextPage = true
+
+    while (hasNextPage) {
+      const page = await this.provider.getDynamicFields({ parentId, cursor })
+      for (const field of page.data) {
+        const type = (field.name as any)?.type
+        if (typeof type === 'string' && type.endsWith(`::${keyTypeSuffix}`)) {
+          return await this.provider.getDynamicFieldObject({
+            parentId,
+            name: field.name as any,
+          })
+        }
+      }
+      hasNextPage = page.hasNextPage
+      cursor = page.nextCursor
+    }
+    return null
+  }
+
+  static #parseSwapImpactConfig(raw: any): SwapImpactConfig {
+    const { fields } = raw.data.content
+    return {
+      id: fields.id.id,
+      enabled: fields.enabled,
+      impactMultiplier: parseValue(fields.impact_multiplier),
+      maxImpactRate: parseValue(fields.max_impact_rate),
+    }
+  }
+
+  static #parseEmaVolatilityFeeConfig(raw: any): EmaVolatilityFeeConfig {
+    const { fields } = raw.data.content
+    return {
+      id: fields.id.id,
+      enabled: fields.enabled,
+      multiplier: parseValue(fields.multiplier),
+      maxFeeRate: parseValue(fields.max_fee_rate),
+    }
+  }
+
+  static #computeSwapImpactFeeValue(swapValue: number, totalVaultsValue: number, impactMultiplier: number, maxImpactRate: number): number {
+    if (swapValue <= 0 || totalVaultsValue <= 0)
+      return 0
+    const utilization = swapValue / totalVaultsValue
+    const rawImpactRate = impactMultiplier * utilization
+    const impactRate = Math.min(rawImpactRate, maxImpactRate)
+    return swapValue * impactRate
+  }
+
+  static #computeEmaVolatilityFeeValue(swapValue: number, maxDiv: number, multiplier: number, maxFeeRate: number): number {
+    if (swapValue <= 0 || maxDiv <= 0)
+      return 0
+    const rawFeeRate = multiplier * maxDiv
+    const feeRate = Math.min(rawFeeRate, maxFeeRate)
+    return swapValue * feeRate
+  }
+
+  static #maxEmaDivergenceRate(sourceFeed: any, destFeed: any): number {
+    const sourceDiv = ZLPDataAPI.#emaDivergenceRate(sourceFeed)
+    const destDiv = ZLPDataAPI.#emaDivergenceRate(destFeed)
+    return Math.max(sourceDiv, destDiv)
+  }
+
+  static #emaDivergenceRate(priceFeed: any): number {
+    const price = priceFeed.getPriceUnchecked().getPriceAsNumberUnchecked()
+    const ema = priceFeed.getEmaPriceUnchecked().getPriceAsNumberUnchecked()
+    const denom = Math.abs(price)
+    if (denom === 0)
+      return 0
+    return Math.abs(price - ema) / denom
+  }
+
   public async getPositionCapInfoList(owner: string): Promise<IZLPPositionCapInfo[]> {
     const positionCapInfoList: IZLPPositionCapInfo[] = []
     let cursor: string | undefined | null
@@ -671,7 +845,7 @@ export class ZLPDataAPI extends BaseDataAPI implements IZLPDataAPI {
     const longSize = longSymbol.openingSize
     const shortSize = shortSymbol.openingSize
 
-    const deltaRate = ZLPDataAPI.calcOiFundingFeeRate(oiState.model, longSize, shortSize, elapsed)
+    const deltaRate = ZLPDataAPI.calcOiFundingFeeRate(oiState.model, longSize, shortSize, elapsed, oiState.maxOiLong, oiState.maxOiShort)
     return long ? deltaRate : -deltaRate
   }
 
@@ -758,13 +932,42 @@ export class ZLPDataAPI extends BaseDataAPI implements IZLPDataAPI {
     return pnlPerRate >= 0 ? -secondsRate : secondsRate
   }
 
-  private static calcOiFundingFeeRate(model: IZLPOiFundingModel, longSize: number, shortSize: number, elapsed: number): number {
-    const imbalance = Math.abs(longSize - shortSize)
+  /**
+   * OI funding rate matching Move compute_oi_funding_rate_capped.
+   * When both maxOiLong and maxOiShort are set and > 0, uses normalized skew (oi/cap);
+   * otherwise falls back to (long - short) / total.
+   */
+  private static calcOiFundingFeeRate(
+    model: IZLPOiFundingModel,
+    oiLong: number,
+    oiShort: number,
+    elapsed: number,
+    maxOiLong?: number,
+    maxOiShort?: number,
+  ): number {
+    let skew: number
+    if (maxOiLong && maxOiShort && maxOiLong > 0 && maxOiShort > 0) {
+      const normLong = Math.min(oiLong / maxOiLong, 1)
+      const normShort = Math.min(oiShort / maxOiShort, 1)
+      skew = normLong - normShort
+    }
+    else {
+      const total = oiLong + oiShort
+      if (total === 0)
+        return 0
+      skew = (oiLong - oiShort) / total
+    }
+
+    if (skew === 0)
+      return 0
 
-    // multiplier = 0.1%, exponent = 1
-    const dailyRate = Math.min(model.multiplier * (imbalance ** model.exponent) / (longSize + shortSize > 0 ? longSize + shortSize : 1), model.max)
-    const secondsRate = dailyRate * elapsed / SECONDS_PER_EIGHT_HOUR
-    return longSize >= shortSize ? secondsRate : -secondsRate
+    const skewIsPositive = skew > 0
+    const skewAbs = Math.abs(skew)
+    const exponentInt = Math.floor(model.exponent)
+    const skewPow = skewAbs ** exponentInt
+    const dailyRate = Math.min(model.multiplier * skewPow, model.max)
+    const secondsRate = (dailyRate * elapsed) / SECONDS_PER_EIGHT_HOUR
+    return skewIsPositive ? secondsRate : -secondsRate
   }
 
   private static calcAccFundingFeeRate(
@@ -773,17 +976,17 @@ export class ZLPDataAPI extends BaseDataAPI implements IZLPDataAPI {
     price: number,
     lpSupplyAmount: number,
     timestamp: number,
-    oiModel?: IZLPOiFundingModel,
+    oiState?: IZLPOiFundingState,
     pairedOpeningSize?: number,
   ): number {
     if (symbol.lastUpdate > 0) {
       const elapsed = timestamp - symbol.lastUpdate
       if (elapsed > 0) {
-        // Prefer OI-based delta when model and paired side are available
-        if (oiModel && typeof pairedOpeningSize === 'number') {
+        // Prefer OI-based delta when state and paired side are available
+        if (oiState?.enabled && oiState.model && typeof pairedOpeningSize === 'number') {
           const longSize = symbol.long ? symbol.openingSize : pairedOpeningSize
           const shortSize = symbol.long ? pairedOpeningSize : symbol.openingSize
-          const deltaRate = ZLPDataAPI.calcOiFundingFeeRate(oiModel, longSize, shortSize, elapsed)
+          const deltaRate = ZLPDataAPI.calcOiFundingFeeRate(oiState.model, longSize, shortSize, elapsed, oiState.maxOiLong, oiState.maxOiShort)
           const appliedRate = symbol.long ? deltaRate : -deltaRate
           return symbol.accFundingRate + appliedRate
         }
@@ -803,7 +1006,7 @@ export class ZLPDataAPI extends BaseDataAPI implements IZLPDataAPI {
     price: number,
     lpSupplyAmount: number,
     timestamp: number,
-    oiModel?: IZLPOiFundingModel,
+    oiState?: IZLPOiFundingState,
     pairedOpeningSize?: number,
   ): number {
     const accFundingRate = ZLPDataAPI.calcAccFundingFeeRate(
@@ -812,7 +1015,7 @@ export class ZLPDataAPI extends BaseDataAPI implements IZLPDataAPI {
       price,
       lpSupplyAmount,
       timestamp,
-      oiModel,
+      oiState,
       pairedOpeningSize,
     )
     return symbol.unrealisedFundingFeeValue + (accFundingRate - symbol.accFundingRate) * symbol.openingSize
@@ -1006,7 +1209,7 @@ export class ZLPDataAPI extends BaseDataAPI implements IZLPDataAPI {
     // OI context for funding: fetch state and paired side size when enabled
     const oiState = await this.getSymbolOiFundingState(positionInfo.indexToken)
     const pairedSymbol = await this.getSymbolInfo(positionInfo.indexToken, !positionInfo.long)
-    positionInfo.fundingFeeValue = ZLPDataAPI.calculatePositionFundingFee(positionInfo, await this.getSymbolInfo(positionInfo.indexToken, positionInfo.long), (await this.getSymbolInfo(positionInfo.indexToken, positionInfo.long)).fundingFeeModel, (await this.getOraclePrice(positionInfo.indexToken)).getPriceUnchecked().getPriceAsNumberUnchecked(), (await this.getMarketInfo()).lpSupplyWithDecimals, Date.now() / 1000, oiState && oiState.enabled ? oiState.model : undefined, pairedSymbol.openingSize)
+    positionInfo.fundingFeeValue = ZLPDataAPI.calculatePositionFundingFee(positionInfo, await this.getSymbolInfo(positionInfo.indexToken, positionInfo.long), (await this.getSymbolInfo(positionInfo.indexToken, positionInfo.long)).fundingFeeModel, (await this.getOraclePrice(positionInfo.indexToken)).getPriceUnchecked().getPriceAsNumberUnchecked(), (await this.getMarketInfo()).lpSupplyWithDecimals, Date.now() / 1000, oiState && oiState.enabled ? oiState : undefined, pairedSymbol.openingSize)
 
     return positionInfo
   }
@@ -1018,7 +1221,7 @@ export class ZLPDataAPI extends BaseDataAPI implements IZLPDataAPI {
     price: number,
     lpSupplyAmount: number,
     timestamp: number,
-    oiModel?: IZLPOiFundingModel,
+    oiState?: IZLPOiFundingState,
     pairedOpeningSize?: number,
   ): number {
     const accFundingRate = ZLPDataAPI.calcAccFundingFeeRate(
@@ -1027,7 +1230,7 @@ export class ZLPDataAPI extends BaseDataAPI implements IZLPDataAPI {
       price,
       lpSupplyAmount,
       timestamp,
-      oiModel,
+      oiState,
       pairedOpeningSize,
     )
     return position.fundingFeeValue + (accFundingRate - position.lastFundingRate) * position.positionSize
@@ -1100,6 +1303,8 @@ export class ZLPDataAPI extends BaseDataAPI implements IZLPDataAPI {
         exponent: parseValue(content.model.fields.exponent),
         max: parseValue(content.model.fields.max),
       },
+      maxOiLong: content.max_oi_long !== null && content.max_oi_long !== undefined ? parseValue(content.max_oi_long) : undefined,
+      maxOiShort: content.max_oi_short !== null && content.max_oi_short !== undefined ? parseValue(content.max_oi_short) : undefined,
     }
   }
 

package/src/interfaces/base.ts

@@ -18,6 +18,32 @@ export interface IBaseMarketValuationInfo {
   apr?: number
 }
 
+export interface ISwapFeeBreakdown {
+  /** Swap notional value (in USD terms using oracle prices) */
+  swapValue: number
+  /** Total value of all vaults (in USD terms using oracle prices) */
+  totalVaultsValue: number
+
+  /** Rebase fee rate applied to swap-in leg (source token) */
+  rebaseFeeInRate: number
+  /** Rebase fee rate applied to swap-out leg (dest token) */
+  rebaseFeeOutRate: number
+  /** Rebase fee value for swap-in leg (USD value) */
+  rebaseFeeInValue: number
+  /** Rebase fee value for swap-out leg (USD value) */
+  rebaseFeeOutValue: number
+
+  /** Swap impact fee value (USD value) */
+  swapImpactFeeValue: number
+  /** EMA volatility fee value (USD value) */
+  emaVolatilityFeeValue: number
+
+  /** Sum of all fee components (USD value) */
+  totalFeeValue: number
+  /** totalFeeValue / swapValue (0 when swapValue is 0) */
+  totalFeeRate: number
+}
+
 export interface IBaseMarketInfo {
   lpSupply: string
   positionId: string

package/src/interfaces/slp.ts

@@ -25,6 +25,7 @@ import type {
   IBaseStakePool,
   IBaseSymbolInfo,
   IBaseVaultInfo,
+  ISwapFeeBreakdown,
 } from './base'
 
 // SLP-specific interfaces
@@ -102,6 +103,10 @@ export interface ISLPOiFundingState {
   enabled: boolean
   last_update: number
   model: ISLPOiFundingModel
+  /** OI cap for long side (optional; when set with maxOiShort, uses capped skew formula) */
+  maxOiLong?: number
+  /** OI cap for short side (optional; when set with maxOiLong, uses capped skew formula) */
+  maxOiShort?: number
 }
 
 /**
@@ -211,6 +216,7 @@ export interface ISLPDataAPI extends IBaseDataAPI {
   getCumulativeApr: () => Promise<number>
   getSymbolConfig: (indexToken: string, long: boolean) => Promise<ISLPSymbolConfig | null>
   getPriceImpactConfig: (indexToken: string) => Promise<ISLPPriceImpactConfig | null>
+  calculateSwapFeeBreakdown: (fromToken: string, toToken: string, fromAmount: number) => Promise<ISwapFeeBreakdown>
 }
 
 // SLP-specific API interface
@@ -268,4 +274,17 @@ export interface ISLPAPI extends IBaseAPI {
     pool: string,
     tx: Transaction,
   ) => TransactionObjectArgument[]
+
+  /**
+   * Swaps tokens and returns the output coin to the user (PTB).
+   * Same as swap() but returns the output coin for use in composed transactions.
+   */
+  swapV2Ptb: (
+    fromToken: string,
+    toToken: string,
+    fromAmount: bigint,
+    fromCoinObjects: string[],
+    minAmountOut?: number,
+    tx?: Transaction,
+  ) => Promise<TransactionObjectArgument>
 }

package/src/interfaces/usdz.ts

@@ -23,6 +23,7 @@ import type {
   IBaseStakePool,
   IBaseSymbolInfo,
   IBaseVaultInfo,
+  ISwapFeeBreakdown,
 } from './base'
 
 // USDZ-specific interfaces
@@ -103,6 +104,10 @@ export interface IUSDZOiFundingState {
   enabled: boolean
   last_update: number
   model: IUSDZOiFundingModel
+  /** OI cap for long side (optional; when set with maxOiShort, uses capped skew formula) */
+  maxOiLong?: number
+  /** OI cap for short side (optional; when set with maxOiLong, uses capped skew formula) */
+  maxOiShort?: number
 }
 
 /**
@@ -133,6 +138,7 @@ export interface IUSDZPriceImpactConfig {
 export interface IUSDZDataAPI extends IBaseDataAPI {
   getSymbolConfig: (indexToken: string, long: boolean) => Promise<IUSDZSymbolConfig | null>
   getPriceImpactConfig: (indexToken: string) => Promise<IUSDZPriceImpactConfig | null>
+  calculateSwapFeeBreakdown: (fromToken: string, toToken: string, fromAmount: number) => Promise<ISwapFeeBreakdown>
 }
 
 // USDZ-specific API interface
@@ -181,4 +187,17 @@ export interface IUSDZAPI extends IBaseAPI {
     pool: string,
     tx: Transaction,
   ) => TransactionObjectArgument[]
+
+  /**
+   * Swaps tokens and returns the output coin to the user (PTB).
+   * Same as swap() but returns the output coin for use in composed transactions.
+   */
+  swapV2Ptb: (
+    fromToken: string,
+    toToken: string,
+    fromAmount: bigint,
+    fromCoinObjects: string[],
+    minAmountOut?: number,
+    tx?: Transaction,
+  ) => Promise<TransactionObjectArgument>
 }

package/src/interfaces/zlp.ts

@@ -23,6 +23,7 @@ import type {
   IBaseStakePool,
   IBaseSymbolInfo,
   IBaseVaultInfo,
+  ISwapFeeBreakdown,
 } from './base'
 
 // ZLP-specific interfaces
@@ -103,6 +104,10 @@ export interface IZLPOiFundingState {
   enabled: boolean
   last_update: number
   model: IZLPOiFundingModel
+  /** OI cap for long side (optional; when set with maxOiShort, uses capped skew formula) */
+  maxOiLong?: number
+  /** OI cap for short side (optional; when set with maxOiLong, uses capped skew formula) */
+  maxOiShort?: number
 }
 
 /**
@@ -133,6 +138,7 @@ export interface IZLPPriceImpactConfig {
 export interface IZLPDataAPI extends IBaseDataAPI {
   getSymbolConfig: (indexToken: string, long: boolean) => Promise<IZLPSymbolConfig | null>
   getPriceImpactConfig: (indexToken: string) => Promise<IZLPPriceImpactConfig | null>
+  calculateSwapFeeBreakdown: (fromToken: string, toToken: string, fromAmount: number) => Promise<ISwapFeeBreakdown>
 }
 
 // ZLP-specific API interface
@@ -244,4 +250,17 @@ export interface IZLPAPI extends IBaseAPI {
     pool: string,
     tx: Transaction,
   ) => TransactionObjectArgument[]
+
+  /**
+   * Swaps tokens and returns the output coin to the user (PTB).
+   * Same as swap() but returns the output coin for use in composed transactions.
+   */
+  swapV2Ptb: (
+    fromToken: string,
+    toToken: string,
+    fromAmount: bigint,
+    fromCoinObjects: string[],
+    minAmountOut?: number,
+    tx?: Transaction,
+  ) => Promise<TransactionObjectArgument>
 }