@velocity-exchange/sdk 0.2.5 → 0.4.0

package/src/math/orders.ts

@@ -30,6 +30,7 @@ import {
 } from './amm';
 import { calculateSizePremiumLiabilityWeight } from './margin';
 
+/** Rounds `baseAssetAmount` down to the nearest multiple of `stepSize` (always truncates toward zero — never rounds up), matching the on-chain order/fill step-size standardization. @param baseAssetAmount Amount to round, BASE_PRECISION (1e9). @param stepSize Market's order step size, BASE_PRECISION (1e9). @returns Amount rounded down to a `stepSize` multiple, BASE_PRECISION (1e9). */
 export function standardizeBaseAssetAmount(
 	baseAssetAmount: BN,
 	stepSize: BN
@@ -38,13 +39,32 @@ export function standardizeBaseAssetAmount(
 	return baseAssetAmount.sub(remainder);
 }
 
+/**
+ * Rounds `price` to a multiple of `tickSize`, rounding in the direction that's conservative
+ * for the order's side: down for a long (never overpay past the tick) and up for a short
+ * (never undersell past the tick). Used across auction pricing and limit-price derivation so
+ * every price the SDK produces already lines up with the market's `orderTickSize` before it
+ * reaches the program, avoiding the on-chain tick-size rejection this standardization fix
+ * addresses. A `tickSize <= 0` (unset/no constraint) or `price == 0` passes through
+ * unchanged.
+ * @param price Price to standardize, PRICE_PRECISION (1e6).
+ * @param tickSize Market's order tick size, PRICE_PRECISION (1e6). Non-positive means "no tick constraint."
+ * @param direction Order side; determines rounding direction.
+ * @returns `price` rounded to the nearest tick in the conservative direction, PRICE_PRECISION (1e6).
+ */
 export function standardizePrice(
 	price: BN,
 	tickSize: BN,
 	direction: PositionDirection
 ): BN {
 	if (price.eq(ZERO)) {
-		console.log('price is zero');
+		return price;
+	}
+
+	// A non-positive tick size means "no tick constraint" (e.g. unset markets);
+	// on-chain markets always have tick_size >= 1, but guard against a zero
+	// divisor rather than throwing.
+	if (tickSize.lte(ZERO)) {
 		return price;
 	}
 
@@ -60,23 +80,43 @@ export function standardizePrice(
 	}
 }
 
+/**
+ * Resolves an order's effective limit price at the current slot, standardized to
+ * `tickSize`: the in-progress auction price while the auction hasn't completed, the
+ * oracle-offset price for oracle-pegged orders, the order's fixed `price` if set, or
+ * `fallbackPrice` (also standardized) for a market order with no price/offset/auction.
+ * @param order Order to price.
+ * @param oraclePriceData Oracle price source — use `MMOraclePriceData` for perp orders, `OraclePriceData` for spot.
+ * @param slot Current slot, used to evaluate auction progress.
+ * @param fallbackPrice Price to return for a market order with no auction/offset/fixed price (e.g. a mark or oracle price), PRICE_PRECISION (1e6).
+ * @param tickSize Market's order tick size, PRICE_PRECISION (1e6). Defaults to `ONE` (no effective standardization).
+ * @returns Limit price, PRICE_PRECISION (1e6); `undefined` if the order has no resolvable price and no `fallbackPrice` was given.
+ */
 export function getLimitPrice<T extends MarketTypeStr>(
 	order: Order,
 	oraclePriceData: T extends 'spot' ? OraclePriceData : MMOraclePriceData,
 	slot: number,
-	fallbackPrice?: BN
+	fallbackPrice?: BN,
+	tickSize: BN = ONE
 ): BN | undefined {
 	if (hasAuctionPrice(order, slot)) {
-		return getAuctionPrice(order, slot, oraclePriceData.price);
+		return getAuctionPrice(order, slot, oraclePriceData.price, tickSize);
 	} else if (!order.oraclePriceOffset.eq(ZERO)) {
-		return BN.max(oraclePriceData.price.add(order.oraclePriceOffset), ONE);
+		const limitPrice = BN.max(
+			oraclePriceData.price.add(order.oraclePriceOffset),
+			tickSize
+		);
+		return standardizePrice(limitPrice, tickSize, order.direction);
 	} else if (order.price.eq(ZERO)) {
-		return fallbackPrice;
+		return fallbackPrice === undefined
+			? undefined
+			: standardizePrice(fallbackPrice, tickSize, order.direction);
 	} else {
 		return order.price;
 	}
 }
 
+/** True if the order has any way to resolve a limit price right now: a fixed `price`, a nonzero oracle offset, or an auction still in progress. */
 export function hasLimitPrice(order: Order, slot: number): boolean {
 	return (
 		order.price.gt(ZERO) ||
@@ -85,6 +125,7 @@ export function hasLimitPrice(order: Order, slot: number): boolean {
 	);
 }
 
+/** True if the order still has an active (incomplete) auction with a nonzero start or end price. */
 export function hasAuctionPrice(order: Order, slot: number): boolean {
 	return (
 		!isAuctionComplete(order, slot) &&
@@ -92,6 +133,19 @@ export function hasAuctionPrice(order: Order, slot: number): boolean {
 	);
 }
 
+/**
+ * True if the AMM is currently a fillable liquidity source for `order` — either it's
+ * expired (always fillable to clean up), or the AMM has fillable size at the order's limit
+ * price AND is an allowed liquidity source right now (`isFallbackAvailableLiquiditySource`,
+ * which gates on oracle validity and low-risk-for-AMM classification).
+ * @param order Order to check.
+ * @param market Perp market the order is on.
+ * @param mmOraclePriceData Current MM oracle price data.
+ * @param slot Current slot.
+ * @param ts Current unix timestamp (seconds), used for expiry.
+ * @param state Global state, providing oracle guard rails and paused-operations flags.
+ * @returns `true` if the AMM may currently fill this order.
+ */
 export function isFillableByVAMM(
 	order: Order,
 	market: PerpMarketAccount,
@@ -118,6 +172,17 @@ export function isFillableByVAMM(
 	);
 }
 
+/**
+ * True if filling `order` against the AMM is considered low-risk even when the MM oracle
+ * isn't fully valid, approximating `Order::is_low_risk_for_amm` in
+ * `programs/velocity/src/state/user.rs`. Always false for spot orders. True when the order
+ * was placed at or before the MM oracle's slot (so it can't be exploiting oracle staleness),
+ * during liquidation, or when the order carries the `SafeTriggerOrder` bit flag.
+ * @param order Order to check.
+ * @param mmOraclePriceData Current MM oracle price data, used for its `slot`.
+ * @param isLiquidation Whether the fill is part of a liquidation (always low-risk if so).
+ * @returns `true` if the order is low-risk for an AMM fill under a degraded oracle.
+ */
 export function isLowRiskForAmm(
 	order: Order,
 	mmOraclePriceData: MMOraclePriceData,
@@ -138,6 +203,19 @@ export function isLowRiskForAmm(
 	);
 }
 
+/**
+ * Calculates how much of `order` the AMM can currently fill, capped by both the order's
+ * limit price (via `calculateBaseAssetAmountToFillUpToLimitPrice`, standardized to
+ * `market.orderTickSize`) and the AMM's own max fillable size
+ * (`calculateMaxBaseAssetAmountFillable`). Returns zero for a not-yet-triggered
+ * trigger order. Prices against `calculateUpdatedAMM` (i.e. the repegged/curve-updated AMM
+ * state), not the raw stored reserves.
+ * @param order Order to evaluate.
+ * @param market Perp market the order is on.
+ * @param mmOraclePriceData Current MM oracle price data.
+ * @param slot Current slot.
+ * @returns Fillable base asset amount, BASE_PRECISION (1e9).
+ */
 export function calculateBaseAssetAmountForAmmToFulfill(
 	order: Order,
 	market: PerpMarketAccount,
@@ -148,7 +226,13 @@ export function calculateBaseAssetAmountForAmmToFulfill(
 		return ZERO;
 	}
 
-	const limitPrice = getLimitPrice(order, mmOraclePriceData, slot);
+	const limitPrice = getLimitPrice(
+		order,
+		mmOraclePriceData,
+		slot,
+		undefined,
+		market.orderTickSize
+	);
 	let baseAssetAmount;
 
 	const updatedAMM = calculateUpdatedAMM(market.amm, mmOraclePriceData);
@@ -175,6 +259,21 @@ export function calculateBaseAssetAmountForAmmToFulfill(
 	return BN.min(maxBaseAssetAmount, baseAssetAmount);
 }
 
+/**
+ * Calculates how much base asset the AMM can trade against `order` without crossing its
+ * limit price, adjusting the limit by one tick in the order's favor (so the AMM never fills
+ * exactly at the boundary) before asking `calculateMaxBaseAssetAmountToTrade` how much
+ * inventory the AMM has at that price. Returns zero if the AMM would only trade in the
+ * opposite direction from the order. Caps the result at the order's unfilled remainder.
+ * @param order Order being filled.
+ * @param amm AMM state to trade against.
+ * @param marketStats Market stats needed to compute spread reserves.
+ * @param orderStepSize Market's order step size, BASE_PRECISION (1e9), used to standardize the result.
+ * @param orderTickSize Market's order tick size, PRICE_PRECISION (1e6), used to adjust the limit price by one tick.
+ * @param limitPrice Order's limit price, PRICE_PRECISION (1e6).
+ * @param mmOraclePriceData Current MM oracle price data.
+ * @returns Fillable base asset amount up to the limit price, BASE_PRECISION (1e9).
+ */
 export function calculateBaseAssetAmountToFillUpToLimitPrice(
 	order: Order,
 	amm: AMM,
@@ -225,6 +324,15 @@ function isSameDirection(
 	);
 }
 
+/**
+ * True if `order.maxTs` has passed as of `ts`. Never true for trigger orders, non-`open`
+ * orders, or orders with no expiry (`maxTs == 0`).
+ * @param order Order to check.
+ * @param ts Current unix timestamp (seconds).
+ * @param enforceBuffer If true, extends `maxTs` by `bufferSeconds` before comparing, but only for limit orders (default false) — gives resting limit orders a grace period before being treated as expired.
+ * @param bufferSeconds Grace period in seconds applied when `enforceBuffer` is true (default 15).
+ * @returns `true` if the order has expired.
+ */
 export function isOrderExpired(
 	order: Order,
 	ts: number,
@@ -249,18 +357,22 @@ export function isOrderExpired(
 	return new BN(ts).gt(maxTs);
 }
 
+/** True if `order.orderType` is `market`, `triggerMarket`, or `oracle`. */
 export function isMarketOrder(order: Order): boolean {
 	return isOneOfVariant(order.orderType, ['market', 'triggerMarket', 'oracle']);
 }
 
+/** True if `order.orderType` is `limit` or `triggerLimit`. */
 export function isLimitOrder(order: Order): boolean {
 	return isOneOfVariant(order.orderType, ['limit', 'triggerLimit']);
 }
 
+/** True if the order requires a trigger condition to fire before it becomes fillable (`triggerMarket`/`triggerLimit`). */
 export function mustBeTriggered(order: Order): boolean {
 	return isOneOfVariant(order.orderType, ['triggerMarket', 'triggerLimit']);
 }
 
+/** True if a trigger order's condition has already fired (`triggeredAbove`/`triggeredBelow`). */
 export function isTriggered(order: Order): boolean {
 	return isOneOfVariant(order.triggerCondition, [
 		'triggeredAbove',
@@ -268,6 +380,7 @@ export function isTriggered(order: Order): boolean {
 	]);
 }
 
+/** True if a limit order currently rests on the book — i.e. it's `postOnly`, or its auction (if any) has completed. Always false for non-limit orders. */
 export function isRestingLimitOrder(order: Order, slot: number): boolean {
 	if (!isLimitOrder(order)) {
 		return false;
@@ -276,16 +389,25 @@ export function isRestingLimitOrder(order: Order, slot: number): boolean {
 	return order.postOnly || isAuctionComplete(order, slot);
 }
 
-const FLAG_IS_SIGNED_MSG = 0x01;
+/** True if the order was submitted via the signed-message (swift/off-chain relay) path (`OrderBitFlag.SignedMessage`). */
 export function isSignedMsgOrder(order: Order): boolean {
-	return (order.bitFlags & FLAG_IS_SIGNED_MSG) !== 0;
+	return (order.bitFlags & OrderBitFlag.SignedMessage) !== 0;
 }
 
-const FLAG_HAS_BUILDER = 0x10;
+/** True if the order carries a builder-fee attribution (`OrderBitFlag.HasBuilder`) — the associated builder is entitled to a fee cut on fill. */
 export function hasBuilder(order: Order): boolean {
-	return (order.bitFlags & FLAG_HAS_BUILDER) !== 0;
+	return (order.bitFlags & OrderBitFlag.HasBuilder) !== 0;
 }
 
+/**
+ * Resolves the effective base asset amount for a reduce-only order: caps it so the order
+ * can't flip the position through zero (a reduce-only long can close at most the existing
+ * short, and vice versa). Non-reduce-only orders pass through `order.baseAssetAmount`
+ * unchanged.
+ * @param order Order to resolve.
+ * @param existingBaseAssetAmount Current position size before this order fills, BASE_PRECISION (1e9, signed).
+ * @returns Effective base asset amount, BASE_PRECISION (1e9).
+ */
 export function calculateOrderBaseAssetAmount(
 	order: Order,
 	existingBaseAssetAmount: BN
@@ -306,12 +428,15 @@ export function calculateOrderBaseAssetAmount(
 
 // ---------- inverse ----------
 /**
- * Invert the size-premium liability weight: given a target margin ratio (liability weight),
- * return the max `size` (AMM_RESERVE_PRECISION units) that still yields <= target.
- *
- * Returns:
- * - BN size (>=0) if bounded
- * - null if impossible (target < liabilityWeight) OR imfFactor == 0 (unbounded)
+ * Inverts `calculateSizePremiumLiabilityWeight` via binary search: given a target margin ratio
+ * (liability weight), finds the largest position `size` whose size-premium-adjusted liability
+ * weight is still `<= target`. Used to size down an order/position to stay under a margin-ratio
+ * target as size grows (the on-chain weight increases with `sqrt(size)` via `imfFactor`).
+ * @param target Target (max acceptable) liability weight, MARGIN_PRECISION (1e4).
+ * @param imfFactor Market's initial-margin-fraction scaling factor, SPOT_MARKET_IMF_PRECISION-scaled.
+ * @param liabilityWeight Market's base (zero-size) liability weight, MARGIN_PRECISION (1e4).
+ * @param market Perp market providing `maxOpenInterest` as a final cap on the result.
+ * @returns Max size, AMM_RESERVE_PRECISION (1e9), capped at `market.maxOpenInterest` (a zero `maxOpenInterest` means uncapped, per on-chain convention); `null` if `target < liabilityWeight` (impossible) or `imfFactor` is zero (weight is size-invariant, so no size bounds it).
  */
 export function maxSizeForTargetLiabilityWeightBN(
 	target: BN,
@@ -364,9 +489,10 @@ export function maxSizeForTargetLiabilityWeightBN(
 		}
 	}
 
-	// cap at max OI
+	// cap at max OI. A maxOpenInterest of 0 means no configured cap (unlimited),
+	// matching the on-chain convention — do not treat it as a hard cap of 0.
 	const maxOpenInterest = market.maxOpenInterest;
-	if (lo.gt(maxOpenInterest)) {
+	if (!maxOpenInterest.isZero() && lo.gt(maxOpenInterest)) {
 		return maxOpenInterest;
 	}
 

package/src/math/position.ts

@@ -26,12 +26,17 @@ import { calculateBaseAssetValueWithOracle } from './margin';
 import { calculateNetUserPnlImbalance } from './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).
  */
 export function calculateBaseAssetValue(
 	market: PerpMarketAccount,
@@ -98,13 +103,14 @@ export function 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).
  */
 export function calculatePositionPNL(
 	market: PerpMarketAccount,
@@ -137,6 +143,22 @@ export function calculatePositionPNL(
 	return pnl;
 }
 
+/**
+ * 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 function calculateClaimablePnl(
 	market: PerpMarketAccount,
 	spotMarket: SpotMarketAccount,
@@ -170,12 +192,14 @@ export function 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).
  */
 export function calculateFeesAndFundingPnl(
 	market: PerpMarketAccount,
@@ -199,13 +223,16 @@ export function 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).
  */
 export function calculateUnsettledFundingPnl(
 	market: PerpMarketAccount,
@@ -232,6 +259,16 @@ export function calculateUnsettledFundingPnl(
 	return perPositionFundingRate;
 }
 
+/**
+ * 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 function positionIsAvailable(position: PerpPosition): boolean {
 	return (
 		position.baseAssetAmount.eq(ZERO) &&
@@ -242,6 +279,7 @@ export function positionIsAvailable(position: PerpPosition): boolean {
 	);
 }
 
+/** True if `position.positionFlag` has the `BeingLiquidated` or `Bankruptcy` bit set. */
 export function positionIsBeingLiquidated(position: PerpPosition): boolean {
 	return (
 		(position.positionFlag &
@@ -251,9 +289,10 @@ export 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 function calculateBreakEvenPrice(userPosition: PerpPosition): BN {
 	if (userPosition.baseAssetAmount.eq(ZERO)) {
@@ -268,9 +307,9 @@ export 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 function calculateEntryPrice(userPosition: PerpPosition): BN {
 	if (userPosition.baseAssetAmount.eq(ZERO)) {
@@ -285,9 +324,13 @@ export 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 function calculateCostBasis(
 	userPosition: PerpPosition,
@@ -305,6 +348,7 @@ export function calculateCostBasis(
 		.abs();
 }
 
+/** Direction of the trade that would fully close `userPosition`: `SHORT` for a long position (base > 0), `LONG` otherwise (including flat). */
 export function findDirectionToClose(
 	userPosition: PerpPosition
 ): PositionDirection {
@@ -313,6 +357,7 @@ export function findDirectionToClose(
 		: PositionDirection.LONG;
 }
 
+/** The position's own directional exposure: `LONG` if `baseAssetAmount >= 0` (including flat), `SHORT` if negative. */
 export function positionCurrentDirection(
 	userPosition: PerpPosition
 ): PositionDirection {
@@ -321,10 +366,12 @@ export function positionCurrentDirection(
 		: PositionDirection.SHORT;
 }
 
+/** 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 function isEmptyPosition(userPosition: PerpPosition): boolean {
 	return userPosition.baseAssetAmount.eq(ZERO) && userPosition.openOrders === 0;
 }
 
+/** 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 function hasOpenOrders(position: PerpPosition): boolean {
 	return (
 		position.openOrders != 0 ||

package/src/math/repeg.ts

@@ -13,11 +13,18 @@ import {
 } from '../constants/numericConstants';
 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 function calculateAdjustKCost(
 	amm: AMM,
@@ -82,11 +89,16 @@ export function 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).
  */
 export function calculateRepegCost(amm: AMM, newPeg: BN): BN {
 	const dqar = amm.quoteAssetReserve.sub(amm.terminalQuoteAssetReserve);
@@ -97,6 +109,21 @@ export function calculateRepegCost(amm: AMM, newPeg: BN): BN {
 	return cost;
 }
 
+/**
+ * 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 function calculateBudgetedKBN(
 	x: BN,
 	y: BN,
@@ -148,6 +175,17 @@ export function calculateBudgetedKBN(
 	return [numerator, denominator];
 }
 
+/**
+ * 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 function calculateBudgetedPeg(
 	amm: AMM,
 	budget: BN,