@velocity-exchange/sdk 0.2.5 → 0.4.0

package/src/math/liquidation.ts

@@ -7,16 +7,31 @@ import {
 	QUOTE_PRECISION,
 	LIQUIDATION_PCT_PRECISION,
 	SPOT_MARKET_WEIGHT_PRECISION,
+	BASE_PRECISION,
 	TEN,
 	ONE,
+	ZERO,
 } from '../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.
  */
 export function calculateBaseAssetAmountToCoverMarginShortage(
 	marginShortage: BN,
@@ -49,11 +64,27 @@ export function 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.
  */
 export function calculateLiabilityTransferToCoverMarginShortage(
 	marginShortage: BN,
@@ -112,6 +143,157 @@ export function 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`.
+ */
+export function calculatePerpIfFee(
+	marginShortage: BN,
+	userBaseAssetAmount: BN,
+	marginRatio: number,
+	liquidatorFee: number,
+	oraclePrice: BN,
+	quoteOraclePrice: BN,
+	maxIfLiquidationFee: number
+): number {
+	const marginRatioBN = new BN(marginRatio).mul(
+		LIQUIDATION_FEE_PRECISION.div(MARGIN_PRECISION)
+	);
+
+	if (
+		oraclePrice.eq(ZERO) ||
+		quoteOraclePrice.eq(ZERO) ||
+		marginRatioBN.lte(new BN(liquidatorFee)) ||
+		userBaseAssetAmount.eq(ZERO)
+	) {
+		return 0;
+	}
+
+	const price = oraclePrice.mul(quoteOraclePrice).div(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 = BN.max(marginRatioBN.sub(new BN(liquidatorFee)), ZERO);
+	const shortageComponent = marginShortage
+		.mul(BASE_PRECISION)
+		.div(userBaseAssetAmount.abs())
+		.mul(PRICE_PRECISION)
+		.div(price);
+	impliedIfFee = BN.max(impliedIfFee.sub(shortageComponent), ZERO);
+
+	// multiply by 95% to avoid situation where fee leads to deposits == negative pnl
+	// leading to bankruptcy
+	impliedIfFee = impliedIfFee.mul(new BN(19)).div(new BN(20));
+
+	return BN.min(new BN(maxIfLiquidationFee), impliedIfFee).toNumber();
+}
+
+/**
+ * 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.
+ */
+export function calculateSpotIfFee(
+	marginShortage: BN,
+	tokenAmount: BN,
+	assetWeight: number,
+	assetLiquidationMultiplier: number,
+	liabilityWeight: number,
+	liabilityLiquidationMultiplier: number,
+	liabilityDecimals: number,
+	liabilityPrice: BN,
+	maxIfFee: number
+): number {
+	if (
+		assetWeight >= liabilityWeight ||
+		liabilityPrice.eq(ZERO) ||
+		tokenAmount.eq(ZERO) ||
+		liabilityLiquidationMultiplier === 0
+	) {
+		return 0;
+	}
+
+	const tokenPrecision = TEN.pow(new BN(liabilityDecimals));
+
+	const weightPrecisionRatio = LIQUIDATION_FEE_PRECISION.div(
+		SPOT_MARKET_WEIGHT_PRECISION
+	);
+	const liabilityWeightBN = new BN(liabilityWeight).mul(weightPrecisionRatio);
+	const assetWeightBN = new BN(assetWeight).mul(weightPrecisionRatio);
+
+	let impliedIfFee = BN.max(
+		liabilityWeightBN.sub(
+			assetWeightBN
+				.mul(new BN(assetLiquidationMultiplier))
+				.div(new BN(liabilityLiquidationMultiplier))
+		),
+		ZERO
+	);
+
+	const shortageComponent = marginShortage
+		.mul(LIQUIDATION_FEE_PRECISION)
+		.mul(tokenPrecision)
+		.div(tokenAmount)
+		.div(liabilityPrice);
+	impliedIfFee = BN.max(impliedIfFee.sub(shortageComponent), ZERO);
+
+	impliedIfFee = impliedIfFee
+		.mul(LIQUIDATION_FEE_PRECISION)
+		.div(liabilityWeightBN);
+
+	return BN.min(new BN(maxIfFee), impliedIfFee).toNumber();
+}
+
+/**
+ * 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).
+ */
 export function calculateAssetTransferForLiabilityTransfer(
 	assetAmount: BN,
 	assetLiquidationMultiplier: number,
@@ -173,25 +355,44 @@ export function calculateAssetTransferForLiabilityTransfer(
 	return assetTransfer;
 }
 
+/**
+ * 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).
+ */
 export function calculateMaxPctToLiquidate(
 	userLastActiveSlot: BN,
 	userLiquidationMarginFreed: BN,
 	marginShortage: BN,
 	slot: BN,
 	initialPctToLiquidate: BN,
-	liquidationDuration: BN
+	liquidationDuration: BN,
+	isIsolatedPosition = false
 ): BN {
+	// isolated perp positions are liquidated 100% in one shot
+	if (isIsolatedPosition) {
+		return LIQUIDATION_PCT_PRECISION;
+	}
+
 	// if margin shortage is tiny, accelerate liquidation
 	if (marginShortage.lt(new BN(50).mul(QUOTE_PRECISION))) {
 		return LIQUIDATION_PCT_PRECISION;
 	}
 
-	let slotsElapsed;
-	if (userLiquidationMarginFreed.gt(new BN(0))) {
-		slotsElapsed = BN.max(slot.sub(userLastActiveSlot), new BN(0));
-	} else {
-		slotsElapsed = new BN(0);
-	}
+	const slotsElapsed = BN.max(slot.sub(userLastActiveSlot), new BN(0));
 
 	const pctFreeable = BN.min(
 		slotsElapsed
@@ -213,6 +414,15 @@ export function calculateMaxPctToLiquidate(
 	return marginFreeable.mul(LIQUIDATION_PCT_PRECISION).div(marginShortage);
 }
 
+/**
+ * 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).
+ */
 export function getMarginShortage(
 	maintenanceMarginRequirementPlusBuffer: BN,
 	maintenanceTotalCollateral: BN

package/src/math/margin.ts

@@ -1,7 +1,7 @@
 /**
  * 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.
  */
 import { squareRootBN } from './utils';
 import {
@@ -23,6 +23,19 @@ import { PerpMarketAccount, PerpPosition } from '../types';
 import { isVariant } from '../types';
 import { assert } from '../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`.
+ */
 export function calculateSizePremiumLiabilityWeight(
 	size: BN, // AMM_RESERVE_PRECISION
 	imfFactor: BN,
@@ -59,6 +72,17 @@ export function calculateSizePremiumLiabilityWeight(
 	return maxLiabilityWeight;
 }
 
+/**
+ * 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 function calculateSizeDiscountAssetWeight(
 	size: BN, // AMM_RESERVE_PRECISION
 	imfFactor: BN,
@@ -89,12 +113,17 @@ export function 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).
  */
 export function calculateBaseAssetValueWithOracle(
 	market: PerpMarketAccount,
@@ -118,6 +147,7 @@ export function calculateBaseAssetValueWithOracle(
 	return baseAssetAmount.abs().mul(price).div(AMM_RESERVE_PRECISION);
 }
 
+/** Convenience wrapper returning just `worstCaseBaseAssetAmount` from `calculateWorstCasePerpLiabilityValue` — see that function for semantics and units (AMM_RESERVE_PRECISION, 1e9, signed). */
 export function calculateWorstCaseBaseAssetAmount(
 	perpPosition: PerpPosition,
 	perpMarket: PerpMarketAccount,
@@ -130,6 +160,19 @@ export function calculateWorstCaseBaseAssetAmount(
 	).worstCaseBaseAssetAmount;
 }
 
+/**
+ * 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 function calculateWorstCasePerpLiabilityValue(
 	perpPosition: PerpPosition,
 	perpMarket: PerpMarketAccount,
@@ -171,6 +214,13 @@ export function 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).
+ */
 export function calculatePerpLiabilityValue(
 	baseAssetAmount: BN,
 	price: BN
@@ -179,10 +229,17 @@ export function 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).
  */
 export function calculateMarginUSDCRequiredForTrade(
 	velocityClient: VelocityClient,
@@ -215,9 +272,18 @@ export function 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`).
  */
 export function calculateCollateralDepositRequiredForTrade(
 	velocityClient: VelocityClient,