@velocity-exchange/sdk 0.3.0 → 0.6.0

package/lib/browser/math/builder.js

@@ -1,29 +1,59 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isBuilderOrderAvailable = exports.isBuilderOrderReferral = exports.isBuilderOrderCompleted = exports.isBuilderOrderOpen = exports.hasBuilderParams = exports.escrowHasReferrer = exports.isBuilderReferral = void 0;
+exports.isBuilderOrderAvailable = exports.isBuilderOrderReferral = exports.isBuilderOrderCompleted = exports.isBuilderOrderOpen = exports.hasBuilderParams = exports.escrowHasReferrer = exports.isBuilderReferral = exports.calculateBuilderFee = void 0;
 const web3_js_1 = require("@solana/web3.js");
+const anchor_1 = require("../isomorphic/anchor");
 const types_1 = require("../types");
+const BUILDER_FEE_TENTH_BPS_DENOMINATOR = new anchor_1.BN(100000);
 /**
- * True when the user's RevenueShareEscrow was initialized with a referrer.
- * Fills for such users must include the escrow account or the program rejects
- * them with UnableToLoadRevenueShareAccount.
+ * Calculates the builder fee charged on top of the tiered taker/maker fee, mirroring the
+ * program's builder-fee calc. `builderFeeTenthBps` is denominated in tenth-basis-points, i.e.
+ * `10 * builderFeeTenthBps == 1 bp == 0.01%` — the fee fraction is `builderFeeTenthBps / 100_000`.
+ *
+ * @param {BN} quoteAssetAmount - The fill's quote asset amount the fee is charged against,
+ *   QUOTE_PRECISION (1e6)
+ * @param {number} builderFeeTenthBps - The builder fee rate, in tenth-bps (`OrderParams.builderFeeTenthBps`)
+ * @return {BN} The builder fee, QUOTE_PRECISION (1e6)
+ */
+function calculateBuilderFee(quoteAssetAmount, builderFeeTenthBps) {
+    return quoteAssetAmount
+        .mul(new anchor_1.BN(builderFeeTenthBps))
+        .div(BUILDER_FEE_TENTH_BPS_DENOMINATOR);
+}
+exports.calculateBuilderFee = calculateBuilderFee;
+/**
+ * True when the user's `RevenueShareEscrow` was initialized with a referrer.
+ *
+ * @param {Pick<UserStatsAccount, 'referrerStatus'>} userStats - The user's stats account (or a
+ *   pick containing just `referrerStatus`)
+ * @return {boolean} Whether `ReferrerStatus.BuilderReferral` is set in `referrerStatus`. When
+ *   true, fills for this user must include the escrow account as a remaining account or the
+ *   program rejects them with `UnableToLoadRevenueShareAccount`
  */
 function isBuilderReferral(userStats) {
     return (userStats.referrerStatus & types_1.ReferrerStatus.BuilderReferral) !== 0;
 }
 exports.isBuilderReferral = isBuilderReferral;
 /**
- * True when the escrow was initialized with a referrer. Referral rewards
- * accrue into such escrows on fills, so fills of the escrow owner's orders
- * must include the escrow account (see `isBuilderReferral`).
+ * True when the escrow was initialized with a referrer (its `referrer` field is not the default
+ * pubkey).
+ *
+ * @param {Pick<RevenueShareEscrowAccount, 'referrer'>} escrow - The revenue share escrow account
+ *   (or a pick containing just `referrer`)
+ * @return {boolean} Whether `escrow.referrer` is set. Referral rewards accrue into such escrows on
+ *   fills, so fills of the escrow owner's orders must include the escrow account (see `isBuilderReferral`)
  */
 function escrowHasReferrer(escrow) {
     return !escrow.referrer.equals(web3_js_1.PublicKey.default);
 }
 exports.escrowHasReferrer = escrowHasReferrer;
 /**
- * True when the order params carry a builder code (`builderIdx` +
- * `builderFeeTenthBps`).
+ * True when the order params carry a builder code (both `builderIdx` and `builderFeeTenthBps`
+ * are set, i.e. neither `null` nor `undefined`).
+ *
+ * @param {Pick<OrderParams, 'builderIdx' | 'builderFeeTenthBps'>} orderParams - The order params
+ *   (or a pick containing just the builder fields)
+ * @return {boolean} Whether both builder fields are present
  */
 function hasBuilderParams(orderParams) {
     return (orderParams.builderIdx !== null &&
@@ -33,20 +63,52 @@ function hasBuilderParams(orderParams) {
 }
 exports.hasBuilderParams = hasBuilderParams;
 const FLAG_IS_OPEN = 0x01;
+/**
+ * True if this `RevenueShareOrder` slot is occupied by an active order, mirroring
+ * `RevenueShareOrder::is_open` (`RevenueShareOrderBitFlag::Open`). While open, `orderId` and
+ * `subAccountId` identify the live order this slot is tracking.
+ *
+ * @param {RevenueShareOrder} order - The revenue share order slot
+ * @return {boolean} Whether the `Open` bit is set in `order.bitFlags`
+ */
 function isBuilderOrderOpen(order) {
     return (order.bitFlags & FLAG_IS_OPEN) !== 0;
 }
 exports.isBuilderOrderOpen = isBuilderOrderOpen;
 const FLAG_IS_COMPLETED = 0x02;
+/**
+ * True if this `RevenueShareOrder` has been filled or canceled and is awaiting settlement into
+ * the builder's account, mirroring `RevenueShareOrder::is_completed`
+ * (`RevenueShareOrderBitFlag::Completed`). Once completed, `orderId`/`subAccountId` are no
+ * longer meaningful and the slot's accrued fees may be merged with other completed orders.
+ *
+ * @param {RevenueShareOrder} order - The revenue share order slot
+ * @return {boolean} Whether the `Completed` bit is set in `order.bitFlags`
+ */
 function isBuilderOrderCompleted(order) {
     return (order.bitFlags & FLAG_IS_COMPLETED) !== 0;
 }
 exports.isBuilderOrderCompleted = isBuilderOrderCompleted;
 const FLAG_IS_REFERRAL = 0x04;
+/**
+ * True if this `RevenueShareOrder` slot instead holds referral rewards pending settlement for a
+ * market (`RevenueShareOrderBitFlag::Referral`), rather than tracking a builder-fee order. When
+ * set, no other bit flag should be set and `builderIdx` is ignored.
+ *
+ * @param {RevenueShareOrder} order - The revenue share order slot
+ * @return {boolean} Whether the `Referral` bit is set in `order.bitFlags`
+ */
 function isBuilderOrderReferral(order) {
     return (order.bitFlags & FLAG_IS_REFERRAL) !== 0;
 }
 exports.isBuilderOrderReferral = isBuilderOrderReferral;
+/**
+ * True if this `RevenueShareOrder` slot is free to be (re)written — neither open nor completed —
+ * mirroring `RevenueShareOrder::is_available`.
+ *
+ * @param {RevenueShareOrder} order - The revenue share order slot
+ * @return {boolean} Whether the slot can be claimed for a new order
+ */
 function isBuilderOrderAvailable(order) {
     return !isBuilderOrderOpen(order) && !isBuilderOrderCompleted(order);
 }

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

@@ -1,3 +1,24 @@
 import { BN } from '../isomorphic/anchor';
+/**
+ * Converts a fixed-point `BN` into a human-readable JS `number` by dividing out `precision`.
+ * Correctly handles negative `bigNumber` values: `bn.js`'s `.div()`/`.mod()` truncate toward
+ * zero (matching JS `%` semantics), so the whole and fractional parts recombine with consistent
+ * sign without needing separate negative-number handling. Precision beyond what a JS `number`
+ * (IEEE-754 double) can represent exactly may be lost — this is a display/estimation helper, not
+ * for further on-chain-precision math.
+ *
+ * @param {BN} bigNumber - The value to convert; `null`/`undefined` return 0 (a `BN` instance for
+ *   zero is still an object and thus truthy, so it falls through to the normal division below)
+ * @param {BN} [precision] - The fixed-point precision to divide out; defaults to `PRICE_PRECISION` (1e6)
+ * @return {number} The value as a JS number, in the same units `precision` represents one whole unit of
+ */
 export declare const convertToNumber: (bigNumber: BN, precision?: BN) => number;
+/**
+ * Converts a human-readable JS `number` into a fixed-point `BN` scaled by `precision`. The
+ * fractional part is rounded (`Math.round`) to the nearest unit of `precision`, not truncated.
+ *
+ * @param {number} value - The human-readable value to convert
+ * @param {BN} precision - The fixed-point precision to scale by (e.g. `QUOTE_PRECISION`, `BASE_PRECISION`)
+ * @return {BN} `value` scaled by `precision`
+ */
 export declare function convertToBN(value: number, precision: BN): BN;

package/lib/browser/math/conversion.js

@@ -3,6 +3,19 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.convertToBN = exports.convertToNumber = void 0;
 const anchor_1 = require("../isomorphic/anchor");
 const numericConstants_1 = require("../constants/numericConstants");
+/**
+ * Converts a fixed-point `BN` into a human-readable JS `number` by dividing out `precision`.
+ * Correctly handles negative `bigNumber` values: `bn.js`'s `.div()`/`.mod()` truncate toward
+ * zero (matching JS `%` semantics), so the whole and fractional parts recombine with consistent
+ * sign without needing separate negative-number handling. Precision beyond what a JS `number`
+ * (IEEE-754 double) can represent exactly may be lost — this is a display/estimation helper, not
+ * for further on-chain-precision math.
+ *
+ * @param {BN} bigNumber - The value to convert; `null`/`undefined` return 0 (a `BN` instance for
+ *   zero is still an object and thus truthy, so it falls through to the normal division below)
+ * @param {BN} [precision] - The fixed-point precision to divide out; defaults to `PRICE_PRECISION` (1e6)
+ * @return {number} The value as a JS number, in the same units `precision` represents one whole unit of
+ */
 const convertToNumber = (bigNumber, precision = numericConstants_1.PRICE_PRECISION) => {
     if (!bigNumber)
         return 0;
@@ -10,6 +23,14 @@ const convertToNumber = (bigNumber, precision = numericConstants_1.PRICE_PRECISI
         bigNumber.mod(precision).toNumber() / precision.toNumber());
 };
 exports.convertToNumber = convertToNumber;
+/**
+ * Converts a human-readable JS `number` into a fixed-point `BN` scaled by `precision`. The
+ * fractional part is rounded (`Math.round`) to the nearest unit of `precision`, not truncated.
+ *
+ * @param {number} value - The human-readable value to convert
+ * @param {BN} precision - The fixed-point precision to scale by (e.g. `QUOTE_PRECISION`, `BASE_PRECISION`)
+ * @return {BN} `value` scaled by `precision`
+ */
 function convertToBN(value, precision) {
     // Get the whole part using Math.floor
     const wholePart = Math.floor(value);

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

@@ -1,9 +1,100 @@
 import { PerpMarketAccount, PerpOperation, SpotMarketAccount, SpotOperation, StateAccount, InsuranceFundOperation, MarketConfigFlag } from '../types';
+/**
+ * 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 declare function exchangePaused(state: StateAccount): boolean;
+/**
+ * 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 declare function solvencyRepairPaused(state: StateAccount): boolean;
+/**
+ * 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 declare function depositPaused(state: StateAccount, market: SpotMarketAccount): boolean;
+/**
+ * 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 declare function withdrawPaused(state: StateAccount, market: SpotMarketAccount): boolean;
+/**
+ * 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 declare function fillPaused(state: StateAccount, market: PerpMarketAccount | SpotMarketAccount): boolean;
+/**
+ * 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 declare function ammPaused(state: StateAccount, market: PerpMarketAccount | SpotMarketAccount): boolean;
+/**
+ * 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 declare function isOperationPaused(pausedOperations: number, operation: PerpOperation | SpotOperation | InsuranceFundOperation): boolean;
+/**
+ * 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 declare function isAmmDrawdownPause(market: PerpMarketAccount): boolean;
+/**
+ * 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 declare function isMarketConfigFlagSet(marketConfig: number, flag: MarketConfigFlag): boolean;
+/**
+ * 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 declare function isFormulaicKUpdateDisabled(market: PerpMarketAccount): boolean;

package/lib/browser/math/exchangeStatus.js

@@ -1,20 +1,79 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isFormulaicKUpdateDisabled = exports.isMarketConfigFlagSet = exports.isAmmDrawdownPause = exports.isOperationPaused = exports.ammPaused = exports.fillPaused = exports.solvencyRepairPaused = exports.exchangePaused = void 0;
+exports.isFormulaicKUpdateDisabled = exports.isMarketConfigFlagSet = exports.isAmmDrawdownPause = exports.isOperationPaused = exports.ammPaused = exports.fillPaused = exports.withdrawPaused = exports.depositPaused = exports.solvencyRepairPaused = exports.exchangePaused = void 0;
 const numericConstants_1 = require("../constants/numericConstants");
 const types_1 = require("../types");
 const anchor_1 = require("../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
+ */
 function exchangePaused(state) {
     return state.exchangeStatus !== types_1.ExchangeStatus.ACTIVE;
 }
 exports.exchangePaused = exchangePaused;
-// Mirror of the program's `State::solvency_repair_paused`. Gates the resolve
-// bankruptcy / pnl-deficit instructions, independent of WITHDRAW_PAUSED.
+/**
+ * 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`
+ */
 function solvencyRepairPaused(state) {
     return ((state.solvencyStatus & types_1.SolvencyStatus.SOLVENCY_REPAIR_PAUSED) ===
         types_1.SolvencyStatus.SOLVENCY_REPAIR_PAUSED);
 }
 exports.solvencyRepairPaused = solvencyRepairPaused;
+/**
+ * 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
+ */
+function depositPaused(state, market) {
+    if ((state.exchangeStatus & types_1.ExchangeStatus.DEPOSIT_PAUSED) ===
+        types_1.ExchangeStatus.DEPOSIT_PAUSED) {
+        return true;
+    }
+    return isOperationPaused(market.pausedOperations, types_1.SpotOperation.DEPOSIT);
+}
+exports.depositPaused = depositPaused;
+/**
+ * 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
+ */
+function withdrawPaused(state, market) {
+    if ((state.exchangeStatus & types_1.ExchangeStatus.WITHDRAW_PAUSED) ===
+        types_1.ExchangeStatus.WITHDRAW_PAUSED) {
+        return true;
+    }
+    return isOperationPaused(market.pausedOperations, types_1.SpotOperation.WITHDRAW);
+}
+exports.withdrawPaused = withdrawPaused;
+/**
+ * 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
+ */
 function fillPaused(state, market) {
     if ((state.exchangeStatus & types_1.ExchangeStatus.FILL_PAUSED) ===
         types_1.ExchangeStatus.FILL_PAUSED) {
@@ -28,6 +87,17 @@ function fillPaused(state, market) {
     }
 }
 exports.fillPaused = 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
+ */
 function ammPaused(state, market) {
     if ((state.exchangeStatus & types_1.ExchangeStatus.AMM_PAUSED) ===
         types_1.ExchangeStatus.AMM_PAUSED) {
@@ -45,10 +115,28 @@ function ammPaused(state, market) {
     return false;
 }
 exports.ammPaused = ammPaused;
+/**
+ * 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
+ */
 function isOperationPaused(pausedOperations, operation) {
     return (pausedOperations & operation) > 0;
 }
 exports.isOperationPaused = isOperationPaused;
+/**
+ * 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
+ */
 function isAmmDrawdownPause(market) {
     let quoteDrawdownLimitBreached;
     if ((0, types_1.isVariant)(market.contractTier, 'a') ||
@@ -82,10 +170,25 @@ function isAmmDrawdownPause(market) {
     return false;
 }
 exports.isAmmDrawdownPause = isAmmDrawdownPause;
+/**
+ * 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
+ */
 function isMarketConfigFlagSet(marketConfig, flag) {
     return (marketConfig & flag) > 0;
 }
 exports.isMarketConfigFlagSet = isMarketConfigFlagSet;
+/**
+ * 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`
+ */
 function isFormulaicKUpdateDisabled(market) {
     return isMarketConfigFlagSet(market.marketConfig, types_1.MarketConfigFlag.DISABLE_FORMULAIC_K_UPDATE);
 }

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

@@ -2,16 +2,41 @@ import { BN } from '../isomorphic/anchor';
 import { PerpMarketAccount } from '../types';
 import { MMOraclePriceData, OraclePriceData } from '../oracles/types';
 /**
- *
- * @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 declare function calculateAllEstimatedFundingRate(market: PerpMarketAccount, mmOraclePriceData?: MMOraclePriceData, oraclePriceData?: OraclePriceData, markPrice?: BN, now?: BN): [BN, BN, BN, BN, 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 declare function calculateFormattedLiveFundingRate(market: PerpMarketAccount, mmOraclePriceData: MMOraclePriceData, oraclePriceData: OraclePriceData, period: 'hour' | 'year'): {
     longRate: number;
@@ -20,24 +45,36 @@ export declare function calculateFormattedLiveFundingRate(market: PerpMarketAcco
     formattedFundingRateSummary: string;
 };
 /**
- *
- * @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 declare function calculateLongShortFundingRate(market: PerpMarketAccount, mmOraclePriceData?: MMOraclePriceData, oraclePriceData?: OraclePriceData, markPrice?: BN, now?: BN): [BN, BN];
 /**
- *
- * @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 declare function calculateLongShortFundingRateAndLiveTwaps(market: PerpMarketAccount, mmOraclePriceData?: MMOraclePriceData, oraclePriceData?: OraclePriceData, markPrice?: BN, now?: BN): [BN, BN, BN, BN];
 /**
- *
- * @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 declare function calculateFundingPool(market: PerpMarketAccount): BN;