@lifi/perps-sdk 0.2.0-alpha.0 → 1.0.0

package/src/utils/calculations.ts

@@ -6,6 +6,16 @@
  * values for critical financial parameters.
  */
 
+import type {
+  FeeTier,
+  Market,
+  MarketPrice,
+  OrderbookLevel,
+  Quote,
+  QuoteSide,
+  TradeType,
+} from '@lifi/perps-types'
+
 /**
  * Calculate position size in asset units from margin.
  *
@@ -13,6 +23,11 @@
  * @param leverage - Position leverage
  * @param price - Current asset price
  * @returns Position size in asset units
+ * @example
+ * ```ts
+ * calculatePositionSize(100, 10, 2000) // 0.5 (ETH at $2000)
+ * ```
+ * @public
  */
 export function calculatePositionSize(
   marginUsd: number,
@@ -28,6 +43,7 @@ export function calculatePositionSize(
  * @param size - Position size in asset units
  * @param price - Current asset price
  * @returns Notional value in USD
+ * @public
  */
 export function calculateNotionalValue(size: number, price: number): number {
   return Math.abs(size) * price
@@ -40,6 +56,7 @@ export function calculateNotionalValue(size: number, price: number): number {
  * @param currentPrice - Current market price
  * @param size - Position size (positive for long, negative for short)
  * @returns Unrealized PnL in USD
+ * @public
  */
 export function calculateUnrealizedPnl(
   entryPrice: number,
@@ -55,6 +72,7 @@ export function calculateUnrealizedPnl(
  * @param pnl - Profit/loss in USD
  * @param margin - Initial margin in USD
  * @returns ROE as percentage (e.g., 10 for 10%)
+ * @public
  */
 export function calculateRoe(pnl: number, margin: number): number {
   if (margin === 0) {
@@ -69,6 +87,7 @@ export function calculateRoe(pnl: number, margin: number): number {
  * @param notionalValue - Position notional value in USD
  * @param leverage - Position leverage
  * @returns Required margin in USD
+ * @public
  */
 export function calculateRequiredMargin(
   notionalValue: number,
@@ -83,6 +102,7 @@ export function calculateRequiredMargin(
  * @param sizeUsd - Position size in USD (notional value)
  * @param feeRate - Fee rate as decimal (e.g., 0.00035 for 0.035%)
  * @returns Estimated fee in USD
+ * @public
  */
 export function estimateFees(sizeUsd: number, feeRate: number): number {
   return sizeUsd * feeRate
@@ -95,6 +115,7 @@ export function estimateFees(sizeUsd: number, feeRate: number): number {
  * @param slippagePercent - Slippage tolerance as percentage (e.g., 0.5 for 0.5%)
  * @param isBuy - True if buying (price goes up), false if selling (price goes down)
  * @returns Price adjusted for slippage
+ * @public
  */
 export function applySlippage(
   price: number,
@@ -105,10 +126,80 @@ export function applySlippage(
   return isBuy ? price * multiplier : price / multiplier
 }
 
-// ---------------------------------------------------------------------------
-// TP/SL expected P&L calculations
-// ---------------------------------------------------------------------------
+/**
+ * Distance from the current price to the liquidation price, as a percentage of
+ * the current price.
+ *
+ * @param liquidationPrice - The position's liquidation price
+ * @param currentPrice - Current market price
+ * @returns Absolute distance as a percentage, or 0 when current price is zero
+ * @public
+ */
+export function liquidationDistancePercent(params: {
+  liquidationPrice: number
+  currentPrice: number
+}): number {
+  const { liquidationPrice, currentPrice } = params
+  if (currentPrice === 0) {
+    return 0
+  }
+  return Math.abs((liquidationPrice - currentPrice) / currentPrice) * 100
+}
+
+/**
+ * Effective leverage of an open position.
+ *
+ * leverage = positionValueUsd / marginUsd
+ *
+ * @param positionValueUsd - Position notional value in USD
+ * @param marginUsd - Margin backing the position in USD
+ * @returns Effective leverage, or 0 when margin is zero
+ * @public
+ */
+export function effectiveLeverage(params: {
+  positionValueUsd: number
+  marginUsd: number
+}): number {
+  const { positionValueUsd, marginUsd } = params
+  if (marginUsd === 0) {
+    return 0
+  }
+  return positionValueUsd / marginUsd
+}
+
+/**
+ * Margin that can be removed from a position while keeping its leverage at or
+ * below the asset's maximum.
+ *
+ * The minimum margin to stay within `maxLeverage` is the required margin for
+ * the position's notional (see {@link calculateRequiredMargin}); anything above
+ * that is removable.
+ *
+ * @param marginUsed - Margin currently backing the position in USD
+ * @param positionValueUsd - Position notional value in USD
+ * @param maxLeverage - Maximum leverage allowed for the asset
+ * @returns Removable margin in USD (never negative); falls back to the full
+ *   `marginUsed` when `maxLeverage` is zero (no constraint available)
+ * @public
+ */
+export function removableMargin(params: {
+  marginUsed: number
+  positionValueUsd: number
+  maxLeverage: number
+}): number {
+  const { marginUsed, positionValueUsd, maxLeverage } = params
+  if (maxLeverage === 0) {
+    return marginUsed
+  }
+  const minMargin = calculateRequiredMargin(positionValueUsd, maxLeverage)
+  return Math.max(0, marginUsed - minMargin)
+}
 
+/**
+ * Signed expected PnL for a trigger price — see {@link calculateExpectedPnl}.
+ *
+ * @public
+ */
 export interface ExpectedPnl {
   amount: number
   percent: number
@@ -123,6 +214,7 @@ export interface ExpectedPnl {
  * @param leverage - Position leverage multiplier
  * @param isLong - True for long positions, false for short
  * @param margin - Margin amount in USD
+ * @public
  */
 export function calculateExpectedPnl(
   triggerPrice: number,
@@ -149,6 +241,7 @@ export function calculateExpectedPnl(
  * @param entryPrice - Position entry price
  * @param leverage - Position leverage multiplier
  * @param isLong - True for long positions, false for short
+ * @public
  */
 export function priceFromPercent(
   percent: number,
@@ -170,6 +263,7 @@ export function priceFromPercent(
  * @param entryPrice - Position entry price
  * @param leverage - Position leverage multiplier
  * @param isLong - True for long positions, false for short
+ * @public
  */
 export function percentFromPrice(
   price: number,
@@ -184,10 +278,6 @@ export function percentFromPrice(
   return (priceDiff / entryPrice) * leverage * 100
 }
 
-// ---------------------------------------------------------------------------
-// Realized PnL percentage
-// ---------------------------------------------------------------------------
-
 /**
  * Calculate realized PnL as a percentage of position value at close.
  *
@@ -195,6 +285,7 @@ export function percentFromPrice(
  * @param size - Position size in asset units at close
  * @param price - Price at close
  * @returns PnL as a percentage of position value
+ * @public
  */
 export function calculateRealizedPnlPercent(
   realizedPnl: number,
@@ -207,3 +298,109 @@ export function calculateRealizedPnlPercent(
   }
   return (realizedPnl / positionValue) * 100
 }
+
+/** Result of {@link walkOrderbook} — the fill obtained for a USD-notional walk. */
+interface BookWalk {
+  /** Base amount filled. */
+  baseSize: number
+  /** Notional actually filled in USD (equals the requested size unless the book ran dry). */
+  filledNotional: number
+  /** Volume-weighted average fill price, or 0 when the book is empty. */
+  vwap: number
+  /** True when the levels could not absorb the requested notional. */
+  insufficientLiquidity: boolean
+}
+
+/**
+ * Walk one side of an orderbook to fill `sizeUsd` notional, accumulating base
+ * size and notional level-by-level to derive the VWAP fill. Levels are consumed
+ * in array order — the caller passes asks for a buy and bids for a sell, each
+ * already ordered best-price-first. When the book cannot absorb the full
+ * notional, the walk stops at the last level and flags `insufficientLiquidity`,
+ * returning the best obtainable fill.
+ *
+ * @public
+ */
+export function walkOrderbook(
+  levels: OrderbookLevel[],
+  sizeUsd: number
+): BookWalk {
+  let remaining = sizeUsd
+  let baseSize = 0
+  let filledNotional = 0
+  for (const level of levels) {
+    if (remaining <= 0) {
+      break
+    }
+    const price = Number.parseFloat(level.price)
+    const levelNotional = Number.parseFloat(level.size) * price
+    const take = Math.min(remaining, levelNotional)
+    filledNotional += take
+    baseSize += take / price
+    remaining -= take
+  }
+  return {
+    baseSize,
+    filledNotional,
+    vwap: baseSize === 0 ? 0 : filledNotional / baseSize,
+    insufficientLiquidity: remaining > 0,
+  }
+}
+
+/** Inputs to {@link buildQuote} — the resolved market, its live price, its book, and the trade ask. */
+interface BuildQuoteInput {
+  provider: string
+  symbol: string
+  type: TradeType
+  side: QuoteSide
+  sizeUsd: number
+  market: Market
+  price: MarketPrice
+  bids: OrderbookLevel[]
+  asks: OrderbookLevel[]
+  /** Public base-tier fees for the venue; `isDefaultFeeTier` is always set true. */
+  feeTier: FeeTier
+  timestamp: number
+}
+
+/**
+ * Build a {@link Quote} from a resolved market, its live {@link MarketPrice},
+ * and its orderbook snapshot. Pure: walks the relevant side (buy → asks,
+ * sell → bids) for the VWAP fill, derives the price impact in basis points
+ * versus mark, applies the base taker fee on the filled notional, and carries
+ * the market's `funding` (`null` for spot, which has none).
+ *
+ * @public
+ */
+export function buildQuote(input: BuildQuoteInput): Quote {
+  const { market, price, side, sizeUsd, feeTier } = input
+  const markPrice = Number.parseFloat(price.markPrice)
+  const levels = side === 'buy' ? input.asks : input.bids
+  const walk = walkOrderbook(levels, sizeUsd)
+  const priceImpactBps =
+    markPrice === 0 || walk.vwap === 0
+      ? 0
+      : Math.abs((walk.vwap - markPrice) / markPrice) * 10_000
+  const feeUsd = estimateFees(
+    walk.filledNotional,
+    Number.parseFloat(feeTier.taker)
+  )
+  return {
+    provider: input.provider,
+    symbol: input.symbol,
+    marketId: market.id,
+    type: input.type,
+    side,
+    sizeUsd: sizeUsd.toString(),
+    baseSize: walk.baseSize.toString(),
+    markPrice: price.markPrice,
+    expectedFillPrice: walk.vwap.toString(),
+    priceImpactBps: priceImpactBps.toString(),
+    feeTier,
+    isDefaultFeeTier: true,
+    feeUsd: feeUsd.toString(),
+    funding: price.funding ?? null,
+    insufficientLiquidity: walk.insufficientLiquidity,
+    timestamp: input.timestamp,
+  }
+}

package/src/utils/depositChain.ts

@@ -0,0 +1,37 @@
+import type { AccountConfig } from '@lifi/perps-types'
+import { ChainId } from '@lifi/types'
+
+/**
+ * Perps provider keys that have a declared LI.FI deposit-target chain.
+ *
+ * @public
+ */
+export type DepositProviderKey = AccountConfig['provider']
+
+/**
+ * Declared single source of truth: perps provider key → the LI.FI chain a
+ * client opens the swap widget against to fund that provider. Values come from
+ * the `@lifi/types` `ChainId` enum; never hardcode the numeric ids.
+ *
+ * @public
+ */
+export const LIFI_DEPOSIT_CHAIN_BY_PROVIDER: Record<
+  DepositProviderKey,
+  ChainId
+> = {
+  hyperliquid: ChainId.HPL,
+  lighter: ChainId.LTR,
+}
+
+/**
+ * Resolve the LI.FI deposit-target chain for a perps provider key.
+ *
+ * @returns The `@lifi/types` `ChainId`, or `undefined` for a provider key with
+ *   no declared deposit chain (the `/providers` wire key is an open `string`).
+ * @public
+ */
+export function lifiDepositChainForProvider(
+  providerKey: string
+): ChainId | undefined {
+  return LIFI_DEPOSIT_CHAIN_BY_PROVIDER[providerKey as DepositProviderKey]
+}

package/src/utils/explorer.ts

@@ -0,0 +1,51 @@
+/**
+ * Block-explorer URL resolution.
+ *
+ * Provider plugins resolve a tx hash to a fully-qualified explorer URL during
+ * wire→domain mapping. The explorer target is a function of the settling chain,
+ * so the map is keyed by chain id rather than by provider.
+ */
+
+/**
+ * Settling chains a perps tx can be observed on.
+ *
+ * @public
+ */
+export const ExplorerChainId = {
+  ETHEREUM: 1,
+  ARBITRUM_ONE: 42161,
+  LIGHTER: 304,
+  HYPERLIQUID: 999,
+} as const
+
+/**
+ * Union of {@link ExplorerChainId} values.
+ *
+ * @public
+ */
+export type ExplorerChainId =
+  (typeof ExplorerChainId)[keyof typeof ExplorerChainId]
+
+const TX_BASE_URL_BY_CHAIN: Record<ExplorerChainId, string> = {
+  [ExplorerChainId.ETHEREUM]: 'https://etherscan.io/tx/',
+  [ExplorerChainId.ARBITRUM_ONE]: 'https://arbiscan.io/tx/',
+  [ExplorerChainId.LIGHTER]: 'https://app.lighter.xyz/explorer/logs/',
+  [ExplorerChainId.HYPERLIQUID]: 'https://app.hyperliquid.xyz/explorer/tx/',
+}
+
+/**
+ * Build a fully-resolved block-explorer URL for a tx on a known chain.
+ *
+ * @returns The explorer URL, or `undefined` when the hash is empty (no on-chain
+ *   tx to link).
+ * @public
+ */
+export function explorerTxUrl(
+  chainId: ExplorerChainId,
+  txHash: string | undefined
+): string | undefined {
+  if (!txHash) {
+    return undefined
+  }
+  return `${TX_BASE_URL_BY_CHAIN[chainId]}${txHash}`
+}

package/src/utils/fillClassification.ts

@@ -0,0 +1,51 @@
+import { FillClassification } from '@lifi/perps-types'
+
+/**
+ * Classify a perpetual fill into the Open/Close/Increase/Reduce/Switch
+ * taxonomy from `FillClassification`.
+ *
+ * @param startPosition Signed position held BEFORE this fill (`> 0` long,
+ *   `< 0` short, `0` flat).
+ * @param side Hyperliquid-style: `'B'` for buy, anything else for sell.
+ * @param sz Unsigned fill size, parsed with `parseFloat`.
+ * @public
+ */
+export function classifyFillFromPosition(
+  startPosition: string,
+  side: string,
+  sz: string
+): FillClassification {
+  const start = parseFloat(startPosition)
+  const delta = side === 'B' ? parseFloat(sz) : -parseFloat(sz)
+  const end = start + delta
+
+  if (start === 0) {
+    return end > 0
+      ? FillClassification.OPENED_LONG
+      : FillClassification.OPENED_SHORT
+  }
+
+  if (start > 0) {
+    if (end === 0) {
+      return FillClassification.CLOSED_LONG
+    }
+    if (end < 0) {
+      return FillClassification.SWITCHED_SHORT
+    }
+    if (end > start) {
+      return FillClassification.INCREASED_LONG
+    }
+    return FillClassification.REDUCED_LONG
+  }
+
+  if (end === 0) {
+    return FillClassification.CLOSED_SHORT
+  }
+  if (end > 0) {
+    return FillClassification.SWITCHED_LONG
+  }
+  if (end < start) {
+    return FillClassification.INCREASED_SHORT
+  }
+  return FillClassification.REDUCED_SHORT
+}

package/src/utils/format.ts

@@ -0,0 +1,212 @@
+/**
+ * Options shared by the human-facing display formatters.
+ *
+ * @public
+ */
+export interface FormatOptions {
+  /** Fixed number of decimal places. Defaults are per-formatter. */
+  decimals?: number
+  /** Rendered when the value is null/undefined/NaN/non-finite. Defaults to `'—'`. */
+  placeholder?: string
+  /** BCP 47 locale controlling digit grouping and separators (e.g. `'en-US'`). */
+  locale?: string
+}
+
+const DEFAULT_PLACEHOLDER = '—'
+
+type FormatInput = number | string | null | undefined
+
+/**
+ * Tolerantly coerce a display input to a finite number.
+ *
+ * Strips `$`, `,`, and surrounding whitespace from strings. Returns `null`
+ * when the value is null/undefined/blank or does not resolve to a finite
+ * number, so callers can render a placeholder instead of `$0.00` or `$NaN`.
+ */
+function toFiniteNumber(value: FormatInput): number | null {
+  let n: number
+  if (typeof value === 'string') {
+    const cleaned = value.replace(/[$,\s]/g, '')
+    if (!cleaned) {
+      return null
+    }
+    n = Number(cleaned)
+  } else if (typeof value === 'number') {
+    n = value
+  } else {
+    return null
+  }
+  return Number.isFinite(n) ? n : null
+}
+
+/**
+ * Round to `decimals` then split into a sign (`'-'` or `''`) and the
+ * locale-formatted absolute body. Deriving the sign from the rounded value
+ * avoids `-$0.00` for values that round to zero.
+ */
+function signAndBody(
+  n: number,
+  decimals: number,
+  locale: string | undefined,
+  grouping: boolean
+): { sign: '-' | ''; body: string } {
+  const rounded = Number(n.toFixed(decimals))
+  const sign = rounded < 0 ? '-' : ''
+  const body = Math.abs(rounded).toLocaleString(locale, {
+    minimumFractionDigits: decimals,
+    maximumFractionDigits: decimals,
+    useGrouping: grouping,
+  })
+  return { sign, body }
+}
+
+/**
+ * Auto-detect a sensible number of decimal places from a value's magnitude:
+ * `>=1` → 2, `>=0.1` → 4, `>=0.01` → 5, otherwise 6.
+ */
+function autoDecimals(abs: number): number {
+  if (abs >= 1) {
+    return 2
+  }
+  if (abs >= 0.1) {
+    return 4
+  }
+  if (abs >= 0.01) {
+    return 5
+  }
+  return 6
+}
+
+/**
+ * Format a USD value, unsigned: `$1,234.50`, `-$1,500.00`, `$0.00`.
+ *
+ * Two decimal places with locale digit grouping. Negatives place the `-`
+ * before the `$`. Null/undefined/non-finite input renders the placeholder.
+ *
+ * @public
+ */
+export function formatUsd(
+  value: FormatInput,
+  options: FormatOptions = {}
+): string {
+  const { decimals = 2, placeholder = DEFAULT_PLACEHOLDER, locale } = options
+  const n = toFiniteNumber(value)
+  if (n === null) {
+    return placeholder
+  }
+  const { sign, body } = signAndBody(n, decimals, locale, true)
+  return `${sign}$${body}`
+}
+
+/**
+ * Format a USD value with an explicit sign: `+$1.43`, `-$1.43`, `$0.00`.
+ *
+ * The sign is derived after rounding, so sub-cent magnitudes render `$0.00`
+ * (no spurious `+`/`-`). Null/undefined/non-finite input renders the
+ * placeholder.
+ *
+ * @public
+ */
+export function formatSignedUsd(
+  value: FormatInput,
+  options: FormatOptions = {}
+): string {
+  const { decimals = 2, placeholder = DEFAULT_PLACEHOLDER, locale } = options
+  const n = toFiniteNumber(value)
+  if (n === null) {
+    return placeholder
+  }
+  const rounded = Number(n.toFixed(decimals))
+  const sign = rounded > 0 ? '+' : rounded < 0 ? '-' : ''
+  const body = Math.abs(rounded).toLocaleString(locale, {
+    minimumFractionDigits: decimals,
+    maximumFractionDigits: decimals,
+    useGrouping: true,
+  })
+  return `${sign}$${body}`
+}
+
+/**
+ * Format a percentage with an explicit sign and no grouping: `+1.43%`,
+ * `-1.43%`, `0.00%`.
+ *
+ * The sign is derived after rounding, so sub-threshold magnitudes render
+ * `0.00%`. Null/undefined/non-finite input renders the placeholder.
+ *
+ * @public
+ */
+export function formatSignedPercent(
+  value: FormatInput,
+  options: FormatOptions = {}
+): string {
+  const { decimals = 2, placeholder = DEFAULT_PLACEHOLDER, locale } = options
+  const n = toFiniteNumber(value)
+  if (n === null) {
+    return placeholder
+  }
+  const rounded = Number(n.toFixed(decimals))
+  const sign = rounded > 0 ? '+' : rounded < 0 ? '-' : ''
+  const body = Math.abs(rounded).toLocaleString(locale, {
+    minimumFractionDigits: decimals,
+    maximumFractionDigits: decimals,
+    useGrouping: false,
+  })
+  return `${sign}${body}%`
+}
+
+/**
+ * Format a price, unsigned, with decimals auto-detected from magnitude:
+ * `$1,234.50`, `$0.1234`, `-$1,500.00`.
+ *
+ * Decimals follow {@link autoDecimals} unless `options.decimals` is given.
+ * Grouping applies once the absolute value reaches 1000. Negatives place the
+ * `-` before the `$`. Null/undefined/non-finite input renders the placeholder.
+ *
+ * @public
+ */
+export function formatPrice(
+  value: FormatInput,
+  options: FormatOptions = {}
+): string {
+  const { placeholder = DEFAULT_PLACEHOLDER, locale } = options
+  const n = toFiniteNumber(value)
+  if (n === null) {
+    return placeholder
+  }
+  const abs = Math.abs(n)
+  const decimals = options.decimals ?? autoDecimals(abs)
+  const { sign, body } = signAndBody(n, decimals, locale, abs >= 1000)
+  return `${sign}$${body}`
+}
+
+/**
+ * Format a USD value compactly with a `B`/`M`/`K` suffix: `$1.23B`, `$45.6M`,
+ * `$789.0K`, `$12.34`.
+ *
+ * Negatives place the `-` before the `$`. Null/undefined/non-finite input
+ * renders the placeholder.
+ *
+ * @public
+ */
+export function formatCompactUsd(
+  value: FormatInput,
+  options: FormatOptions = {}
+): string {
+  const { decimals = 2, placeholder = DEFAULT_PLACEHOLDER } = options
+  const n = toFiniteNumber(value)
+  if (n === null) {
+    return placeholder
+  }
+  const sign = n < 0 ? '-' : ''
+  const abs = Math.abs(n)
+  if (abs >= 1_000_000_000) {
+    return `${sign}$${(abs / 1_000_000_000).toFixed(decimals)}B`
+  }
+  if (abs >= 1_000_000) {
+    return `${sign}$${(abs / 1_000_000).toFixed(decimals)}M`
+  }
+  if (abs >= 1_000) {
+    return `${sign}$${(abs / 1_000).toFixed(decimals)}K`
+  }
+  return `${sign}$${abs.toFixed(decimals)}`
+}