@lifi/perps-sdk 23.1.0 → 25.0.0

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

@@ -1,41 +1,47 @@
 /**
- * Display-tier order formulas. Every function takes and gives `number`;
- * exact decimal arithmetic happens internally with `DivBig`.
+ * Display-tier order formulas. Every function takes and gives decimal
+ * strings; arithmetic is exact Big.js, with division to 40 decimal places.
+ * Each formula throws `ValidationError` on an input that does not match the
+ * decimal pattern and has a `safe*` pair that gives `undefined` in place of the throw.
  */
 import { type FeeTier, type Market, type MarketContext, type Order, type OrderbookLevel, type Position, type Quote, type QuoteSide, type TradeType } from '@lifi/perps-types';
 /**
- * Calculate position size in asset units from margin.
+ * Position size in asset units from margin: `marginUsd × leverage ÷ price`.
  *
- * @param marginUsd - Margin amount in USD
- * @param leverage - Position leverage
- * @param price - Current asset price
- * @returns Position size in asset units
  * @example
  * ```ts
- * calculateSize(100, 10, 2000) // 0.5 (ETH at $2000)
+ * calculateSize('100', '10', '2000') // '0.5' (ETH at $2000)
  * ```
+ * @throws {PerpsError} `ValidationError` when an input does not match the decimal pattern
+ *   or `price` is zero.
  * @public
  */
-export declare function calculateSize(marginUsd: number, leverage: number, price: number): number;
+export declare function calculateSize(marginUsd: string, leverage: string, price: string): string;
+/** @public */
+export declare const safeCalculateSize: (marginUsd: string, leverage: string, price: string) => string | undefined;
 /**
- * Estimate trading fees.
+ * Estimated trading fee in USD: `sizeUsd × feeRate`.
  *
- * @param sizeUsd - Position size in USD (notional value)
- * @param feeRate - Fee rate as decimal (e.g., 0.00035 for 0.035%)
- * @returns Estimated fee in USD
+ * @param feeRate - Fee rate as a fraction (`'0.00035'` for 0.035%).
+ * @throws {PerpsError} `ValidationError` when an input does not match the decimal pattern.
  * @public
  */
-export declare function estimateFees(sizeUsd: number, feeRate: number): number;
+export declare function estimateFees(sizeUsd: string, feeRate: string): string;
+/** @public */
+export declare const safeEstimateFees: (sizeUsd: string, feeRate: string) => string | undefined;
 /**
- * Apply slippage to a price for order execution.
+ * Apply slippage to an order-entry price with exact decimal math: a buy
+ * multiplies by `1 + slippagePercent / 100`, a sell divides by it. The result
+ * is not rounded; snap it to the market tick before it goes to a venue.
  *
- * @param price - Base price
- * @param slippagePercent - Slippage tolerance as percentage (e.g., 0.5 for 0.5%)
- * @param isBuy - True if buying (price goes up), false if selling (price goes down)
- * @returns Price adjusted for slippage
+ * @param slippagePercent - Slippage tolerance as a percentage (`'0.5'` is 0.5%).
+ * @throws {PerpsError} `ValidationError` when an input does not match the
+ *   decimal pattern, or `slippagePercent` is -100 or less.
  * @public
  */
-export declare function applySlippage(price: number, slippagePercent: number, isBuy: boolean): number;
+export declare function applySlippageToPrice(price: string, slippagePercent: string, isBuy: boolean): string;
+/** @public */
+export declare const safeApplySlippageToPrice: (price: string, slippagePercent: string, isBuy: boolean) => string | undefined;
 /**
  * Signed expected PnL for a trigger price — see {@link calculateExpectedPnl}.
  *
@@ -43,61 +49,63 @@ export declare function applySlippage(price: number, slippagePercent: number, is
  */
 export interface ExpectedPnl {
     /** Signed expected profit/loss in USD. */
-    amount: number;
-    /** Signed expected return as a percentage (10 means 10%). */
-    percent: number;
+    amount: string;
+    /** Signed expected return as a percentage (`'10'` means 10%). */
+    percent: string;
 }
 /**
- * Calculate expected gain/loss for a TP or SL trigger price.
- * Returns signed values — positive means profit, negative means loss.
+ * Expected gain or loss for a TP or SL trigger price. Positive is a profit,
+ * negative a loss.
  *
- * @param triggerPrice - The TP or SL target price
- * @param entryPrice - Position entry / current market price
- * @param leverage - Position leverage multiplier
- * @param isLong - True for long positions, false for short
- * @param margin - Margin amount in USD
+ * @param entryPrice - Position entry or current market price.
+ * @param margin - Margin amount in USD.
+ * @throws {PerpsError} `ValidationError` when an input does not match the
+ *   decimal pattern, or `triggerPrice`, `entryPrice` or `margin` is zero.
  * @public
  */
