@velocity-exchange/sdk 0.0.1

package/lib/browser/math/funding.js

@@ -0,0 +1,260 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateFundingPool = exports.calculateLongShortFundingRateAndLiveTwaps = exports.calculateLongShortFundingRate = exports.calculateFormattedLiveFundingRate = exports.calculateAllEstimatedFundingRate = void 0;
+const anchor_1 = require("../isomorphic/anchor");
+const numericConstants_1 = require("../constants/numericConstants");
+const bigNum_1 = require("../factory/bigNum");
+const types_1 = require("../types");
+const amm_1 = require("./amm");
+const oracles_1 = require("./oracles");
+const utils_1 = require("./utils");
+const numericConstants_2 = require("../constants/numericConstants");
+function calculateLiveMarkTwap(market, mmOraclePriceData, markPrice, now, period = new anchor_1.BN(3600)) {
+    now = now || new anchor_1.BN((Date.now() / 1000).toFixed(0));
+    const lastMarkTwapWithMantissa = market.amm.lastMarkPriceTwap;
+    const lastMarkPriceTwapTs = market.amm.lastMarkPriceTwapTs;
+    const timeSinceLastMarkChange = now.sub(lastMarkPriceTwapTs);
+    const markTwapTimeSinceLastUpdate = anchor_1.BN.max(period, anchor_1.BN.max(numericConstants_1.ZERO, period.sub(timeSinceLastMarkChange)));
+    if (!markPrice) {
+        const [bid, ask] = (0, amm_1.calculateBidAskPrice)(market.amm, mmOraclePriceData);
+        markPrice = bid.add(ask).div(new anchor_1.BN(2));
+    }
+    const markTwapWithMantissa = markTwapTimeSinceLastUpdate
+        .mul(lastMarkTwapWithMantissa)
+        .add(timeSinceLastMarkChange.mul(markPrice))
+        .div(timeSinceLastMarkChange.add(markTwapTimeSinceLastUpdate));
+    return markTwapWithMantissa;
+}
+function shrinkStaleTwaps(market, markTwapWithMantissa, oracleTwapWithMantissa, now) {
+    now = now || new anchor_1.BN((Date.now() / 1000).toFixed(0));
+    let newMarkTwap = markTwapWithMantissa;
+    let newOracleTwap = oracleTwapWithMantissa;
+    if (market.amm.lastMarkPriceTwapTs.gt(market.amm.historicalOracleData.lastOraclePriceTwapTs)) {
+        // shrink oracle based on invalid intervals
+        const oracleInvalidDuration = anchor_1.BN.max(numericConstants_1.ZERO, market.amm.lastMarkPriceTwapTs.sub(market.amm.historicalOracleData.lastOraclePriceTwapTs));
+        const timeSinceLastOracleTwapUpdate = now.sub(market.amm.historicalOracleData.lastOraclePriceTwapTs);
+        const oracleTwapTimeSinceLastUpdate = anchor_1.BN.max(numericConstants_1.ONE, anchor_1.BN.min(market.amm.fundingPeriod, anchor_1.BN.max(numericConstants_1.ONE, market.amm.fundingPeriod.sub(timeSinceLastOracleTwapUpdate))));
+        newOracleTwap = oracleTwapTimeSinceLastUpdate
+            .mul(oracleTwapWithMantissa)
+            .add(oracleInvalidDuration.mul(markTwapWithMantissa))
+            .div(oracleTwapTimeSinceLastUpdate.add(oracleInvalidDuration));
+    }
+    else if (market.amm.lastMarkPriceTwapTs.lt(market.amm.historicalOracleData.lastOraclePriceTwapTs)) {
+        // shrink mark to oracle twap over tradless intervals
+        const tradelessDuration = anchor_1.BN.max(numericConstants_1.ZERO, market.amm.historicalOracleData.lastOraclePriceTwapTs.sub(market.amm.lastMarkPriceTwapTs));
+        const timeSinceLastMarkTwapUpdate = now.sub(market.amm.lastMarkPriceTwapTs);
+        const markTwapTimeSinceLastUpdate = anchor_1.BN.max(numericConstants_1.ONE, anchor_1.BN.min(market.amm.fundingPeriod, anchor_1.BN.max(numericConstants_1.ONE, market.amm.fundingPeriod.sub(timeSinceLastMarkTwapUpdate))));
+        newMarkTwap = markTwapTimeSinceLastUpdate
+            .mul(markTwapWithMantissa)
+            .add(tradelessDuration.mul(oracleTwapWithMantissa))
+            .div(markTwapTimeSinceLastUpdate.add(tradelessDuration));
+    }
+    return [newMarkTwap, newOracleTwap];
+}
+/**
+ *
+ * @param market
+ * @param oraclePriceData
+ * @param periodAdjustment
+ * @returns Estimated funding rate. : Precision //TODO-PRECISION
+ */
+function calculateAllEstimatedFundingRate(market, mmOraclePriceData, oraclePriceData, markPrice, now) {
+    if ((0, types_1.isVariant)(market.status, 'uninitialized')) {
+        return [numericConstants_1.ZERO, numericConstants_1.ZERO, numericConstants_1.ZERO, numericConstants_1.ZERO, numericConstants_1.ZERO];
+    }
+    // todo: sufficiently differs from blockchain timestamp?
+    now = now || new anchor_1.BN((Date.now() / 1000).toFixed(0));
+    // calculate real-time mark and oracle twap
+    const liveMarkTwap = calculateLiveMarkTwap(market, mmOraclePriceData, markPrice, now, market.amm.fundingPeriod);
+    const liveOracleTwap = (0, oracles_1.calculateLiveOracleTwap)(market.amm.historicalOracleData, oraclePriceData, now, market.amm.fundingPeriod);
+    const [markTwap, oracleTwap] = shrinkStaleTwaps(market, liveMarkTwap, liveOracleTwap, now);
+    // if(!markTwap.eq(liveMarkTwap)){
+    // 	console.log('shrink mark:', liveMarkTwap.toString(), '->', markTwap.toString());
+    // }
+    // if(!oracleTwap.eq(liveOracleTwap)){
+    // 	console.log('shrink orac:', liveOracleTwap.toString(), '->', oracleTwap.toString());
+    // }
+    const twapSpread = markTwap.sub(oracleTwap);
+    const offset = oracleTwap.abs().div(numericConstants_1.FUNDING_RATE_OFFSET_DENOMINATOR);
+    const twapSpreadWithOffset = twapSpread
+        .abs()
+        .lte(oracleTwap.abs().div(numericConstants_1.FUNDING_RATE_CLAMP_DENOMINATOR))
+        ? offset
+        : twapSpread.add(offset);
+    const maxSpread = getMaxPriceDivergenceForFundingRate(market, oracleTwap);
+    const clampedSpreadWithOffset = (0, utils_1.clampBN)(twapSpreadWithOffset, maxSpread.mul(new anchor_1.BN(-1)), maxSpread);
+    const twapSpreadPct = clampedSpreadWithOffset
+        .mul(numericConstants_1.PRICE_PRECISION)
+        .mul(new anchor_1.BN(100))
+        .div(oracleTwap);
+    const secondsInHour = new anchor_1.BN(3600);
+    const hoursInDay = new anchor_1.BN(24);
+    const timeSinceLastUpdate = now.sub(market.amm.lastFundingRateTs);
+    const lowerboundEst = twapSpreadPct
+        .mul(market.amm.fundingPeriod)
+        .mul(anchor_1.BN.min(secondsInHour, timeSinceLastUpdate))
+        .div(secondsInHour)
+        .div(secondsInHour)
+        .div(hoursInDay);
+    const interpEst = twapSpreadPct.div(hoursInDay);
+    const interpRateQuote = twapSpreadPct
+        .div(hoursInDay)
+        .div(numericConstants_1.PRICE_PRECISION.div(numericConstants_1.QUOTE_PRECISION));
+    let feePoolSize = calculateFundingPool(market);
+    if (interpRateQuote.lt(new anchor_1.BN(0))) {
+        feePoolSize = feePoolSize.mul(new anchor_1.BN(-1));
+    }
+    let cappedAltEst;
+    let largerSide;
+    let smallerSide;
+    if (market.amm.baseAssetAmountLong.gt(market.amm.baseAssetAmountShort.abs())) {
+        largerSide = market.amm.baseAssetAmountLong.abs();
+        smallerSide = market.amm.baseAssetAmountShort.abs();
+        if (twapSpread.gt(new anchor_1.BN(0))) {
+            return [markTwap, oracleTwap, lowerboundEst, interpEst, interpEst];
+        }
+    }
+    else if (market.amm.baseAssetAmountLong.lt(market.amm.baseAssetAmountShort.abs())) {
+        largerSide = market.amm.baseAssetAmountShort.abs();
+        smallerSide = market.amm.baseAssetAmountLong.abs();
+        if (twapSpread.lt(new anchor_1.BN(0))) {
+            return [markTwap, oracleTwap, lowerboundEst, interpEst, interpEst];
+        }
+    }
+    else {
+        return [markTwap, oracleTwap, lowerboundEst, interpEst, interpEst];
+    }
+    if (largerSide.gt(numericConstants_1.ZERO)) {
+        // funding smaller flow
+        cappedAltEst = smallerSide.mul(twapSpread).div(hoursInDay);
+        const feePoolTopOff = feePoolSize
+            .mul(numericConstants_1.PRICE_PRECISION.div(numericConstants_1.QUOTE_PRECISION))
+            .mul(numericConstants_1.AMM_RESERVE_PRECISION);
+        cappedAltEst = cappedAltEst.add(feePoolTopOff).div(largerSide);
+        cappedAltEst = cappedAltEst
+            .mul(numericConstants_1.PRICE_PRECISION)
+            .mul(new anchor_1.BN(100))
+            .div(oracleTwap);
+        if (cappedAltEst.abs().gte(interpEst.abs())) {
+            cappedAltEst = interpEst;
+        }
+    }
+    else {
+        cappedAltEst = interpEst;
+    }
+    return [markTwap, oracleTwap, lowerboundEst, cappedAltEst, interpEst];
+}
+exports.calculateAllEstimatedFundingRate = calculateAllEstimatedFundingRate;
+/**
+ * To get funding rate as a percentage, you need to multiply by the funding rate buffer precision
+ * @param rawFundingRate
+ * @returns
+ */
+const getFundingRatePct = (rawFundingRate) => {
+    return bigNum_1.BigNum.from(rawFundingRate.mul(numericConstants_2.FUNDING_RATE_BUFFER_PRECISION), numericConstants_2.FUNDING_RATE_PRECISION_EXP).toNum();
+};
+/**
+ * Calculate funding rates in human-readable form. Values will have some lost precision and shouldn't be used in strict accounting.
+ * @param period : 'hour' | 'year' :: Use 'hour' for the hourly payment as a percentage, 'year' for the payment as an estimated APR.
+ */
+function calculateFormattedLiveFundingRate(market, mmOraclePriceData, oraclePriceData, period) {
+    const nowBN = new anchor_1.BN(Date.now() / 1000);
+    const [_markTwapLive, _oracleTwapLive, longFundingRate, shortFundingRate] = calculateLongShortFundingRateAndLiveTwaps(market, mmOraclePriceData, oraclePriceData, undefined, nowBN);
+    let longFundingRateNum = getFundingRatePct(longFundingRate);
+    let shortFundingRateNum = getFundingRatePct(shortFundingRate);
+    if (period == 'year') {
+        const paymentsPerYear = 24 * 365.25;
+        longFundingRateNum *= paymentsPerYear;
+        shortFundingRateNum *= paymentsPerYear;
+    }
+    const longsArePaying = longFundingRateNum > 0;
+    const shortsArePaying = !(shortFundingRateNum > 0);
+    const longsAreString = longsArePaying ? 'pay' : 'receive';
+    const shortsAreString = !shortsArePaying ? 'receive' : 'pay';
+    const absoluteLongFundingRateNum = Math.abs(longFundingRateNum);
+    const absoluteShortFundingRateNum = Math.abs(shortFundingRateNum);
+    const formattedLongRatePct = absoluteLongFundingRateNum.toFixed(period == 'hour' ? 5 : 2);
+    const formattedShortRatePct = absoluteShortFundingRateNum.toFixed(period == 'hour' ? 5 : 2);
+    const fundingRateUnit = period == 'year' ? '% APR' : '%';
+    const formattedFundingRateSummary = `At this rate, longs would ${longsAreString} ${formattedLongRatePct} ${fundingRateUnit} and shorts would ${shortsAreString} ${formattedShortRatePct} ${fundingRateUnit} at the end of the hour.`;
+    return {
+        longRate: longsArePaying
+            ? -absoluteLongFundingRateNum
+            : absoluteLongFundingRateNum,
+        shortRate: shortsArePaying
+            ? -absoluteShortFundingRateNum
+            : absoluteShortFundingRateNum,
+        fundingRateUnit: fundingRateUnit,
+        formattedFundingRateSummary,
+    };
+}
+exports.calculateFormattedLiveFundingRate = calculateFormattedLiveFundingRate;
+function getMaxPriceDivergenceForFundingRate(market, oracleTwap) {
+    if ((0, types_1.isVariant)(market.contractTier, 'a')) {
+        return oracleTwap.divn(33);
+    }
+    else if ((0, types_1.isVariant)(market.contractTier, 'b')) {
+        return oracleTwap.divn(33);
+    }
+    else if ((0, types_1.isVariant)(market.contractTier, 'c')) {
+        return oracleTwap.divn(20);
+    }
+    else {
+        return oracleTwap.divn(10);
+    }
+}
+/**
+ *
+ * @param market
+ * @param oraclePriceData
+ * @param periodAdjustment
+ * @returns Estimated funding rate. : Precision //TODO-PRECISION
+ */
+function calculateLongShortFundingRate(market, mmOraclePriceData, oraclePriceData, markPrice, now) {
+    const [_1, _2, _, cappedAltEst, interpEst] = calculateAllEstimatedFundingRate(market, mmOraclePriceData, oraclePriceData, markPrice, now);
+    if (market.amm.baseAssetAmountLong.gt(market.amm.baseAssetAmountShort)) {
+        return [cappedAltEst, interpEst];
+    }
+    else if (market.amm.baseAssetAmountLong.lt(market.amm.baseAssetAmountShort)) {
+        return [interpEst, cappedAltEst];
+    }
+    else {
+        return [interpEst, interpEst];
+    }
+}
+exports.calculateLongShortFundingRate = calculateLongShortFundingRate;
+/**
+ *
+ * @param market
+ * @param oraclePriceData
+ * @param periodAdjustment
+ * @returns Estimated funding rate. : Precision //TODO-PRECISION
+ */
+function calculateLongShortFundingRateAndLiveTwaps(market, mmOraclePriceData, oraclePriceData, markPrice, now) {
+    const [markTwapLive, oracleTwapLive, _2, cappedAltEst, interpEst] = calculateAllEstimatedFundingRate(market, mmOraclePriceData, oraclePriceData, markPrice, now);
+    if (market.amm.baseAssetAmountLong.gt(market.amm.baseAssetAmountShort.abs())) {
+        return [markTwapLive, oracleTwapLive, cappedAltEst, interpEst];
+    }
+    else if (market.amm.baseAssetAmountLong.lt(market.amm.baseAssetAmountShort.abs())) {
+        return [markTwapLive, oracleTwapLive, interpEst, cappedAltEst];
+    }
+    else {
+        return [markTwapLive, oracleTwapLive, interpEst, interpEst];
+    }
+}
+exports.calculateLongShortFundingRateAndLiveTwaps = calculateLongShortFundingRateAndLiveTwaps;
+/**
+ *
+ * @param market
+ * @returns Estimated fee pool size
+ */
+function calculateFundingPool(market) {
+    // todo
+    const totalFeeLB = market.amm.totalExchangeFee.div(new anchor_1.BN(2));
+    const feePool = anchor_1.BN.max(numericConstants_1.ZERO, market.amm.totalFeeMinusDistributions
+        .sub(totalFeeLB)
+        .mul(new anchor_1.BN(1))
+        .div(new anchor_1.BN(3)));
+    return feePool;
+}
+exports.calculateFundingPool = calculateFundingPool;

