@velocity-exchange/sdk 0.4.0 → 0.6.0

package/src/math/spotMarket.ts

@@ -1,115 +0,0 @@
-import { BN } from '../isomorphic/anchor';
-import {
-	isVariant,
-	MarginCategory,
-	SpotBalanceType,
-	SpotMarketAccount,
-} from '../types';
-import {
-	calculateAssetWeight,
-	calculateLiabilityWeight,
-	getTokenAmount,
-} from './spotBalance';
-import { MARGIN_PRECISION, ZERO } from '../constants/numericConstants';
-import { numberToSafeBN } from './utils';
-
-/**
- * Converts a human-readable number or `BN` into the spot market's on-chain token precision
- * (`10 ** spotMarket.decimals`). Both inputs are treated as whole-token amounts and multiplied
- * by the market's precision.
- *
- * @param {number | BN} value - A human-readable amount, or a `BN` expressed in whole
- *   tokens (not yet scaled) that will be multiplied by the market's precision
- * @param {SpotMarketAccount} spotMarket - The spot market account (supplies `decimals`)
- * @return {BN} The token amount scaled by `10 ** spotMarket.decimals`
- */
-export function castNumberToSpotPrecision(
-	value: number | BN,
-	spotMarket: SpotMarketAccount
-): BN {
-	if (typeof value === 'number') {
-		return numberToSafeBN(value, new BN(Math.pow(10, spotMarket.decimals)));
-	} else {
-		return value.mul(new BN(Math.pow(10, spotMarket.decimals)));
-	}
-}
-
-/**
- * Calculates the effective margin ratio for a spot deposit or borrow position, expressed as
- * `MARGIN_PRECISION - assetWeight` (deposits) or `liabilityWeight - MARGIN_PRECISION` (borrows).
- * Note `MARGIN_PRECISION` and `SPOT_MARKET_WEIGHT_PRECISION` are both 1e4, so weights and margin
- * ratios share the same scale.
- *
- * @param {SpotMarketAccount} market - The spot market account
- * @param {BN} oraclePrice - The oracle price, PRICE_PRECISION (1e6)
- * @param {MarginCategory} marginCategory - `'Initial'` or `'Maintenance'`
- * @param {BN} size - The position size, scaled by `market.decimals`
- * @param {SpotBalanceType} balanceType - Whether `size` is a deposit or a borrow
- * @param {number} [customMarginRatio] - User's custom max margin ratio, `MARGIN_PRECISION` (1e4)
- *   units; only takes effect for `'Initial'`, where the looser (higher) of the computed ratio
- *   and this value is used, so a user can only demand *more* margin than the market default
- * @return {number} The margin ratio, scaled by `MARGIN_PRECISION` (1e4, i.e. 10000 = 100%)
- */
-export function calculateSpotMarketMarginRatio(
-	market: SpotMarketAccount,
-	oraclePrice: BN,
-	marginCategory: MarginCategory,
-	size: BN,
-	balanceType: SpotBalanceType,
-	customMarginRatio = 0
-): number {
-	let marginRatio;
-
-	if (isVariant(balanceType, 'deposit')) {
-		const assetWeight = calculateAssetWeight(
-			size,
-			oraclePrice,
-			market,
-			marginCategory
-		);
-		marginRatio = MARGIN_PRECISION.sub(assetWeight).toNumber();
-	} else {
-		const liabilityWeight = calculateLiabilityWeight(
-			size,
-			market,
-			marginCategory
-		);
-		marginRatio = liabilityWeight.sub(MARGIN_PRECISION).toNumber();
-	}
-
-	if (marginCategory === 'Initial') {
-		// use lowest leverage between max allowed and optional user custom max
-		return Math.max(marginRatio, customMarginRatio);
-	}
-
-	return marginRatio;
-}
-
-/**
- * Calculates the remaining room under the spot market's deposit cap, mirroring the check in the
- * program's deposit handler (`deposit_token_amount + amount <= max_token_deposits`, when the cap
- * is set).
- *
- * @param {SpotMarketAccount} market - The spot market account
- * @return {BN} `market.maxTokenDeposits - currentDeposits` (floored at zero), scaled by
- *   `market.decimals`. **Ambiguous zero:** returns `ZERO` both when `maxTokenDeposits === 0`
- *   (cap disabled, deposits are actually unlimited) and when the cap is enabled but already
- *   fully utilized — callers must check `market.maxTokenDeposits.eq(ZERO)` separately to tell
- *   "no limit" from "no room left".
- */
-export function calculateMaxRemainingDeposit(market: SpotMarketAccount) {
-	const marketMaxTokenDeposits = market.maxTokenDeposits;
-
-	if (marketMaxTokenDeposits.eq(ZERO)) {
-		// If the maxTokenDeposits is set to zero then that means there is no limit. Return the largest number we can to represent infinite available deposit.
-		return ZERO;
-	}
-
-	const totalDepositsTokenAmount = getTokenAmount(
-		market.depositBalance,
-		market,
-		SpotBalanceType.DEPOSIT
-	);
-
-	return BN.max(ZERO, marketMaxTokenDeposits.sub(totalDepositsTokenAmount));
-}

