@velocity-exchange/sdk 0.3.0 → 0.4.0

package/lib/browser/math/position.d.ts

@@ -2,65 +2,112 @@ import { BN } from '../isomorphic/anchor';
 import { MMOraclePriceData, OraclePriceData } from '../oracles/types';
 import { PerpMarketAccount, PositionDirection, PerpPosition, SpotMarketAccount } from '../types';
 /**
- * calculateBaseAssetValue
- * = market value of closing entire position
- * @param market
- * @param userPosition
- * @param oraclePriceData
- * @returns Base Asset Value. : Precision QUOTE_PRECISION
+ * Simulates fully closing `userPosition` against the AMM (optionally through its bid/ask
+ * spread reserves) and returns the resulting quote value — i.e. the market value of closing
+ * the entire position right now, distinct from `calculateBaseAssetValueWithOracle`'s
+ * mark-to-oracle valuation used for margin.
+ * @param market Perp market whose AMM is used to price the close.
+ * @param userPosition Position to value; returns zero if flat (`baseAssetAmount == 0`).
+ * @param mmOraclePriceData MM oracle price data used to re-peg/update the AMM before pricing (unless `skipUpdate`).
+ * @param useSpread If true (default) and the market has a nonzero base spread, price through the bid/ask spread reserves on the closing side rather than the raw AMM reserves.
+ * @param skipUpdate If true, price against `market.amm` as-is without applying `calculateUpdatedAMM`/spread-reserve updates first (default false).
+ * @param latestSlot Current slot, forwarded to the spread-reserve update for reference-price-offset smoothing.
+ * @returns Value of fully closing the position, QUOTE_PRECISION (1e6).
  */
 export declare function calculateBaseAssetValue(market: PerpMarketAccount, userPosition: PerpPosition, mmOraclePriceData: MMOraclePriceData, useSpread?: boolean, skipUpdate?: boolean, latestSlot?: BN): BN;
 /**
- * calculatePositionPNL
- * = BaseAssetAmount * (Avg Exit Price - Avg Entry Price)
- * @param market
- * @param PerpPosition
- * @param withFunding (adds unrealized funding payment pnl to result)
- * @param oraclePriceData
- * @returns BaseAssetAmount : Precision QUOTE_PRECISION
+ * Calculates a position's unrealized pnl, marked to the oracle price (via
+ * `calculateBaseAssetValueWithOracle`) rather than the AMM close price. For a flat position
+ * this is simply `quoteAssetAmount` (any residual realized/settled pnl still on the position).
+ * @param market Perp market the position belongs to.
+ * @param perpPosition Position to value.
+ * @param withFunding If true, adds unsettled funding pnl (`calculateUnsettledFundingPnl`) to the result (default false).
+ * @param oraclePriceData Must provide `price`, PRICE_PRECISION (1e6); used unless the market is in `settlement` status (which uses `market.expiryPrice` internally).
+ * @returns Unrealized pnl, QUOTE_PRECISION (1e6, signed).
  */
 export declare function calculatePositionPNL(market: PerpMarketAccount, perpPosition: PerpPosition, withFunding: boolean | undefined, oraclePriceData: Pick<OraclePriceData, 'price'>): BN;
