@velocity-exchange/sdk 0.3.0 → 0.4.0

package/lib/browser/math/liquidation.js

@@ -1,14 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getMarginShortage = exports.calculateMaxPctToLiquidate = exports.calculateAssetTransferForLiabilityTransfer = exports.calculateLiabilityTransferToCoverMarginShortage = exports.calculateBaseAssetAmountToCoverMarginShortage = void 0;
+exports.getMarginShortage = exports.calculateMaxPctToLiquidate = exports.calculateAssetTransferForLiabilityTransfer = exports.calculateSpotIfFee = exports.calculatePerpIfFee = exports.calculateLiabilityTransferToCoverMarginShortage = exports.calculateBaseAssetAmountToCoverMarginShortage = void 0;
 const anchor_1 = require("../isomorphic/anchor");
 const numericConstants_1 = require("../constants/numericConstants");
 /**
- * @param ifLiquidationFee Since PR#75 the program sizes liquidations against the
- *   COMBINED insurance-fund + protocol liquidation fee budget:
- *   `market.ifLiquidationFee + market.protocolLiquidationFee` (split IF-first
- *   on-chain). Pass that sum here to match on-chain sizing; passing
- *   `market.ifLiquidationFee` alone under-sizes the estimate.
+ * Calculates the base asset amount a liquidator must take from a perp position to cover a
+ * given margin shortage, mirroring `calculate_base_asset_amount_to_cover_margin_shortage` in
+ * `programs/velocity/src/math/liquidation.rs`. Larger `marginRatio`/`liquidationFee` spread
+ * (the liquidator's margin) means less base asset amount is needed per dollar of shortage
+ * covered; the `ifLiquidationFee` cut is subtracted from the liquidator's proceeds first.
+ * @param marginShortage Margin shortfall to cover, QUOTE_PRECISION (1e6).
+ * @param marginRatio Position's maintenance margin ratio, MARGIN_PRECISION (1e4).
+ * @param liquidationFee Liquidator's fee rate, LIQUIDATION_FEE_PRECISION (1e6).
+ * @param ifLiquidationFee The margin-shortage-aware insurance-side fee, i.e. the
+ *   output of `calculatePerpIfFee` (which is itself capped at
+ *   `market.ifLiquidationFee + market.protocolLiquidationFee`). Pass that
+ *   computed value here, not the raw `ifLiquidationFee + protocolLiquidationFee`
+ *   sum — the on-chain sizing uses the capped, shortage-aware amount.
+ * @param oraclePrice Oracle price of the perp market, PRICE_PRECISION (1e6).
+ * @param quoteOraclePrice Oracle price of the quote asset, PRICE_PRECISION (1e6).
+ * @returns Base asset amount to transfer, BASE_PRECISION (1e9); `undefined` means "no finite
+ *   amount can cover the shortage" (oracle price is zero, or the margin ratio doesn't exceed
+ *   the liquidation fee) — treat as unbounded/take the whole position.
  */
 function calculateBaseAssetAmountToCoverMarginShortage(marginShortage, marginRatio, liquidationFee, ifLiquidationFee, oraclePrice, quoteOraclePrice) {
     const marginRatioBN = new anchor_1.BN(marginRatio)
@@ -28,11 +41,27 @@ function calculateBaseAssetAmountToCoverMarginShortage(marginShortage, marginRat
 }
 exports.calculateBaseAssetAmountToCoverMarginShortage = calculateBaseAssetAmountToCoverMarginShortage;
 /**
- * @param ifLiquidationFee Since PR#75 the program sizes liquidations against the
- *   COMBINED insurance-fund + protocol liquidation fee budget:
- *   `market.ifLiquidationFee + market.protocolLiquidationFee` (split IF-first
- *   on-chain). Pass that sum here to match on-chain sizing; passing
- *   `market.ifLiquidationFee` alone under-sizes the estimate.
+ * Calculates the spot liability token amount a liquidator must take to cover a given margin
+ * shortage, mirroring `calculate_liability_transfer_to_cover_margin_shortage` in
+ * `programs/velocity/src/math/liquidation.rs`. Scales with the gap between the asset and
+ * liability weights (adjusted by their respective liquidation multipliers) — a wider spread
+ * means less liability token amount is needed per dollar of shortage covered.
+ * @param marginShortage Margin shortfall to cover, QUOTE_PRECISION (1e6).
+ * @param assetWeight Weight of the collateral asset the liquidator gives up, SPOT_MARKET_WEIGHT_PRECISION (1e4).
+ * @param assetLiquidationMultiplier Liquidation-time discount multiplier on the asset side, LIQUIDATION_FEE_PRECISION (1e6).
+ * @param liabilityWeight Weight of the liability being repaid, SPOT_MARKET_WEIGHT_PRECISION (1e4).
+ * @param liabilityLiquidationMultiplier Liquidation-time premium multiplier on the liability side, LIQUIDATION_FEE_PRECISION (1e6).
+ * @param liabilityDecimals Liability spot market's token decimals.
+ * @param liabilityPrice Oracle price of the liability asset, PRICE_PRECISION (1e6).
+ * @param ifLiquidationFee The margin-shortage-aware insurance-side fee, i.e. the
+ *   output of `calculateSpotIfFee` (which is itself capped at
+ *   `liabilityMarket.ifLiquidationFee + liabilityMarket.protocolLiquidationFee`).
+ *   Pass that computed value here, not the raw sum of the two rates — the
+ *   on-chain sizing uses the capped, shortage-aware amount.
+ * @returns Liability token amount to transfer, in the liability spot market's own token
+ *   precision (`10^liabilityDecimals`); `undefined` means "no finite amount can cover the
+ *   shortage" (`assetWeight >= liabilityWeight`, or the effective spread is non-positive) —
+ *   treat as unbounded/take the whole liability.
  */
 function calculateLiabilityTransferToCoverMarginShortage(marginShortage, assetWeight, assetLiquidationMultiplier, liabilityWeight, liabilityLiquidationMultiplier, liabilityDecimals, liabilityPrice, ifLiquidationFee) {
     if (assetWeight >= liabilityWeight) {
@@ -69,6 +98,115 @@ function calculateLiabilityTransferToCoverMarginShortage(marginShortage, assetWe
         .div(denominatorScale), numericConstants_1.ONE);
 }
 exports.calculateLiabilityTransferToCoverMarginShortage = calculateLiabilityTransferToCoverMarginShortage;
+/**
+ * Calculates the margin-shortage-aware insurance-fund fee for liquidating a perp position,
+ * mirroring `calculate_perp_if_fee` in `programs/velocity/src/math/liquidation.rs`. Starts
+ * from `marginRatio - liquidatorFee` (the room left after the liquidator's own cut) and
+ * subtracts a shortage-proportional deduction so the IF fee shrinks as the shortage grows
+ * relative to position value — this is the "shortage-aware" behavior referenced by
+ * `calculateBaseAssetAmountToCoverMarginShortage`'s `ifLiquidationFee` param. The result is
+ * further scaled by 95% (to avoid the fee itself pushing the user into bankruptcy) and capped
+ * at `maxIfLiquidationFee` (typically `market.ifLiquidationFee + market.protocolLiquidationFee`).
+ * @param marginShortage Margin shortfall being covered, QUOTE_PRECISION (1e6).
+ * @param userBaseAssetAmount Base amount being liquidated, BASE_PRECISION (1e9, signed — only magnitude matters).
+ * @param marginRatio Position's maintenance margin ratio, MARGIN_PRECISION (1e4).
+ * @param liquidatorFee Liquidator's fee rate, LIQUIDATION_FEE_PRECISION (1e6).
+ * @param oraclePrice Oracle price of the perp market, PRICE_PRECISION (1e6).
+ * @param quoteOraclePrice Oracle price of the quote asset, PRICE_PRECISION (1e6).
+ * @param maxIfLiquidationFee Upper bound on the returned fee, LIQUIDATION_FEE_PRECISION (1e6).
+ * @returns Insurance-fund fee rate, LIQUIDATION_FEE_PRECISION (1e6); `0` if either oracle
+ *   price is zero, the position size is zero, or `marginRatio` doesn't exceed `liquidatorFee`.
+ */
+function calculatePerpIfFee(marginShortage, userBaseAssetAmount, marginRatio, liquidatorFee, oraclePrice, quoteOraclePrice, maxIfLiquidationFee) {
+    const marginRatioBN = new anchor_1.BN(marginRatio).mul(numericConstants_1.LIQUIDATION_FEE_PRECISION.div(numericConstants_1.MARGIN_PRECISION));
+    if (oraclePrice.eq(numericConstants_1.ZERO) ||
+        quoteOraclePrice.eq(numericConstants_1.ZERO) ||
+        marginRatioBN.lte(new anchor_1.BN(liquidatorFee)) ||
+        userBaseAssetAmount.eq(numericConstants_1.ZERO)) {
+        return 0;
+    }
+    const price = oraclePrice.mul(quoteOraclePrice).div(numericConstants_1.PRICE_PRECISION);
+    // margin ratio - liquidator fee - (margin shortage / (user base asset amount * price))
+    // the program receives base_asset_amount.unsigned_abs() (u64), so only the magnitude
+    // participates in the shortage term
+    let impliedIfFee = anchor_1.BN.max(marginRatioBN.sub(new anchor_1.BN(liquidatorFee)), numericConstants_1.ZERO);
+    const shortageComponent = marginShortage
+        .mul(numericConstants_1.BASE_PRECISION)
+        .div(userBaseAssetAmount.abs())
+        .mul(numericConstants_1.PRICE_PRECISION)
+        .div(price);
+    impliedIfFee = anchor_1.BN.max(impliedIfFee.sub(shortageComponent), numericConstants_1.ZERO);
+    // multiply by 95% to avoid situation where fee leads to deposits == negative pnl
+    // leading to bankruptcy
+    impliedIfFee = impliedIfFee.mul(new anchor_1.BN(19)).div(new anchor_1.BN(20));
+    return anchor_1.BN.min(new anchor_1.BN(maxIfLiquidationFee), impliedIfFee).toNumber();
+}
+exports.calculatePerpIfFee = calculatePerpIfFee;
+/**
+ * Calculates the margin-shortage-aware insurance-fund fee for a spot liability liquidation,
+ * mirroring `calculate_spot_if_fee` in `programs/velocity/src/math/liquidation.rs`. Same
+ * shortage-aware shape as `calculatePerpIfFee`: starts from the asset/liability weight
+ * spread (scaled by their liquidation multipliers), subtracts a shortage-proportional
+ * deduction, and caps at `maxIfFee` (typically `liabilityMarket.ifLiquidationFee +
+ * liabilityMarket.protocolLiquidationFee`).
+ * @param marginShortage Margin shortfall being covered, QUOTE_PRECISION (1e6).
+ * @param tokenAmount Liability token amount being liquidated, liability spot market's own token precision (`10^liabilityDecimals`).
+ * @param assetWeight Weight of the collateral asset the liquidator gives up, SPOT_MARKET_WEIGHT_PRECISION (1e4).
+ * @param assetLiquidationMultiplier Liquidation-time discount multiplier on the asset side, LIQUIDATION_FEE_PRECISION (1e6).
+ * @param liabilityWeight Weight of the liability being repaid, SPOT_MARKET_WEIGHT_PRECISION (1e4).
+ * @param liabilityLiquidationMultiplier Liquidation-time premium multiplier on the liability side, LIQUIDATION_FEE_PRECISION (1e6).
+ * @param liabilityDecimals Liability spot market's token decimals.
+ * @param liabilityPrice Oracle price of the liability asset, PRICE_PRECISION (1e6).
+ * @param maxIfFee Upper bound on the returned fee, LIQUIDATION_FEE_PRECISION (1e6).
+ * @returns Insurance-fund fee rate, LIQUIDATION_FEE_PRECISION (1e6); `0` if
+ *   `assetWeight >= liabilityWeight`, the liability price/token amount is zero, or
+ *   `liabilityLiquidationMultiplier` is zero.
+ */
+function calculateSpotIfFee(marginShortage, tokenAmount, assetWeight, assetLiquidationMultiplier, liabilityWeight, liabilityLiquidationMultiplier, liabilityDecimals, liabilityPrice, maxIfFee) {
+    if (assetWeight >= liabilityWeight ||
+        liabilityPrice.eq(numericConstants_1.ZERO) ||
+        tokenAmount.eq(numericConstants_1.ZERO) ||
+        liabilityLiquidationMultiplier === 0) {
+        return 0;
+    }
+    const tokenPrecision = numericConstants_1.TEN.pow(new anchor_1.BN(liabilityDecimals));
+    const weightPrecisionRatio = numericConstants_1.LIQUIDATION_FEE_PRECISION.div(numericConstants_1.SPOT_MARKET_WEIGHT_PRECISION);
+    const liabilityWeightBN = new anchor_1.BN(liabilityWeight).mul(weightPrecisionRatio);
+    const assetWeightBN = new anchor_1.BN(assetWeight).mul(weightPrecisionRatio);
+    let impliedIfFee = anchor_1.BN.max(liabilityWeightBN.sub(assetWeightBN
+        .mul(new anchor_1.BN(assetLiquidationMultiplier))
+        .div(new anchor_1.BN(liabilityLiquidationMultiplier))), numericConstants_1.ZERO);
+    const shortageComponent = marginShortage
+        .mul(numericConstants_1.LIQUIDATION_FEE_PRECISION)
+        .mul(tokenPrecision)
+        .div(tokenAmount)
+        .div(liabilityPrice);
+    impliedIfFee = anchor_1.BN.max(impliedIfFee.sub(shortageComponent), numericConstants_1.ZERO);
+    impliedIfFee = impliedIfFee
+        .mul(numericConstants_1.LIQUIDATION_FEE_PRECISION)
+        .div(liabilityWeightBN);
+    return anchor_1.BN.min(new anchor_1.BN(maxIfFee), impliedIfFee).toNumber();
+}
+exports.calculateSpotIfFee = calculateSpotIfFee;
+/**
+ * Calculates how much of a liquidated user's collateral asset a liquidator receives in
+ * exchange for repaying `liabilityAmount` of a liability, mirroring
+ * `calculate_asset_transfer_for_liability_transfer` in
+ * `programs/velocity/src/math/liquidation.rs`. Converts the liability amount to an
+ * equivalent asset amount at the two assets' oracle prices, scaled by their respective
+ * liquidation multipliers (the premium/discount applied at liquidation), then rounds up to
+ * the user's full remaining asset balance (`assetAmount`) if the difference is under
+ * `QUOTE_PRECISION` (1e6) worth of value — avoiding dust asset balances left behind.
+ * @param assetAmount User's available balance of the asset being transferred, asset spot market's own token precision.
+ * @param assetLiquidationMultiplier Liquidation-time discount multiplier on the asset side, LIQUIDATION_FEE_PRECISION (1e6).
+ * @param assetDecimals Asset spot market's token decimals.
+ * @param assetPrice Oracle price of the asset, PRICE_PRECISION (1e6).
+ * @param liabilityAmount Liability amount being repaid, liability spot market's own token precision.
+ * @param liabilityLiquidationMultiplier Liquidation-time premium multiplier on the liability side, LIQUIDATION_FEE_PRECISION (1e6).
+ * @param liabilityDecimals Liability spot market's token decimals.
+ * @param liabilityPrice Oracle price of the liability asset, PRICE_PRECISION (1e6).
+ * @returns Asset amount to transfer to the liquidator, asset spot market's own token precision (floored at 1).
+ */
 function calculateAssetTransferForLiabilityTransfer(assetAmount, assetLiquidationMultiplier, assetDecimals, assetPrice, liabilityAmount, liabilityLiquidationMultiplier, liabilityDecimals, liabilityPrice) {
     let numeratorScale;
     let denominatorScale;
@@ -116,18 +254,34 @@ function calculateAssetTransferForLiabilityTransfer(assetAmount, assetLiquidatio
     return assetTransfer;
 }
 exports.calculateAssetTransferForLiabilityTransfer = calculateAssetTransferForLiabilityTransfer;
-function calculateMaxPctToLiquidate(userLastActiveSlot, userLiquidationMarginFreed, marginShortage, slot, initialPctToLiquidate, liquidationDuration) {
+/**
+ * Calculates the fraction of a position's remaining liability a liquidator may currently
+ * take, mirroring `calculate_max_pct_to_liquidate` in
+ * `programs/velocity/src/math/liquidation.rs`. Liquidations ramp up gradually over
+ * `liquidationDuration` slots (starting from `initialPctToLiquidate`) rather than allowing
+ * 100% in one shot, so a user isn't force-closed more aggressively than necessary — except:
+ * isolated perp positions (`isIsolatedPosition`) are always liquidated 100% in one shot
+ * since they have no other cross-margin exposure to protect, and any position is liquidated
+ * 100% immediately once `marginShortage` is under $50 (dust threshold, not worth ramping).
+ * @param userLastActiveSlot Slot the user was last active (start of the liquidation ramp), used with `slot` to compute elapsed time.
+ * @param userLiquidationMarginFreed Margin already freed by liquidation actions so far this liquidation, QUOTE_PRECISION (1e6).
+ * @param marginShortage Total margin shortfall for the user/position, QUOTE_PRECISION (1e6).
+ * @param slot Current slot.
+ * @param initialPctToLiquidate Starting liquidatable fraction at slot zero of the ramp, LIQUIDATION_PCT_PRECISION (1e4).
+ * @param liquidationDuration Number of slots for the ramp to reach 100% (~1 minute at 400ms/slot for the on-chain default).
+ * @param isIsolatedPosition If true, always returns 100% (LIQUIDATION_PCT_PRECISION) regardless of the other inputs (default false).
+ * @returns Fraction of the remaining liability liquidatable now, LIQUIDATION_PCT_PRECISION (1e4).
+ */
+function calculateMaxPctToLiquidate(userLastActiveSlot, userLiquidationMarginFreed, marginShortage, slot, initialPctToLiquidate, liquidationDuration, isIsolatedPosition = false) {
+    // isolated perp positions are liquidated 100% in one shot
+    if (isIsolatedPosition) {
+        return numericConstants_1.LIQUIDATION_PCT_PRECISION;
+    }
     // if margin shortage is tiny, accelerate liquidation
     if (marginShortage.lt(new anchor_1.BN(50).mul(numericConstants_1.QUOTE_PRECISION))) {
         return numericConstants_1.LIQUIDATION_PCT_PRECISION;
     }
-    let slotsElapsed;
-    if (userLiquidationMarginFreed.gt(new anchor_1.BN(0))) {
-        slotsElapsed = anchor_1.BN.max(slot.sub(userLastActiveSlot), new anchor_1.BN(0));
-    }
-    else {
-        slotsElapsed = new anchor_1.BN(0);
-    }
+    const slotsElapsed = anchor_1.BN.max(slot.sub(userLastActiveSlot), new anchor_1.BN(0));
     const pctFreeable = anchor_1.BN.min(slotsElapsed
         .mul(numericConstants_1.LIQUIDATION_PCT_PRECISION)
         .div(liquidationDuration) // ~ 1 minute if per slot is 400ms
@@ -140,6 +294,15 @@ function calculateMaxPctToLiquidate(userLastActiveSlot, userLiquidationMarginFre
     return marginFreeable.mul(numericConstants_1.LIQUIDATION_PCT_PRECISION).div(marginShortage);
 }
 exports.calculateMaxPctToLiquidate = calculateMaxPctToLiquidate;
+/**
+ * Absolute margin shortfall between a (buffered) maintenance margin requirement and total
+ * collateral. Returns a positive magnitude regardless of which side is larger — callers
+ * typically only call this once `meetsMarginRequirementWithBuffer()` has already returned
+ * `false`, at which point the result is the true shortage to cover.
+ * @param maintenanceMarginRequirementPlusBuffer Buffered maintenance margin requirement, QUOTE_PRECISION (1e6).
+ * @param maintenanceTotalCollateral Total collateral at maintenance weights, QUOTE_PRECISION (1e6).
+ * @returns `abs(maintenanceMarginRequirementPlusBuffer - maintenanceTotalCollateral)`, QUOTE_PRECISION (1e6).
+ */
 function getMarginShortage(maintenanceMarginRequirementPlusBuffer, maintenanceTotalCollateral) {
     return maintenanceMarginRequirementPlusBuffer
         .sub(maintenanceTotalCollateral)

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

@@ -2,35 +2,101 @@ import { BN } from '../isomorphic/anchor';
 import { OraclePriceData } from '../oracles/types';
 import { VelocityClient } from '../velocityClient';
 import { PerpMarketAccount, PerpPosition } from '../types';
+/**
+ * Applies the IMF (initial margin factor) size premium to a base liability weight, mirroring
+ * `calculate_size_premium_liability_weight` in `programs/velocity/src/math/margin.rs`. Larger
+ * positions get a higher (worse) liability weight, scaling with `sqrt(size)`, so leverage
+ * effectively decreases as position size grows. Returns `liabilityWeight` unchanged when
+ * `imfFactor` is zero (IMF scaling disabled for the market).
+ * @param size Position size driving the premium, AMM_RESERVE_PRECISION (1e9).
+ * @param imfFactor Market's IMF factor, SPOT_MARKET_IMF_PRECISION (1e6) or the margin-ratio-scaled equivalent depending on caller.
+ * @param liabilityWeight Base liability weight before the size premium, same precision as `precision`.
+ * @param precision Precision `liabilityWeight` is expressed in (e.g. `MARGIN_PRECISION` 1e4 for perp margin ratios, `SPOT_MARKET_WEIGHT_PRECISION` 1e4 for spot weights).
+ * @param isBounded If true (default), the result is floored at `liabilityWeight` (the premium can only increase it); if false, returns the raw (possibly lower) premium-adjusted value.
+ * @returns Size-adjusted liability weight, same precision as `liabilityWeight`.
+ */
 export declare function calculateSizePremiumLiabilityWeight(size: BN, // AMM_RESERVE_PRECISION
 imfFactor: BN, liabilityWeight: BN, precision: BN, isBounded?: boolean): BN;
+/**
+ * Applies the IMF size discount to a base asset weight, mirroring
+ * `calculate_size_discount_asset_weight` in `programs/velocity/src/math/margin.rs`. Larger
+ * deposits get a lower (worse) asset weight, scaling down with `sqrt(size)`, capping how much
+ * collateral credit a single large position can contribute. Returns `assetWeight` unchanged
+ * when `imfFactor` is zero.
+ * @param size Deposit size driving the discount, AMM_RESERVE_PRECISION (1e9).
+ * @param imfFactor Market's IMF factor, SPOT_MARKET_IMF_PRECISION (1e6).
+ * @param assetWeight Base asset weight before the size discount, SPOT_MARKET_WEIGHT_PRECISION (1e4).
+ * @returns `min(assetWeight, sizeDiscountedWeight)`, SPOT_MARKET_WEIGHT_PRECISION (1e4).
+ */
 export declare function calculateSizeDiscountAssetWeight(size: BN, // AMM_RESERVE_PRECISION
 imfFactor: BN, assetWeight: BN): BN;
 /**
- * This is _not_ the same as liability value as for prediction markets, the liability for the short in prediction market is (1 - oracle price) * base
- * See {@link calculatePerpLiabilityValue} to get the liabiltiy value
- * @param market
- * @param perpPosition
- * @param oraclePriceData
- * @param includeOpenOrders
+ * Marks a perp position (or its worst-case size including open orders) to the oracle price:
+ * `abs(baseAssetAmount) * price / AMM_RESERVE_PRECISION`. Used for margin/health
+ * calculations, not close-value simulation (see `calculateBaseAssetValue` in `position.ts`
+ * for the AMM-simulated close value). This is a base *asset value*, not necessarily the same
+ * as liability value in every case — see `calculatePerpLiabilityValue` to get the liability
+ * value used directly in margin requirement math.
+ * @param market Perp market the position belongs to; uses `market.expiryPrice` instead of the oracle price when the market is in `settlement` status.
+ * @param perpPosition Position to value.
+ * @param oraclePriceData Must provide `price`, PRICE_PRECISION (1e6).
+ * @param includeOpenOrders If true, values the worst-case base amount including open bids/asks (via `calculateWorstCaseBaseAssetAmount`) instead of just the current position (default false).
+ * @returns Base asset value, QUOTE_PRECISION (1e6).
  */
 export declare function calculateBaseAssetValueWithOracle(market: PerpMarketAccount, perpPosition: PerpPosition, oraclePriceData: Pick<OraclePriceData, 'price'>, includeOpenOrders?: boolean): BN;
+/** Convenience wrapper returning just `worstCaseBaseAssetAmount` from `calculateWorstCasePerpLiabilityValue` — see that function for semantics and units (AMM_RESERVE_PRECISION, 1e9, signed). */
 export declare function calculateWorstCaseBaseAssetAmount(perpPosition: PerpPosition, perpMarket: PerpMarketAccount, oraclePrice: BN): BN;
+/**
+ * Computes the worst-case base position and liability value if all of a position's resting
+ * orders on the more-adverse side were to fill, mirroring the program's worst-case-liability
+ * margin methodology: compares the liability value of `baseAssetAmount + openBids` against
+ * `baseAssetAmount + openAsks` and returns whichever is larger (i.e. whichever side, if
+ * filled, would leave the user with more liability exposure). This is what margin
+ * requirements are sized against, not the position's current base amount alone.
+ * @param perpPosition Position providing `baseAssetAmount`, `openBids`, `openAsks`.
+ * @param perpMarket Unused by this function (accepted for call-site symmetry with other market-scoped valuation helpers).
+ * @param oraclePrice Oracle price, PRICE_PRECISION (1e6).
+ * @param includeOpenOrders If false, skips the bids/asks comparison and returns the position's actual base amount/liability value as-is (default true).
+ * @returns `worstCaseBaseAssetAmount` (AMM_RESERVE_PRECISION 1e9, signed) and `worstCaseLiabilityValue` (QUOTE_PRECISION 1e6) for the more-adverse side.
+ */
 export declare function calculateWorstCasePerpLiabilityValue(perpPosition: PerpPosition, perpMarket: PerpMarketAccount, oraclePrice: BN, includeOpenOrders?: boolean): {
     worstCaseBaseAssetAmount: BN;
     worstCaseLiabilityValue: BN;
 };
+/**
+ * Liability value of a base amount at a given price: `abs(baseAssetAmount) * price / BASE_PRECISION`.
+ * This is the value margin requirements are computed against.
+ * @param baseAssetAmount Base amount, BASE_PRECISION (1e9, signed).
+ * @param price Price, PRICE_PRECISION (1e6).
+ * @returns Liability value, QUOTE_PRECISION (1e6).
+ */
 export declare function calculatePerpLiabilityValue(baseAssetAmount: BN, price: BN): BN;
 /**
- * Calculates the margin required to open a trade, in quote amount. Only accounts for the trade size as a scalar value, does not account for the trade direction or current open positions and whether the trade would _actually_ be risk-increasing and use any extra collateral.
- * @param targetMarketIndex
- * @param baseSize
- * @returns
+ * Calculates the margin required to open a trade, in quote amount. Only accounts for the
+ * trade size as a scalar value — does not account for the trade direction, current open
+ * positions, or whether the trade would _actually_ be risk-increasing and use any extra
+ * collateral (i.e. it's an upper-bound estimate for a standalone new position, not a
+ * risk-increase delta).
+ * @param velocityClient Client used to look up the target market and its oracle price.
+ * @param targetMarketIndex Perp market index of the trade.
+ * @param baseSize Trade size, BASE_PRECISION (1e9).
+ * @param userMaxMarginRatio Optional per-user max margin ratio override (MARGIN_PRECISION, 1e4) — forwarded to `calculateMarketMarginRatio`; if omitted, the market's default initial margin ratio is used (subject to the size premium).
+ * @param entryPrice Optional price to value the trade at instead of the current oracle price, PRICE_PRECISION (1e6).
+ * @returns Margin required, QUOTE_PRECISION (1e6).
  */
 export declare function calculateMarginUSDCRequiredForTrade(velocityClient: VelocityClient, targetMarketIndex: number, baseSize: BN, userMaxMarginRatio?: number, entryPrice?: BN): BN;
 /**
- * Similar to calculatetMarginUSDCRequiredForTrade, but calculates how much of a given collateral is required to cover the margin requirements for a given trade. Basically does the same thing as getMarginUSDCRequiredForTrade but also accounts for asset weight of the selected collateral.
- *
- * Returns collateral required in the precision of the target collateral market.
+ * Similar to `calculateMarginUSDCRequiredForTrade`, but calculates how much of a given
+ * collateral asset is required to cover the margin requirement for a given trade —
+ * additionally accounts for the collateral's scaled initial asset weight (via
+ * `calculateScaledInitialAssetWeight`), so a lower-weight collateral (e.g. a volatile asset)
+ * requires depositing more than its face USDC value would suggest.
+ * @param velocityClient Client used to look up the target/collateral markets and oracle prices.
+ * @param targetMarketIndex Perp market index of the trade.
+ * @param baseSize Trade size, BASE_PRECISION (1e9).
+ * @param collateralIndex Spot market index of the collateral asset to deposit.
+ * @param userMaxMarginRatio Optional per-user max margin ratio override (MARGIN_PRECISION, 1e4), forwarded to `calculateMarginUSDCRequiredForTrade`.
+ * @param estEntryPrice Optional price to value the trade at instead of the current oracle price, PRICE_PRECISION (1e6).
+ * @returns Collateral amount required, in `collateralIndex`'s own spot-market precision (via `velocityClient.convertToSpotPrecision`).
  */
 export declare function calculateCollateralDepositRequiredForTrade(velocityClient: VelocityClient, targetMarketIndex: number, baseSize: BN, collateralIndex: number, userMaxMarginRatio?: number, estEntryPrice?: BN): BN;

package/lib/browser/math/margin.js

@@ -4,7 +4,7 @@ exports.calculateCollateralDepositRequiredForTrade = exports.calculateMarginUSDC
 /**
  * Margin calculation helpers — TypeScript mirror of `programs/velocity/src/math/margin.rs`.
  * Computes initial/maintenance margin requirements, free collateral, and account health.
- * Used by {@link User} for leverage queries and by keeper bots for liquidation eligibility checks.
+ * Used by `User` for leverage queries and by keeper bots for liquidation eligibility checks.
  */
 const utils_1 = require("./utils");
 const numericConstants_1 = require("../constants/numericConstants");
@@ -13,6 +13,19 @@ const market_1 = require("./market");
 const spotBalance_1 = require("./spotBalance");
 const types_1 = require("../types");
 const assert_1 = require("../assert/assert");
+/**
+ * Applies the IMF (initial margin factor) size premium to a base liability weight, mirroring
+ * `calculate_size_premium_liability_weight` in `programs/velocity/src/math/margin.rs`. Larger
+ * positions get a higher (worse) liability weight, scaling with `sqrt(size)`, so leverage
+ * effectively decreases as position size grows. Returns `liabilityWeight` unchanged when
+ * `imfFactor` is zero (IMF scaling disabled for the market).
+ * @param size Position size driving the premium, AMM_RESERVE_PRECISION (1e9).
+ * @param imfFactor Market's IMF factor, SPOT_MARKET_IMF_PRECISION (1e6) or the margin-ratio-scaled equivalent depending on caller.
+ * @param liabilityWeight Base liability weight before the size premium, same precision as `precision`.
+ * @param precision Precision `liabilityWeight` is expressed in (e.g. `MARGIN_PRECISION` 1e4 for perp margin ratios, `SPOT_MARKET_WEIGHT_PRECISION` 1e4 for spot weights).
+ * @param isBounded If true (default), the result is floored at `liabilityWeight` (the premium can only increase it); if false, returns the raw (possibly lower) premium-adjusted value.
+ * @returns Size-adjusted liability weight, same precision as `liabilityWeight`.
+ */
 function calculateSizePremiumLiabilityWeight(size, // AMM_RESERVE_PRECISION
 imfFactor, liabilityWeight, precision, isBounded = true) {
     if (imfFactor.eq(numericConstants_1.ZERO)) {
@@ -36,6 +49,17 @@ imfFactor, liabilityWeight, precision, isBounded = true) {
     return maxLiabilityWeight;
 }
 exports.calculateSizePremiumLiabilityWeight = calculateSizePremiumLiabilityWeight;
+/**
+ * Applies the IMF size discount to a base asset weight, mirroring
+ * `calculate_size_discount_asset_weight` in `programs/velocity/src/math/margin.rs`. Larger
+ * deposits get a lower (worse) asset weight, scaling down with `sqrt(size)`, capping how much
+ * collateral credit a single large position can contribute. Returns `assetWeight` unchanged
+ * when `imfFactor` is zero.
+ * @param size Deposit size driving the discount, AMM_RESERVE_PRECISION (1e9).
+ * @param imfFactor Market's IMF factor, SPOT_MARKET_IMF_PRECISION (1e6).
+ * @param assetWeight Base asset weight before the size discount, SPOT_MARKET_WEIGHT_PRECISION (1e4).
+ * @returns `min(assetWeight, sizeDiscountedWeight)`, SPOT_MARKET_WEIGHT_PRECISION (1e4).
+ */
 function calculateSizeDiscountAssetWeight(size, // AMM_RESERVE_PRECISION
 imfFactor, assetWeight) {
     if (imfFactor.eq(numericConstants_1.ZERO)) {
@@ -54,12 +78,17 @@ imfFactor, assetWeight) {
 }
 exports.calculateSizeDiscountAssetWeight = calculateSizeDiscountAssetWeight;
 /**
- * This is _not_ the same as liability value as for prediction markets, the liability for the short in prediction market is (1 - oracle price) * base
- * See {@link calculatePerpLiabilityValue} to get the liabiltiy value
- * @param market
- * @param perpPosition
- * @param oraclePriceData
- * @param includeOpenOrders
+ * Marks a perp position (or its worst-case size including open orders) to the oracle price:
+ * `abs(baseAssetAmount) * price / AMM_RESERVE_PRECISION`. Used for margin/health
+ * calculations, not close-value simulation (see `calculateBaseAssetValue` in `position.ts`
+ * for the AMM-simulated close value). This is a base *asset value*, not necessarily the same
+ * as liability value in every case — see `calculatePerpLiabilityValue` to get the liability
+ * value used directly in margin requirement math.
+ * @param market Perp market the position belongs to; uses `market.expiryPrice` instead of the oracle price when the market is in `settlement` status.
+ * @param perpPosition Position to value.
+ * @param oraclePriceData Must provide `price`, PRICE_PRECISION (1e6).
+ * @param includeOpenOrders If true, values the worst-case base amount including open bids/asks (via `calculateWorstCaseBaseAssetAmount`) instead of just the current position (default false).
+ * @returns Base asset value, QUOTE_PRECISION (1e6).
  */
 function calculateBaseAssetValueWithOracle(market, perpPosition, oraclePriceData, includeOpenOrders = false) {
     let price = oraclePriceData.price;
@@ -72,10 +101,24 @@ function calculateBaseAssetValueWithOracle(market, perpPosition, oraclePriceData
     return baseAssetAmount.abs().mul(price).div(numericConstants_1.AMM_RESERVE_PRECISION);
 }
 exports.calculateBaseAssetValueWithOracle = calculateBaseAssetValueWithOracle;
+/** Convenience wrapper returning just `worstCaseBaseAssetAmount` from `calculateWorstCasePerpLiabilityValue` — see that function for semantics and units (AMM_RESERVE_PRECISION, 1e9, signed). */
 function calculateWorstCaseBaseAssetAmount(perpPosition, perpMarket, oraclePrice) {
     return calculateWorstCasePerpLiabilityValue(perpPosition, perpMarket, oraclePrice).worstCaseBaseAssetAmount;
 }
 exports.calculateWorstCaseBaseAssetAmount = calculateWorstCaseBaseAssetAmount;
+/**
+ * Computes the worst-case base position and liability value if all of a position's resting
+ * orders on the more-adverse side were to fill, mirroring the program's worst-case-liability
+ * margin methodology: compares the liability value of `baseAssetAmount + openBids` against
+ * `baseAssetAmount + openAsks` and returns whichever is larger (i.e. whichever side, if
+ * filled, would leave the user with more liability exposure). This is what margin
+ * requirements are sized against, not the position's current base amount alone.
+ * @param perpPosition Position providing `baseAssetAmount`, `openBids`, `openAsks`.
+ * @param perpMarket Unused by this function (accepted for call-site symmetry with other market-scoped valuation helpers).
+ * @param oraclePrice Oracle price, PRICE_PRECISION (1e6).
+ * @param includeOpenOrders If false, skips the bids/asks comparison and returns the position's actual base amount/liability value as-is (default true).
+ * @returns `worstCaseBaseAssetAmount` (AMM_RESERVE_PRECISION 1e9, signed) and `worstCaseLiabilityValue` (QUOTE_PRECISION 1e6) for the more-adverse side.
+ */
 function calculateWorstCasePerpLiabilityValue(perpPosition, perpMarket, oraclePrice, includeOpenOrders = true) {
     // return early if no open orders required
     if (!includeOpenOrders) {
@@ -102,15 +145,29 @@ function calculateWorstCasePerpLiabilityValue(perpPosition, perpMarket, oraclePr
     }
 }
 exports.calculateWorstCasePerpLiabilityValue = calculateWorstCasePerpLiabilityValue;
+/**
+ * Liability value of a base amount at a given price: `abs(baseAssetAmount) * price / BASE_PRECISION`.
+ * This is the value margin requirements are computed against.
+ * @param baseAssetAmount Base amount, BASE_PRECISION (1e9, signed).
+ * @param price Price, PRICE_PRECISION (1e6).
+ * @returns Liability value, QUOTE_PRECISION (1e6).
+ */
 function calculatePerpLiabilityValue(baseAssetAmount, price) {
     return baseAssetAmount.abs().mul(price).div(numericConstants_1.BASE_PRECISION);
 }
 exports.calculatePerpLiabilityValue = calculatePerpLiabilityValue;
 /**
- * Calculates the margin required to open a trade, in quote amount. Only accounts for the trade size as a scalar value, does not account for the trade direction or current open positions and whether the trade would _actually_ be risk-increasing and use any extra collateral.
- * @param targetMarketIndex
- * @param baseSize
- * @returns
+ * Calculates the margin required to open a trade, in quote amount. Only accounts for the
+ * trade size as a scalar value — does not account for the trade direction, current open
+ * positions, or whether the trade would _actually_ be risk-increasing and use any extra
+ * collateral (i.e. it's an upper-bound estimate for a standalone new position, not a
+ * risk-increase delta).
+ * @param velocityClient Client used to look up the target market and its oracle price.
+ * @param targetMarketIndex Perp market index of the trade.
+ * @param baseSize Trade size, BASE_PRECISION (1e9).
+ * @param userMaxMarginRatio Optional per-user max margin ratio override (MARGIN_PRECISION, 1e4) — forwarded to `calculateMarketMarginRatio`; if omitted, the market's default initial margin ratio is used (subject to the size premium).
+ * @param entryPrice Optional price to value the trade at instead of the current oracle price, PRICE_PRECISION (1e6).
+ * @returns Margin required, QUOTE_PRECISION (1e6).
  */
 function calculateMarginUSDCRequiredForTrade(velocityClient, targetMarketIndex, baseSize, userMaxMarginRatio, entryPrice) {
     const targetMarket = velocityClient.getPerpMarketAccountOrThrow(targetMarketIndex);
@@ -123,9 +180,18 @@ function calculateMarginUSDCRequiredForTrade(velocityClient, targetMarketIndex,
 }
 exports.calculateMarginUSDCRequiredForTrade = calculateMarginUSDCRequiredForTrade;
 /**
- * Similar to calculatetMarginUSDCRequiredForTrade, but calculates how much of a given collateral is required to cover the margin requirements for a given trade. Basically does the same thing as getMarginUSDCRequiredForTrade but also accounts for asset weight of the selected collateral.
- *
- * Returns collateral required in the precision of the target collateral market.
+ * Similar to `calculateMarginUSDCRequiredForTrade`, but calculates how much of a given
+ * collateral asset is required to cover the margin requirement for a given trade —
+ * additionally accounts for the collateral's scaled initial asset weight (via
+ * `calculateScaledInitialAssetWeight`), so a lower-weight collateral (e.g. a volatile asset)
+ * requires depositing more than its face USDC value would suggest.
+ * @param velocityClient Client used to look up the target/collateral markets and oracle prices.
+ * @param targetMarketIndex Perp market index of the trade.
+ * @param baseSize Trade size, BASE_PRECISION (1e9).
+ * @param collateralIndex Spot market index of the collateral asset to deposit.
+ * @param userMaxMarginRatio Optional per-user max margin ratio override (MARGIN_PRECISION, 1e4), forwarded to `calculateMarginUSDCRequiredForTrade`.
+ * @param estEntryPrice Optional price to value the trade at instead of the current oracle price, PRICE_PRECISION (1e6).
+ * @returns Collateral amount required, in `collateralIndex`'s own spot-market precision (via `velocityClient.convertToSpotPrecision`).
  */
 function calculateCollateralDepositRequiredForTrade(velocityClient, targetMarketIndex, baseSize, collateralIndex, userMaxMarginRatio, estEntryPrice) {
     const marginRequiredUsdc = calculateMarginUSDCRequiredForTrade(velocityClient, targetMarketIndex, baseSize, userMaxMarginRatio, estEntryPrice);