@velocity-exchange/sdk 0.3.0 → 0.4.0

package/lib/node/idl/velocity.json

@@ -11081,13 +11081,13 @@
                 133
             ],
             "accounts": [
-                {
-                    "name": "admin",
-                    "signer": true
-                },
                 {
                     "name": "state",
                     "writable": true
+                },
+                {
+                    "name": "admin",
+                    "signer": true
                 }
             ],
             "args": [

package/lib/node/keypair.d.ts

@@ -1,3 +1,11 @@
 import { Keypair } from '@solana/web3.js';
+/**
+ * Loads a Solana `Keypair` from a private key given in any of the common CLI/env formats.
+ * @param privateKey - One of: a filesystem path to a JSON keypair file (checked first via
+ * `fs.existsSync`); a JSON array string (e.g. `"[1,2,3,...]"`); a comma-separated list of byte
+ * values (e.g. `"1,2,3,..."`); or a base58-encoded secret key string (whitespace is stripped).
+ * @returns The decoded `Keypair`.
+ * @throws Error (from `Keypair.fromSecretKey`) if the decoded bytes are not a valid 64-byte secret key.
+ */
 export declare function loadKeypair(privateKey: string): Keypair;
 //# sourceMappingURL=keypair.d.ts.map

package/lib/node/keypair.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"keypair.d.ts","sourceRoot":"","sources":["../../src/keypair.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAE1C,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAmBvD"}
+{"version":3,"file":"keypair.d.ts","sourceRoot":"","sources":["../../src/keypair.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAE1C;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAmBvD"}

package/lib/node/keypair.js

@@ -7,6 +7,14 @@ exports.loadKeypair = void 0;
 const fs_1 = __importDefault(require("fs"));
 const bs58_1 = __importDefault(require("bs58"));
 const web3_js_1 = require("@solana/web3.js");
+/**
+ * Loads a Solana `Keypair` from a private key given in any of the common CLI/env formats.
+ * @param privateKey - One of: a filesystem path to a JSON keypair file (checked first via
+ * `fs.existsSync`); a JSON array string (e.g. `"[1,2,3,...]"`); a comma-separated list of byte
+ * values (e.g. `"1,2,3,..."`); or a base58-encoded secret key string (whitespace is stripped).
+ * @returns The decoded `Keypair`.
+ * @throws Error (from `Keypair.fromSecretKey`) if the decoded bytes are not a valid 64-byte secret key.
+ */
 function loadKeypair(privateKey) {
     // try to load privateKey as a filepath
     let loadedKey;

package/lib/node/marginCalculation.d.ts

@@ -1,19 +1,38 @@
 import { BN } from './isomorphic/anchor';
-import { MarketType } from './types';
-export type MarginCategory = 'Initial' | 'Maintenance' | 'Fill';
+import { MarginCategory, MarketType } from './types';
+/**
+ * Which margin threshold a `MarginCalculation` is computing against: `Initial` (opening/increasing
+ * risk), `Maintenance` (liquidation eligibility), or `Fill` (order-fill-time check, the
+ * integer-averaged midpoint of Initial and Maintenance). Re-exported from `./types` so the SDK has
+ * a single `MarginCategory` definition.
+ */
+export type { MarginCategory };
+/** Selects the margin-buffer behavior of a `MarginContext`: `Standard` for ordinary health checks (no buffer), or `Liquidation` to apply the cross/isolated margin buffers used to avoid liquidating a user who is only marginally underwater. */
 export type MarginCalculationMode = {
     type: 'Standard';
 } | {
     type: 'Liquidation';
 };
+/** Identifies a market by type (spot or perp) and index, used as a key into per-market margin state (e.g. isolated margin buffers). Construct via `MarketIdentifier.spot` / `MarketIdentifier.perp`. */
 export declare class MarketIdentifier {
     marketType: MarketType;
     marketIndex: number;
     private constructor();
+    /** Builds a `MarketIdentifier` for a spot market index. */
     static spot(marketIndex: number): MarketIdentifier;
+    /** Builds a `MarketIdentifier` for a perp market index. */
     static perp(marketIndex: number): MarketIdentifier;
+    /** True if `other` refers to the same market type and index. */
     equals(other: MarketIdentifier | undefined): boolean;
 }
+/**
+ * Configuration driving a `MarginCalculation` pass: which margin category to compute,
+ * whether it's a plain health check or a liquidation-margin-freed calculation, and the
+ * per-market buffers (in `MARGIN_PRECISION`, 1e4, fractional-of-liability-value units)
+ * applied to cross-margin and isolated-margin requirements/collateral so a user isn't
+ * flagged liquidatable from a hair's-width shortfall. Mirrors `MarginContext` in
+ * `programs/velocity/src/state/margin_calculation.rs`.
+ */
 export declare class MarginContext {
     marginType: MarginCategory;
     mode: MarginCalculationMode;
@@ -22,46 +41,159 @@ export declare class MarginContext {
     isolatedMarginBuffers: Map<number, BN>;
     crossMarginBuffer: BN;
     private constructor();
+    /** Builds a plain `Standard`-mode context (no liquidation buffers) for the given margin category — the usual choice for health/leverage/order-placement checks. */
     static standard(marginType: MarginCategory): MarginContext;
+    /**
+     * Builds a `Maintenance`-category, `Liquidation`-mode context with the given buffers.
+     * Used by liquidation eligibility / margin-freed calculations so a position is only
+     * eligible once it's underwater by more than the buffer, avoiding flip-flopping right
+     * at the maintenance threshold.
+     * @param crossMarginBuffer Extra maintenance-margin cushion applied to the cross-margin
+     *   book, `MARGIN_PRECISION` (1e4) fraction of liability value.
+     * @param isolatedMarginBuffers Same buffer, per isolated-position market index.
+     */
     static liquidation(crossMarginBuffer: BN, isolatedMarginBuffers: Map<number, BN>): MarginContext;
+    /** Sets whether strict oracle pricing (worse of last/twap price) is used for collateral/liability valuation. Returns `this` for chaining. */
     strictMode(strict: boolean): this;
+    /** Sets whether spot deposits with an invalid oracle are ignored (valued at zero) rather than failing the calculation. Returns `this` for chaining. */
     ignoreInvalidDeposits(ignore: boolean): this;
+    /** Sets the cross-margin maintenance buffer (`MARGIN_PRECISION`, 1e4, fraction of liability value). Returns `this` for chaining. */
     setCrossMarginBuffer(crossMarginBuffer: BN): this;
+    /** Replaces the whole per-market isolated-margin buffer map. Returns `this` for chaining. */
     setIsolatedMarginBuffers(isolatedMarginBuffers: Map<number, BN>): this;
+    /** Sets the isolated-margin buffer (`MARGIN_PRECISION`, 1e4, fraction of liability value) for a single perp market index. Returns `this` for chaining. */
     setIsolatedMarginBuffer(marketIndex: number, isolatedMarginBuffer: BN): this;
 }
+/**
+ * Accumulated margin requirement and collateral for a single isolated perp position,
+ * built up during a `MarginCalculation` pass via `MarginCalculation.addIsolatedMarginCalculation`.
+ * All BN fields are QUOTE_PRECISION (1e6). Isolated positions have their own dedicated
+ * collateral pool, so their margin health is tracked independently of the user's
+ * cross-margin book.
+ */
 export declare class IsolatedMarginCalculation {
+    /** Margin required to maintain/open the isolated position, QUOTE_PRECISION (1e6). */
     marginRequirement: BN;
+    /** Isolated collateral: position's deposit value plus unrealized/settled pnl, QUOTE_PRECISION (1e6). */
     totalCollateral: BN;
+    /** Signed adjustment to `totalCollateral` from the context's isolated margin buffer (liquidation mode only), QUOTE_PRECISION (1e6). */
     totalCollateralBuffer: BN;
+    /** `marginRequirement` plus the buffered liability-value addition (liquidation mode only), QUOTE_PRECISION (1e6). */
     marginRequirementPlusBuffer: BN;
     constructor();
+    /** `totalCollateral + totalCollateralBuffer`, QUOTE_PRECISION (1e6). */
     getTotalCollateralPlusBuffer(): BN;
+    /** True if the isolated position's collateral covers its margin requirement (no buffer applied). */
     meetsMarginRequirement(): boolean;
+    /** True if the buffered collateral covers the buffered margin requirement — the check used for liquidation eligibility. */
     meetsMarginRequirementWithBuffer(): boolean;
+    /** Buffered margin shortfall (`marginRequirementPlusBuffer - totalCollateralPlusBuffer`, floored at zero), QUOTE_PRECISION (1e6). */
     marginShortage(): BN;
 }
+/**
+ * Accumulator built up by walking a user's spot and perp positions, mirroring
+ * `MarginCalculation` in `programs/velocity/src/state/margin_calculation.rs`. Tracks the
+ * cross-margin book's total collateral/margin requirement plus a separate
+ * `IsolatedMarginCalculation` per isolated perp market, so cross and isolated health are
+ * evaluated independently — `meetsMarginRequirement`/`meetsMarginRequirementWithBuffer`
+ * require both the cross book and every isolated position to pass.
+ *
+ * `numSpotLiabilities`/`numPerpLiabilities`/`withPerpIsolatedLiability`/
+ * `withSpotIsolatedLiability` track the on-chain "isolated contract tier" risk-isolation
+ * rule (`validate_any_isolated_tier_requirements`): a user holding a liability in a market
+ * whose `ContractTier` is `Isolated` may not simultaneously hold other liabilities (perp or
+ * non-quote spot) unless in reduce-only mode. Note this `ContractTier::Isolated` market
+ * classification is unrelated to per-position isolated margin
+ * (`isolatedPositionScaledBalance`) — a market can be isolated-tier without any position on
+ * it using isolated margin.
+ */
 export declare class MarginCalculation {
     context: MarginContext;
+    /** Cross-margin collateral (deposits + perp pnl), QUOTE_PRECISION (1e6). */
     totalCollateral: BN;
+    /** Signed liquidation-buffer adjustment to `totalCollateral`, QUOTE_PRECISION (1e6). Zero outside `Liquidation` mode. */
     totalCollateralBuffer: BN;
+    /** Cross-margin requirement accumulated so far, QUOTE_PRECISION (1e6). */
     marginRequirement: BN;
+    /** `marginRequirement` plus the buffered liability-value addition (liquidation mode only), QUOTE_PRECISION (1e6). */
     marginRequirementPlusBuffer: BN;
+    /** Per-isolated-perp-market margin state, keyed by perp market index. */
     isolatedMarginCalculations: Map<number, IsolatedMarginCalculation>;
+    /** Sum of worst-case perp liability value across all (cross + isolated) perp positions seen so far, QUOTE_PRECISION (1e6). */
     totalPerpLiabilityValue: BN;
+    /** Count of spot positions counted as liabilities (borrows) so far. */
+    numSpotLiabilities: number;
+    /** Count of perp positions counted as liabilities (non-flat base, negative quote, or open orders) so far. */
+    numPerpLiabilities: number;
+    /** True once any perp liability seen belongs to a `ContractTier::Isolated` market. */
+    withPerpIsolatedLiability: boolean;
+    /** True once any spot liability seen is a borrow (or has open orders) in an `AssetTier::Isolated` spot market (isolated-tier borrows are restricted to the quote asset). */
+    withSpotIsolatedLiability: boolean;
     constructor(context: MarginContext);
+    /**
+     * Adds a signed collateral delta (deposit value or perp pnl, QUOTE_PRECISION 1e6) to
+     * the cross-margin book. When in `Liquidation` mode with a nonzero `crossMarginBuffer`
+     * and the delta is negative, also extends `totalCollateralBuffer` by
+     * `delta * crossMarginBuffer / MARGIN_PRECISION` so a negative-pnl position looks worse
+     * under the buffered (liquidation-eligibility) check than under the plain one.
+     * @param delta Signed collateral value to add, QUOTE_PRECISION (1e6).
+     */
     addCrossMarginTotalCollateral(delta: BN): void;
+    /**
+     * Adds a position's margin requirement to the cross-margin book. When a nonzero
+     * `crossMarginBuffer` is configured, also accrues `marginRequirementPlusBuffer` with an
+     * extra `liabilityValue * crossMarginBuffer / MARGIN_PRECISION` on top, inflating the
+     * buffered requirement used for liquidation eligibility.
+     * @param marginRequirement Margin required for this position, QUOTE_PRECISION (1e6).
+     * @param liabilityValue Position's (worst-case) liability value the buffer is scaled from, QUOTE_PRECISION (1e6).
+     */
     addCrossMarginRequirement(marginRequirement: BN, liabilityValue: BN): void;
+    /**
+     * Records (or overwrites) the margin state for one isolated perp position, applying that
+     * market's isolated margin buffer (from `context.isolatedMarginBuffers`) to the
+     * buffered requirement, and to the buffered collateral only when `pnl` is negative —
+     * mirroring `addCrossMarginRequirement`/`addCrossMarginTotalCollateral` but scoped to a
+     * single isolated market instead of the shared cross-margin book.
+     * @param marketIndex Perp market index of the isolated position.
+     * @param depositValue Isolated collateral deposited into the position, QUOTE_PRECISION (1e6).
+     * @param pnl Position's unrealized/settled pnl, QUOTE_PRECISION (1e6, signed).
+     * @param liabilityValue Position's (worst-case) liability value the buffer is scaled from, QUOTE_PRECISION (1e6).
+     * @param marginRequirement Margin required to maintain/open the isolated position, QUOTE_PRECISION (1e6).
+     */
     addIsolatedMarginCalculation(marketIndex: number, depositValue: BN, pnl: BN, liabilityValue: BN, marginRequirement: BN): void;
+    /** Adds to the running total of worst-case perp liability value across all perp positions seen. @param perpLiabilityValue QUOTE_PRECISION (1e6). */
     addPerpLiabilityValue(perpLiabilityValue: BN): void;
+    /** Increments the count of spot positions counted as liabilities (borrows, or zero-balance positions with open orders). Call once per qualifying spot position. */
+    addSpotLiability(): void;
+    /** Increments the count of perp positions counted as liabilities (non-flat base, negative quote, or open orders). Call once per qualifying perp position. */
+    addPerpLiability(): void;
+    /** Latches `withSpotIsolatedLiability` to `true` if `isolated` is true (sticky OR — never reset to false once set). Pass whether the spot liability just added belongs to an `AssetTier::Isolated` market. */
+    updateWithSpotIsolatedLiability(isolated: boolean): void;
+    /** Latches `withPerpIsolatedLiability` to `true` if `isolated` is true (sticky OR — never reset to false once set). Pass whether the perp liability just added belongs to a `ContractTier::Isolated` market. */
+    updateWithPerpIsolatedLiability(isolated: boolean): void;
+    /** Total number of liability positions (spot borrows + perp liabilities) counted so far. */
+    getNumOfLiabilities(): number;
+    /** `totalCollateral + totalCollateralBuffer` for the cross-margin book, QUOTE_PRECISION (1e6). */
     getCrossTotalCollateralPlusBuffer(): BN;
+    /** True if the cross-margin book's collateral covers its margin requirement (no buffer applied). */
     meetsCrossMarginRequirement(): boolean;
+    /** True if the cross-margin book's buffered collateral covers its buffered margin requirement — the check used for cross-margin liquidation eligibility. */
     meetsCrossMarginRequirementWithBuffer(): boolean;
+    /** True only if the cross-margin book AND every tracked isolated position independently meet their (unbuffered) margin requirement. */
     meetsMarginRequirement(): boolean;
+    /** True only if the cross-margin book AND every tracked isolated position independently meet their buffered margin requirement — the overall liquidation-eligibility check. */
     meetsMarginRequirementWithBuffer(): boolean;
+    /** Cross-margin collateral in excess of its margin requirement, floored at zero, QUOTE_PRECISION (1e6). */
     getCrossFreeCollateral(): BN;
+    /**
+     * Free (unbuffered) collateral for one isolated perp position, floored at zero, QUOTE_PRECISION (1e6).
+     * @param marketIndex Perp market index of the isolated position.
+     * @throws if no isolated margin calculation was recorded for `marketIndex` (call `addIsolatedMarginCalculation` first).
+     */
     getIsolatedFreeCollateral(marketIndex: number): BN;
+    /** Returns the recorded `IsolatedMarginCalculation` for `marketIndex`, or `undefined` if none was recorded (the user has no isolated position in that market). */
     getIsolatedMarginCalculation(marketIndex: number): IsolatedMarginCalculation | undefined;
+    /** True if an isolated margin calculation has been recorded for `marketIndex`. */
     hasIsolatedMarginCalculation(marketIndex: number): boolean;
 }
 //# sourceMappingURL=marginCalculation.d.ts.map

package/lib/node/marginCalculation.d.ts.map

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

package/lib/node/marginCalculation.js

@@ -3,17 +3,21 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MarginCalculation = exports.IsolatedMarginCalculation = exports.MarginContext = exports.MarketIdentifier = void 0;
 const numericConstants_1 = require("./constants/numericConstants");
 const types_1 = require("./types");
+/** Identifies a market by type (spot or perp) and index, used as a key into per-market margin state (e.g. isolated margin buffers). Construct via `MarketIdentifier.spot` / `MarketIdentifier.perp`. */
 class MarketIdentifier {
     constructor(marketType, marketIndex) {
         this.marketType = marketType;
         this.marketIndex = marketIndex;
     }
+    /** Builds a `MarketIdentifier` for a spot market index. */
     static spot(marketIndex) {
         return new MarketIdentifier(types_1.MarketType.SPOT, marketIndex);
     }
+    /** Builds a `MarketIdentifier` for a perp market index. */
     static perp(marketIndex) {
         return new MarketIdentifier(types_1.MarketType.PERP, marketIndex);
     }
+    /** True if `other` refers to the same market type and index. */
     equals(other) {
         return (!!other &&
             (0, types_1.isVariant)(this.marketType, (0, types_1.getVariant)(other.marketType)) &&
@@ -21,6 +25,14 @@ class MarketIdentifier {
     }
 }
 exports.MarketIdentifier = MarketIdentifier;
+/**
+ * Configuration driving a `MarginCalculation` pass: which margin category to compute,
+ * whether it's a plain health check or a liquidation-margin-freed calculation, and the
+ * per-market buffers (in `MARGIN_PRECISION`, 1e4, fractional-of-liability-value units)
+ * applied to cross-margin and isolated-margin requirements/collateral so a user isn't
+ * flagged liquidatable from a hair's-width shortfall. Mirrors `MarginContext` in
+ * `programs/velocity/src/state/margin_calculation.rs`.
+ */
 class MarginContext {
     constructor(marginType) {
         this.marginType = marginType;
@@ -30,9 +42,19 @@ class MarginContext {
         this.isolatedMarginBuffers = new Map();
         this.crossMarginBuffer = numericConstants_1.ZERO;
     }
+    /** Builds a plain `Standard`-mode context (no liquidation buffers) for the given margin category — the usual choice for health/leverage/order-placement checks. */
     static standard(marginType) {
         return new MarginContext(marginType);
     }
+    /**
+     * Builds a `Maintenance`-category, `Liquidation`-mode context with the given buffers.
+     * Used by liquidation eligibility / margin-freed calculations so a position is only
+     * eligible once it's underwater by more than the buffer, avoiding flip-flopping right
+     * at the maintenance threshold.
+     * @param crossMarginBuffer Extra maintenance-margin cushion applied to the cross-margin
+     *   book, `MARGIN_PRECISION` (1e4) fraction of liability value.
+     * @param isolatedMarginBuffers Same buffer, per isolated-position market index.
+     */
     static liquidation(crossMarginBuffer, isolatedMarginBuffers) {
         const ctx = new MarginContext('Maintenance');
         ctx.mode = { type: 'Liquidation' };
@@ -40,28 +62,40 @@ class MarginContext {
         ctx.isolatedMarginBuffers = isolatedMarginBuffers;
         return ctx;
     }
+    /** Sets whether strict oracle pricing (worse of last/twap price) is used for collateral/liability valuation. Returns `this` for chaining. */
     strictMode(strict) {
         this.strict = strict;
         return this;
     }
+    /** Sets whether spot deposits with an invalid oracle are ignored (valued at zero) rather than failing the calculation. Returns `this` for chaining. */
     ignoreInvalidDeposits(ignore) {
         this.ignoreInvalidDepositOracles = ignore;
         return this;
     }
+    /** Sets the cross-margin maintenance buffer (`MARGIN_PRECISION`, 1e4, fraction of liability value). Returns `this` for chaining. */
     setCrossMarginBuffer(crossMarginBuffer) {
         this.crossMarginBuffer = crossMarginBuffer;
         return this;
     }
+    /** Replaces the whole per-market isolated-margin buffer map. Returns `this` for chaining. */
     setIsolatedMarginBuffers(isolatedMarginBuffers) {
         this.isolatedMarginBuffers = isolatedMarginBuffers;
         return this;
     }
+    /** Sets the isolated-margin buffer (`MARGIN_PRECISION`, 1e4, fraction of liability value) for a single perp market index. Returns `this` for chaining. */
     setIsolatedMarginBuffer(marketIndex, isolatedMarginBuffer) {
         this.isolatedMarginBuffers.set(marketIndex, isolatedMarginBuffer);
         return this;
     }
 }
 exports.MarginContext = MarginContext;
+/**
+ * Accumulated margin requirement and collateral for a single isolated perp position,
+ * built up during a `MarginCalculation` pass via `MarginCalculation.addIsolatedMarginCalculation`.
+ * All BN fields are QUOTE_PRECISION (1e6). Isolated positions have their own dedicated
+ * collateral pool, so their margin health is tracked independently of the user's
+ * cross-margin book.
+ */
 class IsolatedMarginCalculation {
     constructor() {
         this.marginRequirement = numericConstants_1.ZERO;
@@ -69,21 +103,42 @@ class IsolatedMarginCalculation {
         this.totalCollateralBuffer = numericConstants_1.ZERO;
         this.marginRequirementPlusBuffer = numericConstants_1.ZERO;
     }
+    /** `totalCollateral + totalCollateralBuffer`, QUOTE_PRECISION (1e6). */
     getTotalCollateralPlusBuffer() {
         return this.totalCollateral.add(this.totalCollateralBuffer);
     }
+    /** True if the isolated position's collateral covers its margin requirement (no buffer applied). */
     meetsMarginRequirement() {
         return this.totalCollateral.gte(this.marginRequirement);
     }
+    /** True if the buffered collateral covers the buffered margin requirement — the check used for liquidation eligibility. */
     meetsMarginRequirementWithBuffer() {
         return this.getTotalCollateralPlusBuffer().gte(this.marginRequirementPlusBuffer);
     }
+    /** Buffered margin shortfall (`marginRequirementPlusBuffer - totalCollateralPlusBuffer`, floored at zero), QUOTE_PRECISION (1e6). */
     marginShortage() {
         const shortage = this.marginRequirementPlusBuffer.sub(this.getTotalCollateralPlusBuffer());
         return shortage.isNeg() ? numericConstants_1.ZERO : shortage;
     }
 }
 exports.IsolatedMarginCalculation = IsolatedMarginCalculation;
+/**
+ * Accumulator built up by walking a user's spot and perp positions, mirroring
+ * `MarginCalculation` in `programs/velocity/src/state/margin_calculation.rs`. Tracks the
+ * cross-margin book's total collateral/margin requirement plus a separate
+ * `IsolatedMarginCalculation` per isolated perp market, so cross and isolated health are
+ * evaluated independently — `meetsMarginRequirement`/`meetsMarginRequirementWithBuffer`
+ * require both the cross book and every isolated position to pass.
+ *
+ * `numSpotLiabilities`/`numPerpLiabilities`/`withPerpIsolatedLiability`/
+ * `withSpotIsolatedLiability` track the on-chain "isolated contract tier" risk-isolation
+ * rule (`validate_any_isolated_tier_requirements`): a user holding a liability in a market
+ * whose `ContractTier` is `Isolated` may not simultaneously hold other liabilities (perp or
+ * non-quote spot) unless in reduce-only mode. Note this `ContractTier::Isolated` market
+ * classification is unrelated to per-position isolated margin
+ * (`isolatedPositionScaledBalance`) — a market can be isolated-tier without any position on
+ * it using isolated margin.
+ */
 class MarginCalculation {
     constructor(context) {
         this.context = context;
@@ -93,7 +148,19 @@ class MarginCalculation {
         this.marginRequirementPlusBuffer = numericConstants_1.ZERO;
         this.isolatedMarginCalculations = new Map();
         this.totalPerpLiabilityValue = numericConstants_1.ZERO;
+        this.numSpotLiabilities = 0;
+        this.numPerpLiabilities = 0;
+        this.withPerpIsolatedLiability = false;
+        this.withSpotIsolatedLiability = false;
     }
+    /**
+     * Adds a signed collateral delta (deposit value or perp pnl, QUOTE_PRECISION 1e6) to
+     * the cross-margin book. When in `Liquidation` mode with a nonzero `crossMarginBuffer`
+     * and the delta is negative, also extends `totalCollateralBuffer` by
+     * `delta * crossMarginBuffer / MARGIN_PRECISION` so a negative-pnl position looks worse
+     * under the buffered (liquidation-eligibility) check than under the plain one.
+     * @param delta Signed collateral value to add, QUOTE_PRECISION (1e6).
+     */
     addCrossMarginTotalCollateral(delta) {
         const crossMarginBuffer = this.context.crossMarginBuffer;
         this.totalCollateral = this.totalCollateral.add(delta);
@@ -101,6 +168,14 @@ class MarginCalculation {
             this.totalCollateralBuffer = this.totalCollateralBuffer.add(delta.mul(crossMarginBuffer).div(numericConstants_1.MARGIN_PRECISION));
         }
     }
+    /**
+     * Adds a position's margin requirement to the cross-margin book. When a nonzero
+     * `crossMarginBuffer` is configured, also accrues `marginRequirementPlusBuffer` with an
+     * extra `liabilityValue * crossMarginBuffer / MARGIN_PRECISION` on top, inflating the
+     * buffered requirement used for liquidation eligibility.
+     * @param marginRequirement Margin required for this position, QUOTE_PRECISION (1e6).
+     * @param liabilityValue Position's (worst-case) liability value the buffer is scaled from, QUOTE_PRECISION (1e6).
+     */
     addCrossMarginRequirement(marginRequirement, liabilityValue) {
         const crossMarginBuffer = this.context.crossMarginBuffer;
         this.marginRequirement = this.marginRequirement.add(marginRequirement);
@@ -108,6 +183,18 @@ class MarginCalculation {
             this.marginRequirementPlusBuffer = this.marginRequirementPlusBuffer.add(marginRequirement.add(liabilityValue.mul(crossMarginBuffer).div(numericConstants_1.MARGIN_PRECISION)));
         }
     }
+    /**
+     * Records (or overwrites) the margin state for one isolated perp position, applying that
+     * market's isolated margin buffer (from `context.isolatedMarginBuffers`) to the
+     * buffered requirement, and to the buffered collateral only when `pnl` is negative —
+     * mirroring `addCrossMarginRequirement`/`addCrossMarginTotalCollateral` but scoped to a
+     * single isolated market instead of the shared cross-margin book.
+     * @param marketIndex Perp market index of the isolated position.
+     * @param depositValue Isolated collateral deposited into the position, QUOTE_PRECISION (1e6).
+     * @param pnl Position's unrealized/settled pnl, QUOTE_PRECISION (1e6, signed).
+     * @param liabilityValue Position's (worst-case) liability value the buffer is scaled from, QUOTE_PRECISION (1e6).
+     * @param marginRequirement Margin required to maintain/open the isolated position, QUOTE_PRECISION (1e6).
+     */
     addIsolatedMarginCalculation(marketIndex, depositValue, pnl, liabilityValue, marginRequirement) {
         var _a;
         const totalCollateral = depositValue.add(pnl);
@@ -125,19 +212,44 @@ class MarginCalculation {
         iso.marginRequirementPlusBuffer = marginRequirementPlusBuffer;
         this.isolatedMarginCalculations.set(marketIndex, iso);
     }
+    /** Adds to the running total of worst-case perp liability value across all perp positions seen. @param perpLiabilityValue QUOTE_PRECISION (1e6). */
     addPerpLiabilityValue(perpLiabilityValue) {
         this.totalPerpLiabilityValue =
             this.totalPerpLiabilityValue.add(perpLiabilityValue);
     }
+    /** Increments the count of spot positions counted as liabilities (borrows, or zero-balance positions with open orders). Call once per qualifying spot position. */
+    addSpotLiability() {
+        this.numSpotLiabilities += 1;
+    }
+    /** Increments the count of perp positions counted as liabilities (non-flat base, negative quote, or open orders). Call once per qualifying perp position. */
+    addPerpLiability() {
+        this.numPerpLiabilities += 1;
+    }
+    /** Latches `withSpotIsolatedLiability` to `true` if `isolated` is true (sticky OR — never reset to false once set). Pass whether the spot liability just added belongs to an `AssetTier::Isolated` market. */
+    updateWithSpotIsolatedLiability(isolated) {
+        this.withSpotIsolatedLiability = this.withSpotIsolatedLiability || isolated;
+    }
+    /** Latches `withPerpIsolatedLiability` to `true` if `isolated` is true (sticky OR — never reset to false once set). Pass whether the perp liability just added belongs to a `ContractTier::Isolated` market. */
+    updateWithPerpIsolatedLiability(isolated) {
+        this.withPerpIsolatedLiability = this.withPerpIsolatedLiability || isolated;
+    }
+    /** Total number of liability positions (spot borrows + perp liabilities) counted so far. */
+    getNumOfLiabilities() {
+        return this.numSpotLiabilities + this.numPerpLiabilities;
+    }
+    /** `totalCollateral + totalCollateralBuffer` for the cross-margin book, QUOTE_PRECISION (1e6). */
     getCrossTotalCollateralPlusBuffer() {
         return this.totalCollateral.add(this.totalCollateralBuffer);
     }
+    /** True if the cross-margin book's collateral covers its margin requirement (no buffer applied). */
     meetsCrossMarginRequirement() {
         return this.totalCollateral.gte(this.marginRequirement);
     }
+    /** True if the cross-margin book's buffered collateral covers its buffered margin requirement — the check used for cross-margin liquidation eligibility. */
     meetsCrossMarginRequirementWithBuffer() {
         return this.getCrossTotalCollateralPlusBuffer().gte(this.marginRequirementPlusBuffer);
     }
+    /** True only if the cross-margin book AND every tracked isolated position independently meet their (unbuffered) margin requirement. */
     meetsMarginRequirement() {
         if (!this.meetsCrossMarginRequirement())
             return false;
@@ -147,6 +259,7 @@ class MarginCalculation {
         }
         return true;
     }
+    /** True only if the cross-margin book AND every tracked isolated position independently meet their buffered margin requirement — the overall liquidation-eligibility check. */
     meetsMarginRequirementWithBuffer() {
         if (!this.meetsCrossMarginRequirementWithBuffer())
             return false;
@@ -156,10 +269,16 @@ class MarginCalculation {
         }
         return true;
     }
+    /** Cross-margin collateral in excess of its margin requirement, floored at zero, QUOTE_PRECISION (1e6). */
     getCrossFreeCollateral() {
         const free = this.totalCollateral.sub(this.marginRequirement);
         return free.isNeg() ? numericConstants_1.ZERO : free;
     }
+    /**
+     * Free (unbuffered) collateral for one isolated perp position, floored at zero, QUOTE_PRECISION (1e6).
+     * @param marketIndex Perp market index of the isolated position.
+     * @throws if no isolated margin calculation was recorded for `marketIndex` (call `addIsolatedMarginCalculation` first).
+     */
     getIsolatedFreeCollateral(marketIndex) {
         const iso = this.isolatedMarginCalculations.get(marketIndex);
         if (!iso)
@@ -167,9 +286,11 @@ class MarginCalculation {
         const free = iso.totalCollateral.sub(iso.marginRequirement);
         return free.isNeg() ? numericConstants_1.ZERO : free;
     }
+    /** Returns the recorded `IsolatedMarginCalculation` for `marketIndex`, or `undefined` if none was recorded (the user has no isolated position in that market). */
     getIsolatedMarginCalculation(marketIndex) {
         return this.isolatedMarginCalculations.get(marketIndex);
     }
+    /** True if an isolated margin calculation has been recorded for `marketIndex`. */
     hasIsolatedMarginCalculation(marketIndex) {
         return this.isolatedMarginCalculations.has(marketIndex);
     }