@velocity-exchange/sdk 0.3.0 → 0.4.0

package/lib/node/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/node/math/state.d.ts

@@ -1,6 +1,37 @@
 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;
 //# sourceMappingURL=state.d.ts.map

package/lib/node/math/state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../src/math/state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,sBAAsB,CAAC;AAM1C,OAAO,EAAmB,YAAY,EAAE,MAAM,UAAU,CAAC;AAEzD,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,YAAY,GAAG,EAAE,CAkBnE;AAED,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,YAAY,GAAG,EAAE,CAKxE;AAED,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,YAAY,GAAG,OAAO,CAIzE"}
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../src/math/state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,sBAAsB,CAAC;AAM1C,OAAO,EAAmB,YAAY,EAAE,MAAM,UAAU,CAAC;AAEzD;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,YAAY,GAAG,EAAE,CAkBnE;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,YAAY,GAAG,EAAE,CAKxE;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,YAAY,GAAG,OAAO,CAIzE"}

package/lib/node/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)
@@ -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/node/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,11 +194,47 @@ 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;
 //# sourceMappingURL=superStake.d.ts.map

package/lib/node/math/superStake.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"superStake.d.ts","sourceRoot":"","sources":["../../../src/math/superStake.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"superStake.d.ts","sourceRoot":"","sources":["../../../src/math/superStake.ts"],"names":[],"mappings":"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"}

package/lib/node/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/node/math/tiers.d.ts

@@ -1,5 +1,34 @@
 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;
 //# sourceMappingURL=tiers.d.ts.map

package/lib/node/math/tiers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tiers.d.ts","sourceRoot":"","sources":["../../../src/math/tiers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAE3E,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,iBAAiB,GAAG,MAAM,CAc7E;AAED,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,iBAAiB,GAAG,MAAM,CAc7E;AAED,wBAAgB,kBAAkB,CACjC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,aAAa,EAAE,MAAM,GACnB,OAAO,CAKT"}
+{"version":3,"file":"tiers.d.ts","sourceRoot":"","sources":["../../../src/math/tiers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAE3E;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,iBAAiB,GAAG,MAAM,CAc7E;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,iBAAiB,GAAG,MAAM,CAc7E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CACjC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,aAAa,EAAE,MAAM,GACnB,OAAO,CAKT"}