@velocity-exchange/sdk 0.3.0 → 0.4.0

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

@@ -2,40 +2,160 @@ import { BN } from '../isomorphic/anchor';
 import { PerpMarketAccount, MarginCategory, SpotMarketAccount } from '../types';
 import { MMOraclePriceData, OraclePriceData } from '../oracles/types';
 /**
- * Calculates market mark price
+ * Calculates the perp market's current mark (mid) price from its raw (non-spread) AMM reserves,
+ * after first repegging the AMM to the oracle price (`calculateUpdatedAMM`) if `mmOraclePriceData`
+ * is provided.
  *
- * @param market
- * @return markPrice : Precision PRICE_PRECISION
+ * @param {PerpMarketAccount} market - The perp market account
+ * @param {MMOraclePriceData} [mmOraclePriceData] - Current MM oracle price data; omit to price the
+ *   AMM's stored reserves as-is without repegging
+ * @return {BN} The mark price, PRICE_PRECISION (1e6)
  */
 export declare function calculateReservePrice(market: PerpMarketAccount, mmOraclePriceData?: MMOraclePriceData): BN;
 /**
- * Calculates market bid price
+ * Calculates the perp market's current bid price — the price a taker sells into — by repegging
+ * the AMM to the oracle price and pricing the short-side spread reserves.
  *
- * @param market
- * @return bidPrice : Precision PRICE_PRECISION
+ * @param {PerpMarketAccount} market - The perp market account
+ * @param {MMOraclePriceData} [mmOraclePriceData] - Current MM oracle price data, used both to
+ *   repeg the AMM and to compute the spread reserves
+ * @param {BN} [latestSlot] - Current slot, used for reference-price-offset smoothing in the
+ *   spread calculation
+ * @return {BN} The bid price, PRICE_PRECISION (1e6)
  */
 export declare function calculateBidPrice(market: PerpMarketAccount, mmOraclePriceData?: MMOraclePriceData, latestSlot?: BN): BN;
 /**
- * Calculates market ask price
+ * Calculates the perp market's current ask price — the price a taker buys at — by repegging
+ * the AMM to the oracle price and pricing the long-side spread reserves.
  *
- * @param market
- * @return askPrice : Precision PRICE_PRECISION
+ * @param {PerpMarketAccount} market - The perp market account
+ * @param {MMOraclePriceData} [mmOraclePriceData] - Current MM oracle price data, used both to
+ *   repeg the AMM and to compute the spread reserves
+ * @param {BN} [latestSlot] - Current slot, used for reference-price-offset smoothing in the
+ *   spread calculation
+ * @return {BN} The ask price, PRICE_PRECISION (1e6)
  */
 export declare function calculateAskPrice(market: PerpMarketAccount, mmOraclePriceData?: MMOraclePriceData, latestSlot?: BN): BN;
+/**
+ * Calculates the signed spread between a price and the oracle price.
+ *
+ * @param {BN} price - A price, PRICE_PRECISION (1e6)
+ * @param {OraclePriceData} oraclePriceData - Oracle price data, PRICE_PRECISION (1e6)
+ * @return {BN} `price - oraclePriceData.price`, PRICE_PRECISION (1e6)
+ */
 export declare function calculateOracleSpread(price: BN, oraclePriceData: OraclePriceData): BN;
+/**
+ * Calculates the effective margin ratio for a perp position of a given size, applying the
+ * IMF size premium on top of the market's base initial/maintenance ratio. Returns 0 for markets
+ * in `'Settlement'` status (no margin is required once a market is settling out).
+ *
+ * @param {PerpMarketAccount} market - The perp market account
+ * @param {BN} size - The position's base asset amount (`abs()` semantics expected), BASE_PRECISION (1e9)
+ * @param {MarginCategory} marginCategory - `'Initial'`, `'Maintenance'`, or `'Fill'`; throws for any other value.
+ *   `'Fill'` uses `(marginRatioInitial + marginRatioMaintenance) / 2` (integer division), mirroring
+ *   `PerpMarket::get_margin_ratio`.
+ * @param {number} [customMarginRatio] - User's custom max margin ratio, `MARGIN_PRECISION` (1e4)
+ *   units; only applied for `'Initial'`, where the looser (higher) of the computed ratio and
+ *   this value is used
+ * @return {number} The margin ratio, scaled by `MARGIN_PRECISION` (1e4, i.e. 10000 = 100%)
+ */
 export declare function calculateMarketMarginRatio(market: PerpMarketAccount, size: BN, marginCategory: MarginCategory, customMarginRatio?: number): number;
