@lifi/perps-sdk 23.1.0 → 25.0.0

package/src/decimal/format.ts

@@ -1,4 +1,6 @@
 import type { DecimalString } from '@lifi/perps-types'
+import Big from 'big.js'
+import { decimalStringToBig } from './decimalStringToBig.js'
 
 /**
  * Options shared by the human-facing display formatters.
@@ -8,7 +10,10 @@ import type { DecimalString } from '@lifi/perps-types'
 export interface FormatOptions {
   /** Fixed number of decimal places. Defaults are per-formatter. */
   decimals?: number
-  /** Rendered when the value is null/undefined/NaN/non-finite. Defaults to `'—'`. */
+  /**
+   * Rendered when the value is null, undefined, blank or a non-finite number.
+   * A string that is not a decimal is shown unchanged. Defaults to `'—'`.
+   */
   placeholder?: string
   /** BCP 47 locale controlling digit grouping and separators (e.g. `'en-US'`). */
   locale?: string
@@ -33,76 +38,62 @@ const DEFAULT_PLACEHOLDER = '—'
 type FormatInput = number | DecimalString | string | null | undefined
 
 /**
- * Extra decimal places used to normalise IEEE-754 representation noise before
- * truncating. `toFixed` at this higher precision cleans values like
- * `0.28999999…` back to `0.29`; truncation then chops the guard digits.
- */
-const FLOAT_GUARD_DIGITS = 9
-
-/**
- * Tolerantly coerce a display input to a finite number.
- *
- * Strips `$`, `,`, and surrounding whitespace from strings. Returns `null`
- * when the value is null/undefined/blank or does not resolve to a finite
- * number, so callers can render a placeholder instead of `$0.00` or `$NaN`.
+ * Read a display input as a `Big`. `null` means the formatter renders the
+ * placeholder; a string that does not match the decimal pattern is returned
+ * unchanged for display.
  */
