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

package/src/bisect.ts

@@ -1,3 +1,14 @@
+/**
+ * Binary search (bisection method) to find root of a monotonic function.
+ * Finds x where f(x) = 0 within the range [lo, hi].
+ *
+ * @param func - Monotonic function to find root of
+ * @param lo - Lower bound of search range
+ * @param hi - Upper bound of search range
+ * @param epsilon - Convergence tolerance (default 0.0001)
+ * @param maxIterations - Maximum iterations (default 2000)
+ * @returns The x value where f(x) ≈ 0, or null if root is not bracketed
+ */
 export function bisectSearch2(
   func: (x: number) => number,
   lo: number,
@@ -9,13 +20,12 @@ export function bisectSearch2(
     throw new Error("lo must be less than hi")
   }
 
-  let iterations = 0
-
   // Evaluate boundaries once
-  const fLo = func(lo)
-  const fHi = func(hi)
+  let fLo = func(lo)
+  let fHi = func(hi)
 
   // Check if the target is bracketed between lo and hi
+  // Root exists only if f(lo) and f(hi) have opposite signs
   if (fLo * fHi > 0) {
     return null
   }
@@ -28,6 +38,8 @@ export function bisectSearch2(
   let bestMid = (lo + hi) / 2
   let bestError = Infinity
 
+  let iterations = 0
+
   // Binary search within the range
   while (iterations < maxIterations) {
     // Use midpoint for standard bisection
@@ -48,22 +60,21 @@ export function bisectSearch2(
       return mid
     }
 
-    // Early termination if range is too small relative to epsilon
+    // Early termination if range is too small
     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)
+    // Adjust the search range based on signs
+    // If f(lo) and f(mid) have opposite signs, root is in [lo, mid]
+    // Otherwise, root is in [mid, hi]
     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
+      fHi = fMid
     } else {
-      // eslint-disable-next-line no-param-reassign
       lo = mid
-      // Note: fLo would be fMid, but we recalculate in the condition anyway
+      fLo = fMid
     }
   }
 

package/src/index.ts