+/**
+ * Calculates the asset weight applied to a perp position's unrealized (positive) PnL when it
+ * counts toward collateral, mirroring `PerpMarket::get_unrealized_asset_weight`'s
+ * `Initial`/`Maintenance` branches. Only call this for a positive `unrealizedPnl` — the on-chain
+ * equivalent always weights a negative unrealized PnL at `SPOT_MARKET_WEIGHT_PRECISION` (100%,
+ * i.e. it's not discounted since it's a liability, not an asset).
+ *
+ * `'Initial'` weighting applies two independent discounts: (1) if `calculateNetUserPnlImbalance`
+ * (net user PnL less the pnl pool and a fifth of the fee pool) exceeds `unrealizedPnlMaxImbalance`,
+ * the base weight is first scaled down by `unrealizedPnlMaxImbalance / netUnsettledPnl`; (2) the
+ * IMF size-discount (`calculateSizeDiscountAssetWeight`) is then applied to the position's own
+ * `unrealizedPnl` size. Two notes for exact parity with the on-chain `get_unrealized_asset_weight`:
+ * (a) the Rust gate compares the *raw* `calculate_net_user_pnl` (no pool subtraction) against
+ * `unrealized_pnl_max_imbalance`, whereas step (1) here nets out the pnl/fee pool first — a
+ * looser (more forgiving) trigger condition; (b) the Rust size-discount rescales `unrealized_pnl`
+ * by `AMM_TO_QUOTE_PRECISION_RATIO` (1e3) before step (2), whereas this passes `unrealizedPnl`
+ * (QUOTE_PRECISION, 1e6) directly — `calculateSizeDiscountAssetWeight`'s `size` parameter is
+ * otherwise documented as `AMM_RESERVE_PRECISION` (1e9) elsewhere in the SDK.
+ *
+ * @param {PerpMarketAccount} market - The perp market account
+ * @param {SpotMarketAccount} quoteSpotMarket - The market's quote spot market account
+ * @param {BN} unrealizedPnl - The position's unrealized PnL, expected positive, QUOTE_PRECISION (1e6)
+ * @param {MarginCategory} marginCategory - `'Initial'`, `'Maintenance'`, or `'Fill'` (Fill is weighted identically to Initial)
+ * @param {Pick<OraclePriceData, 'price'>} oraclePriceData - Oracle price, PRICE_PRECISION (1e6),
+ *   used only for the imbalance check's `calculateNetUserPnlImbalance` call
+ * @return {BN} The asset weight, scaled by `SPOT_MARKET_WEIGHT_PRECISION` (1e4, i.e. 10000 = 100%)
+ */
 export declare function calculateUnrealizedAssetWeight(market: PerpMarketAccount, quoteSpotMarket: SpotMarketAccount, unrealizedPnl: BN, marginCategory: MarginCategory, oraclePriceData: Pick<OraclePriceData, 'price'>): BN;
+/**
+ * Calculates the perp market's pnl pool balance — the quote tokens on hand to pay out settled
+ * user profits before insurance fund draws are needed.
+ *
+ * @param {PerpMarketAccount} perpMarket - The perp market account
+ * @param {SpotMarketAccount} spotMarket - The market's quote spot market account
+ * @return {BN} The pnl pool token amount, scaled by `spotMarket.decimals` (quote decimals)
+ */
 export declare function calculateMarketAvailablePNL(perpMarket: PerpMarketAccount, spotMarket: SpotMarketAccount): BN;
+/**
+ * Calculates the maximum insurance the market could still draw to cover a PnL deficit: the
+ * remaining `quoteMaxInsurance` allocation not yet claimed, plus the AMM's own fee pool (which is
+ * drawn down before external insurance). `spotMarket` must be the quote spot market — asserts
+ * otherwise.
+ *
+ * @param {PerpMarketAccount} perpMarket - The perp market account
+ * @param {SpotMarketAccount} spotMarket - The quote spot market account (must have
+ *   `marketIndex === QUOTE_SPOT_MARKET_INDEX`)
+ * @return {BN} `quoteMaxInsurance - quoteSettledInsurance + ammFeePoolTokenAmount`, scaled by
+ *   quote decimals
+ */
 export declare function calculateMarketMaxAvailableInsurance(perpMarket: PerpMarketAccount, spotMarket: SpotMarketAccount): BN;
+/**
+ * Calculates the net unrealized + unsettled PnL owed to all users of a perp market at a given
+ * oracle price, mirroring `calculate_net_user_pnl`: the AMM's net counterparty position valued
+ * at `oraclePriceData.price`, plus the market's cost basis (`quoteAssetAmount +
+ * netUnsettledFundingPnl`). This is the quantity the pnl pool + insurance fund must be able to
+ * cover across all users.
+ *
+ * @param {PerpMarketAccount} perpMarket - The perp market account
+ * @param {Pick<OraclePriceData, 'price'>} oraclePriceData - Oracle price, PRICE_PRECISION (1e6)
+ *   (callers typically pass the live price or a TWAP depending on the check being performed)
+ * @return {BN} Net user PnL, QUOTE_PRECISION (1e6); positive means users are net owed
+ */
 export declare function calculateNetUserPnl(perpMarket: PerpMarketAccount, oraclePriceData: Pick<OraclePriceData, 'price'>): BN;