+/**
+ * Caps a position's unrealized pnl (incl. funding) to the amount actually settleable via
+ * `settle_pnl`, mirroring `PerpPosition::get_claimable_pnl` in
+ * `programs/velocity/src/state/user.rs`. Positive pnl can only be settled up to whichever is
+ * larger: pnl already realized by reducing the position (`quoteAssetAmount -
+ * quoteEntryAmount`, floored at zero) plus any pnl-pool surplus over the market's net user
+ * pnl (`calculateNetUserPnlImbalance`, negated and floored at zero). Negative pnl passes
+ * through uncapped — this function does not itself gate on margin requirements (the program
+ * separately blocks settling negative pnl for a user who wouldn't meet maintenance margin
+ * afterward).
+ * @param market Perp market the position belongs to.
+ * @param spotMarket Quote spot market, used to size the pnl pool via `calculateNetUserPnlImbalance`.
+ * @param perpPosition Position to evaluate.
+ * @param oraclePriceData Must provide `price`, PRICE_PRECISION (1e6).
+ * @returns Settleable pnl, QUOTE_PRECISION (1e6, signed) — equal to unrealized pnl if negative or uncapped, otherwise capped.
+ */
 export declare function calculateClaimablePnl(market: PerpMarketAccount, spotMarket: SpotMarketAccount, perpPosition: PerpPosition, oraclePriceData: Pick<OraclePriceData, 'price'>): BN;
 /**
- * Returns total fees and funding pnl for a position
- *
- * @param market
- * @param PerpPosition
- * @param includeUnsettled include unsettled funding in return value (default: true)
- * @returns — // QUOTE_PRECISION
+ * Returns the cumulative fees-plus-funding component of a position's pnl (i.e. the part of
+ * pnl not explained by price movement): settled funding/fees so far
+ * (`quoteBreakEvenAmount - quoteEntryAmount`) plus, optionally, unsettled funding accrued
+ * since the last funding settlement.
+ * @param market Perp market the position belongs to.
+ * @param perpPosition Position to evaluate.
+ * @param includeUnsettled If true (default), adds `calculateUnsettledFundingPnl` to the result.
+ * @returns Fees + funding pnl, QUOTE_PRECISION (1e6, signed).
  */
 export declare function calculateFeesAndFundingPnl(market: PerpMarketAccount, perpPosition: PerpPosition, includeUnsettled?: boolean): BN;
 /**
- * Returns unsettled funding pnl for the position
+ * Returns unsettled funding pnl accrued on the position since its last funding settlement:
+ * the delta between the market's current cumulative funding rate (long or short side,
+ * selected by position direction) and the position's `lastCumulativeFundingRate`, applied to
+ * `baseAssetAmount`. Zero for a flat position.
  *
- * To calculate all fees and funding pnl including settled, use calculateFeesAndFundingPnl
+ * To calculate all fees and funding pnl including settled, use `calculateFeesAndFundingPnl`.
  *
- * @param market
- * @param PerpPosition
- * @returns // QUOTE_PRECISION
+ * @param market Perp market the position belongs to; uses `cumulativeFundingRateLong`/`cumulativeFundingRateShort`.
+ * @param perpPosition Position to evaluate.
+ * @returns Unsettled funding pnl, QUOTE_PRECISION (1e6, signed).
  */
 export declare function calculateUnsettledFundingPnl(market: PerpMarketAccount, perpPosition: PerpPosition): BN;
+/**
+ * True if a `PerpPosition` slot is free to be reused for a different market, mirroring
+ * `PerpPosition::is_available` in `programs/velocity/src/state/user.rs`: no open base
+ * position, no open orders, no unsettled quote pnl, no isolated-margin collateral parked in
+ * it (`isolatedPositionScaledBalance == 0`), and not currently mid-liquidation/bankruptcy.
+ * An isolated position with collateral still deposited is never "available" even if flat,
+ * since that collateral must be withdrawn first.
+ * @param position Position slot to check.
+ * @returns `true` if the slot can be assigned to a new market.
+ */
 export declare function positionIsAvailable(position: PerpPosition): boolean;
+/** True if `position.positionFlag` has the `BeingLiquidated` or `Bankruptcy` bit set. */
 export declare function positionIsBeingLiquidated(position: PerpPosition): boolean;
 /**
- *
- * @param userPosition
- * @returns Precision: PRICE_PRECISION (10^6)
+ * Price at which closing the position realizes zero further pnl, i.e. entry price adjusted
+ * for fees and funding paid/received so far (`quoteBreakEvenAmount / baseAssetAmount`).
+ * @param userPosition Position to evaluate.
+ * @returns Break-even price (always non-negative), PRICE_PRECISION (1e6). Zero if flat.
  */
 export declare function calculateBreakEvenPrice(userPosition: PerpPosition): BN;
 /**
- *
- * @param userPosition
- * @returns Precision: PRICE_PRECISION (10^6)
+ * Average entry price of the position, before fees/funding (`quoteEntryAmount / baseAssetAmount`).
+ * @param userPosition Position to evaluate.
+ * @returns Average entry price (always non-negative), PRICE_PRECISION (1e6). Zero if flat.
  */
 export declare function calculateEntryPrice(userPosition: PerpPosition): BN;
 /**
- *
- * @param userPosition
- * @returns Precision: PRICE_PRECISION (10^10)
+ * Cost basis of the position (`quoteAssetAmount / baseAssetAmount`, optionally including
+ * realized settled pnl), i.e. the current quote value backing the position expressed per
+ * unit of base — this differs from `calculateEntryPrice` whenever the position has
+ * accumulated settled pnl or fees since it was opened.
+ * @param userPosition Position to evaluate.
+ * @param includeSettledPnl If true, folds `userPosition.settledPnl` into the quote amount before dividing (default false).
+ * @returns Cost basis (always non-negative), PRICE_PRECISION (1e6). Zero if flat.
  */
 export declare function calculateCostBasis(userPosition: PerpPosition, includeSettledPnl?: boolean): BN;
