@velocity-exchange/sdk 0.0.1

package/src/math/liquidation.ts

@@ -0,0 +1,209 @@
+import { BN } from '../isomorphic/anchor';
+import {
+	PRICE_PRECISION,
+	LIQUIDATION_FEE_PRECISION,
+	MARGIN_PRECISION,
+	PRICE_TIMES_AMM_TO_QUOTE_PRECISION_RATIO,
+	QUOTE_PRECISION,
+	LIQUIDATION_PCT_PRECISION,
+	SPOT_MARKET_WEIGHT_PRECISION,
+	TEN,
+	ONE,
+} from '../constants/numericConstants';
+
+export function calculateBaseAssetAmountToCoverMarginShortage(
+	marginShortage: BN,
+	marginRatio: number,
+	liquidationFee: number,
+	ifLiquidationFee: number,
+	oraclePrice: BN,
+	quoteOraclePrice: BN
+): BN | undefined {
+	const marginRatioBN = new BN(marginRatio)
+		.mul(LIQUIDATION_FEE_PRECISION)
+		.div(MARGIN_PRECISION);
+	const liquidationFeeBN = new BN(liquidationFee);
+
+	if (oraclePrice.eq(new BN(0)) || marginRatioBN.lte(liquidationFeeBN)) {
+		// undefined is max
+		return undefined;
+	}
+
+	return marginShortage.mul(PRICE_TIMES_AMM_TO_QUOTE_PRECISION_RATIO).div(
+		oraclePrice
+			.mul(quoteOraclePrice)
+			.div(PRICE_PRECISION)
+			.mul(marginRatioBN.sub(liquidationFeeBN))
+			.div(LIQUIDATION_FEE_PRECISION)
+			.sub(
+				oraclePrice.mul(new BN(ifLiquidationFee)).div(LIQUIDATION_FEE_PRECISION)
+			)
+	);
+}
+
+export function calculateLiabilityTransferToCoverMarginShortage(
+	marginShortage: BN,
+	assetWeight: number,
+	assetLiquidationMultiplier: number,
+	liabilityWeight: number,
+	liabilityLiquidationMultiplier: number,
+	liabilityDecimals: number,
+	liabilityPrice: BN,
+	ifLiquidationFee: number
+): BN | undefined {
+	if (assetWeight >= liabilityWeight) {
+		// undefined is max
+		return undefined;
+	}
+
+	let numeratorScale: BN;
+	let denominatorScale: BN;
+	if (liabilityDecimals > 6) {
+		numeratorScale = new BN(10).pow(new BN(liabilityDecimals - 6));
+		denominatorScale = new BN(1);
+	} else {
+		numeratorScale = new BN(1);
+		denominatorScale = new BN(10).pow(new BN(6 - liabilityDecimals));
+	}
+
+	// multiply market weights by extra 10 to increase precision
+	const liabilityWeightComponent = liabilityWeight * 10;
+	const assetWeightComponent =
+		(assetWeight * 10 * assetLiquidationMultiplier) /
+		liabilityLiquidationMultiplier;
+
+	if (assetWeightComponent >= liabilityWeightComponent) {
+		return undefined;
+	}
+
+	return BN.max(
+		marginShortage
+			.mul(numeratorScale)
+			.mul(PRICE_PRECISION.mul(SPOT_MARKET_WEIGHT_PRECISION).mul(TEN))
+			.div(
+				liabilityPrice
+					.mul(
+						new BN(liabilityWeightComponent).sub(new BN(assetWeightComponent))
+					)
+					.sub(
+						liabilityPrice
+							.mul(new BN(ifLiquidationFee))
+							.div(LIQUIDATION_FEE_PRECISION)
+							.mul(new BN(liabilityWeight))
+							.mul(new BN(10))
+					)
+			)
+			.div(denominatorScale),
+		ONE
+	);
+}
+
+export function calculateAssetTransferForLiabilityTransfer(
+	assetAmount: BN,
+	assetLiquidationMultiplier: number,
+	assetDecimals: number,
+	assetPrice: BN,
+	liabilityAmount: BN,
+	liabilityLiquidationMultiplier: number,
+	liabilityDecimals: number,
+	liabilityPrice: BN
+): BN | undefined {
+	let numeratorScale: BN;
+	let denominatorScale: BN;
+	if (assetDecimals > liabilityDecimals) {
+		numeratorScale = new BN(10).pow(new BN(assetDecimals - liabilityDecimals));
+		denominatorScale = new BN(1);
+	} else {
+		numeratorScale = new BN(1);
+		denominatorScale = new BN(10).pow(
+			new BN(liabilityDecimals - assetDecimals)
+		);
+	}
+
+	let assetTransfer = liabilityAmount
+		.mul(numeratorScale)
+		.mul(liabilityPrice)
+		.mul(new BN(assetLiquidationMultiplier))
+		.div(assetPrice.mul(new BN(liabilityLiquidationMultiplier)))
+		.div(denominatorScale);
+	assetTransfer = BN.max(assetTransfer, ONE);
+
+	// Need to check if asset_transfer should be rounded to asset amount
+	let assetValueNumeratorScale: BN;
+	let assetValueDenominatorScale: BN;
+	if (assetDecimals > 6) {
+		assetValueNumeratorScale = new BN(10).pow(new BN(assetDecimals - 6));
+		assetValueDenominatorScale = new BN(1);
+	} else {
+		assetValueNumeratorScale = new BN(1);
+		assetValueDenominatorScale = new BN(10).pow(new BN(6 - assetDecimals));
+	}
+
+	let assetDelta: BN;
+	if (assetTransfer > assetAmount) {
+		assetDelta = assetTransfer.sub(assetAmount);
+	} else {
+		assetDelta = assetAmount.sub(assetTransfer);
+	}
+
+	const assetValueDelta = assetDelta
+		.mul(assetPrice)
+		.div(PRICE_PRECISION)
+		.mul(assetValueNumeratorScale)
+		.div(assetValueDenominatorScale);
+
+	if (assetValueDelta.lt(QUOTE_PRECISION)) {
+		assetTransfer = assetAmount;
+	}
+
+	return assetTransfer;
+}
+
+export function calculateMaxPctToLiquidate(
+	userLastActiveSlot: BN,
+	userLiquidationMarginFreed: BN,
+	marginShortage: BN,
+	slot: BN,
+	initialPctToLiquidate: BN,
+	liquidationDuration: BN
+): BN {
+	// if margin shortage is tiny, accelerate liquidation
+	if (marginShortage.lt(new BN(50).mul(QUOTE_PRECISION))) {
+		return LIQUIDATION_PCT_PRECISION;
+	}
+
+	let slotsElapsed;
+	if (userLiquidationMarginFreed.gt(new BN(0))) {
+		slotsElapsed = BN.max(slot.sub(userLastActiveSlot), new BN(0));
+	} else {
+		slotsElapsed = new BN(0);
+	}
+
+	const pctFreeable = BN.min(
+		slotsElapsed
+			.mul(LIQUIDATION_PCT_PRECISION)
+			.div(liquidationDuration) // ~ 1 minute if per slot is 400ms
+			.add(initialPctToLiquidate),
+		LIQUIDATION_PCT_PRECISION
+	);
+
+	const totalMarginShortage = marginShortage.add(userLiquidationMarginFreed);
+	const maxMarginFreed = totalMarginShortage
+		.mul(pctFreeable)
+		.div(LIQUIDATION_PCT_PRECISION);
+	const marginFreeable = BN.max(
+		maxMarginFreed.sub(userLiquidationMarginFreed),
+		new BN(0)
+	);
+
+	return marginFreeable.mul(LIQUIDATION_PCT_PRECISION).div(marginShortage);
+}
+
+export function getMarginShortage(
+	maintenanceMarginRequirementPlusBuffer: BN,
+	maintenanceTotalCollateral: BN
+): BN {
+	return maintenanceMarginRequirementPlusBuffer
+		.sub(maintenanceTotalCollateral)
+		.abs();
+}

