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

package/src/utils/transferMargin.ts

@@ -1,31 +1,40 @@
 import {
+  addDecimalString,
+  isDecimalString,
+  isDecimalStringGreaterThan,
   PerpsError,
   positionSupportsMarginAdjustment,
   positionSupportsMarginRemoval,
+  roundDecimalString,
+  subtractDecimalString,
 } from '@lifi/perps-sdk'
 import {
   type DecimalString,
   PerpsErrorCode,
   type Position,
 } from '@lifi/perps-types'
-import Big from 'big.js'
 
 const AMOUNT_DECIMALS = 6
 
-function positionAmount(value: string, field: string): Big {
-  try {
-    return new Big(value)
-  } catch {
+function positionAmount(
+  value: DecimalString | undefined,
+  field: string
+): DecimalString {
+  if (!isDecimalString(value)) {
     throw new PerpsError(
       PerpsErrorCode.ValidationError,
-      `Invalid decimal string on Position.${field}: '${value}'`
+      `Invalid \`Position.${field}\`: '${value}' is not a decimal string.`
     )
   }
+  return value
 }
 
-function positivePositionAmount(value: string, field: string): Big {
+function positivePositionAmount(
+  value: DecimalString | undefined,
+  field: string
+): DecimalString {
   const amount = positionAmount(value, field)
-  if (amount.lte(0)) {
+  if (!isDecimalStringGreaterThan(amount, '0')) {
     throw new PerpsError(
       PerpsErrorCode.ValidationError,
       `Position.${field} must be greater than zero.`
@@ -57,16 +66,18 @@ export function positionRemovableMargin(
   if (!positionSupportsMarginRemoval(position)) {
     return '0'
   }
-  const removable = positivePositionAmount(position.marginUsed, 'marginUsed')
-    .plus(positionAmount(position.unrealizedPnl, 'unrealizedPnl'))
-    .minus(
-      positivePositionAmount(
-        position.initialMarginRequirement,
-        'initialMarginRequirement'
-      )
+  const removable = subtractDecimalString(
+    addDecimalString(
+      positivePositionAmount(position.marginUsed, 'marginUsed'),
+      positionAmount(position.unrealizedPnl, 'unrealizedPnl')
+    ),
+    positivePositionAmount(
+      position.initialMarginRequirement,
+      'initialMarginRequirement'
     )
-  if (removable.lte(0)) {
+  )
+  if (!isDecimalStringGreaterThan(removable, '0')) {
     return '0'
   }
-  return removable.round(AMOUNT_DECIMALS, Big.roundDown).toFixed()
+  return roundDecimalString(removable, AMOUNT_DECIMALS, 'truncate')
 }

package/src/utils/withdrawableBalances.ts

@@ -1,15 +1,17 @@
 import {
   calculateTransferable,
   calculateWithdrawMax,
+  isDecimalStringGreaterThan,
   type ProviderWithdrawableBalance,
+  subtractDecimalString,
+  unknownToDecimalString,
 } from '@lifi/perps-sdk'
-import Big from 'big.js'
+import { LIGHTER_PROVIDER_KEY, LIGHTER_SPOT_CATEGORY_ID } from '../constants.js'
 import type { LtAccount } from '../types/account.js'
-import { toRequiredBig } from './decimal.js'
 
 /**
- * Split each held asset into the two routes a Lighter withdrawal can name:
- * spot draws on `balance` net of `locked_balance`, perps draws on
+ * Split each held asset into the two categories a Lighter withdrawal can
+ * name: spot draws on `balance` net of `locked_balance`, perps draws on
  * `margin_balance`. The settlement asset's perps route is also capped by the
  * account `available_balance`, which excludes the margin open positions use.
  * Every other asset's perps route reports its full `margin_balance`, uncapped,
@@ -20,42 +22,54 @@ import { toRequiredBig } from './decimal.js'
  *
  * @param settlementAssetIndex - L2 asset index of the deployment's collateral
  * asset, the only asset that `available_balance` is denominated in.
+ * @param perpsCategoryId - The instance's perps category id, the
+ * `categoryId` its collateral `Balance` rows carry.
  * @public
  */
 export const lighterWithdrawableBalances = (
   account: Pick<LtAccount, 'assets' | 'available_balance'>,
-  settlementAssetIndex: number
+  settlementAssetIndex: number,
+  perpsCategoryId: string
 ): ProviderWithdrawableBalance[] => {
   const rows: ProviderWithdrawableBalance[] = []
   for (const asset of account.assets) {
     const assetId = String(asset.asset_id)
-    const spot = toRequiredBig(asset.balance, 'balance').minus(
-      toRequiredBig(asset.locked_balance, 'locked_balance')
+    const spot = subtractDecimalString(
+      unknownToDecimalString(asset.balance, 'balance', LIGHTER_PROVIDER_KEY),
+      unknownToDecimalString(
+        asset.locked_balance,
+        'locked_balance',
+        LIGHTER_PROVIDER_KEY
+      )
     )
-    if (spot.gt(0)) {
-      const available = spot.toFixed()
+    if (isDecimalStringGreaterThan(spot, '0')) {
       rows.push({
         assetId,
-        route: 'spot',
-        available,
-        max: calculateWithdrawMax({ available }),
+        categoryId: LIGHTER_SPOT_CATEGORY_ID,
+        available: spot,
+        max: calculateWithdrawMax({ available: spot }),
       })
     }
-    const marginBalance = toRequiredBig(asset.margin_balance, 'margin_balance')
+    const marginBalance = unknownToDecimalString(
+      asset.margin_balance,
+      'margin_balance',
+      LIGHTER_PROVIDER_KEY
+    )
     const perps =
       asset.asset_id === settlementAssetIndex
         ? calculateTransferable(
-            toRequiredBig(
+            unknownToDecimalString(
               account.available_balance,
-              'available_balance'
-            ).toFixed(),
-            marginBalance.toFixed()
+              'available_balance',
+              LIGHTER_PROVIDER_KEY
+            ),
+            marginBalance
           )
-        : marginBalance.toFixed()
-    if (new Big(perps).gt(0)) {
+        : marginBalance
+    if (isDecimalStringGreaterThan(perps, '0')) {
       rows.push({
         assetId,
-        route: 'perps',
+        categoryId: perpsCategoryId,
         available: perps,
         max: calculateWithdrawMax({ available: perps }),
       })

package/src/utils/withdrawalTypes.ts

@@ -0,0 +1,125 @@
+import {
+  divideDecimalString,
+  isDecimalStringGreaterThan,
+  type ProviderWithdrawableBalance,
+  unknownToDecimalString,
+  type WithdrawalAssetRef,
+  type WithdrawalSourceTypes,
+  type WithdrawalTypeOption,
+} from '@lifi/perps-sdk'
+import { WithdrawalType } from '@lifi/perps-types'
+import { LIGHTER_PROVIDER_KEY } from '../constants.js'
+import type {
+  LtFastwithdrawInfoResponse,
+  LtTransferFeeInfoResponse,
+} from '../types/submit.js'
+
+const LIGHTER_SUCCESS_CODE = 200
+const L2_COLLATERAL_SCALE = '1000000'
+
+/**
+ * The `withdrawalOptions` a Lighter withdrawal accepts. `fast` sends the
+ * amount to the fast-withdraw operator account `toAccountIndex`; `fee` is the
+ * transfer fee in L2 6-decimal integer units.
+ *
+ * @public
+ */
+export type LighterWithdrawalOptions =
+  | { mode: 'standard' }
+  | { mode: 'fast'; toAccountIndex: number; fee: number }
+
+/**
+ * The fast-withdraw terms Lighter offers an account.
+ *
+ * @public
+ */
+export interface LighterFastWithdrawal {
+  toAccountIndex: number
+  fee: number
+  /** The lower of `withdraw_limit` and `max_withdrawal_amount`, in collateral units. */
+  limit: string
+}
+
+/**
+ * The fast-withdraw terms from `/fastwithdraw/info` and `/transferFeeInfo`, or
+ * `undefined` when either read reports a code other than 200 or no operator
+ * account is set.
+ *
+ * @throws {PerpsError} When a limit is not a decimal.
+ * @public
+ */
+export const lighterFastWithdrawal = (
+  info: LtFastwithdrawInfoResponse,
+  feeInfo: LtTransferFeeInfoResponse
+): LighterFastWithdrawal | undefined => {
+  if (
+    info.code !== LIGHTER_SUCCESS_CODE ||
+    feeInfo.code !== LIGHTER_SUCCESS_CODE ||
+    !(info.to_account_index > 0)
+  ) {
+    return undefined
+  }
+  const withdrawLimit = unknownToDecimalString(
+    info.withdraw_limit,
+    'withdraw_limit',
+    LIGHTER_PROVIDER_KEY
+  )
+  const maxWithdrawalAmount = unknownToDecimalString(
+    info.max_withdrawal_amount,
+    'max_withdrawal_amount',
+    LIGHTER_PROVIDER_KEY
+  )
+  const limit = isDecimalStringGreaterThan(withdrawLimit, maxWithdrawalAmount)
+    ? maxWithdrawalAmount
+    : withdrawLimit
+  return {
+    toAccountIndex: info.to_account_index,
+    fee: feeInfo.transfer_fee_usdc,
+    limit: divideDecimalString(limit, L2_COLLATERAL_SCALE),
+  }
+}
+
+/**
+ * The withdrawal types per withdrawable row. Every row offers `STANDARD` up to
+ * its `max`. The `fastSource` row also offers `FAST` when `fast` is set, up to
+ * the lower of its `max` and `fast.limit`.
+ *
+ * @public
+ */
+export const lighterWithdrawalTypes = (
+  rows: ProviderWithdrawableBalance[],
+  fastSource: WithdrawalAssetRef,
+  fast: LighterFastWithdrawal | undefined
+): WithdrawalSourceTypes[] =>
+  rows.map((row) => {
+    const standard: LighterWithdrawalOptions = { mode: 'standard' }
+    const options: WithdrawalTypeOption[] = [
+      {
+        type: WithdrawalType.STANDARD,
+        max: row.max,
+        withdrawalOptions: standard,
+      },
+    ]
+    if (
+      fast !== undefined &&
+      row.categoryId === fastSource.categoryId &&
+      row.assetId === fastSource.asset.id
+    ) {
+      const fastOptions: LighterWithdrawalOptions = {
+        mode: 'fast',
+        toAccountIndex: fast.toAccountIndex,
+        fee: fast.fee,
+      }
+      options.push({
+        type: WithdrawalType.FAST,
+        max: isDecimalStringGreaterThan(row.max, fast.limit)
+          ? fast.limit
+          : row.max,
+        withdrawalOptions: fastOptions,
+      })
+    }
+    return {
+      source: { categoryId: row.categoryId, asset: { id: row.assetId } },
+      options,
+    }
+  })

package/src/websocket/LighterWsProvider.ts

@@ -1,6 +1,8 @@
 import {
+  addDecimalString,
   cachePromise,
   getMarketRegistry,
+  isDecimalStringGreaterThan,
   type MarketRegistry,
   PerpsError,
   type PerpsProvider,
@@ -10,7 +12,9 @@ import {
   ReconnectingWebSocket,
   resolveRetryPolicy,
   resolveSubscribeQuote,
+  subtractDecimalString,
   toPerpsMarketDisplay,
+  unknownToDecimalString,
   WsProviderBase,
   type WsProviderFactory,
   type WsProviderFactoryParams,
@@ -24,7 +28,6 @@ import {
   type Position,
   type Subscription,
 } from '@lifi/perps-types'
-import Big from 'big.js'
 import type { Address } from 'viem'
 import { lighterPortfolioValue } from '../accountSummary.js'
 import {
@@ -48,7 +51,6 @@ import type {
   LtWsMarketStats,
   LtWsMarketStatsAllMessage,
   LtWsMessage,
-  LtWsOrderBook,
   LtWsOrderBookMessage,
   LtWsSpotMarketStats,
   LtWsSpotMarketStatsAllMessage,
@@ -58,13 +60,14 @@ import type {
 import { LIGHTER_RETRY_DEFAULTS, LighterApiClient } from '../utils/apiClient.js'
 import {
   fetchDetailedAccount,
+  isOpenPosition,
   mapFill,
   mapMarketContext,
   mapOrderUpdates,
   mapPosition,
-  toRequiredBig,
 } from '../utils/index.js'
 import { spotPriceByAssetId, spotValuation } from '../utils/spotPrice.js'
+import { askOrder, bidOrder, OrderBookSide } from './orderBookSide.js'
 
 // Public channels: `marketsContext` (market_stats/all + spot_market_stats/all),
 // `marketContext` (market_stats/N or spot_market_stats/N), `orderbook`
@@ -139,26 +142,16 @@ interface SubState {
   needsAuth: boolean
 }
 
-/**
- * A maintained book level, keyed in {@link OrderbookState} by its price string.
- * `priceNum` is the price parsed once on insert so the emit-time sort orders by
- * a cached number instead of re-parsing every price on every comparison.
- */
-interface BookLevel {
-  size: string
-  priceNum: number
-}
-
 /** Settlement equity and per-asset route quantities for account valuation. */
 interface AccountSummaryInputs {
-  perps?: { equity: Big } & Omit<AccountSummary, 'portfolioValue'>
-  balances?: Map<number, { spot: Big; margin: Big }>
+  perps?: { equity: string } & Omit<AccountSummary, 'portfolioValue'>
+  balances?: Map<number, { spot: string; margin: string }>
   lastPortfolioValue?: string
 }
 
 interface OrderbookState {
-  bids: Map<string, BookLevel>
-  asks: Map<string, BookLevel>
+  bids: OrderBookSide
+  asks: OrderBookSide
   assetId: string
 }
 
@@ -730,38 +723,47 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
       return
     }
 
-    const portfolio = toRequiredBig(
+    const portfolio = unknownToDecimalString(
       stats.portfolio_value,
-      'stats.portfolio_value'
+      'stats.portfolio_value',
+      this.providerKey
+    )
+    const collateral = unknownToDecimalString(
+      stats.collateral,
+      'stats.collateral',
+      this.providerKey
     )
-    const collateral = toRequiredBig(stats.collateral, 'stats.collateral')
 
-    let available: Big
-    let marginUsed: Big
+    let available: string
+    let marginUsed: string
     if (stats.cross_stats === undefined) {
       // Compatibility with legacy gateways that omitted the entire
       // cross_stats object.
-      available = toRequiredBig(
+      available = unknownToDecimalString(
         stats.available_balance,
-        'stats.available_balance'
+        'stats.available_balance',
+        this.providerKey
       )
-      marginUsed = portfolio.minus(available)
+      marginUsed = subtractDecimalString(portfolio, available)
     } else {
-      const crossCollateral = toRequiredBig(
+      const crossCollateral = unknownToDecimalString(
         stats.cross_stats.collateral,
-        'stats.cross_stats.collateral'
+        'stats.cross_stats.collateral',
+        this.providerKey
       )
-      const crossPortfolio = toRequiredBig(
+      const crossPortfolio = unknownToDecimalString(
         stats.cross_stats.portfolio_value,
-        'stats.cross_stats.portfolio_value'
+        'stats.cross_stats.portfolio_value',
+        this.providerKey
       )
-      available = toRequiredBig(
+      available = unknownToDecimalString(
         stats.cross_stats.available_balance,
-        'stats.cross_stats.available_balance'
+        'stats.cross_stats.available_balance',
+        this.providerKey
       )
-      const isolatedMargin = collateral.minus(crossCollateral)
-      const crossMargin = crossPortfolio.minus(available)
-      marginUsed = isolatedMargin.plus(crossMargin)
+      const isolatedMargin = subtractDecimalString(collateral, crossCollateral)
+      const crossMargin = subtractDecimalString(crossPortfolio, available)
+      marginUsed = addDecimalString(isolatedMargin, crossMargin)
     }
 
     const inputs = this.accountSummaryInputs.get(address)
@@ -770,9 +772,9 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
     }
     inputs.perps = {
       equity: portfolio,
-      availableMargin: available.toFixed(),
-      marginUsed: marginUsed.toFixed(),
-      unrealizedPnl: portfolio.minus(collateral).toFixed(),
+      availableMargin: available,
+      marginUsed,
+      unrealizedPnl: subtractDecimalString(portfolio, collateral),
     }
     this.emitAccountSummary(address)
   }
@@ -793,14 +795,18 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
     }
     const parsed = Object.values(msg.assets ?? {}).map((asset) => ({
       assetId: asset.asset_id,
-      spot: toRequiredBig(asset.balance, 'balance'),
+      spot: unknownToDecimalString(asset.balance, 'balance', this.providerKey),
       margin:
         asset.margin_balance === undefined
           ? undefined
-          : toRequiredBig(asset.margin_balance, 'margin_balance'),
+          : unknownToDecimalString(
+              asset.margin_balance,
+              'margin_balance',
+              this.providerKey
+            ),
     }))
     const balances = isSnapshot
-      ? new Map<number, { spot: Big; margin: Big }>()
+      ? new Map<number, { spot: string; margin: string }>()
       : inputs.balances
     if (balances === undefined) {
       return
@@ -808,7 +814,7 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
     for (const { assetId, spot, margin } of parsed) {
       balances.set(assetId, {
         spot,
-        margin: margin ?? balances.get(assetId)?.margin ?? new Big(0),
+        margin: margin ?? balances.get(assetId)?.margin ?? '0',
       })
     }
     inputs.balances = balances
@@ -827,10 +833,12 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
         ([assetId, { spot, margin }]) =>
           [
             assetId,
-            assetId === settlementAssetIndex ? spot : spot.plus(margin),
+            assetId === settlementAssetIndex
+              ? spot
+              : addDecimalString(spot, margin),
           ] as const
       )
-      .filter(([, balance]) => balance.gt(0))
+      .filter(([, balance]) => isDecimalStringGreaterThan(balance, '0'))
     const spotPrices = spotPriceByAssetId(
       this.registry?.markets ?? [],
       LIGHTER_SPOT_CATEGORY_ID,
@@ -845,14 +853,10 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
       inputs.perps.equity,
       held.map(
         ([assetId, balance]) =>
-          spotValuation(
-            assetId,
-            balance.toFixed(),
-            settlementAssetIndex,
-            spotPrices
-          ).valueUsd
+          spotValuation(assetId, balance, settlementAssetIndex, spotPrices)
+            .valueUsd
       )
-    ).toFixed()
+    )
     if (onlyOnChange && portfolioValue === inputs.lastPortfolioValue) {
       return
     }
@@ -887,7 +891,8 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
     const raw = collectAuthChannelItems<LtTrade>(msg, 'trades')
     const fills: Fill[] = raw.flatMap((t) => {
       const market = this.registry?.get(String(t.market_id))
-      return market ? [mapFill(t, accountIndex, market)] : []
+      const mapped = market && mapFill(t, accountIndex, market)
+      return mapped ? [mapped] : []
     })
     this.emit(`fills:${address}`, { channel: 'fills', data: fills })
   }
@@ -910,13 +915,18 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
       this.positionsByAddress.set(address, state)
     }
     for (const p of raw) {
-      if (Number.parseFloat(p.position) === 0) {
-        state.delete(p.market_id)
-      } else {
+      if (isOpenPosition(p)) {
         const market = this.registry?.get(String(p.market_id))
-        if (market) {
-          state.set(p.market_id, mapPosition(p, toPerpsMarketDisplay(market)))
+        const position = market
+          ? mapPosition(p, toPerpsMarketDisplay(market))
+          : undefined
+        if (position) {
+          state.set(p.market_id, position)
+        } else {
+          state.delete(p.market_id)
         }
+      } else {
+        state.delete(p.market_id)
       }
     }
     this.emit(`positions:${address}`, {
@@ -1006,20 +1016,24 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
 
     let state = this.orderbooks.get(marketId)
     if (!state || isSnapshot) {
-      state = { bids: new Map(), asks: new Map(), assetId }
+      state = {
+        bids: new OrderBookSide(bidOrder, this.providerKey),
+        asks: new OrderBookSide(askOrder, this.providerKey),
+        assetId,
+      }
       this.orderbooks.set(marketId, state)
     }
 
-    applyLevels(state.bids, msg.order_book.bids)
-    applyLevels(state.asks, msg.order_book.asks)
+    state.bids.apply(msg.order_book.bids)
+    state.asks.apply(msg.order_book.asks)
 
     this.emit(`orderbook:${assetId}`, {
       channel: 'orderbook',
       data: {
         provider: this.providerKey,
         marketId: assetId,
-        bids: mapToLevels(state.bids, true),
-        asks: mapToLevels(state.asks, false),
+        bids: state.bids.toLevels(),
+        asks: state.asks.toLevels(),
         timestamp: Date.now(),
       },
     })
@@ -1121,37 +1135,6 @@ function isMarketStatsEntry(
   return isObject(value) && typeof value.market_id === 'number'
 }
 
-function applyLevels(
-  book: Map<string, BookLevel>,
-  levels: LtWsOrderBook['bids']
-): void {
-  for (const level of levels) {
-    if (level.size === '0' || Number(level.size) === 0) {
-      book.delete(level.price)
-    } else {
-      const existing = book.get(level.price)
-      if (existing) {
-        existing.size = level.size
-      } else {
-        book.set(level.price, {
-          size: level.size,
-          priceNum: Number(level.price),
-        })
-      }
-    }
-  }
-}
-
-function mapToLevels(
-  book: Map<string, BookLevel>,
-  descending: boolean
-): Array<{ price: string; size: string }> {
-  const entries = [...book].sort(([, a], [, b]) =>
-    descending ? b.priceNum - a.priceNum : a.priceNum - b.priceNum
-  )
-  return entries.map(([price, { size }]) => ({ price, size }))
-}
-
 /**
  * Extract items from an auth-channel payload field. The field may be:
  *   - a flat array (e.g. `trades: []` on the initial subscribed snapshot)