@velocity-exchange/sdk 0.3.0 → 0.6.0

package/src/math/liquidation.ts

@@ -1,223 +0,0 @@
-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';
-
-/**
- * @param ifLiquidationFee Since PR#75 the program sizes liquidations against the
- *   COMBINED insurance-fund + protocol liquidation fee budget:
- *   `market.ifLiquidationFee + market.protocolLiquidationFee` (split IF-first
- *   on-chain). Pass that sum here to match on-chain sizing; passing
- *   `market.ifLiquidationFee` alone under-sizes the estimate.
- */
-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)
-			)
-	);
-}
-
-/**
- * @param ifLiquidationFee Since PR#75 the program sizes liquidations against the
- *   COMBINED insurance-fund + protocol liquidation fee budget:
- *   `market.ifLiquidationFee + market.protocolLiquidationFee` (split IF-first
- *   on-chain). Pass that sum here to match on-chain sizing; passing
- *   `market.ifLiquidationFee` alone under-sizes the estimate.
- */
-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

@@ -1,261 +0,0 @@
-/**
- * Margin calculation helpers — TypeScript mirror of `programs/velocity/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,
-	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 { PerpMarketAccount, PerpPosition } from '../types';
-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;
-}
-
-/**
- * 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(
-	velocityClient: VelocityClient,
-	targetMarketIndex: number,
-	baseSize: BN,
-	userMaxMarginRatio?: number,
-	entryPrice?: BN
-): BN {
-	const targetMarket =
-		velocityClient.getPerpMarketAccountOrThrow(targetMarketIndex);
-
-	const price =
-		entryPrice ??
-		velocityClient.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(
-	velocityClient: VelocityClient,
-	targetMarketIndex: number,
-	baseSize: BN,
-	collateralIndex: number,
-	userMaxMarginRatio?: number,
-	estEntryPrice?: BN
-): BN {
-	const marginRequiredUsdc = calculateMarginUSDCRequiredForTrade(
-		velocityClient,
-		targetMarketIndex,
-		baseSize,
-		userMaxMarginRatio,
-		estEntryPrice
-	);
-
-	const collateralMarket =
-		velocityClient.getSpotMarketAccountOrThrow(collateralIndex);
-
-	const collateralOracleData =
-		velocityClient.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 = velocityClient
-		.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;
-}