@velocity-exchange/sdk 0.3.0 → 0.6.0

package/lib/browser/math/trade.js

@@ -11,24 +11,23 @@ const utils_1 = require("./utils");
 const types_2 = require("../types");
 const MAXPCT = new anchor_1.BN(1000); //percentage units are [0,1000] => [0,1]
 /**
- * Calculates avg/max slippage (price impact) for candidate trade
+ * Calculates avg/max slippage (price impact) for a hypothetical AMM-only trade.
  *
- * @deprecated use calculateEstimatedPerpEntryPrice instead
+ * @deprecated Use `calculateEstimatedPerpEntryPrice` instead (this ignores DLOB liquidity and
+ *   only swaps against the vAMM).
  *
- * @param direction
- * @param amount
- * @param market
- * @param inputAssetType which asset is being traded
- * @param useSpread whether to consider spread with calculating slippage
- * @return [pctAvgSlippage, pctMaxSlippage, entryPrice, newPrice]
- *
- * 'pctAvgSlippage' =>  the percentage change to entryPrice (average est slippage in execution) : Precision PRICE_PRECISION
- *
- * 'pctMaxSlippage' =>  the percentage change to maxPrice (highest est slippage in execution) : Precision PRICE_PRECISION
- *
- * 'entryPrice' => the average price of the trade : Precision PRICE_PRECISION
- *
- * 'newPrice' => the price of the asset after the trade : Precision PRICE_PRECISION
+ * @param {PositionDirection} direction - Taker's trade direction
+ * @param {BN} amount - Trade size in `inputAssetType` units (base: BASE_PRECISION (1e9); quote: QUOTE_PRECISION (1e6))
+ * @param {PerpMarketAccount} market - The perp market account
+ * @param {AssetType} [inputAssetType] - Whether `amount` denominates base or quote; defaults to `'quote'`
+ * @param {MMOraclePriceData} mmOraclePriceData - MM oracle price data used for spread reserve calc
+ * @param {boolean} [useSpread] - Whether to consider the bid/ask spread when computing slippage; defaults to `true`
+ * @param {BN} [latestSlot] - Slot used for spread-reserve staleness/decay calc when `useSpread` is true
+ * @return {[BN, BN, BN, BN]} `[pctAvgSlippage, pctMaxSlippage, entryPrice, newPrice]`, all
+ *   PRICE_PRECISION (1e6): `pctAvgSlippage` is the percentage change from the pre-trade price to
+ *   `entryPrice` (average execution slippage); `pctMaxSlippage` is the percentage change from the
+ *   pre-trade price to `newPrice` (worst-case/marginal slippage); `entryPrice` is the trade's
+ *   average execution price; `newPrice` is the AMM's price after the trade
  */
 function calculateTradeSlippage(direction, amount, market, inputAssetType = 'quote', mmOraclePriceData, useSpread = true, latestSlot) {
     let oldPrice;
@@ -85,15 +84,20 @@ function calculateTradeSlippage(direction, amount, market, inputAssetType = 'quo
 }
 exports.calculateTradeSlippage = calculateTradeSlippage;
 /**
- * Calculates acquired amounts for trade executed
- * @param direction
- * @param amount
- * @param market
- * @param inputAssetType
- * @param useSpread
- * @return
- * 	| 'acquiredBase' =>  positive/negative change in user's base : BN AMM_RESERVE_PRECISION
- * 	| 'acquiredQuote' => positive/negative change in user's quote : BN TODO-PRECISION
+ * Calculates the AMM reserve deltas and resulting quote amount for a hypothetical constant-product
+ * swap against the vAMM, without executing anything on-chain.
+ *
+ * @param {PositionDirection} direction - Taker's trade direction
+ * @param {BN} amount - Trade size in `inputAssetType` units (base: BASE_PRECISION (1e9); quote: QUOTE_PRECISION (1e6))
+ * @param {PerpMarketAccount} market - The perp market account
+ * @param {AssetType} [inputAssetType] - Whether `amount` denominates base or quote; defaults to `'quote'`
+ * @param {MMOraclePriceData} mmOraclePriceData - MM oracle price data used for spread reserve calc
+ * @param {boolean} [useSpread] - Whether to swap against the spread-adjusted reserves (bid/ask)
+ *   rather than the raw reserves; defaults to `true`
+ * @param {BN} [latestSlot] - Slot used for spread-reserve staleness/decay calc when `useSpread` is true
+ * @return {[BN, BN, BN]} `[acquiredBase, acquiredQuote, acquiredQuoteAssetAmount]` — the change
+ *   in the AMM's base and quote reserves (signed, `AMM_RESERVE_PRECISION` (1e9)), and the
+ *   resulting user-facing quote amount swapped, `QUOTE_PRECISION` (1e6)
  */
 function calculateTradeAcquiredAmounts(direction, amount, market, inputAssetType = 'quote', mmOraclePriceData, useSpread = true, latestSlot) {
     if (amount.eq(numericConstants_1.ZERO)) {
@@ -121,24 +125,26 @@ function calculateTradeAcquiredAmounts(direction, amount, market, inputAssetType
 }
 exports.calculateTradeAcquiredAmounts = calculateTradeAcquiredAmounts;
 /**
- * calculateTargetPriceTrade
- * simple function for finding arbitraging trades
- *
- * @deprecated
+ * Calculates the AMM-only trade (direction + size) required to push the market's reserve price
+ * to (or `pct` of the way to) `targetPrice` — a simple arbitrage-sizing helper.
  *
- * @param market
- * @param targetPrice
- * @param pct optional default is 100% gap filling, can set smaller.
- * @param outputAssetType which asset to trade.
- * @param useSpread whether or not to consider the spread when calculating the trade size
- * @returns trade direction/size in order to push price to a targetPrice,
+ * @deprecated No longer actively maintained; ignores DLOB liquidity.
  *
- * [
- *   direction => direction of trade required, PositionDirection
- *   tradeSize => size of trade required, TODO-PRECISION
- *   entryPrice => the entry price for the trade, PRICE_PRECISION
- *   targetPrice => the target price PRICE_PRECISION
- * ]
+ * @param {PerpMarketAccount} market - The perp market account
+ * @param {BN} targetPrice - The price to arbitrage toward, PRICE_PRECISION (1e6)
+ * @param {BN} [pct] - Fraction of the full price gap to close, out of `MAXPCT` (1000 = 100%);
+ *   defaults to fully closing the gap
+ * @param {AssetType} [outputAssetType] - Whether the returned trade size is denominated in base
+ *   or quote; defaults to `'quote'`
+ * @param {MMOraclePriceData} [mmOraclePriceData] - MM oracle price data used for spread reserve calc
+ * @param {boolean} [useSpread] - Whether to consider the bid/ask spread when sizing the trade;
+ *   defaults to `true`. If `targetPrice` already sits within the current bid/ask spread, returns
+ *   a zero-size trade
+ * @param {BN} [latestSlot] - Slot used for spread-reserve staleness/decay calc when `useSpread` is true
+ * @return {[PositionDirection, BN, BN, BN]} `[direction, tradeSize, entryPrice, targetPrice]` —
+ *   `direction` required to move price toward `targetPrice`; `tradeSize` in `outputAssetType`
+ *   units (base: BASE_PRECISION (1e9); quote: QUOTE_PRECISION (1e6)); `entryPrice`/`targetPrice`
+ *   PRICE_PRECISION (1e6)
  */
 function calculateTargetPriceTrade(market, targetPrice, pct = MAXPCT, outputAssetType = 'quote', mmOraclePriceData, useSpread = true, latestSlot) {
     (0, assert_1.assert)(market.amm.baseAssetReserve.gt(numericConstants_1.ZERO));
@@ -254,17 +260,29 @@ function calculateTargetPriceTrade(market, targetPrice, pct = MAXPCT, outputAsse
 }
 exports.calculateTargetPriceTrade = calculateTargetPriceTrade;
 /**
- * Calculates the estimated entry price and price impact of order, in base or quote
- * Price impact is based on the difference between the entry price and the best bid/ask price (whether it's dlob or vamm)
+ * Simulates walking the combined DLOB + vAMM liquidity to estimate the entry price and price
+ * impact of a hypothetical taker order, filling against resting limit orders and the AMM's
+ * spread-adjusted reserves in whichever is cheaper at each step. Price impact is the difference
+ * between the estimated entry price and the best available price (top of book/AMM) before any
+ * fill.
  *
- * @param assetType
- * @param amount
- * @param direction
- * @param market
- * @param oraclePriceData
- * @param dlob
- * @param slot
- * @param usersToSkip
+ * @param {AssetType} assetType - Whether `amount` denominates base or quote
+ * @param {BN} amount - Order size, `assetType === 'base'`: BASE_PRECISION (1e9); `'quote'`: QUOTE_PRECISION (1e6)
+ * @param {PositionDirection} direction - Taker's trade direction
+ * @param {PerpMarketAccount} market - The perp market account
+ * @param {MMOraclePriceData} mmOraclePriceData - MM oracle price data used to price both the DLOB
+ *   resting orders and the AMM's spread-adjusted reserves
+ * @param {DLOB} dlob - The order book to walk for resting limit orders
+ * @param {number} slot - Current slot, used to resolve oracle-pegged/auction limit order prices
+ * @param {Map<PublicKey, boolean>} [usersToSkip] - Maker user accounts to exclude from the fill
+ *   simulation (e.g. the taker's own resting orders); defaults to none
+ * @return {{ entryPrice: BN; priceImpact: BN; bestPrice: BN; worstPrice: BN; baseFilled: BN;
+ *   quoteFilled: BN }} `entryPrice`/`bestPrice`/`worstPrice` are PRICE_PRECISION (1e6);
+ *   `priceImpact` is `|entryPrice - bestPrice| / bestPrice`, also scaled by PRICE_PRECISION
+ *   (1e6) but represents a ratio, not a price (e.g. `1e4` = 1% impact); `baseFilled` is
+ *   BASE_PRECISION (1e9); `quoteFilled` is QUOTE_PRECISION (1e6). All-zero only if `amount` is
+ *   zero; if liquidity runs out before `amount` fully fills, the returned fields reflect the
+ *   partial fill
  */
 function calculateEstimatedPerpEntryPrice(assetType, amount, direction, market, mmOraclePriceData, dlob, slot, usersToSkip = new Map()) {
     if (amount.eq(numericConstants_1.ZERO)) {
@@ -278,7 +296,7 @@ function calculateEstimatedPerpEntryPrice(assetType, amount, direction, market,
         };
     }
     const takerIsLong = (0, types_2.isVariant)(direction, 'long');
-    const limitOrders = dlob[takerIsLong ? 'getRestingLimitAsks' : 'getRestingLimitBids'](market.marketIndex, slot, types_1.MarketType.PERP, mmOraclePriceData);
+    const limitOrders = dlob[takerIsLong ? 'getRestingLimitAsks' : 'getRestingLimitBids'](market.marketIndex, slot, types_1.MarketType.PERP, mmOraclePriceData, undefined, market.orderTickSize);
     const swapDirection = (0, amm_1.getSwapDirection)(assetType, direction);
     const { baseAssetReserve, quoteAssetReserve, sqrtK, newPeg } = (0, amm_1.calculateUpdatedAMMSpreadReserves)(market.amm, market.marketStats, direction, mmOraclePriceData, new anchor_1.BN(slot));
     const amm = {
@@ -302,7 +320,7 @@ function calculateEstimatedPerpEntryPrice(assetType, amount, direction, market,
     let cumulativeQuoteFilled = numericConstants_1.ZERO;
     let limitOrder = limitOrders.next().value;
     if (limitOrder) {
-        const limitOrderPrice = limitOrder.getPriceOrThrow(mmOraclePriceData, slot);
+        const limitOrderPrice = limitOrder.getPriceOrThrow(mmOraclePriceData, slot, market.orderTickSize);
         bestPrice = takerIsLong
             ? anchor_1.BN.min(limitOrderPrice, bestPrice)
             : anchor_1.BN.max(limitOrderPrice, bestPrice);
@@ -311,7 +329,7 @@ function calculateEstimatedPerpEntryPrice(assetType, amount, direction, market,
     if (assetType === 'base') {
         while (!cumulativeBaseFilled.eq(amount) &&
             (ammLiquidity.gt(numericConstants_1.ZERO) || limitOrder)) {
-            const limitOrderPrice = limitOrder === null || limitOrder === void 0 ? void 0 : limitOrder.getPrice(mmOraclePriceData, slot);
+            const limitOrderPrice = limitOrder === null || limitOrder === void 0 ? void 0 : limitOrder.getPrice(mmOraclePriceData, slot, market.orderTickSize);
             let maxAmmFill;
             if (limitOrderPrice) {
                 const newBaseReserves = (0, utils_1.squareRootBN)(invariant
@@ -362,7 +380,7 @@ function calculateEstimatedPerpEntryPrice(assetType, amount, direction, market,
     else {
         while (!cumulativeQuoteFilled.eq(amount) &&
             (ammLiquidity.gt(numericConstants_1.ZERO) || limitOrder)) {
-            const limitOrderPrice = limitOrder === null || limitOrder === void 0 ? void 0 : limitOrder.getPrice(mmOraclePriceData, slot);
+            const limitOrderPrice = limitOrder === null || limitOrder === void 0 ? void 0 : limitOrder.getPrice(mmOraclePriceData, slot, market.orderTickSize);
             let maxAmmFill;
             if (limitOrderPrice) {
                 const newQuoteReserves = (0, utils_1.squareRootBN)(invariant
@@ -431,6 +449,23 @@ function calculateEstimatedPerpEntryPrice(assetType, amount, direction, market,
     };
 }
 exports.calculateEstimatedPerpEntryPrice = calculateEstimatedPerpEntryPrice;
+/**
+ * Estimates entry price and price impact of a hypothetical taker order by walking a pre-built L2
+ * order book snapshot (asks for a long taker, bids for a short taker), rather than the live DLOB.
+ * Useful when an L2 snapshot is already available and a fresh DLOB walk isn't needed.
+ *
+ * @param {AssetType} assetType - Whether `amount` denominates base or quote
+ * @param {BN} amount - Order size, `basePrecision` for `'base'`; QUOTE_PRECISION (1e6) for `'quote'`
+ * @param {PositionDirection} direction - Taker's trade direction
+ * @param {BN} basePrecision - The base precision to use for size/price math (e.g. `BASE_PRECISION`)
+ * @param {L2OrderBook} l2 - Pre-computed L2 order book (bids/asks with price + size levels)
+ * @return {{ entryPrice: BN; priceImpact: BN; bestPrice: BN; worstPrice: BN; baseFilled: BN;
+ *   quoteFilled: BN }} `entryPrice`/`bestPrice`/`worstPrice` are PRICE_PRECISION (1e6);
+ *   `priceImpact` is `|entryPrice - bestPrice| / bestPrice` scaled by PRICE_PRECISION (1e6);
+ *   `baseFilled` is `basePrecision`-scaled; `quoteFilled` is QUOTE_PRECISION (1e6). If the book
+ *   is empty, `bestPrice`/`worstPrice` are `BN_MAX` (long) or `ZERO` (short) and `entryPrice`/
+ *   `priceImpact` are `ZERO`
+ */
 function calculateEstimatedEntryPriceWithL2(assetType, amount, direction, basePrecision, l2) {
     const takerIsLong = (0, types_2.isVariant)(direction, 'long');
     let cumulativeBaseFilled = numericConstants_1.ZERO;
@@ -487,6 +522,17 @@ function calculateEstimatedEntryPriceWithL2(assetType, amount, direction, basePr
     };
 }
 exports.calculateEstimatedEntryPriceWithL2 = calculateEstimatedEntryPriceWithL2;
+/**
+ * Estimates a user's trailing-30-day taker + maker volume as of `now`, using the same
+ * time-weighted decay shape as the on-chain `update_taker_volume_30d` / `update_maker_volume_30d`
+ * (`calculate_rolling_sum`) but without requiring a new fill to trigger the on-chain update —
+ * useful for e.g. displaying live fee-tier progress between actual `UserStats` refreshes.
+ *
+ * @param {UserStatsAccount} userStatsAccount - The user's stats account (`takerVolume30D`,
+ *   `makerVolume30D`, and their respective last-update timestamps)
+ * @param {BN} [now] - Current unix timestamp (seconds); defaults to `Date.now() / 1000`
+ * @return {BN} Estimated combined 30-day taker + maker volume, QUOTE_PRECISION (1e6)
+ */
 function getUser30dRollingVolumeEstimate(userStatsAccount, now) {
     now = now || new anchor_1.BN(new Date().getTime() / 1000);
     const sinceLastTaker = anchor_1.BN.max(now.sub(userStatsAccount.lastTakerVolume30DTs), numericConstants_1.ZERO);

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

@@ -1,22 +1,84 @@
 import { BN } from '../isomorphic/anchor';
+/**
+ * Clamps `x` to the inclusive range `[min, max]`.
+ *
+ * @param {BN} x - The value to clamp
+ * @param {BN} min - The lower bound
+ * @param {BN} max - The upper bound
+ * @return {BN} `x` if within range, otherwise `min` or `max`
+ */
 export declare function clampBN(x: BN, min: BN, max: BN): BN;
+/**
+ * Integer square root via binary recursion, floored to the nearest integer (i.e.
+ * `squareRootBN(n) === Math.floor(Math.sqrt(n))` for values representable as a double). Used
+ * throughout the AMM math wherever the program takes an integer sqrt of the constant-product
+ * invariant.
+ *
+ * @param {BN} n - A non-negative integer
+ * @return {BN} `floor(sqrt(n))`
+ * @throws {Error} If `n` is negative
+ */
 export declare const squareRootBN: (n: BN) => BN;
+/**
+ * Integer division rounded up (ceiling), mirroring the program's unsigned `safe_div_ceil` (e.g.
+ * used for borrow token amounts, where rounding up favors the protocol/lenders over the
+ * borrower). Only meaningful for non-negative operands — `bn.js`'s `.mod()` returns a remainder
+ * with the sign of the dividend, so this is not a general-purpose ceiling division for signed
+ * inputs.
+ *
+ * @param {BN} a - The dividend (expected non-negative)
+ * @param {BN} b - The divisor (expected positive)
+ * @return {BN} `ceil(a / b)`
+ */
 export declare const divCeil: (a: BN, b: BN) => BN;
+/**
+ * Sign function returning ±1 (never 0).
+ *
+ * @param {BN} x - The value to test
+ * @return {BN} `-1` if `x` is negative, otherwise `1` (including for zero)
+ */
 export declare const sigNum: (x: BN) => BN;
 /**
- * calculates the time remaining until the next update based on a rounded, "on-the-hour" update schedule
- * this schedule is used for Perpetual Funding Rate and Revenue -> Insurance Updates
- * @param now: current blockchain unix timestamp
- * @param lastUpdateTs: the unix timestamp of the last update
- * @param updatePeriod: desired interval between updates (in seconds)
- * @returns: timeRemainingUntilUpdate (in seconds)
+ * Calculates the time remaining until the next update is eligible under a rounded, "on-the-hour"
+ * update schedule. Used for perp funding rate updates and revenue-to-insurance-fund sweeps: if the
+ * last update landed within 1/3 of `updatePeriod` of an hour boundary, the next update is allowed
+ * on that boundary; otherwise it's pushed to the following boundary (two periods out) to avoid
+ * drifting the schedule off-hour. Returns zero once the wait has already elapsed.
+ *
+ * @param {BN} now - Current unix timestamp, seconds
+ * @param {BN} lastUpdateTs - Unix timestamp of the last update, seconds
+ * @param {BN} updatePeriod - Desired interval between updates, seconds
+ * @return {BN} Seconds remaining until the next update is eligible (zero if already due)
  */
 export declare function timeRemainingUntilUpdate(now: BN, lastUpdateTs: BN, updatePeriod: BN): BN;
+/**
+ * Compares two date strings for equality by calendar day (year/month/date), ignoring
+ * time-of-day. Uses the local `getDate()`/`getMonth()`/`getFullYear()` getters, so the
+ * comparison is against the process's local-timezone calendar day (not UTC).
+ *
+ * @param {string} dateString1 - A date string parseable by `new Date()`
+ * @param {string} dateString2 - A date string parseable by `new Date()`
+ * @return {boolean} Whether both parse to the same calendar day
+ */
 export declare const checkSameDate: (dateString1: string, dateString2: string) => boolean;
+/**
+ * True if `number` is within `Number.MAX_SAFE_INTEGER` (2^53 - 1), i.e. safe to convert to a
+ * `BN` via a JS `number` without losing precision.
+ *
+ * @param {number} number - The value to check (typically already multiplied by a target precision)
+ * @return {boolean} Whether `number` can be represented exactly as a JS number
+ */
 export declare function isBNSafe(number: number): boolean;
 /**
- * Converts a number to BN makes sure the number is safe to convert to BN (that it does not overflow number after multiplying by precision)
- * @param number the number to convert to BN
- * @param precision the BN precision to use (i.e. QUOTE_PRECISION and BASE_PRECISION from velocity sdk)
+ * Converts a human-readable JS `number` into a `BN` scaled by `precision`, routing through a
+ * string conversion (`number.toString()` for whole numbers) instead of `number * precision` when
+ * the naive multiplication would exceed `Number.MAX_SAFE_INTEGER` (per `isBNSafe`), avoiding
+ * silent floating-point precision loss for large inputs. Note a fractional input whose scaled
+ * value exceeds `Number.MAX_SAFE_INTEGER` has its fractional part truncated (`bn.js` accepts only
+ * integer numbers); this is intentional and pinned by `tests/bn/test.ts`.
+ *
+ * @param {number} number - The human-readable amount to convert
+ * @param {BN} precision - The target fixed-point precision (e.g. `QUOTE_PRECISION`, `BASE_PRECISION`)
+ * @return {BN} `number` scaled by `precision`
  */
 export declare function numberToSafeBN(number: number, precision: BN): BN;

package/lib/browser/math/utils.js

@@ -3,10 +3,28 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.numberToSafeBN = exports.isBNSafe = exports.checkSameDate = exports.timeRemainingUntilUpdate = exports.sigNum = exports.divCeil = exports.squareRootBN = exports.clampBN = void 0;
 const anchor_1 = require("../isomorphic/anchor");
 const numericConstants_1 = require("../constants/numericConstants");
+/**
+ * Clamps `x` to the inclusive range `[min, max]`.
+ *
+ * @param {BN} x - The value to clamp
+ * @param {BN} min - The lower bound
+ * @param {BN} max - The upper bound
+ * @return {BN} `x` if within range, otherwise `min` or `max`
+ */
 function clampBN(x, min, max) {
     return anchor_1.BN.max(min, anchor_1.BN.min(x, max));
 }
 exports.clampBN = clampBN;
+/**
+ * Integer square root via binary recursion, floored to the nearest integer (i.e.
+ * `squareRootBN(n) === Math.floor(Math.sqrt(n))` for values representable as a double). Used
+ * throughout the AMM math wherever the program takes an integer sqrt of the constant-product
+ * invariant.
+ *
+ * @param {BN} n - A non-negative integer
+ * @return {BN} `floor(sqrt(n))`
+ * @throws {Error} If `n` is negative
+ */
 const squareRootBN = (n) => {
     if (n.lt(new anchor_1.BN(0))) {
         throw new Error('Sqrt only works on non-negtiave inputs');
@@ -24,6 +42,17 @@ const squareRootBN = (n) => {
     }
 };
 exports.squareRootBN = squareRootBN;
+/**
+ * Integer division rounded up (ceiling), mirroring the program's unsigned `safe_div_ceil` (e.g.
+ * used for borrow token amounts, where rounding up favors the protocol/lenders over the
+ * borrower). Only meaningful for non-negative operands — `bn.js`'s `.mod()` returns a remainder
+ * with the sign of the dividend, so this is not a general-purpose ceiling division for signed
+ * inputs.
+ *
+ * @param {BN} a - The dividend (expected non-negative)
+ * @param {BN} b - The divisor (expected positive)
+ * @return {BN} `ceil(a / b)`
+ */
 const divCeil = (a, b) => {
     const quotient = a.div(b);
     const remainder = a.mod(b);
@@ -35,17 +64,27 @@ const divCeil = (a, b) => {
     }
 };
 exports.divCeil = divCeil;
+/**
+ * Sign function returning ±1 (never 0).
+ *
+ * @param {BN} x - The value to test
+ * @return {BN} `-1` if `x` is negative, otherwise `1` (including for zero)
+ */
 const sigNum = (x) => {
     return x.isNeg() ? new anchor_1.BN(-1) : new anchor_1.BN(1);
 };
 exports.sigNum = sigNum;
 /**
- * calculates the time remaining until the next update based on a rounded, "on-the-hour" update schedule
- * this schedule is used for Perpetual Funding Rate and Revenue -> Insurance Updates
- * @param now: current blockchain unix timestamp
- * @param lastUpdateTs: the unix timestamp of the last update
- * @param updatePeriod: desired interval between updates (in seconds)
- * @returns: timeRemainingUntilUpdate (in seconds)
+ * Calculates the time remaining until the next update is eligible under a rounded, "on-the-hour"
+ * update schedule. Used for perp funding rate updates and revenue-to-insurance-fund sweeps: if the
+ * last update landed within 1/3 of `updatePeriod` of an hour boundary, the next update is allowed
+ * on that boundary; otherwise it's pushed to the following boundary (two periods out) to avoid
+ * drifting the schedule off-hour. Returns zero once the wait has already elapsed.
+ *
+ * @param {BN} now - Current unix timestamp, seconds
+ * @param {BN} lastUpdateTs - Unix timestamp of the last update, seconds
+ * @param {BN} updatePeriod - Desired interval between updates, seconds
+ * @return {BN} Seconds remaining until the next update is eligible (zero if already due)
  */
 function timeRemainingUntilUpdate(now, lastUpdateTs, updatePeriod) {
     const timeSinceLastUpdate = now.sub(lastUpdateTs);
@@ -77,6 +116,15 @@ function timeRemainingUntilUpdate(now, lastUpdateTs, updatePeriod) {
     return timeRemainingUntilUpdate;
 }
 exports.timeRemainingUntilUpdate = timeRemainingUntilUpdate;
+/**
+ * Compares two date strings for equality by calendar day (year/month/date), ignoring
+ * time-of-day. Uses the local `getDate()`/`getMonth()`/`getFullYear()` getters, so the
+ * comparison is against the process's local-timezone calendar day (not UTC).
+ *
+ * @param {string} dateString1 - A date string parseable by `new Date()`
+ * @param {string} dateString2 - A date string parseable by `new Date()`
+ * @return {boolean} Whether both parse to the same calendar day
+ */
 const checkSameDate = (dateString1, dateString2) => {
     const date1 = new Date(dateString1);
     const date2 = new Date(dateString2);
@@ -86,14 +134,28 @@ const checkSameDate = (dateString1, dateString2) => {
     return isSameDate;
 };
 exports.checkSameDate = checkSameDate;
+/**
+ * True if `number` is within `Number.MAX_SAFE_INTEGER` (2^53 - 1), i.e. safe to convert to a
+ * `BN` via a JS `number` without losing precision.
+ *
+ * @param {number} number - The value to check (typically already multiplied by a target precision)
+ * @return {boolean} Whether `number` can be represented exactly as a JS number
+ */
 function isBNSafe(number) {
     return number <= 0x1fffffffffffff;
 }
 exports.isBNSafe = isBNSafe;
 /**
- * Converts a number to BN makes sure the number is safe to convert to BN (that it does not overflow number after multiplying by precision)
- * @param number the number to convert to BN
- * @param precision the BN precision to use (i.e. QUOTE_PRECISION and BASE_PRECISION from velocity sdk)
+ * Converts a human-readable JS `number` into a `BN` scaled by `precision`, routing through a
+ * string conversion (`number.toString()` for whole numbers) instead of `number * precision` when
+ * the naive multiplication would exceed `Number.MAX_SAFE_INTEGER` (per `isBNSafe`), avoiding
+ * silent floating-point precision loss for large inputs. Note a fractional input whose scaled
+ * value exceeds `Number.MAX_SAFE_INTEGER` has its fractional part truncated (`bn.js` accepts only
+ * integer numbers); this is intentional and pinned by `tests/bn/test.ts`.
+ *
+ * @param {number} number - The human-readable amount to convert
+ * @param {BN} precision - The target fixed-point precision (e.g. `QUOTE_PRECISION`, `BASE_PRECISION`)
+ * @return {BN} `number` scaled by `precision`
  */
 function numberToSafeBN(number, precision) {
     // check if number has decimals

package/lib/browser/memcmp.d.ts

@@ -1,17 +1,111 @@
 import { MemcmpFilter, PublicKey } from '@solana/web3.js';
+/**
+ * Builds a `getProgramAccounts` memcmp filter matching the 8-byte Anchor discriminator of the
+ * `User` account type at offset 0. Use to fetch all `User` (sub-account) accounts.
+ * @returns A memcmp filter for `User` accounts.
+ */
 export declare function getUserFilter(): MemcmpFilter;
+/**
+ * Builds a memcmp filter matching `User` accounts whose `idle` flag (offset 4470) is `false`.
+ * Idle sub-accounts have no open positions/orders and have been inactive past the idle threshold;
+ * this filter excludes them, e.g. when scanning for accounts that need active monitoring.
+ * @returns A memcmp filter for non-idle `User` accounts.
+ */
 export declare function getNonIdleUserFilter(): MemcmpFilter;
+/**
+ * Builds a memcmp filter matching `User` accounts with `hasOpenOrder` (offset 4472) set to `true`
+ * — i.e. at least one live order. Used by the DLOB to fetch only accounts that can populate the
+ * order book.
+ * @returns A memcmp filter for `User` accounts with at least one open order.
+ */
 export declare function getUserWithOrderFilter(): MemcmpFilter;
+/**
+ * Builds a memcmp filter matching `User` accounts with `hasOpenOrder` (offset 4472) set to `false`
+ * — i.e. no live orders.
+ * @returns A memcmp filter for `User` accounts with no open orders.
+ */
 export declare function getUserWithoutOrderFilter(): MemcmpFilter;
+/**
+ * Builds a memcmp filter matching `User` accounts with `hasOpenAuction` (offset 4474) set to
+ * `true` — i.e. at least one order still in its Dutch-auction window.
+ * @returns A memcmp filter for `User` accounts with an active order auction.
+ */
 export declare function getUserWithAuctionFilter(): MemcmpFilter;
+/**
+ * Builds a memcmp filter matching `User` accounts whose `name` field (32 bytes, offset 72) equals
+ * `name` once encoded/padded the same way as on-chain.
+ * @param name - Human-readable sub-account name to match; encoded via `encodeName` (UTF-8,
+ * space-padded/truncated to 32 bytes) before comparison.
+ * @returns A memcmp filter for `User` accounts with the given name.
+ */
 export declare function getUserWithName(name: string): MemcmpFilter;
+/**
+ * Builds a memcmp filter matching `User` accounts whose `poolId` (single byte, offset 4475) equals
+ * `poolId`. Used to scope account scans to a specific isolated pool.
+ * @param poolId - Pool id byte (0 = main/cross pool) to match.
+ * @returns A memcmp filter for `User` accounts in the given pool.
+ */
 export declare function getUsersWithPoolId(poolId: number): MemcmpFilter;
+/**
+ * Builds a `getProgramAccounts` memcmp filter matching the 8-byte Anchor discriminator of the
+ * `UserStats` account type at offset 0. Use to fetch all `UserStats` accounts.
+ * @returns A memcmp filter for `UserStats` accounts.
+ */
 export declare function getUserStatsFilter(): MemcmpFilter;
+/**
+ * Builds a memcmp filter matching `UserStats` accounts whose `referrerStatus` bitflag byte (offset
+ * 164) is exactly `ReferrerStatus.IsReferred` (2) — i.e. the account was referred and is *not*
+ * also flagged `IsReferrer`. Because memcmp does an exact byte match rather than a bitwise test,
+ * this excludes accounts that are both `IsReferrer` and `IsReferred` (byte value 3); use
+ * `getUserStatsIsReferredOrReferrerFilter` for that combined case.
+ * @returns A memcmp filter for `UserStats` accounts referred by (but not also referring) another user.
+ */
 export declare function getUserStatsIsReferredFilter(): MemcmpFilter;
+/**
+ * Builds a memcmp filter matching `UserStats` accounts whose `referrerStatus` bitflag byte (offset
+ * 164) is exactly 3 — i.e. `ReferrerStatus.IsReferrer | ReferrerStatus.IsReferred` both set on the
+ * same account. Despite the name, this is an exact-byte match (memcmp can't test bits in
+ * isolation), so it does *not* match an account that is only `IsReferrer` (1) or only `IsReferred`
+ * (2) — use `getUserStatsIsReferredFilter` for the referred-only case.
+ * @returns A memcmp filter for `UserStats` accounts with both the referrer and referred flags set.
+ */
 export declare function getUserStatsIsReferredOrReferrerFilter(): MemcmpFilter;
+/**
+ * Builds a `getProgramAccounts` memcmp filter matching the 8-byte Anchor discriminator of the
+ * `SignedMsgUserOrders` account type at offset 0. Use to fetch all swift/signed-message order
+ * accounts.
+ * @returns A memcmp filter for `SignedMsgUserOrders` accounts.
+ */
 export declare function getSignedMsgUserOrdersFilter(): MemcmpFilter;
+/**
+ * Builds a `getProgramAccounts` memcmp filter matching the 8-byte Anchor discriminator of the
+ * `PerpMarket` account type at offset 0. Use to fetch all perp market accounts.
+ * @returns A memcmp filter for `PerpMarket` accounts.
+ */
 export declare function getPerpMarketAccountsFilter(): MemcmpFilter;
+/**
+ * Builds a `getProgramAccounts` memcmp filter matching the 8-byte Anchor discriminator of the
+ * `SpotMarket` account type at offset 0. Use to fetch all spot market accounts.
+ * @returns A memcmp filter for `SpotMarket` accounts.
+ */
 export declare function getSpotMarketAccountsFilter(): MemcmpFilter;
+/**
+ * Builds a `getProgramAccounts` memcmp filter matching the 8-byte Anchor discriminator of the
+ * `RevenueShareEscrow` account type at offset 0. Use to fetch all revenue-share escrow accounts
+ * (builder-fee approvals/referral state).
+ * @returns A memcmp filter for `RevenueShareEscrow` accounts.
+ */
 export declare function getRevenueShareEscrowFilter(): MemcmpFilter;
+/**
+ * Builds a `getProgramAccounts` memcmp filter matching the 8-byte Anchor discriminator of the
+ * `Constituent` account type at offset 0. Use to fetch all LP-pool constituent accounts.
+ * @returns A memcmp filter for `Constituent` accounts.
+ */
 export declare function getConstituentFilter(): MemcmpFilter;
+/**
+ * Builds a memcmp filter matching `Constituent` accounts belonging to a specific LP pool, by
+ * comparing the `lpPool` pubkey field (32 bytes, offset 72) against `lpPoolPublicKey`.
+ * @param lpPoolPublicKey - The `LpPool` account's pubkey to match constituents against.
+ * @returns A memcmp filter for `Constituent` accounts of the given LP pool.
+ */
 export declare function getConstituentLpPoolFilter(lpPoolPublicKey: PublicKey): MemcmpFilter;