@velocity-exchange/sdk 0.2.5 → 0.4.0

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

@@ -1,10 +1,43 @@
 import { BN } from '../isomorphic/anchor';
 import { MarginCategory, SpotBalanceType, SpotMarketAccount } from '../types';
+/**
+ * Converts a human-readable number or `BN` into the spot market's on-chain token precision
+ * (`10 ** spotMarket.decimals`). Both inputs are treated as whole-token amounts and multiplied
+ * by the market's precision.
+ *
+ * @param {number | BN} value - A human-readable amount, or a `BN` expressed in whole
+ *   tokens (not yet scaled) that will be multiplied by the market's precision
+ * @param {SpotMarketAccount} spotMarket - The spot market account (supplies `decimals`)
+ * @return {BN} The token amount scaled by `10 ** spotMarket.decimals`
+ */
 export declare function castNumberToSpotPrecision(value: number | BN, spotMarket: SpotMarketAccount): BN;
+/**
+ * Calculates the effective margin ratio for a spot deposit or borrow position, expressed as
+ * `MARGIN_PRECISION - assetWeight` (deposits) or `liabilityWeight - MARGIN_PRECISION` (borrows).
+ * Note `MARGIN_PRECISION` and `SPOT_MARKET_WEIGHT_PRECISION` are both 1e4, so weights and margin
+ * ratios share the same scale.
+ *
+ * @param {SpotMarketAccount} market - The spot market account
+ * @param {BN} oraclePrice - The oracle price, PRICE_PRECISION (1e6)
+ * @param {MarginCategory} marginCategory - `'Initial'` or `'Maintenance'`
+ * @param {BN} size - The position size, scaled by `market.decimals`
+ * @param {SpotBalanceType} balanceType - Whether `size` is a deposit or a borrow
+ * @param {number} [customMarginRatio] - User's custom max margin ratio, `MARGIN_PRECISION` (1e4)
+ *   units; only takes effect for `'Initial'`, where the looser (higher) of the computed ratio
+ *   and this value is used, so a user can only demand *more* margin than the market default
+ * @return {number} The margin ratio, scaled by `MARGIN_PRECISION` (1e4, i.e. 10000 = 100%)
+ */
 export declare function calculateSpotMarketMarginRatio(market: SpotMarketAccount, oraclePrice: BN, marginCategory: MarginCategory, size: BN, balanceType: SpotBalanceType, customMarginRatio?: number): number;
 /**
- * Returns the maximum remaining deposit that can be made to the spot market. If the maxTokenDeposits on the market is zero then there is no limit and this function will also return zero. (so that needs to be checked)
- * @param market
- * @returns
+ * Calculates the remaining room under the spot market's deposit cap, mirroring the check in the
+ * program's deposit handler (`deposit_token_amount + amount <= max_token_deposits`, when the cap
+ * is set).
+ *
+ * @param {SpotMarketAccount} market - The spot market account
+ * @return {BN} `market.maxTokenDeposits - currentDeposits` (floored at zero), scaled by
+ *   `market.decimals`. **Ambiguous zero:** returns `ZERO` both when `maxTokenDeposits === 0`
+ *   (cap disabled, deposits are actually unlimited) and when the cap is enabled but already
+ *   fully utilized — callers must check `market.maxTokenDeposits.eq(ZERO)` separately to tell
+ *   "no limit" from "no room left".
  */
 export declare function calculateMaxRemainingDeposit(market: SpotMarketAccount): BN;

package/lib/browser/math/spotMarket.js

@@ -6,6 +6,16 @@ const types_1 = require("../types");
 const spotBalance_1 = require("./spotBalance");
 const numericConstants_1 = require("../constants/numericConstants");
 const utils_1 = require("./utils");
