@lifi/perps-sdk-provider-hyperliquid 4.1.0 → 4.3.0

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

@@ -1,4 +1,4 @@
-import { type PerpsSDKClient, type ProviderGetQuoteParams, type QuoteListener, WsProviderBase, type WsProviderFactory } from '@lifi/perps-sdk';
+import { type PerpsSDKClient, type ProviderGetQuoteParams, type QuoteListener, type SubscriptionListener, WsProviderBase, type WsProviderFactory, type WsStatusListener } from '@lifi/perps-sdk';
 import { type Subscription } from '@lifi/perps-types';
 /**
  * `WsProviderFactory` constructor for Hyperliquid — pass to
@@ -29,6 +29,11 @@ export declare class HyperliquidWsProvider extends WsProviderBase<object> {
     private readonly clearinghouseRefs;
     private readonly client;
     private readonly registry;
+    private readonly abstractionByUser;
+    private readonly spotRefs;
+    private readonly unifiedSummaryByUser;
+    private readonly latestPositionsByUser;
+    private readonly heldSummaryByUser;
     private perpCtxBySubDex;
     private spotCtxByMarketId;
     private marketsContextByMarketId;
@@ -41,6 +46,7 @@ export declare class HyperliquidWsProvider extends WsProviderBase<object> {
     private readonly sacDecodeChain;
     private readonly orderbookDecodeChain;
     constructor(wsUrl: string, providerKey: string, client?: PerpsSDKClient);
+    subscribe(sub: Subscription, listener: SubscriptionListener, onStatus?: WsStatusListener): Promise<() => void>;
     subscribeQuote(params: ProviderGetQuoteParams, onQuote: QuoteListener): Promise<() => void>;
     protected openChannel(sub: Subscription): Promise<() => void>;
     /**
@@ -108,6 +114,22 @@ export declare class HyperliquidWsProvider extends WsProviderBase<object> {
     private handleOrderUpdates;
     private handleUserFills;
     private handleAllDexsClearinghouseState;
+    /** Whether the mode's collateral lives per-dex, making the perps-only
+     * summary frame honest. Unified/portfolio hold collateral in spot. */
+    private static summaryComputableFor;
+    private acquireSpotWire;
+    /** Start or stop the spot-fed unified pipeline to match the resolved mode. */
+    private syncUnifiedPipeline;
+    private emitUnifiedSummary;
+    /** Re-read the abstraction mode this long after the previous read, so an
+     * in-session account-mode switch flips the gate within one refresh. */
+    private static readonly ABSTRACTION_TTL_MS;
+    /** Subscribe-triggered re-reads younger than this are skipped: a config
+     * change resubscribes every consumer hook in one React commit, and one
+     * read serves them all. */
+    private static readonly REFRESH_COALESCE_MS;
+    private emitSummaryIfModeAllows;
+    private fetchAbstractionMode;
     private handleSpotState;
 }
 //# sourceMappingURL=HyperliquidWsProvider.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"HyperliquidWsProvider.d.ts","sourceRoot":"","sources":["../../../src/websocket/HyperliquidWsProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAGlB,cAAc,EACd,KAAK,iBAAiB,EAEvB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAOL,KAAK,YAAY,EAElB,MAAM,mBAAmB,CAAA;AA8C1B;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,QAC5B,iBAEgD,CAAA;AAEtD;;;;;;;;;;;;;GAaG;AACH,qBAAa,qBAAsB,SAAQ,cAAc,CAAC,MAAM,CAAC;IAC/D,OAAO,CAAC,eAAe,CAAoB;IAC3C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA4B;IAC9D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;IACnD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;IACrD,OAAO,CAAC,eAAe,CAAsD;IAC7E,OAAO,CAAC,iBAAiB,CAAuC;IAChE,OAAO,CAAC,wBAAwB,CAAoC;IACpE,OAAO,CAAC,uBAAuB,CAAiC;IAChE,OAAO,CAAC,yBAAyB,CAAuC;IAKxE,OAAO,CAAC,iBAAiB,CAAuC;IAChE,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CACW;IAM/C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAG/B;IACD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAG9B;IACD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAG9B;IACD,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAGpC;gBAEW,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,cAAc;IASjE,cAAc,CAClB,MAAM,EAAE,sBAAsB,EAC9B,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,IAAI,CAAC;cAkBN,WAAW,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC;IA0FnE;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IAiB5B,OAAO,CAAC,iBAAiB;IAmBzB;;;;OAIG;IACH,OAAO,CAAC,2BAA2B;IAWnC,OAAO,CAAC,iBAAiB;IAUzB,OAAO,CAAC,gBAAgB;cAcL,OAAO,IAAI,IAAI;IAclC,SAAS,CAAC,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAM9C,SAAS,CAAC,KAAK,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM;IA4B1C,OAAO,CAAC,oBAAoB;IAa5B,OAAO,CAAC,uBAAuB;IAa/B,OAAO,CAAC,WAAW;IA8CnB,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,MAAM;IA8EnC,OAAO,CAAC,sBAAsB;IAM9B,OAAO,CAAC,SAAS;IAUjB,oFAAoF;IACpF,OAAO,CAAC,wBAAwB;IAyBhC,OAAO,CAAC,SAAS;IAoBjB,OAAO,CAAC,oBAAoB;IAe5B;;;;;;OAMG;IACH,OAAO,CAAC,mBAAmB;IAc3B;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAgB1B;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IA6B5B,OAAO,CAAC,oBAAoB;IAY5B,OAAO,CAAC,wBAAwB;IAWhC,sEAAsE;IACtE,OAAO,CAAC,UAAU;IAuBlB,OAAO,CAAC,uBAAuB;IAgB/B,OAAO,CAAC,YAAY;IAgBpB,OAAO,CAAC,QAAQ;IAkBhB,OAAO,CAAC,oBAAoB;IAmC5B,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,YAAY;IAcpB,OAAO,CAAC,YAAY;IAmBpB,OAAO,CAAC,kBAAkB;IAyD1B,OAAO,CAAC,eAAe;IAkBvB,OAAO,CAAC,+BAA+B;IA2CvC,OAAO,CAAC,eAAe;CAaxB"}
