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

package/dist/types/websocket/LighterWsProvider.d.ts

@@ -59,6 +59,7 @@ export declare class LighterWsProvider extends WsProviderBase<SubState> {
      * is a full open-position snapshot per the `PositionsEvent` contract.
      */
     private readonly positionsByAddress;
+    private readonly accountSummaryInputs;
     private readonly registry;
     private readonly accountIndexCache;
     private readonly accountIndexPromises;
@@ -77,6 +78,12 @@ export declare class LighterWsProvider extends WsProviderBase<SubState> {
      */
     subscribeQuote(params: ProviderGetQuoteParams, onQuote: QuoteListener): Promise<() => void>;
     protected openChannel(sub: Subscription): Promise<() => void>;
+    /**
+     * 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;
     protected onClose(): void;
     protected sendSubscribe({ channel, needsAuth, address, }: SubState): Promise<void>;
     /**
@@ -87,6 +94,8 @@ export declare class LighterWsProvider extends WsProviderBase<SubState> {
      * code, as it does for the Ondo and Lighter REST auth failures.
      */
     private requireAuthToken;
+    /** Whether a token resolves for the address; a resolver that throws counts as no token. */
+    private canResolveAuthToken;
     protected toKey(sub: Subscription): string;
     private resolveChannel;
     private resolveAccountIndex;
@@ -95,6 +104,21 @@ export declare class LighterWsProvider extends WsProviderBase<SubState> {
     private dispatch;
     private handleAccountOrders;
     private handleUserStats;
+    /**
+     * 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;
+    /**
+     * 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;
+    private settlementAssetIndex;
     private handleAccountTrades;
     private handleAccountPositions;
     /**

package/dist/types/websocket/LighterWsProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LighterWsProvider.d.ts","sourceRoot":"","sources":["../../../src/websocket/LighterWsProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAKlB,cAAc,EACd,KAAK,iBAAiB,EAGvB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAKL,KAAK,YAAY,EAClB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AA8EnC;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,wBAAwB,GAAG,CACrC,OAAO,EAAE,OAAO,KACb,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;AAEhC,UAAU,QAAQ;IAChB,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAA;IACf,+DAA+D;IAC/D,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,yEAAyE;IACzE,SAAS,EAAE,OAAO,CAAA;CACnB;AAkBD;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,wBAAwB,CAAA;CAC5C;AAED;;;;;;GAMG;AACH,qBAAa,iBAAkB,SAAQ,cAAc,CAAC,QAAQ,CAAC;IAC7D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAkB;IACtC,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAE5B;IACb,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;IAEnD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoC;IAC/D,OAAO,CAAC,cAAc,CAAoC;IAE1D;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAA2C;IAE9E,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;IAErD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA4B;IAC9D,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAqC;gBAGxE,KAAK,GAAE,MAA+B,EACtC,WAAW,GAAE,MAA6B,EAC1C,OAAO,GAAE,wBAA6B,EACtC,MAAM,CAAC,EAAE,cAAc;IAsBzB;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAWzB;;;;;OAKG;IACG,cAAc,CAClB,MAAM,EAAE,sBAAsB,EAC9B,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,IAAI,CAAC;cAkBN,WAAW,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC;cA6ChD,OAAO,IAAI,IAAI;cAMlB,aAAa,CAAC,EAC5B,OAAO,EACP,SAAS,EACT,OAAO,GACR,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAW3B;;;;;;OAMG;YACW,gBAAgB;IAsB9B,SAAS,CAAC,KAAK,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM;YAyB5B,cAAc;YAyFd,mBAAmB;YAqBnB,iBAAiB;IAK/B,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAqB1C,OAAO,CAAC,QAAQ;IAkFhB,OAAO,CAAC,mBAAmB;IAgB3B,OAAO,CAAC,eAAe;IAuDvB,OAAO,CAAC,mBAAmB;IAiB3B,OAAO,CAAC,sBAAsB;IAiC9B;;;;;;OAMG;IACH,OAAO,CAAC,kBAAkB;IAuB1B,OAAO,CAAC,iBAAiB;IAuCzB,OAAO,CAAC,eAAe;IA+BvB,OAAO,CAAC,YAAY;IAwBpB,OAAO,CAAC,mBAAmB;CAc5B;AAkID;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,iBAAiB,GAC5B,UAAU,wBAAwB,KACjC,iBAKA,CAAA"}
+{"version":3,"file":"LighterWsProvider.d.ts","sourceRoot":"","sources":["../../../src/websocket/LighterWsProvider.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifi/perps-sdk-provider-lighter",
-  "version": "30.0.1",
+  "version": "31.0.0",
   "description": "Lighter provider plugin for @lifi/perps-sdk",
   "homepage": "https://github.com/lifinance/perps-sdk",
   "bugs": {
@@ -44,10 +44,10 @@
   "dependencies": {
     "big.js": "^7.0.1",
     "viem": "^2.55.18",
-    "@lifi/perps-types": "^17.0.0"
+    "@lifi/perps-types": "^18.0.0"
   },
   "peerDependencies": {
-    "@lifi/perps-sdk": "^19.0.0"
+    "@lifi/perps-sdk": "^20.0.0"
   },
   "publishConfig": {
     "access": "public"

package/src/LighterProvider.ts

@@ -9,6 +9,8 @@ import {
   getProviders,
   isActiveOrderStatus,
   localStorageAdapter,
+  maxOf,
+  minOf,
   PerpsError,
   type PerpsProviderPlugin,
   type PerpsSDKClient,
@@ -74,7 +76,7 @@ import {
   projectLighterConfigSettings,
   resolveAccountTier,
 } from './accountConfig.js'
-import { getAccountSummary } from './accountSummary.js'
+import { getAccountSummary, lighterConfig } from './accountSummary.js'
 import { lighterAvailableToTrade } from './availableToTrade.js'
 import {
   DEFAULT_TRADES_LIMIT,
@@ -159,7 +161,7 @@ import {
   fetchRegisteredApiKey,
   normalizeLighterPublicKey,
 } from './utils/registeredApiKey.js'
-import { spotPriceByAssetId } from './utils/spotPrice.js'
+import { spotPriceByAssetId, spotValuation } from './utils/spotPrice.js'
 import { isPlaceholderTxHash } from './utils/txHash.js'
 import { wireList } from './utils/wireList.js'
 
@@ -168,13 +170,6 @@ const ZERO_FEE_TIER = { maker: '0', taker: '0' }
 const tickToFeeString = (tick: number): string =>
   String(tick / LIGHTER_FEE_TICK_SCALE)
 
-const transferableWithin = (venueFigure: Big, units: Big): string => {
-  if (venueFigure.lt(0)) {
-    return '0'
-  }
-  return (venueFigure.gt(units) ? units : venueFigure).toFixed()
-}
-
 const projectFeeTier = (
   limits: LtAccountLimits
 ): { maker: string; taker: string } => ({
@@ -789,24 +784,48 @@ export const createLighterProvider = (
     }
   }
 
-  const resolveAccountExists = async (
-    address: Address,
-    opts?: SDKRequestOptions
-  ): Promise<boolean> => {
+  /** The account, or `undefined` when Lighter has no account for the address. */
+  const fetchAccountIfExists = async (
+    client: LighterApiClient,
+    address: Address
+  ): Promise<LtAccount | undefined> => {
     try {
-      await fetchDetailedAccount(apiClient(opts), address)
-      return true
+      return await fetchDetailedAccount(client, address)
     } catch (err) {
       if (
         err instanceof PerpsError &&
         err.code === PerpsErrorCode.AccountNotFound
       ) {
-        return false
+        return undefined
       }
       throw err
     }
   }
 
+  /** The venue default for a market: its backend `defaultLeverage`, with cross margin. */
+  const resolveDefaultMarketSettings = async (
+    marketId: string
+  ): Promise<MarketSettings> => {
+    const registry = getMarketRegistry(requireClient(), providerKey)
+    await registry.sync()
+    const market = registry.require(marketId)
+    const leverage =
+      'maxLeverage' in market ? market.defaultLeverage : undefined
+    if (leverage === undefined || !(leverage > 0)) {
+      throw new PerpsError(
+        PerpsErrorCode.SDKError,
+        `The backend market '${marketId}' carries no positive Lighter default leverage`
+      )
+    }
+    return { marginMode: MarginMode.CROSS, leverage }
+  }
+
+  const resolveAccountExists = async (
+    address: Address,
+    opts?: SDKRequestOptions
+  ): Promise<boolean> =>
+    (await fetchAccountIfExists(apiClient(opts), address)) !== undefined
+
   let setupPromise: Promise<SetupAction[]> | undefined
 
   /** The venue's own `Provider.setup` descriptor for an action, if declared. */
@@ -963,9 +982,6 @@ export const createLighterProvider = (
       const instanceMeta = providers.find((p) => p.key === providerKey)
       const categories = instanceMeta?.categories ?? []
       const perpsCategory = categories.find((c) => c.quoteAsset !== null)
-      const spotCategoryId =
-        categories.find((c) => c.quoteAsset === null)?.id ??
-        LIGHTER_SPOT_CATEGORY_ID
 
       const availableBalance = toRequiredBig(
         account.available_balance,
@@ -982,7 +998,7 @@ export const createLighterProvider = (
       )
       const spotPrices = spotPriceByAssetId(
         registry.markets,
-        spotCategoryId,
+        LIGHTER_SPOT_CATEGORY_ID,
         prices,
         new Set(
           [...heldAssets, ...marginAssets]
@@ -996,16 +1012,17 @@ export const createLighterProvider = (
         asset: Asset,
         units: string
       ): Balance => {
-        const price =
-          a.asset_id === collateral.assetIndex
-            ? new Big(1)
-            : spotPrices.get(String(a.asset_id))
+        const { valueUsd, price } = spotValuation(
+          a.asset_id,
+          units,
+          collateral.assetIndex,
+          spotPrices
+        )
         return {
           categoryId,
           asset,
           units,
-          valueUsd:
-            price === undefined ? '0' : new Big(units).times(price).toFixed(),
+          valueUsd,
           ...(price === undefined ? {} : { price: price.toFixed() }),
         }
       }
@@ -1033,13 +1050,31 @@ export const createLighterProvider = (
             a.margin_balance
           ),
           transferable: isSettlement
-            ? transferableWithin(availableBalance, new Big(a.margin_balance))
+            ? minOf(
+                maxOf(availableBalance, new Big(0)),
+                new Big(a.margin_balance)
+              ).toFixed()
             : '0',
         }
       })
-      const balances: Balance[] = heldAssets.map((a) =>
-        toBalance(a, spotCategoryId, registryAsset(a), a.balance)
-      )
+      const balances: Balance[] = heldAssets.map((a) => {
+        const balance = new Big(a.balance)
+        return {
+          ...toBalance(
+            a,
+            LIGHTER_SPOT_CATEGORY_ID,
+            registryAsset(a),
+            a.balance
+          ),
+          transferable: minOf(
+            maxOf(
+              balance.minus(toRequiredBig(a.locked_balance, 'locked_balance')),
+              new Big(0)
+            ),
+            balance
+          ).toFixed(),
+        }
+      })
 
       const assetCollateral = account.assets.flatMap((a) =>
         a.margin_mode === undefined
@@ -1059,6 +1094,8 @@ export const createLighterProvider = (
         apiKeyRegistered,
         accountType: account.account_type,
         availableBalance: account.available_balance,
+        crossAssetValue: account.cross_asset_value,
+        crossInitialMarginRequirement: account.cross_initial_margin_requirement,
         totalAssetValue: account.total_asset_value,
         userTierName: limitsResult?.user_tier_name,
         accountTradingMode:
@@ -1112,11 +1149,13 @@ export const createLighterProvider = (
       params: ProviderGetWithdrawableBalancesParams,
       opts?: SDKRequestOptions
     ): Promise<ProviderWithdrawableBalance[]> {
-      const account = await fetchDetailedAccount(
+      const account = await fetchAccountIfExists(
         apiClient(opts),
         params.address
       )
-      return lighterWithdrawableBalances(account.assets)
+      return account === undefined
+        ? []
+        : lighterWithdrawableBalances(account, collateral.assetIndex)
     },
 
     async getPositions(
@@ -1126,9 +1165,16 @@ export const createLighterProvider = (
       const client = apiClient(opts)
       const registry = getMarketRegistry(requireClient(), providerKey)
       const [account] = await Promise.all([
-        fetchDetailedAccount(client, params.address),
+        fetchAccountIfExists(client, params.address),
         registry.sync(),
       ])
+      if (account === undefined) {
+        return {
+          provider: providerKey,
+          positions: [],
+          pagination: { limit: params.limit ?? 0, hasMore: false },
+        }
+      }
 
       let positions: Position[] = mapOpenPositions(account.positions, (id) =>
         toPerpsMarketDisplay(registry.require(String(id)))
@@ -1165,39 +1211,38 @@ export const createLighterProvider = (
     },
 
     /**
-     * Lighter reports a market's margin mode and leverage only on the
-     * account's position row, so a market the account never touched (or a
-     * missing account) resolves `undefined` rather than a venue default.
+     * Lighter reports a market's margin mode and leverage on the account's
+     * position row. Without a row carrying a positive IMF (or without an
+     * account), the venue applies the market's default leverage with cross margin.
      */
     async getMarketSettings(
       params: ProviderGetMarketSettingsParams,
       opts?: SDKRequestOptions
-    ): Promise<MarketSettings | undefined> {
-      // Spot markets carry no margin mode or leverage.
-      if (params.market.categoryId === LIGHTER_SPOT_CATEGORY_ID) {
-        return undefined
-      }
-      let account: LtAccount
-      try {
-        account = await fetchDetailedAccount(apiClient(opts), params.address)
-      } catch (err) {
-        if (
-          err instanceof PerpsError &&
-          err.code === PerpsErrorCode.AccountNotFound
-        ) {
-          return undefined
-        }
-        throw err
+    ): Promise<MarketSettings> {
+      const { marketId, categoryId } = params.market
+      if (categoryId === LIGHTER_SPOT_CATEGORY_ID) {
+        throw new PerpsError(
+          PerpsErrorCode.ValidationError,
+          `Lighter market '${marketId}' is a spot market and carries no leverage setting`
+        )
       }
-      const row = account.positions.find(
-        (p) => String(p.market_id) === params.market.marketId
+      const client = apiClient(opts)
+      const account = await fetchAccountIfExists(client, params.address)
+      const row = account?.positions.find(
+        (p) => String(p.market_id) === marketId
       )
-      if (!row) {
-        return undefined
-      }
-      const leverage = leverageFromImf(row.initial_margin_fraction)
-      if (leverage === undefined) {
-        return undefined
+      // An unparsable IMF throws; a non-positive one means no stored setting.
+      const leverage =
+        row === undefined
+          ? undefined
+          : leverageFromImf(
+              toRequiredBig(
+                row.initial_margin_fraction,
+                'initial_margin_fraction'
+              ).toFixed()
+            )
+      if (row === undefined || leverage === undefined) {
+        return resolveDefaultMarketSettings(marketId)
       }
       return {
         marginMode:
@@ -1493,12 +1538,12 @@ export const createLighterProvider = (
       }
 
       const client = apiClient(opts)
-      const account = await fetchDetailedAccount(client, params.address)
+      const account = await plugin.getAccount({ address: params.address }, opts)
       const window = PNL_WINDOWS[params.range]
       const endTimestampSeconds = Math.floor(Date.now() / 1_000)
       const queryParams: Record<string, string | number | boolean> = {
         by: 'index',
-        value: String(account.index),
+        value: String(lighterConfig(account).accountIndex),
         resolution: window.resolution,
         start_timestamp:
           params.range === 'all'
@@ -1537,7 +1582,7 @@ export const createLighterProvider = (
       return mapPortfolioHistory(
         params.range,
         wireList(response.pnl),
-        toRequiredBig(account.total_asset_value, 'total_asset_value')
+        new Big(getAccountSummary(account, account.positions).portfolioValue)
       )
     },
 

package/src/accountSummary.ts

@@ -7,10 +7,18 @@ import type {
 } from '@lifi/perps-types'
 import { PerpsErrorCode } from '@lifi/perps-types'
 import Big from 'big.js'
+import { atLeastZero } from './availableToTrade.js'
 import { LIGHTER_PROVIDER_KEY, LIGHTER_RH_PROVIDER_KEY } from './constants.js'
 import { toRequiredBig } from './utils/decimal.js'
 
-const lighterConfig = (account: AccountResponse): LighterAccountConfig => {
+/**
+ * The Lighter arm of `account.config`.
+ *
+ * @throws {PerpsError} `SDKError` when the account is not a Lighter one.
+ */
+export const lighterConfig = (
+  account: AccountResponse
+): LighterAccountConfig => {
   const { config } = account
   if (
     config.provider !== LIGHTER_PROVIDER_KEY &&
@@ -24,12 +32,27 @@ const lighterConfig = (account: AccountResponse): LighterAccountConfig => {
   return config
 }
 
+/**
+ * Lighter portfolio value: the perps-route equity (`total_asset_value`) plus
+ * the USD value of every spot-route holding, settlement asset included.
+ */
+export const lighterPortfolioValue = (
+  perpsEquity: Big,
+  spotValuesUsd: readonly string[]
+): Big =>
+  spotValuesUsd.reduce(
+    (sum, valueUsd) => sum.plus(toRequiredBig(valueUsd, 'valueUsd')),
+    perpsEquity
+  )
+
 /**
  * Roll a Lighter account up into an {@link AccountSummary}. `totalAssetValue`
  * is perps-route equity and excludes the spot route, so `portfolioValue` adds
  * every spot `balances` row, settlement included; the `collateralBalances` rows
- * are the perps-route holding already inside `totalAssetValue`. The positions
- * supply only the margin and PnL breakdown.
+ * are the perps-route holding already inside `totalAssetValue`.
+ * `availableMargin` is the cross free collateral, floored at 0: an isolated
+ * position's equity stays with that position until the user removes it. The
+ * positions supply only the margin and PnL breakdown.
  *
  * @throws {PerpsError} `SDKError` when the account is not a Lighter one.
  * @public
@@ -47,18 +70,18 @@ export function getAccountSummary(
     unrealizedPnl = unrealizedPnl.plus(position.unrealizedPnl)
   }
 
-  let portfolioValue = toRequiredBig(config.totalAssetValue, 'totalAssetValue')
-  for (const balance of account.balances) {
-    portfolioValue = portfolioValue.plus(
-      toRequiredBig(balance.valueUsd, 'valueUsd')
-    )
-  }
-
   return {
-    portfolioValue: portfolioValue.toFixed(),
-    availableMargin: toRequiredBig(
-      config.availableBalance,
-      'availableBalance'
+    portfolioValue: lighterPortfolioValue(
+      toRequiredBig(config.totalAssetValue, 'totalAssetValue'),
+      account.balances.map((balance) => balance.valueUsd)
+    ).toFixed(),
+    availableMargin: atLeastZero(
+      toRequiredBig(config.crossAssetValue, 'crossAssetValue').minus(
+        toRequiredBig(
+          config.crossInitialMarginRequirement,
+          'crossInitialMarginRequirement'
+        )
+      )
     ).toFixed(),
     marginUsed: marginUsed.toFixed(),
     unrealizedPnl: unrealizedPnl.toFixed(),

package/src/availableToTrade.ts

@@ -4,23 +4,19 @@ import { MarginMode, PositionSide } from '@lifi/perps-types'
 import Big from 'big.js'
 import { toRequiredBig } from './utils/decimal.js'
 
-const atLeastZero = (value: Big): Big => (value.lt(0) ? new Big(0) : value)
+export const atLeastZero = (value: Big): Big =>
+  value.lt(0) ? new Big(0) : value
 
-// Lighter's `available_balance` already nets cross unrealized PnL and counts
-// an isolated position's equity above its IMR, so only the rest is released.
+// `availableMargin` is the cross free collateral and holds nothing of an
+// isolated position, so closing one releases its whole equity.
 const releasedOnClose = (position: Position): Big => {
   const marginUsed = toRequiredBig(position.marginUsed, 'marginUsed')
   if (position.marginMode !== MarginMode.ISOLATED) {
     return marginUsed
   }
-  const equity = marginUsed.plus(
-    toRequiredBig(position.unrealizedPnl, 'unrealizedPnl')
+  return atLeastZero(
+    marginUsed.plus(toRequiredBig(position.unrealizedPnl, 'unrealizedPnl'))
   )
-  const imr = toRequiredBig(
-    position.initialMarginRequirement,
-    'initialMarginRequirement'
-  )
-  return equity.lt(imr) ? equity : imr
 }
 
 /**

package/src/types/ws.ts

@@ -1,3 +1,5 @@
+import type { LtAccountAsset } from './account.js'
+
 // The Lighter stream server sends JSON messages of shape:
 //   { type: 'subscribed/<channel>' | 'update/<channel>' | 'ping',
 //     channel: '<channel>/<id>',
@@ -9,6 +11,7 @@
 //   - spot_market_stats/all   → context across all spot markets
 //   - spot_market_stats/{id}  → context for one spot market
 //   - order_book/{market_id}  → bids/asks per market (stateful with deltas)
+//   - account_all/{account}   → per-asset spot-route balances
 
 /**
  * Common envelope fields on every Lighter WebSocket frame.
@@ -211,6 +214,26 @@ export type LtWsUserStatsMessage = LtWsMessage & {
   }
 }
 
+/**
+ * `account_all/{account_index}` or `account_all_assets/{account_index}` frame,
+ * read for its `assets` map only. The `subscribed/` frame carries every asset
+ * keyed by asset index; an `update/` frame carries the changed assets, or
+ * `null` when no balance changed. `balance` is the spot-route balance in asset
+ * units.
+ * @public
+ */
+export type LtWsAccountAllMessage = LtWsMessage & {
+  type:
+    | 'subscribed/account_all'
+    | 'update/account_all'
+    | 'subscribed/account_all_assets'
+    | 'update/account_all_assets'
+  assets?: Record<
+    string,
+    Pick<LtAccountAsset, 'symbol' | 'asset_id' | 'balance' | 'locked_balance'>
+  > | null
+}
+
 /**
  * Authenticated account-position frame. Position and funding maps are keyed
  * by Lighter market index; the provider normalizes the payload before emitting

package/src/utils/apiClient.ts

@@ -15,6 +15,15 @@ import { lighterErrorCodeFromBody } from './lighterErrorCode.js'
 /** @internal */
 export type ApiParams = Record<string, string | number | boolean>
 
+/**
+ * Short excerpt of a parsed Lighter body for an error message. `undefined`
+ * stands for a body that did not parse as JSON.
+ *
+ * @internal
+ */
+export const lighterBodyExcerpt = (data: unknown): string =>
+  data === undefined ? 'non-JSON body' : JSON.stringify(data).slice(0, 200)
+
 /**
  * Lighter signals errors on two channels: a non-2xx HTTP status, or an HTTP 200
  * carrying an error `code` in the JSON body. Returns the body error `code` when
@@ -269,7 +278,7 @@ export class LighterApiClient {
   async getWithStatus<T>(
     path: string,
     params?: ApiParams
-  ): Promise<{ status: number; data: T }> {
+  ): Promise<{ status: number; data: T | undefined }> {
     return this.sendGet<T>(path, params)
   }
 
@@ -277,7 +286,7 @@ export class LighterApiClient {
     path: string,
     params?: ApiParams,
     headers?: Record<string, string>
-  ): Promise<{ status: number; data: T }> {
+  ): Promise<{ status: number; data: T | undefined }> {
     this.assertRequestAllowed()
     const url = this.buildUrl(path, params)
     const response = await fetchWithRetry(
@@ -290,7 +299,7 @@ export class LighterApiClient {
       }
     )
     this.assertNotRateLimited(response)
-    const data = (await response.json().catch(() => undefined)) as T
+    const data = (await response.json().catch(() => undefined)) as T | undefined
     return { status: response.status, data }
   }
 
@@ -305,7 +314,7 @@ export class LighterApiClient {
     path: string,
     authToken: string,
     params: ApiParams
-  ): Promise<{ status: number; data: T }> {
+  ): Promise<{ status: number; data: T | undefined }> {
     const body = new URLSearchParams()
     for (const [k, v] of Object.entries(params)) {
       body.set(k, String(v))
@@ -320,7 +329,7 @@ export class LighterApiClient {
       signal: this.signal,
     })
     this.assertNotRateLimited(response)
-    const data = (await response.json().catch(() => undefined)) as T
+    const data = (await response.json().catch(() => undefined)) as T | undefined
     return { status: response.status, data }
   }
 
@@ -344,13 +353,13 @@ export class LighterApiClient {
     if (status < 200 || status >= 300) {
       throw new PerpsError(
         code,
-        `Lighter API request failed: ${status} — ${JSON.stringify(data).slice(0, 200)}`
+        `Lighter API request failed: ${status} — ${lighterBodyExcerpt(data)}`
       )
     }
     if (errorCode !== undefined) {
       throw new PerpsError(
         code,
-        `Lighter API error for ${path}: code ${errorCode} — ${JSON.stringify(data).slice(0, 200)}`
+        `Lighter API error for ${path}: code ${errorCode} — ${lighterBodyExcerpt(data)}`
       )
     }
   }

package/src/utils/fetchDetailedAccount.ts

@@ -3,7 +3,7 @@ import { PerpsErrorCode } from '@lifi/perps-types'
 import type { Address } from 'viem'
 import { LIGHTER_CODE_ACCOUNT_NOT_FOUND } from '../constants.js'
 import type { LtAccount, LtDetailedAccount } from '../types/index.js'
-import type { LighterApiClient } from './apiClient.js'
+import { type LighterApiClient, lighterBodyExcerpt } from './apiClient.js'
 import { wireList } from './wireList.js'
 
 /**
@@ -33,7 +33,7 @@ export const fetchDetailedAccount = async (
   if (status < 200 || status >= 300) {
     throw new PerpsError(
       PerpsErrorCode.ThirdPartyError,
-      `Lighter account request failed: ${status} — ${JSON.stringify(data).slice(0, 200)}`
+      `Lighter account request failed: ${status} — ${lighterBodyExcerpt(data)}`
     )
   }
 

package/src/utils/mapFill.ts

@@ -6,12 +6,9 @@ import {
 import type { Fill, MarketDisplay } from '@lifi/perps-types'
 import { LiquidityRole, OrderSide, OrderType } from '@lifi/perps-types'
 import Big from 'big.js'
-import {
-  LIGHTER_FEE_TICK_SCALE,
-  LIGHTER_IMF_PERCENT_SCALE,
-} from '../constants.js'
+import { LIGHTER_FEE_TICK_SCALE } from '../constants.js'
 import type { LtTrade } from '../types/index.js'
-import { leverageFromImf } from './mapPosition.js'
+import { leverageFromScaledImf } from './mapPosition.js'
 import { isPlaceholderTxHash } from './txHash.js'
 
 /**
@@ -36,16 +33,12 @@ const tickToFeeAmount = (
     .toFixed()
 
 /**
- * Display leverage the viewer had set on the market when the trade executed.
- * Lighter reports it as the pre-trade initial margin fraction, an integer
- * percent on `LIGHTER_IMF_PERCENT_SCALE`: `500` is 5.00%, so 20x. Returns
- * `undefined` when the row omits the fraction. Lighter declares the fraction a
- * `StrictInt`, so the scale division is exact and `toFixed()` loses nothing.
+ * Display leverage the viewer had set on the market when the trade executed,
+ * from the pre-trade initial margin fraction. Returns `undefined` when the
+ * row omits the fraction.
  */
 const leverageFromTradeImf = (imf: number | undefined): number | undefined =>
-  imf === undefined
-    ? undefined
-    : leverageFromImf(new Big(imf).div(LIGHTER_IMF_PERCENT_SCALE).toFixed())
+  imf === undefined ? undefined : leverageFromScaledImf(imf)
 
 /**
  * Realized PnL on a position-reducing fill, derived from the pre-trade entry