@velocity-exchange/sdk 0.2.5 → 0.4.0

package/src/idl/velocity.ts

@@ -11074,6 +11074,35 @@ export type Velocity = {
         }
       ]
     },
+    {
+      "name": "updateSolvencyStatus",
+      "discriminator": [
+        81,
+        136,
+        15,
+        6,
+        24,
+        165,
+        44,
+        133
+      ],
+      "accounts": [
+        {
+          "name": "state",
+          "writable": true
+        },
+        {
+          "name": "admin",
+          "signer": true
+        }
+      ],
+      "args": [
+        {
+          "name": "solvencyStatus",
+          "type": "u8"
+        }
+      ]
+    },
     {
       "name": "updateSpecialUserStatus",
       "discriminator": [
@@ -15978,6 +16007,16 @@ export type Velocity = {
       "code": 6354,
       "name": "insufficientProtocolFees",
       "msg": "Insufficient protocol fees available to withdraw"
+    },
+    {
+      "code": 6355,
+      "name": "invalidNativeStateAccount",
+      "msg": "Native dispatch: supplied state account is not the canonical Velocity state PDA"
+    },
+    {
+      "code": 6356,
+      "name": "invalidNativePerpMarketAccount",
+      "msg": "Native dispatch: supplied market account is not a Velocity perp market"
     }
   ],
   "types": [
@@ -23213,6 +23252,16 @@ export type Velocity = {
             "name": "lpPoolFeatureBitFlags",
             "type": "u8"
           },
+          {
+            "name": "solvencyStatus",
+            "docs": [
+              "Bitmask of `SolvencyStatus` flags. Gates internal solvency-repair flows",
+              "(bankruptcy / pnl-deficit resolution) independently of `WithdrawPaused`,",
+              "so user withdrawals can be halted while repair keeps running, or repair",
+              "can be frozen on its own when an oracle is suspect. `0` = repair allowed."
+            ],
+            "type": "u8"
+          },
           {
             "name": "protocolFeeRecipientPerp",
             "docs": [
@@ -23247,7 +23296,7 @@ export type Velocity = {
             "type": {
               "array": [
                 "u8",
-                272
+                271
               ]
             }
           }

package/src/keypair.ts

@@ -2,6 +2,14 @@ import fs from 'fs';
 import bs58 from 'bs58';
 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 function loadKeypair(privateKey: string): Keypair {
 	// try to load privateKey as a filepath
 	let loadedKey: Uint8Array;

package/src/marginCalculation.ts

@@ -1,13 +1,21 @@
 import { BN } from './isomorphic/anchor';
 import { MARGIN_PRECISION, ZERO } from './constants/numericConstants';
-import { getVariant, isVariant, MarketType } from './types';
+import { getVariant, isVariant, MarginCategory, MarketType } from './types';
 
-export type MarginCategory = 'Initial' | 'Maintenance' | 'Fill';
+/**
+ * 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 class MarketIdentifier {
 	marketType: MarketType;
 	marketIndex: number;
@@ -17,14 +25,17 @@ export class MarketIdentifier {
 		this.marketIndex = marketIndex;
 	}
 
+	/** Builds a `MarketIdentifier` for a spot market index. */
 	static spot(marketIndex: number): MarketIdentifier {
 		return new MarketIdentifier(MarketType.SPOT, marketIndex);
 	}
 
+	/** Builds a `MarketIdentifier` for a perp market index. */
 	static perp(marketIndex: number): MarketIdentifier {
 		return new MarketIdentifier(MarketType.PERP, marketIndex);
 	}
 
+	/** True if `other` refers to the same market type and index. */
 	equals(other: MarketIdentifier | undefined): boolean {
 		return (
 			!!other &&
@@ -34,6 +45,14 @@ export class 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`.
+ */
 export class MarginContext {
 	marginType: MarginCategory;
 	mode: MarginCalculationMode;
@@ -51,10 +70,20 @@ export class MarginContext {
 		this.crossMarginBuffer = 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: MarginCategory): MarginContext {
 		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: BN,
 		isolatedMarginBuffers: Map<number, BN>
@@ -66,34 +95,50 @@ export class MarginContext {
 		return ctx;
 	}
 
+	/** Sets whether strict oracle pricing (worse of last/twap price) is used for collateral/liability valuation. Returns `this` for chaining. */
 	strictMode(strict: boolean): this {
 		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: boolean): this {
 		this.ignoreInvalidDepositOracles = ignore;
 		return this;
 	}
 
+	/** Sets the cross-margin maintenance buffer (`MARGIN_PRECISION`, 1e4, fraction of liability value). Returns `this` for chaining. */
 	setCrossMarginBuffer(crossMarginBuffer: BN): this {
 		this.crossMarginBuffer = crossMarginBuffer;
 		return this;
 	}
+	/** Replaces the whole per-market isolated-margin buffer map. Returns `this` for chaining. */
 	setIsolatedMarginBuffers(isolatedMarginBuffers: Map<number, BN>): this {
 		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: number, isolatedMarginBuffer: BN): this {
 		this.isolatedMarginBuffers.set(marketIndex, isolatedMarginBuffer);
 		return 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 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; // deposit + pnl
+	/** 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() {
@@ -103,20 +148,24 @@ export class IsolatedMarginCalculation {
 		this.marginRequirementPlusBuffer = ZERO;
 	}
 
+	/** `totalCollateral + totalCollateralBuffer`, QUOTE_PRECISION (1e6). */
 	getTotalCollateralPlusBuffer(): BN {
 		return this.totalCollateral.add(this.totalCollateralBuffer);
 	}
 
+	/** True if the isolated position's collateral covers its margin requirement (no buffer applied). */
 	meetsMarginRequirement(): boolean {
 		return this.totalCollateral.gte(this.marginRequirement);
 	}
 
+	/** True if the buffered collateral covers the buffered margin requirement — the check used for liquidation eligibility. */
 	meetsMarginRequirementWithBuffer(): boolean {
 		return this.getTotalCollateralPlusBuffer().gte(
 			this.marginRequirementPlusBuffer
 		);
 	}
 
+	/** Buffered margin shortfall (`marginRequirementPlusBuffer - totalCollateralPlusBuffer`, floored at zero), QUOTE_PRECISION (1e6). */
 	marginShortage(): BN {
 		const shortage = this.marginRequirementPlusBuffer.sub(
 			this.getTotalCollateralPlusBuffer()
@@ -125,14 +174,45 @@ export class 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.
+ */
 export 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) {
 		this.context = context;
@@ -142,8 +222,20 @@ export class MarginCalculation {
 		this.marginRequirementPlusBuffer = ZERO;
 		this.isolatedMarginCalculations = new Map();
 		this.totalPerpLiabilityValue = 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: BN): void {
 		const crossMarginBuffer = this.context.crossMarginBuffer;
 		this.totalCollateral = this.totalCollateral.add(delta);
@@ -154,6 +246,14 @@ export class MarginCalculation {
 		}
 	}
 
+	/**
+	 * 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 {
 		const crossMarginBuffer = this.context.crossMarginBuffer;
 		this.marginRequirement = this.marginRequirement.add(marginRequirement);
@@ -166,6 +266,18 @@ export class MarginCalculation {
 		}
 	}
 
+	/**
+	 * 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,
@@ -196,25 +308,55 @@ export class MarginCalculation {
 		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: BN): void {
 		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(): void {
+		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(): void {
+		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: boolean): void {
+		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: boolean): void {
+		this.withPerpIsolatedLiability = this.withPerpIsolatedLiability || isolated;
+	}
+
+	/** Total number of liability positions (spot borrows + perp liabilities) counted so far. */
+	getNumOfLiabilities(): number {
+		return this.numSpotLiabilities + this.numPerpLiabilities;
+	}
+
+	/** `totalCollateral + totalCollateralBuffer` for the cross-margin book, QUOTE_PRECISION (1e6). */
 	getCrossTotalCollateralPlusBuffer(): BN {
 		return this.totalCollateral.add(this.totalCollateralBuffer);
 	}
 
+	/** True if the cross-margin book's collateral covers its margin requirement (no buffer applied). */
 	meetsCrossMarginRequirement(): boolean {
 		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(): boolean {
 		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(): boolean {
 		if (!this.meetsCrossMarginRequirement()) return false;
 		for (const [, iso] of this.isolatedMarginCalculations) {
@@ -223,6 +365,7 @@ export 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(): boolean {
 		if (!this.meetsCrossMarginRequirementWithBuffer()) return false;
 		for (const [, iso] of this.isolatedMarginCalculations) {
@@ -231,11 +374,17 @@ export class MarginCalculation {
 		return true;
 	}
 
+	/** Cross-margin collateral in excess of its margin requirement, floored at zero, QUOTE_PRECISION (1e6). */
 	getCrossFreeCollateral(): BN {
 		const free = this.totalCollateral.sub(this.marginRequirement);
 		return free.isNeg() ? 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: number): BN {
 		const iso = this.isolatedMarginCalculations.get(marketIndex);
 		if (!iso)
@@ -244,12 +393,14 @@ export class MarginCalculation {
 		return free.isNeg() ? 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: number
 	): IsolatedMarginCalculation | undefined {
 		return this.isolatedMarginCalculations.get(marketIndex);
 	}
 
+	/** True if an isolated margin calculation has been recorded for `marketIndex`. */
 	hasIsolatedMarginCalculation(marketIndex: number): boolean {
 		return this.isolatedMarginCalculations.has(marketIndex);
 	}