package/lib/browser/math/insurance.d.ts

@@ -0,0 +1,8 @@
+/// <reference types="bn.js" />
+import { BN } from '../isomorphic/anchor';
+import { SpotMarketAccount } from '../types';
+export declare function nextRevenuePoolSettleApr(spotMarket: SpotMarketAccount, vaultBalance: BN, // vault token amount
+amount?: BN): number;
+export declare function stakeAmountToShares(amount: BN, totalIfShares: BN, insuranceFundVaultBalance: BN): BN;
+export declare function unstakeSharesToAmount(nShares: BN, totalIfShares: BN, insuranceFundVaultBalance: BN): BN;
+export declare function unstakeSharesToAmountWithOpenRequest(nShares: BN, withdrawRequestShares: BN, withdrawRequestAmount: BN, totalIfShares: BN, insuranceFundVaultBalance: BN): BN;

package/lib/browser/math/insurance.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unstakeSharesToAmountWithOpenRequest = exports.unstakeSharesToAmount = exports.stakeAmountToShares = exports.nextRevenuePoolSettleApr = void 0;
+const numericConstants_1 = require("../constants/numericConstants");
+const spotBalance_1 = require("../math/spotBalance");
+const anchor_1 = require("../isomorphic/anchor");
+const types_1 = require("../types");
+function nextRevenuePoolSettleApr(spotMarket, vaultBalance, // vault token amount
+amount // delta token amount
+) {
+    const MAX_APR = new anchor_1.BN(10).mul(numericConstants_1.PERCENTAGE_PRECISION); // 1000% APR
+    // Conmputing the APR:
+    const revenuePoolBN = (0, spotBalance_1.getTokenAmount)(spotMarket.revenuePool.scaledBalance, spotMarket, types_1.SpotBalanceType.DEPOSIT);
+    const payoutRatio = 0.1;
+    const ratioForStakers = spotMarket.insuranceFund.totalFactor > 0 &&
+        spotMarket.insuranceFund.userFactor > 0 &&
+        spotMarket.insuranceFund.revenueSettlePeriod.gt(numericConstants_1.ZERO)
+        ? spotMarket.insuranceFund.userFactor /
+            spotMarket.insuranceFund.totalFactor
+        : 0;
+    // Settle periods from on-chain data:
+    const revSettlePeriod = spotMarket.insuranceFund.revenueSettlePeriod.toNumber() * 1000;
+    const settlesPerYear = 31536000000 / revSettlePeriod;
+    const projectedAnnualRev = revenuePoolBN
+        .muln(settlesPerYear)
+        .muln(payoutRatio);
+    const uncappedApr = vaultBalance.add(amount).eq(numericConstants_1.ZERO)
+        ? 0
+        : projectedAnnualRev.muln(1000).div(vaultBalance.add(amount)).toNumber() *
+            100 *
+            1000;
+    const cappedApr = Math.min(uncappedApr, MAX_APR.toNumber());
+    const nextApr = cappedApr * ratioForStakers;
+    return nextApr;
+}
+exports.nextRevenuePoolSettleApr = nextRevenuePoolSettleApr;
+function stakeAmountToShares(amount, totalIfShares, insuranceFundVaultBalance) {
+    let nShares;
+    if (insuranceFundVaultBalance.gt(numericConstants_1.ZERO)) {
+        nShares = amount.mul(totalIfShares).div(insuranceFundVaultBalance);
+    }
+    else {
+        nShares = amount;
+    }
+    return nShares;
+}
+exports.stakeAmountToShares = stakeAmountToShares;
+function unstakeSharesToAmount(nShares, totalIfShares, insuranceFundVaultBalance) {
+    let amount;
+    if (totalIfShares.gt(numericConstants_1.ZERO)) {
+        amount = anchor_1.BN.max(numericConstants_1.ZERO, nShares.mul(insuranceFundVaultBalance).div(totalIfShares));
+    }
+    else {
+        amount = numericConstants_1.ZERO;
+    }
+    return amount;
+}
+exports.unstakeSharesToAmount = unstakeSharesToAmount;
+function unstakeSharesToAmountWithOpenRequest(nShares, withdrawRequestShares, withdrawRequestAmount, totalIfShares, insuranceFundVaultBalance) {
+    let stakedAmount;
+    if (totalIfShares.gt(numericConstants_1.ZERO)) {
+        stakedAmount = anchor_1.BN.max(numericConstants_1.ZERO, nShares
+            .sub(withdrawRequestShares)
+            .mul(insuranceFundVaultBalance)
+            .div(totalIfShares));
+    }
+    else {
+        stakedAmount = numericConstants_1.ZERO;
+    }
+    const withdrawAmount = anchor_1.BN.min(withdrawRequestAmount, withdrawRequestShares.mul(insuranceFundVaultBalance).div(totalIfShares));
+    const amount = withdrawAmount.add(stakedAmount);
+    return amount;
+}
+exports.unstakeSharesToAmountWithOpenRequest = unstakeSharesToAmountWithOpenRequest;

