@exponent-labs/market-three-math 0.9.12 → 0.9.14

package/src/swapV2.ts

@@ -3,23 +3,19 @@
  * Closely mirrors the Rust on-chain implementation from swap.rs
  * Uses TicksWrapper to simulate RB-tree behavior
  */
-import {
-  MarketThreeState,
-  SwapArgs,
-  SwapDirection,
-  SwapExactOutArgs,
-  SwapOutcomeV2,
-} from "./types"
-import {
-  EffSnap,
-  TicksWrapper,
-  calculateFeeRate,
-  getFeeFromAmount,
-  normalizedTimeRemaining,
-} from "./utilsV2"
+import { MarketThreeState, SwapArgs, SwapDirection, SwapExactOutArgs, SwapOutcomeV2 } from "./types"
+import { EffSnap, TicksWrapper, calculateFeeRate, getFeeFromAmount, normalizedTimeRemaining } from "./utilsV2"
 
 const BASE_POINTS = 10000
 
+function computeFlashFeeOut(ytValue: number, grossOut: number, lpFeeRate: number): number {
+  if (grossOut === 0) {
+    return 0
+  }
+
+  return Math.min(grossOut, Math.max(1, getFeeFromAmount(ytValue, lpFeeRate)))
+}
+
 /**
  * Simulate a swap on the CLMM market (V2 - mirrors Rust closely)
  * This is a pure function that does not mutate the market state
@@ -364,7 +360,7 @@ export function simulateSwap(marketState: MarketThreeState, args: SwapArgs): Swa
         if (args.isCurrentFlashSwap) {
           const syInBase = syInSegmentU64 * args.syExchangeRate
           const ytValue = ptOutGrossU64 - syInBase
-          totalFeeOut = getFeeFromAmount(Math.max(0, Math.floor(ytValue)), lpFeeRate)
+          totalFeeOut = computeFlashFeeOut(Math.max(0, Math.floor(ytValue)), ptOutGrossU64, lpFeeRate)
         } else {
           totalFeeOut = getFeeFromAmount(ptOutGrossU64, lpFeeRate)
         }
@@ -605,6 +601,8 @@ export function simulateSwapExactOut(marketState: MarketThreeState, args: SwapEx
 
     const totalFeeOutBoundary = getFeeFromAmount(ptOutGrossBoundaryU64, lpFeeRate)
     const ptOutNetBoundary = Math.max(0, ptOutGrossBoundaryU64 - totalFeeOutBoundary)
+    let boundarySegmentSeed: ReturnType<typeof calculateSwapSegment> | null = null
+    let ptOutNetBoundaryEffectiveSeed: number | null = null
 
     if (ptOutNetBoundary === 0) {
       const boundarySegment = calculateSwapSegment(
@@ -619,87 +617,115 @@ export function simulateSwapExactOut(marketState: MarketThreeState, args: SwapEx
         args.isCurrentFlashSwap,
       )
 
-      let syInBoundary = boundarySegment.syInSegmentU64
-      if (ptOutGrossBoundaryU64 > 0 && syInBoundary === 0) {
-        syInBoundary = 1
-      }
+      const ptOutNetBoundaryActual = Math.max(0, boundarySegment.ptOutGrossActual - boundarySegment.totalFeeOut)
+      if (ptOutNetBoundaryActual > 0) {
+        boundarySegmentSeed = boundarySegment
+        ptOutNetBoundaryEffectiveSeed = ptOutNetBoundaryActual
+      } else {
+        let syInBoundary = boundarySegment.syInSegmentU64
+        if (ptOutGrossBoundaryU64 > 0 && syInBoundary === 0) {
+          syInBoundary = 1
+        }
 
-      if (
-        amountInConstraint !== undefined &&
-        amountInConsumed + syInBoundary > amountInConstraint
-      ) {
-        throw new Error("Insufficient SY budget for exact-out trade")
-      }
+        if (amountInConstraint !== undefined && amountInConsumed + syInBoundary > amountInConstraint) {
+          throw new Error("Insufficient SY budget for exact-out trade")
+        }
 
-      amountInConsumed += syInBoundary
+        amountInConsumed += syInBoundary
 
-      if (boundarySegment.totalFeeOut > 0) {
-        const protocolFeeOut = Math.floor((boundarySegment.totalFeeOut * protocolFeeBps) / BASE_POINTS)
-        const lpFeeOut = boundarySegment.totalFeeOut - protocolFeeOut
-        feeLpOutU64 += lpFeeOut
-        feeProtocolOutU64 += protocolFeeOut
-      }
+        if (boundarySegment.totalFeeOut > 0) {
+          const protocolFeeOut = Math.floor((boundarySegment.totalFeeOut * protocolFeeBps) / BASE_POINTS)
+          const lpFeeOut = boundarySegment.totalFeeOut - protocolFeeOut
+          feeLpOutU64 += lpFeeOut
+          feeProtocolOutU64 += protocolFeeOut
+        }
 
-      if (syInBoundary > 0 || boundarySegment.ptOutGrossActual > 0) {
-        ticksWrapper.setPrincipals(
+        if (syInBoundary > 0 || boundarySegment.ptOutGrossActual > 0) {
+          ticksWrapper.setPrincipals(
+            currentLeftBoundaryKey,
+            principalPt - BigInt(boundarySegment.ptOutGrossActual),
+            principalSy + BigInt(syInBoundary),
+          )
+        }
+
+        currentPriceSpot = boundarySegment.spotPriceNew
+
+        const crossed = crossOneBoundary(ticksWrapper, SwapDirection.SyToPt, currentLeftBoundaryKey, {
           currentLeftBoundaryKey,
-          principalPt - BigInt(boundarySegment.ptOutGrossActual),
-          principalSy + BigInt(syInBoundary),
-        )
+          currentPriceSpot,
+          activeLiquidityU64,
+          activeLiquidityF64,
+        })
+        if (!crossed) break
+        currentLeftBoundaryKey = crossed.currentLeftBoundaryKey
+        currentPriceSpot = crossed.currentPriceSpot
+        activeLiquidityU64 = crossed.activeLiquidityU64
+        activeLiquidityF64 = crossed.activeLiquidityF64
+        continue
       }
+    }
 
-      currentPriceSpot = boundarySegment.spotPriceNew
-
-      const crossed = crossOneBoundary(ticksWrapper, SwapDirection.SyToPt, currentLeftBoundaryKey, {
-        currentLeftBoundaryKey,
-        currentPriceSpot,
-        activeLiquidityU64,
-        activeLiquidityF64,
-      })
-      if (!crossed) break
-      currentLeftBoundaryKey = crossed.currentLeftBoundaryKey
-      currentPriceSpot = crossed.currentPriceSpot
-      activeLiquidityU64 = crossed.activeLiquidityU64
-      activeLiquidityF64 = crossed.activeLiquidityF64
-      continue
+    let ptOutNetBoundaryEffective = ptOutNetBoundaryEffectiveSeed ?? ptOutNetBoundary
+    let precomputedBoundarySegment: ReturnType<typeof calculateSwapSegment> | null = null
+    if (amountOutLeft >= ptOutNetBoundary) {
+      const boundarySegment =
+        boundarySegmentSeed ??
+        calculateSwapSegment(
+          ptOutGrossBoundaryU64,
+          lTradeF64,
+          currentPriceSpot,
+          duToLeft,
+          anchorULeft,
+          snapshot,
+          cEffOld,
+          lpFeeRate,
+          args.isCurrentFlashSwap,
+        )
+      const ptOutNetBoundaryActual =
+        ptOutNetBoundaryEffectiveSeed ?? Math.max(0, boundarySegment.ptOutGrossActual - boundarySegment.totalFeeOut)
+      ptOutNetBoundaryEffective = ptOutNetBoundaryActual
+      if (ptOutNetBoundaryActual > 0 && amountOutLeft >= ptOutNetBoundaryActual) {
+        precomputedBoundarySegment = boundarySegment
+      }
     }
 
-    const targetNet = Math.min(amountOutLeft, ptOutNetBoundary)
-    const grossCandidate = findGrossForTargetNet(targetNet, 0, ptOutGrossBoundaryU64, (gross) =>
-      calculateNetPtOut(
-        gross,
+    const targetNet = Math.min(amountOutLeft, ptOutNetBoundaryEffective)
+    const grossCandidate = precomputedBoundarySegment
+      ? ptOutGrossBoundaryU64
+      : findGrossForTargetNet(targetNet, Math.min(targetNet, ptOutGrossBoundaryU64), ptOutGrossBoundaryU64, (gross) =>
+          calculateNetPtOut(
+            gross,
+            lTradeF64,
+            currentPriceSpot,
+            duToLeft,
+            anchorULeft,
+            lpFeeRate,
+            args.isCurrentFlashSwap,
+            snapshot,
+            cEffOld,
+          ),
+        )
+
+    const segment =
+      precomputedBoundarySegment ??
+      calculateSwapSegment(
+        grossCandidate,
         lTradeF64,
         currentPriceSpot,
         duToLeft,
         anchorULeft,
-        lpFeeRate,
-        args.isCurrentFlashSwap,
         snapshot,
         cEffOld,
-      ),
-    )
-
-    const segment = calculateSwapSegment(
-      grossCandidate,
-      lTradeF64,
-      currentPriceSpot,
-      duToLeft,
-      anchorULeft,
-      snapshot,
-      cEffOld,
-      lpFeeRate,
-      args.isCurrentFlashSwap,
-    )
+        lpFeeRate,
+        args.isCurrentFlashSwap,
+      )
 
     let syInSegmentU64 = segment.syInSegmentU64
     if (grossCandidate > 0 && syInSegmentU64 === 0) {
       syInSegmentU64 = 1
     }
 
-    if (
-      amountInConstraint !== undefined &&
-      amountInConsumed + syInSegmentU64 > amountInConstraint
-    ) {
+    if (amountInConstraint !== undefined && amountInConsumed + syInSegmentU64 > amountInConstraint) {
       throw new Error("Insufficient SY budget for exact-out trade")
     }
 
@@ -781,27 +807,11 @@ function computeKappaAndLTrade(
   let kappaPt: number
 
   if (direction === SwapDirection.SyToPt) {
-    kappaPt = isSyOnlyRange
-      ? 0
-      : ptMaxToLeftF > 0
-        ? principalPtInInterval / ptMaxToLeftF
-        : Infinity
-    kappaSy = isPtOnlyRange
-      ? 1
-      : yMaxToBoundaryF > 0
-        ? principalSyInInterval / yMaxToBoundaryF
-        : Infinity
+    kappaPt = isSyOnlyRange ? 0 : ptMaxToLeftF > 0 ? principalPtInInterval / ptMaxToLeftF : Infinity
+    kappaSy = isPtOnlyRange ? 1 : yMaxToBoundaryF > 0 ? principalSyInInterval / yMaxToBoundaryF : Infinity
   } else {
-    kappaSy = isPtOnlyRange
-      ? 0
-      : yMaxToBoundaryF > 0
-        ? principalSyInInterval / yMaxToBoundaryF
-        : Infinity
-    kappaPt = isSyOnlyRange
-      ? 1
-      : ptMaxToLeftF > 0
-        ? principalPtInInterval / ptMaxToLeftF
-        : Infinity
+    kappaSy = isPtOnlyRange ? 0 : yMaxToBoundaryF > 0 ? principalSyInInterval / yMaxToBoundaryF : Infinity
+    kappaPt = isSyOnlyRange ? 1 : ptMaxToLeftF > 0 ? principalPtInInterval / ptMaxToLeftF : Infinity
   }
 
   const kappa = Math.min(kappaPt, kappaSy, 1)
@@ -823,16 +833,94 @@ function findGrossForTargetNet(
   maxGross: number,
   calculateNet: (gross: number) => number,
 ): number {
+  const MAX_INTERPOLATION_STEPS = 6
+  const MAX_LOCAL_ADJUST_STEPS = 24
+  const MAX_BINARY_FALLBACK_STEPS = 12
+
   if (minGross >= maxGross) {
     return minGross
   }
 
   let left = minGross
+  let leftNet = calculateNet(left)
+  if (leftNet >= targetNet) {
+    return left
+  }
+
   let right = maxGross
-  let bestGross = minGross
+  let rightNet = calculateNet(right)
+  if (rightNet <= targetNet) {
+    return right
+  }
+
+  for (let i = 0; i < MAX_INTERPOLATION_STEPS; i++) {
+    if (right <= left + 1) {
+      return left
+    }
+    if (rightNet <= leftNet) {
+      break
+    }
+
+    const span = right - left
+    const targetDelta = Math.max(0, targetNet - leftNet)
+    const denominator = rightNet - leftNet
+    if (denominator === 0) {
+      break
+    }
+
+    const estimatedOffset = Number((BigInt(targetDelta) * BigInt(span)) / BigInt(denominator))
+    let estimate = left + estimatedOffset
+    if (estimate <= left) {
+      estimate = left + 1
+    }
+    if (estimate >= right) {
+      estimate = right - 1
+    }
+
+    const estimateNet = calculateNet(estimate)
+    if (estimateNet === targetNet) {
+      return estimate
+    }
+    if (estimateNet < targetNet) {
+      left = estimate
+      leftNet = estimateNet
+    } else {
+      right = estimate
+      rightNet = estimateNet
+    }
+  }
+
+  let best = left
+  for (let i = 0; i < MAX_LOCAL_ADJUST_STEPS; i++) {
+    if (best >= right) {
+      break
+    }
+    const next = best + 1
+    if (next > right) {
+      break
+    }
+    const nextNet = calculateNet(next)
+    if (nextNet > targetNet) {
+      break
+    }
+    best = next
+    if (nextNet === targetNet) {
+      return best
+    }
+  }
+
+  if (right <= best + 1) {
+    return best
+  }
+
+  let low = best
+  let high = right
+  let bestGross = best
+  let steps = 0
 
-  while (left <= right) {
-    const mid = left + Math.floor((right - left) / 2)
+  while (low <= high && steps < MAX_BINARY_FALLBACK_STEPS) {
+    steps += 1
+    const mid = low + Math.floor((high - low) / 2)
     const net = calculateNet(mid)
 
     if (net === targetNet) {
@@ -841,12 +929,12 @@ function findGrossForTargetNet(
 
     if (net < targetNet) {
       bestGross = mid
-      left = mid + 1
+      low = mid + 1
     } else {
       if (mid === 0) {
         break
       }
-      right = mid - 1
+      high = mid - 1
     }
   }
 
@@ -871,10 +959,7 @@ function calculateNetPtOut(
     spotPriceNew = anchorULeft
   }
 
-  const ptOutGrossActual = Math.max(
-    0,
-    Math.floor(lTradeF64 * (currentPriceSpot - spotPriceNew)),
-  )
+  const ptOutGrossActual = Math.max(0, Math.floor(lTradeF64 * (currentPriceSpot - spotPriceNew)))
 
   const totalFeeOut = isCurrentFlashSwap
     ? (() => {
@@ -882,7 +967,7 @@ function calculateNetPtOut(
         const syInSegmentF = lTradeF64 * (cEffNew - cEffOld)
         const syInBase = Math.ceil(syInSegmentF) * snapshot.syExchangeRate
         const ytValue = ptOutGrossActual - syInBase
-        return getFeeFromAmount(Math.max(0, Math.floor(ytValue)), lpFeeRate)
+        return computeFlashFeeOut(Math.max(0, Math.floor(ytValue)), ptOutGrossActual, lpFeeRate)
       })()
     : getFeeFromAmount(ptOutGrossActual, lpFeeRate)
 
@@ -915,15 +1000,12 @@ function calculateSwapSegment(
   const cEffNew = snapshot.getEffectivePrice(spotPriceNew)
   const syInSegmentF = lTradeF64 * (cEffNew - cEffOld)
   const syInSegmentU64 = Math.max(0, Math.ceil(syInSegmentF))
-  const ptOutGrossActual = Math.max(
-    0,
-    Math.floor(lTradeF64 * (currentPriceSpot - spotPriceNew)),
-  )
+  const ptOutGrossActual = Math.max(0, Math.floor(lTradeF64 * (currentPriceSpot - spotPriceNew)))
 
   const normalFee = getFeeFromAmount(ptOutGrossActual, lpFeeRate)
   const syInBase = Math.ceil(syInSegmentF) * snapshot.syExchangeRate
   const ytValue = ptOutGrossActual - syInBase
-  const flashFee = getFeeFromAmount(Math.max(0, Math.floor(ytValue)), lpFeeRate)
+  const flashFee = computeFlashFeeOut(Math.max(0, Math.floor(ytValue)), ptOutGrossActual, lpFeeRate)
   const totalFeeOut = isCurrentFlashSwap ? flashFee : normalFee
 
   return {

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 {