@velocity-exchange/sdk 0.3.0 → 0.4.0

package/src/math/spotBalance.ts

@@ -25,6 +25,18 @@ import { PERCENTAGE_PRECISION } from '../constants/numericConstants';
 import { divCeil } from './utils';
 import { StrictOraclePrice } from '../oracles/strictOraclePrice';
 
+// BN's `.div()` truncates toward zero; the program uses `safe_div_floor` when
+// the numerator is negative (get_token_value / get_strict_token_value), so a
+// negative dividend must round toward -infinity here to match.
+function divFloor(a: BN, b: BN): BN {
+	const quotient = a.div(b);
+	const remainder = a.mod(b);
+	if (!remainder.isZero() && a.isNeg() !== b.isNeg()) {
+		return quotient.sub(ONE);
+	}
+	return quotient;
+}
+
 /**
  * Calculates the balance of a given token amount including any accumulated interest. This
  * is the same as `SpotPosition.scaledBalance`.
@@ -32,12 +44,16 @@ import { StrictOraclePrice } from '../oracles/strictOraclePrice';
  * @param {BN} tokenAmount - the amount of tokens
  * @param {SpotMarketAccount} spotMarket - the spot market account
  * @param {SpotBalanceType} balanceType - the balance type ('deposit' or 'borrow')
+ * @param {boolean} [roundUp] - override the default rounding direction (program's `round_up`);
+ *   defaults to rounding up for borrows only. Callers reducing a deposit balance while the
+ *   funds are leaving Velocity (e.g. a withdrawal) should pass `true` to match `is_leaving_velocity`.
  * @return {BN} the calculated balance, scaled by `SPOT_MARKET_BALANCE_PRECISION`
  */
 export function getBalance(
 	tokenAmount: BN,
 	spotMarket: SpotMarketAccount,
-	balanceType: SpotBalanceType
+	balanceType: SpotBalanceType,
+	roundUp?: boolean
 ): BN {
 	const precisionIncrease = TEN.pow(new BN(19 - spotMarket.decimals));
 
@@ -47,7 +63,8 @@ export function getBalance(
 
 	let balance = tokenAmount.mul(precisionIncrease).div(cumulativeInterest);
 
-	if (!balance.eq(ZERO) && isVariant(balanceType, 'borrow')) {
+	const shouldRoundUp = roundUp ?? isVariant(balanceType, 'borrow');
+	if (!balance.eq(ZERO) && shouldRoundUp) {
 		balance = balance.add(ONE);
 	}
 
@@ -123,8 +140,12 @@ export function getStrictTokenValue(
 	}
 
 	const precisionDecrease = TEN.pow(new BN(spotDecimals));
+	const tokenWithPrice = tokenAmount.mul(price);
 
-	return tokenAmount.mul(price).div(precisionDecrease);
+	if (tokenWithPrice.isNeg()) {
+		return divFloor(tokenWithPrice, precisionDecrease);
+	}
+	return tokenWithPrice.div(precisionDecrease);
 }
 
 /**
@@ -145,10 +166,30 @@ export function getTokenValue(
 	}
 
 	const precisionDecrease = TEN.pow(new BN(spotDecimals));
+	const tokenWithOraclePrice = tokenAmount.mul(oraclePriceData.price);
 
-	return tokenAmount.mul(oraclePriceData.price).div(precisionDecrease);
+	if (tokenWithOraclePrice.isNeg()) {
+		return divFloor(tokenWithOraclePrice, precisionDecrease);
+	}
+	return tokenWithOraclePrice.div(precisionDecrease);
 }
 
+/**
+ * Calculates the collateral (asset) weight applied to a spot deposit balance, mirroring
+ * `SpotMarket::get_asset_weight`'s `Initial`/`Maintenance` branches (there is no SDK
+ * equivalent of the on-chain `Fill` branch, which averages initial and maintenance).
+ * Size is first rescaled into `AMM_RESERVE_PRECISION` before the IMF size-discount is applied,
+ * so larger positions receive a lower (more conservative) weight.
+ *
+ * @param {BN} balanceAmount - The deposit token amount, scaled by the spot market's token decimals
+ * @param {BN} oraclePrice - The oracle price, PRICE_PRECISION (1e6); only used for the `Initial`
+ *   scaled-weight lookup (`calculateScaledInitialAssetWeight`)
+ * @param {SpotMarketAccount} spotMarket - The spot market account
+ * @param {MarginCategory | undefined} marginCategory - `'Initial'`, `'Maintenance'`, `'Fill'`
+ *   (the integer-averaged midpoint of scaled-initial and maintenance weights), or `undefined`
+ *   (defaults to the scaled initial weight, used for e.g. UI display outside a margin check)
+ * @return {BN} The asset weight, scaled by `SPOT_MARKET_WEIGHT_PRECISION` (1e4, i.e. 10000 = 100%)
+ */
 export function calculateAssetWeight(
 	balanceAmount: BN,
 	oraclePrice: BN,
@@ -177,6 +218,17 @@ export function calculateAssetWeight(
 				calculateScaledInitialAssetWeight(spotMarket, oraclePrice)
 			);
 			break;
+		case 'Fill':
+			// mirrors SpotMarket::get_asset_weight's Fill branch:
+			// (scaled_initial_asset_weight + maintenance_asset_weight) / 2 (integer division)
+			assetWeight = calculateSizeDiscountAssetWeight(
+				sizeInAmmReservePrecision,
+				new BN(spotMarket.imfFactor),
+				calculateScaledInitialAssetWeight(spotMarket, oraclePrice)
+					.add(new BN(spotMarket.maintenanceAssetWeight))
+					.divn(2)
+			);
+			break;
 		case 'Maintenance':
 			assetWeight = calculateSizeDiscountAssetWeight(
 				sizeInAmmReservePrecision,
@@ -192,6 +244,17 @@ export function calculateAssetWeight(
 	return assetWeight;
 }
 
+/**
+ * Calculates the initial asset weight after applying the market's optional deposit-value
+ * scaling, mirroring `SpotMarket::get_scaled_initial_asset_weight`. When
+ * `scaleInitialAssetWeightStart` is set and total deposit value exceeds it, the weight is
+ * scaled down proportionally (`initialAssetWeight * scaleInitialAssetWeightStart / depositsValue`)
+ * so the market's collateral usefulness degrades as its deposits grow past the configured cap.
+ *
+ * @param {SpotMarketAccount} spotMarket - The spot market account
+ * @param {BN} oraclePrice - The oracle price, PRICE_PRECISION (1e6), used to value total deposits
+ * @return {BN} The (possibly scaled) initial asset weight, `SPOT_MARKET_WEIGHT_PRECISION` (1e4)
+ */
 export function calculateScaledInitialAssetWeight(
 	spotMarket: SpotMarketAccount,
 	oraclePrice: BN
@@ -218,6 +281,19 @@ export function calculateScaledInitialAssetWeight(
 	}
 }
 
+/**
+ * Calculates the liability (borrow) weight applied to a spot borrow balance, mirroring
+ * `SpotMarket::get_liability_weight`'s `Initial`/`Maintenance` branches. Size is rescaled into
+ * `AMM_RESERVE_PRECISION` before the IMF size-premium is applied, so larger borrows receive a
+ * higher (more conservative) weight.
+ *
+ * @param {BN} size - The borrow token amount, scaled by the spot market's token decimals
+ * @param {SpotMarketAccount} spotMarket - The spot market account
+ * @param {MarginCategory | undefined} marginCategory - `'Initial'`, `'Maintenance'`, `'Fill'`
+ *   (the integer-averaged midpoint of initial and maintenance liability weights), or
+ *   `undefined` (defaults to `initialLiabilityWeight` with no size premium applied)
+ * @return {BN} The liability weight, scaled by `SPOT_MARKET_WEIGHT_PRECISION` (1e4, i.e. 10000 = 100%)
+ */
 export function calculateLiabilityWeight(
 	size: BN,
 	spotMarket: SpotMarketAccount,
@@ -246,6 +322,18 @@ export function calculateLiabilityWeight(
 				SPOT_MARKET_WEIGHT_PRECISION
 			);
 			break;
+		case 'Fill':
+			// mirrors SpotMarket::get_liability_weight's Fill branch:
+			// (initial_liability_weight + maintenance_liability_weight) / 2 (integer division)
+			liabilityWeight = calculateSizePremiumLiabilityWeight(
+				sizeInAmmReservePrecision,
+				new BN(spotMarket.imfFactor),
+				new BN(spotMarket.initialLiabilityWeight)
+					.add(new BN(spotMarket.maintenanceLiabilityWeight))
+					.divn(2),
+				SPOT_MARKET_WEIGHT_PRECISION
+			);
+			break;
 		case 'Maintenance':
 			liabilityWeight = calculateSizePremiumLiabilityWeight(
 				sizeInAmmReservePrecision,
@@ -262,6 +350,17 @@ export function calculateLiabilityWeight(
 	return liabilityWeight;
 }
 
+/**
+ * Calculates a spot market's utilization (borrows / deposits), mirroring
+ * `calculate_utilization`. Returns `SPOT_MARKET_UTILIZATION_PRECISION` (100% utilization) if
+ * there are borrows but no deposits, and zero if both are zero.
+ *
+ * @param {SpotMarketAccount} bank - The spot market account
+ * @param {BN} [delta] - Optional hypothetical change in token amount, scaled by the market's
+ *   token decimals: a positive delta is added to deposits, a negative delta (its absolute
+ *   value) is added to borrows. Defaults to zero (current on-chain utilization).
+ * @return {BN} Utilization, scaled by `SPOT_MARKET_UTILIZATION_PRECISION` (1e6, i.e. 1e6 = 100%)
+ */
 export function calculateUtilization(
 	bank: SpotMarketAccount,
 	delta = ZERO
@@ -298,10 +397,17 @@ export function calculateUtilization(
 }
 
 /**
- * calculates max borrow amount where rate would stay below targetBorrowRate
- * @param spotMarketAccount
- * @param targetBorrowRate
- * @returns : Precision: TOKEN DECIMALS
+ * SDK-only helper (no direct on-chain counterpart) that inverts `calculateInterestRate`'s
+ * utilization curve to find how much more can be borrowed before the borrow rate would reach
+ * `targetBorrowRate`. Useful for UI "available to borrow at rate X" displays.
+ *
+ * @param {SpotMarketAccount} spotMarketAccount - The spot market account
+ * @param {BN} targetBorrowRate - The target annualized borrow rate, `SPOT_MARKET_RATE_PRECISION` (1e6)
+ * @returns {{ totalCapacity: BN; remainingCapacity: BN }} Both scaled by the market's token
+ *   decimals. `totalCapacity` is the total borrow amount implied by the target utilization;
+ *   `remainingCapacity` is `totalCapacity` minus current borrows (zero if the market's current
+ *   borrow rate already meets or exceeds the target), additionally capped by
+ *   `maxTokenBorrowsFraction` of `maxTokenDeposits` when that cap is configured (>0)
  */
 export function calculateSpotMarketBorrowCapacity(
 	spotMarketAccount: SpotMarketAccount,
@@ -377,6 +483,21 @@ export function calculateSpotMarketBorrowCapacity(
 	return { totalCapacity, remainingCapacity };
 }
 
+/**
+ * Calculates the annualized borrow interest rate for a spot market, mirroring
+ * `calculate_borrow_rate` / the underlying utilization curve. Below `optimalUtilization` the
+ * rate ramps linearly from 0 to `optimalBorrowRate`; above it, the rate ramps through a fixed
+ * piecewise schedule (85/90/95/99/99.5/100% utilization breakpoints) from `optimalBorrowRate`
+ * up to `maxBorrowRate`. The result is floored at `minBorrowRate / 200` (i.e. `minBorrowRate`
+ * is in units of half-percentage-points of `PERCENTAGE_PRECISION`).
+ *
+ * @param {SpotMarketAccount} bank - The spot market account
+ * @param {BN} [delta] - Optional hypothetical change in token amount passed through to
+ *   `calculateUtilization` (ignored if `currentUtilization` is provided)
+ * @param {BN} [currentUtilization] - Precomputed utilization, `SPOT_MARKET_UTILIZATION_PRECISION`
+ *   (1e6); if omitted it is derived from `bank` and `delta`
+ * @return {BN} Annualized borrow rate, scaled by `SPOT_MARKET_RATE_PRECISION` (1e6)
+ */
 export function calculateInterestRate(
 	bank: SpotMarketAccount,
 	delta = ZERO,
@@ -439,6 +560,19 @@ export function calculateInterestRate(
 	return BN.max(minRate, rate);
 }
 
+/**
+ * Calculates the annualized deposit interest rate for a spot market, mirroring
+ * `calculate_deposit_rate` (velocity-rs). Lenders receive the borrow rate net of the insurance
+ * fund and protocol fee carveouts (`ifFeeFactor` + `protocolFeeFactor`, both `PERCENTAGE_PRECISION`),
+ * scaled down by utilization since only borrowed deposits earn interest.
+ *
+ * @param {SpotMarketAccount} bank - The spot market account
+ * @param {BN} [delta] - Optional hypothetical change in token amount; positive adds to deposits,
+ *   negative adds to borrows (see `calculateUtilization`)
+ * @param {BN} [currentUtilization] - Precomputed utilization, `SPOT_MARKET_UTILIZATION_PRECISION`
+ *   (1e6); if omitted it is derived from `bank` and `delta`
+ * @return {BN} Annualized deposit rate, scaled by `SPOT_MARKET_RATE_PRECISION` (1e6)
+ */
 export function calculateDepositRate(
 	bank: SpotMarketAccount,
 	delta = ZERO,
@@ -461,6 +595,14 @@ export function calculateDepositRate(
 	return depositRate;
 }
 
+/**
+ * Alias for `calculateInterestRate` (annualized borrow rate).
+ *
+ * @param {SpotMarketAccount} bank - The spot market account
+ * @param {BN} [delta] - Optional hypothetical change in token amount (see `calculateUtilization`)
+ * @param {BN} [currentUtilization] - Precomputed utilization, `SPOT_MARKET_UTILIZATION_PRECISION` (1e6)
+ * @return {BN} Annualized borrow rate, scaled by `SPOT_MARKET_RATE_PRECISION` (1e6)
+ */
 export function calculateBorrowRate(
 	bank: SpotMarketAccount,
 	delta = ZERO,
@@ -469,6 +611,28 @@ export function calculateBorrowRate(
 	return calculateInterestRate(bank, delta, currentUtilization);
 }
 
+/**
+ * Projects the cumulative interest multipliers that would accrue between `spotMarket.lastInterestTs`
+ * and `now` at the market's current interest rate, mirroring the gross amounts computed by
+ * `calculate_accumulated_interest`. This is a point-in-time estimate for display purposes only —
+ * the actual on-chain update (`update_spot_market_cumulative_interest`) re-derives the rate from
+ * utilization at settlement time (same as this function calling `calculateInterestRate(bank)` with
+ * no delta), and only runs at all if `deposit_interest > 0 && borrow_interest > 1`. Borrow interest
+ * is always rounded up by 1 (added unconditionally), matching the program's lender-favoring
+ * rounding, and is credited to `cumulativeBorrowInterest` in full. **`depositInterest` here is the
+ * gross pre-carveout amount** — on-chain, `insuranceFund.ifFeeFactor` and `protocolFeeFactor`
+ * (both `IF_FACTOR_PRECISION`) are each cut from it first (to `revenuePool` and `protocolFeePool`
+ * respectively) and only the remainder is what actually gets added to `cumulativeDepositInterest`;
+ * this function does not replicate that split, so it overstates the deposit-side increment
+ * whenever either factor is non-zero.
+ *
+ * @param {SpotMarketAccount} bank - The spot market account
+ * @param {BN} now - The timestamp (unix seconds) to project interest up to
+ * @return {{ borrowInterest: BN; depositInterest: BN }} `borrowInterest` is the exact amount added
+ *   to `cumulativeBorrowInterest`; `depositInterest` is the gross pre-carveout amount, not
+ *   necessarily what's added to `cumulativeDepositInterest` (see above). Both in the same
+ *   fixed-point units as those cumulative fields (`SPOT_MARKET_CUMULATIVE_INTEREST_PRECISION`)
+ */
 export function calculateInterestAccumulated(
 	bank: SpotMarketAccount,
 	now: BN
@@ -498,6 +662,22 @@ export function calculateInterestAccumulated(
 	return { borrowInterest, depositInterest };
 }
 
+/**
+ * Calculates the minimum deposit / maximum borrow token amounts that keep the market's
+ * utilization from exceeding a "max withdraw utilization" ceiling, mirroring
+ * `calculate_token_utilization_limits`. The ceiling is `max(optimalUtilization,
+ * utilizationTwap + (100% - utilizationTwap) / 2)` — i.e. it allows utilization to rise, but
+ * only up to halfway from the TWAP to 100%. Deposit sizes already below
+ * `withdrawGuardThreshold` are never blocked (the min-deposit result is capped so it can't
+ * exceed `depositTokenAmount - withdrawGuardThreshold`), and borrows below the guard threshold
+ * are never blocked either (the max-borrow result is floored at `withdrawGuardThreshold`).
+ *
+ * @param {BN} depositTokenAmount - Current total deposit token amount, market's token decimals
+ * @param {BN} borrowTokenAmount - Current total borrow token amount, market's token decimals
+ * @param {SpotMarketAccount} spotMarket - The spot market account
+ * @return {{ minDepositTokensForUtilization: BN; maxBorrowTokensForUtilization: BN }} Both
+ *   scaled by the market's token decimals
+ */
 export function calculateTokenUtilizationLimits(
 	depositTokenAmount: BN,
 	borrowTokenAmount: BN,
@@ -545,6 +725,32 @@ export function calculateTokenUtilizationLimits(
 	};
 }
 
+/**
+ * Estimates the current immediate withdraw/borrow limits for a spot market, mirroring the
+ * on-chain `check_withdraw_limits` / `get_max_withdraw_for_market_with_token_amount` guard
+ * (combining `calculate_min_deposit_token_amount`, `calculate_max_borrow_token_amount`, and
+ * `calculateTokenUtilizationLimits`). Because the SDK cannot force an on-chain TWAP update
+ * before reading it, this projects a "live" 24h deposit/borrow TWAP by weighting the stored
+ * TWAP and the current amount by `sinceStart`/`sinceLast` (the same weighted-average shape as
+ * `update_spot_market_twap_stats`, without its rounding bias term) before deriving limits, so
+ * the result approximates what the on-chain TWAP would be if updated at `now`.
+ *
+ * Deposit/borrow TWAP friction bands differ by pool: the main pool (`poolId === 0`) targets
+ * ~30-92.5% utilization (borrow ceiling is `lesserDepositAmount` clamped between 1/3 and
+ * 13/14 of itself, floored around the live borrow TWAP + 1/5), isolated pools (`poolId !== 0`)
+ * target ~50-95% (clamped between 1/2 and 19/20, floored around the live borrow TWAP + 1/3).
+ * `lesserDepositAmount` is `min(currentDepositAmount, live deposit TWAP)` — using the smaller of
+ * the two keeps the borrow ceiling conservative whether deposits are rising or falling.
+ * `borrowLimit` is additionally zeroed for `assetTier === 'protected'` markets, and both limits
+ * are clamped by `maxTokenBorrowsFraction` of `maxTokenDeposits` when that cap is configured.
+ *
+ * @param {SpotMarketAccount} spotMarket - The spot market account
+ * @param {BN} now - The timestamp (unix seconds) to project the live TWAP up to
+ * @return {{ borrowLimit: BN; withdrawLimit: BN; minDepositAmount: BN; maxBorrowAmount: BN;
+ *   currentDepositAmount: BN; currentBorrowAmount: BN }} All values scaled by the market's token
+ *   decimals. `withdrawLimit`/`borrowLimit` are floored at zero (a market already past its
+ *   min-deposit/max-borrow bound reports zero remaining room rather than negative)
+ */
 export function calculateWithdrawLimit(
 	spotMarket: SpotMarketAccount,
 	now: BN
@@ -591,10 +797,10 @@ export function calculateWithdrawLimit(
 			spotMarket.withdrawGuardThreshold,
 			BN.min(
 				BN.max(
-					marketDepositTokenAmount.div(new BN(3)),
-					borrowTokenTwapLive.add(lesserDepositAmount.div(new BN(7)))
+					lesserDepositAmount.div(new BN(3)),
+					borrowTokenTwapLive.add(lesserDepositAmount.div(new BN(5)))
 				),
-				lesserDepositAmount.sub(lesserDepositAmount.div(new BN(8)))
+				lesserDepositAmount.sub(lesserDepositAmount.div(new BN(14)))
 			)
 		); // main pool between ~30-92.5% utilization with friction on twap in 20% increments
 	} else {
@@ -602,7 +808,7 @@ export function calculateWithdrawLimit(
 			spotMarket.withdrawGuardThreshold,
 			BN.min(
 				BN.max(
-					marketDepositTokenAmount.div(new BN(2)),
+					lesserDepositAmount.div(new BN(2)),
 					borrowTokenTwapLive.add(lesserDepositAmount.div(new BN(3)))
 				),
 				lesserDepositAmount.sub(lesserDepositAmount.div(new BN(20)))
@@ -674,6 +880,22 @@ export function calculateWithdrawLimit(
 	};
 }
 
+/**
+ * Calculates the margin-weighted value of a spot deposit, mirroring the asset-side of the
+ * program's collateral valuation (`get_strict_token_value` + `get_asset_weight`). Uses the
+ * worst of the oracle's live price and its 5min TWAP (via `strictOraclePrice`) so a favorable
+ * price spike can't be used to over-value collateral.
+ *
+ * @param {BN} tokenAmount - The deposit token amount, scaled by `spotMarketAccount.decimals`
+ * @param {StrictOraclePrice} strictOraclePrice - Live oracle price + 5min TWAP, PRICE_PRECISION (1e6)
+ * @param {SpotMarketAccount} spotMarketAccount - The spot market account
+ * @param {number} maxMarginRatio - The user's custom max margin ratio (0 if unset), in
+ *   `SPOT_MARKET_WEIGHT_PRECISION` (1e4) units; only applied when `marginCategory === 'Initial'`
+ *   and the market isn't the quote spot market, capping the weight at
+ *   `SPOT_MARKET_WEIGHT_PRECISION - maxMarginRatio`
+ * @param {MarginCategory} [marginCategory] - When omitted, returns the unweighted (100%) value
+ * @return {BN} The (optionally weighted) asset value, scaled by `PRICE_PRECISION` (1e6)
+ */
 export function getSpotAssetValue(
 	tokenAmount: BN,
 	strictOraclePrice: StrictOraclePrice,
@@ -712,6 +934,24 @@ export function getSpotAssetValue(
 	return assetValue;
 }
 
+/**
+ * Calculates the margin-weighted value of a spot borrow, mirroring the liability-side of the
+ * program's collateral valuation (`get_strict_token_value` + `get_liability_weight`). Uses the
+ * worst of the oracle's live price and its 5min TWAP (via `strictOraclePrice`) so a favorable
+ * price dip can't be used to under-value a liability.
+ *
+ * @param {BN} tokenAmount - The borrow token amount (positive), scaled by `spotMarketAccount.decimals`
+ * @param {StrictOraclePrice} strictOraclePrice - Live oracle price + 5min TWAP, PRICE_PRECISION (1e6)
+ * @param {SpotMarketAccount} spotMarketAccount - The spot market account
+ * @param {number} maxMarginRatio - The user's custom max margin ratio (0 if unset),
+ *   `SPOT_MARKET_WEIGHT_PRECISION` (1e4) units; only applied when `marginCategory === 'Initial'`
+ *   and the market isn't the quote spot market, flooring the weight at
+ *   `SPOT_MARKET_WEIGHT_PRECISION + maxMarginRatio`
+ * @param {MarginCategory} [marginCategory] - When omitted, returns the unweighted (100%) value
+ * @param {BN} [liquidationBuffer] - Extra weight added on top (`SPOT_MARKET_WEIGHT_PRECISION`
+ *   units) to make maintenance margin checks stricter during liquidation eligibility checks
+ * @return {BN} The (optionally weighted) liability value, scaled by `PRICE_PRECISION` (1e6)
+ */
 export function getSpotLiabilityValue(
 	tokenAmount: BN,
 	strictOraclePrice: StrictOraclePrice,

package/src/math/spotMarket.ts

@@ -13,6 +13,16 @@ import {
 import { MARGIN_PRECISION, ZERO } from '../constants/numericConstants';
 import { numberToSafeBN } from './utils';
 
+/**
+ * Converts a human-readable number or `BN` into the spot market's on-chain token precision
+ * (`10 ** spotMarket.decimals`). Both inputs are treated as whole-token amounts and multiplied
+ * by the market's precision.
+ *
+ * @param {number | BN} value - A human-readable amount, or a `BN` expressed in whole
+ *   tokens (not yet scaled) that will be multiplied by the market's precision
+ * @param {SpotMarketAccount} spotMarket - The spot market account (supplies `decimals`)
+ * @return {BN} The token amount scaled by `10 ** spotMarket.decimals`
+ */
 export function castNumberToSpotPrecision(
 	value: number | BN,
 	spotMarket: SpotMarketAccount
@@ -24,6 +34,22 @@ export function castNumberToSpotPrecision(
 	}
 }
 
+/**
+ * Calculates the effective margin ratio for a spot deposit or borrow position, expressed as
+ * `MARGIN_PRECISION - assetWeight` (deposits) or `liabilityWeight - MARGIN_PRECISION` (borrows).
+ * Note `MARGIN_PRECISION` and `SPOT_MARKET_WEIGHT_PRECISION` are both 1e4, so weights and margin
+ * ratios share the same scale.
+ *
+ * @param {SpotMarketAccount} market - The spot market account
+ * @param {BN} oraclePrice - The oracle price, PRICE_PRECISION (1e6)
+ * @param {MarginCategory} marginCategory - `'Initial'` or `'Maintenance'`
+ * @param {BN} size - The position size, scaled by `market.decimals`
+ * @param {SpotBalanceType} balanceType - Whether `size` is a deposit or a borrow
+ * @param {number} [customMarginRatio] - User's custom max margin ratio, `MARGIN_PRECISION` (1e4)
+ *   units; only takes effect for `'Initial'`, where the looser (higher) of the computed ratio
+ *   and this value is used, so a user can only demand *more* margin than the market default
+ * @return {number} The margin ratio, scaled by `MARGIN_PRECISION` (1e4, i.e. 10000 = 100%)
+ */
 export function calculateSpotMarketMarginRatio(
 	market: SpotMarketAccount,
 	oraclePrice: BN,
@@ -60,9 +86,16 @@ export function calculateSpotMarketMarginRatio(
 }
 
 /**
- * Returns the maximum remaining deposit that can be made to the spot market. If the maxTokenDeposits on the market is zero then there is no limit and this function will also return zero. (so that needs to be checked)
- * @param market
- * @returns
+ * Calculates the remaining room under the spot market's deposit cap, mirroring the check in the
+ * program's deposit handler (`deposit_token_amount + amount <= max_token_deposits`, when the cap
+ * is set).
+ *
+ * @param {SpotMarketAccount} market - The spot market account
+ * @return {BN} `market.maxTokenDeposits - currentDeposits` (floored at zero), scaled by
+ *   `market.decimals`. **Ambiguous zero:** returns `ZERO` both when `maxTokenDeposits === 0`
+ *   (cap disabled, deposits are actually unlimited) and when the cap is enabled but already
+ *   fully utilized — callers must check `market.maxTokenDeposits.eq(ZERO)` separately to tell
+ *   "no limit" from "no room left".
  */
 export function calculateMaxRemainingDeposit(market: SpotMarketAccount) {
 	const marketMaxTokenDeposits = market.maxTokenDeposits;

package/src/math/spotPosition.ts

@@ -15,19 +15,56 @@ import {
 } from './spotBalance';
 import { StrictOraclePrice } from '../oracles/strictOraclePrice';
 
+/**
+ * True if a `SpotPosition` slot has no balance and no open orders, meaning it is free to be
+ * reused (or shown as empty) rather than representing an active position.
+ *
+ * @param {SpotPosition} position - The spot position
+ * @return {boolean} Whether the slot is unused
+ */
 export function isSpotPositionAvailable(position: SpotPosition): boolean {
 	return position.scaledBalance.eq(ZERO) && position.openOrders === 0;
 }
 
+/**
+ * Result of simulating a spot position's collateral contribution, optionally after its resting
+ * open orders are assumed to fill. All quote-denominated fields are `PRICE_PRECISION` (1e6).
+ */
 export type OrderFillSimulation = {
+	/** Signed token amount (base for non-quote markets), the market's token decimals */
 	tokenAmount: BN;
+	/** Value of the open orders assumed to fill, at the worst-case (max) oracle price */
 	ordersValue: BN;
+	/** Strict-oracle value of `tokenAmount` before margin weighting */
 	tokenValue: BN;
+	/** Asset or liability weight applied to `tokenValue`, `SPOT_MARKET_WEIGHT_PRECISION` (1e4) */
 	weight: BN;
+	/** `tokenValue` after applying `weight` */
 	weightedTokenValue: BN;
+	/** Net contribution to free collateral: `weightedTokenValue` plus `ordersValue` where applicable */
 	freeCollateralContribution: BN;
 };
 
+/**
+ * Calculates a spot position's worst-case token amount and margin contribution, accounting for
+ * the possibility that its resting open bids or asks could fill. Mirrors the program's
+ * worst-case spot balance logic used in margin/health checks: if both `openBids` and `openAsks`
+ * are zero (or `includeOpenOrders` is false), the position's current balance is valued as-is;
+ * otherwise the function separately simulates full fill of the bids and of the asks
+ * (`simulateOrderFill`) and returns whichever leaves the *lower* `freeCollateralContribution` —
+ * i.e. the more conservative (worse-case) scenario for margin purposes.
+ *
+ * @param {SpotPosition} spotPosition - The user's spot position
+ * @param {SpotMarketAccount} spotMarketAccount - The spot market account
+ * @param {StrictOraclePrice} strictOraclePrice - Live oracle price + 5min TWAP, PRICE_PRECISION (1e6)
+ * @param {MarginCategory | undefined} marginCategory - `'Initial'`, `'Maintenance'`, or
+ *   `undefined` for an unweighted valuation
+ * @param {number} [customMarginRatio] - User's custom max margin ratio (`'Initial'` only); see
+ *   `calculateWeightedTokenValue`
+ * @param {boolean} [includeOpenOrders] - Whether to simulate open order fills at all; defaults
+ *   to `true`. When `false`, only the current balance is valued regardless of open orders.
+ * @return {OrderFillSimulation} The worst-case simulation result
+ */
 export function getWorstCaseTokenAmounts(
 	spotPosition: SpotPosition,
 	spotMarketAccount: SpotMarketAccount,
@@ -103,6 +140,24 @@ export function getWorstCaseTokenAmounts(
 	}
 }
 
+/**
+ * Applies the appropriate asset or liability weight (based on the sign of `tokenValue`) to a
+ * token value, mirroring the program's `calculate_weighted_token_value` closure used in both
+ * plain and worst-case-fill spot margin calculations.
+ *
+ * @param {BN} tokenAmount - Signed token amount, used (as `abs()`) for the IMF size adjustment
+ * @param {BN} tokenValue - Signed strict-oracle value, `PRICE_PRECISION` (1e6); sign selects
+ *   asset weight (`>= 0`) vs liability weight (`< 0`)
+ * @param {BN} oraclePrice - The oracle price, PRICE_PRECISION (1e6), passed through to
+ *   `calculateAssetWeight` for the initial-weight deposit-value scaling lookup
+ * @param {SpotMarketAccount} spotMarket - The spot market account
+ * @param {MarginCategory | undefined} marginCategory - `'Initial'`, `'Maintenance'`, or `undefined`
+ * @param {number} [customMarginRatio] - User's custom max margin ratio, `SPOT_MARKET_WEIGHT_PRECISION`
+ *   (1e4) units; only applied for `'Initial'` on non-quote markets, tightening (never loosening)
+ *   the weight in the direction unfavorable to the user
+ * @return {{ weight: BN; weightedTokenValue: BN }} `weight` in `SPOT_MARKET_WEIGHT_PRECISION`
+ *   (1e4); `weightedTokenValue` in `PRICE_PRECISION` (1e6)
+ */
 export function calculateWeightedTokenValue(
 	tokenAmount: BN,
 	tokenValue: BN,
@@ -152,6 +207,23 @@ export function calculateWeightedTokenValue(
 	};
 }
 
+/**
+ * Simulates one side (bids or asks) of a spot position's open orders fully filling, and
+ * recomputes the resulting margin contribution. Mirrors the per-side branch of the program's
+ * `simulate_fills_both_sides`. The filled orders' value is valued at the *worst-case* price
+ * (`strictOraclePrice.max()`) regardless of side, since filling either bids or asks moves the
+ * position further from its current state in the direction that could hurt collateral value.
+ *
+ * @param {BN} tokenAmount - Current signed token amount before the simulated fill
+ * @param {BN} tokenValue - Current strict-oracle token value before the simulated fill, `PRICE_PRECISION` (1e6)
+ * @param {BN} openOrders - Signed open order base size for this side: `spotPosition.openBids`
+ *   (stored positive) or `spotPosition.openAsks` (stored negative), the market's token decimals
+ * @param {StrictOraclePrice} strictOraclePrice - Live oracle price + 5min TWAP, PRICE_PRECISION (1e6)
+ * @param {SpotMarketAccount} spotMarket - The spot market account
+ * @param {MarginCategory | undefined} marginCategory - `'Initial'`, `'Maintenance'`, or `undefined`
+ * @param {number} [customMarginRatio] - User's custom max margin ratio; see `calculateWeightedTokenValue`
+ * @return {OrderFillSimulation} The post-fill simulation for this side
+ */
 export function simulateOrderFill(
 	tokenAmount: BN,
 	tokenValue: BN,

package/src/math/state.ts

@@ -6,6 +6,19 @@ import {
 } from '../constants/numericConstants';
 import { FeatureBitFlags, StateAccount } from '../types';
 
+/**
+ * Calculates the SOL fee that will be charged to initialize a new sub-account, mirroring
+ * `State::get_init_user_fee`'s account-space-utilization scaling: once sub-account utilization
+ * passes 80% of the max allowed, the fee ramps linearly from 0 up to `maxInitializeUserFee` at
+ * 100% utilization; below 80% it's free. `numberOfSubAccounts` is incremented by 1 before this
+ * ratio is computed because the on-chain handler bumps `state.numberOfSubAccounts` *before*
+ * calling `get_init_user_fee` — so a client reading pre-transaction state must simulate that
+ * increment itself to predict the fee the transaction will actually charge.
+ *
+ * @param {StateAccount} stateAccount - The global state account, read before submitting the
+ *   `initializeUser` transaction
+ * @return {BN} The init fee in lamports, `LAMPORTS_PRECISION` (1e9)
+ */
 export function calculateInitUserFee(stateAccount: StateAccount): BN {
 	const maxInitFee = new BN(stateAccount.maxInitializeUserFee)
 		.mul(LAMPORTS_PRECISION)
@@ -26,6 +39,15 @@ export function calculateInitUserFee(stateAccount: StateAccount): BN {
 	}
 }
 
+/**
+ * Calculates the effective max number of sub-accounts allowed per authority, mirroring
+ * `State::max_number_of_sub_accounts`. Values of 5 or below are used as-is (an explicit small
+ * cap); values above 5 are multiplied by 100, letting the admin store a compact "hundreds" unit
+ * for large caps.
+ *
+ * @param {StateAccount} stateAccount - The global state account
+ * @return {BN} The effective max sub-account count (unitless count, not a token amount)
+ */
 export function getMaxNumberOfSubAccounts(stateAccount: StateAccount): BN {
 	if (stateAccount.maxNumberOfSubAccounts <= 5) {
 		return new BN(stateAccount.maxNumberOfSubAccounts);
@@ -33,6 +55,15 @@ export function getMaxNumberOfSubAccounts(stateAccount: StateAccount): BN {
 	return new BN(stateAccount.maxNumberOfSubAccounts).muln(100);
 }
 
+/**
+ * True if the protocol-wide feature flag for median-based trigger prices is enabled, mirroring
+ * `State::use_median_trigger_price`. When enabled, `getTriggerPrice` (in `market.ts`) uses the
+ * median of last-fill, funding-basis, and 5min-basis prices instead of the raw oracle price for
+ * trigger order evaluation.
+ *
+ * @param {StateAccount} stateAccount - The global state account
+ * @return {boolean} Whether `FeatureBitFlags.MEDIAN_TRIGGER_PRICE` is set
+ */
 export function useMedianTriggerPrice(stateAccount: StateAccount): boolean {
 	return (
 		(stateAccount.featureBitFlags & FeatureBitFlags.MEDIAN_TRIGGER_PRICE) > 0