@exponent-labs/market-three-math 0.1.8

package/src/addLiquidity.ts

@@ -0,0 +1,384 @@
+/**
+ * CLMM Add Liquidity simulation
+ * Ported from exponent_clmm/src/state/market_three/helpers/add_liquidity.rs
+ */
+import { AddLiquidityArgs, AddLiquidityOutcome, LiquidityNeeds, MarketThreeState } from "./types"
+import { EffSnap, normalizedTimeRemaining } from "./utils"
+
+const TICK_KEY_BASE_POINTS = 1_000_000
+
+/**
+ * Compute liquidity target and token needs based on position range and budgets
+ * Ported from compute_liquidity_target_and_token_needs in math.rs
+ */
+export function computeLiquidityTargetAndTokenNeeds(
+  snap: EffSnap,
+  spotPriceCurrent: number,
+  priceEffLower: number,
+  priceEffUpper: number,
+  lowerPrice: number,
+  upperPrice: number,
+  lowerTickIdx: number,
+  upperTickIdx: number,
+  currentIndex: number,
+  maxSy: number,
+  maxPt: number,
+  epsilonClamp: number,
+): LiquidityNeeds {
+  // Decide region and compute target ΔL and token needs
+  // IMPORTANT: Price below range = SY only; Price above range = PT only
+
+  if (spotPriceCurrent <= lowerPrice) {
+    // Below range: SY only (NOT PT!)
+    const deltaCTotal = Math.max(priceEffLower - priceEffUpper, epsilonClamp)
+    const liquidityFromSy = maxSy / deltaCTotal
+    const liquidityTarget = liquidityFromSy
+    const syNeed = liquidityTarget * (priceEffLower - priceEffUpper)
+
+    return {
+      liquidityTarget: Math.floor(liquidityTarget),
+      syNeeded: Math.floor(syNeed),
+      ptNeeded: 0,
+      priceSplitForNeed: lowerPrice,
+      priceSplitTickIdx: lowerTickIdx,
+    }
+  } else if (spotPriceCurrent >= upperPrice) {
+    // Above range: PT only (NOT SY!)
+    const duTotal = Math.max(upperPrice - lowerPrice, epsilonClamp)
+    const liquidityFromPt = maxPt / duTotal
+    const liquidityTarget = liquidityFromPt
+    const ptNeed = liquidityTarget * duTotal
+
+    return {
+      liquidityTarget: Math.floor(liquidityTarget),
+      syNeeded: 0,
+      ptNeeded: Math.floor(ptNeed),
+      priceSplitForNeed: upperPrice,
+      priceSplitTickIdx: upperTickIdx,
+    }
+  } else {
+    // Inside range: both sides
+    const duLeft = Math.max(spotPriceCurrent - lowerPrice, epsilonClamp)
+    const liquidityFromPt = maxPt / duLeft
+
+    const priceEffCurrent = snap.getEffectivePrice(spotPriceCurrent)
+    const deltaCRight = Math.max(priceEffCurrent - priceEffUpper, epsilonClamp)
+    const liquidityFromSy = maxSy / deltaCRight
+
+    const liquidityTarget = Math.min(liquidityFromPt, liquidityFromSy)
+    const ptNeed = liquidityTarget * duLeft
+    const syNeed = liquidityTarget * deltaCRight
+
+    return {
+      liquidityTarget: Math.floor(liquidityTarget),
+      syNeeded: Math.floor(syNeed),
+      ptNeeded: Math.floor(ptNeed),
+      priceSplitForNeed: spotPriceCurrent,
+      priceSplitTickIdx: currentIndex,
+    }
+  }
+}
+
+/**
+ * Simulate adding liquidity to the CLMM market
+ * This is a pure function that does not mutate the market state
+ */
+export function simulateAddLiquidity(marketState: MarketThreeState, args: AddLiquidityArgs): AddLiquidityOutcome {
+  const { financials, configurationOptions, ticks } = marketState
+  const secondsRemaining = Math.max(0, Number(financials.expirationTs) - Date.now() / 1000)
+
+  // Create effective price snapshot
+  const snap = new EffSnap(normalizedTimeRemaining(secondsRemaining), args.syExchangeRate)
+
+  // Current spot price
+  const currentSpot = ticks.currentSpotPrice
+
+  // Resolve tick prices - convert tick keys (parts per million) to spot prices
+  const lowerPrice = 1 + args.lowerTick / TICK_KEY_BASE_POINTS
+  const upperPrice = 1 + args.upperTick / TICK_KEY_BASE_POINTS
+
+  // Precompute effective prices
+  const priceEffLower = snap.getEffectivePrice(lowerPrice)
+  const priceEffUpper = snap.getEffectivePrice(upperPrice)
+
+  // Calculate liquidity needs
+  const liquidityNeeds = computeLiquidityTargetAndTokenNeeds(
+    snap,
+    currentSpot,
+    priceEffLower,
+    priceEffUpper,
+    lowerPrice,
+    upperPrice,
+    args.lowerTick,
+    args.upperTick,
+    ticks.currentTick,
+    args.maxSy,
+    args.maxPt,
+    configurationOptions.epsilonClamp,
+  )
+
+  // Enforce budgets
+  const sySpent = liquidityNeeds.syNeeded
+  const ptSpent = liquidityNeeds.ptNeeded
+
+  if (sySpent > args.maxSy) {
+    throw new Error(`Insufficient SY budget: need ${sySpent}, have ${args.maxSy}`)
+  }
+  if (ptSpent > args.maxPt) {
+    throw new Error(`Insufficient PT budget: need ${ptSpent}, have ${args.maxPt}`)
+  }
+
+  return {
+    deltaL: liquidityNeeds.liquidityTarget,
+    sySpent,
+    ptSpent,
+  }
+}
+
+/**
+ * Calculate the LP tokens that will be received for a given deposit
+ * This is useful for UI display and slippage calculations
+ */
+export function calculateLpOut(liquidityAdded: number, totalLiquidityBefore: number): number {
+  if (totalLiquidityBefore === 0) {
+    // First deposit
+    return liquidityAdded
+  }
+
+  // LP tokens are proportional to liquidity added
+  return liquidityAdded
+}
+
+/**
+ * Estimate the balanced amounts of PT and SY needed for a liquidity deposit
+ * Given a target liquidity amount, calculate how much PT and SY are needed
+ */
+export function estimateBalancedDeposit(
+  marketState: MarketThreeState,
+  targetLiquidity: number,
+  lowerTickApy: number,
+  upperTickApy: number,
+): { ptNeeded: number; syNeeded: number } {
+  const { financials, ticks } = marketState
+  const secondsRemaining = Math.max(0, Number(financials.expirationTs) - Date.now() / 1000)
+
+  const snap = new EffSnap(normalizedTimeRemaining(secondsRemaining), marketState.currentSyExchangeRate)
+
+  const currentSpot = ticks.currentSpotPrice
+  // Convert APY (in %) to spot price: 1 + apy/100
+  const lowerPrice = 1.0 + lowerTickApy / 100
+  const upperPrice = 1.0 + upperTickApy / 100
+
+  const priceEffLower = snap.getEffectivePrice(lowerPrice)
+  const priceEffUpper = snap.getEffectivePrice(upperPrice)
+
+  if (currentSpot <= lowerPrice) {
+    // Below range: SY only
+    const syNeeded = (targetLiquidity / snap.timeFactor) * (priceEffLower - priceEffUpper)
+    return { ptNeeded: 0, syNeeded }
+  } else if (currentSpot >= upperPrice) {
+    // Above range: PT only
+    const ptNeeded = targetLiquidity * (upperPrice - lowerPrice)
+    return { ptNeeded, syNeeded: 0 }
+  } else {
+    // Inside range: both
+    const ptNeeded = targetLiquidity * (upperPrice - currentSpot)
+    const priceEffCurrent = snap.getEffectivePrice(currentSpot)
+    const syNeeded = (targetLiquidity / snap.timeFactor) * (priceEffLower - priceEffCurrent)
+    return { ptNeeded, syNeeded }
+  }
+}
+
+/** Calculate SY and PT needed to deposit into liquidity pool from base token amount */
+/** Off-chain analogue of on-chain wrapper_provide_liquidity function */
+export function calcDepositSyAndPtFromBaseAmount(params: {
+  lowerPrice: number
+  upperPrice: number
+  baseTokenAmount: number
+  expirationTs: number
+  currentSpotPrice: number
+  syExchangeRate: number
+}) {
+  const { expirationTs, currentSpotPrice, syExchangeRate, lowerPrice, upperPrice, baseTokenAmount } = params
+
+  if (baseTokenAmount <= 0 || syExchangeRate <= 0) {
+    return {
+      syNeeded: 0,
+      ptNeeded: 0,
+    }
+  }
+
+  const secondsRemaining = Math.max(0, expirationTs)
+  const effSnap = new EffSnap(normalizedTimeRemaining(secondsRemaining), syExchangeRate)
+
+  const priceEffLower = effSnap.getEffectivePrice(lowerPrice)
+  const priceEffUpper = effSnap.getEffectivePrice(upperPrice)
+
+  // We mirror the on-chain logic in `wrapper_provide_liquidity`:
+  // 1. Use a large mock amount for both SY and PT to infer the *ratio* of SY/PT
+  //    the market "wants" for this price range (compute_token_needs on-chain).
+  // 2. Use that ratio plus the current SY exchange rate to decide how much of the
+  //    minted SY should be stripped into PT to keep the user-close to pool proportions.
+  const { syNeeded: syMock, ptNeeded: ptMock } = computeLiquidityTargetAndTokenNeeds(
+    effSnap,
+    currentSpotPrice,
+    priceEffLower,
+    priceEffUpper,
+    lowerPrice,
+    upperPrice,
+    0,
+    0,
+    0,
+    1e9,
+    1e9,
+    1e-18,
+  )
+
+  // Total SY the user would get by minting SY from base off-chain
+  // (we approximate on-chain `mint_sy_return_data.sy_out_amount`).
+  const syAmount = Math.floor(baseTokenAmount * syExchangeRate)
+
+  // Off-chain analogue of on-chain `calc_strip_amount`:
+  // B = (amt_sy * market_pt_liq) / (market_pt_liq + market_sy_liq * cur_sy_rate)
+  // here: amt_sy = syAmount, market_pt_liq = ptMock, market_sy_liq = syMock
+  const denominator = syExchangeRate * syMock + ptMock
+  const toStrip = denominator > 0 ? Math.ceil((syAmount * ptMock) / denominator) : 0
+
+  const syForLiquidity = Math.max(0, syAmount - toStrip)
+
+  // We approximate PT created from the stripped SY as:
+  //   ptAmount ≈ toStrip * syExchangeRate
+  // which is consistent with PT being a claim on base and `syExchangeRate`
+  // giving the base value of 1 SY.
+  const ptFromStrip = Math.floor(toStrip * syExchangeRate)
+
+  return {
+    syNeeded: syForLiquidity,
+    ptNeeded: ptFromStrip,
+  }
+}
+/**
+ * Calculate the amount of SY to strip into PT based on market liquidity ratio
+ * This matches the Rust implementation: calc_strip_amount in wrapper_provide_liquidity.rs
+ *
+ * The formula splits totalAmountSy into two lots: A (remains as SY) and B (stripped to PT)
+ * such that: A / (B * curSyRate) = marketSyLiq / marketPtLiq
+ *
+ * Solution: B = (totalAmountSy * marketPtLiq) / (marketPtLiq + marketSyLiq * curSyRate)
+ */
+function calcStripAmount(totalAmountSy: number, curSyRate: number, marketPtLiq: number, marketSyLiq: number): number {
+  const toStrip = (totalAmountSy * marketPtLiq) / (curSyRate * marketSyLiq + marketPtLiq)
+  return Math.ceil(toStrip)
+}
+
+/**
+ * Simulate wrapper_provide_liquidity instruction
+ * This matches the flow in wrapper_provide_liquidity.rs:
+ * 1. Mints SY from base asset
+ * 2. Calculates mock token needs for the tick range
+ * 3. Strips some SY into PT/YT based on the ratio
+ * 4. Deposits remaining SY + PT into concentrated liquidity position
+ * 5. Returns YT to user
+ *
+ * @param marketState - Current market state
+ * @param amountBase - Amount of base tokens (in asset terms, will be converted to SY)
+ * @param lowerTick - Lower tick (APY in basis points)
+ * @param upperTick - Upper tick (APY in basis points)
+ * @param syExchangeRate - SY exchange rate
+ * @returns Simulation result with LP out, YT out, amounts spent, etc.
+ */
+export function simulateWrapperProvideLiquidity(
+  marketState: MarketThreeState,
+  amountBase: number,
+  lowerTick: number,
+  upperTick: number,
+  syExchangeRate: number,
+): {
+  lpOut: number
+  ytOut: number
+  syToStrip: number
+  ptFromStrip: number
+  syRemainder: number
+  ptDeposited: number
+  syDeposited: number
+} | null {
+  try {
+    const { financials, configurationOptions, ticks } = marketState
+    const secondsRemaining = Math.max(0, Number(financials.expirationTs) - Date.now() / 1000)
+
+    // Step 1: Convert base to SY (simulating mint_sy)
+    const syAmount = amountBase / syExchangeRate
+
+    // Step 2: Create effective price snapshot
+    const snap = new EffSnap(normalizedTimeRemaining(secondsRemaining), syExchangeRate)
+
+    // Current spot price
+    const currentSpot = ticks.currentSpotPrice
+
+    // Convert tick keys to prices using compute_spot_price formula
+    // Rust: (1.0 + (key as f64) / TICK_KEY_BASE_POINTS).ln().exp() which simplifies to 1 + key/1_000_000
+    const lowerPrice = 1.0 + lowerTick / TICK_KEY_BASE_POINTS
+    const upperPrice = 1.0 + upperTick / TICK_KEY_BASE_POINTS
+
+    // Precompute effective prices
+    const priceEffLower = snap.getEffectivePrice(lowerPrice)
+    const priceEffUpper = snap.getEffectivePrice(upperPrice)
+
+    // Step 3: Calculate "mock" token needs using MOCK_AMOUNT (1e9)
+    // This gives us the ratio of SY:PT needed for this tick range
+    const MOCK_AMOUNT = 1e9
+    const mockNeeds = computeLiquidityTargetAndTokenNeeds(
+      snap,
+      currentSpot,
+      priceEffLower,
+      priceEffUpper,
+      lowerPrice,
+      upperPrice,
+      lowerTick,
+      upperTick,
+      ticks.currentTick,
+      MOCK_AMOUNT,
+      MOCK_AMOUNT,
+      configurationOptions.epsilonClamp,
+    )
+
+    // Step 4: Calculate how much SY to strip
+    // Uses the mock amounts to determine the ratio
+    const syToStrip = calcStripAmount(syAmount, syExchangeRate, mockNeeds.ptNeeded, mockNeeds.syNeeded)
+
+    console.log("[simulateWrapperProvideLiquidity] Strip calculation:", {
+      syToStrip,
+      formula: `(${syAmount} * ${mockNeeds.ptNeeded}) / (${syExchangeRate} * ${mockNeeds.syNeeded} + ${mockNeeds.ptNeeded})`,
+    })
+
+    // Step 5: Calculate PT and YT from stripping
+    // When you strip SY, you get PT = SY * syExchangeRate and YT = SY * syExchangeRate
+    const ptFromStrip = syToStrip * syExchangeRate
+    const ytOut = ptFromStrip // YT amount equals PT amount from strip
+
+    // Step 6: Calculate remaining SY after strip
+    const syRemainder = syAmount - syToStrip
+
+    // Step 7: Simulate deposit liquidity with remaining SY and PT
+    const depositResult = simulateAddLiquidity(marketState, {
+      lowerTick,
+      upperTick,
+      maxSy: Math.floor(syRemainder),
+      maxPt: Math.floor(ptFromStrip),
+      syExchangeRate,
+    })
+
+    return {
+      lpOut: depositResult.deltaL,
+      ytOut: Math.floor(ytOut),
+      syToStrip: Math.floor(syToStrip),
+      ptFromStrip: Math.floor(ptFromStrip),
+      syRemainder: Math.floor(syRemainder),
+      ptDeposited: depositResult.ptSpent,
+      syDeposited: depositResult.sySpent,
+    }
+  } catch (error) {
+    console.error("[simulateWrapperProvideLiquidity] Error:", error)
+    return null
+  }
+}

