@velocity-exchange/sdk 0.3.0 → 0.4.0

package/lib/node/math/amm.js

@@ -9,6 +9,15 @@ const utils_1 = require("./utils");
 const orders_1 = require("./orders");
 const repeg_1 = require("./repeg");
 const oracles_1 = require("./oracles");
+/**
+ * Solves for the `pegMultiplier` that would make the AMM's constant-product price equal
+ * `targetPrice` at the current reserves, mirroring `calculate_peg_from_target_price` in
+ * `vlp/amm/math/repeg.rs`. Rounds to the nearest peg unit and floors at 1.
+ * @param targetPrice Desired price, PRICE_PRECISION (1e6).
+ * @param baseAssetReserve AMM base asset reserve, AMM_RESERVE_PRECISION (1e9).
+ * @param quoteAssetReserve AMM quote asset reserve, AMM_RESERVE_PRECISION (1e9).
+ * @returns Peg multiplier that yields `targetPrice`, PEG_PRECISION (1e6), never below 1.
+ */
 function calculatePegFromTargetPrice(targetPrice, baseAssetReserve, quoteAssetReserve) {
     return anchor_1.BN.max(targetPrice
         .mul(baseAssetReserve)
@@ -17,6 +26,24 @@ function calculatePegFromTargetPrice(targetPrice, baseAssetReserve, quoteAssetRe
         .div(numericConstants_1.PRICE_DIV_PEG), numericConstants_1.ONE);
 }
 exports.calculatePegFromTargetPrice = calculatePegFromTargetPrice;
+/**
+ * Computes the oracle-implied target price/peg for a repeg and the quote budget available to
+ * fund it, mirroring `calculate_optimal_peg_and_budget` in `vlp/amm/math/repeg.rs`. The
+ * budget is the AMM's own retained equity (`max(0, totalFeeMinusDistributions)`) — there is
+ * no separate protocol floor post-isolation. If that budget can't cover a direct repeg to
+ * the oracle price, the target is pulled back to the edge of half the market's max spread
+ * instead (a partial repeg that costs exactly the recomputed budget), and
+ * `checkLowerBound` is set to `false` since that partial move is unconditionally affordable
+ * by construction. `checkLowerBound` is also `false` when the budget is exactly zero (no
+ * equity to spend at all — `calculateUpdatedAMM` uses this to know whether it must reject
+ * the whole update or can proceed with the recomputed, always-affordable target).
+ * @param amm AMM state (reserves, `pegMultiplier`, `totalFeeMinusDistributions`, `maxSpread`).
+ * @param mmOraclePriceData Current MM oracle price data; `price` is the desired target.
+ * @returns `[targetPrice, newPeg, budget, checkLowerBound]`: `targetPrice`/`newPeg` are
+ *   PRICE_PRECISION (1e6) / PEG_PRECISION (1e6) respectively; `budget` is the quote amount
+ *   available to spend, QUOTE_PRECISION (1e6); `checkLowerBound` tells the caller whether it
+ *   must still verify the repeg doesn't push `totalFeeMinusDistributions` negative.
+ */
 function calculateOptimalPegAndBudget(amm, mmOraclePriceData) {
     const reservePriceBefore = calculatePrice(amm.baseAssetReserve, amm.quoteAssetReserve, amm.pegMultiplier);
     const targetPrice = mmOraclePriceData.price;
@@ -57,10 +84,26 @@ function calculateOptimalPegAndBudget(amm, mmOraclePriceData) {
     return [targetPrice, newPeg, budget, checkLowerBound];
 }
 exports.calculateOptimalPegAndBudget = calculateOptimalPegAndBudget;
+/**
+ * Determines the full curve update (repeg cost, K scale factor, new peg) for `amm` against
+ * the current oracle price, mirroring the "use full budget peg" fallback path of `adjust_amm`
+ * in `vlp/amm/math/repeg.rs`. Starts from `calculateOptimalPegAndBudget`'s target/budget; if
+ * the direct repeg cost meets or exceeds that budget, shrinks `sqrtK` by 0.1% (999/1000) via
+ * `calculateAdjustKCost` first to free up additional budget, then re-solves for the peg with
+ * `calculateBudgetedPeg` using the combined budget.
+ * @param amm AMM state to evaluate a curve update for.
+ * @param mmOraclePriceData Current MM oracle price data.
+ * @returns `[prePegCost, pKNumer, pKDenom, newPeg, checkLowerBound]`: `prePegCost` is the
+ *   quote cost of the full update, QUOTE_PRECISION (1e6); `pKNumer`/`pKDenom` are the sqrtK
+ *   scale factor (999/1000 if K was shrunk, else 1/1); `newPeg` is PEG_PRECISION (1e6);
+ *   `checkLowerBound` is forwarded from `calculateOptimalPegAndBudget` and tells
+ *   `calculateUpdatedAMM` whether it must still verify affordability against
+ *   `totalFeeMinusDistributions`.
+ */
 function calculateNewAmm(amm, mmOraclePriceData) {
     let pKNumer = new anchor_1.BN(1);
     let pKDenom = new anchor_1.BN(1);
-    const [targetPrice, _newPeg, budget, _checkLowerBound] = calculateOptimalPegAndBudget(amm, mmOraclePriceData);
+    const [targetPrice, _newPeg, budget, checkLowerBound] = calculateOptimalPegAndBudget(amm, mmOraclePriceData);
     let prePegCost = (0, repeg_1.calculateRepegCost)(amm, _newPeg);
     let newPeg = _newPeg;
     if (prePegCost.gte(budget) && prePegCost.gt(numericConstants_1.ZERO)) {
@@ -81,15 +124,43 @@ function calculateNewAmm(amm, mmOraclePriceData) {
         newPeg = (0, repeg_1.calculateBudgetedPeg)(newAmm, prePegCost, targetPrice);
         prePegCost = (0, repeg_1.calculateRepegCost)(newAmm, newPeg);
     }
-    return [prePegCost, pKNumer, pKDenom, newPeg];
+    return [prePegCost, pKNumer, pKDenom, newPeg, checkLowerBound];
 }
 exports.calculateNewAmm = calculateNewAmm;
+/**
+ * Returns a copy of `amm` with its curve (peg, reserves, sqrtK) repegged/updated to the
+ * current oracle price, or `amm` unchanged if no update applies. Mirrors the program's
+ * curve-update gating: a no-op if `curveUpdateIntensity == 0`, if `mmOraclePriceData` is
+ * omitted, or if the oracle price is non-positive (mirrors
+ * `is_oracle_valid_for_action(..., UpdateAMMCurve)` — only a non-positive price invalidates
+ * the update here). **Affordability gate:** when `calculateNewAmm`'s `checkLowerBound` is
+ * true and debiting the computed cost from `totalFeeMinusDistributions` would push it
+ * negative, the update is rejected wholesale and `amm` is returned unchanged — the AMM will
+ * never spend equity it doesn't have on a repeg. When the update proceeds, both
+ * `totalFeeMinusDistributions` and `netRevenueSinceLastFunding` are debited by the repeg
+ * cost.
+ * @param amm AMM state to update.
+ * @param mmOraclePriceData Current MM oracle price data; omit to skip the update entirely.
+ * @returns Updated `AMM` (new object), or the original `amm` reference if no update applies or the affordability gate rejects it.
+ */
 function calculateUpdatedAMM(amm, mmOraclePriceData) {
     if (amm.curveUpdateIntensity == 0 || mmOraclePriceData === undefined) {
         return amm;
     }
+    // mirrors is_oracle_valid_for_action(..., UpdateAMMCurve): only a
+    // non-positive oracle price invalidates the curve update
+    if (mmOraclePriceData.price.lte(numericConstants_1.ZERO)) {
+        return amm;
+    }
     const newAmm = Object.assign({}, amm);
-    const [prepegCost, pKNumer, pKDenom, newPeg] = calculateNewAmm(amm, mmOraclePriceData);
+    const [prepegCost, pKNumer, pKDenom, newPeg, checkLowerBound] = calculateNewAmm(amm, mmOraclePriceData);
+    if (prepegCost.gt(numericConstants_1.ZERO)) {
+        const newTotalFeeMinusDistributions = amm.totalFeeMinusDistributions.sub(prepegCost);
+        if (checkLowerBound && newTotalFeeMinusDistributions.lt(numericConstants_1.ZERO)) {
+            // affordability floor rejected the debit: passthrough, unchanged
+            return amm;
+        }
+    }
     newAmm.baseAssetReserve = newAmm.baseAssetReserve.mul(pKNumer).div(pKDenom);
     newAmm.sqrtK = newAmm.sqrtK.mul(pKNumer).div(pKDenom);
     const invariant = newAmm.sqrtK.mul(newAmm.sqrtK);
@@ -107,6 +178,18 @@ function calculateUpdatedAMM(amm, mmOraclePriceData) {
     return newAmm;
 }
 exports.calculateUpdatedAMM = calculateUpdatedAMM;
+/**
+ * Repegs `amm` to the current oracle price (`calculateUpdatedAMM`) and returns the
+ * one-sided spread reserves (bid reserves for `short`, ask reserves for `long`) plus the
+ * post-update `sqrtK`/peg — the reserves a trade closing/opening in `direction` would
+ * actually execute against.
+ * @param amm AMM state to update and derive spread reserves from.
+ * @param marketStats Market stats needed for spread and reference-price-offset calculation.
+ * @param direction Which side's spread reserves to return.
+ * @param mmOraclePriceData Current MM oracle price data, forwarded to `calculateUpdatedAMM`.
+ * @param latestSlot Current slot, forwarded for reference-price-offset smoothing.
+ * @returns `baseAssetReserve`/`quoteAssetReserve` for the requested side (AMM_RESERVE_PRECISION, 1e9), and the post-update `sqrtK`/`newPeg` (AMM_RESERVE_PRECISION 1e9 / PEG_PRECISION 1e6).
+ */
 function calculateUpdatedAMMSpreadReserves(amm, marketStats, direction, mmOraclePriceData, latestSlot) {
     const newAmm = calculateUpdatedAMM(amm, mmOraclePriceData);
     const [shortReserves, longReserves] = calculateSpreadReserves(newAmm, marketStats, mmOraclePriceData, undefined, latestSlot);
@@ -122,6 +205,16 @@ function calculateUpdatedAMMSpreadReserves(amm, marketStats, direction, mmOracle
     return result;
 }
 exports.calculateUpdatedAMMSpreadReserves = calculateUpdatedAMMSpreadReserves;
+/**
+ * Returns the AMM's current bid and ask prices, computed from its spread reserves
+ * (`calculateSpreadReserves`) after optionally repegging to the oracle price first.
+ * @param amm AMM state to price.
+ * @param marketStats Market stats needed for spread calculation.
+ * @param mmOraclePriceData Current MM oracle price data; used both to repeg (if `withUpdate`) and to compute the spread.
+ * @param withUpdate If true (default), repegs `amm` to the oracle price (`calculateUpdatedAMM`) before pricing; if false, prices the AMM's stored reserves as-is.
+ * @param latestSlot Current slot, forwarded for reference-price-offset smoothing.
+ * @returns `[bidPrice, askPrice]`, both PRICE_PRECISION (1e6).
+ */
 function calculateBidAskPrice(amm, marketStats, mmOraclePriceData, withUpdate = true, latestSlot) {
     let newAmm;
     if (withUpdate) {
@@ -137,12 +230,14 @@ function calculateBidAskPrice(amm, marketStats, mmOraclePriceData, withUpdate =
 }
 exports.calculateBidAskPrice = calculateBidAskPrice;
 /**
- * Calculates a price given an arbitrary base and quote amount (they must have the same precision)
- *
- * @param baseAssetReserves
- * @param quoteAssetReserves
- * @param pegMultiplier
- * @returns price : Precision PRICE_PRECISION
+ * Computes the constant-product price implied by a pair of AMM reserves and a peg multiplier:
+ * `quoteAssetReserves * pegMultiplier / baseAssetReserves`, converted to `PRICE_PRECISION`.
+ * `baseAssetReserves` and `quoteAssetReserves` must be the same precision (typically both
+ * `AMM_RESERVE_PRECISION`, 1e9) — this is a pure ratio, not tied to any specific reserve field.
+ * @param baseAssetReserves Base reserve amount, same precision as `quoteAssetReserves`.
+ * @param quoteAssetReserves Quote reserve amount, same precision as `baseAssetReserves`.
+ * @param pegMultiplier Peg multiplier to scale the ratio by, PEG_PRECISION (1e6).
+ * @returns Price, PRICE_PRECISION (1e6); zero if `baseAssetReserves` is zero.
  */
 function calculatePrice(baseAssetReserves, quoteAssetReserves, pegMultiplier) {
     if (baseAssetReserves.abs().lte(numericConstants_1.ZERO)) {
@@ -156,13 +251,16 @@ function calculatePrice(baseAssetReserves, quoteAssetReserves, pegMultiplier) {
 }
 exports.calculatePrice = calculatePrice;
 /**
- * Calculates what the amm reserves would be after swapping a quote or base asset amount.
- *
- * @param amm
- * @param inputAssetType
- * @param swapAmount
- * @param swapDirection
- * @returns quoteAssetReserve and baseAssetReserve after swap. : Precision AMM_RESERVE_PRECISION
+ * Calculates what the AMM's reserves would be after swapping a quote or base asset amount
+ * against its constant-product curve (`sqrtK^2 = baseAssetReserve * quoteAssetReserve`). When
+ * `inputAssetType` is `'quote'`, `swapAmount` is first converted from `QUOTE_PRECISION`-scale
+ * quote units into the AMM's own quote-reserve precision via the peg multiplier before being
+ * applied.
+ * @param amm AMM state (`pegMultiplier`, `quoteAssetReserve`, `sqrtK`, `baseAssetReserve`).
+ * @param inputAssetType Which side `swapAmount` is denominated in.
+ * @param swapAmount Amount being swapped, QUOTE_PRECISION (1e6) if `inputAssetType` is `'quote'`, else AMM_RESERVE_PRECISION (1e9); must be non-negative.
+ * @param swapDirection Whether `swapAmount` is added to or removed from the AMM's reserve on the input side.
+ * @returns `[quoteAssetReserve, baseAssetReserve]` after the swap, both AMM_RESERVE_PRECISION (1e9).
  */
 function calculateAmmReservesAfterSwap(amm, inputAssetType, swapAmount, swapDirection) {
     (0, assert_1.assert)(swapAmount.gte(numericConstants_1.ZERO), 'swapAmount must be greater than 0');
@@ -180,6 +278,17 @@ function calculateAmmReservesAfterSwap(amm, inputAssetType, swapAmount, swapDire
     return [newQuoteAssetReserve, newBaseAssetReserve];
 }
 exports.calculateAmmReservesAfterSwap = calculateAmmReservesAfterSwap;
+/**
+ * Calculates how much base asset the AMM could still absorb on each side before hitting its
+ * configured reserve bounds — the AMM's own "open interest" available to bids/asks. Zeroes
+ * out a side if its available room is less than half a step size (dust, not fillable), when
+ * `stepSize` is provided.
+ * @param baseAssetReserve AMM's current base asset reserve, AMM_RESERVE_PRECISION (1e9).
+ * @param minBaseAssetReserve AMM's minimum allowed base asset reserve, AMM_RESERVE_PRECISION (1e9).
+ * @param maxBaseAssetReserve AMM's maximum allowed base asset reserve, AMM_RESERVE_PRECISION (1e9).
+ * @param stepSize Optional order step size, AMM_RESERVE_PRECISION (1e9), used to zero out dust amounts.
+ * @returns `[openBids, openAsks]`: `openBids` non-negative (room to absorb more longs), `openAsks` non-positive (room to absorb more shorts), both AMM_RESERVE_PRECISION (1e9).
+ */
 function calculateMarketOpenBidAsk(baseAssetReserve, minBaseAssetReserve, maxBaseAssetReserve, stepSize) {
     // open orders
     let openAsks;
@@ -205,6 +314,17 @@ function calculateMarketOpenBidAsk(baseAssetReserve, minBaseAssetReserve, maxBas
     return [openBids, openAsks];
 }
 exports.calculateMarketOpenBidAsk = calculateMarketOpenBidAsk;
+/**
+ * Measures how skewed the AMM's net inventory is relative to the thinner of its two
+ * remaining liquidity sides, as a fraction: `|baseAssetAmountWithAmm| / minSideLiquidity`,
+ * capped at 100%. Feeds `calculateInventoryScale`'s spread widening — a fuller inventory
+ * relative to available liquidity widens the paying side's spread more.
+ * @param baseAssetAmountWithAmm AMM's net inventory, AMM_RESERVE_PRECISION (1e9, signed).
+ * @param baseAssetReserve AMM's current base asset reserve, AMM_RESERVE_PRECISION (1e9).
+ * @param minBaseAssetReserve AMM's minimum allowed base asset reserve, AMM_RESERVE_PRECISION (1e9).
+ * @param maxBaseAssetReserve AMM's maximum allowed base asset reserve, AMM_RESERVE_PRECISION (1e9).
+ * @returns Inventory-to-min-side-liquidity ratio, PERCENTAGE_PRECISION (1e6), capped at 100%.
+ */
 function calculateInventoryLiquidityRatio(baseAssetAmountWithAmm, baseAssetReserve, minBaseAssetReserve, maxBaseAssetReserve) {
     // inventory skew
     const [openBids, openAsks] = calculateMarketOpenBidAsk(baseAssetReserve, minBaseAssetReserve, maxBaseAssetReserve);
@@ -216,6 +336,17 @@ function calculateInventoryLiquidityRatio(baseAssetAmountWithAmm, baseAssetReser
     return inventoryScaleBN;
 }
 exports.calculateInventoryLiquidityRatio = calculateInventoryLiquidityRatio;
+/**
+ * Same shape as `calculateInventoryLiquidityRatio` but normalizes by the *average* of the
+ * two liquidity sides rather than the thinner side, used specifically as the liquidity
+ * fraction input to `calculateReferencePriceOffset` (whose offset should react to overall
+ * inventory pressure, not just the constraining side).
+ * @param baseAssetAmountWithAmm AMM's net inventory, AMM_RESERVE_PRECISION (1e9, signed).
+ * @param baseAssetReserve AMM's current base asset reserve, AMM_RESERVE_PRECISION (1e9).
+ * @param minBaseAssetReserve AMM's minimum allowed base asset reserve, AMM_RESERVE_PRECISION (1e9).
+ * @param maxBaseAssetReserve AMM's maximum allowed base asset reserve, AMM_RESERVE_PRECISION (1e9).
+ * @returns Inventory-to-average-side-liquidity ratio, PERCENTAGE_PRECISION (1e6), capped at 100%.
+ */
 function calculateInventoryLiquidityRatioForReferencePriceOffset(baseAssetAmountWithAmm, baseAssetReserve, minBaseAssetReserve, maxBaseAssetReserve) {
     // inventory skew
     const [openBids, openAsks] = calculateMarketOpenBidAsk(baseAssetReserve, minBaseAssetReserve, maxBaseAssetReserve);
@@ -227,6 +358,19 @@ function calculateInventoryLiquidityRatioForReferencePriceOffset(baseAssetAmount
     return inventoryScaleBN;
 }
 exports.calculateInventoryLiquidityRatioForReferencePriceOffset = calculateInventoryLiquidityRatioForReferencePriceOffset;
+/**
+ * Multiplier applied to the paying side's spread based on inventory skew
+ * (`calculateInventoryLiquidityRatio`), scaled so the multiplier never exceeds the greater of
+ * a fixed 10x cap or the ratio between the market's max spread and the current directional
+ * spread. Returns `1` (no scaling) for a flat AMM.
+ * @param baseAssetAmountWithAmm AMM's net inventory, AMM_RESERVE_PRECISION (1e9, signed).
+ * @param baseAssetReserve AMM's current base asset reserve, AMM_RESERVE_PRECISION (1e9).
+ * @param minBaseAssetReserve AMM's minimum allowed base asset reserve, AMM_RESERVE_PRECISION (1e9).
+ * @param maxBaseAssetReserve AMM's maximum allowed base asset reserve, AMM_RESERVE_PRECISION (1e9).
+ * @param directionalSpread The spread (in `BID_ASK_SPREAD_PRECISION` bps-like units) on the inventory's own side, before this scale is applied.
+ * @param maxSpread Market's configured max spread, `BID_ASK_SPREAD_PRECISION`-scaled units.
+ * @returns Plain multiplier (not BN) to apply to the directional spread, `>= 1`.
+ */
 function calculateInventoryScale(baseAssetAmountWithAmm, baseAssetReserve, minBaseAssetReserve, maxBaseAssetReserve, directionalSpread, maxSpread) {
     if (baseAssetAmountWithAmm.eq(numericConstants_1.ZERO)) {
         return 1;
@@ -240,6 +384,28 @@ function calculateInventoryScale(baseAssetAmountWithAmm, baseAssetReserve, minBa
     return inventoryScaleCapped;
 }
 exports.calculateInventoryScale = calculateInventoryScale;
+/**
+ * Calculates the AMM's reference-price offset — a persistent skew applied to both bid and
+ * ask reserves (on top of the volatility/inventory spread) that lets the AMM's quoted price
+ * drift slightly off the raw oracle price when inventory and recent funding both point the
+ * same direction. Averages three clamped mark/oracle premium estimates (1-minute, 1-hour,
+ * and a 24h-funding-implied premium net of the `FUNDING_RATE_OFFSET_DENOMINATOR` baseline —
+ * this baseline subtraction is what keeps the offset from double-counting the funding rate's
+ * own built-in offset), converts to a price-relative percentage, then scales by half the
+ * (signed) inventory `liquidityFraction`. Zeroed out entirely when inventory skew and the
+ * premium disagree in sign (`!sigNum(liquidityFraction).eq(sigNum(markPremiumAvgPct))`) —
+ * the offset only applies when it would reduce net exposure, never to compound it. Returns
+ * zero immediately if there's no funding history or no inventory skew.
+ * @param reservePrice Current AMM reserve price, PRICE_PRECISION (1e6).
+ * @param last24hAvgFundingRate Market's 24h average funding rate, FUNDING_RATE_PRECISION-buffer-scaled (divided internally by `FUNDING_RATE_BUFFER_PRECISION`).
+ * @param liquidityFraction Signed inventory liquidity fraction (see `calculateInventoryLiquidityRatioForReferencePriceOffset`, sign-adjusted for inventory direction), PERCENTAGE_PRECISION (1e6).
+ * @param oracleTwapFast 5-minute oracle TWAP, PRICE_PRECISION (1e6).
+ * @param markTwapFast 5-minute mark TWAP, PRICE_PRECISION (1e6).
+ * @param oracleTwapSlow 1-hour oracle TWAP, PRICE_PRECISION (1e6).
+ * @param markTwapSlow 1-hour mark TWAP, PRICE_PRECISION (1e6).
+ * @param maxOffsetPct Maximum allowed offset, PERCENTAGE_PRECISION (1e6) fraction-of-price units — both the intermediate premium clamps and the final result are bounded by this.
+ * @returns Reference price offset, PERCENTAGE_PRECISION (1e6, signed), clamped to `±maxOffsetPct`.
+ */
 function calculateReferencePriceOffset(reservePrice, last24hAvgFundingRate, liquidityFraction, oracleTwapFast, markTwapFast, oracleTwapSlow, markTwapSlow, maxOffsetPct) {
     if (last24hAvgFundingRate.eq(numericConstants_1.ZERO) || liquidityFraction.eq(numericConstants_1.ZERO)) {
         return numericConstants_1.ZERO;
@@ -251,7 +417,10 @@ function calculateReferencePriceOffset(reservePrice, last24hAvgFundingRate, liqu
     const markPremiumMinute = (0, utils_1.clampBN)(markTwapFast.sub(oracleTwapFast), maxOffsetInPrice.mul(new anchor_1.BN(-1)), maxOffsetInPrice);
     const markPremiumHour = (0, utils_1.clampBN)(markTwapSlow.sub(oracleTwapSlow), maxOffsetInPrice.mul(new anchor_1.BN(-1)), maxOffsetInPrice);
     // Convert last24hAvgFundingRate to quote denominated premium
-    const markPremiumDay = (0, utils_1.clampBN)(last24hAvgFundingRate.div(numericConstants_1.FUNDING_RATE_BUFFER_PRECISION).mul(new anchor_1.BN(24)), maxOffsetInPrice.mul(new anchor_1.BN(-1)), maxOffsetInPrice);
+    const markPremiumDay = (0, utils_1.clampBN)(last24hAvgFundingRate
+        .div(numericConstants_1.FUNDING_RATE_BUFFER_PRECISION)
+        .mul(new anchor_1.BN(24))
+        .sub(oracleTwapSlow.abs().div(numericConstants_1.FUNDING_RATE_OFFSET_DENOMINATOR)), maxOffsetInPrice.mul(new anchor_1.BN(-1)), maxOffsetInPrice);
     // Take average clamped premium as the price-based offset
     const markPremiumAvg = markPremiumMinute
         .add(markPremiumHour)
@@ -269,6 +438,21 @@ function calculateReferencePriceOffset(reservePrice, last24hAvgFundingRate, liqu
     return clampedOffsetPct;
 }
 exports.calculateReferencePriceOffset = calculateReferencePriceOffset;
+/**
+ * Estimates how "levered" the AMM's own net position is relative to its retained equity —
+ * the gap between the AMM's local (reserve-price-valued) exposure and its actual net
+ * inventory value, divided by `totalFeeMinusDistributions`. Used to scale up the spread on
+ * the inventory side when the AMM is thinly capitalized relative to its exposure (see
+ * `calculateSpreadBN`'s `effectiveLeverageCapped` term).
+ * @param baseSpread Market's configured base spread (unused directly here beyond being part of the caller's contract; kept for parity with the on-chain signature).
+ * @param quoteAssetReserve AMM quote asset reserve, AMM_RESERVE_PRECISION (1e9).
+ * @param terminalQuoteAssetReserve AMM terminal (post-close) quote asset reserve, AMM_RESERVE_PRECISION (1e9).
+ * @param pegMultiplier AMM peg multiplier, PEG_PRECISION (1e6).
+ * @param netBaseAssetAmount AMM's net inventory, AMM_RESERVE_PRECISION (1e9, signed).
+ * @param reservePrice Current AMM reserve price, PRICE_PRECISION (1e6).
+ * @param totalFeeMinusDistributions AMM's retained equity, QUOTE_PRECISION (1e6).
+ * @returns Plain (unitless) effective leverage ratio, floored at 0.
+ */
 function calculateEffectiveLeverage(baseSpread, quoteAssetReserve, terminalQuoteAssetReserve, pegMultiplier, netBaseAssetAmount, reservePrice, totalFeeMinusDistributions) {
     // vAMM skew
     const netBaseAssetValue = quoteAssetReserve
@@ -284,6 +468,23 @@ function calculateEffectiveLeverage(baseSpread, quoteAssetReserve, terminalQuote
     return effectiveLeverage;
 }
 exports.calculateEffectiveLeverage = calculateEffectiveLeverage;
+/**
+ * Computes the volatility-driven component of the AMM's bid/ask spread, before inventory,
+ * leverage, revenue-retreat, or funding-bias adjustments are layered on in `calculateSpreadBN`.
+ * Blends the recent mark/oracle standard deviation (`markStd`, `oracleStd`) with oracle
+ * confidence, then scales each side independently by that side's recent fill intensity
+ * relative to 24h volume (a side that's been trading heavily gets a wider spread on that side).
+ * The oracle confidence interval is dampened to 5% of its value below 25bps so tiny confidence
+ * noise doesn't dominate a quiet market.
+ * @param lastOracleConfPct Oracle confidence interval as a fraction of price, PERCENTAGE_PRECISION (1e6).
+ * @param reservePrice Current AMM reserve price, PRICE_PRECISION (1e6).
+ * @param markStd Recent mark price standard deviation, PRICE_PRECISION (1e6).
+ * @param oracleStd Recent oracle price standard deviation, PRICE_PRECISION (1e6).
+ * @param longIntensity Recent long-side fill volume intensity, BASE_PRECISION (1e9) or QUOTE_PRECISION depending on caller; only used relative to `volume24H`.
+ * @param shortIntensity Recent short-side fill volume intensity, same units as `longIntensity`.
+ * @param volume24H Trailing 24h volume, same units as `longIntensity`/`shortIntensity`.
+ * @returns `[longVolSpread, shortVolSpread]`, both PERCENTAGE_PRECISION (1e6) fraction-of-price units.
+ */
 function calculateVolSpreadBN(lastOracleConfPct, reservePrice, markStd, oracleStd, longIntensity, shortIntensity, volume24H) {
     const marketAvgStdPct = markStd
         .add(oracleStd)
@@ -498,6 +699,21 @@ function calculateSpreadBN(baseSpread, lastOracleReservePriceSpreadPct, lastOrac
     return [longSpread, shortSpread];
 }
 exports.calculateSpreadBN = calculateSpreadBN;
+/**
+ * Convenience wrapper around `calculateSpreadBN` that derives its lower-level inputs
+ * (reserve price, oracle-vs-reserve spread, live oracle std, and confidence interval) from
+ * `amm`/`marketStats`/`oraclePriceData` directly, then applies the market's manual
+ * `ammSpreadAdjustment` (%, shrink if negative/grow if positive, floored at 1) on top. Returns
+ * `[baseSpread/2, baseSpread/2]` unchanged (no dynamic widening) if `baseSpread` or
+ * `curveUpdateIntensity` is zero.
+ * @param amm AMM state to price the spread for.
+ * @param marketStats Market stats needed for volatility/funding-bias inputs.
+ * @param oraclePriceData Current oracle price data; required unless `baseSpread`/`curveUpdateIntensity` are both zero.
+ * @param now Current unix timestamp (seconds); defaults to wall-clock time if omitted.
+ * @param reservePrice Current AMM reserve price, PRICE_PRECISION (1e6); computed from `amm`'s reserves if omitted.
+ * @throws if `oraclePriceData` is omitted while `baseSpread` and `curveUpdateIntensity` are both nonzero.
+ * @returns `[longSpread, shortSpread]`, both BID_ASK_SPREAD_PRECISION (1e6) fraction-of-price units.
+ */
 function calculateSpread(amm, marketStats, oraclePriceData, now, reservePrice) {
     if (amm.baseSpread == 0 || amm.curveUpdateIntensity == 0) {
         return [amm.baseSpread / 2, amm.baseSpread / 2];
@@ -530,6 +746,24 @@ function calculateSpread(amm, marketStats, oraclePriceData, now, reservePrice) {
     return [longSpread, shortSpread];
 }
 exports.calculateSpread = calculateSpread;
+/**
+ * Computes the AMM's one-sided bid and ask reserves — the reserves a long (ask side) or short
+ * (bid side) trade would actually execute against — by combining `calculateSpread`'s
+ * volatility/inventory spread with the reference-price-offset skew, mirroring
+ * `calculate_spread_reserves` in `vlp/amm/math/amm_spread.rs`. The reference price offset
+ * (enabled only when `curveUpdateIntensity > 100`) lets quotes drift up to `maxOffset` off the
+ * raw reserve price when inventory skew and recent/24h funding premium agree in direction; a
+ * configurable deadband (`referencePriceOffsetDeadbandPct`) suppresses small offsets, and when
+ * the offset's sign flips versus the market's last stored offset, the change is smoothed in
+ * gradually over elapsed slots (`latestSlot - amm.lastUpdateSlot`) rather than snapping
+ * instantly, to avoid quote whiplash.
+ * @param amm AMM state to derive spread reserves for.
+ * @param marketStats Market stats needed for spread and reference-price-offset calculation (including `lastReferencePriceOffset` for smoothing).
+ * @param mmOraclePriceData Current MM oracle price data, forwarded to `calculateSpread`.
+ * @param now Current unix timestamp (seconds), forwarded to `calculateSpread`.
+ * @param latestSlot Current slot; required for reference-price-offset smoothing to take effect (treated as 0 slots elapsed if omitted).
+ * @returns `[bidReserves, askReserves]`, each `{ baseAssetReserve, quoteAssetReserve }` in AMM_RESERVE_PRECISION (1e9).
+ */
 function calculateSpreadReserves(amm, marketStats, mmOraclePriceData, now, latestSlot) {
     function calculateSpreadReserve(spread, direction, amm) {
         if (spread === 0) {
@@ -615,13 +849,15 @@ function calculateSpreadReserves(amm, marketStats, mmOraclePriceData, now, lates
 }
 exports.calculateSpreadReserves = calculateSpreadReserves;
 /**
- * Helper function calculating constant product curve output. Agnostic to whether input asset is quote or base
- *
- * @param inputAssetReserve
- * @param swapAmount
- * @param swapDirection
- * @param invariant
- * @returns newInputAssetReserve and newOutputAssetReserve after swap. : Precision AMM_RESERVE_PRECISION
+ * Applies the constant-product invariant (`invariant = k^2 = inputReserve * outputReserve`) to
+ * a single reserve swap; agnostic to whether the input side is quote or base. Both reserve
+ * arguments and the result must share the same precision as `invariant`'s square root
+ * (typically `AMM_RESERVE_PRECISION`, 1e9).
+ * @param inputAssetReserve Current reserve on the input side, same precision as `invariant`'s square root.
+ * @param swapAmount Amount being added to or removed from `inputAssetReserve`.
+ * @param swapDirection Whether `swapAmount` is added to or removed from the input reserve.
+ * @param invariant Constant-product invariant (`sqrtK^2`), same precision as `inputAssetReserve` squared.
+ * @returns `[newInputAssetReserve, newOutputAssetReserve]`, both same precision as `inputAssetReserve`.
  */
 function calculateSwapOutput(inputAssetReserve, swapAmount, swapDirection, invariant) {
     let newInputAssetReserve;
@@ -636,10 +872,13 @@ function calculateSwapOutput(inputAssetReserve, swapAmount, swapDirection, invar
 }
 exports.calculateSwapOutput = calculateSwapOutput;
 /**
- * Translate long/shorting quote/base asset into amm operation
- *
- * @param inputAssetType
- * @param positionDirection
+ * Maps a desired position direction and the asset side being specified into the AMM
+ * reserve-swap direction (`ADD`/`REMOVE`) needed to execute it: opening a long by specifying
+ * base, or a short by specifying quote, removes that reserve from the AMM; every other
+ * combination adds to it.
+ * @param inputAssetType Which side (`'quote'` or `'base'`) the trade amount is denominated in.
+ * @param positionDirection Direction of the position being opened/closed.
+ * @returns `SwapDirection.ADD` or `SwapDirection.REMOVE` for `calculateAmmReservesAfterSwap`/`calculateSwapOutput`.
  */
 function getSwapDirection(inputAssetType, positionDirection) {
     if ((0, types_1.isVariant)(positionDirection, 'long') && inputAssetType === 'base') {
@@ -652,10 +891,12 @@ function getSwapDirection(inputAssetType, positionDirection) {
 }
 exports.getSwapDirection = getSwapDirection;
 /**
- * Helper function calculating terminal price of amm
- *
- * @param market
- * @returns cost : Precision PRICE_PRECISION
+ * Computes the AMM's "terminal price" — the constant-product price that would result if the
+ * AMM's entire net inventory (`baseAssetAmountWithAmm`) were closed out against itself in one
+ * swap. Used as a floor/ceiling reference distinct from the current spot reserve price, since
+ * it reflects where the curve would settle once open interest unwinds.
+ * @param market Perp market whose AMM to compute the terminal price for.
+ * @returns Terminal price, PRICE_PRECISION (1e6).
  */
 function calculateTerminalPrice(market) {
     const directionToClose = market.amm.baseAssetAmountWithAmm.gt(numericConstants_1.ZERO)
@@ -670,6 +911,21 @@ function calculateTerminalPrice(market) {
     return terminalPrice;
 }
 exports.calculateTerminalPrice = calculateTerminalPrice;
+/**
+ * Solves for how much base asset the AMM could absorb, trading against its `direction`-side
+ * spread reserves (`calculateSpreadReserves`), before its constant-product price would cross
+ * `limit_price` — i.e. the AMM-side fill size available up to a resting limit order's price.
+ * The returned direction is the side the AMM would be trading (opposite what a taker matching
+ * against it would take): `SHORT` if the AMM's reserves must shrink to reach `limit_price`
+ * (limit price above current), `LONG` if they must grow (limit price below current).
+ * @param amm AMM state to solve against.
+ * @param marketStats Market stats needed to derive spread reserves.
+ * @param limit_price Limit price the AMM may trade up to, PRICE_PRECISION (1e6).
+ * @param direction Which side's spread reserves to start from (see `calculateSpreadReserves`).
+ * @param mmOraclePriceData Current MM oracle price data, forwarded to `calculateSpreadReserves`.
+ * @param now Current unix timestamp (seconds), forwarded to `calculateSpreadReserves`.
+ * @returns `[baseAssetAmount, direction]`: `baseAssetAmount` is AMM_RESERVE_PRECISION (1e9), zero if the trade size would round to nothing.
+ */
 function calculateMaxBaseAssetAmountToTrade(amm, marketStats, limit_price, direction, mmOraclePriceData, now) {
     const invariant = amm.sqrtK.mul(amm.sqrtK);
     const newBaseAssetReserveSquared = invariant
@@ -700,6 +956,16 @@ function calculateMaxBaseAssetAmountToTrade(amm, marketStats, limit_price, direc
     }
 }
 exports.calculateMaxBaseAssetAmountToTrade = calculateMaxBaseAssetAmountToTrade;
+/**
+ * Converts a quote-asset AMM reserve amount into the actual quote asset amount swapped
+ * (applying the peg multiplier), rounding by 1 in the direction that favors the AMM when
+ * `swapDirection` is `remove` (quote leaving the AMM), mirroring the on-chain rounding used to
+ * avoid ever giving out a fraction of a unit more than intended.
+ * @param quoteAssetReserves Quote reserve delta from a swap, AMM_RESERVE_PRECISION (1e9).
+ * @param pegMultiplier AMM peg multiplier, PEG_PRECISION (1e6).
+ * @param swapDirection Whether quote is being added to or removed from the AMM.
+ * @returns Quote asset amount actually swapped, QUOTE_PRECISION (1e6).
+ */
 function calculateQuoteAssetAmountSwapped(quoteAssetReserves, pegMultiplier, swapDirection) {
     if ((0, types_1.isVariant)(swapDirection, 'remove')) {
         quoteAssetReserves = quoteAssetReserves.add(numericConstants_1.ONE);
@@ -713,6 +979,18 @@ function calculateQuoteAssetAmountSwapped(quoteAssetReserves, pegMultiplier, swa
     return quoteAssetAmount;
 }
 exports.calculateQuoteAssetAmountSwapped = calculateQuoteAssetAmountSwapped;
+/**
+ * Caps how much base asset the AMM is willing to fill in one instruction: the smaller of
+ * `amm.maxFillReserveFraction`'s share of the current base reserve and the room remaining to
+ * the AMM's min/max reserve bound on the taker's side, then rounded down to `orderStepSize`.
+ * This is a per-fill risk limit distinct from `calculateMaxBaseAssetAmountToTrade` (which sizes
+ * against a limit price) — it bounds how much of the AMM's own liquidity can move at once
+ * regardless of price.
+ * @param amm AMM state (`baseAssetReserve`, `minBaseAssetReserve`, `maxBaseAssetReserve`, `maxFillReserveFraction`).
+ * @param orderStepSize Order step size to standardize the result to, BASE_PRECISION (1e9).
+ * @param orderDirection Direction of the order being filled against the AMM.
+ * @returns Max fillable base asset amount, BASE_PRECISION (1e9), standardized to `orderStepSize`.
+ */
 function calculateMaxBaseAssetAmountFillable(amm, orderStepSize, orderDirection) {
     const maxFillSize = amm.baseAssetReserve.div(new anchor_1.BN(amm.maxFillReserveFraction));
     let maxBaseAssetAmountOnSide;