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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifi/perps-sdk-provider-hyperliquid",
-  "version": "19.0.0",
+  "version": "20.0.0",
   "description": "Hyperliquid provider plugin for @lifi/perps-sdk",
   "homepage": "https://github.com/lifinance/perps-sdk",
   "bugs": {
@@ -49,10 +49,10 @@
   "dependencies": {
     "big.js": "^7.0.1",
     "viem": "^2.55.18",
-    "@lifi/perps-types": "^17.0.0"
+    "@lifi/perps-types": "^18.0.0"
   },
   "peerDependencies": {
-    "@lifi/perps-sdk": "^19.0.0"
+    "@lifi/perps-sdk": "^20.0.0"
   },
   "publishConfig": {
     "access": "public"

package/src/HyperliquidProvider.ts

@@ -363,7 +363,7 @@ export function hyperliquidProvider(
     getMarketSettings: (
       params: ProviderGetMarketSettingsParams,
       opts?: SDKRequestOptions
-    ): Promise<MarketSettings | undefined> =>
+    ): Promise<MarketSettings> =>
       getMarketSettings(
         contextRef.require(),
         { address: params.address, market: params.market },

package/src/services/getAccount.ts

@@ -1,6 +1,8 @@
 import {
   getMarketRegistry,
   getMarketsContext,
+  maxOf,
+  minOf,
   type ProviderGetAccountParams,
   type SDKRequestOptions,
   stringToFloat,
@@ -14,7 +16,7 @@ import type {
   HyperliquidDexAccountState,
   Position,
 } from '@lifi/perps-types'
-import type Big from 'big.js'
+import Big from 'big.js'
 import { PROVIDER_KEY } from '../constants.js'
 import type { HyperliquidContext } from '../context.js'
 import type {
@@ -66,13 +68,6 @@ interface BalancePartition {
   collateralBalances: Balance[]
 }
 
-const transferableWithin = (venueFigure: Big, units: Big): string => {
-  if (venueFigure.lt(0)) {
-    return '0'
-  }
-  return (venueFigure.gt(units) ? units : venueFigure).toFixed()
-}
-
 const buildBalances = (
   abstraction: HlAbstractionMode | null,
   spotState: HlSpotClearinghouseState,
@@ -84,7 +79,19 @@ const buildBalances = (
   const { balances, collateralBalances } = partitionSpotBalances(
     spotState.balances
       .filter((b) => !assetIsOutcome(b.coin))
-      .map((b) => spotBalance(spotAssetFromToken(b), b.total, priceById)),
+      .map((b) => {
+        const total = toWireBig(b.total, 'spotClearinghouseState.total')
+        return {
+          ...spotBalance(spotAssetFromToken(b), b.total, priceById),
+          transferable: minOf(
+            maxOf(
+              total.minus(toWireBig(b.hold, 'spotClearinghouseState.hold')),
+              new Big(0)
+            ),
+            total
+          ).toFixed(),
+        }
+      }),
     quoteAssetIds
   )
 
@@ -107,10 +114,13 @@ const buildBalances = (
         units: value.toFixed(),
         valueUsd: value.toFixed(),
         price: '1',
-        transferable: transferableWithin(
-          toWireBig(state.withdrawable, 'clearinghouseState.withdrawable'),
+        transferable: minOf(
+          maxOf(
+            toWireBig(state.withdrawable, 'clearinghouseState.withdrawable'),
+            new Big(0)
+          ),
           value
-        ),
+        ).toFixed(),
       })
     }
   }

package/src/services/getActivity.ts

@@ -24,7 +24,9 @@ import type {
   HlUserNonFundingLedgerUpdates,
 } from '../types/index.js'
 import {
+  isBorrowLendDelta,
   isCollateralTransferDelta,
+  isCStakingTransferDelta,
   isDepositDelta,
   isLiquidationDelta,
   isSendAssetDelta,
@@ -130,7 +132,9 @@ const fetchActivityData = async (
             (isSpotTransferDelta(entry.delta) ||
               isSendAssetDelta(entry.delta) ||
               isCollateralTransferDelta(entry.delta) ||
-              isVaultTransferDelta(entry.delta))))
+              isVaultTransferDelta(entry.delta) ||
+              isCStakingTransferDelta(entry.delta) ||
+              isBorrowLendDelta(entry.delta))))
       ) {
         return []
       }

package/src/services/getMarketSettings.ts

@@ -1,11 +1,12 @@
-import type { SDKRequestOptions } from '@lifi/perps-sdk'
+import { PerpsError, type SDKRequestOptions } from '@lifi/perps-sdk'
 import {
   MarginMode,
   type MarketRef,
   type MarketSettings,
+  PerpsErrorCode,
 } from '@lifi/perps-types'
 import type { Address } from 'viem'