@@ -15,10 +15,7 @@ export * from "./types"
 
 // Export utility functions
 export {
-  EffSnap,
   normalizedTimeRemaining,
-  calculateFeeRate,
-  getFeeFromAmount,
   getActiveLiquidity,
   getSuccessorTickKey,
   getPredecessorTickKey,
@@ -27,13 +24,16 @@ export {
   convertApyToApyBp,
   convertApyBpToApy,
   calcPtPriceInAsset,
-  getSuccessorTickByIdx,
+  getSuccessorTickIdxByIdx,
 } from "./utils"
 
 // Export swap functions
-export { simulateSwap } from "./swap"
+export { simulateSwap } from "./swapV2"
 export { getSwapQuote, QuoteDirection } from "./quote"
 
+// Export V2 utilities
+export { EffSnap, TicksWrapper, calculateFeeRate, getFeeFromAmount } from "./utilsV2"
+
 // Export YT trade functions
 export { simulateBuyYt, simulateSellYt, simulateBuyYtWithSyIn } from "./ytTrades"
 export type {
@@ -47,10 +47,14 @@ export type {
 export {
   simulateAddLiquidity,
   computeLiquidityTargetAndTokenNeeds,
+  computeTokenNeedsWithCrossing,
+  getCrossingTickStateFromTicks,
+  scaleCrossingTickInputs,
   calculateLpOut,
   estimateBalancedDeposit,
   calcDepositSyAndPtFromBaseAmount,
   simulateWrapperProvideLiquidity,
+  simulateSwapAndSupply,
 } from "./addLiquidity"
 
 export { getPtAndSyOnWithdrawLiquidity } from "./withdrawLiquidity"
@@ -69,6 +73,8 @@ export type {
   AddLiquidityArgs,
   AddLiquidityOutcome,
   LiquidityNeeds,
+  CrossingTickState,
+  CrossingScaleParams,
   MarketThreeState,
 } from "./types"
 export { SwapDirection } from "./types"

package/src/liquidityHistogram.ts

@@ -25,6 +25,10 @@ export interface LiquidityHistogramBin {
  * from remove_liquidity.rs, where liquidity is distributed proportionally based on
  * the spot price ranges.
  *
+ * When currentTickBp is provided, PT is only assigned to bins below current price
+ * and SY is only assigned to bins above current price. This ensures the visual
+ * representation correctly shows the boundary between PT and SY zones.
+ *
  * Example:
  * - Created ticks at: 1%, 5%, 6%
  * - tickSpace: 1% (100 basis points)
@@ -39,9 +43,10 @@ export interface LiquidityHistogramBin {
  *
  * @param ticks - The market's ticks state
  * @param tickSpace - The tick spacing in basis points (e.g., 100 for 1%)
+ * @param currentTickBp - Optional current tick in basis points for proper PT/SY zone splitting
  * @returns Array of histogram bins aligned to tickSpace
  */
-export function buildLiquidityHistogram(ticks: Ticks, tickSpace: number): LiquidityHistogramBin[] {
+export function buildLiquidityHistogram(ticks: Ticks, tickSpace: number, currentTickBp?: number): LiquidityHistogramBin[] {
   const histogram: LiquidityHistogramBin[] = []
 
   // Edge case: no ticks created yet
@@ -49,8 +54,15 @@ export function buildLiquidityHistogram(ticks: Ticks, tickSpace: number): Liquid
     return histogram
   }
 
-  // Find min and max tick keys (apyBasePoints)
-  const tickKeys = ticks.ticksTree.map((t) => t.apyBasePoints).sort((a, b) => a - b)
+  // Only consider ticks with actual liquidity when determining range
+  const ticksWithLiquidity = ticks.ticksTree.filter(t => t.principalPt > 0 || t.principalSy > 0)
+  
+  if (ticksWithLiquidity.length === 0) {
+    return histogram
+  }
+
+  // Find min and max tick keys (apyBasePoints) from ticks with liquidity
+  const tickKeys = ticksWithLiquidity.map((t) => t.apyBasePoints).sort((a, b) => a - b)
   const minTickKey = tickKeys[0]
   const maxTickKey = tickKeys[tickKeys.length - 1]
 
@@ -102,8 +114,19 @@ export function buildLiquidityHistogram(ticks: Ticks, tickSpace: number): Liquid
             const containingBinKey = Math.floor(intervalStartKey / tickSpace) * tickSpace
             const bin = binMap.get(containingBinKey)
             if (bin) {
-              bin.principalPt += Number(intervalPrincipalPt)
-              bin.principalSy += Number(intervalPrincipalSy)
+              // If currentTickBp is provided, only assign PT to bins below current price
+              // and SY to bins above current price
+              if (currentTickBp !== undefined) {
+                if (containingBinKey < currentTickBp) {
+                  bin.principalPt += Number(intervalPrincipalPt)
+                }
+                if (containingBinKey >= currentTickBp) {
+                  bin.principalSy += Number(intervalPrincipalSy)
+                }
+              } else {
+                bin.principalPt += Number(intervalPrincipalPt)
+                bin.principalSy += Number(intervalPrincipalSy)
+              }
             }
           } else {
             // Distribute proportionally across bins
@@ -119,8 +142,19 @@ export function buildLiquidityHistogram(ticks: Ticks, tickSpace: number): Liquid
               // Proportional share of liquidity for this bin
               const share = binRange / fullRange
 
-              bin.principalPt += Math.floor(Number(intervalPrincipalPt) * share)
-              bin.principalSy += Math.floor(Number(intervalPrincipalSy) * share)
+              // If currentTickBp is provided, only assign PT to bins below current price
+              // and SY to bins above current price
+              if (currentTickBp !== undefined) {
+                if (binKey < currentTickBp) {
+                  bin.principalPt += Math.floor(Number(intervalPrincipalPt) * share)
+                }
+                if (binKey >= currentTickBp) {
+                  bin.principalSy += Math.floor(Number(intervalPrincipalSy) * share)
+                }
+              } else {
+                bin.principalPt += Math.floor(Number(intervalPrincipalPt) * share)
+                bin.principalSy += Math.floor(Number(intervalPrincipalSy) * share)
+              }
             }
           }
         } else {
@@ -128,8 +162,19 @@ export function buildLiquidityHistogram(ticks: Ticks, tickSpace: number): Liquid
           const containingBinKey = Math.floor(currentTickKey / tickSpace) * tickSpace
           const bin = binMap.get(containingBinKey)
           if (bin) {
-            bin.principalPt += Number(intervalPrincipalPt)
-            bin.principalSy += Number(intervalPrincipalSy)
+            // If currentTickBp is provided, only assign PT to bins below current price
+            // and SY to bins above current price
+            if (currentTickBp !== undefined) {
+              if (containingBinKey < currentTickBp) {
+                bin.principalPt += Number(intervalPrincipalPt)
+              }
+              if (containingBinKey >= currentTickBp) {
+                bin.principalSy += Number(intervalPrincipalSy)
+              }
+            } else {
+              bin.principalPt += Number(intervalPrincipalPt)
+              bin.principalSy += Number(intervalPrincipalSy)
+            }
           }
         }
       }

package/src/quote.ts

@@ -1,7 +1,5 @@
-import { Tick, Ticks } from "@exponent-labs/exponent-fetcher"
-
-import { simulateSwap } from "./swap"
-import { MarketThreeState, SwapDirection, SwapOutcome } from "./types"
+import { simulateSwap } from "./swapV2"
+import { MarketThreeState, SwapDirection } from "./types"
 import { simulateBuyYtWithSyIn, simulateSellYt } from "./ytTrades"
 
 export enum QuoteDirection {
@@ -20,109 +18,89 @@ export type Quote = {
 
 /**
  * Calculate the expected output for a given input amount
- * This is a convenience wrapper around simulateSwap
+ * This is a convenience wrapper around simulateSwapV2
  */
 export function getSwapQuote(marketState: MarketThreeState, amountIn: number, direction: QuoteDirection): Quote {
-  //? Calculate correct currentTick index
-  //TODO Remove this logic when contract is updated!!!
-  const currentTickIndex = calculateCurrentTickIndex(marketState.ticks)
-
-  const marketStateMutated: MarketThreeState = {
-    ...marketState,
-    ticks: {
-      ...marketState.ticks,
-      currentTick: currentTickIndex,
-    },
-  }
-
-  if (direction === QuoteDirection.PtToSy) {
-    const { amountInConsumed, amountOut, lpFeeChargedOutToken, protocolFeeChargedOutToken } = simulateSwap(
-      marketStateMutated,
-      {
-        direction: SwapDirection.PtToSy,
-        amountIn,
-        syExchangeRate: marketStateMutated.currentSyExchangeRate,
-        isCurrentFlashSwap: false,
-      },
-    )
-    return {
-      amountIn: amountInConsumed,
-      amountOut: amountOut,
-      lpFee: lpFeeChargedOutToken,
-      protocolFee: protocolFeeChargedOutToken,
-    }
-  }
-  if (direction === QuoteDirection.SyToPt) {
-    const { amountInConsumed, amountOut, lpFeeChargedOutToken, protocolFeeChargedOutToken } = simulateSwap(
-      marketStateMutated,
-      {
-        direction: SwapDirection.SyToPt,
-        amountIn,
-        syExchangeRate: marketStateMutated.currentSyExchangeRate,
-        isCurrentFlashSwap: false,
+  try {
+    const marketStateMutated: MarketThreeState = {
+      ...marketState,
+      ticks: {
+        ...marketState.ticks,
+        currentTick: marketState.ticks.currentTick,
       },
-    )
-    return {
-      amountIn: amountInConsumed,
-      amountOut: amountOut,
-      lpFee: lpFeeChargedOutToken,
-      protocolFee: protocolFeeChargedOutToken,
     }
-  }
-
-  if (direction === QuoteDirection.YtToSy) {
-    const { ytIn, netSyReceived, lpFee, protocolFee } = simulateSellYt(marketStateMutated, {
-      ytIn: amountIn,
-      syExchangeRate: marketStateMutated.currentSyExchangeRate,
-    })
 
-    return {
-      amountIn: ytIn,
-      amountOut: netSyReceived,
-      lpFee: lpFee,
-      protocolFee: protocolFee,
+    if (direction === QuoteDirection.PtToSy) {
+      const { amountInConsumed, amountOut, lpFeeChargedOutToken, protocolFeeChargedOutToken } = simulateSwap(
+        marketStateMutated,
+        {
+          direction: SwapDirection.PtToSy,
+          amountIn,
+          syExchangeRate: marketStateMutated.currentSyExchangeRate,
+          isCurrentFlashSwap: false,
+        },
+      )
+      return {
+        amountIn: amountInConsumed,
+        amountOut: amountOut,
+        lpFee: lpFeeChargedOutToken,
+        protocolFee: protocolFeeChargedOutToken,
+      }
+    }
+    if (direction === QuoteDirection.SyToPt) {
+      const { amountInConsumed, amountOut, lpFeeChargedOutToken, protocolFeeChargedOutToken } = simulateSwap(
+        marketStateMutated,
+        {
+          direction: SwapDirection.SyToPt,
+          amountIn,
+          syExchangeRate: marketStateMutated.currentSyExchangeRate,
+          isCurrentFlashSwap: false,
+        },
+      )
+      return {
+        amountIn: amountInConsumed,
+        amountOut: amountOut,
+        lpFee: lpFeeChargedOutToken,
+        protocolFee: protocolFeeChargedOutToken,
+      }
     }
-  }
 
-  if (direction === QuoteDirection.SyToYt) {
-    const { ytOut, netSyCost, lpFee, protocolFee } = simulateBuyYtWithSyIn(marketStateMutated, {
-      syIn: amountIn,
-      syExchangeRate: marketStateMutated.currentSyExchangeRate,
-    })
+    if (direction === QuoteDirection.YtToSy) {
+      const { ytIn, netSyReceived, lpFee, protocolFee } = simulateSellYt(marketStateMutated, {
+        ytIn: amountIn,
+        syExchangeRate: marketStateMutated.currentSyExchangeRate,
+      })
 
-    return {
-      amountIn: netSyCost,
-      amountOut: ytOut,
-      lpFee: lpFee,
-      protocolFee,
+      return {
+        amountIn: ytIn,
+        amountOut: netSyReceived,
+        lpFee: lpFee,
+        protocolFee: protocolFee,
+      }
     }
-  }
 
-  throw new Error(`Unknown quote direction: ${direction}`)
-}
+    if (direction === QuoteDirection.SyToYt) {
+      const { ytOut, netSyCost, lpFee, protocolFee } = simulateBuyYtWithSyIn(marketStateMutated, {
+        syIn: amountIn,
+        syExchangeRate: marketStateMutated.currentSyExchangeRate,
+      })
 
-/**
- * Calculate the correct currentTick index for the market state
- *
- * IMPORTANT: currentTick must be a 1-based ARRAY INDEX, not apyBasePoints!
- * The simulateSwap function uses findTickByIndex which does: ticksTree.at(index - 1)
- *
- * @returns The 1-based array index of the tick where impliedRate <= currentSpotPrice
- */
-function calculateCurrentTickIndex(ticksData: Ticks): number {
-  // Find the tick with highest impliedRate <= currentSpotPrice
-  let currentTickApyBps = ticksData.ticksTree[0]?.apyBasePoints || 0
+      return {
+        amountIn: netSyCost,
+        amountOut: ytOut,
+        lpFee: lpFee,
+        protocolFee,
+      }
+    }
 
-  for (const tick of ticksData.ticksTree) {
-    const tickRate = Number(tick.impliedRate)
-    if (tickRate <= ticksData.currentSpotPrice) {
-      currentTickApyBps = tick.apyBasePoints
+    throw new Error(`Unknown quote direction: ${direction}`)
+  } catch (error) {
+    console.error("Unable to get swap quote", error)
+    return {
+      amountIn,
+      amountOut: 0,
+      lpFee: 0,
+      protocolFee: 0,
     }
   }
-
-  // Find the array index (0-based) of this tick
-  const arrayIndex = ticksData.ticksTree.findIndex((t: Tick) => t.apyBasePoints === currentTickApyBps)
-
-  // Convert to 1-based index for simulateSwap
-  return arrayIndex !== -1 ? arrayIndex + 1 : 1
 }

package/src/swap.ts

@@ -13,11 +13,10 @@ import {
   bigIntMin,
   calculateFeeRate,
   findTickByIndex,
-  findTickByKey,
   getFeeFromAmount,
   getImpliedRate,
-  getPredecessorTickKey,
-  getSuccessorTickKey,
+  getPredecessorTickIdxByIdx,
+  getSuccessorTickIdxByIdx,
   normalizedTimeRemaining,
 } from "./utils"
 
@@ -81,25 +80,25 @@ export function simulateSwap(marketState: MarketThreeState, args: SwapArgs): Swa
     iterations++
     if (debug) console.log(`\n--- Iteration ${iterations}, amountInLeft=${amountInLeft} ---`)
 
-    // Get right boundary of current interval
-    const rightBoundaryIndexOpt = findTickByKey(ticks, getSuccessorTickKey(ticks, currentLeftBoundaryIndex))?.index
+    // Get right boundary of current interval (successor tick index)
+    const rightBoundaryIndexOpt = getSuccessorTickIdxByIdx(ticks, currentLeftBoundaryIndex)
     if (debug) console.log(`rightBoundary=${rightBoundaryIndexOpt}`)
 
     if (rightBoundaryIndexOpt === null) {
       if (args.direction === SwapDirection.SyToPt) {
         // Cross to create a new interval
-        const predecessor = getPredecessorTickKey(ticks, currentLeftBoundaryIndex)
-        if (predecessor === null) break
+        const predecessorIdx = getPredecessorTickIdxByIdx(ticks, currentLeftBoundaryIndex)
+        if (predecessorIdx === null) break
 
         // Update active liquidity by subtracting liquidity_net at boundary
-        const boundaryTick = findTickByKey(ticks, predecessor)
+        const boundaryTick = findTickByIndex(ticks, currentLeftBoundaryIndex)
 
         // When crossing downward (SyToPt), update state
-        currentPriceSpot = getImpliedRate(currentLeftBoundaryIndex) // Boundary we're crossing
-        currentLeftBoundaryIndex = boundaryTick.index // New left boundary
+        currentPriceSpot = getImpliedRate(boundaryTick?.apyBasePoints ?? 0) // Boundary we're crossing
+        currentLeftBoundaryIndex = predecessorIdx // New left boundary
 
         if (boundaryTick) {
-          activeLiquidityU64 = bigIntMax(0n, activeLiquidityU64 - boundaryTick.tick.liquidityNet)
+          activeLiquidityU64 = bigIntMax(0n, activeLiquidityU64 - boundaryTick.liquidityNet)
           activeLiquidityF64 = Number(activeLiquidityU64)
         }
         continue
@@ -167,7 +166,16 @@ export function simulateSwap(marketState: MarketThreeState, args: SwapArgs): Swa
       const syOutGrossClamped: number = Math.min(syOutGross, Number(principalSy))
 
       if (syOutGrossClamped > 0) {
-        const totalFeeOut: number = getFeeFromAmount(syOutGrossClamped, lpFeeRate)
+        // For flash swaps, fee is based on YT value = (pt - sy × sy_exchange_rate) / sy_exchange_rate (in SY terms)
+        let totalFeeOut: number
+        if (args.isCurrentFlashSwap) {
+          const syOutBase = syOutGrossClamped * args.syExchangeRate
+          const ytValueBase = ptInSegment - syOutBase
+          const ytValueSy = ytValueBase / args.syExchangeRate
+          totalFeeOut = getFeeFromAmount(Math.max(0, Math.floor(ytValueSy)), lpFeeRate)
+        } else {
+          totalFeeOut = getFeeFromAmount(syOutGrossClamped, lpFeeRate)
+        }
         const protocolFeeOut: number = Math.floor((totalFeeOut * protocolFeeBps) / BASE_POINTS)
         const lpFeeOut: number = totalFeeOut - protocolFeeOut
         const syOutNet: number = syOutGrossClamped - totalFeeOut
@@ -204,7 +212,7 @@ export function simulateSwap(marketState: MarketThreeState, args: SwapArgs): Swa
 
       if (deltaCToLeftBoundary <= eps) {
         // Cross boundary to the left
-        const predecessor = getPredecessorTickKey(ticks, currentLeftBoundaryIndex)
+        const predecessor = getPredecessorTickIdxByIdx(ticks, currentLeftBoundaryIndex)
         if (predecessor === null) break
 
         // Update active liquidity by subtracting liquidity_net at boundary
@@ -214,7 +222,7 @@ export function simulateSwap(marketState: MarketThreeState, args: SwapArgs): Swa
           activeLiquidityF64 = Number(activeLiquidityU64)
         }
 
-        currentPriceSpot = getImpliedRate(currentLeftBoundaryIndex)
+        currentPriceSpot = getImpliedRate(boundaryTick?.apyBasePoints ?? 0)
         currentLeftBoundaryIndex = predecessor
         continue
       }
@@ -240,7 +248,7 @@ export function simulateSwap(marketState: MarketThreeState, args: SwapArgs): Swa
 
       if (ptOutGrossU64 === 0n) {
         // Nothing to pay out; try to cross
-        const predecessor = getPredecessorTickKey(ticks, currentLeftBoundaryIndex)
+        const predecessor = getPredecessorTickIdxByIdx(ticks, currentLeftBoundaryIndex)
         if (predecessor === null) break
 
         // Update active liquidity
@@ -250,13 +258,21 @@ export function simulateSwap(marketState: MarketThreeState, args: SwapArgs): Swa
           activeLiquidityF64 = Number(activeLiquidityU64)
         }
 
-        currentPriceSpot = getImpliedRate(currentLeftBoundaryIndex)
+        currentPriceSpot = getImpliedRate(boundaryTick?.apyBasePoints ?? 0)
         currentLeftBoundaryIndex = predecessor
         continue
       }
 
       // Fees in token_out (PT)
-      const totalFeeOut: number = getFeeFromAmount(Number(ptOutGrossU64), lpFeeRate)
+      // For flash swaps, fee is based on YT value = pt - sy × sy_exchange_rate
+      let totalFeeOut: number
+      if (args.isCurrentFlashSwap) {
+        const syInBase = Number(syInSegmentU64) * args.syExchangeRate
+        const ytValue = Number(ptOutGrossU64) - syInBase
+        totalFeeOut = getFeeFromAmount(Math.max(0, Math.floor(ytValue)), lpFeeRate)
+      } else {
+        totalFeeOut = getFeeFromAmount(Number(ptOutGrossU64), lpFeeRate)
+      }
       const protocolFeeOut: number = Math.floor((totalFeeOut * protocolFeeBps) / BASE_POINTS)
       const lpFeeOut: number = totalFeeOut - protocolFeeOut
       const ptOutNet: number = Number(ptOutGrossU64) - totalFeeOut
@@ -272,7 +288,7 @@ export function simulateSwap(marketState: MarketThreeState, args: SwapArgs): Swa
 
       // If we hit boundary, cross
       if (Math.abs(currentPriceSpot - anchorULeft) <= eps && amountInLeft > 0) {
-        const predecessor = getPredecessorTickKey(ticks, currentLeftBoundaryIndex)
+        const predecessor = getPredecessorTickIdxByIdx(ticks, currentLeftBoundaryIndex)
         if (predecessor === null) break
 
         // Update active liquidity
@@ -282,7 +298,7 @@ export function simulateSwap(marketState: MarketThreeState, args: SwapArgs): Swa
           activeLiquidityF64 = Number(activeLiquidityU64)
         }
 
-        currentPriceSpot = getImpliedRate(currentLeftBoundaryIndex)
+        currentPriceSpot = getImpliedRate(boundaryTick?.apyBasePoints ?? 0)
         currentLeftBoundaryIndex = predecessor
       }
     }