@lifi/perps-sdk 21.1.0 → 23.0.0

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

@@ -41,17 +41,6 @@ export type RequestInterceptor = (
 export interface SDKRequestOptions {
   /** Abort the request and any pending backoff delay. */
   signal?: AbortSignal
-  /**
-   * Lighter auth token consumed by provider-direct venue reads (getOrders,
-   * getOrder, getActivity, getAccount). Create via
-   * `lighterSigner.createAuthToken(deadline, context)`. Sent only to Lighter
-   * venue endpoints, never to the LI.FI backend — read-only by design
-   * (8h max TTL, cannot authorize writes). Each call routes to a single Lighter
-   * instance via `params.provider`, so this token scopes to that instance's
-   * venue; token caches are held per `lighterProvider()` instance and do not
-   * cross between instances.
-   */
-  lighterAuthToken?: string
 }
 
 /**

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.1.0'
+export const version = '23.0.0'

package/src/wire/orderAmounts.ts

@@ -1,12 +1,7 @@
-import {
-  type DecimalString,
-  isDecimalString,
-  type Market,
-  PerpsErrorCode,
-} from '@lifi/perps-types'
+import type { DecimalString, Market } from '@lifi/perps-types'
 import Big from 'big.js'
-import { TruncBig } from '../decimal/big.js'
-import { PerpsError } from '../errors/PerpsError.js'
+import { DivBig, TruncBig } from '../decimal/big.js'
+import { isDecimalString } from '../decimal/parse.js'
 import type { PerpsSDKClient } from '../types/provider.js'
 import { snapOrderSize } from './snap.js'
 
@@ -19,66 +14,22 @@ export interface OrderAmountsInput {
   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.
+   * The held `amount`, byte-identical, when the user holds the margin;
+   * otherwise `notional ÷ leverage`, a display and comparison value that
+   * never reaches a venue.
    */
   margin: DecimalString
-  /** Snapped onto the venue lot grid. */
+  /** Snapped onto the venue lot grid; the one amount an order sends. */
   size: DecimalString
-  /** Truncated to `quoteDecimals`. */
+  /** Exactly `size × price`, from the snapped size. */
   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
@@ -89,47 +40,22 @@ function positiveDecimal(value: DecimalString): Big | null {
 
 /**
  * The three order-entry amounts, derived from whichever one the user typed.
+ * Only `size` snaps, onto the market's venue lot grid, because an order sends
+ * size alone; no quote amount has a grid. A held margin returns byte-identical,
+ * `notional` is the snapped size × price, and a derived margin is
+ * `notional ÷ leverage` in `DivBig` (40 places, half-up).
  *
- * 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.
+ * @returns `null` when `amount` or `price` is not a positive
+ *   {@link DecimalString}, when `leverage` is not a positive finite number, or
+ *   when the snapped size is zero (below one lot).
+ * @throws {PerpsError} `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 { sdk, market, held, leverage } = input
   const amount = positiveDecimal(input.amount)
   const price = positiveDecimal(input.price)
   if (
@@ -140,33 +66,25 @@ export function calculateOrderAmounts(
   ) {
     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),
-    })
+  const requested =
+    held === 'size'
+      ? input.amount
+      : held === 'notional'
+        ? amount.div(price).toFixed()
+        : amount.times(leverage).div(price).toFixed()
+  const size = snapOrderSize(sdk, market, requested)
+  if (new Big(size).eq(0)) {
+    return null
   }
 
-  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 notional = new TruncBig(size).times(price)
+  return {
+    margin:
+      held === 'margin'
+        ? input.amount
+        : new DivBig(notional).div(leverage).toFixed(),
+    size,
+    notional: notional.toFixed(),
   }
-
-  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),
-  })
 }

package/src/wire/refuel.ts

@@ -1,7 +1,7 @@
 import { type DecimalString, PerpsErrorCode } from '@lifi/perps-types'
 import { DivBig } from '../decimal/big.js'
+import { requireDecimal } from '../decimal/requireDecimal.js'
 import { PerpsError } from '../errors/PerpsError.js'
-import { requireDecimal } from './requireDecimal.js'
 
 /** @public */
 export interface RefuelAmountInput {

package/src/wire/transferable.ts

@@ -1,5 +1,5 @@
 import type { DecimalString } from '@lifi/perps-types'
-import { requireDecimal } from './requireDecimal.js'
+import { requireDecimal } from '../decimal/requireDecimal.js'
 
 /**
  * The part of `units` that a venue-wide free figure releases: never below

package/src/wire/withdraw.ts

@@ -1,6 +1,6 @@
 import type { DecimalString } from '@lifi/perps-types'
+import { requireDecimal } from '../decimal/requireDecimal.js'
 import type { WithdrawableBalance } from '../types/withdrawal.js'
-import { requireDecimal } from './requireDecimal.js'
 
 /**
  * Largest `amount` a withdrawable row can fund: `available` when the venue

package/dist/cjs/wire/requireDecimal.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"requireDecimal.d.ts","sourceRoot":"","sources":["../../../src/wire/requireDecimal.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,aAAa,EAGnB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,GAAG,MAAM,QAAQ,CAAA;AAUxB,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG,GAAG,CAQvE"}

package/dist/cjs/wire/requireDecimal.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"requireDecimal.js","sourceRoot":"","sources":["../../../src/wire/requireDecimal.ts"],"names":[],"mappings":";;;;;AAeA,wCAQC;AAvBD,mDAI0B;AAC1B,oDAAwB;AACxB,2DAAoD;AASpD,SAAgB,cAAc,CAAC,KAAoB,EAAE,KAAa;IAChE,IAAI,CAAC,IAAA,6BAAe,EAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,0BAAU,CAClB,4BAAc,CAAC,eAAe,EAC9B,aAAa,KAAK,QAAQ,KAAK,4BAA4B,CAC5D,CAAA;IACH,CAAC;IACD,OAAO,IAAI,gBAAG,CAAC,KAAK,CAAC,CAAA;AACvB,CAAC"}

package/dist/esm/wire/requireDecimal.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"requireDecimal.d.ts","sourceRoot":"","sources":["../../../src/wire/requireDecimal.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,aAAa,EAGnB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,GAAG,MAAM,QAAQ,CAAA;AAGxB;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG,GAAG,CAQvE"}

package/dist/esm/wire/requireDecimal.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"requireDecimal.js","sourceRoot":"","sources":["../../../src/wire/requireDecimal.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,eAAe,EACf,cAAc,GACf,MAAM,mBAAmB,CAAA;AAC1B,OAAO,GAAG,MAAM,QAAQ,CAAA;AACxB,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AAEpD;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,KAAoB,EAAE,KAAa;IAChE,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,UAAU,CAClB,cAAc,CAAC,eAAe,EAC9B,aAAa,KAAK,QAAQ,KAAK,4BAA4B,CAC5D,CAAA;IACH,CAAC;IACD,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,CAAA;AACvB,CAAC"}

package/dist/types/wire/requireDecimal.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"requireDecimal.d.ts","sourceRoot":"","sources":["../../../src/wire/requireDecimal.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,aAAa,EAGnB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,GAAG,MAAM,QAAQ,CAAA;AAGxB;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG,GAAG,CAQvE"}