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

package/src/types/submit.ts

@@ -1,13 +1,24 @@
 // Lighter submit/execute-path wire shapes (sendTx, fastwithdraw, changeAccountTier).
 
-/** @public */
+/**
+ * Request body for Lighter's `/api/v1/sendTx` endpoint. `tx_type` and
+ * `tx_info` are the signed WASM transaction envelope; `price_protection` is an
+ * optional venue-side execution guard.
+ *
+ * @public
+ */
 export interface LtSendTxRequest {
   tx_type: number
   tx_info: string
   price_protection?: boolean
 }
 
-/** @public */
+/**
+ * Response from Lighter's `/api/v1/sendTx` endpoint. `tx_hash` identifies the
+ * submitted transaction; timing and quota fields are optional venue estimates.
+ *
+ * @public
+ */
 export interface LtSendTxResponse {
   code: number
   message: string
@@ -16,13 +27,24 @@ export interface LtSendTxResponse {
   volume_quota_remaining?: number
 }
 
-/** @public */
+/**
+ * Batch request body for Lighter's transaction submission endpoint.
+ * `tx_types` is a JSON-encoded number array and `tx_infos` a JSON-encoded
+ * string array; corresponding entries are submitted in array order.
+ *
+ * @public
+ */
 export interface LtSendTxBatchRequest {
   tx_types: string // JSON-encoded number[]
   tx_infos: string // JSON-encoded string[]
 }
 
-/** @public */
+/**
+ * Batch submission response from Lighter. Each `tx_hash` corresponds to the
+ * transaction at the same index in the submitted batch.
+ *
+ * @public
+ */
 export interface LtSendTxBatchResponse {
   code: number
   message: string

package/src/types/ws.ts

@@ -10,16 +10,33 @@
 //   - spot_market_stats/{id}  → context for one spot market
 //   - order_book/{market_id}  → bids/asks per market (stateful with deltas)
 
-/** @public */
+/**
+ * Common envelope fields on every Lighter WebSocket frame.
+ *
+ * `channel` identifies the subscribed stream when present; `type` is the
+ * subscription, update, or control-frame discriminator.
+ *
+ * @public
+ */
 export type LtWsMessage = {
   channel?: string
   type: string
 }
 
-/** @public */
+/**
+ * Lighter WebSocket keepalive frame.
+ *
+ * @public
+ */
 export type LtWsPingMessage = LtWsMessage & { type: 'ping' }
 
-/** @public */
+/**
+ * Perpetual-market statistics pushed by Lighter's `market_stats` channels.
+ * Price, interest, volume, and funding values are decimal strings; the funding
+ * timestamp is a Unix timestamp in milliseconds.
+ *
+ * @public
+ */
 export type LtWsMarketStats = {
   market_id: number
   index_price: string
@@ -75,20 +92,34 @@ export type LtWsSpotMarketStatsAllMessage = LtWsMessage & {
   spot_market_stats?: LtWsSpotMarketStats | Record<string, LtWsSpotMarketStats>
 }
 
-/** @public */
+/**
+ * One bid or ask level in a Lighter order-book snapshot or delta. Price and
+ * size are decimal strings in the market's native precision.
+ *
+ * @public
+ */
 export type LtWsOrderBookLevel = {
   price: string
   size: string
 }
 
-/** @public */
+/**
+ * Lighter order-book state containing ask and bid levels. `offset`, when
+ * present, identifies the sequence offset used for stateful delta updates.
+ *
+ * @public
+ */
 export type LtWsOrderBook = {
   asks: LtWsOrderBookLevel[]
   bids: LtWsOrderBookLevel[]
   offset?: number
 }
 
-/** @public */
+/**
+ * Subscription or update frame carrying a Lighter order-book snapshot/delta.
+ *
+ * @public
+ */
 export type LtWsOrderBookMessage = LtWsMessage & {
   type: 'subscribed/order_book' | 'update/order_book'
   order_book: LtWsOrderBook
@@ -109,7 +140,11 @@ export type LtWsTrade = {
   timestamp: number
 }
 
-/** @public */
+/**
+ * Subscription or update frame carrying public trades from a Lighter market.
+ *
+ * @public
+ */
 export type LtWsTradeMessage = LtWsMessage & {
   type: 'subscribed/trade' | 'update/trade'
   trades?: LtWsTrade[]
@@ -138,7 +173,13 @@ export type LtWsAccountAllOrdersMessage = LtWsMessage & {
   data?: { orders?: Record<string, unknown[]> | unknown[] }
 }
 
-/** @public */
+/**
+ * Authenticated account trade-history frame. Trade arrays may be flat or
+ * market-indexed depending on whether the frame is an initial snapshot or
+ * update.
+ *
+ * @public
+ */
 export type LtWsAccountAllTradesMessage = LtWsMessage & {
   type: 'subscribed/account_all_trades' | 'update/account_all_trades'
   trades?: Record<string, unknown[]> | unknown[]
@@ -150,7 +191,10 @@ export type LtWsAccountAllTradesMessage = LtWsMessage & {
 }
 
 /**
- * `user_stats/{account_index}` frame; decimal strings in USD.
+ * `user_stats/{account_index}` frame; decimal strings in USD. The top-level
+ * figures span the whole account (`available_balance` = total withdrawable,
+ * including isolated positions' excess margin); `cross_stats` scopes them to
+ * the cross pool, whose `available_balance` is the free tradable collateral.
  * @public
  */
 export type LtWsUserStatsMessage = LtWsMessage & {
@@ -158,9 +202,21 @@ export type LtWsUserStatsMessage = LtWsMessage & {
     collateral?: string
     portfolio_value?: string
     available_balance?: string
+    cross_stats?: {
+      collateral: string
+      portfolio_value: string
+      available_balance: string
+    }
   }
 }
 
+/**
+ * Authenticated account-position frame. Position and funding maps are keyed
+ * by Lighter market index; the provider normalizes the payload before emitting
+ * account updates.
+ *
+ * @public
+ */
 export type LtWsAccountAllPositionsMessage = LtWsMessage & {
   type: 'subscribed/account_all_positions' | 'update/account_all_positions'
   positions?: Record<string, unknown>

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/lighterAsset.ts

@@ -1,7 +1,13 @@
 import type { Asset } from '@lifi/perps-types'
 import { LIGHTER_PROVIDER_KEY } from '../constants.js'
 
-/** @public */
+/**
+ * Create the SDK asset descriptor for a Lighter asset identifier and display
+ * symbol. Lighter assets do not provide a package-level logo URI, so this
+ * helper leaves that field empty.
+ *
+ * @public
+ */
 export const lighterAsset = (id: string, displaySymbol: string): Asset => ({
   providerId: LIGHTER_PROVIDER_KEY,
   id,

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/ohlcvInterval.ts

@@ -20,7 +20,12 @@ const LIGHTER_SUPPORTED_INTERVALS: Record<string, string> = {
   '1w': '1w',
 }
 
-/** @public */
+/**
+ * Validate and map an SDK OHLCV interval to Lighter's resolution string.
+ * Unsupported intervals raise a validation error instead of being rounded.
+ *
+ * @public
+ */
 export const mapInterval = (interval: string): string => {
   const resolution = LIGHTER_SUPPORTED_INTERVALS[interval]
   if (!resolution) {

package/src/utils/transferMargin.ts

@@ -0,0 +1,31 @@
+import {
+  type Position,
+  type PositionMarginConstraints,
+  positionSupportsMarginAdjustment,
+} 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 (!positionSupportsMarginAdjustment(position)) {
+    return undefined
+  }
+  return {
+    minimumMarginRequirement: toPositiveRequiredBig(
+      position.initialMarginRequirement,
+      'initialMarginRequirement'
+    ).toFixed(),
+    amountIncrement: AMOUNT_INCREMENT,
+  }
+}

package/src/utils/wireEncoding.ts

@@ -1,7 +1,6 @@
 /**
- * Lighter wire encoding for the WASM signer: scaled-integer decimal values,
- * basis-point margin fractions, and order-type/TIF/expiry resolution
- * mirroring the lighter-go signer's rules.
+ * Lighter wire encoding for the WASM signer: basis-point margin fractions and
+ * order-type/time-in-force/expiry resolution mirroring lighter-go's rules.
  */
 
 import { PerpsError } from '@lifi/perps-sdk'
@@ -20,8 +19,15 @@ import {
 } from '../types/action.js'
 
 /**
- * Lighter uses basis-points (1/10000) for margin fractions.
- * Convert to a decimal multiplier: 1000 → 0.1 (10x leverage).
+ * Convert Lighter's initial-margin fraction to the largest whole-number
+ * leverage exposed by the provider.
+ *
+ * Lighter expresses margin fractions in basis points (`10_000` = 100%), so
+ * the conversion is `floor(10_000 / fraction)`. Non-finite or non-positive
+ * input uses the safe `1x` fallback.
+ *
+ * @param fraction - Lighter's basis-point initial-margin fraction.
+ * @returns The floored maximum leverage, or `1` for invalid input.
  * @public
  */
 export const marginFractionToMaxLeverage = (fraction: number): number => {
@@ -32,7 +38,15 @@ export const marginFractionToMaxLeverage = (fraction: number): number => {
 }
 
 /**
- * Convert leverage to margin fraction in basis points for WASM signer.
+ * Convert requested leverage to Lighter's basis-point margin fraction.
+ *
+ * The signer expects `round(10_000 / leverage)`, where the result is the
+ * margin requirement in basis points.
+ *
+ * @param leverage - Requested leverage multiplier.
+ * @returns The rounded basis-point margin fraction.
+ * @throws {PerpsError} With `ValidationError` when leverage is less than
+ * or equal to zero.
  * @public
  */
 export const leverageToFraction = (leverage: number): number => {
@@ -46,7 +60,14 @@ export const leverageToFraction = (leverage: number): number => {
 }
 
 /**
- * Map our OrderType enum to Lighter's integer order type.
+ * Map a LI.FI `OrderType` value to Lighter's integer wire type.
+ *
+ * Supported mappings are LIMIT → 0, MARKET → 1, STOP_MARKET → 2,
+ * STOP_LIMIT → 3, TAKE_PROFIT_MARKET → 4, and TAKE_PROFIT_LIMIT → 5.
+ * Omitted or unknown values fall back to LIMIT.
+ *
+ * @param type - LI.FI order type value.
+ * @returns The corresponding Lighter order-type integer.
  * @public
  */
 export const mapOrderTypeToInt = (type?: string): number => {
@@ -62,13 +83,18 @@ export const mapOrderTypeToInt = (type?: string): number => {
 }
 
 /**
- * Lighter pairs each `order_type` with a permitted set of `time_in_force`
- * values: market-style orders (MARKET, STOP_MARKET, TAKE_PROFIT_MARKET) are
- * IOC by definition; limit-style orders may carry any TIF. The Go WASM
- * signer rejects mismatches with `OrderTimeInForce is not valid`. Resolve
- * the caller's optional `timeInForce` against the order type so unspecified
- * values land on the correct default and explicit values are validated up
- * front.
+ * Resolve a Lighter `time_in_force` value that is valid for an order type.
+ *
+ * Market-style orders (MARKET, STOP_MARKET, TAKE_PROFIT_MARKET) are IOC-only.
+ * Limit-style orders default to GTC when no TIF is supplied. An explicit
+ * non-IOC TIF on a market-style order raises a validation error. For
+ * limit-style orders, unknown TIF strings use the GTC fallback from
+ * {@link mapTimeInForceToInt}.
+ *
+ * @param orderTypeInt - Lighter order-type integer.
+ * @param tif - Optional LI.FI time-in-force value.
+ * @returns The validated Lighter time-in-force integer.
+ * @throws {PerpsError} With `ValidationError` for a market-style/TIF mismatch.
  * @public
  */
 export const resolveTimeInForce = (
@@ -93,7 +119,13 @@ export const resolveTimeInForce = (
 }
 
 /**
- * Map our TimeInForce enum to Lighter's integer time-in-force.
+ * Map a LI.FI time-in-force value to Lighter's integer wire value.
+ *
+ * IOC maps to 0, GTC maps to 1, and POST_ONLY maps to 2. Omitted or unknown
+ * values fall back to GTC.
+ *
+ * @param tif - LI.FI time-in-force value.
+ * @returns The corresponding Lighter time-in-force integer.
  * @public
  */
 export const mapTimeInForceToInt = (tif?: string): number => {
@@ -106,14 +138,17 @@ export const mapTimeInForceToInt = (tif?: string): number => {
 }
 
 /**
- * Pick the `order_expiry` value Lighter expects for a given TIF on a
- * regular limit order. `lighter-go/types/txtypes/create_order.go:121-128`
- * enforces:
- *   - IOC limit orders → `OrderExpiry == NilOrderExpiry (0)`
- *   - non-IOC limit orders → `OrderExpiry != NilOrderExpiry`
- * For non-IOC we pass the `-1` sentinel, which the WASM signer rewrites
- * to `now + 28d` (absolute ms). Trigger orders take a different rule —
- * see {@link LT_DEFAULT_ORDER_EXPIRY} call sites.
+ * Select the `order_expiry` sentinel required for a regular Lighter limit
+ * order from its resolved time-in-force.
+ *
+ * IOC uses Lighter's nil expiry (`0`). Every other TIF uses
+ * `LT_DEFAULT_ORDER_EXPIRY` (`-1`), which the WASM signer expands to its
+ * canonical future expiry (`now + 28d`) as an absolute Unix-millisecond
+ * timestamp. Trigger-order expiry handling is provider-specific; see
+ * {@link LT_DEFAULT_ORDER_EXPIRY} and its call sites.
+ *
+ * @param tifInt - Lighter time-in-force integer.
+ * @returns `0` for IOC, otherwise the default-expiry sentinel.
  * @public
  */
 export const orderExpiryForTif = (tifInt: number): number => {

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),
@@ -225,6 +227,12 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
     return undefined
   }
 
+  /**
+   * Subscribe to a live quote stream resolved through the registered Lighter
+   * market registry. Returns an unsubscribe function; quote subscription
+   * requires the provider to be constructed through `lighterWsProvider` with a
+   * bound {@link PerpsSDKClient}.
+   */
   async subscribeQuote(
     params: ProviderGetQuoteParams,
     onQuote: QuoteListener
@@ -588,23 +596,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 +685,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)))
         }
       }
     }