@lifi/perps-sdk 20.1.0 → 21.0.0

package/src/{utils/positionMath.ts → math/position.ts}

@@ -1,24 +1,151 @@
 /**
- * Pure-function helpers for predicting how a perp position changes after a
- * fill.
+ * Display-tier position formulas. Every function takes and gives `number`;
+ * exact decimal arithmetic happens internally with `DivBig`.
  *
- * Sign convention: long = +1, short = -1. Sizes passed to these helpers are
- * always non-negative magnitudes; direction is carried by `isLong`.
+ * Sign convention: long = +1, short = -1. Sizes passed to the `estimate*`
+ * helpers are always non-negative magnitudes; direction is carried by
+ * `isLong`.
  */
 
-import { areFinite, DivBig } from './decimal.js'
+import { areFinite, DivBig } from '../decimal/big.js'
 
 /**
  * Direction sign for a position.
  *
- * @param isLong - True for long positions, false for short.
- * @returns +1 for long, -1 for short.
- * @public
+ * @deprecated Inline `isLong ? 1 : -1`. Removed in the next major.
  */
 export function directionSign(isLong: boolean): 1 | -1 {
   return isLong ? 1 : -1
 }
 
+/**
+ * Calculate notional value of a position.
+ *
+ * @param size - Position size in asset units
+ * @param price - Current asset price
+ * @returns Notional value in USD
+ * @public
+ */
+export function calculateNotionalValue(size: number, price: number): number {
+  if (!areFinite(size, price)) {
+    return Number.NaN
+  }
+  return new DivBig(size).abs().times(price).toNumber()
+}
+
+/**
+ * Calculate unrealized PnL.
+ *
+ * @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
+ * @public
+ */
+export function calculateUnrealizedPnl(
+  entryPrice: number,
+  currentPrice: number,
+  size: number
+): number {
+  if (!areFinite(entryPrice, currentPrice, size)) {
+    return Number.NaN
+  }
+  return new DivBig(currentPrice).minus(entryPrice).times(size).toNumber()
+}
+
+/**
+ * Calculate return on equity (ROE) percentage.
+ *
+ * @param pnl - Profit/loss in USD
+ * @param margin - Initial margin in USD
+ * @returns ROE as percentage (e.g., 10 for 10%)
+ * @public
+ */
+export function calculateRoe(pnl: number, margin: number): number {
+  if (margin === 0) {
+    return 0
+  }
+  if (!areFinite(pnl, margin)) {
+    return Number.NaN
+  }
+  return new DivBig(pnl).div(margin).times(100).toNumber()
+}
+
+/**
+ * Calculate required margin for a position.
+ *
+ * @param notionalValue - Position notional value in USD
+ * @param leverage - Position leverage
+ * @returns Required margin in USD
+ * @public
+ */
+export function calculateRequiredMargin(
+  notionalValue: number,
+  leverage: number
+): number {
+  if (leverage === 0) {
+    return notionalValue / leverage
+  }
+  if (!areFinite(notionalValue, leverage)) {
+    return Number.NaN
+  }
+  return new DivBig(notionalValue).div(leverage).toNumber()
+}
+
+/**
+ * Distance from the current price to the liquidation price, as a percentage of
+ * the current price.
+ *
+ * @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
+ * @public
+ */
+export function calculateLiquidationDistance(params: {
+  liquidationPrice: number
+  currentPrice: number
+}): number {
+  const { liquidationPrice, currentPrice } = params
+  if (currentPrice === 0) {
+    return 0
+  }
+  return Math.abs((liquidationPrice - currentPrice) / currentPrice) * 100
+}
+
+/**
+ * @deprecated Use `calculateLiquidationDistance`. Removed in the next major.
+ */
+export const liquidationDistancePercent = calculateLiquidationDistance
+
+/**
+ * Effective leverage of an open position.
+ *
+ * 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
+ * @public
+ */
+export function calculateEffectiveLeverage(params: {
+  positionValueUsd: number
+  marginUsd: number
+}): number {
+  const { positionValueUsd, marginUsd } = params
+  if (marginUsd === 0) {
+    return 0
+  }
+  if (!areFinite(positionValueUsd, marginUsd)) {
+    return Number.NaN
+  }
+  return new DivBig(positionValueUsd).div(marginUsd).toNumber()
+}
+
+/**
+ * @deprecated Use `calculateEffectiveLeverage`. Removed in the next major.
+ */
+export const effectiveLeverage = calculateEffectiveLeverage
+
 /**
  * Estimated liquidation price for an isolated-margin position, parameterised
  * by the venue's maintenance margin rate.
@@ -37,7 +164,7 @@ export function directionSign(isLong: boolean): 1 | -1 {
  *   produce one (zero leverage, degenerate denominator).
  * @public
  */
