@exponent-labs/market-three-math 0.1.8

package/src/swapLegacy.ts

@@ -0,0 +1,272 @@
+/**
+ * CLMM Swap simulation
+ * Ported from exponent_clmm/src/state/market_three/helpers/swap.rs
+ */
+import { MarketThreeState, SwapArgs, SwapDirection, SwapOutcome } from "./types"
+import {
+  EffSnap,
+  bigIntMax,
+  bigIntMin,
+  calculateFeeRate,
+  findTickByKey,
+  getFeeFromAmount,
+  getImpliedRate,
+  getPredecessorTickKey,
+  getSuccessorTickKey,
+  normalizedTimeRemaining,
+} from "./utils"
+
+const BASE_POINTS = 10000
+
+/**
+ * Simulate a swap on the CLMM market
+ * This is a pure function that does not mutate the market state
+ * Returns the swap outcome including amounts and final state
+ */
+export function simulateSwap(marketState: MarketThreeState, args: SwapArgs): SwapOutcome {
+  const { financials, configurationOptions, ticks } = marketState
+  const secondsRemaining = Math.max(0, Number(financials.expirationTs) - Date.now() / 1000)
+
+  // Create effective price snapshot
+  const snapshot = new EffSnap(normalizedTimeRemaining(secondsRemaining), args.syExchangeRate)
+
+  // Current state
+  let currentPriceSpot: number = ticks.currentSpotPrice
+  let currentLeftBoundaryIndex: number = ticks.currentTick
+
+  // Use currentPrefixSum if available, otherwise fall back to calculating it
+  let activeLiquidityU64: bigint = ticks.currentPrefixSum ?? 0n
+  let activeLiquidityF64: number = Number(activeLiquidityU64)
+
+  // Fees
+  const lpFeeRate = calculateFeeRate(configurationOptions.lnFeeRateRoot, secondsRemaining)
+  const protocolFeeBps: number = configurationOptions.treasuryFeeBps
+
+  // Check price limits
+  if (args.priceSpotLimit !== undefined) {
+    if (args.direction === SwapDirection.PtToSy) {
+      if (args.priceSpotLimit < currentPriceSpot) {
+        throw new Error("Price limit violated: limit must be >= current price for PtToSy")
+      }
+    } else {
+      if (args.priceSpotLimit > currentPriceSpot) {
+        throw new Error("Price limit violated: limit must be <= current price for SyToPt")
+      }
+    }
+  }
+
+  // Accumulators
+  let amountOutNet: number = 0
+  let feeLpOut: number = 0
+  let feeProtocolOut: number = 0
+  let amountInLeft: number = args.amountIn
+
+  // Main loop across contiguous intervals
+  let iterations: number = 0
+  const maxIterations: number = 1000
+
+  while (amountInLeft > 0 && iterations < maxIterations) {
+    iterations++
+
+    // Get right boundary of current interval
+    const rightBoundaryIndexOpt = getSuccessorTickKey(ticks, currentLeftBoundaryIndex)
+
+    if (rightBoundaryIndexOpt === null) {
+      if (args.direction === SwapDirection.SyToPt) {
+        // Cross to create a new interval
+        const predecessor = getPredecessorTickKey(ticks, currentLeftBoundaryIndex)
+        if (predecessor === null) break
+
+        // When crossing downward (SyToPt), update state
+        currentPriceSpot = getImpliedRate(currentLeftBoundaryIndex) // Boundary we're crossing
+        currentLeftBoundaryIndex = predecessor // New left boundary
+
+        // Update active liquidity by subtracting liquidity_net at boundary
+        const boundaryTick = findTickByKey(ticks, predecessor)
+        if (boundaryTick) {
+          activeLiquidityU64 = bigIntMax(0n, activeLiquidityU64 - boundaryTick.tick.liquidityNet)
+          activeLiquidityF64 = Number(activeLiquidityU64)
+        }
+        continue
+      } else {
+        // No more liquidity available
+        break
+      }
+    }
+
+    const rightBoundaryIndex = rightBoundaryIndexOpt
+
+    // Get anchor prices for interval boundaries
+    const anchorULeft: number = getImpliedRate(currentLeftBoundaryIndex)
+    const anchorURight: number = getImpliedRate(rightBoundaryIndex)
+
+    // Effective price at current spot
+    const cEffOld: number = snapshot.getEffectivePrice(currentPriceSpot)
+
+    // Get principal ledgers for the interval
+    const currentTickData = findTickByKey(ticks, currentLeftBoundaryIndex)
+    const principalPt: bigint = currentTickData?.tick.principalPt ?? 0n
+    const principalSy: bigint = currentTickData?.tick.principalSy ?? 0n
+
+    const eps: number = configurationOptions.epsilonClamp
+
+    // Calculate kappa (scaling factor based on available principal)
+    // Y_max = (L/τ) * (C(u_old) - C(u_right))
+    const cEffAtBoundary: number = snapshot.getEffectivePrice(anchorURight)
+    const yMaxToBoundaryF: number = (Number(activeLiquidityF64) / snapshot.timeFactor) * (cEffOld - cEffAtBoundary)
+    const kappaSy: number = yMaxToBoundaryF > 0 ? Number(principalSy) / Number(yMaxToBoundaryF) : 0
+
+    const duToLeft: number = currentPriceSpot - anchorULeft
+    const ptMaxToLeftF: number = Number(activeLiquidityF64) * duToLeft
+    const kappaPt: number = ptMaxToLeftF > 0 ? Number(principalPt) / ptMaxToLeftF : 0
+
+    const kappa: number = Math.min(kappaPt, kappaSy, 1.0)
+    const lTradeF64: number = Number(activeLiquidityF64) * kappa
+
+    if (args.direction === SwapDirection.PtToSy) {
+      // PT -> SY swap (buying SY with PT)
+      const duByInput = lTradeF64 > 0 ? amountInLeft / lTradeF64 : 0
+      const duToBoundary = anchorURight - currentPriceSpot
+      const duActual = Math.min(duByInput, duToBoundary)
+
+      if (duToBoundary <= eps) {
+        // Cross boundary
+        const boundaryTick = findTickByKey(ticks, rightBoundaryIndex)
+        if (boundaryTick) {
+          activeLiquidityU64 += boundaryTick.tick.liquidityNet
+          activeLiquidityF64 = Number(activeLiquidityU64)
+        }
+        currentLeftBoundaryIndex = rightBoundaryIndex
+        currentPriceSpot = anchorURight
+        continue
+      }
+
+      // Token flows for this segment
+      const ptInSegment: number = Math.floor(lTradeF64 * duActual)
+      const anchorUNew: number = currentPriceSpot + duActual
+      const cEffNew: number = snapshot.getEffectivePrice(anchorUNew)
+      const syOutGross: number = Math.floor((lTradeF64 / snapshot.timeFactor) * (cEffOld - cEffNew))
+      const syOutGrossClamped: number = Math.min(syOutGross, Number(principalSy))
+
+      if (syOutGrossClamped > 0) {
+        const totalFeeOut: number = getFeeFromAmount(syOutGrossClamped, lpFeeRate)
+        const protocolFeeOut: number = Math.floor((totalFeeOut * protocolFeeBps) / BASE_POINTS)
+        const lpFeeOut: number = totalFeeOut - protocolFeeOut
+        const syOutNet: number = syOutGrossClamped - totalFeeOut
+
+        amountOutNet += syOutNet
+        feeLpOut += lpFeeOut
+        feeProtocolOut += protocolFeeOut
+      }
+
+      amountInLeft -= ptInSegment
+      currentPriceSpot = anchorUNew
+    } else {
+      // SY -> PT swap (buying PT with SY)
+      const cEffLeft: number = snapshot.getEffectivePrice(anchorULeft)
+      const deltaCByInput: number = lTradeF64 > 0 ? (snapshot.timeFactor / lTradeF64) * amountInLeft : 0
+      const deltaCToLeftBoundary: number = Math.max(0, cEffLeft - cEffOld)
+      const deltaCActual: number = Math.min(deltaCByInput, deltaCToLeftBoundary)
+
+      if (deltaCToLeftBoundary <= eps) {
+        // Cross boundary to the left
+        const predecessor = getPredecessorTickKey(ticks, currentLeftBoundaryIndex)
+        if (predecessor === null) break
+
+        // Update active liquidity
+        const boundaryTick = findTickByKey(ticks, currentLeftBoundaryIndex)
+        if (boundaryTick) {
+          activeLiquidityU64 = bigIntMax(0n, activeLiquidityU64 - boundaryTick.tick.liquidityNet)
+          activeLiquidityF64 = Number(activeLiquidityU64)
+        }
+
+        currentPriceSpot = getImpliedRate(currentLeftBoundaryIndex)
+        currentLeftBoundaryIndex = predecessor
+        continue
+      }
+
+      // New effective price and spot price after consuming ΔC
+      const cEffNew: number = cEffOld + deltaCActual
+      const spotPriceNew: number = snapshot.spotPriceFromEffectivePrice(cEffNew)
+
+      // Token flows
+      const syInSegmentF: number = (lTradeF64 / snapshot.timeFactor) * (cEffNew - cEffOld)
+      const duAbs: number = currentPriceSpot - spotPriceNew
+      const ptOutGrossF: number = lTradeF64 * duAbs
+
+      // Clamp gross PT by available principal
+      const ptOutGrossU64: bigint = bigIntMin(BigInt(Math.floor(ptOutGrossF)), principalPt)
+      const syInSegmentU64: bigint = BigInt(Math.floor(syInSegmentF))
+
+      if (ptOutGrossU64 === 0n) {
+        // Nothing to pay out; try to cross
+        const predecessor = getPredecessorTickKey(ticks, currentLeftBoundaryIndex)
+        if (predecessor === null) break
+
+        // Update active liquidity
+        const boundaryTick = findTickByKey(ticks, currentLeftBoundaryIndex)
+        if (boundaryTick) {
+          activeLiquidityU64 = bigIntMax(0n, activeLiquidityU64 - boundaryTick.tick.liquidityNet)
+          activeLiquidityF64 = Number(activeLiquidityU64)
+        }
+
+        currentPriceSpot = getImpliedRate(currentLeftBoundaryIndex)
+        currentLeftBoundaryIndex = predecessor
+        continue
+      }
+
+      // Fees in token_out (PT)
+      const totalFeeOut = getFeeFromAmount(Number(ptOutGrossU64), lpFeeRate)
+      const protocolFeeOut = Math.floor((totalFeeOut * protocolFeeBps) / BASE_POINTS)
+      const lpFeeOut = totalFeeOut - protocolFeeOut
+      const ptOutNet = Number(ptOutGrossU64) - totalFeeOut
+
+      // Accumulate to user
+      amountOutNet += ptOutNet
+      feeLpOut += lpFeeOut
+      feeProtocolOut += protocolFeeOut
+
+      // Consume input and advance state
+      amountInLeft -= Number(syInSegmentU64)
+      currentPriceSpot = spotPriceNew
+
+      // If we hit boundary, cross
+      if (Math.abs(currentPriceSpot - anchorULeft) <= eps && amountInLeft > 0) {
+        const predecessor = getPredecessorTickKey(ticks, currentLeftBoundaryIndex)
+        if (predecessor === null) break
+
+        // Update active liquidity
+        const boundaryTick = findTickByKey(ticks, currentLeftBoundaryIndex)
+        if (boundaryTick) {
+          activeLiquidityU64 = bigIntMax(0n, activeLiquidityU64 - boundaryTick.tick.liquidityNet)
+          activeLiquidityF64 = Number(activeLiquidityU64)
+        }
+
+        currentPriceSpot = getImpliedRate(currentLeftBoundaryIndex)
+        currentLeftBoundaryIndex = predecessor
+      }
+    }
+  }
+
+  return {
+    amountInConsumed: args.amountIn - amountInLeft,
+    amountOut: amountOutNet,
+    lpFeeChargedOutToken: feeLpOut,
+    protocolFeeChargedOutToken: feeProtocolOut,
+    finalSpotPrice: currentPriceSpot,
+    finalTickIndex: currentLeftBoundaryIndex,
+  }
+}
+
+/**
+ * Calculate the expected output for a given input amount
+ * This is a convenience wrapper around simulateSwap
+ */
+export function getSwapQuote(marketState: MarketThreeState, amountIn: number, direction: SwapDirection): SwapOutcome {
+  return simulateSwap(marketState, {
+    direction,
+    amountIn,
+    syExchangeRate: marketState.currentSyExchangeRate,
+    isCurrentFlashSwap: false,
+  })
+}

