@exponent-labs/market-three-math 0.9.16 → 0.9.18

package/src/withdrawLiquidity.test.ts

@@ -0,0 +1,189 @@
+import { PublicKey } from "@solana/web3.js"
+
+import type { LpPositionCLMM, MarketThree, Tick, Ticks } from "@exponent-labs/exponent-fetcher"
+
+import { getPtAndSyOnWithdrawLiquidity } from "./withdrawLiquidity"
+
+const PRECISE_NUMBER_DENOM = 1_000_000_000_000n
+const SENTINEL_TICK_INDEX = 0xffffffff
+const PUBLIC_KEY = PublicKey.default
+
+const preciseRaw = (value: bigint) => value * PRECISE_NUMBER_DENOM
+
+const marketEmissions: MarketThree["emissions"] = { trackers: [] }
+
+const makeTick = (overrides: Partial<Tick> = {}): Tick => ({
+  apyBasePoints: 1,
+  impliedRate: 1.0,
+  principalPt: 0n,
+  principalSy: 0n,
+  principalShareSupply: 0n,
+  liquidityNet: 0n,
+  liquidityGross: 0n,
+  feeGrowthOutsidePt: 0n,
+  feeGrowthOutsideSy: 0n,
+  farms: [],
+  emissions: [],
+  lastSplitEpoch: 0n,
+  splitParentEpoch: 0n,
+  frozenLiquidity: 0n,
+  splitParentIdx: SENTINEL_TICK_INDEX,
+  ...overrides,
+})
+
+const makeTicks = (ticksTree: Tick[]): Ticks => ({
+  currentTick: 1,
+  ticksTree,
+  market: PUBLIC_KEY,
+  feeGrowthIndexGlobalPt: 0n,
+  feeGrowthIndexGlobalSy: 0n,
+  currentPrefixSum: 0n,
+  currentSpotPrice: 1,
+})
+
+const makePosition = (overrides: Partial<LpPositionCLMM> = {}): LpPositionCLMM => ({
+  owner: PUBLIC_KEY,
+  market: PUBLIC_KEY,
+  feeInsideLastPt: 0n,
+  feeInsideLastSy: 0n,
+  lpBalance: 1n,
+  tokensOwedSy: 0n,
+  tokensOwedPt: 0n,
+  lowerTickIdx: 1,
+  upperTickIdx: 2,
+  farms: [],
+  shareTrackers: [
+    {
+      tickIdx: 1,
+      rightTickIdx: 2,
+      splitEpoch: 0n,
+      lpShare: PRECISE_NUMBER_DENOM / 2n,
+      emissions: [],
+    },
+  ],
+  crossingSplit: {
+    crossLeftIdx: SENTINEL_TICK_INDEX,
+    crossRightIdx: SENTINEL_TICK_INDEX,
+    lpBalanceCrossing: 0n,
+    isActive: false,
+  },
+  ...overrides,
+})
+
+describe("withdraw liquidity math", () => {
+  it("uses precise Number-style principal math for fractional shares", () => {
+    const ticks = makeTicks([
+      makeTick({
+        principalPt: 7n,
+        principalSy: 11n,
+        principalShareSupply: PRECISE_NUMBER_DENOM,
+      }),
+      makeTick({ apyBasePoints: 2, impliedRate: 2 }),
+    ])
+
+    expect(getPtAndSyOnWithdrawLiquidity(marketEmissions, ticks, makePosition(), 1n)).toEqual({
+      totalPtOut: 3n,
+      totalSyOut: 5n,
+    })
+  })
+
+  it("returns full principal when burned shares cover the supply", () => {
+    const ticks = makeTicks([
+      makeTick({
+        principalPt: 7n,
+        principalSy: 11n,
+        principalShareSupply: PRECISE_NUMBER_DENOM,
+      }),
+      makeTick({ apyBasePoints: 2, impliedRate: 2 }),
+    ])
+    const position = makePosition({
+      shareTrackers: [
+        {
+          tickIdx: 1,
+          rightTickIdx: 2,
+          splitEpoch: 0n,
+          lpShare: PRECISE_NUMBER_DENOM,
+          emissions: [],
+        },
+      ],
+    })
+
+    expect(getPtAndSyOnWithdrawLiquidity(marketEmissions, ticks, position, 1n)).toEqual({
+      totalPtOut: 7n,
+      totalSyOut: 11n,
+    })
+  })
+
+  it("rejects burn shares that exceed tick supply", () => {
+    const ticks = makeTicks([
+      makeTick({
+        principalPt: 7n,
+        principalSy: 11n,
+        principalShareSupply: PRECISE_NUMBER_DENOM / 2n,
+      }),
+      makeTick({ apyBasePoints: 2, impliedRate: 2 }),
+    ])
+    const position = makePosition({
+      shareTrackers: [
+        {
+          tickIdx: 1,
+          rightTickIdx: 2,
+          splitEpoch: 0n,
+          lpShare: PRECISE_NUMBER_DENOM,
+          emissions: [],
+        },
+      ],
+    })
+
+    expect(() => getPtAndSyOnWithdrawLiquidity(marketEmissions, ticks, position, 1n)).toThrow(
+      "withdraw burn shares exceed tick supply",
+    )
+  })
+
+  it("projects split shares through split parent epoch instead of immediate successor", () => {
+    const ticks = makeTicks([
+      makeTick({
+        apyBasePoints: 100,
+        impliedRate: 1.0,
+        principalPt: 50n,
+        principalShareSupply: preciseRaw(50n),
+        lastSplitEpoch: 1n,
+      }),
+      makeTick({
+        apyBasePoints: 125,
+        impliedRate: 1.25,
+        principalPt: 999n,
+        principalShareSupply: preciseRaw(50n),
+        splitParentEpoch: 99n,
+        splitParentIdx: 1,
+      }),
+      makeTick({
+        apyBasePoints: 150,
+        impliedRate: 1.5,
+        principalPt: 300n,
+        principalShareSupply: preciseRaw(50n),
+        splitParentEpoch: 0n,
+        splitParentIdx: 1,
+      }),
+      makeTick({
+        apyBasePoints: 200,
+        impliedRate: 2.0,
+      }),
+    ])
+    const position = makePosition({
+      lpBalance: 100n,
+      upperTickIdx: 4,
+      shareTrackers: [
+        {
+          tickIdx: 1,
+          rightTickIdx: 4,
+          splitEpoch: 0n,
+          lpShare: preciseRaw(100n),
+          emissions: [],
+        },
+      ],
+    })
+
+    expect(getPtAndSyOnWithdrawLiquidity(marketEmissions, ticks, position, 100n).totalPtOut).toBe(350n)
+  })
+})

