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

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)

package/src/websocket/orderBookSide.ts

@@ -9,7 +9,7 @@ import type { LtWsOrderBook } from '../types/index.js'
 /**
  * Orders two decimal-string prices: a negative result puts `a` before `b`.
  *
- * @throws {PerpsError} `ValidationError` when a price is not a decimal string.
+ * @throws {PerpsError} `ValidationError` when a price does not match the decimal pattern.
  */
 export type PriceOrder = (a: string, b: string) => number
 
@@ -31,7 +31,8 @@ export class OrderBookSide {
 
   constructor(
     private readonly order: PriceOrder,
-    private readonly providerKey: string
+    private readonly providerKey: string,
+    private readonly marketId: string
   ) {}
 
   /**
@@ -42,11 +43,23 @@ export class OrderBookSide {
   apply(updates: LtWsOrderBook['bids']): void {
     for (const { price, size } of updates) {
       if (!isDecimalString(price)) {
-        wsLog.skippedRow(this.providerKey, 'order book level', 'price', price)
+        wsLog.skippedRow(
+          this.providerKey,
+          'order book level',
+          'price',
+          price,
+          this.marketId
+        )
         continue
       }
       if (!isDecimalString(size)) {
-        wsLog.skippedRow(this.providerKey, 'order book level', 'size', size)
+        wsLog.skippedRow(
+          this.providerKey,
+          'order book level',
+          'size',
+          size,
+          this.marketId
+        )
         this.remove(price)
         continue
       }