@velocity-exchange/sdk 0.2.5 → 0.4.0

package/lib/browser/math/superStake.js

@@ -11,14 +11,52 @@ const types_1 = require("../types");
 const numericConstants_1 = require("../constants/numericConstants");
 const node_fetch_1 = __importDefault(require("node-fetch"));
 const utils_1 = require("./utils");
+/**
+ * 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`
+ */
 async function fetchBSolMetrics() {
     return await (0, node_fetch_1.default)('https://stake.solblaze.org/api/v1/stats');
 }
 exports.fetchBSolMetrics = fetchBSolMetrics;
+/**
+ * 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`
+ */
 async function fetchBSolVelocityEmissions() {
     return await (0, node_fetch_1.default)('https://stake.solblaze.org/api/v1/velocity_emissions');
 }
 exports.fetchBSolVelocityEmissions = fetchBSolVelocityEmissions;
+/**
+ * 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
+ */
 async function findBestSuperStakeIxs({ marketIndex, amount, jupiterClient, velocityClient, userAccountPublicKey, price, forceMarinade, onlyDirectRoutes, jupiterQuote, }) {
     if (marketIndex === 2) {
         return findBestMSolSuperStakeIxs({
@@ -59,6 +97,26 @@ async function findBestSuperStakeIxs({ marketIndex, amount, jupiterClient, veloc
     }
 }
 exports.findBestSuperStakeIxs = 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
+ */
 async function findBestMSolSuperStakeIxs({ amount, jupiterClient, velocityClient, userAccountPublicKey, price, forceMarinade, onlyDirectRoutes, jupiterQuote, }) {
     if (!price) {
         const marinadeProgram = (0, marinade_1.getMarinadeFinanceProgram)(velocityClient.provider);
@@ -115,6 +173,20 @@ async function findBestMSolSuperStakeIxs({ amount, jupiterClient, velocityClient
     }
 }
 exports.findBestMSolSuperStakeIxs = 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'`
+ */
 async function findBestJitoSolSuperStakeIxs({ amount, jupiterClient, velocityClient, userAccountPublicKey, onlyDirectRoutes, jupiterQuote, }) {
     return await findBestLstSuperStakeIxs({
         amount,
@@ -129,9 +201,22 @@ async function findBestJitoSolSuperStakeIxs({ amount, jupiterClient, velocityCli
 }
 exports.findBestJitoSolSuperStakeIxs = 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'`
  */
 async function findBestLstSuperStakeIxs({ amount, jupiterClient, velocityClient, userAccountPublicKey, onlyDirectRoutes, lstMarketIndex, jupiterQuote, }) {
     const { ixs, lookupTables } = await velocityClient.getJupiterSwapIxV6({
@@ -165,6 +250,11 @@ const get30DAgo = () => {
     const date = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
     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
+ */
 async function fetchJitoSolMetrics() {
     const res = await (0, node_fetch_1.default)('https://kobe.mainnet.jito.network/api/v1/stake_pool_stats', {
         headers: {
@@ -214,6 +304,22 @@ const getJitoSolHistoricalPriceMap = async (timestamps) => {
         return undefined;
     }
 };
+/**
+ * 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")
+ */
 async function calculateSolEarned({ marketIndex, user, depositRecords, }) {
     const now = Date.now() / 1000;
     const timestamps = [
@@ -299,7 +405,21 @@ async function calculateSolEarned({ marketIndex, user, depositRecords, }) {
     return solEarned;
 }
 exports.calculateSolEarned = calculateSolEarned;
-// 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
+ */
 function calculateEstimatedSuperStakeLiquidationPrice(lstDepositAmount, lstMaintenanceAssetWeight, solBorrowAmount, solMaintenanceLiabilityWeight, lstPriceRatio) {
     const liquidationDivergence = (solMaintenanceLiabilityWeight * solBorrowAmount) /
         (lstMaintenanceAssetWeight * lstDepositAmount * lstPriceRatio);

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

@@ -1,4 +1,33 @@
 import { 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 declare 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 declare 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 declare function perpTierIsAsSafeAs(perpTier: number, otherPerpTier: number, otherSpotTier: number): boolean;

package/lib/browser/math/tiers.js

@@ -2,6 +2,14 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.perpTierIsAsSafeAs = exports.getSpotMarketTierNumber = exports.getPerpMarketTierNumber = void 0;
 const types_1 = require("../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
+ */
 function getPerpMarketTierNumber(perpMarket) {
     if ((0, types_1.isVariant)(perpMarket.contractTier, 'a')) {
         return 0;
@@ -23,6 +31,14 @@ function getPerpMarketTierNumber(perpMarket) {
     }
 }
 exports.getPerpMarketTierNumber = getPerpMarketTierNumber;
+/**
+ * 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)
+ */
 function getSpotMarketTierNumber(spotMarket) {
     if ((0, types_1.isVariant)(spotMarket.assetTier, 'collateral')) {
         return 0;
@@ -44,6 +60,19 @@ function getSpotMarketTierNumber(spotMarket) {
     }
 }
 exports.getSpotMarketTierNumber = getSpotMarketTierNumber;
+/**
+ * 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
+ */
 function perpTierIsAsSafeAs(perpTier, otherPerpTier, otherSpotTier) {
     const asSafeAsPerp = perpTier <= otherPerpTier;
     const asSafeAsSpot = otherSpotTier === 4 || (otherSpotTier >= 2 && perpTier <= 2);

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

@@ -5,73 +5,96 @@ import { MMOraclePriceData } from '../oracles/types';
 import { DLOB } from '../dlob/DLOB';
 import { PublicKey } from '@solana/web3.js';
 import { L2OrderBook } from '../dlob/orderBookLevels';
+/**
+ * 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' | 'priceDelta' | 'priceDeltaAsNumber' | 'pctAvg' | 'pctMax' | 'quoteAssetAmount' | 'quoteAssetAmountPeg' | 'acquiredBaseAssetAmount' | 'acquiredQuoteAssetAmount' | '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]
+ * Calculates avg/max slippage (price impact) for a hypothetical AMM-only trade.
  *
- * 'pctAvgSlippage' =>  the percentage change to entryPrice (average est slippage in execution) : Precision PRICE_PRECISION
+ * @deprecated Use `calculateEstimatedPerpEntryPrice` instead (this ignores DLOB liquidity and
+ *   only swaps against the vAMM).
  *
- * '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
  */
 export declare function calculateTradeSlippage(direction: PositionDirection, amount: BN, market: PerpMarketAccount, inputAssetType: AssetType | undefined, mmOraclePriceData: MMOraclePriceData, useSpread?: boolean, latestSlot?: BN): [BN, BN, BN, BN];
 /**
- * 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 declare function calculateTradeAcquiredAmounts(direction: PositionDirection, amount: BN, market: PerpMarketAccount, inputAssetType: AssetType | undefined, mmOraclePriceData: MMOraclePriceData, useSpread?: boolean, latestSlot?: BN): [BN, BN, BN];
 /**
- * calculateTargetPriceTrade
- * simple function for finding arbitraging trades
+ * 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.
  *
- * @deprecated
+ * @deprecated No longer actively maintained; ignores DLOB liquidity.
  *
- * @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,
- *
- * [
- *   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 declare function calculateTargetPriceTrade(market: PerpMarketAccount, targetPrice: BN, pct?: BN, outputAssetType?: AssetType, mmOraclePriceData?: MMOraclePriceData, useSpread?: boolean, latestSlot?: BN): [PositionDirection, BN, BN, BN];
 /**
- * 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 declare function calculateEstimatedPerpEntryPrice(assetType: AssetType, amount: BN, direction: PositionDirection, market: PerpMarketAccount, mmOraclePriceData: MMOraclePriceData, dlob: DLOB, slot: number, usersToSkip?: Map<PublicKey, boolean>): {
     entryPrice: BN;
@@ -81,6 +104,23 @@ export declare function calculateEstimatedPerpEntryPrice(assetType: AssetType, a
     baseFilled: BN;
     quoteFilled: BN;
 };
+/**
+ * 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 declare function calculateEstimatedEntryPriceWithL2(assetType: AssetType, amount: BN, direction: PositionDirection, basePrecision: BN, l2: L2OrderBook): {
     entryPrice: BN;
     priceImpact: BN;
@@ -89,4 +129,15 @@ export declare function calculateEstimatedEntryPriceWithL2(assetType: AssetType,
     baseFilled: BN;
     quoteFilled: BN;
 };
+/**
+ * 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 declare function getUser30dRollingVolumeEstimate(userStatsAccount: UserStatsAccount, now?: BN): BN;