package/lib/browser/math/liquidation.d.ts

@@ -0,0 +1,7 @@
+/// <reference types="bn.js" />
+import { BN } from '../isomorphic/anchor';
+export declare function calculateBaseAssetAmountToCoverMarginShortage(marginShortage: BN, marginRatio: number, liquidationFee: number, ifLiquidationFee: number, oraclePrice: BN, quoteOraclePrice: BN): BN | undefined;
+export declare function calculateLiabilityTransferToCoverMarginShortage(marginShortage: BN, assetWeight: number, assetLiquidationMultiplier: number, liabilityWeight: number, liabilityLiquidationMultiplier: number, liabilityDecimals: number, liabilityPrice: BN, ifLiquidationFee: number): BN | undefined;
+export declare function calculateAssetTransferForLiabilityTransfer(assetAmount: BN, assetLiquidationMultiplier: number, assetDecimals: number, assetPrice: BN, liabilityAmount: BN, liabilityLiquidationMultiplier: number, liabilityDecimals: number, liabilityPrice: BN): BN | undefined;
+export declare function calculateMaxPctToLiquidate(userLastActiveSlot: BN, userLiquidationMarginFreed: BN, marginShortage: BN, slot: BN, initialPctToLiquidate: BN, liquidationDuration: BN): BN;
+export declare function getMarginShortage(maintenanceMarginRequirementPlusBuffer: BN, maintenanceTotalCollateral: BN): BN;

