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

package/dist/esm/websocket/HyperliquidWsProvider.js

@@ -1,12 +1,11 @@
-import { calculateTransferable, DecodeChain, getMarketRegistry, isActiveMarket, isActiveOrderStatus, numberToDecimalString, PerpsError, ReconnectingWebSocket, resolveSubscribeQuote, toAssetDisplay, toPerpsMarketDisplay, WsProviderBase, wsLog, } from '@lifi/perps-sdk';
+import { addDecimalString, calculateTransferable, compareDecimalStrings, DecodeChain, getMarketRegistry, isActiveMarket, isActiveOrderStatus, isDecimalString, isDecimalStringZero, PerpsError, ReconnectingWebSocket, resolveSubscribeQuote, safeAddDecimalString, safeDecimalStringToNumber, safeDivideDecimalString, safeIsDecimalStringGreaterThan, safeIsDecimalStringZero, safeMultiplyDecimalString, safeNumberToDecimalString, safeSubtractDecimalString, subtractDecimalString, toAssetDisplay, toPerpsMarketDisplay, unknownToDecimalString, WsProviderBase, wsLog, } from '@lifi/perps-sdk';
 import { PerpsErrorCode } from '@lifi/perps-types';
-import Big from 'big.js';
 import { isAddress } from 'viem';
-import { DEFAULT_HYPERLIQUID_API_URL, HYPERLIQUID_FEE_TIER_FALLBACK, SPOT_MARKET_ID, } from '../constants.js';
+import { DEFAULT_HYPERLIQUID_API_URL, HYPERLIQUID_FEE_TIER_FALLBACK, PROVIDER_KEY, SPOT_MARKET_ID, } from '../constants.js';
 import { requireAccountExists } from '../services/getAccountExists.js';
 import { HlAbstractionMode } from '../types/index.js';
-import { toWireBig } from '../utils/decimal.js';
 import { assetIsOutcome, decodeCompressedJson, decodeFastAssetCtxs, hlInfoOptions, infoRequest, isOpenAssetPosition, mapFill, mapMarketContext, mapOrder, mapPosition, partitionSpotBalances, perpsTotals, priceStepToAggregation, spotAssetFromToken, spotBalance, 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;
 const normalizeHlAddress = (address) => isAddress(address, { strict: false }) ? address.toLowerCase() : address;
@@ -390,7 +389,14 @@ export class HyperliquidWsProvider extends WsProviderBase {
         if (priceStep === undefined) {
             return {};
         }
-        return priceStepToAggregation(priceStep, this.orderbookReferencePrice(marketId));
+        const referencePrice = this.orderbookReferencePrice(marketId);
+        const referencePriceNumber = referencePrice === undefined
+            ? undefined
+            : safeDecimalStringToNumber(referencePrice);
+        if (referencePriceNumber === undefined) {
+            return {};
+        }
+        return priceStepToAggregation(priceStep, referencePriceNumber);
     }
     orderbookAggregationKey(marketId, priceStep) {
         const aggregation = this.orderbookAggregation(marketId, priceStep);
@@ -702,25 +708,26 @@ export class HyperliquidWsProvider extends WsProviderBase {
         });
     }
     /** 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 does not match the decimal pattern is left out. */
     mergedMids() {
         const map = new Map();
+        const setMid = (id, mid) => {
+            const decimal = mid == null ? undefined : wsFigureToDecimalString(mid);
+            if (isDecimalString(decimal)) {
+                map.set(id, decimal);
+            }
+        };
         for (const byMarketId of this.perpCtxBySubDex.values()) {
             for (const [id, ctx] of Object.entries(byMarketId)) {
-                const mid = ctx.midPx ?? ctx.markPx;
-                map.set(id, Number(mid));
+                setMid(id, ctx.midPx ?? ctx.markPx);
             }
         }
         for (const [id, ctx] of Object.entries(this.spotCtxByMarketId)) {
-            const mid = ctx.midPx ?? ctx.markPx;
-            if (mid != null) {
-                map.set(id, Number(mid));
-            }
+            setMid(id, ctx.midPx ?? ctx.markPx);
         }
         for (const [id, fast] of Object.entries(this.fastCtxByMarketId)) {
-            const mid = fast.midPx ?? fast.markPx;
-            if (mid != null) {
-                map.set(id, Number(mid));
-            }
+            setMid(id, fast.midPx ?? fast.markPx);
         }
         return map;
     }
