@lifi/perps-sdk 23.1.0 → 24.0.0

package/dist/esm/math/position.d.ts

@@ -1,181 +1,238 @@
 /**
  * Display-tier position formulas and margin-adjustment predicates. Every
- * formula takes and gives `number`; exact decimal arithmetic happens
- * internally with `DivBig`.
+ * formula takes and gives decimal strings; arithmetic is exact Big.js, with
+ * division to 40 decimal places. Each formula throws `ValidationError` on an
+ * input that is not a decimal string and has a `safe*` pair that gives
+ * `undefined` in place of the throw.
  *
  * Sign convention: long = +1, short = -1. Sizes passed to the `estimate*`
  * helpers are always non-negative magnitudes; direction is carried by
  * `isLong`.
  */
-import { type Position } from '@lifi/perps-types';
+import { type PerpsMarket, type Position } from '@lifi/perps-types';
+import type { LiquidationEstimateParams } from '../types/provider.js';
 /**
- * Calculate notional value of a position.
+ * Notional value of a position: `|size| × price`.
  *
- * @param size - Position size in asset units
- * @param price - Current asset price
- * @returns Notional value in USD
+ * @throws {PerpsError} `ValidationError` when an input is not a decimal string.
  * @public
  */
-export declare function calculateNotionalValue(size: number, price: number): number;
+export declare function calculateNotionalValue(size: string, price: string): string;
+/** @public */
+export declare const safeCalculateNotionalValue: (size: string, price: string) => string | undefined;
 /**
- * Calculate unrealized PnL.
+ * Unrealized PnL: `(currentPrice - entryPrice) × size`, where `size` is
+ * positive for a long and negative for a short.
  *
- * @param entryPrice - Position entry price
- * @param currentPrice - Current market price
- * @param size - Position size (positive for long, negative for short)
- * @returns Unrealized PnL in USD
+ * @throws {PerpsError} `ValidationError` when an input is not a decimal string.
  * @public
  */
-export declare function calculateUnrealizedPnl(entryPrice: number, currentPrice: number, size: number): number;
+export declare function calculateUnrealizedPnl(entryPrice: string, currentPrice: string, size: string): string;
+/** @public */
+export declare const safeCalculateUnrealizedPnl: (entryPrice: string, currentPrice: string, size: string) => string | undefined;
 /**
- * Calculate return on equity (ROE) percentage.
+ * Return on equity as a percentage (`'10'` for 10%): `pnl ÷ margin × 100`.
+ * A zero margin gives `'0'`.
  *
- * @param pnl - Profit/loss in USD
- * @param margin - Initial margin in USD
- * @returns ROE as percentage (e.g., 10 for 10%)
+ * @throws {PerpsError} `ValidationError` when an input is not a decimal string.
  * @public
  */
-export declare function calculateRoe(pnl: number, margin: number): number;
+export declare function calculateRoe(pnl: string, margin: string): string;
+/** @public */
+export declare const safeCalculateRoe: (pnl: string, margin: string) => string | undefined;
 /**
- * Calculate required margin for a position.
+ * Required margin: `notionalValue ÷ leverage`.
  *
- * @param notionalValue - Position notional value in USD
- * @param leverage - Position leverage
- * @returns Required margin in USD
+ * @throws {PerpsError} `ValidationError` when an input is not a decimal string
+ *   or `leverage` is zero.
  * @public
  */
