@velocity-exchange/sdk 0.2.5 → 0.4.0

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

@@ -9,9 +9,12 @@ 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 declare function getBalance(tokenAmount: BN, spotMarket: SpotMarketAccount, balanceType: SpotBalanceType): BN;
+export declare function getBalance(tokenAmount: BN, spotMarket: SpotMarketAccount, balanceType: SpotBalanceType, roundUp?: boolean): BN;
 /**
  * Calculates the spot token amount including any accumulated interest.
  *
@@ -47,31 +50,189 @@ export declare function getStrictTokenValue(tokenAmount: BN, spotDecimals: numbe
  * @return {BN} The value of the token based on the oracle, scaled by `PRICE_PRECISION`
  */
 export declare function getTokenValue(tokenAmount: BN, spotDecimals: number, oraclePriceData: Pick<OraclePriceData, 'price'>): BN;
+/**
+ * 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 declare function calculateAssetWeight(balanceAmount: BN, oraclePrice: BN, spotMarket: SpotMarketAccount, marginCategory: MarginCategory | undefined): BN;
+/**
+ * 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 declare function calculateScaledInitialAssetWeight(spotMarket: SpotMarketAccount, oraclePrice: BN): BN;
+/**
+ * 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 declare function calculateLiabilityWeight(size: BN, spotMarket: SpotMarketAccount, marginCategory: MarginCategory | undefined): BN;
+/**
+ * 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 declare function calculateUtilization(bank: SpotMarketAccount, delta?: BN): BN;
 /**
- * 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 declare function calculateSpotMarketBorrowCapacity(spotMarketAccount: SpotMarketAccount, targetBorrowRate: BN): {
     totalCapacity: BN;
     remainingCapacity: BN;
 };
+/**
+ * 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 declare function calculateInterestRate(bank: SpotMarketAccount, delta?: BN, currentUtilization?: BN): BN;
+/**
+ * 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 declare function calculateDepositRate(bank: SpotMarketAccount, delta?: BN, currentUtilization?: BN): BN;
+/**
+ * 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 declare function calculateBorrowRate(bank: SpotMarketAccount, delta?: BN, currentUtilization?: BN): BN;
+/**
+ * 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 declare function calculateInterestAccumulated(bank: SpotMarketAccount, now: BN): {
     borrowInterest: BN;
     depositInterest: BN;
 };
+/**
+ * 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 declare function calculateTokenUtilizationLimits(depositTokenAmount: BN, borrowTokenAmount: BN, spotMarket: SpotMarketAccount): {
     minDepositTokensForUtilization: BN;
     maxBorrowTokensForUtilization: BN;
 };
+/**
+ * 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 declare function calculateWithdrawLimit(spotMarket: SpotMarketAccount, now: BN): {
     borrowLimit: BN;
     withdrawLimit: BN;
@@ -80,5 +241,39 @@ export declare function calculateWithdrawLimit(spotMarket: SpotMarketAccount, no
     currentDepositAmount: BN;
     currentBorrowAmount: BN;
 };
+/**
+ * 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 declare function getSpotAssetValue(tokenAmount: BN, strictOraclePrice: StrictOraclePrice, spotMarketAccount: SpotMarketAccount, maxMarginRatio: number, marginCategory?: MarginCategory): BN;
+/**
+ * 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 declare function getSpotLiabilityValue(tokenAmount: BN, strictOraclePrice: StrictOraclePrice, spotMarketAccount: SpotMarketAccount, maxMarginRatio: number, marginCategory?: MarginCategory, liquidationBuffer?: BN): BN;

package/lib/browser/math/spotBalance.js

@@ -7,6 +7,17 @@ const numericConstants_1 = require("../constants/numericConstants");
 const margin_1 = require("./margin");
 const numericConstants_2 = require("../constants/numericConstants");
 const utils_1 = require("./utils");
+// 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, b) {
+    const quotient = a.div(b);
+    const remainder = a.mod(b);
+    if (!remainder.isZero() && a.isNeg() !== b.isNeg()) {
+        return quotient.sub(numericConstants_1.ONE);
+    }
+    return quotient;
+}
 /**
  * Calculates the balance of a given token amount including any accumulated interest. This
  * is the same as `SpotPosition.scaledBalance`.
@@ -14,15 +25,19 @@ const utils_1 = require("./utils");
  * @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`
  */
