@exponent-labs/market-three-math 0.1.8 → 0.9.0

package/src/types.ts

@@ -29,6 +29,21 @@ export interface SwapArgs {
   isCurrentFlashSwap: boolean
 }
 
+export interface SwapExactOutArgs {
+  /** Direction of the swap (only SyToPt is supported) */
+  direction: SwapDirection
+  /** Exact amount out target (net, after fees) */
+  amountOut: number
+  /** Optional spot price limit (anti-sandwich) */
+  priceSpotLimit?: number
+  /** SY exchange rate */
+  syExchangeRate: number
+  /** Is this a flash swap? */
+  isCurrentFlashSwap: boolean
+  /** Optional max input budget constraint */
+  amountInConstraint?: number
+}
+
 export interface SwapOutcome {
   /** Amount of input consumed */
   amountInConsumed: number
@@ -44,6 +59,23 @@ export interface SwapOutcome {
   finalTickIndex: number
 }
 
+export interface SwapOutcomeV2 {
+  /** 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 key after swap */
+  finalTickKey: number
+  /** Post-trade market state after applying in-swap state updates */
+  postMarketState?: MarketThreeState
+}
+
 export interface AddLiquidityArgs {
   /** Lower tick key (ln implied rate in bps) */
   lowerTick: number
@@ -77,4 +109,27 @@ export interface LiquidityNeeds {
   priceSplitForNeed: number
   /** Tick index of the split point */
   priceSplitTickIdx: number
+  /** Original max SY before CLMM trimming (for crossing tick scaling) */
+  originalMaxSy: number
+  /** Original max PT before CLMM trimming (for crossing tick scaling) */
+  originalMaxPt: number
+  /** PT distribution extent: current_spot - lower_price */
+  duLeftTotal: number
+  /** SY distribution extent: eff_price_current - eff_price_upper */
+  deltaCRightTotal: number
+}
+
+/** State of the crossing (current) tick for proportional distribution */
+export interface CrossingTickState {
+  principalPt: number
+  principalSy: number
+  principalShareSupply: number
+}
+
+/** Parameters for scaling crossing tick inputs from original max values */
+export interface CrossingScaleParams {
+  originalMaxSy: number
+  originalMaxPt: number
+  duLeftTotal: number
+  deltaCRightTotal: number
 }

package/src/utils.ts

@@ -131,7 +131,7 @@ export function getSuccessorTickKey(ticks: Ticks, currentTickKey: number): numbe
  * 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 {
+export function getSuccessorTickIdxByIdx(ticks: Ticks, tickIdx: number): number | null {
   //TODO Refactor to make it more CPU efficient
   const tick = ticks.ticksTree.at(tickIdx - 1) ?? null
 
@@ -147,6 +147,26 @@ export function getSuccessorTickByIdx(ticks: Ticks, tickIdx: number): number | n
   return !!successorTick ? ticks.ticksTree.indexOf(successorTick) + 1 : null
 }
 
+/**
+ * Find the predecessor tick by index in the tick tree
+ * This is the inverse of getSuccessorTickIdxByIdx - finds the tick with the largest apyBasePoints that is still less than the current tick
+ */
+export function getPredecessorTickIdxByIdx(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 less than current tick
+  const predecessorTicks = ticks.ticksTree
+    .filter((t) => t.apyBasePoints < tick.apyBasePoints)
+    .sort((a, b) => b.apyBasePoints - a.apyBasePoints) // Sort descending to get the largest that's still less
+
+  const predecessorTick = predecessorTicks.at(0) ?? null
+
+  return !!predecessorTick ? ticks.ticksTree.indexOf(predecessorTick) + 1 : null
+}
+
 /**
  * Find the predecessor tick (next tick to the left)
  * In Rust: ticks.predecessor_idx(current_left_boundary_index)
@@ -183,12 +203,13 @@ export function getImpliedRate(tickKey: number): number {
 }
 
 /**
- * Find a tick by its key
+ * Find a tick by its key (apyBasePoints)
+ * @returns tick and its 1-based index, or null if not found
  */
 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 }
+  return { tick: ticks.ticksTree[index], index: index + 1 } // Return 1-based index to match Rust
 }
 
 /**

package/src/utilsV2.ts

@@ -0,0 +1,337 @@
+/**
+ * Utilities V2 for CLMM calculations
+ * More closely mirrors the Rust on-chain implementation
+ * Uses tick key (apyBasePoints) as the primary identifier instead of array index
+ */
+import { Tick, Ticks } from "@exponent-labs/exponent-fetcher"
+
+const SECONDS_PER_YEAR = 365 * 24 * 60 * 60
+const TICK_KEY_BASE_POINTS = 1_000_000
+const PRECISE_NUMBER_DENOM = 1_000_000_000_000_000_000n
+
+function cloneTick(tick: Tick): Tick {
+  return {
+    ...tick,
+    farms: tick.farms.map((farm) => ({ ...farm })),
+    emissions: tick.emissions.map((emission) => ({ ...emission })),
+  }
+}
+
+/**
+ * Effective price snapshot
+ * Matches the Rust EffSnap struct
+ */
+export class EffSnap {
+  timeFactor: number
+  syExchangeRate: number
+
+  constructor(timeFactor: number, syExchangeRate: number) {
+    this.timeFactor = timeFactor
+    this.syExchangeRate = syExchangeRate
+  }
+
+  /**
+   * Calculate effective price from spot price
+   * Rust: C(u) = u^(-(τ-1)) / (r * (τ - 1))
+   */
+  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: u = (r * C * (τ - 1))^(1/(1-τ))
+   */
+  spotPriceFromEffectivePrice(cEff: number): number {
+    const base = this.syExchangeRate * cEff * (this.timeFactor - 1.0)
+    return Math.pow(base, 1.0 / (1.0 - this.timeFactor))
+  }
+}
+
+/**
+ * TicksWrapper - wraps the ticks array and provides RB-tree-like operations
+ * This simulates the Rust RB-tree behavior using a sorted map
+ */
+export class TicksWrapper {
+  private ticksByKey: Map<number, Tick> // key (apyBasePoints) -> Tick
+  private sortedKeys: number[] // sorted list of keys for successor/predecessor
+  private baseTicksTree: Tick[]
+  private market: Ticks["market"]
+
+  currentSpotPrice: number
+  currentTickKey: number // Store key instead of array index
+  currentPrefixSum: bigint
+  feeGrowthIndexGlobalPt: bigint
+  feeGrowthIndexGlobalSy: bigint
+
+  constructor(ticks: Ticks) {
+    this.ticksByKey = new Map()
+    this.baseTicksTree = ticks.ticksTree.map(cloneTick)
+    this.market = ticks.market
+
+    // Build map from apyBasePoints -> Tick
+    for (const tick of this.baseTicksTree) {
+      if (tick.apyBasePoints > 0) {
+        this.ticksByKey.set(tick.apyBasePoints, tick)
+      }
+    }
+
+    // Get sorted keys for efficient successor/predecessor lookup
+    this.sortedKeys = Array.from(this.ticksByKey.keys()).sort((a, b) => a - b)
+
+    this.currentSpotPrice = ticks.currentSpotPrice
+    this.currentPrefixSum = ticks.currentPrefixSum
+    this.feeGrowthIndexGlobalPt = ticks.feeGrowthIndexGlobalPt
+    this.feeGrowthIndexGlobalSy = ticks.feeGrowthIndexGlobalSy
+
+    // Convert currentTick (1-based index) to key
+    // In Rust, currentTick is stored as 1-based index into the ticks tree
+    // We need to find the corresponding key (apyBasePoints)
+    const currentTickFromArray = this.baseTicksTree[ticks.currentTick - 1]
+    if (currentTickFromArray && currentTickFromArray.apyBasePoints > 0) {
+      this.currentTickKey = currentTickFromArray.apyBasePoints
+    } else {
+      // Fallback: find tick with spot price closest to currentSpotPrice
+      this.currentTickKey = this.findTickKeyBySpotPrice(ticks.currentSpotPrice)
+    }
+  }
+
+  /**
+   * Find tick key by spot price (for initialization)
+   */
+  private findTickKeyBySpotPrice(spotPrice: number): number {
+    let closestKey = this.sortedKeys[0] || 0
+
+    // Iterate through sorted keys to ensure order
+    for (const key of this.sortedKeys) {
+      const tick = this.ticksByKey.get(key)
+      if (!tick) continue
+
+      const diff = spotPrice - tick.impliedRate
+      if (diff < 0) {
+        // If diff is negative, return the previous key (the one we just passed)
+        return closestKey
+      }
+      closestKey = key
+    }
+
+    return closestKey
+  }
+
+  /**
+   * Get tick by key (apyBasePoints)
+   * Equivalent to Rust's ticks_tree.get_node(idx).value
+   */
+  getTickByKey(key: number): Tick | null {
+    return this.ticksByKey.get(key) ?? null
+  }
+
+  /**
+   * Get spot price for a tick key
+   * Equivalent to Rust's ticks.get_spot_price(idx)
+   * In Rust: spot_price = 1.0 + key / TICK_KEY_BASE_POINTS
+   */
+  getSpotPrice(key: number): number {
+    const tick = this.ticksByKey.get(key)
+    if (tick) {
+      return tick.impliedRate
+    }
+    // Fallback calculation if tick not found
+    return 1.0 + key / TICK_KEY_BASE_POINTS
+  }
+
+  /**
+   * Find successor key (next tick with greater apyBasePoints)
+   * Equivalent to Rust's ticks.successor_idx(idx)
+   */
+  successorKey(currentKey: number): number | null {
+    const idx = this.sortedKeys.findIndex((k) => k > currentKey)
+    return idx !== -1 ? this.sortedKeys[idx] : null
+  }
+
+  /**
+   * Find predecessor key (previous tick with smaller apyBasePoints)
+   * Equivalent to Rust's ticks.predecessor_idx(idx)
+   */
+  predecessorKey(currentKey: number): number | null {
+    // Find the largest key that is smaller than currentKey
+    for (let i = this.sortedKeys.length - 1; i >= 0; i--) {
+      if (this.sortedKeys[i] < currentKey) {
+        return this.sortedKeys[i]
+      }
+    }
+    return null
+  }
+
+  /**
+   * Get principal values for a tick
+   */
+  getPrincipals(key: number): { principalPt: bigint; principalSy: bigint } {
+    const tick = this.ticksByKey.get(key)
+    return {
+      principalPt: tick?.principalPt ?? 0n,
+      principalSy: tick?.principalSy ?? 0n,
+    }
+  }
+
+  /**
+   * Get liquidity net for a tick
+   */
+  getLiquidityNet(key: number): bigint {
+    const tick = this.ticksByKey.get(key)
+    return tick?.liquidityNet ?? 0n
+  }
+
+  private clamp01(value: number): number {
+    if (!Number.isFinite(value)) return 0
+    if (value <= 0) return 0
+    if (value >= 1) return 1
+    return value
+  }
+
+  private ratioToPrecise(value: number): bigint {
+    const clamped = this.clamp01(value)
+    if (clamped <= 0) return 0n
+    if (clamped >= 1) return PRECISE_NUMBER_DENOM
+    return BigInt(Math.round(clamped * Number(PRECISE_NUMBER_DENOM)))
+  }
+
+  private scaleByRatioFloor(value: bigint, ratioScaled: bigint): bigint {
+    return (value * ratioScaled) / PRECISE_NUMBER_DENOM
+  }
+
+  private splitPrincipalsAfterInsert(insertedKey: number, snap: EffSnap): void {
+    const leftKey = this.predecessorKey(insertedKey)
+    const rightKey = this.successorKey(insertedKey)
+    if (leftKey == null || rightKey == null) {
+      return
+    }
+
+    const leftTick = this.ticksByKey.get(leftKey)
+    const insertedTick = this.ticksByKey.get(insertedKey)
+    if (!leftTick || !insertedTick) {
+      return
+    }
+
+    const lowerPrice = this.getSpotPrice(leftKey)
+    const insertedPrice = this.getSpotPrice(insertedKey)
+    const upperPrice = this.getSpotPrice(rightKey)
+
+    const du = upperPrice - lowerPrice
+    const rLen = du <= 0 ? 0 : this.clamp01((insertedPrice - lowerPrice) / du)
+    const rLenScaled = this.ratioToPrecise(rLen)
+
+    const uPtR = Math.min(upperPrice, this.currentSpotPrice)
+    const duPtTot = uPtR - lowerPrice
+    const duPtLeft = Math.min(insertedPrice, this.currentSpotPrice) - lowerPrice
+    const rPt = duPtTot <= 0 ? 1 : this.clamp01(duPtLeft / duPtTot)
+    const rPtScaled = this.ratioToPrecise(rPt)
+
+    const uSyL = Math.max(lowerPrice, this.currentSpotPrice)
+    const cL = snap.getEffectivePrice(uSyL)
+    const cM = snap.getEffectivePrice(Math.min(Math.max(insertedPrice, this.currentSpotPrice), upperPrice))
+    const cR = snap.getEffectivePrice(upperPrice)
+    const dcTot = cL - cR
+    const dcLeft = cL - cM
+    const rSy = dcTot <= 0 ? 1 : this.clamp01(dcLeft / dcTot)
+    const rSyScaled = this.ratioToPrecise(rSy)
+
+    const ptLowerBefore = leftTick.principalPt
+    const syLowerBefore = leftTick.principalSy
+    const supplyLowerBefore = leftTick.principalShareSupply
+
+    const ptLeft = this.scaleByRatioFloor(ptLowerBefore, rPtScaled)
+    const syLeft = this.scaleByRatioFloor(syLowerBefore, rSyScaled)
+    const supplyLeft = this.scaleByRatioFloor(supplyLowerBefore, rLenScaled)
+
+    leftTick.principalPt = ptLeft
+    leftTick.principalSy = syLeft
+    leftTick.principalShareSupply = supplyLeft
+
+    insertedTick.principalPt += ptLowerBefore - ptLeft
+    insertedTick.principalSy += syLowerBefore - syLeft
+    insertedTick.principalShareSupply += supplyLowerBefore - supplyLeft
+  }
+
+  upsertBoundaryTick(key: number, snap: EffSnap): void {
+    if (this.ticksByKey.has(key)) {
+      return
+    }
+
+    const templateTick = this.baseTicksTree[0]
+    const newTick: Tick = {
+      liquidityNet: 0n,
+      liquidityGross: 0n,
+      feeGrowthOutsidePt: 0n,
+      feeGrowthOutsideSy: 0n,
+      impliedRate: 1 + key / TICK_KEY_BASE_POINTS,
+      principalPt: 0n,
+      principalSy: 0n,
+      apyBasePoints: key,
+      principalShareSupply: 0n,
+      farms: templateTick ? templateTick.farms.map(() => ({ lastSeenIndex: 0 })) : [],
+      emissions: templateTick
+        ? templateTick.emissions.map(() => ({ lastSeenIndex: 0, lastPositionIndex: 0 }))
+        : [],
+      lastSplitEpoch: 0n,
+      frozenLiquidity: 0n,
+    }
+
+    this.baseTicksTree.push(newTick)
+    this.ticksByKey.set(key, newTick)
+    this.sortedKeys.push(key)
+    this.sortedKeys.sort((a, b) => a - b)
+
+    this.splitPrincipalsAfterInsert(key, snap)
+  }
+
+  setPrincipals(key: number, principalPt: bigint, principalSy: bigint): void {
+    const tick = this.ticksByKey.get(key)
+    if (!tick) return
+    tick.principalPt = principalPt < 0n ? 0n : principalPt
+    tick.principalSy = principalSy < 0n ? 0n : principalSy
+  }
+
+  toTicks(currentTickKey: number, currentSpotPrice: number, currentPrefixSum: bigint): Ticks {
+    const currentTickIdx = this.baseTicksTree.findIndex((tick) => tick.apyBasePoints === currentTickKey)
+    const fallbackTickKey = this.findTickKeyBySpotPrice(currentSpotPrice)
+    const fallbackTickIdx = this.baseTicksTree.findIndex((tick) => tick.apyBasePoints === fallbackTickKey)
+    const resolvedCurrentTick = currentTickIdx >= 0 ? currentTickIdx + 1 : fallbackTickIdx >= 0 ? fallbackTickIdx + 1 : 0
+
+    return {
+      currentTick: resolvedCurrentTick,
+      ticksTree: this.baseTicksTree.map(cloneTick),
+      market: this.market,
+      feeGrowthIndexGlobalPt: this.feeGrowthIndexGlobalPt,
+      feeGrowthIndexGlobalSy: this.feeGrowthIndexGlobalSy,
+      currentPrefixSum,
+      currentSpotPrice,
+    }
+  }
+}
+
+/**
+ * Calculate normalized time remaining
+ */
+export function normalizedTimeRemaining(secondsRemaining: number): number {
+  return secondsRemaining / SECONDS_PER_YEAR
+}
+
+/**
+ * Calculate current fee rate
+ */
+export function calculateFeeRate(lnFeeRateRoot: number, secondsRemaining: number): number {
+  const timeFactor = normalizedTimeRemaining(secondsRemaining)
+  return Math.exp(lnFeeRateRoot * timeFactor)
+}
+
+/**
+ * Calculate fee from amount
+ * Mirrors Rust: ((amount as f64) * (fee_rate - 1.0)).ceil() as u64
+ */
+export function getFeeFromAmount(amount: number, feeRate: number): number {
+  return Math.ceil(amount * (feeRate - 1.0))
+}

package/src/withdrawLiquidity.ts

@@ -1,6 +1,6 @@
 import { LpPositionCLMM, MarketThree, Ticks } from "@exponent-labs/exponent-fetcher"
 
-import { getSuccessorTickByIdx } from "./utils"
+import { getSuccessorTickIdxByIdx } from "./utils"
 
 /**
  * TypeScript version of project_anchor_shares_to_current_ticks from Rust
@@ -20,7 +20,14 @@ type ShareTracker = LpPositionCLMM["shareTrackers"][0]
 function projectAnchorSharesToCurrentTicks(ticks: Ticks, rootShares: ShareTracker[]): ShareTracker[] {
   const SENTINEL = 0xffffffff // Sentinel value for tree traversal (matches Rust implementation)
 
-  const stack = [...rootShares] // Clone the trackers array
+  // Deep clone the trackers to avoid mutating the original objects (important for React Query caching)
+  const stack: ShareTracker[] = rootShares.map((s) => ({
+    tickIdx: s.tickIdx,
+    rightTickIdx: s.rightTickIdx,
+    splitEpoch: s.splitEpoch,
+    lpShare: s.lpShare,
+    emissions: s.emissions.map((e) => ({ staged: e.staged, lastSeenIndex: e.lastSeenIndex })),
+  }))
   const newShares: ShareTracker[] = [] // This will hold the leaf shares
 
   while (stack.length > 0) {
@@ -42,7 +49,7 @@ function projectAnchorSharesToCurrentTicks(ticks: Ticks, rootShares: ShareTracke
 
       if (rightIndex !== SENTINEL) {
         // Find the successor tick (the split point)
-        const splitedIndex = getSuccessorTickByIdx(ticks, principalShare.tickIdx)
+        const splitedIndex = getSuccessorTickIdxByIdx(ticks, principalShare.tickIdx)
 
         if (splitedIndex === null) {
           //? No successor tick found for splitting
@@ -201,7 +208,6 @@ function calculatePtSyRemoval(
     const tickNode = ticks.ticksTree.at(share.tickIdx - 1) ?? null
 
     if (!tickNode) {
-      //? Tick node not found for provided tickIdx
       continue
     }
 
@@ -213,11 +219,11 @@ function calculatePtSyRemoval(
 
     // Calculate PT output for this tick
     // pt_out = principal_pt * burn_shares / supply
-    const ptOut = (tickNode.principalPt * burnShares) / supply
+    const ptOut = supply > 0n ? (tickNode.principalPt * burnShares) / supply : 0n
 
     // Calculate SY output for this tick
     // sy_out = principal_sy * burn_shares / supply
-    const syOut = (tickNode.principalSy * burnShares) / supply
+    const syOut = supply > 0n ? (tickNode.principalSy * burnShares) / supply : 0n
 
     totalPtOut += ptOut
     totalSyOut += syOut