@lifi/perps-sdk-provider-lighter 0.2.0-alpha.0

package/src/accountConfig.ts

@@ -0,0 +1,162 @@
+import { PerpsError } from '@lifi/perps-sdk'
+import type {
+  AccountConfigSetting,
+  LighterAccountConfig,
+  ProviderAction,
+} from '@lifi/perps-types'
+import { ActionType, PerpsErrorCode } from '@lifi/perps-types'
+
+function assertNever(value: never): never {
+  throw new Error(
+    `Unreachable: exhaustiveness check failed for value ${JSON.stringify(value)}`
+  )
+}
+
+/**
+ * `account_type` on Lighter's `DetailedAccount` is a `StrictInt` in the
+ * public OpenAPI schema (`lighter-python/lighter/models/detailed_account.py`)
+ * with no documented integer ↔ name mapping in the Python or Go SDKs.
+ *
+ * The empirical mapping below follows the public docs' tier ordering
+ * (apidocs.lighter.xyz/docs/account-types lists Standard → Premium → Plus)
+ * and the Python paper client's `AccountTier` enum ordering (STANDARD
+ * first, PREMIUM next). The write side of `/changeAccountTier` accepts the
+ * lowercase strings `'standard' | 'premium'` — these are what the
+ * descriptor's `ParamOption.value` declarations carry, so this mapping
+ * round-trips cleanly with the OptionsModal selection.
+ *
+ * Lighter publishes a third "Plus" tier (likely integer `2`), but it is
+ * not currently settable via the public API, so we deliberately do not
+ * map it — a Plus account surfaces as "tier not detected" in the widget
+ * rather than offering an option that would 400 on submit. Add
+ * `LIGHTER_ACCOUNT_TYPE_PLUS` here (and to the backend descriptor) if
+ * Lighter exposes it later.
+ *
+ * Each integer is a named constant so a correction (e.g. Lighter publishing
+ * an authoritative table) is a one-line edit. An unmapped integer projects
+ * to `null` and surfaces as "tier not detected" in the widget, so drift is
+ * observable rather than silent.
+ */
+const LIGHTER_ACCOUNT_TYPE_STANDARD = 0
+const LIGHTER_ACCOUNT_TYPE_PREMIUM = 1
+
+const ACCOUNT_TYPE_INT_TO_WIRE: Readonly<Record<number, string>> = {
+  [LIGHTER_ACCOUNT_TYPE_STANDARD]: 'standard',
+  [LIGHTER_ACCOUNT_TYPE_PREMIUM]: 'premium',
+}
+
+/**
+ * Project a single Lighter descriptor against the typed
+ * `LighterAccountConfig` into an `AccountConfigSetting`.
+ *
+ * Mapping table:
+ *
+ * | descriptor.type           | projected values
+ * |---------------------------|--------------------------------------------------
+ * | REGISTER_API_KEY          | []                  (no parameters)
+ * | APPROVE_READ_ONLY_TOKEN   | []                  (no parameters)
+ * | ACCOUNT_MODE              | [{ name: 'mode', value: null }]  (Lighter has no
+ * |                           |  abstraction-mode equivalent; read-only here)
+ * | ACCOUNT_TYPE              | [{ name: 'tier', value: config.accountType }]
+ *
+ * The switch is exhaustive over `ActionType` so enum additions force a
+ * compile error in the `default` arm. ActionTypes that are not valid on
+ * `Provider.setup` / `Provider.options` throw at runtime.
+ */
+function projectLighterDescriptor(
+  descriptor: ProviderAction,
+  config: LighterAccountConfig
+): AccountConfigSetting {
+  switch (descriptor.type) {
+    // `REGISTER_API_KEY` is satisfied only when the locally-held keypair
+    // matches the key registered on-chain at this slot — computed client-side
+    // in `getAccount` (the SDK owns account reads + the keystore). Backend
+    // staging is mutation-only; it never decides satisfaction.
+    case ActionType.REGISTER_API_KEY:
+      return {
+        type: descriptor.type,
+        values: [],
+        satisfied: config.apiKeyRegistered,
+      }
+    // `APPROVE_READ_ONLY_TOKEN` is a client-only flow that never reaches
+    // the backend, so its satisfaction state lives entirely in the typed
+    // `LighterAccountConfig` projection.
+    case ActionType.APPROVE_READ_ONLY_TOKEN:
+      return {
+        type: descriptor.type,
+        values: [],
+        satisfied: config.readOnlyTokenApproved,
+      }
+
+    // Lighter exposes no abstraction-mode equivalent; if a backend descriptor
+    // surfaces ACCOUNT_MODE on Lighter it always projects `null` and callers
+    // fall back to the descriptor's `default` ParamOption.
+    case ActionType.ACCOUNT_MODE:
+      return {
+        type: descriptor.type,
+        values: [{ name: 'mode', value: null }],
+      }
+
+    // `tier` is the wire string `/changeAccountTier` accepts; we decode the
+    // raw integer `config.accountType` Lighter publishes via the mapping
+    // above so the projection matches the descriptor's enumerated values.
+    // Unrecognised integers project to `null` (surfaces as "tier not
+    // detected" — the widget still lets the user pick a value).
+    case ActionType.ACCOUNT_TYPE:
+      return {
+        type: descriptor.type,
+        values: [
+          {
+            name: 'tier',
+            value: ACCOUNT_TYPE_INT_TO_WIRE[config.accountType] ?? null,
+          },
+        ],
+      }
+
+    case ActionType.APPROVE_AGENT:
+    case ActionType.APPROVE_BUILDER_FEE:
+    case ActionType.SEND_ASSET:
+    case ActionType.WITHDRAWAL:
+    case ActionType.TRANSFER:
+    case ActionType.PLACE_ORDER:
+    case ActionType.PLACE_TRIGGER_ORDER:
+    case ActionType.CANCEL_ORDER:
+    case ActionType.CANCEL_ALL_ORDERS:
+    case ActionType.MODIFY_ORDER:
+    case ActionType.UPDATE_LEVERAGE:
+    case ActionType.UPDATE_POSITION_MARGIN:
+    case ActionType.DEPOSIT:
+    case ActionType.META_VOTE:
+    case ActionType.META_ACCEPT_TERMS:
+      throw new PerpsError(
+        PerpsErrorCode.SDKError,
+        `Lighter account-config mapper has no projection for ` +
+          `descriptor type '${descriptor.type}' — this ActionType is not ` +
+          `valid on Provider.setup / Provider.options for Lighter.`
+      )
+
+    default:
+      return assertNever(descriptor.type)
+  }
+}
+
+/**
+ * Project the union of Lighter setup + options descriptors against the typed
+ * `LighterAccountConfig`. Produces exactly one `AccountConfigSetting` per
+ * descriptor, in `setup`-then-`options` order (preserving the order in which
+ * the backend emits them).
+ *
+ * @param config Typed account state for the Lighter account.
+ * @param setup  `Provider.setup` array as emitted by `/providers`.
+ * @param options `Provider.options` array as emitted by `/providers`.
+ * @public
+ */
+export function projectLighterConfigSettings(
+  config: LighterAccountConfig,
+  setup: ProviderAction[],
+  options: ProviderAction[]
+): AccountConfigSetting[] {
+  return [...setup, ...options].map((descriptor) =>
+    projectLighterDescriptor(descriptor, config)
+  )
+}

