@exponent-labs/market-three-math 0.9.13 → 0.9.15

package/src/existingPositionEqualization.ts

@@ -0,0 +1,367 @@
+import type { LpPositionCLMM, Tick, Ticks } from "@exponent-labs/exponent-fetcher"
+
+const SENTINEL_TICK_INDEX = 0xffffffff
+const PRECISE_NUMBER_DENOM = 1_000_000_000_000n
+const U64_MAX = (1n << 64n) - 1n
+const U128_MAX = (1n << 128n) - 1n
+
+export type CrossingEqualizationDirection = "add" | "remove"
+
+export type CrossingEqualizationPlanStep = {
+  shareIndex: number
+  tickIdx: number
+  direction: CrossingEqualizationDirection
+  shareDeltaRaw: bigint
+  ptDelta: bigint
+  syDelta: bigint
+}
+
+export type ExistingPositionEqualization = {
+  sySpent: bigint
+  ptSpent: bigint
+  syReleased: bigint
+  ptReleased: bigint
+  plan: CrossingEqualizationPlanStep[]
+}
+
+export type ExistingPositionBudgetEffect = {
+  userMaxSy: bigint
+  userMaxPt: bigint
+  effectiveMaxSy: bigint
+  effectiveMaxPt: bigint
+  fixedSySpent: bigint
+  fixedPtSpent: bigint
+  fixedSyReleased: bigint
+  fixedPtReleased: bigint
+}
+
+const invariantError = (message: string) => new Error(`CrossingEqualizationInvariantViolated: ${message}`)
+
+const assertU64 = (value: bigint, label: string): bigint => {
+  if (value < 0n || value > U64_MAX) {
+    throw invariantError(`${label} does not fit in u64: ${value.toString()}`)
+  }
+  return value
+}
+
+const assertU128 = (value: bigint, label: string): bigint => {
+  if (value < 0n || value > U128_MAX) {
+    throw invariantError(`${label} does not fit in u128: ${value.toString()}`)
+  }
+  return value
+}
+
+const checkedAddU64 = (left: bigint, right: bigint, label: string) => assertU64(left + right, label)
+
+const checkedSubU64 = (left: bigint, right: bigint, label: string) => {
+  if (right > left) {
+    throw invariantError(`${label} underflow: ${left.toString()} - ${right.toString()}`)
+  }
+  return left - right
+}
+
+const checkedMulU128 = (left: bigint, right: bigint, label: string) => assertU128(left * right, label)
+
+const ceilMulDivU128 = (left: bigint, right: bigint, denominator: bigint, label: string) => {
+  if (denominator <= 0n) {
+    throw invariantError(`${label} division by zero`)
+  }
+
+  const product = checkedMulU128(left, right, `${label} product`)
+  return assertU128(product + denominator - 1n, `${label} ceil numerator`) / denominator
+}
+
+const fastFloorU128 = (rawPreciseNumber: bigint) =>
+  assertU128(rawPreciseNumber, "precise number raw") / PRECISE_NUMBER_DENOM
+
+const fastMulRatioRaw = (rawPreciseNumber: bigint, numerator: bigint, denominator: bigint, label: string) => {
+  if (denominator <= 0n) {
+    throw invariantError(`${label} division by zero`)
+  }
+
+  const raw = assertU128(rawPreciseNumber, `${label} raw precise number`)
+  const product = checkedMulU128(raw, numerator, `${label} product`)
+  return product / denominator
+}
+
+const getTickByIndex = (ticks: Ticks, tickIdx: number): Tick => {
+  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 isCrossingSplitActive = (position: LpPositionCLMM) =>
+  position.crossingSplit.crossLeftIdx !== SENTINEL_TICK_INDEX &&
+  position.crossingSplit.crossRightIdx !== SENTINEL_TICK_INDEX
+
+const shareIsWithinCrossingRange = (
+  ticks: Ticks,
+  position: LpPositionCLMM,
+  share: LpPositionCLMM["shareTrackers"][number],
+): boolean => {
+  const shareLeftKey = getTickKey(ticks, share.tickIdx)
+  let shareRightIdx: number | null = share.rightTickIdx
+  if (share.rightTickIdx === SENTINEL_TICK_INDEX) {
+    shareRightIdx = successorIdx(ticks, share.tickIdx)
+  }
+
+  if (shareRightIdx == null) {
+    return false
+  }
+
+  const shareRightKey = getTickKey(ticks, shareRightIdx)
+  const crossLeftKey = getTickKey(ticks, position.crossingSplit.crossLeftIdx)
+  const crossRightKey = getTickKey(ticks, position.crossingSplit.crossRightIdx)
+
+  return shareLeftKey >= crossLeftKey && shareRightKey <= crossRightKey
+}
+
+const computeAddDeltas = (params: {
+  ownedPt: bigint
+  ownedSy: bigint
+  liquidityDelta: bigint
+  lActual: bigint
+}): [bigint, bigint] => {
+  const ptDelta =
+    params.ownedPt > 0n
+      ? assertU64(
+          ceilMulDivU128(params.ownedPt, params.liquidityDelta, params.lActual, "PT equalization in"),
+          "PT equalization in",
+        )
+      : 0n
+  const syDelta =
+    params.ownedSy > 0n
+      ? assertU64(
+          ceilMulDivU128(params.ownedSy, params.liquidityDelta, params.lActual, "SY equalization in"),
+          "SY equalization in",
+        )
+      : 0n
+
+  return [ptDelta, syDelta]
+}
+
+const computeRemoveDeltas = (params: { shareDeltaRaw: bigint; node: Tick; supply: bigint }): [bigint, bigint] => {
+  const burnShares = fastFloorU128(params.shareDeltaRaw)
+  const ptDelta = assertU64(
+    checkedMulU128(burnShares, params.node.principalPt, "PT equalization out product") / params.supply,
+    "PT equalization out",
+  )
+  const syDelta = assertU64(
+    checkedMulU128(burnShares, params.node.principalSy, "SY equalization out product") / params.supply,
+    "SY equalization out",
+  )
+
+  return [ptDelta, syDelta]
+}
+
+const summarizePlan = (plan: CrossingEqualizationPlanStep[]): ExistingPositionEqualization => {
+  let sySpent = 0n
+  let ptSpent = 0n
+  let syReleased = 0n
+  let ptReleased = 0n
+
+  for (const step of plan) {
+    if (step.direction === "add") {
+      sySpent = checkedAddU64(sySpent, step.syDelta, "equalization sy spent")
+      ptSpent = checkedAddU64(ptSpent, step.ptDelta, "equalization pt spent")
+      continue
+    }
+
+    syReleased = checkedAddU64(syReleased, step.syDelta, "equalization sy released")
+    ptReleased = checkedAddU64(ptReleased, step.ptDelta, "equalization pt released")
+  }
+
+  return {
+    sySpent,
+    ptSpent,
+    syReleased,
+    ptReleased,
+    plan,
+  }
+}
+
+/**
+ * Mirrors `precalc_existing_position_add_liquidity` from the CLMM program.
+ *
+ * The returned `ptSpent` and `sySpent` are the exact token budget that must be
+ * reserved before adding more liquidity to a position with an active crossing split.
+ * All PreciseNumber operations are performed on raw fixed-point `bigint` values so
+ * the rounding matches the contract's `fast_floor_u128`, `fast_mul_ratio`, and
+ * `muldiv_ceil_u128` paths.
+ */
+export function computeExistingPositionEqualization(
+  ticks: Ticks,
+  position: LpPositionCLMM,
+): ExistingPositionEqualization {
+  if (!isCrossingSplitActive(position)) {
+    return summarizePlan([])
+  }
+
+  const lActual = assertU64(position.crossingSplit.lpBalanceCrossing, "lpBalanceCrossing")
+  const lpBalance = assertU64(position.lpBalance, "lpBalance")
+
+  if (lpBalance === lActual) {
+    return summarizePlan([])
+  }
+  if (lActual === 0n) {
+    throw invariantError("active crossing split has zero actual liquidity")
+  }
+
+  const direction: CrossingEqualizationDirection = lpBalance > lActual ? "add" : "remove"
+  const liquidityDelta = lpBalance > lActual ? lpBalance - lActual : lActual - lpBalance
+  const plan: CrossingEqualizationPlanStep[] = []
+  let sawCrossingRangeShare = false
+  let skippedCrossingShareDueToDust = false
+
+  for (let shareIndex = 0; shareIndex < position.shareTrackers.length; shareIndex++) {
+    const share = position.shareTrackers[shareIndex]
+    if (!shareIsWithinCrossingRange(ticks, position, share)) {
+      continue
+    }
+
+    sawCrossingRangeShare = true
+    const node = getTickByIndex(ticks, share.tickIdx)
+    const supply = fastFloorU128(node.principalShareSupply)
+    if (supply === 0n) {
+      skippedCrossingShareDueToDust = true
+      continue
+    }
+
+    const shareFloor = fastFloorU128(share.lpShare)
+    if (shareFloor === 0n) {
+      skippedCrossingShareDueToDust = true
+      continue
+    }
+
+    const ownedPt = assertU64(checkedMulU128(shareFloor, node.principalPt, "owned PT product") / supply, "owned PT")
+    const ownedSy = assertU64(checkedMulU128(shareFloor, node.principalSy, "owned SY product") / supply, "owned SY")
+    const shareDeltaRaw = fastMulRatioRaw(share.lpShare, liquidityDelta, lActual, "share delta")
+
+    let deltas: [bigint, bigint]
+    if (direction === "add") {
+      deltas = computeAddDeltas({
+        ownedPt,
+        ownedSy,
+        liquidityDelta,
+        lActual,
+      })
+    } else {
+      deltas = computeRemoveDeltas({
+        shareDeltaRaw,
+        node,
+        supply,
+      })
+    }
+    const [ptDelta, syDelta] = deltas
+
+    if (shareDeltaRaw === 0n && ptDelta === 0n && syDelta === 0n) {
+      skippedCrossingShareDueToDust = true
+      continue
+    }
+
+    plan.push({
+      shareIndex,
+      tickIdx: share.tickIdx,
+      direction,
+      shareDeltaRaw,
+      ptDelta,
+      syDelta,
+    })
+  }
+
+  if (plan.length === 0 && sawCrossingRangeShare && skippedCrossingShareDueToDust) {
+    return summarizePlan([])
+  }
+  if (plan.length === 0) {
+    throw invariantError("active crossing split has no equalizable crossing-range shares")
+  }
+
+  return summarizePlan(plan)
+}
+
+/**
+ * Mirrors the contract's `compute_existing_position_budget_effect`.
+ *
+ * It throws the same invariant class when the supplied user budgets cannot cover
+ * the fixed equalization spend, for example `userMaxPt=0` while `ptSpent>0`.
+ */
+export function computeExistingPositionBudgetEffect(params: {
+  ticks: Ticks
+  position: LpPositionCLMM
+  userMaxSy: bigint
+  userMaxPt: bigint
+}): ExistingPositionBudgetEffect {
+  const equalization = computeExistingPositionEqualization(params.ticks, params.position)
+  const effectiveMaxSy = checkedAddU64(
+    checkedSubU64(params.userMaxSy, equalization.sySpent, "effective max SY"),
+    equalization.syReleased,
+    "effective max SY",
+  )
+  const effectiveMaxPt = checkedAddU64(
+    checkedSubU64(params.userMaxPt, equalization.ptSpent, "effective max PT"),
+    equalization.ptReleased,
+    "effective max PT",
+  )
+
+  return {
+    userMaxSy: params.userMaxSy,
+    userMaxPt: params.userMaxPt,
+    effectiveMaxSy,
+    effectiveMaxPt,
+    fixedSySpent: equalization.sySpent,
+    fixedPtSpent: equalization.ptSpent,
+    fixedSyReleased: equalization.syReleased,
+    fixedPtReleased: equalization.ptReleased,
+  }
+}
+
+/**
+ * Mirrors `required_user_max_sy/pt`: expands a desired post-equalization budget
+ * into the user-facing max token amounts that should be passed to the instruction.
+ */
+export function computeRequiredUserMaxForExistingPositionEqualization(params: {
+  ticks: Ticks
+  position: LpPositionCLMM
+  desiredEffectiveMaxSy: bigint
+  desiredEffectiveMaxPt: bigint
+}): { userMaxSy: bigint; userMaxPt: bigint; equalization: ExistingPositionEqualization } {
+  const equalization = computeExistingPositionEqualization(params.ticks, params.position)
+  const userMaxSy = checkedSubU64(
+    checkedAddU64(params.desiredEffectiveMaxSy, equalization.sySpent, "required user max SY"),
+    equalization.syReleased,
+    "required user max SY",
+  )
+  const userMaxPt = checkedSubU64(
+    checkedAddU64(params.desiredEffectiveMaxPt, equalization.ptSpent, "required user max PT"),
+    equalization.ptReleased,
+    "required user max PT",
+  )
+
+  return {
+    userMaxSy,
+    userMaxPt,
+    equalization,
+  }
+}

package/src/index.ts

@@ -56,6 +56,17 @@ export {
   simulateWrapperProvideLiquidity,
   simulateSwapAndSupply,
 } from "./addLiquidity"
+export {
+  computeExistingPositionBudgetEffect,
+  computeExistingPositionEqualization,
+  computeRequiredUserMaxForExistingPositionEqualization,
+} from "./existingPositionEqualization"
+export type {
+  CrossingEqualizationDirection,
+  CrossingEqualizationPlanStep,
+  ExistingPositionBudgetEffect,
+  ExistingPositionEqualization,
+} from "./existingPositionEqualization"
 
 export { getPtAndSyOnWithdrawLiquidity } from "./withdrawLiquidity"
 

package/src/utils.ts

@@ -219,18 +219,20 @@ export function findTickByIndex(ticks: Ticks, index: number): Tick {
   return ticks.ticksTree.at(index - 1) ?? null
 }
 
+const CLMM_TICK_KEY_SCALE = 10_000
+
 /**
- * Convert APY percentage to basis points
+ * Convert APY percentage to CLMM tick-key units.
  */
 export function convertApyToApyBp(apyPercent: number): number {
-  return Math.round(apyPercent * 100)
+  return Math.round(apyPercent * CLMM_TICK_KEY_SCALE)
 }
 
 /**
- * Convert basis points to APY percentage
+ * Convert CLMM tick-key units to APY percentage.
  */
 export function convertApyBpToApy(apyBp: number): number {
-  return apyBp / 100
+  return apyBp / CLMM_TICK_KEY_SCALE
 }
 
 export function bigIntMax(...args: bigint[]): bigint {