@drift-labs/sdk-browser 2.155.0-beta.3 → 2.155.0-beta.5

package/src/margin/README.md

@@ -0,0 +1,139 @@
+## Margin Calculation Snapshot (SDK)
+
+This document describes the single-source-of-truth margin engine in the SDK that mirrors the on-chain `MarginCalculation` and related semantics. The goal is to compute an immutable snapshot in one pass and have existing `User` getters delegate to it, eliminating duplicative work across getters and UI hooks while maintaining parity with the program.
+
+### Alignment with on-chain
+
+- The SDK snapshot shape mirrors `programs/drift/src/state/margin_calculation.rs` field-for-field.
+- The inputs and ordering mirror `calculate_margin_requirement_and_total_collateral_and_liability_info` in `programs/drift/src/math/margin.rs`.
+- Isolated positions are represented as `isolatedMarginCalculations` keyed by perp `marketIndex`, matching program logic.
+
+### Core SDK types (shape parity)
+
+```ts
+// Types reflect on-chain names and numeric signs
+import { MarketType } from './types';
+
+export type MarginCategory = 'Initial' | 'Maintenance' | 'Fill';
+
+export type MarginCalculationMode =
+  | { type: 'Standard' }
+  | { type: 'Liquidation' };
+
+export class MarketIdentifier {
+  marketType: MarketType;
+  marketIndex: number;
+
+  static spot(marketIndex: number): MarketIdentifier;
+  static perp(marketIndex: number): MarketIdentifier;
+  equals(other: MarketIdentifier | undefined): boolean;
+}
+
+export class MarginContext {
+  marginType: MarginCategory;
+  mode: MarginCalculationMode;
+  strict: boolean;
+  ignoreInvalidDepositOracles: boolean;
+  isolatedMarginBuffers: Map<number, BN>;
+  crossMarginBuffer: BN;
+
+  // Factory methods
+  static standard(marginType: MarginCategory): MarginContext;
+  static liquidation(
+    crossMarginBuffer: BN,
+    isolatedMarginBuffers: Map<number, BN>
+  ): MarginContext;
+
+  // Builder methods (return this for chaining)
+  strictMode(strict: boolean): this;
+  ignoreInvalidDeposits(ignore: boolean): this;
+  setCrossMarginBuffer(crossMarginBuffer: BN): this;
+  setIsolatedMarginBuffers(isolatedMarginBuffers: Map<number, BN>): this;
+  setIsolatedMarginBuffer(marketIndex: number, isolatedMarginBuffer: BN): this;
+}
+
+export class IsolatedMarginCalculation {
+  marginRequirement: BN;             // u128
+  totalCollateral: BN;               // i128 (deposit + pnl)
+  totalCollateralBuffer: BN;         // i128
+  marginRequirementPlusBuffer: BN;   // u128
+
+  getTotalCollateralPlusBuffer(): BN;
+  meetsMarginRequirement(): boolean;
+  meetsMarginRequirementWithBuffer(): boolean;
+  marginShortage(): BN;
+}
+
+export class MarginCalculation {
+  context: MarginContext;
+
+  totalCollateral: BN;               // i128
+  totalCollateralBuffer: BN;         // i128
+  marginRequirement: BN;             // u128
+  marginRequirementPlusBuffer: BN;   // u128
+
+  isolatedMarginCalculations: Map<number, IsolatedMarginCalculation>;
+
+  totalPerpLiabilityValue: BN;       // u128
+
+  // Cross margin helpers
+  getCrossTotalCollateralPlusBuffer(): BN;
+  meetsCrossMarginRequirement(): boolean;
+  meetsCrossMarginRequirementWithBuffer(): boolean;
+  getCrossFreeCollateral(): BN;
+
+  // Combined (cross + isolated) helpers
+  meetsMarginRequirement(): boolean;
+  meetsMarginRequirementWithBuffer(): boolean;
+
+  // Isolated margin helpers
+  getIsolatedFreeCollateral(marketIndex: number): BN;
+  getIsolatedMarginCalculation(marketIndex: number): IsolatedMarginCalculation | undefined;
+  hasIsolatedMarginCalculation(marketIndex: number): boolean;
+}
+```
+
+### Computation model (on-demand)
+
+- The SDK computes the snapshot on-demand when `getMarginCalculation(...)` is called.
+- No event-driven recomputation by default (oracle prices can change every slot; recomputing every update would be wasteful).
+- Callers (UI/bots) decide polling frequency (e.g., UI can refresh every ~1s on active trade forms).
+
+### User integration
+
+`User` class provides the primary entrypoint:
+
+```ts
+public getMarginCalculation(
+  marginCategory: MarginCategory = 'Initial',
+  opts?: {
+    strict?: boolean;                              // mirror StrictOraclePrice application
+    includeOpenOrders?: boolean;                   // include open orders in margin calc
+    enteringHighLeverage?: boolean;                // entering high leverage mode
+    liquidationBufferMap?: Map<number | 'cross', BN>; // margin buffer for liquidation mode
+  }
+): MarginCalculation;
+```
+
+Existing getters delegate to the snapshot to avoid duplicate work:
+- `getTotalCollateral()` → `snapshot.totalCollateral`
+- `getMarginRequirement(mode)` → `snapshot.marginRequirement`
+- `getFreeCollateral()` → `snapshot.getCrossFreeCollateral()`
+- Per-market isolated FC → `snapshot.getIsolatedFreeCollateral(marketIndex)`
+
+### UI compatibility
+
+- All existing `User` getters remain and delegate to the snapshot, so current UI keeps working without call-site changes.
+- New consumers can call `user.getMarginCalculation()` to access isolated breakdowns via `isolatedMarginCalculations`.
+
+### Testing and parity
+
+- Golden tests comparing SDK snapshot against program outputs (cross and isolated, edge cases).
+- Keep math/rounding identical to program (ordering, buffers, funding, open-order IM, oracle strictness).
+
+### Migration plan (brief)
+
+1. Implement `types` and `engine` with strict parity; land behind a feature flag.
+2. Add `user.getMarginCalculation()` and delegate legacy getters.
+3. Optionally update UI hooks to read richer fields; not required for compatibility.
+4. Expand parity tests; enable by default after validation.

