@lifi/perps-sdk-provider-lighter 4.0.0 → 5.0.0

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,
@@ -49,14 +52,18 @@ export interface ChangePubKeyResult extends LighterSignedBlob {
   messageToSign: string
 }
 
+/** @public */
+export interface ApproveIntegratorResult extends LighterSignedBlob {
+  /** EIP-191 `L2ApproveIntegrator` L1 body the user's wallet must countersign to authorize the integrator approval. */
+  messageToSign: string
+}
+
 /** @public */
 export interface ApiKeyPair {
   publicKey: string
   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.
@@ -97,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,
@@ -133,8 +140,9 @@ export class LighterSigner {
    * `WasmBlobActionStep`. Returns the signed `{ txType, txInfo, txHash }`
    * triple the backend forwards to Lighter's `sendTx` endpoint.
    *
-   * For REGISTER_API_KEY use `signChangePubKey` instead — it returns an
-   * additional `messageToSign` the L1 wallet must countersign.
+   * For REGISTER_API_KEY use `signChangePubKey` and for APPROVE_INTEGRATOR
+   * use `signApproveIntegrator` instead — both return an additional
+   * `messageToSign` the L1 wallet must countersign.
    */
   async sign(
     action: ActionType,
@@ -147,6 +155,12 @@ export class LighterSigner {
           'must be coordinated by the caller.'
       )
     }
+    if (action === ActionType.APPROVE_INTEGRATOR) {
+      throw new Error(
+        'Use signApproveIntegrator() for APPROVE_INTEGRATOR — sign() does ' +
+          'not collect the required L1 user wallet signature.'
+      )
+    }
     const wasm = await this.ensureLoaded()
     await this.ensureClient(context)
     const result = this.dispatch(wasm, action, wasmSignParams, context)
@@ -211,10 +225,51 @@ export class LighterSigner {
   }
 
   /**
-   * Step 2 of REGISTER_API_KEY — inject the L1 signature produced by the
-   * user's Ethereum wallet into the ChangePubKey txInfo JSON. `L1Sig` is the
-   * only field in txInfo that depends on the L1 signature; txHash does NOT
-   * include it (so we do not recompute it).
+   * Sign an APPROVE_INTEGRATOR action with the stored API key and return the
+   * signed blob alongside the EIP-191 `L2ApproveIntegrator` L1 message the
+   * user's Ethereum wallet must countersign. Unlike {@link sign}, this exposes
+   * `messageToSign`: Lighter requires `L1Sig` (injected via
+   * {@link embedL1Signature} before submission) when the integrator account
+   * belongs to a different L1 address with non-zero fee caps.
+   */
+  async signApproveIntegrator(
+    wasmSignParams: Record<string, unknown>,
+    context: LighterSignerContext
+  ): Promise<ApproveIntegratorResult> {
+    const wasm = await this.ensureLoaded()
+    await this.ensureClient(context)
+    const result = this.dispatch(
+      wasm,
+      ActionType.APPROVE_INTEGRATOR,
+      wasmSignParams,
+      context
+    )
+    if (result.error) {
+      throw new Error(`Lighter SignApproveIntegrator failed: ${result.error}`)
+    }
+    if (
+      result.txType === undefined ||
+      result.txInfo === undefined ||
+      result.txHash === undefined ||
+      !result.messageToSign
+    ) {
+      throw new Error(
+        'Lighter SignApproveIntegrator returned an incomplete result'
+      )
+    }
+    return {
+      txType: result.txType,
+      txInfo: result.txInfo,
+      txHash: result.txHash,
+      messageToSign: result.messageToSign,
+    }
+  }
+
+  /**
+   * Inject the L1 signature produced by the user's Ethereum wallet into a
+   * signed txInfo JSON. `L1Sig` is the only field that depends on the L1
+   * signature; txHash does NOT include it (so we do not recompute it). Shared
+   * by the REGISTER_API_KEY (ChangePubKey) and APPROVE_INTEGRATOR flows.
    */
   embedL1Signature(txInfo: string, l1Signature: string): string {
     let parsed: Record<string, unknown>
@@ -222,7 +277,7 @@ export class LighterSigner {
       parsed = JSON.parse(txInfo) as Record<string, unknown>
     } catch (err) {
       throw new Error(
-        `Failed to parse ChangePubKey txInfo as JSON: ${(err as Error).message}`
+        `Failed to parse signed txInfo as JSON: ${(err as Error).message}`
       )
     }
     parsed.L1Sig = l1Signature
@@ -291,7 +346,7 @@ export class LighterSigner {
     action: ActionType,
     p: Record<string, unknown>,
     ctx: LighterSignerContext
-  ): SignResult {
+  ): SignResult & { messageToSign?: string } {
     const nonce = numberField(p, 'nonce')
     switch (action) {
       case ActionType.PLACE_ORDER:

package/src/signers/signActions.ts

@@ -81,6 +81,8 @@ export async function signWasmBlobActions(
   for (const step of steps) {
     if (step.action === ActionType.REGISTER_API_KEY) {
       signed.push(await signRegisterApiKey(deps, address, step, ctx))
+    } else if (step.action === ActionType.APPROVE_INTEGRATOR) {
+      signed.push(await signApproveIntegrator(deps, address, step, ctx))
     } else if (
       TOKEN_AUTH_MUTATION_KINDS.has(step.wasmSignParams.kind as string)
     ) {
@@ -196,6 +198,61 @@ async function signRegisterApiKey(
   }
 }
 
+/**
+ * APPROVE_INTEGRATOR flow:
+ *   1. Load the user's stored API key (no keypair generation).
+ *   2. Wasm-sign the `L2ApproveIntegrator` blob with that key, obtaining the
+ *      EIP-191 L1 message the wallet must countersign.
+ *   3. Have the user's L1 Ethereum wallet sign that message.
+ *   4. Inject the L1 signature into the txInfo JSON as `L1Sig`.
+ *
+ * Requires the end-user's wallet in `ctx.userWallet`: Lighter rejects the tx
+ * without the user's `L1Sig` when the integrator account belongs to a
+ * different L1 address with non-zero fee caps.
+ */
+async function signApproveIntegrator(
+  deps: LighterSignActionsDeps,
+  address: Address,
+  step: WasmBlobActionStep,
+  ctx: SignActionsContext | undefined
+): Promise<WasmBlobSignedActionStep> {
+  const walletSigner = ctx?.userWallet
+  if (!walletSigner) {
+    throw new PerpsError(
+      PerpsErrorCode.SDKError,
+      'APPROVE_INTEGRATOR requires the end-user wallet — pass `userWallet` to ' +
+        'createPerpsClient or call setUserWallet(walletClient).'
+    )
+  }
+
+  const apiKey = await requireApiKey(deps, address)
+  const signed = await deps.signer.signApproveIntegrator(step.wasmSignParams, {
+    apiKeyPrivateKey: apiKey.apiKeyPrivateKey,
+    apiKeyIndex: apiKey.apiKeyIndex,
+    accountIndex: apiKey.accountIndex,
+  })
+
+  const l1Signature = await walletSigner.signMessage({
+    account: walletSigner.account,
+    message: signed.messageToSign,
+  })
+
+  const txInfoWithL1Sig = deps.signer.embedL1Signature(
+    signed.txInfo,
+    l1Signature
+  )
+
+  return {
+    action: step.action,
+    wasmSignParams: step.wasmSignParams,
+    signedTx: {
+      txType: signed.txType,
+      txInfo: txInfoWithL1Sig,
+      txHash: signed.txHash,
+    },
+  }
+}
+
 /**
  * Execute a token-authenticated Lighter mutation (`ACCOUNT_TYPE` →
  * `/changeAccountTier`, `SET_REFERRAL` → `/referral/use`) client-side.

package/src/signers/wasmLoader.ts

@@ -163,9 +163,13 @@ export interface LighterWasmExports {
    * 10 args: integratorAccountIndex, maxPerpsTakerFee, maxPerpsMakerFee,
    * maxSpotTakerFee, maxSpotMakerFee, approvalExpiry, skipNonce, then the
    * trailing three. Fees are uint32 ppm of `FeeTick` (1_000_000); a non-nil
-   * fee requires a non-nil integrator index.
+   * fee requires a non-nil integrator index. `messageToSign` is the EIP-191
+   * `L2ApproveIntegrator` L1 body the user's wallet must countersign — the
+   * venue rejects the tx without the resulting `L1Sig`.
    */
-  SignApproveIntegrator: (...args: unknown[]) => SignResult
+  SignApproveIntegrator: (
+    ...args: unknown[]
+  ) => SignResult & { messageToSign?: string }
   /**
    * 5 args: accountTradingMode (0 = Classic/Simple, 1 = Unified), skipNonce,
    * then the trailing three. `accountTradingMode` is validated to {0, 1} by

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)
     }
   }