@d8x/perpetuals-sdk 0.0.21 → 0.0.22

package/src/d8XMath.ts

@@ -1,3 +1,4 @@
+import { assert } from "console";
 import { BigNumber } from "ethers";
 import { DECIMALS, ONE_64x64 } from "./nodeSDKTypes";
 
@@ -177,3 +178,87 @@ export function calculateLiquidationPriceCollateralQuote(
   let denominator = maintenance_margin_rate * Math.abs(position) - position;
   return numerator / denominator;
 }
+
+/**
+ *
+ * @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 Total collateral amount needed for the new position to have he desired leverage.
+ */
+export function getMarginRequiredForLeveragedTrade(
+  targetLeverage: number | undefined,
+  currentPosition: number,
+  currentLockedInValue: number,
+  tradeAmount: number,
+  markPrice: number,
+  indexPriceS2: number,
+  indexPriceS3: number,
+  tradePrice: number,
+  feeRate: number
+): number {
+  // we solve for margin in:
+  // |new position| * Sm / leverage + fee rate * |trade amount| * S2 = margin * S3 + current position * Sm - L + trade amount * (Sm - trade price)
+  // --> M S3 = |P'|Sm/L + FeeQC - PnL + (P'-P)(Price - Sm) = pos value / leverage + fees + price impact - pnl
+  let isClosing =
+    currentPosition != 0 && currentPosition * tradeAmount < 0 && currentPosition * (currentPosition + tradeAmount) >= 0;
+  let feesCC = (feeRate * Math.abs(tradeAmount) * indexPriceS2) / indexPriceS3;
+  let collRequired = feesCC;
+
+  if (!isClosing) {
+    if (targetLeverage == undefined || targetLeverage <= 0) {
+      throw Error("opening trades must have positive leverage");
+    }
+    // unrealized pnl (could be + or -)  - price impact premium (+)
+    let pnlQC = currentPosition * markPrice - currentLockedInValue - tradeAmount * (tradePrice - markPrice);
+    collRequired +=
+      Math.max(0, (Math.abs(currentPosition + tradeAmount) * markPrice) / targetLeverage - pnlQC) / indexPriceS3;
+  }
+  return collRequired;
+}
+
+export function getMaxSignedPositionSize(
+  marginCollateral: number,
+  currentPosition: number,
+  currentLockedInValue: number,
+  direction: number,
+  limitPrice: number,
+  initialMarginRate: number,
+  feeRate: number,
+  markPrice: number,
+  indexPriceS2: number,
+  indexPriceS3: number
+): number {
+  // we solve for new position in:
+  // |new position| * Sm / leverage + fee rate * |trade amount| * S2 = margin * S3 + current position * Sm - L + trade amount * (Sm - entry price)
+  // |trade amount| = (new position - current position) * direction
+  let availableCash = marginCollateral * indexPriceS3 + currentPosition * markPrice - currentLockedInValue;
+  let effectiveMarginRate =
+    markPrice * initialMarginRate + feeRate * indexPriceS2 + direction * (limitPrice - markPrice);
+
+  return availableCash / effectiveMarginRate;
+}
+
+export function getNewPositionLeverage(
+  tradeAmount: number,
+  marginCollateral: number,
+  currentPosition: number,
+  currentLockedInValue: number,
+  indexPriceS2: number,
+  indexPriceS3: number,
+  markPrice: number,
+  limitPrice: number,
+  feeRate: number
+): number {
+  let newPosition = tradeAmount + currentPosition;
+  let pnlQC = currentPosition * markPrice - currentLockedInValue + tradeAmount * (markPrice - limitPrice);
+  return (
+    (Math.abs(newPosition) * indexPriceS2) / (marginCollateral * indexPriceS3 + pnlQC - feeRate * Math.abs(tradeAmount))
+  );
+}

package/src/liquidityProviderTool.ts

@@ -149,12 +149,4 @@ export default class LiquidityProviderTool extends WriteAccessHandler {
     });
     return tx;
   }
-
-  /*
-  TODO:
-  - add liquidity
-    addLiquidity(uint8 _poolId, int128 _fTokenAmount)
-  - remove liquidity
-    function removeLiquidity(uint8 _poolId, int128 _fShareAmount) external override nonReentrant 
-  */
 }

