@lifi/perps-sdk 21.0.0 → 22.0.0

package/src/index.ts

@@ -17,17 +17,11 @@ export {
 } from './client/createPerpsClient.js'
 export { PerpsClient } from './client/PerpsClient.js'
 export { requireProvider } from './client/requireProvider.js'
-export type {
-  BaseUnitsRounding,
-  ScaleToIntegerPolicy,
-} from './decimal/convert.js'
+export type { BaseUnitsRounding } from './decimal/convert.js'
 export {
   baseUnitsToDecimal,
   decimalToBaseUnits,
-  fromBaseUnits,
-  fromBaseUnitsNumber,
   numberToDecimalString,
-  scaleToInteger,
   truncateDecimal,
 } from './decimal/convert.js'
 export type { FormatOptions, RoundingMode } from './decimal/format.js'
@@ -39,7 +33,7 @@ export {
   formatSignedUsd,
   formatUsd,
 } from './decimal/format.js'
-export { parseDecimal, stringToFloat } from './decimal/parse.js'
+export { isDecimalString, parseDecimal } from './decimal/parse.js'
 export { PerpsErrorMessage } from './errors/constants.js'
 export { PerpsError } from './errors/PerpsError.js'
 export {
@@ -52,18 +46,13 @@ export {
   applySlippage,
   buildQuote,
   calculateExpectedPnl,
-  calculatePositionSize,
   calculateRealizedPnlPercent,
   calculateSize,
   calculateTriggerPercent,
   calculateTriggerPrice,
   estimateFees,
   estimateRealizedPnl,
-  expectedRealizedPnlForOpenOrder,
-  expectedRealizedPnlForTriggerOrder,
   findMatchingPosition,
-  percentFromPrice,
-  priceFromPercent,
   resolveCloseSize,
   walkOrderbook,
 } from './math/order.js'
@@ -75,18 +64,12 @@ export {
   calculateRequiredMargin,
   calculateRoe,
   calculateUnrealizedPnl,
-  directionSign,
-  effectiveLeverage,
   estimateAverageEntryPrice,
-  estimateIsolatedLiquidationPrice,
   estimateLiquidationPrice,
   estimateNewLeverage,
   estimateUnrealizedPnl,
-  liquidationDistancePercent,
-  predictAverageEntryPrice,
-  predictNewLeverage,
-  predictUnrealizedPnl,
-  realizedPnlOnClose,
+  positionSupportsMarginAdjustment,
+  positionSupportsMarginRemoval,
   wouldImmediatelyLiquidate,
 } from './math/position.js'
 // Registries

package/src/math/fills.ts

@@ -1,4 +1,8 @@
-import { FillClassification, OrderSide } from '@lifi/perps-types'
+import {
+  type DecimalString,
+  FillClassification,
+  OrderSide,
+} from '@lifi/perps-types'
 import { parseDecimal } from '../decimal/parse.js'
 
 /**
@@ -19,9 +23,9 @@ export { FillClassification }
  * @public
  */
 export function classifyFillFromPosition(
-  startPosition: string,
+  startPosition: DecimalString,
   side: string,
-  sz: string
+  sz: DecimalString
 ): FillClassification {
   const start = parseFloat(startPosition)
   const delta = side === 'B' ? parseFloat(sz) : -parseFloat(sz)
@@ -66,7 +70,7 @@ export function classifyFillFromPosition(
  */
 export function classifyFill(
   side: OrderSide,
-  realizedPnl: string | null | undefined
+  realizedPnl: DecimalString | null | undefined
 ): FillClassification {
   const isClose = realizedPnl != null && parseDecimal(realizedPnl) !== 0
   if (side === OrderSide.BUY) {

package/src/math/order.ts

@@ -22,6 +22,7 @@ import {
 } from '@lifi/perps-types'
 import type Big from 'big.js'
 import { areFinite, DivBig } from '../decimal/big.js'
+import { numberToDecimalString } from '../decimal/convert.js'
 import { PerpsError } from '../errors/PerpsError.js'
 import {
   isActiveOrderStatus,
@@ -57,11 +58,6 @@ export function calculateSize(
   return new DivBig(marginUsd).times(leverage).div(price).toNumber()
 }
 
-/**
- * @deprecated Use `calculateSize`. Removed in the next major.
- */
-export const calculatePositionSize = calculateSize
-
 /**
  * Estimate trading fees.
  *
@@ -176,11 +172,6 @@ export function calculateTriggerPrice(
   return (isLong ? entry.plus(priceDelta) : entry.minus(priceDelta)).toNumber()
 }
 
-/**
- * @deprecated Use `calculateTriggerPrice`. Removed in the next major.
- */
-export const priceFromPercent = calculateTriggerPrice
-
 /**
  * Calculate the percentage gain/loss a trigger price realises.
  *
@@ -208,11 +199,6 @@ export function calculateTriggerPercent(
   return priceDiff.div(entryPrice).times(leverage).times(100).toNumber()
 }
 
-/**
- * @deprecated Use `calculateTriggerPercent`. Removed in the next major.
- */
-export const percentFromPrice = calculateTriggerPercent
-
 /**
  * Calculate realized PnL as a percentage of position value at close.
  *
@@ -334,7 +320,8 @@ interface BuildQuoteInput {
  * 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}.
+ *   a finite number — see {@link walkOrderbook} — or when a quoted figure is
+ *   not finite (a non-finite `sizeUsd`, mark price or taker fee).
  * @public
  */
 export function buildQuote(input: BuildQuoteInput): Quote {
@@ -356,14 +343,14 @@ export function buildQuote(input: BuildQuoteInput): Quote {
     marketId: market.id,
     type: input.type,
     side,
-    sizeUsd: sizeUsd.toString(),
-    baseSize: walk.baseSize.toString(),
+    sizeUsd: numberToDecimalString(sizeUsd),
+    baseSize: numberToDecimalString(walk.baseSize),
     markPrice: price.markPrice,
-    expectedFillPrice: walk.vwap.toString(),
-    priceImpactBps: priceImpactBps.toString(),
+    expectedFillPrice: numberToDecimalString(walk.vwap),
+    priceImpactBps: numberToDecimalString(priceImpactBps),
     feeTier,
     isDefaultFeeTier: true,
-    feeUsd: feeUsd.toString(),
+    feeUsd: numberToDecimalString(feeUsd),
     funding: price.funding ?? null,
     insufficientLiquidity: walk.insufficientLiquidity,
     timestamp: input.timestamp,
@@ -530,13 +517,3 @@ export function estimateRealizedPnl(
   }
   return null
 }
-
-/**
- * @deprecated Use `estimateRealizedPnl`. Removed in the next major.
- */
-export const expectedRealizedPnlForOpenOrder = regularOrderRealizedPnl
-
-/**
- * @deprecated Use `estimateRealizedPnl`. Removed in the next major.
- */
-export const expectedRealizedPnlForTriggerOrder = triggerOrderRealizedPnl

package/src/math/position.ts

@@ -1,23 +1,20 @@
 /**
- * Display-tier position formulas. Every function takes and gives `number`;
- * exact decimal arithmetic happens internally with `DivBig`.
+ * Display-tier position formulas and margin-adjustment predicates. Every
+ * formula takes and gives `number`; exact decimal arithmetic happens
+ * internally with `DivBig`.
  *
  * Sign convention: long = +1, short = -1. Sizes passed to the `estimate*`
  * helpers are always non-negative magnitudes; direction is carried by
  * `isLong`.
  */
 
+import {
+  MarginMode,
+  type Position,
+  PositionMarginAdjustment,
+} from '@lifi/perps-types'
 import { areFinite, DivBig } from '../decimal/big.js'
 
-/**
- * Direction sign for a position.
- *
- * @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.
  *
@@ -112,11 +109,6 @@ export function calculateLiquidationDistance(params: {
   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.
  *
@@ -141,11 +133,6 @@ export function calculateEffectiveLeverage(params: {
   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.
@@ -192,11 +179,6 @@ export function estimateLiquidationPrice(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
@@ -259,11 +241,6 @@ export function estimateAverageEntryPrice(params: {
     .toNumber()
 }
 
-/**
- * @deprecated Use `estimateAverageEntryPrice`. Removed in the next major.
- */
-export const predictAverageEntryPrice = estimateAverageEntryPrice
-
 /**
  * Estimated effective leverage after adding margin and notional.
  *
@@ -295,11 +272,6 @@ export function estimateNewLeverage(params: {
     .toNumber()
 }
 
-/**
- * @deprecated Use `estimateNewLeverage`. Removed in the next major.
- */
-export const predictNewLeverage = estimateNewLeverage
-
 /**
  * Estimated unrealised PnL at the current mark price.
  *
@@ -325,11 +297,6 @@ export function estimateUnrealizedPnl(params: {
     .toNumber()
 }
 
-/**
- * @deprecated Use `estimateUnrealizedPnl`. Removed in the next major.
- */
-export const predictUnrealizedPnl = estimateUnrealizedPnl
-
 /**
  * Realised PnL on the portion of a position being closed.
  *
@@ -356,6 +323,28 @@ export function calculateRealizedPnl(params: {
 }
 
 /**
- * @deprecated Use `calculateRealizedPnl`. Removed in the next major.
+ * Whether this position can take a margin adjustment at all: it holds margin of
+ * its own and its market exposes individual position margin.
+ *
+ * @public
+ */
+export function positionSupportsMarginAdjustment(position: Position): boolean {
+  return (
+    position.marginMode === MarginMode.ISOLATED &&
+    position.market.positionMarginAdjustment !== PositionMarginAdjustment.NONE
+  )
+}
+
+/**
+ * Whether a removal is among the adjustments this position permits. An
+ * `ADD_ONLY` market takes adds and no withdrawal.
+ *
+ * @public
  */
-export const realizedPnlOnClose = calculateRealizedPnl
+export function positionSupportsMarginRemoval(position: Position): boolean {
+  return (
+    positionSupportsMarginAdjustment(position) &&
+    position.market.positionMarginAdjustment ===
+      PositionMarginAdjustment.ADD_AND_REMOVE
+  )
+}

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/resolveSubscribeQuote.ts

@@ -1,8 +1,10 @@
-import type {
-  FeeTier,
-  MarketContext,
-  OrderbookResponse,
+import {
+  type FeeTier,
+  type MarketContext,
+  type OrderbookResponse,
+  PerpsErrorCode,
 } from '@lifi/perps-types'
+import { PerpsError } from '../errors/PerpsError.js'
 import { buildQuote } from '../math/order.js'
 import type {
   PerpsSDKClient,
@@ -10,6 +12,7 @@ import type {
   QuoteListener,
 } from '../types/provider.js'
 import type { WsProvider } from '../websocket/types.js'
+import { wsLog } from '../websocket/wsLog.js'
 import { resolveQuoteMarket, resolveQuotePrice } from './resolveQuote.js'
 
 /**
@@ -37,6 +40,11 @@ export const QUOTE_THROTTLE_MS = 100
  * listeners once and cancels any pending trailing emission, so the wire
  * subscriptions' ref counts cannot be double-decremented.
  *
+ * A throw while building or delivering a streamed quote (an unparsable mark
+ * price, a throwing `onQuote`) is logged via `wsLog.listenerFailure` and the
+ * emission is skipped, on both the immediate and the trailing-timer path.
+ *
+ * @throws {PerpsError} `ValidationError` when `params.size` is not finite.
  * @throws {PerpsError} `MarketNotFound` when no market matches symbol+type.
  * @internal
  */
@@ -48,6 +56,12 @@ export async function resolveSubscribeQuote(
   feeTier: FeeTier,
   onQuote: QuoteListener
 ): Promise<() => void> {
+  if (!Number.isFinite(params.size)) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `Quote size must be a finite number, got ${params.size}`
+    )
+  }
   const market = await resolveQuoteMarket(client, provider, params)
   // REST snapshot seeds the context; the marketContext subscription below
   // keeps it live so streamed impact/funding track the moving market.
@@ -66,21 +80,25 @@ export async function resolveSubscribeQuote(
       return
     }
     lastEmitAt = Date.now()
-    onQuote(
-      buildQuote({
-        provider,
-        symbol: params.symbol,
-        type: params.type,
-        side: params.side,
-        sizeUsd: params.size,
-        market,
-        price: latestContext,
-        bids: latestBook.bids,
-        asks: latestBook.asks,
-        feeTier,
-        timestamp: Date.now(),
-      })
-    )
+    try {
+      onQuote(
+        buildQuote({
+          provider,
+          symbol: params.symbol,
+          type: params.type,
+          side: params.side,
+          sizeUsd: params.size,
+          market,
+          price: latestContext,
+          bids: latestBook.bids,
+          asks: latestBook.asks,
+          feeTier,
+          timestamp: Date.now(),
+        })
+      )
+    } catch (error) {
+      wsLog.listenerFailure(provider, 'quote', error)
+    }
   }
 
   const unsubscribeContext = await ws.subscribe(

package/src/types/api.ts

@@ -6,6 +6,7 @@ import type {
   ActionParamsMap,
   PlaceTwapOrderParams as ActionPlaceTwapOrderParams,
   ActionStep,
+  DecimalString,
   ExecuteActionResponse,
   MarginMode,
   MarketRef,
@@ -137,9 +138,9 @@ export interface PlaceOrderParams {
   side: OrderSide
   type: Exclude<OrderType, OrderType.TWAP>
   /** Base-asset size as a decimal wire string. */
-  size: string
+  size: DecimalString
   /** Limit price as a decimal wire string; required by limit-style orders. */
-  price: string
+  price: DecimalString
   /** Optional leverage multiplier; provider defaults apply when omitted. */
   leverage?: number
   /**
@@ -223,7 +224,7 @@ export interface SendAssetActionParams {
   /** Destination DEX/account identifier understood by the provider. */
   destinationDex: string
   /** Transfer amount as a provider-compatible decimal wire string. */
-  amount: string
+  amount: DecimalString
 }
 
 /**

package/src/types/provider.ts

@@ -597,7 +597,7 @@ export interface PerpsProviderPlugin {
    * @throws {PerpsError} `ValidationError` when a `Position` decimal that the
    *   venue formula reads is malformed.
    */
-  positionRemovableMargin(position: Position): string | undefined
+  positionRemovableMargin(position: Position): DecimalString | undefined
 
   /**
    * Project a typed {@link AccountConfig} against the provider's `setup`

package/src/version.ts

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