@velocity-exchange/sdk 0.3.0 → 0.6.0

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);
     }