@lifi/perps-sdk-provider-lighter 4.0.1 → 5.1.0

package/src/LighterProvider.ts

@@ -1,6 +1,5 @@
 import {
-  ExplorerChainId,
-  explorerTxUrl,
+  explorerTxUrlFromBase,
   getAssetRegistry,
   getMarketRegistry,
   getProviders,
@@ -31,6 +30,7 @@ import type {
   Balance,
   FillsResponse,
   LighterAccountConfig,
+  LighterProviderKey,
   Order,
   OrdersResponse,
   Position,
@@ -46,6 +46,7 @@ import { projectLighterConfigSettings } from './accountConfig.js'
 import { getAccountSummary } from './accountSummary.js'
 import {
   DEFAULT_API_KEY_INDEX,
+  DEFAULT_LIGHTER_EXPLORER_TX_BASE_URL,
   DEFAULT_LIGHTER_REST_URL,
   DEFAULT_TRADES_LIMIT,
   LIGHTER_ALL_MARKETS_WILDCARD,
@@ -177,8 +178,22 @@ const normalizeLighterPublicKey = (key: string): string =>
  * @public
  */
 export interface LighterProviderOptions {
+  /**
+   * Provider key: the plugin `type`, the `Provider.key` matched against the
+   * backend `/providers` response, and the namespace for this instance's market
+   * / asset registries and retry policy. Defaults to `'lighter'` (mainnet).
+   * Set a distinct key (e.g. `'lighter-rh'`) to register a second Lighter
+   * instance on the same client.
+   */
+  providerKey?: LighterProviderKey
   /** Lighter REST base URL. Defaults to mainnet. */
   restUrl?: string
+  /**
+   * Explorer tx base URL for transfer-activity links (`${base}${txHash}`).
+   * Defaults to the mainnet Lighter explorer for the default provider key, and
+   * to `undefined` (no transfer links) for any other key unless supplied.
+   */
+  explorerTxBaseUrl?: string
   /** Pre-created Lighter read-only bearer. */
   authToken?: string | (() => string | Promise<string>)
   /**
@@ -277,7 +292,13 @@ export const lighterProvider = (
     return boundClient
   }
 
+  const providerKey = options.providerKey ?? LIGHTER_PROVIDER_KEY
   const restUrl = options.restUrl ?? DEFAULT_LIGHTER_REST_URL
+  const explorerTxBaseUrl =
+    options.explorerTxBaseUrl ??
+    (providerKey === LIGHTER_PROVIDER_KEY
+      ? DEFAULT_LIGHTER_EXPLORER_TX_BASE_URL
+      : undefined)
   const authTokenSource: (() => string | Promise<string>) | undefined =
     typeof options.authToken === 'function'
       ? options.authToken
@@ -287,6 +308,7 @@ export const lighterProvider = (
   const signer = options.signer
   const keyStore = options.keyStore
   const readOnlyTokenManager = new LighterReadOnlyTokenManager({
+    providerKey,
     lighterApiUrl: restUrl,
     ...options.readOnlyTokenOptions,
   })
@@ -309,7 +331,7 @@ export const lighterProvider = (
       policy: resolveRetryPolicy(
         LIGHTER_RETRY_DEFAULTS,
         client.config.retry,
-        LIGHTER_PROVIDER_KEY
+        providerKey
       ),
       fetchImpl: client.config.fetch,
     })
@@ -644,7 +666,9 @@ export const lighterProvider = (
   }
 
   return {
-    type: LIGHTER_PROVIDER_KEY,
+    type: providerKey,
+
+    internalSetupActions: [ActionType.SET_REFERRAL],
 
     bind(client: PerpsSDKClient): void {
       boundClient = client
@@ -664,11 +688,8 @@ export const lighterProvider = (
         resolveAuthToken(opts, params.address),
       ])
 
-      const registry = getMarketRegistry(requireClient(), LIGHTER_PROVIDER_KEY)
-      const assetRegistry = getAssetRegistry(
-        requireClient(),
-        LIGHTER_PROVIDER_KEY
-      )
+      const registry = getMarketRegistry(requireClient(), providerKey)
+      const assetRegistry = getAssetRegistry(requireClient(), providerKey)
       const [
         { providers },
         ,
@@ -725,7 +746,7 @@ export const lighterProvider = (
       )
 
       const categories =
-        providers.find((p) => p.key === LIGHTER_PROVIDER_KEY)?.categories ?? []
+        providers.find((p) => p.key === providerKey)?.categories ?? []
       const perpsCategory = categories.find((c) => c.quoteAsset !== null)
       const spotCategoryId =
         categories.find((c) => c.quoteAsset === null)?.id ??
@@ -737,7 +758,7 @@ export const lighterProvider = (
       // carried by the positions' `marginUsed`.
       const collateralBalances: Balance[] = [
         {
-          categoryId: perpsCategory?.id ?? LIGHTER_PROVIDER_KEY,
+          categoryId: perpsCategory?.id ?? providerKey,
           asset: perpsCategory?.quoteAsset ?? lighterAsset('USDC', 'USDC'),
           units: account.available_balance,
           valueUsd: account.available_balance,
@@ -767,7 +788,7 @@ export const lighterProvider = (
       )
 
       const config: LighterAccountConfig = {
-        provider: LIGHTER_PROVIDER_KEY,
+        provider: providerKey,
         accountIndex: account.index,
         apiKeyIndex: DEFAULT_API_KEY_INDEX,
         apiKeyRegistered,
@@ -785,7 +806,7 @@ export const lighterProvider = (
       }
 
       return {
-        provider: LIGHTER_PROVIDER_KEY,
+        provider: providerKey,
         address: params.address,
         balances,
         collateralBalances,
@@ -823,7 +844,7 @@ export const lighterProvider = (
       opts?: SDKRequestOptions
     ): Promise<PositionsResponse> {
       const client = apiClient(opts)
-      const registry = getMarketRegistry(requireClient(), LIGHTER_PROVIDER_KEY)
+      const registry = getMarketRegistry(requireClient(), providerKey)
       const [account] = await Promise.all([
         fetchDetailedAccount(client, params.address),
         registry.sync(),
@@ -838,7 +859,7 @@ export const lighterProvider = (
       }
 
       return {
-        provider: LIGHTER_PROVIDER_KEY,
+        provider: providerKey,
         positions,
         pagination: { limit: params.limit ?? positions.length, hasMore: false },
       }
@@ -857,7 +878,7 @@ export const lighterProvider = (
       const token = await resolveAuthToken(opts, params.address)
       if (token === undefined) {
         return {
-          provider: LIGHTER_PROVIDER_KEY,
+          provider: providerKey,
           openOrders: [],
           triggerOrders: [],
           pagination: { limit: params.limit ?? 0, hasMore: false },
@@ -865,7 +886,7 @@ export const lighterProvider = (
       }
 
       const client = apiClient(opts)
-      const registry = getMarketRegistry(requireClient(), LIGHTER_PROVIDER_KEY)
+      const registry = getMarketRegistry(requireClient(), providerKey)
       const [account] = await Promise.all([
         fetchDetailedAccount(client, params.address),
         registry.sync(),
@@ -891,7 +912,7 @@ export const lighterProvider = (
 
       const total = openOrders.length + triggerOrders.length
       return {
-        provider: LIGHTER_PROVIDER_KEY,
+        provider: providerKey,
         openOrders,
         triggerOrders,
         pagination: { limit: total, hasMore: false },
@@ -913,7 +934,7 @@ export const lighterProvider = (
       }
 
       const client = apiClient(opts)
-      const registry = getMarketRegistry(requireClient(), LIGHTER_PROVIDER_KEY)
+      const registry = getMarketRegistry(requireClient(), providerKey)
       const [account] = await Promise.all([
         fetchDetailedAccount(client, params.address),
         registry.sync(),
@@ -981,14 +1002,14 @@ export const lighterProvider = (
       const token = await resolveAuthToken(opts, params.address)
       if (token === undefined) {
         return {
-          provider: LIGHTER_PROVIDER_KEY,
+          provider: providerKey,
           items: [],
           pagination: { limit: params.limit ?? 0, hasMore: false },
         }
       }
 
       const client = apiClient(opts)
-      const registry = getMarketRegistry(requireClient(), LIGHTER_PROVIDER_KEY)
+      const registry = getMarketRegistry(requireClient(), providerKey)
       const [account] = await Promise.all([
         fetchDetailedAccount(client, params.address),
         registry.sync(),
@@ -1017,7 +1038,7 @@ export const lighterProvider = (
       )
 
       return {
-        provider: LIGHTER_PROVIDER_KEY,
+        provider: providerKey,
         items,
         pagination: {
           limit: params.limit ?? items.length,
@@ -1034,7 +1055,7 @@ export const lighterProvider = (
       const token = await resolveAuthToken(opts, params.address)
       if (token === undefined) {
         return {
-          provider: LIGHTER_PROVIDER_KEY,
+          provider: providerKey,
           items: [],
           pagination: { limit: params.limit ?? 0, hasMore: false },
         }
@@ -1043,14 +1064,8 @@ export const lighterProvider = (
       const inputCursor = decodeActivityCursor(params.cursor)
       const client = apiClient(opts)
       const account = await fetchDetailedAccount(client, params.address)
-      const marketRegistry = getMarketRegistry(
-        requireClient(),
-        LIGHTER_PROVIDER_KEY
-      )
-      const assetRegistry = getAssetRegistry(
-        requireClient(),
-        LIGHTER_PROVIDER_KEY
-      )
+      const marketRegistry = getMarketRegistry(requireClient(), providerKey)
+      const assetRegistry = getAssetRegistry(requireClient(), providerKey)
       const [history] = await Promise.all([
         retryOnRevoked(opts, params.address, token, (t) =>
           fetchAllHistory(
@@ -1070,7 +1085,7 @@ export const lighterProvider = (
         ...history.deposits.deposits.map(
           (d): ActivityItem => ({
             id: d.id,
-            provider: LIGHTER_PROVIDER_KEY,
+            provider: providerKey,
             timestamp: toIsoFromMs(d.timestamp),
             type: ActivityType.DEPOSIT,
             amount: d.amount,
@@ -1082,7 +1097,7 @@ export const lighterProvider = (
         ...history.withdraws.withdraws.map(
           (w): ActivityItem => ({
             id: w.id,
-            provider: LIGHTER_PROVIDER_KEY,
+            provider: providerKey,
             timestamp: toIsoFromMs(w.timestamp),
             type: ActivityType.WITHDRAWAL,
             amount: w.amount,
@@ -1095,7 +1110,7 @@ export const lighterProvider = (
         ...history.fundings.position_fundings.map(
           (f): ActivityItem => ({
             id: `funding-${f.funding_id}`,
-            provider: LIGHTER_PROVIDER_KEY,
+            provider: providerKey,
             timestamp: toIsoFromSeconds(f.timestamp),
             type: ActivityType.FUNDING,
             market: marketRegistry.require(String(f.market_id)),
@@ -1107,7 +1122,7 @@ export const lighterProvider = (
         ...history.liquidations.liquidations.map(
           (l): ActivityItem => ({
             id: `liquidation-${l.id}`,
-            provider: LIGHTER_PROVIDER_KEY,
+            provider: providerKey,
             timestamp: toIsoFromMs(l.executed_at),
             type: ActivityType.LIQUIDATION,
             liquidatedNotionalPosition: '0',
@@ -1128,7 +1143,7 @@ export const lighterProvider = (
             direction === 'OUT' ? t.to_account_index : t.from_account_index
           return {
             id: t.id,
-            provider: LIGHTER_PROVIDER_KEY,
+            provider: providerKey,
             timestamp: toIsoFromMs(t.timestamp),
             type: ActivityType.TRANSFER,
             direction,
@@ -1137,7 +1152,7 @@ export const lighterProvider = (
               assetRegistry.get(String(t.asset_id))?.displaySymbol ??
               String(t.asset_id),
             amount: t.amount,
-            explorerLink: explorerTxUrl(ExplorerChainId.LIGHTER, t.tx_hash),
+            explorerLink: explorerTxUrlFromBase(explorerTxBaseUrl, t.tx_hash),
             meta: {
               transferType: t.type,
               txHash: t.tx_hash,
@@ -1183,7 +1198,7 @@ export const lighterProvider = (
       const hasMore = responseCursor !== undefined
 
       return {
-        provider: LIGHTER_PROVIDER_KEY,
+        provider: providerKey,
         items: emitted,
         pagination: {
           limit,
@@ -1199,7 +1214,7 @@ export const lighterProvider = (
     ): Promise<Quote> {
       return resolveQuote(
         requireClient(),
-        LIGHTER_PROVIDER_KEY,
+        providerKey,
         params,
         LIGHTER_BASE_FEE_TIER,
         opts
@@ -1224,7 +1239,7 @@ export const lighterProvider = (
       setup: ProviderAction[],
       options: ProviderAction[]
     ): AccountConfigSetting[] {
-      if (config.provider !== LIGHTER_PROVIDER_KEY) {
+      if (config.provider !== providerKey) {
         throw new PerpsError(
           PerpsErrorCode.SDKError,
           `lighterProvider.projectConfig received config for provider ` +

package/src/constants.ts

@@ -1,4 +1,4 @@
-import type { FeeTier } from '@lifi/perps-types'
+import type { FeeTier, LighterProviderKey } from '@lifi/perps-types'
 
 /**
  * Lighter provider key as it appears on `Provider.key` from the backend.
@@ -24,6 +24,109 @@ export const LIGHTER_SPOT_CATEGORY_ID = 'spot'
 export const DEFAULT_LIGHTER_REST_URL = 'https://mainnet.zklighter.elliot.ai'
 export const DEFAULT_LIGHTER_WS_URL = 'wss://mainnet.zklighter.elliot.ai/stream'
 
+/**
+ * zkLighter L2 signing chain id fed to {@link LighterSigner} on mainnet.
+ *
+ * @public
+ */
+export const DEFAULT_LIGHTER_SIGNER_CHAIN_ID = 304
+
+/**
+ * Base URL the mainnet Lighter zkLighter explorer resolves a tx hash against
+ * (`${base}${txHash}`).
+ *
+ * @public
+ */
+export const DEFAULT_LIGHTER_EXPLORER_TX_BASE_URL =
+  'https://app.lighter.xyz/explorer/logs/'
+
+/**
+ * The venue-specific facts that distinguish one Lighter deployment from
+ * another. One provider + WS pair is built per instance from these; a client
+ * may register several so long as their `providerKey`s differ.
+ *
+ * @public
+ */
+export interface LighterInstanceConfig {
+  /** Wire-visible `Provider.key` and the plugin `type`; unique per instance. */
+  providerKey: LighterProviderKey
+  restUrl: string
+  wsUrl: string
+  /**
+   * zkLighter L2 signing chain id to construct this instance's
+   * {@link LighterSigner} with.
+   */
+  signerChainId: number
+  /**
+   * Explorer tx base URL for transfer-activity links (`${base}${txHash}`).
+   * When omitted, transfer links are not emitted for this instance.
+   */
+  explorerTxBaseUrl?: string
+}
+
+/**
+ * The built-in mainnet Lighter instance — the defaults `lighterProvider()` and
+ * `lighterWsProvider()` apply when constructed with no instance overrides.
+ *
+ * @public
+ */
+export const LIGHTER_MAINNET_INSTANCE: LighterInstanceConfig = {
+  providerKey: LIGHTER_PROVIDER_KEY,
+  restUrl: DEFAULT_LIGHTER_REST_URL,
+  wsUrl: DEFAULT_LIGHTER_WS_URL,
+  signerChainId: DEFAULT_LIGHTER_SIGNER_CHAIN_ID,
+  explorerTxBaseUrl: DEFAULT_LIGHTER_EXPLORER_TX_BASE_URL,
+}
+
+/**
+ * Provider key for the Lighter instance running on Robinhood chain.
+ *
+ * @public
+ */
+export const LIGHTER_RH_PROVIDER_KEY = 'lighter-rh'
+
+/** @public */
+export const LIGHTER_RH_REST_URL = 'https://api.rh.lighter.xyz'
+/** @public */
+export const LIGHTER_RH_WS_URL = 'wss://api.rh.lighter.xyz/stream'
+
+/**
+ * Deployment-supplied facts the RH instance cannot source from public
+ * documentation and the caller must confirm.
+ *
+ * @public
+ */
+export interface LighterRhInstanceOverrides {
+  /**
+   * zkLighter L2 signing chain id for the RH instance. Unverified from public
+   * sources — must be the value confirmed against lighter-go / RH support, not
+   * mainnet's 304 nor the RH L1 chain id 4663.
+   */
+  signerChainId: number
+  /**
+   * RH zkLighter explorer tx base URL. Omit until confirmed; transfer links are
+   * then left unset rather than pointed at the mainnet explorer.
+   */
+  explorerTxBaseUrl?: string
+}
+
+/**
+ * Build the `lighter-rh` {@link LighterInstanceConfig}. The signing chain id is
+ * a required argument because it is not verifiable from public sources — the
+ * caller must pass the value confirmed against lighter-go / RH support.
+ *
+ * @public
+ */
+export const lighterRhInstance = (
+  overrides: LighterRhInstanceOverrides
+): LighterInstanceConfig => ({
+  providerKey: LIGHTER_RH_PROVIDER_KEY,
+  restUrl: LIGHTER_RH_REST_URL,
+  wsUrl: LIGHTER_RH_WS_URL,
+  signerChainId: overrides.signerChainId,
+  explorerTxBaseUrl: overrides.explorerTxBaseUrl,
+})
+
 /** @internal */
 export const DEFAULT_TRADES_LIMIT = 50
 

package/src/index.ts

@@ -15,11 +15,23 @@
 
 export { projectLighterConfigSettings } from './accountConfig.js'
 export { getAccountSummary } from './accountSummary.js'
+export type {
+  LighterInstanceConfig,
+  LighterRhInstanceOverrides,
+} from './constants.js'
 export {
   DEFAULT_API_KEY_INDEX,
+  DEFAULT_LIGHTER_EXPLORER_TX_BASE_URL,
   DEFAULT_LIGHTER_REST_URL,
+  DEFAULT_LIGHTER_SIGNER_CHAIN_ID,
+  DEFAULT_LIGHTER_WS_URL,
+  LIGHTER_MAINNET_INSTANCE,
   LIGHTER_PROVIDER_KEY,
+  LIGHTER_RH_PROVIDER_KEY,
+  LIGHTER_RH_REST_URL,
+  LIGHTER_RH_WS_URL,
   LIGHTER_SPOT_CATEGORY_ID,
+  lighterRhInstance,
 } from './constants.js'
 export type {
   LighterPerpsProvider,

package/src/signers/LighterReadOnlyTokenManager.ts

@@ -7,12 +7,11 @@ import {
 import type {
   ApproveReadOnlyTokenParams,
   LighterAccountConfig,
+  LighterProviderKey,
 } from '@lifi/perps-types'
 import { PerpsErrorCode } from '@lifi/perps-types'
 import type { Address } from 'viem'
-import { DEFAULT_LIGHTER_REST_URL } from '../constants.js'
-
-const STORAGE_PREFIX = 'lifi:perps:lighter:rotoken'
+import { DEFAULT_LIGHTER_REST_URL, LIGHTER_PROVIDER_KEY } from '../constants.js'
 
 /**
  * Default token name persisted alongside Lighter's `tokens/create` row.
@@ -73,6 +72,13 @@ export type LighterTokenFetcher = (params: {
 /** @public */
 export interface LighterReadOnlyTokenManagerOptions {
   storage?: StorageAdapter
+  /**
+   * Provider instance key. Namespaces persisted tokens so two Lighter
+   * instances sharing a storage backend never serve each other's token for a
+   * coincident `(address, accountIndex)` pair, and stamps the `provider` of
+   * the {@link ApproveReadOnlyTokenResult} config. Defaults to `'lighter'`.
+   */
+  providerKey?: LighterProviderKey
   /** Lighter API host. Defaults to {@link DEFAULT_LIGHTER_REST_URL}. */
   lighterApiUrl?: string
   /** Override the multipart POST. Defaults to a `fetch`-based implementation. */
@@ -145,6 +151,7 @@ const isLighterReadOnlyToken = (
  */
 export class LighterReadOnlyTokenManager {
   private readonly storage: StorageAdapter
+  private readonly providerKey: LighterProviderKey
   private readonly lighterApiUrl: string
   private readonly fetcher: LighterTokenFetcher
   private readonly now: () => number
@@ -152,13 +159,14 @@ export class LighterReadOnlyTokenManager {
 
   constructor(options: LighterReadOnlyTokenManagerOptions = {}) {
     this.storage = options.storage ?? localStorageAdapter
+    this.providerKey = options.providerKey ?? LIGHTER_PROVIDER_KEY
     this.lighterApiUrl = options.lighterApiUrl ?? DEFAULT_LIGHTER_REST_URL
     this.fetcher = options.fetcher ?? defaultLighterTokenFetcher
     this.now = options.now ?? (() => Date.now())
   }
 
   private storageKey(address: Address, accountIndex: number): string {
-    return `${STORAGE_PREFIX}:${address.toLowerCase()}:${accountIndex}`
+    return `lifi:perps:${this.providerKey}:rotoken:${address.toLowerCase()}:${accountIndex}`
   }
 
   private isExpired(token: LighterReadOnlyToken): boolean {
@@ -291,7 +299,7 @@ export class LighterReadOnlyTokenManager {
     return {
       token,
       config: {
-        provider: 'lighter',
+        provider: this.providerKey,
         accountIndex: token.accountIndex,
         readOnlyTokenApproved: true,
         readOnlyTokenExpiry: token.expiry,

package/src/signers/LighterSigner.ts

@@ -1,5 +1,8 @@
 import { ActionType } from '@lifi/perps-types'
-import { DEFAULT_LIGHTER_REST_URL } from '../constants.js'
+import {
+  DEFAULT_LIGHTER_REST_URL,
+  DEFAULT_LIGHTER_SIGNER_CHAIN_ID,
+} from '../constants.js'
 import {
   LT_ASSET_ID_USDC,
   LT_ROUTE_PERP,
@@ -61,8 +64,6 @@ export interface ApiKeyPair {
   privateKey: string
 }
 
-const DEFAULT_CHAIN_ID = 304
-
 // Signing "unset" sentinels mirror lighter-go `types/txtypes/constants.go`.
 // Passing them yields an empty `L2TxAttributes` — no integrator fees, default
 // self-trade rules.
@@ -103,7 +104,7 @@ export class LighterSigner {
 
   constructor(config: LighterSignerConfig = {}) {
     this.apiUrl = config.apiUrl ?? DEFAULT_LIGHTER_REST_URL
-    this.chainId = config.chainId ?? DEFAULT_CHAIN_ID
+    this.chainId = config.chainId ?? DEFAULT_LIGHTER_SIGNER_CHAIN_ID
     this.loaderOptions = {
       wasmBinaryUrl: config.wasmBinaryUrl,
       wasmExecJsUrl: config.wasmExecJsUrl,

package/src/websocket/LighterWsProvider.ts

@@ -185,7 +185,7 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
 
   constructor(
     wsUrl: string = DEFAULT_LIGHTER_WS_URL,
-    providerKey = 'lighter',
+    providerKey: string = LIGHTER_PROVIDER_KEY,
     options: LighterWsProviderOptions = {},
     client?: PerpsSDKClient
   ) {
@@ -199,7 +199,7 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
         policy: resolveRetryPolicy(
           LIGHTER_RETRY_DEFAULTS,
           client?.config.retry,
-          LIGHTER_PROVIDER_KEY
+          providerKey
         ),
         fetchImpl: client?.config.fetch,
       }
@@ -468,19 +468,19 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
     try {
       msg = JSON.parse(raw) as LtWsMessage
     } catch {
-      wsLog.parseFailure(LIGHTER_PROVIDER_KEY, raw)
+      wsLog.parseFailure(this.providerKey, raw)
       return
     }
 
     if (!isValidLighterFrame(msg)) {
-      wsLog.parseFailure(LIGHTER_PROVIDER_KEY, raw)
+      wsLog.parseFailure(this.providerKey, raw)
       return
     }
 
     try {
       this.dispatch(msg)
     } catch (error) {
-      wsLog.handlerFailure(LIGHTER_PROVIDER_KEY, error)
+      wsLog.handlerFailure(this.providerKey, error)
     }
   }