-export function estimateIsolatedLiquidationPrice(params: {
+export function estimateLiquidationPrice(params: {
   entryPrice: number
   leverage: number
   isLong: boolean
@@ -47,7 +174,7 @@ export function estimateIsolatedLiquidationPrice(params: {
   if (leverage === 0) {
     return undefined
   }
-  const side = directionSign(isLong)
+  const side = isLong ? 1 : -1
   const denominator = 1 - maintenanceMarginRate * side
   if (denominator === 0) {
     return undefined
@@ -65,6 +192,11 @@ export function estimateIsolatedLiquidationPrice(params: {
     .toNumber()
 }
 
+/**
+ * @deprecated Use `estimateLiquidationPrice`. Removed in the next major.
+ */
+export const estimateIsolatedLiquidationPrice = estimateLiquidationPrice
+
 /**
  * Whether an isolated position with this liquidation price is already past
  * liquidation at `currentPrice`: a long liquidates when the price falls to its
@@ -88,7 +220,7 @@ export function wouldImmediatelyLiquidate(params: {
 }
 
 /**
- * Predicted average entry price after adding to an existing position.
+ * 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
@@ -103,7 +235,7 @@ export function wouldImmediatelyLiquidate(params: {
  *   cannot produce a valid average (zero combined size, non-finite values).
  * @public
  */
-export function predictAverageEntryPrice(params: {
+export function estimateAverageEntryPrice(params: {
   currentSize: number
   currentEntry: number
   addSize: number
@@ -128,7 +260,12 @@ export function predictAverageEntryPrice(params: {
 }
 
 /**
- * Predicted effective leverage after adding margin and notional.
+ * @deprecated Use `estimateAverageEntryPrice`. Removed in the next major.
+ */
+export const predictAverageEntryPrice = estimateAverageEntryPrice
+
+/**
+ * Estimated effective leverage after adding margin and notional.
  *
  * leverage = totalNotional / totalMargin. The caller computes notional from
  * size and price (`calculateNotionalValue`) and supplies the additional
@@ -138,7 +275,7 @@ export function predictAverageEntryPrice(params: {
  *   non-positive.
  * @public
  */
-export function predictNewLeverage(params: {
+export function estimateNewLeverage(params: {
   currentNotional: number
   currentMargin: number
   addNotional: number
@@ -159,14 +296,19 @@ export function predictNewLeverage(params: {
 }
 
 /**
- * Predicted unrealised PnL at the current mark price.
+ * @deprecated Use `estimateNewLeverage`. Removed in the next major.
+ */
+export const predictNewLeverage = estimateNewLeverage
+
+/**
+ * Estimated unrealised PnL at the current mark price.
  *
- * `pnl = (markPrice - entryPrice) * size * directionSign(isLong)`
+ * `pnl = (markPrice - entryPrice) * size * (isLong ? 1 : -1)`
  *
  * @param size - Position size as a non-negative magnitude.
  * @public
  */
-export function predictUnrealizedPnl(params: {
+export function estimateUnrealizedPnl(params: {
   entryPrice: number
   markPrice: number
   size: number
@@ -179,19 +321,24 @@ export function predictUnrealizedPnl(params: {
   return new DivBig(markPrice)
     .minus(entryPrice)
     .times(size)
-    .times(directionSign(isLong))
+    .times(isLong ? 1 : -1)
     .toNumber()
 }
 
+/**
+ * @deprecated Use `estimateUnrealizedPnl`. Removed in the next major.
+ */
+export const predictUnrealizedPnl = estimateUnrealizedPnl
+
 /**
  * Realised PnL on the portion of a position being closed.
  *
- * `rPnl = (closePrice - entryPrice) * closeSize * directionSign(isLong)`
+ * `rPnl = (closePrice - entryPrice) * closeSize * (isLong ? 1 : -1)`
  *
  * @param closeSize - Size being closed as a non-negative magnitude.
  * @public
  */
-export function realizedPnlOnClose(params: {
+export function calculateRealizedPnl(params: {
   entryPrice: number
   closePrice: number
   closeSize: number
@@ -204,6 +351,11 @@ export function realizedPnlOnClose(params: {
   return new DivBig(closePrice)
     .minus(entryPrice)
     .times(closeSize)
-    .times(directionSign(isLong))
+    .times(isLong ? 1 : -1)
     .toNumber()
 }
+
+/**
+ * @deprecated Use `calculateRealizedPnl`. Removed in the next major.
+ */
+export const realizedPnlOnClose = calculateRealizedPnl

package/src/services/resolveQuote.ts

@@ -6,12 +6,12 @@ import {
   type Quote,
 } from '@lifi/perps-types'
 import { PerpsError } from '../errors/PerpsError.js'
+import { buildQuote } from '../math/order.js'
 import type { SDKRequestOptions } from '../types/config.js'
 import type {
   PerpsSDKClient,
   ProviderGetQuoteParams,
 } from '../types/provider.js'
-import { buildQuote } from '../utils/calculations.js'
 import { getMarkets } from './getMarkets.js'
 import { getMarketsContext } from './getMarketsContext.js'
 import { getOrderbook } from './getOrderbook.js'

package/src/services/resolveSubscribeQuote.ts

@@ -3,12 +3,12 @@ import type {
   MarketContext,
   OrderbookResponse,
 } from '@lifi/perps-types'
+import { buildQuote } from '../math/order.js'
 import type {
   PerpsSDKClient,
   ProviderGetQuoteParams,
   QuoteListener,
 } from '../types/provider.js'
-import { buildQuote } from '../utils/calculations.js'
 import type { WsProvider } from '../websocket/types.js'
 import { resolveQuoteMarket, resolveQuotePrice } from './resolveQuote.js'
 

package/src/types/provider.ts

@@ -9,6 +9,7 @@ import type {
   ActivitiesResponse,
   ActivityType,
   AvailableToTrade,
+  DecimalString,
   FillsResponse,
   Market,
   MarketRef,
@@ -534,29 +535,37 @@ export interface PerpsProviderPlugin {
   ): AccountSummary
 
   /**
-   * Format an order price onto the venue's tick grid for `market`. This is
-   * the canonical, provider-correct formatting surface — venue tick rules
-   * differ per provider, so provider-agnostic consumers must route every
-   * order price through the market's own provider instead of applying one
-   * venue's rules to another's markets. Pure — does no I/O.
+   * Snap an order price onto the venue's tick grid for `market`, rounding
+   * half-up. This is the canonical, provider-correct price surface — venue
+   * tick rules differ per provider, so provider-agnostic consumers must route
+   * every order price through the market's own provider instead of applying
+   * one venue's rules to another's markets. Pure — does no I/O.
+   *
+   * Takes and gives a {@link DecimalString}. Never pass a `number`: above 15
+   * significant digits the value has already lost digits by the time it
+   * arrives.
    *
    * @returns The price as a wire-ready decimal string, trailing zeros
    *   stripped.
    * @throws {PerpsError} `ValidationError` when `market` lacks the tick
    *   metadata the venue's rules need (e.g. `Market.priceDecimals` absent).
    */
-  formatOrderPrice(market: Market, price: number): string
+  snapOrderPrice(market: Market, price: DecimalString): DecimalString
 
   /**
-   * Format an order size onto the venue's lot grid for `market`. Truncates
-   * (never rounds up) so the formatted size cannot exceed the user's intended
-   * size or available balance. Pure — does no I/O.
+   * Snap an order size onto the venue's lot grid for `market`, truncating
+   * toward zero (never rounding up) so the snapped size cannot exceed the
+   * user's intended size or available balance. Pure — does no I/O.
+   *
+   * Takes and gives a {@link DecimalString}. Never pass a `number`: above 15
+   * significant digits the value has already lost digits by the time it
+   * arrives.
    *
    * @param size - Size in base-asset units as a non-negative magnitude.
    * @returns The size as a wire-ready decimal string, trailing zeros
    *   stripped.
    */
-  formatOrderSize(market: Market, size: number): string
+  snapOrderSize(market: Market, size: DecimalString): DecimalString
 
   /**
    * Estimate the liquidation price of a new isolated position on `market`
@@ -564,6 +573,10 @@ export interface PerpsProviderPlugin {
    * positions, prefer `Position.liquidationPrice` from the venue. Pure —
    * does no I/O.
    *
+   * Numbers, in and out, on purpose: this is a display-tier estimate that
+   * feeds a screen, not a wire amount. It is not a `snap*` method and must
+   * not be converted to {@link DecimalString}.
+   *
    * @returns The estimated liquidation price, or `undefined` when the venue's
    *   model cannot be evaluated client-side (degenerate inputs, or `market`
    *   lacks the margin metadata the model needs).

package/src/types/withdrawal.ts

@@ -1,4 +1,9 @@
-import type { ActionType, Asset, WithdrawalRoute } from '@lifi/perps-types'
+import type {
+  ActionType,
+  Asset,
+  DecimalString,
+  WithdrawalRoute,
+} from '@lifi/perps-types'
 import type { Address } from 'viem'
 
 export type { WithdrawalRoute }
@@ -14,13 +19,19 @@ export interface ProviderWithdrawableBalance {
   assetId: string
   route: WithdrawalRoute
   /** Withdrawable amount in the asset's own units. Always greater than zero. */
-  available: string
+  available: DecimalString
+  /**
+   * Largest `amount` the row can fund: `available` when the fee is deducted
+   * from the amount or absent; `available − withdrawalFee` floored at zero
+   * when the venue charges the fee on top (`isFeeDeducted === false`).
+   */
+  max: DecimalString
   /**
    * Flat venue fee on a withdrawal from this row, in the asset's own units.
    * Absent when the venue publishes no fee for the asset. The client rejects
    * a value that is not a non-negative decimal.
    */
-  withdrawalFee?: string
+  withdrawalFee?: DecimalString
   /**
    * `true` when the venue takes `withdrawalFee` out of the requested amount,
    * `false` when it charges the fee in addition. Set together with
@@ -40,7 +51,13 @@ export interface WithdrawableBalance {
   asset: Asset
   route: WithdrawalRoute
   /** Withdrawable amount in the asset's own units. */
-  available: string
+  available: DecimalString
+  /**
+   * Largest `amount` the row can fund: `available` when the fee is deducted
+   * from the amount or absent; `available − withdrawalFee` floored at zero
+   * when the venue charges the fee on top (`isFeeDeducted === false`).
+   */
+  max: DecimalString
   /**
    * Flat venue fee on a withdrawal from this row, in the asset's own units.
    * Absent when the venue publishes no fee for the asset. With
@@ -51,7 +68,7 @@ export interface WithdrawableBalance {
    * is zero or negative when the fee is at or above `available`, and the row
    * then funds no withdrawal.
    */
-  withdrawalFee?: string
+  withdrawalFee?: DecimalString
   /**
    * Present only together with `withdrawalFee`. Absent on a row from a
    * provider plugin that does not report it; absence means unknown, not

package/src/utils/orderClassification.ts

@@ -5,20 +5,11 @@ import type {
   TwapOrder,
 } from '@lifi/perps-types'
 import {
-  FillClassification,
   OrderSide,
   OrderStatus,
   OrderType,
   TriggerCondition,
 } from '@lifi/perps-types'
-import { stringToFloat } from './parse.js'
-
-/**
- * Re-exported fill taxonomy used by {@link classifyFillFromPosition}.
- *
- * @public
- */
-export { FillClassification }
 
 const TP_TYPES = new Set<OrderType>([
   OrderType.TAKE_PROFIT_MARKET,
@@ -97,24 +88,3 @@ export const ACTIVE_ORDER_STATUSES: ReadonlySet<OrderStatus> = new Set([
 export function isActiveOrderStatus(status: OrderStatus): boolean {
   return ACTIVE_ORDER_STATUSES.has(status)
 }
-
-/**
- * Classify a fill as open or close based on realizedPnl.
- * @deprecated Use `Fill.classification` instead — it uses startPosition
- * for accurate open/increase/reduce/close/reverse classification.
- * @public
- */
-export function classifyFill(
-  side: OrderSide,
-  realizedPnl: string | null | undefined
-): FillClassification {
-  const isClose = realizedPnl != null && stringToFloat(realizedPnl) !== 0
-  if (side === OrderSide.BUY) {
-    return isClose
-      ? FillClassification.CLOSED_SHORT
-      : FillClassification.OPENED_LONG
-  }
-  return isClose
-    ? FillClassification.CLOSED_LONG
-    : FillClassification.OPENED_SHORT
-}

package/src/version.ts

@@ -10,4 +10,4 @@ export const name = '@lifi/perps-sdk'
  *
  * @public
  */
-export const version = '20.1.0'
+export const version = '21.0.0'

package/src/wire/orderAmounts.ts

@@ -0,0 +1,172 @@
+import {
+  type DecimalString,
+  isDecimalString,
+  type Market,
+  PerpsErrorCode,
+} from '@lifi/perps-types'
+import Big from 'big.js'
+import { TruncBig } from '../decimal/big.js'
+import { PerpsError } from '../errors/PerpsError.js'
+import type { PerpsSDKClient } from '../types/provider.js'
+import { snapOrderSize } from './snap.js'
+
+/** @public */
+export interface OrderAmountsInput {
+  sdk: PerpsSDKClient
+  market: Market
+  /** The field the user typed; the other two are calculated from it. */
+  held: 'margin' | 'size' | 'notional'
+  amount: DecimalString
+  leverage: number
+  price: DecimalString
+  /** Decimals for the quote-asset amounts (margin, notional). Default 2. */
+  quoteDecimals?: number
+}
+
+/** @public */
+export interface OrderAmounts {
+  /**
+   * On the `quoteDecimals` grid: rounded up when derived, so it funds `size`
+   * at the requested leverage, and truncated when the user holds it.
+   */
+  margin: DecimalString
+  /** Snapped onto the venue lot grid. */
+  size: DecimalString
+  /** Truncated to `quoteDecimals`. */
+  notional: DecimalString
+}
+
+const DEFAULT_QUOTE_DECIMALS = 2
+const TEN = new Big(10)
+
+/** Round a quote amount down onto its decimal grid, with no trailing zeros. */
+function quoteAmount(value: Big, decimals: number): DecimalString {
+  const truncated = value.round(decimals, Big.roundDown)
+  return truncated.eq(0) ? '0' : truncated.toFixed()
+}
+
+/**
+ * The smallest margin on the `decimals` grid that funds `notional` at
+ * `leverage`, so `margin × leverage ≥ notional` holds. The one derived amount
+ * that rounds up: a margin rounded down under-funds the size it backs.
+ *
+ * The ceiling is exact: the remainder decides the carry, so the result never
+ * leans on a fixed decimal-place limit the way `div` then `round` would.
+ */
+function coveringMargin(
+  notional: Big,
+  leverage: Big,
+  decimals: number
+): DecimalString {
+  const scale = TEN.pow(decimals)
+  const scaled = notional.times(scale)
+  const remainder = scaled.mod(leverage)
+  const whole = scaled.minus(remainder).div(leverage)
+  const covering = remainder.eq(0) ? whole : whole.plus(1)
+  return covering.eq(0) ? '0' : covering.div(scale).toFixed()
+}
+
+/**
+ * An order needs three positive amounts. A grid that snaps any of them to
+ * zero — a sub-lot size, a sub-cent quote amount — describes no order a venue
+ * can take, so the caller gets `null` instead of a result it has to re-check.
+ */
+function executable(amounts: OrderAmounts): OrderAmounts | null {
+  const positive =
+    new Big(amounts.size).gt(0) &&
+    new Big(amounts.margin).gt(0) &&
+    new Big(amounts.notional).gt(0)
+  return positive ? amounts : null
+}
+
+function positiveDecimal(value: DecimalString): Big | null {
+  if (!isDecimalString(value)) {
+    return null
+  }
+  const parsed = new TruncBig(value)
+  return parsed.gt(0) ? parsed : null
+}
+
+/**
+ * The three order-entry amounts, derived from whichever one the user typed.
+ *
+ * The held field is normalised first — truncated to `quoteDecimals` for a
+ * margin or notional, snapped onto the venue lot grid for a size — and the
+ * other two are then derived from that normalised value, so the three agree
+ * with each other rather than with an input the user cannot see.
+ *
+ * Rounding is directional, so the result always funds itself:
+ * `size × price ≤ margin × leverage`. A derived size truncates onto the lot
+ * grid and a derived notional truncates onto the quote grid, but a derived
+ * margin rounds **up** onto the quote grid, because it is the one amount that
+ * has to cover the others rather than cap them.
+ *
+ * Formulas: `size = margin × leverage ÷ price`,
+ * `margin = size × price ÷ leverage`, `notional = size × price`
+ * (or `margin × leverage` when the margin is held).
+ *
+ * @returns `null` when `amount` or `price` is not a positive decimal string,
+ *   when `leverage` is not a positive finite number, or when the venue and
+ *   quote grids snap the result to a non-positive amount — a sub-lot size or
+ *   a sub-cent quote amount describes no order a venue can take.
+ * @throws {PerpsError} `ValidationError` when `quoteDecimals` is not a
+ *   non-negative integer, or `SDKError` when `market.providerId` names no
+ *   registered provider plugin.
+ * @public
+ */
+export function calculateOrderAmounts(
+  input: OrderAmountsInput
+): OrderAmounts | null {
+  const {
+    sdk,
+    market,
+    held,
+    leverage,
+    quoteDecimals = DEFAULT_QUOTE_DECIMALS,
+  } = input
+  if (!Number.isInteger(quoteDecimals) || quoteDecimals < 0) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `Invalid quoteDecimals for order amounts: ${quoteDecimals}`
+    )
+  }
+  const amount = positiveDecimal(input.amount)
+  const price = positiveDecimal(input.price)
+  if (
+    amount === null ||
+    price === null ||
+    !Number.isFinite(leverage) ||
+    leverage <= 0
+  ) {
+    return null
+  }
+  const leverageFactor = new TruncBig(leverage)
+
+  if (held === 'size') {
+    const size = snapOrderSize(sdk, market, amount.toFixed())
+    const notional = new TruncBig(size).times(price)
+    return executable({
+      margin: coveringMargin(notional, leverageFactor, quoteDecimals),
+      size,
+      notional: quoteAmount(notional, quoteDecimals),
+    })
+  }
+
+  if (held === 'notional') {
+    const notional = quoteAmount(amount, quoteDecimals)
+    const exact = new TruncBig(notional)
+    return executable({
+      margin: coveringMargin(exact, leverageFactor, quoteDecimals),
+      size: snapOrderSize(sdk, market, exact.div(price).toFixed()),
+      notional,
+    })
+  }
+
+  const margin = quoteAmount(amount, quoteDecimals)
+  const notional = new TruncBig(margin).times(leverage)
+  return executable({
+    margin,
+    size: snapOrderSize(sdk, market, notional.div(price).toFixed()),
+    notional: quoteAmount(notional, quoteDecimals),
+  })
+}