@velocity-exchange/sdk 0.3.0 → 0.4.0

package/lib/browser/math/funding.js

@@ -52,11 +52,29 @@ function shrinkStaleTwaps(market, markTwapWithMantissa, oracleTwapWithMantissa,
     return [newMarkTwap, newOracleTwap];
 }
 /**
- *
- * @param market
- * @param oraclePriceData
- * @param periodAdjustment
- * @returns Estimated funding rate. : Precision //TODO-PRECISION
+ * Client-side projection of the market's next funding rate, mirroring the pure-math portion
+ * of `update_funding_rate` in `programs/velocity/src/controller/funding.rs` (live mark/oracle
+ * TWAPs, the per-market dead-zone/ramp-slope premium, the baseline
+ * `FUNDING_RATE_OFFSET_DENOMINATOR` offset, and the contract-tier divergence cap) without
+ * requiring an on-chain funding update to have actually run. This is an estimate for display
+ * or pre-trade planning — it does not settle anything and can differ slightly from what the
+ * next on-chain `update_funding_rate` call computes if `now`/`oraclePriceData` have moved
+ * since.
+ * @param market Perp market to estimate funding for; must not be `uninitialized`.
+ * @param mmOraclePriceData Current MM oracle price data, used to compute the live mark TWAP if `markPrice` isn't supplied.
+ * @param oraclePriceData Current oracle price data — required unless the market is uninitialized.
+ * @param markPrice Optional mark price override; if omitted, derived from the current bid/ask midpoint.
+ * @param now Current unix timestamp (seconds); defaults to wall-clock time.
+ * @returns `[markTwap, oracleTwap, lowerboundEst, cappedAltEst, interpEst]`:
+ *   - `markTwap` / `oracleTwap`: live-projected TWAPs, PRICE_PRECISION (1e6).
+ *   - `lowerboundEst`, `cappedAltEst`, `interpEst`: funding-rate-per-period estimates
+ *     expressed as `(price spread / oracle price) * 1e8` — feed these into
+ *     `getFundingRatePct`/`calculateFormattedLiveFundingRate` (which multiply by
+ *     `FUNDING_RATE_BUFFER_PRECISION` and read the result at `FUNDING_RATE_PRECISION_EXP`,
+ *     1e9) to get a plain percentage. `cappedAltEst` is the smaller-open-interest side,
+ *     capped by how much the fee pool can top it up; `interpEst` is the uncapped
+ *     straight-line interpolation; `lowerboundEst` further scales the spread down by the
+ *     fraction of the current funding period that has elapsed since the last update.
  */
 function calculateAllEstimatedFundingRate(market, mmOraclePriceData, oraclePriceData, markPrice, now) {
     if ((0, types_1.isVariant)(market.status, 'uninitialized')) {
@@ -165,16 +183,26 @@ function calculateAllEstimatedFundingRate(market, mmOraclePriceData, oraclePrice
 }
 exports.calculateAllEstimatedFundingRate = calculateAllEstimatedFundingRate;
 /**
- * To get funding rate as a percentage, you need to multiply by the funding rate buffer precision
- * @param rawFundingRate
- * @returns
+ * Converts a raw funding-rate estimate (as produced by `calculateAllEstimatedFundingRate`,
+ * scaled as `(price spread / oracle price) * 1e8`) into a plain human-readable percentage
+ * number (e.g. `0.05` means 0.05%), by rescaling into `FUNDING_RATE_PRECISION_EXP` (1e9)
+ * fixed-point via `FUNDING_RATE_BUFFER_PRECISION`.
+ * @param rawFundingRate Raw funding rate estimate to convert.
+ * @returns Plain percentage number (not a fraction — `1` means 1%, not 100%).
  */
 const getFundingRatePct = (rawFundingRate) => {
     return bigNum_1.BigNum.from(rawFundingRate.mul(numericConstants_2.FUNDING_RATE_BUFFER_PRECISION), numericConstants_2.FUNDING_RATE_PRECISION_EXP).toNum();
 };
 /**
- * Calculate funding rates in human-readable form. Values will have some lost precision and shouldn't be used in strict accounting.
- * @param period : 'hour' | 'year' :: Use 'hour' for the hourly payment as a percentage, 'year' for the payment as an estimated APR.
+ * Calculates estimated funding rates in human-readable form (plain JS `number` percentages,
+ * not BN), including a plain-English summary sentence. Values pass through floating-point
+ * math and lose precision vs the underlying BN estimate — use `calculateAllEstimatedFundingRate`
+ * or `calculateLongShortFundingRate` directly for anything that needs exact precision.
+ * @param market Perp market to estimate funding for.
+ * @param mmOraclePriceData Current MM oracle price data.
+ * @param oraclePriceData Current oracle price data.
+ * @param period `'hour'` for the hourly payment as a percentage, `'year'` for the payment annualized (assuming 24 funding payments/day) as an estimated APR.
+ * @returns `longRate`/`shortRate`: signed percentage numbers from that side's own perspective — negative means that side pays funding, positive means that side receives it; `fundingRateUnit`: `'%'` or `'% APR'`; `formattedFundingRateSummary`: a human-readable sentence describing who pays whom.
  */
 function calculateFormattedLiveFundingRate(market, mmOraclePriceData, oraclePriceData, period) {
     const nowBN = new anchor_1.BN(Date.now() / 1000);
@@ -223,11 +251,16 @@ function getMaxPriceDivergenceForFundingRate(market, oracleTwap) {
     }
 }
 /**
- *
- * @param market
- * @param oraclePriceData
- * @param periodAdjustment
- * @returns Estimated funding rate. : Precision //TODO-PRECISION
+ * Convenience wrapper around `calculateAllEstimatedFundingRate` that assigns its capped
+ * (`cappedAltEst`) vs. uncapped (`interpEst`) estimate to the long/short side by comparing
+ * `market.baseAssetAmountLong` against `market.baseAssetAmountShort`. When both sides are
+ * equal, both get `interpEst`.
+ * @param market Perp market to estimate funding for.
+ * @param mmOraclePriceData Current MM oracle price data.
+ * @param oraclePriceData Current oracle price data.
+ * @param markPrice Optional mark price override.
+ * @param now Current unix timestamp (seconds); defaults to wall-clock time.
+ * @returns `[longFundingRateEst, shortFundingRateEst]`, same scale as `calculateAllEstimatedFundingRate`'s rate outputs.
  */
 function calculateLongShortFundingRate(market, mmOraclePriceData, oraclePriceData, markPrice, now) {
     const [_1, _2, _, cappedAltEst, interpEst] = calculateAllEstimatedFundingRate(market, mmOraclePriceData, oraclePriceData, markPrice, now);
@@ -243,11 +276,15 @@ function calculateLongShortFundingRate(market, mmOraclePriceData, oraclePriceDat
 }
 exports.calculateLongShortFundingRate = calculateLongShortFundingRate;
 /**
- *
- * @param market
- * @param oraclePriceData
- * @param periodAdjustment
- * @returns Estimated funding rate. : Precision //TODO-PRECISION
+ * Same estimate assignment as `calculateLongShortFundingRate` (using
+ * `market.baseAssetAmountLong` vs `market.baseAssetAmountShort.abs()` this time) but also
+ * returns the live-projected mark/oracle TWAPs alongside the rate estimates.
+ * @param market Perp market to estimate funding for.
+ * @param mmOraclePriceData Current MM oracle price data.
+ * @param oraclePriceData Current oracle price data.
+ * @param markPrice Optional mark price override.
+ * @param now Current unix timestamp (seconds); defaults to wall-clock time.
+ * @returns `[markTwapLive, oracleTwapLive, longFundingRateEst, shortFundingRateEst]` — TWAPs in PRICE_PRECISION (1e6), rate estimates in the same scale as `calculateAllEstimatedFundingRate`.
  */
 function calculateLongShortFundingRateAndLiveTwaps(market, mmOraclePriceData, oraclePriceData, markPrice, now) {
     const [markTwapLive, oracleTwapLive, _2, cappedAltEst, interpEst] = calculateAllEstimatedFundingRate(market, mmOraclePriceData, oraclePriceData, markPrice, now);
@@ -263,9 +300,12 @@ function calculateLongShortFundingRateAndLiveTwaps(market, mmOraclePriceData, or
 }
 exports.calculateLongShortFundingRateAndLiveTwaps = calculateLongShortFundingRateAndLiveTwaps;
 /**
- *
- * @param market
- * @returns Estimated fee pool size
+ * Estimated quote pool available to top up the smaller side's funding payment shortfall:
+ * one-third of the AMM's own retained equity (`totalFeeMinusDistributions`), floored at
+ * zero. Post-isolation there is no separate protocol floor to reserve — the AMM's own
+ * equity is the only buffer.
+ * @param market Perp market to evaluate.
+ * @returns Estimated fee pool size, QUOTE_PRECISION (1e6).
  */
 function calculateFundingPool(market) {
     // todo

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

@@ -1,7 +1,69 @@
 import { BN } from '../isomorphic/anchor';
 import { SpotMarketAccount } from '../types';
+/**
+ * Estimates the annualized yield (APR) insurance fund stakers would earn if the market's revenue
+ * pool were settled into the insurance fund vault right now, projected forward assuming the same
+ * revenue pool size settles at the market's configured `revenueSettlePeriod` cadence for a year.
+ * The insurance fund is entirely staker-owned (no protocol split): all settled revenue accrues to
+ * stakers via share-price appreciation. Only 10% of the projected annual revenue (`payoutRatio`)
+ * is assumed to actually reach the vault as yield; the result is capped at 1000% APR.
+ *
+ * @param {SpotMarketAccount} spotMarket - The spot market account (its `revenuePool` and
+ *   `insuranceFund.revenueSettlePeriod` drive the projection)
+ * @param {BN} vaultBalance - Current insurance fund vault token amount, market's token decimals
+ * @param {BN} amount - Hypothetical additional deposit/withdrawal token amount to apply to the
+ *   vault balance before computing the ratio (positive = deposit, negative = withdrawal),
+ *   market's token decimals
+ * @return {number} Estimated APR as a plain JS percentage number (e.g. `12.5` = 12.5% APR), or
+ *   `0` if `revenueSettlePeriod` is unset or `vaultBalance + amount` is zero. This is a display
+ *   estimate, not a program mirror — it also inherits a small numerical imprecision from scaling
+ *   a `BN` by the fractional `payoutRatio` (0.1) via `BN.muln`, which multiplies fractionally
+ *   per-limb rather than performing exact fixed-point math.
+ */
 export declare function nextRevenuePoolSettleApr(spotMarket: SpotMarketAccount, vaultBalance: BN, // vault token amount
 amount: BN): number;
+/**
+ * Calculates how many insurance fund shares a deposit of `amount` would mint, mirroring
+ * `vault_amount_to_if_shares`. Shares are minted proportionally to the deposit's fraction of the
+ * vault (`amount * totalIfShares / insuranceFundVaultBalance`, floored); if the vault is
+ * currently empty, 1 share is minted per token (bootstrapping the share price at 1:1).
+ *
+ * @param {BN} amount - Token amount being staked, market's token decimals
+ * @param {BN} totalIfShares - Current total insurance fund shares outstanding
+ * @param {BN} insuranceFundVaultBalance - Current insurance fund vault token amount, market's token decimals
+ * @return {BN} Shares minted
+ */
 export declare function stakeAmountToShares(amount: BN, totalIfShares: BN, insuranceFundVaultBalance: BN): BN;
+/**
+ * Calculates the token amount `nShares` of the insurance fund are currently worth, mirroring
+ * `if_shares_to_vault_amount` (floored). Returns zero (rather than dividing by zero) if there are
+ * no shares outstanding.
+ *
+ * @param {BN} nShares - Number of insurance fund shares
+ * @param {BN} totalIfShares - Current total insurance fund shares outstanding
+ * @param {BN} insuranceFundVaultBalance - Current insurance fund vault token amount, market's token decimals
+ * @return {BN} Token value of `nShares`, market's token decimals; floored at zero
+ */
 export declare function unstakeSharesToAmount(nShares: BN, totalIfShares: BN, insuranceFundVaultBalance: BN): BN;
+/**
+ * Calculates a staker's total current value — their remaining staked shares plus any pending
+ * withdrawal request — accounting for the fact that a pending request's payout is locked in at
+ * the vault-value snapshot taken when the request was made (`InsuranceFundStake.lastWithdrawRequestValue`),
+ * not the vault's current value. This is what a user can expect to see if they cancel/complete a
+ * pending unstake request without further vault movement.
+ *
+ * @param {BN} nShares - The staker's total shares (`InsuranceFundStake.ifShares`), including any
+ *   shares already earmarked by a pending withdrawal request
+ * @param {BN} withdrawRequestShares - Shares locked by a pending withdrawal request
+ *   (`InsuranceFundStake.lastWithdrawRequestShares`), 0 if none is pending
+ * @param {BN} withdrawRequestAmount - The token amount locked in at request time
+ *   (`InsuranceFundStake.lastWithdrawRequestValue`), market's token decimals
+ * @param {BN} totalIfShares - Current total insurance fund shares outstanding
+ * @param {BN} insuranceFundVaultBalance - Current insurance fund vault token amount, market's token decimals
+ * @return {BN} `stakedAmount + withdrawAmount`: the current value of `nShares - withdrawRequestShares`
+ *   (floored at zero) at today's vault price, plus `min(withdrawRequestAmount, withdrawRequestShares'
+ *   value at today's vault price)` — the pending withdrawal is whichever is lower of its
+ *   locked-in amount and its current value, so vault depreciation since the request reduces the
+ *   payout but vault appreciation does not increase it
+ */
 export declare function unstakeSharesToAmountWithOpenRequest(nShares: BN, withdrawRequestShares: BN, withdrawRequestAmount: BN, totalIfShares: BN, insuranceFundVaultBalance: BN): BN;

package/lib/browser/math/insurance.js

@@ -5,6 +5,26 @@ const numericConstants_1 = require("../constants/numericConstants");
 const spotBalance_1 = require("../math/spotBalance");
 const anchor_1 = require("../isomorphic/anchor");
 const types_1 = require("../types");
+/**
+ * Estimates the annualized yield (APR) insurance fund stakers would earn if the market's revenue
+ * pool were settled into the insurance fund vault right now, projected forward assuming the same
+ * revenue pool size settles at the market's configured `revenueSettlePeriod` cadence for a year.
+ * The insurance fund is entirely staker-owned (no protocol split): all settled revenue accrues to
+ * stakers via share-price appreciation. Only 10% of the projected annual revenue (`payoutRatio`)
+ * is assumed to actually reach the vault as yield; the result is capped at 1000% APR.
+ *
+ * @param {SpotMarketAccount} spotMarket - The spot market account (its `revenuePool` and
+ *   `insuranceFund.revenueSettlePeriod` drive the projection)
+ * @param {BN} vaultBalance - Current insurance fund vault token amount, market's token decimals
+ * @param {BN} amount - Hypothetical additional deposit/withdrawal token amount to apply to the
+ *   vault balance before computing the ratio (positive = deposit, negative = withdrawal),
+ *   market's token decimals
+ * @return {number} Estimated APR as a plain JS percentage number (e.g. `12.5` = 12.5% APR), or
+ *   `0` if `revenueSettlePeriod` is unset or `vaultBalance + amount` is zero. This is a display
+ *   estimate, not a program mirror — it also inherits a small numerical imprecision from scaling
+ *   a `BN` by the fractional `payoutRatio` (0.1) via `BN.muln`, which multiplies fractionally
+ *   per-limb rather than performing exact fixed-point math.
+ */
 function nextRevenuePoolSettleApr(spotMarket, vaultBalance, // vault token amount
 amount // delta token amount
 ) {
@@ -33,6 +53,17 @@ amount // delta token amount
     return nextApr;
 }
 exports.nextRevenuePoolSettleApr = nextRevenuePoolSettleApr;
+/**
+ * Calculates how many insurance fund shares a deposit of `amount` would mint, mirroring
+ * `vault_amount_to_if_shares`. Shares are minted proportionally to the deposit's fraction of the
+ * vault (`amount * totalIfShares / insuranceFundVaultBalance`, floored); if the vault is
+ * currently empty, 1 share is minted per token (bootstrapping the share price at 1:1).
+ *
+ * @param {BN} amount - Token amount being staked, market's token decimals
+ * @param {BN} totalIfShares - Current total insurance fund shares outstanding
+ * @param {BN} insuranceFundVaultBalance - Current insurance fund vault token amount, market's token decimals
+ * @return {BN} Shares minted
+ */
 function stakeAmountToShares(amount, totalIfShares, insuranceFundVaultBalance) {
     let nShares;
     if (insuranceFundVaultBalance.gt(numericConstants_1.ZERO)) {
@@ -44,6 +75,16 @@ function stakeAmountToShares(amount, totalIfShares, insuranceFundVaultBalance) {
     return nShares;
 }
 exports.stakeAmountToShares = stakeAmountToShares;
+/**
+ * Calculates the token amount `nShares` of the insurance fund are currently worth, mirroring
+ * `if_shares_to_vault_amount` (floored). Returns zero (rather than dividing by zero) if there are
+ * no shares outstanding.
+ *
+ * @param {BN} nShares - Number of insurance fund shares
+ * @param {BN} totalIfShares - Current total insurance fund shares outstanding
+ * @param {BN} insuranceFundVaultBalance - Current insurance fund vault token amount, market's token decimals
+ * @return {BN} Token value of `nShares`, market's token decimals; floored at zero
+ */
 function unstakeSharesToAmount(nShares, totalIfShares, insuranceFundVaultBalance) {
     let amount;
     if (totalIfShares.gt(numericConstants_1.ZERO)) {
@@ -55,6 +96,27 @@ function unstakeSharesToAmount(nShares, totalIfShares, insuranceFundVaultBalance
     return amount;
 }
 exports.unstakeSharesToAmount = unstakeSharesToAmount;
+/**
+ * Calculates a staker's total current value — their remaining staked shares plus any pending
+ * withdrawal request — accounting for the fact that a pending request's payout is locked in at
+ * the vault-value snapshot taken when the request was made (`InsuranceFundStake.lastWithdrawRequestValue`),
+ * not the vault's current value. This is what a user can expect to see if they cancel/complete a
+ * pending unstake request without further vault movement.
+ *
+ * @param {BN} nShares - The staker's total shares (`InsuranceFundStake.ifShares`), including any
+ *   shares already earmarked by a pending withdrawal request
+ * @param {BN} withdrawRequestShares - Shares locked by a pending withdrawal request
+ *   (`InsuranceFundStake.lastWithdrawRequestShares`), 0 if none is pending
+ * @param {BN} withdrawRequestAmount - The token amount locked in at request time
+ *   (`InsuranceFundStake.lastWithdrawRequestValue`), market's token decimals
+ * @param {BN} totalIfShares - Current total insurance fund shares outstanding
+ * @param {BN} insuranceFundVaultBalance - Current insurance fund vault token amount, market's token decimals
+ * @return {BN} `stakedAmount + withdrawAmount`: the current value of `nShares - withdrawRequestShares`
+ *   (floored at zero) at today's vault price, plus `min(withdrawRequestAmount, withdrawRequestShares'
+ *   value at today's vault price)` — the pending withdrawal is whichever is lower of its
+ *   locked-in amount and its current value, so vault depreciation since the request reduces the
+ *   payout but vault appreciation does not increase it
+ */
 function unstakeSharesToAmountWithOpenRequest(nShares, withdrawRequestShares, withdrawRequestAmount, totalIfShares, insuranceFundVaultBalance) {
     let stakedAmount;
     if (totalIfShares.gt(numericConstants_1.ZERO)) {

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

@@ -1,20 +1,136 @@
 import { BN } from '../isomorphic/anchor';
 /**
- * @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 declare function calculateBaseAssetAmountToCoverMarginShortage(marginShortage: BN, marginRatio: number, liquidationFee: number, ifLiquidationFee: number, oraclePrice: BN, quoteOraclePrice: BN): BN | undefined;
 /**
- * @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 declare function calculateLiabilityTransferToCoverMarginShortage(marginShortage: BN, assetWeight: number, assetLiquidationMultiplier: number, liabilityWeight: number, liabilityLiquidationMultiplier: number, liabilityDecimals: number, liabilityPrice: BN, ifLiquidationFee: number): BN | undefined;
+/**
+ * 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 declare function calculatePerpIfFee(marginShortage: BN, userBaseAssetAmount: BN, marginRatio: number, liquidatorFee: number, oraclePrice: BN, quoteOraclePrice: BN, maxIfLiquidationFee: number): number;
+/**
+ * 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 declare function calculateSpotIfFee(marginShortage: BN, tokenAmount: BN, assetWeight: number, assetLiquidationMultiplier: number, liabilityWeight: number, liabilityLiquidationMultiplier: number, liabilityDecimals: number, liabilityPrice: BN, maxIfFee: number): number;
+/**
+ * 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 declare function calculateAssetTransferForLiabilityTransfer(assetAmount: BN, assetLiquidationMultiplier: number, assetDecimals: number, assetPrice: BN, liabilityAmount: BN, liabilityLiquidationMultiplier: number, liabilityDecimals: number, liabilityPrice: BN): BN | undefined;
-export declare function calculateMaxPctToLiquidate(userLastActiveSlot: BN, userLiquidationMarginFreed: BN, marginShortage: BN, slot: BN, initialPctToLiquidate: BN, liquidationDuration: BN): BN;
+/**
+ * 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 declare function calculateMaxPctToLiquidate(userLastActiveSlot: BN, userLiquidationMarginFreed: BN, marginShortage: BN, slot: BN, initialPctToLiquidate: BN, liquidationDuration: BN, isIsolatedPosition?: boolean): BN;
+/**
+ * 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 declare function getMarginShortage(maintenanceMarginRequirementPlusBuffer: BN, maintenanceTotalCollateral: BN): BN;