package/src/withdrawLiquidity.ts

@@ -1,6 +1,88 @@
-import { LpPositionCLMM, MarketThree, Ticks } from "@exponent-labs/exponent-fetcher"
+import type { LpPositionCLMM, MarketThree, Ticks } from "@exponent-labs/exponent-fetcher"
 
-import { getSuccessorTickIdxByIdx } from "./utils"
+const PRECISE_NUMBER_DENOM = 1_000_000_000_000n
+const SENTINEL_TICK_INDEX = 0xffffffff
+
+const invariantError = (message: string) => new Error(`WithdrawLiquidityInvariantViolated: ${message}`)
+
+const getTickByIndex = (ticks: Ticks, tickIdx: number) => {
+  const tick = ticks.ticksTree[tickIdx - 1]
+  if (!tick || tick.apyBasePoints <= 0) {
+    throw invariantError(`missing tick at index ${tickIdx}`)
+  }
+
+  return tick
+}
+
+const getTickKey = (ticks: Ticks, tickIdx: number) => getTickByIndex(ticks, tickIdx).apyBasePoints
+
+const successorIdx = (ticks: Ticks, tickIdx: number): number | null => {
+  const tickKey = getTickKey(ticks, tickIdx)
+  let best: { tickIdx: number; key: number } | null = null
+
+  for (let index = 0; index < ticks.ticksTree.length; index++) {
+    const key = ticks.ticksTree[index].apyBasePoints
+    if (key <= tickKey) {
+      continue
+    }
+    if (!best || key < best.key) {
+      best = { tickIdx: index + 1, key }
+    }
+  }
+
+  return best?.tickIdx ?? null
+}
+
+const splitSuccessorForEpoch = (ticks: Ticks, leftIdx: number, rightIdx: number, splitEpoch: bigint): number | null => {
+  let cursor = successorIdx(ticks, leftIdx)
+  while (cursor != null && cursor !== SENTINEL_TICK_INDEX && cursor !== rightIdx) {
+    const tick = getTickByIndex(ticks, cursor)
+    if (tick.splitParentIdx === leftIdx && tick.splitParentEpoch === splitEpoch) {
+      return cursor
+    }
+    cursor = successorIdx(ticks, cursor)
+  }
+
+  return null
+}
+
+const fastMulRatioRaw = (rawPreciseNumber: bigint, numerator: bigint, denominator: bigint): bigint => {
+  if (denominator <= 0n) {
+    throw invariantError("fastMulRatio denominator is zero")
+  }
+  if (numerator === 0n || rawPreciseNumber === 0n) {
+    return 0n
+  }
+  if (numerator === denominator) {
+    return rawPreciseNumber
+  }
+
+  const q = rawPreciseNumber / denominator
+  const r = rawPreciseNumber % denominator
+  return q * numerator + (r * numerator) / denominator
+}
+
+const numberFromRatioRaw = (numerator: bigint, denominator: bigint): bigint => {
+  if (denominator <= 0n) {
+    throw invariantError("Number::from_ratio denominator is zero")
+  }
+
+  return (numerator * PRECISE_NUMBER_DENOM) / denominator
+}
+
+const mulNumberRaw = (leftRaw: bigint, rightRaw: bigint): bigint => (leftRaw * rightRaw) / PRECISE_NUMBER_DENOM
+
+const principalOutForBurn = (principal: bigint, burnShares: bigint, shareSupply: bigint): bigint => {
+  if (principal === 0n || burnShares === 0n || shareSupply === 0n) {
+    return 0n
+  }
+  if (burnShares >= shareSupply) {
+    return principal
+  }
+
+  const out = (principal * burnShares) / shareSupply
+  return out < principal ? out : principal
+}
 
 /**
  * TypeScript version of project_anchor_shares_to_current_ticks from Rust
@@ -13,13 +95,10 @@ import { getSuccessorTickIdxByIdx } from "./utils"
  * @param rootShares - The original share trackers to project
  * @returns Array of projected principal shares
  *
- * Note: Requires TicksExtended with lastSplitEpoch and emissions data.
- * The current exponent-fetcher deserializer would need to be updated to extract these fields.
+ * Note: Requires TicksExtended with split-parent metadata and emissions data.
  */
 type ShareTracker = LpPositionCLMM["shareTrackers"][0]
 function projectAnchorSharesToCurrentTicks(ticks: Ticks, rootShares: ShareTracker[]): ShareTracker[] {
-  const SENTINEL = 0xffffffff // Sentinel value for tree traversal (matches Rust implementation)
-
   // Deep clone the trackers to avoid mutating the original objects (important for React Query caching)
   const stack: ShareTracker[] = rootShares.map((s) => ({
     tickIdx: s.tickIdx,
@@ -32,14 +111,7 @@ function projectAnchorSharesToCurrentTicks(ticks: Ticks, rootShares: ShareTracke
 
   while (stack.length > 0) {
     const principalShare = stack.pop()!
-
-    // Find the tick node for this share
-    const tickNode = ticks.ticksTree.at(principalShare.tickIdx - 1) ?? null
-
-    if (!tickNode) {
-      //? Tick node not found for tickIdx
-      continue
-    }
+    const tickNode = getTickByIndex(ticks, principalShare.tickIdx)
 
     const lastSplitEpoch = tickNode.lastSplitEpoch
 
@@ -47,60 +119,54 @@ function projectAnchorSharesToCurrentTicks(ticks: Ticks, rootShares: ShareTracke
     if (principalShare.splitEpoch < lastSplitEpoch) {
       const rightIndex = principalShare.rightTickIdx
 
-      if (rightIndex !== SENTINEL) {
-        // Find the successor tick (the split point)
-        const splitedIndex = getSuccessorTickIdxByIdx(ticks, principalShare.tickIdx)
-
-        if (splitedIndex === null) {
-          //? No successor tick found for splitting
-          continue
-        }
-
-        const tickSpotPrice = tickNode.impliedRate
-        const rightTickNode = ticks.ticksTree.at(rightIndex - 1) ?? null
-        const splitedTickNode = ticks.ticksTree.at(splitedIndex - 1) ?? null
-
-        if (!rightTickNode || !splitedTickNode) {
-          //? Could not find right or split tick nodes
-          continue
-        }
-
-        // Calculate the proportions based on spot price ranges
-        const splitedFullRange = rightTickNode.impliedRate - tickSpotPrice
-        const currentSplitRange = splitedTickNode.impliedRate - tickSpotPrice
-
-        // Calculate how much LP share goes to the left portion
-        const leftShare = Math.floor(Number(principalShare.lpShare) * (currentSplitRange / splitedFullRange))
-
-        // Create new emission trackers with staged reset to 0
-        const newEmissions: ShareTracker["emissions"] = principalShare.emissions.map((tracker) => ({
-          staged: 0n,
-          lastSeenIndex: tracker.lastSeenIndex,
-        }))
-
-        // Calculate the migrated share (right portion)
-        const migratedShare = principalShare.lpShare - BigInt(leftShare)
-
-        // Update the current share to be the left portion
-        principalShare.lpShare = BigInt(leftShare)
-        principalShare.rightTickIdx = splitedIndex
-
-        // Push the right portion back onto the stack for further processing
-        stack.push({
-          tickIdx: splitedIndex,
-          rightTickIdx: rightIndex,
-          splitEpoch: principalShare.splitEpoch,
-          lpShare: migratedShare,
-          emissions: newEmissions,
-        })
-
-        // Update the split epoch to mark this share as processed
-        principalShare.splitEpoch = lastSplitEpoch
-      } else {
-        // Error: we have a split range but no right index
-        //? No right index for split range
-        continue
+      if (rightIndex === SENTINEL_TICK_INDEX) {
+        throw invariantError("no right index for split range")
       }
+
+      const splitedIndex = splitSuccessorForEpoch(ticks, principalShare.tickIdx, rightIndex, principalShare.splitEpoch)
+      if (splitedIndex == null) {
+        throw invariantError("no split successor for parent epoch")
+      }
+
+      const tickSpotPrice = tickNode.impliedRate
+      const rightTickNode = getTickByIndex(ticks, rightIndex)
+      const splitedTickNode = getTickByIndex(ticks, splitedIndex)
+
+      const splitedFullRange = rightTickNode.impliedRate - tickSpotPrice
+      const currentSplitRange = splitedTickNode.impliedRate - tickSpotPrice
+
+      const [leftShare, migratedShare] =
+        splitedFullRange <= 0
+          ? [0n, principalShare.lpShare]
+          : (() => {
+              const ratio = Math.max(0, Math.min(1, currentSplitRange / splitedFullRange))
+              const scaledNum = BigInt(Math.round(ratio * Number(PRECISE_NUMBER_DENOM)))
+              const rightScaledNum = PRECISE_NUMBER_DENOM - scaledNum
+              return [
+                fastMulRatioRaw(principalShare.lpShare, scaledNum, PRECISE_NUMBER_DENOM),
+                fastMulRatioRaw(principalShare.lpShare, rightScaledNum, PRECISE_NUMBER_DENOM),
+              ]
+            })()
+
+      const newEmissions: ShareTracker["emissions"] = principalShare.emissions.map((tracker) => ({
+        staged: 0n,
+        lastSeenIndex: tracker.lastSeenIndex,
+      }))
+
+      principalShare.lpShare = leftShare
+      principalShare.rightTickIdx = splitedIndex
+
+      stack.push({
+        tickIdx: splitedIndex,
+        rightTickIdx: rightIndex,
+        splitEpoch: principalShare.splitEpoch,
+        lpShare: migratedShare,
+        emissions: newEmissions,
+      })
+
+      principalShare.splitEpoch += 1n
+      stack.push(principalShare)
+      continue
     }
 
     // Add the processed share to the result
@@ -138,14 +204,7 @@ function updateLpPositionShares(
   // Iterate through each share and update
   for (const share of recomputedShares) {
     const myShares = share.lpShare
-
-    // Find the tick node in the ticks tree
-    const tickNode = ticks.ticksTree.at(share.tickIdx - 1) ?? null
-
-    if (!tickNode) {
-      //? Tick node not found for provided tickIdx
-      continue
-    }
+    const tickNode = getTickByIndex(ticks, share.tickIdx)
 
     // Update tick emissions with market emission indices
     // In Rust: node_mut.value.update_tick_emissions(market_emission_indices)
@@ -202,28 +261,28 @@ function calculatePtSyRemoval(
 ): { totalPtOut: bigint; totalSyOut: bigint } {
   let totalPtOut = 0n
   let totalSyOut = 0n
+  const isFullRemoval = liquidityToRemove === position.lpBalance
+
+  if (liquidityToRemove <= 0n || liquidityToRemove > position.lpBalance) {
+    throw invariantError("invalid liquidity amount")
+  }
 
   for (const share of position.shareTrackers) {
     const myShares = share.lpShare
-    const tickNode = ticks.ticksTree.at(share.tickIdx - 1) ?? null
-
-    if (!tickNode) {
-      continue
-    }
+    const tickNode = getTickByIndex(ticks, share.tickIdx)
 
     const supply = tickNode.principalShareSupply
 
-    // Calculate burn shares: r = l_remove / pos.L
-    // burn_shares = my_shares * liquidity_to_remove / position.lp_balance
-    const burnShares = (myShares * liquidityToRemove) / position.lpBalance
+    const burnShares = isFullRemoval
+      ? myShares
+      : mulNumberRaw(myShares, numberFromRatioRaw(liquidityToRemove, position.lpBalance))
 
-    // Calculate PT output for this tick
-    // pt_out = principal_pt * burn_shares / supply
-    const ptOut = supply > 0n ? (tickNode.principalPt * burnShares) / supply : 0n
+    if (burnShares > supply) {
+      throw invariantError("withdraw burn shares exceed tick supply")
+    }
 
-    // Calculate SY output for this tick
-    // sy_out = principal_sy * burn_shares / supply
-    const syOut = supply > 0n ? (tickNode.principalSy * burnShares) / supply : 0n
+    const ptOut = principalOutForBurn(tickNode.principalPt, burnShares, supply)
+    const syOut = principalOutForBurn(tickNode.principalSy, burnShares, supply)
 
     totalPtOut += ptOut
     totalSyOut += syOut