@lifi/perps-sdk-provider-hyperliquid 13.0.1 → 15.0.0

package/src/utils/mapActivity.ts

@@ -1,5 +1,12 @@
+import {
+  type AssetRegistry,
+  ExplorerChainId,
+  explorerTxUrl,
+  PerpsError,
+} from '@lifi/perps-sdk'
 import type {
   ActivityItem,
+  Asset,
   DepositActivity,
   Fee,
   FundingActivity,
@@ -8,13 +15,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 +44,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,93 +86,102 @@ 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
-        ? `https://app.hyperliquid.xyz/explorer/tx/${entry.hash}`
-        : undefined,
+      explorerLink: explorerTxUrl(ExplorerChainId.HYPERLIQUID, entry.hash),
     } 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,
-      explorerLink: entry.hash
-        ? `https://app.hyperliquid.xyz/explorer/tx/${entry.hash}`
-        : undefined,
+      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: explorerTxUrl(ExplorerChainId.HYPERLIQUID, entry.hash),
     } satisfies TransferActivity
   }
 
@@ -163,11 +191,9 @@ 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}`
-        : undefined,
+      explorerLink: explorerTxUrl(ExplorerChainId.HYPERLIQUID, entry.hash),
     } satisfies DepositActivity
   }
 
@@ -175,14 +201,12 @@ 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
         ? {}
         : { fee: { amount: delta.fee, asset: HL_COLLATERAL_SYMBOL } }),
-      explorerLink: entry.hash
-        ? `https://scan.li.fi/tx/${entry.hash}`
-        : undefined,
+      explorerLink: explorerTxUrl(ExplorerChainId.HYPERLIQUID, entry.hash),
     } satisfies WithdrawalActivity
   }
 
@@ -247,3 +271,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: {