package/lib/browser/math/liquidation.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMarginShortage = exports.calculateMaxPctToLiquidate = exports.calculateAssetTransferForLiabilityTransfer = exports.calculateLiabilityTransferToCoverMarginShortage = exports.calculateBaseAssetAmountToCoverMarginShortage = void 0;
+const anchor_1 = require("../isomorphic/anchor");
+const numericConstants_1 = require("../constants/numericConstants");
+function calculateBaseAssetAmountToCoverMarginShortage(marginShortage, marginRatio, liquidationFee, ifLiquidationFee, oraclePrice, quoteOraclePrice) {
+    const marginRatioBN = new anchor_1.BN(marginRatio)
+        .mul(numericConstants_1.LIQUIDATION_FEE_PRECISION)
+        .div(numericConstants_1.MARGIN_PRECISION);
+    const liquidationFeeBN = new anchor_1.BN(liquidationFee);
+    if (oraclePrice.eq(new anchor_1.BN(0)) || marginRatioBN.lte(liquidationFeeBN)) {
+        // undefined is max
+        return undefined;
+    }
+    return marginShortage.mul(numericConstants_1.PRICE_TIMES_AMM_TO_QUOTE_PRECISION_RATIO).div(oraclePrice
+        .mul(quoteOraclePrice)
+        .div(numericConstants_1.PRICE_PRECISION)
+        .mul(marginRatioBN.sub(liquidationFeeBN))
+        .div(numericConstants_1.LIQUIDATION_FEE_PRECISION)
+        .sub(oraclePrice.mul(new anchor_1.BN(ifLiquidationFee)).div(numericConstants_1.LIQUIDATION_FEE_PRECISION)));
+}
+exports.calculateBaseAssetAmountToCoverMarginShortage = calculateBaseAssetAmountToCoverMarginShortage;
+function calculateLiabilityTransferToCoverMarginShortage(marginShortage, assetWeight, assetLiquidationMultiplier, liabilityWeight, liabilityLiquidationMultiplier, liabilityDecimals, liabilityPrice, ifLiquidationFee) {
+    if (assetWeight >= liabilityWeight) {
+        // undefined is max
+        return undefined;
+    }
+    let numeratorScale;
+    let denominatorScale;
+    if (liabilityDecimals > 6) {
+        numeratorScale = new anchor_1.BN(10).pow(new anchor_1.BN(liabilityDecimals - 6));
+        denominatorScale = new anchor_1.BN(1);
+    }
+    else {
+        numeratorScale = new anchor_1.BN(1);
+        denominatorScale = new anchor_1.BN(10).pow(new anchor_1.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 anchor_1.BN.max(marginShortage
+        .mul(numeratorScale)
+        .mul(numericConstants_1.PRICE_PRECISION.mul(numericConstants_1.SPOT_MARKET_WEIGHT_PRECISION).mul(numericConstants_1.TEN))
+        .div(liabilityPrice
+        .mul(new anchor_1.BN(liabilityWeightComponent).sub(new anchor_1.BN(assetWeightComponent)))
+        .sub(liabilityPrice
+        .mul(new anchor_1.BN(ifLiquidationFee))
+        .div(numericConstants_1.LIQUIDATION_FEE_PRECISION)
+        .mul(new anchor_1.BN(liabilityWeight))
+        .mul(new anchor_1.BN(10))))
+        .div(denominatorScale), numericConstants_1.ONE);
+}
+exports.calculateLiabilityTransferToCoverMarginShortage = calculateLiabilityTransferToCoverMarginShortage;
+function calculateAssetTransferForLiabilityTransfer(assetAmount, assetLiquidationMultiplier, assetDecimals, assetPrice, liabilityAmount, liabilityLiquidationMultiplier, liabilityDecimals, liabilityPrice) {
+    let numeratorScale;
+    let denominatorScale;
+    if (assetDecimals > liabilityDecimals) {
+        numeratorScale = new anchor_1.BN(10).pow(new anchor_1.BN(assetDecimals - liabilityDecimals));
+        denominatorScale = new anchor_1.BN(1);
+    }
+    else {
+        numeratorScale = new anchor_1.BN(1);
+        denominatorScale = new anchor_1.BN(10).pow(new anchor_1.BN(liabilityDecimals - assetDecimals));
+    }
+    let assetTransfer = liabilityAmount
+        .mul(numeratorScale)
+        .mul(liabilityPrice)
+        .mul(new anchor_1.BN(assetLiquidationMultiplier))
+        .div(assetPrice.mul(new anchor_1.BN(liabilityLiquidationMultiplier)))
+        .div(denominatorScale);
+    assetTransfer = anchor_1.BN.max(assetTransfer, numericConstants_1.ONE);
+    // Need to check if asset_transfer should be rounded to asset amount
+    let assetValueNumeratorScale;
+    let assetValueDenominatorScale;
+    if (assetDecimals > 6) {
+        assetValueNumeratorScale = new anchor_1.BN(10).pow(new anchor_1.BN(assetDecimals - 6));
+        assetValueDenominatorScale = new anchor_1.BN(1);
+    }
+    else {
+        assetValueNumeratorScale = new anchor_1.BN(1);
+        assetValueDenominatorScale = new anchor_1.BN(10).pow(new anchor_1.BN(6 - assetDecimals));
+    }
+    let assetDelta;
+    if (assetTransfer > assetAmount) {
+        assetDelta = assetTransfer.sub(assetAmount);
+    }
+    else {
+        assetDelta = assetAmount.sub(assetTransfer);
+    }
+    const assetValueDelta = assetDelta
+        .mul(assetPrice)
+        .div(numericConstants_1.PRICE_PRECISION)
+        .mul(assetValueNumeratorScale)
+        .div(assetValueDenominatorScale);
+    if (assetValueDelta.lt(numericConstants_1.QUOTE_PRECISION)) {
+        assetTransfer = assetAmount;
+    }
+    return assetTransfer;
+}
+exports.calculateAssetTransferForLiabilityTransfer = calculateAssetTransferForLiabilityTransfer;
+function calculateMaxPctToLiquidate(userLastActiveSlot, userLiquidationMarginFreed, marginShortage, slot, initialPctToLiquidate, liquidationDuration) {
+    // if margin shortage is tiny, accelerate liquidation
+    if (marginShortage.lt(new anchor_1.BN(50).mul(numericConstants_1.QUOTE_PRECISION))) {
+        return numericConstants_1.LIQUIDATION_PCT_PRECISION;
+    }
+    let slotsElapsed;
+    if (userLiquidationMarginFreed.gt(new anchor_1.BN(0))) {
+        slotsElapsed = anchor_1.BN.max(slot.sub(userLastActiveSlot), new anchor_1.BN(0));
+    }
+    else {
+        slotsElapsed = new anchor_1.BN(0);
+    }
+    const pctFreeable = anchor_1.BN.min(slotsElapsed
+        .mul(numericConstants_1.LIQUIDATION_PCT_PRECISION)
+        .div(liquidationDuration) // ~ 1 minute if per slot is 400ms
+        .add(initialPctToLiquidate), numericConstants_1.LIQUIDATION_PCT_PRECISION);
+    const totalMarginShortage = marginShortage.add(userLiquidationMarginFreed);
+    const maxMarginFreed = totalMarginShortage
+        .mul(pctFreeable)
+        .div(numericConstants_1.LIQUIDATION_PCT_PRECISION);
+    const marginFreeable = anchor_1.BN.max(maxMarginFreed.sub(userLiquidationMarginFreed), new anchor_1.BN(0));
+    return marginFreeable.mul(numericConstants_1.LIQUIDATION_PCT_PRECISION).div(marginShortage);
+}
+exports.calculateMaxPctToLiquidate = calculateMaxPctToLiquidate;
+function getMarginShortage(maintenanceMarginRequirementPlusBuffer, maintenanceTotalCollateral) {
+    return maintenanceMarginRequirementPlusBuffer
+        .sub(maintenanceTotalCollateral)
+        .abs();
+}
+exports.getMarginShortage = getMarginShortage;

package/lib/browser/math/margin.d.ts

@@ -0,0 +1,45 @@
+/// <reference types="bn.js" />
+import { BN } from '../isomorphic/anchor';
+import { OraclePriceData } from '../oracles/types';
+import { VelocityClient } from '../velocityClient';
+import { PerpMarketAccount, PerpPosition, PositionDirection, UserAccount } from '../types';
+import { PublicKey } from '@solana/web3.js';
+export declare function calculateSizePremiumLiabilityWeight(size: BN, // AMM_RESERVE_PRECISION
+imfFactor: BN, liabilityWeight: BN, precision: BN, isBounded?: boolean): BN;
+export declare function calculateSizeDiscountAssetWeight(size: BN, // AMM_RESERVE_PRECISION
+imfFactor: BN, assetWeight: BN): BN;
+export declare function calculateOraclePriceForPerpMargin(perpPosition: PerpPosition, market: PerpMarketAccount, oraclePriceData: OraclePriceData): BN;
+/**
+ * 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 declare function calculateBaseAssetValueWithOracle(market: PerpMarketAccount, perpPosition: PerpPosition, oraclePriceData: Pick<OraclePriceData, 'price'>, includeOpenOrders?: boolean): BN;
+export declare function calculateWorstCaseBaseAssetAmount(perpPosition: PerpPosition, perpMarket: PerpMarketAccount, oraclePrice: BN): BN;
+export declare function calculateWorstCasePerpLiabilityValue(perpPosition: PerpPosition, perpMarket: PerpMarketAccount, oraclePrice: BN, includeOpenOrders?: boolean): {
+    worstCaseBaseAssetAmount: BN;
+    worstCaseLiabilityValue: BN;
+};
+export declare function calculatePerpLiabilityValue(baseAssetAmount: BN, price: BN): BN;
+/**
+ * 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 declare function calculateMarginUSDCRequiredForTrade(driftClient: VelocityClient, targetMarketIndex: number, baseSize: BN, userMaxMarginRatio?: number, entryPrice?: BN): BN;
+/**
+ * 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 declare function calculateCollateralDepositRequiredForTrade(driftClient: VelocityClient, targetMarketIndex: number, baseSize: BN, collateralIndex: number, userMaxMarginRatio?: number, estEntryPrice?: BN): BN;
+export declare function calculateCollateralValueOfDeposit(driftClient: VelocityClient, collateralIndex: number, baseSize: BN): BN;
+export declare function calculateLiquidationPrice(freeCollateral: BN, freeCollateralDelta: BN, oraclePrice: BN): BN;
+export declare function calculateUserMaxPerpOrderSize(driftClient: VelocityClient, userAccountKey: PublicKey, userAccount: UserAccount, targetMarketIndex: number, tradeSide: PositionDirection): {
+    tradeSize: BN;
+    oppositeSideTradeSize: BN;
+};