@@ -732,21 +739,22 @@ export class HyperliquidWsProvider extends WsProviderBase {
         const book = this.latestOrderbookByMarketId.get(marketId);
         const bid = book?.bids[0]?.price;
         const ask = book?.asks[0]?.price;
-        if (bid !== undefined && ask !== undefined) {
-            return (Number(bid) + Number(ask)) / 2;
+        if (bid === undefined || ask === undefined) {
+            return undefined;
         }
-        return Number.NaN;
+        const sum = safeAddDecimalString(bid, ask);
+        return sum === undefined ? undefined : safeDivideDecimalString(sum, '2');
     }
     handleL2Book(data) {
         const book = {
             provider: this.providerKey,
             marketId: data.coin,
             bids: data.levels[0]
-                .slice(0, HL_L2_BOOK_MAX_LEVELS_PER_SIDE)
-                .map((l) => ({ price: l.px, size: l.sz })),
+                .flatMap((l) => toOrderbookLevel(data.coin, l.px, l.sz))
+                .slice(0, HL_L2_BOOK_MAX_LEVELS_PER_SIDE),
             asks: data.levels[1]
-                .slice(0, HL_L2_BOOK_MAX_LEVELS_PER_SIDE)
-                .map((l) => ({ price: l.px, size: l.sz })),
+                .flatMap((l) => toOrderbookLevel(data.coin, l.px, l.sz))
+                .slice(0, HL_L2_BOOK_MAX_LEVELS_PER_SIDE),
             timestamp: data.time,
         };
         this.latestOrderbookByMarketId.set(data.coin, book);
@@ -782,8 +790,8 @@ export class HyperliquidWsProvider extends WsProviderBase {
         const book = {
             provider: this.providerKey,
             marketId: delta.c,
-            bids: applyCompressedL2Side(previous.bids, delta.l[0], delta.r?.[0] ?? [], 'bid'),
-            asks: applyCompressedL2Side(previous.asks, delta.l[1], delta.r?.[1] ?? [], 'ask'),
+            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] ?? [], 'ask'),
             timestamp: delta.t,
         };
         this.latestOrderbookByMarketId.set(delta.c, book);
@@ -846,40 +854,25 @@ export class HyperliquidWsProvider extends WsProviderBase {
             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) {
-                    return undefined;
+                let detail;
+                try {
+                    detail = await this.readOrderDetail(user, client, update);
                 }
-                const response = await infoRequest(this.orderApiUrl, {
-                    type: 'orderStatus',
-                    user: key.slice('orderUpdates:'.length),
-                    oid: basic.oid,
-                }, hlInfoOptions(client));
-                if (response.status !== 'order') {
-                    throw new PerpsError(PerpsErrorCode.OrderNotFound, `Hyperliquid order metadata not found: ${basic.oid}`);
+                catch (error) {
+                    if (!(error instanceof PerpsError)) {
+                        throw error;
+                    }
+                    wsLog.droppedRow(this.providerKey, 'order', `${basic.oid}: ${error.message}`);
+                    return undefined;
                 }
-                // REST supplies execution metadata; the stream owns this event's lifecycle and quantities.
-                const detail = {
-                    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);
+                return mapOrderRow(basic.coin, this.registry, (resolved) => mapOrder(detail, resolved));
             }));
             if (epoch !== this.orderUpdatesEpoch || key !== this.orderUpdatesKey) {
                 return;
@@ -898,6 +891,29 @@ export class HyperliquidWsProvider extends WsProviderBase {
             this.emit(key, { channel: 'orderUpdates', data: { orders, terminated } });
         });
     }
