@lifi/perps-sdk 20.1.1 → 21.1.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/getActivity.ts

@@ -30,6 +30,10 @@ export interface GetActivityParams {
  *
  * @throws {PerpsError} When the provider plugin is not registered, or on
  *   backend / network / parsing errors.
+ * @throws {PerpsError} `SetupRequired` when the venue needs a credential (a
+ *   Lighter auth token or an Ondo session) and none is stored.
+ * @throws {PerpsError} `Unauthorized` when the venue rejects the credential.
+ * @throws {PerpsError} `AccountNotFound` when the wallet has no venue account.
  * @example
  * ```ts
  * const { items, pagination } = await getActivity(client, {

package/src/services/getFills.ts

@@ -29,6 +29,10 @@ export interface GetFillsParams {
  *
  * @throws {PerpsError} When the provider plugin is not registered, or on
  *   backend / network / parsing errors.
+ * @throws {PerpsError} `SetupRequired` when the venue needs a credential (a
+ *   Lighter auth token or an Ondo session) and none is stored.
+ * @throws {PerpsError} `Unauthorized` when the venue rejects the credential.
+ * @throws {PerpsError} `AccountNotFound` when the wallet has no venue account.
  * @example
  * ```ts
  * const { items, pagination } = await getFills(client, {

package/src/services/getOrder.ts

@@ -23,6 +23,10 @@ export interface GetOrderParams {
  *
  * @throws {PerpsError} When the provider plugin is not registered, or on
  *   backend / network / parsing errors.
+ * @throws {PerpsError} `SetupRequired` when the venue needs a credential (a
+ *   Lighter auth token or an Ondo session) and none is stored.
+ * @throws {PerpsError} `Unauthorized` when the venue rejects the credential.
+ * @throws {PerpsError} `AccountNotFound` when the wallet has no venue account.
  * @example
  * ```ts
  * const order = await getOrder(client, {

package/src/services/getOrders.ts

@@ -22,7 +22,16 @@ export interface GetOrdersParams {
   cursor?: string
 }
 
-/** Read account orders with active lifecycle statuses as the default filter. */
+/**
+ * Read account orders with active lifecycle statuses as the default filter.
+ *
+ * @throws {PerpsError} When the provider plugin is not registered, or on
+ *   backend / network / parsing errors.
+ * @throws {PerpsError} `SetupRequired` when the venue needs a credential (a
+ *   Lighter auth token or an Ondo session) and none is stored.
+ * @throws {PerpsError} `Unauthorized` when the venue rejects the credential.
+ * @throws {PerpsError} `AccountNotFound` when the wallet has no venue account.
+ */
 export async function getOrders(
   client: PerpsSDKClient,
   params: GetOrdersParams,

package/src/services/getPositions.ts

@@ -27,6 +27,10 @@ export interface GetPositionsParams {
  *
  * @throws {PerpsError} When the provider plugin is not registered, or on
  *   backend / network / parsing errors.
+ * @throws {PerpsError} `SetupRequired` when the venue needs a credential (a
+ *   Lighter auth token or an Ondo session) and none is stored.
+ * @throws {PerpsError} `Unauthorized` when the venue rejects the credential.
+ * @throws {PerpsError} `AccountNotFound` when the wallet has no venue account.
  * @example
  * ```ts
  * const { positions } = await getPositions(client, {

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

@@ -20,6 +20,12 @@ export interface ProviderWithdrawableBalance {
   route: WithdrawalRoute
   /** Withdrawable amount in the asset's own units. Always greater than zero. */
   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
@@ -46,6 +52,12 @@ export interface WithdrawableBalance {
   route: WithdrawalRoute
   /** Withdrawable amount in the asset's own units. */
   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

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.1'
+export const version = '21.1.0'