@velocity-exchange/sdk 0.2.5 → 0.4.0

package/lib/browser/user.d.ts

@@ -9,14 +9,14 @@
  *   - Health factor and liquidation threshold checks.
  *   - Subscribes to and caches the latest `User` account state from chain.
  *
- * To send instructions (deposit, place order, etc.) use {@link VelocityClient}.
- * For referral/volume stats see {@link UserStats} (userStats.ts).
+ * To send instructions (deposit, place order, etc.) use `VelocityClient`.
+ * For referral/volume stats see `UserStats` (userStats.ts).
  */
 import { PublicKey } from '@solana/web3.js';
 import { EventEmitter } from 'events';
 import StrictEventEmitter from 'strict-event-emitter-types';
 import { VelocityClient } from './velocityClient';
-import { HealthComponent, HealthComponents, MarginCategory, Order, PerpMarketAccount, PerpPosition, SpotPosition, UserAccount, UserStatus, UserStatsAccount, AccountLiquidatableStatus } from './types';
+import { HealthComponent, HealthComponents, MarginCategory, Order, OrderParams, PerpMarketAccount, PerpPosition, SpotPosition, UserAccount, UserStatus, UserStatsAccount, AccountLiquidatableStatus } from './types';
 import { DataAndSlot, UserAccountEvents, UserAccountSubscriber } from './accounts/types';
 import { BN } from './isomorphic/anchor';
 import { MarketType, PositionDirection, SpotMarketAccount } from './types';