-import { SPOT_MARKET_ID } from '../constants.js'
+import { PROVIDER_KEY, SPOT_MARKET_ID } from '../constants.js'
 import type { HyperliquidContext } from '../context.js'
 import { fetchActiveAssetData } from './activeAssetData.js'
 
@@ -22,17 +23,23 @@ export interface GetMarketSettingsParams {
 /**
  * The user's venue-stored margin mode and leverage for one perps market,
  * read from `activeAssetData` — present whether or not a position is open.
- * @throws {PerpsError} On Hyperliquid REST error, network, or parsing failures.
+ * @throws {PerpsError} `ValidationError` for a spot market; `SDKError` when
+ *   the response carries no positive leverage; any other `PerpsError` on
+ *   Hyperliquid REST error, network, or parsing failures.
  * @public
  */
 export const getMarketSettings = async (
   context: HyperliquidContext,
   params: GetMarketSettingsParams,
   options?: SDKRequestOptions
-): Promise<MarketSettings | undefined> => {
-  // Spot markets carry no leverage state on the venue.
+): Promise<MarketSettings> => {
   if (params.market.categoryId === SPOT_MARKET_ID) {
-    return undefined
+    const error = new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `Hyperliquid market '${params.market.marketId}' is a spot market and carries no leverage setting`
+    )
+    error.tool = PROVIDER_KEY
+    throw error
   }
   const data = await fetchActiveAssetData(
     context,
@@ -41,8 +48,13 @@ export const getMarketSettings = async (
     options
   )
   const leverage = data.leverage
-  if (!leverage) {
-    return undefined
+  if (!leverage || !(leverage.value > 0)) {
+    const error = new PerpsError(
+      PerpsErrorCode.SDKError,
+      `Hyperliquid returned no leverage for market '${params.market.marketId}'`
+    )
+    error.tool = PROVIDER_KEY
+    throw error
   }
   return {
     marginMode:

package/src/types/ledger.ts

@@ -130,6 +130,38 @@ export type HlLiquidationDelta = {
   liquidatedPositions?: HlLiquidatedPosition[]
 }
 
+/**
+ * Hyperliquid `cStakingTransfer` ledger delta. Moves `token` between the
+ * account's spot balance and its staking balance; `isDeposit` is `true` for a
+ * move into staking. `amount` is unsigned. A completed unstake row carries the
+ * zero hash.
+ * @public
+ */
+export type HlCStakingTransferDelta = {
+  type: 'cStakingTransfer'
+  token: string
+  amount: string
+  isDeposit: boolean
+}
+
+/** Borrow-lend market action named by a `borrowLend` ledger delta. @public */
+export type HlBorrowLendOperation = 'supply' | 'withdraw' | 'borrow' | 'repay'
+
+/**
+ * Hyperliquid `borrowLend` ledger delta. Moves `token` between the account's
+ * spot balance and the borrow-lend market; `operation` gives the direction and
+ * `amount` is unsigned. `interestAmount` is the accrued interest that
+ * `amount` includes on a `withdraw` or `repay`, and `"0.0"` otherwise.
+ * @public
+ */
+export type HlBorrowLendDelta = {
+  type: 'borrowLend'
+  token: string
+  operation: HlBorrowLendOperation
+  amount: string
+  interestAmount: string
+}
+
 /**
  * Union of known Hyperliquid non-funding ledger deltas plus an open fallback
  * for endpoint variants the provider does not map.
@@ -143,6 +175,8 @@ export type HlLedgerDelta =
   | HlDepositDelta
   | HlWithdrawDelta
   | HlLiquidationDelta
+  | HlCStakingTransferDelta
+  | HlBorrowLendDelta
   | {
       type: string
       usdc?: string
@@ -202,6 +236,33 @@ export const isLiquidationDelta = (
   delta: HlLedgerDelta
 ): delta is HlLiquidationDelta => delta.type === 'liquidation'
 
+/**
+ * Type guard for `HlCStakingTransferDelta`. `isDeposit` is part of the guard:
+ * a row without a boolean `isDeposit` names no direction for the movement.
+ * @public
+ */
+export const isCStakingTransferDelta = (
+  delta: HlLedgerDelta
+): delta is HlCStakingTransferDelta =>
+  delta.type === 'cStakingTransfer' &&
+  'isDeposit' in delta &&
+  typeof delta.isDeposit === 'boolean'
+
+const HL_BORROW_LEND_OPERATIONS: ReadonlySet<unknown> =
+  new Set<HlBorrowLendOperation>(['supply', 'withdraw', 'borrow', 'repay'])
+
+/**
+ * Type guard for `HlBorrowLendDelta`. The operation is part of the guard: an
+ * unknown operation names no direction for the movement.
+ * @public
+ */
+export const isBorrowLendDelta = (
+  delta: HlLedgerDelta
+): delta is HlBorrowLendDelta =>
+  delta.type === 'borrowLend' &&
+  'operation' in delta &&
+  HL_BORROW_LEND_OPERATIONS.has(delta.operation)
+
 /**
  * One timestamped non-funding ledger update. `time` is milliseconds since
  * epoch and `hash` is the upstream transaction identifier.

package/src/utils/mapActivity.ts

@@ -17,13 +17,17 @@ import type {
 } from '@lifi/perps-types'
 import { ActivityType, PerpsErrorCode } from '@lifi/perps-types'
 import Big from 'big.js'
+import { zeroHash } from 'viem'
 import type {
+  HlBorrowLendOperation,
   HlFundingUpdate,
   HlLedgerUpdate,
   HlUserFill,
 } from '../types/index.js'
 import {
+  isBorrowLendDelta,
   isCollateralTransferDelta,
+  isCStakingTransferDelta,
   isDepositDelta,
   isLiquidationDelta,
   isSendAssetDelta,
@@ -47,6 +51,17 @@ const HL_NATIVE_TOKEN_SYMBOL = 'HYPE'
 // Hyperliquid reserves spot token index 0 for USDC.
 const HL_COLLATERAL_ASSET_ID = '0'
 
+/**
+ * Direction relative to the account's spot balance, the same frame as an
+ * outbound `vaultDeposit`.
+ */
+const BORROW_LEND_DIRECTION: Record<HlBorrowLendOperation, 'IN' | 'OUT'> = {
+  supply: 'OUT',
+  withdraw: 'IN',
+  borrow: 'IN',
+  repay: 'OUT',
+}
+
 /**
  * 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
@@ -69,6 +84,7 @@ const resolveLedgerAsset = (symbol: string, registry: AssetRegistry): Asset => {
 
 /**
  * Map supported ledger entries; exclude same-account moves and unsupported types.
+ * Staking and borrow-lend moves map with the queried account as counterparty.
  * Missing assets throw; unresolved liquidation markets omit only those positions.
  * @public
  */
@@ -143,6 +159,46 @@ export const mapLedgerEntry = (
     } satisfies TransferActivity
   }
 
+  if (isCStakingTransferDelta(delta) || isBorrowLendDelta(delta)) {
+    // A completed unstake is a system event with the zero hash and no venue
+    // transaction, so the id is synthesized and no explorer link applies.
+    const hasTransaction = entry.hash !== zeroHash
+    const direction = isCStakingTransferDelta(delta)
+      ? delta.isDeposit
+        ? 'OUT'
+        : 'IN'
+      : BORROW_LEND_DIRECTION[delta.operation]
+    const action = isCStakingTransferDelta(delta) ? direction : delta.operation
+    return {
+      ...base,
+      ...(hasTransaction
+        ? {}
+        : {
+            id: `${delta.type}:${delta.token}:${action}:${delta.amount}:${base.timestamp}`,
+          }),
+      type: ActivityType.TRANSFER,
+      direction,
+      counterpartyAddress: queriedAddress.toLowerCase(),
+      asset: resolveLedgerAsset(delta.token, assetRegistry),
+      amount: delta.amount,
+      meta: isCStakingTransferDelta(delta)
+        ? { transferType: delta.type }
+        : {
+            transferType: delta.type,
+            operation: delta.operation,
+            interestAmount: delta.interestAmount,
+          },
+      ...(hasTransaction
+        ? {
+            explorerLink: explorerTxUrl(
+              ExplorerChainId.HYPERLIQUID,
+              entry.hash
+            ),
+          }
+        : {}),
+    } satisfies TransferActivity
+  }
+
   if (isVaultTransferDelta(delta)) {
     const queried = queriedAddress.toLowerCase()
     const vault = delta.vault.toLowerCase()

package/src/utils/withdrawableBalances.ts

@@ -17,7 +17,8 @@ import { toWireBig } from './decimal.js'
  *
  * @param quoteAssetId - `Asset.id` the perps-route row is keyed by.
  * @param withdrawalFee - Flat venue fee in quote-asset units, set on every
- *   quote-asset row. Absent leaves every row without a fee.
+ *   quote-asset row. Hyperliquid deducts it from the requested amount. Absent
+ *   leaves every row without a fee.
  * @public
  */
 export const hyperliquidWithdrawableBalances = (
@@ -32,8 +33,12 @@ export const hyperliquidWithdrawableBalances = (
     withdrawalFee === undefined
       ? undefined
       : toWireBig(withdrawalFee, 'providers.withdrawalFeeUsd').toFixed()
-  const feeFor = (assetId: string) =>
-    fee === undefined || assetId !== quoteAssetId ? {} : { withdrawalFee: fee }
+  const feeFor = (
+    assetId: string
+  ): Pick<ProviderWithdrawableBalance, 'withdrawalFee' | 'isFeeDeducted'> =>
+    fee === undefined || assetId !== quoteAssetId
+      ? {}
+      : { withdrawalFee: fee, isFeeDeducted: true }
 
   if (isUnifiedAbstraction(abstraction)) {
     for (const balance of spotState.balances) {