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

package/src/addLiquidity.ts

@@ -2,10 +2,63 @@
  * CLMM Add Liquidity simulation
  * Ported from exponent_clmm/src/state/market_three/helpers/add_liquidity.rs
  */
-import { AddLiquidityArgs, AddLiquidityOutcome, LiquidityNeeds, MarketThreeState } from "./types"
-import { EffSnap, normalizedTimeRemaining } from "./utils"
+import { simulateSwap, simulateSwapExactOut } from "./swapV2"
+import {
+  AddLiquidityArgs,
+  AddLiquidityOutcome,
+  CrossingScaleParams,
+  CrossingTickState,
+  LiquidityNeeds,
+  MarketThreeState,
+  SwapDirection,
+} from "./types"
+import { EffSnap, normalizedTimeRemaining, TicksWrapper } from "./utilsV2"
+import { findTickByKey, getSuccessorTickKey } from "./utils"
+import { Ticks } from "@exponent-labs/exponent-fetcher"
 
 const TICK_KEY_BASE_POINTS = 1_000_000
+// Keep this in sync with exponent_clmm's add_liquidity helper so off-chain
+// quotes match the on-chain classic deposit path as closely as possible.
+const GAP_TOKEN_NEEDS = 5
+const SWAP_EXACT_OUT_SY_HEADROOM = 10
+
+const EMPTY_CROSSING_TICK_STATE: CrossingTickState = {
+  principalPt: 0,
+  principalSy: 0,
+  principalShareSupply: 0,
+}
+
+/**
+ * Get crossing tick state and price boundaries from Ticks.
+ * Matches wrapper_provide_liquidity.rs: current node's spot_price, principal_pt/sy/supply, successor's spot_price.
+ */
+export function getCrossingTickStateFromTicks(ticks: Ticks): {
+  crossingTickState: CrossingTickState
+  crossingTickPriceLeft: number
+  crossingTickPriceRight: number
+} {
+  const currentTickNode = ticks.ticksTree[ticks.currentTick - 1]
+  if (!currentTickNode || ticks.currentTick <= 0) {
+    return {
+      crossingTickState: EMPTY_CROSSING_TICK_STATE,
+      crossingTickPriceLeft: 0,
+      crossingTickPriceRight: 0,
+    }
+  }
+  const crossingTickPriceLeft = currentTickNode.impliedRate
+  const successorKey = getSuccessorTickKey(ticks, currentTickNode.apyBasePoints)
+  const successorTick = successorKey != null ? findTickByKey(ticks, successorKey)?.tick : null
+  const crossingTickPriceRight = successorTick?.impliedRate ?? Number.POSITIVE_INFINITY
+  return {
+    crossingTickState: {
+      principalPt: Number(currentTickNode.principalPt),
+      principalSy: Number(currentTickNode.principalSy),
+      principalShareSupply: Number(currentTickNode.principalShareSupply),
+    },
+    crossingTickPriceLeft,
+    crossingTickPriceRight,
+  }
+}
 
 /**
  * Compute liquidity target and token needs based on position range and budgets
@@ -41,6 +94,11 @@ export function computeLiquidityTargetAndTokenNeeds(
       ptNeeded: 0,
       priceSplitForNeed: lowerPrice,
       priceSplitTickIdx: lowerTickIdx,
+      // No crossing possible when below range
+      originalMaxSy: maxSy,
+      originalMaxPt: maxPt,
+      duLeftTotal: 0,
+      deltaCRightTotal: deltaCTotal,
     }
   } else if (spotPriceCurrent >= upperPrice) {
     // Above range: PT only (NOT SY!)
@@ -55,9 +113,14 @@ export function computeLiquidityTargetAndTokenNeeds(
       ptNeeded: Math.floor(ptNeed),
       priceSplitForNeed: upperPrice,
       priceSplitTickIdx: upperTickIdx,
+      // No crossing possible when above range
+      originalMaxSy: maxSy,
+      originalMaxPt: maxPt,
+      duLeftTotal: duTotal,
+      deltaCRightTotal: 0,
     }
   } else {
-    // Inside range: both sides
+    // Inside range: both sides - crossing tick possible
     const duLeft = Math.max(spotPriceCurrent - lowerPrice, epsilonClamp)
     const liquidityFromPt = maxPt / duLeft
 
@@ -75,8 +138,529 @@ export function computeLiquidityTargetAndTokenNeeds(
       ptNeeded: Math.floor(ptNeed),
       priceSplitForNeed: spotPriceCurrent,
       priceSplitTickIdx: currentIndex,
+      // Store for crossing tick scaling
+      originalMaxSy: maxSy,
+      originalMaxPt: maxPt,
+      duLeftTotal: duLeft,
+      deltaCRightTotal: deltaCRight,
+    }
+  }
+}
+
+/**
+ * Scale crossing tick token inputs from original max values to prevent double trimming.
+ *
+ * When adding liquidity that spans the current price (crossing tick), tokens get trimmed twice:
+ * 1. First by CLMM formula in computeLiquidityTargetAndTokenNeeds
+ * 2. Then by AMM formula in simulateAddLiquidityProportional
+ *
+ * This function calculates the segment's proportion of the total distribution and scales
+ * the original max values accordingly, ensuring maximum token utilization.
+ *
+ * @param scaleParams - Original max values and CLMM distribution extents
+ * @param duPtPart - PT segment length (spot price delta for this segment)
+ * @param syPerL1 - SY per unit liquidity for this segment
+ * @param clmmPtDelta - PT amount calculated from CLMM formula
+ * @param clmmSyDelta - SY amount calculated from CLMM formula
+ * @returns Tuple of [scaledPtIn, scaledSyIn] - maximum of CLMM-calculated and scaled original values
+ */
+export function scaleCrossingTickInputs(
+  scaleParams: CrossingScaleParams,
+  duPtPart: number,
+  syPerL1: number,
+  clmmPtDelta: number,
+  clmmSyDelta: number,
+): [number, number] {
+  const { duLeftTotal, deltaCRightTotal, originalMaxPt, originalMaxSy } = scaleParams
+
+  if (duLeftTotal > 0 && deltaCRightTotal > 0) {
+    // Calculate segment's proportion of total distribution
+    const ptSegmentRatio = duPtPart / duLeftTotal
+    const sySegmentRatio = syPerL1 / deltaCRightTotal
+
+    // Scale original max values by segment proportion
+    const scaledPt = Math.ceil(originalMaxPt * ptSegmentRatio)
+    const scaledSy = Math.ceil(originalMaxSy * sySegmentRatio)
+
+    // Use max of CLMM-calculated value and scaled original value
+    // This ensures we don't lose tokens due to double trimming
+    return [Math.max(clmmPtDelta, scaledPt), Math.max(clmmSyDelta, scaledSy)]
+  }
+
+  // Fallback to original logic if no crossing scale params
+  return [clmmPtDelta, clmmSyDelta]
+}
+
+/**
+ * Simulate the proportional add_liquidity logic
+ * Returns [usedPt, usedSy] based on existing tick proportions
+ */
+function simulateAddLiquidityProportional(
+  intentPt: number,
+  intentSy: number,
+  marketTotalPt: number,
+  marketTotalSy: number,
+  marketTotalLp: number,
+): [number, number] {
+  if (marketTotalLp === 0 || marketTotalPt === 0 || marketTotalSy === 0) {
+    // Empty tick - use all intended amounts
+    return [intentPt, intentSy]
+  }
+
+  const lpFromPt = (marketTotalLp * intentPt) / marketTotalPt
+  const lpFromSy = (marketTotalLp * intentSy) / marketTotalSy
+
+  if (lpFromPt < lpFromSy) {
+    // PT is the limiting factor
+    const lpTokensOut = lpFromPt
+    const usedPt = intentPt
+    const usedSy = Math.ceil((marketTotalSy * lpTokensOut) / marketTotalLp)
+    return [usedPt, usedSy]
+  } else {
+    // SY is the limiting factor
+    const lpTokensOut = lpFromSy
+    const usedSy = intentSy
+    const usedPt = Math.ceil((marketTotalPt * lpTokensOut) / marketTotalLp)
+    return [usedPt, usedSy]
+  }
+}
+
+function toU64BigInt(value: number): bigint {
+  return BigInt(Math.max(0, Math.floor(value)))
+}
+
+function ceilDivBigInt(numerator: bigint, denominator: bigint): bigint {
+  if (denominator <= 0n) {
+    return 0n
+  }
+  return numerator <= 0n ? 0n : (numerator + denominator - 1n) / denominator
+}
+
+function floorSqrtBigInt(value: bigint): bigint {
+  if (value <= 1n) {
+    return value
+  }
+  let x0 = value
+  let x1 = (x0 + 1n) >> 1n
+  while (x1 < x0) {
+    x0 = x1
+    x1 = (x1 + value / x1) >> 1n
+  }
+  return x0
+}
+
+type VirtualTickState = {
+  principalPt: bigint
+  principalSy: bigint
+  principalShareSupply: bigint
+}
+
+function getVirtualTickState(
+  key: number,
+  ticksWrapper: TicksWrapper,
+  virtualStates: Map<number, VirtualTickState>,
+): VirtualTickState {
+  const cached = virtualStates.get(key)
+  if (cached) {
+    return cached
+  }
+
+  const { principalPt, principalSy } = ticksWrapper.getPrincipals(key)
+  const tick = ticksWrapper.getTickByKey(key)
+  const state: VirtualTickState = {
+    principalPt,
+    principalSy,
+    principalShareSupply: tick ? BigInt(tick.principalShareSupply) : 0n,
+  }
+  virtualStates.set(key, state)
+  return state
+}
+
+function simulateMintSharesForTickPrestateCalcUsed(params: {
+  key: number
+  dptIn: bigint
+  dsyIn: bigint
+  ticksWrapper: TicksWrapper
+  virtualStates: Map<number, VirtualTickState>
+}): { minted: bigint; usedPt: bigint; usedSy: bigint } | null {
+  const { key, dptIn, dsyIn, ticksWrapper, virtualStates } = params
+  const state = getVirtualTickState(key, ticksWrapper, virtualStates)
+
+  const ptBefore = state.principalPt
+  const syBefore = state.principalSy
+  const supply = state.principalShareSupply
+
+  let minted = 0n
+  let usedPt = 0n
+  let usedSy = 0n
+
+  const hasPt = dptIn > 0n
+  const hasSy = dsyIn > 0n
+
+  if (hasPt && hasSy) {
+    if (supply === 0n) {
+      minted = floorSqrtBigInt(dptIn * dsyIn)
+      usedPt = dptIn
+      usedSy = dsyIn
+    } else {
+      if (ptBefore === 0n || syBefore === 0n) {
+        return null
+      }
+
+      const lpFromPt = (supply * dptIn) / ptBefore
+      const lpFromSy = (supply * dsyIn) / syBefore
+      const usePtSide = lpFromPt < lpFromSy
+      const lpTokensOut = usePtSide ? lpFromPt : lpFromSy
+
+      minted = lpTokensOut
+      if (minted === 0n) {
+        return null
+      }
+
+      if (usePtSide) {
+        usedPt = dptIn
+        usedSy = ceilDivBigInt(syBefore * lpTokensOut, supply)
+      } else {
+        usedSy = dsyIn
+        usedPt = ceilDivBigInt(ptBefore * lpTokensOut, supply)
+      }
+    }
+  } else if (hasPt && !hasSy) {
+    usedSy = 0n
+    if (supply === 0n && ptBefore === 0n) {
+      minted = dptIn
+      usedPt = dptIn
+    } else {
+      if (supply === 0n || ptBefore === 0n) {
+        return null
+      }
+      minted = (supply * dptIn) / ptBefore
+      if (minted === 0n) {
+        return null
+      }
+      usedPt = dptIn
+    }
+  } else if (!hasPt && hasSy) {
+    usedPt = 0n
+    if (supply === 0n && syBefore === 0n) {
+      minted = dsyIn
+      usedSy = dsyIn
+    } else {
+      if (supply === 0n || syBefore === 0n) {
+        return null
+      }
+      minted = (supply * dsyIn) / syBefore
+      if (minted === 0n) {
+        return null
+      }
+      usedSy = dsyIn
+    }
+  } else {
+    return { minted: 0n, usedPt: 0n, usedSy: 0n }
+  }
+
+  if (minted > 0n) {
+    state.principalShareSupply += minted
+  }
+  if (usedPt > 0n || usedSy > 0n) {
+    state.principalPt += usedPt
+    state.principalSy += usedSy
+    ticksWrapper.setPrincipals(key, state.principalPt, state.principalSy)
+  }
+
+  return { minted, usedPt, usedSy }
+}
+
+function simulateAccruePrincipalForDeposit(params: {
+  ticks: Ticks
+  snap: EffSnap
+  lowerPrice: number
+  upperPrice: number
+  priceSplitForNeed: number
+  splitTickKey: number
+  lowerTickKey: number
+  upperTickKey: number
+  liquidityTarget: number
+  originalMaxSy: number
+  originalMaxPt: number
+}): { sySpent: number; ptSpent: number } {
+  const {
+    ticks,
+    snap,
+    lowerPrice,
+    upperPrice,
+    priceSplitForNeed,
+    splitTickKey,
+    lowerTickKey,
+    upperTickKey,
+    liquidityTarget,
+    originalMaxSy,
+    originalMaxPt,
+  } = params
+
+  const ticksWrapper = new TicksWrapper(ticks)
+  ticksWrapper.upsertBoundaryTick(lowerTickKey, snap)
+  ticksWrapper.upsertBoundaryTick(upperTickKey, snap)
+  const virtualStates = new Map<number, VirtualTickState>()
+
+  let totalSySpend = 0n
+  let totalPtSpend = 0n
+  let pendingCrossPt: { leftKey: number; rightKey: number; ptDelta: bigint; duPart: number } | null = null
+  let pendingCrossSy: { leftKey: number; rightKey: number; syDelta: bigint; syPerL: number } | null = null
+
+  const resolveTraversalStartKey = (candidateKey: number): number => {
+    if (ticksWrapper.getTickByKey(candidateKey)) {
+      return candidateKey
+    }
+    const predecessor = ticksWrapper.predecessorKey(candidateKey)
+    return predecessor ?? candidateKey
+  }
+
+  const visitIntervals = (startKey: number, priceStart: number, priceEnd: number, visitor: (params: {
+    leftKey: number
+    rightKey: number
+    leftPrice: number
+    rightPrice: number
+  }) => void) => {
+    if (!(priceStart < priceEnd)) {
+      return
+    }
+
+    let currentKey = startKey
+    while (true) {
+      const rightKey = ticksWrapper.successorKey(currentKey)
+      if (rightKey == null) {
+        break
+      }
+
+      const leftPrice = ticksWrapper.getSpotPrice(currentKey)
+      const rightPrice = ticksWrapper.getSpotPrice(rightKey)
+      visitor({ leftKey: currentKey, rightKey, leftPrice, rightPrice })
+
+      if (rightPrice >= priceEnd) {
+        break
+      }
+      currentKey = rightKey
     }
   }
+
+  const ptSliceStart = lowerPrice
+  const ptSliceEnd = Math.min(priceSplitForNeed, upperPrice)
+  const ptStartKey = resolveTraversalStartKey(lowerTickKey)
+  visitIntervals(ptStartKey, ptSliceStart, ptSliceEnd, ({ leftKey, rightKey, leftPrice, rightPrice }) => {
+    const segmentStart = Math.max(leftPrice, ptSliceStart)
+    const segmentEnd = Math.min(rightPrice, ptSliceEnd)
+    const segmentLength = segmentEnd - segmentStart
+    if (!(segmentLength > 0)) {
+      return
+    }
+
+    const isCrossing = leftPrice < priceSplitForNeed && rightPrice > priceSplitForNeed
+    const principalPtDelta = toU64BigInt(Math.ceil(liquidityTarget * segmentLength))
+    if (principalPtDelta <= 0n) {
+      return
+    }
+
+    if (isCrossing) {
+      pendingCrossPt = {
+        leftKey,
+        rightKey,
+        ptDelta: principalPtDelta,
+        duPart: segmentLength,
+      }
+      return
+    }
+
+    const minted = simulateMintSharesForTickPrestateCalcUsed({
+      key: leftKey,
+      dptIn: principalPtDelta,
+      dsyIn: 0n,
+      ticksWrapper,
+      virtualStates,
+    })
+    if (!minted) {
+      throw new Error("Deposit too small to mint shares in PT segment")
+    }
+
+    totalPtSpend += minted.usedPt
+    totalSySpend += minted.usedSy
+  })
+
+  const sySliceStart = Math.max(priceSplitForNeed, lowerPrice)
+  const sySliceEnd = upperPrice
+  const syStartCandidate = splitTickKey >= lowerTickKey ? splitTickKey : lowerTickKey
+  const syStartKey = resolveTraversalStartKey(syStartCandidate)
+
+  visitIntervals(syStartKey, sySliceStart, sySliceEnd, ({ leftKey, rightKey, leftPrice, rightPrice }) => {
+    const segmentStart = Math.max(leftPrice, sySliceStart)
+    const segmentEnd = Math.min(rightPrice, sySliceEnd)
+    if (!(segmentEnd > segmentStart)) {
+      return
+    }
+
+    const syPerL = snap.getEffectivePrice(segmentStart) - snap.getEffectivePrice(segmentEnd)
+    const principalSyDelta = toU64BigInt(Math.ceil(liquidityTarget * syPerL))
+    if (principalSyDelta <= 0n) {
+      return
+    }
+
+    const isCrossing = leftPrice < priceSplitForNeed && rightPrice > priceSplitForNeed
+    if (isCrossing) {
+      pendingCrossSy = {
+        leftKey,
+        rightKey,
+        syDelta: principalSyDelta,
+        syPerL,
+      }
+      return
+    }
+
+    const minted = simulateMintSharesForTickPrestateCalcUsed({
+      key: leftKey,
+      dptIn: 0n,
+      dsyIn: principalSyDelta,
+      ticksWrapper,
+      virtualStates,
+    })
+    if (!minted) {
+      throw new Error("Deposit too small to mint shares in SY segment")
+    }
+
+    totalPtSpend += minted.usedPt
+    totalSySpend += minted.usedSy
+  })
+
+  if (pendingCrossPt && pendingCrossSy) {
+    const ptLeft = BigInt(Math.max(0, Math.floor(originalMaxPt) - Number(totalPtSpend) - GAP_TOKEN_NEEDS))
+    const syLeft = BigInt(Math.max(0, Math.floor(originalMaxSy) - Number(totalSySpend) - GAP_TOKEN_NEEDS))
+    const scaledPtIn = pendingCrossPt.ptDelta > ptLeft ? pendingCrossPt.ptDelta : ptLeft
+    const scaledSyIn = pendingCrossSy.syDelta > syLeft ? pendingCrossSy.syDelta : syLeft
+
+    const minted = simulateMintSharesForTickPrestateCalcUsed({
+      key: pendingCrossPt.leftKey,
+      dptIn: scaledPtIn,
+      dsyIn: scaledSyIn,
+      ticksWrapper,
+      virtualStates,
+    })
+    if (!minted) {
+      throw new Error("Deposit too small to mint shares in crossing segment")
+    }
+
+    totalPtSpend += minted.usedPt
+    totalSySpend += minted.usedSy
+  }
+
+  const sySpent = Number(totalSySpend)
+  const ptSpent = Number(totalPtSpend)
+  if (!Number.isSafeInteger(sySpent) || !Number.isSafeInteger(ptSpent)) {
+    throw new Error("Token spend exceeds JS safe integer range")
+  }
+
+  return { sySpent, ptSpent }
+}
+
+/**
+ * Compute token needs with crossing tick adjustment
+ * This matches the Rust compute_token_needs_with_crossing function
+ */
+export function computeTokenNeedsWithCrossing(
+  snap: EffSnap,
+  spotPriceCurrent: number,
+  priceEffLower: number,
+  priceEffUpper: number,
+  lowerPrice: number,
+  upperPrice: number,
+  maxSy: number,
+  maxPt: number,
+  epsilonClamp: number,
+  crossingTickState: CrossingTickState,
+  crossingTickPriceLeft: number,
+  crossingTickPriceRight: number,
+): [number, number] {
+  // Below range: SY only
+  if (spotPriceCurrent <= lowerPrice) {
+    const deltaCTotal = priceEffLower - priceEffUpper
+    const liquidityFromSy = maxSy / deltaCTotal
+    const syNeed = liquidityFromSy * deltaCTotal
+    return [Math.ceil(syNeed), 0]
+  }
+
+  // Above range: PT only
+  if (spotPriceCurrent >= upperPrice) {
+    const duTotal = upperPrice - lowerPrice
+    const liquidityFromPt = maxPt / duTotal
+    const ptNeed = liquidityFromPt * duTotal
+    return [0, Math.ceil(ptNeed)]
+  }
+
+  // Inside range: both sides
+  const duLeft = Math.max(spotPriceCurrent - lowerPrice, epsilonClamp)
+  const priceEffCurrent = snap.getEffectivePrice(spotPriceCurrent)
+  const deltaCRight = Math.max(priceEffCurrent - priceEffUpper, epsilonClamp)
+
+  const liquidityFromPt = maxPt / duLeft
+  const liquidityFromSy = maxSy / deltaCRight
+
+  const liquidityTarget = Math.min(liquidityFromPt, liquidityFromSy)
+  let ptNeed = liquidityTarget * duLeft
+  let syNeed = liquidityTarget * deltaCRight
+
+  // Apply crossing tick adjustment if the tick has existing liquidity
+  // Match Rust: !crossing_tick_state.is_empty() where is_empty = (principal_share_supply == 0)
+  const isCrossingTickActive =
+    crossingTickState.principalShareSupply > 0 &&
+    crossingTickPriceLeft < spotPriceCurrent &&
+    crossingTickPriceRight > spotPriceCurrent
+
+  if (isCrossingTickActive) {
+    // Calculate PT and SY portions that would go into the crossing tick
+    // PT portion: from crossing_tick_price_left to spot_price_current (match Rust)
+    const crossingPtSegment = spotPriceCurrent - Math.max(crossingTickPriceLeft, lowerPrice)
+    const crossingPtIntended = Math.ceil(liquidityTarget * crossingPtSegment)
+
+    // SY portion: from spotPriceCurrent to crossingTickPriceRight
+    const crossingSySegmentStart = Math.max(spotPriceCurrent, crossingTickPriceLeft)
+    const crossingSySegmentEnd = Math.min(crossingTickPriceRight, upperPrice)
+    const syPerL = snap.getEffectivePrice(crossingSySegmentStart) - snap.getEffectivePrice(crossingSySegmentEnd)
+    const crossingSyIntended = Math.ceil(liquidityTarget * Math.max(syPerL, 0))
+
+    if (crossingPtIntended > 0 && crossingSyIntended > 0) {
+      // Tokens already allocated to non-crossing segments before crossing processing.
+      const ptOutsideCrossing = Math.max(ptNeed - crossingPtIntended, 0)
+      const syOutsideCrossing = Math.max(syNeed - crossingSyIntended, 0)
+
+      // Apply scaling from original max values to prevent double trimming
+      const [scaledPtIn, scaledSyIn] =
+        duLeft > 0 && deltaCRight > 0
+          ? (() => {
+              const totalPtSpend = Math.ceil(ptOutsideCrossing)
+              const totalSySpend = Math.ceil(syOutsideCrossing)
+              const ptLeft = Math.max(maxPt - totalPtSpend - GAP_TOKEN_NEEDS, 0)
+              const syLeft = Math.max(maxSy - totalSySpend - GAP_TOKEN_NEEDS, 0)
+
+              // Use max of CLMM-calculated value and scaled original value
+              return [Math.max(crossingPtIntended, ptLeft), Math.max(crossingSyIntended, syLeft)]
+            })()
+          : [crossingPtIntended, crossingSyIntended]
+
+      // Simulate add_liquidity proportional logic with scaled inputs
+      const [usedPt, usedSy] = simulateAddLiquidityProportional(
+        scaledPtIn,
+        scaledSyIn,
+        crossingTickState.principalPt,
+        crossingTickState.principalSy,
+        crossingTickState.principalShareSupply,
+      )
+
+      // Adjust needs based on what would actually be used
+      ptNeed = ptOutsideCrossing + usedPt
+
+      syNeed = syOutsideCrossing + usedSy
+    }
+  }
+
+  return [Math.ceil(syNeed), Math.ceil(ptNeed)]
 }
 
 /**
@@ -101,6 +685,9 @@ export function simulateAddLiquidity(marketState: MarketThreeState, args: AddLiq
   const priceEffLower = snap.getEffectivePrice(lowerPrice)
   const priceEffUpper = snap.getEffectivePrice(upperPrice)
 
+  const maxSyForNeeds = Math.max(0, Math.floor(args.maxSy) - GAP_TOKEN_NEEDS)
+  const maxPtForNeeds = Math.max(0, Math.floor(args.maxPt) - GAP_TOKEN_NEEDS)
+
   // Calculate liquidity needs
   const liquidityNeeds = computeLiquidityTargetAndTokenNeeds(
     snap,
@@ -112,14 +699,33 @@ export function simulateAddLiquidity(marketState: MarketThreeState, args: AddLiq
     args.lowerTick,
     args.upperTick,
     ticks.currentTick,
-    args.maxSy,
-    args.maxPt,
+    maxSyForNeeds,
+    maxPtForNeeds,
     configurationOptions.epsilonClamp,
   )
 
+  const currentTickNode = ticks.ticksTree[ticks.currentTick - 1]
+  const currentTickKey =
+    currentTickNode && currentTickNode.apyBasePoints > 0 ? currentTickNode.apyBasePoints : args.lowerTick
+  const splitTickKey =
+    currentSpot <= lowerPrice ? args.lowerTick : currentSpot >= upperPrice ? args.upperTick : currentTickKey
+  const { sySpent: syNeededWithCrossing, ptSpent: ptNeededWithCrossing } = simulateAccruePrincipalForDeposit({
+    ticks,
+    snap,
+    lowerPrice,
+    upperPrice,
+    priceSplitForNeed: liquidityNeeds.priceSplitForNeed,
+    splitTickKey,
+    lowerTickKey: args.lowerTick,
+    upperTickKey: args.upperTick,
+    liquidityTarget: liquidityNeeds.liquidityTarget,
+    originalMaxSy: liquidityNeeds.originalMaxSy,
+    originalMaxPt: liquidityNeeds.originalMaxPt,
+  })
+
   // Enforce budgets
-  const sySpent = liquidityNeeds.syNeeded
-  const ptSpent = liquidityNeeds.ptNeeded
+  const sySpent = syNeededWithCrossing
+  const ptSpent = ptNeededWithCrossing
 
   if (sySpent > args.maxSy) {
     throw new Error(`Insufficient SY budget: need ${sySpent}, have ${args.maxSy}`)
@@ -198,8 +804,26 @@ export function calcDepositSyAndPtFromBaseAmount(params: {
   expirationTs: number
   currentSpotPrice: number
   syExchangeRate: number
+  /** Optional crossing tick state for accurate ratio prediction.
+   *  When provided, the prediction accounts for the existing PT/SY proportions
+   *  in the active tick, matching the on-chain behaviour more closely. */
+  crossingTickState?: CrossingTickState
+  crossingTickPriceLeft?: number
+  crossingTickPriceRight?: number
+  epsilonClamp?: number
 }) {
-  const { expirationTs, currentSpotPrice, syExchangeRate, lowerPrice, upperPrice, baseTokenAmount } = params
+  const {
+    expirationTs,
+    currentSpotPrice,
+    syExchangeRate,
+    lowerPrice,
+    upperPrice,
+    baseTokenAmount,
+    crossingTickState = EMPTY_CROSSING_TICK_STATE,
+    crossingTickPriceLeft = 0,
+    crossingTickPriceRight = 0,
+    epsilonClamp = 1e-18,
+  } = params
 
   if (baseTokenAmount <= 0 || syExchangeRate <= 0) {
     return {
@@ -215,23 +839,25 @@ export function calcDepositSyAndPtFromBaseAmount(params: {
   const priceEffUpper = effSnap.getEffectivePrice(upperPrice)
 
   // We mirror the on-chain logic in `wrapper_provide_liquidity`:
-  // 1. Use a large mock amount for both SY and PT to infer the *ratio* of SY/PT
-  //    the market "wants" for this price range (compute_token_needs on-chain).
+  // 1. Use compute_token_needs_with_crossing to infer the ratio of SY/PT
+  //    the market "wants" for this price range.
+  //    When crossing tick state is provided, this accounts for the existing
+  //    PT/SY proportions in the active tick, significantly improving accuracy.
   // 2. Use that ratio plus the current SY exchange rate to decide how much of the
-  //    minted SY should be stripped into PT to keep the user-close to pool proportions.
-  const { syNeeded: syMock, ptNeeded: ptMock } = computeLiquidityTargetAndTokenNeeds(
+  //    minted SY should be stripped into PT (calc_strip_amount).
+  const [syMock, ptMock] = computeTokenNeedsWithCrossing(
     effSnap,
     currentSpotPrice,
     priceEffLower,
     priceEffUpper,
     lowerPrice,
     upperPrice,
-    0,
-    0,
-    0,
     1e9,
     1e9,
-    1e-18,
+    epsilonClamp,
+    crossingTickState,
+    crossingTickPriceLeft,
+    crossingTickPriceRight,
   )
 
   // Total SY the user would get by minting SY from base off-chain
@@ -267,7 +893,9 @@ export function calcDepositSyAndPtFromBaseAmount(params: {
  * Solution: B = (totalAmountSy * marketPtLiq) / (marketPtLiq + marketSyLiq * curSyRate)
  */
 function calcStripAmount(totalAmountSy: number, curSyRate: number, marketPtLiq: number, marketSyLiq: number): number {
-  const toStrip = (totalAmountSy * marketPtLiq) / (curSyRate * marketSyLiq + marketPtLiq)
+  const denominator = curSyRate * marketSyLiq + marketPtLiq
+  if (denominator <= 0) return 0
+  const toStrip = (totalAmountSy * marketPtLiq) / denominator
   return Math.ceil(toStrip)
 }
 
@@ -324,42 +952,43 @@ export function simulateWrapperProvideLiquidity(
     const priceEffLower = snap.getEffectivePrice(lowerPrice)
     const priceEffUpper = snap.getEffectivePrice(upperPrice)
 
-    // Step 3: Calculate "mock" token needs using MOCK_AMOUNT (1e9)
-    // This gives us the ratio of SY:PT needed for this tick range
-    const MOCK_AMOUNT = 1e9
-    const mockNeeds = computeLiquidityTargetAndTokenNeeds(
+    // Step 3: Get crossing tick state (matches wrapper_provide_liquidity.rs)
+    const { crossingTickState, crossingTickPriceLeft, crossingTickPriceRight } =
+      getCrossingTickStateFromTicks(ticks)
+
+    // Step 4: Calculate mock token needs using compute_token_needs_with_crossing
+    // max_sy = syAmount, max_pt = syAmount * syExchangeRate (as on-chain)
+    const maxPt = syAmount * syExchangeRate
+    const [syMock, ptMock] = computeTokenNeedsWithCrossing(
       snap,
       currentSpot,
       priceEffLower,
       priceEffUpper,
       lowerPrice,
       upperPrice,
-      lowerTick,
-      upperTick,
-      ticks.currentTick,
-      MOCK_AMOUNT,
-      MOCK_AMOUNT,
+      syAmount,
+      maxPt,
       configurationOptions.epsilonClamp,
+      crossingTickState,
+      crossingTickPriceLeft,
+      crossingTickPriceRight,
     )
 
-    // Step 4: Calculate how much SY to strip
-    // Uses the mock amounts to determine the ratio
-    const syToStrip = calcStripAmount(syAmount, syExchangeRate, mockNeeds.ptNeeded, mockNeeds.syNeeded)
-
-    console.log("[simulateWrapperProvideLiquidity] Strip calculation:", {
-      syToStrip,
-      formula: `(${syAmount} * ${mockNeeds.ptNeeded}) / (${syExchangeRate} * ${mockNeeds.syNeeded} + ${mockNeeds.ptNeeded})`,
-    })
+    // Step 5: Calculate how much SY to strip (calc_strip_amount on-chain)
+    // Cap syToStrip to syAmount to prevent negative remainder from ceil rounding
+    const syToStripRaw = calcStripAmount(syAmount, syExchangeRate, ptMock, syMock)
+    const syToStrip = Math.min(syToStripRaw, syAmount)
 
-    // Step 5: Calculate PT and YT from stripping
+    // Step 6: Calculate PT and YT from stripping
     // When you strip SY, you get PT = SY * syExchangeRate and YT = SY * syExchangeRate
     const ptFromStrip = syToStrip * syExchangeRate
     const ytOut = ptFromStrip // YT amount equals PT amount from strip
 
-    // Step 6: Calculate remaining SY after strip
-    const syRemainder = syAmount - syToStrip
+    // Step 7: Calculate remaining SY after strip
+    // Use Math.max to ensure non-negative (safety net for floating point edge cases)
+    const syRemainder = Math.max(0, syAmount - syToStrip)
 
-    // Step 7: Simulate deposit liquidity with remaining SY and PT
+    // Step 8: Simulate deposit liquidity with remaining SY and PT
     const depositResult = simulateAddLiquidity(marketState, {
       lowerTick,
       upperTick,
@@ -382,3 +1011,348 @@ export function simulateWrapperProvideLiquidity(
     return null
   }
 }
+
+/**
+ * Simulate swap & supply operation (ixProvideLiquidityBase)
+ * 1. Mints SY from base asset
+ * 2. Swaps some SY for PT on the market (instead of stripping)
+ * 3. Deposits remaining SY + bought PT into liquidity position
+ *
+ * This approach has lower slippage than minting because it uses market liquidity.
+ *
+ * @param marketState - Current market state
+ * @param amountBase - Amount of base tokens (in lamports)
+ * @param lowerTick - Lower tick key (APY in basis points)
+ * @param upperTick - Upper tick key (APY in basis points)
+ * @param syExchangeRate - SY exchange rate
+ * @returns Simulation result with LP out, PT to buy, SY constraint, etc.
+ */
+export function simulateSwapAndSupply(
+  marketState: MarketThreeState,
+  amountBase: number,
+  lowerTick: number,
+  upperTick: number,
+  syExchangeRate: number,
+): {
+  lpOut: number
+  ptToBuy: number
+  syConstraint: number
+  syForSwap: number
+  syRemainder: number
+  ptFromSwap: number
+  syDeposited: number
+  ptDeposited: number
+} | null {
+  try {
+    // Wrapper provide-liquidity-base debits base as:
+    //   base_needed = ceil(total_sy_spent * sy_exchange_rate)
+    // So the strict SY budget for a user-provided base input is floor(base / rate).
+    const syBudget = convertBaseToSyBudget(amountBase)
+
+    if (syBudget <= 0) {
+      return {
+        lpOut: 0,
+        ptToBuy: 0,
+        syConstraint: 0,
+        syForSwap: 0,
+        syRemainder: 0,
+        ptFromSwap: 0,
+        syDeposited: 0,
+        ptDeposited: 0,
+      }
+    }
+
+    const MOCK_AMOUNT = 1e9
+    const mockNeeds = simulateAddLiquidity(marketState, {
+      lowerTick,
+      upperTick,
+      maxSy: MOCK_AMOUNT,
+      maxPt: MOCK_AMOUNT,
+      syExchangeRate,
+    })
+    const searchBudget = Math.max(0, syBudget - SWAP_EXACT_OUT_SY_HEADROOM)
+
+    // Wrapper flow still executes a flash swap even when external_pt_to_buy is 0
+    // (effective exact-out target becomes 2 due +2 safety margin).
+    let externalPtToBuy = 0
+    if (syBudget > 0 && mockNeeds.ptSpent > 0) {
+      if (mockNeeds.sySpent > 0) {
+        // Normal case: position range includes current spot price
+        // Calculate optimal split between swap and deposit
+        const denominator = syExchangeRate * mockNeeds.sySpent + mockNeeds.ptSpent
+        const syToSwapGuess = denominator > 0 ? Math.ceil((syBudget * mockNeeds.ptSpent) / denominator) : 0
+
+        if (syToSwapGuess > 0) {
+          const guessSwap = simulateSwap(marketState, {
+            direction: SwapDirection.SyToPt,
+            amountIn: syToSwapGuess,
+            syExchangeRate,
+            isCurrentFlashSwap: true,
+          })
+          externalPtToBuy = Math.max(0, Math.floor(guessSwap.amountOut))
+        }
+      } else {
+        // Below-range case: position only needs PT (sySpent = 0)
+        // Swap all SY to PT
+        const guessSwap = simulateSwap(marketState, {
+          direction: SwapDirection.SyToPt,
+          amountIn: syBudget,
+          syExchangeRate,
+          isCurrentFlashSwap: true,
+        })
+        externalPtToBuy = Math.max(0, Math.floor(guessSwap.amountOut))
+      }
+    }
+
+    const candidateCache = new Map<number, SwapAndSupplyCandidate | null>()
+    const evaluateCandidate = (ptConstraint: number) => {
+      const key = Math.max(0, Math.floor(ptConstraint))
+      const cached = candidateCache.get(key)
+      if (cached !== undefined) {
+        return cached
+      }
+      const candidate = simulateSwapAndSupplyForPtConstraint(
+        marketState,
+        lowerTick,
+        upperTick,
+        syBudget,
+        key,
+        syExchangeRate,
+      )
+      candidateCache.set(key, candidate)
+      return candidate
+    }
+    const ptCap = 1_000_000_000
+    let bestUnderBudget: SwapAndSupplyCandidate | null = null
+    let leastOverspend: SwapAndSupplyCandidate | null = null
+    const considerCandidate = (candidate: SwapAndSupplyCandidate | null) => {
+      if (!candidate) {
+        return
+      }
+      if (candidate.totalSySpent <= searchBudget) {
+        if (
+          !bestUnderBudget ||
+          candidate.totalSySpent > bestUnderBudget.totalSySpent ||
+          (candidate.totalSySpent === bestUnderBudget.totalSySpent && candidate.lpOut > bestUnderBudget.lpOut)
+        ) {
+          bestUnderBudget = candidate
+        }
+        return
+      }
+
+      if (
+        !leastOverspend ||
+        candidate.totalSySpent < leastOverspend.totalSySpent ||
+        (candidate.totalSySpent === leastOverspend.totalSySpent && candidate.lpOut > leastOverspend.lpOut)
+      ) {
+        leastOverspend = candidate
+      }
+    }
+
+    // Always evaluate from zero to establish a valid lower bound.
+    considerCandidate(evaluateCandidate(0))
+
+    let lowPt = 0
+    let highPt = Math.max(1, externalPtToBuy)
+    let highCandidate = evaluateCandidate(highPt)
+    considerCandidate(highCandidate)
+    if (highCandidate && highCandidate.totalSySpent <= searchBudget) {
+      lowPt = highPt
+    }
+
+    // Expand upward until we hit over-budget/null region so binary search can maximize usage.
+    for (let i = 0; i < 18 && highPt < ptCap; i++) {
+      if (!highCandidate || highCandidate.totalSySpent > searchBudget) {
+        break
+      }
+      const nextHigh = Math.min(ptCap, highPt * 2)
+      if (nextHigh === highPt) {
+        break
+      }
+      highPt = nextHigh
+      highCandidate = evaluateCandidate(highPt)
+      considerCandidate(highCandidate)
+      if (highCandidate && highCandidate.totalSySpent <= searchBudget) {
+        lowPt = highPt
+      }
+    }
+
+    // Binary search the feasibility boundary.
+    let searchLow = Math.max(0, lowPt + 1)
+    let searchHigh = highPt
+    while (searchLow <= searchHigh) {
+      const mid = Math.floor((searchLow + searchHigh) / 2)
+      const candidate = evaluateCandidate(mid)
+      considerCandidate(candidate)
+
+      if (candidate && candidate.totalSySpent <= searchBudget) {
+        searchLow = mid + 1
+      } else {
+        searchHigh = mid - 1
+      }
+    }
+
+    // Local sweep around the boundary to handle small non-monotonic steps.
+    const localRadius = 16
+    const localStart = Math.max(0, searchHigh - localRadius)
+    const localEnd = Math.min(ptCap, searchHigh + localRadius)
+    for (let pt = localStart; pt <= localEnd; pt++) {
+      considerCandidate(evaluateCandidate(pt))
+    }
+
+    const selected = bestUnderBudget ?? leastOverspend
+    if (!selected) {
+      throw new Error("Unable to simulate swap & supply for initial PT constraint")
+    }
+    if (process.env.DEBUG_SWAP_SUPPLY === "1") {
+      console.log("[simulateSwapAndSupply]", {
+        syBudget,
+        searchBudget,
+        mockNeeds,
+        externalPtToBuy,
+        selected,
+      })
+    }
+
+    return {
+      lpOut: selected.lpOut,
+      ptToBuy: selected.ptConstraint,
+      syConstraint: syBudget,
+      syForSwap: selected.tradeSySpent,
+      syRemainder: selected.syRemainderAfterSwap,
+      ptFromSwap: selected.tradePtOut,
+      syDeposited: selected.depositSySpent,
+      ptDeposited: selected.depositPtSpent,
+    }
+  } catch (error) {
+    console.error("[simulateSwapAndSupply] Error:", error)
+    return null
+  }
+}
+
+type SwapAndSupplyCandidate = {
+  ptConstraint: number
+  tradeSySpent: number
+  tradePtOut: number
+  depositSySpent: number
+  depositPtSpent: number
+  lpOut: number
+  totalSySpent: number
+  syRemainderAfterSwap: number
+}
+
+function simulateSwapAndSupplyForPtConstraint(
+  marketState: MarketThreeState,
+  lowerTick: number,
+  upperTick: number,
+  syBudget: number,
+  ptConstraint: number,
+  syExchangeRate: number,
+): SwapAndSupplyCandidate | null {
+  let swapResult: {
+    sySpent: number
+    ptOut: number
+    postMarketState?: MarketThreeState
+  }
+
+  try {
+    swapResult = simulateBuyPtExactOutWrapper(
+      marketState,
+      syBudget,
+      ptConstraint,
+      syExchangeRate,
+    )
+  } catch {
+    // Budget insufficient for this PT constraint
+    return null
+  }
+
+  const depositState = swapResult.postMarketState ?? marketState
+  const syAvailableForDeposit = Math.max(0, syBudget - swapResult.sySpent)
+  const depositResult = simulateAddLiquidity(depositState, {
+    lowerTick,
+    upperTick,
+    maxSy: syBudget,
+    maxPt: swapResult.ptOut,
+    syExchangeRate,
+  })
+
+  // Swap & supply must actually add liquidity.
+  // Discard candidates that end up as swap-only (deltaL == 0).
+  if (depositResult.deltaL <= 0) {
+    return null
+  }
+
+  const ptRemainder = Math.max(0, swapResult.ptOut - depositResult.ptSpent)
+  if (ptRemainder > 1_000) {
+    return null
+  }
+
+  const totalSySpent = swapResult.sySpent + depositResult.sySpent
+
+  return {
+    ptConstraint,
+    tradeSySpent: swapResult.sySpent,
+    tradePtOut: swapResult.ptOut,
+    depositSySpent: depositResult.sySpent,
+    depositPtSpent: depositResult.ptSpent,
+    lpOut: depositResult.deltaL,
+    totalSySpent,
+    syRemainderAfterSwap: Math.max(0, syBudget - swapResult.sySpent),
+  }
+}
+
+function convertBaseToSyBudget(amountBase: number): number {
+  const baseAmount = Math.max(0, Math.floor(amountBase))
+  return baseAmount
+}
+
+function simulateBuyPtExactOutWrapper(
+  marketState: MarketThreeState,
+  syBudget: number,
+  ptConstraint: number,
+  syExchangeRate: number,
+): {
+  sySpent: number
+  ptOut: number
+  postMarketState?: MarketThreeState
+} {
+  const maxSyBudget = Math.max(0, Math.floor(syBudget))
+  const effectivePtOutTarget = Math.max(0, Math.floor(ptConstraint)) + 2
+
+  if (maxSyBudget === 0) {
+    return {
+      sySpent: 0,
+      ptOut: 0,
+      postMarketState: marketState,
+    }
+  }
+
+  const tryExactOut = (targetPtOut: number) => {
+    return simulateSwapExactOut(marketState, {
+      direction: SwapDirection.SyToPt,
+      amountOut: targetPtOut,
+      syExchangeRate,
+      isCurrentFlashSwap: true,
+      amountInConstraint: maxSyBudget,
+    })
+  }
+
+  // WrapperProvideLiquidityBase always executes exact-out with `pt_constraint + 2`.
+  // Do not fallback to lower exact-out targets here, otherwise client simulation can
+  // accept candidates that deterministically fail on-chain with InsufficientBudgetSY.
+  let bestQuote: ReturnType<typeof tryExactOut>
+  try {
+    bestQuote = tryExactOut(effectivePtOutTarget)
+  } catch {
+    throw new Error(
+      `Insufficient SY budget for wrapper exact-out simulation (budget=${maxSyBudget}, pt_constraint=${ptConstraint})`,
+    )
+  }
+
+  return {
+    sySpent: bestQuote.amountInConsumed,
+    ptOut: bestQuote.amountOut,
+    postMarketState: bestQuote.postMarketState,
+  }
+}