@velocity-exchange/sdk 0.2.5 → 0.4.0

package/src/math/superStake.ts

@@ -14,6 +14,7 @@ import { LAMPORTS_PRECISION, ZERO } from '../constants/numericConstants';
 import fetch from 'node-fetch';
 import { checkSameDate } from './utils';
 
+/** Response shape of SolBlaze's `bsol/stats` endpoint (bSOL conversion ratio + APY breakdown). */
 export type BSOL_STATS_API_RESPONSE = {
 	success: boolean;
 	stats?: {
@@ -31,6 +32,7 @@ export type BSOL_STATS_API_RESPONSE = {
 	};
 };
 
+/** Response shape of SolBlaze's Velocity-specific lending emissions endpoint. */
 export type BSOL_EMISSIONS_API_RESPONSE = {
 	success: boolean;
 	emissions?: {
@@ -38,14 +40,52 @@ export type BSOL_EMISSIONS_API_RESPONSE = {
 	};
 };
 
+/**
+ * Fetches bSOL conversion/APY stats from SolBlaze's public API.
+ *
+ * @return {Promise<Response>} The raw `fetch` response; caller must check `.status` and parse
+ *   JSON as `BSOL_STATS_API_RESPONSE`
+ */
 export async function fetchBSolMetrics() {
 	return await fetch('https://stake.solblaze.org/api/v1/stats');
 }
 
+/**
+ * Fetches bSOL lending-emissions data specific to Velocity from SolBlaze's public API.
+ *
+ * @return {Promise<Response>} The raw `fetch` response; caller must check `.status` and parse
+ *   JSON as `BSOL_EMISSIONS_API_RESPONSE`
+ */
 export async function fetchBSolVelocityEmissions() {
 	return await fetch('https://stake.solblaze.org/api/v1/velocity_emissions');
 }
 
+/**
+ * Dispatches to the correct "super-stake" (deposit SOL, swap to an LST, deposit the LST as
+ * leveraged collateral) instruction builder for a given LST spot market, routing by the SDK's
+ * hardcoded market-index constants: `2` (mSOL) uses Marinade-or-Jupiter (`findBestMSolSuperStakeIxs`),
+ * `6` (JitoSOL) and `8` (a generic LST, e.g. bSOL) both use Jupiter-only routing.
+ *
+ * @param {object} params
+ * @param {number} params.marketIndex - The LST spot market index; must be `2`, `6`, or `8`
+ * @param {BN} params.amount - SOL amount to stake, `LAMPORTS_PRECISION` (1e9)
+ * @param {JupiterClient} params.jupiterClient - Jupiter aggregator client for swap routing
+ * @param {VelocityClient} params.velocityClient - Velocity client (for market accounts + instruction building)
+ * @param {PublicKey} [params.userAccountPublicKey] - The target sub-account; defaults to the
+ *   client's active sub-account if omitted
+ * @param {number} [params.price] - Pre-fetched mSOL/SOL price (market index 2 only); fetched from
+ *   Marinade if omitted
+ * @param {boolean} [params.forceMarinade] - Force the direct Marinade stake path over a Jupiter
+ *   swap even if Jupiter would be cheaper (market index 2 only)
+ * @param {boolean} [params.onlyDirectRoutes] - Restrict Jupiter routing to direct swaps only
+ * @param {QuoteResponse} [params.jupiterQuote] - A pre-fetched Jupiter quote to reuse instead of
+ *   fetching a fresh one
+ * @return {Promise<{ ixs: TransactionInstruction[]; lookupTables: AddressLookupTableAccount[];
+ *   method: 'jupiter' | 'marinade'; price?: number }>} The instructions to submit, any address
+ *   lookup tables they require, which routing method was chosen, and (market index 2 only) the
+ *   price used for the routing decision
+ * @throws {Error} If `marketIndex` is not one of the supported LST markets
+ */
 export async function findBestSuperStakeIxs({
 	marketIndex,
 	amount,
@@ -108,6 +148,26 @@ export async function findBestSuperStakeIxs({
 	}
 }
 
+/**
+ * Chooses between staking SOL directly with Marinade (mint mSOL 1:1 at the protocol rate) or
+ * swapping SOL for mSOL via Jupiter, whichever is cheaper for the user, then returns the
+ * resulting deposit instructions. Marinade is chosen when its price is lower than (i.e. gives
+ * more mSOL per SOL than) the best Jupiter quote, when `forceMarinade` is set, or when a Jupiter
+ * quote couldn't be obtained.
+ *
+ * @param {object} params
+ * @param {BN} params.amount - SOL amount to stake, `LAMPORTS_PRECISION` (1e9)
+ * @param {JupiterClient} params.jupiterClient - Jupiter aggregator client
+ * @param {VelocityClient} params.velocityClient - Velocity client
+ * @param {number} [params.price] - Pre-fetched mSOL/SOL Marinade rate; fetched live if omitted
+ * @param {PublicKey} [params.userAccountPublicKey] - The target sub-account
+ * @param {boolean} [params.forceMarinade] - Force the Marinade path regardless of Jupiter pricing
+ * @param {boolean} [params.onlyDirectRoutes] - Restrict Jupiter routing to direct swaps only
+ * @param {QuoteResponse} [params.jupiterQuote] - A pre-fetched Jupiter quote to reuse
+ * @return {Promise<{ ixs: TransactionInstruction[]; lookupTables: AddressLookupTableAccount[];
+ *   method: 'jupiter' | 'marinade'; price: number }>} The chosen route's instructions, required
+ *   lookup tables, the method used, and the mSOL/SOL price used for the decision
+ */
 export async function findBestMSolSuperStakeIxs({
 	amount,
 	jupiterClient,
@@ -190,6 +250,20 @@ export async function findBestMSolSuperStakeIxs({
 	}
 }
 
+/**
+ * Builds instructions to super-stake into JitoSOL (spot market index `6`) by swapping SOL for
+ * JitoSOL via Jupiter. Thin wrapper around `findBestLstSuperStakeIxs`.
+ *
+ * @param {object} params
+ * @param {BN} params.amount - SOL amount to stake, `LAMPORTS_PRECISION` (1e9)
+ * @param {JupiterClient} params.jupiterClient - Jupiter aggregator client
+ * @param {VelocityClient} params.velocityClient - Velocity client
+ * @param {PublicKey} [params.userAccountPublicKey] - The target sub-account
+ * @param {boolean} [params.onlyDirectRoutes] - Restrict Jupiter routing to direct swaps only
+ * @param {QuoteResponse} [params.jupiterQuote] - A pre-fetched Jupiter quote to reuse
+ * @return {Promise<{ ixs: TransactionInstruction[]; lookupTables: AddressLookupTableAccount[];
+ *   method: 'jupiter' | 'marinade'; price?: number }>} Always resolves with `method: 'jupiter'`
+ */
 export async function findBestJitoSolSuperStakeIxs({
 	amount,
 	jupiterClient,
@@ -223,9 +297,22 @@ export async function findBestJitoSolSuperStakeIxs({
 }
 
 /**
- * Finds best swap instructions for a generic lstMint
+ * Builds instructions to super-stake into an arbitrary LST via a Jupiter swap from SOL. Unlike
+ * `findBestMSolSuperStakeIxs`, this does not compare against a direct-stake rate with the LST's
+ * own protocol — it always routes through Jupiter.
  *
- * Without doing any extra steps like checking if you can get a better rate by staking directly with that LST platform
+ * @param {object} params
+ * @param {BN} params.amount - SOL amount to stake, `LAMPORTS_PRECISION` (1e9)
+ * @param {PublicKey} params.lstMint - The target LST's mint (unused directly here; kept for
+ *   caller symmetry with `lstMarketIndex`)
+ * @param {number} params.lstMarketIndex - The target LST's spot market index
+ * @param {JupiterClient} params.jupiterClient - Jupiter aggregator client
+ * @param {VelocityClient} params.velocityClient - Velocity client
+ * @param {PublicKey} [params.userAccountPublicKey] - The target sub-account
+ * @param {boolean} [params.onlyDirectRoutes] - Restrict Jupiter routing to direct swaps only
+ * @param {QuoteResponse} [params.jupiterQuote] - A pre-fetched Jupiter quote to reuse
+ * @return {Promise<{ ixs: TransactionInstruction[]; lookupTables: AddressLookupTableAccount[];
+ *   method: 'jupiter' | 'marinade' }>} Always resolves with `method: 'jupiter'`
  */
 export async function findBestLstSuperStakeIxs({
 	amount,
@@ -266,6 +353,7 @@ export async function findBestLstSuperStakeIxs({
 	};
 }
 
+/** Response shape of Jito's `stake_pool_stats` endpoint: daily TVL, jitoSOL supply, and APY series. */
 export type JITO_SOL_METRICS_ENDPOINT_RESPONSE = {
 	tvl: {
 		// TVL in SOL, BN
@@ -299,6 +387,11 @@ const get30DAgo = () => {
 	return date;
 };
 
+/**
+ * Fetches daily jitoSOL TVL/supply/APY stats for the trailing 30 days from Jito's public API.
+ *
+ * @return {Promise<JITO_SOL_METRICS_ENDPOINT_RESPONSE>} The parsed JSON response
+ */
 export async function fetchJitoSolMetrics() {
 	const res = await fetch(
 		'https://kobe.mainnet.jito.network/api/v1/stake_pool_stats',
@@ -360,6 +453,22 @@ const getJitoSolHistoricalPriceMap = async (timestamps: number[]) => {
 	}
 };
 
+/**
+ * Estimates net SOL earned (or lost) from super-staking a given LST market over the user's full
+ * deposit history, by converting every historical SOL and LST deposit/withdrawal record to a SOL
+ * value at the LST/SOL ratio effective at that record's timestamp, then adding back the current
+ * SOL-value of the user's present SOL and LST balances. Requires third-party price history APIs
+ * per LST (Marinade for mSOL, Jito's stake pool stats for JitoSOL, SolBlaze's current-only rate
+ * for bSOL — bSOL therefore uses one flat ratio for all historical records, not a true history).
+ *
+ * @param {object} params
+ * @param {number} params.marketIndex - The LST spot market index (`2` mSOL, `6` JitoSOL, `8` bSOL)
+ * @param {User} params.user - The user account to read current SOL/LST balances from
+ * @param {DepositRecord[]} params.depositRecords - The user's historical deposit/withdraw records
+ *   across the SOL market (index `1`) and the LST market
+ * @return {Promise<BN>} Estimated net SOL earned, `LAMPORTS_PRECISION` (1e9); can be negative
+ * @throws {Error} If an LST/SOL ratio can't be resolved for a record's timestamp (or for "now")
+ */
 export async function calculateSolEarned({
 	marketIndex,
 	user,
@@ -463,7 +572,21 @@ export async function calculateSolEarned({
 	return solEarned;
 }
 
-// calculate estimated liquidation price (in LST/SOL) based on target amounts
+/**
+ * Estimates the LST/SOL price at which a super-staked (leveraged LST-collateral, SOL-borrow)
+ * position would hit maintenance margin and become liquidatable: the price where
+ * `lstMaintenanceAssetWeight * lstDepositAmount * price === solMaintenanceLiabilityWeight * solBorrowAmount`.
+ * All inputs are plain (unscaled) numbers, not `BN` — weights are expected as fractions (e.g.
+ * `0.8` for 80%, i.e. already divided by `SPOT_MARKET_WEIGHT_PRECISION`), and this is a
+ * float-precision estimate for UI display, not a program-exact calculation.
+ *
+ * @param {number} lstDepositAmount - LST collateral amount, in whole LST tokens
+ * @param {number} lstMaintenanceAssetWeight - The LST market's maintenance asset weight, as a fraction
+ * @param {number} solBorrowAmount - SOL borrow amount, in whole SOL
+ * @param {number} solMaintenanceLiabilityWeight - The SOL market's maintenance liability weight, as a fraction
+ * @param {number} lstPriceRatio - Current LST/SOL price ratio
+ * @return {number} Estimated liquidation LST/SOL price
+ */
 export function calculateEstimatedSuperStakeLiquidationPrice(
 	lstDepositAmount: number,
 	lstMaintenanceAssetWeight: number,

package/src/math/tiers.ts

@@ -1,5 +1,13 @@
 import { isVariant, PerpMarketAccount, SpotMarketAccount } from '../types';
 
+/**
+ * Maps a perp market's `contractTier` to an ordinal safety rank, lower is safer. Matches the
+ * declaration order of the Rust `ContractTier` enum (which derives `Ord` from declaration order,
+ * used by `ContractTier::is_as_safe_as_contract`'s `self <= other`).
+ *
+ * @param {PerpMarketAccount} perpMarket - The perp market account
+ * @return {number} `0` (A, safest) through `5` (Isolated, riskiest); `4` = HighlySpeculative
+ */
 export function getPerpMarketTierNumber(perpMarket: PerpMarketAccount): number {
 	if (isVariant(perpMarket.contractTier, 'a')) {
 		return 0;
@@ -16,6 +24,14 @@ export function getPerpMarketTierNumber(perpMarket: PerpMarketAccount): number {
 	}
 }
 
+/**
+ * Maps a spot market's `assetTier` to an ordinal safety rank, lower is safer. Matches the
+ * declaration order of the Rust `AssetTier` enum, used by `ContractTier::is_as_safe_as_asset`.
+ *
+ * @param {SpotMarketAccount} spotMarket - The spot market account
+ * @return {number} `0` (Collateral, safest) through `4` (Unlisted, riskiest); `5` is unreachable
+ *   (falls through only if `assetTier` matches none of the known variants)
+ */
 export function getSpotMarketTierNumber(spotMarket: SpotMarketAccount): number {
 	if (isVariant(spotMarket.assetTier, 'collateral')) {
 		return 0;
@@ -32,6 +48,19 @@ export function getSpotMarketTierNumber(spotMarket: SpotMarketAccount): number {
 	}
 }
 
+/**
+ * True if a perp market's tier is at least as safe as both a reference perp tier and a reference
+ * spot tier, mirroring `ContractTier::is_as_safe_as`. Used to gate cross-margining: a position in
+ * a market riskier than the account's other collateral/positions can force isolated margin.
+ * A perp tier is "as safe as" a spot tier if the spot tier is Unlisted (anything beats Unlisted);
+ * otherwise, if the spot tier is Cross or Isolated, the perp tier must be C-or-safer (tiers 0-2).
+ *
+ * @param {number} perpTier - This market's tier number, from `getPerpMarketTierNumber`
+ * @param {number} otherPerpTier - The reference perp tier number to compare against
+ * @param {number} otherSpotTier - The reference spot tier number to compare against, from
+ *   `getSpotMarketTierNumber`
+ * @return {boolean} Whether `perpTier` is as safe as both references
+ */
 export function perpTierIsAsSafeAs(
 	perpTier: number,
 	otherPerpTier: number,

package/src/math/trade.ts

@@ -37,6 +37,11 @@ import { L2OrderBook } from '../dlob/orderBookLevels';
 
 const MAXPCT = new BN(1000); //percentage units are [0,1000] => [0,1]
 
+/**
+ * Enumerates the price-impact-related fields historically produced by trade-slippage helpers.
+ * Not currently consumed as a parameter/return type by any function in this file — kept for
+ * backward compatibility with callers that reference it as a key type.
+ */
 export type PriceImpactUnit =
 	| 'entryPrice'
 	| 'maxPrice'
@@ -51,24 +56,23 @@ export type PriceImpactUnit =
 	| 'all';
 
 /**
- * Calculates avg/max slippage (price impact) for candidate trade
- *
- * @deprecated use calculateEstimatedPerpEntryPrice instead
- *
- * @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
+ * Calculates avg/max slippage (price impact) for a hypothetical AMM-only trade.
  *
- * 'entryPrice' => the average price of the trade : Precision PRICE_PRECISION
+ * @deprecated Use `calculateEstimatedPerpEntryPrice` instead (this ignores DLOB liquidity and
+ *   only swaps against the vAMM).
  *
- * '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
  */
 export function calculateTradeSlippage(
 	direction: PositionDirection,
@@ -155,15 +159,20 @@ export function 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)
  */
 export function calculateTradeAcquiredAmounts(
 	direction: PositionDirection,
@@ -215,24 +224,26 @@ export function 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)
  */
 export function calculateTargetPriceTrade(
 	market: PerpMarketAccount,
@@ -389,17 +400,29 @@ export function 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
  */
 export function calculateEstimatedPerpEntryPrice(
 	assetType: AssetType,
@@ -432,7 +455,14 @@ export function calculateEstimatedPerpEntryPrice(
 	const takerIsLong = isVariant(direction, 'long');
 	const limitOrders = dlob[
 		takerIsLong ? 'getRestingLimitAsks' : 'getRestingLimitBids'
-	](market.marketIndex, slot, MarketType.PERP, mmOraclePriceData);
+	](
+		market.marketIndex,
+		slot,
+		MarketType.PERP,
+		mmOraclePriceData,
+		undefined,
+		market.orderTickSize
+	);
 
 	const swapDirection = getSwapDirection(assetType, direction);
 
@@ -489,7 +519,11 @@ export function calculateEstimatedPerpEntryPrice(
 
 	let limitOrder = limitOrders.next().value;
 	if (limitOrder) {
-		const limitOrderPrice = limitOrder.getPriceOrThrow(mmOraclePriceData, slot);
+		const limitOrderPrice = limitOrder.getPriceOrThrow(
+			mmOraclePriceData,
+			slot,
+			market.orderTickSize
+		);
 		bestPrice = takerIsLong
 			? BN.min(limitOrderPrice, bestPrice)
 			: BN.max(limitOrderPrice, bestPrice);
@@ -502,7 +536,11 @@ export function calculateEstimatedPerpEntryPrice(
 			!cumulativeBaseFilled.eq(amount) &&
 			(ammLiquidity.gt(ZERO) || limitOrder)
 		) {
-			const limitOrderPrice = limitOrder?.getPrice(mmOraclePriceData, slot);
+			const limitOrderPrice = limitOrder?.getPrice(
+				mmOraclePriceData,
+				slot,
+				market.orderTickSize
+			);
 
 			let maxAmmFill: BN;
 			if (limitOrderPrice) {
@@ -586,7 +624,11 @@ export function calculateEstimatedPerpEntryPrice(
 			!cumulativeQuoteFilled.eq(amount) &&
 			(ammLiquidity.gt(ZERO) || limitOrder)
 		) {
-			const limitOrderPrice = limitOrder?.getPrice(mmOraclePriceData, slot);
+			const limitOrderPrice = limitOrder?.getPrice(
+				mmOraclePriceData,
+				slot,
+				market.orderTickSize
+			);
 
 			let maxAmmFill: BN;
 			if (limitOrderPrice) {
@@ -695,6 +737,23 @@ export function 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`
+ */
 export function calculateEstimatedEntryPriceWithL2(
 	assetType: AssetType,
 	amount: BN,
@@ -782,6 +841,17 @@ export function 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)
+ */
 export function getUser30dRollingVolumeEstimate(
 	userStatsAccount: UserStatsAccount,
 	now?: BN

package/src/math/utils.ts

@@ -1,10 +1,28 @@
 import { BN } from '../isomorphic/anchor';
 import { ONE, ZERO } from '../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`
+ */
 export function clampBN(x: BN, min: BN, max: BN): BN {
 	return BN.max(min, BN.min(x, max));
 }
 
+/**
+ * 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 const squareRootBN = (n: BN): BN => {
 	if (n.lt(new BN(0))) {
 		throw new Error('Sqrt only works on non-negtiave inputs');
@@ -23,6 +41,17 @@ export 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 const divCeil = (a: BN, b: BN): BN => {
 	const quotient = a.div(b);
 
@@ -35,17 +64,27 @@ export 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 const sigNum = (x: BN): BN => {
 	return x.isNeg() ? new BN(-1) : new BN(1);
 };
 
 /**
- * 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 function timeRemainingUntilUpdate(
 	now: BN,
@@ -85,6 +124,15 @@ export function timeRemainingUntilUpdate(
 	return 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
+ */
 export const checkSameDate = (dateString1: string, dateString2: string) => {
 	const date1 = new Date(dateString1);
 	const date2 = new Date(dateString2);
@@ -97,14 +145,28 @@ export const checkSameDate = (dateString1: string, dateString2: string) => {
 	return isSameDate;
 };
 
+/**
+ * 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 function isBNSafe(number: number): boolean {
 	return number <= 0x1fffffffffffff;
 }
 
 /**
- * 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 function numberToSafeBN(number: number, precision: BN): BN {
 	// check if number has decimals