package/src/types.ts

@@ -0,0 +1,80 @@
+import { MarketConfigurationOptions, MarketThreeFinancials, Ticks } from "@exponent-labs/exponent-fetcher"
+
+export enum SwapDirection {
+  PtToSy = "PtToSy",
+  SyToPt = "SyToPt",
+}
+
+export interface MarketThreeState {
+  /** Market financials */
+  financials: MarketThreeFinancials
+  /** Configuration options */
+  configurationOptions: MarketConfigurationOptions
+  /** Ticks data */
+  ticks: Ticks
+  /** Current SY exchange rate */
+  currentSyExchangeRate: number
+}
+
+export interface SwapArgs {
+  /** Direction of the swap */
+  direction: SwapDirection
+  /** Exact amount in */
+  amountIn: number
+  /** Optional spot price limit (anti-sandwich) */
+  priceSpotLimit?: number
+  /** SY exchange rate */
+  syExchangeRate: number
+  /** Is this a flash swap? */
+  isCurrentFlashSwap: boolean
+}
+
+export interface SwapOutcome {
+  /** Amount of input consumed */
+  amountInConsumed: number
+  /** Amount out (after fees) */
+  amountOut: number
+  /** LP fee charged in out token */
+  lpFeeChargedOutToken: number
+  /** Protocol fee charged in out token */
+  protocolFeeChargedOutToken: number
+  /** Final spot price after swap */
+  finalSpotPrice: number
+  /** Final tick index after swap */
+  finalTickIndex: number
+}
+
+export interface AddLiquidityArgs {
+  /** Lower tick key (ln implied rate in bps) */
+  lowerTick: number
+  /** Upper tick key (ln implied rate in bps) */
+  upperTick: number
+  /** Maximum SY to spend */
+  maxSy: number
+  /** Maximum PT to spend */
+  maxPt: number
+  /** SY exchange rate */
+  syExchangeRate: number
+}
+
+export interface AddLiquidityOutcome {
+  /** Liquidity added */
+  deltaL: number
+  /** SY spent */
+  sySpent: number
+  /** PT spent */
+  ptSpent: number
+}
+
+export interface LiquidityNeeds {
+  /** Target liquidity to add */
+  liquidityTarget: number
+  /** SY needed */
+  syNeeded: number
+  /** PT needed */
+  ptNeeded: number
+  /** Price split point for the need calculation */
+  priceSplitForNeed: number
+  /** Tick index of the split point */
+  priceSplitTickIdx: number
+}

