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

package/src/addLiquidity.ts

@@ -2,6 +2,8 @@
  * CLMM Add Liquidity simulation
  * Ported from exponent_clmm/src/state/market_three/helpers/add_liquidity.rs
  */
+import { Ticks } from "@exponent-labs/exponent-fetcher"
+
 import { simulateSwap, simulateSwapExactOut } from "./swapV2"
 import {
   AddLiquidityArgs,
@@ -12,15 +14,22 @@ import {
   MarketThreeState,
   SwapDirection,
 } from "./types"
-import { EffSnap, normalizedTimeRemaining, TicksWrapper } from "./utilsV2"
 import { findTickByKey, getSuccessorTickKey } from "./utils"
-import { Ticks } from "@exponent-labs/exponent-fetcher"
+import { EffSnap, TicksWrapper, normalizedTimeRemaining } from "./utilsV2"
 
 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 GAP_TOKEN_NEEDS = 20
+const MIN_SWAP_EXACT_OUT_SY_HEADROOM = 100
+const SWAP_EXACT_OUT_SY_HEADROOM = 100
+const SWAP_EXACT_OUT_HEADROOM_PT_THRESHOLD = 10_000_000
+const MIN_SWAP_AND_SUPPLY_SY_BUDGET = 1_000_000
+const FLASH_SY_POSITION_HEADROOM = 1_000
+const MAX_SWAP_AND_SUPPLY_UNDERSPEND_LAMPORTS = 1_000
+const MAX_SWAP_AND_SUPPLY_SIMULATED_OVERSPEND_LAMPORTS = 0
+const LARGE_SWAP_AND_SUPPLY_SY_BUDGET = 50_000_000_000
+const PT_ONLY_SWAP_EXACT_OUT_ESTIMATE_SLACK = 0
 
 const EMPTY_CROSSING_TICK_STATE: CrossingTickState = {
   principalPt: 0,
@@ -416,12 +425,12 @@ function simulateAccruePrincipalForDeposit(params: {
     return predecessor ?? candidateKey
   }
 
-  const visitIntervals = (startKey: number, priceStart: number, priceEnd: number, visitor: (params: {
-    leftKey: number
-    rightKey: number
-    leftPrice: number
-    rightPrice: number
-  }) => void) => {
+  const visitIntervals = (
+    startKey: number,
+    priceStart: number,
+    priceEnd: number,
+    visitor: (params: { leftKey: number; rightKey: number; leftPrice: number; rightPrice: number }) => void,
+  ) => {
     if (!(priceStart < priceEnd)) {
       return
     }
@@ -953,8 +962,7 @@ export function simulateWrapperProvideLiquidity(
     const priceEffUpper = snap.getEffectivePrice(upperPrice)
 
     // Step 3: Get crossing tick state (matches wrapper_provide_liquidity.rs)
-    const { crossingTickState, crossingTickPriceLeft, crossingTickPriceRight } =
-      getCrossingTickStateFromTicks(ticks)
+    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)
@@ -997,6 +1005,10 @@ export function simulateWrapperProvideLiquidity(
       syExchangeRate,
     })
 
+    if (!hasLpSupplyCapacity(marketState, depositResult.deltaL)) {
+      return null
+    }
+
     return {
       lpOut: depositResult.deltaL,
       ytOut: Math.floor(ytOut),
@@ -1047,9 +1059,9 @@ export function simulateSwapAndSupply(
     // 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)
+    const syBudget = convertBaseToSyBudget(amountBase, syExchangeRate)
 
-    if (syBudget <= 0) {
+    if (syBudget <= 0 || syBudget < MIN_SWAP_AND_SUPPLY_SY_BUDGET) {
       return {
         lpOut: 0,
         ptToBuy: 0,
@@ -1062,6 +1074,11 @@ export function simulateSwapAndSupply(
       }
     }
 
+    const flashSyAvailable = Math.max(0, Number(marketState.financials.syBalance) - FLASH_SY_POSITION_HEADROOM)
+    if (syBudget > flashSyAvailable) {
+      return null
+    }
+
     const MOCK_AMOUNT = 1e9
     const mockNeeds = simulateAddLiquidity(marketState, {
       lowerTick,
@@ -1070,8 +1087,6 @@ export function simulateSwapAndSupply(
       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
@@ -1103,6 +1118,15 @@ export function simulateSwapAndSupply(
         externalPtToBuy = Math.max(0, Math.floor(guessSwap.amountOut))
       }
     }
+    const baseSwapExactOutSyHeadroom =
+      externalPtToBuy >= SWAP_EXACT_OUT_HEADROOM_PT_THRESHOLD
+        ? SWAP_EXACT_OUT_SY_HEADROOM
+        : MIN_SWAP_EXACT_OUT_SY_HEADROOM
+    const swapExactOutSyHeadroom = syBudget >= LARGE_SWAP_AND_SUPPLY_SY_BUDGET ? 0 : baseSwapExactOutSyHeadroom
+    const simulatedOverspendTolerance =
+      syBudget >= LARGE_SWAP_AND_SUPPLY_SY_BUDGET ? MAX_SWAP_AND_SUPPLY_SIMULATED_OVERSPEND_LAMPORTS : 0
+    const searchBudget = Math.max(0, syBudget - swapExactOutSyHeadroom + simulatedOverspendTolerance)
+    const exactOutEstimateSlack = mockNeeds.sySpent === 0 ? PT_ONLY_SWAP_EXACT_OUT_ESTIMATE_SLACK : 0
 
     const candidateCache = new Map<number, SwapAndSupplyCandidate | null>()
     const evaluateCandidate = (ptConstraint: number) => {
@@ -1118,13 +1142,35 @@ export function simulateSwapAndSupply(
         syBudget,
         key,
         syExchangeRate,
+        exactOutEstimateSlack,
       )
       candidateCache.set(key, candidate)
       return candidate
     }
+
+    if (mockNeeds.ptSpent <= 0) {
+      const selected = evaluateCandidate(0)
+      if (!selected || !hasLpSupplyCapacity(marketState, selected.lpOut)) {
+        return null
+      }
+      if (!isSyDebitWithinTolerance(syBudget, selected.totalSySpent, simulatedOverspendTolerance)) {
+        return null
+      }
+
+      return {
+        lpOut: selected.lpOut,
+        ptToBuy: 0,
+        syConstraint: syBudget,
+        syForSwap: selected.tradeSySpent,
+        syRemainder: selected.syRemainderAfterSwap,
+        ptFromSwap: selected.tradePtOut,
+        syDeposited: selected.depositSySpent,
+        ptDeposited: selected.depositPtSpent,
+      }
+    }
+
     const ptCap = 1_000_000_000
     let bestUnderBudget: SwapAndSupplyCandidate | null = null
-    let leastOverspend: SwapAndSupplyCandidate | null = null
     const considerCandidate = (candidate: SwapAndSupplyCandidate | null) => {
       if (!candidate) {
         return
@@ -1139,14 +1185,6 @@ export function simulateSwapAndSupply(
         }
         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.
@@ -1200,14 +1238,21 @@ export function simulateSwapAndSupply(
       considerCandidate(evaluateCandidate(pt))
     }
 
-    const selected = bestUnderBudget ?? leastOverspend
+    const selected = bestUnderBudget
     if (!selected) {
-      throw new Error("Unable to simulate swap & supply for initial PT constraint")
+      throw new Error("Unable to simulate swap & supply within SY budget")
+    }
+    if (!hasLpSupplyCapacity(marketState, selected.lpOut)) {
+      return null
+    }
+    if (!isSyDebitWithinTolerance(syBudget, selected.totalSySpent, simulatedOverspendTolerance)) {
+      return null
     }
     if (process.env.DEBUG_SWAP_SUPPLY === "1") {
       console.log("[simulateSwapAndSupply]", {
         syBudget,
         searchBudget,
+        swapExactOutSyHeadroom,
         mockNeeds,
         externalPtToBuy,
         selected,
@@ -1248,6 +1293,7 @@ function simulateSwapAndSupplyForPtConstraint(
   syBudget: number,
   ptConstraint: number,
   syExchangeRate: number,
+  exactOutEstimateSlack: number,
 ): SwapAndSupplyCandidate | null {
   let swapResult: {
     sySpent: number
@@ -1261,6 +1307,7 @@ function simulateSwapAndSupplyForPtConstraint(
       syBudget,
       ptConstraint,
       syExchangeRate,
+      exactOutEstimateSlack,
     )
   } catch {
     // Budget insufficient for this PT constraint
@@ -1268,7 +1315,6 @@ function simulateSwapAndSupplyForPtConstraint(
   }
 
   const depositState = swapResult.postMarketState ?? marketState
-  const syAvailableForDeposit = Math.max(0, syBudget - swapResult.sySpent)
   const depositResult = simulateAddLiquidity(depositState, {
     lowerTick,
     upperTick,
@@ -1302,9 +1348,39 @@ function simulateSwapAndSupplyForPtConstraint(
   }
 }
 
-function convertBaseToSyBudget(amountBase: number): number {
+function convertBaseToSyBudget(amountBase: number, syExchangeRate: number): number {
   const baseAmount = Math.max(0, Math.floor(amountBase))
-  return baseAmount
+  if (syExchangeRate <= 0) {
+    return 0
+  }
+  return Math.floor(baseAmount / syExchangeRate)
+}
+
+function hasLpSupplyCapacity(marketState: MarketThreeState, deltaL: number): boolean {
+  const deltaLiquidity = Math.ceil(deltaL)
+  if (!Number.isFinite(deltaLiquidity) || deltaLiquidity < 0 || !Number.isSafeInteger(deltaLiquidity)) {
+    return false
+  }
+
+  const liquidityBalance = BigInt(marketState.financials.liquidityBalance.toString())
+  const maxLpSupply = BigInt(marketState.configurationOptions.maxLpSupply.toString())
+
+  return liquidityBalance + BigInt(deltaLiquidity) <= maxLpSupply
+}
+
+function isSyDebitWithinTolerance(
+  syBudget: number,
+  totalSySpent: number,
+  simulatedOverspendTolerance: number,
+): boolean {
+  const targetSyDebit = Math.max(0, Math.floor(syBudget))
+  const estimatedSyDebit = Math.max(0, Math.floor(totalSySpent))
+  const underSpendLamports = targetSyDebit - estimatedSyDebit
+  if (underSpendLamports < 0) {
+    return Math.abs(underSpendLamports) <= simulatedOverspendTolerance
+  }
+
+  return underSpendLamports <= MAX_SWAP_AND_SUPPLY_UNDERSPEND_LAMPORTS
 }
 
 function simulateBuyPtExactOutWrapper(
@@ -1312,12 +1388,14 @@ function simulateBuyPtExactOutWrapper(
   syBudget: number,
   ptConstraint: number,
   syExchangeRate: number,
+  exactOutEstimateSlack: number,
 ): {
   sySpent: number
   ptOut: number
   postMarketState?: MarketThreeState
 } {
   const maxSyBudget = Math.max(0, Math.floor(syBudget))
+  const exactOutSyConstraint = maxSyBudget + Math.max(0, Math.floor(exactOutEstimateSlack))
   const effectivePtOutTarget = Math.max(0, Math.floor(ptConstraint)) + 2
 
   if (maxSyBudget === 0) {
@@ -1334,7 +1412,7 @@ function simulateBuyPtExactOutWrapper(
       amountOut: targetPtOut,
       syExchangeRate,
       isCurrentFlashSwap: true,
-      amountInConstraint: maxSyBudget,
+      amountInConstraint: exactOutSyConstraint,
     })
   }
 

package/src/existingPositionEqualization.test.ts

@@ -0,0 +1,162 @@
+import { PublicKey } from "@solana/web3.js"
+
+import type { LpPositionCLMM, Ticks } from "@exponent-labs/exponent-fetcher"
+
+import {
+  computeExistingPositionBudgetEffect,
+  computeExistingPositionEqualization,
+  computeRequiredUserMaxForExistingPositionEqualization,
+} from "./existingPositionEqualization"
+
+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 makeTicks = (): Ticks => ({
+  currentTick: 1,
+  ticksTree: [
+    {
+      apyBasePoints: 63_000,
+      impliedRate: 1.063,
+      principalPt: 500n,
+      principalSy: 700n,
+      principalShareSupply: preciseRaw(100n),
+      liquidityNet: 0n,
+      liquidityGross: 0n,
+      feeGrowthOutsidePt: 0n,
+      feeGrowthOutsideSy: 0n,
+      farms: [],
+      emissions: [],
+      lastSplitEpoch: 0n,
+      frozenLiquidity: 0n,
+    },
+    {
+      apyBasePoints: 65_000,
+      impliedRate: 1.065,
+      principalPt: 0n,
+      principalSy: 0n,
+      principalShareSupply: 0n,
+      liquidityNet: 0n,
+      liquidityGross: 0n,
+      feeGrowthOutsidePt: 0n,
+      feeGrowthOutsideSy: 0n,
+      farms: [],
+      emissions: [],
+      lastSplitEpoch: 0n,
+      frozenLiquidity: 0n,
+    },
+  ],
+  market: PUBLIC_KEY,
+  feeGrowthIndexGlobalPt: 0n,
+  feeGrowthIndexGlobalSy: 0n,
+  currentPrefixSum: 0n,
+  currentSpotPrice: 1.062,
+})
+
+const makePosition = (): LpPositionCLMM => ({
+  owner: PUBLIC_KEY,
+  market: PUBLIC_KEY,
+  feeInsideLastPt: 0n,
+  feeInsideLastSy: 0n,
+  lpBalance: 200n,
+  tokensOwedSy: 0n,
+  tokensOwedPt: 0n,
+  lowerTickIdx: 1,
+  upperTickIdx: 2,
+  farms: [],
+  shareTrackers: [
+    {
+      tickIdx: 1,
+      rightTickIdx: 2,
+      splitEpoch: 0n,
+      lpShare: preciseRaw(100n),
+      emissions: [],
+    },
+  ],
+  crossingSplit: {
+    crossLeftIdx: 1,
+    crossRightIdx: 2,
+    lpBalanceCrossing: 100n,
+    isActive: true,
+  },
+})
+
+describe("existing position equalization", () => {
+  it("matches the contract add-direction budget math with integer rounding", () => {
+    const equalization = computeExistingPositionEqualization(makeTicks(), makePosition())
+
+    expect(equalization.sySpent).toBe(700n)
+    expect(equalization.ptSpent).toBe(500n)
+    expect(equalization.syReleased).toBe(0n)
+    expect(equalization.ptReleased).toBe(0n)
+    expect(equalization.plan).toEqual([
+      {
+        shareIndex: 0,
+        tickIdx: 1,
+        direction: "add",
+        shareDeltaRaw: preciseRaw(100n),
+        ptDelta: 500n,
+        syDelta: 700n,
+      },
+    ])
+  })
+
+  it("throws when user budgets cannot cover fixed equalization spend", () => {
+    expect(() =>
+      computeExistingPositionBudgetEffect({
+        ticks: makeTicks(),
+        position: makePosition(),
+        userMaxSy: 700n,
+        userMaxPt: 499n,
+      }),
+    ).toThrow("CrossingEqualizationInvariantViolated")
+
+    expect(
+      computeExistingPositionBudgetEffect({
+        ticks: makeTicks(),
+        position: makePosition(),
+        userMaxSy: 700n,
+        userMaxPt: 500n,
+      }),
+    ).toMatchObject({
+      effectiveMaxSy: 0n,
+      effectiveMaxPt: 0n,
+      fixedSySpent: 700n,
+      fixedPtSpent: 500n,
+    })
+  })
+
+  it("expands desired effective budgets to user-facing instruction inputs", () => {
+    expect(
+      computeRequiredUserMaxForExistingPositionEqualization({
+        ticks: makeTicks(),
+        position: makePosition(),
+        desiredEffectiveMaxSy: 10n,
+        desiredEffectiveMaxPt: 20n,
+      }),
+    ).toMatchObject({
+      userMaxSy: 710n,
+      userMaxPt: 520n,
+    })
+  })
+
+  it("returns a no-op for inactive crossing splits", () => {
+    const position = makePosition()
+    position.crossingSplit = {
+      crossLeftIdx: SENTINEL_TICK_INDEX,
+      crossRightIdx: SENTINEL_TICK_INDEX,
+      lpBalanceCrossing: 0n,
+      isActive: false,
+    }
+
+    expect(computeExistingPositionEqualization(makeTicks(), position)).toMatchObject({
+      sySpent: 0n,
+      ptSpent: 0n,
+      syReleased: 0n,
+      ptReleased: 0n,
+      plan: [],
+    })
+  })
+})