@lifi/perps-sdk-provider-lighter 8.2.1 → 9.0.0

package/src/constants.ts

@@ -38,11 +38,12 @@ 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.
+ * zkLighter L2 signing chain id for the Lighter mainnet deployment, from
+ * `elliottech/lighter-python` v1.1.2 `lighter/endpoint_profiles.py`.
  *
  * @public
  */
-export const DEFAULT_LIGHTER_SIGNER_CHAIN_ID = 304
+export const LIGHTER_MAINNET_SIGNER_CHAIN_ID = 304
 
 /**
  * Base URL the mainnet Lighter zkLighter explorer resolves a tx hash against
@@ -78,29 +79,30 @@ export const LIGHTER_COLLATERAL_ASSETS: Record<
   LighterProviderKey,
   LighterCollateralAsset
 > = {
-  [LIGHTER_PROVIDER_KEY]: {
+  [LIGHTER_PROVIDER_KEY]: Object.freeze({
     assetIndex: LT_ASSET_ID_USDC,
     displaySymbol: 'USDC',
-  },
-  [LIGHTER_RH_PROVIDER_KEY]: { assetIndex: 3, displaySymbol: 'USDG' },
+  }),
+  [LIGHTER_RH_PROVIDER_KEY]: Object.freeze({
+    assetIndex: 3,
+    displaySymbol: 'USDG',
+  }),
 }
 
 /**
- * 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.
+ * The immutable venue facts that distinguish one Lighter deployment from
+ * another. The SDK owns one descriptor per supported deployment; consumers
+ * select a deployment by picking its provider factory, never by assembling
+ * these fields.
  *
  * @public
  */
-export interface LighterInstanceConfig {
-  /** Wire-visible `Provider.key` and the plugin `type`; unique per instance. */
+export interface LighterDeployment {
+  /** Wire-visible `Provider.key` and the plugin `type`; unique per deployment. */
   providerKey: LighterProviderKey
   restUrl: string
   wsUrl: string
-  /**
-   * zkLighter L2 signing chain id to construct this instance's
-   * {@link LighterSigner} with.
-   */
+  /** zkLighter L2 signing chain id this deployment's transactions are signed against. */
   signerChainId: number
   /**
    * Collateral asset this deployment settles in — signed into its withdrawals
@@ -109,75 +111,63 @@ export interface LighterInstanceConfig {
   collateral: LighterCollateralAsset
   /**
    * Explorer tx base URL for transfer-activity links (`${base}${txHash}`).
-   * When omitted, transfer links are not emitted for this instance.
+   * When omitted, transfer links are not emitted for this deployment.
    */
   explorerTxBaseUrl?: string
 }
 
 /**
- * The built-in mainnet Lighter instance — the defaults `lighterProvider()` and
- * `lighterWsProvider()` apply when constructed with no instance overrides.
+ * Lighter mainnet, as served by `lighterProvider()`.
  *
  * @public
  */
-export const LIGHTER_MAINNET_INSTANCE: LighterInstanceConfig = {
+export const LIGHTER_MAINNET_DEPLOYMENT: LighterDeployment = Object.freeze({
   providerKey: LIGHTER_PROVIDER_KEY,
   restUrl: DEFAULT_LIGHTER_REST_URL,
   wsUrl: DEFAULT_LIGHTER_WS_URL,
-  signerChainId: DEFAULT_LIGHTER_SIGNER_CHAIN_ID,
+  signerChainId: LIGHTER_MAINNET_SIGNER_CHAIN_ID,
   collateral: LIGHTER_COLLATERAL_ASSETS[LIGHTER_PROVIDER_KEY],
   explorerTxBaseUrl: DEFAULT_LIGHTER_EXPLORER_TX_BASE_URL,
-}
+})
 
 /**
- * Default REST base URL for the Lighter Robinhood deployment.
+ * REST base URL for the Lighter Robinhood deployment.
  *
  * @public
  */
 export const LIGHTER_RH_REST_URL = 'https://api.rh.lighter.xyz'
 /**
- * Default WebSocket URL for the Lighter Robinhood deployment.
+ * WebSocket URL for the Lighter Robinhood deployment.
  *
  * @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.
+ * zkLighter L2 signing chain id for the Lighter Robinhood deployment, from
+ * `elliottech/lighter-python` v1.1.2 `lighter/endpoint_profiles.py`
+ * (`ROBINHOOD.chain_id`) and its `signer_client.py` host fallback. Distinct
+ * from mainnet's 304 and from Robinhood's L1 chain id 4663 — signing with
+ * either yields a venue-rejected transaction.
  *
  * @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
-}
+export const LIGHTER_RH_SIGNER_CHAIN_ID = 466324
 
 /**
- * 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.
+ * 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.
  *
  * @public
  */
-export const lighterRhInstance = (
-  overrides: LighterRhInstanceOverrides
-): LighterInstanceConfig => ({
+export const LIGHTER_RH_DEPLOYMENT: LighterDeployment = Object.freeze({
   providerKey: LIGHTER_RH_PROVIDER_KEY,
   restUrl: LIGHTER_RH_REST_URL,
   wsUrl: LIGHTER_RH_WS_URL,
-  signerChainId: overrides.signerChainId,
+  signerChainId: LIGHTER_RH_SIGNER_CHAIN_ID,
   collateral: LIGHTER_COLLATERAL_ASSETS[LIGHTER_RH_PROVIDER_KEY],
-  explorerTxBaseUrl: overrides.explorerTxBaseUrl,
+  explorerTxBaseUrl: undefined,
 })
 
 /** @internal */

package/src/index.ts

@@ -5,9 +5,9 @@
  * Lighter provider plugin for `@lifi/perps-sdk`. Serves `PerpsProvider` reads
  * directly from Lighter's REST API (no LI.FI backend hop); auth-gated reads
  * use the user's Lighter read-only token. Also owns `signActions` (the
- * `WASM_BLOB` / `EVM_TX` arms of `PerpsClient.execute`) — `LighterSigner`,
- * `LighterKeyStore`, `LighterReadOnlyTokenManager`, and the WASM blob ship
- * with this package.
+ * `WASM_BLOB` / `EVM_TX` arms of `PerpsClient.execute`): each provider
+ * instance creates its own WASM signer, API-key store and read-only token
+ * manager, and the Go signer binary ships with this package.
  *
  * @packageDocumentation
  * @public
@@ -17,32 +17,35 @@ export { projectLighterConfigSettings } from './accountConfig.js'
 export { getAccountSummary } from './accountSummary.js'
 export type {
   LighterCollateralAsset,
-  LighterInstanceConfig,
-  LighterRhInstanceOverrides,
+  LighterDeployment,
 } 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_COLLATERAL_ASSETS,
-  LIGHTER_MAINNET_INSTANCE,
+  LIGHTER_MAINNET_DEPLOYMENT,
+  LIGHTER_MAINNET_SIGNER_CHAIN_ID,
   LIGHTER_PROVIDER_KEY,
+  LIGHTER_RH_DEPLOYMENT,
   LIGHTER_RH_PROVIDER_KEY,
   LIGHTER_RH_REST_URL,
+  LIGHTER_RH_SIGNER_CHAIN_ID,
   LIGHTER_RH_WS_URL,
   LIGHTER_SPOT_CATEGORY_ID,
-  lighterRhInstance,
 } from './constants.js'
 export { lighterDepositFlow } from './depositFlow.js'
 export type {
   LighterPerpsProvider,
   LighterProviderOptions,
 } from './LighterProvider.js'