package/src/math/spotPosition.ts

@@ -1,263 +0,0 @@
-import { MarginCategory, SpotMarketAccount, SpotPosition } from '../types';
-import {
-	QUOTE_SPOT_MARKET_INDEX,
-	SPOT_MARKET_WEIGHT_PRECISION,
-	ZERO,
-} from '../constants/numericConstants';
-import { BN } from '../isomorphic/anchor';
-import {
-	calculateAssetWeight,
-	calculateLiabilityWeight,
-	getSignedTokenAmount,
-	getStrictTokenValue,
-	getTokenAmount,
-	getTokenValue,
-} from './spotBalance';
-import { StrictOraclePrice } from '../oracles/strictOraclePrice';
-
-/**
- * True if a `SpotPosition` slot has no balance and no open orders, meaning it is free to be
- * reused (or shown as empty) rather than representing an active position.
- *
- * @param {SpotPosition} position - The spot position
- * @return {boolean} Whether the slot is unused
- */
-export function isSpotPositionAvailable(position: SpotPosition): boolean {
-	return position.scaledBalance.eq(ZERO) && position.openOrders === 0;
-}
-
-/**
- * Result of simulating a spot position's collateral contribution, optionally after its resting
- * open orders are assumed to fill. All quote-denominated fields are `PRICE_PRECISION` (1e6).
- */
-export type OrderFillSimulation = {
-	/** Signed token amount (base for non-quote markets), the market's token decimals */
-	tokenAmount: BN;
-	/** Value of the open orders assumed to fill, at the worst-case (max) oracle price */
-	ordersValue: BN;
-	/** Strict-oracle value of `tokenAmount` before margin weighting */
-	tokenValue: BN;
-	/** Asset or liability weight applied to `tokenValue`, `SPOT_MARKET_WEIGHT_PRECISION` (1e4) */
-	weight: BN;
-	/** `tokenValue` after applying `weight` */
-	weightedTokenValue: BN;
-	/** Net contribution to free collateral: `weightedTokenValue` plus `ordersValue` where applicable */
-	freeCollateralContribution: BN;
-};
-
-/**
- * Calculates a spot position's worst-case token amount and margin contribution, accounting for
- * the possibility that its resting open bids or asks could fill. Mirrors the program's
- * worst-case spot balance logic used in margin/health checks: if both `openBids` and `openAsks`
- * are zero (or `includeOpenOrders` is false), the position's current balance is valued as-is;
- * otherwise the function separately simulates full fill of the bids and of the asks
- * (`simulateOrderFill`) and returns whichever leaves the *lower* `freeCollateralContribution` —
- * i.e. the more conservative (worse-case) scenario for margin purposes.
- *
- * @param {SpotPosition} spotPosition - The user's spot position
- * @param {SpotMarketAccount} spotMarketAccount - The spot market account
- * @param {StrictOraclePrice} strictOraclePrice - Live oracle price + 5min TWAP, PRICE_PRECISION (1e6)
- * @param {MarginCategory | undefined} marginCategory - `'Initial'`, `'Maintenance'`, or
- *   `undefined` for an unweighted valuation
- * @param {number} [customMarginRatio] - User's custom max margin ratio (`'Initial'` only); see
- *   `calculateWeightedTokenValue`
- * @param {boolean} [includeOpenOrders] - Whether to simulate open order fills at all; defaults
- *   to `true`. When `false`, only the current balance is valued regardless of open orders.
- * @return {OrderFillSimulation} The worst-case simulation result
- */
-export function getWorstCaseTokenAmounts(
-	spotPosition: SpotPosition,
-	spotMarketAccount: SpotMarketAccount,
-	strictOraclePrice: StrictOraclePrice,
-	marginCategory: MarginCategory | undefined,
-	customMarginRatio?: number,
-	includeOpenOrders: boolean = true
-): OrderFillSimulation {
-	const tokenAmount = getSignedTokenAmount(
-		getTokenAmount(
-			spotPosition.scaledBalance,
-			spotMarketAccount,
-			spotPosition.balanceType
-		),
-		spotPosition.balanceType
-	);
-
-	const tokenValue = getStrictTokenValue(
-		tokenAmount,
-		spotMarketAccount.decimals,
-		strictOraclePrice
-	);
-
-	if (
-		(spotPosition.openBids.eq(ZERO) && spotPosition.openAsks.eq(ZERO)) ||
-		!includeOpenOrders
-	) {
-		const { weight, weightedTokenValue } = calculateWeightedTokenValue(
-			tokenAmount,
-			tokenValue,
-			strictOraclePrice.current,
-			spotMarketAccount,
-			marginCategory,
-			customMarginRatio
-		);
-		return {
-			tokenAmount,
-			ordersValue: ZERO,
-			tokenValue,
-			weight,
-			weightedTokenValue,
-			freeCollateralContribution: weightedTokenValue,
-		};
-	}
-
-	const bidsSimulation = simulateOrderFill(
-		tokenAmount,
-		tokenValue,
-		spotPosition.openBids,
-		strictOraclePrice,
-		spotMarketAccount,
-		marginCategory,
-		customMarginRatio
-	);
-	const asksSimulation = simulateOrderFill(
-		tokenAmount,
-		tokenValue,
-		spotPosition.openAsks,
-		strictOraclePrice,
-		spotMarketAccount,
-		marginCategory,
-		customMarginRatio
-	);
-
-	if (
-		asksSimulation.freeCollateralContribution.lt(
-			bidsSimulation.freeCollateralContribution
-		)
-	) {
-		return asksSimulation;
-	} else {
-		return bidsSimulation;
-	}
-}
-
-/**
- * Applies the appropriate asset or liability weight (based on the sign of `tokenValue`) to a
- * token value, mirroring the program's `calculate_weighted_token_value` closure used in both
- * plain and worst-case-fill spot margin calculations.
- *
- * @param {BN} tokenAmount - Signed token amount, used (as `abs()`) for the IMF size adjustment
- * @param {BN} tokenValue - Signed strict-oracle value, `PRICE_PRECISION` (1e6); sign selects
- *   asset weight (`>= 0`) vs liability weight (`< 0`)
- * @param {BN} oraclePrice - The oracle price, PRICE_PRECISION (1e6), passed through to
- *   `calculateAssetWeight` for the initial-weight deposit-value scaling lookup
- * @param {SpotMarketAccount} spotMarket - The spot market account
- * @param {MarginCategory | undefined} marginCategory - `'Initial'`, `'Maintenance'`, or `undefined`
- * @param {number} [customMarginRatio] - User's custom max margin ratio, `SPOT_MARKET_WEIGHT_PRECISION`
- *   (1e4) units; only applied for `'Initial'` on non-quote markets, tightening (never loosening)
- *   the weight in the direction unfavorable to the user
- * @return {{ weight: BN; weightedTokenValue: BN }} `weight` in `SPOT_MARKET_WEIGHT_PRECISION`
- *   (1e4); `weightedTokenValue` in `PRICE_PRECISION` (1e6)
- */
-export function calculateWeightedTokenValue(
-	tokenAmount: BN,
-	tokenValue: BN,
-	oraclePrice: BN,
-	spotMarket: SpotMarketAccount,
-	marginCategory: MarginCategory | undefined,
-	customMarginRatio?: number
-): { weight: BN; weightedTokenValue: BN } {
-	let weight: BN;
-	if (tokenValue.gte(ZERO)) {
-		weight = calculateAssetWeight(
-			tokenAmount,
-			oraclePrice,
-			spotMarket,
-			marginCategory
-		);
-	} else {
-		weight = calculateLiabilityWeight(
-			tokenAmount.abs(),
-			spotMarket,
-			marginCategory
-		);
-	}
-
-	if (
-		marginCategory === 'Initial' &&
-		customMarginRatio &&
-		spotMarket.marketIndex !== QUOTE_SPOT_MARKET_INDEX
-	) {
-		const userCustomAssetWeight = tokenValue.gte(ZERO)
-			? BN.max(
-					ZERO,
-					SPOT_MARKET_WEIGHT_PRECISION.sub(new BN(customMarginRatio))
-			  )
-			: SPOT_MARKET_WEIGHT_PRECISION.add(new BN(customMarginRatio));
-
-		weight = tokenValue.gte(ZERO)
-			? BN.min(weight, userCustomAssetWeight)
-			: BN.max(weight, userCustomAssetWeight);
-	}
-
-	return {
-		weight: weight,
-		weightedTokenValue: tokenValue
-			.mul(weight)
-			.div(SPOT_MARKET_WEIGHT_PRECISION),
-	};
-}
-
-/**
- * Simulates one side (bids or asks) of a spot position's open orders fully filling, and
- * recomputes the resulting margin contribution. Mirrors the per-side branch of the program's
- * `simulate_fills_both_sides`. The filled orders' value is valued at the *worst-case* price
- * (`strictOraclePrice.max()`) regardless of side, since filling either bids or asks moves the
- * position further from its current state in the direction that could hurt collateral value.
- *
- * @param {BN} tokenAmount - Current signed token amount before the simulated fill
- * @param {BN} tokenValue - Current strict-oracle token value before the simulated fill, `PRICE_PRECISION` (1e6)
- * @param {BN} openOrders - Signed open order base size for this side: `spotPosition.openBids`
- *   (stored positive) or `spotPosition.openAsks` (stored negative), the market's token decimals
- * @param {StrictOraclePrice} strictOraclePrice - Live oracle price + 5min TWAP, PRICE_PRECISION (1e6)
- * @param {SpotMarketAccount} spotMarket - The spot market account
- * @param {MarginCategory | undefined} marginCategory - `'Initial'`, `'Maintenance'`, or `undefined`
- * @param {number} [customMarginRatio] - User's custom max margin ratio; see `calculateWeightedTokenValue`
- * @return {OrderFillSimulation} The post-fill simulation for this side
- */
-export function simulateOrderFill(
-	tokenAmount: BN,
-	tokenValue: BN,
-	openOrders: BN,
-	strictOraclePrice: StrictOraclePrice,
-	spotMarket: SpotMarketAccount,
-	marginCategory: MarginCategory | undefined,
-	customMarginRatio?: number
-): OrderFillSimulation {
-	const ordersValue = getTokenValue(openOrders.neg(), spotMarket.decimals, {
-		price: strictOraclePrice.max(),
-	});
-	const tokenAmountAfterFill = tokenAmount.add(openOrders);
-	const tokenValueAfterFill = tokenValue.add(ordersValue.neg());
-
-	const { weight, weightedTokenValue: weightedTokenValueAfterFill } =
-		calculateWeightedTokenValue(
-			tokenAmountAfterFill,
-			tokenValueAfterFill,
-			strictOraclePrice.current,
-			spotMarket,
-			marginCategory,
-			customMarginRatio
-		);
-
-	const freeCollateralContribution =
-		weightedTokenValueAfterFill.add(ordersValue);
-
-	return {
-		tokenAmount: tokenAmountAfterFill,
-		ordersValue: ordersValue,
-		tokenValue: tokenValueAfterFill,
-		weight,
-		weightedTokenValue: weightedTokenValueAfterFill,
-		freeCollateralContribution,
-	};
-}