@@ -31,24 +31,29 @@ export declare class User {
     accountSubscriber: UserAccountSubscriber;
     _isSubscribed: boolean;
     eventEmitter: StrictEventEmitter<EventEmitter, UserAccountEvents>;
+    /** True only when both `subscribe()` has completed and the underlying `accountSubscriber` itself reports subscribed. */
     get isSubscribed(): boolean;
     set isSubscribed(val: boolean);
+    /** Constructs a `User` for the account at `config.userAccountPublicKey`, wiring up the account subscriber selected by `config.accountSubscription` (`'websocket'`/`'polling'`/`'grpc'`/`'custom'`). Does not fetch or subscribe — call `subscribe()` next. */
     constructor(config: UserConfig);
     /**
-     * Subscribe to User state accounts
-     * @returns SusbcriptionSuccess result
+     * Subscribes to this `User` account (websocket/polling/gRPC/custom per
+     * `UserConfig.accountSubscription`) and awaits the initial account fetch.
+     * Must resolve before any `get*`/margin/PnL accessor is called — those
+     * throw `NotSubscribedError` until this has completed.
+     * @param userAccount Optional pre-fetched account to seed the subscriber with, skipping the initial RPC fetch.
+     * @returns True once the underlying subscriber reports subscribed.
      */
     subscribe(userAccount?: UserAccount): Promise<boolean>;
-    /**
-     *	Forces the accountSubscriber to fetch account updates from rpc
-     */
+    /** Forces the account subscriber to re-fetch the `User` account from RPC (bypassing any push/poll cadence). */
     fetchAccounts(): Promise<void>;
+    /** Removes all event listeners and tears down the account subscription. */
     unsubscribe(): Promise<void>;
     /**
      * Returns the cached user account.
      *
      * - **Throws** `NotSubscribedError` if the subscriber has not been subscribed
-     *   yet — reading the account before {@link subscribe} resolves is a
+     *   yet — reading the account before `subscribe()` resolves is a
      *   programming error, not a missing-account condition.
      * - Returns `undefined` when subscribed but no account was found on chain.
      *   Because `subscribe()` awaits the initial fetch, an `undefined` here means
@@ -57,24 +62,46 @@ export declare class User {
      */
     getUserAccount(): UserAccount | undefined;
     /**
-     * Like {@link getUserAccount} but throws instead of returning `undefined`
+     * Like `getUserAccount` but throws instead of returning `undefined`
      * when the account was not found. Use at call sites that structurally
      * require the account to exist. (Still propagates `NotSubscribedError` when
      * called before subscribing.)
      *
-     * Delegates to {@link getUserAccount} (rather than the subscriber directly)
+     * Delegates to `getUserAccount` (rather than the subscriber directly)
      * so callers that override `getUserAccount` see the override here too.
+     * @returns The current `UserAccount`.
      */
     getUserAccountOrThrow(): UserAccount;
+    /**
+     * Bypasses the cached subscriber state and force-fetches the `User` account
+     * directly from the RPC (via `fetchAccounts`), then returns the freshly
+     * cached value. Useful right after sending a transaction, when the
+     * websocket/polling subscriber may not yet have observed the update.
+     * @returns The freshly fetched `UserAccount`, or `undefined` if the account does not exist on chain.
+     */
     forceGetUserAccount(): Promise<UserAccount | undefined>;
+    /**
+     * Returns the cached user account together with the slot at which it was
+     * last observed. Same `undefined`/`NotSubscribedError` contract as `getUserAccount`.
+     */
     getUserAccountAndSlot(): DataAndSlot<UserAccount> | undefined;
     /**
-     * Like {@link getUserAccountAndSlot} but throws instead of returning
+     * Like `getUserAccountAndSlot` but throws instead of returning
      * `undefined` when the account was not found. Use at call sites that
      * structurally require the account to exist. (Still propagates
      * `NotSubscribedError` when called before subscribing.)
      */
     getUserAccountAndSlotOrThrow(): DataAndSlot<UserAccount>;
+    /**
+     * Finds the perp position for `marketIndex` on an explicit `userAccount`
+     * snapshot rather than the cached account. Only matches "active" positions
+     * (see `getActivePerpPositionsForUserAccount`) — a market the user has never
+     * touched (or has fully closed and settled) returns `undefined` even though
+     * the on-chain array always has a fixed-size slot for every market.
+     * @param userAccount Account snapshot to search (does not have to be the subscribed account).
+     * @param marketIndex Perp market index to look up.
+     * @returns The matching `PerpPosition`, or `undefined` if the user has no active position in that market.
+     */
     getPerpPositionForUserAccount(userAccount: UserAccount, marketIndex: number): PerpPosition | undefined;
     /**
      * Gets the user's current position for a given perp market. If the user has no position returns undefined
@@ -82,9 +109,31 @@ export declare class User {
      * @returns userPerpPosition
      */
     getPerpPosition(marketIndex: number): PerpPosition | undefined;
+    /**
+     * Like `getPerpPosition`, but returns a zeroed-out placeholder position
+     * (see `getEmptyPosition`) instead of `undefined` when the user has no
+     * active position in `marketIndex`. Convenient for math helpers that need a
+     * `PerpPosition` shape unconditionally (e.g. buying-power/leverage calcs).
+     */
     getPerpPositionOrEmpty(marketIndex: number): PerpPosition;
+    /**
+     * Like `getPerpPosition`, but throws instead of returning `undefined` when
+     * the user has no active position in `marketIndex`.
+     */
     getPerpPositionOrThrow(marketIndex: number): PerpPosition;
+    /**
+     * Like `getPerpPosition`, but also returns the slot at which the underlying
+     * `UserAccount` was observed.
+     */
     getPerpPositionAndSlot(marketIndex: number): DataAndSlot<PerpPosition | undefined>;
+    /**
+     * Finds the spot position for `marketIndex` on an explicit `userAccount`
+     * snapshot. Unlike `getPerpPositionForUserAccount`, this does not filter to
+     * "active" positions first — it returns whatever fixed-size slot entry
+     * exists for that market index, even if the position is empty/available.
+     * @param userAccount Account snapshot to search (does not have to be the subscribed account).
+     * @param marketIndex Spot market index to look up.
+     */
     getSpotPositionForUserAccount(userAccount: UserAccount, marketIndex: number): SpotPosition | undefined;
     /**
      * Gets the user's current position for a given spot market. If the user has no position returns undefined
@@ -92,58 +141,125 @@ export declare class User {
      * @returns userSpotPosition
      */
     getSpotPosition(marketIndex: number): SpotPosition | undefined;
+    /**
+     * Like `getSpotPosition`, but also returns the slot at which the underlying
+     * `UserAccount` was observed.
+     */
     getSpotPositionAndSlot(marketIndex: number): DataAndSlot<SpotPosition | undefined>;
+    /** Returns a zeroed-out (no deposit/borrow) placeholder `SpotPosition` for `marketIndex`. */
     getEmptySpotPosition(marketIndex: number): SpotPosition;
     /**
      * Returns the token amount for a given market. The spot market precision is based on the token mint decimals.
      * Positive if it is a deposit, negative if it is a borrow.
      *
      * @param marketIndex
+     * @returns Signed token amount, in the spot market's own token decimals (not QUOTE_PRECISION). `ZERO` if the user has no position in the market.
      */
     getTokenAmount(marketIndex: number): BN;
+    /** Returns a zeroed-out placeholder `PerpPosition` for `marketIndex` (no size, no orders, cross margin). */
     getEmptyPosition(marketIndex: number): PerpPosition;
+    /** Returns true if `position` has no size and no open orders (a market slot that can be treated as unused). */
     isPositionEmpty(position: PerpPosition): boolean;
+    /**
+     * Returns the isolated-margin quote deposit backing a given perp position,
+     * i.e. `PerpPosition.isolatedPositionScaledBalance` converted to a token
+     * amount. This is the collateral segregated to that single isolated
+     * position, separate from the user's cross-margin free collateral.
+     * @param perpMarketIndex
+     * @returns Quote token amount (the quote spot market's own decimals). `ZERO` if the user has no position or no isolated deposit in the market.
+     */
     getIsolatePerpPositionTokenAmount(perpMarketIndex: number): BN;
     /**
      * Returns the total USD value of deposits across all isolated perp positions.
+     * @returns Precision QUOTE_PRECISION (1e6).
      */
     getTotalIsolatedPositionDeposits(): BN;
+    /** Returns a shallow copy of `position`. Mutating the clone does not affect the cached account. */
     getClonedPosition(position: PerpPosition): PerpPosition;
+    /** Finds an order by its program-assigned `orderId` on an explicit `userAccount` snapshot. */
     getOrderForUserAccount(userAccount: UserAccount, orderId: number): Order | undefined;
     /**
+     * Finds an order in the cached `UserAccount` by its program-assigned `orderId`.
      * @param orderId
-     * @returns Order
+     * @returns The matching `Order`, or `undefined` if no order with that id exists.
      */
     getOrder(orderId: number): Order | undefined;
+    /** Like `getOrder`, but also returns the slot at which the underlying `UserAccount` was observed. */
     getOrderAndSlot(orderId: number): DataAndSlot<Order | undefined>;
+    /**
+     * Finds an order by its caller-assigned `userOrderId` (a client-chosen tag,
+     * distinct from the program-assigned `orderId`) on an explicit `userAccount`
+     * snapshot.
+     */
     getOrderByUserIdForUserAccount(userAccount: UserAccount, userOrderId: number): Order | undefined;
     /**
+     * Finds an order in the cached `UserAccount` by its caller-assigned
+     * `userOrderId` (a client-chosen tag, distinct from the program-assigned `orderId`).
      * @param userOrderId
-     * @returns Order
+     * @returns The matching `Order`, or `undefined` if no order with that tag exists.
      */
     getOrderByUserOrderId(userOrderId: number): Order | undefined;
+    /** Like `getOrderByUserOrderId`, but also returns the slot at which the underlying `UserAccount` was observed. */
     getOrderByUserOrderIdAndSlot(userOrderId: number): DataAndSlot<Order | undefined>;
+    /**
+     * Filters an explicit `userAccount` snapshot's orders down to those with
+     * `OrderStatus.Open`.
+     * @returns `undefined` if `userAccount` is `undefined` (i.e. no account loaded), otherwise the array of open orders (possibly empty).
+     */
     getOpenOrdersForUserAccount(userAccount?: UserAccount): Order[] | undefined;
+    /** Returns all of the user's orders with `OrderStatus.Open`. Empty array (not `undefined`) if there are none or no account is loaded. */
     getOpenOrders(): Order[];
+    /** Like `getOpenOrders`, but also returns the slot at which the underlying `UserAccount` was observed. */
     getOpenOrdersAndSlot(): DataAndSlot<Order[]>;
+    /** Returns this `User`'s account address (does not require the account to be subscribed or to exist on chain). */
     getUserAccountPublicKey(): PublicKey;
+    /** Checks directly via RPC (bypassing the subscriber cache) whether the `User` account exists on chain. */
     exists(): Promise<boolean>;
     /**
-     * calculates the total open bids/asks in a perp market (including lps)
-     * @returns : open bids
-     * @returns : open asks
+     * Returns the position's total resting open-order bid/ask size in a perp market.
+     * @param marketIndex
+     * @returns Tuple of `[openBids, openAsks]`, both `BASE_PRECISION` (1e9). Throws (via `getPerpPositionOrThrow`) if the user has no active position in `marketIndex`.
      */
     getPerpBidAsks(marketIndex: number): [BN, BN];
     /**
      * calculates Buying Power = free collateral / initial margin ratio
-     * @returns : Precision QUOTE_PRECISION
+     *
+     * For `positionType: 'isolated'`, the buying power is capped by the
+     * lesser of (a) the user's cross free collateral and (b) the free quote
+     * asset value in the perp's quote spot market — mirroring that an isolated
+     * position can only draw down as much quote collateral as is actually
+     * available to isolate into it.
+     * @param marketIndex Perp market to size buying power for.
+     * @param collateralBuffer Amount (QUOTE_PRECISION) subtracted from free collateral before sizing, e.g. to reserve for fees. Defaults to zero.
+     * @param maxMarginRatio Optional override for the max margin ratio component (see `resolveMaxMarginRatio`); defaults to the position's/user's configured ratio.
+     * @param positionType Whether to size for a cross or isolated-margin position. Defaults to `'cross'`.
+     * @returns Precision QUOTE_PRECISION (1e6).
      */
     getPerpBuyingPower(marketIndex: number, collateralBuffer?: BN, maxMarginRatio?: number | undefined, positionType?: 'isolated' | 'cross'): BN;
     private resolveMaxMarginRatio;
+    /**
+     * Converts a free-collateral amount directly into buying power for a perp
+     * market, given the (hypothetical) resulting base position size — used
+     * internally so the margin ratio (which can vary with position size via the
+     * IMF factor) reflects the post-trade size rather than the current size.
+     * @param marketIndex
+     * @param freeCollateral QUOTE_PRECISION (1e6).
+     * @param baseAssetAmount Base size, BASE_PRECISION (1e9), used only to select the applicable margin ratio.
+     * @param perpMarketMaxMarginRatio Optional max-margin-ratio override, see `resolveMaxMarginRatio`.
+     * @returns Precision QUOTE_PRECISION (1e6).
+     */
     getPerpBuyingPowerFromFreeCollateralAndBaseAssetAmount(marketIndex: number, freeCollateral: BN, baseAssetAmount: BN, perpMarketMaxMarginRatio?: number | undefined): BN;
     /**
      * calculates Free Collateral = Total collateral - margin requirement
-     * @returns : Precision QUOTE_PRECISION
+     *
+     * When `perpMarketIndex` is provided, returns the free collateral scoped to
+     * that market's isolated margin bucket (the isolated quote deposit plus its
+     * unrealized PnL, minus its own margin requirement) rather than the user's
+     * cross-margin free collateral. If the user has no isolated position open in
+     * that market, returns `ZERO` rather than throwing.
+     * @param marginCategory `'Initial'` or `'Maintenance'`. Defaults to `'Initial'`; `'Initial'` also enables strict (TWAP-bounded) oracle pricing.
+     * @param perpMarketIndex Optional isolated perp market to scope the calculation to; omit for cross margin.
+     * @returns Precision QUOTE_PRECISION (1e6). Can be negative (deficit).
      */
     getFreeCollateral(marginCategory?: MarginCategory, perpMarketIndex?: number): BN;
     /**
@@ -153,134 +269,330 @@ export declare class User {
     /**
      * Calculates the margin requirement based on the specified parameters.
      *
+     * When `perpMarketIndex` is passed, returns the isolated margin requirement
+     * for that market's isolated position only (`ZERO` if none exists) rather
+     * than the cross-margin requirement. `liquidationBuffer`, when non-zero,
+     * selects the buffered variant (`marginRequirementPlusBuffer` /
+     * `MarginContext.liquidation`), which pads the requirement to build in the
+     * state account's `liquidationMarginBufferRatio` — the same buffer keepers
+     * apply so a position doesn't get flagged for liquidation and immediately
+     * clear again.
+     *
      * @param marginCategory - The category of margin to calculate ('Initial' or 'Maintenance').
-     * @param liquidationBuffer - Optional buffer amount to consider during liquidation scenarios.
-     * @param strict - Optional flag to enforce strict margin calculations.
-     * @param includeOpenOrders - Optional flag to include open orders in the margin calculation.
-     * @param perpMarketIndex - Optional index of the perpetual market. Required if marginType is 'Isolated'.
+     * @param liquidationBuffer - Optional buffer amount (MARGIN_PRECISION, 1e4, added to the margin ratio) to consider during liquidation scenarios.
+     * @param strict - Optional flag to enforce strict (TWAP-bounded) oracle pricing.
+     * @param includeOpenOrders - Optional flag to include open orders' worst-case margin impact.
+     * @param perpMarketIndex - Optional index of the perpetual market. Scopes the result to that market's isolated position.
      *
-     * @returns The calculated margin requirement as a BN (BigNumber).
+     * @returns The calculated margin requirement, QUOTE_PRECISION (1e6).
      */
     getMarginRequirement(marginCategory: MarginCategory, liquidationBuffer?: BN, strict?: boolean, includeOpenOrders?: boolean, perpMarketIndex?: number): BN;
     /**
-     * @returns The initial margin requirement in USDC. : QUOTE_PRECISION
+     * Initial margin requirement — the collateral needed to open/maintain a
+     * position at initial (as opposed to maintenance) margin ratios, using
+     * strict (TWAP-bounded) oracle pricing. This is what gates new orders and
+     * increases in leverage.
+     * @param perpMarketIndex Optional isolated perp market to scope to; omit for the cross-margin requirement.
+     * @returns The initial margin requirement in USDC. : QUOTE_PRECISION (1e6)
      */
     getInitialMarginRequirement(perpMarketIndex?: number): BN;
     /**
-     * @returns The maintenance margin requirement in USDC. : QUOTE_PRECISION
+     * Maintenance margin requirement — the minimum collateral below which the
+     * position becomes eligible for liquidation. Uses non-strict oracle pricing
+     * and includes open orders' worst-case impact by default.
+     * @param liquidationBuffer Optional buffer (MARGIN_PRECISION, 1e4) added to the margin ratio, mirroring the state account's `liquidationMarginBufferRatio`.
+     * @param perpMarketIndex Optional isolated perp market to scope to; omit for the cross-margin requirement.
+     * @returns The maintenance margin requirement in USDC. : QUOTE_PRECISION (1e6)
      */
     getMaintenanceMarginRequirement(liquidationBuffer?: BN, perpMarketIndex?: number): BN;
+    /**
+     * Filters an explicit `userAccount` snapshot's fixed-size perp position
+     * array down to slots that are actually "active": nonzero base or quote
+     * amount, an outstanding open order count, or a nonzero isolated-margin
+     * quote deposit (a position can be flat but still isolated-funded).
+     */
     getActivePerpPositionsForUserAccount(userAccount: UserAccount): PerpPosition[];
+    /** Returns the cached account's active perp positions. See `getActivePerpPositionsForUserAccount` for the activity criteria. */
     getActivePerpPositions(): PerpPosition[];
+    /** Like `getActivePerpPositions`, but also returns the slot at which the underlying `UserAccount` was observed. */
     getActivePerpPositionsAndSlot(): DataAndSlot<PerpPosition[]>;
+    /** Filters an explicit `userAccount` snapshot's spot positions to those that are not `isSpotPositionAvailable` (i.e. have a nonzero balance, orders, or cumulative deposits). */
     getActiveSpotPositionsForUserAccount(userAccount: UserAccount): SpotPosition[];
+    /** Returns the cached account's active spot positions. See `getActiveSpotPositionsForUserAccount` for the activity criteria. */
     getActiveSpotPositions(): SpotPosition[];
+    /** Like `getActiveSpotPositions`, but also returns the slot at which the underlying `UserAccount` was observed. */
     getActiveSpotPositionsAndSlot(): DataAndSlot<SpotPosition[]>;
     /**
-     * calculates unrealized position price pnl
-     * @returns : Precision QUOTE_PRECISION
+     * Calculates unrealized position price PnL, summed across all active perp
+     * positions (or a single one if `marketIndex` is given).
+     *
+     * When `withWeightMarginCategory` is supplied, the PnL is asset-weighted
+     * for margin purposes: profitable positions are scaled down by
+     * `calculateUnrealizedAssetWeight` (an unrealized gain is a less-trusted
+     * asset than settled collateral), and — for `'Initial'` margin specifically
+     * — the *per-position* weighted gain is additionally capped at
+     * `MAX_POSITIVE_UPNL_FOR_INITIAL_MARGIN` (**$100**, QUOTE_PRECISION), a
+     * safety guard against a single dangerously-configured or manipulated
+     * market inflating buying power. Losses are never capped, and a
+     * `liquidationBuffer` (if provided) further inflates negative PnL to
+     * mirror the on-chain liquidation-buffer treatment.
+     * @param withFunding If true, includes unsettled funding in each position's PnL.
+     * @param marketIndex Optional single perp market to scope to; omit to sum across all active positions.
+     * @param withWeightMarginCategory Optional `'Initial'` or `'Maintenance'` — applies the asset-weighting (and, for `'Initial'`, the $100-per-position cap) described above. Omit for raw, unweighted PnL.
+     * @param strict Use the worse of live oracle price vs 5-minute TWAP per position (gains use the lower price, losses use the higher price). Defaults to false.
+     * @param liquidationBuffer Optional buffer (MARGIN_PRECISION, 1e4) that further penalizes negative PnL; only applied when `withWeightMarginCategory` is set.
+     * @returns : Precision QUOTE_PRECISION (1e6)
      */
     getUnrealizedPNL(withFunding?: boolean, marketIndex?: number, withWeightMarginCategory?: MarginCategory, strict?: boolean, liquidationBuffer?: BN): BN;
     /**
-     * calculates unrealized funding payment pnl
-     * @returns : Precision QUOTE_PRECISION
+     * Calculates unrealized funding payment PnL — the funding accrued since
+     * each position's `lastCumulativeFundingRate` was last settled, not yet
+     * reflected in `quoteAssetAmount`.
+     * @param marketIndex Optional single perp market to scope to; omit to sum across all positions.
+     * @returns : Precision QUOTE_PRECISION (1e6)
      */
     getUnrealizedFundingPNL(marketIndex?: number): BN;
+    /**
+     * Computes the combined weighted asset value and weighted liability value
+     * across the user's spot positions (worst-case, including open-order
+     * exposure by default), plus the net quote balance. This is the core spot
+     * side of the margin system that `getTotalCollateral`/`getMarginRequirement`
+     * build on.
+     * @param marketIndex Optional single spot market to scope to; omit to sum across all spot markets.
+     * @param marginCategory `'Initial'` or `'Maintenance'` asset/liability weights; omit for unweighted (100%) values.
+     * @param liquidationBuffer Optional buffer (MARGIN_PRECISION, 1e4) added to the liability weight side.
+     * @param includeOpenOrders If false, ignores open bids/asks and only counts the current balance (faster, less conservative).
+     * @param strict Use the worse of live oracle price vs 5-minute TWAP. Defaults to false.
+     * @param now Unix timestamp (seconds) used for TWAP staleness when `strict` is set; defaults to current time.
+     * @returns `{ totalAssetValue, totalLiabilityValue }`, both QUOTE_PRECISION (1e6) and non-negative.
+     */
     getSpotMarketAssetAndLiabilityValue(marketIndex?: number, marginCategory?: MarginCategory, liquidationBuffer?: BN, includeOpenOrders?: boolean, strict?: boolean, now?: BN): {
         totalAssetValue: BN;
         totalLiabilityValue: BN;
     };
+    /** Convenience wrapper around `getSpotMarketAssetAndLiabilityValue` returning only `totalLiabilityValue`. See that method for parameter semantics. Returns QUOTE_PRECISION (1e6). */
     getSpotMarketLiabilityValue(marketIndex?: number, marginCategory?: MarginCategory, liquidationBuffer?: BN, includeOpenOrders?: boolean, strict?: boolean, now?: BN): BN;
+    /** Thin wrapper around the `math/spotBalance` `getSpotLiabilityValue` helper that supplies the user's `maxMarginRatio`. Returns QUOTE_PRECISION (1e6), negative. */
     getSpotLiabilityValue(tokenAmount: BN, strictOraclePrice: StrictOraclePrice, spotMarketAccount: SpotMarketAccount, marginCategory?: MarginCategory, liquidationBuffer?: BN): BN;
+    /** Convenience wrapper around `getSpotMarketAssetAndLiabilityValue` returning only `totalAssetValue`. See that method for parameter semantics. Returns QUOTE_PRECISION (1e6), non-negative. */
     getSpotMarketAssetValue(marketIndex?: number, marginCategory?: MarginCategory, includeOpenOrders?: boolean, strict?: boolean, now?: BN): BN;
+    /** Thin wrapper around the `math/spotBalance` `getSpotAssetValue` helper that supplies the user's `maxMarginRatio`. Returns QUOTE_PRECISION (1e6), non-negative. */
     getSpotAssetValue(tokenAmount: BN, strictOraclePrice: StrictOraclePrice, spotMarketAccount: SpotMarketAccount, marginCategory?: MarginCategory): BN;
+    /** Net spot value (`totalAssetValue - totalLiabilityValue`) for a single spot market. See `getSpotMarketAssetAndLiabilityValue` for parameter semantics. Returns QUOTE_PRECISION (1e6), can be negative. */
     getSpotPositionValue(marketIndex: number, marginCategory?: MarginCategory, includeOpenOrders?: boolean, strict?: boolean, now?: BN): BN;
+    /**
+     * Net spot value (`totalAssetValue - totalLiabilityValue`) across all spot
+     * markets combined.
+     * @param withWeightMarginCategory Optional `'Initial'`/`'Maintenance'` weighting; omit for unweighted values.
+     * @returns Precision QUOTE_PRECISION (1e6), can be negative.
+     */
     getNetSpotMarketValue(withWeightMarginCategory?: MarginCategory): BN;
     /**
      * calculates TotalCollateral: collateral + unrealized pnl
      * @returns : Precision QUOTE_PRECISION
      */
+    /**
+     * Calculates Total Collateral: net spot collateral value plus weighted
+     * unrealized perp PnL (see `getUnrealizedPNL`'s `$100`-per-position cap
+     * under `'Initial'` margin). This is the numerator side of the margin
+     * system; `getFreeCollateral`/`getMarginRequirement` are derived from it.
+     *
+     * When `perpMarketIndex` is provided, returns the isolated total collateral
+     * for that market's isolated position bucket instead of the cross-margin
+     * total — and **throws** if the user has no isolated margin calculation for
+     * that market (unlike `getFreeCollateral`, which swallows the same case and
+     * returns `ZERO`).
+     * @param marginCategory `'Initial'` or `'Maintenance'`. Defaults to `'Initial'`.
+     * @param strict Use TWAP-bounded oracle pricing. Defaults to false.
+     * @param includeOpenOrders Include open orders' worst-case impact. Defaults to true.
+     * @param liquidationBuffer Optional buffer (MARGIN_PRECISION, 1e4); selects the buffered collateral variant when non-zero.
+     * @param perpMarketIndex Optional isolated perp market to scope to.
+     * @returns Precision QUOTE_PRECISION (1e6).
+     */
     getTotalCollateral(marginCategory?: MarginCategory, strict?: boolean, includeOpenOrders?: boolean, liquidationBuffer?: BN, perpMarketIndex?: number): BN;
+    /**
+     * Builds the liquidation-buffer map to pass into margin calculations while
+     * a liquidation is in progress: `'cross'` is set to the state account's
+     * `liquidationMarginBufferRatio` if cross margin is being liquidated, and
+     * each isolated perp position currently flagged `BeingLiquidated` or
+     * `Bankruptcy` gets the same buffer under its market index. Positions not
+     * currently being liquidated are omitted (no buffer applied).
+     * @returns Map from `'cross'` or a perp market index to the buffer amount (MARGIN_PRECISION, 1e4).
+     */
     getLiquidationBuffer(): Map<number | 'cross', BN>;
     /**
-     * calculates User Health by comparing total collateral and maint. margin requirement
-     * @returns : number (value from [0, 100])
+     * Calculates a user's health score by comparing total collateral against
+     * the maintenance margin requirement: `100 * (1 - maintenanceMarginReq / totalCollateral)`,
+     * clamped to `[0, 100]` and rounded to the nearest integer. `100` means no
+     * maintenance requirement (or a requirement of zero with non-negative
+     * collateral); `0` means at or past the maintenance threshold (liquidatable)
+     * or that collateral is non-positive.
+     *
+     * Short-circuits to `0` if the relevant scope is already flagged as being
+     * liquidated: cross margin via `isCrossMarginBeingLiquidated` (when
+     * `perpMarketIndex` is omitted), or the specific isolated position via
+     * `isIsolatedPositionBeingLiquidated` (when `perpMarketIndex` is given).
+     * @param perpMarketIndex Optional isolated perp market to scope health to; omit for the cross-margin account's health.
+     * @returns Health, an integer in `[0, 100]`.
      */
     getHealth(perpMarketIndex?: number): number;
+    /**
+     * Computes a single perp position's margin-weighted liability value: worst-case
+     * (or current, if `includeOpenOrders` is false) base amount, valued at the
+     * oracle price (or `expiryPrice` if the market is in settlement, which also
+     * zeroes the margin ratio), scaled by the applicable margin ratio for
+     * `marginCategory`. Underlies `getPerpMarketLiabilityValue`,
+     * `getTotalPerpPositionLiability`, and the leverage/liquidation-price math.
+     * @returns Precision QUOTE_PRECISION (1e6); unweighted (raw notional, no margin ratio applied) if `marginCategory` is omitted.
+     */
     calculateWeightedPerpPositionLiability(perpPosition: PerpPosition, marginCategory?: MarginCategory, liquidationBuffer?: BN, includeOpenOrders?: boolean, strict?: boolean): BN;
     /**
-     * calculates position value of a single perp market in margin system
-     * @returns : Precision QUOTE_PRECISION
+     * Margin-weighted liability value of a single perp position. Thin wrapper
+     * around `calculateWeightedPerpPositionLiability` for the position in
+     * `marketIndex`; see that method for the worst-case/margin-ratio semantics.
+     * @param marketIndex
+     * @param marginCategory `'Initial'`/`'Maintenance'` margin ratio to apply; omit for the raw unweighted notional.
+     * @param liquidationBuffer Optional buffer (MARGIN_PRECISION, 1e4) added to the margin ratio.
+     * @param includeOpenOrders If true (recommended for margin checks), uses the worst-case base amount including open bids/asks.
+     * @param strict Use TWAP-bounded quote pricing. Defaults to false.
+     * @returns Precision QUOTE_PRECISION (1e6). Throws (via `getPerpPositionOrThrow`) if the user has no active position in `marketIndex`.
      */
     getPerpMarketLiabilityValue(marketIndex: number, marginCategory?: MarginCategory, liquidationBuffer?: BN, includeOpenOrders?: boolean, strict?: boolean): BN;
     /**
-     * calculates sum of position value across all positions in margin system
-     * @returns : Precision QUOTE_PRECISION
+     * Sums `calculateWeightedPerpPositionLiability` across every active perp
+     * position — the perp side of the margin requirement (see `getMarginRequirement`).
+     * @param marginCategory `'Initial'`/`'Maintenance'` margin ratio to apply; omit for the raw unweighted notional.
+     * @param liquidationBuffer Optional buffer (MARGIN_PRECISION, 1e4) added to the margin ratio.
+     * @param includeOpenOrders If true, uses each position's worst-case base amount including open bids/asks.
+     * @param strict Use TWAP-bounded quote pricing. Defaults to false.
+     * @returns Precision QUOTE_PRECISION (1e6).
      */
     getTotalPerpPositionLiability(marginCategory?: MarginCategory, liquidationBuffer?: BN, includeOpenOrders?: boolean, strict?: boolean): BN;
     /**
-     * calculates position value based on oracle
-     * @returns : Precision QUOTE_PRECISION
+     * Values a perp position's base-asset notional at a caller-supplied oracle
+     * price rather than looking one up internally — useful for pricing against
+     * a simulated/custom price. Returns `ZERO` (via `getPerpPositionOrEmpty`) if
+     * the user has no position in `marketIndex`.
+     * @param marketIndex
+     * @param oraclePriceData Price to value the position at, PRICE_PRECISION (1e6). Caller-supplied so callers can pass a custom/simulated price.
+     * @param includeOpenOrders If true, uses the worst-case base amount (including open bids/asks) instead of the current position size. Defaults to false.
+     * @returns Precision QUOTE_PRECISION (1e6).
      */
     getPerpPositionValue(marketIndex: number, oraclePriceData: Pick<OraclePriceData, 'price'>, includeOpenOrders?: boolean): BN;
     /**
-     * calculates position liabiltiy value in margin system
-     * @returns : Precision QUOTE_PRECISION
+     * Unweighted (no margin ratio applied) perp liability notional at a
+     * caller-supplied oracle price. Returns `ZERO` (via `getPerpPositionOrEmpty`)
+     * if the user has no position in `marketIndex`.
+     * @param marketIndex
+     * @param oraclePriceData Price to value the position at, PRICE_PRECISION (1e6).
+     * @param includeOpenOrders If true, uses the worst-case (including open bids/asks) liability value; otherwise just the current position. Defaults to false.
+     * @returns Precision QUOTE_PRECISION (1e6).
      */
     getPerpLiabilityValue(marketIndex: number, oraclePriceData: OraclePriceData, includeOpenOrders?: boolean): BN;
+    /** Returns `PositionDirection.LONG`/`SHORT` from the sign of `baseAssetAmount`, or `undefined` if the position is flat. */
     getPositionSide(currentPosition: Pick<PerpPosition, 'baseAssetAmount'>): PositionDirection | undefined;
     /**
      * calculates average exit price (optionally for closing up to 100% of position)
-     * @returns : Precision PRICE_PRECISION
+     * @param position Position to estimate the close for.
+     * @param amountToClose Optional base amount (BASE_PRECISION, 1e9) to simulate closing; if omitted, closes the full position. Passing `ZERO` returns the current reserve price with zero PnL.
+     * @param useAMMClose If true, values the close against the AMM's own reserves (`calculateBaseAssetValue`) instead of the oracle-referenced value (`calculateBaseAssetValueWithOracle`). Defaults to false.
+     * @returns Tuple of `[exitPrice, pnl]` — exitPrice is PRICE_PRECISION (1e6), pnl is QUOTE_PRECISION (1e6).
      */
     getPositionEstimatedExitPriceAndPnl(position: PerpPosition, amountToClose?: BN, useAMMClose?: boolean): [BN, BN];
     /**
      * calculates current user leverage which is (total liability size) / (net asset value)
-     * @returns : Precision TEN_THOUSAND
+     * @param includeOpenOrders If true, sizes the perp liability using worst-case open-order exposure. Defaults to true.
+     * @param perpMarketIndex Optional single isolated perp market to scope leverage to (uses that position's own isolated deposit + PnL as its asset value); omit for account-wide leverage.
+     * @returns : Precision TEN_THOUSAND (1e4, i.e. `10000` = 1x leverage). `ZERO` if net asset value is zero.
      */
     getLeverage(includeOpenOrders?: boolean, perpMarketIndex?: number): BN;
+    /** Combines the components from `getLeverageComponents` into a single leverage ratio: `(perpLiability + spotLiability) / (spotAsset + perpPnl - spotLiability)`. Returns TEN_THOUSAND (1e4) precision; `ZERO` if net asset value is zero. */
     calculateLeverageFromComponents({ perpLiabilityValue, perpPnl, spotAssetValue, spotLiabilityValue, }: {
         perpLiabilityValue: BN;
         perpPnl: BN;
         spotAssetValue: BN;
         spotLiabilityValue: BN;
     }): BN;
+    /**
+     * Gathers the four raw components (`perpLiabilityValue`, `perpPnl`,
+     * `spotAssetValue`, `spotLiabilityValue`, all QUOTE_PRECISION/1e6) that
+     * `calculateLeverageFromComponents` combines into a leverage ratio.
+     *
+     * When `perpMarketIndex` is given, scopes to a single isolated position:
+     * `spotAssetValue` becomes that position's isolated quote deposit and
+     * `spotLiabilityValue` is `ZERO` (isolated positions carry no spot
+     * liability of their own). Otherwise sums across the whole account, and
+     * folds in `getTotalIsolatedPositionDeposits` as additional spot asset
+     * value when `marginCategory` is unweighted.
+     */
     getLeverageComponents(includeOpenOrders?: boolean, marginCategory?: MarginCategory | undefined, perpMarketIndex?: number): {
         perpLiabilityValue: BN;
         perpPnl: BN;
         spotAssetValue: BN;
         spotLiabilityValue: BN;
     };
+    /**
+     * Returns true if the user's deposit position in `spotMarketAccount` is
+     * non-empty but worth less than `DUST_POSITION_SIZE` (QUOTE_PRECISION) —
+     * i.e. too small to be economically worth withdrawing/settling. Only
+     * evaluates deposits (returns false for borrows or an empty position).
+     * @throws If the user has no spot position slot for the market (should not happen for a valid `SpotMarketAccount`).
+     */
     isDustDepositPosition(spotMarketAccount: SpotMarketAccount): boolean;
+    /** Returns every spot market where the user holds a dust-sized deposit; see `isDustDepositPosition`. */
     getSpotMarketAccountsWithDustPosition(): SpotMarketAccount[];
+    /**
+     * Sum of the user's total perp position liability (worst-case, open orders
+     * included) and total spot liability value (worst-case, open orders included).
+     * @param marginCategory Optional `'Initial'`/`'Maintenance'` weighting; omit for unweighted values.
+     * @returns Precision QUOTE_PRECISION (1e6), non-negative.
+     */
     getTotalLiabilityValue(marginCategory?: MarginCategory): BN;
+    /**
+     * Sum of the user's total spot asset value and total unrealized perp PnL
+     * (with funding). When `marginCategory` is omitted (unweighted), also
+     * includes `getTotalIsolatedPositionDeposits`.
+     * @param marginCategory Optional `'Initial'`/`'Maintenance'` weighting; omit for unweighted values.
+     * @returns Precision QUOTE_PRECISION (1e6), non-negative.
+     */
     getTotalAssetValue(marginCategory?: MarginCategory): BN;
+    /**
+     * Unweighted net USD value of the account: net spot market value, plus
+     * unrealized (funding-inclusive) perp PnL, plus isolated position deposits.
+     * @returns Precision QUOTE_PRECISION (1e6), can be negative.
+     */
     getNetUsdValue(): BN;
     /**
-     * Calculates the all time P&L of the user.
-     *
-     * Net withdraws + Net spot market value + Net unrealized P&L -
+     * Calculates the all-time P&L of the user: current net USD value
+     * (`getNetUsdValue`), plus lifetime total withdraws, minus lifetime total
+     * deposits. Equivalent to "everything the account is worth now, plus
+     * everything ever taken out, minus everything ever put in".
+     * @returns Precision QUOTE_PRECISION (1e6), can be negative.
      */
     getTotalAllTimePnl(): BN;
     /**
      * calculates max allowable leverage exceeding hitting requirement category
      * for large sizes where imf factor activates, result is a lower bound
-     * @param marginCategory {Initial, Maintenance}
-     * @returns : Precision TEN_THOUSAND
+     * @param marginCategory {Initial, Maintenance} — currently unused; the calculation always uses the max-tradeable-size ('Initial') buying power.
+     * @returns : Precision TEN_THOUSAND (1e4, i.e. `10000` = 1x)
      */
     getMaxLeverageForPerp(perpMarketIndex: number, _marginCategory?: MarginCategory): BN;
     /**
      * calculates max allowable leverage exceeding hitting requirement category
      * @param spotMarketIndex
-     * @param direction
-     * @returns : Precision TEN_THOUSAND
+     * @param direction Whether to simulate a long (deposit-increasing) or short (borrow-increasing) trade.
+     * @returns : Precision TEN_THOUSAND (1e4, i.e. `10000` = 1x)
      */
     getMaxLeverageForSpot(spotMarketIndex: number, direction: PositionDirection): BN;
     /**
      * calculates margin ratio: 1 / leverage
-     * @returns : Precision TEN_THOUSAND
+     * @returns : Precision TEN_THOUSAND (1e4, i.e. `10000` = 100% margin ratio / 1x leverage). Returns `BN_MAX` if the account has no liabilities.
      */
     getMarginRatio(): BN;
+    /**
+     * @deprecated Use `getLiquidationStatuses` for the full cross + per-isolated-market breakdown. This method returns only the cross-margin status (plus the same isolated map, for convenience) for backward compatibility.
+     * @returns The cross-margin `AccountLiquidatableStatus`, plus `isolatedPositions` mapping each isolated perp market index to its own status.
+     */
     canBeLiquidated(): AccountLiquidatableStatus & {
         isolatedPositions: Map<number, AccountLiquidatableStatus>;
     };
@@ -289,52 +601,125 @@ export declare class User {
      * Map keys:
      *  - 'cross' for cross margin
      *  - marketIndex (number) for each isolated perp position
+     *
+     * Each `canBeLiquidated` compares maintenance total collateral against the
+     * maintenance margin requirement for that scope. If `marginCalc` is not
+     * supplied, one is computed under `'Maintenance'` with the account's
+     * current `getLiquidationBuffer()` applied — i.e. this defaults to the same
+     * buffered check the on-chain liquidation instructions use, not a bare
+     * maintenance-margin comparison.
+     * @param marginCalc Optional pre-computed `MarginCalculation` to reuse (avoids recomputing margin across repeated calls).
      */
     getLiquidationStatuses(marginCalc?: MarginCalculation): Map<'cross' | number, AccountLiquidatableStatus>;
+    /** Returns true if cross margin or any isolated perp position is currently flagged as being liquidated or bankrupt. */
     isBeingLiquidated(): boolean;
+    /** Returns true if the account-level `UserStatus` has `BEING_LIQUIDATED` or `BANKRUPT` set (cross margin, not per-isolated-position). */
     isCrossMarginBeingLiquidated(): boolean;
     /** Returns true if cross margin is currently below maintenance requirement (no buffer). */
     canCrossMarginBeLiquidated(marginCalc?: MarginCalculation): boolean;
+    /** Returns true if any active perp position has `PositionFlag.BeingLiquidated` or `PositionFlag.Bankruptcy` set. */
     hasIsolatedPositionBeingLiquidated(): boolean;
+    /** Returns true if the specific perp position in `perpMarketIndex` has `PositionFlag.BeingLiquidated` or `PositionFlag.Bankruptcy` set. False (not throw) if the user has no position there. */
     isIsolatedPositionBeingLiquidated(perpMarketIndex: number): boolean;
     /** Returns true if any isolated perp position is currently below its maintenance requirement (no buffer). */
     getLiquidatableIsolatedPositions(marginCalc?: MarginCalculation): number[];
+    /** Returns true if `isolatedMarginCalculation`'s collateral is below its margin requirement (no buffer). */
     canIsolatedPositionMarginBeLiquidated(isolatedMarginCalculation: IsolatedMarginCalculation): boolean;
+    /** Returns true if the account's `UserStatus` bitmask has `status` set. */
     hasStatus(status: UserStatus): boolean;
+    /** Returns true if the account's `UserStatus` has `BANKRUPT` set (equity insufficient to cover liabilities; awaiting bankruptcy resolution). */
     isBankrupt(): boolean;
     /**
      * Checks if any user position cumulative funding differs from respective market cumulative funding
-     * @returns
+     * @returns True if at least one non-flat perp position has stale `lastCumulativeFundingRate` relative to the market's current long/short cumulative funding rate.
      */
     needsToSettleFundingPayment(): boolean;
     /**
-     * Calculate the liquidation price of a spot position
-     * @param marketIndex
-     * @returns Precision : PRICE_PRECISION
+     * Calculate the liquidation price of a spot position — the oracle price at
+     * which maintenance free collateral would hit zero, extrapolating linearly
+     * from the current free collateral and the position's per-unit-price
+     * sensitivity (`calculateFreeCollateralDeltaForSpot`). If a perp market
+     * shares the same oracle as this spot market, that perp position's
+     * sensitivity is folded in too (scaled for any oracle-source unit
+     * difference), since a single price move affects both simultaneously.
+     * @param marketIndex Spot market to compute the liquidation price for.
+     * @param positionBaseSizeChange Optional simulated change to the position size, in the spot market's own token decimals. Defaults to no change.
+     * @returns Precision PRICE_PRECISION (1e6). Returns `new BN(-1)` as a sentinel when there is no position, the position (after `positionBaseSizeChange`) is flat, the price sensitivity is zero, or the computed liquidation price would be negative (position cannot be liquidated by a price move alone).
      */
     spotLiquidationPrice(marketIndex: number, positionBaseSizeChange?: BN): BN;
     /**
-     * Calculate the liquidation price of a perp position, with optional parameter to calculate the liquidation price after a trade
+     * Calculate the liquidation price of a perp position, with optional parameter to calculate the liquidation price after a trade.
+     *
+     * Like `spotLiquidationPrice`, this extrapolates linearly from current free
+     * collateral (`totalCollateral - marginRequirement`, plus `offsetCollateral`)
+     * and the position's price sensitivity; if a spot market shares the same
+     * oracle, its sensitivity is folded in too. When `marginType === 'Isolated'`,
+     * free collateral and the margin requirement are scoped to that market's
+     * isolated bucket instead of the cross-margin account (and the spot-oracle
+     * cross-contribution above is skipped).
      * @param marketIndex
-     * @param positionBaseSizeChange // change in position size to calculate liquidation price for : Precision 10^9
-     * @param estimatedEntryPrice
-     * @param marginCategory // allow Initial to be passed in if we are trying to calculate price for DLP de-risking
-     * @param includeOpenOrders
-     * @param offsetCollateral // allows calculating the liquidation price after this offset collateral is added to the user's account (e.g. : what will the liquidation price be for this position AFTER I deposit $x worth of collateral)
-     * @returns Precision : PRICE_PRECISION
+     * @param positionBaseSizeChange Change in position size to calculate the liquidation price for, standardized to the market's order step size. Precision BASE_PRECISION (1e9).
+     * @param estimatedEntryPrice Entry price for `positionBaseSizeChange`, PRICE_PRECISION (1e6); only affects the result under `marginCategory: 'Maintenance'` (it adjusts free collateral for the estimated realized PnL and taker fee of entering at this price rather than at the oracle price).
+     * @param marginCategory Allow `'Initial'` to be passed in if we are trying to calculate price for DLP de-risking. Defaults to `'Maintenance'` (the actual liquidation threshold).
+     * @param includeOpenOrders Include open orders' worst-case exposure when sizing the position. Defaults to false.
+     * @param offsetCollateral Allows calculating the liquidation price after this offset collateral (QUOTE_PRECISION, 1e6) is added to the user's account (e.g. : what will the liquidation price be for this position AFTER I deposit $x worth of collateral). Defaults to zero.
+     * @param marginType `'Isolated'` to scope the calculation to `marketIndex`'s isolated margin bucket; omit/`'Cross'` for the cross-margin account.
+     * @returns Precision : PRICE_PRECISION (1e6). Returns `new BN(-1)` as a sentinel when there is no isolated margin calculation for the market (isolated mode), the price sensitivity is zero, or the computed price would be negative (position cannot be liquidated by a price move alone).
      */
     liquidationPrice(marketIndex: number, positionBaseSizeChange?: BN, estimatedEntryPrice?: BN, marginCategory?: MarginCategory, includeOpenOrders?: boolean, offsetCollateral?: BN, marginType?: MarginType): BN;
+    /**
+     * Helper for `liquidationPrice`: estimates the net change to free collateral
+     * from simultaneously (a) realizing PnL on `positionBaseSizeChange` entered
+     * at `estimatedEntryPrice` (assuming the worst/taker fee tier) versus the
+     * oracle price, and (b) the resulting change in margin requirement from the
+     * new position size. Only component (a) applies under `'Maintenance'`
+     * (matching `liquidationPrice`'s default); under other margin categories
+     * only the margin-requirement delta is applied.
+     * @returns Precision QUOTE_PRECISION (1e6); can be negative.
+     */
     calculateEntriesEffectOnFreeCollateral(market: PerpMarketAccount, oraclePrice: BN, perpPosition: PerpPosition, positionBaseSizeChange: BN, estimatedEntryPrice: BN, includeOpenOrders: boolean, marginCategory?: MarginCategory): BN;
+    /**
+     * Helper for `liquidationPrice`: the derivative of free collateral with
+     * respect to the perp market's oracle price, for the proposed post-trade
+     * position (`positionBaseSizeChange` applied to the current, or worst-case
+     * if `includeOpenOrders`, base amount). Used as the linear-extrapolation
+     * slope to solve for the price at which free collateral hits zero.
+     * @returns Precision QUOTE_PRECISION (1e6) per unit of PRICE_PRECISION move, or `undefined` if the proposed position is flat (no defined liquidation price).
+     */
     calculateFreeCollateralDeltaForPerp(market: PerpMarketAccount, perpPosition: PerpPosition, positionBaseSizeChange: BN, oraclePrice: BN, marginCategory?: MarginCategory, includeOpenOrders?: boolean): BN | undefined;
+    /**
+     * Helper for `spotLiquidationPrice`/`liquidationPrice`: the derivative of
+     * free collateral with respect to the spot market's oracle price, for a
+     * position of `signedTokenAmount` (positive = deposit, negative = borrow).
+     * @returns Precision QUOTE_PRECISION (1e6) per unit of PRICE_PRECISION move.
+     */
     calculateFreeCollateralDeltaForSpot(market: SpotMarketAccount, signedTokenAmount: BN, marginCategory?: MarginCategory): BN;
     /**
      * Calculates the estimated liquidation price for a position after closing a quote amount of the position.
      * @param positionMarketIndex
-     * @param closeQuoteAmount
-     * @returns : Precision PRICE_PRECISION
+     * @param closeQuoteAmount Quote-denominated amount of the position to close, QUOTE_PRECISION (1e6). Converted proportionally to a base-size reduction via the position's current cost basis.
+     * @param estimatedEntryPrice Forwarded to `liquidationPrice` as the entry price for the (negative, i.e. closing) size change. PRICE_PRECISION (1e6). Defaults to zero.
+     * @returns : Precision PRICE_PRECISION (1e6). See `liquidationPrice` for the `-1` sentinel cases.
      */
     liquidationPriceAfterClose(positionMarketIndex: number, closeQuoteAmount: BN, estimatedEntryPrice?: BN): BN;
+    /**
+     * Calculates the margin required to open a trade of `baseSize` in `targetMarketIndex`, scalar only — does not account for trade direction or existing positions/whether the trade is actually risk-increasing.
+     * @param baseSize BASE_PRECISION (1e9).
+     * @param estEntryPrice Optional entry price to value the trade at, PRICE_PRECISION (1e6); defaults to the oracle price.
+     * @param perpMarketMaxMarginRatio Optional max-margin-ratio override, see `resolveMaxMarginRatio`.
+     * @returns Precision QUOTE_PRECISION (1e6).
+     */
     getMarginUSDCRequiredForTrade(targetMarketIndex: number, baseSize: BN, estEntryPrice?: BN, perpMarketMaxMarginRatio?: number): BN;
+    /**
+     * Converts `getMarginUSDCRequiredForTrade`'s USDC margin requirement into
+     * how much of `collateralIndex`'s token a user would need to deposit to
+     * cover it, accounting for that collateral's scaled initial asset weight
+     * (a lower-weighted asset requires proportionally more deposited).
+     * @param baseSize BASE_PRECISION (1e9).
+     * @param collateralIndex Spot market to size the deposit in.
+     * @param perpMarketMaxMarginRatio Optional max-margin-ratio override, see `resolveMaxMarginRatio`.
+     * @returns Token amount in `collateralIndex`'s own decimals.
+     */
     getCollateralDepositRequiredForTrade(targetMarketIndex: number, baseSize: BN, collateralIndex: number, perpMarketMaxMarginRatio?: number): BN;
     /**
      * Separates the max trade size into two parts:
@@ -342,7 +727,9 @@ export declare class User {
      * - oppositeSideTradeSize: the trade size for closing the opposite direction
      * @param targetMarketIndex
      * @param tradeSide
-     * @returns { tradeSize: BN, oppositeSideTradeSize: BN} : Precision QUOTE_PRECISION
+     * @param maxMarginRatio Optional max-margin-ratio override, see `resolveMaxMarginRatio`.
+     * @param positionType Whether to size for a cross or isolated-margin position (forwarded to `getPerpBuyingPower`). Defaults to `'cross'`.
+     * @returns { tradeSize: BN, oppositeSideTradeSize: BN} : Precision QUOTE_PRECISION (1e6)
      */
     getMaxTradeSizeUSDCForPerp(targetMarketIndex: number, tradeSide: PositionDirection, maxMarginRatio?: number | undefined, positionType?: 'isolated' | 'cross'): {
         tradeSize: BN;
@@ -352,10 +739,10 @@ export declare class User {
      * Get the maximum trade size for a given market, taking into account the user's current leverage, positions, collateral, etc.
      *
      * @param targetMarketIndex
-     * @param direction
-     * @param currentQuoteAssetValue
-     * @param currentSpotMarketNetValue
-     * @returns tradeSizeAllowed : Precision QUOTE_PRECISION
+     * @param direction Long (increase deposit / reduce borrow) or short (increase borrow / reduce deposit).
+     * @param currentQuoteAssetValue Ignored — always recomputed internally from `getSpotMarketAssetValue(QUOTE_SPOT_MARKET_INDEX)`.
+     * @param currentSpotMarketNetValue Optional pre-computed net value for `targetMarketIndex` (QUOTE_PRECISION, 1e6); if omitted, computed via `getSpotPositionValue`.
+     * @returns tradeSizeAllowed : Precision QUOTE_PRECISION (1e6)
      */
     getMaxTradeSizeUSDCForSpot(targetMarketIndex: number, direction: PositionDirection, currentQuoteAssetValue?: BN, currentSpotMarketNetValue?: BN): BN;
     /**
@@ -364,8 +751,9 @@ export declare class User {
      *
      * @param inMarketIndex
      * @param outMarketIndex
-     * @param calculateSwap function to similate in to out swa
-     * @param iterationLimit how long to run appromixation before erroring out
+     * @param calculateSwap Optional function to simulate the in-to-out conversion (e.g. to model swap fees/slippage); defaults to a 1:1 oracle-price conversion.
+     * @param iterationLimit How many binary-search iterations to run before erroring out. Defaults to 1000.
+     * @returns `inAmount`/`outAmount` in each market's own token decimals, and the resulting `leverage` (TEN_THOUSAND, 1e4 precision) after the swap.
      */
     getMaxSwapAmount({ inMarketIndex, outMarketIndex, calculateSwap, iterationLimit, }: {
         inMarketIndex: number;
@@ -377,18 +765,28 @@ export declare class User {
         outAmount: BN;
         leverage: BN;
     };
+    /**
+     * Returns a cloned `SpotPosition` with `tokenAmount` (signed, positive =
+     * deposit / negative = borrow) applied on top of the existing balance —
+     * used to simulate the post-trade/post-swap position without mutating the
+     * cached account.
+     * @param tokenAmount Signed delta in `market`'s own token decimals.
+     */
     cloneAndUpdateSpotPosition(position: SpotPosition, tokenAmount: BN, market: SpotMarketAccount): SpotPosition;
+    /** Worst-case free-collateral contribution (under `'Initial'` margin) of a single spot position. Returns QUOTE_PRECISION (1e6). */
     calculateSpotPositionFreeCollateralContribution(spotPosition: SpotPosition, strictOraclePrice: StrictOraclePrice): BN;
+    /** Worst-case (under `'Initial'` margin) asset/liability value split of a single spot position, for use in leverage calculations. Both fields QUOTE_PRECISION (1e6), non-negative. */
     calculateSpotPositionLeverageContribution(spotPosition: SpotPosition, strictOraclePrice: StrictOraclePrice): {
         totalAssetValue: BN;
         totalLiabilityValue: BN;
     };
     /**
      * Estimates what the user leverage will be after swap
-     * @param inMarketIndex
-     * @param outMarketIndex
-     * @param inAmount
-     * @param outAmount
+     * @param inMarketIndex Market being sold/paid from.
+     * @param outMarketIndex Market being bought/received.
+     * @param inAmount Amount removed from `inMarketIndex`, that market's own token decimals.
+     * @param outAmount Amount added to `outMarketIndex`, that market's own token decimals.
+     * @returns Precision TEN_THOUSAND (1e4, i.e. `10000` = 1x).
      */
     accountLeverageAfterSwap({ inMarketIndex, outMarketIndex, inAmount, outAmount, }: {
         inMarketIndex: number;
@@ -399,42 +797,146 @@ export declare class User {
     /**
      * Returns the leverage ratio for the account after adding (or subtracting) the given quote size to the given position
      * @param targetMarketIndex
-     * @param: targetMarketType
-     * @param tradeQuoteAmount
-     * @param tradeSide
-     * @param includeOpenOrders
-     * @returns leverageRatio : Precision TEN_THOUSAND
+     * @param targetMarketType Whether the trade is on a perp or spot market — the two use different valuation paths.
+     * @param tradeQuoteAmount Quote size of the simulated trade, QUOTE_PRECISION (1e6).
+     * @param tradeSide Direction of the simulated trade.
+     * @param includeOpenOrders Include existing open orders' worst-case impact in both the before/after values. Defaults to true.
+     * @returns leverageRatio : Precision TEN_THOUSAND (1e4, i.e. `10000` = 1x)
      */
     accountLeverageRatioAfterTrade(targetMarketIndex: number, targetMarketType: MarketType, tradeQuoteAmount: BN, tradeSide: PositionDirection, includeOpenOrders?: boolean): BN;
+    /**
+     * Looks up the user's fee tier from the state account's fee structure.
+     *
+     * For perp markets, the tier is selected by the user's rolling 30-day
+     * volume (`getUser30dRollingVolumeEstimate`, QUOTE_PRECISION) against fixed
+     * breakpoints — $2M, $10M, $20M, $80M, $200M — picking the lowest-index
+     * tier whose breakpoint the user's volume is still under (tier 5, the
+     * lowest fees, if volume meets or exceeds the top breakpoint). Spot markets
+     * always use tier 0 (no volume-based discount).
+     * @param marketType `MarketType.PERP` or `MarketType.SPOT`.
+     * @param now Optional unix timestamp (seconds) to evaluate the rolling volume window as of; defaults to current time.
+     * @returns The matching `FeeTier` (numerator/denominator fee fractions and referee-discount fractions).
+     */
     getUserFeeTier(marketType: MarketType, now?: BN): import("./types").FeeTier;
     /**
-     * Calculates how much perp fee will be taken for a given sized trade
-     * @param quoteAmount
-     * @returns feeForQuote : Precision QUOTE_PRECISION
+     * Calculates how much perp fee will be taken for a given sized trade.
+     *
+     * When `marketIndex` is provided, delegates to `VelocityClient.getMarketFees`
+     * for that specific market's taker-fee multiplier (which itself applies the
+     * market's `feeAdjustment`, the referee discount, and — when `builderInfo` is
+     * passed — the builder fee). Otherwise uses the volume-based fee tier from
+     * `getUserFeeTier(MarketType.PERP)`; if the user is a referee (determined
+     * from `UserStats.referrerStatus`'s `IsReferred` flag unless `isReferee` is
+     * explicitly passed), the tier's `refereeFeeNumerator`/`refereeFeeDenominator`
+     * proportion is subtracted from the fee as a discount, and — when `builderInfo`
+     * carries a builder code — the builder fee (`quoteAmount * builderFeeTenthBps /
+     * 100_000`) is added on top, mirroring the program's `builder_fee` (`math/fees.rs`).
+     * @param quoteAmount Trade size, QUOTE_PRECISION (1e6).
+     * @param marketIndex Optional perp market to use `VelocityClient.getMarketFees` for instead of the volume-tier fee structure.
+     * @param isReferee Optional override for whether the referee discount applies; defaults to the user's actual `UserStats` referred status. Ignored on the `marketIndex` path (which reads referee status inside `getMarketFees`).
+     * @param builderInfo Optional builder code; when it carries `builderIdx` + `builderFeeTenthBps`, the builder fee is added on top of the tiered fee.
+     * @returns feeForQuote : Precision QUOTE_PRECISION (1e6)
      */
-    calculateFeeForQuoteAmount(quoteAmount: BN, marketIndex?: number): BN;
+    calculatePerpTakerFee(quoteAmount: BN, marketIndex?: number, isReferee?: boolean, builderInfo?: Pick<OrderParams, 'builderIdx' | 'builderFeeTenthBps'>): BN;
     /**
      * Calculates a user's max withdrawal amounts for a spot market. If reduceOnly is true,
-     * it will return the max withdrawal amount without opening a liability for the user
+     * it will return the max withdrawal amount without opening a liability for the user.
+     *
+     * Combines three caps: the market-wide withdraw/borrow guard
+     * (`calculateWithdrawLimit`, a rolling-window rate limit on the spot
+     * market), the user's own deposit balance, and how much their free
+     * collateral supports withdrawing/borrowing. If `canBypassWithdrawLimits`
+     * returns `canBypass: true` (see that method), the market-wide withdraw
+     * limit floor is raised to the user's full deposit amount — letting a
+     * small, healthy, always-net-positive depositor withdraw in full even if
+     * the market-wide guard would otherwise throttle them.
      * @param marketIndex
+     * @param reduceOnly If true, caps the result so the withdrawal cannot open a borrow (never exceeds the user's current deposit). If false/omitted, may return an amount larger than the deposit, up to the user's max allowed new liability.
      * @returns withdrawalLimit : Precision is the token precision for the chosen SpotMarket
      */
     getWithdrawalLimit(marketIndex: number, reduceOnly?: boolean): BN;
+    /**
+     * Determines whether the user can bypass the spot market's rolling
+     * withdraw-guard limit for `marketIndex`. `canBypass` is true only when
+     * **all** of the following hold:
+     *   - The user currently holds a deposit (not a borrow) in the market.
+     *   - Their lifetime net deposits (`totalDeposits - totalWithdraws`) are
+     *     non-negative — they have never net-withdrawn more than they net-deposited.
+     *   - Their `cumulativeDeposits` for the position has never gone negative
+     *     (no history of having borrowed and repaid in this market).
+     *   - Their current deposit amount is below `maxDepositAmount`, i.e. 10% of
+     *     the spot market's `withdrawGuardThreshold`.
+     *
+     * This lets a small, well-behaved depositor withdraw their own funds in
+     * full even while the market-wide withdraw guard is actively throttling
+     * larger movements. Used by `getWithdrawalLimit`.
+     * @param marketIndex
+     * @returns `canBypass`; `netDeposits` (lifetime `totalDeposits - totalWithdraws`, QUOTE_PRECISION, 1e6); `depositAmount` and `maxDepositAmount`, both in the spot market's own token decimals.
+     */
     canBypassWithdrawLimits(marketIndex: number): {
         canBypass: boolean;
         netDeposits: BN;
         depositAmount: BN;
         maxDepositAmount: BN;
     };
+    /**
+     * Determines whether the user can be marked idle (excluded from userMap
+     * subscriptions by default, and skipped by most keeper crank passes) as of
+     * `slot`. Requires: not already idle; inactive for the required window
+     * since `lastActiveSlot` (1 hour / 9,000 slots if equity is under $1,000,
+     * otherwise 1 week / 1,512,000 slots); not currently being liquidated; and
+     * no open perp positions, borrows, spot open orders, or open orders of any kind.
+     * @param slot Current slot to evaluate inactivity against.
+     */
     canMakeIdle(slot: BN): boolean;
+    /**
+     * Determines whether this `User` (sub)account can be deleted (checked
+     * before sending a delete-user instruction, to give a friendlier error than
+     * an on-chain revert). Returns `canDelete: false` with a `reason` string if
+     * any of the following hold: it's a referrer's sub-account 0 (referrers
+     * cannot delete their primary account); the account is bankrupt or being
+     * liquidated; it has any non-empty perp/spot position or open order; or
+     * (when the state account charges an initialize-user fee) the account is a
+     * "fresh" account — younger than `ACCOUNT_AGE_DELETION_CUTOFF_SECONDS`,
+     * measured from its earliest recorded filler/maker/taker volume timestamp —
+     * that is not currently idle.
+     * @param userStatsAccount Optional pre-fetched `UserStatsAccount`; defaults to `VelocityClient.getUserStatsOrThrow().getAccount()`.
+     * @param now Optional unix timestamp (seconds) to evaluate account age against; defaults to current time.
+     */
     canBeDeleted(userStatsAccount?: UserStatsAccount, now?: BN): {
         canDelete: boolean;
         reason?: string;
     };
+    /**
+     * Returns the numerically-lowest (i.e. safest) contract/asset tier across
+     * the user's active positions — perp tiers from active perp positions,
+     * spot tiers only from spot **borrows** (deposits are skipped, since asset
+     * tier only restricts borrowing exposure). Defaults to `4` (the
+     * second-riskiest tier index) when the user has no positions of that kind —
+     * this is a permissive default intended for callers doing tier-safety
+     * comparisons (see `perpTierIsAsSafeAs` in `math/tiers`), not a claim that
+     * "no position" is itself a risky tier.
+     * @returns Lower `perpTier`/`spotTier` numbers indicate a safer tier; see `math/tiers` (`getPerpMarketTierNumber`/`getSpotMarketTierNumber`) for the numbering.
+     */
     getSafestTiers(): {
         perpTier: number;
         spotTier: number;
     };
+    /**
+     * Breaks down a single perp position's contribution to the margin system
+     * as a `HealthComponent`: worst-case base size, its unweighted liability
+     * value, the applicable margin ratio (`weight`), and the resulting
+     * weighted margin requirement (`weightedValue`, which includes the
+     * position's open-order margin add-on). Used to build up
+     * `getHealthComponents`' `perpPositions` array (e.g. for UI breakdowns of
+     * "what's consuming my margin").
+     * @param marginCategory `'Initial'` or `'Maintenance'`.
+     * @param perpPosition Position to evaluate.
+     * @param oraclePriceData Optional oracle price override for the perp market; defaults to the live oracle price.
+     * @param quoteOraclePriceData Optional oracle price override for the quote spot market; defaults to the live oracle price.
+     * @param includeOpenOrders Include worst-case open-order exposure. Defaults to true.
+     * @returns `size` is BASE_PRECISION (1e9); `value`/`weightedValue` are QUOTE_PRECISION (1e6); `weight` is MARGIN_PRECISION (1e4).
+     */
     getPerpPositionHealth({ marginCategory, perpPosition, oraclePriceData, quoteOraclePriceData, includeOpenOrders, }: {
         marginCategory: MarginCategory;
         perpPosition: PerpPosition;
@@ -442,6 +944,18 @@ export declare class User {
         quoteOraclePriceData?: OraclePriceData;
         includeOpenOrders?: boolean;
     }): HealthComponent;
+    /**
+     * Builds a full breakdown of every component feeding into the user's
+     * margin calculation, for UI/diagnostic display: `deposits` and `borrows`
+     * (one `HealthComponent` per non-quote spot market with a nonzero
+     * worst-case position, plus a synthetic entry for the net quote balance),
+     * `perpPositions` (via `getPerpPositionHealth`, one per active perp
+     * position), and `perpPnl` (each position's weighted unrealized PnL — see
+     * `getUnrealizedPNL` for the `'Initial'`-margin $100 cap that also applies
+     * here).
+     * @param marginCategory `'Initial'` or `'Maintenance'` — determines which asset/liability weights are applied.
+     * @returns `HealthComponents` with `size`/`value`/`weightedValue` in each entry using the same precisions as `getPerpPositionHealth`.
+     */
     getHealthComponents({ marginCategory, }: {
         marginCategory: MarginCategory;
     }): HealthComponents;
@@ -456,6 +970,7 @@ export declare class User {
     private getOracleDataForSpotMarket;
     /**
      * Get the active perp and spot positions of the user.
+     * @returns Market indices only (not full position objects); see `getActivePerpPositions`/`getActiveSpotPositions` for the "active" criteria.
      */
     getActivePositions(): {
         activePerpPositions: number[];
@@ -465,11 +980,57 @@ export declare class User {
      * Compute the full margin calculation for the user's account.
      * Prioritize using this function instead of calling getMarginRequirement or getTotalCollateral multiple times.
      * Consumers can use this to avoid duplicating work across separate calls.
+     *
+     * Mirrors the on-chain margin accumulation in `math/margin.rs`, splitting
+     * contributions into cross-margin and per-market isolated buckets
+     * (`MarginCalculation.isolatedMarginCalculations`, keyed by perp market
+     * index — see `isPerpPositionIsolated`) and tracking whether the account
+     * holds any isolated-tier liability (`withPerpIsolatedLiability` /
+     * `withSpotIsolatedLiability`, consumed by
+     * `validateAnyIsolatedTierRequirements`). A perp position's isolated
+     * quote-deposit collateral only counts toward that position's own isolated
+     * bucket, never the cross-margin total.
+     *
+     * Also enforces pool-id consistency: every spot/perp position's market must
+     * match the user's `poolId`, **except** a pool-1 user is allowed to hold a
+     * quote-asset deposit (not borrow) even though the quote spot market itself
+     * belongs to pool 0 — throws `InvalidPoolId: ...` otherwise.
+     * @param marginCategory `'Initial'` or `'Maintenance'`. Defaults to `'Initial'`.
+     * @param opts.strict Apply TWAP-bounded (`StrictOraclePrice`) oracle pricing, mirroring the on-chain strict-price gating. Defaults to false.
+     * @param opts.includeOpenOrders Include open orders' worst-case impact. Defaults to true.
+     * @param opts.liquidationBufferMap Per-scope buffer (MARGIN_PRECISION, 1e4) to pad margin requirements with — `'cross'` for the cross-margin bucket, or a perp market index for that market's isolated bucket. See `getLiquidationBuffer`.
      */
     getMarginCalculation(marginCategory?: MarginCategory, opts?: {
         strict?: boolean;
         includeOpenOrders?: boolean;
         liquidationBufferMap?: Map<number | 'cross', BN>;
     }): MarginCalculation;
+    /**
+     * Returns true if `perpPosition` was opened/is held under isolated margin
+     * (`PositionFlag.IsolatedPosition` set) — segregated to its own margin
+     * bucket (see `getMarginCalculation`) rather than sharing cross-margin
+     * collateral with the rest of the account.
+     */
     isPerpPositionIsolated(perpPosition: PerpPosition): boolean;
+    /**
+     * Pre-flight check for `IsolatedAssetTierViolation`: mirrors
+     * `validate_any_isolated_tier_requirements` in `math/margin.rs`. A user
+     * holding an isolated-tier perp or spot liability may not simultaneously
+     * carry other liabilities (besides a single usdc borrow, for a perp
+     * isolated liability), unless they are reduce-only.
+     *
+     * Specifically, if `calculation.withPerpIsolatedLiability` is set (an
+     * isolated-*contract-tier* perp liability exists) and the user is not
+     * `UserStatus.REDUCE_ONLY`: more than one perp liability is invalid; margin
+     * trading enabled is invalid; and any spot liability other than a single
+     * USDC borrow is invalid. If `calculation.withSpotIsolatedLiability` is set
+     * (an isolated-*asset-tier* spot liability exists) and not reduce-only: any
+     * perp liability, or more than the one isolated-tier spot liability, is invalid.
+     * @param calculation A `MarginCalculation` from `getMarginCalculation` (any margin category — only the isolated-liability flags and liability counts are read).
+     * @returns `{ valid: true }` if the account satisfies isolated-tier requirements, else `{ valid: false, reason }` with a human-readable reason.
+     */
+    validateAnyIsolatedTierRequirements(calculation: MarginCalculation): {
+        valid: boolean;
+        reason?: string;
+    };
 }