@lifi/perps-sdk-provider-hyperliquid 13.0.0 → 14.0.0

package/src/utils/infoClient.ts

@@ -1,6 +1,7 @@
 import {
   errorCodeFromStatus,
   fetchWithRetry,
+  isAbortError,
   PerpsError,
   type PerpsSDKClient,
   type ResolvedRetryPolicy,
@@ -57,7 +58,7 @@ export const HYPERLIQUID_RETRY_DEFAULTS: ResolvedRetryPolicy = {
 }
 
 /**
- * Transport options for a direct Hyperliquid `/info` request. `policy`
+ * Transport options for a direct Hyperliquid REST request. `policy`
  * controls retries, `signal` cancels the request, and `fetchImpl` overrides
  * the runtime's global `fetch` implementation.
  * @public
@@ -87,7 +88,7 @@ export const hlInfoOptions = (
 })
 
 /**
- * POST to the Hyperliquid `/info` endpoint and return the parsed JSON body.
+ * POST a JSON body to a Hyperliquid REST surface and return the parsed body.
  *
  * Direct-to-venue: no proxy, no AJV validation, no cache. The caller's type
  * parameter is trusted; consumers should treat the response shape as
@@ -97,20 +98,24 @@ export const hlInfoOptions = (
  * Non-2xx responses raise a {@link PerpsError} tagged with the Hyperliquid
  * provider key, carrying the code the status resolves to: `RateLimitExceeded`
  * for a 429, `Unauthorized` for a 401, `AgentUnauthorized` for a 403, and
- * `ThirdPartyError` for every other status.
- * @public
+ * `ThirdPartyError` for every other status. A transport failure and a 2xx body
+ * that is not JSON both raise `ServerError`, so every failure but a caller
+ * abort reaches the caller as a `PerpsError`. An abort rejects untouched.
+ *
+ * @param label - Names the surface in the error message, e.g. `info request`.
+ * @internal
  */
-export async function infoRequest<T>(
-  apiUrl: string,
+export async function hlPostJson<T>(
+  url: string,
+  label: string,
   body: Record<string, unknown>,
   options?: InfoRequestOptions
 ): Promise<T> {
   const policy = options?.policy ?? HYPERLIQUID_RETRY_DEFAULTS
 
-  let response: Response
   try {
-    response = await fetchWithRetry(
-      `${apiUrl}/info`,
+    const response = await fetchWithRetry(
+      url,
       {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
@@ -122,27 +127,44 @@ export async function infoRequest<T>(
         signal: options?.signal,
       }
     )
+
+    if (!response.ok) {
+      const err = new PerpsError(
+        errorCodeFromStatus(
+          response.status,
+          PerpsErrorCode.ThirdPartyError,
+          HYPERLIQUID_STATUS_ERROR_CODES
+        ),
+        `Hyperliquid ${label} failed: ${response.status}`
+      )
+      err.tool = PROVIDER_KEY
+      throw err
+    }
+
+    return (await response.json()) as T
   } catch (error) {
+    if (error instanceof PerpsError || isAbortError(error)) {
+      throw error
+    }
     const err = new PerpsError(
       PerpsErrorCode.ServerError,
-      error instanceof Error ? error.message : 'Hyperliquid info request failed'
-    )
-    err.tool = PROVIDER_KEY
-    throw err
-  }
-
-  if (!response.ok) {
-    const err = new PerpsError(
-      errorCodeFromStatus(
-        response.status,
-        PerpsErrorCode.ThirdPartyError,
-        HYPERLIQUID_STATUS_ERROR_CODES
-      ),
-      `Hyperliquid info request failed: ${response.status}`
+      error instanceof Error ? error.message : `Hyperliquid ${label} failed`
     )
     err.tool = PROVIDER_KEY
     throw err
   }
+}
 
-  return (await response.json()) as T
+/**
+ * POST to the Hyperliquid `/info` endpoint and return the parsed JSON body.
+ * See {@link hlPostJson} for the transport and error contract.
+ *
+ * @public
+ */
+export function infoRequest<T>(
+  apiUrl: string,
+  body: Record<string, unknown>,
+  options?: InfoRequestOptions
+): Promise<T> {
+  return hlPostJson<T>(`${apiUrl}/info`, 'info request', body, options)
 }

package/src/utils/mapActivity.ts

@@ -1,5 +1,7 @@
+import { type AssetRegistry, PerpsError } from '@lifi/perps-sdk'
 import type {
   ActivityItem,
+  Asset,
   DepositActivity,
   Fee,
   FundingActivity,
@@ -8,13 +10,20 @@ import type {
   TransferActivity,
   WithdrawalActivity,
 } from '@lifi/perps-types'
-import { ActivityType } from '@lifi/perps-types'
-import type { HlFundingUpdate, HlLedgerUpdate } from '../types/index.js'
+import { ActivityType, PerpsErrorCode } from '@lifi/perps-types'
+import Big from 'big.js'
+import type {
+  HlFundingUpdate,
+  HlLedgerUpdate,
+  HlUserFill,
+} from '../types/index.js'
 import {
+  isCollateralTransferDelta,
   isDepositDelta,
   isLiquidationDelta,
   isSendAssetDelta,
   isSpotTransferDelta,
+  isVaultTransferDelta,
   isWithdrawDelta,
 } from '../types/index.js'
 
@@ -30,34 +39,39 @@ const HL_COLLATERAL_SYMBOL = 'USDC'
  */
 const HL_NATIVE_TOKEN_SYMBOL = 'HYPE'
 
+// Hyperliquid reserves spot token index 0 for USDC.
+const HL_COLLATERAL_ASSET_ID = '0'
+
 /**
- * Display symbol for a ledger delta's wire token (`"USDC"`, `"PURR:0x..."`).
- * The colon separates the name from the token id, so the symbol is the part
- * BEFORE it — the opposite half to a market coin's `dex:COIN`, which is why
- * `coinAsset` cannot be reused here.
+ * A ledger row moves a spot asset — a perp contract cannot be sent, received
+ * or withdrawn — so the delta's token symbol resolves inside the spot asset
+ * registry. The HIP-1 ticker auction keeps those symbols unique.
  */
-const ledgerTokenSymbol = (token: string): string => {
-  const separator = token.indexOf(':')
-  return separator === -1 ? token : token.slice(0, separator)
+const resolveLedgerAsset = (symbol: string, registry: AssetRegistry): Asset => {
+  const asset = registry.assets.find(
+    (candidate) => candidate.displaySymbol === symbol
+  )
+  if (asset === undefined) {
+    const error = new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `[hyperliquid] stale or mis-keyed asset registry: unknown spot symbol '${symbol}'`
+    )
+    error.tool = 'hyperliquid'
+    throw error
+  }
+  return asset
 }
 
 /**
- * Map a Hyperliquid non-funding ledger entry to an ActivityItem.
- *
- * Direction for `spotTransfer` and `sendAsset` is derived from
- * `queriedAddress` matching the delta's `user` (OUT) or `destination` (IN).
- * Returns null for unsupported delta types and for same-account moves, where
- * `user === destination === queriedAddress`.
- *
- * @param resolveMarket - Market identity for a venue coin, or `undefined` when
- * the backend market list does not hold it. A liquidated position the resolver
- * cannot identify is dropped.
+ * Map supported ledger entries; exclude same-account moves and unsupported types.
+ * Missing assets throw; unresolved liquidation markets omit only those positions.
  * @public
  */
 export const mapLedgerEntry = (
   entry: HlLedgerUpdate,
   providerKey: string,
   queriedAddress: string,
+  assetRegistry: AssetRegistry,
   resolveMarket: (coin: string) => MarketDisplay | undefined
 ): ActivityItem | null => {
   const { delta } = entry
@@ -67,48 +81,57 @@ export const mapLedgerEntry = (
     timestamp: new Date(entry.time).toISOString(),
   }
 
-  // Handled before the switch: the catch-all arm of `HlLedgerDelta` is a
-  // structural supertype of the concrete delta, so a `switch (delta.type)`
-  // cannot narrow off the discriminant. The user-defined type guard does.
-  if (isSpotTransferDelta(delta)) {
+  if (
+    isSpotTransferDelta(delta) ||
+    isSendAssetDelta(delta) ||
+    isCollateralTransferDelta(delta)
+  ) {
     const queried = queriedAddress.toLowerCase()
     const sender = delta.user.toLowerCase()
     const recipient = delta.destination.toLowerCase()
-
-    // A transfer reports a movement between two accounts. A row whose sender
-    // and recipient are the queried account moves nothing between accounts.
     if (sender === recipient && sender === queried) {
       return null
     }
-
     const direction: 'IN' | 'OUT' = queried === sender ? 'OUT' : 'IN'
-    const counterpartyAddress = direction === 'OUT' ? recipient : sender
-    const meta: Record<string, unknown> = {
-      transferType: 'spotTransfer',
-    }
-    if (delta.usdcValue !== undefined) {
-      meta.usdcValue = delta.usdcValue
-    }
-    if (delta.nonce !== undefined) {
-      meta.nonce = delta.nonce
-    }
     const fees: Fee[] = []
     if (delta.fee !== undefined) {
-      fees.push({ amount: delta.fee, asset: HL_COLLATERAL_SYMBOL })
-    }
-    if (delta.nativeTokenFee !== undefined) {
       fees.push({
-        amount: delta.nativeTokenFee,
-        asset: HL_NATIVE_TOKEN_SYMBOL,
+        amount: delta.fee,
+        asset: isSendAssetDelta(delta)
+          ? delta.feeToken.split(':')[0]
+          : HL_COLLATERAL_SYMBOL,
       })
     }
+    if (
+      !isCollateralTransferDelta(delta) &&
+      delta.nativeTokenFee !== undefined
+    ) {
+      fees.push({ amount: delta.nativeTokenFee, asset: HL_NATIVE_TOKEN_SYMBOL })
+    }
+    const meta: Record<string, unknown> = {
+      transferType: isSendAssetDelta(delta) ? 'sendAsset' : delta.type,
+    }
+    if (!isCollateralTransferDelta(delta)) {
+      if (delta.usdcValue !== undefined) {
+        meta.usdcValue = delta.usdcValue
+      }
+      if (delta.nonce !== undefined) {
+        meta.nonce = delta.nonce
+      }
+    }
+    if (isSendAssetDelta(delta)) {
+      meta.sourceDex = delta.sourceDex
+      meta.destinationDex = delta.destinationDex
+    }
     return {
       ...base,
       type: ActivityType.TRANSFER,
       direction,
-      counterpartyAddress,
-      asset: ledgerTokenSymbol(delta.token),
-      amount: delta.amount,
+      counterpartyAddress: direction === 'OUT' ? recipient : sender,
+      asset: isCollateralTransferDelta(delta)
+        ? assetRegistry.require(HL_COLLATERAL_ASSET_ID)
+        : resolveLedgerAsset(delta.token, assetRegistry),
+      amount: isCollateralTransferDelta(delta) ? delta.usdc : delta.amount,
       ...(fees.length === 0 ? {} : { fees }),
       meta,
       explorerLink: entry.hash
@@ -117,40 +140,44 @@ export const mapLedgerEntry = (
     } satisfies TransferActivity
   }
 
-  // `sendAsset` (wire `type === 'send'`) covers cross-user transfers
-  // (modelled as TRANSFER) and same-user dex moves (returned as null —
-  // overloading TRANSFER for those would lie about direction). Pre-switch
-  // narrowing for the same reason as spotTransfer.
-  if (isSendAssetDelta(delta)) {
+  if (isVaultTransferDelta(delta)) {
     const queried = queriedAddress.toLowerCase()
-    const sender = delta.user.toLowerCase()
-    const recipient = delta.destination.toLowerCase()
-
-    if (sender === recipient && sender === queried) {
-      return null
+    const vault = delta.vault.toLowerCase()
+    if (delta.type === 'vaultDeposit' && queried === vault) {
+      throw new PerpsError(
+        PerpsErrorCode.ValidationError,
+        'Hyperliquid vaultDeposit identifies no depositor for the vault account'
+      )
     }
-
-    const direction: 'IN' | 'OUT' = queried === sender ? 'OUT' : 'IN'
-    const counterpartyAddress = direction === 'OUT' ? recipient : sender
-    const meta: Record<string, unknown> = {
-      transferType: 'sendAsset',
-      sourceDex: delta.sourceDex,
-      destinationDex: delta.destinationDex,
-      usdcValue: delta.usdcValue,
-      nonce: delta.nonce,
+    if (
+      delta.type === 'vaultWithdraw' &&
+      delta.user.toLowerCase() === vault &&
+      queried === vault
+    ) {
+      return null
     }
     return {
       ...base,
       type: ActivityType.TRANSFER,
-      direction,
-      counterpartyAddress,
-      asset: ledgerTokenSymbol(delta.token),
-      amount: delta.amount,
-      fees: [
-        { amount: delta.fee, asset: ledgerTokenSymbol(delta.feeToken) },
-        { amount: delta.nativeTokenFee, asset: HL_NATIVE_TOKEN_SYMBOL },
-      ],
-      meta,
+      direction:
+        delta.type === 'vaultDeposit' || queried === vault ? 'OUT' : 'IN',
+      counterpartyAddress:
+        delta.type === 'vaultWithdraw' && queried === vault
+          ? delta.user.toLowerCase()
+          : vault,
+      asset: assetRegistry.require(HL_COLLATERAL_ASSET_ID),
+      amount:
+        delta.type === 'vaultDeposit' ? delta.usdc : delta.netWithdrawnUsd,
+      meta:
+        delta.type === 'vaultDeposit'
+          ? { transferType: delta.type }
+          : {
+              transferType: delta.type,
+              requestedUsd: delta.requestedUsd,
+              commission: delta.commission,
+              closingCost: delta.closingCost,
+              basis: delta.basis,
+            },
       explorerLink: entry.hash
         ? `https://app.hyperliquid.xyz/explorer/tx/${entry.hash}`
         : undefined,
@@ -163,7 +190,7 @@ export const mapLedgerEntry = (
     return {
       ...base,
       type: ActivityType.DEPOSIT,
-      asset: HL_COLLATERAL_SYMBOL,
+      asset: assetRegistry.require(HL_COLLATERAL_ASSET_ID),
       amount: delta.usdc,
       explorerLink: entry.hash
         ? `https://scan.li.fi/tx/${entry.hash}`
@@ -175,7 +202,7 @@ export const mapLedgerEntry = (
     return {
       ...base,
       type: ActivityType.WITHDRAWAL,
-      asset: HL_COLLATERAL_SYMBOL,
+      asset: assetRegistry.require(HL_COLLATERAL_ASSET_ID),
       amount: delta.usdc,
       ...(delta.fee === undefined
         ? {}
@@ -247,3 +274,64 @@ export const mapFundingActivity = (
     fundingRate: entry.delta.fundingRate,
   }
 }
+
+/**
+ * Build one liquidation activity per liquidation order from the fills of the
+ * liquidated account. Hyperliquid attaches `liquidation` to the fills of both
+ * parties, so only fills whose `liquidatedUser` is the queried address count.
+ * A fill whose hash a ledger liquidation row already carries is the same
+ * event and is skipped. The size sign follows the closed position: a sell
+ * fill closes a long. Groups whose market does not resolve are dropped.
+ * @public
+ */
+export const mapLiquidationFills = (
+  fills: HlUserFill[],
+  providerKey: string,
+  queriedAddress: string,
+  resolveMarket: (coin: string) => MarketDisplay | undefined,
+  ledgerHashes: ReadonlySet<string>
+): LiquidationActivity[] => {
+  const queried = queriedAddress.toLowerCase()
+  const byOrder = new Map<number, HlUserFill[]>()
+  for (const fill of fills) {
+    if (
+      fill.liquidation?.liquidatedUser.toLowerCase() !== queried ||
+      (fill.hash !== undefined && ledgerHashes.has(fill.hash))
+    ) {
+      continue
+    }
+    const group = byOrder.get(fill.oid) ?? []
+    group.push(fill)
+    byOrder.set(fill.oid, group)
+  }
+  return [...byOrder.entries()].flatMap(([oid, group]) => {
+    const [first] = group
+    const market = resolveMarket(first.coin)
+    if (market === undefined) {
+      return []
+    }
+    let size = new Big(0)
+    let notional = new Big(0)
+    let time = first.time
+    for (const fill of group) {
+      size = size.plus(fill.sz)
+      notional = notional.plus(new Big(fill.px).times(fill.sz))
+      time = Math.max(time, fill.time)
+    }
+    return [
+      {
+        id: `liquidation:${oid}`,
+        provider: providerKey,
+        timestamp: new Date(time).toISOString(),
+        type: ActivityType.LIQUIDATION,
+        liquidatedNotionalPosition: notional.toFixed(),
+        liquidatedPositions: [
+          {
+            market,
+            size: (first.side === 'A' ? size : size.neg()).toFixed(),
+          },
+        ],
+      } satisfies LiquidationActivity,
+    ]
+  })
+}

package/src/utils/mapFill.ts

@@ -6,7 +6,6 @@ import {
 import type { Fill, MarketDisplay } from '@lifi/perps-types'
 import {
   FillClassification,
-  FillStatus,
   LiquidityRole,
   OrderSide,
   OrderType,
@@ -42,7 +41,6 @@ export const mapFill = (fill: HlUserFill, market: MarketDisplay): Fill => {
     type: fill.crossed ? undefined : OrderType.LIMIT,
     size: fill.sz,
     price: fill.px,
-    status: FillStatus.FILLED,
     liquidity: fill.crossed ? LiquidityRole.TAKER : LiquidityRole.MAKER,
     filledSize: fill.sz,
     fee: {