package/src/math/state.ts

@@ -1,71 +0,0 @@
-import { BN } from '../isomorphic/anchor';
-import {
-	LAMPORTS_PRECISION,
-	PERCENTAGE_PRECISION,
-	ZERO,
-} from '../constants/numericConstants';
-import { FeatureBitFlags, StateAccount } from '../types';
-
-/**
- * Calculates the SOL fee that will be charged to initialize a new sub-account, mirroring
- * `State::get_init_user_fee`'s account-space-utilization scaling: once sub-account utilization
- * passes 80% of the max allowed, the fee ramps linearly from 0 up to `maxInitializeUserFee` at
- * 100% utilization; below 80% it's free. `numberOfSubAccounts` is incremented by 1 before this
- * ratio is computed because the on-chain handler bumps `state.numberOfSubAccounts` *before*
- * calling `get_init_user_fee` — so a client reading pre-transaction state must simulate that
- * increment itself to predict the fee the transaction will actually charge.
- *
- * @param {StateAccount} stateAccount - The global state account, read before submitting the
- *   `initializeUser` transaction
- * @return {BN} The init fee in lamports, `LAMPORTS_PRECISION` (1e9)
- */
-export function calculateInitUserFee(stateAccount: StateAccount): BN {
-	const maxInitFee = new BN(stateAccount.maxInitializeUserFee)
-		.mul(LAMPORTS_PRECISION)
-		.divn(100);
-	const targetUtilization = PERCENTAGE_PRECISION.muln(8).divn(10);
-
-	const accountSpaceUtilization = stateAccount.numberOfSubAccounts
-		.addn(1)
-		.mul(PERCENTAGE_PRECISION)
-		.div(BN.max(getMaxNumberOfSubAccounts(stateAccount), new BN(1)));
-
-	if (accountSpaceUtilization.gt(targetUtilization)) {
-		return maxInitFee
-			.mul(accountSpaceUtilization.sub(targetUtilization))
-			.div(PERCENTAGE_PRECISION.sub(targetUtilization));
-	} else {
-		return ZERO;
-	}
-}
-
-/**
- * Calculates the effective max number of sub-accounts allowed per authority, mirroring
- * `State::max_number_of_sub_accounts`. Values of 5 or below are used as-is (an explicit small
- * cap); values above 5 are multiplied by 100, letting the admin store a compact "hundreds" unit
- * for large caps.
- *
- * @param {StateAccount} stateAccount - The global state account
- * @return {BN} The effective max sub-account count (unitless count, not a token amount)
- */
-export function getMaxNumberOfSubAccounts(stateAccount: StateAccount): BN {
-	if (stateAccount.maxNumberOfSubAccounts <= 5) {
-		return new BN(stateAccount.maxNumberOfSubAccounts);
-	}
-	return new BN(stateAccount.maxNumberOfSubAccounts).muln(100);
-}
-
-/**
- * True if the protocol-wide feature flag for median-based trigger prices is enabled, mirroring
- * `State::use_median_trigger_price`. When enabled, `getTriggerPrice` (in `market.ts`) uses the
- * median of last-fill, funding-basis, and 5min-basis prices instead of the raw oracle price for
- * trigger order evaluation.
- *
- * @param {StateAccount} stateAccount - The global state account
- * @return {boolean} Whether `FeatureBitFlags.MEDIAN_TRIGGER_PRICE` is set
- */
-export function useMedianTriggerPrice(stateAccount: StateAccount): boolean {
-	return (
-		(stateAccount.featureBitFlags & FeatureBitFlags.MEDIAN_TRIGGER_PRICE) > 0
-	);
-}