@lifi/perps-sdk-provider-lighter 7.0.0 → 8.0.0

package/src/utils/decimal.ts

@@ -0,0 +1,52 @@
+import { PerpsError } from '@lifi/perps-sdk'
+import { PerpsErrorCode } from '@lifi/perps-types'
+import Big from 'big.js'
+
+/**
+ * Exact-decimal parse of a venue decimal string; null when absent or
+ * unparsable, so callers can gate on presence before deriving.
+ * @public
+ */
+export const toBigOrNull = (value: string | undefined): Big | null => {
+  if (value === undefined) {
+    return null
+  }
+  try {
+    return new Big(value)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Parse a required venue decimal and identify the bad field on failure.
+ * @public
+ */
+export const toRequiredBig = (
+  value: string | undefined,
+  field: string
+): Big => {
+  const parsed = toBigOrNull(value)
+  if (parsed !== null) {
+    return parsed
+  }
+  throw new PerpsError(
+    PerpsErrorCode.SDKError,
+    `Lighter field \`${field}\` is not a valid decimal.`
+  )
+}
+
+/** Parse a required venue decimal that must be greater than zero. */
+export const toPositiveRequiredBig = (
+  value: string | undefined,
+  field: string
+): Big => {
+  const parsed = toRequiredBig(value, field)
+  if (parsed.lte(0)) {
+    throw new PerpsError(
+      PerpsErrorCode.SDKError,
+      `Lighter field \`${field}\` must be greater than zero.`
+    )
+  }
+  return parsed
+}

package/src/utils/index.ts

@@ -9,6 +9,7 @@ export {
 } from './activityCursor.js'
 export { LighterApiClient } from './apiClient.js'
 export { assetMarginModeInt, isAssetMarginEnabled } from './assetCollateral.js'
+export { toBigOrNull, toRequiredBig } from './decimal.js'
 export { fetchDetailedAccount } from './fetchDetailedAccount.js'
 export { lighterAsset } from './lighterAsset.js'
 export { estimateLiquidationPrice } from './liquidation.js'
@@ -24,10 +25,11 @@ export {
   mapStatusReason,
   mapTriggerOrder,
 } from './mapOrder.js'
-export { mapPosition } from './mapPosition.js'
+export { leverageFromImf, mapPosition } from './mapPosition.js'
 export { mapInterval } from './ohlcvInterval.js'
 export { formatOrderPrice, formatOrderSize } from './orderFormatting.js'
 export { toIsoFromMs, toIsoFromSeconds } from './time.js'
+export { positionMarginConstraints } from './transferMargin.js'
 export {
   leverageToFraction,
   mapOrderTypeToInt,

package/src/utils/mapOpenPositions.ts

@@ -1,4 +1,4 @@
-import type { MarketDisplay, Position } from '@lifi/perps-types'
+import type { PerpsMarketDisplay, Position } from '@lifi/perps-types'
 import type { LtAccountPosition } from '../types/index.js'
 import { mapPosition } from './mapPosition.js'
 
@@ -11,7 +11,7 @@ import { mapPosition } from './mapPosition.js'
  */
 export const mapOpenPositions = (
   positions: LtAccountPosition[],
-  resolveMarket: (marketId: number) => MarketDisplay
+  resolveMarket: (marketId: number) => PerpsMarketDisplay
 ): Position[] =>
   positions
     .filter((p) => Number.parseFloat(p.position) !== 0)

package/src/utils/mapPosition.ts

@@ -1,7 +1,29 @@
-import type { MarketDisplay, Position } from '@lifi/perps-types'
+import type { PerpsMarketDisplay, Position } from '@lifi/perps-types'
 import { MarginMode, PositionSide } from '@lifi/perps-types'
+import Big from 'big.js'
 import type { LtAccountPosition } from '../types/index.js'
 import { LT_MARGIN_MODE_ISOLATED } from '../types/index.js'
+import { toPositiveRequiredBig, toRequiredBig } from './decimal.js'
+
+/**
+ * Display leverage from an IMF percent string: `100 / IMF` in exact decimal
+ * arithmetic before conversion to `number`. This value is for displaying the
+ * venue setting; provider risk calculations consume the original decimal IMF
+ * instead. `undefined` for a non-positive or unparsable IMF.
+ * @public
+ */
+export const leverageFromImf = (imf: string): number | undefined => {
+  let parsed: Big
+  try {
+    parsed = new Big(imf)
+  } catch {
+    return undefined
+  }
+  if (parsed.lte(0)) {
+    return undefined
+  }
+  return new Big(100).div(parsed).toNumber()
+}
 
 /**
  * Map a raw Lighter account position to the generic Position type.
@@ -10,33 +32,37 @@ import { LT_MARGIN_MODE_ISOLATED } from '../types/index.js'
  */
 export const mapPosition = (
   pos: LtAccountPosition,
-  market: MarketDisplay
+  market: PerpsMarketDisplay
 ): Position => {
-  const size = parseFloat(pos.position)
+  const size = toRequiredBig(pos.position, 'position')
   const isIsolated = pos.margin_mode === LT_MARGIN_MODE_ISOLATED
-
-  // `allocated_margin` is only populated for isolated positions (always "0"
-  // on cross accounts). For cross, derive margin as
-  // `position_value × initial_margin_fraction / 100` (IMF is in percent).
-  const positionValue = Math.abs(parseFloat(pos.position_value))
-  const imf = parseFloat(pos.initial_margin_fraction)
+  const positionValue = toRequiredBig(
+    pos.position_value,
+    'position_value'
+  ).abs()
+  const imf = toPositiveRequiredBig(
+    pos.initial_margin_fraction,
+    'initial_margin_fraction'
+  )
+  const initialMarginRequirement = positionValue.times(imf).div(100)
   const marginUsed = isIsolated
     ? pos.allocated_margin
-    : ((positionValue * imf) / 100).toString()
+    : initialMarginRequirement.toFixed()
 
   return {
     market,
     side: pos.sign >= 0 ? PositionSide.LONG : PositionSide.SHORT,
-    size: Math.abs(size).toString(),
+    size: size.abs().toFixed(),
     entryPrice: pos.avg_entry_price,
     markPrice:
-      pos.position_value === '0' || size === 0
+      positionValue.eq(0) || size.eq(0)
         ? '0'
-        : (parseFloat(pos.position_value) / Math.abs(size)).toString(),
+        : positionValue.div(size.abs()).toFixed(),
     liquidationPrice: pos.liquidation_price,
     unrealizedPnl: pos.unrealized_pnl,
-    leverage: imf > 0 ? Math.round(100 / imf) : 1,
+    leverage: leverageFromImf(pos.initial_margin_fraction) ?? 1,
     marginUsed,
+    initialMarginRequirement: initialMarginRequirement.toFixed(),
     marginMode: isIsolated ? MarginMode.ISOLATED : MarginMode.CROSS,
   }
 }

package/src/utils/transferMargin.ts

@@ -0,0 +1,35 @@
+import {
+  MarginMode,
+  type Position,
+  PositionMarginAdjustment,
+  type PositionMarginConstraints,
+} from '@lifi/perps-types'
+import { toPositiveRequiredBig } from './decimal.js'
+
+const AMOUNT_INCREMENT = '0.000001'
+
+/**
+ * Lighter's exact isolated-margin requirement. Lighter publishes no separate
+ * notional floor, so the provider-normalized initial-margin requirement is
+ * the retained amount.
+ *
+ * @see https://docs.lighter.xyz/trading/liquidations-and-llp-insurance-fund
+ * @public
+ */
+export function positionMarginConstraints(
+  position: Position
+): PositionMarginConstraints | undefined {
+  if (
+    position.marginMode !== MarginMode.ISOLATED ||
+    position.market.positionMarginAdjustment === PositionMarginAdjustment.NONE
+  ) {
+    return undefined
+  }
+  return {
+    minimumMarginRequirement: toPositiveRequiredBig(
+      position.initialMarginRequirement,
+      'initialMarginRequirement'
+    ).toFixed(),
+    amountIncrement: AMOUNT_INCREMENT,
+  }
+}

package/src/websocket/LighterWsProvider.ts

@@ -9,6 +9,7 @@ import {
   ReconnectingWebSocket,
   resolveRetryPolicy,
   resolveSubscribeQuote,
+  toPerpsMarketDisplay,
   WsProviderBase,
   type WsProviderFactory,
   wsLog,
@@ -51,6 +52,7 @@ import {
   mapFill,
   mapMarketContext,
   mapPosition,
+  toRequiredBig,
 } from '../utils/index.js'
 
 // Public channels: `marketsContext` (market_stats/all + spot_market_stats/all),
@@ -588,23 +590,51 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
       return
     }
     const stats = msg.stats
-    const portfolio = Number.parseFloat(stats?.portfolio_value ?? '')
-    const available = Number.parseFloat(stats?.available_balance ?? '')
-    if (!Number.isFinite(portfolio) || !Number.isFinite(available)) {
+    if (stats === undefined) {
       return
     }
-    // Identities of the REST 'net' semantics: `available_balance` nets locked
-    // margin out with PnL marked in, and `collateral` is gross, PnL-exclusive.
-    const collateral = Number.parseFloat(stats?.collateral ?? '')
+
+    const portfolio = toRequiredBig(
+      stats.portfolio_value,
+      'stats.portfolio_value'
+    )
+    const collateral = toRequiredBig(stats.collateral, 'stats.collateral')
+
+    let available: Big
+    let marginUsed: Big
+    if (stats.cross_stats === undefined) {
+      // Compatibility with legacy gateways that omitted the entire
+      // cross_stats object.
+      available = toRequiredBig(
+        stats.available_balance,
+        'stats.available_balance'
+      )
+      marginUsed = portfolio.minus(available)
+    } else {
+      const crossCollateral = toRequiredBig(
+        stats.cross_stats.collateral,
+        'stats.cross_stats.collateral'
+      )
+      const crossPortfolio = toRequiredBig(
+        stats.cross_stats.portfolio_value,
+        'stats.cross_stats.portfolio_value'
+      )
+      available = toRequiredBig(
+        stats.cross_stats.available_balance,
+        'stats.cross_stats.available_balance'
+      )
+      const isolatedMargin = collateral.minus(crossCollateral)
+      const crossMargin = crossPortfolio.minus(available)
+      marginUsed = isolatedMargin.plus(crossMargin)
+    }
+
     this.emit(`accountSummary:${address}`, {
       channel: 'accountSummary',
       data: {
         portfolioValue: portfolio.toString(),
         availableMargin: available.toString(),
-        marginUsed: Math.max(portfolio - available, 0).toString(),
-        unrealizedPnl: Number.isFinite(collateral)
-          ? (portfolio - collateral).toString()
-          : '0',
+        marginUsed: marginUsed.toString(),
+        unrealizedPnl: portfolio.minus(collateral).toString(),
       },
     })
   }
@@ -649,7 +679,7 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
       } else {
         const market = this.registry?.get(String(p.market_id))
         if (market) {
-          state.set(p.market_id, mapPosition(p, market))
+          state.set(p.market_id, mapPosition(p, toPerpsMarketDisplay(market)))
         }
       }
     }