package/src/bisect.ts

@@ -0,0 +1,72 @@
+export function bisectSearch2(
+  func: (x: number) => number,
+  lo: number,
+  hi: number,
+  epsilon: number = 0.0001,
+  maxIterations: number = 2000,
+): number | null {
+  if (lo > hi) {
+    throw new Error("lo must be less than hi")
+  }
+
+  let iterations = 0
+
+  // Evaluate boundaries once
+  const fLo = func(lo)
+  const fHi = func(hi)
+
+  // Check if the target is bracketed between lo and hi
+  if (fLo * fHi > 0) {
+    return null
+  }
+
+  // Check if we're already at a root
+  if (Math.abs(fLo) < epsilon) return lo
+  if (Math.abs(fHi) < epsilon) return hi
+
+  // Track best approximation in case we don't converge exactly
+  let bestMid = (lo + hi) / 2
+  let bestError = Infinity
+
+  // Binary search within the range
+  while (iterations < maxIterations) {
+    // Use midpoint for standard bisection
+    const mid = (lo + hi) / 2
+    const fMid = func(mid)
+    const absFMid = Math.abs(fMid)
+
+    iterations++
+
+    // Track best approximation
+    if (absFMid < bestError) {
+      bestError = absFMid
+      bestMid = mid
+    }
+
+    // Check convergence
+    if (absFMid < epsilon) {
+      return mid
+    }
+
+    // Early termination if range is too small relative to epsilon
+    const rangeSize = hi - lo
+    if (rangeSize < epsilon * 0.01) {
+      return bestMid
+    }
+
+    // Adjust the search range based on the target
+    // Use fLo instead of recalculating func(lo)
+    if (fLo * fMid < 0) {
+      // eslint-disable-next-line no-param-reassign
+      hi = mid
+      // Note: fHi would be fMid, but we don't need to track it
+    } else {
+      // eslint-disable-next-line no-param-reassign
+      lo = mid
+      // Note: fLo would be fMid, but we recalculate in the condition anyway
+    }
+  }
+
+  // Return best approximation if we didn't converge
+  return bestMid
+}

