@lifi/perps-sdk-provider-hyperliquid 25.0.0 → 27.0.0

package/src/utils/mapOrder.ts

@@ -1,4 +1,16 @@
-import { PerpsError, triggerConditionFor } from '@lifi/perps-sdk'
+import {
+  createWarnOnce,
+  isDecimalString,
+  isDecimalStringGreaterThan,
+  type MarketRegistry,
+  PerpsError,
+  safeDivideDecimalString,
+  safeIsDecimalStringGreaterThan,
+  safeIsDecimalStringZero,
+  safeSubtractDecimalString,
+  triggerConditionFor,
+  warnSkippedVenueRow,
+} from '@lifi/perps-sdk'
 import type {
   MarketDisplay,
   Order,
@@ -12,13 +24,14 @@ import {
   PerpsErrorCode,
   TimeInForce,
 } from '@lifi/perps-types'
-import Big from 'big.js'
 import { PROVIDER_KEY } from '../constants.js'
 import type {
   HlFrontendOpenOrder,
   HlOrderDetail,
   HlTwapHistoryEntry,
 } from '../types/index.js'
+import { assetIsOutcome } from './assetId.js'
+import { rowTimestampToIsoStringOrUndefined } from './rowTimestamp.js'
 
 /** Order payload shared by frontend, historical, and single-order reads. */
 export type HlOrderLike = HlFrontendOpenOrder | HlOrderDetail['order']
@@ -87,28 +100,85 @@ export const mapOrderStatus = (status: string): OrderStatus => {
   }
 }
 
+const skipOrder = (
+  marketId: string,
+  field: string,
+  value: unknown
+): undefined => {
+  warnSkippedVenueRow(PROVIDER_KEY, 'order', field, value, { marketId })
+  return undefined
+}
+
+const warnDroppedRowOnce = createWarnOnce()
+
+/**
+ * Map one venue row, or drop it. An outcome market identity, a coin the backend
+ * market list does not hold, and a row the mapper rejects each drop only their
+ * own row; each distinct mapper message warns once.
+ */
+export const mapOrderRow = (
+  coin: string,
+  registry: MarketRegistry | undefined,
+  map: (market: MarketDisplay) => Order | undefined
+): Order | undefined => {
+  if (assetIsOutcome(coin)) {
+    return undefined
+  }
+  const market = registry?.get(coin)
+  if (market === undefined) {
+    return undefined
+  }
+  try {
+    return map(market)
+  } catch (error) {
+    if (!(error instanceof PerpsError)) {
+      throw error
+    }
+    const message = `[${PROVIDER_KEY}] dropped order row: ${error.message}`
+    warnDroppedRowOnce(message, message)
+    return undefined
+  }
+}
+
 function venueError(message: string): PerpsError {
   const error = new PerpsError(PerpsErrorCode.ThirdPartyError, message)
   error.tool = PROVIDER_KEY
   return error
 }
 