-export declare function calculateExpectedPnl(triggerPrice: number, entryPrice: number, leverage: number, isLong: boolean, margin: number): ExpectedPnl | null;
+export declare function calculateExpectedPnl(triggerPrice: string, entryPrice: string, leverage: string, isLong: boolean, margin: string): ExpectedPnl;
+/** @public */
+export declare const safeCalculateExpectedPnl: (triggerPrice: string, entryPrice: string, leverage: string, isLong: boolean, margin: string) => ExpectedPnl | undefined;
 /**
- * Calculate the trigger price that realises a percentage gain/loss.
+ * Trigger price that realises a percentage gain or loss.
  *
- * @param percent - Target gain/loss percentage (positive = profitable direction)
- * @param entryPrice - Position entry price
- * @param leverage - Position leverage multiplier
- * @param isLong - True for long positions, false for short
+ * @param percent - Target gain or loss percentage (positive = profitable
+ *   direction).
+ * @throws {PerpsError} `ValidationError` when an input does not match the decimal pattern.
  * @public
  */
-export declare function calculateTriggerPrice(percent: number, entryPrice: number, leverage: number, isLong: boolean): number;
+export declare function calculateTriggerPrice(percent: string, entryPrice: string, leverage: string, isLong: boolean): string;
+/** @public */
+export declare const safeCalculateTriggerPrice: (percent: string, entryPrice: string, leverage: string, isLong: boolean) => string | undefined;
 /**
- * Calculate the percentage gain/loss a trigger price realises.
+ * Percentage gain or loss that a trigger price realises.
  *
- * @param price - Target price
- * @param entryPrice - Position entry price
- * @param leverage - Position leverage multiplier
- * @param isLong - True for long positions, false for short
+ * @throws {PerpsError} `ValidationError` when an input does not match the decimal pattern.
  * @public
  */
-export declare function calculateTriggerPercent(price: number, entryPrice: number, leverage: number, isLong: boolean): number;
+export declare function calculateTriggerPercent(price: string, entryPrice: string, leverage: string, isLong: boolean): string;
+/** @public */
+export declare const safeCalculateTriggerPercent: (price: string, entryPrice: string, leverage: string, isLong: boolean) => string | undefined;
 /**
- * Calculate realized PnL as a percentage of position value at close.
+ * Realized PnL as a percentage of the position value at close:
+ * `realizedPnl ÷ (|size| × price) × 100`.
  *
- * @param realizedPnl - The realized profit/loss in USD
- * @param size - Position size in asset units at close
- * @param price - Price at close
- * @returns PnL as a percentage of position value
+ * @throws {PerpsError} `ValidationError` when an input does not match the
+ *   decimal pattern or `size × price` is zero.
  * @public
  */
