@lifi/perps-sdk-provider-hyperliquid 1.5.4 → 1.5.6

package/src/websocket/HyperliquidWsProvider.ts

@@ -61,6 +61,7 @@ import {
   spotBalance,
   spotPriceById,
 } from '../utils/index.js'
+import { DecodeChain } from './decodeChain.js'
 
 /** HL's compact `l2` snapshot carries 20 levels per side. */
 const HL_L2_BOOK_MAX_LEVELS_PER_SIDE = 20
@@ -99,6 +100,7 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
   private readonly registry: MarketRegistry | undefined
   private perpCtxBySubDex = new Map<string, Record<string, HlWsPerpAssetCtx>>()
   private spotCtxByMarketId: Record<string, HlWsSpotAssetCtx> = {}
+  private marketsContextByMarketId: Record<string, MarketContext> = {}
   private orderbookKeysByMarketId = new Map<string, Set<string>>()
   private latestOrderbookByMarketId = new Map<string, OrderbookResponse>()
   // Latest mid/mark per `Market.id` from the high-frequency `fastAssetCtxs`
@@ -106,12 +108,29 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
   // frames carry only changed coins — and overlaid onto asset contexts that
   // carry oracle/funding/OI/metadata.
   private fastCtxByMarketId: Record<string, HlWsFastAssetCtx> = {}
-  // `fastAssetCtxs` payloads are base64 + raw-DEFLATE; decode is async, so
-  // chain decodes to apply incremental frames in arrival order.
-  private fastDecodeChain: Promise<void> = Promise.resolve()
-  private pacDecodeChain: Promise<void> = Promise.resolve()
-  private sacDecodeChain: Promise<void> = Promise.resolve()
-  private orderbookDecodeChain: Promise<void> = Promise.resolve()
+  private readonly reportDecodeFailure = (error: unknown) =>
+    wsLog.handlerFailure(this.providerKey, error)
+  // Compressed payloads (base64 + raw-DEFLATE) decode async, so each channel
+  // chains decodes to apply frames in arrival order. Only the fast feed
+  // coalesces a stall backlog to its newest frame: a coin's dropped tick is
+  // refreshed by its next one. pac/sac field-merges and l2 deltas depend on
+  // every frame, so they must not coalesce.
+  private readonly fastDecodeChain = new DecodeChain(
+    'latest',
+    this.reportDecodeFailure
+  )
+  private readonly pacDecodeChain = new DecodeChain(
+    'every',
+    this.reportDecodeFailure
+  )
+  private readonly sacDecodeChain = new DecodeChain(
+    'every',
+    this.reportDecodeFailure
+  )
+  private readonly orderbookDecodeChain = new DecodeChain(
+    'every',
+    this.reportDecodeFailure
+  )
 
   constructor(wsUrl: string, providerKey: string, client?: PerpsSDKClient) {
     super(
@@ -173,6 +192,7 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
         this.perpCtxBySubDex.clear()
         this.spotCtxByMarketId = {}
         this.fastCtxByMarketId = {}
+        this.marketsContextByMarketId = {}
       }
     }
 
@@ -292,12 +312,13 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
     this.perpCtxBySubDex.clear()
     this.spotCtxByMarketId = {}
     this.fastCtxByMarketId = {}
+    this.marketsContextByMarketId = {}
     this.orderbookKeysByMarketId.clear()
     this.latestOrderbookByMarketId.clear()
-    this.fastDecodeChain = Promise.resolve()
-    this.pacDecodeChain = Promise.resolve()
-    this.sacDecodeChain = Promise.resolve()
-    this.orderbookDecodeChain = Promise.resolve()
+    this.fastDecodeChain.reset()
+    this.pacDecodeChain.reset()
+    this.sacDecodeChain.reset()
+    this.orderbookDecodeChain.reset()
     this.orderUpdatesKey = undefined
   }
 