package/src/math/margin.ts

@@ -0,0 +1,368 @@
+/**
+ * Margin calculation helpers — TypeScript mirror of `programs/drift/src/math/margin.rs`.
+ * Computes initial/maintenance margin requirements, free collateral, and account health.
+ * Used by {@link User} for leverage queries and by keeper bots for liquidation eligibility checks.
+ */
+import { squareRootBN } from './utils';
+import {
+	SPOT_MARKET_WEIGHT_PRECISION,
+	SPOT_MARKET_IMF_PRECISION,
+	ZERO,
+	BID_ASK_SPREAD_PRECISION,
+	AMM_RESERVE_PRECISION,
+	BASE_PRECISION,
+	MARGIN_PRECISION,
+	PRICE_PRECISION,
+	QUOTE_PRECISION,
+} from '../constants/numericConstants';
+import { BN } from '../isomorphic/anchor';
+import { OraclePriceData } from '../oracles/types';
+import { calculateMarketMarginRatio } from './market';
+import { calculateScaledInitialAssetWeight } from './spotBalance';
+import { VelocityClient } from '../velocityClient';
+import { OneShotUserAccountSubscriber } from '../accounts/oneShotUserAccountSubscriber';
+import {
+	PerpMarketAccount,
+	PerpPosition,
+	PositionDirection,
+	UserAccount,
+} from '../types';
+import { PublicKey } from '@solana/web3.js';
+import { User } from '../user';
+import { isVariant } from '../types';
+import { assert } from '../assert/assert';
+
+export function calculateSizePremiumLiabilityWeight(
+	size: BN, // AMM_RESERVE_PRECISION
+	imfFactor: BN,
+	liabilityWeight: BN,
+	precision: BN,
+	isBounded = true
+): BN {
+	if (imfFactor.eq(ZERO)) {
+		return liabilityWeight;
+	}
+
+	const sizeSqrt = squareRootBN(size.abs().mul(new BN(10)).add(new BN(1))); //1e9 -> 1e10 -> 1e5
+
+	const liabilityWeightNumerator = liabilityWeight.sub(
+		liabilityWeight.div(new BN(5))
+	);
+
+	const denom = new BN(100_000).mul(SPOT_MARKET_IMF_PRECISION).div(precision);
+	assert(denom.gt(ZERO));
+
+	const sizePremiumLiabilityWeight = liabilityWeightNumerator.add(
+		sizeSqrt // 1e5
+			.mul(imfFactor)
+			.div(denom) // 1e5
+	);
+
+	let maxLiabilityWeight;
+	if (isBounded) {
+		maxLiabilityWeight = BN.max(liabilityWeight, sizePremiumLiabilityWeight);
+	} else {
+		maxLiabilityWeight = sizePremiumLiabilityWeight;
+	}
+
+	return maxLiabilityWeight;
+}
+
+export function calculateSizeDiscountAssetWeight(
+	size: BN, // AMM_RESERVE_PRECISION
+	imfFactor: BN,
+	assetWeight: BN
+): BN {
+	if (imfFactor.eq(ZERO)) {
+		return assetWeight;
+	}
+
+	const sizeSqrt = squareRootBN(size.abs().mul(new BN(10)).add(new BN(1))); //1e9 -> 1e10 -> 1e5
+	const imfNumerator = SPOT_MARKET_IMF_PRECISION.add(
+		SPOT_MARKET_IMF_PRECISION.div(new BN(10))
+	);
+
+	const sizeDiscountAssetWeight = imfNumerator
+		.mul(SPOT_MARKET_WEIGHT_PRECISION)
+		.div(
+			SPOT_MARKET_IMF_PRECISION.add(
+				sizeSqrt // 1e5
+					.mul(imfFactor)
+					.div(new BN(100_000)) // 1e5
+			)
+		);
+
+	const minAssetWeight = BN.min(assetWeight, sizeDiscountAssetWeight);
+
+	return minAssetWeight;
+}
+
+export function calculateOraclePriceForPerpMargin(
+	perpPosition: PerpPosition,
+	market: PerpMarketAccount,
+	oraclePriceData: OraclePriceData
+): BN {
+	const oraclePriceOffset = BN.min(
+		new BN(market.amm.maxSpread)
+			.mul(oraclePriceData.price)
+			.div(BID_ASK_SPREAD_PRECISION),
+		oraclePriceData.confidence.add(
+			new BN(market.amm.baseSpread)
+				.mul(oraclePriceData.price)
+				.div(BID_ASK_SPREAD_PRECISION)
+		)
+	);
+
+	let marginPrice: BN;
+	if (perpPosition.baseAssetAmount.gt(ZERO)) {
+		marginPrice = oraclePriceData.price.sub(oraclePriceOffset);
+	} else {
+		marginPrice = oraclePriceData.price.add(oraclePriceOffset);
+	}
+
+	return marginPrice;
+}
+
+/**
+ * This is _not_ the same as liability value as for prediction markets, the liability for the short in prediction market is (1 - oracle price) * base
+ * See {@link calculatePerpLiabilityValue} to get the liabiltiy value
+ * @param market
+ * @param perpPosition
+ * @param oraclePriceData
+ * @param includeOpenOrders
+ */
+export function calculateBaseAssetValueWithOracle(
+	market: PerpMarketAccount,
+	perpPosition: PerpPosition,
+	oraclePriceData: Pick<OraclePriceData, 'price'>,
+	includeOpenOrders = false
+): BN {
+	let price = oraclePriceData.price;
+	if (isVariant(market.status, 'settlement')) {
+		price = market.expiryPrice;
+	}
+
+	const baseAssetAmount = includeOpenOrders
+		? calculateWorstCaseBaseAssetAmount(
+				perpPosition,
+				market,
+				oraclePriceData.price
+		  )
+		: perpPosition.baseAssetAmount;
+
+	return baseAssetAmount.abs().mul(price).div(AMM_RESERVE_PRECISION);
+}
+
+export function calculateWorstCaseBaseAssetAmount(
+	perpPosition: PerpPosition,
+	perpMarket: PerpMarketAccount,
+	oraclePrice: BN
+): BN {
+	return calculateWorstCasePerpLiabilityValue(
+		perpPosition,
+		perpMarket,
+		oraclePrice
+	).worstCaseBaseAssetAmount;
+}
+
+export function calculateWorstCasePerpLiabilityValue(
+	perpPosition: PerpPosition,
+	perpMarket: PerpMarketAccount,
+	oraclePrice: BN,
+	includeOpenOrders: boolean = true
+): { worstCaseBaseAssetAmount: BN; worstCaseLiabilityValue: BN } {
+	// return early if no open orders required
+	if (!includeOpenOrders) {
+		return {
+			worstCaseBaseAssetAmount: perpPosition.baseAssetAmount,
+			worstCaseLiabilityValue: calculatePerpLiabilityValue(
+				perpPosition.baseAssetAmount,
+				oraclePrice
+			),
+		};
+	}
+	const allBids = perpPosition.baseAssetAmount.add(perpPosition.openBids);
+	const allAsks = perpPosition.baseAssetAmount.add(perpPosition.openAsks);
+
+	const allBidsLiabilityValue = calculatePerpLiabilityValue(
+		allBids,
+		oraclePrice
+	);
+	const allAsksLiabilityValue = calculatePerpLiabilityValue(
+		allAsks,
+		oraclePrice
+	);
+
+	if (allAsksLiabilityValue.gte(allBidsLiabilityValue)) {
+		return {
+			worstCaseBaseAssetAmount: allAsks,
+			worstCaseLiabilityValue: allAsksLiabilityValue,
+		};
+	} else {
+		return {
+			worstCaseBaseAssetAmount: allBids,
+			worstCaseLiabilityValue: allBidsLiabilityValue,
+		};
+	}
+}
+
+export function calculatePerpLiabilityValue(
+	baseAssetAmount: BN,
+	price: BN
+): BN {
+	return baseAssetAmount.abs().mul(price).div(BASE_PRECISION);
+}
+
+/**
+ * Calculates the margin required to open a trade, in quote amount. Only accounts for the trade size as a scalar value, does not account for the trade direction or current open positions and whether the trade would _actually_ be risk-increasing and use any extra collateral.
+ * @param targetMarketIndex
+ * @param baseSize
+ * @returns
+ */
+export function calculateMarginUSDCRequiredForTrade(
+	driftClient: VelocityClient,
+	targetMarketIndex: number,
+	baseSize: BN,
+	userMaxMarginRatio?: number,
+	entryPrice?: BN
+): BN {
+	const targetMarket = driftClient.getPerpMarketAccount(targetMarketIndex);
+
+	const price =
+		entryPrice ??
+		driftClient.getOracleDataForPerpMarket(targetMarket.marketIndex).price;
+
+	const perpLiabilityValue = calculatePerpLiabilityValue(baseSize, price);
+
+	const marginRequired = new BN(
+		calculateMarketMarginRatio(
+			targetMarket,
+			baseSize.abs(),
+			'Initial',
+			userMaxMarginRatio
+		)
+	)
+		.mul(perpLiabilityValue)
+		.div(MARGIN_PRECISION);
+
+	return marginRequired;
+}
+
+/**
+ * Similar to calculatetMarginUSDCRequiredForTrade, but calculates how much of a given collateral is required to cover the margin requirements for a given trade. Basically does the same thing as getMarginUSDCRequiredForTrade but also accounts for asset weight of the selected collateral.
+ *
+ * Returns collateral required in the precision of the target collateral market.
+ */
+export function calculateCollateralDepositRequiredForTrade(
+	driftClient: VelocityClient,
+	targetMarketIndex: number,
+	baseSize: BN,
+	collateralIndex: number,
+	userMaxMarginRatio?: number,
+	estEntryPrice?: BN
+): BN {
+	const marginRequiredUsdc = calculateMarginUSDCRequiredForTrade(
+		driftClient,
+		targetMarketIndex,
+		baseSize,
+		userMaxMarginRatio,
+		estEntryPrice
+	);
+
+	const collateralMarket = driftClient.getSpotMarketAccount(collateralIndex);
+
+	const collateralOracleData =
+		driftClient.getOracleDataForSpotMarket(collateralIndex);
+
+	const scaledAssetWeight = calculateScaledInitialAssetWeight(
+		collateralMarket,
+		collateralOracleData.price
+	);
+
+	// Base amount required to deposit = (marginRequiredUsdc / priceOfAsset) / assetWeight .. (E.g. $100 required / $10000 price / 0.5 weight)
+	const baseAmountRequired = driftClient
+		.convertToSpotPrecision(collateralIndex, marginRequiredUsdc)
+		.mul(PRICE_PRECISION) // adjust for division by oracle price
+		.mul(SPOT_MARKET_WEIGHT_PRECISION) // adjust for division by scaled asset weight
+		.div(collateralOracleData.price)
+		.div(scaledAssetWeight)
+		.div(QUOTE_PRECISION); // adjust for marginRequiredUsdc value's QUOTE_PRECISION
+
+	// TODO : Round by step size?
+
+	return baseAmountRequired;
+}
+
+export function calculateCollateralValueOfDeposit(
+	driftClient: VelocityClient,
+	collateralIndex: number,
+	baseSize: BN
+): BN {
+	const collateralMarket = driftClient.getSpotMarketAccount(collateralIndex);
+
+	const collateralOracleData =
+		driftClient.getOracleDataForSpotMarket(collateralIndex);
+
+	const scaledAssetWeight = calculateScaledInitialAssetWeight(
+		collateralMarket,
+		collateralOracleData.price
+	);
+
+	// CollateralBaseValue = oracle price * collateral base amount (and shift to QUOTE_PRECISION)
+	const collateralBaseValue = collateralOracleData.price
+		.mul(baseSize)
+		.mul(QUOTE_PRECISION)
+		.div(PRICE_PRECISION)
+		.div(new BN(10).pow(new BN(collateralMarket.decimals)));
+
+	const depositCollateralValue = collateralBaseValue
+		.mul(scaledAssetWeight)
+		.div(SPOT_MARKET_WEIGHT_PRECISION);
+
+	return depositCollateralValue;
+}
+
+export function calculateLiquidationPrice(
+	freeCollateral: BN,
+	freeCollateralDelta: BN,
+	oraclePrice: BN
+): BN {
+	const liqPriceDelta = freeCollateral
+		.mul(QUOTE_PRECISION)
+		.div(freeCollateralDelta);
+
+	const liqPrice = oraclePrice.sub(liqPriceDelta);
+
+	if (liqPrice.lt(ZERO)) {
+		return new BN(-1);
+	}
+
+	return liqPrice;
+}
+
+export function calculateUserMaxPerpOrderSize(
+	driftClient: VelocityClient,
+	userAccountKey: PublicKey,
+	userAccount: UserAccount,
+	targetMarketIndex: number,
+	tradeSide: PositionDirection
+): { tradeSize: BN; oppositeSideTradeSize: BN } {
+	const userAccountSubscriber = new OneShotUserAccountSubscriber(
+		driftClient.program,
+		userAccountKey,
+		userAccount
+	);
+
+	const user = new User({
+		driftClient,
+		userAccountPublicKey: userAccountKey,
+		accountSubscription: {
+			type: 'custom',
+			userAccountSubscriber: userAccountSubscriber,
+		},
+	});
+
+	user.isSubscribed = true;
+
+	return user.getMaxTradeSizeUSDCForPerp(targetMarketIndex, tradeSide);
+}