package/src/utils.ts

@@ -0,0 +1,235 @@
+/**
+ * Utility functions for CLMM calculations
+ * Ported from exponent_clmm/src/utils/math.rs
+ */
+import { Tick, Ticks } from "@exponent-labs/exponent-fetcher"
+
+const SECONDS_PER_YEAR = 365 * 24 * 60 * 60
+// const BASE_POINTS = 10000
+
+/**
+ * Effective price snapshot
+ * This captures the time factor and SY exchange rate at a given moment
+ * Matches the Rust implementation from exponent_clmm/src/state/market_three/helpers/add_liquidity.rs
+ */
+export class EffSnap {
+  /** Time factor (tau = normalized time remaining) */
+  timeFactor: number
+  /** SY exchange rate (r) */
+  syExchangeRate: number
+
+  constructor(timeFactor: number, syExchangeRate: number) {
+    this.timeFactor = timeFactor
+    this.syExchangeRate = syExchangeRate
+  }
+
+  /**
+   * Calculate effective price from spot price
+   * Rust formula: C(u) = u^(-(τ-1)) / (r * (τ - 1))
+   * where τ = time_factor, u = spot_price (ln implied rate), r = sy_exchange_rate
+   */
+  getEffectivePrice(u: number): number {
+    if (this.timeFactor === 1.0) {
+      throw new Error("time_factor cannot be 1.0")
+    }
+    return Math.pow(u, -this.timeFactor + 1.0) / (this.syExchangeRate * (this.timeFactor - 1.0))
+  }
+
+  /**
+   * Convert effective price back to spot price
+   * Rust formula: u = (r * C * (τ - 1))^(1/(1-τ))
+   * In Rust: spot_price_from_effective_price
+   */
+  spotPriceFromEffectivePrice(cEff: number): number {
+    const base = this.syExchangeRate * cEff * (this.timeFactor - 1.0)
+    return Math.pow(base, 1.0 / (1.0 - this.timeFactor))
+  }
+
+  /**
+   * Legacy alias for backwards compatibility
+   */
+  impliedRateFromEffectivePrice(cEff: number): number {
+    return this.spotPriceFromEffectivePrice(cEff)
+  }
+
+  /**
+   * Calculate delta SY from change in effective price
+   * Rust formula: ΔSY = L * (C_old - C_new)
+   * Note: No division by time_factor in the Rust implementation
+   */
+  deltaEffPriceToSy(liquidity: number, oldEffPrice: number, newEffPrice: number): number {
+    return liquidity * (oldEffPrice - newEffPrice)
+  }
+}
+
+/**
+ * Calculate normalized time remaining
+ * Returns seconds_remaining / SECONDS_PER_YEAR
+ */
+export function normalizedTimeRemaining(secondsRemaining: number): number {
+  return secondsRemaining / SECONDS_PER_YEAR
+}
+
+/**
+ * Calculate current fee rate from fee rate root and time remaining
+ * fee_rate = e^(ln_fee_rate_root * time_factor)
+ */
+export function calculateFeeRate(lnFeeRateRoot: number, secondsRemaining: number): number {
+  const timeFactor = normalizedTimeRemaining(secondsRemaining)
+  return Math.exp(lnFeeRateRoot * timeFactor)
+}
+
+/**
+ * Calculate fee from amount
+ * Returns the fee to charge given an amount and fee rate
+ * fee = amount * (fee_rate - 1.0)
+ */
+export function getFeeFromAmount(amount: number, feeRate: number): number {
+  return Math.ceil(amount * (feeRate - 1.0))
+}
+
+/**
+ * Find the active liquidity at a given tick index
+ * This is computed by summing liquidity_net up to the current tick
+ */
+export function getActiveLiquidity(ticks: Ticks, tickIndex: number): bigint {
+  let activeLiquidity = 0n
+
+  // Sum all liquidity_net from ticks up to and including tickIndex
+
+  for (const tick of ticks.ticksTree) {
+    if (tick.apyBasePoints <= tickIndex) {
+      activeLiquidity += tick.liquidityNet
+    }
+  }
+
+  return activeLiquidity
+}
+
+/**
+ * Find the successor tick (next tick to the right)
+ * In Rust: ticks.successor_idx(current_left_boundary_index)
+ * @param ticks - The ticks data structure
+ * @param currentTickKey - The current tick key (apyBasePoints)
+ * @returns The next tick key (apyBasePoints) or null if none exists
+ */
+export function getSuccessorTickKey(ticks: Ticks, currentTickKey: number): number | null {
+  let minKey: number | null = null
+
+  for (const tick of ticks.ticksTree) {
+    if (tick.apyBasePoints > currentTickKey) {
+      if (minKey === null || tick.apyBasePoints < minKey) {
+        minKey = tick.apyBasePoints
+      }
+    }
+  }
+
+  return minKey
+}
+
+/**
+ * Find the successor tick by index in the tick tree
+ * This is almost equivalent to the Rust successor_idx method
+ */
+export function getSuccessorTickByIdx(ticks: Ticks, tickIdx: number): number | null {
+  //TODO Refactor to make it more CPU efficient
+  const tick = ticks.ticksTree.at(tickIdx - 1) ?? null
+
+  if (!tick) return null
+
+  // Find ticks with apyBasePoints greater than tickIdx
+  const successorTicks = ticks.ticksTree
+    .filter((t) => t.apyBasePoints > tick.apyBasePoints)
+    .sort((a, b) => a.apyBasePoints - b.apyBasePoints)
+
+  const successorTick = successorTicks.at(0) ?? null
+
+  return !!successorTick ? ticks.ticksTree.indexOf(successorTick) + 1 : null
+}
+
+/**
+ * Find the predecessor tick (next tick to the left)
+ * In Rust: ticks.predecessor_idx(current_left_boundary_index)
+ * @param ticks - The ticks data structure
+ * @param currentTickKey - The current tick key (apyBasePoints)
+ * @returns The previous tick key (apyBasePoints) or null if none exists
+ */
+export function getPredecessorTickKey(ticks: Ticks, currentTickKey: number): number | null {
+  let maxKey: number | null = null
+
+  for (const tick of ticks.ticksTree) {
+    if (tick.apyBasePoints < currentTickKey) {
+      if (maxKey === null || tick.apyBasePoints > maxKey) {
+        maxKey = tick.apyBasePoints
+      }
+    }
+  }
+
+  return maxKey
+}
+
+/**
+ * Get the spot price (implied rate) for a tick key
+ * Tick key represents APY in parts per million (1e6)
+ * spot_price = 1 + tick_key / 1e6
+ *
+ * This is equivalent to the Rust code:
+ * let spot_price = (1.0 + (key as f64) / TICK_KEY_BASE_POINTS);
+ * But Rust stores it pre-computed, we compute it here
+ */
+export function getImpliedRate(tickKey: number): number {
+  const TICK_KEY_BASE_POINTS = 1_000_000
+  return 1.0 + tickKey / TICK_KEY_BASE_POINTS
+}
+
+/**
+ * Find a tick by its key
+ */
+export function findTickByKey(ticks: Ticks, tickKey: number): { tick: Tick; index: number } | null {
+  const index = ticks.ticksTree.findIndex((t) => t.apyBasePoints === tickKey)
+  if (index === -1) return null
+  return { tick: ticks.ticksTree[index - 1], index }
+}
+
+/**
+ * Find a tick by its index
+ */
+export function findTickByIndex(ticks: Ticks, index: number): Tick {
+  return ticks.ticksTree.at(index - 1) ?? null
+}
+
+/**
+ * Convert APY percentage to basis points
+ */
+export function convertApyToApyBp(apyPercent: number): number {
+  return Math.round(apyPercent * 100)
+}
+
+/**
+ * Convert basis points to APY percentage
+ */
+export function convertApyBpToApy(apyBp: number): number {
+  return apyBp / 100
+}
+
+export function bigIntMax(...args: bigint[]): bigint {
+  return args.reduce((m, e) => (e > m ? e : m))
+}
+
+export function bigIntMin(...args: bigint[]): bigint {
+  return args.reduce((m, e) => (e < m ? e : m))
+}
+
+/**
+ * Calculate PT price in asset from current spot price and expiration timestamp
+ * @param currentSpotPrice - Current spot price in format of 1 + percentage / 100
+ * @param expirationTs - Expiration timestamp in seconds
+ * @returns PT price in asset
+ */
+export function calcPtPriceInAsset(currentSpotPrice: number, expirationTs: number) {
+  const impliedApy = currentSpotPrice - 1
+  const secondsRemaining = Math.max(0, expirationTs)
+  const SECONDS_PER_YEAR = 365 * 86400
+  const ptPriceInAsset = Math.exp(Math.log(1 + impliedApy) * (-secondsRemaining / SECONDS_PER_YEAR))
+  return ptPriceInAsset
+}