package/src/marketData.ts

@@ -8,10 +8,24 @@ import {
   COLLATERAL_CURRENCY_QUANTO,
   PERP_STATE_STR,
   ZERO_ADDRESS,
+  PoolStaticInfo,
+  BUY_SIDE,
+  CLOSED_SIDE,
+  SELL_SIDE,
+  CollaterlCCY,
 } from "./nodeSDKTypes";
 import { BigNumber, BytesLike, ethers } from "ethers";
-import { floatToABK64x64, ABK64x64ToFloat } from "./d8XMath";
-import { fromBytes4HexString, toBytes4 } from "./utils";
+import {
+  floatToABK64x64,
+  ABK64x64ToFloat,
+  getNewPositionLeverage,
+  getMarginRequiredForLeveragedTrade,
+  calculateLiquidationPriceCollateralBase,
+  calculateLiquidationPriceCollateralQuanto,
+  calculateLiquidationPriceCollateralQuote,
+  getMaxSignedPositionSize,
+} from "./d8XMath";
+import { contractSymbolToSymbol, fromBytes4HexString, toBytes4 } from "./utils";
 import PerpetualDataHandler from "./perpetualDataHandler";
 import { SmartContractOrder, Order } from "./nodeSDKTypes";
 import "./nodeSDKTypes";
@@ -60,6 +74,15 @@ export default class MarketData extends PerpetualDataHandler {
     await this.initContractsAndData(this.provider);
   }
 
