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

package/src/types/fill.ts

@@ -1,6 +1,13 @@
 // Trade (fill) shapes returned by Lighter's `/api/v1/trades` endpoint.
 
-/** @public */
+/**
+ * Public trade/fill row returned by Lighter's `/api/v1/trades` endpoint.
+ * Size, price, and notional fields are decimal strings in market precision;
+ * `timestamp` and `transaction_time` are Unix millisecond timestamps. The
+ * optional fee fields are integer fee ticks and may be absent on older rows.
+ *
+ * @public
+ */
 export type LtTrade = {
   trade_id: number
   tx_hash: string
@@ -34,7 +41,12 @@ export type LtTrade = {
   maker_entry_quote_before?: string
 }
 
-/** @public */
+/**
+ * Paginated trade-history response from Lighter. `next_cursor` is an opaque
+ * continuation value for the next page.
+ *
+ * @public
+ */
 export interface LtTradesResponse {
   code: number
   next_cursor: string

package/src/types/order.ts

@@ -1,6 +1,14 @@
 // Order shapes returned by Lighter's REST API.
 
-/** @public */
+/**
+ * Order payload returned by Lighter's REST API. Amounts and prices are decimal
+ * strings in market precision. `order_expiry` is an absolute Unix-millisecond
+ * expiry; `created_at`, `updated_at`, and `transaction_time` are Unix seconds.
+ * Enum-like side, type, time-in-force, status, and trigger fields retain
+ * Lighter's wire strings.
+ *
+ * @public
+ */
 export type LtOrder = {
   order_index: number
   client_order_index: number
@@ -36,14 +44,25 @@ export type LtOrder = {
   transaction_time: number
 }
 
-/** @public */
+/**
+ * Paginated order-history response from Lighter. `next_cursor` is an opaque
+ * continuation value for the next page.
+ *
+ * @public
+ */
 export interface LtOrdersResponse {
   code: number
   next_cursor: string
   orders: LtOrder[]
 }
 
-/** @public */
+/**
+ * Single order-book level returned by Lighter. Amounts and prices are decimal
+ * strings in the market's native precision; expiry and transaction time are
+ * Unix milliseconds.
+ *
+ * @public
+ */
 export interface LtOrderBookOrder {
   order_index: number
   order_id: string
@@ -55,7 +74,11 @@ export interface LtOrderBookOrder {
   transaction_time: number
 }
 
-/** @public */
+/**
+ * Order-book response containing separate ask and bid levels plus their counts.
+ *
+ * @public
+ */
 export interface LtOrderBookOrdersResponse {
   code: number
   total_asks: number

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[]
@@ -169,6 +210,13 @@ export type LtWsUserStatsMessage = LtWsMessage & {
   }
 }
 
+/**
+ * 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/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/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

@@ -1,8 +1,7 @@
 import {
-  MarginMode,
   type Position,
-  PositionMarginAdjustment,
   type PositionMarginConstraints,
+  positionSupportsMarginAdjustment,
 } from '@lifi/perps-types'
 import { toPositiveRequiredBig } from './decimal.js'
 
@@ -19,10 +18,7 @@ const AMOUNT_INCREMENT = '0.000001'
 export function positionMarginConstraints(
   position: Position
 ): PositionMarginConstraints | undefined {
-  if (
-    position.marginMode !== MarginMode.ISOLATED ||
-    position.market.positionMarginAdjustment === PositionMarginAdjustment.NONE
-  ) {
+  if (!positionSupportsMarginAdjustment(position)) {
     return undefined
   }
   return {

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

@@ -227,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