@lifi/perps-sdk-provider-lighter 30.0.0 → 31.0.0

package/src/websocket/LighterWsProvider.ts

@@ -17,6 +17,7 @@ import {
   wsLog,
 } from '@lifi/perps-sdk'
 import {
+  type AccountSummary,
   type Fill,
   type MarketContext,
   PerpsErrorCode,
@@ -24,11 +25,14 @@ import {
   type Subscription,
 } from '@lifi/perps-types'
 import type { Address } from 'viem'
+import { lighterPortfolioValue } from '../accountSummary.js'
 import {
   DEFAULT_LIGHTER_REST_URL,
   DEFAULT_LIGHTER_WS_URL,
   LIGHTER_BASE_FEE_TIER,
+  LIGHTER_COLLATERAL_ASSETS,
   LIGHTER_PROVIDER_KEY,
+  LIGHTER_RH_PROVIDER_KEY,
   LIGHTER_SPOT_CATEGORY_ID,
 } from '../constants.js'
 import type { LighterPerpsProvider } from '../LighterProvider.js'
@@ -36,6 +40,7 @@ import type {
   LtAccountPosition,
   LtOrder,
   LtTrade,
+  LtWsAccountAllMessage,
   LtWsAccountAllOrdersMessage,
   LtWsAccountAllPositionsMessage,
   LtWsAccountAllTradesMessage,
@@ -58,14 +63,18 @@ import {
   mapPosition,
   toRequiredBig,
 } from '../utils/index.js'
+import { spotPriceByAssetId, spotValuation } from '../utils/spotPrice.js'
 
 // Public channels: `marketsContext` (market_stats/all + spot_market_stats/all),
 // `marketContext` (market_stats/N or spot_market_stats/N), `orderbook`
-// (order_book/N), `trades` (trade/N).
+// (order_book/N), `trades` (trade/N), `accountSummary` (user_stats/N +
+// account_all/N, priced by the `marketsContext` spot marks).
 // Authenticated channels (resolve an auth token per subscribe send):
 //   - orderUpdates → account_all_orders/{account_index}
 //   - fills        → account_all_trades/{account_index}
 //   - positions    → account_all_positions/{account_index}
+//   - accountSummary spot balances → account_all_assets/{account_index}, when
+//     a token resolves at subscribe time; else the public account_all/N
 //
 // Auth pattern (per Lighter WS spec): the subscribe payload carries the
 // token directly — `{ type: "subscribe", channel: "...", auth: "<token>" }`.
@@ -95,6 +104,7 @@ const LIGHTER_AUTH_CHANNEL = {
 function channelNeedsMarkets(channel: Subscription['channel']): boolean {
   return (
     channel === 'marketContext' ||
+    channel === 'accountSummary' ||
     channel === 'orderUpdates' ||
     channel === 'fills' ||
     channel === 'positions'
@@ -138,6 +148,17 @@ interface BookLevel {
   priceNum: number
 }
 
+/**
+ * Per-address inputs of the `accountSummary` emit: the latest `user_stats`
+ * figures (`perps`, whose `equity` is perps-route only) and the spot-route
+ * balance per asset index from `account_all` or `account_all_assets`.
+ */
+interface AccountSummaryInputs {
+  perps?: { equity: Big } & Omit<AccountSummary, 'portfolioValue'>
+  spotBalances?: Map<number, Big>
+  lastPortfolioValue?: string
+}
+
 interface OrderbookState {
   bids: Map<string, BookLevel>
   asks: Map<string, BookLevel>
@@ -185,6 +206,11 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
    */
   private readonly positionsByAddress = new Map<string, Map<number, Position>>()
 
+  private readonly accountSummaryInputs = new Map<
+    string,
+    AccountSummaryInputs
+  >()
+
   private readonly registry: MarketRegistry | undefined
 
   private readonly accountIndexCache = new Map<string, number>()
@@ -279,15 +305,37 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
       }
     }
 
-    // Registry keyed by the wire channel (unique per sub), so replay-failure
-    // logs name the channel the venue knows. A logical sub may fan out to
-    // several wire channels (e.g. `marketsContext`), each registered independently.
-    for (const { channel, needsAuth, address } of wireChannels) {
-      await this.registerSub(channel, { channel, needsAuth, address })
+    // Acquired before the wire subs register, so a rejected spot-mark open
+    // leaves no `user_stats`/`account_all` entry behind for the next replay.
+    const releaseSpotMarks =
+      sub.channel === 'accountSummary'
+        ? await this.subscribeSpotMarks(sub)
+        : undefined
+    if (sub.channel === 'accountSummary') {
+      this.accountSummaryInputs.set(sub.address.toLowerCase(), {})
+    }
+
+    try {
+      // Registry keyed by the wire channel (unique per sub), so replay-failure
+      // logs name the channel the venue knows. A logical sub may fan out to
+      // several wire channels (e.g. `marketsContext`), each registered independently.
+      for (const { channel, needsAuth, address } of wireChannels) {
+        await this.registerSub(channel, { channel, needsAuth, address })
+      }
+      await this.rws.ready()
+    } catch (error) {
+      releaseSpotMarks?.()
+      for (const { channel } of wireChannels) {
+        this.unregisterSub(channel)
+      }
+      if (sub.channel === 'accountSummary') {
+        this.accountSummaryInputs.delete(sub.address.toLowerCase())
+      }
+      throw error
     }
-    await this.rws.ready()
 
     return () => {
+      releaseSpotMarks?.()
       for (const { channel } of wireChannels) {
         this.unregisterSub(channel)
         this.rws.send(JSON.stringify({ type: 'unsubscribe', channel }))
@@ -301,13 +349,31 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
       if (sub.channel === 'positions') {
         this.positionsByAddress.delete(sub.address.toLowerCase())
       }
+      if (sub.channel === 'accountSummary') {
+        this.accountSummaryInputs.delete(sub.address.toLowerCase())
+      }
     }
   }
 
+  /**
+   * Hold a `marketsContext` subscription for the spot marks that price the
+   * account's spot balances. The ref-counted base shares the wire channels
+   * with any consumer `marketsContext` subscription.
+   */
+  private subscribeSpotMarks(
+    sub: Extract<Subscription, { channel: 'accountSummary' }>
+  ): Promise<() => void> {
+    const address = sub.address.toLowerCase()
+    return this.subscribe({ channel: 'marketsContext', dex: sub.dex }, () =>
+      this.emitAccountSummary(address, true)
+    )
+  }
+
   protected override onClose(): void {
     this.orderbooks.clear()
     this.marketsContext = {}
     this.positionsByAddress.clear()
+    this.accountSummaryInputs.clear()
   }
 
   protected async sendSubscribe({
@@ -354,6 +420,19 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
     return token
   }
 
+  /** Whether a token resolves for the address; a resolver that throws counts as no token. */
+  private async canResolveAuthToken(address: Address): Promise<boolean> {
+    const resolve = this.authTokenResolver()
+    if (!resolve) {
+      return false
+    }
+    try {
+      return Boolean(await resolve(address))
+    } catch {
+      return false
+    }
+  }
+
   protected toKey(sub: Subscription): string {
     switch (sub.channel) {
       case 'marketsContext':
@@ -433,14 +512,26 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
       return [{ channel: `trade/${id}`, needsAuth: false }]
     }
     if (sub.channel === 'accountSummary') {
+      // Rejects the subscribe for a provider key with no settlement asset,
+      // instead of every later frame.
+      this.settlementAssetIndex()
       const accountIndex = await this.resolveAccountIndex(sub.address)
-      // `user_stats` is publicly readable; no token needed.
+      // `account_all_assets` carries only the spot balances but rejects a
+      // subscribe without auth; the public `account_all` also carries the
+      // account's trades, positions and funding.
+      const hasToken = await this.canResolveAuthToken(sub.address)
+      const assetsChannel = hasToken ? 'account_all_assets' : 'account_all'
       return [
         {
           channel: `user_stats/${accountIndex}`,
           needsAuth: false,
           address: sub.address,
         },
+        {
+          channel: `${assetsChannel}/${accountIndex}`,
+          needsAuth: hasToken,
+          address: sub.address,
+        },
       ]
     }
     if (
@@ -585,6 +676,30 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
       return
     }
 
+    if (
+      msg.type === 'subscribed/account_all' ||
+      msg.type === 'update/account_all'
+    ) {
+      this.handleAccountAll(
+        msg as LtWsAccountAllMessage,
+        'account_all',
+        msg.type === 'subscribed/account_all'
+      )
+      return
+    }
+
+    if (
+      msg.type === 'subscribed/account_all_assets' ||
+      msg.type === 'update/account_all_assets'
+    ) {
+      this.handleAccountAll(
+        msg as LtWsAccountAllMessage,
+        'account_all_assets',
+        msg.type === 'subscribed/account_all_assets'
+      )
+      return
+    }
+
     if (
       msg.type === 'subscribed/account_all_positions' ||
       msg.type === 'update/account_all_positions'
@@ -657,17 +772,110 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
       marginUsed = isolatedMargin.plus(crossMargin)
     }
 
+    const inputs = this.accountSummaryInputs.get(address)
+    if (inputs === undefined) {
+      return
+    }
+    inputs.perps = {
+      equity: portfolio,
+      availableMargin: available.toFixed(),
+      marginUsed: marginUsed.toFixed(),
+      unrealizedPnl: portfolio.minus(collateral).toFixed(),
+    }
+    this.emitAccountSummary(address)
+  }
+
+  /**
+   * Replace the spot balances on a `subscribed/` frame and upsert them on an
+   * `update/` frame. An update before the first snapshot is dropped, so the
+   * map never holds a partial set. Balances parse here, so a non-decimal
+   * balance rejects its frame and never reaches the emit path.
+   */
+  private handleAccountAll(
+    msg: LtWsAccountAllMessage,
+    prefix: 'account_all' | 'account_all_assets',
+    isSnapshot: boolean
+  ): void {
+    const address = this.addressFromChannel(msg.channel, prefix)
+    if (!address) {
+      return
+    }
+    const inputs = this.accountSummaryInputs.get(address)
+    if (inputs === undefined || (!isSnapshot && !msg.assets)) {
+      return
+    }
+    const parsed = Object.values(msg.assets ?? {}).map(
+      (asset) =>
+        [asset.asset_id, toRequiredBig(asset.balance, 'balance')] as const
+    )
+    const balances = isSnapshot ? new Map<number, Big>() : inputs.spotBalances
+    if (balances === undefined) {
+      return
+    }
+    for (const [assetId, balance] of parsed) {
+      balances.set(assetId, balance)
+    }
+    inputs.spotBalances = balances
+    this.emitAccountSummary(address)
+  }
+
+  /**
+   * Emit the account summary once both the `user_stats` figures and the spot
+   * balances are in. `portfolioValue` values the spot balances as REST
+   * `getAccount` does. `onlyOnChange` skips an emit whose `portfolioValue`
+   * equals the last one, so a mark tick on an unrelated market emits nothing.
+   */
+  private emitAccountSummary(address: string, onlyOnChange = false): void {
+    const inputs = this.accountSummaryInputs.get(address)
+    if (inputs?.perps === undefined || inputs.spotBalances === undefined) {
+      return
+    }
+    const settlementAssetIndex = this.settlementAssetIndex()
+    const held = [...inputs.spotBalances].filter(([, balance]) => balance.gt(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(
+      inputs.perps.equity,
+      held.map(
+        ([assetId, balance]) =>
+          spotValuation(
+            assetId,
+            balance.toFixed(),
+            settlementAssetIndex,
+            spotPrices
+          ).valueUsd
+      )
+    ).toFixed()
+    if (onlyOnChange && portfolioValue === inputs.lastPortfolioValue) {
+      return
+    }
+    inputs.lastPortfolioValue = portfolioValue
+    const { equity: _equity, ...perps } = inputs.perps
     this.emit(`accountSummary:${address}`, {
       channel: 'accountSummary',
-      data: {
-        portfolioValue: portfolio.toFixed(),
-        availableMargin: available.toFixed(),
-        marginUsed: marginUsed.toFixed(),
-        unrealizedPnl: portfolio.minus(collateral).toFixed(),
-      },
+      data: { portfolioValue, ...perps },
     })
   }
 
+  private settlementAssetIndex(): number {
+    const key = this.providerKey
+    if (key === LIGHTER_PROVIDER_KEY || key === LIGHTER_RH_PROVIDER_KEY) {
+      return LIGHTER_COLLATERAL_ASSETS[key].assetIndex
+    }
+    throw new PerpsError(
+      PerpsErrorCode.SDKError,
+      `Lighter WS: no settlement asset for provider '${key}'.`
+    )
+  }
+
   private handleAccountTrades(msg: LtWsAccountAllTradesMessage): void {
     const address = this.addressFromChannel(msg.channel, 'account_all_trades')
     if (!address) {