package/src/index.ts

@@ -0,0 +1,74 @@
+/**
+ * Market Three Math - CLMM Simulation Package
+ *
+ * This package provides TypeScript implementations of the CLMM (Concentrated Liquidity Market Maker)
+ * mathematical functions from the Exponent CLMM program. It allows for client-side simulation of:
+ * - Swap operations (PT <-> SY trades)
+ * - Liquidity deposits (add_liquidity)
+ * - Price and liquidity calculations
+ *
+ * The implementations are ported from Rust code in solana/programs/exponent_clmm
+ */
+
+// Export types
+export * from "./types"
+
+// Export utility functions
+export {
+  EffSnap,
+  normalizedTimeRemaining,
+  calculateFeeRate,
+  getFeeFromAmount,
+  getActiveLiquidity,
+  getSuccessorTickKey,
+  getPredecessorTickKey,
+  getImpliedRate,
+  findTickByKey,
+  convertApyToApyBp,
+  convertApyBpToApy,
+  calcPtPriceInAsset,
+  getSuccessorTickByIdx,
+} from "./utils"
+
+// Export swap functions
+export { simulateSwap } from "./swap"
+export { getSwapQuote, QuoteDirection } from "./quote"
+
+// Export YT trade functions
+export { simulateBuyYt, simulateSellYt, simulateBuyYtWithSyIn } from "./ytTrades"
+export type {
+  BuyYtSimulationArgs,
+  BuyYtSimulationResult,
+  SellYtSimulationArgs,
+  SellYtSimulationResult,
+} from "./ytTrades"
+
+// Export add liquidity functions
+export {
+  simulateAddLiquidity,
+  computeLiquidityTargetAndTokenNeeds,
+  calculateLpOut,
+  estimateBalancedDeposit,
+  calcDepositSyAndPtFromBaseAmount,
+  simulateWrapperProvideLiquidity,
+} from "./addLiquidity"
+
+export { getPtAndSyOnWithdrawLiquidity } from "./withdrawLiquidity"
+
+// Export bisect search utility
+export { bisectSearch2 } from "./bisect"
+
+// Export liquidity histogram functions
+export { buildLiquidityHistogram, buildLiquidityHistogramSimple } from "./liquidityHistogram"
+export type { LiquidityHistogramBin } from "./liquidityHistogram"
+
+// Re-export common types for convenience
+export type {
+  SwapArgs,
+  SwapOutcome,
+  AddLiquidityArgs,
+  AddLiquidityOutcome,
+  LiquidityNeeds,
+  MarketThreeState,
+} from "./types"
+export { SwapDirection } from "./types"