@velocity-exchange/sdk 0.2.5 → 0.4.0

package/src/math/exchangeStatus.ts

@@ -7,6 +7,7 @@ import {
 	ExchangeStatus,
 	PerpMarketAccount,
 	PerpOperation,
+	SolvencyStatus,
 	SpotMarketAccount,
 	SpotOperation,
 	StateAccount,
@@ -16,10 +17,90 @@ import {
 } from '../types';
 import { BN } from '../isomorphic/anchor';
 
+/**
+ * True if the exchange-wide status is anything other than fully active, i.e. any bit in
+ * `ExchangeStatus` is set (deposits, withdraws, AMM, fills, liquidations, funding, settle-pnl,
+ * or AMM-immediate-fill paused).
+ *
+ * @param {StateAccount} state - The global state account
+ * @return {boolean} Whether any exchange-wide pause flag is set
+ */
 export function exchangePaused(state: StateAccount): boolean {
 	return state.exchangeStatus !== ExchangeStatus.ACTIVE;
 }
 
+/**
+ * Mirror of the program's `State::solvency_repair_paused`. Gates the resolve-bankruptcy /
+ * pnl-deficit instructions independently of `ExchangeStatus.WITHDRAW_PAUSED` — an admin can pause
+ * solvency repair without also blocking ordinary user withdrawals, or vice versa.
+ *
+ * @param {StateAccount} state - The global state account
+ * @return {boolean} Whether the `SOLVENCY_REPAIR_PAUSED` bit is set in `state.solvencyStatus`
+ */
+export function solvencyRepairPaused(state: StateAccount): boolean {
+	return (
+		(state.solvencyStatus & SolvencyStatus.SOLVENCY_REPAIR_PAUSED) ===
+		SolvencyStatus.SOLVENCY_REPAIR_PAUSED
+	);
+}
+
+/**
+ * True if deposits are blocked for `market`, either because the exchange-wide
+ * `ExchangeStatus.DEPOSIT_PAUSED` flag is set, or because the market's own
+ * `pausedOperations` bitmask has `SpotOperation.DEPOSIT` set.
+ *
+ * @param {StateAccount} state - The global state account
+ * @param {SpotMarketAccount} market - The spot market account
+ * @return {boolean} Whether deposits are paused for this market
+ */
+export function depositPaused(
+	state: StateAccount,
+	market: SpotMarketAccount
+): boolean {
+	if (
+		(state.exchangeStatus & ExchangeStatus.DEPOSIT_PAUSED) ===
+		ExchangeStatus.DEPOSIT_PAUSED
+	) {
+		return true;
+	}
+
+	return isOperationPaused(market.pausedOperations, SpotOperation.DEPOSIT);
+}
+
+/**
+ * True if withdrawals are blocked for `market`, either because the exchange-wide
+ * `ExchangeStatus.WITHDRAW_PAUSED` flag is set, or because the market's own
+ * `pausedOperations` bitmask has `SpotOperation.WITHDRAW` set. Independent of
+ * `solvencyRepairPaused`.
+ *
+ * @param {StateAccount} state - The global state account
+ * @param {SpotMarketAccount} market - The spot market account
+ * @return {boolean} Whether withdrawals are paused for this market
+ */
+export function withdrawPaused(
+	state: StateAccount,
+	market: SpotMarketAccount
+): boolean {
+	if (
+		(state.exchangeStatus & ExchangeStatus.WITHDRAW_PAUSED) ===
+		ExchangeStatus.WITHDRAW_PAUSED
+	) {
+		return true;
+	}
+
+	return isOperationPaused(market.pausedOperations, SpotOperation.WITHDRAW);
+}
+
+/**
+ * True if fills are blocked for `market`, either because the exchange-wide
+ * `ExchangeStatus.FILL_PAUSED` flag is set, or because the market's own `pausedOperations`
+ * bitmask has the market-type-appropriate fill flag set (`PerpOperation.FILL` for perp markets,
+ * detected via the presence of an `amm` field; `SpotOperation.FILL` otherwise).
+ *
+ * @param {StateAccount} state - The global state account
+ * @param {PerpMarketAccount | SpotMarketAccount} market - The perp or spot market account
+ * @return {boolean} Whether fills are paused for this market
+ */
 export function fillPaused(
 	state: StateAccount,
 	market: PerpMarketAccount | SpotMarketAccount
@@ -38,6 +119,17 @@ export function fillPaused(
 	}
 }
 
+/**
+ * True if AMM fills are blocked for `market`: the exchange-wide `ExchangeStatus.AMM_PAUSED` flag
+ * is set, the market's `pausedOperations` has `PerpOperation.AMM_FILL` set (perp markets only),
+ * or (perp markets only) the AMM has breached its per-funding-period drawdown limit
+ * (`isAmmDrawdownPause`). Always `false` for spot markets beyond the exchange-wide flag, since
+ * spot markets have no AMM.
+ *
+ * @param {StateAccount} state - The global state account
+ * @param {PerpMarketAccount | SpotMarketAccount} market - The perp or spot market account
+ * @return {boolean} Whether AMM fills are paused for this market
+ */
 export function ammPaused(
 	state: StateAccount,
 	market: PerpMarketAccount | SpotMarketAccount
@@ -65,6 +157,13 @@ export function ammPaused(
 	return false;
 }
 
+/**
+ * Bitmask test for whether `operation` is set in a `pausedOperations` field.
+ *
+ * @param {number} pausedOperations - A market or insurance-fund `pausedOperations` bitmask
+ * @param {PerpOperation | SpotOperation | InsuranceFundOperation} operation - The operation flag to test
+ * @return {boolean} Whether `operation`'s bit is set
+ */
 export function isOperationPaused(
 	pausedOperations: number,
 	operation: PerpOperation | SpotOperation | InsuranceFundOperation
@@ -72,6 +171,17 @@ export function isOperationPaused(
 	return (pausedOperations & operation) > 0;
 }
 
+/**
+ * True if a perp market's AMM has accumulated too much drawdown since its last funding update to
+ * keep accepting AMM fills, mirroring `AMM::has_too_much_drawdown`. Uses a two-stage gate: an
+ * absolute quote-denominated drawdown floor (contract tier A/B: -$10,000; others: -$5,000, i.e.
+ * `DEFAULT_REVENUE_SINCE_LAST_FUNDING_SPREAD_RETREAT` ($25) times 400 or 200) must first be
+ * breached, then a tier-specific percentage-of-total-fees drawdown limit (A: 2%, B: ~3%, C: 4%,
+ * others: 5%) must also be breached.
+ *
+ * @param {PerpMarketAccount} market - The perp market account
+ * @return {boolean} Whether the AMM should stop accepting fills due to drawdown this funding period
+ */
 export function isAmmDrawdownPause(market: PerpMarketAccount): boolean {
 	let quoteDrawdownLimitBreached: boolean;
 
@@ -121,6 +231,13 @@ export function isAmmDrawdownPause(market: PerpMarketAccount): boolean {
 	return false;
 }
 
+/**
+ * Bitmask test for whether `flag` is set in a perp market's `marketConfig` field.
+ *
+ * @param {number} marketConfig - A `PerpMarketAccount.marketConfig` bitmask
+ * @param {MarketConfigFlag} flag - The config flag to test
+ * @return {boolean} Whether `flag`'s bit is set
+ */
 export function isMarketConfigFlagSet(
 	marketConfig: number,
 	flag: MarketConfigFlag
@@ -128,6 +245,14 @@ export function isMarketConfigFlagSet(
 	return (marketConfig & flag) > 0;
 }
 
+/**
+ * True if formulaic (automatic) `k` (AMM depth) updates are disabled for this market, meaning
+ * `k` only changes via explicit admin instructions rather than the keeper-driven repeg/curve
+ * update logic.
+ *
+ * @param {PerpMarketAccount} market - The perp market account
+ * @return {boolean} Whether `DISABLE_FORMULAIC_K_UPDATE` is set in `market.marketConfig`
+ */
 export function isFormulaicKUpdateDisabled(market: PerpMarketAccount): boolean {
 	return isMarketConfigFlagSet(
 		market.marketConfig,

package/src/math/funding.ts

@@ -128,11 +128,29 @@ function shrinkStaleTwaps(
 }
 
 /**
- *
- * @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.
  */
 export function calculateAllEstimatedFundingRate(
 	market: PerpMarketAccount,
@@ -285,9 +303,12 @@ export function 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: BN) => {
 	return BigNum.from(
@@ -297,8 +318,15 @@ const getFundingRatePct = (rawFundingRate: BN) => {
 };
 
 /**
- * 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.
  */
 export function calculateFormattedLiveFundingRate(
 	market: PerpMarketAccount,
@@ -380,11 +408,16 @@ function getMaxPriceDivergenceForFundingRate(
 }
 
 /**
- *
- * @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.
  */
 export function calculateLongShortFundingRate(
 	market: PerpMarketAccount,
@@ -411,11 +444,15 @@ export function 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`.
  */
 export function calculateLongShortFundingRateAndLiveTwaps(
 	market: PerpMarketAccount,
@@ -443,9 +480,12 @@ export function 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).
  */
 export function calculateFundingPool(market: PerpMarketAccount): BN {
 	// todo

package/src/math/insurance.ts

@@ -3,6 +3,26 @@ import { getTokenAmount } from '../math/spotBalance';
 import { BN } from '../isomorphic/anchor';
 import { SpotBalanceType, 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 function nextRevenuePoolSettleApr(
 	spotMarket: SpotMarketAccount,
 	vaultBalance: BN, // vault token amount
@@ -46,6 +66,17 @@ export function nextRevenuePoolSettleApr(
 	return nextApr;
 }
 
+/**
+ * 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 function stakeAmountToShares(
 	amount: BN,
 	totalIfShares: BN,
@@ -61,6 +92,16 @@ export function stakeAmountToShares(
 	return nShares;
 }
 
+/**
+ * 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 function unstakeSharesToAmount(
 	nShares: BN,
 	totalIfShares: BN,
@@ -79,6 +120,27 @@ export function unstakeSharesToAmount(
 	return amount;
 }
 
+/**
+ * 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 function unstakeSharesToAmountWithOpenRequest(
 	nShares: BN,
 	withdrawRequestShares: BN,