@lifi/perps-sdk-provider-hyperliquid 20.0.0 → 20.1.0

package/dist/types/websocket/HyperliquidWsProvider.d.ts

@@ -32,7 +32,12 @@ export declare class HyperliquidWsProvider extends WsProviderBase<object> {
     private readonly client;
     private readonly registry;
     private readonly abstractionByUser;
+    private readonly summaryUsers;
+    private readonly abstractionReadsByUser;
     private readonly spotRefs;
+    private spotWireEpoch;
+    private readonly latestSpotByUser;
+    private readonly revalueSpotBalances;
     private readonly unifiedSummaryByUser;
     private readonly latestPerpsByUser;
     private readonly heldSummaryByUser;
@@ -136,6 +141,7 @@ export declare class HyperliquidWsProvider extends WsProviderBase<object> {
     private fetchAbstractionMode;
     private handleActiveAssetData;
     private handleSpotState;
+    private emitSpotBalances;
     /** Read the venue buying power over REST when the spot frame omits it. */
     private fetchAvailableAfterMaintenance;
 }

package/dist/types/websocket/HyperliquidWsProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HyperliquidWsProvider.d.ts","sourceRoot":"","sources":["../../../src/websocket/HyperliquidWsProvider.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"HyperliquidWsProvider.d.ts","sourceRoot":"","sources":["../../../src/websocket/HyperliquidWsProvider.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifi/perps-sdk-provider-hyperliquid",
-  "version": "20.0.0",
+  "version": "20.1.0",
   "description": "Hyperliquid provider plugin for @lifi/perps-sdk",
   "homepage": "https://github.com/lifinance/perps-sdk",
   "bugs": {
@@ -52,7 +52,7 @@
     "@lifi/perps-types": "^18.0.0"
   },
   "peerDependencies": {
-    "@lifi/perps-sdk": "^20.0.0"
+    "@lifi/perps-sdk": "^20.1.0"
   },
   "publishConfig": {
     "access": "public"

package/src/services/getActivity.ts

@@ -2,6 +2,7 @@ import {
   type AssetRegistry,
   getAssetRegistry,
   getMarketRegistry,
+  PerpsError,
   type SDKRequestOptions,
 } from '@lifi/perps-sdk'
 import type {
@@ -10,13 +11,9 @@ import type {
   FundingActivity,
   MarketDisplay,
 } from '@lifi/perps-types'
-import { ActivityType } from '@lifi/perps-types'
+import { ActivityType, PerpsErrorCode } from '@lifi/perps-types'
 import type { Address } from 'viem'
-import {
-  DEFAULT_HISTORY_LIMIT,
-  MAX_HISTORY_LIMIT,
-  PROVIDER_KEY,
-} from '../constants.js'
+import { PROVIDER_KEY } from '../constants.js'
 import type { HyperliquidContext } from '../context.js'
 import type {
   HlUserFills,
@@ -44,6 +41,7 @@ import {
   type InfoRequestOptions,
   infoRequest,
 } from '../utils/infoClient.js'
+import { getHistoryLimit, historyPage } from './historyPagination.js'
 
 /**
  * Parameters for {@link getActivity}.
@@ -52,9 +50,9 @@ import {
  */
 export interface GetActivityParams {
   address: Address
-  /** Maximum items returned; defaults to 50 and is capped at 200. */
+  /** Positive safe integer; defaults to 50 and is capped at 200. */
   limit?: number
-  /** Millisecond timestamp cursor; rows strictly older than it are returned. */
+  /** Opaque cursor returned in the previous page's `pagination.cursor`. */
   cursor?: string
   /** Inclusive lower bound in milliseconds since epoch. */
   startTime?: number
@@ -78,23 +76,100 @@ const ASSET_BEARING_TYPES: ReadonlySet<ActivityType> = new Set([
 const needsMarkets = (typeFilter: ActivityType[] | undefined): boolean =>
   !typeFilter || typeFilter.some((t) => MARKET_BEARING_TYPES.has(t))
 
+const fetchLiquidationHistory = async (
+  apiUrl: string,
+  user: Address,
+  startTime: number,
+  endTime: number,
+  resolveMarket: (coin: string) => MarketDisplay | undefined,
+  options?: InfoRequestOptions
+): Promise<ActivityItem[]> => {
+  const retained = new Map<number, HlUserFills[number]>()
+  while (startTime <= endTime) {
+    options?.signal?.throwIfAborted()
+    const fills = await infoRequest<HlUserFills>(
+      apiUrl,
+      { type: 'userFillsByTime', user, startTime, endTime },
+      options
+    )
+    options?.signal?.throwIfAborted()
+    let latest = startTime
+    for (const fill of fills) {
+      retained.set(fill.tid, fill)
+      latest = Math.max(latest, fill.time)
+    }
+    if (fills.length < 2000 || retained.size >= 10000) {
+      break
+    }
+    if (latest === startTime) {
+      throw new PerpsError(
+        PerpsErrorCode.ThirdPartyError,
+        'Hyperliquid fills saturate a single millisecond; liquidation history cannot be paginated safely'
+      )
+    }
+    // Inclusive overlap retains all same-time fills at the venue page boundary.
+    startTime = latest
+  }
+  const queried = user.toLowerCase()
+  const fills = [...retained.values()].filter(
+    (fill) => fill.liquidation?.liquidatedUser.toLowerCase() === queried
+  )
+  if (fills.length === 0) {
+    return []
+  }
+  const hashes = new Set<string>()
+  let firstTime = Infinity
+  let lastTime = 0
+  for (const fill of fills) {
+    if (fill.hash !== undefined) {
+      hashes.add(fill.hash)
+    }
+    firstTime = Math.min(firstTime, fill.time)
+    lastTime = Math.max(lastTime, fill.time)
+  }
+  // Exclusions must cover the entire order, not the current SDK page's ledger window.
+  const ledger = await historyPage(
+    { startTime: firstTime, endTime: lastTime },
+    Number.MAX_SAFE_INTEGER,
+    async (startTime, endTime) => {
+      const updates = await infoRequest<HlUserNonFundingLedgerUpdates>(
+        apiUrl,
+        { type: 'userNonFundingLedgerUpdates', user, startTime, endTime },
+        options
+      )
+      return {
+        items: updates.filter(
+          (entry) => isLiquidationDelta(entry.delta) && hashes.has(entry.hash)
+        ),
+        saturated: updates.length >= 500,
+      }
+    },
+    (entry) => ({ time: entry.time, key: entry.hash }),
+    options?.signal
+  )
+  return mapLiquidationFills(
+    fills,
+    PROVIDER_KEY,
+    user,
+    resolveMarket,
+    new Set(ledger.items.map((entry) => entry.hash))
+  )
+}
+
 const fetchActivityData = async (
   apiUrl: string,
   typeFilter: ActivityType[] | undefined,
-  timeParams: { user: Address; startTime?: number; endTime?: number },
+  timeParams: { user: Address; startTime: number; endTime: number },
   assetRegistry: AssetRegistry,
   resolveMarket: (coin: string) => MarketDisplay | undefined,
+  liquidationHistory: Promise<ActivityItem[]> | undefined,
   options?: InfoRequestOptions
-): Promise<ActivityItem[]> => {
+): Promise<{ items: ActivityItem[]; saturated: boolean }> => {
   const needLedger =
     !typeFilter || typeFilter.some((t) => t !== ActivityType.FUNDING)
   const needFunding = !typeFilter || typeFilter.includes(ActivityType.FUNDING)
-  // A liquidation executed as a market order reaches the account as fills
-  // with a `liquidation` field and never as a ledger `liquidation` delta.
-  const needLiquidationFills =
-    !typeFilter || typeFilter.includes(ActivityType.LIQUIDATION)
 
-  const [ledgerUpdates, fundingUpdates, fills] = await Promise.all([
+  const [ledgerUpdates, fundingUpdates, liquidations] = await Promise.all([
     needLedger
       ? infoRequest<HlUserNonFundingLedgerUpdates>(
           apiUrl,
@@ -109,16 +184,11 @@ const fetchActivityData = async (
           options
         )
       : Promise.resolve([] as HlUserFunding),
-    needLiquidationFills
-      ? infoRequest<HlUserFills>(
-          apiUrl,
-          timeParams.startTime === undefined
-            ? { type: 'userFills', user: timeParams.user }
-            : { type: 'userFillsByTime', ...timeParams },
-          options
-        )
-      : Promise.resolve([] as HlUserFills),
+    liquidationHistory,
   ])
+  if (ledgerUpdates.length >= 500 || fundingUpdates.length >= 500) {
+    return { items: [], saturated: true }
+  }
 
   const ledgerItems: ActivityItem[] = ledgerUpdates.flatMap(
     (entry): ActivityItem[] => {
@@ -156,46 +226,20 @@ const fetchActivityData = async (
     }
   )
 
-  const ledgerLiquidationHashes = new Set(
-    ledgerUpdates
-      .filter((entry) => isLiquidationDelta(entry.delta))
-      .map((entry) => entry.hash)
-  )
-  const liquidationItems = mapLiquidationFills(
-    fills,
-    PROVIDER_KEY,
-    timeParams.user,
-    resolveMarket,
-    ledgerLiquidationHashes
-  )
-
-  const merged = [...ledgerItems, ...fundingItems, ...liquidationItems].sort(
-    (a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime()
-  )
-
-  if (!typeFilter) {
-    return merged
-  }
-  const typeSet = new Set(typeFilter)
-  return merged.filter((item) => typeSet.has(item.type))
+  const merged = [...ledgerItems, ...fundingItems, ...(liquidations ?? [])]
+  const items = typeFilter
+    ? merged.filter((item) => typeFilter.includes(item.type))
+    : merged
+  return { items, saturated: false }
 }
 
-/**
- * Fetch a chronological activity feed (deposits, withdrawals, transfers,
- * liquidations, funding) for `address`. Combines results from Hyperliquid's
- * `userNonFundingLedgerUpdates`, `userFunding`, and `userFills` endpoints,
- * sorted newest-first.
- *
- * Cursor-based pagination uses the ms-since-epoch timestamp of the last item
- * on the current page.
- * @throws {PerpsError} On Hyperliquid REST error, network, or parsing failures.
- * @public
- */
+/** Fetch retained activity newest-first with opaque cursors across inclusive time ranges. */
 export const getActivity = async (
   { client, apiUrl }: HyperliquidContext,
   params: GetActivityParams,
   options?: SDKRequestOptions
 ): Promise<ActivitiesResponse> => {
+  const limit = getHistoryLimit(params.limit)
   const registry = getMarketRegistry(client, PROVIDER_KEY)
   // Only funding and liquidation rows carry a market, so a Ledger-only
   // request must not pull the market list.
@@ -211,53 +255,38 @@ export const getActivity = async (
   }
   const infoOpts = hlInfoOptions(client, options)
 
-  const limit = Math.min(
-    params.limit ?? DEFAULT_HISTORY_LIMIT,
-    MAX_HISTORY_LIMIT
-  )
-  const timeParams = {
-    user: params.address,
-    ...(params.startTime !== undefined || params.endTime !== undefined
-      ? { startTime: params.startTime ?? 0 }
-      : {}),
-    ...(params.endTime === undefined ? {} : { endTime: params.endTime }),
-  }
-
-  // `get`, not `require`: a coin the backend market list does not hold drops
-  // only its own row instead of rejecting the whole feed. The registry warns
-  // once per unresolved id. A delisted market still resolves, so its rows stay.
-  const merged = await fetchActivityData(
-    apiUrl,
-    params.type,
-    timeParams,
-    assetRegistry,
-    (coin) => registry.get(coin),
-    infoOpts
-  )
-
-  // Drop boundary items so the next page does not return the cursor row twice.
-  const filtered =
-    params.cursor === undefined
-      ? merged
-      : merged.filter(
-          (item) =>
-            new Date(item.timestamp).getTime() <
-            Number.parseInt(params.cursor!, 10)
+  const needLiquidationFills =
+    !params.type || params.type.includes(ActivityType.LIQUIDATION)
+  let liquidationHistory: Promise<ActivityItem[]> | undefined
+  const page = await historyPage(
+    params,
+    limit,
+    (startTime, endTime, snapshotEnd) => {
+      if (needLiquidationFills && liquidationHistory === undefined) {
+        liquidationHistory = fetchLiquidationHistory(
+          apiUrl,
+          params.address,
+          params.startTime ?? 0,
+          snapshotEnd,
+          (coin) => registry.get(coin),
+          infoOpts
         )
-
-  const hasMore = filtered.length > limit
-  const items = filtered.slice(0, limit)
-
-  return {
-    provider: PROVIDER_KEY,
-    items,
-    pagination: {
-      limit,
-      hasMore,
-      cursor:
-        items.length > 0
-          ? String(new Date(items[items.length - 1].timestamp).getTime())
-          : undefined,
+      }
+      return fetchActivityData(
+        apiUrl,
+        params.type,
+        { user: params.address, startTime, endTime },
+        assetRegistry,
+        (coin) => registry.get(coin),
+        liquidationHistory,
+        infoOpts
+      )
     },
-  }
+    (item) => ({
+      time: new Date(item.timestamp).getTime(),
+      key: `${item.type}:${item.id}`,
+    }),
+    options?.signal
+  )
+  return { provider: PROVIDER_KEY, ...page }
 }

package/src/services/getFills.ts

@@ -1,19 +1,12 @@
 import { getMarketRegistry, type SDKRequestOptions } from '@lifi/perps-sdk'
 import type { Fill, FillsResponse } from '@lifi/perps-types'
 import type { Address } from 'viem'
-import {
-  DEFAULT_HISTORY_LIMIT,
-  MAX_HISTORY_LIMIT,
-  PROVIDER_KEY,
-} from '../constants.js'
+import { PROVIDER_KEY } from '../constants.js'
 import type { HyperliquidContext } from '../context.js'
-import type {
-  HlUserFill,
-  HlUserFills,
-  HlUserFillsByTime,
-} from '../types/index.js'
+import type { HlUserFills } from '../types/index.js'
 import { assetIsOutcome, mapFill } from '../utils/index.js'
 import { hlInfoOptions, infoRequest } from '../utils/infoClient.js'
+import { getHistoryLimit, historyPage } from './historyPagination.js'
 
 /**
  * Parameters for {@link getFills}.
@@ -22,7 +15,7 @@ import { hlInfoOptions, infoRequest } from '../utils/infoClient.js'
  */
 export interface GetFillsParams {
   address: Address
-  /** Maximum items returned; defaults to 50 and is capped at 200. */
+  /** Positive safe integer; defaults to 50 and is capped at 200. */
   limit?: number
   /** Opaque cursor returned in the previous page's `pagination.cursor`. */
   cursor?: string
@@ -32,101 +25,55 @@ export interface GetFillsParams {
   endTime?: number
 }
 
-interface FillCursor {
-  time: number
-  tid: number
-}
-
-// HL's docs specify neither newest-first ordering nor monotonic `tid` for
-// `userFills`/`userFillsByTime`, so pagination can't rely on upstream order —
-// it must impose its own (time desc, tid desc as tiebreaker for same-time fills).
-const compareFillsDesc = (a: FillCursor, b: FillCursor): number =>
-  b.time - a.time || b.tid - a.tid
-
-const encodeCursor = (fill: FillCursor): string => `${fill.time}:${fill.tid}`
-
-const decodeCursor = (cursor: string): FillCursor => {
-  const [time, tid] = cursor.split(':').map(Number)
-  return { time, tid }
-}
-
-/**
- * Fetch the user's fills history. When `startTime` or `endTime` is provided,
- * Hyperliquid's `userFillsByTime` endpoint is used; otherwise the unbounded
- * `userFills` endpoint returns the full history. The backend's enriched asset
- * list supplies the display fields; only the fills endpoint is read direct
- * from HL.
- *
- * The response is sorted (time desc, `tid` as tiebreaker) before pagination —
- * see {@link compareFillsDesc}. The cursor encodes the last returned fill's
- * `(time, tid)`; the next page keeps fills that sort strictly after it.
- * @throws {PerpsError} On Hyperliquid REST error, network, or parsing failures.
- * @public
- */
+/** Fetch retained fills newest-first, using opaque cursors across inclusive time ranges. */
 export const getFills = async (
   { client, apiUrl }: HyperliquidContext,
   params: GetFillsParams,
   options?: SDKRequestOptions
 ): Promise<FillsResponse> => {
+  const limit = getHistoryLimit(params.limit)
   const registry = getMarketRegistry(client, PROVIDER_KEY)
   await registry.sync()
   const infoOpts = hlInfoOptions(client, options)
 
-  const limit = Math.min(
-    params.limit ?? DEFAULT_HISTORY_LIMIT,
-    MAX_HISTORY_LIMIT
-  )
-
-  const useByTime =
-    params.startTime !== undefined || params.endTime !== undefined
-
-  const allFills = useByTime
-    ? await infoRequest<HlUserFillsByTime>(
-        apiUrl,
-        {
-          type: 'userFillsByTime',
-          user: params.address,
-          startTime: params.startTime ?? 0,
-          ...(params.endTime !== undefined ? { endTime: params.endTime } : {}),
-        },
-        infoOpts
-      )
-    : await infoRequest<HlUserFills>(
+  let useRecent =
+    params.cursor === undefined &&
+    params.startTime === undefined &&
+    params.endTime === undefined
+  const page = await historyPage(
+    params,
+    limit,
+    async (startTime, endTime) => {
+      const fills = await infoRequest<HlUserFills>(
         apiUrl,
-        { type: 'userFills', user: params.address },
+        useRecent
+          ? { type: 'userFills', user: params.address }
+          : {
+              type: 'userFillsByTime',
+              user: params.address,
+              startTime,
+              endTime,
+            },
         infoOpts
       )
-
-  const sorted = [...allFills].sort(compareFillsDesc)
-
-  const filtered =
-    params.cursor === undefined
-      ? sorted
-      : sorted.filter(
-          (f) => compareFillsDesc(f, decodeCursor(params.cursor!)) > 0
-        )
-
-  const hasMore = filtered.length > limit
-  const page = filtered.slice(0, limit)
-  // `get`, not `require`: a coin the backend market list does not hold drops
-  // only its own row instead of rejecting the whole page. The registry warns
-  // once per unresolved id. A delisted market still resolves, so its rows stay.
-  const items = page.flatMap((f): Fill[] => {
-    if (assetIsOutcome(f.coin)) {
-      return []
-    }
-    const market = registry.get(f.coin)
-    return market === undefined ? [] : [mapFill(f, market)]
-  })
-  const lastPageFill: HlUserFill | undefined = page[page.length - 1]
-
-  return {
-    provider: PROVIDER_KEY,
-    items,
-    pagination: {
-      limit,
-      hasMore,
-      cursor: lastPageFill ? encodeCursor(lastPageFill) : undefined,
+      useRecent = false
+      if (fills.length >= 2000) {
+        return { items: [], saturated: true }
+      }
+      const items = fills.flatMap((fill): Fill[] => {
+        if (assetIsOutcome(fill.coin)) {
+          return []
+        }
+        const market = registry.get(fill.coin)
+        return market === undefined ? [] : [mapFill(fill, market)]
+      })
+      return { items, saturated: false }
     },
-  }
+    (fill) => ({
+      time: new Date(fill.createdAt).getTime(),
+      key: Number(fill.id),
+    }),
+    options?.signal
+  )
+  return { provider: PROVIDER_KEY, ...page }
 }