@lifi/perps-sdk 24.0.0 → 25.0.0

package/src/math/position.ts

@@ -2,7 +2,7 @@
  * Display-tier position formulas and margin-adjustment predicates. Every
  * formula takes and gives decimal strings; arithmetic is exact Big.js, with
  * division to 40 decimal places. Each formula throws `ValidationError` on an
- * input that is not a decimal string and has a `safe*` pair that gives
+ * input that does not match the decimal pattern and has a `safe*` pair that gives
  * `undefined` in place of the throw.
  *
  * Sign convention: long = +1, short = -1. Sizes passed to the `estimate*`
@@ -12,26 +12,24 @@
 
 import {
   MarginMode,
-  PerpsErrorCode,
   type PerpsMarket,
   type Position,
   PositionMarginAdjustment,
 } from '@lifi/perps-types'
 import { DivBig } from '../decimal/big.js'
-import { numberToDecimalString } from '../decimal/convert.js'
 import {
   bigToDecimalString,
   decimalStringToBig,
   decimalStringToDivBig,
 } from '../decimal/decimalStringToBig.js'
-import { PerpsError } from '../errors/PerpsError.js'
+import { invalidInput } from '../errors/invalidInput.js'
 import type { LiquidationEstimateParams } from '../types/provider.js'
 import { createSafeFunction } from '../utils/createSafeFunction.js'
 
 /**
  * Notional value of a position: `|size| × price`.
  *
- * @throws {PerpsError} `ValidationError` when an input is not a decimal string.
+ * @throws {PerpsError} `ValidationError` when an input does not match the decimal pattern.
  * @public
  */
 export function calculateNotionalValue(size: string, price: string): string {
@@ -50,7 +48,7 @@ export const safeCalculateNotionalValue = createSafeFunction(
  * Unrealized PnL: `(currentPrice - entryPrice) × size`, where `size` is
  * positive for a long and negative for a short.
  *
- * @throws {PerpsError} `ValidationError` when an input is not a decimal string.
+ * @throws {PerpsError} `ValidationError` when an input does not match the decimal pattern.
  * @public
  */
 export function calculateUnrealizedPnl(
@@ -73,16 +71,16 @@ export const safeCalculateUnrealizedPnl = createSafeFunction(
 
 /**
  * Return on equity as a percentage (`'10'` for 10%): `pnl ÷ margin × 100`.
- * A zero margin gives `'0'`.
  *
- * @throws {PerpsError} `ValidationError` when an input is not a decimal string.
+ * @throws {PerpsError} `ValidationError` when an input does not match the
+ *   decimal pattern or `margin` is zero.
  * @public
  */
 export function calculateRoe(pnl: string, margin: string): string {
   const marginBig = decimalStringToBig(margin)
   const pnlBig = decimalStringToDivBig(pnl)
   if (marginBig.eq(0)) {
-    return '0'
+    throw invalidInput('margin', 'must not be zero')
   }
   return bigToDecimalString(pnlBig.div(marginBig).times(100))
 }
@@ -93,7 +91,7 @@ export const safeCalculateRoe = createSafeFunction('calculateRoe', calculateRoe)
 /**
  * Required margin: `notionalValue ÷ leverage`.
  *
- * @throws {PerpsError} `ValidationError` when an input is not a decimal string
+ * @throws {PerpsError} `ValidationError` when an input does not match the decimal pattern
  *   or `leverage` is zero.
  * @public
  */
@@ -104,10 +102,7 @@ export function calculateRequiredMargin(
   const notionalBig = decimalStringToDivBig(notionalValue)
   const leverageBig = decimalStringToBig(leverage)
   if (leverageBig.eq(0)) {
-    throw new PerpsError(
-      PerpsErrorCode.ValidationError,
-      'Leverage must not be zero.'
-    )
+    throw invalidInput('leverage', 'must not be zero')
   }
   return bigToDecimalString(notionalBig.div(leverageBig))
 }
@@ -120,9 +115,10 @@ export const safeCalculateRequiredMargin = createSafeFunction(
 
 /**
  * Distance from the current price to the liquidation price, as an absolute
- * percentage of the current price. A zero current price gives `'0'`.
+ * percentage of the current price.
  *
- * @throws {PerpsError} `ValidationError` when an input is not a decimal string.
+ * @throws {PerpsError} `ValidationError` when an input does not match the
+ *   decimal pattern or `currentPrice` is zero.
  * @public
  */
 export function calculateLiquidationDistance(params: {
@@ -132,7 +128,7 @@ export function calculateLiquidationDistance(params: {
   const liquidationPrice = decimalStringToDivBig(params.liquidationPrice)
   const currentPrice = decimalStringToBig(params.currentPrice)
   if (currentPrice.eq(0)) {
-    return '0'
+    throw invalidInput('currentPrice', 'must not be zero')
   }
   return bigToDecimalString(
     liquidationPrice.minus(currentPrice).div(currentPrice).abs().times(100)
@@ -147,9 +143,9 @@ export const safeCalculateLiquidationDistance = createSafeFunction(
 
 /**
  * Effective leverage of an open position: `positionValueUsd ÷ marginUsd`.
- * A zero margin gives `'0'`.
  *
- * @throws {PerpsError} `ValidationError` when an input is not a decimal string.
+ * @throws {PerpsError} `ValidationError` when an input does not match the
+ *   decimal pattern or `marginUsd` is zero.
  * @public
  */
 export function calculateEffectiveLeverage(params: {
@@ -159,7 +155,7 @@ export function calculateEffectiveLeverage(params: {
   const positionValue = decimalStringToDivBig(params.positionValueUsd)
   const margin = decimalStringToBig(params.marginUsd)
   if (margin.eq(0)) {
-    return '0'
+    throw invalidInput('marginUsd', 'must not be zero')
   }
   return bigToDecimalString(positionValue.div(margin))
 }
@@ -182,9 +178,9 @@ export const safeCalculateEffectiveLeverage = createSafeFunction(
  *
  * @param maintenanceMarginRate - Venue maintenance margin rate as a fraction
  *   (`'0.01'` = 1%).
- * @returns The estimate, or `undefined` for a zero leverage or a zero
- *   denominator.
- * @throws {PerpsError} `ValidationError` when an input is not a decimal string.
+ * @throws {PerpsError} `ValidationError` when an input does not match the
+ *   decimal pattern, `leverage` is zero, or `maintenanceMarginRate` gives a
+ *   zero denominator (`1` for a long, `-1` for a short).
  * @public
  */
 export function estimateLiquidationPrice(params: {
@@ -192,14 +188,20 @@ export function estimateLiquidationPrice(params: {
   leverage: string
   isLong: boolean
   maintenanceMarginRate: string
-}): string | undefined {
+}): string {
   const entryPrice = decimalStringToBig(params.entryPrice)
   const leverage = decimalStringToBig(params.leverage)
   const mmr = decimalStringToBig(params.maintenanceMarginRate)
   const side = params.isLong ? 1 : -1
   const denominator = mmr.times(-side).plus(1)
-  if (leverage.eq(0) || denominator.eq(0)) {
-    return undefined
+  if (leverage.eq(0)) {
+    throw invalidInput('leverage', 'must not be zero')
+  }
+  if (denominator.eq(0)) {
+    throw invalidInput(
+      'maintenanceMarginRate',
+      `must not be ${params.isLong ? '1' : '-1'} for this side`
+    )
   }
   const marginAvailable = new DivBig(1)
     .div(leverage)
@@ -221,8 +223,9 @@ export const safeEstimateLiquidationPrice = createSafeFunction(
  * `market.maintenanceMarginRate`.
  *
  * @returns The estimate, or `undefined` when the market carries no
- *   `maintenanceMarginRate` or `estimateLiquidationPrice` gives `undefined`.
- * @throws {PerpsError} `ValidationError` when an input is not a decimal string.
+ *   `maintenanceMarginRate`.
+ * @throws {PerpsError} `ValidationError` on an input that
+ *   {@link estimateLiquidationPrice} rejects.
  * @public
  */
 export function estimateLiquidationPriceAtMarketRate(
@@ -236,7 +239,7 @@ export function estimateLiquidationPriceAtMarketRate(
     entryPrice: params.entryPrice,
     leverage: params.leverage,
     isLong: params.isLong,
-    maintenanceMarginRate: numberToDecimalString(market.maintenanceMarginRate),
+    maintenanceMarginRate: market.maintenanceMarginRate,
   })
 }
 
@@ -252,7 +255,7 @@ export const safeEstimateLiquidationPriceAtMarketRate = createSafeFunction(
  * liquidation level, a short when it rises to it. A non-positive price on
  * either side counts as unknown, so the result is `false`.
  *
- * @throws {PerpsError} `ValidationError` when a price is not a decimal string.
+ * @throws {PerpsError} `ValidationError` when a price does not match the decimal pattern.
  * @public
  */
 export function wouldImmediatelyLiquidate(params: {
@@ -283,9 +286,8 @@ export const safeWouldImmediatelyLiquidate = createSafeFunction(
  *
  * @param fillPrice - Expected fill price (mid for market, limit price for
  *   limit orders).
- * @returns The new average entry price, or `undefined` when the combined size
- *   is not positive.
- * @throws {PerpsError} `ValidationError` when an input is not a decimal string.
+ * @throws {PerpsError} `ValidationError` when an input does not match the
+ *   decimal pattern or `currentSize + addSize` is not positive.
  * @public
  */
 export function estimateAverageEntryPrice(params: {
@@ -293,14 +295,14 @@ export function estimateAverageEntryPrice(params: {
   currentEntry: string
   addSize: string
   fillPrice: string
-}): string | undefined {
+}): string {
   const currentSize = decimalStringToDivBig(params.currentSize)
   const addSize = decimalStringToBig(params.addSize)
   const currentEntry = decimalStringToBig(params.currentEntry)
   const fillPrice = decimalStringToBig(params.fillPrice)
   const totalSize = currentSize.plus(addSize)
   if (totalSize.lte(0)) {
-    return undefined
+    throw invalidInput('currentSize + addSize', 'must be positive')
   }
   return bigToDecimalString(
     currentSize
@@ -320,9 +322,8 @@ export const safeEstimateAverageEntryPrice = createSafeFunction(
  * Estimated effective leverage after adding margin and notional:
  * `(currentNotional + addNotional) ÷ (currentMargin + addMargin)`.
  *
- * @returns The new leverage, or `undefined` when the total margin is not
- *   positive.
- * @throws {PerpsError} `ValidationError` when an input is not a decimal string.
+ * @throws {PerpsError} `ValidationError` when an input does not match the
+ *   decimal pattern or `currentMargin + addMargin` is not positive.
  * @public
  */
 export function estimateNewLeverage(params: {
@@ -330,7 +331,7 @@ export function estimateNewLeverage(params: {
   currentMargin: string
   addNotional: string
   addMargin: string
-}): string | undefined {
+}): string {
   const totalNotional = decimalStringToDivBig(params.currentNotional).plus(
     decimalStringToBig(params.addNotional)
   )
@@ -338,7 +339,7 @@ export function estimateNewLeverage(params: {
     decimalStringToBig(params.addMargin)
   )
   if (totalMargin.lte(0)) {
-    return undefined
+    throw invalidInput('currentMargin + addMargin', 'must be positive')
   }
   return bigToDecimalString(totalNotional.div(totalMargin))
 }
@@ -354,7 +355,7 @@ export const safeEstimateNewLeverage = createSafeFunction(
  * `(markPrice - entryPrice) × size × (isLong ? 1 : -1)`.
  *
  * @param size - Position size as a non-negative magnitude.
- * @throws {PerpsError} `ValidationError` when an input is not a decimal string.
+ * @throws {PerpsError} `ValidationError` when an input does not match the decimal pattern.
  * @public
  */
 export function estimateUnrealizedPnl(params: {
@@ -382,7 +383,7 @@ export const safeEstimateUnrealizedPnl = createSafeFunction(
  * `(closePrice - entryPrice) × closeSize × (isLong ? 1 : -1)`.
  *
  * @param closeSize - Size being closed as a non-negative magnitude.
- * @throws {PerpsError} `ValidationError` when an input is not a decimal string.
+ * @throws {PerpsError} `ValidationError` when an input does not match the decimal pattern.
  * @public
  */
 export function calculateRealizedPnl(params: {

package/src/services/resolveSubscribeQuote.ts

@@ -45,7 +45,7 @@ export const QUOTE_THROTTLE_MS = 100
  * 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 a decimal string.
+ * @throws {PerpsError} `ValidationError` when `params.size` does not match the decimal pattern.
  * @throws {PerpsError} `MarketNotFound` when no market matches symbol+type.
  * @internal
  */

package/src/types/provider.ts

@@ -599,9 +599,10 @@ export interface PerpsProviderPlugin {
    * positions, prefer `Position.liquidationPrice` from the venue. Pure —
    * does no I/O.
    *
-   * @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).
+   * @returns The estimated liquidation price, or `undefined` when `market`
+   *   lacks the margin metadata the model needs.
+   * @throws {PerpsError} `ValidationError` when an input does not match the
+   *   decimal pattern or is degenerate, such as a zero leverage.
    */
   estimateLiquidationPrice(
     market: PerpsMarket,

package/src/utils/createSafeFunction.ts

@@ -3,7 +3,7 @@
  * The wrapper logs a warning with `name` and the error, which carries the
  * stack trace.
  *
- * @internal
+ * @public
  */
 export function createSafeFunction<Args extends unknown[], Result>(
   name: string,

package/src/utils/warnOnce.ts

@@ -30,6 +30,19 @@ export const createWarnOnce = (): ((key: string, message: string) => void) => {
 
 const MAX_VALUE_CHARS = 64
 
+/**
+ * Cut venue text to a fixed length, so a warner key or message built from it
+ * stays small.
+ *
+ * @internal
+ */
+export const cutVenueText = (value: unknown): string => {
+  const text = String(value)
+  return text.length > MAX_VALUE_CHARS
+    ? `${text.slice(0, MAX_VALUE_CHARS)}…`
+    : text
+}
+
 /**
  * Describe a skipped venue row. The venue value is cut to a fixed length, so
  * a warner key built from the text stays small.
@@ -41,22 +54,22 @@ export const skippedRowMessage = (
   row: string,
   field: string,
   value: unknown,
-  expected: string
+  expected: string,
+  marketId?: string
 ): string => {
-  const text = String(value)
-  const shown =
-    text.length > MAX_VALUE_CHARS ? `${text.slice(0, MAX_VALUE_CHARS)}…` : text
-  return `[${source}] skipping ${row} row: \`${field}\` is not a valid ${expected}: '${shown}'`
+  const market = marketId === undefined ? '' : ` on market '${marketId}'`
+  return `[${source}] skipping ${row} row${market}: \`${field}\` is not a valid ${expected}: '${cutVenueText(value)}'`
 }
 
 const warnSkippedRowOnce = createWarnOnce()
 
 /**
- * Warn once for each provider, row, field and expected kind that a provider
- * mapper skipped a venue row because a required field is not valid. The key
- * holds no venue value, so a second bad value for the same field stays silent.
+ * Warn once for each provider, row, field, expected kind and market that a
+ * provider mapper skipped a venue row because a required field is not valid.
+ * The key holds no venue value, so a second bad value for the same field on
+ * the same market stays silent.
  *
- * @param expected - What the field must be. Defaults to `'decimal'`.
+ * @param options.expected - What the field must be. Defaults to `'decimal'`.
  * @internal
  */
 export const warnSkippedVenueRow = (
@@ -64,10 +77,13 @@ export const warnSkippedVenueRow = (
   row: string,
   field: string,
   value: unknown,
-  expected = 'decimal'
+  {
+    marketId,
+    expected = 'decimal',
+  }: { marketId?: string; expected?: string } = {}
 ): void => {
   warnSkippedRowOnce(
-    `${provider}|${row}|${field}|${expected}`,
-    skippedRowMessage(provider, row, field, value, expected)
+    `${provider}|${row}|${field}|${expected}|${marketId ?? ''}`,
+    skippedRowMessage(provider, row, field, value, expected, marketId)
   )
 }

package/src/version.ts

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

package/src/websocket/wsLog.ts

@@ -1,4 +1,8 @@
-import { createWarnOnce, skippedRowMessage } from '../utils/warnOnce.js'
+import {
+  createWarnOnce,
+  cutVenueText,
+  skippedRowMessage,
+} from '../utils/warnOnce.js'
 
 const MAX_PAYLOAD_CHARS = 512
 
@@ -64,29 +68,38 @@ export const wsLog = {
   },
   /**
    * A frame row or order-book level with a required field that is not valid.
-   * Only that row is skipped. Logged once at `warn` for each provider, row and
-   * field; the key holds no venue value.
+   * Only that row is skipped. Logged once at `warn` for each provider, row,
+   * field and market; the key holds no venue value.
    */
   skippedRow(
     provider: string,
     row: string,
     field: string,
-    value: unknown
+    value: unknown,
+    marketId?: string
   ): void {
     warnSkippedRowOnce(
-      `${provider}|${row}|${field}`,
-      skippedRowMessage(`${provider}:ws`, row, field, value, 'decimal')
+      `${provider}|${row}|${field}|${marketId ?? ''}`,
+      skippedRowMessage(
+        `${provider}:ws`,
+        row,
+        field,
+        value,
+        'decimal',
+        marketId
+      )
     )
   },
   /**
    * A frame row the mapper rejected for a reason other than one field, such as
    * a lifecycle state the SDK does not carry. Logged once at `warn` for each
-   * provider and row; the key holds no venue value.
+   * provider, row and reason; the reason is cut to a fixed length.
    */
   droppedRow(provider: string, row: string, reason: string): void {
+    const shown = cutVenueText(reason)
     warnSkippedRowOnce(
-      `${provider}|${row}|dropped`,
-      `[${provider}:ws] skipping ${row} row: ${reason}`
+      `${provider}|${row}|dropped|${shown}`,
+      `[${provider}:ws] skipping ${row} row: ${shown}`
     )
   },
   /**

package/src/wire/orderAmounts.ts

@@ -1,9 +1,16 @@
-import type { DecimalString, Market } from '@lifi/perps-types'
+import {
+  type DecimalString,
+  type Market,
+  PerpsErrorCode,
+} from '@lifi/perps-types'
 import type Big from 'big.js'
 import { DivBig, TruncBig } from '../decimal/big.js'
 import { isDecimalStringZero } from '../decimal/compare.js'
 import { isDecimalString } from '../decimal/parse.js'
+import { invalidInput } from '../errors/invalidInput.js'
+import { PerpsError } from '../errors/PerpsError.js'
 import type { PerpsSDKClient } from '../types/provider.js'
+import { createSafeFunction } from '../utils/createSafeFunction.js'
 import { snapOrderSize } from './snap.js'
 
 /** @public */
@@ -31,14 +38,20 @@ export interface OrderAmounts {
   notional: DecimalString
 }
 
-function positiveDecimal(value: DecimalString): Big | null {
-  if (!isDecimalString(value)) {
-    return null
+function requirePositiveDecimal(value: DecimalString, parameter: string): Big {
+  const parsed = isDecimalString(value) ? new TruncBig(value) : undefined
+  if (parsed === undefined || !parsed.gt(0)) {
+    throw invalidInput(
+      parameter,
+      `must be a positive decimal, got '${String(value)}'`
+    )
   }
-  const parsed = new TruncBig(value)
-  return parsed.gt(0) ? parsed : null
+  return parsed
 }
 
+const lotSize = (market: Market): DecimalString =>
+  market.sizeIncrement ?? new TruncBig(`1e-${market.szDecimals}`).toFixed()
+
 /**
  * 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
@@ -46,26 +59,22 @@ function positiveDecimal(value: DecimalString): Big | null {
  * `notional` is the snapped size × price, and a derived margin is
  * `notional ÷ leverage` in `DivBig` (40 places, half-up).
  *
- * @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.
+ * @throws {PerpsError} `ValidationError` that names `amount` or `price` when
+ *   it is not a positive decimal, or `leverage` when it is not a finite number
+ *   above zero. `ValidationError` with the lot size when the snapped size is
+ *   zero (below one lot). `SDKError` when `market.providerId` names no
+ *   registered provider plugin.
  * @public
  */
-export function calculateOrderAmounts(
-  input: OrderAmountsInput
-): OrderAmounts | null {
+export function calculateOrderAmounts(input: OrderAmountsInput): OrderAmounts {
   const { sdk, market, held, leverage } = input
-  const amount = positiveDecimal(input.amount)
-  const price = positiveDecimal(input.price)
-  if (
-    amount === null ||
-    price === null ||
-    !Number.isFinite(leverage) ||
-    leverage <= 0
-  ) {
-    return null
+  const amount = requirePositiveDecimal(input.amount, 'amount')
+  const price = requirePositiveDecimal(input.price, 'price')
+  if (!Number.isFinite(leverage) || leverage <= 0) {
+    throw invalidInput(
+      'leverage',
+      `must be a finite number above zero, got ${leverage}`
+    )
   }
 
   const requested =
@@ -76,7 +85,10 @@ export function calculateOrderAmounts(
         : amount.times(leverage).div(price).toFixed()
   const size = snapOrderSize(sdk, market, requested)
   if (isDecimalStringZero(size)) {
-    return null
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `The order size ${requested} is below the lot size ${lotSize(market)}.`
+    )
   }
 
   const notional = new TruncBig(size).times(price)
@@ -89,3 +101,9 @@ export function calculateOrderAmounts(
     notional: notional.toFixed(),
   }
 }
+
+/** @public */
+export const safeCalculateOrderAmounts = createSafeFunction(
+  'calculateOrderAmounts',
+  calculateOrderAmounts
+)

package/src/wire/refuel.ts

@@ -2,7 +2,7 @@ import { type DecimalString, PerpsErrorCode } from '@lifi/perps-types'
 import type Big from 'big.js'
 import { DivBig } from '../decimal/big.js'
 import { BASE_UNITS_PATTERN } from '../decimal/convert.js'
-import { decimalStringToBig } from '../decimal/decimalStringToBig.js'
+import { decimalStringToDivBig } from '../decimal/decimalStringToBig.js'
 import { PerpsError } from '../errors/PerpsError.js'
 
 /**
@@ -48,7 +48,7 @@ function requireBaseUnits(value: DecimalString, field: string): Big {
  *   when `recommendedAmount`, `recommendedUsd` or `priceUsd` is not greater
  *   than zero: a route with nothing to refuel, not a failure.
  * @throws {PerpsError} `ValidationError` when a base-unit field is not an
- *   integer string, a USD field is not a {@link DecimalString}, or `decimals`
+ *   integer string, a USD field does not match the decimal pattern, or `decimals`
  *   is not a non-negative integer.
  * @public
  */
@@ -67,8 +67,8 @@ export function calculateRefuelAmount(
     'recommendedAmount'
   )
   const balance = requireBaseUnits(input.nativeBalance, 'nativeBalance')
-  const recommendedUsd = decimalStringToBig(input.recommendedUsd)
-  const priceUsd = decimalStringToBig(input.priceUsd)
+  const recommendedUsd = decimalStringToDivBig(input.recommendedUsd)
+  const priceUsd = decimalStringToDivBig(input.priceUsd)
   const deficit = recommended.minus(balance)
   if (
     !recommended.gt(0) ||

package/src/wire/transferable.ts

@@ -9,8 +9,8 @@ import { decimalStringToBig } from '../decimal/decimalStringToBig.js'
  * @param venueFigure - The venue's free figure for the category, which can
  *   exceed `units` or fall below zero.
  * @param units - Units held in the category, the upper bound of the clamp.
- * @throws {PerpsError} `ValidationError` when either input is not a
- *   {@link DecimalString}, naming the field.
+ * @throws {PerpsError} `ValidationError` when either input does not match the
+ *   decimal pattern, naming the field.
  * @public
  */
 export function calculateTransferable(