@@ -483,61 +504,65 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
   }
 
   private handleAllDexsAssetCtxs(data: HlWsAllDexsAssetCtxsData) {
-    this.mergePerpAssetCtxEntries(allDexsAssetCtxEntries(data))
-    this.emitMarketsContext()
+    this.emitMarketsContext(
+      this.mergePerpAssetCtxEntries(allDexsAssetCtxEntries(data))
+    )
   }
 
   private handlePac(base64: string) {
-    this.pacDecodeChain = this.pacDecodeChain
-      .then(async () => {
+    this.pacDecodeChain.push(async () => {
+      this.emitMarketsContext(
         this.mergePerpAssetCtxEntries(
           await decodeCompressedJson<HlWsPacData>(base64)
         )
-        this.emitMarketsContext()
-      })
-      .catch((error) => wsLog.handlerFailure(this.providerKey, error))
+      )
+    })
   }
 
+  /** Merge perp asset contexts in place; returns the marketIds this frame touched. */
   private mergePerpAssetCtxEntries(
     entries: [string, HlWsPerpAssetCtxPayload[]][]
-  ) {
+  ): Set<string> {
+    const touched = new Set<string>()
     for (const [dex, ctxs] of entries) {
-      const previous = this.perpCtxBySubDex.get(dex || 'default')
-      const byMarketId: Record<string, HlWsPerpAssetCtx> = {
-        ...(previous ?? {}),
+      let byMarketId = this.perpCtxBySubDex.get(dex || 'default')
+      if (byMarketId === undefined) {
+        byMarketId = {}
+        this.perpCtxBySubDex.set(dex || 'default', byMarketId)
       }
       for (const ctx of ctxs) {
         const marketId = ctx.coin
         if (marketId === undefined) {
           continue
         }
-        const merged = mergePerpAssetCtx(previous?.[marketId], marketId, ctx)
+        const merged = mergePerpAssetCtx(byMarketId[marketId], marketId, ctx)
         if (merged !== undefined) {
           byMarketId[marketId] = merged
+          touched.add(marketId)
         }
       }
-      this.perpCtxBySubDex.set(dex || 'default', byMarketId)
     }
+    return touched
   }
 
   private handleSac(base64: string) {
-    this.sacDecodeChain = this.sacDecodeChain
-      .then(async () => {
-        const spotMarketIdBySacKey = this.spotMarketIdBySacKey()
-        const ctxs = await decodeCompressedJson<HlWsSacData>(base64)
-        for (const [sacKey, ctx] of Object.entries(ctxs)) {
-          const marketId = spotMarketIdBySacKey.get(sacKey)
-          if (marketId === undefined) {
-            continue
-          }
-          this.spotCtxByMarketId[marketId] = {
-            ...this.spotCtxByMarketId[marketId],
-            ...ctx,
-          }
+    this.sacDecodeChain.push(async () => {
+      const spotMarketIdBySacKey = this.spotMarketIdBySacKey()
+      const ctxs = await decodeCompressedJson<HlWsSacData>(base64)
+      const touched = new Set<string>()
+      for (const [sacKey, ctx] of Object.entries(ctxs)) {
+        const marketId = spotMarketIdBySacKey.get(sacKey)
+        if (marketId === undefined) {
+          continue
         }
-        this.emitMarketsContext()
-      })
-      .catch((error) => wsLog.handlerFailure(this.providerKey, error))
+        this.spotCtxByMarketId[marketId] = {
+          ...this.spotCtxByMarketId[marketId],
+          ...ctx,
+        }
+        touched.add(marketId)
+      }
+      this.emitMarketsContext(touched)
+    })
   }
 
   private spotMarketIdBySacKey(): Map<string, string> {
@@ -559,65 +584,78 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
    * Decode a `fastAssetCtxs` frame (base64 + raw-DEFLATE) and merge its changed
    * coins into the per-market fast-context store. Frames are incremental, so a
    * field absent from this frame keeps its prior value. Decodes are chained to
-   * preserve arrival order across the async boundary.
+   * preserve arrival order across the async boundary; a backlog coalesces to
+   * its newest frame (see the chain's mode).
    */
   private handleFastAssetCtxs(base64: string) {
-    this.fastDecodeChain = this.fastDecodeChain
-      .then(async () => {
-        const ctxs = await decodeFastAssetCtxs(base64)
-        for (const [marketId, ctx] of Object.entries(ctxs)) {
-          const prev = this.fastCtxByMarketId[marketId]
-          this.fastCtxByMarketId[marketId] = {
-            markPx: 'markPx' in ctx ? ctx.markPx : prev?.markPx,
-            midPx: 'midPx' in ctx ? ctx.midPx : prev?.midPx,
-          }
+    this.fastDecodeChain.push(async () => {
+      const ctxs = await decodeFastAssetCtxs(base64)
+      for (const [marketId, ctx] of Object.entries(ctxs)) {
+        const prev = this.fastCtxByMarketId[marketId]
+        this.fastCtxByMarketId[marketId] = {
+          markPx: 'markPx' in ctx ? ctx.markPx : prev?.markPx,
+          midPx: 'midPx' in ctx ? ctx.midPx : prev?.midPx,
         }
-        this.emitMarketsContext()
-      })
-      .catch((error) => wsLog.handlerFailure(this.providerKey, error))
+      }
+      this.emitMarketsContext(Object.keys(ctxs))
+    })
   }
 
   /**
-   * Build the all-markets context map from perp + spot asset contexts, with mid
-   * + mark overlaid from `fastAssetCtxs`.
+   * Emit the all-markets context map, re-mapping only the markets the incoming
+   * frame touched. Each emission is a fresh snapshot object that carries
+   * untouched entries over by reference, so a listener holding an earlier
+   * snapshot never observes later-frame mutation.
    */
-  private emitMarketsContext() {
-    const data: Record<string, MarketContext> = {}
-    for (const byMarketId of this.perpCtxBySubDex.values()) {
-      for (const [marketId, ctx] of Object.entries(byMarketId)) {
-        const base = mapMarketContext(marketId, ctx)
-        const fast = this.fastCtxByMarketId[marketId]
-        data[marketId] = {
-          ...base,
-          midPrice: fast?.midPx != null ? fast.midPx : base.midPrice,
-          markPrice: fast?.markPx != null ? fast.markPx : base.markPrice,
-        }
-      }
+  private emitMarketsContext(touchedMarketIds: Iterable<string>) {
+    const data: Record<string, MarketContext> = {
+      ...this.marketsContextByMarketId,
     }
-    for (const [marketId, ctx] of Object.entries(this.spotCtxByMarketId)) {
-      const context = mapSpotMarketContext(
-        marketId,
-        ctx,
-        this.fastCtxByMarketId[marketId]
-      )
+    for (const marketId of touchedMarketIds) {
+      const context = this.computeMarketContext(marketId)
       if (context === undefined) {
-        continue
+        delete data[marketId]
+      } else {
+        data[marketId] = context
       }
-      data[marketId] = context
     }
-    for (const [marketId, fast] of Object.entries(this.fastCtxByMarketId)) {
-      if (data[marketId] !== undefined) {
-        continue
+    this.marketsContextByMarketId = data
+    this.emit('marketsContext', { channel: 'marketsContext', data })
+  }
+
+  /**
+   * Context for one market from the cached feeds: spot asset context when it
+   * maps, else perp asset context with mid + mark overlaid from
+   * `fastAssetCtxs`, else the fast feed alone — each price standing in for the
+   * other where it carries only one of mid/mark.
+   */
+  private computeMarketContext(marketId: string): MarketContext | undefined {
+    const fast = this.fastCtxByMarketId[marketId]
+    const spotCtx = this.spotCtxByMarketId[marketId]
+    if (spotCtx !== undefined) {
+      const context = mapSpotMarketContext(marketId, spotCtx, fast)
+      if (context !== undefined) {
+        return context
       }
-      // No asset-context frame for this market yet — each price stands in for
-      // the other where the fast feed carries only one of mid/mark.
-      const midPrice = fast.midPx ?? fast.markPx
-      const markPrice = fast.markPx ?? fast.midPx
-      if (midPrice != null && markPrice != null) {
-        data[marketId] = { marketId, midPrice, markPrice }
+    }
+    let perpCtx: HlWsPerpAssetCtx | undefined
+    for (const byMarketId of this.perpCtxBySubDex.values()) {
+      perpCtx = byMarketId[marketId] ?? perpCtx
+    }
+    if (perpCtx !== undefined) {
+      const base = mapMarketContext(marketId, perpCtx)
+      return {
+        ...base,
+        midPrice: fast?.midPx != null ? fast.midPx : base.midPrice,
+        markPrice: fast?.markPx != null ? fast.markPx : base.markPrice,
       }
     }
-    this.emit('marketsContext', { channel: 'marketsContext', data })
+    const midPrice = fast?.midPx ?? fast?.markPx
+    const markPrice = fast?.markPx ?? fast?.midPx
+    if (midPrice != null && markPrice != null) {
+      return { marketId, midPrice, markPrice }
+    }
+    return undefined
   }
 
   private handleActiveAssetCtx(data: HlWsActiveAssetCtxData, raw: string) {
@@ -710,13 +748,11 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
       return
     }
     const compressed = data.c
-    this.orderbookDecodeChain = this.orderbookDecodeChain
-      .then(async () => {
-        this.handleCompactL2Delta(
-          await decodeCompressedJson<HlWsCompressedL2Data>(compressed)
-        )
-      })
-      .catch((error) => wsLog.handlerFailure(this.providerKey, error))
+    this.orderbookDecodeChain.push(async () => {
+      this.handleCompactL2Delta(
+        await decodeCompressedJson<HlWsCompressedL2Data>(compressed)
+      )
+    })
   }
 
   private handleCompactL2Delta(delta: HlWsCompressedL2Data) {
@@ -725,6 +761,14 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
       return
     }
 
+    // Compact deltas decode asynchronously via `orderbookDecodeChain`, so one
+    // can resolve after a newer frame (sync snapshot/update, or a later delta)
+    // has already been applied. A delta no newer than the maintained book is
+    // stale; applying it would overwrite fresher state with older levels.
+    if (delta.t <= previous.timestamp) {
+      return
+    }
+
     const book: OrderbookResponse = {
       provider: this.providerKey,
       marketId: delta.c,
@@ -806,8 +850,7 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
         continue
       }
       const type = mapOrderType(o.orderType)
-      // A miss warns once and schedules a cooldown-gated registry refetch
-      // (the id may have listed after the snapshot); skip just this item.
+      // Unknown market id (absent from the synced snapshot); skip just this item.
       const market = this.registry?.get(o.coin)
       if (!market) {
         continue

package/src/websocket/decodeChain.ts

@@ -0,0 +1,54 @@
+/**
+ * Frame semantics of a {@link DecodeChain}:
+ * - `'every'`: every frame decodes and applies in arrival order — required for
+ *   delta-carrying channels, where dropping a frame corrupts downstream state.
+ * - `'latest'`: frames queued behind an in-flight decode coalesce to the
+ *   newest — for snapshot-like channels, where a newer frame supersedes
+ *   anything still waiting.
+ */
+export type DecodeChainMode = 'every' | 'latest'
+
+/**
+ * Serializes async WS frame decodes so results apply in arrival order.
+ * In `'latest'` mode a backlog (e.g. queued behind a main-thread stall)
+ * collapses to its newest frame instead of replaying every stale decode.
+ * Decode failures are reported to `onError` and never break the chain.
+ */
+export class DecodeChain {
+  private tail: Promise<void> = Promise.resolve()
+  private queued: (() => Promise<void>) | undefined
+
+  constructor(
+    private readonly mode: DecodeChainMode,
+    private readonly onError: (error: unknown) => void
+  ) {}
+
+  push(decode: () => Promise<void>): void {
+    if (this.mode === 'every') {
+      this.tail = this.tail.then(decode).catch(this.onError)
+      return
+    }
+    const drainScheduled = this.queued !== undefined
+    this.queued = decode
+    if (drainScheduled) {
+      return
+    }
+    this.tail = this.tail
+      .then(() => {
+        const next = this.queued
+        this.queued = undefined
+        return next?.()
+      })
+      .catch(this.onError)
+  }
+
+  /**
+   * Detach on connection teardown: drops the queued latest-mode decode and
+   * starts subsequent pushes on a fresh chain. A decode already in flight
+   * still settles.
+   */
+  reset(): void {
+    this.tail = Promise.resolve()
+    this.queued = undefined
+  }
+}