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

package/src/accountSummary.ts

@@ -1,53 +1,57 @@
+import { PerpsError } from '@lifi/perps-sdk'
 import type {
   AccountResponse,
   AccountSummary,
+  LighterAccountConfig,
   Position,
 } from '@lifi/perps-types'
-import { MarginMode } from '@lifi/perps-types'
+import { PerpsErrorCode } from '@lifi/perps-types'
 import Big from 'big.js'
+import { toRequiredBig } from './utils/decimal.js'
+
+const lighterConfig = (account: AccountResponse): LighterAccountConfig => {
+  if (account.config.provider !== 'lighter') {
+    throw new PerpsError(
+      PerpsErrorCode.SDKError,
+      `Lighter account summary received a '${account.config.provider}' account config`
+    )
+  }
+  return account.config
+}
 
 /**
- * Roll a Lighter {@link AccountResponse} up into an {@link AccountSummary}.
- *
- * Lighter's cross available balance is already marked to market, while an
- * isolated position's unrealized PnL remains inside that position's isolated
- * sub-account. Reconciliation therefore adds every position's locked margin,
- * but adds unrealized PnL only for isolated positions.
+ * 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.
  *
+ * @throws {PerpsError} `SDKError` when the account is not a Lighter one.
  * @public
  */
 export function getAccountSummary(
   account: AccountResponse,
   positions: Position[]
 ): AccountSummary {
-  let availableMargin = new Big(0)
-  for (const balance of account.collateralBalances) {
-    availableMargin = availableMargin.plus(balance.valueUsd)
-  }
-
-  let nonCollateralValue = new Big(0)
-  for (const balance of account.balances) {
-    nonCollateralValue = nonCollateralValue.plus(balance.valueUsd)
-  }
+  const config = lighterConfig(account)
 
   let marginUsed = new Big(0)
   let unrealizedPnl = new Big(0)
-  let isolatedUnrealizedPnl = new Big(0)
   for (const position of positions) {
     marginUsed = marginUsed.plus(position.marginUsed)
     unrealizedPnl = unrealizedPnl.plus(position.unrealizedPnl)
-    if (position.marginMode === MarginMode.ISOLATED) {
-      isolatedUnrealizedPnl = isolatedUnrealizedPnl.plus(position.unrealizedPnl)
-    }
   }
 
   return {
-    portfolioValue: nonCollateralValue
-      .plus(availableMargin)
-      .plus(marginUsed)
-      .plus(isolatedUnrealizedPnl)
-      .toString(),
-    availableMargin: availableMargin.toString(),
+    // `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(),
+    availableMargin: toRequiredBig(
+      config.availableBalance,
+      'availableBalance'
+    ).toString(),
     marginUsed: marginUsed.toString(),
     unrealizedPnl: unrealizedPnl.toString(),
   }

package/src/constants.ts

@@ -1,3 +1,4 @@
+import { ExplorerChainId } from '@lifi/perps-sdk'
 import type { FeeTier, LighterProviderKey } from '@lifi/perps-types'
 import { LT_ASSET_ID_USDC } from './types/action.js'
 
@@ -114,6 +115,11 @@ export interface LighterDeployment {
    * When omitted, transfer links are not emitted for this deployment.
    */
   explorerTxBaseUrl?: string
+  /**
+   * L1 the deployment's bridge settles on. Deposit and withdrawal rows report
+   * an `l1_tx_hash` on this chain, not on the zkLighter L2.
+   */
+  bridgeChainId: ExplorerChainId
 }
 
 /**
@@ -128,6 +134,7 @@ export const LIGHTER_MAINNET_DEPLOYMENT: LighterDeployment = Object.freeze({
   signerChainId: LIGHTER_MAINNET_SIGNER_CHAIN_ID,
   collateral: LIGHTER_COLLATERAL_ASSETS[LIGHTER_PROVIDER_KEY],
   explorerTxBaseUrl: DEFAULT_LIGHTER_EXPLORER_TX_BASE_URL,
+  bridgeChainId: ExplorerChainId.ETHEREUM,
 })
 
 /**
@@ -155,9 +162,9 @@ export const LIGHTER_RH_WS_URL = 'wss://api.rh.lighter.xyz/stream'
 export const LIGHTER_RH_SIGNER_CHAIN_ID = 466324
 
 /**
- * Lighter on Robinhood chain, as served by `lighterRhProvider()`. No explorer
- * base URL: the RH zkLighter explorer is unpublished, so transfer links are
- * left unset rather than pointed at the mainnet explorer.
+ * Lighter on Robinhood chain, as served by `lighterRhProvider()`. No L2
+ * explorer base URL: the RH zkLighter explorer is unpublished, so transfer
+ * links are left unset rather than pointed at the mainnet explorer.
  *
  * @public
  */
@@ -168,6 +175,7 @@ export const LIGHTER_RH_DEPLOYMENT: LighterDeployment = Object.freeze({
   signerChainId: LIGHTER_RH_SIGNER_CHAIN_ID,
   collateral: LIGHTER_COLLATERAL_ASSETS[LIGHTER_RH_PROVIDER_KEY],
   explorerTxBaseUrl: undefined,
+  bridgeChainId: ExplorerChainId.ROBINHOOD,
 })
 
 /** @internal */

package/src/types/ws.ts

@@ -65,7 +65,7 @@ export type LtWsMarketStatsAllMessage = LtWsMessage & {
 
 /**
  * Spot market stats carry no funding/open-interest fields and address
- * markets by their spot `market_id` (2048+).
+ * markets by their `market_id`.
  * @public
  */
 export type LtWsSpotMarketStats = {

package/src/utils/mapFill.ts

@@ -12,6 +12,7 @@ import {
 } from '../constants.js'
 import type { LtTrade } from '../types/index.js'
 import { leverageFromImf } from './mapPosition.js'
+import { isPlaceholderTxHash } from './txHash.js'
 
 /**
  * Fee charged on a fill, in the market's quote asset. Lighter publishes the
@@ -156,6 +157,8 @@ export const mapFill = (
       trade.size
     ),
     createdAt: new Date(trade.timestamp).toISOString(),
-    explorerLink: explorerTxUrl(ExplorerChainId.LIGHTER, trade.tx_hash),
+    explorerLink: isPlaceholderTxHash(trade.tx_hash)
+      ? undefined
+      : explorerTxUrl(ExplorerChainId.LIGHTER, trade.tx_hash),
   }
 }

package/src/utils/mapOrder.ts

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

package/src/utils/txHash.ts

@@ -0,0 +1,20 @@
+/**
+ * Trailing hex characters a Lighter placeholder `tx_hash` leaves zero. Lighter
+ * reports a 40-byte hash on every fill and transfer row, and a row that settled
+ * no transaction carries a sequence pair in the leading 16 bytes and zero in
+ * the remaining 24. A settled row fills all 40 bytes.
+ */
+const PLACEHOLDER_ZERO_SUFFIX_LENGTH = 48
+
+const ALL_ZERO = /^0+$/
+
+/**
+ * Report whether a Lighter `tx_hash` is the placeholder the venue sends for a
+ * row that settled no transaction. Such a row resolves to no explorer link.
+ *
+ * @internal
+ */
+export const isPlaceholderTxHash = (txHash: string | undefined): boolean =>
+  txHash !== undefined &&
+  txHash.length > PLACEHOLDER_ZERO_SUFFIX_LENGTH &&
+  ALL_ZERO.test(txHash.slice(-PLACEHOLDER_ZERO_SUFFIX_LENGTH))

package/src/websocket/LighterWsProvider.ts

@@ -29,6 +29,7 @@ import {
   DEFAULT_LIGHTER_WS_URL,
   LIGHTER_BASE_FEE_TIER,
   LIGHTER_PROVIDER_KEY,
+  LIGHTER_SPOT_CATEGORY_ID,
 } from '../constants.js'
 import type { LighterPerpsProvider } from '../LighterProvider.js'
 import type {
@@ -84,18 +85,19 @@ import {
 // Orderbook is stateful: the first message is a full snapshot, subsequent
 // messages are deltas where size=0 deletes a level.
 
-const LIGHTER_SPOT_MARKET_ID_OFFSET = 2048
-
 const LIGHTER_AUTH_CHANNEL = {
   orderUpdates: 'account_all_orders',
   fills: 'account_all_trades',
   positions: 'account_all_positions',
 } as const
 
-/** Channels whose handlers resolve market identity from the registry. */
+/** Channels whose wire name or handler reads market identity from the registry. */
 function channelNeedsMarkets(channel: Subscription['channel']): boolean {
   return (
-    channel === 'orderUpdates' || channel === 'fills' || channel === 'positions'
+    channel === 'marketContext' ||
+    channel === 'orderUpdates' ||
+    channel === 'fills' ||
+    channel === 'positions'
   )
 }
 
@@ -258,10 +260,10 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
   }
 
   protected async openChannel(sub: Subscription): Promise<() => void> {
-    // Only the auth channels (orders/fills/positions) resolve markets.
-    // `marketsContext`/`orderbook` are keyed purely by `String(market_id)`, so
-    // gating them on the registry sync would let a failed `/markets` fetch kill
-    // live price ticks.
+    // `marketsContext` resolves to two fixed `/all` channels and `orderbook` is
+    // keyed purely by `String(market_id)`, so neither needs the registry;
+    // gating them on the sync would let a failed `/markets` fetch kill live
+    // price ticks.
     if (channelNeedsMarkets(sub.channel)) {
       await this.registry?.sync()
     }
@@ -372,6 +374,7 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
         return `accountSummary:${sub.address.toLowerCase()}`
       case 'candle':
       case 'spotBalances':
+      case 'availableToTrade':
         throw new Error(`Lighter WS does not support channel: ${sub.channel}.`)
     }
   }
@@ -393,18 +396,21 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
       ]
     }
     if (sub.channel === 'marketContext') {
-      const id = Number(sub.marketId)
-      if (!Number.isFinite(id)) {
-        throw new Error(
-          `Lighter WS: unknown market for marketId '${sub.marketId}'. ` +
-            'MarketId must be a numeric market_id string.'
+      // Lighter market ids carry no type information, so the wire channel comes
+      // from the registry row's category, not from the numeric id.
+      if (this.registry === undefined) {
+        throw new PerpsError(
+          PerpsErrorCode.MarketNotFound,
+          `Lighter WS: no market registry for marketId '${sub.marketId}'. ` +
+            'Construct via `lighterWsProvider({...})` and register with PerpsWsClient.'
         )
       }
+      const market = this.registry.require(sub.marketId)
       const prefix =
-        id >= LIGHTER_SPOT_MARKET_ID_OFFSET
+        market.categoryId === LIGHTER_SPOT_CATEGORY_ID
           ? 'spot_market_stats'
           : 'market_stats'
-      return [{ channel: `${prefix}/${id}`, needsAuth: false }]
+      return [{ channel: `${prefix}/${market.id}`, needsAuth: false }]
     }
     if (sub.channel === 'orderbook') {
       const id = Number(sub.marketId)