-export declare function calculateRequiredMargin(notionalValue: number, leverage: number): number;
+export declare function calculateRequiredMargin(notionalValue: string, leverage: string): string;
+/** @public */
+export declare const safeCalculateRequiredMargin: (notionalValue: string, leverage: string) => string | undefined;
 /**
- * Distance from the current price to the liquidation price, as a percentage of
- * the current price.
+ * Distance from the current price to the liquidation price, as an absolute
+ * percentage of the current price. A zero current price gives `'0'`.
  *
- * @param liquidationPrice - The position's liquidation price
- * @param currentPrice - Current market price
- * @returns Absolute distance as a percentage, or 0 when current price is zero
+ * @throws {PerpsError} `ValidationError` when an input is not a decimal string.
  * @public
  */
 export declare function calculateLiquidationDistance(params: {
-    liquidationPrice: number;
-    currentPrice: number;
-}): number;
+    liquidationPrice: string;
+    currentPrice: string;
+}): string;
+/** @public */
+export declare const safeCalculateLiquidationDistance: (params: {
+    liquidationPrice: string;
+    currentPrice: string;
+}) => string | undefined;
 /**
- * Effective leverage of an open position.
+ * Effective leverage of an open position: `positionValueUsd ÷ marginUsd`.
+ * A zero margin gives `'0'`.
  *
- * leverage = positionValueUsd / marginUsd
- *
- * @param positionValueUsd - Position notional value in USD
- * @param marginUsd - Margin backing the position in USD
- * @returns Effective leverage, or 0 when margin is zero
+ * @throws {PerpsError} `ValidationError` when an input is not a decimal string.
  * @public
  */
 export declare function calculateEffectiveLeverage(params: {
-    positionValueUsd: number;
-    marginUsd: number;
-}): number;
+    positionValueUsd: string;
+    marginUsd: string;
+}): string;
+/** @public */
+export declare const safeCalculateEffectiveLeverage: (params: {
+    positionValueUsd: string;
+    marginUsd: string;
+}) => string | undefined;
 /**
  * Estimated liquidation price for an isolated-margin position, parameterised
  * by the venue's maintenance margin rate.
  *
  * Standard isolated-margin model (new position, no existing exposure):
- *   margin_per_unit      = entryPrice / leverage
- *   maintenance_per_unit = entryPrice * mmr
- *   margin_available     = margin_per_unit - maintenance_per_unit
- *   liq_price            = entryPrice - side * margin_available / (1 - mmr * side)
+ *   margin_available = entryPrice × (1 / leverage - mmr)
+ *   liq_price        = entryPrice - side × margin_available / (1 - mmr × side)
  *
  * For existing positions, prefer `Position.liquidationPrice` from the venue.
  *
  * @param maintenanceMarginRate - Venue maintenance margin rate as a fraction
- *   (e.g. 0.01 = 1%).
- * @returns Estimated liquidation price, or undefined if the inputs cannot
- *   produce one (zero leverage, degenerate denominator).
+ *   (`'0.01'` = 1%).
+ * @returns The estimate, or `undefined` for a zero leverage or a zero
+ *   denominator.
+ * @throws {PerpsError} `ValidationError` when an input is not a decimal string.
  * @public
  */
 export declare function estimateLiquidationPrice(params: {
-    entryPrice: number;
-    leverage: number;
+    entryPrice: string;
+    leverage: string;
+    isLong: boolean;
+    maintenanceMarginRate: string;
+}): string | undefined;
+/** @public */
+export declare const safeEstimateLiquidationPrice: (params: {
+    entryPrice: string;
+    leverage: string;
     isLong: boolean;
-    maintenanceMarginRate: number;
-}): number | undefined;
+    maintenanceMarginRate: string;
+}) => string | undefined;
+/**
+ * Estimate the liquidation price of a new isolated position from the flat
+ * `market.maintenanceMarginRate`.
+ *
+ * @returns The estimate, or `undefined` when the market carries no
+ *   `maintenanceMarginRate` or `estimateLiquidationPrice` gives `undefined`.
+ * @throws {PerpsError} `ValidationError` when an input is not a decimal string.
+ * @public
+ */
+export declare function estimateLiquidationPriceAtMarketRate(market: PerpsMarket, params: LiquidationEstimateParams): string | undefined;
+/** @public */
+export declare const safeEstimateLiquidationPriceAtMarketRate: (market: PerpsMarket, params: LiquidationEstimateParams) => string | undefined;
 /**
  * Whether an isolated position with this liquidation price is already past
  * liquidation at `currentPrice`: a long liquidates when the price falls to its
  * liquidation level, a short when it rises to it. A non-positive price on
  * either side counts as unknown, so the result is `false`.
  *
+ * @throws {PerpsError} `ValidationError` when a price is not a decimal string.
  * @public
  */
 export declare function wouldImmediatelyLiquidate(params: {
-    liquidationPrice: number;
-    currentPrice: number;
+    liquidationPrice: string;
+    currentPrice: string;
     isLong: boolean;
 }): boolean;