+/** Direction of the trade that would fully close `userPosition`: `SHORT` for a long position (base > 0), `LONG` otherwise (including flat). */
 export declare function findDirectionToClose(userPosition: PerpPosition): PositionDirection;
+/** The position's own directional exposure: `LONG` if `baseAssetAmount >= 0` (including flat), `SHORT` if negative. */
 export declare function positionCurrentDirection(userPosition: PerpPosition): PositionDirection;
+/** True if the position has no open base exposure and no open orders (a coarser check than `positionIsAvailable` — does not check quote pnl, isolated collateral, or liquidation flags). */
 export declare function isEmptyPosition(userPosition: PerpPosition): boolean;
+/** True if the position has any open orders, resting bids, or resting asks, mirroring `PerpPosition::has_open_order` in `programs/velocity/src/state/user.rs`. */
 export declare function hasOpenOrders(position: PerpPosition): boolean;

package/lib/browser/math/position.js

@@ -8,12 +8,17 @@ const amm_1 = require("./amm");
 const margin_1 = require("./margin");
 const market_1 = require("./market");
 /**
- * calculateBaseAssetValue
- * = market value of closing entire position
- * @param market
- * @param userPosition
- * @param oraclePriceData
- * @returns Base Asset Value. : Precision QUOTE_PRECISION
+ * Simulates fully closing `userPosition` against the AMM (optionally through its bid/ask
+ * spread reserves) and returns the resulting quote value — i.e. the market value of closing
+ * the entire position right now, distinct from `calculateBaseAssetValueWithOracle`'s
+ * mark-to-oracle valuation used for margin.
+ * @param market Perp market whose AMM is used to price the close.
+ * @param userPosition Position to value; returns zero if flat (`baseAssetAmount == 0`).
+ * @param mmOraclePriceData MM oracle price data used to re-peg/update the AMM before pricing (unless `skipUpdate`).
+ * @param useSpread If true (default) and the market has a nonzero base spread, price through the bid/ask spread reserves on the closing side rather than the raw AMM reserves.
+ * @param skipUpdate If true, price against `market.amm` as-is without applying `calculateUpdatedAMM`/spread-reserve updates first (default false).
+ * @param latestSlot Current slot, forwarded to the spread-reserve update for reference-price-offset smoothing.
+ * @returns Value of fully closing the position, QUOTE_PRECISION (1e6).
  */
 function calculateBaseAssetValue(market, userPosition, mmOraclePriceData, useSpread = true, skipUpdate = false, latestSlot) {
     if (userPosition.baseAssetAmount.eq(numericConstants_1.ZERO)) {
@@ -57,13 +62,14 @@ function calculateBaseAssetValue(market, userPosition, mmOraclePriceData, useSpr
 }
 exports.calculateBaseAssetValue = calculateBaseAssetValue;
 /**
- * calculatePositionPNL
- * = BaseAssetAmount * (Avg Exit Price - Avg Entry Price)
- * @param market
- * @param PerpPosition
- * @param withFunding (adds unrealized funding payment pnl to result)
- * @param oraclePriceData
- * @returns BaseAssetAmount : Precision QUOTE_PRECISION
+ * Calculates a position's unrealized pnl, marked to the oracle price (via
+ * `calculateBaseAssetValueWithOracle`) rather than the AMM close price. For a flat position
+ * this is simply `quoteAssetAmount` (any residual realized/settled pnl still on the position).
+ * @param market Perp market the position belongs to.
+ * @param perpPosition Position to value.
+ * @param withFunding If true, adds unsettled funding pnl (`calculateUnsettledFundingPnl`) to the result (default false).
+ * @param oraclePriceData Must provide `price`, PRICE_PRECISION (1e6); used unless the market is in `settlement` status (which uses `market.expiryPrice` internally).
+ * @returns Unrealized pnl, QUOTE_PRECISION (1e6, signed).
  */
 function calculatePositionPNL(market, perpPosition, withFunding = false, oraclePriceData) {
     if (perpPosition.baseAssetAmount.eq(numericConstants_1.ZERO)) {
@@ -83,6 +89,22 @@ function calculatePositionPNL(market, perpPosition, withFunding = false, oracleP
     return pnl;
 }
 exports.calculatePositionPNL = calculatePositionPNL;
+/**
+ * Caps a position's unrealized pnl (incl. funding) to the amount actually settleable via
+ * `settle_pnl`, mirroring `PerpPosition::get_claimable_pnl` in
+ * `programs/velocity/src/state/user.rs`. Positive pnl can only be settled up to whichever is
+ * larger: pnl already realized by reducing the position (`quoteAssetAmount -
+ * quoteEntryAmount`, floored at zero) plus any pnl-pool surplus over the market's net user
+ * pnl (`calculateNetUserPnlImbalance`, negated and floored at zero). Negative pnl passes
+ * through uncapped — this function does not itself gate on margin requirements (the program
+ * separately blocks settling negative pnl for a user who wouldn't meet maintenance margin
+ * afterward).
+ * @param market Perp market the position belongs to.
+ * @param spotMarket Quote spot market, used to size the pnl pool via `calculateNetUserPnlImbalance`.
+ * @param perpPosition Position to evaluate.
+ * @param oraclePriceData Must provide `price`, PRICE_PRECISION (1e6).
+ * @returns Settleable pnl, QUOTE_PRECISION (1e6, signed) — equal to unrealized pnl if negative or uncapped, otherwise capped.
+ */
 function calculateClaimablePnl(market, spotMarket, perpPosition, oraclePriceData) {
     const unrealizedPnl = calculatePositionPNL(market, perpPosition, true, oraclePriceData);
     let unsettledPnl = unrealizedPnl;
@@ -95,12 +117,14 @@ function calculateClaimablePnl(market, spotMarket, perpPosition, oraclePriceData
 }
 exports.calculateClaimablePnl = calculateClaimablePnl;
 /**
- * Returns total fees and funding pnl for a position
- *
- * @param market
- * @param PerpPosition
- * @param includeUnsettled include unsettled funding in return value (default: true)
- * @returns — // QUOTE_PRECISION
+ * Returns the cumulative fees-plus-funding component of a position's pnl (i.e. the part of
+ * pnl not explained by price movement): settled funding/fees so far
+ * (`quoteBreakEvenAmount - quoteEntryAmount`) plus, optionally, unsettled funding accrued
+ * since the last funding settlement.
+ * @param market Perp market the position belongs to.
+ * @param perpPosition Position to evaluate.
+ * @param includeUnsettled If true (default), adds `calculateUnsettledFundingPnl` to the result.
+ * @returns Fees + funding pnl, QUOTE_PRECISION (1e6, signed).
  */
 function calculateFeesAndFundingPnl(market, perpPosition, includeUnsettled = true) {
     const settledFundingAndFeesPnl = perpPosition.quoteBreakEvenAmount.sub(perpPosition.quoteEntryAmount);
@@ -112,13 +136,16 @@ function calculateFeesAndFundingPnl(market, perpPosition, includeUnsettled = tru
 }
 exports.calculateFeesAndFundingPnl = calculateFeesAndFundingPnl;
 /**
- * Returns unsettled funding pnl for the position
+ * Returns unsettled funding pnl accrued on the position since its last funding settlement:
+ * the delta between the market's current cumulative funding rate (long or short side,
+ * selected by position direction) and the position's `lastCumulativeFundingRate`, applied to
+ * `baseAssetAmount`. Zero for a flat position.
  *
- * To calculate all fees and funding pnl including settled, use calculateFeesAndFundingPnl
+ * To calculate all fees and funding pnl including settled, use `calculateFeesAndFundingPnl`.
  *
- * @param market
- * @param PerpPosition
- * @returns // QUOTE_PRECISION
+ * @param market Perp market the position belongs to; uses `cumulativeFundingRateLong`/`cumulativeFundingRateShort`.
+ * @param perpPosition Position to evaluate.
+ * @returns Unsettled funding pnl, QUOTE_PRECISION (1e6, signed).
  */
 function calculateUnsettledFundingPnl(market, perpPosition) {
     if (perpPosition.baseAssetAmount.eq(numericConstants_1.ZERO)) {
@@ -140,6 +167,16 @@ function calculateUnsettledFundingPnl(market, perpPosition) {
     return perPositionFundingRate;
 }
 exports.calculateUnsettledFundingPnl = calculateUnsettledFundingPnl;
+/**
+ * True if a `PerpPosition` slot is free to be reused for a different market, mirroring
+ * `PerpPosition::is_available` in `programs/velocity/src/state/user.rs`: no open base
+ * position, no open orders, no unsettled quote pnl, no isolated-margin collateral parked in
+ * it (`isolatedPositionScaledBalance == 0`), and not currently mid-liquidation/bankruptcy.
+ * An isolated position with collateral still deposited is never "available" even if flat,
+ * since that collateral must be withdrawn first.
+ * @param position Position slot to check.
+ * @returns `true` if the slot can be assigned to a new market.
+ */
 function positionIsAvailable(position) {
     return (position.baseAssetAmount.eq(numericConstants_1.ZERO) &&
         position.openOrders === 0 &&
@@ -148,6 +185,7 @@ function positionIsAvailable(position) {
         !positionIsBeingLiquidated(position));
 }
 exports.positionIsAvailable = positionIsAvailable;
+/** True if `position.positionFlag` has the `BeingLiquidated` or `Bankruptcy` bit set. */
 function positionIsBeingLiquidated(position) {
     return ((position.positionFlag &
         (types_1.PositionFlag.BeingLiquidated | types_1.PositionFlag.Bankruptcy)) >
@@ -155,9 +193,10 @@ function positionIsBeingLiquidated(position) {
 }
 exports.positionIsBeingLiquidated = positionIsBeingLiquidated;
 /**
- *
- * @param userPosition
- * @returns Precision: PRICE_PRECISION (10^6)
+ * Price at which closing the position realizes zero further pnl, i.e. entry price adjusted
+ * for fees and funding paid/received so far (`quoteBreakEvenAmount / baseAssetAmount`).
+ * @param userPosition Position to evaluate.
+ * @returns Break-even price (always non-negative), PRICE_PRECISION (1e6). Zero if flat.
  */
 function calculateBreakEvenPrice(userPosition) {
     if (userPosition.baseAssetAmount.eq(numericConstants_1.ZERO)) {
@@ -171,9 +210,9 @@ function calculateBreakEvenPrice(userPosition) {
 }
 exports.calculateBreakEvenPrice = calculateBreakEvenPrice;
 /**
- *
- * @param userPosition
- * @returns Precision: PRICE_PRECISION (10^6)
+ * Average entry price of the position, before fees/funding (`quoteEntryAmount / baseAssetAmount`).
+ * @param userPosition Position to evaluate.
+ * @returns Average entry price (always non-negative), PRICE_PRECISION (1e6). Zero if flat.
  */
 function calculateEntryPrice(userPosition) {
     if (userPosition.baseAssetAmount.eq(numericConstants_1.ZERO)) {
@@ -187,9 +226,13 @@ function calculateEntryPrice(userPosition) {
 }
 exports.calculateEntryPrice = calculateEntryPrice;
 /**
- *
- * @param userPosition
- * @returns Precision: PRICE_PRECISION (10^10)
+ * Cost basis of the position (`quoteAssetAmount / baseAssetAmount`, optionally including
+ * realized settled pnl), i.e. the current quote value backing the position expressed per
+ * unit of base — this differs from `calculateEntryPrice` whenever the position has
+ * accumulated settled pnl or fees since it was opened.
+ * @param userPosition Position to evaluate.
+ * @param includeSettledPnl If true, folds `userPosition.settledPnl` into the quote amount before dividing (default false).
+ * @returns Cost basis (always non-negative), PRICE_PRECISION (1e6). Zero if flat.
  */
 function calculateCostBasis(userPosition, includeSettledPnl = false) {
     if (userPosition.baseAssetAmount.eq(numericConstants_1.ZERO)) {
@@ -203,22 +246,26 @@ function calculateCostBasis(userPosition, includeSettledPnl = false) {
         .abs();
 }
 exports.calculateCostBasis = calculateCostBasis;
+/** Direction of the trade that would fully close `userPosition`: `SHORT` for a long position (base > 0), `LONG` otherwise (including flat). */
 function findDirectionToClose(userPosition) {
     return userPosition.baseAssetAmount.gt(numericConstants_1.ZERO)
         ? types_1.PositionDirection.SHORT
         : types_1.PositionDirection.LONG;
 }
 exports.findDirectionToClose = findDirectionToClose;
+/** The position's own directional exposure: `LONG` if `baseAssetAmount >= 0` (including flat), `SHORT` if negative. */
 function positionCurrentDirection(userPosition) {
     return userPosition.baseAssetAmount.gte(numericConstants_1.ZERO)
         ? types_1.PositionDirection.LONG
         : types_1.PositionDirection.SHORT;
 }
 exports.positionCurrentDirection = positionCurrentDirection;
+/** True if the position has no open base exposure and no open orders (a coarser check than `positionIsAvailable` — does not check quote pnl, isolated collateral, or liquidation flags). */
 function isEmptyPosition(userPosition) {
     return userPosition.baseAssetAmount.eq(numericConstants_1.ZERO) && userPosition.openOrders === 0;
 }
 exports.isEmptyPosition = isEmptyPosition;
+/** True if the position has any open orders, resting bids, or resting asks, mirroring `PerpPosition::has_open_order` in `programs/velocity/src/state/user.rs`. */
 function hasOpenOrders(position) {
     return (position.openOrders != 0 ||
         !position.openBids.eq(numericConstants_1.ZERO) ||

package/lib/browser/math/repeg.d.ts

@@ -1,20 +1,58 @@
 import { BN } from '../isomorphic/anchor';
 import { AMM } from '../types';
 /**
- * Helper function calculating adjust k cost
- * @param amm
- * @param numerator
- * @param denomenator
- * @returns cost : Precision QUOTE_ASSET_PRECISION
+ * Closed-form estimate of the quote-denominated cost of scaling the AMM's `sqrtK`
+ * (liquidity depth) by `numerator / denomenator` while holding `pegMultiplier` fixed.
+ * Used by `calculateNewAmm` as the cheap-to-compute stand-in for the program's K-shrink
+ * step (`adjust_k_cost_and_update` in `vlp/amm/quoter.rs`, which shrinks `sqrtK` by 0.1%
+ * — i.e. `numerator`/`denomenator` = 999/1000 — when a straight repeg to the oracle price
+ * would exceed the AMM's affordability budget). A positive result is a cost the AMM must
+ * fund from `totalFeeMinusDistributions`; shrinking K (denomenator > numerator) typically
+ * yields a negative cost (a rebate) since it reduces the AMM's net unrealized exposure.
+ * @param amm AMM state (uses `baseAssetReserve`, `quoteAssetReserve`, `baseAssetAmountWithAmm`, `pegMultiplier`).
+ * @param numerator Numerator of the K scale factor (e.g. 999).
+ * @param denomenator Denominator of the K scale factor (e.g. 1000).
+ * @returns Cost of the K adjustment, QUOTE_PRECISION (1e6).
  */
 export declare function calculateAdjustKCost(amm: AMM, numerator: BN, denomenator: BN): BN;
 /**
- * Helper function calculating adjust pegMultiplier (repeg) cost
- *
- * @param amm
- * @param newPeg
- * @returns cost : Precision QUOTE_ASSET_PRECISION
+ * Calculates the quote-denominated cost of moving the AMM's `pegMultiplier` to `newPeg`,
+ * mirroring `calculate_repeg_cost` in `vlp/amm/math/repeg.rs`: `(quoteAssetReserve -
+ * terminalQuoteAssetReserve) * (newPeg - pegMultiplier) / AMM_TO_QUOTE_PRECISION_RATIO`.
+ * The sign follows the AMM's inventory skew (`quoteAssetReserve - terminalQuoteAssetReserve`)
+ * — repegging in the direction that favors the AMM's current net position is free or a
+ * rebate; repegging against it costs `totalFeeMinusDistributions`. Zero when the AMM carries
+ * no net inventory (`quoteAssetReserve == terminalQuoteAssetReserve`).
+ * @param amm AMM state (uses `quoteAssetReserve`, `terminalQuoteAssetReserve`, `pegMultiplier`).
+ * @param newPeg Candidate peg multiplier, PEG_PRECISION (1e6).
+ * @returns Signed cost of the repeg, QUOTE_PRECISION (1e6).
  */
 export declare function calculateRepegCost(amm: AMM, newPeg: BN): BN;
+/**
+ * Solves for a `sqrtK` scale factor `numerator / denominator` such that repegging the AMM
+ * to price-neutral (holding the terminal/reserve price relationship implied by the current
+ * inventory) costs exactly `budget`. Used as the closed-form companion to
+ * `calculateAdjustKCost` (same K-shrink mechanism as the program's `adjust_k_cost_and_update`)
+ * when solving for "how much must K move to spend exactly this much." Falls back to a fixed
+ * `[10000, 1]` (10000x factor) if the budget is negative (protocol spending to increase K) and the
+ * solution would be numerically unstable.
+ * @param x AMM `baseAssetReserve`, AMM_RESERVE_PRECISION (1e9).
+ * @param y AMM `quoteAssetReserve`, AMM_RESERVE_PRECISION (1e9).
+ * @param budget Quote budget available to spend on the K adjustment, QUOTE_PRECISION (1e6).
+ * @param Q AMM `pegMultiplier`, PEG_PRECISION (1e6).
+ * @param d AMM `baseAssetAmountWithAmm` (net AMM inventory), AMM_RESERVE_PRECISION (1e9).
+ * @returns `[numerator, denominator]` scale factor to apply to `sqrtK`/`baseAssetReserve`.
+ */
 export declare function calculateBudgetedKBN(x: BN, y: BN, budget: BN, Q: BN, d: BN): [BN, BN];
+/**
+ * Calculates the largest peg move affordable within `budget`, capped so it never overshoots
+ * `targetPrice`'s implied peg. Mirrors the "use full budget peg" branch of `adjust_amm` in
+ * `vlp/amm/math/repeg.rs`: computes a per-peg-unit cost from the AMM's inventory skew, then
+ * returns `targetPeg` directly whenever moving toward it is free or revenue-generating
+ * (`useTargetPeg`), otherwise walks the peg by `budget / perPegCost` and floors it at 1.
+ * @param amm AMM state (uses `quoteAssetReserve`, `terminalQuoteAssetReserve`, `baseAssetReserve`, `pegMultiplier`).
+ * @param budget Quote budget available to spend on the repeg, QUOTE_PRECISION (1e6).
+ * @param targetPrice Oracle-implied target price driving the optimal peg, PRICE_PRECISION (1e6).
+ * @returns New peg multiplier, PEG_PRECISION (1e6), never below 1.
+ */
 export declare function calculateBudgetedPeg(amm: AMM, budget: BN, targetPrice: BN): BN;

package/lib/browser/math/repeg.js

@@ -5,11 +5,18 @@ const anchor_1 = require("../isomorphic/anchor");
 const assert_1 = require("../assert/assert");
 const numericConstants_1 = require("../constants/numericConstants");
 /**
- * Helper function calculating adjust k cost
- * @param amm
- * @param numerator
- * @param denomenator
- * @returns cost : Precision QUOTE_ASSET_PRECISION
+ * Closed-form estimate of the quote-denominated cost of scaling the AMM's `sqrtK`
+ * (liquidity depth) by `numerator / denomenator` while holding `pegMultiplier` fixed.
+ * Used by `calculateNewAmm` as the cheap-to-compute stand-in for the program's K-shrink
+ * step (`adjust_k_cost_and_update` in `vlp/amm/quoter.rs`, which shrinks `sqrtK` by 0.1%
+ * — i.e. `numerator`/`denomenator` = 999/1000 — when a straight repeg to the oracle price
+ * would exceed the AMM's affordability budget). A positive result is a cost the AMM must
+ * fund from `totalFeeMinusDistributions`; shrinking K (denomenator > numerator) typically
+ * yields a negative cost (a rebate) since it reduces the AMM's net unrealized exposure.
+ * @param amm AMM state (uses `baseAssetReserve`, `quoteAssetReserve`, `baseAssetAmountWithAmm`, `pegMultiplier`).
+ * @param numerator Numerator of the K scale factor (e.g. 999).
+ * @param denomenator Denominator of the K scale factor (e.g. 1000).
+ * @returns Cost of the K adjustment, QUOTE_PRECISION (1e6).
  */
 function calculateAdjustKCost(amm, numerator, denomenator) {
     // const k = market.amm.sqrtK.mul(market.amm.sqrtK);
@@ -61,11 +68,16 @@ exports.calculateAdjustKCost = calculateAdjustKCost;
 // 		);
 // }
 /**
- * Helper function calculating adjust pegMultiplier (repeg) cost
- *
- * @param amm
- * @param newPeg
- * @returns cost : Precision QUOTE_ASSET_PRECISION
+ * Calculates the quote-denominated cost of moving the AMM's `pegMultiplier` to `newPeg`,
+ * mirroring `calculate_repeg_cost` in `vlp/amm/math/repeg.rs`: `(quoteAssetReserve -
+ * terminalQuoteAssetReserve) * (newPeg - pegMultiplier) / AMM_TO_QUOTE_PRECISION_RATIO`.
+ * The sign follows the AMM's inventory skew (`quoteAssetReserve - terminalQuoteAssetReserve`)
+ * — repegging in the direction that favors the AMM's current net position is free or a
+ * rebate; repegging against it costs `totalFeeMinusDistributions`. Zero when the AMM carries
+ * no net inventory (`quoteAssetReserve == terminalQuoteAssetReserve`).
+ * @param amm AMM state (uses `quoteAssetReserve`, `terminalQuoteAssetReserve`, `pegMultiplier`).
+ * @param newPeg Candidate peg multiplier, PEG_PRECISION (1e6).
+ * @returns Signed cost of the repeg, QUOTE_PRECISION (1e6).
  */
 function calculateRepegCost(amm, newPeg) {
     const dqar = amm.quoteAssetReserve.sub(amm.terminalQuoteAssetReserve);
@@ -76,6 +88,21 @@ function calculateRepegCost(amm, newPeg) {
     return cost;
 }
 exports.calculateRepegCost = calculateRepegCost;
+/**
+ * Solves for a `sqrtK` scale factor `numerator / denominator` such that repegging the AMM
+ * to price-neutral (holding the terminal/reserve price relationship implied by the current
+ * inventory) costs exactly `budget`. Used as the closed-form companion to
+ * `calculateAdjustKCost` (same K-shrink mechanism as the program's `adjust_k_cost_and_update`)
+ * when solving for "how much must K move to spend exactly this much." Falls back to a fixed
+ * `[10000, 1]` (10000x factor) if the budget is negative (protocol spending to increase K) and the
+ * solution would be numerically unstable.
+ * @param x AMM `baseAssetReserve`, AMM_RESERVE_PRECISION (1e9).
+ * @param y AMM `quoteAssetReserve`, AMM_RESERVE_PRECISION (1e9).
+ * @param budget Quote budget available to spend on the K adjustment, QUOTE_PRECISION (1e6).
+ * @param Q AMM `pegMultiplier`, PEG_PRECISION (1e6).
+ * @param d AMM `baseAssetAmountWithAmm` (net AMM inventory), AMM_RESERVE_PRECISION (1e9).
+ * @returns `[numerator, denominator]` scale factor to apply to `sqrtK`/`baseAssetReserve`.
+ */
 function calculateBudgetedKBN(x, y, budget, Q, d) {
     (0, assert_1.assert)(Q.gt(new anchor_1.BN(0)));
     const C = budget.mul(new anchor_1.BN(-1));
@@ -115,6 +142,17 @@ function calculateBudgetedKBN(x, y, budget, Q, d) {
     return [numerator, denominator];
 }
 exports.calculateBudgetedKBN = calculateBudgetedKBN;
+/**
+ * Calculates the largest peg move affordable within `budget`, capped so it never overshoots
+ * `targetPrice`'s implied peg. Mirrors the "use full budget peg" branch of `adjust_amm` in
+ * `vlp/amm/math/repeg.rs`: computes a per-peg-unit cost from the AMM's inventory skew, then
+ * returns `targetPeg` directly whenever moving toward it is free or revenue-generating
+ * (`useTargetPeg`), otherwise walks the peg by `budget / perPegCost` and floors it at 1.
+ * @param amm AMM state (uses `quoteAssetReserve`, `terminalQuoteAssetReserve`, `baseAssetReserve`, `pegMultiplier`).
+ * @param budget Quote budget available to spend on the repeg, QUOTE_PRECISION (1e6).
+ * @param targetPrice Oracle-implied target price driving the optimal peg, PRICE_PRECISION (1e6).
+ * @returns New peg multiplier, PEG_PRECISION (1e6), never below 1.
+ */
 function calculateBudgetedPeg(amm, budget, targetPrice) {
     let perPegCost = amm.quoteAssetReserve
         .sub(amm.terminalQuoteAssetReserve)