package/src/accountSummary.ts

@@ -0,0 +1,22 @@
+import { summarizeAccount } from '@lifi/perps-sdk'
+import type {
+  AccountResponse,
+  AccountSummary,
+  Position,
+} from '@lifi/perps-types'
+
+/**
+ * Roll a Lighter {@link AccountResponse} up into an {@link AccountSummary}.
+ * Lighter has a single flat collateral model with no abstraction modes: the
+ * collateral rows hold `available_balance` (free margin), so available margin
+ * is the collateral as-is and the locked margin (carried by the positions'
+ * `marginUsed`) is added back for the gross portfolio value.
+ *
+ * @public
+ */
+export function summarizeLighterAccount(
+  account: AccountResponse,
+  positions: Position[]
+): AccountSummary {
+  return summarizeAccount(account, positions, false)
+}

package/src/constants.ts

@@ -0,0 +1,89 @@
+import type { FeeTier } from '@lifi/perps-types'
+
+/**
+ * Lighter provider key as it appears on `Provider.key` from the backend.
+ *
+ * @public
+ */
+export const LIGHTER_PROVIDER_KEY = 'lighter'
+
+/**
+ * Default mainnet REST base URL for Lighter.
+ *
+ * @public
+ */
+export const DEFAULT_LIGHTER_REST_URL = 'https://mainnet.zklighter.elliot.ai'
+
+/** @internal */
+export const DEFAULT_TRADES_LIMIT = 50
+
+/**
+ * Lighter pairs each maker/taker fee with a 1e6 integer tick:
+ *   fee_fraction = current_*_fee_tick / 1_000_000
+ *
+ * See lighter-python `paper_client/types.py:_FEE_TICK` for the canonical scale.
+ *
+ * @internal
+ */
+export const LIGHTER_FEE_TICK_SCALE = 1_000_000
+
+/**
+ * Lighter's public base fee tier (Standard Account): 0% maker / 0% taker on all
+ * perps markets. Per-account Premium tiers exist but require auth to resolve;
+ * unauthenticated quotes use this public base. Fractions, not basis points.
+ *
+ * @public
+ */
+export const LIGHTER_BASE_FEE_TIER: FeeTier = { maker: '0', taker: '0' }
+
+/**
+ * Wildcard `market_id` accepted by Lighter's per-market account endpoints to
+ * indicate "every market". Used on `accountInactiveOrders`, `positionFunding`,
+ * `liquidations`.
+ *
+ * @internal
+ */
+export const LIGHTER_ALL_MARKETS_WILDCARD = 255
+
+/**
+ * Lighter caps `limit` at 100 on positionFunding/liquidations endpoints.
+ *
+ * @internal
+ */
+export const LIGHTER_HISTORY_PAGE_SIZE = 100
+
+/**
+ * Default API key slot — reused per account. Lighter's docs reserve indexes
+ * `{0,1,2,3}` for its own desktop/mobile interfaces; user keys start at 4
+ * (max 254, with 255 reserved as `NilApiKeyIndex`). 42 is the LI.FI-wide
+ * identifier so a user running both the Lighter app and the widget never
+ * collides with the app's session key.
+ *
+ * @public
+ */
+export const DEFAULT_API_KEY_INDEX = 42
+
+/** @internal */
+const LIGHTER_CODE_ACCOUNT_NOT_FOUND = 21100
+
+/**
+ * Lighter body `code` for a rejected/invalid auth token ("invalid auth string").
+ *
+ * @internal
+ */
+const LIGHTER_INVALID_AUTH_CODE = 20013
+
+/**
+ * Lighter body `code` values that mean success. Lighter is inconsistent per
+ * endpoint: `/api/v1/account` returns `code: 200`, most others return `code: 0`.
+ * A body with no `code` field is also success (no error channel present).
+ *
+ * @internal
+ */
+const LIGHTER_SUCCESS_CODES = new Set([0, 200])
+
+export {
+  LIGHTER_CODE_ACCOUNT_NOT_FOUND,
+  LIGHTER_INVALID_AUTH_CODE,
+  LIGHTER_SUCCESS_CODES,
+}

