@d8x/perpetuals-sdk 2.1.12-alpha2 → 2.1.13-alpha2

package/doc/d8x-perpetuals-sdk.md

@@ -149,10 +149,11 @@ on-chain</p></dd>
     * [~pmMarginThresh(pos, s2, s3, m)](#module_d8xMath..pmMarginThresh) ⇒
     * [~pmMaintenanceMarginRate(posSign, sm, m)](#module_d8xMath..pmMaintenanceMarginRate) ⇒
     * [~pmInitialMarginRate(posSign, sm, m)](#module_d8xMath..pmInitialMarginRate) ⇒
-    * [~expectedLoss(p, m, totLong, totShort, tradeAmt, tradeMgnRate)](#module_d8xMath..expectedLoss)
-    * [~pmExchangeFee(prob, m, totShort, totLong, tradeAmt, tradeMgnRate)](#module_d8xMath..pmExchangeFee) ⇒
+    * [~expectedLoss(p, m, totLong, totShort, tradeAmt, tradeMgnRate)](#module_d8xMath..expectedLoss) ⇒
+    * [~expectedLossImpact(p, m, tradeAmt, tradeMgnRate)](#module_d8xMath..expectedLossImpact) ⇒
+    * [~pmExchangeFee(prob, m, tradeAmt, tradeMgnRate)](#module_d8xMath..pmExchangeFee) ⇒
     * [~pmMarginBalance(pos, s2, s3, ell, mc)](#module_d8xMath..pmMarginBalance) ⇒
-    * [~excessMargin(tradeAmt, currentCashCC, currentPos, currentLockedInQC, limitPrice, Sm, S3, totLong, totShort)](#module_d8xMath..excessMargin) ⇒
+    * [~excessMargin(tradeAmt, currentCashCC, currentPos, currentLockedInQC, limitPrice, Sm, S3)](#module_d8xMath..excessMargin) ⇒
     * [~pmGetDepositAmtForLvgTrade(tradeAmt, targetLvg, price, S3, S2Mark)](#module_d8xMath..pmGetDepositAmtForLvgTrade) ⇒
     * [~pmExcessCashAtLvg(tradeAmt, lvg, walletBalCC, currentCashCC, currentPosition, currentLockedInValue, slippage, S2, Sm, S3, totLong, totShort)](#module_d8xMath..pmExcessCashAtLvg) ⇒
     * [~pmFindMaxPersonalTradeSizeAtLeverage(dir, lvg, walletBalCC, slippage, currentPosition, currentCashCC, currentLockedInValue, S2, Sm, S3, totLong, totShort, maxShort, maxLong)](#module_d8xMath..pmFindMaxPersonalTradeSizeAtLeverage) ⇒
@@ -464,11 +465,12 @@ Smart contract equivalent: calcMarginForTargetLeverage(..., _ignorePosBalance =
 
 <a name="module_d8xMath..expectedLoss"></a>
 
-### d8xMath~expectedLoss(p, m, totLong, totShort, tradeAmt, tradeMgnRate)
+### d8xMath~expectedLoss(p, m, totLong, totShort, tradeAmt, tradeMgnRate) ⇒
 <p>Calculate the expected loss for a prediction market trade used for
 prediction market fees</p>
 
 **Kind**: inner method of [<code>d8xMath</code>](#module_d8xMath)  
+**Returns**: <p>expected loss in dollars</p>  
 
 | Param | Description |
 | --- | --- |
@@ -479,21 +481,37 @@ prediction market fees</p>
 | tradeAmt | <p>signed trade amount, can be zero</p> |
 | tradeMgnRate | <p>margin rate of the trader</p> |
 
+<a name="module_d8xMath..expectedLossImpact"></a>
+
+### d8xMath~expectedLossImpact(p, m, tradeAmt, tradeMgnRate) ⇒
+<p>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);</p>
+
+**Kind**: inner method of [<code>d8xMath</code>](#module_d8xMath)  
+**Returns**: <p>dollar fee</p>  
+
+| Param | Description |
+| --- | --- |
+| p | <p>prob long probability</p> |
+| m | <p>max maintenance margin rate (0.18)</p> |
+| tradeAmt | <p>trade amount in base currency</p> |
+| tradeMgnRate | <p>margin rate for this trade</p> |
+
 <a name="module_d8xMath..pmExchangeFee"></a>
 
-### d8xMath~pmExchangeFee(prob, m, totShort, totLong, tradeAmt, tradeMgnRate) ⇒
+### d8xMath~pmExchangeFee(prob, m, tradeAmt, tradeMgnRate) ⇒
 <p>Exchange fee as a rate for prediction markets
 For opening trades only</p>
 
 **Kind**: inner method of [<code>d8xMath</code>](#module_d8xMath)  
-**Returns**: <p>fee relative to tradeAmt</p>  
+**Returns**: <p>dollar fee relative to tradeAmt</p>  
 
 | Param | Description |
 | --- | --- |
 | prob | <p>long probability</p> |
 | m | <p>max maintenance margin rate (0.18)</p> |
-| totShort |  |
-| totLong |  |
 | tradeAmt | <p>trade amount in base currency</p> |
 | tradeMgnRate | <p>margin rate for this trade</p> |
 
@@ -515,7 +533,7 @@ For opening trades only</p>
 
 <a name="module_d8xMath..excessMargin"></a>
 
-### d8xMath~excessMargin(tradeAmt, currentCashCC, currentPos, currentLockedInQC, limitPrice, Sm, S3, totLong, totShort) ⇒
+### d8xMath~excessMargin(tradeAmt, currentCashCC, currentPos, currentLockedInQC, limitPrice, Sm, S3) ⇒
 <p>Calculate the excess margin defined as
 excess := margin balance - trading fee - initial margin threshold
 for the given trade and position</p>
@@ -532,8 +550,6 @@ for the given trade and position</p>
 | limitPrice | 
 | Sm | 
 | S3 | 
-| totLong | 
-| totShort | 
 
 <a name="module_d8xMath..pmGetDepositAmtForLvgTrade"></a>
 
@@ -3773,7 +3789,7 @@ No gas required for the queries here.</p>
         * [.getABI(contract)](#PerpetualDataHandler+getABI) ⇒
         * [.isPredictionMarket(symbol)](#PerpetualDataHandler+isPredictionMarket) ⇒
     * _static_
-        * [.exchangeFeePrdMkts(state, maxMaintMgnRate, Sm, tradeAmtBC, tradeMgnRate)](#MarketData.exchangeFeePrdMkts) ⇒
+        * [.exchangeFeePrdMkts(maxMaintMgnRate, Sm, tradeAmtBC, tradeMgnRate)](#MarketData.exchangeFeePrdMkts) ⇒
 
 <a name="new_MarketData_new"></a>
 
@@ -4942,7 +4958,7 @@ main();
 
 <a name="MarketData.exchangeFeePrdMkts"></a>
 
-### MarketData.exchangeFeePrdMkts(state, maxMaintMgnRate, Sm, tradeAmtBC, tradeMgnRate) ⇒
+### MarketData.exchangeFeePrdMkts(maxMaintMgnRate, Sm, tradeAmtBC, tradeMgnRate) ⇒
 <p>Fee is relative to base-currency amount (=trade amount)</p>
 
 **Kind**: static method of [<code>MarketData</code>](#MarketData)  
@@ -4950,7 +4966,6 @@ main();
 
 | Param | Description |
 | --- | --- |
-| state | <p>current perpetual state (need longBC and shortBC)</p> |
 | maxMaintMgnRate | <p>maintenance margin rate param for pred mkts</p> |
 | Sm | <p>Mark price</p> |
 | tradeAmtBC | <p>signed trade amount</p> |

package/doc/marketData.md

@@ -44,7 +44,7 @@ No gas required for the queries here.</p>
         * [.fetchPricesForPerpetual(symbol)](#MarketData+fetchPricesForPerpetual) ⇒
         * [.fetchPrdMktMetaData(symbol)](#MarketData+fetchPrdMktMetaData) ⇒
     * _static_
-        * [.exchangeFeePrdMkts(state, maxMaintMgnRate, Sm, tradeAmtBC, tradeMgnRate)](#MarketData.exchangeFeePrdMkts) ⇒
+        * [.exchangeFeePrdMkts(maxMaintMgnRate, Sm, tradeAmtBC, tradeMgnRate)](#MarketData.exchangeFeePrdMkts) ⇒
 
 <a name="new_MarketData_new"></a>
 
@@ -810,7 +810,7 @@ main();
 
 <a name="MarketData.exchangeFeePrdMkts"></a>
 
-### MarketData.exchangeFeePrdMkts(state, maxMaintMgnRate, Sm, tradeAmtBC, tradeMgnRate) ⇒
+### MarketData.exchangeFeePrdMkts(maxMaintMgnRate, Sm, tradeAmtBC, tradeMgnRate) ⇒
 <p>Fee is relative to base-currency amount (=trade amount)</p>
 
 **Kind**: static method of [<code>MarketData</code>](#MarketData)  
@@ -818,7 +818,6 @@ main();
 
 | Param | Description |
 | --- | --- |
-| state | <p>current perpetual state (need longBC and shortBC)</p> |
 | maxMaintMgnRate | <p>maintenance margin rate param for pred mkts</p> |
 | Sm | <p>Mark price</p> |
 | tradeAmtBC | <p>signed trade amount</p> |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@d8x/perpetuals-sdk",
-  "version": "2.1.12-alpha2",
+  "version": "2.1.13-alpha2",
   "description": "Node TypeScript SDK for D8X Perpetual Futures",
   "author": "D8X",
   "homepage": "https://github.com/D8-X/d8x-futures-node-sdk#readme",

package/src/d8XMath.ts

@@ -505,6 +505,7 @@ export function pmInitialMarginRate(posSign: number, sm: number, m: number | und
  * @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,
@@ -532,7 +533,18 @@ export function expectedLoss(
   return p * (1 - p) * Math.max(0, a + b);
 }
 
-function newFee(p: number, m: number, tradeAmt: number, tradeMgnRate: number) {
+/**
+ * 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;
@@ -556,26 +568,18 @@ function newFee(p: number, m: number, tradeAmt: number, tradeMgnRate: number) {
  * For opening trades only
  * @param prob long probability
  * @param m max maintenance margin rate (0.18)
- * @param totShort
- * @param totLong
  * @param tradeAmt trade amount in base currency
  * @param tradeMgnRate margin rate for this trade
- * @returns fee relative to tradeAmt
+ * @returns dollar fee relative to tradeAmt
  */
-export function pmExchangeFee(
-  prob: number,
-  m: number,
-  totShort: number,
-  totLong: number,
-  tradeAmt: number,
-  tradeMgnRate: number
-): number {
-  const el0 = expectedLoss(prob, m, totLong, totShort, 0, 0);
-  const el1 = expectedLoss(prob, m, totLong, totShort, tradeAmt, tradeMgnRate);
-  console.log("el0=", el0);
-  console.log("el1=", el1);
-  const fee = (el1 - el0) / Math.abs(tradeAmt);
-  console.log("diff=", el1 - el0);
+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);
   return Math.max(fee, 0.001);
 }
 
@@ -644,8 +648,6 @@ export function pmFindLiquidationPrice(
  * @param limitPrice
  * @param Sm
  * @param S3
- * @param totLong
- * @param totShort
  * @returns excess margin as defined above
  */
 function excessMargin(
@@ -655,9 +657,7 @@ function excessMargin(
   currentLockedInQC: number,
   limitPrice: number,
   Sm: number,
-  S3: number,
-  totLong: number,
-  totShort: number
+  S3: number
 ): number {
   const m = 0.18; //max maintenance margin rate
   const m0 = 0.2; //max initial margin rate
@@ -672,7 +672,7 @@ function excessMargin(
   const b0 = currentCashCC + Math.abs(currentPos) * Sm - currentLockedInQC + Math.max(0, tradeAmt * (Sm - limitPrice));
   // b0 + margin - fee > threshold
   // margin = threshold - b0 + fee
-  const fee_cc = pmExchangeFee(p, m, totShort, totLong, tradeAmt, tau) / S3;
+  const fee_cc = pmExchangeFee(p, m, tradeAmt, tau) / S3;
 
   // missing: referral rebate
   return b0 / S3 - thresh / S3 - fee_cc;
@@ -737,9 +737,7 @@ function pmExcessCashAtLvg(
   slippage: number,
   S2: number,
   Sm: number,
-  S3: number,
-  totLong: number,
-  totShort: number
+  S3: number
 ): number {
   //determine deposit amount for given leverage
   const limitPrice = S2 * (1 + Math.sign(tradeAmt) * slippage);
@@ -750,7 +748,7 @@ function pmExcessCashAtLvg(
   if (tradeAmt < 0) {
     p0 = 2 - Sm; //=1-(Sm-1)
   }
-  const feeCc = pmExchangeFee(p0, m0, totShort, totLong, tradeAmt, 1 / lvg) / S3;
+  const feeCc = pmExchangeFee(p0, m0, tradeAmt, 1 / lvg) / S3;
 
   //excess cash
   let exc = walletBalCC - depositFromWallet - feeCc;
@@ -833,9 +831,7 @@ export function pmFindMaxPersonalTradeSizeAtLeverage(
     slippage,
     S2,
     Sm,
-    S3,
-    totLong,
-    totShort
+    S3
   );
   if (f0 < lot) {
     // no trade possible
@@ -859,9 +855,7 @@ export function pmFindMaxPersonalTradeSizeAtLeverage(
           slippage,
           S2,
           Sm,
-          S3,
-          totLong,
-          totShort
+          S3
         ) ** 2;
       const f2 =
         pmExcessCashAtLvg(
@@ -874,9 +868,7 @@ export function pmFindMaxPersonalTradeSizeAtLeverage(
           slippage,
           S2,
           Sm,
-          S3,
-          totLong,
-          totShort
+          S3
         ) ** 2;
       let ds = (f2 - f) / deltaS;
       if (ds == 0) {
@@ -934,8 +926,6 @@ export function pmFindMaxTradeSize(
   limitPrice: number,
   Sm: number,
   S3: number,
-  totLong: number,
-  totShort: number,
   maxShort: number,
   maxLong: number
 ): number {
@@ -946,17 +936,7 @@ export function pmFindMaxTradeSize(
   }
   const lot = 10;
   const deltaS = 1; //for derivative
-  const f0 = excessMargin(
-    dir * deltaS,
-    currentCashCC,
-    currentPosition,
-    currentLockedInValue,
-    limitPrice,
-    Sm,
-    S3,
-    totLong,
-    totShort
-  );
+  const f0 = excessMargin(dir * deltaS, currentCashCC, currentPosition, currentLockedInValue, limitPrice, Sm, S3);
   if (f0 < lot) {
     // no trade possible
     return 0;
@@ -968,21 +948,9 @@ export function pmFindMaxTradeSize(
     let count = 0;
     while (Math.abs(sNew - s) > 1 && count < 100) {
       s = sNew;
-      const f =
-        excessMargin(s, currentCashCC, currentPosition, currentLockedInValue, limitPrice, Sm, S3, totLong, totShort) **
-        2;
+      const f = excessMargin(s, currentCashCC, currentPosition, currentLockedInValue, limitPrice, Sm, S3) ** 2;
       const f2 =
-        excessMargin(
-          s + deltaS,
-          currentCashCC,
-          currentPosition,
-          currentLockedInValue,
-          limitPrice,
-          Sm,
-          S3,
-          totLong,
-          totShort
-        ) ** 2;
+        excessMargin(s + deltaS, currentCashCC, currentPosition, currentLockedInValue, limitPrice, Sm, S3) ** 2;
       let ds = (f2 - f) / deltaS;
       sNew = s - f / ds;
       count += 1;

package/src/marketData.ts

@@ -804,7 +804,6 @@ export default class MarketData extends PerpetualDataHandler {
 
   /**
    * Fee is relative to base-currency amount (=trade amount)
-   * @param state current perpetual state (need longBC and shortBC)
    * @param maxMaintMgnRate maintenance margin rate param for pred mkts
    * @param Sm Mark price
    * @param tradeAmtBC signed trade amount
@@ -812,7 +811,6 @@ export default class MarketData extends PerpetualDataHandler {
    * @returns relative exchange fee in decimals
    */
   public static exchangeFeePrdMkts(
-    state: PerpetualState,
     maxMaintMgnRate: number,
     Sm: number,
     tradeAmtBC: number,
@@ -826,7 +824,7 @@ export default class MarketData extends PerpetualDataHandler {
       // 0.1cents if is close
       return 0.001;
     }
-    return pmExchangeFee(Sm - 1, maxMaintMgnRate, state.shortBC, state.longBC, tradeAmtBC, tradeMgnRate);
+    return pmExchangeFee(Sm - 1, maxMaintMgnRate, tradeAmtBC, tradeMgnRate);
   }
 
   /**
@@ -1279,8 +1277,6 @@ export default class MarketData extends PerpetualDataHandler {
       Sm,
       Sm,
       indexPriceInfo.s3 ?? 0,
-      totLong,
-      totShort,
       maxShortPosPerp,
       maxLongPosPerp
     );
@@ -1292,8 +1288,6 @@ export default class MarketData extends PerpetualDataHandler {
       Sm,
       Sm,
       indexPriceInfo.s3 ?? 0,
-      totLong,
-      totShort,
       maxShortPosPerp,
       maxLongPosPerp
     );

package/src/version.ts

@@ -1 +1 @@
-export const D8X_SDK_VERSION = "2.1.12-alpha2";
+export const D8X_SDK_VERSION = "2.1.13-alpha2";