+/** @public */
+export declare const safeWouldImmediatelyLiquidate: (params: {
+    liquidationPrice: string;
+    currentPrice: string;
+    isLong: boolean;
+}) => boolean | undefined;
 /**
- * Estimated average entry price after adding to an existing position.
- *
- * Weighted average of the current entry and the new fill price, weighted by
- * the size of each leg in coin units. Both legs assumed in the same direction
- * (this helper is for adding to, not flipping, a position).
- *
- * @param currentSize - Existing position size in coin units (>= 0).
- * @param currentEntry - Existing position's average entry price.
- * @param addSize - Size being added in coin units (>= 0).
- * @param fillPrice - Price the new size is expected to fill at (mid for
- *   market, limitPrice for limit orders).
- * @returns The new weighted-average entry price, or undefined if the inputs
- *   cannot produce a valid average (zero combined size, non-finite values).
+ * Estimated average entry price after adding to an existing position: the
+ * size-weighted average of the current entry and the fill price. Both legs
+ * are in the same direction (an add, not a flip).
+ *
+ * @param fillPrice - Expected fill price (mid for market, limit price for
+ *   limit orders).
+ * @returns The new average entry price, or `undefined` when the combined size
+ *   is not positive.
+ * @throws {PerpsError} `ValidationError` when an input is not a decimal string.
  * @public
  */
 export declare function estimateAverageEntryPrice(params: {
-    currentSize: number;
-    currentEntry: number;
-    addSize: number;
-    fillPrice: number;
-}): number | undefined;
+    currentSize: string;
+    currentEntry: string;
+    addSize: string;
+    fillPrice: string;
+}): string | undefined;
+/** @public */
+export declare const safeEstimateAverageEntryPrice: (params: {
+    currentSize: string;
+    currentEntry: string;
+    addSize: string;
+    fillPrice: string;
+}) => string | undefined;
 /**
- * Estimated effective leverage after adding margin and notional.
+ * Estimated effective leverage after adding margin and notional:
+ * `(currentNotional + addNotional) ÷ (currentMargin + addMargin)`.
  *
- * leverage = totalNotional / totalMargin. The caller computes notional from
- * size and price (`calculateNotionalValue`) and supplies the additional
- * margin the user is about to put up.
- *
- * @returns The new effective leverage, or undefined if total margin is
- *   non-positive.
+ * @returns The new leverage, or `undefined` when the total margin is not
+ *   positive.
+ * @throws {PerpsError} `ValidationError` when an input is not a decimal string.
  * @public
  */
 export declare function estimateNewLeverage(params: {
-    currentNotional: number;
-    currentMargin: number;
-    addNotional: number;
-    addMargin: number;
-}): number | undefined;
+    currentNotional: string;
+    currentMargin: string;
+    addNotional: string;
+    addMargin: string;
+}): string | undefined;
+/** @public */
+export declare const safeEstimateNewLeverage: (params: {
+    currentNotional: string;
+    currentMargin: string;
+    addNotional: string;
+    addMargin: string;
+}) => string | undefined;
 /**
- * Estimated unrealised PnL at the current mark price.
- *
- * `pnl = (markPrice - entryPrice) * size * (isLong ? 1 : -1)`
+ * Estimated unrealised PnL at the mark price:
+ * `(markPrice - entryPrice) × size × (isLong ? 1 : -1)`.
  *
  * @param size - Position size as a non-negative magnitude.
+ * @throws {PerpsError} `ValidationError` when an input is not a decimal string.
  * @public
  */
 export declare function estimateUnrealizedPnl(params: {
-    entryPrice: number;
-    markPrice: number;
-    size: number;
+    entryPrice: string;
+    markPrice: string;
+    size: string;
     isLong: boolean;
-}): number;
+}): string;
+/** @public */
+export declare const safeEstimateUnrealizedPnl: (params: {
+    entryPrice: string;
+    markPrice: string;
+    size: string;
+    isLong: boolean;
+}) => string | undefined;
 /**
- * Realised PnL on the portion of a position being closed.
- *
- * `rPnl = (closePrice - entryPrice) * closeSize * (isLong ? 1 : -1)`
+ * Realised PnL on the portion of a position being closed:
+ * `(closePrice - entryPrice) × closeSize × (isLong ? 1 : -1)`.
  *
  * @param closeSize - Size being closed as a non-negative magnitude.
+ * @throws {PerpsError} `ValidationError` when an input is not a decimal string.
  * @public
  */
 export declare function calculateRealizedPnl(params: {
-    entryPrice: number;
-    closePrice: number;
-    closeSize: number;
+    entryPrice: string;
+    closePrice: string;
+    closeSize: string;
+    isLong: boolean;
+}): string;
+/** @public */
+export declare const safeCalculateRealizedPnl: (params: {
+    entryPrice: string;
+    closePrice: string;
+    closeSize: string;
     isLong: boolean;
-}): number;
+}) => string | undefined;
 /**
  * Whether this position can take a margin adjustment at all: it holds margin of
  * its own and its market exposes individual position margin.

package/dist/esm/math/position.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"position.d.ts","sourceRoot":"","sources":["../../../src/math/position.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAEL,KAAK,QAAQ,EAEd,MAAM,mBAAmB,CAAA;AAG1B;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAK1E;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,GACX,MAAM,CAKR;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAQhE;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,GACf,MAAM,CAQR;AAED;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE;IACnD,gBAAgB,EAAE,MAAM,CAAA;IACxB,YAAY,EAAE,MAAM,CAAA;CACrB,GAAG,MAAM,CAMT;AAED;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE;IACjD,gBAAgB,EAAE,MAAM,CAAA;IACxB,SAAS,EAAE,MAAM,CAAA;CAClB,GAAG,MAAM,CAST;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE;IAC/C,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,OAAO,CAAA;IACf,qBAAqB,EAAE,MAAM,CAAA;CAC9B,GAAG,MAAM,GAAG,SAAS,CAqBrB;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE;IAChD,gBAAgB,EAAE,MAAM,CAAA;IACxB,YAAY,EAAE,MAAM,CAAA;IACpB,MAAM,EAAE,OAAO,CAAA;CAChB,GAAG,OAAO,CAQV;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE;IAChD,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,CAAA;IACpB,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;CAClB,GAAG,MAAM,GAAG,SAAS,CAiBrB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAC1C,eAAe,EAAE,MAAM,CAAA;IACvB,aAAa,EAAE,MAAM,CAAA;IACrB,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;CAClB,GAAG,MAAM,GAAG,SAAS,CAarB;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE;IAC5C,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,OAAO,CAAA;CAChB,GAAG,MAAM,CAUT;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE;IAC3C,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,OAAO,CAAA;CAChB,GAAG,MAAM,CAUT;AAED;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAK5E;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAMzE"}
+{"version":3,"file":"position.d.ts","sourceRoot":"","sources":["../../../src/math/position.ts"],"names":[],"mappings":"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"}