+{"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": "4.1.0",
+  "version": "4.3.0",
   "description": "Hyperliquid provider plugin for @lifi/perps-sdk",
   "homepage": "https://github.com/lifinance/perps-sdk",
   "bugs": {
@@ -48,10 +48,10 @@
   "dependencies": {
     "big.js": "^7.0.1",
     "viem": "^2.48.8",
-    "@lifi/perps-types": "^3.0.0"
+    "@lifi/perps-types": "^3.2.0"
   },
   "peerDependencies": {
-    "@lifi/perps-sdk": "^4.1.0"
+    "@lifi/perps-sdk": "^4.3.0"
   },
   "publishConfig": {
     "access": "public"

package/src/services/getAccount.ts

@@ -22,6 +22,7 @@ import {
   type HlUserFees,
 } from '../types/index.js'
 import {
+  partitionSpotBalances,
   perpsDexNames,
   spotAssetFromToken,
   spotBalance,
@@ -96,18 +97,13 @@ const buildBalances = (
   priceById: Map<string, number>,
   quoteAssetByCategory: Map<string, Asset>
 ): BalancePartition => {
-  const balances: Balance[] = []
-  const collateralBalances: Balance[] = []
-
-  // Spot balances: collateral if and only if the token is a category quote asset.
-  for (const b of spotState.balances) {
-    const balance = spotBalance(spotAssetFromToken(b), b.total, priceById)
-    if (quoteAssetIds.has(balance.asset.id)) {
-      collateralBalances.push(balance)
-    } else {
-      balances.push(balance)
-    }
-  }
+  const { balances, collateralBalances } = partitionSpotBalances(
+    spotState.balances.map((b) =>
+      spotBalance(spotAssetFromToken(b), b.total, priceById)
+    ),
+    quoteAssetIds,
+    abstraction === HlAbstractionMode.PORTFOLIO_MARGIN
+  )
 
   // Unified/portfolio modes hold everything in spot — per-dex equity would
   // double-count. Only disabled/dexAbstraction carry separate venue collateral.

package/src/types/account.ts

@@ -69,10 +69,12 @@ export type HlPreTransferCheck = {
 
 /**
  * Possible values returned by the `userAbstraction` info endpoint.
- * `null` means abstraction has never been set (standard mode).
+ * `null` means abstraction has never been set; `'default'`/`'disabled'` are
+ * the live and legacy spellings of standard (non-abstracted) mode.
  * @public
  */
 export const HlAbstractionMode = {
+  DEFAULT: 'default',
   DISABLED: 'disabled',
   UNIFIED_ACCOUNT: 'unifiedAccount',
   PORTFOLIO_MARGIN: 'portfolioMargin',

package/src/utils/assetLogo.ts

@@ -0,0 +1,85 @@
+import type { Asset } from '@lifi/perps-types'
+
+const HL_COIN_CDN = 'https://app.hyperliquid.xyz/coins'
+
+const HYPE_LOGO_URI =
+  'https://static.debank.com/image/hyper_token/logo_url/hyper/0b3e288cfe418e9ce69eef4c96374583.png'
+
+/**
+ * Per-symbol logo overrides applied on top of the derived HL CDN URL, keyed by
+ * `Asset.displaySymbol`. Each entry notes why the default URL is wrong.
+ */
+const BASE_ASSET_LOGO_OVERRIDES: Readonly<Record<string, string>> = {
+  // coins/HYPE.svg is low quality; the debank hyper_token PNG is the canonical icon.
+  HYPE: HYPE_LOGO_URI,
+  // coins/USDC_spot.svg doesn't exist — HL's app 200s with its SPA shell HTML
+  // instead of a 404, so the collateral asset needs the non-suffixed path.
+  USDC: `${HL_COIN_CDN}/USDC.svg`,
+  // Neither coins/USDT0.svg nor coins/USDT0_spot.svg serves an image (both 200
+  // with the SPA shell); USDT0 is HL's USDT deployment, so reuse USDT's icon.
+  USDT0: `${HL_COIN_CDN}/USDT.svg`,
+}
+
+/**
+ * Underlying spot symbol for each Unit-bridged token (`fullName` starts with
+ * "Unit"), keyed by the token `name`. Hand-verified that `coins/<symbol>.svg`
+ * serves a real image; the Unit-suffixed `NAME_spot.svg` path 200s with HTML
+ * instead. Unit tokens absent here have no working HL icon and intentionally
+ * resolve to '' (client letter avatar).
+ */
+const UNIT_UNDERLYING_SYMBOL: Readonly<Record<string, string>> = {
+  UBTC: 'BTC',
+  UETH: 'ETH',
+  USOL: 'SOL',
+  UFART: 'FARTCOIN',
+  UPUMP: 'PUMP',
+  UUUSPX: 'SPX',
+  UVIRT: 'VIRTUAL',
+  UBONK: 'BONK',
+  UDOGE: 'DOGE',
+  UZEC: 'ZEC',
+  UMON: 'MON',
+  UWLD: 'WLD',
+  UENA: 'ENA',
+  UXPL: 'XPL',
+  UAVAX: 'AVAX',
+  UMEGA: 'MEGA',
+  UANSEM: 'ANSEM',
+}
+
+/** Token `name`s of the Unit-bridged HL spot assets. */
+export const UNIT_TOKEN_NAMES: ReadonlySet<string> = new Set(
+  Object.keys(UNIT_UNDERLYING_SYMBOL)
+)
+
+/** Logo URI for a Unit-bridged spot token; '' when the underlying is unmapped. */
+const unitSpotLogoURI = (name: string): string => {
+  const underlying = UNIT_UNDERLYING_SYMBOL[name]
+  return underlying === undefined ? '' : `${HL_COIN_CDN}/${underlying}.svg`
+}
+
+/** Return `asset` with its `logoURI` replaced when a display-symbol override exists. */
+export const applyLogoOverride = (asset: Asset): Asset => {
+  const override = BASE_ASSET_LOGO_OVERRIDES[asset.displaySymbol]
+  return override === undefined ? asset : { ...asset, logoURI: override }
+}
+
+/**
+ * Override-aware logo URI for a Hyperliquid spot token. Base rule is
+ * `coins/${name}_spot.svg`; a Unit-bridged token (`fullName` starts with
+ * "Unit") resolves to its underlying's icon instead; the override table wins
+ * over both.
+ *
+ * When `fullName` is absent — spot *balances* (`HlSpotBalance`) carry no
+ * `fullName` and this issue deliberately does not fetch `spotMeta` on the
+ * account path — the derivation degrades to the symbol-keyed override + base
+ * `_spot` rule, so a Unit-bridged balance uses the base rule rather than its
+ * underlying's icon. The registry path (which has `fullName`) keeps full Unit
+ * resolution.
+ */
+export const spotLogoURI = (name: string, fullName?: string | null): string => {
+  const base = fullName?.startsWith('Unit')
+    ? unitSpotLogoURI(name)
+    : `${HL_COIN_CDN}/${name}_spot.svg`
+  return BASE_ASSET_LOGO_OVERRIDES[name] ?? base
+}

package/src/utils/index.ts

@@ -3,6 +3,11 @@
 // (e.g. `./assetId.js`, `./mapFill.js`) directly.
 
 export { assetIsSpot, calculateAssetId, getProviderIndex } from './assetId.js'
+export {
+  applyLogoOverride,
+  spotLogoURI,
+  UNIT_TOKEN_NAMES,
+} from './assetLogo.js'
 export {
   decodeCompressedJson,
   decodeFastAssetCtxs,
@@ -40,3 +45,4 @@ export {
   spotBalance,
   spotPriceById,
 } from './spotBalance.js'
+export { partitionSpotBalances, type SpotPartition } from './spotCollateral.js'

package/src/utils/marketDisplay.ts

@@ -5,20 +5,25 @@ import {
   PROVIDER_KEY,
   SPOT_MARKET_ID,
 } from '../constants.js'
+import { applyLogoOverride } from './assetLogo.js'
 
 /**
- * Synthesise the {@link Asset} for a Hyperliquid wire coin. `id` and `logoURI`
- * keep the raw coin — the logo CDN is keyed by it, HIP-3 `dex:` prefix
- * included. `displaySymbol` drops the prefix: the category is carried by
- * `categoryId`, never by the display string.
+ * Synthesise the {@link Asset} for a Hyperliquid wire coin. `id` keeps the raw
+ * coin — the logo CDN is keyed by it, HIP-3 `dex:` prefix included.
+ * `displaySymbol` drops the prefix: the category is carried by `categoryId`,
+ * never by the display string. `logoURI` is the CDN URL corrected by the
+ * shared override table (see {@link applyLogoOverride}).
  * @public
  */
-export const coinAsset = (coin: string): Asset => ({
-  providerId: PROVIDER_KEY,
-  id: coin,
-  displaySymbol: coin.includes(':') ? coin.slice(coin.indexOf(':') + 1) : coin,
-  logoURI: `https://app.hyperliquid.xyz/coins/${coin}.svg`,
-})
+export const coinAsset = (coin: string): Asset =>
+  applyLogoOverride({
+    providerId: PROVIDER_KEY,
+    id: coin,
+    displaySymbol: coin.includes(':')
+      ? coin.slice(coin.indexOf(':') + 1)
+      : coin,
+    logoURI: `https://app.hyperliquid.xyz/coins/${coin}.svg`,
+  })
 
 /**
  * Distinct wire `dex` names to fan `clearinghouseState` / `frontendOpenOrders`

package/src/utils/spotBalance.ts

@@ -2,6 +2,7 @@ import { stringToFloat } from '@lifi/perps-sdk'
 import type { Asset, Balance, Market } from '@lifi/perps-types'
 import { SPOT_MARKET_ID } from '../constants.js'
 import type { HlSpotBalance } from '../types/index.js'
+import { spotLogoURI } from './assetLogo.js'
 import { coinAsset } from './marketDisplay.js'
 
 /**
@@ -31,11 +32,14 @@ export const spotPriceById = (
 /**
  * The held spot {@link Asset} for an HL balance: the venue token index
  * (`b.token`) as `Asset.id` — equal to that token's spot `Market.baseAsset.id`
- * — with display fields derived from the coin.
+ * — with display fields derived from the coin and the override-aware spot logo.
+ * `HlSpotBalance` carries no `fullName`, so Unit-bridged balances take the base
+ * `_spot` rule (see {@link spotLogoURI}).
  */
 export const spotAssetFromToken = (b: HlSpotBalance): Asset => ({
   ...coinAsset(b.coin),
   id: String(b.token),
+  logoURI: spotLogoURI(b.coin),
 })
 
 /** Assemble a typed spot {@link Balance} from its resolved asset and raw size. */

package/src/utils/spotCollateral.ts

@@ -0,0 +1,50 @@
+import type { Balance } from '@lifi/perps-types'
+
+/**
+ * Portfolio-margin collateral beyond the category quote assets, keyed by spot
+ * display symbol with its loan-to-value weight. Hyperliquid credits these
+ * toward buying power at the given fraction (0.5 for both today). Quote assets
+ * (USDC/USDT) are already full-value collateral via the category model, so
+ * they are not listed here.
+ * https://hyperliquid.gitbook.io/hyperliquid-docs/trading/portfolio-margin
+ */
+const PORTFOLIO_MARGIN_LTV: Readonly<Record<string, number>> = {
+  HYPE: 0.5,
+  UBTC: 0.5,
+}
+
+/** @internal */
+export interface SpotPartition {
+  collateralBalances: Balance[]
+  balances: Balance[]
+}
+
+/**
+ * Split spot balances into margin collateral and flat holdings. A balance is
+ * collateral when its token is a category quote asset (full value) or, under
+ * portfolio margin, an LTV-weighted asset (HYPE/BTC); everything else is a
+ * flat holding.
+ */
+export const partitionSpotBalances = (
+  spotBalances: readonly Balance[],
+  quoteAssetIds: ReadonlySet<string>,
+  portfolioMargin: boolean
+): SpotPartition => {
+  const collateralBalances: Balance[] = []
+  const balances: Balance[] = []
+  for (const balance of spotBalances) {
+    if (quoteAssetIds.has(balance.asset.id)) {
+      collateralBalances.push(balance)
+      continue
+    }
+    const ltv = portfolioMargin
+      ? PORTFOLIO_MARGIN_LTV[balance.asset.displaySymbol]
+      : undefined
+    if (ltv !== undefined) {
+      collateralBalances.push({ ...balance, collateralWeight: ltv })
+    } else {
+      balances.push(balance)
+    }
+  }
+  return { collateralBalances, balances }
+}