@lifi/perps-sdk 23.1.0 → 24.0.0

package/src/decimal/parse.ts

@@ -1,87 +1,97 @@
-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` is not a decimal string
+ *   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
-
 /**
- * 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.
+ * {@link decimalStringToNumber}, or `undefined` with a warning when it throws.
  *
  * @public
  */
-export function parseDecimal(
-  value: DecimalString | string | null | undefined
-): number | undefined {
-  if (value == null) {
-    return undefined
-  }
-  if (value.trim() === '') {
-    return toFloat(value)
-  }
-  if (!FORMATTED_NUMBER.test(value.trim())) {
-    return undefined
-  }
-  const parsed = toFloat(value)
-  return Number.isFinite(parsed) ? parsed : undefined
-}
+export const safeDecimalStringToNumber = createSafeFunction(
+  'decimalStringToNumber',
+  decimalStringToNumber
+)
 
 /**
- * Narrows an unknown value to a {@link DecimalString}.
+ * Narrows an unknown value to a {@link DecimalString}. No characters are
+ * removed first.
  *
  * @public
  */
-export function isDecimalString(value: unknown): value is DecimalString {
+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
+  }
+  let parsed: Big
+  try {
+    parsed = new Big(value)
+  } catch {
+    return undefined
+  }
+  // Spelling out an unbounded exponent builds a string of that many digits.
+  if (Math.abs(parsed.e) > MAX_SPELLED_EXPONENT) {
+    return undefined
+  }
+  return (parsed.eq(0) ? new Big(0) : parsed).toFixed()
+}
+
 /**
- * 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.
+ * 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.
  *
- * @returns `value`, unchanged.
- * @throws {PerpsError} `ValidationError` naming `field`.
+ * @param tool - Provider key set on the error.
+ * @throws {PerpsError} `SDKError` naming `field` when `value` is not a finite
+ *   decimal.
  * @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.`
-    )
+export function unknownToDecimalString(
+  value: unknown,
+  field: string,
+  tool: string
+): string {
+  const decimal = spellDecimal(value)
+  if (decimal !== undefined) {
+    return decimal
   }
-  return value
+  const error = new PerpsError(
+    PerpsErrorCode.SDKError,
+    `${tool} field \`${field}\` is not a valid decimal: '${String(value)}'`
+  )
+  error.tool = tool
+  throw error
 }

package/src/index.ts

@@ -17,12 +17,39 @@ 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,
+  divideDecimalString,
+  divideDecimalStringRoundDown,
+  multiplyDecimalString,
+  safeAbsDecimalString,
+  safeAddDecimalString,
+  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,
+  roundDecimalString,
+  safeDecimalStringToScaledInteger,
+  safeNumberToDecimalString,
+  safeRoundDecimalString,
+  safeScaledIntegerToDecimalString,
+  safeTruncateDecimal,
+  scaledIntegerToDecimalString,
   truncateDecimal,
 } from './decimal/convert.js'
 export type { FormatOptions, RoundingMode } from './decimal/format.js'
@@ -35,9 +62,10 @@ export {
   formatUsd,
 } from './decimal/format.js'
 export {
+  decimalStringToNumber,
   isDecimalString,
-  parseDecimal,
-  validateDecimalString,
+  safeDecimalStringToNumber,
+  unknownToDecimalString,
 } from './decimal/parse.js'
 export { PerpsErrorMessage } from './errors/constants.js'
 export { PerpsError } from './errors/PerpsError.js'
