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

package/src/ytTrades.ts

@@ -6,20 +6,31 @@
  * - Sell YT: Merge PT+YT → SY, then buy PT from pool to repay
  */
 import { bisectSearch2 } from "./bisect"
-import { simulateSwap } from "./swap"
-import { MarketThreeState, SwapDirection, SwapOutcome } from "./types"
+import { simulateSwap, simulateSwapExactOut } from "./swapV2"
+import { MarketThreeState, SwapDirection, SwapOutcomeV2 } from "./types"
 
 /**
- * Helper function to convert PY to SY
- * @param syExchangeRate - The SY exchange rate
+ * Helper function to convert PY to SY (floor)
+ * @param syExchangeRate - The SY exchange rate (SY value in terms of underlying)
  * @param pyAmount - The PY (PT or YT) amount
- * @returns The equivalent SY amount
+ * @returns The equivalent SY amount (floored)
  */
 function pyToSy(syExchangeRate: number, pyAmount: number): number {
   if (syExchangeRate <= 0) return 0
   return Math.floor(pyAmount / syExchangeRate)
 }
 
+/**
+ * Helper function to convert PY to SY (ceil) - for when you need AT LEAST this much SY
+ * @param syExchangeRate - The SY exchange rate
+ * @param pyAmount - The PY (PT or YT) amount
+ * @returns The equivalent SY amount (ceiled)
+ */
+function pyToSyCeil(syExchangeRate: number, pyAmount: number): number {
+  if (syExchangeRate <= 0) return 0
+  return Math.ceil(pyAmount / syExchangeRate)
+}
+
 /**
  * Helper function to convert SY to PY
  * @param syExchangeRate - The SY exchange rate
@@ -75,14 +86,13 @@ export function simulateBuyYt(marketState: MarketThreeState, args: BuyYtSimulati
   const { ytOut, syExchangeRate, priceSpotLimit } = args
 
   // Calculate how much SY needs to be stripped to get the desired YT
-  // Add 1 to counter-act the flooring function when converting from PY to SY
-  const syToStrip = pyToSy(syExchangeRate, ytOut) + 1
+  // Use ceiling to ensure we strip enough SY
+  const syToStrip = pyToSyCeil(syExchangeRate, ytOut)
 
-  // Stripping gives approximately equal amounts of PT and YT
+  // Stripping gives equal amounts of PT and YT (1:1 ratio based on underlying value)
   const ptFromStrip = ytOut
 
   // Simulate selling the PT to get SY back
-  // Note: We use ytOut as the amount because PT out = YT out from the strip
   const swapResult = simulateSwap(marketState, {
     direction: SwapDirection.PtToSy,
     amountIn: ytOut,
@@ -117,6 +127,31 @@ export interface BuyYtWithSyInSimulationArgs {
   priceSpotLimit?: number
 }
 
+/**
+ * Helper to calculate net SY cost for a given YT amount
+ */
+function calculateNetSyCost(
+  marketState: MarketThreeState,
+  ytAmount: number,
+  syExchangeRate: number,
+  priceSpotLimit?: number,
+): { netSyCost: number; syToStrip: number; syFromPtSale: number } {
+  const syToStrip = pyToSyCeil(syExchangeRate, ytAmount)
+
+  const swapResult = simulateSwap(marketState, {
+    direction: SwapDirection.PtToSy,
+    amountIn: ytAmount,
+    priceSpotLimit,
+    syExchangeRate,
+    isCurrentFlashSwap: true,
+  })
+
+  const syFromPtSale = swapResult.amountOut
+  const netSyCost = syToStrip - syFromPtSale
+
+  return { netSyCost, syToStrip, syFromPtSale }
+}
+
 /**
  * Simulates buying YT tokens given a SY input amount
  *
@@ -139,130 +174,131 @@ export function simulateBuyYtWithSyIn(
 ): BuyYtSimulationResult {
   const { syIn, syExchangeRate, priceSpotLimit } = args
 
-  // Lower bound: Start very low since PT recycling allows buying much more YT than naive calculation
-  // The actual minimum depends on PT price (how much SY we get back from selling PT)
-  // If PT price is high (close to 1), we get most SY back, so we can buy much more YT
-  // Example: With 1000 SY and PT price 0.9:
-  //   - To get 5000 YT, strip 5000 SY → 5000 PT + 5000 YT
-  //   - Sell 5000 PT at 0.9 → 4500 SY back
-  //   - Net cost: 5000 - 4500 = 500 SY (way less than 1000!)
+  if (syIn <= 0) {
+    throw new Error("syIn must be positive")
+  }
+
+  if (syExchangeRate <= 0) {
+    throw new Error("syExchangeRate must be positive")
+  }
+
+  // Lower bound: minimum meaningful YT amount
   const minPossibleYt = 1
 
-  // Better initial upper bound estimate based on market liquidity
-  // Maximum possible YT is constrained by available PT liquidity in the market
-  const marketPtLiquidity = Number(marketState.financials.ptBalance)
+  // Buy-YT uses a flash-swap PT->SY path, so the tradeable size is determined by active
+  // tick liquidity, not by the idle PT balance stored on the market account.
   const marketSyLiquidity = Number(marketState.financials.syBalance)
 
-  // Conservative estimate: we can't buy more YT than there's PT in the market
-  // High multiplier needed because PT recycling amplifies buying power dramatically
-  // Formula: ytOut ≈ syIn / (1 - ptPrice)
-  // Examples: PT@0.99 → 100x, PT@0.95 → 20x, PT@0.90 → 10x, PT@0.80 → 5x
-  const liquidityBasedMax = Math.min(
-    marketPtLiquidity * 0.9, // 90% of PT liquidity to be safe
-    syToPy(syExchangeRate, syIn) * 100, // 100x to handle PT prices up to 0.99
-  )
+  // Calculate cost at minimum YT to verify function behavior
+  let minCost: number
+  try {
+    const minResult = calculateNetSyCost(marketState, minPossibleYt, syExchangeRate, priceSpotLimit)
+    minCost = minResult.netSyCost
+  } catch {
+    throw new Error("Market cannot support even minimum YT trade")
+  }
 
-  // Start with a reasonable initial guess (10x covers most realistic scenarios)
-  let maxPossibleYt = Math.min(syToPy(syExchangeRate, syIn) * 10, liquidityBasedMax)
-  let foundUpperBound = false
-  let lastValidCost = 0
+  // If minimum cost already exceeds syIn, we can't do this trade
+  if (minCost > syIn) {
+    throw new Error(`Trade too small: minimum YT (${minPossibleYt}) costs ${minCost} SY, but only ${syIn} SY available`)
+  }
 
-  // Use exponential search with better growth rate
-  for (let attempt = 0; attempt < 12; attempt++) {
-    try {
-      const syToStrip = pyToSy(syExchangeRate, maxPossibleYt) + 1
+  // Find upper bound using exponential search
+  // We need to find ytMax where netSyCost(ytMax) > syIn
+  let maxPossibleYt = Math.max(minPossibleYt + 1, syToPy(syExchangeRate, syIn)) // Start with naive estimate
+  let foundUpperBound = false
+  let lastValidYt = minPossibleYt
+  let lastValidCost = minCost
 
-      const swapResult = simulateSwap(marketState, {
-        direction: SwapDirection.PtToSy,
-        amountIn: maxPossibleYt,
-        priceSpotLimit,
-        syExchangeRate,
-        isCurrentFlashSwap: true,
-      })
+  // Exponential search to find upper bound
+  const maxAttempts = 40
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    const testYt = Math.max(minPossibleYt + 1, Math.floor(maxPossibleYt))
 
-      const syFromPtSale = swapResult.amountOut
-      const netSyCost = syToStrip - syFromPtSale
+    try {
+      const result = calculateNetSyCost(marketState, testYt, syExchangeRate, priceSpotLimit)
 
-      // If this costs more than syIn, we found our upper bound
-      if (netSyCost > syIn) {
+      if (result.netSyCost > syIn) {
+        // Found upper bound
+        maxPossibleYt = testYt
         foundUpperBound = true
         break
       }
 
-      lastValidCost = netSyCost
-
-      // Use adaptive growth rate based on how far we are from target
-      const costRatio = syIn / Math.max(netSyCost, 1)
-      const growthFactor = attempt < 3 ? 2.0 : Math.min(1.5, 1 + costRatio * 0.3)
+      // This YT amount is still affordable, save it
+      lastValidYt = testYt
+      lastValidCost = result.netSyCost
 
-      maxPossibleYt *= growthFactor
-
-      // Don't exceed liquidity constraints
-      if (maxPossibleYt > liquidityBasedMax) {
-        maxPossibleYt = liquidityBasedMax
-        foundUpperBound = true
+      // Increase estimate using adaptive growth
+      // The closer lastValidCost is to syIn, the smaller the growth factor
+      const remainingBudget = syIn - lastValidCost
+      const growthFactor = Math.max(1.5, Math.min(3, 1 + remainingBudget / Math.max(lastValidCost, 1)))
+      maxPossibleYt = Math.ceil(testYt * growthFactor)
+    } catch (error) {
+      // Swap failed - we've exceeded what the market can handle
+      if (lastValidYt > minPossibleYt) {
+        // Use binary search between lastValidYt and testYt to find exact upper bound
+        let searchLo = lastValidYt
+        let searchHi = testYt
+
+        for (let i = 0; i < 10; i++) {
+          const mid = Math.floor((searchLo + searchHi) / 2)
+          try {
+            const midResult = calculateNetSyCost(marketState, mid, syExchangeRate, priceSpotLimit)
+            if (midResult.netSyCost > syIn) {
+              searchHi = mid
+              foundUpperBound = true
+            } else {
+              searchLo = mid
+              lastValidYt = mid
+              lastValidCost = midResult.netSyCost
+            }
+          } catch {
+            searchHi = mid
+          }
+        }
+
+        if (foundUpperBound) {
+          maxPossibleYt = searchHi
+        } else {
+          // Couldn't find upper bound - trade exceeds market capacity
+          throw new Error(
+            `Trade exceeds market capacity: max affordable YT is ~${lastValidYt} (cost: ${lastValidCost}), ` +
+              `syIn = ${syIn}`,
+          )
+        }
         break
       }
-    } catch (error) {
-      // If simulation fails, we've exceeded market capacity
-      // Use last valid value with small buffer, ensuring it's > minPossibleYt
-      if (lastValidCost > 0) {
-        // Interpolate to find better upper bound
-        const estimatedMax = maxPossibleYt * 0.7 * (syIn / lastValidCost)
-        maxPossibleYt = Math.max(estimatedMax, minPossibleYt * 1.2)
-      } else {
-        // No valid cost yet, use a conservative upper bound
-        maxPossibleYt = Math.max(maxPossibleYt * 0.8, minPossibleYt * 1.5)
+
+      // Re-throw if we haven't found any valid YT amount
+      if (error instanceof Error) {
+        throw error
       }
-      foundUpperBound = true
-      break
+      throw new Error("Failed to find valid YT range")
     }
   }
 
   if (!foundUpperBound) {
-    throw new Error(`Could not find upper bound for YT amount. Market may have unusual price dynamics.`)
+    throw new Error(
+      `Could not find upper bound for YT amount after ${maxAttempts} attempts. ` +
+        `Last valid: ${lastValidYt} (cost: ${lastValidCost}), syIn: ${syIn}`,
+    )
   }
 
-  // Final safety check: ensure maxPossibleYt > minPossibleYt
+  // Sanity check bounds
   if (maxPossibleYt <= minPossibleYt) {
-    maxPossibleYt = minPossibleYt * 2
+    throw new Error(`Invalid bounds: min=${minPossibleYt}, max=${maxPossibleYt}`)
   }
 
   // Use bisection search to find the ytOut that results in netSyCost = syIn
-  // Adaptive epsilon based on input size for better precision scaling
-  const adaptiveEpsilon = Math.max(0.01, syIn * 0.0001)
-
-  // Reduce max iterations since we have better bounds
-  const maxIterations = 10000
-
-  // Debug info for bounds validation
-  if (maxPossibleYt <= minPossibleYt) {
-    throw new Error(
-      `Invalid bisection bounds for buy YT. ` +
-        `Min: ${minPossibleYt}, Max: ${maxPossibleYt}, ` +
-        `SyIn: ${syIn}, SyExchangeRate: ${syExchangeRate}, ` +
-        `MarketPtBalance: ${marketPtLiquidity}, MarketSyBalance: ${marketSyLiquidity}`,
-    )
-  }
+  // Epsilon should be small relative to the expected result magnitude
+  const adaptiveEpsilon = Math.max(1, syIn * 0.0001)
+  const maxIterations = 100 // Bisection converges fast with good bounds
 
   const ytOut = bisectSearch2(
     (ytGuess: number) => {
-      // Calculate the cost for this ytGuess
-      const syToStrip = pyToSy(syExchangeRate, ytGuess) + 1
-
-      const swapResult = simulateSwap(marketState, {
-        direction: SwapDirection.PtToSy,
-        amountIn: ytGuess,
-        priceSpotLimit,
-        syExchangeRate,
-        isCurrentFlashSwap: true,
-      })
-
-      const syFromPtSale = swapResult.amountOut
-      const netSyCost = syToStrip - syFromPtSale
-
-      // Return the difference between actual cost and target syIn
-      return netSyCost - syIn
+      const result = calculateNetSyCost(marketState, ytGuess, syExchangeRate, priceSpotLimit)
+      return result.netSyCost - syIn
     },
     minPossibleYt,
     maxPossibleYt,
@@ -271,19 +307,37 @@ export function simulateBuyYtWithSyIn(
   )
 
   if (ytOut === null) {
+    // This shouldn't happen if bounds are correct
+    // Provide detailed debug info
+    const minResult = calculateNetSyCost(marketState, minPossibleYt, syExchangeRate, priceSpotLimit)
+    let maxResult: { netSyCost: number } | null = null
+    try {
+      maxResult = calculateNetSyCost(marketState, maxPossibleYt, syExchangeRate, priceSpotLimit)
+    } catch {
+      // Max might fail
+    }
+
     throw new Error(
-      `Failed to converge on correct YT amount. ` +
-        `Search range: [${minPossibleYt}, ${maxPossibleYt}], ` +
-        `Epsilon: ${adaptiveEpsilon}`,
+      `Failed to converge: bounds [${minPossibleYt}, ${maxPossibleYt}], ` +
+        `f(min)=${minResult.netSyCost - syIn}, f(max)=${maxResult ? maxResult.netSyCost - syIn : "error"}, ` +
+        `syIn=${syIn}, epsilon=${adaptiveEpsilon}`,
     )
   }
 
-  // Now calculate the full result with the found ytOut
-  return simulateBuyYt(marketState, {
-    ytOut,
+  // Return full result using the found ytOut
+  const result = simulateBuyYt(marketState, {
+    ytOut: Math.floor(ytOut), // Floor to ensure we don't over-promise
     syExchangeRate,
     priceSpotLimit,
   })
+
+  if (marketSyLiquidity * syExchangeRate < result.ytOut * 2) {
+    throw new Error(
+      `Insufficient SY liquidity in the market. Required: ${result.ytOut * 2}, Available: ${marketSyLiquidity}`,
+    )
+  }
+
+  return result
 }
 
 export interface SellYtSimulationArgs {
@@ -293,6 +347,13 @@ export interface SellYtSimulationArgs {
   syExchangeRate: number
   /** Optional spot price limit (anti-sandwich) */
   priceSpotLimit?: number