package/src/index.ts

@@ -0,0 +1,37 @@
+// biome-ignore-all lint/performance/noBarrelFile: package public entry point.
+// biome-ignore-all lint/performance/noReExportAll: package public entry point.
+
+/**
+ * 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.
+ *
+ * @packageDocumentation
+ * @public
+ */
+
+export { projectLighterConfigSettings } from './accountConfig.js'
+export { summarizeLighterAccount } from './accountSummary.js'
+export {
+  DEFAULT_API_KEY_INDEX,
+  DEFAULT_LIGHTER_REST_URL,
+  LIGHTER_PROVIDER_KEY,
+} from './constants.js'
+export type {
+  LighterPerpsProvider,
+  LighterProviderOptions,
+} from './LighterProvider.js'
+export { Lighter, lighterProvider } from './LighterProvider.js'
+
+export * from './signers/index.js'
+export * from './types/index.js'
+export * from './utils/index.js'
+export type { LighterAuthProvider } from './websocket/LighterWsProvider.js'
+export {
+  LighterWsProvider,
+  type LighterWsProviderOptions,
+  lighterWsProvider,
+} from './websocket/LighterWsProvider.js'

package/src/signers/LighterKeyStore.ts

@@ -0,0 +1,79 @@
+import { readValidatedRecord, type StorageAdapter } from '@lifi/perps-sdk'
+import type { Address } from 'viem'
+
+// The private key here is a Lighter custom keypair — generated via WASM
+// GenerateAPIKey — not an Ethereum private key. The storage key is namespaced
+// by provider (`lighter`) so the same user can hold credentials for other
+// WASM-blob providers without collision.
+
+const STORAGE_PREFIX = 'lifi-perps-lighter-key'
+
+/** @public */
+export interface LighterApiKey {
+  /** Lighter account index, looked up once via accountsByL1Address. */
+  accountIndex: number
+  /** API key slot (0-255). Defaults to {@link DEFAULT_API_KEY_INDEX}. */
+  apiKeyIndex: number
+  /** Lighter-native private key (0x-prefixed hex). */
+  apiKeyPrivateKey: string
+  /** Corresponding public key, registered via ChangePubKey. */
+  apiKeyPublicKey: string
+}
+
+const isLighterApiKey = (value: unknown): value is LighterApiKey => {
+  if (typeof value !== 'object' || value === null) {
+    return false
+  }
+  const { accountIndex, apiKeyIndex, apiKeyPrivateKey, apiKeyPublicKey } =
+    value as Record<string, unknown>
+  return (
+    typeof accountIndex === 'number' &&
+    Number.isFinite(accountIndex) &&
+    typeof apiKeyIndex === 'number' &&
+    Number.isFinite(apiKeyIndex) &&
+    typeof apiKeyPrivateKey === 'string' &&
+    apiKeyPrivateKey.length > 0 &&
+    typeof apiKeyPublicKey === 'string' &&
+    apiKeyPublicKey.length > 0
+  )
+}
+
+/** @public */
+export class LighterKeyStore {
+  private readonly storage: StorageAdapter
+  private readonly cache = new Map<string, LighterApiKey>()
+
+  constructor(storage: StorageAdapter) {
+    this.storage = storage
+  }
+
+  private storageKey(address: Address): string {
+    return `${STORAGE_PREFIX}:${address.toLowerCase()}`
+  }
+
+  async get(address: Address): Promise<LighterApiKey | null> {
+    const key = this.storageKey(address)
+    const cached = this.cache.get(key)
+    if (cached) {
+      return cached
+    }
+    const parsed = await readValidatedRecord(this.storage, key, isLighterApiKey)
+    if (!parsed) {
+      return null
+    }
+    this.cache.set(key, parsed)
+    return parsed
+  }
+
+  async set(address: Address, value: LighterApiKey): Promise<void> {
+    const key = this.storageKey(address)
+    this.cache.set(key, value)
+    await this.storage.set(key, JSON.stringify(value))
+  }
+
+  async remove(address: Address): Promise<void> {
+    const key = this.storageKey(address)
+    this.cache.delete(key)
+    await this.storage.remove(key)
+  }
+}