@velocity-exchange/sdk 0.3.0 → 0.4.0

package/lib/node/user.js

@@ -16,6 +16,7 @@ const spotBalance_1 = require("./math/spotBalance");
 const trade_1 = require("./math/trade");
 const types_2 = require("./types");
 const orders_1 = require("./math/orders");
+const builder_1 = require("./math/builder");
 const websocketProgramUserAccountSubscriber_1 = require("./accounts/websocketProgramUserAccountSubscriber");
 const spotBalance_2 = require("./math/spotBalance");
 const margin_2 = require("./math/margin");
@@ -27,13 +28,35 @@ const tiers_1 = require("./math/tiers");
 const strictOraclePrice_1 = require("./oracles/strictOraclePrice");
 const grpcUserAccountSubscriber_1 = require("./accounts/grpcUserAccountSubscriber");
 const marginCalculation_1 = require("./marginCalculation");
+/**
+ * Ports `get_proportion_u128` (math/helpers.rs) for the referee fee discount
+ * calculation. The Rust version routes large operands through a wider U192
+ * type purely to avoid u128 overflow; BN has no such ceiling, so that branch
+ * is elided here since it produces the same numeric result.
+ */
+function getProportion128(value, numerator, denominator) {
+    if (numerator.eq(denominator)) {
+        return value;
+    }
+    if (numerator.gt(denominator.div(numericConstants_1.TWO)) && denominator.gt(numerator)) {
+        // ceiling division, mirroring standardize_value_with_remainder_i128
+        const scaled = value.mul(denominator.sub(numerator));
+        const remainder = scaled.mod(denominator);
+        const floorDiv = scaled.div(denominator);
+        const ceilDiv = remainder.isZero() ? floorDiv : floorDiv.add(numericConstants_1.ONE);
+        return value.sub(ceilDiv);
+    }
+    return value.mul(numerator).div(denominator);
+}
 class User {
+    /** True only when both `subscribe()` has completed and the underlying `accountSubscriber` itself reports subscribed. */
     get isSubscribed() {
         return this._isSubscribed && this.accountSubscriber.isSubscribed;
     }
     set isSubscribed(val) {
         this._isSubscribed = val;
     }
+    /** 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) {
         var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
         this._isSubscribed = false;
@@ -74,19 +97,22 @@ class User {
         this.eventEmitter = this.accountSubscriber.eventEmitter;
     }
     /**
-     * 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.
      */
     async subscribe(userAccount) {
         this.isSubscribed = await this.accountSubscriber.subscribe(userAccount);
         return this.isSubscribed;
     }
-    /**
-     *	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). */
     async fetchAccounts() {
         await this.accountSubscriber.fetch();
     }
+    /** Removes all event listeners and tears down the account subscription. */
     async unsubscribe() {
         this.eventEmitter.removeAllListeners();
         await this.accountSubscriber.unsubscribe();
@@ -96,7 +122,7 @@ class User {
      * 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
@@ -108,13 +134,14 @@ class User {
         return (_a = this.accountSubscriber.getUserAccountAndSlot()) === null || _a === void 0 ? void 0 : _a.data;
     }
     /**
-     * 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() {
         const userAccount = this.getUserAccount();
@@ -123,16 +150,27 @@ class User {
         }
         return 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.
+     */
     async forceGetUserAccount() {
         await this.fetchAccounts();
         const account = this.accountSubscriber.getUserAccountAndSlot();
         return account === null || account === void 0 ? void 0 : account.data;
     }
+    /**
+     * Returns the cached user account together with the slot at which it was
+     * last observed. Same `undefined`/`NotSubscribedError` contract as `getUserAccount`.
+     */
     getUserAccountAndSlot() {
         return this.accountSubscriber.getUserAccountAndSlot();
     }
     /**
-     * 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.)
@@ -140,6 +178,16 @@ class User {
     getUserAccountAndSlotOrThrow() {
         return (0, utils_1.assertDataAndSlot)(this.accountSubscriber.getUserAccountAndSlot(), `User account not found: ${this.getUserAccountPublicKey().toString()}`);
     }
+    /**
+     * 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, marketIndex) {
         return this.getActivePerpPositionsForUserAccount(userAccount).find((position) => position.marketIndex === marketIndex);
     }
@@ -152,11 +200,21 @@ class User {
         const userAccount = this.getUserAccountOrThrow();
         return this.getPerpPositionForUserAccount(userAccount, marketIndex);
     }
+    /**
+     * 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) {
         var _a;
         const userAccount = this.getUserAccountOrThrow();
         return ((_a = this.getPerpPositionForUserAccount(userAccount, marketIndex)) !== null && _a !== void 0 ? _a : this.getEmptyPosition(marketIndex));
     }
+    /**
+     * Like `getPerpPosition`, but throws instead of returning `undefined` when
+     * the user has no active position in `marketIndex`.
+     */
     getPerpPositionOrThrow(marketIndex) {
         const position = this.getPerpPosition(marketIndex);
         if (!position) {
@@ -164,6 +222,10 @@ class User {
         }
         return position;
     }
+    /**
+     * Like `getPerpPosition`, but also returns the slot at which the underlying
+     * `UserAccount` was observed.
+     */
     getPerpPositionAndSlot(marketIndex) {
         const userAccount = this.getUserAccountAndSlotOrThrow();
         const perpPosition = this.getPerpPositionForUserAccount(userAccount.data, marketIndex);
@@ -172,6 +234,14 @@ class User {
             slot: userAccount.slot,
         };
     }
+    /**
+     * 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, marketIndex) {
         return userAccount.spotPositions.find((position) => position.marketIndex === marketIndex);
     }
@@ -184,6 +254,10 @@ class User {
         const userAccount = this.getUserAccountOrThrow();
         return this.getSpotPositionForUserAccount(userAccount, marketIndex);
     }
+    /**
+     * Like `getSpotPosition`, but also returns the slot at which the underlying
+     * `UserAccount` was observed.
+     */
     getSpotPositionAndSlot(marketIndex) {
         const userAccount = this.getUserAccountAndSlotOrThrow();
         const spotPosition = this.getSpotPositionForUserAccount(userAccount.data, marketIndex);
@@ -192,6 +266,7 @@ class User {
             slot: userAccount.slot,
         };
     }
+    /** Returns a zeroed-out (no deposit/borrow) placeholder `SpotPosition` for `marketIndex`. */
     getEmptySpotPosition(marketIndex) {
         return {
             marketIndex,
@@ -208,6 +283,7 @@ class User {
      * 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) {
         const spotPosition = this.getSpotPosition(marketIndex);
@@ -217,6 +293,7 @@ class User {
         const spotMarket = this.velocityClient.getSpotMarketAccountOrThrow(marketIndex);
         return (0, spotBalance_1.getSignedTokenAmount)((0, spotBalance_2.getTokenAmount)(spotPosition.scaledBalance, spotMarket, spotPosition.balanceType), spotPosition.balanceType);
     }
+    /** Returns a zeroed-out placeholder `PerpPosition` for `marketIndex` (no size, no orders, cross margin). */
     getEmptyPosition(marketIndex) {
         return {
             baseAssetAmount: numericConstants_1.ZERO,
@@ -235,9 +312,18 @@ class User {
             positionFlag: 0,
         };
     }
+    /** Returns true if `position` has no size and no open orders (a market slot that can be treated as unused). */
     isPositionEmpty(position) {
         return position.baseAssetAmount.eq(numericConstants_1.ZERO) && position.openOrders === 0;
     }
+    /**
+     * 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) {
         var _a;
         const perpPosition = this.getPerpPosition(perpMarketIndex);
@@ -253,6 +339,7 @@ class User {
     }
     /**
      * Returns the total USD value of deposits across all isolated perp positions.
+     * @returns Precision QUOTE_PRECISION (1e6).
      */
     getTotalIsolatedPositionDeposits() {
         return this.getActivePerpPositions().reduce((total, perpPosition) => {
@@ -268,21 +355,25 @@ class User {
             return total.add((0, spotBalance_1.getStrictTokenValue)(tokenAmount, quoteSpotMarket.decimals, strictOracle));
         }, numericConstants_1.ZERO);
     }
+    /** Returns a shallow copy of `position`. Mutating the clone does not affect the cached account. */
     getClonedPosition(position) {
         const clonedPosition = Object.assign({}, position);
         return clonedPosition;
     }
+    /** Finds an order by its program-assigned `orderId` on an explicit `userAccount` snapshot. */
     getOrderForUserAccount(userAccount, orderId) {
         return userAccount.orders.find((order) => order.orderId === orderId);
     }
     /**
+     * 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) {
         const userAccount = this.getUserAccountOrThrow();
         return this.getOrderForUserAccount(userAccount, orderId);
     }
+    /** Like `getOrder`, but also returns the slot at which the underlying `UserAccount` was observed. */
     getOrderAndSlot(orderId) {
         const userAccount = this.getUserAccountAndSlotOrThrow();
         const order = this.getOrderForUserAccount(userAccount.data, orderId);
@@ -291,17 +382,25 @@ class User {
             slot: userAccount.slot,
         };
     }
+    /**
+     * 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, userOrderId) {
         return userAccount.orders.find((order) => order.userOrderId === userOrderId);
     }
     /**
+     * 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) {
         const userAccount = this.getUserAccountOrThrow();
         return this.getOrderByUserIdForUserAccount(userAccount, userOrderId);
     }
+    /** Like `getOrderByUserOrderId`, but also returns the slot at which the underlying `UserAccount` was observed. */
     getOrderByUserOrderIdAndSlot(userOrderId) {
         const userAccount = this.getUserAccountAndSlotOrThrow();
         const order = this.getOrderByUserIdForUserAccount(userAccount.data, userOrderId);
@@ -310,14 +409,21 @@ class User {
             slot: userAccount.slot,
         };
     }
+    /**
+     * 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) {
         return userAccount === null || userAccount === void 0 ? void 0 : userAccount.orders.filter((order) => (0, types_1.isVariant)(order.status, 'open'));
     }
+    /** Returns all of the user's orders with `OrderStatus.Open`. Empty array (not `undefined`) if there are none or no account is loaded. */
     getOpenOrders() {
         var _a;
         const userAccount = this.getUserAccount();
         return (_a = this.getOpenOrdersForUserAccount(userAccount)) !== null && _a !== void 0 ? _a : [];
     }
+    /** Like `getOpenOrders`, but also returns the slot at which the underlying `UserAccount` was observed. */
     getOpenOrdersAndSlot() {
         var _a;
         const userAccount = this.getUserAccountAndSlotOrThrow();
@@ -327,17 +433,19 @@ class User {
             slot: userAccount.slot,
         };
     }
+    /** Returns this `User`'s account address (does not require the account to be subscribed or to exist on chain). */
     getUserAccountPublicKey() {
         return this.userAccountPublicKey;
     }
+    /** Checks directly via RPC (bypassing the subscriber cache) whether the `User` account exists on chain. */
     async exists() {
         const userAccountRPCResponse = await this.velocityClient.connection.getParsedAccountInfo(this.userAccountPublicKey);
         return userAccountRPCResponse.value !== null;
     }
     /**
-     * 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) {
         const position = this.getPerpPositionOrThrow(marketIndex);
@@ -347,7 +455,17 @@ class User {
     }
     /**
      * 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, collateralBuffer = numericConstants_1.ZERO, maxMarginRatio = undefined, positionType = 'cross') {
         const perpPosition = this.getPerpPositionOrEmpty(marketIndex);
@@ -375,6 +493,17 @@ class User {
         // userAccount.maxMarginRatio unchanged — the expected semantic.
         return Math.max(perpMarketMaxMarginRatio !== null && perpMarketMaxMarginRatio !== void 0 ? perpMarketMaxMarginRatio : 0, this.getUserAccountOrThrow().maxMarginRatio);
     }
+    /**
+     * 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, freeCollateral, baseAssetAmount, perpMarketMaxMarginRatio = undefined) {
         const maxMarginRatio = this.resolveMaxMarginRatio(perpMarketMaxMarginRatio);
         const marginRatio = (0, market_1.calculateMarketMarginRatio)(this.velocityClient.getPerpMarketAccountOrThrow(marketIndex), baseAssetAmount, 'Initial', maxMarginRatio);
@@ -382,7 +511,15 @@ class User {
     }
     /**
      * 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 = 'Initial', perpMarketIndex) {
         const calc = this.getMarginCalculation(marginCategory, {
@@ -432,19 +569,35 @@ class User {
         return marginCalc.marginRequirement;
     }
     /**
-     * @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) {
         return this.getMarginRequirement('Initial', undefined, true, undefined, perpMarketIndex);
     }
     /**
-     * @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, perpMarketIndex) {
         return this.getMarginRequirement('Maintenance', liquidationBuffer, false, // strict default
         true, // includeOpenOrders default
         perpMarketIndex);
     }
+    /**
+     * 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) {
         return userAccount.perpPositions.filter((pos) => {
             var _a;
@@ -454,10 +607,12 @@ class User {
                 ((_a = pos.isolatedPositionScaledBalance) === null || _a === void 0 ? void 0 : _a.gt(numericConstants_1.ZERO));
         });
     }
+    /** Returns the cached account's active perp positions. See `getActivePerpPositionsForUserAccount` for the activity criteria. */
     getActivePerpPositions() {
         const userAccount = this.getUserAccountOrThrow();
         return this.getActivePerpPositionsForUserAccount(userAccount);
     }
+    /** Like `getActivePerpPositions`, but also returns the slot at which the underlying `UserAccount` was observed. */
     getActivePerpPositionsAndSlot() {
         const userAccount = this.getUserAccountAndSlotOrThrow();
         const positions = this.getActivePerpPositionsForUserAccount(userAccount.data);
@@ -466,13 +621,16 @@ class User {
             slot: userAccount.slot,
         };
     }
+    /** 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) {
         return userAccount.spotPositions.filter((pos) => !(0, spotPosition_1.isSpotPositionAvailable)(pos));
     }
+    /** Returns the cached account's active spot positions. See `getActiveSpotPositionsForUserAccount` for the activity criteria. */
     getActiveSpotPositions() {
         const userAccount = this.getUserAccountOrThrow();
         return this.getActiveSpotPositionsForUserAccount(userAccount);
     }
+    /** Like `getActiveSpotPositions`, but also returns the slot at which the underlying `UserAccount` was observed. */
     getActiveSpotPositionsAndSlot() {
         const userAccount = this.getUserAccountAndSlotOrThrow();
         const positions = this.getActiveSpotPositionsForUserAccount(userAccount.data);
@@ -482,8 +640,25 @@ class User {
         };
     }
     /**
-     * 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, marketIndex, withWeightMarginCategory, strict = false, liquidationBuffer) {
         return this.getActivePerpPositions()
@@ -513,6 +688,10 @@ class User {
                         .mul((0, market_1.calculateUnrealizedAssetWeight)(market, quoteSpotMarket, positionUnrealizedPnl, withWeightMarginCategory, oraclePriceData))
                         .div(new anchor_1.BN(numericConstants_1.SPOT_MARKET_WEIGHT_PRECISION));
                 }
+                if (withWeightMarginCategory === 'Initial') {
+                    // safety guard for dangerously configured perp market
+                    positionUnrealizedPnl = anchor_1.BN.min(positionUnrealizedPnl, numericConstants_1.MAX_POSITIVE_UPNL_FOR_INITIAL_MARGIN);
+                }
                 if (liquidationBuffer && positionUnrealizedPnl.lt(numericConstants_1.ZERO)) {
                     positionUnrealizedPnl = positionUnrealizedPnl.add(positionUnrealizedPnl.mul(liquidationBuffer).div(numericConstants_1.MARGIN_PRECISION));
                 }
@@ -521,8 +700,11 @@ class User {
         }, numericConstants_1.ZERO);
     }
     /**
-     * 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) {
         return this.getUserAccountOrThrow()
@@ -532,6 +714,20 @@ class User {
             return pnl.add((0, position_1.calculateUnsettledFundingPnl)(market, perpPosition));
         }, numericConstants_1.ZERO);
     }
+    /**
+     * 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, marginCategory, liquidationBuffer, includeOpenOrders, strict = false, now) {
         now = now || new anchor_1.BN(new Date().getTime() / 1000);
         let netQuoteValue = numericConstants_1.ZERO;
@@ -616,24 +812,35 @@ class User {
         }
         return { totalAssetValue, totalLiabilityValue };
     }
+    /** Convenience wrapper around `getSpotMarketAssetAndLiabilityValue` returning only `totalLiabilityValue`. See that method for parameter semantics. Returns QUOTE_PRECISION (1e6). */
     getSpotMarketLiabilityValue(marketIndex, marginCategory, liquidationBuffer, includeOpenOrders, strict = false, now) {
         const { totalLiabilityValue } = this.getSpotMarketAssetAndLiabilityValue(marketIndex, marginCategory, liquidationBuffer, includeOpenOrders, strict, now);
         return totalLiabilityValue;
     }
+    /** Thin wrapper around the `math/spotBalance` `getSpotLiabilityValue` helper that supplies the user's `maxMarginRatio`. Returns QUOTE_PRECISION (1e6), negative. */
     getSpotLiabilityValue(tokenAmount, strictOraclePrice, spotMarketAccount, marginCategory, liquidationBuffer) {
         return (0, spotBalance_2.getSpotLiabilityValue)(tokenAmount, strictOraclePrice, spotMarketAccount, this.getUserAccountOrThrow().maxMarginRatio, marginCategory, liquidationBuffer);
     }
+    /** Convenience wrapper around `getSpotMarketAssetAndLiabilityValue` returning only `totalAssetValue`. See that method for parameter semantics. Returns QUOTE_PRECISION (1e6), non-negative. */
     getSpotMarketAssetValue(marketIndex, marginCategory, includeOpenOrders, strict = false, now) {
         const { totalAssetValue } = this.getSpotMarketAssetAndLiabilityValue(marketIndex, marginCategory, undefined, includeOpenOrders, strict, now);
         return totalAssetValue;
     }
+    /** Thin wrapper around the `math/spotBalance` `getSpotAssetValue` helper that supplies the user's `maxMarginRatio`. Returns QUOTE_PRECISION (1e6), non-negative. */
     getSpotAssetValue(tokenAmount, strictOraclePrice, spotMarketAccount, marginCategory) {
         return (0, spotBalance_2.getSpotAssetValue)(tokenAmount, strictOraclePrice, spotMarketAccount, this.getUserAccountOrThrow().maxMarginRatio, marginCategory);
     }
+    /** Net spot value (`totalAssetValue - totalLiabilityValue`) for a single spot market. See `getSpotMarketAssetAndLiabilityValue` for parameter semantics. Returns QUOTE_PRECISION (1e6), can be negative. */
     getSpotPositionValue(marketIndex, marginCategory, includeOpenOrders, strict = false, now) {
         const { totalAssetValue, totalLiabilityValue } = this.getSpotMarketAssetAndLiabilityValue(marketIndex, marginCategory, undefined, includeOpenOrders, strict, now);
         return totalAssetValue.sub(totalLiabilityValue);
     }
+    /**
+     * 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) {
         const { totalAssetValue, totalLiabilityValue } = this.getSpotMarketAssetAndLiabilityValue(undefined, withWeightMarginCategory);
         return totalAssetValue.sub(totalLiabilityValue);
@@ -642,6 +849,24 @@ class User {
      * 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 = 'Initial', strict = false, includeOpenOrders = true, liquidationBuffer, perpMarketIndex) {
         const liquidationBufferMap = (() => {
             if (liquidationBuffer && perpMarketIndex !== undefined) {
@@ -673,6 +898,15 @@ class User {
         }
         return marginCalc.totalCollateral;
     }
+    /**
+     * 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() {
         const liquidationBufferMap = new Map();
         if (this.isBeingLiquidated()) {
@@ -687,8 +921,19 @@ class User {
         return liquidationBufferMap;
     }
     /**
-     * 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) {
         if (this.isCrossMarginBeingLiquidated() && !perpMarketIndex) {
@@ -725,6 +970,15 @@ class User {
         }
         return health;
     }
+    /**
+     * 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, marginCategory, liquidationBuffer, includeOpenOrders, strict = false) {
         const market = this.velocityClient.getPerpMarketAccountOrThrow(perpPosition.marketIndex);
         let valuationPrice = this.getOracleDataForPerpMarket(market.marketIndex).price;
@@ -772,16 +1026,28 @@ class User {
         return liabilityValue;
     }
     /**
-     * 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, marginCategory, liquidationBuffer, includeOpenOrders, strict = false) {
         const perpPosition = this.getPerpPositionOrThrow(marketIndex);
         return this.calculateWeightedPerpPositionLiability(perpPosition, marginCategory, liquidationBuffer, includeOpenOrders, strict);
     }
     /**
-     * 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, liquidationBuffer, includeOpenOrders, strict = false) {
         return this.getActivePerpPositions().reduce((totalPerpValue, perpPosition) => {
@@ -790,8 +1056,14 @@ class User {
         }, numericConstants_1.ZERO);
     }
     /**
-     * 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, oraclePriceData, includeOpenOrders = false) {
         const userPosition = this.getPerpPositionOrEmpty(marketIndex);
@@ -799,8 +1071,13 @@ class User {
         return (0, margin_2.calculateBaseAssetValueWithOracle)(market, userPosition, oraclePriceData, includeOpenOrders);
     }
     /**
-     * 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, oraclePriceData, includeOpenOrders = false) {
         const userPosition = this.getPerpPositionOrEmpty(marketIndex);
@@ -812,6 +1089,7 @@ class User {
             return (0, margin_1.calculatePerpLiabilityValue)(userPosition.baseAssetAmount, oraclePriceData.price);
         }
     }
+    /** Returns `PositionDirection.LONG`/`SHORT` from the sign of `baseAssetAmount`, or `undefined` if the position is flat. */
     getPositionSide(currentPosition) {
         if (currentPosition.baseAssetAmount.gt(numericConstants_1.ZERO)) {
             return types_2.PositionDirection.LONG;
@@ -825,7 +1103,10 @@ class User {
     }
     /**
      * 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, amountToClose, useAMMClose = false) {
         const market = this.velocityClient.getPerpMarketAccountOrThrow(position.marketIndex);
@@ -865,11 +1146,14 @@ class User {
     }
     /**
      * 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 = true, perpMarketIndex) {
         return this.calculateLeverageFromComponents(this.getLeverageComponents(includeOpenOrders, undefined, perpMarketIndex));
     }
+    /** 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, }) {
         const totalLiabilityValue = perpLiabilityValue.add(spotLiabilityValue);
         const totalAssetValue = spotAssetValue.add(perpPnl);
@@ -879,6 +1163,18 @@ class User {
         }
         return totalLiabilityValue.mul(numericConstants_1.TEN_THOUSAND).div(netAssetValue);
     }
+    /**
+     * 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 = true, marginCategory = undefined, perpMarketIndex) {
         var _a;
         if (perpMarketIndex) {
@@ -912,6 +1208,13 @@ class User {
             spotLiabilityValue,
         };
     }
+    /**
+     * 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) {
         const marketIndex = spotMarketAccount.marketIndex;
         const spotPosition = this.getSpotPosition(spotMarketAccount.marketIndex);
@@ -933,6 +1236,7 @@ class User {
         }
         return false;
     }
+    /** Returns every spot market where the user holds a dust-sized deposit; see `isDustDepositPosition`. */
     getSpotMarketAccountsWithDustPosition() {
         const spotMarketAccounts = this.velocityClient.getSpotMarketAccounts();
         const dustPositionAccounts = [];
@@ -944,9 +1248,22 @@ class User {
         }
         return dustPositionAccounts;
     }
+    /**
+     * 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) {
         return this.getTotalPerpPositionLiability(marginCategory, undefined, true).add(this.getSpotMarketLiabilityValue(undefined, marginCategory, undefined, true));
     }
+    /**
+     * 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) {
         const value = this.getSpotMarketAssetValue(undefined, marginCategory, true).add(this.getUnrealizedPNL(true, undefined, marginCategory));
         if (marginCategory === undefined) {
@@ -954,6 +1271,11 @@ class User {
         }
         return value;
     }
+    /**
+     * 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() {
         const netSpotValue = this.getNetSpotMarketValue();
         const unrealizedPnl = this.getUnrealizedPNL(true, undefined, undefined);
@@ -961,9 +1283,11 @@ class User {
         return netSpotValue.add(unrealizedPnl).add(isolatedDeposits);
     }
     /**
-     * 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() {
         const netUsdValue = this.getNetUsdValue();
@@ -975,8 +1299,8 @@ class User {
     /**
      * 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, _marginCategory = 'Initial') {
         const { perpLiabilityValue, perpPnl, spotAssetValue, spotLiabilityValue } = this.getLeverageComponents();
@@ -997,8 +1321,8 @@ class User {
     /**
      * 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, direction) {
         const { perpLiabilityValue, perpPnl, spotAssetValue, spotLiabilityValue } = this.getLeverageComponents();
@@ -1039,7 +1363,7 @@ class User {
     }
     /**
      * 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() {
         const { perpLiabilityValue, perpPnl, spotAssetValue, spotLiabilityValue } = this.getLeverageComponents();
@@ -1051,6 +1375,10 @@ class User {
         const netAssetValue = totalAssetValue.sub(spotLiabilityValue);
         return netAssetValue.mul(numericConstants_1.TEN_THOUSAND).div(totalLiabilityValue);
     }
+    /**
+     * @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() {
         // Deprecated signature retained for backward compatibility in type only
         // but implementation now delegates to the new Map-based API and returns cross margin status.
@@ -1073,6 +1401,14 @@ 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) {
         // If not provided, use buffer-aware calc for canBeLiquidated checks
@@ -1103,10 +1439,12 @@ class User {
         }
         return result;
     }
+    /** Returns true if cross margin or any isolated perp position is currently flagged as being liquidated or bankrupt. */
     isBeingLiquidated() {
         return (this.isCrossMarginBeingLiquidated() ||
             this.hasIsolatedPositionBeingLiquidated());
     }
+    /** Returns true if the account-level `UserStatus` has `BEING_LIQUIDATED` or `BANKRUPT` set (cross margin, not per-isolated-position). */
     isCrossMarginBeingLiquidated() {
         return ((this.getUserAccountOrThrow().status &
             (types_1.UserStatus.BEING_LIQUIDATED | types_1.UserStatus.BANKRUPT)) >
@@ -1117,11 +1455,13 @@ class User {
         const calc = marginCalc !== null && marginCalc !== void 0 ? marginCalc : this.getMarginCalculation('Maintenance');
         return calc.totalCollateral.lt(calc.marginRequirement);
     }
+    /** Returns true if any active perp position has `PositionFlag.BeingLiquidated` or `PositionFlag.Bankruptcy` set. */
     hasIsolatedPositionBeingLiquidated() {
         return this.getActivePerpPositions().some((position) => (position.positionFlag &
             (types_2.PositionFlag.BeingLiquidated | types_2.PositionFlag.Bankruptcy)) >
             0);
     }
+    /** 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) {
         var _a;
         const position = this.getActivePerpPositions().find((position) => position.marketIndex === perpMarketIndex);
@@ -1140,18 +1480,21 @@ class User {
         }
         return liquidatableIsolatedPositions;
     }
+    /** Returns true if `isolatedMarginCalculation`'s collateral is below its margin requirement (no buffer). */
     canIsolatedPositionMarginBeLiquidated(isolatedMarginCalculation) {
         return isolatedMarginCalculation.totalCollateral.lt(isolatedMarginCalculation.marginRequirement);
     }
+    /** Returns true if the account's `UserStatus` bitmask has `status` set. */
     hasStatus(status) {
         return (this.getUserAccountOrThrow().status & status) > 0;
     }
+    /** Returns true if the account's `UserStatus` has `BANKRUPT` set (equity insufficient to cover liabilities; awaiting bankruptcy resolution). */
     isBankrupt() {
         return (this.getUserAccountOrThrow().status & types_1.UserStatus.BANKRUPT) > 0;
     }
     /**
      * 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() {
         for (const userPosition of this.getUserAccountOrThrow().perpPositions) {
@@ -1168,9 +1511,16 @@ class User {
         return false;
     }
     /**
-     * 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, positionBaseSizeChange = numericConstants_1.ZERO) {
         const currentSpotPosition = this.getSpotPosition(marketIndex);
@@ -1218,14 +1568,23 @@ class User {
         return liqPrice;
     }
     /**
-     * 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, positionBaseSizeChange = numericConstants_1.ZERO, estimatedEntryPrice = numericConstants_1.ZERO, marginCategory = 'Maintenance', includeOpenOrders = false, offsetCollateral = numericConstants_1.ZERO, marginType) {
         const market = this.velocityClient.getPerpMarketAccountOrThrow(marketIndex);
@@ -1294,6 +1653,16 @@ class User {
         }
         return liqPrice;
     }
+    /**
+     * 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, oraclePrice, perpPosition, positionBaseSizeChange, estimatedEntryPrice, includeOpenOrders, marginCategory = 'Maintenance') {
         let freeCollateralChange = numericConstants_1.ZERO;
         // update free collateral to account for change in pnl from new position
@@ -1312,11 +1681,9 @@ class User {
             else {
                 freeCollateralChange = newPositionValue.sub(costBasis);
             }
-            // assume worst fee tier
+            // assume worst fee tier; ceil-divide to match calculate_taker_fee's safe_div_ceil
             const takerFeeTier = this.velocityClient.getStateAccount().perpFeeStructure.feeTiers[0];
-            const takerFee = newPositionValue
-                .muln(takerFeeTier.feeNumerator)
-                .divn(takerFeeTier.feeDenominator);
+            const takerFee = (0, utils_2.divCeil)(newPositionValue.muln(takerFeeTier.feeNumerator), new anchor_1.BN(takerFeeTier.feeDenominator));
             freeCollateralChange = freeCollateralChange.sub(takerFee);
         }
         const calculateMarginRequirement = (perpPosition) => {
@@ -1341,6 +1708,14 @@ class User {
         const freeCollateralConsumptionAfter = calculateMarginRequirement(perpPositionAfter);
         return freeCollateralChange.sub(freeCollateralConsumptionAfter.sub(freeCollateralConsumptionBefore));
     }
+    /**
+     * 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, perpPosition, positionBaseSizeChange, oraclePrice, marginCategory = 'Maintenance', includeOpenOrders = false) {
         const baseAssetAmount = includeOpenOrders
             ? (0, margin_2.calculateWorstCaseBaseAssetAmount)(perpPosition, market, oraclePrice)
@@ -1375,6 +1750,12 @@ class User {
         }
         return freeCollateralDelta;
     }
+    /**
+     * 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, signedTokenAmount, marginCategory = 'Maintenance') {
         const tokenPrecision = new anchor_1.BN(Math.pow(10, market.decimals));
         if (signedTokenAmount.gt(numericConstants_1.ZERO)) {
@@ -1397,8 +1778,9 @@ class User {
     /**
      * 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, closeQuoteAmount, estimatedEntryPrice = numericConstants_1.ZERO) {
         const currentPosition = this.getPerpPositionOrEmpty(positionMarketIndex);
@@ -1411,10 +1793,27 @@ class User {
             .neg();
         return this.liquidationPrice(positionMarketIndex, closeBaseAmount, estimatedEntryPrice);
     }
+    /**
+     * 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, baseSize, estEntryPrice, perpMarketMaxMarginRatio) {
         const maxMarginRatio = this.resolveMaxMarginRatio(perpMarketMaxMarginRatio);
         return (0, margin_2.calculateMarginUSDCRequiredForTrade)(this.velocityClient, targetMarketIndex, baseSize, maxMarginRatio, estEntryPrice);
     }
+    /**
+     * 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, baseSize, collateralIndex, perpMarketMaxMarginRatio) {
         const maxMarginRatio = this.resolveMaxMarginRatio(perpMarketMaxMarginRatio);
         return (0, margin_2.calculateCollateralDepositRequiredForTrade)(this.velocityClient, targetMarketIndex, baseSize, collateralIndex, maxMarginRatio);
@@ -1425,7 +1824,9 @@ 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, tradeSide, maxMarginRatio = undefined, positionType = 'cross') {
         let tradeSize = numericConstants_1.ZERO;
@@ -1504,10 +1905,10 @@ 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, direction, currentQuoteAssetValue, currentSpotMarketNetValue) {
         const market = this.velocityClient.getSpotMarketAccountOrThrow(targetMarketIndex);
@@ -1549,8 +1950,9 @@ 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 = 1000, }) {
         const inMarket = this.velocityClient.getSpotMarketAccountOrThrow(inMarketIndex);
@@ -1654,6 +2056,13 @@ class User {
         });
         return { inAmount: inSwap, outAmount: outSwap, leverage };
     }
+    /**
+     * 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, tokenAmount, market) {
         const clonedPosition = Object.assign({}, position);
         if (tokenAmount.eq(numericConstants_1.ZERO)) {
@@ -1680,12 +2089,14 @@ class User {
         }
         return clonedPosition;
     }
+    /** Worst-case free-collateral contribution (under `'Initial'` margin) of a single spot position. Returns QUOTE_PRECISION (1e6). */
     calculateSpotPositionFreeCollateralContribution(spotPosition, strictOraclePrice) {
         const marginCategory = 'Initial';
         const spotMarketAccount = this.velocityClient.getSpotMarketAccountOrThrow(spotPosition.marketIndex);
         const { freeCollateralContribution } = (0, spotPosition_1.getWorstCaseTokenAmounts)(spotPosition, spotMarketAccount, strictOraclePrice, marginCategory, this.getUserAccountOrThrow().maxMarginRatio);
         return freeCollateralContribution;
     }
+    /** 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, strictOraclePrice) {
         let totalAssetValue = numericConstants_1.ZERO;
         let totalLiabilityValue = numericConstants_1.ZERO;
@@ -1710,10 +2121,11 @@ class User {
     }
     /**
      * 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, }) {
         const inMarket = this.velocityClient.getSpotMarketAccountOrThrow(inMarketIndex);
@@ -1756,11 +2168,11 @@ 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, targetMarketType, tradeQuoteAmount, tradeSide, includeOpenOrders = true) {
         const tradeIsPerp = (0, types_1.isVariant)(targetMarketType, 'perp');
@@ -1837,6 +2249,19 @@ class User {
             .div(netAssetValue);
         return newLeverage;
     }
+    /**
+     * 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, now) {
         const state = this.velocityClient.getStateAccount();
         if ((0, types_1.isVariant)(marketType, 'perp')) {
@@ -1863,28 +2288,64 @@ class User {
         return state.spotFeeStructure.feeTiers[0];
     }
     /**
-     * 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, marketIndex) {
+    calculatePerpTakerFee(quoteAmount, marketIndex, isReferee, builderInfo) {
         if (marketIndex !== undefined) {
-            const takerFeeMultiplier = this.velocityClient.getMarketFees(types_2.MarketType.PERP, marketIndex, this).takerFee;
+            const takerFeeMultiplier = this.velocityClient.getMarketFees(types_2.MarketType.PERP, marketIndex, this, builderInfo).takerFee;
             const feeAmountNum = bigNum_1.BigNum.from(quoteAmount, numericConstants_1.QUOTE_PRECISION_EXP).toNum() *
                 takerFeeMultiplier;
             return bigNum_1.BigNum.fromPrint(feeAmountNum.toString(), numericConstants_1.QUOTE_PRECISION_EXP).val;
         }
         else {
             const feeTier = this.getUserFeeTier(types_2.MarketType.PERP);
-            return quoteAmount
-                .mul(new anchor_1.BN(feeTier.feeNumerator))
-                .div(new anchor_1.BN(feeTier.feeDenominator));
+            let fee = (0, utils_2.divCeil)(quoteAmount.mul(new anchor_1.BN(feeTier.feeNumerator)), new anchor_1.BN(feeTier.feeDenominator));
+            const isUserReferee = isReferee !== null && isReferee !== void 0 ? isReferee : (this.velocityClient.getUserStatsOrThrow().getAccountOrThrow()
+                .referrerStatus &
+                types_1.ReferrerStatus.IsReferred) >
+                0;
+            if (isUserReferee) {
+                const refereeDiscount = getProportion128(fee, new anchor_1.BN(feeTier.refereeFeeNumerator), new anchor_1.BN(feeTier.refereeFeeDenominator));
+                fee = fee.sub(refereeDiscount);
+            }
+            // Builder fee (M12): charged on top of the tiered fee, on the raw quote
+            // (independent of the referee discount), mirroring `builder_fee` in `math/fees.rs`.
+            if (builderInfo && (0, builder_1.hasBuilderParams)(builderInfo)) {
+                fee = fee.add((0, builder_1.calculateBuilderFee)(quoteAmount, builderInfo.builderFeeTenthBps));
+            }
+            return fee;
         }
     }
     /**
      * 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, reduceOnly) {
@@ -1941,6 +2402,24 @@ class User {
             return anchor_1.BN.max(maxBorrowValue, numericConstants_1.ZERO);
         }
     }
+    /**
+     * 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) {
         const spotMarket = this.velocityClient.getSpotMarketAccountOrThrow(marketIndex);
         const maxDepositAmount = spotMarket.withdrawGuardThreshold.div(new anchor_1.BN(10));
@@ -1971,6 +2450,14 @@ class User {
                 netDeposits,
             };
         }
+        if (position.cumulativeDeposits.lt(numericConstants_1.ZERO)) {
+            return {
+                canBypass: false,
+                maxDepositAmount,
+                depositAmount,
+                netDeposits,
+            };
+        }
         return {
             canBypass: depositAmount.lt(maxDepositAmount),
             maxDepositAmount,
@@ -1978,6 +2465,15 @@ class User {
             depositAmount,
         };
     }
+    /**
+     * 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) {
         const userAccount = this.getUserAccountOrThrow();
         if (userAccount.idle) {
@@ -2021,6 +2517,20 @@ class User {
         }
         return true;
     }
+    /**
+     * 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, now) {
         const userAccount = this.getUserAccountOrThrow();
         const userStatsAccountToUse = userStatsAccount !== null && userStatsAccount !== void 0 ? userStatsAccount : this.velocityClient.getUserStatsOrThrow().getAccount();
@@ -2071,6 +2581,17 @@ class User {
         }
         return { canDelete: true };
     }
+    /**
+     * 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() {
         let safestPerpTier = 4;
         let safestSpotTier = 4;
@@ -2088,6 +2609,21 @@ class User {
             spotTier: safestSpotTier,
         };
     }
+    /**
+     * 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 = true, }) {
         const perpMarket = this.velocityClient.getPerpMarketAccountOrThrow(perpPosition.marketIndex);
         const _oraclePriceData = oraclePriceData ||
@@ -2122,6 +2658,18 @@ class User {
             weightedValue: marginRequirement,
         };
     }
+    /**
+     * 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, }) {
         const healthComponents = {
             deposits: [],
@@ -2246,6 +2794,7 @@ class User {
     }
     /**
      * 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() {
         const activePerpMarkets = this.getActivePerpPositions().map((position) => position.marketIndex);
@@ -2259,9 +2808,28 @@ 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 = 'Initial', opts) {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+        var _a, _b, _c, _d, _e, _f, _g, _h;
         const strict = (_a = opts === null || opts === void 0 ? void 0 : opts.strict) !== null && _a !== void 0 ? _a : false;
         const liquidationBufferMap = (_b = opts === null || opts === void 0 ? void 0 : opts.liquidationBufferMap) !== null && _b !== void 0 ? _b : new Map();
         const includeOpenOrders = (_c = opts === null || opts === void 0 ? void 0 : opts.includeOpenOrders) !== null && _c !== void 0 ? _c : true;
@@ -2281,12 +2849,29 @@ class User {
             .setCrossMarginBuffer((_f = (_e = opts === null || opts === void 0 ? void 0 : opts.liquidationBufferMap) === null || _e === void 0 ? void 0 : _e.get('cross')) !== null && _f !== void 0 ? _f : numericConstants_1.ZERO)
             .setIsolatedMarginBuffers(isolatedMarginBuffers);
         const calc = new marginCalculation_1.MarginCalculation(ctx);
+        const userPoolId = this.getUserAccountOrThrow().poolId;
         // SPOT POSITIONS
         for (const spotPosition of this.getUserAccountOrThrow().spotPositions) {
             if ((0, spotPosition_1.isSpotPositionAvailable)(spotPosition))
                 continue;
             const isQuote = spotPosition.marketIndex === numericConstants_1.QUOTE_SPOT_MARKET_INDEX;
+            const isBorrow = (0, types_1.isVariant)(spotPosition.balanceType, 'borrow');
             const spotMarket = this.velocityClient.getSpotMarketAccountOrThrow(spotPosition.marketIndex);
+            // the pool-1/quote-deposit carve-out lets a pool-1 user *hold* a quote
+            // deposit without matching the quote market's own pool id (no
+            // InvalidPoolId throw); every other combination requires an exact pool
+            // match. Note the deposit still contributes ZERO collateral in this case
+            // (skipTokenValue below) — this faithfully mirrors margin.rs:319-321,
+            // which sets token_value = 0 before add_cross_margin_total_collateral.
+            let skipTokenValue = false;
+            if (!(userPoolId === 1 && isQuote && !isBorrow)) {
+                if (userPoolId !== spotMarket.poolId) {
+                    throw new Error(`InvalidPoolId: user pool id (${userPoolId}) does not match spot market pool id (${spotMarket.poolId}) for market index ${spotMarket.marketIndex}`);
+                }
+            }
+            else {
+                skipTokenValue = true;
+            }
             const oraclePriceData = this.getOracleDataForSpotMarket(spotPosition.marketIndex);
             const twap5 = strict
                 ? (0, oracles_1.calculateLiveOracleTwap)(spotMarket.historicalOracleData, oraclePriceData, new anchor_1.BN(Math.floor(Date.now() / 1000)), numericConstants_1.FIVE_MINUTE)
@@ -2294,15 +2879,20 @@ class User {
             const strictOracle = new strictOraclePrice_1.StrictOraclePrice(oraclePriceData.price, twap5);
             if (isQuote) {
                 const tokenAmount = (0, spotBalance_1.getSignedTokenAmount)((0, spotBalance_2.getTokenAmount)(spotPosition.scaledBalance, spotMarket, spotPosition.balanceType), spotPosition.balanceType);
+                // mirrors margin.rs's `market_index == 0` block: the quote market uses the
+                // raw strict token value on both sides — no asset/liability weight, and the
+                // cross-margin buffer is applied inside addCrossMarginRequirement (from
+                // context.crossMarginBuffer), not folded into the value here
+                const tokenValue = (0, spotBalance_1.getStrictTokenValue)(tokenAmount, spotMarket.decimals, strictOracle);
                 if ((0, types_1.isVariant)(spotPosition.balanceType, 'deposit')) {
                     // add deposit value to total collateral
-                    const weightedTokenValue = this.getSpotAssetValue(tokenAmount, strictOracle, spotMarket, marginCategory);
-                    calc.addCrossMarginTotalCollateral(weightedTokenValue);
+                    calc.addCrossMarginTotalCollateral(skipTokenValue ? numericConstants_1.ZERO : tokenValue);
                 }
                 else {
                     // borrow on quote contributes to margin requirement
-                    const tokenValueAbs = this.getSpotLiabilityValue(tokenAmount, strictOracle, spotMarket, marginCategory, (_g = liquidationBufferMap.get('cross')) !== null && _g !== void 0 ? _g : new anchor_1.BN(0)).abs();
+                    const tokenValueAbs = tokenValue.abs();
                     calc.addCrossMarginRequirement(tokenValueAbs, tokenValueAbs);
+                    calc.addSpotLiability();
                 }
                 continue;
             }
@@ -2314,6 +2904,7 @@ class User {
                 // open order IM
                 calc.addCrossMarginRequirement(new anchor_1.BN(spotPosition.openOrders).mul(numericConstants_1.OPEN_ORDER_MARGIN_REQUIREMENT), numericConstants_1.ZERO);
             }
+            const isIsolatedSpotTier = (0, types_1.isVariant)(spotMarket.assetTier, 'isolated');
             if (worstCaseTokenAmount.gt(numericConstants_1.ZERO)) {
                 const baseAssetValue = this.getSpotAssetValue(worstCaseTokenAmount, strictOracle, spotMarket, marginCategory);
                 // asset side increases total collateral (weighted)
@@ -2323,6 +2914,14 @@ class User {
                 // liability side increases margin requirement (weighted >= abs(token_value))
                 const getSpotLiabilityValue = this.getSpotLiabilityValue(worstCaseTokenAmount, strictOracle, spotMarket, marginCategory, liquidationBufferMap.get('cross'));
                 calc.addCrossMarginRequirement(getSpotLiabilityValue.abs(), getSpotLiabilityValue.abs());
+                calc.addSpotLiability();
+                calc.updateWithSpotIsolatedLiability(isIsolatedSpotTier);
+            }
+            else if (spotPosition.openOrders !== 0 ||
+                !spotPosition.openBids.isZero() ||
+                !spotPosition.openAsks.isZero()) {
+                calc.addSpotLiability();
+                calc.updateWithSpotIsolatedLiability(isIsolatedSpotTier);
             }
             // orders value contributes to collateral or requirement
             if (worstCaseOrdersValue.gt(numericConstants_1.ZERO)) {
@@ -2336,6 +2935,9 @@ class User {
         // PERP POSITIONS
         for (const marketPosition of this.getActivePerpPositions()) {
             const market = this.velocityClient.getPerpMarketAccountOrThrow(marketPosition.marketIndex);
+            if (userPoolId !== market.poolId) {
+                throw new Error(`InvalidPoolId: user pool id (${userPoolId}) does not match perp market pool id (${market.poolId}) for market index ${market.marketIndex}`);
+            }
             const quoteSpotMarket = this.velocityClient.getSpotMarketAccountOrThrow(market.quoteSpotMarketIndex);
             const quoteOraclePriceData = this.getOracleDataForSpotMarket(market.quoteSpotMarketIndex);
             const oraclePriceData = this.getMMOracleDataForPerpMarket(market.marketIndex);
@@ -2348,13 +2950,15 @@ class User {
             if ((0, types_1.isVariant)(market.status, 'settlement')) {
                 marginRatio = numericConstants_1.ZERO;
             }
-            // convert liability to quote value and apply margin ratio
+            // convert liability to quote value and apply margin ratio; since this is
+            // a liability, use the larger of the twap and current quote price
             const quotePrice = strict
                 ? anchor_1.BN.max(quoteOraclePriceData.price, quoteSpotMarket.historicalOracleData.lastOraclePriceTwap5Min)
                 : quoteOraclePriceData.price;
-            let perpMarginRequirement = worstCaseLiabilityValue
+            const worstCaseLiabilityValueQuote = worstCaseLiabilityValue
                 .mul(quotePrice)
-                .div(numericConstants_1.PRICE_PRECISION)
+                .div(numericConstants_1.PRICE_PRECISION);
+            let perpMarginRequirement = worstCaseLiabilityValueQuote
                 .mul(marginRatio)
                 .div(numericConstants_1.MARGIN_PRECISION);
             // add open orders IM
@@ -2383,33 +2987,112 @@ class User {
                         .div(new anchor_1.BN(numericConstants_1.SPOT_MARKET_WEIGHT_PRECISION));
                 }
             }
+            if (marginCategory === 'Initial') {
+                // safety guard for dangerously configured perp market
+                positionUnrealizedPnl = anchor_1.BN.min(positionUnrealizedPnl, numericConstants_1.MAX_POSITIVE_UPNL_FOR_INITIAL_MARGIN);
+            }
+            const hasPerpLiability = !marketPosition.baseAssetAmount.isZero() ||
+                marketPosition.quoteAssetAmount.isNeg() ||
+                marketPosition.openOrders !== 0 ||
+                !marketPosition.openBids.isZero() ||
+                !marketPosition.openAsks.isZero();
+            if (hasPerpLiability) {
+                calc.addPerpLiability();
+                calc.updateWithPerpIsolatedLiability((0, types_1.isVariant)(market.contractTier, 'isolated'));
+            }
             // Add perp contribution: isolated vs cross
             const isIsolated = this.isPerpPositionIsolated(marketPosition);
             if (isIsolated) {
                 // derive isolated quote deposit value, mirroring on-chain logic
                 let depositValue = numericConstants_1.ZERO;
-                if ((_h = marketPosition.isolatedPositionScaledBalance) === null || _h === void 0 ? void 0 : _h.gt(numericConstants_1.ZERO)) {
+                if ((_g = marketPosition.isolatedPositionScaledBalance) === null || _g === void 0 ? void 0 : _g.gt(numericConstants_1.ZERO)) {
                     const quoteSpotMarket = this.velocityClient.getSpotMarketAccountOrThrow(market.quoteSpotMarketIndex);
                     const quoteOraclePriceData = this.getOracleDataForSpotMarket(market.quoteSpotMarketIndex);
                     const strictQuote = new strictOraclePrice_1.StrictOraclePrice(quoteOraclePriceData.price, strict
                         ? quoteSpotMarket.historicalOracleData.lastOraclePriceTwap5Min
                         : undefined);
-                    const quoteTokenAmount = (0, spotBalance_2.getTokenAmount)((_j = marketPosition.isolatedPositionScaledBalance) !== null && _j !== void 0 ? _j : numericConstants_1.ZERO, quoteSpotMarket, types_2.SpotBalanceType.DEPOSIT);
+                    const quoteTokenAmount = (0, spotBalance_2.getTokenAmount)((_h = marketPosition.isolatedPositionScaledBalance) !== null && _h !== void 0 ? _h : numericConstants_1.ZERO, quoteSpotMarket, types_2.SpotBalanceType.DEPOSIT);
                     depositValue = (0, spotBalance_1.getStrictTokenValue)(quoteTokenAmount, quoteSpotMarket.decimals, strictQuote);
                 }
-                calc.addIsolatedMarginCalculation(market.marketIndex, depositValue, positionUnrealizedPnl, worstCaseLiabilityValue, perpMarginRequirement);
-                calc.addPerpLiabilityValue(worstCaseLiabilityValue);
+                calc.addIsolatedMarginCalculation(market.marketIndex, depositValue, positionUnrealizedPnl, worstCaseLiabilityValueQuote, perpMarginRequirement);
             }
             else {
                 // cross: add to global requirement and collateral
-                calc.addCrossMarginRequirement(perpMarginRequirement, worstCaseLiabilityValue);
+                calc.addCrossMarginRequirement(perpMarginRequirement, worstCaseLiabilityValueQuote);
                 calc.addCrossMarginTotalCollateral(positionUnrealizedPnl);
             }
+            // mirrors margin.rs:616-617 — perp liability value accumulates for every
+            // position regardless of the isolated/cross split, so it must run outside
+            // the branch above (previously only the isolated branch accumulated it,
+            // underreporting totalPerpLiabilityValue for cross positions)
+            calc.addPerpLiabilityValue(worstCaseLiabilityValueQuote);
         }
         return calc;
     }
+    /**
+     * 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) {
         return (perpPosition.positionFlag & types_2.PositionFlag.IsolatedPosition) !== 0;
     }
+    /**
+     * 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) {
+        const userAccount = this.getUserAccountOrThrow();
+        const isReduceOnly = this.hasStatus(types_1.UserStatus.REDUCE_ONLY);
+        if (calculation.withPerpIsolatedLiability && !isReduceOnly) {
+            if (calculation.numPerpLiabilities > 1) {
+                return {
+                    valid: false,
+                    reason: 'User attempting to increase perp liabilities above 1 with a isolated tier liability',
+                };
+            }
+            if (userAccount.isMarginTradingEnabled) {
+                return {
+                    valid: false,
+                    reason: 'User attempting isolated tier liability with margin trading enabled',
+                };
+            }
+            if (calculation.numSpotLiabilities > 0) {
+                const quoteSpotPosition = this.getSpotPosition(numericConstants_1.QUOTE_SPOT_MARKET_INDEX);
+                const quoteIsBorrow = !!quoteSpotPosition &&
+                    (0, types_1.isVariant)(quoteSpotPosition.balanceType, 'borrow');
+                if (!(calculation.numSpotLiabilities === 1 && quoteIsBorrow)) {
+                    return {
+                        valid: false,
+                        reason: 'User attempting to increase spot liabilities beyond usdc with a isolated tier liability',
+                    };
+                }
+            }
+        }
+        if (calculation.withSpotIsolatedLiability && !isReduceOnly) {
+            if (!(calculation.numPerpLiabilities === 0 &&
+                calculation.numSpotLiabilities === 1)) {
+                return {
+                    valid: false,
+                    reason: 'User attempting to increase perp liabilities above 0 with a isolated tier liability',
+                };
+            }
+        }
+        return { valid: true };
+    }
 }
 exports.User = User;