+  /**
+   * Safety margin in basis points to apply to the expected output.
+   * This can be used as an optional conservative buffer on top of the simulated output.
+   *
+   * Default: 0 (no buffer). Set to a positive value to reduce reported output.
+   */
+  safetyMarginBps?: number
 }
 
 export interface SellYtSimulationResult {
@@ -328,84 +389,42 @@ export interface SellYtSimulationResult {
  * @returns Simulation result with net SY received
  */
 export function simulateSellYt(marketState: MarketThreeState, args: SellYtSimulationArgs): SellYtSimulationResult {
-  const { ytIn, syExchangeRate, priceSpotLimit } = args
+  const { ytIn, syExchangeRate, priceSpotLimit, safetyMarginBps = 0 } = args
 
-  // Check if there's sufficient PT liquidity
-  // The market needs at least 2x the YT amount in PT
-  if (marketState.financials.ptBalance < ytIn * 2) {
-    throw new Error(
-      `Insufficient PT liquidity in the market. Required: ${ytIn * 2}, Available: ${marketState.financials.ptBalance}`,
-    )
+  if (ytIn <= 0) {
+    throw new Error("ytIn must be positive")
   }
 
-  // Merging PT + YT gives back the original SY
-  // The amount of PT needed equals ytIn (1:1 ratio)
-  const syFromMerge = pyToSy(syExchangeRate, ytIn)
-
-  const ptNeeded = ytIn
-
-  const upperBoundSwap = simulateSwap(marketState, {
-    direction: SwapDirection.SyToPt,
-    amountIn: syFromMerge,
-    priceSpotLimit,
-    syExchangeRate,
-    isCurrentFlashSwap: true,
-  })
-
-  // Check that we can buy enough PT from CLMM
-  if (upperBoundSwap.amountOut < ptNeeded) {
-    throw new Error(
-      `Cannot buy enough PT with available SY. Need ${ytIn} PT but can only afford ${upperBoundSwap.amountOut} PT`,
-    )
+  // Check if there's sufficient PT liquidity
+  const marketPtBalance = Number(marketState.financials.ptBalance)
+  if (marketPtBalance < ytIn * 2) {
+    throw new Error(`Insufficient PT liquidity in the market. Required: ${ytIn * 2}, Available: ${marketPtBalance}`)
   }
 
-  // Better initial bounds for bisection
-  // We know the upper bound from the check above, and we can estimate a better lower bound
-  // based on the current price
-  const estimatedLowerBound = Math.min(syFromMerge * 0.5, syFromMerge * 0.9) // Start from 50% of max, but not too close to upper
-
-  // Adaptive epsilon based on PT needed
-  const adaptiveEpsilon = Math.max(0.01, ptNeeded * 0.0001)
-
-  // Safety check: ensure lower bound is less than upper bound
-  const safeLowerBound = Math.min(estimatedLowerBound, syFromMerge * 0.95)
-  const safeUpperBound = syFromMerge
+  // Merging PT + YT gives back the original SY (floor since you can't get fractional SY)
+  const syFromMerge = pyToSy(syExchangeRate, ytIn)
 
-  if (safeLowerBound >= safeUpperBound) {
-    throw new Error(`Invalid bisection bounds for sell YT. Lower: ${safeLowerBound}, Upper: ${safeUpperBound}`)
+  if (syFromMerge <= 0) {
+    throw new Error(`Trade too small: merging ${ytIn} YT yields 0 SY`)
   }
 
-  const syToSpend = bisectSearch2(
-    (syGuess: number) => {
-      const swapResult = simulateSwap(marketState, {
-        direction: SwapDirection.SyToPt,
-        amountIn: syGuess,
-        priceSpotLimit,
-        syExchangeRate,
-        isCurrentFlashSwap: true,
-      })
-
-      return swapResult.amountOut - ptNeeded
-    },
-    safeLowerBound,
-    safeUpperBound,
-    adaptiveEpsilon,
-    100, // Reduced iterations with better bounds
-  )
-
-  if (syToSpend === null) {
-    throw new Error("Failed to converge on correct SY amount using bisection search")
-  }
+  // On-chain uses pt_constraint + 2 to account for rounding, so we match that behavior
+  const ptNeeded = ytIn + 2
 
-  const swapResult = simulateSwap(marketState, {
+  // Match on-chain SellYt exactly: TradePtExactOut with pt_target = yt_in + 2 and SY budget = syFromMerge
+  const swapResult = simulateSwapExactOut(marketState, {
     direction: SwapDirection.SyToPt,
-    amountIn: syToSpend,
+    amountOut: ptNeeded,
     priceSpotLimit,
     syExchangeRate,
     isCurrentFlashSwap: true,
+    amountInConstraint: syFromMerge,
   })
 
-  const netSyReceived = syFromMerge - swapResult.amountInConsumed
+  // Optional conservative output buffer.
+  const rawNetSyReceived = syFromMerge - swapResult.amountInConsumed
+  const safetyDeduction = safetyMarginBps > 0 ? Math.ceil((rawNetSyReceived * safetyMarginBps) / 10000) : 0
+  const netSyReceived = rawNetSyReceived - safetyDeduction
 
   return {
     ytIn,