@d8x/perpetuals-sdk/dist/cjs/d8XMath.d.ts

Node TypeScript SDK for D8X Perpetual Futures

import { BigNumberish } from "ethers";
/**
 * @module d8xMath
 */
/**
 * Convert ABK64x64/2^35 bigint-format to float.
 * Divide by 2^64 to get a float, but it's already "divided" by 2^35,
 * so there's only 2^29 left
 * @param  {BigNumber|number} x number in ABDK-format/2^35
 * @returns {number} x/2^64 in number-format (float)
 */
export declare function ABDK29ToFloat(x: bigint | number): number;
/**
 * Convert ABK64x64 bigint-format to float.
 * Result = x/2^64 if big number, x/2^29 if number
 * @param  {BigNumberish|number} x number in ABDK-format or 2^29
 * @returns {number} x/2^64 in number-format (float)
 */
export declare function ABK64x64ToFloat(x: bigint | number): number;
/**
 *
 * @param {BigNumberish} x BigNumber in Dec-N format
 * @returns {number} x as a float (number)
 */
export declare function decNToFloat(x: BigNumberish, numDec: BigNumberish): number;
/**
 *
 * @param {BigNumberish} x BigNumber in Dec18 format
 * @returns {number} x as a float (number)
 */
export declare function dec18ToFloat(x: BigNumberish): number;
/**
 * Converts x into ABDK64x64 format
 * @param {number} x   number (float)
 * @returns {bigint} x^64 in big number format
 */
export declare function floatToABK64x64(x: number): bigint;
/**
 *
 * @param {number} x number (float)
 * @returns {BigNumber} x as a BigNumber in Dec18 format
 */
export declare function floatToDec18(x: number): bigint;
/**
 *
 * @param {number} x number (float)
 * @param {number} decimals number of decimals
 * @returns {BigNumber} x as a BigNumber in Dec18 format
 */
export declare function floatToDecN(x: number, decimals: number): bigint;
/**
 * 9 are rounded up regardless of precision, e.g, 0.1899000 at precision 6 results in 3
 * @param {number} x
 * @param {number} precision
 * @returns number of decimals
 */
export declare function countDecimalsOf(x: number, precision: number): number;
/**
 * Round a number to a given lot size and return a string formated
 * to for this lot-size
 * @param {number} x number to round
 * @param {number} lot lot size (could be 'uneven' such as 0.019999999 instead of 0.02)
 * @param {number} precision optional lot size precision (e.g. if 0.01999 should be 0.02 then precision could be 5)
 * @returns formated number string
 */
export declare function roundToLotString(x: number, lot: number, precision?: number): string;
/**
 *
 * @param {bigint} x
 * @param {bigint} y
 * @returns {bigint} x * y
 */
export declare function mul64x64(x: bigint, y: bigint): bigint;
/**
 *
 * @param {bigint} x
 * @param {bigint} y
 * @returns {bigint} x / y
 */
export declare function div64x64(x: bigint, y: bigint): bigint;
/**
 * Determine the liquidation price
 * @param {number} LockedInValueQC - trader locked in value in quote currency
 * @param {number} position - trader position in base currency
 * @param {number} cash_cc - trader available margin cash in collateral currency
 * @param {number} maintenance_margin_rate - maintenance margin ratio
 * @param {number} S3 - collateral to quote conversion (=S2 if base-collateral, =1 if quuote collateral, = index S3 if quanto)
 * @returns {number} Amount to be deposited to have the given leverage when trading into position pos
 */
export declare function calculateLiquidationPriceCollateralBase(LockedInValueQC: number, position: number, cash_cc: number, maintenance_margin_rate: number): number;
/**
 * Determine the liquidation price
 * @param {number} LockedInValueQC - trader locked in value in quote currency
 * @param {number} position - trader position in base currency
 * @param {number} cash_cc - trader available margin cash in collateral currency
 * @param {number} maintenance_margin_rate - maintenance margin ratio
 * @param {number} S3 - collateral to quote conversion (=S2 if base-collateral, =1 if quuote collateral, = index S3 if quanto)
 * @param {number} Sm - mark price
 * @returns {number} Amount to be deposited to have the given leverage when trading into position pos
 */
export declare function calculateLiquidationPriceCollateralQuantoConservative(LockedInValueQC: number, position: number, cash_cc: number, maintenance_margin_rate: number, S3: number, Sm: number): number;
/**
 * Determine the liquidation price for quanto -- assuming quanto currency value remains constant
 * See calculateLiquidationPriceCollateralQuantoConservative for a more conservative version
 * @param {number} LockedInValueQC - trader locked in value in quote currency
 * @param {number} position - trader position in base currency
 * @param {number} cash_cc - trader available margin cash in collateral currency
 * @param {number} maintenance_margin_rate - maintenance margin ratio
 * @param {number} S3 - collateral to quote conversion (=S2 if base-collateral, =1 if quuote collateral, = index S3 if quanto)
 * @param {number} Sm - mark price
 * @returns {number} Amount to be deposited to have the given leverage when trading into position pos
 */
