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

package/src/LighterProvider.ts

@@ -1,5 +1,6 @@
 import {
   ACTIVE_ORDER_STATUSES,
+  calculateTransferable,
   type DepositFlow,
   explorerTxUrl,
   explorerTxUrlFromBase,
@@ -9,8 +10,6 @@ import {
   getProviders,
   isActiveOrderStatus,
   localStorageAdapter,
-  maxOf,
-  minOf,
   PerpsError,
   type PerpsProviderPlugin,
   type PerpsSDKClient,
@@ -66,6 +65,7 @@ import type {
 import {
   ActionType,
   ActivityType,
+  isDecimalString,
   MarginMode,
   PerpsErrorCode,
 } from '@lifi/perps-types'
@@ -142,8 +142,6 @@ import { isAssetMarginEnabled } from './utils/assetCollateral.js'
 import {
   estimateLiquidationPrice,
   fetchDetailedAccount,
-  formatOrderPrice,
-  formatOrderSize,
   leverageFromImf,
   lighterAsset,
   lighterWithdrawableBalances,
@@ -152,6 +150,8 @@ import {
   mapOrder,
   mapPortfolioHistory,
   positionRemovableMargin,
+  snapOrderPrice,
+  snapOrderSize,
   toBigOrNull,
   toIsoFromMs,
   toIsoFromSeconds,
@@ -1042,37 +1042,37 @@ export const createLighterProvider = (
       // account's free margin; every other perps-route asset releases none.
       const collateralBalances: Balance[] = marginAssets.map((a) => {
         const isSettlement = a.asset_id === collateral.assetIndex
+        const marginBalance = toRequiredBig(
+          a.margin_balance,
+          'margin_balance'
+        ).toFixed()
         return {
           ...toBalance(
             a,
             perpsCategory?.id ?? providerKey,
             isSettlement ? settlementAsset : registryAsset(a),
-            a.margin_balance
+            isDecimalString(a.margin_balance) ? a.margin_balance : marginBalance
           ),
           transferable: isSettlement
-            ? minOf(
-                maxOf(availableBalance, new Big(0)),
-                new Big(a.margin_balance)
-              ).toFixed()
+            ? calculateTransferable(availableBalance.toFixed(), marginBalance)
             : '0',
         }
       })
       const balances: Balance[] = heldAssets.map((a) => {
-        const balance = new Big(a.balance)
+        const balance = toRequiredBig(a.balance, 'balance')
         return {
           ...toBalance(
             a,
             LIGHTER_SPOT_CATEGORY_ID,
             registryAsset(a),
-            a.balance
+            isDecimalString(a.balance) ? a.balance : balance.toFixed()
           ),
-          transferable: minOf(
-            maxOf(
-              balance.minus(toRequiredBig(a.locked_balance, 'locked_balance')),
-              new Big(0)
-            ),
+          transferable: calculateTransferable(
             balance
-          ).toFixed(),
+              .minus(toRequiredBig(a.locked_balance, 'locked_balance'))
+              .toFixed(),
+            balance.toFixed()
+          ),
         }
       })
 
@@ -1192,8 +1192,8 @@ export const createLighterProvider = (
     },
 
     /**
-     * Lighter publishes no per-market figure, so this derives one from the
-     * account's `available_balance` and its open position on the market.
+     * Derive per-market capacity from signed cross free collateral and the
+     * margin released by closing the market's open position.
      */
     async getAvailableToTrade(
       params: ProviderGetAvailableToTradeParams,
@@ -1206,8 +1206,21 @@ export const createLighterProvider = (
         return undefined
       }
       const account = await plugin.getAccount({ address: params.address }, opts)
-      const { availableMargin } = getAccountSummary(account, account.positions)
-      return lighterAvailableToTrade(market, availableMargin, account.positions)
+      const config = lighterConfig(account)
+      const crossFreeCollateral = toRequiredBig(
+        config.crossAssetValue,
+        'crossAssetValue'
+      ).minus(
+        toRequiredBig(
+          config.crossInitialMarginRequirement,
+          'crossInitialMarginRequirement'
+        )
+      )
+      return lighterAvailableToTrade(
+        market,
+        crossFreeCollateral.toFixed(),
+        account.positions
+      )
     },
 
     /**
@@ -1801,9 +1814,9 @@ export const createLighterProvider = (
       return getAccountSummary(account, positions)
     },
 
-    formatOrderPrice,
+    snapOrderPrice,
 
-    formatOrderSize,
+    snapOrderSize,
 
     estimateLiquidationPrice,
 

package/src/accountSummary.ts

@@ -8,7 +8,11 @@ import type {
 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 {
+  LIGHTER_COLLATERAL_ASSETS,
+  LIGHTER_PROVIDER_KEY,
+  LIGHTER_RH_PROVIDER_KEY,
+} from './constants.js'
 import { toRequiredBig } from './utils/decimal.js'
 
 /**
@@ -33,26 +37,20 @@ export const lighterConfig = (
 }
 
 /**
- * Lighter portfolio value: the perps-route equity (`total_asset_value`) plus
- * the USD value of every spot-route holding, settlement asset included.
+ * Add marked holdings excluded from Lighter's settlement equity.
  */
 export const lighterPortfolioValue = (
   perpsEquity: Big,
-  spotValuesUsd: readonly string[]
+  holdingValuesUsd: readonly string[]
 ): Big =>
-  spotValuesUsd.reduce(
+  holdingValuesUsd.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`.
- * `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.
+ * Roll up settlement equity, spot holdings and non-settlement margin holdings.
+ * Settlement margin is already included in `totalAssetValue`.
  *
  * @throws {PerpsError} `SDKError` when the account is not a Lighter one.
  * @public
@@ -62,6 +60,15 @@ export function getAccountSummary(
   positions: Position[]
 ): AccountSummary {
   const config = lighterConfig(account)
+  const settlement = LIGHTER_COLLATERAL_ASSETS[config.provider]
+  const holdings = [
+    ...account.balances,
+    ...account.collateralBalances.filter(
+      ({ asset }) =>
+        asset.id !== String(settlement.assetIndex) &&
+        asset.id !== settlement.displaySymbol
+    ),
+  ]
 
   let marginUsed = new Big(0)
   let unrealizedPnl = new Big(0)
@@ -73,7 +80,7 @@ export function getAccountSummary(
   return {
     portfolioValue: lighterPortfolioValue(
       toRequiredBig(config.totalAssetValue, 'totalAssetValue'),
-      account.balances.map((balance) => balance.valueUsd)
+      holdings.map((balance) => balance.valueUsd)
     ).toFixed(),
     availableMargin: atLeastZero(
       toRequiredBig(config.crossAssetValue, 'crossAssetValue').minus(

package/src/availableToTrade.ts

@@ -27,7 +27,7 @@ const releasedOnClose = (position: Position): Big => {
  * plus `availableMargin` and the margin that closing releases, floored at 0.
  * A deficit therefore never cuts the closing part. Both amounts are at least 0.
  *
- * @param availableMargin - The account's {@link AccountSummary.availableMargin}.
+ * @param availableMargin - Signed cross free collateral, before summary clamping.
  * @throws {PerpsError} `SDKError` when a decimal the formula reads is malformed.
  * @internal
  */

package/src/constants.ts

@@ -18,8 +18,10 @@ export const LIGHTER_RH_PROVIDER_KEY = 'lighter-rh'
 
 /**
  * Category id for Lighter spot token holdings, matching the backend's Lighter
- * spot asset category. The perps category id is not a constant — it is read
- * from the fetched markets so it tracks the backend taxonomy.
+ * spot asset category. Every Lighter call site, REST and WebSocket, uses this
+ * constant for the spot category. The perps category id is not a constant:
+ * `LighterProvider.getAccount` reads it from the `/providers` category whose
+ * `quoteAsset` is not null.
  *
  * @public
  */

package/src/signers/LighterSigner.ts

@@ -1,4 +1,4 @@
-import { PerpsError, scaleToInteger } from '@lifi/perps-sdk'
+import { decimalToBaseUnits, PerpsError } from '@lifi/perps-sdk'
 import { ActionType, PerpsErrorCode } from '@lifi/perps-types'
 import Big from 'big.js'
 import { LT_ROUTE_PERP, LT_ROUTE_SPOT } from '../types/action.js'
@@ -632,7 +632,7 @@ export class LighterSigner {
         return wasm.SignWithdraw(
           numberField(p, 'asset_index'),
           routeType,
-          scaleToInteger(amount, numberField(p, 'decimals'), 'truncate'),
+          decimalToBaseUnits(amount, numberField(p, 'decimals'), 'truncate'),
           SKIP_NONCE_DISABLED,
           nonce,
           ctx.apiKeyIndex,

package/src/types/ws.ts

@@ -11,7 +11,7 @@ import type { LtAccountAsset } from './account.js'
 //   - 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
+//   - account_all/{account}   → per-asset spot and margin-route balances
 
 /**
  * Common envelope fields on every Lighter WebSocket frame.
@@ -218,8 +218,7 @@ 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.
+ * `null` when no balance changed. Route balances are in asset units.
  * @public
  */
 export type LtWsAccountAllMessage = LtWsMessage & {
@@ -230,7 +229,8 @@ export type LtWsAccountAllMessage = LtWsMessage & {
     | 'update/account_all_assets'
   assets?: Record<
     string,
-    Pick<LtAccountAsset, 'symbol' | 'asset_id' | 'balance' | 'locked_balance'>
+    Pick<LtAccountAsset, 'symbol' | 'asset_id' | 'balance' | 'locked_balance'> &
+      Partial<Pick<LtAccountAsset, 'margin_balance'>>
   > | null
 }
 

package/src/utils/index.ts

@@ -21,7 +21,7 @@ export { mapPortfolioHistory } from './mapPortfolioHistory.js'
 export { leverageFromImf, mapPosition } from './mapPosition.js'
 export { mapMarketOrderLimits } from './marketLimits.js'
 export { mapInterval } from './ohlcvInterval.js'
-export { formatOrderPrice, formatOrderSize } from './orderFormatting.js'
+export { snapOrderPrice, snapOrderSize } from './orderFormatting.js'
 export { toIsoFromMs, toIsoFromSeconds } from './time.js'
 export { positionRemovableMargin } from './transferMargin.js'
 export {

package/src/utils/liquidation.ts

@@ -8,7 +8,7 @@
  */
 
 import {
-  estimateIsolatedLiquidationPrice,
+  estimateLiquidationPrice as estimateIsolatedLiquidationPrice,
   type LiquidationEstimateParams,
 } from '@lifi/perps-sdk'
 import type { PerpsMarket } from '@lifi/perps-types'

package/src/utils/mapMarketContext.ts

@@ -1,3 +1,4 @@
+import { numberToDecimalString } from '@lifi/perps-sdk'
 import type { MarketContext } from '@lifi/perps-types'
 import type { LtWsMarketStats, LtWsSpotMarketStats } from '../types/index.js'
 
@@ -7,6 +8,27 @@ const isPerpStats = (
   stats: LtWsMarketStats | LtWsSpotMarketStats
 ): stats is LtWsMarketStats => 'mark_price' in stats
 
+const isFiniteFigure = (value: number | null | undefined): value is number =>
+  typeof value === 'number' && Number.isFinite(value)
+
+/**
+ * The 24h figures of one record, omitted where the frame carries no finite
+ * number. The venue publishes them as unvalidated JSON, and `market_stats/all`
+ * maps every market in one pass, so a single absent figure must not cost the
+ * whole frame.
+ */
+const dailyFigures = (stats: {
+  daily_price_change?: number | null
+  daily_quote_token_volume?: number | null
+}): Pick<MarketContext, 'priceChange24h' | 'volume24h'> => ({
+  ...(isFiniteFigure(stats.daily_price_change)
+    ? { priceChange24h: numberToDecimalString(stats.daily_price_change) }
+    : {}),
+  ...(isFiniteFigure(stats.daily_quote_token_volume)
+    ? { volume24h: numberToDecimalString(stats.daily_quote_token_volume) }
+    : {}),
+})
+
 /**
  * Map a Lighter market-stats record to a {@link MarketContext}: `index_price`
  * is the oracle, `mid_price` the mid. Perp records carry the venue
@@ -24,8 +46,7 @@ export const mapMarketContext = (
       midPrice: stats.mid_price,
       markPrice: stats.mark_price,
       oraclePrice: stats.index_price,
-      priceChange24h: String(stats.daily_price_change),
-      volume24h: String(stats.daily_quote_token_volume),
+      ...dailyFigures(stats),
       openInterest: stats.open_interest,
       funding: {
         rate: stats.current_funding_rate,
@@ -38,7 +59,6 @@ export const mapMarketContext = (
     midPrice: stats.mid_price,
     markPrice: stats.mid_price,
     oraclePrice: stats.index_price,
-    priceChange24h: String(stats.daily_price_change),
-    volume24h: String(stats.daily_quote_token_volume),
+    ...dailyFigures(stats),
   }
 }

package/src/utils/orderFormatting.ts

@@ -1,31 +1,38 @@
 /**
- * Lighter order size and price formatting for exchange submission.
+ * Lighter order size and price snapping for exchange submission.
  *
  * Lighter publishes a flat per-market decimal budget on its order books
  * (`supported_price_decimals` / `supported_size_decimals`), surfaced on the
- * generic {@link Market} as `priceDecimals` / `szDecimals`. Prices round to
- * the tick grid; sizes truncate to the lot grid.
+ * generic {@link Market} as `priceDecimals` / `szDecimals`. Prices round onto
+ * the tick grid; sizes truncate onto the lot grid.
  */
 
 import { PerpsError } from '@lifi/perps-sdk'
-import { type Market, PerpsErrorCode } from '@lifi/perps-types'
+import {
+  type DecimalString,
+  type Market,
+  PerpsErrorCode,
+} from '@lifi/perps-types'
 import Big from 'big.js'
 
 /**
- * Format a price onto a Lighter market's tick grid: rounded to the market's
- * `priceDecimals` (Lighter's `supported_price_decimals`), trailing zeros
- * stripped.
+ * Snap a price onto a Lighter market's tick grid: rounded half-up to the
+ * market's `priceDecimals` (Lighter's `supported_price_decimals`), trailing
+ * zeros stripped.
  *
  * @throws {PerpsError} `ValidationError` when `market.priceDecimals` is
  *   absent — without the venue's tick grid no correct price can be produced.
  * @public
  */
-export function formatOrderPrice(market: Market, price: number): string {
+export function snapOrderPrice(
+  market: Market,
+  price: DecimalString
+): DecimalString {
   if (market.priceDecimals === undefined) {
     throw new PerpsError(
       PerpsErrorCode.ValidationError,
       `Market '${market.id}' carries no priceDecimals; Lighter order prices ` +
-        `cannot be formatted without the market's tick grid.`
+        `cannot be snapped without the market's tick grid.`
     )
   }
   const rounded = new Big(price).round(market.priceDecimals, Big.roundHalfUp)
@@ -33,14 +40,17 @@ export function formatOrderPrice(market: Market, price: number): string {
 }
 
 /**
- * Format a size onto a Lighter market's lot grid: truncated (never rounded
- * up, so the size cannot exceed the user's balance) to the market's
+ * Snap a size onto a Lighter market's lot grid: truncated toward zero (never
+ * rounded up, so the size cannot exceed the user's balance) to the market's
  * `szDecimals` (Lighter's `supported_size_decimals`), trailing zeros stripped.
  *
  * @param size - Size in base-asset units as a non-negative magnitude.
  * @public
  */
-export function formatOrderSize(market: Market, size: number): string {
+export function snapOrderSize(
+  market: Market,
+  size: DecimalString
+): DecimalString {
   const truncated = new Big(size).round(market.szDecimals, Big.roundDown)
   return truncated.eq(0) ? '0' : truncated.toFixed()
 }

package/src/utils/withdrawableBalances.ts

@@ -1,4 +1,8 @@
-import { maxOf, minOf, type ProviderWithdrawableBalance } from '@lifi/perps-sdk'
+import {
+  calculateTransferable,
+  calculateWithdrawMax,
+  type ProviderWithdrawableBalance,
+} from '@lifi/perps-sdk'
 import Big from 'big.js'
 import type { LtAccount } from '../types/account.js'
 import { toRequiredBig } from './decimal.js'
@@ -29,21 +33,32 @@ export const lighterWithdrawableBalances = (
       toRequiredBig(asset.locked_balance, 'locked_balance')
     )
     if (spot.gt(0)) {
-      rows.push({ assetId, route: 'spot', available: spot.toFixed() })
+      const available = spot.toFixed()
+      rows.push({
+        assetId,
+        route: 'spot',
+        available,
+        max: calculateWithdrawMax({ available }),
+      })
     }
     const marginBalance = toRequiredBig(asset.margin_balance, 'margin_balance')
     const perps =
       asset.asset_id === settlementAssetIndex
-        ? minOf(
-            maxOf(
-              toRequiredBig(account.available_balance, 'available_balance'),
-              new Big(0)
-            ),
-            marginBalance
+        ? calculateTransferable(
+            toRequiredBig(
+              account.available_balance,
+              'available_balance'
+            ).toFixed(),
+            marginBalance.toFixed()
           )
-        : marginBalance
-    if (perps.gt(0)) {
-      rows.push({ assetId, route: 'perps', available: perps.toFixed() })
+        : marginBalance.toFixed()
+    if (new Big(perps).gt(0)) {
+      rows.push({
+        assetId,
+        route: 'perps',
+        available: perps,
+        max: calculateWithdrawMax({ available: perps }),
+      })
     }
   }
   return rows

package/src/websocket/LighterWsProvider.ts

@@ -24,6 +24,7 @@ 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 {
@@ -148,14 +149,10 @@ 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`.
- */
+/** Settlement equity and per-asset route quantities for account valuation. */
 interface AccountSummaryInputs {
   perps?: { equity: Big } & Omit<AccountSummary, 'portfolioValue'>
-  spotBalances?: Map<number, Big>
+  balances?: Map<number, { spot: Big; margin: Big }>
   lastPortfolioValue?: string
 }
 
@@ -516,9 +513,7 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
       // instead of every later frame.
       this.settlementAssetIndex()
       const accountIndex = await this.resolveAccountIndex(sub.address)
-      // `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.
+      // `account_all_assets` requires auth; `account_all` is publicly readable.
       const hasToken = await this.canResolveAuthToken(sub.address)
       const assetsChannel = hasToken ? 'account_all_assets' : 'account_all'
       return [
@@ -785,12 +780,7 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
     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.
-   */
+  /** Snapshots replace all route quantities; deltas upsert changed assets. */
   private handleAccountAll(
     msg: LtWsAccountAllMessage,
     prefix: 'account_all' | 'account_all_assets',
@@ -804,34 +794,46 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
     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
+    const parsed = Object.values(msg.assets ?? {}).map((asset) => ({
+      assetId: asset.asset_id,
+      spot: toRequiredBig(asset.balance, 'balance'),
+      margin:
+        asset.margin_balance === undefined
+          ? undefined
+          : toRequiredBig(asset.margin_balance, 'margin_balance'),
+    }))
+    const balances = isSnapshot
+      ? new Map<number, { spot: Big; margin: Big }>()
+      : inputs.balances
     if (balances === undefined) {
       return
     }
-    for (const [assetId, balance] of parsed) {
-      balances.set(assetId, balance)
+    for (const { assetId, spot, margin } of parsed) {
+      balances.set(assetId, {
+        spot,
+        margin: margin ?? balances.get(assetId)?.margin ?? new Big(0),
+      })
     }
-    inputs.spotBalances = balances
+    inputs.balances = 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.
-   */
+  /** Unrelated mark ticks do not emit an unchanged portfolio value. */
   private emitAccountSummary(address: string, onlyOnChange = false): void {
     const inputs = this.accountSummaryInputs.get(address)
-    if (inputs?.perps === undefined || inputs.spotBalances === undefined) {
+    if (inputs?.perps === undefined || inputs.balances === undefined) {
       return
     }
     const settlementAssetIndex = this.settlementAssetIndex()
-    const held = [...inputs.spotBalances].filter(([, balance]) => balance.gt(0))
+    const held = [...inputs.balances]
+      .map(
+        ([assetId, { spot, margin }]) =>
+          [
+            assetId,
+            assetId === settlementAssetIndex ? spot : spot.plus(margin),
+          ] as const
+      )
+      .filter(([, balance]) => balance.gt(0))
     const spotPrices = spotPriceByAssetId(
       this.registry?.markets ?? [],
       LIGHTER_SPOT_CATEGORY_ID,