@@ -48,7 +76,7 @@ export {
 } from './math/fills.js'
 export type { ExpectedPnl } from './math/order.js'
 export {
-  applySlippage,
+  applySlippageToPrice,
   buildQuote,
   calculateExpectedPnl,
   calculateRealizedPnlPercent,
@@ -59,6 +87,17 @@ export {
   estimateRealizedPnl,
   findMatchingPosition,
   resolveCloseSize,
+  safeApplySlippageToPrice,
+  safeBuildQuote,
+  safeCalculateExpectedPnl,
+  safeCalculateRealizedPnlPercent,
+  safeCalculateSize,
+  safeCalculateTriggerPercent,
+  safeCalculateTriggerPrice,
+  safeEstimateFees,
+  safeEstimateRealizedPnl,
+  safeResolveCloseSize,
+  safeWalkOrderbook,
   walkOrderbook,
 } from './math/order.js'
 export {
@@ -71,10 +110,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 +230,7 @@ export type {
   GetPortfolioHistoryParams,
   GetSetupParams,
   GetWithdrawableBalancesParams,
+  GetWithdrawalTypesParams,
   GetWithdrawFlowParams,
   ModifyOrdersParams,
   PerpsClientOptions,
@@ -223,6 +277,7 @@ export type {
   ProviderGetPositionsParams,
   ProviderGetQuoteParams,
   ProviderGetWithdrawableBalancesParams,
+  ProviderGetWithdrawalTypesParams,
   ProviderGetWithdrawFlowParams,
   QuoteListener,
   SignActionProgress,
@@ -231,7 +286,8 @@ export type {
 export type {
   ProviderWithdrawableBalance,
   WithdrawableBalance,
-  WithdrawalRoute,
+  WithdrawalSourceTypes,
+  WithdrawalTypeOption,
   WithdrawFlow,
   WithdrawFlowReady,
   WithdrawFlowSetupRequired,
@@ -269,7 +325,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'
@@ -301,7 +361,10 @@ export type {
 } from './wire/orderAmounts.js'
 export { calculateOrderAmounts } 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'

package/src/math/fills.ts

@@ -3,7 +3,9 @@ import {
   FillClassification,
   OrderSide,
 } from '@lifi/perps-types'
-import { parseDecimal } from '../decimal/parse.js'
+import Big from 'big.js'
+import { isDecimalStringZero } from '../decimal/compare.js'
+import { isDecimalString } from '../decimal/parse.js'
 
 /**
  * Re-exported fill taxonomy used by {@link classifyFillFromPosition}.
@@ -18,45 +20,51 @@ export { FillClassification }
  *
  * @param startPosition Signed position held BEFORE this fill (`> 0` long,
  *   `< 0` short, `0` flat).
- * @param side Hyperliquid-style: `'B'` for buy, anything else for sell.
- * @param sz Unsigned fill size, parsed with `parseFloat`.
+ * @param sz Unsigned fill size.
+ * @returns `BUY` or `SELL` when `startPosition` or `sz` is not a decimal
+ *   string, so one malformed venue fill still maps.
  * @public
  */
 export function classifyFillFromPosition(
   startPosition: DecimalString,
-  side: string,
+  side: OrderSide,
   sz: DecimalString
 ): FillClassification {
-  const start = parseFloat(startPosition)
-  const delta = side === 'B' ? parseFloat(sz) : -parseFloat(sz)
-  const end = start + delta
+  if (!isDecimalString(startPosition) || !isDecimalString(sz)) {
+    return side === OrderSide.BUY
+      ? FillClassification.BUY
+      : FillClassification.SELL
+  }
+  const start = new Big(startPosition)
+  const size = new Big(sz)
+  const end = side === OrderSide.BUY ? start.plus(size) : start.minus(size)
 
-  if (start === 0) {
-    return end > 0
+  if (start.eq(0)) {
+    return end.gt(0)
       ? FillClassification.OPENED_LONG
       : FillClassification.OPENED_SHORT
   }
 
-  if (start > 0) {
-    if (end === 0) {
+  if (start.gt(0)) {
+    if (end.eq(0)) {
       return FillClassification.CLOSED_LONG
     }
-    if (end < 0) {
+    if (end.lt(0)) {
       return FillClassification.SWITCHED_SHORT
     }
-    if (end > start) {
+    if (end.gt(start)) {
       return FillClassification.INCREASED_LONG
     }
     return FillClassification.REDUCED_LONG
   }
 
-  if (end === 0) {
+  if (end.eq(0)) {
     return FillClassification.CLOSED_SHORT
   }
-  if (end > 0) {
+  if (end.gt(0)) {
     return FillClassification.SWITCHED_LONG
   }
-  if (end < start) {
+  if (end.lt(start)) {
     return FillClassification.INCREASED_SHORT
   }
   return FillClassification.REDUCED_SHORT
@@ -66,13 +74,20 @@ export function classifyFillFromPosition(
  * Classify a fill as open or close based on realizedPnl.
  * @deprecated Use `Fill.classification` instead — it uses startPosition
  * for accurate open/increase/reduce/close/reverse classification.
+ * @returns `BUY` or `SELL` when `realizedPnl` is a string that is not a
+ *   decimal string.
  * @public
  */
 export function classifyFill(
   side: OrderSide,
   realizedPnl: DecimalString | null | undefined
 ): FillClassification {
-  const isClose = realizedPnl != null && parseDecimal(realizedPnl) !== 0
+  if (realizedPnl != null && !isDecimalString(realizedPnl)) {
+    return side === OrderSide.BUY
+      ? FillClassification.BUY
+      : FillClassification.SELL
+  }
+  const isClose = realizedPnl != null && !isDecimalStringZero(realizedPnl)
   if (side === OrderSide.BUY) {
     return isClose
       ? FillClassification.CLOSED_SHORT