@lifi/perps-sdk 18.1.0 → 20.0.0

package/src/utils/calculations.ts

@@ -16,7 +16,9 @@ import {
   type QuoteSide,
   type TradeType,
 } from '@lifi/perps-types'
+import type Big from 'big.js'
 import { PerpsError } from '../errors/PerpsError.js'
+import { areFinite, DivBig } from './decimal.js'
 
 /**
  * Calculate position size in asset units from margin.
@@ -36,7 +38,13 @@ export function calculatePositionSize(
   leverage: number,
   price: number
 ): number {
-  return (marginUsd * leverage) / price
+  if (price === 0) {
+    return (marginUsd * leverage) / price
+  }
+  if (!areFinite(marginUsd, leverage, price)) {
+    return Number.NaN
+  }
+  return new DivBig(marginUsd).times(leverage).div(price).toNumber()
 }
 
 /**
@@ -48,7 +56,10 @@ export function calculatePositionSize(
  * @public
  */
 export function calculateNotionalValue(size: number, price: number): number {
-  return Math.abs(size) * price
+  if (!areFinite(size, price)) {
+    return Number.NaN
+  }
+  return new DivBig(size).abs().times(price).toNumber()
 }
 
 /**
@@ -65,7 +76,10 @@ export function calculateUnrealizedPnl(
   currentPrice: number,
   size: number
 ): number {
-  return (currentPrice - entryPrice) * size
+  if (!areFinite(entryPrice, currentPrice, size)) {
+    return Number.NaN
+  }
+  return new DivBig(currentPrice).minus(entryPrice).times(size).toNumber()
 }
 
 /**
@@ -80,7 +94,10 @@ export function calculateRoe(pnl: number, margin: number): number {
   if (margin === 0) {
     return 0
   }
-  return (pnl / margin) * 100
+  if (!areFinite(pnl, margin)) {
+    return Number.NaN
+  }
+  return new DivBig(pnl).div(margin).times(100).toNumber()
 }
 
 /**
@@ -95,7 +112,13 @@ export function calculateRequiredMargin(
   notionalValue: number,
   leverage: number
 ): number {
-  return notionalValue / leverage
+  if (leverage === 0) {
+    return notionalValue / leverage
+  }
+  if (!areFinite(notionalValue, leverage)) {
+    return Number.NaN
+  }
+  return new DivBig(notionalValue).div(leverage).toNumber()
 }
 
 /**
@@ -107,7 +130,10 @@ export function calculateRequiredMargin(
  * @public
  */
 export function estimateFees(sizeUsd: number, feeRate: number): number {
-  return sizeUsd * feeRate
+  if (!areFinite(sizeUsd, feeRate)) {
+    return Number.NaN
+  }
+  return new DivBig(sizeUsd).times(feeRate).toNumber()
 }
 
 /**
@@ -124,8 +150,17 @@ export function applySlippage(
   slippagePercent: number,
   isBuy: boolean
 ): number {
-  const multiplier = 1 + slippagePercent / 100
-  return isBuy ? price * multiplier : price / multiplier
+  if (!areFinite(price, slippagePercent)) {
+    return Number.NaN
+  }
+  const multiplier = new DivBig(slippagePercent).div(100).plus(1)
+  if (isBuy) {
+    return new DivBig(price).times(multiplier).toNumber()
+  }
+  if (multiplier.eq(0)) {
+    return price / multiplier.toNumber()
+  }
+  return new DivBig(price).div(multiplier).toNumber()
 }
 
 /**
@@ -166,7 +201,10 @@ export function effectiveLeverage(params: {
   if (marginUsd === 0) {
     return 0
   }
-  return positionValueUsd / marginUsd
+  if (!areFinite(positionValueUsd, marginUsd)) {
+    return Number.NaN
+  }
+  return new DivBig(positionValueUsd).div(marginUsd).toNumber()
 }
 
 /**
@@ -202,12 +240,15 @@ export function calculateExpectedPnl(
   if (!triggerPrice || entryPrice === 0 || margin === 0) {
     return null
   }
+  if (!areFinite(triggerPrice, entryPrice, leverage, margin)) {
+    return { amount: Number.NaN, percent: Number.NaN }
+  }
   const priceDiff = isLong
-    ? triggerPrice - entryPrice
-    : entryPrice - triggerPrice
-  const percent = (priceDiff / entryPrice) * leverage * 100
-  const amount = margin * (percent / 100)
-  return { amount, percent }
+    ? new DivBig(triggerPrice).minus(entryPrice)
+    : new DivBig(entryPrice).minus(triggerPrice)
+  const percent = priceDiff.div(entryPrice).times(leverage).times(100)
+  const amount = percent.times(margin).div(100)
+  return { amount: amount.toNumber(), percent: percent.toNumber() }
 }
 
 /**
@@ -228,8 +269,14 @@ export function priceFromPercent(
   if (entryPrice === 0 || leverage === 0) {
     return 0
   }
-  const priceDelta = (percent / 100 / leverage) * entryPrice
-  return isLong ? entryPrice + priceDelta : entryPrice - priceDelta
+  if (!areFinite(percent, entryPrice, leverage)) {
+    return Number.NaN
+  }
+  const priceDelta = new DivBig(percent)
+    .times(entryPrice)
+    .div(new DivBig(leverage).times(100))
+  const entry = new DivBig(entryPrice)
+  return (isLong ? entry.plus(priceDelta) : entry.minus(priceDelta)).toNumber()
 }
 
 /**
@@ -250,8 +297,13 @@ export function percentFromPrice(
   if (entryPrice === 0 || leverage === 0) {
     return 0
   }
-  const priceDiff = isLong ? price - entryPrice : entryPrice - price
-  return (priceDiff / entryPrice) * leverage * 100
+  if (!areFinite(price, entryPrice, leverage)) {
+    return Number.NaN
+  }
+  const priceDiff = isLong
+    ? new DivBig(price).minus(entryPrice)
+    : new DivBig(entryPrice).minus(price)
+  return priceDiff.div(entryPrice).times(leverage).times(100).toNumber()
 }
 
 /**
@@ -268,11 +320,14 @@ export function calculateRealizedPnlPercent(
   size: number,
   price: number
 ): number {
-  const positionValue = Math.abs(size) * price
-  if (positionValue === 0) {
+  if (!areFinite(realizedPnl, size, price)) {
+    return Number.NaN
+  }
+  const positionValue = new DivBig(size).abs().times(price)
+  if (positionValue.eq(0)) {
     return 0
   }
-  return (realizedPnl / positionValue) * 100
+  return new DivBig(realizedPnl).div(positionValue).times(100).toNumber()
 }
 
 /** Result of {@link walkOrderbook} — the fill obtained for a USD-notional walk. */