-function toFiniteNumber(value: FormatInput): number | null {
-  let n: number
-  if (typeof value === 'string') {
-    const cleaned = value.replace(/[$,\s]/g, '')
-    if (!cleaned) {
-      return null
-    }
-    n = Number(cleaned)
-  } else if (typeof value === 'number') {
-    n = value
-  } else {
+function toBig(value: FormatInput): Big | null | string {
+  if (typeof value === 'number') {
+    return Number.isFinite(value) ? new Big(value) : null
+  }
+  if (typeof value !== 'string' || value.trim() === '') {
     return null
   }
-  return Number.isFinite(n) ? n : null
+  try {
+    return decimalStringToBig(value)
+  } catch {
+    return value
+  }
 }
 
-/**
- * Truncate a non-negative value toward zero to `decimals` places using its
- * decimal string, never float scaling. Representation noise is first
- * normalised by `toFixed` at {@link FLOAT_GUARD_DIGITS} extra precision, then
- * the guard digits are chopped: `99.999` at 2dp → `99.99`, `0.29` → `0.29`.
- */
-function truncateAbs(abs: number, decimals: number): number {
-  // `toFixed` emits exponent notation at >= 1e21; every double that large is an integer.
-  if (Number.isInteger(abs)) {
-    return abs
-  }
-  const s = abs.toFixed(Math.min(decimals + FLOAT_GUARD_DIGITS, 100))
-  const dot = s.indexOf('.')
-  const cut = decimals === 0 ? dot : dot + 1 + decimals
-  return Number(s.slice(0, cut))
+function decimalSeparator(locale: string | undefined): string {
+  return (
+    new Intl.NumberFormat(locale)
+      .formatToParts(1.5)
+      .find((part) => part.type === 'decimal')?.value ?? '.'
+  )
 }
 
 /**
- * Reduce `n` to `decimals` places then split into a sign and the
+ * Reduce `value` to `decimals` places then split into a sign and the
  * locale-formatted absolute body. The sign is derived from the reduced value
  * so magnitudes that collapse to zero render without a spurious `-`/`+`.
  * `signed` emits `+` for positives; `rounding` selects half-up or truncation.
  */
 function signAndBody(
-  n: number,
+  value: Big,
   decimals: number,
   locale: string | undefined,
   grouping: boolean,
   rounding: RoundingMode,
   signed: boolean
 ): { sign: '+' | '-' | ''; body: string } {
-  const reduced =
-    rounding === 'floor'
-      ? (n < 0 ? -1 : 1) * truncateAbs(Math.abs(n), decimals)
-      : Number(n.toFixed(decimals))
-  const sign = reduced < 0 ? '-' : signed && reduced > 0 ? '+' : ''
-  const body = Math.abs(reduced).toLocaleString(locale, {
-    minimumFractionDigits: decimals,
-    maximumFractionDigits: decimals,
-    useGrouping: grouping,
-  })
+  const reduced = value.round(
+    decimals,
+    rounding === 'floor' ? Big.roundDown : Big.roundHalfUp
+  )
+  const sign = reduced.lt(0) ? '-' : signed && reduced.gt(0) ? '+' : ''
+  const [integerPart = '0', fractionPart] = reduced
+    .abs()
+    .toFixed(decimals)
+    .split('.')
+  const integerBody = grouping
+    ? BigInt(integerPart).toLocaleString(locale)
+    : integerPart
+  const body =
+    fractionPart === undefined
+      ? integerBody
+      : `${integerBody}${decimalSeparator(locale)}${fractionPart}`
   return { sign, body }
 }
 
@@ -110,14 +101,14 @@ function signAndBody(
  * Auto-detect a sensible number of decimal places from a value's magnitude:
  * `>=1` → 2, `>=0.1` → 4, `>=0.01` → 5, otherwise 6.
  */
-function autoDecimals(abs: number): number {
-  if (abs >= 1) {
+function autoDecimals(abs: Big): number {
+  if (abs.gte(1)) {
     return 2
   }
-  if (abs >= 0.1) {
+  if (abs.gte('0.1')) {
     return 4
   }
-  if (abs >= 0.01) {
+  if (abs.gte('0.01')) {
     return 5
   }
   return 6
@@ -145,10 +136,13 @@ export function formatNumber(
     locale,
     rounding = 'halfUp',
   } = options
-  const n = toFiniteNumber(value)
+  const n = toBig(value)
   if (n === null) {
     return placeholder
   }
+  if (typeof n === 'string') {
+    return n
+  }
   const { sign, body } = signAndBody(n, decimals, locale, true, rounding, false)
   return `${sign}${body}`
 }
@@ -171,10 +165,13 @@ export function formatUsd(
     locale,
     rounding = 'halfUp',
   } = options
-  const n = toFiniteNumber(value)
+  const n = toBig(value)
   if (n === null) {
     return placeholder
   }
+  if (typeof n === 'string') {
+    return n
+  }
   const { sign, body } = signAndBody(n, decimals, locale, true, rounding, false)
   return `${sign}$${body}`
 }
@@ -198,10 +195,13 @@ export function formatSignedUsd(
     locale,
     rounding = 'halfUp',
   } = options
-  const n = toFiniteNumber(value)
+  const n = toBig(value)
   if (n === null) {
     return placeholder
   }
+  if (typeof n === 'string') {
+    return n
+  }
   const { sign, body } = signAndBody(n, decimals, locale, true, rounding, true)
   return `${sign}$${body}`
 }
@@ -225,10 +225,13 @@ export function formatSignedPercent(
     locale,
     rounding = 'halfUp',
   } = options
-  const n = toFiniteNumber(value)
+  const n = toBig(value)
   if (n === null) {
     return placeholder
   }
+  if (typeof n === 'string') {
+    return n
+  }
   const { sign, body } = signAndBody(n, decimals, locale, false, rounding, true)
   return `${sign}${body}%`
 }
@@ -252,17 +255,20 @@ export function formatPrice(
     locale,
     rounding = 'halfUp',
   } = options
-  const n = toFiniteNumber(value)
+  const n = toBig(value)
   if (n === null) {
     return placeholder
   }
-  const abs = Math.abs(n)
+  if (typeof n === 'string') {
+    return n
+  }
+  const abs = n.abs()
   const decimals = options.decimals ?? autoDecimals(abs)
   const { sign, body } = signAndBody(
     n,
     decimals,
     locale,
-    abs >= 1000,
+    abs.gte(1000),
     rounding,
     false
   )
@@ -283,20 +289,23 @@ export function formatCompactUsd(
   options: FormatOptions = {}
 ): string {
   const { decimals = 2, placeholder = DEFAULT_PLACEHOLDER } = options
-  const n = toFiniteNumber(value)
+  const n = toBig(value)
   if (n === null) {
     return placeholder
   }
-  const sign = n < 0 ? '-' : ''
-  const abs = Math.abs(n)
-  if (abs >= 1_000_000_000) {
-    return `${sign}$${(abs / 1_000_000_000).toFixed(decimals)}B`
+  if (typeof n === 'string') {
+    return n
+  }
+  const sign = n.lt(0) ? '-' : ''
+  const abs = n.abs()
+  if (abs.gte(1_000_000_000)) {
+    return `${sign}$${abs.div(1_000_000_000).toFixed(decimals)}B`
   }
-  if (abs >= 1_000_000) {
-    return `${sign}$${(abs / 1_000_000).toFixed(decimals)}M`
+  if (abs.gte(1_000_000)) {
+    return `${sign}$${abs.div(1_000_000).toFixed(decimals)}M`
   }
-  if (abs >= 1_000) {
-    return `${sign}$${(abs / 1_000).toFixed(decimals)}K`
+  if (abs.gte(1_000)) {
+    return `${sign}$${abs.div(1_000).toFixed(decimals)}K`
   }
   return `${sign}$${abs.toFixed(decimals)}`
 }

package/src/decimal/parse.ts

@@ -1,87 +1,108 @@
-import {
-  DECIMAL_PATTERN,
-  type DecimalString,
-  PerpsErrorCode,
-} from '@lifi/perps-types'
+import { DECIMAL_PATTERN, PerpsErrorCode } from '@lifi/perps-types'
+import Big from 'big.js'
 import { PerpsError } from '../errors/PerpsError.js'
+import { createSafeFunction } from '../utils/createSafeFunction.js'
+import { decimalStringToBig } from './decimalStringToBig.js'
 
 /**
- * Parse a string to a float, stripping common formatting artefacts.
+ * Read a decimal string as a JS float, for a chart or pixel value only. A
+ * float holds about 15 significant digits, so the result can lose precision;
+ * never use it for an amount sent to a venue.
  *
- * Handles:
- * - Currency prefixes/suffixes ($, USD, etc.)
- * - Explicit sign prefixes (+/-)
- * - Thousands separators (commas)
- * - Percentage suffixes (%)
- * - Whitespace
- *
- * @returns Parsed number; `0` for empty/blank input, `NaN` when a non-empty
- *   string contains no parseable number
+ * @throws {PerpsError} `ValidationError` when `value` does not match the decimal pattern
+ *   or is too large for a finite float.
+ * @public
  */
-function toFloat(value: string): number {
-  if (!value) {
-    return 0
-  }
-  const cleaned = value.trim().replace(/[$%]/g, '').replace(/,/g, '').trim()
-  if (!cleaned) {
-    return 0
+export function decimalStringToNumber(value: string): number {
+  const parsed = decimalStringToBig(value).toNumber()
+  if (!Number.isFinite(parsed)) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `'${value}' is too large for a finite number.`
+    )
   }
-  return parseFloat(cleaned)
+  return parsed
 }
 
-const FORMATTED_NUMBER =
-  /^(?:[+-]\s*)?(?:\$\s*)?(?:(?:\d{1,3}(?:,\d{3})+|\d+)(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?(?:\s*(?:%|USD))?$/i
+/**
+ * {@link decimalStringToNumber}, or `undefined` with a warning when it throws.
+ *
+ * @public
+ */
+export const safeDecimalStringToNumber = createSafeFunction(
+  'decimalStringToNumber',
+  decimalStringToNumber
+)
 
 /**
- * Parse an optional decimal field, tolerating currency symbols, grouping
- * separators and a percentage suffix around the number.
- * Gives back `undefined` for a missing, malformed or non-finite value, and `0` for an empty string.
+ * Narrows an unknown value to a {@link DecimalString}. No characters are
+ * removed first.
  *
  * @public
  */
-export function parseDecimal(
-  value: DecimalString | string | null | undefined
-): number | undefined {
-  if (value == null) {
+export function isDecimalString(value: unknown): value is string {
+  return typeof value === 'string' && DECIMAL_PATTERN.test(value)
+}
+
+const MAX_SPELLED_EXPONENT = 1000
+
+function spellDecimal(value: unknown): string | undefined {
+  if (isDecimalString(value)) {
+    return value
+  }
+  if (typeof value !== 'string' && typeof value !== 'number') {
+    return undefined
+  }
+  if (typeof value === 'number' && !Number.isFinite(value)) {
     return undefined
   }
-  if (value.trim() === '') {
-    return toFloat(value)
+  let parsed: Big
+  try {
+    parsed = new Big(value)
+  } catch {
+    return undefined
   }
-  if (!FORMATTED_NUMBER.test(value.trim())) {
+  // Spelling out an unbounded exponent builds a string of that many digits.
+  if (Math.abs(parsed.e) > MAX_SPELLED_EXPONENT) {
     return undefined
   }
-  const parsed = toFloat(value)
-  return Number.isFinite(parsed) ? parsed : undefined
+  return (parsed.eq(0) ? new Big(0) : parsed).toFixed()
 }
 
 /**
- * Narrows an unknown value to a {@link DecimalString}.
+ * Read a venue value (a string or a number) as a decimal string, for a
+ * money-path value that must not go on wrong. A number or an exponent string
+ * is spelled out in full; no `$`, `%` or `,` is removed.
  *
+ * @param tool - Provider key set on the error.
+ * @throws {PerpsError} `SDKError` naming `field` when `value` is not a finite
+ *   decimal.
  * @public
  */
-export function isDecimalString(value: unknown): value is DecimalString {
-  return typeof value === 'string' && DECIMAL_PATTERN.test(value)
+export function unknownToDecimalString(
+  value: unknown,
+  field: string,
+  tool: string
+): string {
+  const decimal = spellDecimal(value)
+  if (decimal !== undefined) {
+    return decimal
+  }
+  const error = new PerpsError(
+    PerpsErrorCode.SDKError,
+    `${tool} field \`${field}\` is not a valid decimal: '${String(value)}'`
+  )
+  error.tool = tool
+  throw error
 }
 
 /**
- * Check a decimal input against the {@link DecimalString} contract, naming
- * the field it came from, so a malformed amount fails at the SDK boundary
- * instead of inside big.js.
+ * The safe pair of {@link unknownToDecimalString}: `undefined` and a warning
+ * in place of a throw.
  *
- * @returns `value`, unchanged.
- * @throws {PerpsError} `ValidationError` naming `field`.
  * @public
  */
-export function validateDecimalString(
-  value: DecimalString,
-  field: string
-): DecimalString {
-  if (!isDecimalString(value)) {
-    throw new PerpsError(
-      PerpsErrorCode.ValidationError,
-      `Invalid \`${field}\`: '${value}' is not a decimal string.`
-    )
-  }
-  return value
-}
+export const safeUnknownToDecimalString = createSafeFunction(
+  'unknownToDecimalString',
+  unknownToDecimalString
+)

package/src/errors/invalidInput.ts

@@ -0,0 +1,10 @@
+import { PerpsErrorCode } from '@lifi/perps-types'
+import { PerpsError } from './PerpsError.js'
+
+/** A `ValidationError` that names the input parameter and the rule it breaks. */
+export function invalidInput(parameter: string, rule: string): PerpsError {
+  return new PerpsError(
+    PerpsErrorCode.ValidationError,
+    `\`${parameter}\` ${rule}.`
+  )
+}

package/src/index.ts

@@ -17,13 +17,40 @@ export {
 } from './client/createPerpsClient.js'
 export { PerpsClient } from './client/PerpsClient.js'
 export { requireProvider } from './client/requireProvider.js'
-export { isDecimalStringGreaterThan } from './decimal/compare.js'
-export type { BaseUnitsRounding } from './decimal/convert.js'
 export {
-  baseUnitsToDecimal,
-  decimalToBaseUnits,
+  absDecimalString,
+  addDecimalString,
+  addDecimalStrings,
+  divideDecimalString,
+  divideDecimalStringRoundDown,
+  multiplyDecimalString,
+  safeAbsDecimalString,
+  safeAddDecimalString,
+  safeAddDecimalStrings,
+  safeDivideDecimalString,
+  safeDivideDecimalStringRoundDown,
+  safeMultiplyDecimalString,
+  safeSubtractDecimalString,
+  subtractDecimalString,
+} from './decimal/arithmetic.js'
+export {
+  compareDecimalStrings,
+  isDecimalStringGreaterThan,
+  isDecimalStringZero,
+  safeCompareDecimalStrings,
+  safeIsDecimalStringGreaterThan,
+  safeIsDecimalStringZero,
+} from './decimal/compare.js'
+export type { DecimalRounding } from './decimal/convert.js'
+export {
+  decimalStringToScaledInteger,
   numberToDecimalString,
-  truncateDecimal,
+  roundDecimalString,
+  safeDecimalStringToScaledInteger,
+  safeNumberToDecimalString,
+  safeRoundDecimalString,
+  safeScaledIntegerToDecimalString,
+  scaledIntegerToDecimalString,
 } from './decimal/convert.js'
 export type { FormatOptions, RoundingMode } from './decimal/format.js'
 export {
@@ -35,9 +62,11 @@ export {
   formatUsd,
 } from './decimal/format.js'
 export {
+  decimalStringToNumber,
   isDecimalString,
-  parseDecimal,
-  validateDecimalString,
+  safeDecimalStringToNumber,
+  safeUnknownToDecimalString,
+  unknownToDecimalString,
 } from './decimal/parse.js'
 export { PerpsErrorMessage } from './errors/constants.js'
 export { PerpsError } from './errors/PerpsError.js'
@@ -48,7 +77,7 @@ export {
 } from './math/fills.js'
 export type { ExpectedPnl } from './math/order.js'
 export {
-  applySlippage,
+  applySlippageToPrice,
   buildQuote,
   calculateExpectedPnl,
   calculateRealizedPnlPercent,
@@ -59,6 +88,17 @@ export {
   estimateRealizedPnl,
   findMatchingPosition,
   resolveCloseSize,
+  safeApplySlippageToPrice,
+  safeBuildQuote,
+  safeCalculateExpectedPnl,
+  safeCalculateRealizedPnlPercent,
+  safeCalculateSize,
+  safeCalculateTriggerPercent,
+  safeCalculateTriggerPrice,
+  safeEstimateFees,
+  safeEstimateRealizedPnl,
+  safeResolveCloseSize,
+  safeWalkOrderbook,
   walkOrderbook,
 } from './math/order.js'
 export {
@@ -71,10 +111,24 @@ export {
   calculateUnrealizedPnl,
   estimateAverageEntryPrice,
   estimateLiquidationPrice,
+  estimateLiquidationPriceAtMarketRate,
   estimateNewLeverage,
   estimateUnrealizedPnl,
   positionSupportsMarginAdjustment,
   positionSupportsMarginRemoval,
+  safeCalculateEffectiveLeverage,
+  safeCalculateLiquidationDistance,
+  safeCalculateNotionalValue,
+  safeCalculateRealizedPnl,
+  safeCalculateRequiredMargin,
+  safeCalculateRoe,
+  safeCalculateUnrealizedPnl,
+  safeEstimateAverageEntryPrice,
+  safeEstimateLiquidationPrice,
+  safeEstimateLiquidationPriceAtMarketRate,
+  safeEstimateNewLeverage,
+  safeEstimateUnrealizedPnl,
+  safeWouldImmediatelyLiquidate,
   wouldImmediatelyLiquidate,
 } from './math/position.js'
 // Registries
@@ -177,6 +231,7 @@ export type {
   GetPortfolioHistoryParams,
   GetSetupParams,
   GetWithdrawableBalancesParams,
+  GetWithdrawalTypesParams,
   GetWithdrawFlowParams,
   ModifyOrdersParams,
   PerpsClientOptions,
@@ -223,6 +278,7 @@ export type {
   ProviderGetPositionsParams,
   ProviderGetQuoteParams,
   ProviderGetWithdrawableBalancesParams,
+  ProviderGetWithdrawalTypesParams,
   ProviderGetWithdrawFlowParams,
   QuoteListener,
   SignActionProgress,
@@ -231,12 +287,14 @@ export type {
 export type {
   ProviderWithdrawableBalance,
   WithdrawableBalance,
-  WithdrawalRoute,
+  WithdrawalSourceTypes,
+  WithdrawalTypeOption,
   WithdrawFlow,
   WithdrawFlowReady,
   WithdrawFlowSetupRequired,
 } from './types/withdrawal.js'
 export { paginateActivity } from './utils/activityPaging.js'
+export { createSafeFunction } from './utils/createSafeFunction.js'
 export {
   ETHEREUM_NATIVE_GAS,
   ETHEREUM_USDC,
@@ -269,7 +327,11 @@ export {
   signTypedData,
   signTypedDataWithSigner,
 } from './utils/signTypedData.js'
-export { createWarnOnce } from './utils/warnOnce.js'
+export {
+  safeTimestampToIsoString,
+  timestampToIsoString,
+} from './utils/timestampToIsoString.js'
+export { createWarnOnce, warnSkippedVenueRow } from './utils/warnOnce.js'
 // Version
 export { name, version } from './version.js'
 export { cachePromise } from './websocket/cachePromise.js'
@@ -299,9 +361,15 @@ export type {
   OrderAmounts,
   OrderAmountsInput,
 } from './wire/orderAmounts.js'
-export { calculateOrderAmounts } from './wire/orderAmounts.js'
+export {
+  calculateOrderAmounts,
+  safeCalculateOrderAmounts,
+} from './wire/orderAmounts.js'
 export type { RefuelAmountInput } from './wire/refuel.js'
-export { calculateRefuelAmount } from './wire/refuel.js'
+export {
+  calculateRefuelAmount,
+  REFUEL_FEE_MARGIN_PERCENT,
+} from './wire/refuel.js'
 export { snapOrderPrice, snapOrderSize } from './wire/snap.js'
 export { calculateTransferable } from './wire/transferable.js'
 export { calculateWithdrawMax } from './wire/withdraw.js'