@lifi/perps-sdk-provider-hyperliquid 26.0.0 → 27.0.1

package/src/utils/mapOrder.ts

@@ -1,13 +1,14 @@
 import {
+  createWarnOnce,
+  isDecimalString,
   isDecimalStringGreaterThan,
+  type MarketRegistry,
   PerpsError,
   safeDivideDecimalString,
   safeIsDecimalStringGreaterThan,
   safeIsDecimalStringZero,
   safeSubtractDecimalString,
-  subtractDecimalString,
   triggerConditionFor,
-  unknownToDecimalString,
   warnSkippedVenueRow,
 } from '@lifi/perps-sdk'
 import type {
@@ -29,6 +30,7 @@ import type {
   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. */
@@ -98,15 +100,42 @@ export const mapOrderStatus = (status: string): OrderStatus => {
   }
 }
 
-const skipOrder = (field: string, value: unknown): undefined => {
-  warnSkippedVenueRow(PROVIDER_KEY, 'order', field, value)
+const skipOrder = (
+  marketId: string,
+  field: string,
+  value: unknown
+): undefined => {
+  warnSkippedVenueRow(PROVIDER_KEY, 'order', field, value, { marketId })
   return undefined
 }
 
-const venueDecimal = (value: unknown, field: string): string | 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 unknownToDecimalString(value, field, PROVIDER_KEY)
-  } catch {
+    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
   }
 }
