@lifi/perps-sdk-provider-lighter 36.0.0 → 37.0.1

package/src/utils/mapOpenPositions.ts

@@ -1,10 +1,5 @@
-import { PerpsError, safeIsDecimalStringZero } from '@lifi/perps-sdk'
-import {
-  PerpsErrorCode,
-  type PerpsMarketDisplay,
-  type Position,
-} from '@lifi/perps-types'
-import { LIGHTER_PROVIDER_KEY } from '../constants.js'
+import { safeIsDecimalStringZero } from '@lifi/perps-sdk'
+import type { PerpsMarketDisplay, Position } from '@lifi/perps-types'
 import type { LtAccountPosition } from '../types/index.js'
 import { mapPosition } from './mapPosition.js'
 
@@ -32,26 +27,3 @@ export const mapOpenPositions = (
     const position = mapPosition(p, resolveMarket(p.market_id))
     return position === undefined ? [] : [position]
   })
-
-/**
- * Map every open Lighter position for account totals, which must not leave a
- * position out.
- *
- * @throws {PerpsError} `SDKError` when `mapPosition` skips an open row.
- */
-export const requireOpenPositions = (
-  positions: LtAccountPosition[],
-  resolveMarket: (marketId: number) => PerpsMarketDisplay
-): Position[] =>
-  positions.filter(isOpenPosition).map((p) => {
-    const position = mapPosition(p, resolveMarket(p.market_id))
-    if (position !== undefined) {
-      return position
-    }
-    const error = new PerpsError(
-      PerpsErrorCode.SDKError,
-      `${LIGHTER_PROVIDER_KEY} position for market ${p.market_id} is not valid, so the account totals are unknown.`
-    )
-    error.tool = LIGHTER_PROVIDER_KEY
-    throw error
-  })

package/src/utils/mapOrder.ts