@@ -283,7 +338,7 @@ interface BookWalk {
   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. */
+  /** True when the levels could not absorb the requested notional, and for a non-finite notional. */
   insufficientLiquidity: boolean
 }
 
@@ -293,7 +348,8 @@ 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.
+ * returning the best obtainable fill. A non-finite `sizeUsd` gives NaN fill
+ * fields with `insufficientLiquidity` set.
  *
  * @throws {PerpsError} `ValidationError` when a level's `price` or `size`
  *   does not parse to a finite number.
@@ -303,32 +359,47 @@ export function walkOrderbook(
   levels: OrderbookLevel[],
   sizeUsd: number
 ): BookWalk {
-  let remaining = sizeUsd
-  let baseSize = 0
-  let filledNotional = 0
+  if (!Number.isFinite(sizeUsd)) {
+    return {
+      baseSize: Number.NaN,
+      filledNotional: Number.NaN,
+      vwap: Number.NaN,
+      insufficientLiquidity: true,
+    }
+  }
+  let remaining = new DivBig(sizeUsd)
+  let baseSize = new DivBig(0)
+  let filledNotional = new DivBig(0)
   for (const level of levels) {
-    if (remaining <= 0) {
+    if (remaining.lte(0)) {
       break
     }
-    const price = Number.parseFloat(level.price)
-    const size = Number.parseFloat(level.size)
-    if (!Number.isFinite(price) || !Number.isFinite(size)) {
-      throw new PerpsError(
-        PerpsErrorCode.ValidationError,
-        `Malformed orderbook level: price='${level.price}', size='${level.size}'`
-      )
+    const { price, size } = parseLevel(level)
+    const levelNotional = size.times(price)
+    const take = remaining.lt(levelNotional) ? remaining : levelNotional
+    if (take.eq(0)) {
+      continue
     }
-    const levelNotional = size * price
-    const take = Math.min(remaining, levelNotional)
-    filledNotional += take
-    baseSize += take / price
-    remaining -= take
+    filledNotional = filledNotional.plus(take)
+    baseSize = baseSize.plus(take.div(price))
+    remaining = remaining.minus(take)
   }
   return {
-    baseSize,
-    filledNotional,
-    vwap: baseSize === 0 ? 0 : filledNotional / baseSize,
-    insufficientLiquidity: remaining > 0,
+    baseSize: baseSize.toNumber(),
+    filledNotional: filledNotional.toNumber(),
+    vwap: baseSize.eq(0) ? 0 : filledNotional.div(baseSize).toNumber(),
+    insufficientLiquidity: remaining.gt(0),
+  }
+}
+
+function parseLevel(level: OrderbookLevel): { price: Big; size: Big } {
+  try {
+    return { price: new DivBig(level.price), size: new DivBig(level.size) }
+  } catch {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `Malformed orderbook level: price='${level.price}', size='${level.size}'`
+    )
   }
 }
 

package/src/utils/decimal.ts

@@ -0,0 +1,13 @@
+import Big from 'big.js'
+
+/**
+ * Scoped big.js constructor with 40 decimal places for division, so the
+ * shared global `Big.DP` and `Big.RM` stay untouched.
+ */
+export const DivBig = Big()
+DivBig.DP = 40
+
+/** True when every value is a finite number, so `new DivBig(value)` cannot throw. */
+export function areFinite(...values: number[]): boolean {
+  return values.every(Number.isFinite)
+}

package/src/utils/math.ts

@@ -0,0 +1,7 @@
+import type Big from 'big.js'
+
+/** The larger of two Big values, as `Math.max` for numbers. */
+export const maxOf = (a: Big, b: Big): Big => (a.gt(b) ? a : b)
+
+/** The smaller of two Big values, as `Math.min` for numbers. */
+export const minOf = (a: Big, b: Big): Big => (a.lt(b) ? a : b)

package/src/utils/parse.ts

@@ -27,3 +27,28 @@ export function stringToFloat(value: string): number {
   }
   return parseFloat(cleaned)
 }