+/**
+ * Calculates how far `calculateNetUserPnl` exceeds the funds already on hand to pay it out (the
+ * pnl pool, plus by default a 20% slice of the AMM fee pool as a conservative haircut on funds
+ * not yet swept into the pnl pool). A positive result means the market is short of pnl-pool
+ * funds by that amount; a negative result means the pnl pool has surplus.
+ *
+ * @param {PerpMarketAccount} perpMarket - The perp market account
+ * @param {SpotMarketAccount} spotMarket - The market's quote spot market account
+ * @param {Pick<OraclePriceData, 'price'>} oraclePriceData - Oracle price, PRICE_PRECISION (1e6),
+ *   passed through to `calculateNetUserPnl`
+ * @param {boolean} [applyFeePoolDiscount] - When true (default), only 1/5 of the AMM fee pool
+ *   counts toward available funds; when false, the full fee pool counts
+ * @return {BN} `netUserPnl - (pnlPool + feePoolContribution)`, QUOTE_PRECISION (1e6)
+ */
 export declare function calculateNetUserPnlImbalance(perpMarket: PerpMarketAccount, spotMarket: SpotMarketAccount, oraclePriceData: Pick<OraclePriceData, 'price'>, applyFeePoolDiscount?: boolean): BN;
 /**
- * Calculates trigger price for a perp market based on oracle price and current time
- * Implements the same logic as the Rust get_trigger_price function
+ * Calculates the price used to evaluate trigger (stop/take-profit) orders for a perp market,
+ * mirroring the Rust `get_trigger_price`. When `useMedianPrice` is true, the trigger price is the
+ * median of three candidates — the last fill price (or oracle price if there's been no fill), the
+ * oracle price adjusted by the implied funding basis, and the oracle price adjusted by the 5min
+ * mark/oracle TWAP basis — then clamped to within a contract-tier-dependent band around the raw
+ * oracle price (tier A/B: 20bps, tier C: 100bps, others: 250bps) via `clampTriggerPrice`. This
+ * resists a single manipulated print (last fill or a momentary oracle/mark divergence) from
+ * triggering orders it shouldn't. When `useMedianPrice` is false, the raw oracle price is used
+ * directly with no smoothing.
  *
- * @param market - The perp market account
- * @param oraclePrice - Current oracle price (precision: PRICE_PRECISION)
- * @param now - Current timestamp in seconds
- * @returns trigger price (precision: PRICE_PRECISION)
+ * @param {PerpMarketAccount} market - The perp market account
+ * @param {BN} oraclePrice - Current oracle price, PRICE_PRECISION (1e6); its absolute value is
+ *   used throughout
+ * @param {BN} now - Current unix timestamp, seconds; used to prorate the implied funding basis
+ *   over the time remaining until the next funding update
+ * @param {boolean} useMedianPrice - Whether to apply the median-of-three + clamp smoothing, or
+ *   use the raw oracle price directly
+ * @returns {BN} The trigger price, PRICE_PRECISION (1e6)
  */
 export declare function getTriggerPrice(market: PerpMarketAccount, oraclePrice: BN, now: BN, useMedianPrice: boolean): BN;

package/lib/browser/math/market.js