@@ -133,15 +162,15 @@ export const mapOrder = (
     const { state } = raw
     const remainingSize = safeSubtractDecimalString(state.sz, state.executedSz)
     if (remainingSize === undefined) {
-      return skipOrder('executedSz', state.executedSz)
+      return skipOrder(market.id, 'executedSz', state.executedSz)
     }
     const createdAt = rowTimestampToIsoStringOrUndefined(state.timestamp)
     if (createdAt === undefined) {
-      return skipOrder('timestamp', state.timestamp)
+      return skipOrder(market.id, 'timestamp', state.timestamp)
     }
     const updatedAt = rowTimestampToIsoStringOrUndefined(raw.time * 1000)
     if (updatedAt === undefined) {
-      return skipOrder('time', raw.time)
+      return skipOrder(market.id, 'time', raw.time)
     }
     let status: OrderStatus
     switch (raw.status.status) {
@@ -195,23 +224,20 @@ export const mapOrder = (
   }
   const o = 'order' in raw ? raw.order : raw
   const venueStatus = 'order' in raw ? raw.status : 'open'
-  const originalSize = venueDecimal(o.origSz, 'origSz')
-  if (originalSize === undefined) {
-    return skipOrder('origSz', o.origSz)
-  }
-  const remainingSize = venueDecimal(o.sz, 'sz')
-  if (remainingSize === undefined) {
-    return skipOrder('sz', 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 filledSize = subtractDecimalString(originalSize, remainingSize)
   const createdAt = rowTimestampToIsoStringOrUndefined(o.timestamp)
   if (createdAt === undefined) {
-    return skipOrder('timestamp', o.timestamp)
+    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('statusTimestamp', statusTimestamp)
+    return skipOrder(market.id, 'statusTimestamp', statusTimestamp)
   }
   let status = mapOrderStatus(venueStatus)
   if (parentOrderId !== undefined && !('order' in raw)) {

package/src/utils/mapPosition.ts

@@ -18,8 +18,12 @@ import type { HlAssetPosition } from '../types/index.js'
 
 const warnNonPositiveLeverageOnce = createWarnOnce()
 
-const skipPosition = (field: string, value: unknown): undefined => {
-  warnSkippedVenueRow(PROVIDER_KEY, 'position', field, value)
+const skipPosition = (
+  marketId: string,
+  field: string,
+  value: unknown
+): undefined => {
+  warnSkippedVenueRow(PROVIDER_KEY, 'position', field, value, { marketId })
   return undefined
 }
 
@@ -48,7 +52,7 @@ export const mapPosition = (
 ): Position | undefined => {
   const pos = ap.position
   if (!isDecimalString(pos.szi)) {
-    return skipPosition('szi', pos.szi)
+    return skipPosition(market.id, 'szi', pos.szi)
   }
   const size = absDecimalString(pos.szi)
   const positionValue = safeAbsDecimalString(pos.positionValue)
@@ -89,7 +93,7 @@ export const mapPosition = (
     size,
     entryPrice: pos.entryPx ?? '0',
     ...(markPrice === undefined ? {} : { markPrice }),
-    liquidationPrice: pos.liquidationPx ?? '0',
+    liquidationPrice: pos.liquidationPx || '0',
     unrealizedPnl: pos.unrealizedPnl,
     ...(accruedFunding === undefined ? {} : { accruedFunding }),
     ...(leverage === undefined ? {} : { leverage }),

package/src/utils/spotBalance.ts

@@ -38,12 +38,19 @@ export const spotPriceById = (
  * Convert a Hyperliquid spot balance's numeric token index into an SDK asset.
  * The balance payload has no `fullName`, so logo resolution uses the base
  * `_spot` URI rule rather than Unit-underlying lookup.
+ * @param registered - The registry `Asset` with the same `id`; only its `decimals` is copied.
  * @public
  */
-export const spotAssetFromToken = (b: HlSpotBalance): Asset => ({
+export const spotAssetFromToken = (
+  b: HlSpotBalance,
+  registered?: Asset
+): Asset => ({
   ...coinAsset(b.coin),
   id: String(b.token),
   logoURI: spotLogoURI(b.coin),
+  ...(registered?.decimals === undefined
+    ? {}
+    : { decimals: registered.decimals }),
 })
 
 /** Assemble a typed spot {@link Balance}; `total` is native token units and its unit price and USD value use `priceById`. @public */

package/src/utils/transferMargin.ts

@@ -24,7 +24,7 @@ function requirePositionAmount(
   if (!isDecimalString(value)) {
     throw new PerpsError(
       PerpsErrorCode.ValidationError,
-      `Invalid \`Position.${field}\`: '${value}' is not a decimal string.`
+      `Invalid \`Position.${field}\`: '${value}' does not match the decimal pattern.`
     )
   }
   return value

package/src/utils/venueTotals.ts

@@ -1,6 +1,8 @@
 import {
   addDecimalString,
-  safeAddDecimalString,
+  addDecimalStrings,
+  createWarnOnce,
+  isDecimalString,
   unknownToDecimalString,
 } from '@lifi/perps-sdk'
 import type {
@@ -55,35 +57,26 @@ export const perpsTotals = (
   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[]
-): DecimalString =>
-  positions.reduce(
-    (sum, position) =>
-      addDecimalString(
-        sum,
-        unknownToDecimalString(
-          position.unrealizedPnl,
-          'position.unrealizedPnl',
-          PROVIDER_KEY
-        )
-      ),
-    '0'
-  )
-
-/**
- * Sum every term, or `undefined` with a warning when any term is not a
- * decimal string. A bad term never gives a partial sum.
- */
-export const safeSumDecimalStrings = (
-  terms: readonly string[]
-): DecimalString | undefined =>
-  terms.reduce<DecimalString | undefined>(
-    (sum, term) =>
-      sum === undefined ? undefined : safeAddDecimalString(sum, term),
-    '0'
-  )
+): 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)
+}

package/src/utils/withdrawableBalances.ts

@@ -25,8 +25,8 @@ import { assetIsOutcome } from './assetId.js'
  * @param withdrawalFee - Flat venue fee in quote-asset units, set on every
  *   quote-asset row. Hyperliquid deducts it from the requested amount. Absent
  *   leaves every row without a fee.
- * @throws {PerpsError} `SDKError` when the fee or a venue figure is not a
- * decimal.
+ * @throws {PerpsError} `SDKError` when the fee or a venue figure does not match the
+ * decimal pattern.
  * @public
  */
 export const hyperliquidWithdrawableBalances = (

package/src/websocket/HyperliquidWsProvider.ts

@@ -1,13 +1,14 @@
 import {
+  type AssetRegistry,
   addDecimalString,
   calculateTransferable,
   compareDecimalStrings,
   DecodeChain,
+  getAssetRegistry,
   getMarketRegistry,
   isActiveMarket,
   isActiveOrderStatus,
   isDecimalString,
-  isDecimalStringGreaterThan,
   isDecimalStringZero,
   type MarketRegistry,
   PerpsError,
@@ -24,6 +25,7 @@ import {
   safeIsDecimalStringZero,
   safeMultiplyDecimalString,
   safeNumberToDecimalString,
+  safeSubtractDecimalString,
   subtractDecimalString,
   toAssetDisplay,
   toPerpsMarketDisplay,
@@ -100,6 +102,7 @@ import {
   spotPriceById,
   sumUnrealizedPnl,
 } from '../utils/index.js'
+import { mapOrderRow } from '../utils/mapOrder.js'
 
 /** HL's compact `l2` snapshot carries 20 levels per side. */
 const HL_L2_BOOK_MAX_LEVELS_PER_SIDE = 20
@@ -153,6 +156,7 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
   private readonly clearinghouseRefs = new Map<string, number>()
   private readonly client: PerpsSDKClient | undefined
   private readonly registry: MarketRegistry | undefined
+  private readonly assetRegistry: AssetRegistry | undefined
   private readonly accountChecksByUser = new Map<string, Promise<void>>()
   // Spot-funded modes need both spot valuation and clearinghouse margin state.
   private readonly abstractionByUser = new Map<
@@ -241,6 +245,7 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
     )
     this.client = client
     this.registry = client && getMarketRegistry(client, providerKey)
+    this.assetRegistry = client && getAssetRegistry(client, providerKey)
     const orderApiUrl = new URL(wsUrl)
     orderApiUrl.protocol = orderApiUrl.protocol === 'wss:' ? 'https:' : 'http:'
     this.orderApiUrl = orderApiUrl.origin
@@ -973,7 +978,7 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
 
   /** Latest mid per `Market.id` across asset-context and fast feeds. */
   /** Latest mid per `Market.id` across asset-context and fast feeds; a mid
-   * that is not a decimal string is left out. */
+   * that does not match the decimal pattern is left out. */
   private mergedMids(): Map<string, DecimalString> {
     const map = new Map<string, DecimalString>()
     const setMid = (id: string, mid: string | number | null | undefined) => {
@@ -1017,10 +1022,10 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
       provider: this.providerKey,
       marketId: data.coin,
       bids: data.levels[0]
-        .flatMap((l) => toOrderbookLevel(l.px, l.sz))
+        .flatMap((l) => toOrderbookLevel(data.coin, l.px, l.sz))
         .slice(0, HL_L2_BOOK_MAX_LEVELS_PER_SIDE),
       asks: data.levels[1]
-        .flatMap((l) => toOrderbookLevel(l.px, l.sz))
+        .flatMap((l) => toOrderbookLevel(data.coin, l.px, l.sz))
         .slice(0, HL_L2_BOOK_MAX_LEVELS_PER_SIDE),
       timestamp: data.time,
     }
@@ -1064,12 +1069,14 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
       provider: this.providerKey,
       marketId: delta.c,
       bids: applyCompressedL2Side(
+        delta.c,
         previous.bids,
         delta.l[0],
         delta.r?.[0] ?? [],
         'bid'
       ),
       asks: applyCompressedL2Side(
+        delta.c,
         previous.asks,
         delta.l[1],
         delta.r?.[1] ?? [],
@@ -1141,48 +1148,33 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
       if (epoch !== this.orderUpdatesEpoch || key !== this.orderUpdatesKey) {
         return
       }
+      const user = key.slice('orderUpdates:'.length)
       const mapped = await Promise.all(
         data.map(async (update) => {
           const basic = update.order
-          if (assetIsOutcome(basic.coin)) {
+          if (
+            assetIsOutcome(basic.coin) ||
+            this.registry?.get(basic.coin) === undefined
+          ) {
             return undefined
           }
-          const market = this.registry?.get(basic.coin)
-          if (market === undefined) {
+          let detail: HlOrderDetail
+          try {
+            detail = await this.readOrderDetail(user, client, update)
+          } catch (error) {
+            if (!(error instanceof PerpsError)) {
+              throw error
+            }
+            wsLog.droppedRow(
+              this.providerKey,
+              'order',
+              `${basic.oid}: ${error.message}`
+            )
             return undefined
           }
-          const response = await infoRequest<HlOrderStatusResponse>(
-            this.orderApiUrl,
-            {
-              type: 'orderStatus',
-              user: key.slice('orderUpdates:'.length),
-              oid: basic.oid,
-            },
-            hlInfoOptions(client)
+          return mapOrderRow(basic.coin, this.registry, (resolved) =>
+            mapOrder(detail, resolved)
           )
-          if (response.status !== 'order') {
-            throw new PerpsError(
-              PerpsErrorCode.OrderNotFound,
-              `Hyperliquid order metadata not found: ${basic.oid}`
-            )
-          }
-          // REST supplies execution metadata; the stream owns this event's lifecycle and quantities.
-          const detail: HlOrderDetail = {
-            status: update.status,
-            statusTimestamp: update.statusTimestamp,
-            order: {
-              ...response.order.order,
-              coin: basic.coin,
-              side: basic.side,
-              limitPx: basic.limitPx,
-              sz: basic.sz,
-              oid: basic.oid,
-              timestamp: basic.timestamp,
-              origSz: basic.origSz,
-              cloid: basic.cloid ?? response.order.order.cloid,
-            },
-          }
-          return mapOrder(detail, market)
         })
       )
       if (epoch !== this.orderUpdatesEpoch || key !== this.orderUpdatesKey) {
@@ -1203,6 +1195,41 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
     })
   }
 
+  // REST supplies execution metadata; the stream owns this event's lifecycle and quantities.
+  private async readOrderDetail(
+    user: string,
+    client: PerpsSDKClient,
+    update: HlWsOrder
+  ): Promise<HlOrderDetail> {
+    const basic = update.order
+    const response = await infoRequest<HlOrderStatusResponse>(
+      this.orderApiUrl,
+      { type: 'orderStatus', user, oid: basic.oid },
+      hlInfoOptions(client)
+    )
+    if (response.status !== 'order') {
+      throw new PerpsError(
+        PerpsErrorCode.OrderNotFound,
+        `Hyperliquid order metadata not found: ${basic.oid}`
+      )
+    }
+    return {
+      status: update.status,
+      statusTimestamp: update.statusTimestamp,
+      order: {
+        ...response.order.order,
+        coin: basic.coin,
+        side: basic.side,
+        limitPx: basic.limitPx,
+        sz: basic.sz,
+        oid: basic.oid,
+        timestamp: basic.timestamp,
+        origSz: basic.origSz,
+        cloid: basic.cloid ?? response.order.order.cloid,
+      },
+    }
+  }
+
   private handleUserFills(data: HlWsUserFillsData) {
     // The snapshot frame carries up to ~2000 historical fills and is replayed
     // on every reconnect via `replaySubs`; emitting them would surface old
@@ -1308,6 +1335,7 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
       }
     }
     try {
+      await this.assetRegistry?.sync()
       if (count === 0) {
         await this.registerSub(wireKey, payload)
       }
@@ -1552,15 +1580,10 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
     const priceById = spotPriceById(markets, this.mergedMids())
     const balances = data.spotState.balances
       .filter((balance) => !assetIsOutcome(balance.coin))
-      .map((balance) => ({
-        balance,
-        total: unknownToDecimalString(
-          balance.total,
-          'spotState.balances.total',
-          this.providerKey
-        ),
-      }))
-      .filter(({ total }) => isDecimalStringGreaterThan(total, '0'))
+      .filter(
+        (balance) => safeIsDecimalStringGreaterThan(balance.total, '0') === true
+      )
+      .map((balance) => ({ balance, total: balance.total }))
     const pipeline = this.unifiedSummaryByUser.get(user)
     // Known spot markets await a price; unlisted tokens keep their unpriced balance.
     if (
@@ -1574,21 +1597,22 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
       }
       return
     }
-    const rows = balances.map(({ balance, total }) => ({
-      ...spotBalance(spotAssetFromToken(balance), total, priceById),
-      locked: balance.hold,
-      transferable: calculateTransferable(
-        subtractDecimalString(
+    const rows = balances.map(({ balance, total }) => {
+      const free = safeSubtractDecimalString(total, balance.hold)
+      return {
+        ...spotBalance(
+          spotAssetFromToken(
+            balance,
+            this.assetRegistry?.get(String(balance.token))
+          ),
           total,
-          unknownToDecimalString(
-            balance.hold,
-            'spotState.balances.hold',
-            this.providerKey
-          )
+          priceById
         ),
-        total
-      ),
-    }))
+        locked: balance.hold,
+        transferable:
+          free === undefined ? '0' : calculateTransferable(free, total),
+      }
+    })
     this.emit(`spotState:${user}`, {
       channel: 'spotBalances',
       data: rows,
@@ -1776,27 +1800,38 @@ function mapSpotMarketContext(
 const BOOK_LEVEL_ROW = 'order book level'
 
 /** The venue price when it is a decimal string, or `undefined` after a logged skip. */
-function bookLevelPrice(price: string): DecimalString | undefined {
+function bookLevelPrice(
+  marketId: string,
+  price: string
+): DecimalString | undefined {
   if (!isDecimalString(price)) {
-    wsLog.skippedRow(PROVIDER_KEY, BOOK_LEVEL_ROW, 'price', price)
+    wsLog.skippedRow(PROVIDER_KEY, BOOK_LEVEL_ROW, 'price', price, marketId)
     return undefined
   }
   return price
 }
 
 /** The venue size when it is a decimal string, or `undefined` after a logged skip. */
-function bookLevelSize(size: string): DecimalString | undefined {
+function bookLevelSize(
+  marketId: string,
+  size: string
+): DecimalString | undefined {
   if (!isDecimalString(size)) {
-    wsLog.skippedRow(PROVIDER_KEY, BOOK_LEVEL_ROW, 'size', size)
+    wsLog.skippedRow(PROVIDER_KEY, BOOK_LEVEL_ROW, 'size', size, marketId)
     return undefined
   }
   return size
 }
 
 /** One order-book level, or none when the venue price or size is invalid. */
-function toOrderbookLevel(price: string, size: string): OrderbookLevel[] {
-  const levelPrice = bookLevelPrice(price)
-  const levelSize = levelPrice === undefined ? undefined : bookLevelSize(size)
+function toOrderbookLevel(
+  marketId: string,
+  price: string,
+  size: string
+): OrderbookLevel[] {
+  const levelPrice = bookLevelPrice(marketId, price)
+  const levelSize =
+    levelPrice === undefined ? undefined : bookLevelSize(marketId, size)
   return levelPrice === undefined || levelSize === undefined
     ? []
     : [{ price: levelPrice, size: levelSize }]
@@ -1813,6 +1848,7 @@ function compactRemovalPrice(
 }
 
 function applyCompressedL2Side(
+  marketId: string,
   previous: OrderbookLevel[],
   updates: HlWsCompressedL2Data['l'][number],
   removals: NonNullable<HlWsCompressedL2Data['r']>[number],
@@ -1826,11 +1862,11 @@ function applyCompressedL2Side(
     }
   }
   for (const update of updates) {
-    const price = bookLevelPrice(update.p)
+    const price = bookLevelPrice(marketId, update.p)
     if (price === undefined) {
       continue
     }
-    const size = bookLevelSize(update.s)
+    const size = bookLevelSize(marketId, update.s)
     // A level whose new size is unknown must not keep its old size.
     if (size === undefined || safeIsDecimalStringZero(size) !== false) {
       byPrice.delete(price)