export declare function calculateLiquidationPriceCollateralQuanto(LockedInValueQC: number, position: number, cash_cc: number, maintenance_margin_rate: number, S3: number, Sm: number): number;
/**
 * Determine the liquidation price
 * @param {number} LockedInValueQC - trader locked in value in quote currency
 * @param {number} position - trader position in base currency
 * @param {number} cash_cc - trader available margin cash in collateral currency
 * @param {number} maintenance_margin_rate - maintenance margin ratio
 * @param {number} S3 - collateral to quote conversion (=S2 if base-collateral, =1 if quuote collateral, = index S3 if quanto)
 * @returns {number} Amount to be deposited to have the given leverage when trading into position pos
 */
export declare function calculateLiquidationPriceCollateralQuote(LockedInValueQC: number, position: number, cash_cc: number, maintenance_margin_rate: number): number;
/**
 *
 * @param targetLeverage Leverage of the resulting position. It must be positive unless the resulting position is closed.
 * @param currentPosition Current position size, in base currency, signed.
 * @param currentLockedInValue Current locked in value, average entry price times position size, in quote currency.
 * @param tradeAmount Trade amount, in base currency, signed.
 * @param markPrice Mark price, positive.
 * @param indexPriceS2 Index price, positive.
 * @param indexPriceS3 Collateral index price, positive.
 * @param tradePrice Expected price to trade tradeAmount.
 * @param feeRate
 * @returns {number} Total collateral amount needed for the new position to have he desired leverage.
 */
export declare function getMarginRequiredForLeveragedTrade(targetLeverage: number | undefined, currentPosition: number, currentLockedInValue: number, tradeAmount: number, markPrice: number, indexPriceS2: number, indexPriceS3: number, tradePrice: number, feeRate: number): number;
export declare function getMaxSignedPositionSize(marginCollateral: number, currentPosition: number, currentLockedInValue: number, direction: number, limitPrice: number, initialMarginRate: number, feeRate: number, markPrice: number, indexPriceS2: number, indexPriceS3: number): number;
/**
 * Compute the leverage resulting from a trade
 * @param tradeAmount Amount to trade, in base currency, signed
 * @param marginCollateral Amount of cash in the margin account, in collateral currency
 * @param currentPosition Position size before the trade
 * @param currentLockedInValue Locked-in value before the trade
 * @param price Price charged to trade tradeAmount
 * @param indexPriceS3 Spot price of the collateral currency when the trade happens
 * @param markPrice Mark price of the index when the trade happens
 * @returns Leverage of the resulting position
 */
export declare function getNewPositionLeverage(tradeAmount: number, marginCollateral: number, currentPosition: number, currentLockedInValue: number, price: number, indexPriceS3: number, markPrice: number): number;
/**
 * Determine amount to be deposited into margin account so that the given leverage
 * is obtained when trading a position pos (trade amount = position)
 * Does NOT include fees
 * Smart contract equivalent: calcMarginForTargetLeverage(..., _ignorePosBalance = false & balance = b0)
 * @param {number} pos0 - current position
 * @param {number} b0 - current balance
 * @param {number} tradeAmnt - amount to trade
 * @param {number} targetLvg - target leverage
 * @param {number} price - price to trade amount 'tradeAmnt'
 * @param {number} S3 - collateral to quote conversion (=S2 if base-collateral, =1 if quote collateral, = index S3 if quanto)
 * @param {number} S2Mark - mark price
 * @param {number} cmin - Absolute minimum margin per contract, only for pred markets
 * @returns {number} Amount to be deposited to have the given leverage when trading into position pos before fees
 */
export declare function getDepositAmountForLvgTrade(pos0: number, b0: number, tradeAmnt: number, targetLvg: number, price: number, S3: number, S2Mark: number, cmin: number | undefined): number;
/**
 * Determine amount to be deposited into margin account so that the given leverage
 * is obtained when opening a prediction market position
 * Does NOT include fees, but accounts for a possible non-zero current position
 * Smart contract equivalent: getDepositAmountForPredMktLvgPosition
 * @param {number} pos0 - current position
 * @param {number} b0 - current balance
 * @param {number} c0 - current available cash
 * @param {number} tradeAmnt - amount to trade
 * @param {number} targetLvg - target leverage
 * @param {number} prob - prob to trade amount 'tradeAmnt'
 * @param {number} S3 - collateral to quote conversion (=S2 if base-collateral, =1 if quote collateral, = index S3 if quanto)
 * @param {number} markProb - mark prob
 * @param {number} imr - minimum absolute margin per contract (fInitialMarginRate)
 * @returns {number} Amount to be deposited to have the given leverage when trading into position pos before fees
 */
export declare function getDepositAmountForPredMktLvgTrade(pos0: number, b0: number, c0: number, tradeAmnt: number, targetLvg: number, prob: number, S3: number, markProb: number, imr: number): number;
/**
 * Convert a perpetual price to probability (predtictive markets)
 * @param px Perpetual price
 * @returns Probability in [0,1]
 */