@@ -1,12 +1,12 @@
 import {
   isActiveOrderStatus,
-  isDecimalStringGreaterThan,
   PerpsError,
   safeDivideDecimalString,
+  safeIsDecimalStringGreaterThan,
   safeTimestampToIsoString,
   triggerConditionFor,
-  unknownToDecimalString,
   warnSkippedVenueRow,
+  wsLog,
 } from '@lifi/perps-sdk'
 import type { MarketDisplay, Order, OrderBase } from '@lifi/perps-types'
 import {
@@ -20,6 +20,9 @@ import { LIGHTER_PROVIDER_KEY } from '../constants.js'
 import type { LtOrder } from '../types/index.js'
 import { rowTimestampToIsoStringOrUndefined } from './rowTimestamp.js'
 
+// Lighter sends client index 0 as the string "0" for an order placed without one.
+const NO_CLIENT_ORDER_ID = '0'
+
 const mapOrderType = (type: string): Order['type'] => {
   switch (type.replace(/-/g, '_')) {
     case 'market':
@@ -62,18 +65,8 @@ const mapTimeInForce = (tif: string): TimeInForce => {
   }
 }
 
-const venueDecimal = (value: unknown, field: string): string | undefined => {
-  try {
-    return unknownToDecimalString(value, field, LIGHTER_PROVIDER_KEY)
-  } catch {
-    return undefined
-  }
-}
-
-const hasFill = (order: LtOrder): boolean => {
-  const filled = venueDecimal(order.filled_base_amount, 'filled_base_amount')
-  return filled !== undefined && isDecimalStringGreaterThan(filled, '0')
-}
+const hasFill = (order: LtOrder): boolean =>
+  safeIsDecimalStringGreaterThan(order.filled_base_amount, '0') === true
 
 const mapOrderStatus = (order: LtOrder): OrderStatus => {
   switch (order.status) {
@@ -113,84 +106,56 @@ const mapOrderStatus = (order: LtOrder): OrderStatus => {
   }
 }
 
-const skipOrder = (field: string, value: unknown): undefined => {
-  warnSkippedVenueRow(LIGHTER_PROVIDER_KEY, 'order', field, value)
+const skipOrder = (
+  marketId: string,
+  field: string,
+  value: unknown
+): undefined => {
+  warnSkippedVenueRow(LIGHTER_PROVIDER_KEY, 'order', field, value, { marketId })
   return undefined
 }
 
-const orderSizeOrSkip = (
-  field: 'initial_base_amount' | 'remaining_base_amount' | 'filled_base_amount',
-  value: string
-): string | undefined =>
-  venueDecimal(value, field) === undefined ? skipOrder(field, value) : value
-
 /**
  * Map a Lighter order with its venue identity, lifecycle, and execution fields.
- * A row with an invalid size or time gives `undefined`. An invalid limit price or
- * filled quote amount omits that field.
+ * Venue sizes and prices pass verbatim. A row with an invalid time gives
+ * `undefined`. An average price that cannot be derived is omitted.
  */
 export const mapOrder = (
   order: LtOrder,
   market: MarketDisplay
 ): Order | undefined => {
   const type = mapOrderType(order.type)
-  const originalSize = orderSizeOrSkip(
-    'initial_base_amount',
-    order.initial_base_amount
-  )
-  if (originalSize === undefined) {
-    return undefined
-  }
-  const remainingSize = orderSizeOrSkip(
-    'remaining_base_amount',
-    order.remaining_base_amount
-  )
-  if (remainingSize === undefined) {
-    return undefined
-  }
-  const filledSize = orderSizeOrSkip(
-    'filled_base_amount',
-    order.filled_base_amount
-  )
-  if (filledSize === undefined) {
-    return undefined
-  }
   const createdAt = rowTimestampToIsoStringOrUndefined(order.created_at * 1000)
   if (createdAt === undefined) {
-    return skipOrder('created_at', order.created_at)
+    return skipOrder(market.id, 'created_at', order.created_at)
   }
   const updatedAt = rowTimestampToIsoStringOrUndefined(order.updated_at * 1000)
   if (updatedAt === undefined) {
-    return skipOrder('updated_at', order.updated_at)
+    return skipOrder(market.id, 'updated_at', order.updated_at)
   }
-  const filledQuote = venueDecimal(
-    order.filled_quote_amount,
-    'filled_quote_amount'
-  )
-  const filledAmount = venueDecimal(filledSize, 'filled_base_amount')
-  const averagePrice =
-    filledQuote !== undefined &&
-    filledAmount !== undefined &&
-    isDecimalStringGreaterThan(filledAmount, '0')
-      ? safeDivideDecimalString(filledQuote, filledAmount)
-      : undefined
+  const averagePrice = hasFill(order)
+    ? safeDivideDecimalString(
+        order.filled_quote_amount,
+        order.filled_base_amount
+      )
+    : undefined
   const expiresAt =
     order.order_expiry > 0
       ? safeTimestampToIsoString(order.order_expiry)
       : undefined
   const status = mapOrderStatus(order)
   const base: OrderBase = {
-    orderId: String(order.order_index),
-    ...(order.client_order_index === 0
+    orderId: order.order_id,
+    ...(order.client_order_id === NO_CLIENT_ORDER_ID
       ? {}
-      : { clientOrderId: String(order.client_order_index) }),
+      : { clientOrderId: order.client_order_id }),
     market,
     side: order.is_ask ? OrderSide.SELL : OrderSide.BUY,
     status,
     ...(status === OrderStatus.CANCELLED ? { statusReason: order.status } : {}),
-    originalSize,
-    remainingSize,
-    filledSize,
+    originalSize: order.initial_base_amount,
+    remainingSize: order.remaining_base_amount,
+    filledSize: order.filled_base_amount,
     ...(averagePrice === undefined ? {} : { averagePrice }),
     reduceOnly: order.reduce_only,
     ...(order.parent_order_id ? { parentOrderId: order.parent_order_id } : {}),
@@ -214,9 +179,8 @@ export const mapOrder = (
         type,
         triggerPrice: order.trigger_price,
         triggerCondition: triggerConditionFor(type, base.side),
-        ...((type === OrderType.STOP_LIMIT ||
-          type === OrderType.TAKE_PROFIT_LIMIT) &&
-        venueDecimal(order.price, 'price') !== undefined
+        ...(type === OrderType.STOP_LIMIT ||
+        type === OrderType.TAKE_PROFIT_LIMIT
           ? { limitPrice: order.price }
           : {}),
       }
@@ -233,7 +197,10 @@ export const mapOrder = (
   }
 }
 
-/** Include terminal rows and their ids so consumers can update history and active caches. */
+/**
+ * Include terminal rows and their ids so consumers can update history and
+ * active caches. A row the mapper rejects is dropped and warns once.
+ */
 export const mapOrderUpdates = (
   rawOrders: LtOrder[],
   resolveMarket: (marketIndex: number) => MarketDisplay | undefined
@@ -242,9 +209,24 @@ export const mapOrderUpdates = (
   const terminated: string[] = []
   for (const raw of rawOrders) {
     const market = resolveMarket(raw.market_index)
-    const order = market === undefined ? undefined : mapOrder(raw, market)
-    if (!isActiveOrderStatus(order?.status ?? mapOrderStatus(raw))) {
-      terminated.push(String(raw.order_index))
+    let order: Order | undefined
+    let status: OrderStatus
+    try {
+      order = market === undefined ? undefined : mapOrder(raw, market)
+      status = order?.status ?? mapOrderStatus(raw)
+    } catch (error) {
+      if (!(error instanceof PerpsError)) {
+        throw error
+      }
+      wsLog.droppedRow(
+        LIGHTER_PROVIDER_KEY,
+        'order',
+        `${raw.order_id}: ${error.message}`
+      )
+      continue
+    }
+    if (!isActiveOrderStatus(status)) {
+      terminated.push(raw.order_id)
     }
     if (order !== undefined) {
       orders.push(order)

package/src/utils/mapPortfolioHistory.ts

@@ -69,8 +69,8 @@ function getCumulativeNetFlow(snapshot: LtPnLEntry): string {
  * Historical account values are anchored to the current account value. A
  * snapshot with a non-finite value is skipped.
  *
- * @throws {PerpsError} `ValidationError` when `currentValue` is not a decimal
- *   string.
+ * @throws {PerpsError} `ValidationError` when `currentValue` does not match the
+ *   decimal pattern.
  */
 export const mapPortfolioHistory = (
   range: PortfolioHistoryRange,

package/src/utils/mapPosition.ts

@@ -1,5 +1,6 @@
 import {
   absDecimalString,
+  createWarnOnce,
   divideDecimalString,
   isDecimalString,
   isDecimalStringZero,
@@ -53,16 +54,32 @@ export const leverageFromScaledImf = (imf: number): string | undefined => {
   return percent === undefined ? undefined : leverageFromImf(percent)
 }
 
-const skipPosition = (field: string, value: unknown): undefined => {
-  warnSkippedVenueRow(LIGHTER_PROVIDER_KEY, 'position', field, value)
+const skipPosition = (
+  marketId: string,
+  field: string,
+  value: unknown
+): undefined => {
+  warnSkippedVenueRow(LIGHTER_PROVIDER_KEY, 'position', field, value, {
+    marketId,
+  })
   return undefined
 }
 
+const warnUnreadableFieldOnce = createWarnOnce()
+
+const warnUnreadableField = (field: string, value: unknown): void => {
+  warnUnreadableFieldOnce(
+    `${LIGHTER_PROVIDER_KEY}|position.${field}`,
+    `[${LIGHTER_PROVIDER_KEY}] position \`${field}\` is not readable, so the derived fields are absent: '${String(value).slice(0, 64)}'`
+  )
+}
+
 /**
  * Map a raw Lighter account position to the generic Position type. A row with
- * an invalid size or value, or a non-positive initial margin fraction, gives
- * `undefined`: the mapper derives the size, mark price, margin and leverage
- * from them. Prices, PnL, funding and isolated margin pass through raw.
+ * an invalid size gives `undefined`. An invalid position value or a
+ * non-positive initial margin fraction keeps the row, leaves `leverage` and
+ * `initialMarginRequirement` absent, sets a cross `marginUsed` to `'0'` and
+ * warns once. Prices, PnL, funding and isolated margin pass through raw.
  * @param market - Backend-resolved market identity for `pos.market_id`.
  * @public
  */
@@ -71,39 +88,49 @@ export const mapPosition = (
   market: PerpsMarketDisplay
 ): Position | undefined => {
   if (!isDecimalString(pos.position)) {
-    return skipPosition('position', pos.position)
+    return skipPosition(market.id, 'position', pos.position)
   }
-  if (!isDecimalString(pos.position_value)) {
-    return skipPosition('position_value', pos.position_value)
+  const isIsolated = pos.margin_mode === LT_MARGIN_MODE_ISOLATED
+  const size = absDecimalString(pos.position)
+  const positionValue = isDecimalString(pos.position_value)
+    ? absDecimalString(pos.position_value)
+    : undefined
+  if (positionValue === undefined) {
+    warnUnreadableField('position_value', pos.position_value)
   }
   const imf = pos.initial_margin_fraction
   const leverage = isDecimalString(imf) ? leverageFromImf(imf) : undefined
   if (leverage === undefined) {
-    return skipPosition('initial_margin_fraction', imf)
+    warnUnreadableField('initial_margin_fraction', imf)
   }
-  const isIsolated = pos.margin_mode === LT_MARGIN_MODE_ISOLATED
-  const size = absDecimalString(pos.position)
-  const positionValue = absDecimalString(pos.position_value)
-  const initialMarginRequirement = divideDecimalString(
-    multiplyDecimalString(positionValue, imf),
-    '100'
-  )
+  const initialMarginRequirement =
+    positionValue === undefined || leverage === undefined
+      ? undefined
+      : divideDecimalString(multiplyDecimalString(positionValue, imf), '100')
 
   return {
     market,
     side: pos.sign >= 0 ? PositionSide.LONG : PositionSide.SHORT,
     size,
     entryPrice: pos.avg_entry_price,
-    markPrice:
-      isDecimalStringZero(positionValue) || isDecimalStringZero(size)
-        ? '0'
-        : divideDecimalString(positionValue, size),
+    ...(positionValue === undefined
+      ? {}
+      : {
+          markPrice:
+            isDecimalStringZero(positionValue) || isDecimalStringZero(size)
+              ? '0'
+              : divideDecimalString(positionValue, size),
+        }),
     liquidationPrice: pos.liquidation_price,
     unrealizedPnl: pos.unrealized_pnl,
     accruedFunding: pos.total_funding_paid_out ?? '0',
-    leverage,
-    marginUsed: isIsolated ? pos.allocated_margin : initialMarginRequirement,
-    initialMarginRequirement,
+    ...(leverage === undefined ? {} : { leverage }),
+    marginUsed: isIsolated
+      ? pos.allocated_margin
+      : (initialMarginRequirement ?? '0'),
+    ...(initialMarginRequirement === undefined
+      ? {}
+      : { initialMarginRequirement }),
     marginMode: isIsolated ? MarginMode.ISOLATED : MarginMode.CROSS,
   }
 }

package/src/utils/transferMargin.ts

@@ -23,7 +23,7 @@ function positionAmount(
   if (!isDecimalString(value)) {
     throw new PerpsError(
       PerpsErrorCode.ValidationError,
-      `Invalid \`Position.${field}\`: '${value}' is not a decimal string.`
+      `Invalid \`Position.${field}\`: '${value}' does not match the decimal pattern.`
     )
   }
   return value

package/src/utils/wireEncoding.ts

@@ -1,6 +1,6 @@
 /**
- * Lighter wire encoding for the WASM signer: basis-point margin fractions and
- * order-type/time-in-force/expiry resolution mirroring lighter-go's rules.
+ * Lighter wire encoding for the WASM signer: order-type/time-in-force/expiry
+ * resolution mirroring lighter-go's rules.
  */
 
 import { PerpsError } from '@lifi/perps-sdk'
@@ -19,47 +19,6 @@ import {
   LT_TIME_IN_FORCE_POST_ONLY,
 } from '../types/action.js'
 
-/**
- * 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 => {
-  if (!Number.isFinite(fraction) || fraction <= 0) {
-    return 1
-  }
-  return Math.floor(10_000 / fraction)
-}
-
-/**
- * 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 => {
-  if (leverage <= 0) {
-    throw new PerpsError(
-      PerpsErrorCode.ValidationError,
-      `Invalid leverage: ${leverage}`
-    )
-  }
-  return Math.round(10_000 / leverage)
-}
-
 /**
  * Map a LI.FI `OrderType` value to Lighter's integer wire type.
  * Supported mappings are LIMIT → 0, MARKET → 1, STOP_MARKET → 2,

package/src/websocket/LighterWsProvider.ts

@@ -1,6 +1,7 @@
 import {
   addDecimalString,
   cachePromise,
+  createSafeFunction,
   getMarketRegistry,
   isDecimalStringGreaterThan,
   type MarketRegistry,
@@ -12,6 +13,7 @@ import {
   ReconnectingWebSocket,
   resolveRetryPolicy,
   resolveSubscribeQuote,
+  safeUnknownToDecimalString,
   subtractDecimalString,
   toPerpsMarketDisplay,
   unknownToDecimalString,
@@ -23,6 +25,7 @@ import {
 import {
   type AccountSummary,
   type Fill,
+  type Market,
   type MarketContext,
   PerpsErrorCode,
   type Position,
@@ -172,6 +175,57 @@ export interface LighterWsProviderOptions {
   resolveAuthToken?: LighterAuthTokenResolver
 }
 
+/**
+ * Perps equity plus the USD value of every positive held balance. A non-
+ * settlement asset counts its spot and margin routes; the settlement asset
+ * counts its spot route only, because the equity already holds its margin.
+ *
+ * @throws {PerpsError} `SDKError` when a held asset's spot mark does not
+ *   match the decimal pattern.
+ */
+const heldPortfolioValue = (
+  perpsEquity: string,
+  balances: ReadonlyMap<number, { spot: string; margin: string }>,
+  settlementAssetIndex: number,
+  markets: readonly Market[],
+  contexts: readonly MarketContext[]
+): string => {
+  const held = [...balances]
+    .map(
+      ([assetId, { spot, margin }]) =>
+        [
+          assetId,
+          assetId === settlementAssetIndex
+            ? spot
+            : addDecimalString(spot, margin),
+        ] as const
+    )
+    .filter(([, balance]) => isDecimalStringGreaterThan(balance, '0'))
+  const spotPrices = spotPriceByAssetId(
+    markets,
+    LIGHTER_SPOT_CATEGORY_ID,
+    contexts,
+    new Set(
+      held
+        .filter(([assetId]) => assetId !== settlementAssetIndex)
+        .map(([assetId]) => String(assetId))
+    )
+  )
+  return lighterPortfolioValue(
+    perpsEquity,
+    held.map(
+      ([assetId, balance]) =>
+        spotValuation(assetId, balance, settlementAssetIndex, spotPrices)
+          .valueUsd
+    )
+  )
+}
+
+const safeHeldPortfolioValue = createSafeFunction(
+  'heldPortfolioValue',
+  heldPortfolioValue
+)
+
 /**
  * Lighter WebSocket provider (extends {@link WsProviderBase}): subscribes to
  * Lighter's WS channels (orderbook, marketsContext, orders, positions), attaching auth
@@ -723,47 +777,53 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
       return
     }
 
-    const portfolio = unknownToDecimalString(
-      stats.portfolio_value,
-      'stats.portfolio_value',
-      this.providerKey
-    )
-    const collateral = unknownToDecimalString(
-      stats.collateral,
-      'stats.collateral',
-      this.providerKey
-    )
+    const read = (value: unknown, field: string): string | undefined =>
+      safeUnknownToDecimalString(value, field, this.providerKey)
+    const portfolio = read(stats.portfolio_value, 'stats.portfolio_value')
+    const collateral = read(stats.collateral, 'stats.collateral')
 
-    let available: string
-    let marginUsed: string
+    let available: string | undefined
+    let marginUsed: string | undefined
     if (stats.cross_stats === undefined) {
       // Compatibility with legacy gateways that omitted the entire
       // cross_stats object.
-      available = unknownToDecimalString(
-        stats.available_balance,
-        'stats.available_balance',
-        this.providerKey
-      )
-      marginUsed = subtractDecimalString(portfolio, available)
+      available = read(stats.available_balance, 'stats.available_balance')
+      marginUsed =
+        portfolio === undefined || available === undefined
+          ? undefined
+          : subtractDecimalString(portfolio, available)
     } else {
-      const crossCollateral = unknownToDecimalString(
+      const crossCollateral = read(
         stats.cross_stats.collateral,
-        'stats.cross_stats.collateral',
-        this.providerKey
+        'stats.cross_stats.collateral'
       )
-      const crossPortfolio = unknownToDecimalString(
+      const crossPortfolio = read(
         stats.cross_stats.portfolio_value,
-        'stats.cross_stats.portfolio_value',
-        this.providerKey
+        'stats.cross_stats.portfolio_value'
       )
-      available = unknownToDecimalString(
+      available = read(
         stats.cross_stats.available_balance,
-        'stats.cross_stats.available_balance',
-        this.providerKey
+        'stats.cross_stats.available_balance'
       )
-      const isolatedMargin = subtractDecimalString(collateral, crossCollateral)
-      const crossMargin = subtractDecimalString(crossPortfolio, available)
-      marginUsed = addDecimalString(isolatedMargin, crossMargin)
+      marginUsed =
+        collateral === undefined ||
+        crossCollateral === undefined ||
+        crossPortfolio === undefined ||
+        available === undefined
+          ? undefined
+          : addDecimalString(
+              subtractDecimalString(collateral, crossCollateral),
+              subtractDecimalString(crossPortfolio, available)
+            )
+    }
+    // Every AccountSummary field is required, so the last summary stays.
+    if (
+      portfolio === undefined ||
+      collateral === undefined ||
+      available === undefined ||
+      marginUsed === undefined
+    ) {
+      return
     }
 
     const inputs = this.accountSummaryInputs.get(address)
@@ -827,36 +887,16 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
     if (inputs?.perps === undefined || inputs.balances === undefined) {
       return
     }
-    const settlementAssetIndex = this.settlementAssetIndex()
-    const held = [...inputs.balances]
-      .map(
-        ([assetId, { spot, margin }]) =>
-          [
-            assetId,
-            assetId === settlementAssetIndex
-              ? spot
-              : addDecimalString(spot, margin),
-          ] as const
-      )
-      .filter(([, balance]) => isDecimalStringGreaterThan(balance, '0'))
-    const spotPrices = spotPriceByAssetId(
-      this.registry?.markets ?? [],
-      LIGHTER_SPOT_CATEGORY_ID,
-      Object.values(this.marketsContext),
-      new Set(
-        held
-          .filter(([assetId]) => assetId !== settlementAssetIndex)
-          .map(([assetId]) => String(assetId))
-      )
-    )
-    const portfolioValue = lighterPortfolioValue(
+    const portfolioValue = safeHeldPortfolioValue(
       inputs.perps.equity,
-      held.map(
-        ([assetId, balance]) =>
-          spotValuation(assetId, balance, settlementAssetIndex, spotPrices)
-            .valueUsd
-      )
+      inputs.balances,
+      this.settlementAssetIndex(),
+      this.registry?.markets ?? [],
+      Object.values(this.marketsContext)
     )
+    if (portfolioValue === undefined) {
+      return
+    }
     if (onlyOnChange && portfolioValue === inputs.lastPortfolioValue) {
       return
     }
@@ -1017,8 +1057,8 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
     let state = this.orderbooks.get(marketId)
     if (!state || isSnapshot) {
       state = {
-        bids: new OrderBookSide(bidOrder, this.providerKey),
-        asks: new OrderBookSide(askOrder, this.providerKey),
+        bids: new OrderBookSide(bidOrder, this.providerKey, assetId),
+        asks: new OrderBookSide(askOrder, this.providerKey, assetId),
         assetId,
       }
       this.orderbooks.set(marketId, state)