-export { Lighter, lighterProvider } from './LighterProvider.js'
+export {
+  Lighter,
+  lighterProvider,
+  lighterRhProvider,
+} from './LighterProvider.js'
 
-export * from './signers/index.js'
 export * from './types/index.js'
 export * from './utils/index.js'
 export type { LighterAuthTokenResolver } from './websocket/LighterWsProvider.js'

package/src/signers/LighterSigner.ts

@@ -1,17 +1,8 @@
 import { ActionType } from '@lifi/perps-types'
-import {
-  DEFAULT_LIGHTER_REST_URL,
-  DEFAULT_LIGHTER_SIGNER_CHAIN_ID,
-} from '../constants.js'
-import {
-  LT_ASSET_ID_USDC,
-  LT_ROUTE_PERP,
-  LT_ROUTE_SPOT,
-} from '../types/action.js'
+import { LT_ROUTE_PERP, LT_ROUTE_SPOT } from '../types/action.js'
 import { assetMarginModeInt } from '../utils/assetCollateral.js'
 import {
   type LighterWasmExports,
-  type LoadLighterWasmOptions,
   loadLighterWasm,
   type SignResult,
 } from './wasmLoader.js'
@@ -38,22 +29,16 @@ export interface LighterSignerContext {
 }
 
 /**
- * Configuration for {@link LighterSigner}: optional WASM asset overrides plus
- * the per-instance REST base URL, signing chain id and collateral asset index.
+ * Deployment facts {@link LighterSigner} signs against: the venue's REST base
+ * URL, its zkLighter L2 signing chain id, and the L2 asset index its
+ * withdrawals and transfers settle in.
  *
- * @public
+ * @internal
  */
-export interface LighterSignerConfig extends LoadLighterWasmOptions {
-  /** Lighter REST API base URL. */
-  apiUrl?: string
-  /** Lighter chain ID (304 = mainnet). */
-  chainId?: number
-  /**
-   * L2 asset index this instance's withdrawals and transfers are signed
-   * against — pass the instance's `collateral.assetIndex`. Defaults to
-   * mainnet's USDC slot.
-   */
-  collateralAssetIndex?: number
+export interface LighterSignerConfig {
+  apiUrl: string
+  signerChainId: number
+  collateralAssetIndex: number
 }
 
 /**
@@ -136,25 +121,19 @@ const LIGHTER_ROUTE_BY_DEX: Record<string, number> = {
  * hybrid flows. The instance memoizes WASM initialization and registered
  * `(apiKeyIndex, accountIndex)` clients.
  *
- * @public
+ * @internal
  */
 export class LighterSigner {
   private readonly apiUrl: string
   private readonly chainId: number
   private readonly collateralAssetIndex: number
-  private readonly loaderOptions: LoadLighterWasmOptions
   private wasm: LighterWasmExports | undefined
   private readonly registeredClients = new Set<string>()
 
-  constructor(config: LighterSignerConfig = {}) {
-    this.apiUrl = config.apiUrl ?? DEFAULT_LIGHTER_REST_URL
-    this.chainId = config.chainId ?? DEFAULT_LIGHTER_SIGNER_CHAIN_ID
-    this.collateralAssetIndex = config.collateralAssetIndex ?? LT_ASSET_ID_USDC
-    this.loaderOptions = {
-      wasmBinaryUrl: config.wasmBinaryUrl,
-      wasmExecJsUrl: config.wasmExecJsUrl,
-      wasmExecJsSource: config.wasmExecJsSource,
-    }
+  constructor(config: LighterSignerConfig) {
+    this.apiUrl = config.apiUrl
+    this.chainId = config.signerChainId
+    this.collateralAssetIndex = config.collateralAssetIndex
   }
 
   /**
@@ -163,7 +142,7 @@ export class LighterSigner {
    */
   async initialize(): Promise<void> {
     if (!this.wasm) {
-      this.wasm = await loadLighterWasm(this.loaderOptions)
+      this.wasm = await loadLighterWasm()
     }
   }