export declare function priceToProb(px: number): number;
/**
 * Convert a probability to a predictive market price
 * @param prob Probability in [0,1]
 * @returns Perpetual price
 */
export declare function probToPrice(prob: number): number;
export declare function entropy(prob: number): number;
export declare function pmMaintenanceMarginRate(position: number, lockedInQC: number, sm: number, m: number): number;
/**
 * Initial margin rate for prediction markets.
 * @param posSign sign of position in base currency (can be signed position or -1, 1)
 * @param s0 trade price
 * @param sm  mark-price (=1+p)
 * @param cmin Absolute min margin saved as `fInitialMarginRate`
 * @returns {number} The margin rate to be applied: `(Math.abs(pos) * p * tau) / s3`
 */
export declare function pmInitialMarginRate(posSign: number, s0: number, sm: number, cmin: number): number;
/**
 * Exchange fee as a rate for prediction markets
 * For opening trades only
 * @param prob long probability
 * @param m max maintenance margin rate (0.18)
 * @param tradeAmt trade amount in base currency
 * @param tradeMgnRate margin rate for this trade
 * @returns dollar fee relative to tradeAmt
 */
export declare function pmExchangeFee(prob: number, m: number, tradeAmt: number, tradeMgnRate: number): number;
export declare function pmExitFee(varphi: number, varphi_0: number, m_0Exit: number, mu_m: number, mu_i: number, sigt: number, jump: number): number;
export declare function pmOpenFee(varphi_0: number, m_0: number, mu_m: number, sigt: number, jump: number): number;
export declare function extractLvgFeeParams(conf: bigint): {
    jump: number;
    sigt: number;
};
export declare function decodePriceImpact(amount: bigint, params: bigint): {
    a: number;
    m: number;
    l: number;
    dp: number;
};
export declare function erfc(x: number): number;
/**
 * Margin balance for prediction markets
 * @param pos signed position
 * @param s2 mark price
 * @param s3 collateral to quote conversion
 * @param ell locked in value
 * @param mc margin cash in collateral currency
 * @returns current margin balance
 */
export declare function pmMarginBalance(pos: number, s2: number, s3: number, ell: number, mc: number): number;
export declare function pmExcessBalance(pos: number, s2: number, s3: number, ell: number, mc: number, m: number): number;
/**
 *
 * @param pos Signed position size
 * @param s3 Collateral to quote conversion at spot
 * @param ell Locked-in value
 * @param mc Margin collateral
 * @param baseMarginRate Maintenance margin per contract (mu_m)
 * @param sm Mark price at entry
 * @returns {number} Liquidation price as a probability in the range [0, 1]
 */
export declare function pmFindLiquidationPrice(pos: number, s3: number, ell: number, mc: number, baseMarginRate: number): number;
/**
 * Find maximal *affordable* trade size (short dir=-1 or long dir=1) for prediction
 * markets at provided leverage and incorporating the current position
 * and wallet balance.
 * Factors in lot size and global max short/long, factors in opening/closing position
 * @param dir   direction of trade (-1 sell, 1 buy)
 * @param lvg   leverage of the trade
 * @param walletBalCC wallet balance of the trader (collateral currency)
 * @param slippage  slippage percent used to estimate a traded price
 * @param currentPosition position in base currency of the trader
 * @param currentCashCC this is the cash available net of unpaid funding (often called available cash)
 * @param currentLockedInValue average entry price * signed position size in base currency, in margin account
 * @param S2  current index price of the form 1+p (regardless whether short or long)
 * @param Sm  current mark price (not just the mark price index but including the ema-premium from the contract)
 * @param S3  current collateral to quote index price
 * @param glblMaxTrade global max short or long order size that we retreive, e.g., from position risk (sign irrelevant)
 *        based on  long: (*ℓ+n) * (1-p) - m (1-p) s = F → n = (F+m*(1-p)*s)/(1-p)-ℓ*
 *                  short: (s+n)*p - m p *ℓ* = F →n = (F+m*p**ℓ*)/p-s
 * @returns max *signed* trade size
 */
export declare function pmFindMaxPersonalTradeSizeAtLeverage(dir: number, lvg: number, walletBalCC: number, slippage: number, currentPosition: number, currentCashCC: number, currentLockedInValue: number, S2: number, Sm: number, S3: number, glblMaxTrade: number): number;
/**
 * See PerpetualTradeLogic::_getMaxSignedOpenPredMktTradeSize
 * @param long Long open OI
 * @param short Short open OI
 * @param sm Mark price (>1)
 * @param isBuy True if trade is long
 * @param mr Margin threshold per contract for liquidation (mu_m)
 */
export declare function pmMaxSignedOpenTradeSize(long: number, short: number, sm: number, isBuy: boolean, mr: number, ammFundsQC: number): number;