@d8x/perpetuals-sdk 2.6.23 → 2.7.0

package/src/d8XMath.ts

@@ -410,7 +410,7 @@ export function getNewPositionLeverage(
  * @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 {boolean} isPredMkt - true if prediction market
+ * @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 function getDepositAmountForLvgTrade(
@@ -421,29 +421,112 @@ export function getDepositAmountForLvgTrade(
   price: number,
   S3: number,
   S2Mark: number,
-  isPredMkt: boolean
+  cmin: number | undefined
 ) {
-  let pnl = (tradeAmnt * (S2Mark - price)) / S3;
-  let S2MarkBefore = S2Mark;
-  if (isPredMkt) {
-    // adjust mark price to 'probability'
-    S2Mark = S2Mark - 1;
-    S2MarkBefore = S2Mark;
-    if (pos0 < 0) {
-      S2MarkBefore = 1 - S2Mark;
-    }
-    if (pos0 + tradeAmnt < 0) {
-      S2Mark = 1 - S2Mark;
+  if (cmin && cmin > 0) {
+    // TODO: c0?
+    if (b0 != 0) {
+      console.log("b0 != 0");
     }
+    return getDepositAmountForPredMktLvgTrade(pos0, b0, 0, tradeAmnt, targetLvg, price - 1, S3, S2Mark - 1, cmin);
   }
+  let pnl = (tradeAmnt * (S2Mark - price)) / S3;
   if (targetLvg == 0) {
     // use current leverage
-    targetLvg = (Math.abs(pos0) * S2MarkBefore) / S3 / b0;
+    targetLvg = (Math.abs(pos0) * S2Mark) / S3 / b0;
   }
   let b = (Math.abs(pos0 + tradeAmnt) * S2Mark) / S3 / targetLvg;
   return -(b0 + pnl - b);
 }
 
+/**
+ * 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 function getDepositAmountForPredMktLvgTrade(
+  pos0: number,
+  b0: number,
+  c0: number,
+  tradeAmnt: number,
+  targetLvg: number,
+  prob: number,
+  S3: number,
+  markProb: number,
+  imr: number
+) {
+  /**
+   * Smart contract implementation:
+        // find smallest x such that:
+        //      bal * s3 >= pos value / lvg
+        // where:
+        //      pos value / lvg = |pos| * R(pm, sign(pos)) * margin rate
+        //      pos = pos0 + k
+        //      cash = cash0 + x
+        //      ell = ell0 + px * k
+        //      bal * s3 = cash * s3 + pos * sm - ell
+        //               = bal0 * s3 + x * s3 + k * (sm - px)
+
+        // subject to:
+        //      x >= 0
+        //      cash * s3 >= |pos| * min(cmin, prob(sign(pos)))
+        //      k * (sm - px) <= 0 a.s.
+        //      (positive pnl does not contribute, i.e. ignore px better than mark)
+
+        // solution:
+        //  bal0 * s3 + x * s3 >= pos value / lvg + (k * (px - sm))_+ = v * s3
+        // -->
+        //  x >= v + (cash0 - bal0)_+ - cash0 = v - min(bal0, cash0)
+        //     = pos value / lvg/ s3 + (k * (px - sm))_+ / s3  - min (bal0, cash0)
+        //     = A + B - C
+        //  x >= |pos| *  min(cmin, prob(sign(pos))) / s3 - cash0
+        //  x >= 0
+
+        // init x = A = pos value / lvg / s3
+        int128 fNewPos = _fPosition0.add(_fTradeAmount);
+        int128 v = (
+            fNewPos > 0 ? fNewPos.mul(_fMarkProb) : fNewPos.neg().mul(ONE_64x64.sub(_fMarkProb))
+        ).mul(_fMarginRate).div(_fS3);
+        // + B = max(0,k * (px - sm)) / s3
+        {
+            int128 fPnL = _fTradeAmount.mul(_fMarkProb.sub(_fTradeProb));
+            if (fPnL < 0) {
+                v = v.sub(fPnL.div(_fS3)); // pnl < 0 -> increase v
+            }
+        }
+        // - C = - min(bal0, cash0) = - Equity
+        {
+            int128 equity = _fCash0CC < _fBalance0 ? _fCash0CC : _fBalance0;
+            v = v.sub(equity); // equity can be used / must be covered if negative
+        }
+        return v > 0 ? v : int128(0);
+   */
+
+  const newPos = pos0 + tradeAmnt;
+  const posProb = newPos > 0 ? markProb : 1 - markProb; // R(pm, sign(new pos))
+  const maxLvg = pmMaxLeverage(newPos, markProb, imr);
+  targetLvg = targetLvg > maxLvg ? maxLvg : targetLvg;
+  const posValue = (Math.abs(newPos) * posProb) / S3;
+  const tradeLoss = Math.max(0, tradeAmnt * (prob - markProb)) / S3;
+  const curEquity = Math.min(c0, b0);
+  return Math.max(posValue / targetLvg + tradeLoss - curEquity, 0);
+}
+
+function pmMaxLeverage(posSign: number, markProb: number, minMarginPerCtrct: number) {
+  return Math.round(100 * (posSign > 0 ? markProb / minMarginPerCtrct : (1 - markProb) / minMarginPerCtrct)) / 100;
+}
+
 /**
  * Convert a perpetual price to probability (predtictive markets)
  * @param px Perpetual price
@@ -459,7 +542,7 @@ export function priceToProb(px: number) {
  * @returns Perpetual price
  */
 export function probToPrice(prob: number) {
-  return 1 + prob;
+  return Math.max(1, Math.min(2, 1 + prob));
 }
 
 // shannon entropy
@@ -473,118 +556,58 @@ export function entropy(prob: number) {
 /**
  * Maintenance margin requirement for prediction markets
  * @param pos signed position
+ * @param lockedInQC locked in value
  * @param s2 mark price
  * @param s3 collateral to quote conversion
  * @param m base margin rate
  * @returns required margin balance
  */
-function pmMarginThresh(pos: number, s2: number, s3: number, m: number | undefined = 0.18) {
-  let p = s2 - 1;
-  if (pos < 0) {
-    p = 1 - p;
-  }
-  const h = entropy(p);
-  const tau = m + (0.4 - m) * h;
-  return (Math.abs(pos) * p * tau) / s3;
+function pmMarginThresh(pos: number, lockedInQC: number, s2: number, s3: number, m: number):number {
+  return (pmMaintenanceMarginRate(pos, lockedInQC, s2, m) * Math.abs(pos)) / s3;
 }
 
 /**
  * Maintenance margin rate for prediction markets.
- * @param posSign sign of position in base currency (can be signed position or -1, 1)
+ * @param position signed position in base currency
+ * @param lockedInQC locked in value, p or 1-p times number of contracts
  * @param sm  mark-price (=1+p)
- * @param m   max margin rate from fInitialMarginRate
- * @returns margin rate to be applied (Math.abs(pos) * p * tau) / s3;
- */
-export function pmMaintenanceMarginRate(posSign: number, sm: number, m: number | undefined = 0.18): number {
-  let p = sm - 1;
-  if (posSign < 0) {
-    p = 1 - p;
+ * @param m absolute maintenance buffer per contract (mu_m, fMaintenanceMarginRate)
+ * @returns {number} The margin rate to be applied: (Math.abs(pos) * p * tau) / s3
+ */
+export function pmMaintenanceMarginRate(position: number, lockedInQC: number, sm: number, m: number): number {
+  let pm = sm - 1;
+  let entryP = position == 0 ? pm : Math.abs(lockedInQC / position) - 1;
+  if (position < 0) {
+    pm = 1 - pm;
+    entryP = 1 - entryP;
   }
-  const h = entropy(p);
-  return m + (0.4 - m) * h;
+  const L = Math.max(entryP - pm, 0);
+  const balAtLiq = Math.min(m + L, entryP) * Math.abs(position) + position * sm - lockedInQC;
+  return balAtLiq / (Math.abs(position) * pm);
 }
 
 /**
- * Maintenance margin rate for prediction markets.
+ * 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 m   max margin rate from fMaintenanceMarginRate
- * @returns margin rate to be applied (Math.abs(pos) * p * tau) / s3;
+ * @param cmin Absolute min margin saved as `fInitialMarginRate`
+ * @returns {number} The margin rate to be applied: `(Math.abs(pos) * p * tau) / s3`
  */
-export function pmInitialMarginRate(posSign: number, sm: number, m: number | undefined = 0.2): number {
-  let p = sm - 1;
+export function pmInitialMarginRate(posSign: number, s0: number, sm: number, cmin: number): number {
+  let pm = sm - 1;
+  let p0 = s0 - 1;
   if (posSign < 0) {
-    p = 1 - p;
+    pm = 1 - pm; // R(p_mark, sign(pos))
+    p0 = 1 - p0; // R(p_entry, sign(pos))
   }
-  const h = entropy(p);
-  return m + (0.5 - m) * h;
-}
-
-/**
- * Calculate the expected loss for a prediction market trade used for
- * prediction market fees
- * @param p probability derived from mark price (long)
- * @param m maximal maintenance rate from which we defer the actual maintenance margin rate
- * @param totLong total long in base currency
- * @param totShort total short
- * @param tradeAmt signed trade amount, can be zero
- * @param tradeMgnRate margin rate of the trader
- * @returns expected loss in dollars
- */
-export function expectedLoss(
-  p: number,
-  m: number,
-  totLong: number,
-  totShort: number,
-  tradeAmt: number,
-  tradeMgnRate: number
-): number {
-  // maintenance margin rate
-  m = (0.4 - m) * entropy(p) + m;
-  let dlm = 0;
-  let dl = 0;
-  let dsm = 0;
-  let ds = 0;
-  if (tradeAmt > 0) {
-    dlm = p * tradeAmt * tradeMgnRate;
-    dl = tradeAmt;
-  } else if (tradeAmt < 0) {
-    dsm = (1 - p) * Math.abs(tradeAmt) * tradeMgnRate;
-    ds = Math.abs(tradeAmt);
-  }
-  const a = dl + totLong - m * totShort - dsm;
-  const b = ds + totShort - m * totLong - dlm;
-  return p * (1 - p) * Math.max(0, a + b);
-}
-
-/**
- * Equivalent to
- * const el0 = expectedLoss(prob, m, totLong, totShort, 0, 0);
- * const el1 = expectedLoss(prob, m, totLong, totShort, tradeAmt, tradeMgnRate)
- * const fee = (el1 - el0) / Math.abs(tradeAmt);
- * @param p 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
- */
-function expectedLossImpact(p: number, m: number, tradeAmt: number, tradeMgnRate: number) {
-  m = (0.4 - m) * entropy(p) + m;
-  let dlm = 0;
-  let dl = 0;
-  let dsm = 0;
-  let ds = 0;
-  if (tradeAmt > 0) {
-    dlm = p * tradeAmt * tradeMgnRate;
-    dl = tradeAmt;
-  } else if (tradeAmt < 0) {
-    dsm = (1 - p) * Math.abs(tradeAmt) * tradeMgnRate;
-    ds = Math.abs(tradeAmt);
-  }
-  //long: p * (1 - p) max(0, dl-dlm) = p * (1 - p) max(0, tradeAmt - p * tradeAmt * tradeMgnRate)
-  const a = dl - dsm;
-  const b = ds - dlm;
-  return p * (1 - p) * Math.max(0, a + b);
+  // mu0 = max(Rm/lvg, min(Rm, cmin))
+  // balance  = (mu0 * |k| + k *(sm - s0)) / s3
+  // pos value = |k| * Rm / s3
+  // at max init lvg: Rm/lvg = min(cmin, Rm)
+  // --> margin rate = (mu0 + Rm - R0) / Rm
+  const mu0 = Math.min(pm, cmin) + Math.max(0, p0 - pm);
+  return (mu0 + pm - p0) / pm;
 }
 
 /**
@@ -597,13 +620,12 @@ function expectedLossImpact(p: number, m: number, tradeAmt: number, tradeMgnRate
  * @returns dollar fee relative to tradeAmt
  */
 export function pmExchangeFee(prob: number, m: number, tradeAmt: number, tradeMgnRate: number): number {
-  /*
-  equivalent:
-    const el0 = expectedLoss(prob, m, totLong, totShort, 0, 0);
-    const el1 = expectedLoss(prob, m, totLong, totShort, tradeAmt, tradeMgnRate);
-    const fee = (el1 - el0) / Math.abs(tradeAmt);
-  */
-  let fee = expectedLossImpact(prob, m, tradeAmt, tradeMgnRate) / Math.abs(tradeAmt);
+  // TODO: port contract logic here
+  const [kappa, es] = [0, 0];
+  prob = tradeAmt > 0 ? prob : 1 - prob;
+  let fee = prob * (1 - kappa);
+  const scaledLvg = prob * tradeMgnRate * (1 - fee);
+  fee = fee * (1 - prob) - scaledLvg + es;
   return Math.max(fee, 0.001);
 }
 
@@ -620,45 +642,53 @@ export function pmMarginBalance(pos: number, s2: number, s3: number, ell: number
   return (pos * s2) / s3 - ell / s3 + mc;
 }
 
-export function pmExcessBalance(
-  pos: number,
-  s2: number,
-  s3: number,
-  ell: number,
-  mc: number,
-  m: number | undefined
-): number {
-  return pmMarginBalance(pos, s2, s3, ell, mc) - pmMarginThresh(pos, s2, s3, m);
+export function pmExcessBalance(pos: number, s2: number, s3: number, ell: number, mc: number, m: number): number {
+  return pmMarginBalance(pos, s2, s3, ell, mc) - pmMarginThresh(pos, ell, s2, s3, m);
 }
 
-// finds the liquidation price for prediction markets
-// using Newton's algorithm
+/**
+ *
+ * @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 function pmFindLiquidationPrice(
   pos: number,
   s3: number,
   ell: number,
   mc: number,
-  baseMarginRate: number | undefined,
-  s2Start: number | undefined = 0.5
+  baseMarginRate: number
 ): number {
-  const delta_s = 0.01;
-  let s = 100;
-  let s_new = s2Start;
-
-  while (Math.abs(s_new - s) > 0.01) {
-    s = s_new;
-    const f = Math.pow(pmExcessBalance(pos, s, s3, ell, mc, baseMarginRate), 2);
-    const ds = (Math.pow(pmExcessBalance(pos, s + delta_s, s3, ell, mc, baseMarginRate), 2) - f) / delta_s;
-    s_new = s - f / ds;
-
-    if (s_new < 1) {
-      return 1;
-    }
-    if (s_new > 2) {
-      return 2;
-    }
+  // liq <--> (A) c / |k| < R0  && (B) E < |k| * mu_m
+
+  // if not (A), return 0 (long) or 1 (short) [no liq]
+
+  // else, solve for pm:
+  //  E = c - |k| max(0, s * (p0 - pm)) = |k| * mu_m
+  //  if c/|k| < mu_m:
+  //    any number would do --> return 1 (long) or 0 (short)
+  //  else:
+  //    pm = p0 - s * (c/|k| - mu_m)
+
+  const p0 = Math.abs(ell / pos) - 1;
+  const R0 = pos > 0 ? p0 : 1 - p0;
+  const excessPerCtrct = (mc * s3) / Math.abs(pos) - baseMarginRate; // c/|k| - mu_m, mu_m < CMINUS
+
+  if (mc * s3 > R0 * Math.abs(pos)) {
+    // c > |k| R(p0, s) --> no liquidation
+    return probToPrice(pos > 0 ? 0.0001 : 0.9999);
   }
-  return s;
+
+  if (excessPerCtrct < 0) {
+    // already underwater
+    return probToPrice(pos > 0 ? 0.9999 : 0.0001);
+  }
+
+  return probToPrice(pos > 0 ? p0 - excessPerCtrct : p0 + excessPerCtrct);
 }
 
 /**
@@ -719,19 +749,22 @@ function pmGetDepositAmtForLvgTrade(
   S3: number,
   S2Mark: number
 ): number {
-  const pnl = (tradeAmt * (S2Mark - price)) / S3;
-  let p = S2Mark - 1;
-  if (tradeAmt < 0) {
-    p = 1 - p;
-  }
-  const b = (Math.abs(tradeAmt) * p) / S3 / targetLvg;
-  const amt = -(pnl - b);
-  // check:
-  //bal = amt+pnl
-  //pos_val = (np.abs(trade_amt) * p) / S3
-  //lvg = pos_val/bal
-  //assert(np.abs(lvg-targetLvg)<0.1)
-  return amt;
+  const cmin = 0.05;
+  // refer to main contract function for this:
+  return getDepositAmountForPredMktLvgTrade(0, 0, 0, tradeAmt, targetLvg, price - 1, S3, S2Mark - 1, cmin);
+  // const pnl = (tradeAmt * (S2Mark - price)) / S3;
+  // let p = S2Mark - 1;
+  // if (tradeAmt < 0) {
+  //   p = 1 - p;
+  // }
+  // const b = (Math.abs(tradeAmt) * p) / S3 / targetLvg;
+  // const amt = -(pnl - b);
+  // // check:
+  // //bal = amt+pnl
+  // //pos_val = (np.abs(trade_amt) * p) / S3
+  // //lvg = pos_val/bal
+  // //assert(np.abs(lvg-targetLvg)<0.1)
+  // return amt;
 }
 
 /**
@@ -763,16 +796,21 @@ function pmExcessCashAtLvg(
   Sm: number,
   S3: number
 ): number {
+  const cmin = 0.05;
+  const mu_m = 0.01;
+
+  const maxLvg = pmMaxLeverage(currentPosition + tradeAmt, Sm - 1, cmin);
+  lvg = lvg < maxLvg ? lvg : maxLvg;
   //determine deposit amount for given leverage
   const limitPrice = S2 * (1 + Math.sign(tradeAmt) * slippage);
   const depositFromWallet = pmGetDepositAmtForLvgTrade(tradeAmt, lvg, limitPrice, S3, Sm);
-  const m0 = 0.18;
+
   //leverage fee
   let p0 = Sm - 1;
   if (tradeAmt < 0) {
     p0 = 2 - Sm; //=1-(Sm-1)
   }
-  const feeCc = (Math.abs(tradeAmt) * pmExchangeFee(p0, m0, tradeAmt, 1 / lvg)) / S3;
+  const feeCc = (Math.abs(tradeAmt) * pmExchangeFee(p0, mu_m, tradeAmt, 1 / lvg)) / S3;
 
   //excess cash
   let exc = walletBalCC - depositFromWallet - feeCc;
@@ -782,12 +820,15 @@ function pmExcessCashAtLvg(
   // margin balance
   let pos = currentPosition + tradeAmt;
   let p = Sm - 1;
+  let entryP = limitPrice - 1;
   if (pos < 0) {
-    p = 2 - Sm;
+    p = 1 - Sm;
+    entryP = 1 - entryP;
   }
-  const h = entropy(p);
-  const tau = m0 + (0.5 - m0) * h;
-  const thresh = Math.abs(pos) * p * tau;
+
+  const mu0 = p / lvg + Math.max(0, entryP - p);
+  const thresh = Math.abs(pos) * mu0;
+
   const b0 =
     depositFromWallet +
     currentCashCC +
@@ -947,7 +988,7 @@ export function pmFindMaxPersonalTradeSizeAtLeverage(
  * @param short Short open OI
  * @param sm Mark price (>1)
  * @param isBuy True if trade is long
- * @param mr Maintenance margin rate
+ * @param mr Margin threshold per contract for liquidation (mu_m)
  */
 export function pmMaxSignedOpenTradeSize(
   long: number,
@@ -957,10 +998,12 @@ export function pmMaxSignedOpenTradeSize(
   mr: number,
   ammFundsQC: number
 ) {
-  if (sm < 1) {
+  if (sm <= 1 || sm >= 2) {
+    // closed
     return 0;
   }
-  const m = pmMaintenanceMarginRate(isBuy ? 1 : -1, sm, mr);
+  const counterPos = isBuy ? -short : long;
+  const m = pmMaintenanceMarginRate(counterPos, counterPos * sm, sm, mr);
   let p = !isBuy ? sm - 1 : 2 - sm;
   p = p < 0.01 ? 0.01 : p > 0.99 ? 0.99 : p; // same cap as contract
   return isBuy ? (ammFundsQC + m * p * short) / p - long : -(ammFundsQC + m * p * long) / p + short;

package/src/liquidatorTool.ts

@@ -1,7 +1,7 @@
 import { BigNumberish, JsonRpcProvider, Overrides, Signer, TransactionResponse } from "ethers";
 import { PayableOverrides } from "./contracts/common";
 import { IPyth__factory } from "./contracts/factories";
-import { ABK64x64ToFloat, entropy, floatToABK64x64 } from "./d8XMath";
+import { ABK64x64ToFloat, floatToABK64x64 } from "./d8XMath";
 import type { NodeSDKConfig, PriceFeedSubmission } from "./nodeSDKTypes";
 import WriteAccessHandler from "./writeAccessHandler";
 
@@ -282,8 +282,10 @@ export default class LiquidatorTool extends WriteAccessHandler {
     let threshold: number;
     if (this.isPredictionMarket(symbol)) {
       const idx_markPrice = 8;
+      const idx_lockedInValue = 5;
       const markPrice = ABK64x64ToFloat(traderState[idx_markPrice]);
-      threshold = LiquidatorTool.maintenanceMarginPredMkts(maintMgnRate, pos, coll2quote, markPrice);
+      const ell = ABK64x64ToFloat(traderState[idx_lockedInValue]);
+      threshold = LiquidatorTool.maintenanceMarginPredMkts(maintMgnRate, pos, coll2quote, markPrice, ell);
     } else {
       const base2collateral = indexPrices[0] / coll2quote;
       threshold = Math.abs(pos * base2collateral * maintMgnRate);
@@ -291,14 +293,18 @@ export default class LiquidatorTool extends WriteAccessHandler {
     return marginbalance >= threshold;
   }
 
-  public static maintenanceMarginPredMkts(maintMgnRateBase: number, pos: number, s3: number, markPx: number) {
-    let p = markPx - 1;
-    // p: price = 1+prob
-    if (pos < 0) {
-      p = 1 - p;
-    }
-    const tau = maintMgnRateBase + (0.4 - maintMgnRateBase) * entropy(p);
-    return (Math.abs(pos) * p * tau) / s3;
+  public static maintenanceMarginPredMkts(
+    maintMgnRateBase: number,
+    pos: number,
+    s3: number,
+    markPx: number,
+    ell: number
+  ) {
+    const s = pos > 0 ? 1 : -1; // pos is
+    const R = pos == 0 ? markPx - 1 : s > 0 ? Math.abs(ell / pos) - 1 : 2 - Math.abs(ell / pos);
+    const Rm = s > 0 ? markPx - 1 : 2 - markPx;
+    const L = Math.max(0, s * (R - Rm));
+    return (Math.abs(pos) * Math.min(maintMgnRateBase + L, R)) / s3; // liquidated if E < that
   }
 
   /**