+
+const FORMATTED_NUMBER =
+  /^(?:[+-]\s*)?(?:\$\s*)?(?:(?:\d{1,3}(?:,\d{3})+|\d+)(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?(?:\s*(?:%|USD))?$/i
+
+/**
+ * Parse an optional decimal field, with the same formatting tolerance as {@link stringToFloat}.
+ * Gives back `undefined` for a missing, malformed or non-finite value, and `0` for an empty string.
+ *
+ * @public
+ */
+export function parseDecimal(
+  value: string | null | undefined
+): number | undefined {
+  if (value == null) {
+    return undefined
+  }
+  if (value.trim() === '') {
+    return stringToFloat(value)
+  }
+  if (!FORMATTED_NUMBER.test(value.trim())) {
+    return undefined
+  }
+  const parsed = stringToFloat(value)
+  return Number.isFinite(parsed) ? parsed : undefined
+}

package/src/utils/positionMath.ts

@@ -6,6 +6,8 @@
  * always non-negative magnitudes; direction is carried by `isLong`.
  */
 
+import { areFinite, DivBig } from './decimal.js'
+
 /**
  * Direction sign for a position.
  *
@@ -50,8 +52,39 @@ export function estimateIsolatedLiquidationPrice(params: {
   if (denominator === 0) {
     return undefined
   }
-  const marginAvailable = entryPrice * (1 / leverage - maintenanceMarginRate)
-  return entryPrice - (side * marginAvailable) / denominator
+  if (!areFinite(entryPrice, leverage, maintenanceMarginRate)) {
+    return Number.NaN
+  }
+  const mmr = new DivBig(maintenanceMarginRate)
+  const marginAvailable = new DivBig(1)
+    .div(leverage)
+    .minus(mmr)
+    .times(entryPrice)
+  return new DivBig(entryPrice)
+    .minus(marginAvailable.times(side).div(mmr.times(-side).plus(1)))
+    .toNumber()
+}
+
+/**
+ * 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`.
+ *
+ * @public
+ */
+export function wouldImmediatelyLiquidate(params: {
+  liquidationPrice: number
+  currentPrice: number
+  isLong: boolean
+}): boolean {
+  const { liquidationPrice, currentPrice, isLong } = params
+  if (currentPrice <= 0 || liquidationPrice <= 0) {
+    return false
+  }
+  return isLong
+    ? liquidationPrice >= currentPrice
+    : liquidationPrice <= currentPrice
 }
 
 /**
@@ -84,7 +117,14 @@ export function predictAverageEntryPrice(params: {
   if (!Number.isFinite(currentEntry) || !Number.isFinite(fillPrice)) {
     return undefined
   }
-  return (currentSize * currentEntry + addSize * fillPrice) / totalSize
+  if (!areFinite(currentSize, addSize)) {
+    return Number.NaN
+  }
+  return new DivBig(currentSize)
+    .times(currentEntry)
+    .plus(new DivBig(addSize).times(fillPrice))
+    .div(new DivBig(currentSize).plus(addSize))
+    .toNumber()
 }
 
 /**
@@ -109,7 +149,13 @@ export function predictNewLeverage(params: {
   if (totalMargin <= 0) {
     return undefined
   }
-  return (currentNotional + addNotional) / totalMargin
+  if (!areFinite(currentNotional, currentMargin, addNotional, addMargin)) {
+    return Number.NaN
+  }
+  return new DivBig(currentNotional)
+    .plus(addNotional)
+    .div(new DivBig(currentMargin).plus(addMargin))
+    .toNumber()
 }
 
 /**
@@ -127,7 +173,14 @@ export function predictUnrealizedPnl(params: {
   isLong: boolean
 }): number {
   const { entryPrice, markPrice, size, isLong } = params
-  return (markPrice - entryPrice) * size * directionSign(isLong)
+  if (!areFinite(entryPrice, markPrice, size)) {
+    return Number.NaN
+  }
+  return new DivBig(markPrice)
+    .minus(entryPrice)
+    .times(size)
+    .times(directionSign(isLong))
+    .toNumber()
 }
 
 /**
@@ -145,5 +198,12 @@ export function realizedPnlOnClose(params: {
   isLong: boolean
 }): number {
   const { entryPrice, closePrice, closeSize, isLong } = params
-  return (closePrice - entryPrice) * closeSize * directionSign(isLong)
+  if (!areFinite(entryPrice, closePrice, closeSize)) {
+    return Number.NaN
+  }
+  return new DivBig(closePrice)
+    .minus(entryPrice)
+    .times(closeSize)
+    .times(directionSign(isLong))
+    .toNumber()
 }

package/src/utils/setupActions.ts

@@ -1,14 +1,14 @@
-import type { ProviderAction } from '@lifi/perps-types'
+import type { ActionType, SetupAction, SetupOption } from '@lifi/perps-types'
 import { PerpsSigner } from '@lifi/perps-types'
 
 /**
- * Select the `Provider.setup` descriptors a user is responsible for satisfying:
- * those whose `signers` include {@link PerpsSigner.USER}. Descriptors the SDK
- * signs on its own (no `USER` signer) are held back — `checkSetup` completes
- * them inline, so surfacing them would render inert cards the user can't act on.
+ * Select the `Provider.setup` descriptors a user sees: every choice step, and
+ * every non-choice step signed by {@link PerpsSigner.USER}. A non-choice step
+ * the SDK signs on its own is held back — `checkSetup` completes it inline, so
+ * surfacing it would render an inert card the user can't act on.
  *
- * Membership is a property of the descriptor's `signers` alone, independent of
- * any account. When an account is available, prefer `ProviderSetup.checklist`
+ * Membership is a property of the descriptor alone, independent of any
+ * account. When an account is available, prefer `ProviderSetup.checklist`
  * from `checkSetup` for the onboarding list — it applies this filter, omits
  * not-required conditional steps, and carries each entry's satisfied state.
  * This function remains the static, account-free projection.
@@ -16,10 +16,24 @@ import { PerpsSigner } from '@lifi/perps-types'
  * @param setup The provider's `setup` descriptors, in their declared order.
  * @public
  */
-export function selectUserSetupActions(
-  setup: ProviderAction[]
-): ProviderAction[] {
-  return setup.filter((descriptor) =>
-    descriptor.signers.includes(PerpsSigner.USER)
-  )
+export function selectUserSetupActions(setup: SetupAction[]): SetupAction[] {
+  return setup.filter(isUserFacingSetupStep)
+}
+
+/** Whether a setup step is shown to the user rather than drained silently. */
+export function isUserFacingSetupStep(descriptor: SetupAction): boolean {
+  return descriptor.options !== null || descriptor.signer === PerpsSigner.USER
+}
+
+/**
+ * Narrow a setup option to the action it executes, so its bound `params` read
+ * with that action's param shape.
+ *
+ * @public
+ */
+export function isSetupOptionFor<T extends ActionType>(
+  option: SetupOption,
+  type: T
+): option is SetupOption<T> {
+  return option.type === type
 }

package/src/utils/switchChain.ts

@@ -35,7 +35,7 @@ export function userEip712TargetChainId(
 ): number | undefined {
   if (
     descriptor.signingMethod !== SigningMethod.EIP712 ||
-    !descriptor.signers.includes(PerpsSigner.USER)
+    descriptor.signer !== PerpsSigner.USER
   ) {
     return undefined
   }

package/src/version.ts

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

package/src/websocket/PerpsWsClient.ts

@@ -20,13 +20,6 @@ export interface WsProviderFactoryParams {
   provider: string
   /** WS URL discovered from `/providers`. */
   wsUrl: string
-  /**
-   * Markets visible to this provider via `/providers`, optionally filtered
-   * by the consumer's `createPerpsClient({ providers: { [key]: { markets } } })`
-   * config. Each provider interprets these its own way — Hyperliquid uses
-   * them to decide which sub-DEXes to subscribe to; Lighter ignores them.
-   */
-  markets: string[]
   /**
    * The SDK client. WS providers use it to call core services (e.g.
    * `getAssets` to source the wire-id ↔ display-symbol map) without
@@ -235,21 +228,9 @@ export class PerpsWsClient {
       throw new Error(`No WebSocket URL found for provider: ${provider}`)
     }
 
-    const allMarkets = (providerInfo.categories ?? []) as Array<{
-      id: string
-    }>
-    const providerConfig = this.client.config.providers?.[provider]
-    const configuredMarkets = providerConfig?.markets
-    const markets = (
-      configuredMarkets
-        ? allMarkets.filter((m) => configuredMarkets.includes(m.id))
-        : allMarkets
-    ).map((m) => m.id)
-
     const wsProvider = factory({
       provider,
       wsUrl: providerInfo.wsUrl,
-      markets,
       client: this.client,
     })
     this.providers.set(provider, wsProvider)