-/** Normalize regular, trigger, and TWAP rows through one lifecycle model. */
+/**
+ * Normalize regular, trigger, and TWAP rows through one lifecycle model. A row
+ * whose filled or remaining size or timestamp cannot be derived gives `undefined`.
+ */
 export const mapOrder = (
   raw: HlOrderLike | HlOrderDetail | HlTwapHistoryEntry,
   market: MarketDisplay,
   parentOrderId?: string
-): Order => {
+): Order | undefined => {
   if ('state' in raw) {
     if (raw.twapId === undefined) {
       throw venueError('Hyperliquid returned a TWAP without a twapId.')
     }
     const { state } = raw
-    const filled = new Big(state.executedSz)
+    const remainingSize = safeSubtractDecimalString(state.sz, state.executedSz)
+    if (remainingSize === undefined) {
+      return skipOrder(market.id, 'executedSz', state.executedSz)
+    }
+    const createdAt = rowTimestampToIsoStringOrUndefined(state.timestamp)
+    if (createdAt === undefined) {
+      return skipOrder(market.id, 'timestamp', state.timestamp)
+    }
+    const updatedAt = rowTimestampToIsoStringOrUndefined(raw.time * 1000)
+    if (updatedAt === undefined) {
+      return skipOrder(market.id, 'time', raw.time)
+    }
     let status: OrderStatus
     switch (raw.status.status) {
       case 'activated':
-        status = filled.gt(0) ? OrderStatus.PARTIALLY_FILLED : OrderStatus.OPEN
+        status =
+          safeIsDecimalStringGreaterThan(state.executedSz, '0') === true
+            ? OrderStatus.PARTIALLY_FILLED
+            : OrderStatus.OPEN
         break
       case 'waitingForTrigger':
         status = OrderStatus.OPEN
@@ -128,35 +198,54 @@ export const mapOrder = (
           `Unknown Hyperliquid TWAP status: ${raw.status.status}`
         )
     }
+    const averagePrice =
+      safeIsDecimalStringZero(state.executedSz) === false
+        ? safeDivideDecimalString(state.executedNtl, state.executedSz)
+        : undefined
     return {
       orderId: String(raw.twapId),
       market,
       type: OrderType.TWAP,
       side: state.side === 'B' ? OrderSide.BUY : OrderSide.SELL,
       originalSize: state.sz,
-      remainingSize: new Big(state.sz).minus(filled).toFixed(),
+      remainingSize,
       filledSize: state.executedSz,
-      ...(filled.eq(0)
-        ? {}
-        : { averagePrice: new Big(state.executedNtl).div(filled).toFixed() }),
+      ...(averagePrice === undefined ? {} : { averagePrice }),
       reduceOnly: state.reduceOnly,
       status,
       ...(status === OrderStatus.CANCELLED || status === OrderStatus.REJECTED
         ? { statusReason: raw.status.description ?? raw.status.status }
         : {}),
-      createdAt: new Date(state.timestamp).toISOString(),
-      updatedAt: new Date(raw.time * 1000).toISOString(),
-      startedAt: new Date(state.timestamp).toISOString(),
+      createdAt,
+      updatedAt,
+      startedAt: createdAt,
       durationSeconds: state.minutes * 60,
     }
   }
   const o = 'order' in raw ? raw.order : raw
   const venueStatus = 'order' in raw ? raw.status : 'open'
-  const filled = new Big(o.origSz).minus(o.sz)
+  const filledSize = safeSubtractDecimalString(o.origSz, o.sz)
+  if (filledSize === undefined) {
+    return isDecimalString(o.origSz)
+      ? skipOrder(market.id, 'sz', o.sz)
+      : skipOrder(market.id, 'origSz', o.origSz)
+  }
+  const createdAt = rowTimestampToIsoStringOrUndefined(o.timestamp)
+  if (createdAt === undefined) {
+    return skipOrder(market.id, 'timestamp', o.timestamp)
+  }
+  const statusTimestamp = 'order' in raw ? raw.statusTimestamp : o.timestamp
+  const updatedAt = rowTimestampToIsoStringOrUndefined(statusTimestamp)
+  if (updatedAt === undefined) {
+    return skipOrder(market.id, 'statusTimestamp', statusTimestamp)
+  }
   let status = mapOrderStatus(venueStatus)
   if (parentOrderId !== undefined && !('order' in raw)) {
     status = OrderStatus.PENDING
-  } else if (status === OrderStatus.OPEN && filled.gt(0)) {
+  } else if (
+    status === OrderStatus.OPEN &&
+    isDecimalStringGreaterThan(filledSize, '0')
+  ) {
     status = OrderStatus.PARTIALLY_FILLED
   }
   const base: OrderBase = {
@@ -170,13 +259,11 @@ export const mapOrder = (
       : {}),
     originalSize: o.origSz,
     remainingSize: o.sz,
-    filledSize: filled.toFixed(),
+    filledSize,
     reduceOnly: o.reduceOnly,
     ...(parentOrderId === undefined ? {} : { parentOrderId }),
-    createdAt: new Date(o.timestamp).toISOString(),
-    updatedAt: new Date(
-      'order' in raw ? raw.statusTimestamp : o.timestamp
-    ).toISOString(),
+    createdAt,
+    updatedAt,
   }
   let type = mapOrderType(o.orderType)
   if (o.isTrigger && (type === OrderType.MARKET || type === OrderType.LIMIT)) {

package/src/utils/mapPosition.ts

@@ -1,8 +1,32 @@
+import {
+  absDecimalString,
+  createWarnOnce,
+  isDecimalString,
+  isDecimalStringGreaterThan,
+  isDecimalStringZero,
+  safeAbsDecimalString,
+  safeDivideDecimalString,
+  safeIsDecimalStringZero,
+  safeNumberToDecimalString,
+  safeSubtractDecimalString,
+  warnSkippedVenueRow,
+} from '@lifi/perps-sdk'
 import type { PerpsMarketDisplay, Position } from '@lifi/perps-types'
 import { MarginMode, PositionSide } from '@lifi/perps-types'
-import Big from 'big.js'
+import { PROVIDER_KEY } from '../constants.js'
 import type { HlAssetPosition } from '../types/index.js'
 
+const warnNonPositiveLeverageOnce = createWarnOnce()
+
+const skipPosition = (
+  marketId: string,
+  field: string,
+  value: unknown
+): undefined => {
+  warnSkippedVenueRow(PROVIDER_KEY, 'position', field, value, { marketId })
+  return undefined
+}
+
 /**
  * True when the assetPosition has non-zero size. Hyperliquid keeps zero-size
  * rows in clearinghouse states after a close; both the REST and WS positions
@@ -10,39 +34,73 @@ import type { HlAssetPosition } from '../types/index.js'
  * @public
  */
 export const isOpenAssetPosition = (ap: HlAssetPosition): boolean =>
-  Number.parseFloat(ap.position.szi) !== 0
+  safeIsDecimalStringZero(ap.position.szi) !== true
 
 /**
  * Map a non-zero Hyperliquid position payload to the SDK's normalized
  * position. Signed wire size determines side; decimal strings remain strings
  * in the normalized response. `cumFunding.sinceOpen` is negated because
  * Hyperliquid signs funding paid as positive and `accruedFunding` signs it as
- * negative.
+ * negative. A row with an invalid size gives `undefined`; an invalid position
+ * value, a non-positive leverage or an invalid funding leaves the derived field
+ * absent.
  * @public
  */
 export const mapPosition = (
   ap: HlAssetPosition,
   market: PerpsMarketDisplay
-): Position => {
+): Position | undefined => {
   const pos = ap.position
-  const szi = new Big(pos.szi)
-  const positionValue = new Big(pos.positionValue).abs()
-  const leverage = new Big(pos.leverage.value)
+  if (!isDecimalString(pos.szi)) {
+    return skipPosition(market.id, 'szi', pos.szi)
+  }
+  const size = absDecimalString(pos.szi)
+  const positionValue = safeAbsDecimalString(pos.positionValue)
+  const markPrice =
+    positionValue === undefined
+      ? undefined
+      : isDecimalStringZero(size)
+        ? '0'
+        : safeDivideDecimalString(positionValue, size)
+  const accruedFunding = safeSubtractDecimalString(
+    '0',
+    pos.cumFunding.sinceOpen
+  )
+  const venueLeverage = safeNumberToDecimalString(pos.leverage.value)
+  const leverage =
+    venueLeverage !== undefined &&
+    isDecimalStringGreaterThan(venueLeverage, '0')
+      ? venueLeverage
+      : undefined
+  if (venueLeverage !== undefined && leverage === undefined) {
+    warnNonPositiveLeverageOnce(
+      venueLeverage,
+      `[${PROVIDER_KEY}] position \`leverage.value\` is not positive: '${venueLeverage}'`
+    )
+  }
+  const initialMarginRequirement =
+    positionValue === undefined || leverage === undefined
+      ? undefined
+      : safeDivideDecimalString(positionValue, leverage)
   const marginMode =
     pos.leverage.type === 'cross' ? MarginMode.CROSS : MarginMode.ISOLATED
 
   return {
     market,
-    side: szi.gte(0) ? PositionSide.LONG : PositionSide.SHORT,
-    size: szi.abs().toFixed(),
+    side: isDecimalStringGreaterThan('0', pos.szi)
+      ? PositionSide.SHORT
+      : PositionSide.LONG,
+    size,
     entryPrice: pos.entryPx ?? '0',
-    markPrice: szi.eq(0) ? '0' : positionValue.div(szi.abs()).toFixed(),
-    liquidationPrice: pos.liquidationPx ?? '0',
+    ...(markPrice === undefined ? {} : { markPrice }),
+    liquidationPrice: pos.liquidationPx || '0',
     unrealizedPnl: pos.unrealizedPnl,
-    accruedFunding: new Big(pos.cumFunding.sinceOpen).neg().toFixed(),
-    leverage: ap.position.leverage.value,
+    ...(accruedFunding === undefined ? {} : { accruedFunding }),
+    ...(leverage === undefined ? {} : { leverage }),
     marginUsed: pos.marginUsed,
-    initialMarginRequirement: positionValue.div(leverage).toFixed(),
+    ...(initialMarginRequirement === undefined
+      ? {}
+      : { initialMarginRequirement }),
     marginMode,
   }
 }

package/src/utils/rowTimestamp.ts

@@ -0,0 +1,15 @@
+import { timestampToIsoString } from '@lifi/perps-sdk'
+
+/**
+ * Read a venue row time as an ISO-8601 string, or `undefined` when the time is
+ * not valid. The caller logs the row skip, so this logs nothing.
+ */
+export const rowTimestampToIsoStringOrUndefined = (
+  value: string | number
+): string | undefined => {
+  try {
+    return timestampToIsoString(value)
+  } catch {
+    return undefined
+  }
+}

package/src/utils/spotBalance.ts

@@ -1,5 +1,9 @@
-import { numberToDecimalString, parseDecimal } from '@lifi/perps-sdk'
-import type { Asset, Balance, Market } from '@lifi/perps-types'
+import {
+  isDecimalString,
+  isDecimalStringGreaterThan,
+  multiplyDecimalString,
+} from '@lifi/perps-sdk'
+import type { Asset, Balance, DecimalString, Market } from '@lifi/perps-types'
 import { SPOT_MARKET_ID } from '../constants.js'
 import type { HlSpotBalance } from '../types/index.js'
 import { spotLogoURI } from './assetLogo.js'
@@ -7,23 +11,24 @@ import { coinAsset } from './marketDisplay.js'
 
 /**
  * Build USD prices keyed by spot token asset ID. Base tokens use the supplied
- * market mark price; quote tokens default to exactly `$1`; missing base prices
- * default to `0`.
+ * market mark price; quote tokens default to exactly `$1`; missing or invalid
+ * base prices default to `0`.
  * @public
  */
 export const spotPriceById = (
   markets: readonly Market[],
-  priceByMarketId: ReadonlyMap<string, number>
-): Map<string, number> => {
-  const map = new Map<string, number>()
+  priceByMarketId: ReadonlyMap<string, DecimalString>
+): Map<string, DecimalString> => {
+  const map = new Map<string, DecimalString>()
   for (const m of markets) {
     if (m.categoryId === SPOT_MARKET_ID) {
-      map.set(m.baseAsset.id, priceByMarketId.get(m.id) ?? 0)
+      const price = priceByMarketId.get(m.id)
+      map.set(m.baseAsset.id, isDecimalString(price) ? price : '0')
     }
   }
   for (const m of markets) {
     if (!map.has(m.quoteAsset.id)) {
-      map.set(m.quoteAsset.id, 1)
+      map.set(m.quoteAsset.id, '1')
     }
   }
   return map
@@ -44,18 +49,16 @@ export const spotAssetFromToken = (b: HlSpotBalance): Asset => ({
 /** Assemble a typed spot {@link Balance}; `total` is native token units and its unit price and USD value use `priceById`. @public */
 export const spotBalance = (
   asset: Asset,
-  total: string,
-  priceById: Map<string, number>
+  total: DecimalString,
+  priceById: ReadonlyMap<string, DecimalString>
 ): Balance => {
-  const price = priceById.get(asset.id) ?? 0
+  const price = priceById.get(asset.id) ?? '0'
   return {
     categoryId: SPOT_MARKET_ID,
     asset,
     units: total,
-    valueUsd: numberToDecimalString(
-      (parseDecimal(total) ?? Number.NaN) * price
-    ),
+    valueUsd: multiplyDecimalString(total, price),
     // A zero entry means the map holds no mark for the asset, not a free asset.
-    ...(price > 0 ? { price: numberToDecimalString(price) } : {}),
+    ...(isDecimalStringGreaterThan(price, '0') ? { price } : {}),
   }
 }

package/src/utils/spotCollateral.ts

@@ -1,5 +1,9 @@
+import {
+  isDecimalStringGreaterThan,
+  unknownToDecimalString,
+} from '@lifi/perps-sdk'
 import type { Balance } from '@lifi/perps-types'
-import { toWireBig } from './decimal.js'
+import { PROVIDER_KEY } from '../constants.js'
 
 /**
  * Result of {@link partitionSpotBalances}: balances that count toward
@@ -24,7 +28,16 @@ export const partitionSpotBalances = (
   const collateralBalances: Balance[] = []
   const balances: Balance[] = []
   for (const balance of spotBalances) {
-    if (!toWireBig(balance.units, 'spotBalance.units').gt(0)) {
+    if (
+      !isDecimalStringGreaterThan(
+        unknownToDecimalString(
+          balance.units,
+          'spotBalance.units',
+          PROVIDER_KEY
+        ),
+        '0'
+      )
+    ) {
       continue
     }
     if (quoteAssetIds.has(balance.asset.id)) {

package/src/utils/transferMargin.ts

@@ -1,32 +1,49 @@
 import {
+  isDecimalString,
+  isDecimalStringGreaterThan,
+  multiplyDecimalString,
   PerpsError,
   positionSupportsMarginAdjustment,
   positionSupportsMarginRemoval,
-  validateDecimalString,
+  roundDecimalString,
+  subtractDecimalString,
 } from '@lifi/perps-sdk'
 import {
   type DecimalString,
   PerpsErrorCode,
   type Position,
 } from '@lifi/perps-types'
-import Big from 'big.js'
 
 const NOTIONAL_FLOOR_RATIO = '0.1'
 const AMOUNT_DECIMALS = 6
 
-function positionAmount(value: DecimalString, field: string): Big {
-  return new Big(validateDecimalString(value, `Position.${field}`))
+function requirePositionAmount(
+  value: DecimalString,
+  field: string
+): DecimalString {
+  if (!isDecimalString(value)) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `Invalid \`Position.${field}\`: '${value}' does not match the decimal pattern.`
+    )
+  }
+  return value
 }
 
-function positivePositionAmount(value: DecimalString, field: string): Big {
-  const amount = positionAmount(value, field)
-  if (amount.lte(0)) {
+function requirePositivePositionAmount(
+  value: DecimalString | undefined,
+  field: string
+): DecimalString {
+  if (
+    value === undefined ||
+    !isDecimalStringGreaterThan(requirePositionAmount(value, field), '0')
+  ) {
     throw new PerpsError(
       PerpsErrorCode.ValidationError,
       `Position.${field} must be greater than zero.`
     )
   }
-  return amount
+  return value
 }
 
 /**
@@ -40,7 +57,8 @@ function positivePositionAmount(value: DecimalString, field: string): Big {
  *   margin adjustment; `'0'` for add-only strict-isolated markets and when
  *   nothing is removable.
  * @throws {PerpsError} `ValidationError` when a required `Position` decimal
- *   is malformed, or when a size, price or requirement is not positive.
+ *   is absent or malformed, or when a size, price or requirement is not
+ *   positive.
  * @see https://hyperliquid.gitbook.io/hyperliquid-docs/trading/margining
  * @public
  */
@@ -53,21 +71,25 @@ export function positionRemovableMargin(
   if (!positionSupportsMarginRemoval(position)) {
     return '0'
   }
-  const marginUsed = positionAmount(position.marginUsed, 'marginUsed')
-  const initialMargin = positivePositionAmount(
+  const marginUsed = requirePositionAmount(position.marginUsed, 'marginUsed')
+  const initialMargin = requirePositivePositionAmount(
     position.initialMarginRequirement,
     'initialMarginRequirement'
   )
-  const notionalFloor = positivePositionAmount(position.size, 'size')
-    .times(positivePositionAmount(position.markPrice, 'markPrice'))
-    .times(NOTIONAL_FLOOR_RATIO)
-  const minimumMargin = initialMargin.gt(notionalFloor)
+  const notionalFloor = multiplyDecimalString(
+    multiplyDecimalString(
+      requirePositivePositionAmount(position.size, 'size'),
+      requirePositivePositionAmount(position.markPrice, 'markPrice')
+    ),
+    NOTIONAL_FLOOR_RATIO
+  )
+  const minimumMargin = isDecimalStringGreaterThan(initialMargin, notionalFloor)
     ? initialMargin
     : notionalFloor
 
-  const removable = marginUsed.minus(minimumMargin)
-  if (removable.lte(0)) {
+  const removable = subtractDecimalString(marginUsed, minimumMargin)
+  if (!isDecimalStringGreaterThan(removable, '0')) {
     return '0'
   }
-  return removable.round(AMOUNT_DECIMALS, Big.roundDown).toFixed()
+  return roundDecimalString(removable, AMOUNT_DECIMALS, 'truncate')
 }

package/src/utils/venueTotals.ts

@@ -1,6 +1,16 @@
-import type { HyperliquidMarginSummary, Position } from '@lifi/perps-types'
-import Big from 'big.js'
-import { toWireBig } from './decimal.js'
+import {
+  addDecimalString,
+  addDecimalStrings,
+  createWarnOnce,
+  isDecimalString,
+  unknownToDecimalString,
+} from '@lifi/perps-sdk'
+import type {
+  DecimalString,
+  HyperliquidMarginSummary,
+  Position,
+} from '@lifi/perps-types'
+import { PROVIDER_KEY } from '../constants.js'
 
 /**
  * One perps sub-dex entry {@link perpsTotals} reads. The REST response always
@@ -15,34 +25,58 @@ export interface DexMarginSummary {
  * Sum the venue `marginSummary` totals over every perps sub-dex of an
  * account. `accountValue` is total equity, so it already carries locked
  * margin and unrealized PnL. An entry without a `marginSummary` adds nothing.
+ * @throws {PerpsError} `SDKError` when a venue figure is not a decimal.
  * @public
  */
 export const perpsTotals = (
   dexStates: readonly DexMarginSummary[]
-): { accountValue: Big; marginUsed: Big } => {
-  let accountValue = new Big(0)
-  let marginUsed = new Big(0)
+): { accountValue: DecimalString; marginUsed: DecimalString } => {
+  let accountValue = '0'
+  let marginUsed = '0'
   for (const { marginSummary } of dexStates) {
     if (marginSummary === undefined) {
       continue
     }
-    accountValue = accountValue.plus(
-      toWireBig(marginSummary.accountValue, 'marginSummary.accountValue')
+    accountValue = addDecimalString(
+      accountValue,
+      unknownToDecimalString(
+        marginSummary.accountValue,
+        'marginSummary.accountValue',
+        PROVIDER_KEY
+      )
     )
-    marginUsed = marginUsed.plus(
-      toWireBig(marginSummary.totalMarginUsed, 'marginSummary.totalMarginUsed')
+    marginUsed = addDecimalString(
+      marginUsed,
+      unknownToDecimalString(
+        marginSummary.totalMarginUsed,
+        'marginSummary.totalMarginUsed',
+        PROVIDER_KEY
+      )
     )
   }
   return { accountValue, marginUsed }
 }
 
+const warnSkippedTermOnce = createWarnOnce()
+
 /**
- * Sum the unrealized PnL of every position, in quote-asset units.
+ * Sum the unrealized PnL of every position, in quote-asset units. A term that
+ * does not match the decimal pattern adds nothing and warns once.
  * @public
  */
-export const sumUnrealizedPnl = (positions: readonly Position[]): Big =>
-  positions.reduce(
-    (sum, position) =>
-      sum.plus(toWireBig(position.unrealizedPnl, 'position.unrealizedPnl')),
-    new Big(0)
-  )
+export const sumUnrealizedPnl = (
+  positions: readonly Position[]
+): DecimalString => {
+  const terms: DecimalString[] = []
+  for (const { unrealizedPnl } of positions) {
+    if (isDecimalString(unrealizedPnl)) {
+      terms.push(unrealizedPnl)
+      continue
+    }
+    warnSkippedTermOnce(
+      `${PROVIDER_KEY}|position.unrealizedPnl`,
+      `[${PROVIDER_KEY}] skipping a \`position.unrealizedPnl\` term that does not match the decimal pattern: '${String(unrealizedPnl).slice(0, 64)}'`
+    )
+  }
+  return addDecimalStrings(terms)
+}