+/**
+ * Converts a human-readable number or `BN` into the spot market's on-chain token precision
+ * (`10 ** spotMarket.decimals`). Both inputs are treated as whole-token amounts and multiplied
+ * by the market's precision.
+ *
+ * @param {number | BN} value - A human-readable amount, or a `BN` expressed in whole
+ *   tokens (not yet scaled) that will be multiplied by the market's precision
+ * @param {SpotMarketAccount} spotMarket - The spot market account (supplies `decimals`)
+ * @return {BN} The token amount scaled by `10 ** spotMarket.decimals`
+ */
 function castNumberToSpotPrecision(value, spotMarket) {
     if (typeof value === 'number') {
         return (0, utils_1.numberToSafeBN)(value, new anchor_1.BN(Math.pow(10, spotMarket.decimals)));
@@ -15,6 +25,22 @@ function castNumberToSpotPrecision(value, spotMarket) {
     }
 }
 exports.castNumberToSpotPrecision = castNumberToSpotPrecision;
+/**
+ * Calculates the effective margin ratio for a spot deposit or borrow position, expressed as
+ * `MARGIN_PRECISION - assetWeight` (deposits) or `liabilityWeight - MARGIN_PRECISION` (borrows).
+ * Note `MARGIN_PRECISION` and `SPOT_MARKET_WEIGHT_PRECISION` are both 1e4, so weights and margin
+ * ratios share the same scale.
+ *
+ * @param {SpotMarketAccount} market - The spot market account
+ * @param {BN} oraclePrice - The oracle price, PRICE_PRECISION (1e6)
+ * @param {MarginCategory} marginCategory - `'Initial'` or `'Maintenance'`
+ * @param {BN} size - The position size, scaled by `market.decimals`
+ * @param {SpotBalanceType} balanceType - Whether `size` is a deposit or a borrow
+ * @param {number} [customMarginRatio] - User's custom max margin ratio, `MARGIN_PRECISION` (1e4)
+ *   units; only takes effect for `'Initial'`, where the looser (higher) of the computed ratio
+ *   and this value is used, so a user can only demand *more* margin than the market default
+ * @return {number} The margin ratio, scaled by `MARGIN_PRECISION` (1e4, i.e. 10000 = 100%)
+ */
 function calculateSpotMarketMarginRatio(market, oraclePrice, marginCategory, size, balanceType, customMarginRatio = 0) {
     let marginRatio;
     if ((0, types_1.isVariant)(balanceType, 'deposit')) {
@@ -33,9 +59,16 @@ function calculateSpotMarketMarginRatio(market, oraclePrice, marginCategory, siz
 }
 exports.calculateSpotMarketMarginRatio = calculateSpotMarketMarginRatio;
 /**
- * Returns the maximum remaining deposit that can be made to the spot market. If the maxTokenDeposits on the market is zero then there is no limit and this function will also return zero. (so that needs to be checked)
- * @param market
- * @returns
+ * Calculates the remaining room under the spot market's deposit cap, mirroring the check in the
+ * program's deposit handler (`deposit_token_amount + amount <= max_token_deposits`, when the cap
+ * is set).
+ *
+ * @param {SpotMarketAccount} market - The spot market account
+ * @return {BN} `market.maxTokenDeposits - currentDeposits` (floored at zero), scaled by
+ *   `market.decimals`. **Ambiguous zero:** returns `ZERO` both when `maxTokenDeposits === 0`
+ *   (cap disabled, deposits are actually unlimited) and when the cap is enabled but already
+ *   fully utilized — callers must check `market.maxTokenDeposits.eq(ZERO)` separately to tell
+ *   "no limit" from "no room left".
  */
 function calculateMaxRemainingDeposit(market) {
     const marketMaxTokenDeposits = market.maxTokenDeposits;

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

@@ -1,18 +1,90 @@
 import { MarginCategory, SpotMarketAccount, SpotPosition } from '../types';
 import { BN } from '../isomorphic/anchor';
 import { StrictOraclePrice } from '../oracles/strictOraclePrice';
+/**
+ * True if a `SpotPosition` slot has no balance and no open orders, meaning it is free to be
+ * reused (or shown as empty) rather than representing an active position.
+ *
+ * @param {SpotPosition} position - The spot position
+ * @return {boolean} Whether the slot is unused
+ */
 export declare function isSpotPositionAvailable(position: SpotPosition): boolean;
+/**
+ * Result of simulating a spot position's collateral contribution, optionally after its resting
+ * open orders are assumed to fill. All quote-denominated fields are `PRICE_PRECISION` (1e6).
+ */
 export type OrderFillSimulation = {
+    /** Signed token amount (base for non-quote markets), the market's token decimals */
     tokenAmount: BN;
+    /** Value of the open orders assumed to fill, at the worst-case (max) oracle price */
     ordersValue: BN;
+    /** Strict-oracle value of `tokenAmount` before margin weighting */
     tokenValue: BN;
+    /** Asset or liability weight applied to `tokenValue`, `SPOT_MARKET_WEIGHT_PRECISION` (1e4) */
     weight: BN;
+    /** `tokenValue` after applying `weight` */
     weightedTokenValue: BN;
+    /** Net contribution to free collateral: `weightedTokenValue` plus `ordersValue` where applicable */
     freeCollateralContribution: BN;
 };
+/**
+ * Calculates a spot position's worst-case token amount and margin contribution, accounting for
+ * the possibility that its resting open bids or asks could fill. Mirrors the program's
+ * worst-case spot balance logic used in margin/health checks: if both `openBids` and `openAsks`
+ * are zero (or `includeOpenOrders` is false), the position's current balance is valued as-is;
+ * otherwise the function separately simulates full fill of the bids and of the asks
+ * (`simulateOrderFill`) and returns whichever leaves the *lower* `freeCollateralContribution` —
+ * i.e. the more conservative (worse-case) scenario for margin purposes.
+ *
+ * @param {SpotPosition} spotPosition - The user's spot position
+ * @param {SpotMarketAccount} spotMarketAccount - The spot market account
+ * @param {StrictOraclePrice} strictOraclePrice - Live oracle price + 5min TWAP, PRICE_PRECISION (1e6)
+ * @param {MarginCategory | undefined} marginCategory - `'Initial'`, `'Maintenance'`, or
+ *   `undefined` for an unweighted valuation
+ * @param {number} [customMarginRatio] - User's custom max margin ratio (`'Initial'` only); see
+ *   `calculateWeightedTokenValue`
+ * @param {boolean} [includeOpenOrders] - Whether to simulate open order fills at all; defaults
+ *   to `true`. When `false`, only the current balance is valued regardless of open orders.
+ * @return {OrderFillSimulation} The worst-case simulation result
+ */
 export declare function getWorstCaseTokenAmounts(spotPosition: SpotPosition, spotMarketAccount: SpotMarketAccount, strictOraclePrice: StrictOraclePrice, marginCategory: MarginCategory | undefined, customMarginRatio?: number, includeOpenOrders?: boolean): OrderFillSimulation;
+/**
+ * Applies the appropriate asset or liability weight (based on the sign of `tokenValue`) to a
+ * token value, mirroring the program's `calculate_weighted_token_value` closure used in both
+ * plain and worst-case-fill spot margin calculations.
+ *
+ * @param {BN} tokenAmount - Signed token amount, used (as `abs()`) for the IMF size adjustment
+ * @param {BN} tokenValue - Signed strict-oracle value, `PRICE_PRECISION` (1e6); sign selects
+ *   asset weight (`>= 0`) vs liability weight (`< 0`)
+ * @param {BN} oraclePrice - The oracle price, PRICE_PRECISION (1e6), passed through to
+ *   `calculateAssetWeight` for the initial-weight deposit-value scaling lookup
+ * @param {SpotMarketAccount} spotMarket - The spot market account
+ * @param {MarginCategory | undefined} marginCategory - `'Initial'`, `'Maintenance'`, or `undefined`
+ * @param {number} [customMarginRatio] - User's custom max margin ratio, `SPOT_MARKET_WEIGHT_PRECISION`
+ *   (1e4) units; only applied for `'Initial'` on non-quote markets, tightening (never loosening)
+ *   the weight in the direction unfavorable to the user
+ * @return {{ weight: BN; weightedTokenValue: BN }} `weight` in `SPOT_MARKET_WEIGHT_PRECISION`
+ *   (1e4); `weightedTokenValue` in `PRICE_PRECISION` (1e6)
+ */
 export declare function calculateWeightedTokenValue(tokenAmount: BN, tokenValue: BN, oraclePrice: BN, spotMarket: SpotMarketAccount, marginCategory: MarginCategory | undefined, customMarginRatio?: number): {
     weight: BN;
     weightedTokenValue: BN;
 };
+/**
+ * Simulates one side (bids or asks) of a spot position's open orders fully filling, and
+ * recomputes the resulting margin contribution. Mirrors the per-side branch of the program's
+ * `simulate_fills_both_sides`. The filled orders' value is valued at the *worst-case* price
+ * (`strictOraclePrice.max()`) regardless of side, since filling either bids or asks moves the
+ * position further from its current state in the direction that could hurt collateral value.
+ *
+ * @param {BN} tokenAmount - Current signed token amount before the simulated fill
+ * @param {BN} tokenValue - Current strict-oracle token value before the simulated fill, `PRICE_PRECISION` (1e6)
+ * @param {BN} openOrders - Signed open order base size for this side: `spotPosition.openBids`
+ *   (stored positive) or `spotPosition.openAsks` (stored negative), the market's token decimals
+ * @param {StrictOraclePrice} strictOraclePrice - Live oracle price + 5min TWAP, PRICE_PRECISION (1e6)
+ * @param {SpotMarketAccount} spotMarket - The spot market account
+ * @param {MarginCategory | undefined} marginCategory - `'Initial'`, `'Maintenance'`, or `undefined`
+ * @param {number} [customMarginRatio] - User's custom max margin ratio; see `calculateWeightedTokenValue`
+ * @return {OrderFillSimulation} The post-fill simulation for this side
+ */
 export declare function simulateOrderFill(tokenAmount: BN, tokenValue: BN, openOrders: BN, strictOraclePrice: StrictOraclePrice, spotMarket: SpotMarketAccount, marginCategory: MarginCategory | undefined, customMarginRatio?: number): OrderFillSimulation;

package/lib/browser/math/spotPosition.js

@@ -4,10 +4,37 @@ exports.simulateOrderFill = exports.calculateWeightedTokenValue = exports.getWor
 const numericConstants_1 = require("../constants/numericConstants");
 const anchor_1 = require("../isomorphic/anchor");
 const spotBalance_1 = require("./spotBalance");
+/**
+ * True if a `SpotPosition` slot has no balance and no open orders, meaning it is free to be
+ * reused (or shown as empty) rather than representing an active position.
+ *
+ * @param {SpotPosition} position - The spot position
+ * @return {boolean} Whether the slot is unused
+ */
 function isSpotPositionAvailable(position) {
     return position.scaledBalance.eq(numericConstants_1.ZERO) && position.openOrders === 0;
 }
 exports.isSpotPositionAvailable = isSpotPositionAvailable;
+/**
+ * Calculates a spot position's worst-case token amount and margin contribution, accounting for
+ * the possibility that its resting open bids or asks could fill. Mirrors the program's
+ * worst-case spot balance logic used in margin/health checks: if both `openBids` and `openAsks`
+ * are zero (or `includeOpenOrders` is false), the position's current balance is valued as-is;
+ * otherwise the function separately simulates full fill of the bids and of the asks
+ * (`simulateOrderFill`) and returns whichever leaves the *lower* `freeCollateralContribution` —
+ * i.e. the more conservative (worse-case) scenario for margin purposes.
+ *
+ * @param {SpotPosition} spotPosition - The user's spot position
+ * @param {SpotMarketAccount} spotMarketAccount - The spot market account
+ * @param {StrictOraclePrice} strictOraclePrice - Live oracle price + 5min TWAP, PRICE_PRECISION (1e6)
+ * @param {MarginCategory | undefined} marginCategory - `'Initial'`, `'Maintenance'`, or
+ *   `undefined` for an unweighted valuation
+ * @param {number} [customMarginRatio] - User's custom max margin ratio (`'Initial'` only); see
+ *   `calculateWeightedTokenValue`
+ * @param {boolean} [includeOpenOrders] - Whether to simulate open order fills at all; defaults
+ *   to `true`. When `false`, only the current balance is valued regardless of open orders.
+ * @return {OrderFillSimulation} The worst-case simulation result
+ */
 function getWorstCaseTokenAmounts(spotPosition, spotMarketAccount, strictOraclePrice, marginCategory, customMarginRatio, includeOpenOrders = true) {
     const tokenAmount = (0, spotBalance_1.getSignedTokenAmount)((0, spotBalance_1.getTokenAmount)(spotPosition.scaledBalance, spotMarketAccount, spotPosition.balanceType), spotPosition.balanceType);
     const tokenValue = (0, spotBalance_1.getStrictTokenValue)(tokenAmount, spotMarketAccount.decimals, strictOraclePrice);
@@ -33,6 +60,24 @@ function getWorstCaseTokenAmounts(spotPosition, spotMarketAccount, strictOracleP
     }
 }
 exports.getWorstCaseTokenAmounts = getWorstCaseTokenAmounts;
+/**
+ * Applies the appropriate asset or liability weight (based on the sign of `tokenValue`) to a
+ * token value, mirroring the program's `calculate_weighted_token_value` closure used in both
+ * plain and worst-case-fill spot margin calculations.
+ *
+ * @param {BN} tokenAmount - Signed token amount, used (as `abs()`) for the IMF size adjustment
+ * @param {BN} tokenValue - Signed strict-oracle value, `PRICE_PRECISION` (1e6); sign selects
+ *   asset weight (`>= 0`) vs liability weight (`< 0`)
+ * @param {BN} oraclePrice - The oracle price, PRICE_PRECISION (1e6), passed through to
+ *   `calculateAssetWeight` for the initial-weight deposit-value scaling lookup
+ * @param {SpotMarketAccount} spotMarket - The spot market account
+ * @param {MarginCategory | undefined} marginCategory - `'Initial'`, `'Maintenance'`, or `undefined`
+ * @param {number} [customMarginRatio] - User's custom max margin ratio, `SPOT_MARKET_WEIGHT_PRECISION`
+ *   (1e4) units; only applied for `'Initial'` on non-quote markets, tightening (never loosening)
+ *   the weight in the direction unfavorable to the user
+ * @return {{ weight: BN; weightedTokenValue: BN }} `weight` in `SPOT_MARKET_WEIGHT_PRECISION`
+ *   (1e4); `weightedTokenValue` in `PRICE_PRECISION` (1e6)
+ */
 function calculateWeightedTokenValue(tokenAmount, tokenValue, oraclePrice, spotMarket, marginCategory, customMarginRatio) {
     let weight;
     if (tokenValue.gte(numericConstants_1.ZERO)) {
@@ -59,6 +104,23 @@ function calculateWeightedTokenValue(tokenAmount, tokenValue, oraclePrice, spotM
     };
 }
 exports.calculateWeightedTokenValue = calculateWeightedTokenValue;
+/**
+ * Simulates one side (bids or asks) of a spot position's open orders fully filling, and
+ * recomputes the resulting margin contribution. Mirrors the per-side branch of the program's
+ * `simulate_fills_both_sides`. The filled orders' value is valued at the *worst-case* price
+ * (`strictOraclePrice.max()`) regardless of side, since filling either bids or asks moves the
+ * position further from its current state in the direction that could hurt collateral value.
+ *
+ * @param {BN} tokenAmount - Current signed token amount before the simulated fill
+ * @param {BN} tokenValue - Current strict-oracle token value before the simulated fill, `PRICE_PRECISION` (1e6)
+ * @param {BN} openOrders - Signed open order base size for this side: `spotPosition.openBids`
+ *   (stored positive) or `spotPosition.openAsks` (stored negative), the market's token decimals
+ * @param {StrictOraclePrice} strictOraclePrice - Live oracle price + 5min TWAP, PRICE_PRECISION (1e6)
+ * @param {SpotMarketAccount} spotMarket - The spot market account
+ * @param {MarginCategory | undefined} marginCategory - `'Initial'`, `'Maintenance'`, or `undefined`
+ * @param {number} [customMarginRatio] - User's custom max margin ratio; see `calculateWeightedTokenValue`
+ * @return {OrderFillSimulation} The post-fill simulation for this side
+ */
 function simulateOrderFill(tokenAmount, tokenValue, openOrders, strictOraclePrice, spotMarket, marginCategory, customMarginRatio) {
     const ordersValue = (0, spotBalance_1.getTokenValue)(openOrders.neg(), spotMarket.decimals, {
         price: strictOraclePrice.max(),

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

@@ -1,5 +1,36 @@
 import { BN } from '../isomorphic/anchor';
 import { StateAccount } from '../types';
+/**
+ * Calculates the SOL fee that will be charged to initialize a new sub-account, mirroring
+ * `State::get_init_user_fee`'s account-space-utilization scaling: once sub-account utilization
+ * passes 80% of the max allowed, the fee ramps linearly from 0 up to `maxInitializeUserFee` at
+ * 100% utilization; below 80% it's free. `numberOfSubAccounts` is incremented by 1 before this
+ * ratio is computed because the on-chain handler bumps `state.numberOfSubAccounts` *before*
+ * calling `get_init_user_fee` — so a client reading pre-transaction state must simulate that
+ * increment itself to predict the fee the transaction will actually charge.
+ *
+ * @param {StateAccount} stateAccount - The global state account, read before submitting the
+ *   `initializeUser` transaction
+ * @return {BN} The init fee in lamports, `LAMPORTS_PRECISION` (1e9)
+ */
 export declare function calculateInitUserFee(stateAccount: StateAccount): BN;
+/**
+ * Calculates the effective max number of sub-accounts allowed per authority, mirroring
+ * `State::max_number_of_sub_accounts`. Values of 5 or below are used as-is (an explicit small
+ * cap); values above 5 are multiplied by 100, letting the admin store a compact "hundreds" unit
+ * for large caps.
+ *
+ * @param {StateAccount} stateAccount - The global state account
+ * @return {BN} The effective max sub-account count (unitless count, not a token amount)
+ */
 export declare function getMaxNumberOfSubAccounts(stateAccount: StateAccount): BN;
+/**
+ * True if the protocol-wide feature flag for median-based trigger prices is enabled, mirroring
+ * `State::use_median_trigger_price`. When enabled, `getTriggerPrice` (in `market.ts`) uses the
+ * median of last-fill, funding-basis, and 5min-basis prices instead of the raw oracle price for
+ * trigger order evaluation.
+ *
+ * @param {StateAccount} stateAccount - The global state account
+ * @return {boolean} Whether `FeatureBitFlags.MEDIAN_TRIGGER_PRICE` is set
+ */
 export declare function useMedianTriggerPrice(stateAccount: StateAccount): boolean;

package/lib/browser/math/state.js

@@ -4,6 +4,19 @@ exports.useMedianTriggerPrice = exports.getMaxNumberOfSubAccounts = exports.calc
 const anchor_1 = require("../isomorphic/anchor");
 const numericConstants_1 = require("../constants/numericConstants");
 const types_1 = require("../types");
+/**
+ * Calculates the SOL fee that will be charged to initialize a new sub-account, mirroring
+ * `State::get_init_user_fee`'s account-space-utilization scaling: once sub-account utilization
+ * passes 80% of the max allowed, the fee ramps linearly from 0 up to `maxInitializeUserFee` at
+ * 100% utilization; below 80% it's free. `numberOfSubAccounts` is incremented by 1 before this
+ * ratio is computed because the on-chain handler bumps `state.numberOfSubAccounts` *before*
+ * calling `get_init_user_fee` — so a client reading pre-transaction state must simulate that
+ * increment itself to predict the fee the transaction will actually charge.
+ *
+ * @param {StateAccount} stateAccount - The global state account, read before submitting the
+ *   `initializeUser` transaction
+ * @return {BN} The init fee in lamports, `LAMPORTS_PRECISION` (1e9)
+ */
 function calculateInitUserFee(stateAccount) {
     const maxInitFee = new anchor_1.BN(stateAccount.maxInitializeUserFee)
         .mul(numericConstants_1.LAMPORTS_PRECISION)
@@ -12,7 +25,7 @@ function calculateInitUserFee(stateAccount) {
     const accountSpaceUtilization = stateAccount.numberOfSubAccounts
         .addn(1)
         .mul(numericConstants_1.PERCENTAGE_PRECISION)
-        .div(getMaxNumberOfSubAccounts(stateAccount));
+        .div(anchor_1.BN.max(getMaxNumberOfSubAccounts(stateAccount), new anchor_1.BN(1)));
     if (accountSpaceUtilization.gt(targetUtilization)) {
         return maxInitFee
             .mul(accountSpaceUtilization.sub(targetUtilization))
@@ -23,6 +36,15 @@ function calculateInitUserFee(stateAccount) {
     }
 }
 exports.calculateInitUserFee = calculateInitUserFee;
+/**
+ * Calculates the effective max number of sub-accounts allowed per authority, mirroring
+ * `State::max_number_of_sub_accounts`. Values of 5 or below are used as-is (an explicit small
+ * cap); values above 5 are multiplied by 100, letting the admin store a compact "hundreds" unit
+ * for large caps.
+ *
+ * @param {StateAccount} stateAccount - The global state account
+ * @return {BN} The effective max sub-account count (unitless count, not a token amount)
+ */
 function getMaxNumberOfSubAccounts(stateAccount) {
     if (stateAccount.maxNumberOfSubAccounts <= 5) {
         return new anchor_1.BN(stateAccount.maxNumberOfSubAccounts);
@@ -30,6 +52,15 @@ function getMaxNumberOfSubAccounts(stateAccount) {
     return new anchor_1.BN(stateAccount.maxNumberOfSubAccounts).muln(100);
 }
 exports.getMaxNumberOfSubAccounts = getMaxNumberOfSubAccounts;
+/**
+ * True if the protocol-wide feature flag for median-based trigger prices is enabled, mirroring
+ * `State::use_median_trigger_price`. When enabled, `getTriggerPrice` (in `market.ts`) uses the
+ * median of last-fill, funding-basis, and 5min-basis prices instead of the raw oracle price for
+ * trigger order evaluation.
+ *
+ * @param {StateAccount} stateAccount - The global state account
+ * @return {boolean} Whether `FeatureBitFlags.MEDIAN_TRIGGER_PRICE` is set
+ */
 function useMedianTriggerPrice(stateAccount) {
     return ((stateAccount.featureBitFlags & types_1.FeatureBitFlags.MEDIAN_TRIGGER_PRICE) > 0);
 }

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

@@ -5,6 +5,7 @@ import { BN } from '../isomorphic/anchor';
 import { User } from '../user';
 import { DepositRecord } from '../types';
 import fetch from 'node-fetch';
+/** Response shape of SolBlaze's `bsol/stats` endpoint (bSOL conversion ratio + APY breakdown). */
 export type BSOL_STATS_API_RESPONSE = {
     success: boolean;
     stats?: {
@@ -21,14 +22,53 @@ 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?: {
         lend: number;
     };
 };
+/**
+ * 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 declare function fetchBSolMetrics(): Promise<fetch.Response>;
+/**
+ * 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 declare function fetchBSolVelocityEmissions(): Promise<fetch.Response>;
+/**
+ * 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 declare function findBestSuperStakeIxs({ marketIndex, amount, jupiterClient, velocityClient, userAccountPublicKey, price, forceMarinade, onlyDirectRoutes, jupiterQuote, }: {
     marketIndex: number;
     amount: BN;
@@ -45,6 +85,26 @@ export declare function findBestSuperStakeIxs({ marketIndex, amount, jupiterClie
     method: 'jupiter' | 'marinade';
     price?: number;
 }>;
+/**
+ * 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 declare function findBestMSolSuperStakeIxs({ amount, jupiterClient, velocityClient, userAccountPublicKey, price, forceMarinade, onlyDirectRoutes, jupiterQuote, }: {
     amount: BN;
     jupiterClient: JupiterClient;
@@ -60,6 +120,20 @@ export declare function findBestMSolSuperStakeIxs({ amount, jupiterClient, veloc
     method: 'jupiter' | 'marinade';
     price: number;
 }>;
+/**
+ * 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 declare function findBestJitoSolSuperStakeIxs({ amount, jupiterClient, velocityClient, userAccountPublicKey, onlyDirectRoutes, jupiterQuote, }: {
     amount: BN;
     jupiterClient: JupiterClient;
@@ -74,9 +148,22 @@ export declare function findBestJitoSolSuperStakeIxs({ amount, jupiterClient, ve
     price?: number;
 }>;
 /**
- * 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 declare function findBestLstSuperStakeIxs({ amount, jupiterClient, velocityClient, userAccountPublicKey, onlyDirectRoutes, lstMarketIndex, jupiterQuote, }: {
     amount: BN;
@@ -92,6 +179,7 @@ export declare function findBestLstSuperStakeIxs({ amount, jupiterClient, veloci
     lookupTables: AddressLookupTableAccount[];
     method: 'jupiter' | 'marinade';
 }>;
+/** Response shape of Jito's `stake_pool_stats` endpoint: daily TVL, jitoSOL supply, and APY series. */
 export type JITO_SOL_METRICS_ENDPOINT_RESPONSE = {
     tvl: {
         data: number;
@@ -106,10 +194,46 @@ export type JITO_SOL_METRICS_ENDPOINT_RESPONSE = {
         date: string;
     }[];
 };
+/**
+ * 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 declare function fetchJitoSolMetrics(): Promise<JITO_SOL_METRICS_ENDPOINT_RESPONSE>;
+/**
+ * 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 declare function calculateSolEarned({ marketIndex, user, depositRecords, }: {
     marketIndex: number;
     user: User;
     depositRecords: DepositRecord[];
 }): Promise<BN>;
+/**
+ * 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 declare function calculateEstimatedSuperStakeLiquidationPrice(lstDepositAmount: number, lstMaintenanceAssetWeight: number, solBorrowAmount: number, solMaintenanceLiabilityWeight: number, lstPriceRatio: number): number;