+    // REST supplies execution metadata; the stream owns this event's lifecycle and quantities.
+    async readOrderDetail(user, client, update) {
+        const basic = update.order;
+        const response = await infoRequest(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,
+            },
+        };
+    }
     handleUserFills(data) {
         // The snapshot frame carries up to ~2000 historical fills and is replayed
         // on every reconnect via `replaySubs`; emitting them would surface old
@@ -911,7 +927,8 @@ export class HyperliquidWsProvider extends WsProviderBase {
                     return [];
                 }
                 const market = this.registry?.get(f.coin);
-                return market ? [mapFill(f, market)] : [];
+                const mapped = market && mapFill(f, market);
+                return mapped ? [mapped] : [];
             });
         this.emit(`userFills:${data.user.toLowerCase()}`, {
             channel: 'fills',
@@ -925,9 +942,10 @@ export class HyperliquidWsProvider extends WsProviderBase {
                 return [];
             }
             const market = this.registry?.get(ap.position.coin);
-            return market
-                ? [mapPosition(ap, toPerpsMarketDisplay(market))]
-                : [];
+            const position = market === undefined
+                ? undefined
+                : mapPosition(ap, toPerpsMarketDisplay(market));
+            return position === undefined ? [] : [position];
         }));
         this.emit(`positions:${data.user.toLowerCase()}`, {
             channel: 'positions',
@@ -935,20 +953,17 @@ export class HyperliquidWsProvider extends WsProviderBase {
         });
         const { accountValue, marginUsed } = perpsTotals(data.clearinghouseStates.map(([, state]) => state));
         const key = data.user.toLowerCase();
-        this.latestPerpsByUser.set(key, {
-            positions,
-            marginUsed: marginUsed.toFixed(),
-        });
+        this.latestPerpsByUser.set(key, { positions, marginUsed });
         this.emitUnifiedSummary(key);
         // Equity semantics, matching the REST summary: `accountValue` already
         // carries locked margin and unrealized PnL. Spot balances stream apart,
         // so this portfolio value covers perps equity only — which is why the
         // frame is gated on the abstraction mode below.
         this.emitSummaryIfModeAllows(data.user, {
-            portfolioValue: accountValue.toFixed(),
-            availableMargin: accountValue.minus(marginUsed).toFixed(),
-            marginUsed: marginUsed.toFixed(),
-            unrealizedPnl: sumUnrealizedPnl(positions).toFixed(),
+            portfolioValue: accountValue,
+            availableMargin: subtractDecimalString(accountValue, marginUsed),
+            marginUsed,
+            unrealizedPnl: sumUnrealizedPnl(positions),
         });
     }
     /** Whether the mode's collateral lives per-dex, making the perps-only
@@ -1039,14 +1054,14 @@ export class HyperliquidWsProvider extends WsProviderBase {
         const portfolioValue = [
             ...pipeline.spot.collateralBalances,
             ...pipeline.spot.balances,
-        ].reduce((sum, balance) => sum.plus(toWireBig(balance.valueUsd, 'spotBalance.valueUsd')), new Big(0));
+        ].reduce((sum, balance) => addDecimalString(sum, unknownToDecimalString(balance.valueUsd, 'spotBalance.valueUsd', this.providerKey)), '0');
         this.emit(`accountSummary:${key}`, {
             channel: 'accountSummary',
             data: {
-                portfolioValue: portfolioValue.toFixed(),
+                portfolioValue,
                 availableMargin: pipeline.availableMargin,
                 marginUsed: perps.marginUsed,
-                unrealizedPnl: sumUnrealizedPnl(perps.positions).toFixed(),
+                unrealizedPnl: sumUnrealizedPnl(perps.positions),
             },
         });
     }
@@ -1172,24 +1187,27 @@ export class HyperliquidWsProvider extends WsProviderBase {
         }
         const markets = this.registry?.activeMarkets ?? [];
         const priceById = spotPriceById(markets, this.mergedMids());
-        const balances = data.spotState.balances.filter((balance) => !assetIsOutcome(balance.coin) &&
-            toWireBig(balance.total, 'spotState.balances.total').gt(0));
+        const balances = data.spotState.balances
+            .filter((balance) => !assetIsOutcome(balance.coin))
+            .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 (balances.some((balance) => priceById.get(String(balance.token)) === 0)) {
+        if (balances.some(({ balance }) => {
+            const price = priceById.get(String(balance.token));
+            return price !== undefined && isDecimalStringZero(price);
+        })) {
             if (pipeline !== undefined) {
                 pipeline.spot = undefined;
             }
             return;
         }
-        const rows = balances.map((balance) => {
-            const total = toWireBig(balance.total, 'spotState.balances.total');
+        const rows = balances.map(({ balance, total }) => {
+            const free = safeSubtractDecimalString(total, balance.hold);
             return {
-                ...spotBalance(spotAssetFromToken(balance), balance.total, priceById),
+                ...spotBalance(spotAssetFromToken(balance), total, priceById),
                 locked: balance.hold,
-                transferable: calculateTransferable(total
-                    .minus(toWireBig(balance.hold, 'spotState.balances.hold'))
-                    .toFixed(), total.toFixed()),
+                transferable: free === undefined ? '0' : calculateTransferable(free, total),
             };
         });
         this.emit(`spotState:${user}`, {
@@ -1229,29 +1247,22 @@ export class HyperliquidWsProvider extends WsProviderBase {
     }
 }
 const isObject = (v) => typeof v === 'object' && v !== null;
-const toMarketContextString = (value) => {
-    if (typeof value === 'number') {
-        return numberToDecimalString(value);
-    }
-    return typeof value === 'string' ? value : undefined;
-};
+/** A WebSocket figure as a string; a venue number is spelled as a decimal
+ * string, and a non-finite number gives `undefined`. */
+function wsFigureToDecimalString(value) {
+    return typeof value === 'number' ? safeNumberToDecimalString(value) : value;
+}
+function optionalWsFigureToDecimalString(value) {
+    return value == null ? undefined : wsFigureToDecimalString(value);
+}
 const toMarketCapString = (price, circulatingSupply) => {
-    const priceString = toMarketContextString(price);
-    const supplyString = toMarketContextString(circulatingSupply);
-    if (priceString === undefined || supplyString === undefined) {
-        return undefined;
-    }
-    try {
-        const parsedPrice = new Big(priceString);
-        const parsedSupply = new Big(supplyString);
-        if (parsedPrice.lte(0) || parsedSupply.lte(0)) {
-            return undefined;
-        }
-        return parsedPrice.times(parsedSupply).toFixed();
-    }
-    catch {
+    const supply = optionalWsFigureToDecimalString(circulatingSupply);
+    if (supply === undefined ||
+        safeIsDecimalStringGreaterThan(price, '0') !== true ||
+        safeIsDecimalStringGreaterThan(supply, '0') !== true) {
         return undefined;
     }
+    return safeMultiplyDecimalString(price, supply);
 };
 function mergePerpAssetCtx(previous, marketId, update) {
     const funding = update.funding ?? previous?.funding;
@@ -1285,15 +1296,13 @@ function allDexsAssetCtxEntries(data) {
     return data.assetCtxs ?? data.ctxs ?? [];
 }
 function activePerpAssetCtx(marketId, ctx) {
-    const funding = toMarketContextString(ctx.funding);
-    const openInterest = toMarketContextString(ctx.openInterest);
-    const dayNtlVlm = toMarketContextString(ctx.dayNtlVlm);
-    const prevDayPx = toMarketContextString(ctx.prevDayPx);
-    const markPx = toMarketContextString(ctx.markPx);
-    const midPx = ctx.midPx === undefined || ctx.midPx === null
-        ? null
-        : (toMarketContextString(ctx.midPx) ?? null);
-    const oraclePx = toMarketContextString(ctx.oraclePx);
+    const funding = optionalWsFigureToDecimalString(ctx.funding);
+    const openInterest = optionalWsFigureToDecimalString(ctx.openInterest);
+    const dayNtlVlm = optionalWsFigureToDecimalString(ctx.dayNtlVlm);
+    const prevDayPx = optionalWsFigureToDecimalString(ctx.prevDayPx);
+    const markPx = optionalWsFigureToDecimalString(ctx.markPx);
+    const midPx = optionalWsFigureToDecimalString(ctx.midPx) ?? null;
+    const oraclePx = optionalWsFigureToDecimalString(ctx.oraclePx);
     if (funding === undefined ||
         openInterest === undefined ||
         dayNtlVlm === undefined ||
@@ -1314,8 +1323,8 @@ function activePerpAssetCtx(marketId, ctx) {
     };
 }
 function mapSpotMarketContext(marketId, ctx, fast) {
-    const midPrice = toMarketContextString(ctx.midPx ?? ctx.markPx);
-    const markPrice = toMarketContextString(ctx.markPx);
+    const midPrice = optionalWsFigureToDecimalString(ctx.midPx ?? ctx.markPx);
+    const markPrice = optionalWsFigureToDecimalString(ctx.markPx);
     if (midPrice === undefined || markPrice === undefined) {
         return undefined;
     }
@@ -1324,18 +1333,43 @@ function mapSpotMarketContext(marketId, ctx, fast) {
         marketId,
         midPrice: fast?.midPx != null ? fast.midPx : midPrice,
         markPrice: emittedMarkPrice,
-        prevDayPrice: toMarketContextString(ctx.prevDayPx),
-        volume24h: toMarketContextString(ctx.dayNtlVlm),
+        prevDayPrice: optionalWsFigureToDecimalString(ctx.prevDayPx),
+        volume24h: optionalWsFigureToDecimalString(ctx.dayNtlVlm),
         marketCap: toMarketCapString(emittedMarkPrice, ctx.circulatingSupply),
     };
 }
+const BOOK_LEVEL_ROW = 'order book level';
+/** The venue price when it is a decimal string, or `undefined` after a logged skip. */
+function bookLevelPrice(marketId, price) {
+    if (!isDecimalString(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(marketId, size) {
+    if (!isDecimalString(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(marketId, price, size) {
+    const levelPrice = bookLevelPrice(marketId, price);
+    const levelSize = levelPrice === undefined ? undefined : bookLevelSize(marketId, size);
+    return levelPrice === undefined || levelSize === undefined
+        ? []
+        : [{ price: levelPrice, size: levelSize }];
+}
 function compactRemovalPrice(levels, value) {
     if (typeof value === 'number') {
         return levels[value]?.price;
     }
     return typeof value === 'string' ? value : value.p;
 }
-function applyCompressedL2Side(previous, updates, removals, side) {
+function applyCompressedL2Side(marketId, previous, updates, removals, side) {
     const byPrice = new Map(previous.map((level) => [level.price, level.size]));
     for (const removal of removals) {
         const price = compactRemovalPrice(previous, removal);
@@ -1344,18 +1378,24 @@ function applyCompressedL2Side(previous, updates, removals, side) {
         }
     }
     for (const update of updates) {
-        if (Number(update.s) === 0) {
-            byPrice.delete(update.p);
+        const price = bookLevelPrice(marketId, update.p);
+        if (price === undefined) {
+            continue;
+        }
+        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);
         }
         else {
-            byPrice.set(update.p, update.s);
+            byPrice.set(price, size);
         }
     }
     return [...byPrice.entries()]
         .map(([price, size]) => ({ price, size }))
         .sort((a, b) => side === 'bid'
-        ? Number(b.price) - Number(a.price)
-        : Number(a.price) - Number(b.price))
+        ? compareDecimalStrings(b.price, a.price)
+        : compareDecimalStrings(a.price, b.price))
         .slice(0, HL_L2_BOOK_MAX_LEVELS_PER_SIDE);
 }
 /**