@lifi/perps-sdk-provider-lighter 27.0.0 → 29.0.0

package/src/LighterProvider.ts

@@ -5,6 +5,7 @@ import {
   explorerTxUrlFromBase,
   getAssetRegistry,
   getMarketRegistry,
+  getMarketsContext,
   getProviders,
   isActiveOrderStatus,
   localStorageAdapter,
@@ -14,6 +15,7 @@ import {
   type ProviderAccountExistsParams,
   type ProviderGetAccountParams,
   type ProviderGetActivityParams,
+  type ProviderGetAvailableToTradeParams,
   type ProviderGetDepositFlowParams,
   type ProviderGetFillsParams,
   type ProviderGetMarketSettingsParams,
@@ -40,6 +42,7 @@ import type {
   ActionStep,
   ActivitiesResponse,
   ActivityItem,
+  AvailableToTrade,
   Balance,
   Fill,
   FillsResponse,
@@ -63,9 +66,11 @@ import {
   MarginMode,
   PerpsErrorCode,
 } from '@lifi/perps-types'
+import Big from 'big.js'
 import type { Address } from 'viem'
 import { projectLighterConfigSettings } from './accountConfig.js'
 import { getAccountSummary } from './accountSummary.js'
+import { lighterAvailableToTrade } from './availableToTrade.js'
 import {
   DEFAULT_TRADES_LIMIT,
   LIGHTER_ALL_MARKETS_WILDCARD,
@@ -138,7 +143,7 @@ import {
   mapOpenPositions,
   mapOrder,
   mapPortfolioHistory,
-  positionMarginConstraints,
+  positionRemovableMargin,
   toBigOrNull,
   toIsoFromMs,
   toIsoFromSeconds,
@@ -148,6 +153,7 @@ import {
   fetchRegisteredApiKey,
   normalizeLighterPublicKey,
 } from './utils/registeredApiKey.js'
+import { spotPriceByAssetId } from './utils/spotPrice.js'
 import { isPlaceholderTxHash } from './utils/txHash.js'
 import { wireList } from './utils/wireList.js'
 
@@ -781,7 +787,7 @@ export const createLighterProvider = (
     }
   }
 
-  return {
+  const plugin: LighterPerpsProvider = {
     type: providerKey,
 
     internalSetupActions: [ActionType.SET_REFERRAL],
@@ -825,11 +831,12 @@ export const createLighterProvider = (
 
       const registry = getMarketRegistry(requireClient(), providerKey)
       const assetRegistry = getAssetRegistry(requireClient(), providerKey)
-      const [{ providers }, , , limitsResult, storedReadOnlyToken] =
+      const [{ providers }, , , { prices }, limitsResult, storedReadOnlyToken] =
         await Promise.all([
           getProviders(requireClient()),
           registry.sync(),
           assetRegistry.sync(),
+          getMarketsContext(requireClient(), { provider: providerKey }, opts),
           token === undefined
             ? Promise.resolve(undefined)
             : retryOnRevoked(opts, params.address, token, (resolvedToken) =>
@@ -844,12 +851,12 @@ export const createLighterProvider = (
       )
 
       const totalMarginUsed = positions.reduce(
-        (sum, p) => sum + Number.parseFloat(p.marginUsed),
-        0
+        (sum, p) => sum.plus(toRequiredBig(p.marginUsed, 'marginUsed')),
+        new Big(0)
       )
       const totalUnrealizedPnl = positions.reduce(
-        (sum, p) => sum + Number.parseFloat(p.unrealizedPnl),
-        0
+        (sum, p) => sum.plus(toRequiredBig(p.unrealizedPnl, 'unrealizedPnl')),
+        new Big(0)
       )
 
       const instanceMeta = providers.find((p) => p.key === providerKey)
@@ -883,23 +890,39 @@ export const createLighterProvider = (
           ]
         : []
       // Spot token holdings — non-collateral. The instance's settlement asset
-      // is valued 1:1; other tokens have no price source at this boundary, so
-      // their price and USD value are unknown.
-      const balances: Balance[] = account.assets
-        .filter((asset) => toRequiredBig(asset.balance, 'balance').gt(0))
-        .map((a) => {
-          const assetId = String(a.asset_id)
-          const settlement = a.asset_id === collateral.assetIndex
-          return {
-            categoryId: spotCategoryId,
-            asset:
-              assetRegistry.get(assetId) ??
-              lighterAsset(assetId, a.symbol, providerKey),
-            units: a.balance,
-            valueUsd: settlement ? a.balance : '0',
-            ...(settlement ? { price: '1' } : {}),
-          }
-        })
+      // is valued 1:1; an asset no spot market prices keeps a zero USD value.
+      const heldAssets = account.assets.filter((asset) =>
+        toRequiredBig(asset.balance, 'balance').gt(0)
+      )
+      const spotPrices = spotPriceByAssetId(
+        registry.markets,
+        spotCategoryId,
+        prices,
+        new Set(
+          heldAssets
+            .filter((a) => a.asset_id !== collateral.assetIndex)
+            .map((a) => String(a.asset_id))
+        )
+      )
+      const balances: Balance[] = heldAssets.map((a) => {
+        const assetId = String(a.asset_id)
+        const price =
+          a.asset_id === collateral.assetIndex
+            ? new Big(1)
+            : spotPrices.get(assetId)
+        return {
+          categoryId: spotCategoryId,
+          asset:
+            assetRegistry.get(assetId) ??
+            lighterAsset(assetId, a.symbol, providerKey),
+          units: a.balance,
+          valueUsd:
+            price === undefined
+              ? '0'
+              : toRequiredBig(a.balance, 'balance').times(price).toFixed(),
+          ...(price === undefined ? {} : { price: price.toFixed() }),
+        }
+      })
 
       const assetCollateral = account.assets.flatMap((a) =>
         a.margin_mode === undefined
@@ -941,8 +964,8 @@ export const createLighterProvider = (
         balances,
         collateralBalances,
         positions,
-        marginUsed: totalMarginUsed.toString(),
-        unrealizedPnl: totalUnrealizedPnl.toString(),
+        marginUsed: totalMarginUsed.toFixed(),
+        unrealizedPnl: totalUnrealizedPnl.toFixed(),
         feeTier:
           limitsResult === undefined
             ? ZERO_FEE_TIER
@@ -1005,6 +1028,25 @@ 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.
+     */
+    async getAvailableToTrade(
+      params: ProviderGetAvailableToTradeParams,
+      opts?: SDKRequestOptions
+    ): Promise<AvailableToTrade | undefined> {
+      const registry = getMarketRegistry(requireClient(), providerKey)
+      await registry.sync()
+      const market = registry.require(params.marketId)
+      if (market.categoryId === LIGHTER_SPOT_CATEGORY_ID) {
+        return undefined
+      }
+      const account = await plugin.getAccount({ address: params.address }, opts)
+      const { availableMargin } = getAccountSummary(account, account.positions)
+      return lighterAvailableToTrade(market, availableMargin, account.positions)
+    },
+
     /**
      * 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
@@ -1603,7 +1645,7 @@ export const createLighterProvider = (
 
     estimateLiquidationPrice,
 
-    positionMarginConstraints,
+    positionRemovableMargin,
 
     projectConfig(
       config: AccountConfig,
@@ -1675,6 +1717,7 @@ export const createLighterProvider = (
       )
     },
   }
+  return plugin
 }
 
 /**

package/src/accountSummary.ts

@@ -7,23 +7,29 @@ import type {
 } from '@lifi/perps-types'
 import { PerpsErrorCode } from '@lifi/perps-types'
 import Big from 'big.js'
+import { LIGHTER_PROVIDER_KEY, LIGHTER_RH_PROVIDER_KEY } from './constants.js'
 import { toRequiredBig } from './utils/decimal.js'
 
 const lighterConfig = (account: AccountResponse): LighterAccountConfig => {
-  if (account.config.provider !== 'lighter') {
+  const { config } = account
+  if (
+    config.provider !== LIGHTER_PROVIDER_KEY &&
+    config.provider !== LIGHTER_RH_PROVIDER_KEY
+  ) {
     throw new PerpsError(
       PerpsErrorCode.SDKError,
-      `Lighter account summary received a '${account.config.provider}' account config`
+      `Lighter account summary received a '${config.provider}' account config`
     )
   }
-  return account.config
+  return config
 }
 
 /**
- * Roll a Lighter account up into an {@link AccountSummary}, from the venue
- * figures the response carries. `totalAssetValue` is total equity and
- * `availableBalance` is buying power, so neither needs reconciling against the
- * positions; the positions supply only the margin and PnL breakdown.
+ * 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` row
+ * is buying power already inside `totalAssetValue`. The positions supply only
+ * the margin and PnL breakdown.
  *
  * @throws {PerpsError} `SDKError` when the account is not a Lighter one.
  * @public
@@ -41,18 +47,20 @@ 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 {
-    // `total_asset_value` already covers every asset the venue prices, so the
-    // spot `balances` rows must not be added on top of it.
-    portfolioValue: toRequiredBig(
-      config.totalAssetValue,
-      'totalAssetValue'
-    ).toString(),
+    portfolioValue: portfolioValue.toFixed(),
     availableMargin: toRequiredBig(
       config.availableBalance,
       'availableBalance'
-    ).toString(),
-    marginUsed: marginUsed.toString(),
-    unrealizedPnl: unrealizedPnl.toString(),
+    ).toFixed(),
+    marginUsed: marginUsed.toFixed(),
+    unrealizedPnl: unrealizedPnl.toFixed(),
   }
 }

package/src/availableToTrade.ts

@@ -0,0 +1,61 @@
+import { toAssetDisplay } from '@lifi/perps-sdk'
+import type { AvailableToTrade, Market, Position } from '@lifi/perps-types'
+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)
+
+// 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.
+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')
+  )
+  const imr = toRequiredBig(
+    position.initialMarginRequirement,
+    'initialMarginRequirement'
+  )
+  return equity.lt(imr) ? equity : imr
+}
+
+/**
+ * The amounts the account can still buy and sell on one Lighter perps
+ * market. The side that adds to an open position on `market` gets
+ * `availableMargin`. The side that reduces or flips it gets the position's
+ * initial margin requirement, which the closing part of the order consumes,
+ * 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}.
+ * @throws {PerpsError} `SDKError` when a decimal the formula reads is malformed.
+ * @internal
+ */
+export const lighterAvailableToTrade = (
+  market: Market,
+  availableMargin: string,
+  positions: readonly Position[]
+): AvailableToTrade => {
+  const available = toRequiredBig(availableMargin, 'availableMargin')
+  const adding = atLeastZero(available)
+  const position = positions.find((p) => p.market.id === market.id)
+  const reducing =
+    position === undefined
+      ? adding
+      : toRequiredBig(
+          position.initialMarginRequirement,
+          'initialMarginRequirement'
+        ).plus(atLeastZero(available.plus(releasedOnClose(position))))
+  const isShort = position?.side === PositionSide.SHORT
+  return {
+    providerId: market.providerId,
+    marketId: market.id,
+    asset: toAssetDisplay(market.quoteAsset),
+    buy: (isShort ? reducing : adding).toFixed(),
+    sell: (isShort ? adding : reducing).toFixed(),
+  }
+}

package/src/utils/index.ts

@@ -23,7 +23,7 @@ export { mapMarketOrderLimits } from './marketLimits.js'
 export { mapInterval } from './ohlcvInterval.js'
 export { formatOrderPrice, formatOrderSize } from './orderFormatting.js'
 export { toIsoFromMs, toIsoFromSeconds } from './time.js'
-export { positionMarginConstraints } from './transferMargin.js'
+export { positionRemovableMargin } from './transferMargin.js'
 export {
   leverageToFraction,
   mapOrderTypeToInt,

package/src/utils/mapOrder.ts

@@ -61,9 +61,10 @@ const mapOrderStatus = (
   filledSize = new Big(order.filled_base_amount)
 ): OrderStatus => {
   switch (order.status) {
-    case 'pending':
     case 'in-progress':
       return OrderStatus.ACCEPTED
+    case 'pending':
+      return OrderStatus.OPEN
     case 'open':
       if (order.trigger_status === 'parent-order') {
         return OrderStatus.PENDING

package/src/utils/spotPrice.ts

@@ -0,0 +1,39 @@
+import type { Market, MarketContext } from '@lifi/perps-types'
+import type Big from 'big.js'
+import { toRequiredBig } from './decimal.js'
+
+/**
+ * Unit prices keyed by spot base `Asset.id` (the venue `asset_id`), read from
+ * each spot market's `markPrice` for the base assets in `assetIds` only. A
+ * market without a context row or with a non-positive mark adds no entry; when
+ * several spot markets share a base asset, the first priced one in `markets`
+ * order wins. The mark is read as a USD price; `quoteAsset` is not checked.
+ *
+ * @throws {PerpsError} `SDKError` when a context row for a requested asset
+ * carries a non-decimal mark.
+ */
+export const spotPriceByAssetId = (
+  markets: readonly Market[],
+  spotCategoryId: string,
+  contexts: readonly MarketContext[],
+  assetIds: ReadonlySet<string>
+): Map<string, Big> => {
+  const markByMarketId = new Map(contexts.map((c) => [c.marketId, c.markPrice]))
+  const priceByAssetId = new Map<string, Big>()
+  for (const market of markets) {
+    const mark = markByMarketId.get(market.id)
+    if (
+      market.categoryId !== spotCategoryId ||
+      mark === undefined ||
+      !assetIds.has(market.baseAsset.id) ||
+      priceByAssetId.has(market.baseAsset.id)
+    ) {
+      continue
+    }
+    const price = toRequiredBig(mark, 'markPrice')
+    if (price.gt(0)) {
+      priceByAssetId.set(market.baseAsset.id, price)
+    }
+  }
+  return priceByAssetId
+}

package/src/utils/transferMargin.ts

@@ -1,31 +1,69 @@
+import { PerpsError } from '@lifi/perps-sdk'
 import {
+  PerpsErrorCode,
   type Position,
-  type PositionMarginConstraints,
   positionSupportsMarginAdjustment,
+  positionSupportsMarginRemoval,
 } from '@lifi/perps-types'
-import { toPositiveRequiredBig } from './decimal.js'
+import Big from 'big.js'
 
-const AMOUNT_INCREMENT = '0.000001'
+const AMOUNT_DECIMALS = 6
+
+function positionAmount(value: string, field: string): Big {
+  try {
+    return new Big(value)
+  } catch {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `Invalid decimal string on Position.${field}: '${value}'`
+    )
+  }
+}
+
+function positivePositionAmount(value: string, field: string): Big {
+  const amount = positionAmount(value, field)
+  if (amount.lte(0)) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `Position.${field} must be greater than zero.`
+    )
+  }
+  return amount
+}
 
 /**
- * Lighter's exact isolated-margin requirement. Lighter publishes no separate
- * notional floor, so the provider-normalized initial-margin requirement is
- * the retained amount.
+ * Lighter removable isolated margin:
+ * `allocated_margin + unrealized PnL − initial margin requirement`. Lighter
+ * `allocated_margin` (`Position.marginUsed`) excludes the unrealized PnL, and
+ * Lighter publishes no separate notional floor.
  *
+ * @returns `undefined` for cross positions and markets without individual
+ *   margin adjustment; `'0'` for add-only markets and when nothing is
+ *   removable.
+ * @throws {PerpsError} `ValidationError` when a required `Position` decimal
+ *   is malformed or not positive.
  * @see https://docs.lighter.xyz/trading/liquidations-and-llp-insurance-fund
  * @public
  */
-export function positionMarginConstraints(
+export function positionRemovableMargin(
   position: Position
-): PositionMarginConstraints | undefined {
+): string | undefined {
   if (!positionSupportsMarginAdjustment(position)) {
     return undefined
   }
-  return {
-    minimumMarginRequirement: toPositiveRequiredBig(
-      position.initialMarginRequirement,
-      'initialMarginRequirement'
-    ).toFixed(),
-    amountIncrement: AMOUNT_INCREMENT,
+  if (!positionSupportsMarginRemoval(position)) {
+    return '0'
+  }
+  const removable = positivePositionAmount(position.marginUsed, 'marginUsed')
+    .plus(positionAmount(position.unrealizedPnl, 'unrealizedPnl'))
+    .minus(
+      positivePositionAmount(
+        position.initialMarginRequirement,
+        'initialMarginRequirement'
+      )
+    )
+  if (removable.lte(0)) {
+    return '0'
   }
+  return removable.round(AMOUNT_DECIMALS, Big.roundDown).toFixed()
 }

package/src/websocket/LighterWsProvider.ts

@@ -660,10 +660,10 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
     this.emit(`accountSummary:${address}`, {
       channel: 'accountSummary',
       data: {
-        portfolioValue: portfolio.toString(),
-        availableMargin: available.toString(),
-        marginUsed: marginUsed.toString(),
-        unrealizedPnl: portfolio.minus(collateral).toString(),
+        portfolioValue: portfolio.toFixed(),
+        availableMargin: available.toFixed(),
+        marginUsed: marginUsed.toFixed(),
+        unrealizedPnl: portfolio.minus(collateral).toFixed(),
       },
     })
   }
@@ -1008,5 +1008,5 @@ export const lighterWsProvider = (
   Object.assign(
     ({ provider, wsUrl, client }: WsProviderFactoryParams) =>
       new LighterWsProvider(wsUrl, provider, options, client),
-    { streamsCandles: false }
+    { streamsCandles: false, streamsAvailableToTrade: false }
   )