@@ -9,10 +9,14 @@ const numericConstants_1 = require("../constants/numericConstants");
 const spotBalance_1 = require("./spotBalance");
 const assert_1 = require("../assert/assert");
 /**
- * Calculates market mark price
+ * Calculates the perp market's current mark (mid) price from its raw (non-spread) AMM reserves,
+ * after first repegging the AMM to the oracle price (`calculateUpdatedAMM`) if `mmOraclePriceData`
+ * is provided.
  *
- * @param market
- * @return markPrice : Precision PRICE_PRECISION
+ * @param {PerpMarketAccount} market - The perp market account
+ * @param {MMOraclePriceData} [mmOraclePriceData] - Current MM oracle price data; omit to price the
+ *   AMM's stored reserves as-is without repegging
+ * @return {BN} The mark price, PRICE_PRECISION (1e6)
  */
 function calculateReservePrice(market, mmOraclePriceData) {
     const newAmm = (0, amm_1.calculateUpdatedAMM)(market.amm, mmOraclePriceData);
@@ -20,10 +24,15 @@ function calculateReservePrice(market, mmOraclePriceData) {
 }
 exports.calculateReservePrice = calculateReservePrice;
 /**
- * Calculates market bid price
+ * Calculates the perp market's current bid price — the price a taker sells into — by repegging
+ * the AMM to the oracle price and pricing the short-side spread reserves.
  *
- * @param market
- * @return bidPrice : Precision PRICE_PRECISION
+ * @param {PerpMarketAccount} market - The perp market account
+ * @param {MMOraclePriceData} [mmOraclePriceData] - Current MM oracle price data, used both to
+ *   repeg the AMM and to compute the spread reserves
+ * @param {BN} [latestSlot] - Current slot, used for reference-price-offset smoothing in the
+ *   spread calculation
+ * @return {BN} The bid price, PRICE_PRECISION (1e6)
  */
 function calculateBidPrice(market, mmOraclePriceData, latestSlot) {
     const { baseAssetReserve, quoteAssetReserve, newPeg } = (0, amm_1.calculateUpdatedAMMSpreadReserves)(market.amm, market.marketStats, types_1.PositionDirection.SHORT, mmOraclePriceData, latestSlot);
@@ -31,20 +40,47 @@ function calculateBidPrice(market, mmOraclePriceData, latestSlot) {
 }
 exports.calculateBidPrice = calculateBidPrice;
 /**
- * Calculates market ask price
+ * Calculates the perp market's current ask price — the price a taker buys at — by repegging
+ * the AMM to the oracle price and pricing the long-side spread reserves.
  *
- * @param market
- * @return askPrice : Precision PRICE_PRECISION
+ * @param {PerpMarketAccount} market - The perp market account
+ * @param {MMOraclePriceData} [mmOraclePriceData] - Current MM oracle price data, used both to
+ *   repeg the AMM and to compute the spread reserves
+ * @param {BN} [latestSlot] - Current slot, used for reference-price-offset smoothing in the
+ *   spread calculation
+ * @return {BN} The ask price, PRICE_PRECISION (1e6)
  */
 function calculateAskPrice(market, mmOraclePriceData, latestSlot) {
     const { baseAssetReserve, quoteAssetReserve, newPeg } = (0, amm_1.calculateUpdatedAMMSpreadReserves)(market.amm, market.marketStats, types_1.PositionDirection.LONG, mmOraclePriceData, latestSlot);
     return (0, amm_1.calculatePrice)(baseAssetReserve, quoteAssetReserve, newPeg);
 }
 exports.calculateAskPrice = calculateAskPrice;
+/**
+ * Calculates the signed spread between a price and the oracle price.
+ *
+ * @param {BN} price - A price, PRICE_PRECISION (1e6)
+ * @param {OraclePriceData} oraclePriceData - Oracle price data, PRICE_PRECISION (1e6)
+ * @return {BN} `price - oraclePriceData.price`, PRICE_PRECISION (1e6)
+ */
 function calculateOracleSpread(price, oraclePriceData) {
     return price.sub(oraclePriceData.price);
 }
 exports.calculateOracleSpread = calculateOracleSpread;
+/**
+ * Calculates the effective margin ratio for a perp position of a given size, applying the
+ * IMF size premium on top of the market's base initial/maintenance ratio. Returns 0 for markets
+ * in `'Settlement'` status (no margin is required once a market is settling out).
+ *
+ * @param {PerpMarketAccount} market - The perp market account
+ * @param {BN} size - The position's base asset amount (`abs()` semantics expected), BASE_PRECISION (1e9)
+ * @param {MarginCategory} marginCategory - `'Initial'`, `'Maintenance'`, or `'Fill'`; throws for any other value.
+ *   `'Fill'` uses `(marginRatioInitial + marginRatioMaintenance) / 2` (integer division), mirroring
+ *   `PerpMarket::get_margin_ratio`.
+ * @param {number} [customMarginRatio] - User's custom max margin ratio, `MARGIN_PRECISION` (1e4)
+ *   units; only applied for `'Initial'`, where the looser (higher) of the computed ratio and
+ *   this value is used
+ * @return {number} The margin ratio, scaled by `MARGIN_PRECISION` (1e4, i.e. 10000 = 100%)
+ */
 function calculateMarketMarginRatio(market, size, marginCategory, customMarginRatio = 0) {
     if (market.status === 'Settlement')
         return 0;
@@ -53,6 +89,10 @@ function calculateMarketMarginRatio(market, size, marginCategory, customMarginRa
         case 'Initial':
             defaultMarginRatio = market.marginRatioInitial;
             break;
+        case 'Fill':
+            // mirrors PerpMarket::get_margin_ratio's Fill branch: integer-divided average
+            defaultMarginRatio = Math.floor((market.marginRatioInitial + market.marginRatioMaintenance) / 2);
+            break;
         case 'Maintenance':
             defaultMarginRatio = market.marginRatioMaintenance;
             break;
@@ -68,10 +108,40 @@ function calculateMarketMarginRatio(market, size, marginCategory, customMarginRa
     return marginRatio;
 }
 exports.calculateMarketMarginRatio = calculateMarketMarginRatio;
+/**
+ * Calculates the asset weight applied to a perp position's unrealized (positive) PnL when it
+ * counts toward collateral, mirroring `PerpMarket::get_unrealized_asset_weight`'s
+ * `Initial`/`Maintenance` branches. Only call this for a positive `unrealizedPnl` — the on-chain
+ * equivalent always weights a negative unrealized PnL at `SPOT_MARKET_WEIGHT_PRECISION` (100%,
+ * i.e. it's not discounted since it's a liability, not an asset).
+ *
+ * `'Initial'` weighting applies two independent discounts: (1) if `calculateNetUserPnlImbalance`
+ * (net user PnL less the pnl pool and a fifth of the fee pool) exceeds `unrealizedPnlMaxImbalance`,
+ * the base weight is first scaled down by `unrealizedPnlMaxImbalance / netUnsettledPnl`; (2) the
+ * IMF size-discount (`calculateSizeDiscountAssetWeight`) is then applied to the position's own
+ * `unrealizedPnl` size. Two notes for exact parity with the on-chain `get_unrealized_asset_weight`:
+ * (a) the Rust gate compares the *raw* `calculate_net_user_pnl` (no pool subtraction) against
+ * `unrealized_pnl_max_imbalance`, whereas step (1) here nets out the pnl/fee pool first — a
+ * looser (more forgiving) trigger condition; (b) the Rust size-discount rescales `unrealized_pnl`
+ * by `AMM_TO_QUOTE_PRECISION_RATIO` (1e3) before step (2), whereas this passes `unrealizedPnl`
+ * (QUOTE_PRECISION, 1e6) directly — `calculateSizeDiscountAssetWeight`'s `size` parameter is
+ * otherwise documented as `AMM_RESERVE_PRECISION` (1e9) elsewhere in the SDK.
+ *
+ * @param {PerpMarketAccount} market - The perp market account
+ * @param {SpotMarketAccount} quoteSpotMarket - The market's quote spot market account
+ * @param {BN} unrealizedPnl - The position's unrealized PnL, expected positive, QUOTE_PRECISION (1e6)
+ * @param {MarginCategory} marginCategory - `'Initial'`, `'Maintenance'`, or `'Fill'` (Fill is weighted identically to Initial)
+ * @param {Pick<OraclePriceData, 'price'>} oraclePriceData - Oracle price, PRICE_PRECISION (1e6),
+ *   used only for the imbalance check's `calculateNetUserPnlImbalance` call
+ * @return {BN} The asset weight, scaled by `SPOT_MARKET_WEIGHT_PRECISION` (1e4, i.e. 10000 = 100%)
+ */
 function calculateUnrealizedAssetWeight(market, quoteSpotMarket, unrealizedPnl, marginCategory, oraclePriceData) {
     let assetWeight;
     switch (marginCategory) {
+        // mirrors get_unrealized_asset_weight: Fill is treated like Initial (same base
+        // weight, same imbalance + size-discount adjustments).
         case 'Initial':
+        case 'Fill':
             assetWeight = new anchor_1.BN(market.unrealizedPnlInitialAssetWeight);
             if (market.unrealizedPnlMaxImbalance.gt(numericConstants_1.ZERO)) {
                 const netUnsettledPnl = calculateNetUserPnlImbalance(market, quoteSpotMarket, oraclePriceData);
@@ -86,14 +156,36 @@ function calculateUnrealizedAssetWeight(market, quoteSpotMarket, unrealizedPnl,
         case 'Maintenance':
             assetWeight = new anchor_1.BN(market.unrealizedPnlMaintenanceAssetWeight);
             break;
+        default:
+            throw new Error('Invalid margin category');
     }
     return assetWeight;
 }
 exports.calculateUnrealizedAssetWeight = calculateUnrealizedAssetWeight;
+/**
+ * Calculates the perp market's pnl pool balance — the quote tokens on hand to pay out settled
+ * user profits before insurance fund draws are needed.
+ *
+ * @param {PerpMarketAccount} perpMarket - The perp market account
+ * @param {SpotMarketAccount} spotMarket - The market's quote spot market account
+ * @return {BN} The pnl pool token amount, scaled by `spotMarket.decimals` (quote decimals)
+ */
 function calculateMarketAvailablePNL(perpMarket, spotMarket) {
     return (0, spotBalance_1.getTokenAmount)(perpMarket.pnlPool.scaledBalance, spotMarket, types_1.SpotBalanceType.DEPOSIT);
 }
 exports.calculateMarketAvailablePNL = calculateMarketAvailablePNL;
+/**
+ * Calculates the maximum insurance the market could still draw to cover a PnL deficit: the
+ * remaining `quoteMaxInsurance` allocation not yet claimed, plus the AMM's own fee pool (which is
+ * drawn down before external insurance). `spotMarket` must be the quote spot market — asserts
+ * otherwise.
+ *
+ * @param {PerpMarketAccount} perpMarket - The perp market account
+ * @param {SpotMarketAccount} spotMarket - The quote spot market account (must have
+ *   `marketIndex === QUOTE_SPOT_MARKET_INDEX`)
+ * @return {BN} `quoteMaxInsurance - quoteSettledInsurance + ammFeePoolTokenAmount`, scaled by
+ *   quote decimals
+ */
 function calculateMarketMaxAvailableInsurance(perpMarket, spotMarket) {
     (0, assert_1.assert)(spotMarket.marketIndex == numericConstants_1.QUOTE_SPOT_MARKET_INDEX);
     // todo: insuranceFundAllocation technically not guaranteed to be in Insurance Fund
@@ -102,6 +194,18 @@ function calculateMarketMaxAvailableInsurance(perpMarket, spotMarket) {
     return insuranceFundAllocation.add(ammFeePool);
 }
 exports.calculateMarketMaxAvailableInsurance = calculateMarketMaxAvailableInsurance;
+/**
+ * Calculates the net unrealized + unsettled PnL owed to all users of a perp market at a given
+ * oracle price, mirroring `calculate_net_user_pnl`: the AMM's net counterparty position valued
+ * at `oraclePriceData.price`, plus the market's cost basis (`quoteAssetAmount +
+ * netUnsettledFundingPnl`). This is the quantity the pnl pool + insurance fund must be able to
+ * cover across all users.
+ *
+ * @param {PerpMarketAccount} perpMarket - The perp market account
+ * @param {Pick<OraclePriceData, 'price'>} oraclePriceData - Oracle price, PRICE_PRECISION (1e6)
+ *   (callers typically pass the live price or a TWAP depending on the check being performed)
+ * @return {BN} Net user PnL, QUOTE_PRECISION (1e6); positive means users are net owed
+ */
 function calculateNetUserPnl(perpMarket, oraclePriceData) {
     const netUserPositionValue = perpMarket.amm.baseAssetAmountWithAmm
         .mul(oraclePriceData.price)
@@ -112,6 +216,20 @@ function calculateNetUserPnl(perpMarket, oraclePriceData) {
     return netUserPnl;
 }
 exports.calculateNetUserPnl = calculateNetUserPnl;
+/**
+ * Calculates how far `calculateNetUserPnl` exceeds the funds already on hand to pay it out (the
+ * pnl pool, plus by default a 20% slice of the AMM fee pool as a conservative haircut on funds
+ * not yet swept into the pnl pool). A positive result means the market is short of pnl-pool
+ * funds by that amount; a negative result means the pnl pool has surplus.
+ *
+ * @param {PerpMarketAccount} perpMarket - The perp market account
+ * @param {SpotMarketAccount} spotMarket - The market's quote spot market account
+ * @param {Pick<OraclePriceData, 'price'>} oraclePriceData - Oracle price, PRICE_PRECISION (1e6),
+ *   passed through to `calculateNetUserPnl`
+ * @param {boolean} [applyFeePoolDiscount] - When true (default), only 1/5 of the AMM fee pool
+ *   counts toward available funds; when false, the full fee pool counts
+ * @return {BN} `netUserPnl - (pnlPool + feePoolContribution)`, QUOTE_PRECISION (1e6)
+ */
 function calculateNetUserPnlImbalance(perpMarket, spotMarket, oraclePriceData, applyFeePoolDiscount = true) {
     const netUserPnl = calculateNetUserPnl(perpMarket, oraclePriceData);
     const pnlPool = (0, spotBalance_1.getTokenAmount)(perpMarket.pnlPool.scaledBalance, spotMarket, types_1.SpotBalanceType.DEPOSIT);
@@ -124,13 +242,24 @@ function calculateNetUserPnlImbalance(perpMarket, spotMarket, oraclePriceData, a
 }
 exports.calculateNetUserPnlImbalance = calculateNetUserPnlImbalance;
 /**
- * Calculates trigger price for a perp market based on oracle price and current time
- * Implements the same logic as the Rust get_trigger_price function
+ * Calculates the price used to evaluate trigger (stop/take-profit) orders for a perp market,
+ * mirroring the Rust `get_trigger_price`. When `useMedianPrice` is true, the trigger price is the
+ * median of three candidates — the last fill price (or oracle price if there's been no fill), the
+ * oracle price adjusted by the implied funding basis, and the oracle price adjusted by the 5min
+ * mark/oracle TWAP basis — then clamped to within a contract-tier-dependent band around the raw
+ * oracle price (tier A/B: 20bps, tier C: 100bps, others: 250bps) via `clampTriggerPrice`. This
+ * resists a single manipulated print (last fill or a momentary oracle/mark divergence) from
+ * triggering orders it shouldn't. When `useMedianPrice` is false, the raw oracle price is used
+ * directly with no smoothing.
  *
- * @param market - The perp market account
- * @param oraclePrice - Current oracle price (precision: PRICE_PRECISION)
- * @param now - Current timestamp in seconds
- * @returns trigger price (precision: PRICE_PRECISION)
+ * @param {PerpMarketAccount} market - The perp market account
+ * @param {BN} oraclePrice - Current oracle price, PRICE_PRECISION (1e6); its absolute value is
+ *   used throughout
+ * @param {BN} now - Current unix timestamp, seconds; used to prorate the implied funding basis
+ *   over the time remaining until the next funding update
+ * @param {boolean} useMedianPrice - Whether to apply the median-of-three + clamp smoothing, or
+ *   use the raw oracle price directly
+ * @returns {BN} The trigger price, PRICE_PRECISION (1e6)
  */
 function getTriggerPrice(market, oraclePrice, now, useMedianPrice) {
     if (!useMedianPrice) {
@@ -164,8 +293,7 @@ function getLastFundingBasis(market, oraclePrice, now) {
             .mul(numericConstants_1.PRICE_PRECISION)
             .div(market.marketStats.lastFundingOracleTwap)
             .muln(24);
-        const lastFundingRatePreAdj = lastFundingRate.sub(numericConstants_1.FUNDING_RATE_PRECISION.div(new anchor_1.BN(3333)) // FUNDING_RATE_OFFSET_PERCENTAGE
-        );
+        const lastFundingRatePreAdj = lastFundingRate.sub(numericConstants_1.FUNDING_RATE_OFFSET_PERCENTAGE);
         const timeLeftUntilFundingUpdate = anchor_1.BN.min(anchor_1.BN.max(now.sub(market.lastFundingRateTs), numericConstants_1.ZERO), market.marketStats.fundingPeriod);
         const lastFundingBasis = oraclePrice
             .mul(lastFundingRatePreAdj)

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

@@ -1,14 +1,127 @@
 import { HistoricalOracleData, MarketStats, OracleGuardRails, OracleSource, OracleValidity, PerpMarketAccount } from '../types';
 import { OraclePriceData } from '../oracles/types';
 import { BN } from '../isomorphic/anchor';
+/**
+ * Computes a generic sanity band around the oracle price, sized by the gap between the
+ * market's initial and maintenance margin ratios (a wider margin gap allows a wider band).
+ * This is a coarse UI/client-side sanity check, not the exact on-chain price-band gate —
+ * order and settlement price-divergence checks on-chain compare the 5-min oracle TWAP
+ * spread via `isMarkOracleTooDivergent`/`isOracleTooDivergent` instead.
+ * @param market Perp market whose `marginRatioInitial`/`marginRatioMaintenance` (MARGIN_PRECISION, 1e4) set the band width.
+ * @param oraclePriceData Must provide `price`, PRICE_PRECISION (1e6).
+ * @returns `[lowerBound, upperBound]`, both PRICE_PRECISION (1e6).
+ */
 export declare function oraclePriceBands(market: PerpMarketAccount, oraclePriceData: Pick<OraclePriceData, 'price'>): [BN, BN];
+/**
+ * Returns the per-market multiplier applied to `confidenceIntervalMaxSize` when checking
+ * oracle confidence-interval validity, mirroring `PerpMarket::get_max_confidence_interval_multiplier`.
+ * Riskier contract tiers tolerate a wider oracle confidence interval before being flagged
+ * invalid: 1x for tier A/B, 2x for tier C, 10x for Speculative, 50x for HighlySpeculative and Isolated.
+ * @param market Perp market whose `contractTier` selects the multiplier.
+ * @returns Unitless multiplier (dimensionless BN).
+ */
 export declare function getMaxConfidenceIntervalMultiplier(market: PerpMarketAccount): BN;
+/**
+ * Classifies an oracle reading's validity for `market`, mirroring `oracle_validity` in
+ * `programs/velocity/src/math/oracle.rs`. Checks are evaluated in severity order and the
+ * first failing check wins: non-positive price, too volatile vs the oracle TWAP
+ * (`tooVolatileRatio`), confidence interval too wide (scaled by
+ * `getMaxConfidenceIntervalMultiplier`), stale for margin use, insufficient oracle data
+ * points, then stale for AMM use (low-risk or immediate, gated by the market's
+ * `oracleLowRiskSlotDelayOverride`/`oracleSlotDelayOverride`). Returns `OracleValidity.Valid`
+ * only if none of these trip. Callers typically gate on the returned enum via
+ * `isOracleValidForAction`-style helpers rather than comparing directly.
+ * @param market Perp market providing contract tier, oracle source, and stale-slot overrides.
+ * @param oraclePriceData Oracle reading to validate (`price`/`confidence` PRICE_PRECISION 1e6, `slot`).
+ * @param oracleGuardRails Protocol-wide validity thresholds (`state.oracleGuardRails`).
+ * @param slot Current slot, used to compute oracle delay.
+ * @param oracleStalenessBuffer Extra slots subtracted from the raw oracle delay before staleness checks (default 5) to absorb normal reporting lag.
+ * @returns The most severe `OracleValidity` classification that applies.
+ */
 export declare function getOracleValidity(market: PerpMarketAccount, oraclePriceData: OraclePriceData, oracleGuardRails: OracleGuardRails, slot: BN, oracleStalenessBuffer?: BN): OracleValidity;
+/**
+ * Simplified, AMM-fill-oriented validity check: `true` only if the oracle has sufficient
+ * data points, is not stale (vs `slotsBeforeStaleForAmm`), has a positive price, isn't too
+ * volatile vs the market's oracle TWAP, and its confidence interval isn't too wide. Unlike
+ * `getOracleValidity` this does not distinguish "stale for margin" or "low risk" tiers — it
+ * is a single valid/invalid gate specifically for whether the AMM may fill against this
+ * price.
+ * @param market Perp market providing the oracle TWAP and contract tier for the confidence multiplier.
+ * @param oraclePriceData Oracle reading to validate (`price`/`confidence` PRICE_PRECISION 1e6).
+ * @param oracleGuardRails Protocol-wide validity thresholds.
+ * @param slot Current slot, used to compute oracle staleness.
+ * @returns `true` if the oracle is valid for an AMM-only fill.
+ */
 export declare function isOracleValid(market: PerpMarketAccount, oraclePriceData: OraclePriceData, oracleGuardRails: OracleGuardRails, slot: number): boolean;
+/**
+ * True when the live oracle price has diverged from the market's 5-minute oracle TWAP by
+ * more than the configured threshold (with a 50% safety floor). Distinct from
+ * `isMarkOracleTooDivergent`, which compares mark (reserve) price to the same TWAP instead
+ * of the live oracle price to itself — this catches an oracle feed itself jumping abruptly.
+ * @param marketStats Market stats providing `historicalOracleData.lastOraclePriceTwap5Min`, PRICE_PRECISION (1e6).
+ * @param oraclePriceData Live oracle reading (`price`, PRICE_PRECISION 1e6).
+ * @param oracleGuardRails Protocol-wide guard rails; uses `priceDivergence.oracleTwap5MinPercentDivergence`, PERCENTAGE_PRECISION (1e6).
+ * @returns `true` if the oracle-vs-TWAP spread exceeds the divergence threshold.
+ */
 export declare function isOracleTooDivergent(marketStats: MarketStats, oraclePriceData: OraclePriceData, oracleGuardRails: OracleGuardRails): boolean;
+/**
+ * True when `|priceSpreadPct|` exceeds the configured mark/oracle divergence threshold,
+ * with a 10% safety floor. Mirrors `is_mark_oracle_too_divergent` in
+ * `programs/velocity/src/math/oracle.rs` — a pure decision helper used both to block
+ * funding-rate updates (`block_operation`) and to reject orders/settlement when the market
+ * has moved too far from its 5-minute oracle TWAP (`validate_market_within_price_band`,
+ * which calls this once with the mark-vs-TWAP spread and once with the oracle-vs-TWAP
+ * spread, blocking on whichever is more divergent).
+ * @param priceSpreadPct Mark (or oracle) price spread vs the 5-minute oracle TWAP, PERCENTAGE_PRECISION (1e6, signed).
+ * @param oracleGuardRails Protocol-wide guard rails; uses `priceDivergence.markOraclePercentDivergence`, PERCENTAGE_PRECISION (1e6).
+ * @returns `true` if the spread exceeds `max(markOraclePercentDivergence, 10%)`.
+ */
+export declare function isMarkOracleTooDivergent(priceSpreadPct: BN, oracleGuardRails: OracleGuardRails): boolean;
+/**
+ * Projects the oracle TWAP forward to `now` without requiring an on-chain update,
+ * time-weighting the stored TWAP against the live oracle price clamped to within 1/3 of the
+ * current TWAP (so a single outlier tick can't swing the live estimate too far). Uses the
+ * 5-minute TWAP field when `period` equals `FIVE_MINUTE`, otherwise the funding-period (hourly) TWAP field.
+ * @param histOracleData Market's historical oracle data (TWAP fields, PRICE_PRECISION 1e6, and their last-update timestamp).
+ * @param oraclePriceData Live oracle reading (`price`, PRICE_PRECISION 1e6).
+ * @param now Current unix timestamp (seconds).
+ * @param period TWAP window length in seconds — pass `FIVE_MINUTE` for the 5-minute TWAP, otherwise the funding period is assumed.
+ * @returns Live-projected oracle TWAP, PRICE_PRECISION (1e6).
+ */
 export declare function calculateLiveOracleTwap(histOracleData: HistoricalOracleData, oraclePriceData: OraclePriceData, now: BN, period: BN): BN;
+/**
+ * Live-projected oracle price standard deviation, combining the live oracle price's
+ * deviation from the freshly-projected 1hr and 5min TWAPs with the decayed stored
+ * `marketStats.oracleStd`. Feeds `calculateVolSpreadBN`'s volatility-based spread component.
+ * @param marketStats Market stats providing `historicalOracleData`, `fundingPeriod`, and the stored `oracleStd`.
+ * @param oraclePriceData Live oracle reading (`price`, PRICE_PRECISION 1e6).
+ * @param now Current unix timestamp (seconds).
+ * @returns Live oracle price standard deviation, PRICE_PRECISION (1e6).
+ */
 export declare function calculateLiveOracleStd(marketStats: MarketStats, oraclePriceData: OraclePriceData, now: BN): BN;
+/**
+ * Live-projected oracle confidence interval as a fraction of `reservePrice`, floored by a
+ * decaying lower bound derived from the market's last stored confidence (so confidence
+ * can't be understated immediately after a stale update — it decays back down over ~20
+ * seconds). Feeds the volatility-spread and quote calculations that need a current
+ * confidence estimate without waiting for the next on-chain refresh.
+ * @param marketStats Market stats providing `lastOracleConfPct` and `historicalOracleData`'s last-update timestamp.
+ * @param oraclePriceData Live oracle reading; uses `confidence`, PRICE_PRECISION (1e6).
+ * @param reservePrice AMM reserve (mark) price used to express confidence as a fraction, PRICE_PRECISION (1e6).
+ * @param now Current unix timestamp (seconds).
+ * @returns Oracle confidence as a fraction of price, BID_ASK_SPREAD_PRECISION (1e6).
+ */
 export declare function getNewOracleConfPct(marketStats: MarketStats, oraclePriceData: OraclePriceData, reservePrice: BN, now: BN): BN;
+/**
+ * Returns the scale factor to convert a price quoted under `firstOracleSource` into the
+ * equivalent price under `secondOracleSource`, for the Pyth Lazer "scaled" variants
+ * (`pythLazer1K`/`pythLazer1M` report a price 1,000x/1,000,000x smaller than `pythLazer` for
+ * high-priced assets). Returns `{1, 1}` (no conversion) for any other source pair.
+ * @param firstOracleSource Oracle source the input price is denominated in.
+ * @param secondOracleSource Oracle source to convert the price into.
+ * @returns `{ numerator, denominator }` such that `price * numerator / denominator` converts between sources.
+ * @throws if either source is a removed Pyth-pull variant (`pythPull`, `pyth1KPull`, `pyth1MPull`, `pythStableCoinPull`).
+ */
 export declare function getMultipleBetweenOracleSources(firstOracleSource: OracleSource, secondOracleSource: OracleSource): {
     numerator: BN;
     denominator: BN;