-function getBalance(tokenAmount, spotMarket, balanceType) {
+function getBalance(tokenAmount, spotMarket, balanceType, roundUp) {
     const precisionIncrease = numericConstants_1.TEN.pow(new anchor_1.BN(19 - spotMarket.decimals));
     const cumulativeInterest = (0, types_1.isVariant)(balanceType, 'deposit')
         ? spotMarket.cumulativeDepositInterest
         : spotMarket.cumulativeBorrowInterest;
     let balance = tokenAmount.mul(precisionIncrease).div(cumulativeInterest);
-    if (!balance.eq(numericConstants_1.ZERO) && (0, types_1.isVariant)(balanceType, 'borrow')) {
+    const shouldRoundUp = roundUp !== null && roundUp !== void 0 ? roundUp : (0, types_1.isVariant)(balanceType, 'borrow');
+    if (!balance.eq(numericConstants_1.ZERO) && shouldRoundUp) {
         balance = balance.add(numericConstants_1.ONE);
     }
     return balance;
@@ -84,7 +99,11 @@ function getStrictTokenValue(tokenAmount, spotDecimals, strictOraclePrice) {
         price = strictOraclePrice.max();
     }
     const precisionDecrease = numericConstants_1.TEN.pow(new anchor_1.BN(spotDecimals));
-    return tokenAmount.mul(price).div(precisionDecrease);
+    const tokenWithPrice = tokenAmount.mul(price);
+    if (tokenWithPrice.isNeg()) {
+        return divFloor(tokenWithPrice, precisionDecrease);
+    }
+    return tokenWithPrice.div(precisionDecrease);
 }
 exports.getStrictTokenValue = getStrictTokenValue;
 /**
@@ -100,9 +119,29 @@ function getTokenValue(tokenAmount, spotDecimals, oraclePriceData) {
         return numericConstants_1.ZERO;
     }
     const precisionDecrease = numericConstants_1.TEN.pow(new anchor_1.BN(spotDecimals));
-    return tokenAmount.mul(oraclePriceData.price).div(precisionDecrease);
+    const tokenWithOraclePrice = tokenAmount.mul(oraclePriceData.price);
+    if (tokenWithOraclePrice.isNeg()) {
+        return divFloor(tokenWithOraclePrice, precisionDecrease);
+    }
+    return tokenWithOraclePrice.div(precisionDecrease);
 }
 exports.getTokenValue = getTokenValue;
+/**
+ * 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%)
+ */
 function calculateAssetWeight(balanceAmount, oraclePrice, spotMarket, marginCategory) {
     const sizePrecision = numericConstants_1.TEN.pow(new anchor_1.BN(spotMarket.decimals));
     let sizeInAmmReservePrecision;
@@ -119,6 +158,13 @@ function calculateAssetWeight(balanceAmount, oraclePrice, spotMarket, marginCate
         case 'Initial':
             assetWeight = (0, margin_1.calculateSizeDiscountAssetWeight)(sizeInAmmReservePrecision, new anchor_1.BN(spotMarket.imfFactor), 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 = (0, margin_1.calculateSizeDiscountAssetWeight)(sizeInAmmReservePrecision, new anchor_1.BN(spotMarket.imfFactor), calculateScaledInitialAssetWeight(spotMarket, oraclePrice)
+                .add(new anchor_1.BN(spotMarket.maintenanceAssetWeight))
+                .divn(2));
+            break;
         case 'Maintenance':
             assetWeight = (0, margin_1.calculateSizeDiscountAssetWeight)(sizeInAmmReservePrecision, new anchor_1.BN(spotMarket.imfFactor), new anchor_1.BN(spotMarket.maintenanceAssetWeight));
             break;
@@ -129,6 +175,17 @@ function calculateAssetWeight(balanceAmount, oraclePrice, spotMarket, marginCate
     return assetWeight;
 }
 exports.calculateAssetWeight = calculateAssetWeight;
+/**
+ * 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)
+ */
 function calculateScaledInitialAssetWeight(spotMarket, oraclePrice) {
     if (spotMarket.scaleInitialAssetWeightStart.eq(numericConstants_1.ZERO)) {
         return new anchor_1.BN(spotMarket.initialAssetWeight);
@@ -147,6 +204,19 @@ function calculateScaledInitialAssetWeight(spotMarket, oraclePrice) {
     }
 }
 exports.calculateScaledInitialAssetWeight = 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%)
+ */
 function calculateLiabilityWeight(size, spotMarket, marginCategory) {
     const sizePrecision = numericConstants_1.TEN.pow(new anchor_1.BN(spotMarket.decimals));
     let sizeInAmmReservePrecision;
@@ -163,6 +233,13 @@ function calculateLiabilityWeight(size, spotMarket, marginCategory) {
         case 'Initial':
             liabilityWeight = (0, margin_1.calculateSizePremiumLiabilityWeight)(sizeInAmmReservePrecision, new anchor_1.BN(spotMarket.imfFactor), new anchor_1.BN(spotMarket.initialLiabilityWeight), numericConstants_1.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 = (0, margin_1.calculateSizePremiumLiabilityWeight)(sizeInAmmReservePrecision, new anchor_1.BN(spotMarket.imfFactor), new anchor_1.BN(spotMarket.initialLiabilityWeight)
+                .add(new anchor_1.BN(spotMarket.maintenanceLiabilityWeight))
+                .divn(2), numericConstants_1.SPOT_MARKET_WEIGHT_PRECISION);
+            break;
         case 'Maintenance':
             liabilityWeight = (0, margin_1.calculateSizePremiumLiabilityWeight)(sizeInAmmReservePrecision, new anchor_1.BN(spotMarket.imfFactor), new anchor_1.BN(spotMarket.maintenanceLiabilityWeight), numericConstants_1.SPOT_MARKET_WEIGHT_PRECISION);
             break;
@@ -173,6 +250,17 @@ function calculateLiabilityWeight(size, spotMarket, marginCategory) {
     return liabilityWeight;
 }
 exports.calculateLiabilityWeight = calculateLiabilityWeight;
+/**
+ * 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%)
+ */
 function calculateUtilization(bank, delta = numericConstants_1.ZERO) {
     let tokenDepositAmount = getTokenAmount(bank.depositBalance, bank, types_1.SpotBalanceType.DEPOSIT);
     let tokenBorrowAmount = getTokenAmount(bank.borrowBalance, bank, types_1.SpotBalanceType.BORROW);
@@ -198,10 +286,17 @@ function calculateUtilization(bank, delta = numericConstants_1.ZERO) {
 }
 exports.calculateUtilization = 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)
  */
 function calculateSpotMarketBorrowCapacity(spotMarketAccount, targetBorrowRate) {
     const currentBorrowRate = calculateBorrowRate(spotMarketAccount);
@@ -246,6 +341,21 @@ function calculateSpotMarketBorrowCapacity(spotMarketAccount, targetBorrowRate)
     return { totalCapacity, remainingCapacity };
 }
 exports.calculateSpotMarketBorrowCapacity = calculateSpotMarketBorrowCapacity;
+/**
+ * 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)
+ */
 function calculateInterestRate(bank, delta = numericConstants_1.ZERO, currentUtilization) {
     // todo: ensure both a delta and current util aren't pass?
     const utilization = currentUtilization !== null && currentUtilization !== void 0 ? currentUtilization : calculateUtilization(bank, delta);
@@ -296,6 +406,19 @@ function calculateInterestRate(bank, delta = numericConstants_1.ZERO, currentUti
     return anchor_1.BN.max(minRate, rate);
 }
 exports.calculateInterestRate = calculateInterestRate;
+/**
+ * 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)
+ */
 function calculateDepositRate(bank, delta = numericConstants_1.ZERO, currentUtilization) {
     // positive delta => adding to deposit
     // negative delta => adding to borrow
@@ -309,10 +432,40 @@ function calculateDepositRate(bank, delta = numericConstants_1.ZERO, currentUtil
     return depositRate;
 }
 exports.calculateDepositRate = calculateDepositRate;
+/**
+ * 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)
+ */
 function calculateBorrowRate(bank, delta = numericConstants_1.ZERO, currentUtilization) {
     return calculateInterestRate(bank, delta, currentUtilization);
 }
 exports.calculateBorrowRate = calculateBorrowRate;
+/**
+ * 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`)
+ */
 function calculateInterestAccumulated(bank, now) {
     const interestRate = calculateInterestRate(bank);
     const timeSinceLastUpdate = now.sub(bank.lastInterestTs);
@@ -333,6 +486,22 @@ function calculateInterestAccumulated(bank, now) {
     return { borrowInterest, depositInterest };
 }
 exports.calculateInterestAccumulated = calculateInterestAccumulated;
+/**
+ * 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
+ */
 function calculateTokenUtilizationLimits(depositTokenAmount, borrowTokenAmount, spotMarket) {
     // Calculates the allowable minimum deposit and maximum borrow amounts for immediate withdrawal based on market utilization.
     // First, it determines a maximum withdrawal utilization from the market's target and historic utilization.
@@ -354,6 +523,32 @@ function calculateTokenUtilizationLimits(depositTokenAmount, borrowTokenAmount,
     };
 }
 exports.calculateTokenUtilizationLimits = 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)
+ */
 function calculateWithdrawLimit(spotMarket, now) {
     const marketDepositTokenAmount = getTokenAmount(spotMarket.depositBalance, spotMarket, types_1.SpotBalanceType.DEPOSIT);
     const marketBorrowTokenAmount = getTokenAmount(spotMarket.borrowBalance, spotMarket, types_1.SpotBalanceType.BORROW);
@@ -371,10 +566,10 @@ function calculateWithdrawLimit(spotMarket, now) {
     const lesserDepositAmount = anchor_1.BN.min(marketDepositTokenAmount, depositTokenTwapLive);
     let maxBorrowTokensTwap;
     if (spotMarket.poolId == 0) {
-        maxBorrowTokensTwap = anchor_1.BN.max(spotMarket.withdrawGuardThreshold, anchor_1.BN.min(anchor_1.BN.max(marketDepositTokenAmount.div(new anchor_1.BN(3)), borrowTokenTwapLive.add(lesserDepositAmount.div(new anchor_1.BN(7)))), lesserDepositAmount.sub(lesserDepositAmount.div(new anchor_1.BN(8))))); // main pool between ~30-92.5% utilization with friction on twap in 20% increments
+        maxBorrowTokensTwap = anchor_1.BN.max(spotMarket.withdrawGuardThreshold, anchor_1.BN.min(anchor_1.BN.max(lesserDepositAmount.div(new anchor_1.BN(3)), borrowTokenTwapLive.add(lesserDepositAmount.div(new anchor_1.BN(5)))), lesserDepositAmount.sub(lesserDepositAmount.div(new anchor_1.BN(14))))); // main pool between ~30-92.5% utilization with friction on twap in 20% increments
     }
     else {
-        maxBorrowTokensTwap = anchor_1.BN.max(spotMarket.withdrawGuardThreshold, anchor_1.BN.min(anchor_1.BN.max(marketDepositTokenAmount.div(new anchor_1.BN(2)), borrowTokenTwapLive.add(lesserDepositAmount.div(new anchor_1.BN(3)))), lesserDepositAmount.sub(lesserDepositAmount.div(new anchor_1.BN(20))))); // isolated pools between 50-95% utilization with friction on twap in 33% increments
+        maxBorrowTokensTwap = anchor_1.BN.max(spotMarket.withdrawGuardThreshold, anchor_1.BN.min(anchor_1.BN.max(lesserDepositAmount.div(new anchor_1.BN(2)), borrowTokenTwapLive.add(lesserDepositAmount.div(new anchor_1.BN(3)))), lesserDepositAmount.sub(lesserDepositAmount.div(new anchor_1.BN(20))))); // isolated pools between 50-95% utilization with friction on twap in 33% increments
     }
     const minDepositTokensTwap = depositTokenTwapLive.sub(anchor_1.BN.max(depositTokenTwapLive.div(new anchor_1.BN(4)), anchor_1.BN.min(spotMarket.withdrawGuardThreshold, depositTokenTwapLive)));
     const { minDepositTokensForUtilization, maxBorrowTokensForUtilization } = calculateTokenUtilizationLimits(marketDepositTokenAmount, marketBorrowTokenAmount, spotMarket);
@@ -404,6 +599,22 @@ function calculateWithdrawLimit(spotMarket, now) {
     };
 }
 exports.calculateWithdrawLimit = 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)
+ */
 function getSpotAssetValue(tokenAmount, strictOraclePrice, spotMarketAccount, maxMarginRatio, marginCategory) {
     let assetValue = getStrictTokenValue(tokenAmount, spotMarketAccount.decimals, strictOraclePrice);
     if (marginCategory !== undefined) {
@@ -418,6 +629,24 @@ function getSpotAssetValue(tokenAmount, strictOraclePrice, spotMarketAccount, ma
     return assetValue;
 }
 exports.getSpotAssetValue = getSpotAssetValue;
+/**
+ * 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)
+ */
 function getSpotLiabilityValue(tokenAmount, strictOraclePrice, spotMarketAccount, maxMarginRatio, marginCategory, liquidationBuffer) {
     let liabilityValue = getStrictTokenValue(tokenAmount, spotMarketAccount.decimals, strictOraclePrice);
     if (marginCategory !== undefined) {