package/src/marginCalculation.ts

@@ -131,15 +131,7 @@ export class MarginCalculation {
 	marginRequirement: BN;
 	marginRequirementPlusBuffer: BN;
 	isolatedMarginCalculations: Map<number, IsolatedMarginCalculation>;
-	allDepositOraclesValid: boolean;
-	allLiabilityOraclesValid: boolean;
-	withPerpIsolatedLiability: boolean;
-	withSpotIsolatedLiability: boolean;
 	totalPerpLiabilityValue: BN;
-	trackedMarketMarginRequirement: BN;
-	fuelDeposits: number;
-	fuelBorrows: number;
-	fuelPositions: number;
 
 	constructor(context: MarginContext) {
 		this.context = context;
@@ -148,15 +140,7 @@ export class MarginCalculation {
 		this.marginRequirement = ZERO;
 		this.marginRequirementPlusBuffer = ZERO;
 		this.isolatedMarginCalculations = new Map();
-		this.allDepositOraclesValid = true;
-		this.allLiabilityOraclesValid = true;
-		this.withPerpIsolatedLiability = false;
-		this.withSpotIsolatedLiability = false;
 		this.totalPerpLiabilityValue = ZERO;
-		this.trackedMarketMarginRequirement = ZERO;
-		this.fuelDeposits = 0;
-		this.fuelBorrows = 0;
-		this.fuelPositions = 0;
 	}
 
 	addCrossMarginTotalCollateral(delta: BN): void {
@@ -216,22 +200,6 @@ export class MarginCalculation {
 			this.totalPerpLiabilityValue.add(perpLiabilityValue);
 	}
 
-	updateAllDepositOraclesValid(valid: boolean): void {
-		this.allDepositOraclesValid = this.allDepositOraclesValid && valid;
-	}
-
-	updateAllLiabilityOraclesValid(valid: boolean): void {
-		this.allLiabilityOraclesValid = this.allLiabilityOraclesValid && valid;
-	}
-
-	updateWithSpotIsolatedLiability(isolated: boolean): void {
-		this.withSpotIsolatedLiability = this.withSpotIsolatedLiability || isolated;
-	}
-
-	updateWithPerpIsolatedLiability(isolated: boolean): void {
-		this.withPerpIsolatedLiability = this.withPerpIsolatedLiability || isolated;
-	}
-
 	getCrossTotalCollateralPlusBuffer(): BN {
 		return this.totalCollateral.add(this.totalCollateralBuffer);
 	}

package/src/math/margin.ts

@@ -166,10 +166,10 @@ export function calculateWorstCasePerpLiabilityValue(
 	perpPosition: PerpPosition,
 	perpMarket: PerpMarketAccount,
 	oraclePrice: BN,
-	includeOpenOrders = true
+	includeOpenOrders: boolean = true
 ): { worstCaseBaseAssetAmount: BN; worstCaseLiabilityValue: BN } {
 	const isPredictionMarket = isVariant(perpMarket.contractType, 'prediction');
-
+	// return early if no open orders required
 	if (!includeOpenOrders) {
 		return {
 			worstCaseBaseAssetAmount: perpPosition.baseAssetAmount,
@@ -180,7 +180,6 @@ export function calculateWorstCasePerpLiabilityValue(
 			),
 		};
 	}
-
 	const allBids = perpPosition.baseAssetAmount.add(perpPosition.openBids);
 	const allAsks = perpPosition.baseAssetAmount.add(perpPosition.openAsks);
 

package/src/math/position.ts

@@ -14,6 +14,7 @@ import {
 	PositionDirection,
 	PerpPosition,
 	SpotMarketAccount,
+	PositionFlag,
 } from '../types';
 import {
 	calculateUpdatedAMM,
@@ -127,7 +128,6 @@ export function calculatePositionPNL(
 
 	if (withFunding) {
 		const fundingRatePnL = calculateUnsettledFundingPnl(market, perpPosition);
-
 		pnl = pnl.add(fundingRatePnL);
 	}
 
@@ -244,7 +244,17 @@ export function positionIsAvailable(position: PerpPosition): boolean {
 		position.baseAssetAmount.eq(ZERO) &&
 		position.openOrders === 0 &&
 		position.quoteAssetAmount.eq(ZERO) &&
-		position.lpShares.eq(ZERO)
+		position.lpShares.eq(ZERO) &&
+		position.isolatedPositionScaledBalance.eq(ZERO) &&
+		!positionIsBeingLiquidated(position)
+	);
+}
+
+export function positionIsBeingLiquidated(position: PerpPosition): boolean {
+	return (
+		(position.positionFlag &
+			(PositionFlag.BeingLiquidated | PositionFlag.Bankruptcy)) >
+		0
 	);
 }
 

package/src/math/spotBalance.ts

@@ -68,7 +68,6 @@ export function getTokenAmount(
 	balanceType: SpotBalanceType
 ): BN {
 	const precisionDecrease = TEN.pow(new BN(19 - spotMarket.decimals));
-
 	if (isVariant(balanceType, 'deposit')) {
 		return balanceAmount
 			.mul(spotMarket.cumulativeDepositInterest)

package/src/swap/UnifiedSwapClient.ts

@@ -11,11 +11,7 @@ import {
 	JupiterClient,
 	QuoteResponse as JupiterQuoteResponse,
 } from '../jupiter/jupiterClient';
-import {
-	TitanClient,
-	QuoteResponse as TitanQuoteResponse,
-	SwapMode as TitanSwapMode,
-} from '../titan/titanClient';
+import { TitanClient, SwapMode as TitanSwapMode } from '../titan/titanClient';
 
 export type SwapMode = 'ExactIn' | 'ExactOut';
 export type SwapClientType = 'jupiter' | 'titan';
@@ -167,18 +163,11 @@ export class UnifiedSwapClient {
 			return { transaction };
 		} else {
 			const titanClient = this.client as TitanClient;
-			const { quote, userPublicKey, slippageBps } = params;
+			const { userPublicKey } = params;
 
 			// For Titan, we need to reconstruct the parameters from the quote
-			const titanQuote = quote as TitanQuoteResponse;
 			const result = await titanClient.getSwap({
-				inputMint: new PublicKey(titanQuote.inputMint),
-				outputMint: new PublicKey(titanQuote.outputMint),
-				amount: new BN(titanQuote.inAmount),
 				userPublicKey,
-				slippageBps: slippageBps || titanQuote.slippageBps,
-				swapMode: titanQuote.swapMode,
-				sizeConstraint: 1280 - 375, // MAX_TX_BYTE_SIZE - buffer for drift instructions
 			});
 
 			return {

package/src/titan/titanClient.ts

@@ -287,21 +287,11 @@ export class TitanClient {
 	 * Get a swap transaction for quote
 	 */
 	public async getSwap({
-		inputMint,
-		outputMint,
-		amount,
 		userPublicKey,
-		maxAccounts = 50, // 50 is an estimated amount with buffer
-		slippageBps,
-		swapMode,
-		onlyDirectRoutes,
-		excludeDexes,
-		sizeConstraint,
-		accountsLimitWritable,
 	}: {
-		inputMint: PublicKey;
-		outputMint: PublicKey;
-		amount: BN;
+		inputMint?: PublicKey;
+		outputMint?: PublicKey;
+		amount?: BN;
 		userPublicKey: PublicKey;
 		maxAccounts?: number;
 		slippageBps?: number;
@@ -314,22 +304,8 @@ export class TitanClient {
 		transactionMessage: TransactionMessage;
 		lookupTables: AddressLookupTableAccount[];
 	}> {
-		const params = this.buildParams({
-			inputMint,
-			outputMint,
-			amount,
-			userPublicKey,
-			maxAccounts,
-			slippageBps,
-			swapMode,
-			onlyDirectRoutes,
-			excludeDexes,
-			sizeConstraint,
-			accountsLimitWritable,
-		});
-
 		// Check if we have cached quote data that matches the current parameters
-		if (!this.lastQuoteData || this.lastQuoteParams !== params.toString()) {
+		if (!this.lastQuoteData) {
 			throw new Error(
 				'No matching quote data found. Please get a fresh quote before attempting to swap.'
 			);

package/src/types.ts

@@ -591,6 +591,10 @@ export type SpotBankruptcyRecord = {
 	ifPayment: BN;
 };
 
+export class LiquidationBitFlag {
+	static readonly IsolatedPosition = 1;
+}
+
 export type SettlePnlRecord = {
 	ts: BN;
 	user: PublicKey;
@@ -1142,16 +1146,10 @@ export type PerpPosition = {
 	maxMarginRatio: number;
 	lastQuoteAssetAmountPerLp: BN;
 	perLpBase: number;
-	isolatedPositionScaledBalance: BN;
 	positionFlag: number;
+	isolatedPositionScaledBalance: BN;
 };
 
-export class PositionFlag {
-	static readonly IsolatedPosition = 1;
-	static readonly BeingLiquidated = 2;
-	static readonly Bankruptcy = 4;
-}
-
 export type UserStatsAccount = {
 	numberOfSubAccounts: number;
 	numberOfSubAccountsCreated: number;
@@ -1302,6 +1300,12 @@ export class OrderParamsBitFlag {
 	static readonly UpdateHighLeverageMode = 2;
 }
 
+export class PositionFlag {
+	static readonly IsolatedPosition = 1;
+	static readonly BeingLiquidated = 2;
+	static readonly Bankruptcy = 4;
+}
+
 export type NecessaryOrderParams = {
 	orderType: OrderType;
 	marketIndex: number;

package/src/user.ts

@@ -504,8 +504,9 @@ export class User {
 			  )
 			: ZERO;
 
-		let freeCollateral: BN;
-		if (positionType === 'isolated' && this.isPositionEmpty(perpPosition)) {
+		let freeCollateral: BN = ZERO;
+		// if position is isolated, we always add on available quote from the cross account
+		if (positionType === 'isolated') {
 			const {
 				totalAssetValue: quoteSpotMarketAssetValue,
 				totalLiabilityValue: quoteSpotMarketLiabilityValue,
@@ -520,13 +521,16 @@ export class User {
 			freeCollateral = quoteSpotMarketAssetValue.sub(
 				quoteSpotMarketLiabilityValue
 			);
-		} else {
-			freeCollateral = this.getFreeCollateral(
+		}
+
+		// adding free collateral from the cross account or from within isolated margin calc for this marketIndex
+		freeCollateral = freeCollateral.add(
+			this.getFreeCollateral(
 				'Initial',
 				enterHighLeverageMode,
 				positionType === 'isolated' ? marketIndex : undefined
-			).sub(collateralBuffer);
-		}
+			).sub(collateralBuffer)
+		);
 
 		return this.getPerpBuyingPowerFromFreeCollateralAndBaseAssetAmount(
 			marketIndex,
@@ -574,7 +578,12 @@ export class User {
 		});
 
 		if (perpMarketIndex !== undefined) {
-			return calc.getIsolatedFreeCollateral(perpMarketIndex);
+			// getIsolatedFreeCollateral will throw if no existing isolated position but we are fetching for potential new position, so we wrap in a try/catch
+			try {
+				return calc.getIsolatedFreeCollateral(perpMarketIndex);
+			} catch (error) {
+				return ZERO;
+			}
 		} else {
 			return calc.getCrossFreeCollateral();
 		}
@@ -2363,7 +2372,7 @@ export class User {
 				enteringHighLeverage
 			);
 
-			if (freeCollateralDelta.eq(ZERO)) {
+			if (!freeCollateralDelta || freeCollateralDelta.eq(ZERO)) {
 				return new BN(-1);
 			}
 

package/tests/dlob/helpers.ts

@@ -781,4 +781,4 @@ export class MockUserMap implements UserMapInterface {
 			];
 		}
 	}
-}
+}

package/tests/user/test.ts

@@ -49,7 +49,7 @@ async function makeMockUser(
 		oraclePriceMap[myMockSpotMarkets[i].oracle.toString()] =
 			spotOraclePriceList[i];
 	}
-	// console.log(oraclePriceMap);
+	// console.log('oraclePriceMap:', oraclePriceMap);
 
 	function getMockUserAccount(): UserAccount {
 		return myMockUserAccount;