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

package/src/LighterProvider.ts

@@ -61,6 +61,7 @@ import {
   DEFAULT_TRADES_LIMIT,
   LIGHTER_ALL_MARKETS_WILDCARD,
   LIGHTER_BASE_FEE_TIER,
+  LIGHTER_COLLATERAL_ASSETS,
   LIGHTER_FEE_TICK_SCALE,
   LIGHTER_HISTORY_PAGE_SIZE,
   LIGHTER_PROVIDER_KEY,
@@ -187,8 +188,8 @@ const normalizeLighterPublicKey = (key: string): string =>
  *   - `getOrder` throws `Unauthorized`
  *   - `getAccount` returns zero fee tier rather than failing
  *
- * Write actions (`signActions` for the WASM_BLOB / EVM_TX arms) require
- * `signer` and `keyStore` to be supplied.
+ * `WASM_BLOB` write actions (`signActions`) require `signer` and `keyStore` to
+ * be supplied; the `EVM_TX` arm signs with the end-user wallet alone.
  *
  * @public
  */
@@ -212,14 +213,14 @@ export interface LighterProviderOptions {
   /** Pre-created Lighter read-only bearer. */
   authToken?: string | (() => string | Promise<string>)
   /**
-   * WASM signer instance. Required for `signActions` (write actions) and
-   * for on-demand auth-token creating from the user's API key. The default
+   * WASM signer instance. Required for the `WASM_BLOB` arm of `signActions`
+   * and for on-demand auth-token creating from the user's API key. The default
    * configuration loads the WASM blob shipped with this package.
    */
   signer?: LighterSigner
   /**
-   * Store for the user's per-address Lighter API keypair. Required for
-   * `signActions` (write actions) and for on-demand auth-token creating.
+   * Store for the user's per-address Lighter API keypair. Required for the
+   * `WASM_BLOB` arm of `signActions` and for on-demand auth-token creating.
    */
   keyStore?: LighterKeyStore
   /**
@@ -314,6 +315,7 @@ export const lighterProvider = (
     (providerKey === LIGHTER_PROVIDER_KEY
       ? DEFAULT_LIGHTER_EXPLORER_TX_BASE_URL
       : undefined)
+  const collateral = LIGHTER_COLLATERAL_ASSETS[providerKey]
   const authTokenSource: (() => string | Promise<string>) | undefined =
     typeof options.authToken === 'function'
       ? options.authToken
@@ -801,20 +803,29 @@ export const lighterProvider = (
       const collateralBalances: Balance[] = [
         {
           categoryId: perpsCategory?.id ?? providerKey,
-          asset: perpsCategory?.quoteAsset ?? lighterAsset('USDC', 'USDC'),
+          asset:
+            perpsCategory?.quoteAsset ??
+            lighterAsset(
+              collateral.displaySymbol,
+              collateral.displaySymbol,
+              providerKey
+            ),
           units: availableMargin.toString(),
           valueUsd: availableMargin.toString(),
         },
       ]
-      // Spot token holdings — non-collateral. USDC value is 1:1; other tokens
-      // have no price source at this boundary, so their USD value is unknown.
+      // 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 USD value is unknown.
       const balances: Balance[] = account.assets.map((a) => {
         const assetId = String(a.asset_id)
         return {
           categoryId: spotCategoryId,
-          asset: assetRegistry.get(assetId) ?? lighterAsset(assetId, a.symbol),
+          asset:
+            assetRegistry.get(assetId) ??
+            lighterAsset(assetId, a.symbol, providerKey),
           units: a.balance,
-          valueUsd: a.symbol === 'USDC' ? a.balance : '0',
+          valueUsd: a.asset_id === collateral.assetIndex ? a.balance : '0',
         }
       })
 
@@ -1373,22 +1384,13 @@ export const lighterProvider = (
       address: Address,
       ctx?: SignActionsContext
     ): Promise<SignedActionStep[]> {
-      if (signer === undefined || keyStore === undefined) {
-        throw new PerpsError(
-          PerpsErrorCode.SDKError,
-          'lighterProvider.signActions requires `signer` and `keyStore` to be ' +
-            'configured at construction.'
-        )
-      }
-      const signerRef = signer
-      const keyStoreRef = keyStore
       return lighterSignActions(
         {
-          signer: signerRef,
-          keyStore: keyStoreRef,
+          signer,
+          keyStore,
           apiClient: apiClient(),
           resolveAccountIndex: async (addr) => {
-            const apiKey = await keyStoreRef.get(addr)
+            const apiKey = keyStore ? await keyStore.get(addr) : null
             if (apiKey !== null) {
               return apiKey.accountIndex
             }

package/src/constants.ts

@@ -1,4 +1,5 @@
 import type { FeeTier, LighterProviderKey } from '@lifi/perps-types'
+import { LT_ASSET_ID_USDC } from './types/action.js'
 
 /**
  * Lighter provider key as it appears on `Provider.key` from the backend.
@@ -7,6 +8,13 @@ import type { FeeTier, LighterProviderKey } from '@lifi/perps-types'
  */
 export const LIGHTER_PROVIDER_KEY = 'lighter'
 
+/**
+ * Provider key for the Lighter instance running on Robinhood chain.
+ *
+ * @public
+ */
+export const LIGHTER_RH_PROVIDER_KEY = 'lighter-rh'
+
 /**
  * Category id for Lighter spot token holdings, matching the backend's Lighter
  * spot asset category. The perps category id is not a constant — it is read
@@ -45,6 +53,38 @@ export const DEFAULT_LIGHTER_SIGNER_CHAIN_ID = 304
 export const DEFAULT_LIGHTER_EXPLORER_TX_BASE_URL =
   'https://app.lighter.xyz/explorer/logs/'
 
+/**
+ * The collateral asset a Lighter deployment settles in: the L2 asset index its
+ * withdrawals, transfers and route moves are signed against, plus the symbol
+ * shown for the collateral balance.
+ *
+ * @public
+ */
+export interface LighterCollateralAsset {
+  /** L2 asset index, as `asset_id` on the deployment's `/api/v1/assetDetails`. */
+  assetIndex: number
+  displaySymbol: string
+}
+
+/**
+ * Collateral asset per Lighter deployment, each read from that deployment's
+ * `/api/v1/assetDetails`: mainnet settles in USDC, Robinhood chain in USDG.
+ * Both sit at asset index 3 of their own registry — the same slot holds a
+ * different token per deployment, so an index alone never identifies the asset.
+ *
+ * @public
+ */
+export const LIGHTER_COLLATERAL_ASSETS: Record<
+  LighterProviderKey,
+  LighterCollateralAsset
+> = {
+  [LIGHTER_PROVIDER_KEY]: {
+    assetIndex: LT_ASSET_ID_USDC,
+    displaySymbol: 'USDC',
+  },
+  [LIGHTER_RH_PROVIDER_KEY]: { 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
@@ -62,6 +102,11 @@ export interface LighterInstanceConfig {
    * {@link LighterSigner} with.
    */
   signerChainId: number
+  /**
+   * Collateral asset this deployment settles in — signed into its withdrawals
+   * and transfers, and reported as its collateral balance.
+   */
+  collateral: LighterCollateralAsset
   /**
    * Explorer tx base URL for transfer-activity links (`${base}${txHash}`).
    * When omitted, transfer links are not emitted for this instance.
@@ -80,16 +125,10 @@ export const LIGHTER_MAINNET_INSTANCE: LighterInstanceConfig = {
   restUrl: DEFAULT_LIGHTER_REST_URL,
   wsUrl: DEFAULT_LIGHTER_WS_URL,
   signerChainId: DEFAULT_LIGHTER_SIGNER_CHAIN_ID,
+  collateral: LIGHTER_COLLATERAL_ASSETS[LIGHTER_PROVIDER_KEY],
   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'
-
 /**
  * Default REST base URL for the Lighter Robinhood deployment.
  *
@@ -137,6 +176,7 @@ export const lighterRhInstance = (
   restUrl: LIGHTER_RH_REST_URL,
   wsUrl: LIGHTER_RH_WS_URL,
   signerChainId: overrides.signerChainId,
+  collateral: LIGHTER_COLLATERAL_ASSETS[LIGHTER_RH_PROVIDER_KEY],
   explorerTxBaseUrl: overrides.explorerTxBaseUrl,
 })
 

package/src/index.ts

@@ -16,6 +16,7 @@
 export { projectLighterConfigSettings } from './accountConfig.js'
 export { getAccountSummary } from './accountSummary.js'
 export type {
+  LighterCollateralAsset,
   LighterInstanceConfig,
   LighterRhInstanceOverrides,
 } from './constants.js'
@@ -25,6 +26,7 @@ export {
   DEFAULT_LIGHTER_REST_URL,
   DEFAULT_LIGHTER_SIGNER_CHAIN_ID,
   DEFAULT_LIGHTER_WS_URL,
+  LIGHTER_COLLATERAL_ASSETS,
   LIGHTER_MAINNET_INSTANCE,
   LIGHTER_PROVIDER_KEY,
   LIGHTER_RH_PROVIDER_KEY,

package/src/signers/LighterSigner.ts

@@ -38,8 +38,8 @@ export interface LighterSignerContext {
 }
 
 /**
- * Configuration for {@link LighterSigner}, including optional WASM asset
- * overrides and the Lighter REST base URL and signing chain ID.
+ * Configuration for {@link LighterSigner}: optional WASM asset overrides plus
+ * the per-instance REST base URL, signing chain id and collateral asset index.
  *
  * @public
  */
@@ -48,6 +48,12 @@ export interface LighterSignerConfig extends LoadLighterWasmOptions {
   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
 }
 
 /**
@@ -108,12 +114,11 @@ const SKIP_NONCE_DISABLED = 0
 // CancelAll across every market (lighter-go `NilMarketIndex`); a real index
 // scopes the cancel to a single market.
 const NIL_MARKET_INDEX = 255
-// Withdrawals/transfers are USDC on the perps route (lighter-go `USDCAssetIndex`
-// / `AssetRouteType_Perps`). The signer rejects an asset index < 1.
-const USDC_ASSET_INDEX = 3
+// Collateral withdrawals and transfers ride the perps route (lighter-go
+// `AssetRouteType_Perps`). The signer rejects an asset index < 1.
 const ASSET_ROUTE_TYPE_PERPS = 0
 
-// SEND_ASSET is a same-account route→route USDC move (spot↔perp): no counterparty
+// SEND_ASSET is a same-account route→route collateral move (spot↔perp): no
 // fee, and no memo. `SignTransfer` requires a 32-byte memo, so we pass 32 zero
 // bytes in the `0x`-prefixed 64-hex form the WASM signer decodes.
 const SEND_ASSET_NO_FEE = 0
@@ -136,6 +141,7 @@ const LIGHTER_ROUTE_BY_DEX: Record<string, number> = {
 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>()
@@ -143,6 +149,7 @@ export class LighterSigner {
   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,
@@ -499,7 +506,7 @@ export class LighterSigner {
         )
       case ActionType.WITHDRAWAL:
         return wasm.SignWithdraw(
-          USDC_ASSET_INDEX,
+          this.collateralAssetIndex,
           ASSET_ROUTE_TYPE_PERPS,
           numberField(p, 'amount'),
           SKIP_NONCE_DISABLED,
@@ -517,7 +524,7 @@ export class LighterSigner {
         // long".
         return wasm.SignTransfer(
           numberField(p, 'to_account'),
-          USDC_ASSET_INDEX,
+          this.collateralAssetIndex,
           ASSET_ROUTE_TYPE_PERPS,
           ASSET_ROUTE_TYPE_PERPS,
           numberField(p, 'usdc_amount'),
@@ -529,9 +536,9 @@ export class LighterSigner {
           ctx.accountIndex
         )
       case ActionType.SEND_ASSET: {
-        // Same-account USDC self-transfer between the perp and spot routes.
-        // `toAccountIndex` is the signer's own account; the routes come from
-        // the backend-passed `sourceDex`/`destinationDex` wire strings.
+        // Same-account collateral self-transfer between the perp and spot
+        // routes. `toAccountIndex` is the signer's own account; the routes come
+        // from the backend-passed `sourceDex`/`destinationDex` wire strings.
         const fromRouteType = routeFromDex(stringField(p, 'sourceDex'))
         const toRouteType = routeFromDex(stringField(p, 'destinationDex'))
         if (fromRouteType === toRouteType) {
@@ -542,7 +549,7 @@ export class LighterSigner {
         }
         return wasm.SignTransfer(
           ctx.accountIndex,
-          LT_ASSET_ID_USDC,
+          this.collateralAssetIndex,
           fromRouteType,
           toRouteType,
           numberField(p, 'amount'),

package/src/signers/signActions.ts

@@ -23,13 +23,16 @@ import type { LighterSigner } from './LighterSigner.js'
  * Per-batch dependencies the Lighter `signActions` implementation needs:
  * a WASM signer (`LighterSigner`), the API-key store keyed on L1 address,
  * a REST client for the token-authenticated venue mutations that execute
- * client-side, and a reference to the host SDK client for descriptor/account
- * fetches within the REGISTER_API_KEY hybrid flow.
+ * client-side, and an `accountIndex` resolver for the REGISTER_API_KEY
+ * hybrid flow.
+ *
+ * `signer` and `keyStore` are optional because only the `WASM_BLOB` arm signs
+ * with them — `EVM_TX` broadcasts through the end-user wallet in `ctx`.
  * @internal
  */
 export interface LighterSignActionsDeps {
-  signer: LighterSigner
-  keyStore: LighterKeyStore
+  signer?: LighterSigner
+  keyStore?: LighterKeyStore
   /** REST client bound to the user's Lighter base URL, used for the direct
    * `changeAccountTier` / `referral/use` POSTs so their auth token never
    * transits the LI.FI backend. */
@@ -43,6 +46,12 @@ export interface LighterSignActionsDeps {
   resolveAccountIndex(address: Address): Promise<number>
 }
 
+/** {@link LighterSignActionsDeps} narrowed to the arm that signs wasm blobs. */
+type LighterWasmSignActionsDeps = LighterSignActionsDeps & {
+  signer: LighterSigner
+  keyStore: LighterKeyStore
+}
+
 /**
  * `wasmSignParams.kind` values for the Lighter mutations that authenticate with
  * a short-lived auth token instead of a wasm-signed transaction. Both execute
@@ -77,25 +86,35 @@ export async function signWasmBlobActions(
   steps: WasmBlobActionStep[],
   ctx: SignActionsContext | undefined
 ): Promise<WasmBlobSignedActionStep[]> {
+  const { signer, keyStore } = deps
+  if (signer === undefined || keyStore === undefined) {
+    throw new PerpsError(
+      PerpsErrorCode.SDKError,
+      'lighterProvider.signActions requires `signer` and `keyStore` to be ' +
+        'configured at construction.'
+    )
+  }
+  const wasmDeps: LighterWasmSignActionsDeps = { ...deps, signer, keyStore }
+
   const signed: WasmBlobSignedActionStep[] = []
   for (const step of steps) {
     if (step.action === ActionType.REGISTER_API_KEY) {
-      signed.push(await signRegisterApiKey(deps, address, step, ctx))
+      signed.push(await signRegisterApiKey(wasmDeps, address, step, ctx))
     } else if (step.action === ActionType.APPROVE_INTEGRATOR) {
-      signed.push(await signApproveIntegrator(deps, address, step, ctx))
+      signed.push(await signApproveIntegrator(wasmDeps, address, step, ctx))
     } else if (
       TOKEN_AUTH_MUTATION_KINDS.has(step.wasmSignParams.kind as string)
     ) {
-      await executeTokenAuthMutation(deps, address, step)
+      await executeTokenAuthMutation(wasmDeps, address, step)
     } else {
-      signed.push(await signStandardWasmAction(deps, address, step))
+      signed.push(await signStandardWasmAction(wasmDeps, address, step))
     }
   }
   return signed
 }
 
 async function signStandardWasmAction(
-  deps: LighterSignActionsDeps,
+  deps: LighterWasmSignActionsDeps,
   address: Address,
   step: WasmBlobActionStep
 ): Promise<WasmBlobSignedActionStep> {
@@ -125,7 +144,7 @@ async function signStandardWasmAction(
  * user's consent to rotate keys.
  */
 async function signRegisterApiKey(
-  deps: LighterSignActionsDeps,
+  deps: LighterWasmSignActionsDeps,
   address: Address,
   step: WasmBlobActionStep,
   ctx: SignActionsContext | undefined
@@ -211,7 +230,7 @@ async function signRegisterApiKey(
  * different L1 address with non-zero fee caps.
  */
 async function signApproveIntegrator(
-  deps: LighterSignActionsDeps,
+  deps: LighterWasmSignActionsDeps,
   address: Address,
   step: WasmBlobActionStep,
   ctx: SignActionsContext | undefined
@@ -266,7 +285,7 @@ async function signApproveIntegrator(
  * `code`/`message` verbatim as an {@link PerpsErrorCode.ExchangeRejected}.
  */
 async function executeTokenAuthMutation(
-  deps: LighterSignActionsDeps,
+  deps: LighterWasmSignActionsDeps,
   address: Address,
   step: WasmBlobActionStep
 ): Promise<void> {
@@ -345,7 +364,7 @@ function buildTokenAuthMutationRequest(
 }
 
 async function requireApiKey(
-  deps: LighterSignActionsDeps,
+  deps: LighterWasmSignActionsDeps,
   address: Address
 ): Promise<LighterApiKey> {
   const apiKey = await deps.keyStore.get(address)

package/src/types/action.ts

@@ -195,7 +195,9 @@ export const LT_ROUTE_PERP = 0
 export const LT_ROUTE_SPOT = 1
 
 /**
- * Lighter spot USDC asset id.
+ * L2 asset index of USDC on Lighter mainnet — the collateral slot mainnet
+ * withdrawals, transfers and L1 bridge deposits address. Other deployments
+ * settle in their own asset; see `LIGHTER_COLLATERAL_ASSETS`.
  * @public
  */
 export const LT_ASSET_ID_USDC = 3

package/src/utils/lighterAsset.ts

@@ -1,4 +1,4 @@
-import type { Asset } from '@lifi/perps-types'
+import type { Asset, LighterProviderKey } from '@lifi/perps-types'
 import { LIGHTER_PROVIDER_KEY } from '../constants.js'
 
 /**
@@ -6,10 +6,15 @@ import { LIGHTER_PROVIDER_KEY } from '../constants.js'
  * symbol. Lighter assets do not provide a package-level logo URI, so this
  * helper leaves that field empty.
  *
+ * @param providerId - Instance the asset belongs to; defaults to mainnet.
  * @public
  */
-export const lighterAsset = (id: string, displaySymbol: string): Asset => ({
-  providerId: LIGHTER_PROVIDER_KEY,
+export const lighterAsset = (
+  id: string,
+  displaySymbol: string,
+  providerId: LighterProviderKey = LIGHTER_PROVIDER_KEY
+): Asset => ({
+  providerId,
   id,
   displaySymbol,
   logoURI: '',