+  /**
+   * Convert the smart contract output of an order into a convenient format of type "Order"
+   * @param smOrder SmartContractOrder, as obtained e.g., by PerpetualLimitOrderCreated event
+   * @returns more convenient format of order, type "Order"
+   */
+  public smartContractOrderToOrder(smOrder: SmartContractOrder): Order {
+    return PerpetualDataHandler.fromSmartContractOrder(smOrder, this.symbolToPerpStaticInfo);
+  }
+
   /**
    * Get contract instance. Useful for event listening.
    * @example
@@ -107,7 +130,7 @@ export default class MarketData extends PerpetualDataHandler {
     if (this.proxyContract == null) {
       throw Error("no proxy contract initialized. Use createProxyInstance().");
     }
-    return await MarketData._exchangeInfo(this.proxyContract);
+    return await MarketData._exchangeInfo(this.proxyContract, this.poolStaticInfos, this.symbolList);
   }
 
   /**
@@ -142,9 +165,9 @@ export default class MarketData extends PerpetualDataHandler {
   }
 
   /**
-   * Information about the positions open by a given trader in a given perpetual contract.
+   * Information about the position open by a given trader in a given perpetual contract.
    * @param {string} traderAddr Address of the trader for which we get the position risk.
-   * @param {string} symbol Symbol of the form ETH-USD-MATIC.
+   * @param {string} symbol Symbol of the form ETH-USD-MATIC. Can also be the perpetual id as string
    * @example
    * import { MarketData, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
    * async function main() {
@@ -175,6 +198,151 @@ export default class MarketData extends PerpetualDataHandler {
     return mgnAcct;
   }
 
+  public async positionRiskOnTrade(
+    traderAddr: string,
+    order: Order,
+    perpetualState: PerpetualState,
+    currentPositionRisk?: MarginAccount
+  ): Promise<MarginAccount> {
+    if (this.proxyContract == null) {
+      throw Error("no proxy contract initialized. Use createProxyInstance().");
+    }
+    if (currentPositionRisk == undefined) {
+      currentPositionRisk = await this.positionRisk(traderAddr, order.symbol);
+    }
+    let tradeAmount = order.quantity * (order.side == BUY_SIDE ? 1 : -1);
+    let currentPosition = currentPositionRisk.positionNotionalBaseCCY;
+    let newPosition = currentPositionRisk.positionNotionalBaseCCY + tradeAmount;
+    let side = newPosition > 0 ? BUY_SIDE : newPosition < 0 ? SELL_SIDE : CLOSED_SIDE;
+    let lockedInValue = currentPositionRisk.entryPrice * currentPosition;
+    let poolId = PerpetualDataHandler._getPoolIdFromSymbol(order.symbol, this.poolStaticInfos);
+
+    // total fee rate = exchange fee + broker fee
+    let feeRate =
+      (await this.proxyContract.queryExchangeFee(poolId, traderAddr, order.brokerAddr ?? ZERO_ADDRESS)) +
+      (order.brokerFeeTbps ?? 0) / 100_000;
+
+    // price for this order = limit price (conservative) if given, else the current perp price
+    let tradePrice = order.limitPrice ?? (await this.getPerpetualPrice(order.symbol, tradeAmount));
+
+    // need these for leverage/margin calculations
+    let [markPrice, indexPriceS2, indexPriceS3] = [
+      perpetualState.markPrice,
+      perpetualState.indexPrice,
+      perpetualState.collToQuoteIndexPrice,
+    ];
+    let newCollateral: number;
+    let newLeverage: number;
+    if (order.keepPositionLvg) {
+      // we have a target leverage for the resulting position
+      // this gives us the total margin needed in the account so that it satisfies the leverage condition
+      newCollateral = getMarginRequiredForLeveragedTrade(
+        currentPositionRisk.leverage,
+        currentPosition,
+        lockedInValue,
+        tradeAmount,
+        markPrice,
+        indexPriceS2,
+        indexPriceS3,
+        tradePrice,
+        feeRate
+      );
+      // the new leverage follows from the updated margin and position
+      newLeverage = getNewPositionLeverage(
+        tradeAmount,
+        newCollateral,
+        currentPosition,
+        lockedInValue,
+        indexPriceS2,
+        indexPriceS3,
+        markPrice,
+        tradePrice,
+        feeRate
+      );
+    } else {
+      // the order has its own leverage and margin requirements
+      let tradeCollateral = getMarginRequiredForLeveragedTrade(
+        order.leverage,
+        0,
+        0,
+        tradeAmount,
+        markPrice,
+        indexPriceS2,
+        indexPriceS3,
+        tradePrice,
+        feeRate
+      );
+      newCollateral = currentPositionRisk.collateralCC + tradeCollateral;
+      // the new leverage corresponds to increasing the position and collateral according to the order
+      newLeverage = getNewPositionLeverage(
+        tradeAmount,
+        newCollateral,
+        currentPosition,
+        lockedInValue,
+        indexPriceS2,
+        indexPriceS3,
+        markPrice,
+        tradePrice,
+        feeRate
+      );
+    }
+    let newLockedInValue = lockedInValue + tradeAmount * tradePrice;
+
+    // liquidation vars
+    let S2Liq: number, S3Liq: number | undefined;
+    let tau = this.symbolToPerpStaticInfo.get(order.symbol)!.maintenanceMarginRate;
+    let ccyType = this.symbolToPerpStaticInfo.get(order.symbol)!.collateralCurrencyType;
+    if (ccyType == CollaterlCCY.BASE) {
+      S2Liq = calculateLiquidationPriceCollateralBase(newLockedInValue, newPosition, newCollateral, tau);
+      S3Liq = S2Liq;
+    } else if (ccyType == CollaterlCCY.QUANTO) {
+      S3Liq = indexPriceS3;
+      S2Liq = calculateLiquidationPriceCollateralQuanto(
+        newLockedInValue,
+        newPosition,
+        newCollateral,
+        tau,
+        indexPriceS3,
+        markPrice
+      );
+    } else {
+      S2Liq = calculateLiquidationPriceCollateralQuote(newLockedInValue, newPosition, newCollateral, tau);
+    }
+    let newPositionRisk: MarginAccount = {
+      symbol: currentPositionRisk.symbol,
+      positionNotionalBaseCCY: newPosition,
+      side: side,
+      entryPrice: Math.abs(newLockedInValue / newPosition),
+      leverage: newLeverage,
+      markPrice: markPrice,
+      unrealizedPnlQuoteCCY: tradeAmount * (markPrice - tradePrice),
+      unrealizedFundingCollateralCCY: currentPositionRisk.unrealizedFundingCollateralCCY,
+      collateralCC: newCollateral,
+      collToQuoteConversion: indexPriceS3,
+      liquidationPrice: [S2Liq, S3Liq],
+      liquidationLvg: 1 / tau,
+    };
+    return newPositionRisk;
+  }
+
+  public maxOrderSizeForTrader(side: string, positionRisk: MarginAccount, perpetualState: PerpetualState): number {
+    let initialMarginRate = this.symbolToPerpStaticInfo.get(positionRisk.symbol)!.initialMarginRate;
+    // fees not considered here
+    let maxPosition = getMaxSignedPositionSize(
+      positionRisk.collateralCC,
+      positionRisk.positionNotionalBaseCCY,
+      positionRisk.entryPrice * positionRisk.positionNotionalBaseCCY,
+      side == BUY_SIDE ? 1 : -1,
+      perpetualState.markPrice,
+      initialMarginRate,
+      0,
+      perpetualState.markPrice,
+      perpetualState.indexPrice,
+      perpetualState.collToQuoteIndexPrice
+    );
+    return maxPosition - positionRisk.positionNotionalBaseCCY;
+  }
+
   /**
    * Uses the Oracle(s) in the exchange to get the latest price of a given index in a given currency, if a route exists.
    * @param {string} base Index name, e.g. ETH.
@@ -261,6 +429,49 @@ export default class MarketData extends PerpetualDataHandler {
     );
   }
 
+  /**
+   * Query recent perpetual state from blockchain
+   * @param symbol symbol of the form ETH-USD-MATIC
+   * @returns PerpetualState reference
+   */
+  public async getPerpetualState(symbol: string): Promise<PerpetualState> {
+    if (this.proxyContract == null) {
+      throw Error("no proxy contract initialized. Use createProxyInstance().");
+    }
+    let state: PerpetualState = await PerpetualDataHandler._queryPerpetualState(
+      symbol,
+      this.symbolToPerpStaticInfo,
+      this.proxyContract
+    );
+    return state;
+  }
+
+  /**
+   * get the current mid-price for a perpetual
+   * @param symbol symbol of the form ETH-USD-MATIC
+   * @example
+   * import { MarketData, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
+   * async function main() {
+   *   console.log(MarketData);
+   *   // setup
+   *   const config = PerpetualDataHandler.readSDKConfig("testnet");
+   *   let mktData = new MarketData(config);
+   *   await mktData.createProxyInstance();
+   *   // get perpetual mid price
+   *   let midPrice = await mktData.getPerpetualMidPrice("ETH-USD-MATIC");
+   *   console.log(midPrice);
+   * }
+   * main();
+   *
+   * @returns {number} price
+   */
+  public async getPerpetualMidPrice(symbol: string): Promise<number> {
+    if (this.proxyContract == null) {
+      throw Error("no proxy contract initialized. Use createProxyInstance().");
+    }
+    return await this.getPerpetualPrice(symbol, 0);
+  }
+
   /**
    * Query smart contract to get user orders and convert to user friendly order format.
    * @param {string} traderAddr Address of trader.
@@ -298,7 +509,11 @@ export default class MarketData extends PerpetualDataHandler {
     return digests;
   }
 
-  public static async _exchangeInfo(_proxyContract: ethers.Contract): Promise<ExchangeInfo> {
+  public static async _exchangeInfo(
+    _proxyContract: ethers.Contract,
+    _poolStaticInfos: Array<PoolStaticInfo>,
+    _symbolList: Array<{ [key: string]: string }>
+  ): Promise<ExchangeInfo> {
     let nestedPerpetualIDs = await PerpetualDataHandler.getNestedPerpetualIds(_proxyContract);
     let factory = await _proxyContract.getOracleFactory();
     let info: ExchangeInfo = { pools: [], oracleFactoryAddr: factory };
@@ -308,6 +523,7 @@ export default class MarketData extends PerpetualDataHandler {
       let pool = await _proxyContract.getLiquidityPool(j + 1);
       let PoolState: PoolState = {
         isRunning: pool.isRunning,
+        poolSymbol: _poolStaticInfos[j].poolMarginSymbol,
         marginTokenAddr: pool.marginTokenAddress,
         poolShareTokenAddr: pool.shareTokenAddress,
         defaultFundCashCC: ABK64x64ToFloat(pool.fDefaultFundCashCC),
@@ -320,6 +536,7 @@ export default class MarketData extends PerpetualDataHandler {
       for (var k = 0; k < perpetualIDs.length; k++) {
         let perp = await _proxyContract.getPerpetual(perpetualIDs[k]);
         let fIndexS2 = await _proxyContract.getOraclePrice([perp.S2BaseCCY, perp.S2QuoteCCY]);
+        let fMidPrice = await _proxyContract.queryPerpetualPrice(perpetualIDs[k], BigNumber.from(0));
         let indexS2 = ABK64x64ToFloat(fIndexS2);
         let indexS3 = 1;
         if (perp.eCollateralCurrency == COLLATERAL_CURRENCY_BASE) {
@@ -333,11 +550,12 @@ export default class MarketData extends PerpetualDataHandler {
         let PerpetualState: PerpetualState = {
           id: perp.id,
           state: state,
-          baseCurrency: fromBytes4HexString(perp.S2BaseCCY),
-          quoteCurrency: fromBytes4HexString(perp.S2QuoteCCY),
+          baseCurrency: contractSymbolToSymbol(perp.S2BaseCCY, _symbolList)!,
+          quoteCurrency: contractSymbolToSymbol(perp.S2QuoteCCY, _symbolList)!,
           indexPrice: indexS2,
           collToQuoteIndexPrice: indexS3,
           markPrice: indexS2 * (1 + markPremiumRate),
+          midPrice: ABK64x64ToFloat(fMidPrice),
           currentFundingRateBps: currentFundingRateBps,
           openInterestBC: ABK64x64ToFloat(perp.fOpenInterest),
           maxPositionBC: ABK64x64ToFloat(perp.fMaxPositionBC),

package/src/nodeSDKTypes.ts

@@ -39,6 +39,7 @@ export interface NodeSDKConfig {
   limitOrderBookFactoryAddr: string;
   limitOrderBookABILocation: string;
   limitOrderBookFactoryABILocation: string;
+  symbolListLocation: string;
   gasLimit?: number | undefined;
 }
 
@@ -110,6 +111,7 @@ export interface ExchangeInfo {
  */
 export interface PoolState {
   isRunning: boolean;
+  poolSymbol: string;
   marginTokenAddr: string;
   poolShareTokenAddr: string;
   defaultFundCashCC: number;
@@ -128,6 +130,7 @@ export interface PerpetualState {
   indexPrice: number;
   collToQuoteIndexPrice: number;
   markPrice: number;
+  midPrice: number;
   currentFundingRateBps: number;
   openInterestBC: number;
   maxPositionBC: number;
@@ -138,6 +141,11 @@ export interface OrderResponse {
   orderId: string;
 }
 
+export interface OrderStruct {
+  orders: Order[];
+  orderIds: string[];
+}
+
 export interface Order {
   symbol: string;
   side: string;
@@ -156,6 +164,14 @@ export interface Order {
   submittedBlock?: number;
 }
 
+export interface TradeEvent {
+  perpetualId: number;
+  positionId: string;
+  orderId: string;
+  newPositionSizeBC: number;
+  executionPrice: number;
+}
+
 export interface SmartContractOrder {
   flags: BigNumberish;
   iPerpetualId: BigNumberish;

package/src/orderReferrerTool.ts

@@ -234,9 +234,6 @@ export default class OrderReferrerTool extends WriteAccessHandler {
     if (this.proxyContract == null) {
       throw Error("no proxy contract initialized. Use createProxyInstance().");
     }
-    if (order.limitPrice == undefined) {
-      throw Error("order does not have a limit price");
-    }
     // check expiration date
     if (order.deadline != undefined && order.deadline < Date.now() / 1000) {
       return false;
@@ -245,7 +242,10 @@ export default class OrderReferrerTool extends WriteAccessHandler {
     if (order.quantity < PerpetualDataHandler._getLotSize(order.symbol, this.symbolToPerpStaticInfo)) {
       return false;
     }
-    // check limit price
+    // check limit price, which may be undefined if it's an unrestricted market order
+    if (order.limitPrice == undefined) {
+      order.limitPrice = order.side == BUY_SIDE ? Infinity : 0;
+    }
     let orderPrice = await PerpetualDataHandler._queryPerpetualPrice(
       order.symbol,
       order.quantity,