-export declare function calculateRealizedPnlPercent(realizedPnl: number, size: number, price: number): number;
+export declare function calculateRealizedPnlPercent(realizedPnl: string, size: string, price: string): string;
+/** @public */
+export declare const safeCalculateRealizedPnlPercent: (realizedPnl: string, size: string, price: string) => string | undefined;
 /** Result of {@link walkOrderbook} — the fill obtained for a USD-notional walk. */
 interface BookWalk {
     /** Base amount filled. */
-    baseSize: number;
+    baseSize: string;
     /** Notional actually filled in USD (equals the requested size unless the book ran dry). */
-    filledNotional: number;
-    /** Volume-weighted average fill price, or 0 when the book is empty. */
-    vwap: number;
-    /** True when the levels could not absorb the requested notional, and for a non-finite notional. */
+    filledNotional: string;
+    /** Volume-weighted average fill price, or `'0'` when the book is empty. */
+    vwap: string;
+    /** True when the levels could not absorb the requested notional. */
     insufficientLiquidity: boolean;
 }
 /**
@@ -106,21 +114,22 @@ interface BookWalk {
  * in array order — the caller passes asks for a buy and bids for a sell, each
  * already ordered best-price-first. When the book cannot absorb the full
  * notional, the walk stops at the last level and flags `insufficientLiquidity`,
- * returning the best obtainable fill. A non-finite `sizeUsd` gives NaN fill
- * fields with `insufficientLiquidity` set.
+ * returning the best obtainable fill.
  *
- * @throws {PerpsError} `ValidationError` when a level's `price` or `size`
- *   does not parse to a finite number.
+ * @throws {PerpsError} `ValidationError` when `sizeUsd` or a level's `price`
+ *   or `size` does not match the decimal pattern.
  * @public
  */
-export declare function walkOrderbook(levels: OrderbookLevel[], sizeUsd: number): BookWalk;
+export declare function walkOrderbook(levels: OrderbookLevel[], sizeUsd: string): BookWalk;
+/** @public */
+export declare const safeWalkOrderbook: (levels: OrderbookLevel[], sizeUsd: string) => BookWalk | undefined;
 /** Inputs to {@link buildQuote} — the resolved market, its live price, its book, and the trade ask. */
 interface BuildQuoteInput {
     provider: string;
     symbol: string;
     type: TradeType;
     side: QuoteSide;
-    sizeUsd: number;
+    sizeUsd: string;
     market: Market;
     price: MarketContext;
     bids: OrderbookLevel[];
@@ -136,12 +145,13 @@ interface BuildQuoteInput {
  * versus mark, applies the base taker fee on the filled notional, and carries
  * the market's `funding` (`null` for spot, which has none).
  *
- * @throws {PerpsError} `ValidationError` when a book level does not parse to
- *   a finite number — see {@link walkOrderbook} — or when a quoted figure is
- *   not finite (a non-finite `sizeUsd`, mark price or taker fee).
+ * @throws {PerpsError} `ValidationError` when `sizeUsd`, the mark price, the
+ *   taker fee or a book level does not match the decimal pattern.
  * @public
  */
 export declare function buildQuote(input: BuildQuoteInput): Quote;
+/** @public */
+export declare const safeBuildQuote: (input: BuildQuoteInput) => Quote | undefined;
 /**
  * Pick the matching open position for an order's market, if any.
  *
@@ -158,9 +168,13 @@ export declare function findMatchingPosition(marketId: string, positions: readon
  *    position can only close what's open.
  *
  * Inputs are non-negative magnitudes.
+ *
+ * @throws {PerpsError} `ValidationError` when an input does not match the decimal pattern.
  * @public
  */
-export declare function resolveCloseSize(orderSize: number, positionSize: number): number;
+export declare function resolveCloseSize(orderSize: string, positionSize: string): string;
+/** @public */
+export declare const safeResolveCloseSize: (orderSize: string, positionSize: string) => string | undefined;
 /**
  * Expected rPnL an unfilled order would realise against a matching position:
  * a resting limit order prices off its limit, an armed trigger off its trigger
@@ -168,9 +182,13 @@ export declare function resolveCloseSize(orderSize: number, positionSize: number
  * nothing.
  *
  * @returns Realised PnL if the order would reduce the position, otherwise
- *   `null`.
+ *   `undefined`.
+ * @throws {PerpsError} `ValidationError` when a price or size on the order or
+ *   the position does not match the decimal pattern.
  * @public
  */
-export declare function estimateRealizedPnl(order: Order, position: Position | undefined): number | null;
+export declare function estimateRealizedPnl(order: Order, position: Position | undefined): string | undefined;
+/** @public */
+export declare const safeEstimateRealizedPnl: (order: Order, position: Position | undefined) => string | undefined;
 export {};
 //# sourceMappingURL=order.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"order.d.ts","sourceRoot":"","sources":["../../../src/math/order.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"order.d.ts","sourceRoot":"","sources":["../../../src/math/order.ts"],"names":[],"mappings":"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"}