@d8x/perpetuals-sdk 2.6.23 → 2.7.0

package/doc/d8x-perpetuals-sdk.md

@@ -144,16 +144,17 @@ on-chain</p></dd>
     * [~calculateLiquidationPriceCollateralQuote(LockedInValueQC, position, cash_cc, maintenance_margin_rate, S3)](#module_d8xMath..calculateLiquidationPriceCollateralQuote) ⇒ <code>number</code>
     * [~getMarginRequiredForLeveragedTrade(targetLeverage, currentPosition, currentLockedInValue, tradeAmount, markPrice, indexPriceS2, indexPriceS3, tradePrice, feeRate)](#module_d8xMath..getMarginRequiredForLeveragedTrade) ⇒ <code>number</code>
     * [~getNewPositionLeverage(tradeAmount, marginCollateral, currentPosition, currentLockedInValue, price, indexPriceS3, markPrice)](#module_d8xMath..getNewPositionLeverage) ⇒
-    * [~getDepositAmountForLvgTrade(pos0, b0, tradeAmnt, targetLvg, price, S3, S2Mark, isPredMkt)](#module_d8xMath..getDepositAmountForLvgTrade) ⇒ <code>number</code>
+    * [~getDepositAmountForLvgTrade(pos0, b0, tradeAmnt, targetLvg, price, S3, S2Mark, cmin)](#module_d8xMath..getDepositAmountForLvgTrade) ⇒ <code>number</code>
+    * [~getDepositAmountForPredMktLvgTrade(pos0, b0, c0, tradeAmnt, targetLvg, prob, S3, markProb, imr)](#module_d8xMath..getDepositAmountForPredMktLvgTrade) ⇒ <code>number</code>
+        * [~newPos](#module_d8xMath..getDepositAmountForPredMktLvgTrade..newPos)
     * [~priceToProb(px)](#module_d8xMath..priceToProb) ⇒
     * [~probToPrice(prob)](#module_d8xMath..probToPrice) ⇒
-    * [~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) ⇒
-    * [~expectedLossImpact(p, m, tradeAmt, tradeMgnRate)](#module_d8xMath..expectedLossImpact) ⇒
+    * [~pmMarginThresh(pos, lockedInQC, s2, s3, m)](#module_d8xMath..pmMarginThresh) ⇒
+    * [~pmMaintenanceMarginRate(position, lockedInQC, sm, m)](#module_d8xMath..pmMaintenanceMarginRate) ⇒ <code>number</code>
+    * [~pmInitialMarginRate(posSign, s0, sm, cmin)](#module_d8xMath..pmInitialMarginRate) ⇒ <code>number</code>
     * [~pmExchangeFee(prob, m, tradeAmt, tradeMgnRate)](#module_d8xMath..pmExchangeFee) ⇒
     * [~pmMarginBalance(pos, s2, s3, ell, mc)](#module_d8xMath..pmMarginBalance) ⇒
+    * [~pmFindLiquidationPrice(pos, s3, ell, mc, baseMarginRate, sm)](#module_d8xMath..pmFindLiquidationPrice) ⇒ <code>number</code>
     * [~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) ⇒
@@ -395,7 +396,7 @@ See calculateLiquidationPriceCollateralQuantoConservative for a more conservativ
 
 <a name="module_d8xMath..getDepositAmountForLvgTrade"></a>
 
-### d8xMath~getDepositAmountForLvgTrade(pos0, b0, tradeAmnt, targetLvg, price, S3, S2Mark, isPredMkt) ⇒ <code>number</code>
+### d8xMath~getDepositAmountForLvgTrade(pos0, b0, tradeAmnt, targetLvg, price, S3, S2Mark, cmin) ⇒ <code>number</code>
 <p>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
@@ -413,8 +414,77 @@ Smart contract equivalent: calcMarginForTargetLeverage(..., _ignorePosBalance =
 | price | <code>number</code> | <p>price to trade amount 'tradeAmnt'</p> |
 | S3 | <code>number</code> | <p>collateral to quote conversion (=S2 if base-collateral, =1 if quote collateral, = index S3 if quanto)</p> |
 | S2Mark | <code>number</code> | <p>mark price</p> |
-| isPredMkt | <code>boolean</code> | <p>true if prediction market</p> |
+| cmin | <code>number</code> | <p>Absolute minimum margin per contract, only for pred markets</p> |
 
+<a name="module_d8xMath..getDepositAmountForPredMktLvgTrade"></a>
+
+### d8xMath~getDepositAmountForPredMktLvgTrade(pos0, b0, c0, tradeAmnt, targetLvg, prob, S3, markProb, imr) ⇒ <code>number</code>
+<p>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</p>
+
+**Kind**: inner method of [<code>d8xMath</code>](#module_d8xMath)  
+**Returns**: <code>number</code> - <p>Amount to be deposited to have the given leverage when trading into position pos before fees</p>  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| pos0 | <code>number</code> | <p>current position</p> |
+| b0 | <code>number</code> | <p>current balance</p> |
+| c0 | <code>number</code> | <p>current available cash</p> |
+| tradeAmnt | <code>number</code> | <p>amount to trade</p> |
+| targetLvg | <code>number</code> | <p>target leverage</p> |
+| prob | <code>number</code> | <p>prob to trade amount 'tradeAmnt'</p> |
+| S3 | <code>number</code> | <p>collateral to quote conversion (=S2 if base-collateral, =1 if quote collateral, = index S3 if quanto)</p> |
+| markProb | <code>number</code> | <p>mark prob</p> |
+| imr | <code>number</code> | <p>minimum absolute margin per contract (fInitialMarginRate)</p> |
+
+<a name="module_d8xMath..getDepositAmountForPredMktLvgTrade..newPos"></a>
+
+#### getDepositAmountForPredMktLvgTrade~newPos
+<p>Smart contract implementation:
+// find smallest x such that:
+//      bal * s3 &gt;= 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 &gt;= 0
+//      cash * s3 &gt;= |pos| * min(cmin, prob(sign(pos)))
+//      k * (sm - px) &lt;= 0 a.s.
+//      (positive pnl does not contribute, i.e. ignore px better than mark)
+// solution:
+//  bal0 * s3 + x * s3 &gt;= pos value / lvg + (k * (px - sm))<em>+ = v * s3
+// --&gt;
+//  x &gt;= v + (cash0 - bal0)</em>+ - cash0 = v - min(bal0, cash0)
+//     = pos value / lvg/ s3 + (k * (px - sm))_+ / s3  - min (bal0, cash0)
+//     = A + B - C
+//  x &gt;= |pos| *  min(cmin, prob(sign(pos))) / s3 - cash0
+//  x &gt;= 0
+// init x = A = pos value / lvg / s3
+int128 fNewPos = _fPosition0.add(_fTradeAmount);
+int128 v = (
+fNewPos &gt; 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 &lt; 0) {
+v = v.sub(fPnL.div(_fS3)); // pnl &lt; 0 -&gt; increase v
+}
+}
+// - C = - min(bal0, cash0) = - Equity
+{
+int128 equity = _fCash0CC &lt; _fBalance0 ? _fCash0CC : _fBalance0;
+v = v.sub(equity); // equity can be used / must be covered if negative
+}
+return v &gt; 0 ? v : int128(0);</p>
+
+**Kind**: inner constant of [<code>getDepositAmountForPredMktLvgTrade</code>](#module_d8xMath..getDepositAmountForPredMktLvgTrade)  
 <a name="module_d8xMath..priceToProb"></a>
 
 ### d8xMath~priceToProb(px) ⇒
@@ -441,82 +511,49 @@ Smart contract equivalent: calcMarginForTargetLeverage(..., _ignorePosBalance =
 
 <a name="module_d8xMath..pmMarginThresh"></a>
 
-### d8xMath~pmMarginThresh(pos, s2, s3, m) ⇒
+### d8xMath~pmMarginThresh(pos, lockedInQC, s2, s3, m) ⇒
 <p>Maintenance margin requirement for prediction markets</p>
 
 **Kind**: inner method of [<code>d8xMath</code>](#module_d8xMath)  
 **Returns**: <p>required margin balance</p>  
 
-| Param | Default | Description |
-| --- | --- | --- |
-| pos |  | <p>signed position</p> |
-| s2 |  | <p>mark price</p> |
-| s3 |  | <p>collateral to quote conversion</p> |
-| m | <code>0.18</code> | <p>base margin rate</p> |
+| Param | Description |
+| --- | --- |
+| pos | <p>signed position</p> |
+| lockedInQC | <p>locked in value</p> |
+| s2 | <p>mark price</p> |
+| s3 | <p>collateral to quote conversion</p> |
+| m | <p>base margin rate</p> |
 
 <a name="module_d8xMath..pmMaintenanceMarginRate"></a>
 
-### d8xMath~pmMaintenanceMarginRate(posSign, sm, m) ⇒
+### d8xMath~pmMaintenanceMarginRate(position, lockedInQC, sm, m) ⇒ <code>number</code>
 <p>Maintenance margin rate for prediction markets.</p>
 
 **Kind**: inner method of [<code>d8xMath</code>](#module_d8xMath)  
-**Returns**: <p>margin rate to be applied (Math.abs(pos) * p * tau) / s3;</p>  
-
-| Param | Default | Description |
-| --- | --- | --- |
-| posSign |  | <p>sign of position in base currency (can be signed position or -1, 1)</p> |
-| sm |  | <p>mark-price (=1+p)</p> |
-| m | <code>0.18</code> | <p>max margin rate from fInitialMarginRate</p> |
-
-<a name="module_d8xMath..pmInitialMarginRate"></a>
-
-### d8xMath~pmInitialMarginRate(posSign, sm, m) ⇒
-<p>Maintenance margin rate for prediction markets.</p>
-
-**Kind**: inner method of [<code>d8xMath</code>](#module_d8xMath)  
-**Returns**: <p>margin rate to be applied (Math.abs(pos) * p * tau) / s3;</p>  
-
-| Param | Default | Description |
-| --- | --- | --- |
-| posSign |  | <p>sign of position in base currency (can be signed position or -1, 1)</p> |
-| sm |  | <p>mark-price (=1+p)</p> |
-| m | <code>0.2</code> | <p>max margin rate from fMaintenanceMarginRate</p> |
-
-<a name="module_d8xMath..expectedLoss"></a>
-
-### 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>  
+**Returns**: <code>number</code> - <p>The margin rate to be applied: (Math.abs(pos) * p * tau) / s3</p>  
 
 | Param | Description |
 | --- | --- |
-| p | <p>probability derived from mark price (long)</p> |
-| m | <p>maximal maintenance rate from which we defer the actual maintenance margin rate</p> |
-| totLong | <p>total long in base currency</p> |
-| totShort | <p>total short</p> |
-| tradeAmt | <p>signed trade amount, can be zero</p> |
-| tradeMgnRate | <p>margin rate of the trader</p> |
+| position | <p>signed position in base currency</p> |
+| lockedInQC | <p>locked in value, p or 1-p times number of contracts</p> |
+| sm | <p>mark-price (=1+p)</p> |
+| m | <p>absolute maintenance buffer per contract (mu_m, fMaintenanceMarginRate)</p> |
 
-<a name="module_d8xMath..expectedLossImpact"></a>
+<a name="module_d8xMath..pmInitialMarginRate"></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>
+### d8xMath~pmInitialMarginRate(posSign, s0, sm, cmin) ⇒ <code>number</code>
+<p>Initial margin rate for prediction markets.</p>
 
 **Kind**: inner method of [<code>d8xMath</code>](#module_d8xMath)  
-**Returns**: <p>dollar fee</p>  
+**Returns**: <code>number</code> - <p>The margin rate to be applied: <code>(Math.abs(pos) * p * tau) / s3</code></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> |
+| posSign | <p>sign of position in base currency (can be signed position or -1, 1)</p> |
+| s0 | <p>trade price</p> |
+| sm | <p>mark-price (=1+p)</p> |
+| cmin | <p>Absolute min margin saved as <code>fInitialMarginRate</code></p> |
 
 <a name="module_d8xMath..pmExchangeFee"></a>
 
@@ -550,6 +587,21 @@ For opening trades only</p>
 | ell | <p>locked in value</p> |
 | mc | <p>margin cash in collateral currency</p> |
 
+<a name="module_d8xMath..pmFindLiquidationPrice"></a>
+
+### d8xMath~pmFindLiquidationPrice(pos, s3, ell, mc, baseMarginRate, sm) ⇒ <code>number</code>
+**Kind**: inner method of [<code>d8xMath</code>](#module_d8xMath)  
+**Returns**: <code>number</code> - <p>Liquidation price as a probability in the range [0, 1]</p>  
+
+| Param | Description |
+| --- | --- |
+| pos | <p>Signed position size</p> |
+| s3 | <p>Collateral to quote conversion at spot</p> |
+| ell | <p>Locked-in value</p> |
+| mc | <p>Margin collateral</p> |
+| baseMarginRate | <p>Maintenance margin per contract (mu_m)</p> |
+| sm | <p>Mark price at entry</p> |
+
 <a name="module_d8xMath..excessMargin"></a>
 
 ### d8xMath~excessMargin(tradeAmt, currentCashCC, currentPos, currentLockedInQC, limitPrice, Sm, S3) ⇒
@@ -649,7 +701,7 @@ Factors in lot size and global max short/long, factors in opening/closing positi
 | short | <p>Short open OI</p> |
 | sm | <p>Mark price (&gt;1)</p> |
 | isBuy | <p>True if trade is long</p> |
-| mr | <p>Maintenance margin rate</p> |
+| mr | <p>Margin threshold per contract for liquidation (mu_m)</p> |
 
 <a name="module_utils"></a>
 

package/package.json

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

package/src/config/defaultConfig.json

@@ -28,8 +28,8 @@
   {
     "name": "base_sepolia",
     "chainId": 84532,
-    "version": 1,
-    "proxyAddr": "0xa7868558E094E58251c6D12f407294c11522E88D",
+    "version": 3,
+    "proxyAddr": "0xfaC638d51B769D060aFC5953C41bF35595620b1c",
     "nodeURL": "https://sepolia.base.org",
     "priceFeedConfigNetwork": "mainnet",
     "shareTokenABILocation": "./abi/ShareToken.json",

package/src/constants.ts

@@ -34,7 +34,6 @@ export const MASK_PREDICTION_MARKET = 2n;
 export const MASK_LOW_LIQUIDITY_MARKET = 4n;
 export const MASK_TRADFI_MARKET = 8n;
 
-
 export const ORDER_TYPE_LIMIT = "LIMIT";
 export const ORDER_TYPE_MARKET = "MARKET";
 export const ORDER_TYPE_STOP_MARKET = "STOP_MARKET";