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

package/src/signers/signActions.ts

@@ -0,0 +1,311 @@
+import { PerpsError, type SignActionsContext } from '@lifi/perps-sdk'
+import type {
+  ActionStep,
+  EvmTxActionStep,
+  EvmTxSignedActionStep,
+  SignedActionStep,
+  WasmBlobActionStep,
+  WasmBlobSignedActionStep,
+} from '@lifi/perps-types'
+import { ActionType, PerpsErrorCode, SigningMethod } from '@lifi/perps-types'
+import type { Address } from 'viem'
+import { parseAbi } from 'viem'
+import { DEFAULT_API_KEY_INDEX } from '../constants.js'
+import type { LighterApiKey, LighterKeyStore } from './LighterKeyStore.js'
+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,
+ * and a reference to the host SDK client for descriptor/account fetches
+ * within the REGISTER_API_KEY hybrid flow.
+ * @internal
+ */
+export interface LighterSignActionsDeps {
+  signer: LighterSigner
+  keyStore: LighterKeyStore
+  /**
+   * Resolve the user's Lighter `accountIndex` for an L1 address. Required
+   * by REGISTER_API_KEY so the ChangePubKey blob carries the right
+   * account. Implementations typically call Lighter's `/api/v1/account`
+   * with `by=l1_address`.
+   */
+  resolveAccountIndex(address: Address): Promise<number>
+}
+
+/**
+ * Sign a `WASM_BLOB` batch (Lighter). Ensures the user's API keypair is
+ * registered first — generating one and running the REGISTER_API_KEY
+ * hybrid flow via the L1 signer if not — then feeds each subsequent step
+ * through the WASM signer.
+ *
+ * `ACCOUNT_TYPE` (Lighter `/changeAccountTier`) is a WASM_BLOB envelope
+ * authenticated with an auth token rather than a wasm tx signature —
+ * created via `LighterSigner.createAuthToken` and parked in `signedTx.txInfo`.
+ * @internal
+ */
+export async function signWasmBlobActions(
+  deps: LighterSignActionsDeps,
+  address: Address,
+  steps: WasmBlobActionStep[],
+  ctx: SignActionsContext | undefined
+): Promise<WasmBlobSignedActionStep[]> {
+  const signed: WasmBlobSignedActionStep[] = []
+  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.ACCOUNT_TYPE) {
+      signed.push(await signAccountTierChange(deps, address, step))
+    } else {
+      signed.push(await signStandardWasmAction(deps, address, step))
+    }
+  }
+  return signed
+}
+
+async function signStandardWasmAction(
+  deps: LighterSignActionsDeps,
+  address: Address,
+  step: WasmBlobActionStep
+): Promise<WasmBlobSignedActionStep> {
+  const apiKey = await requireApiKey(deps, address)
+  const signedTx = await deps.signer.sign(step.action, step.wasmSignParams, {
+    apiKeyPrivateKey: apiKey.apiKeyPrivateKey,
+    apiKeyIndex: apiKey.apiKeyIndex,
+    accountIndex: apiKey.accountIndex,
+  })
+  return {
+    action: step.action,
+    wasmSignParams: step.wasmSignParams,
+    signedTx,
+  }
+}
+
+/**
+ * REGISTER_API_KEY flow:
+ *   1. Look up the user's Lighter accountIndex (Lighter REST).
+ *   2. Generate a fresh Lighter API keypair via the WASM signer.
+ *   3. Call SignChangePubKey to produce the WASM blob + EIP-191 message.
+ *   4. Have the user's L1 Ethereum wallet sign the message.
+ *   5. Inject the L1 signature into the ChangePubKey txInfo JSON.
+ *   6. Persist the keypair and return the signed blob.
+ *
+ * Requires the end-user's wallet in `ctx.userWallet` — the L1 signature is the
+ * user's consent to rotate keys.
+ */
+async function signRegisterApiKey(
+  deps: LighterSignActionsDeps,
+  address: Address,
+  step: WasmBlobActionStep,
+  ctx: SignActionsContext | undefined
+): Promise<WasmBlobSignedActionStep> {
+  const walletSigner = ctx?.userWallet
+  if (!walletSigner) {
+    throw new PerpsError(
+      PerpsErrorCode.SDKError,
+      'REGISTER_API_KEY requires the end-user wallet — pass `userWallet` to ' +
+        'createPerpsClient or call setUserWallet(walletClient).'
+    )
+  }
+
+  const params = step.wasmSignParams as {
+    api_key_index?: number
+    nonce?: number
+    skip_nonce?: 0 | 1
+  }
+  const apiKeyIndex = params.api_key_index ?? DEFAULT_API_KEY_INDEX
+  const nonce = params.nonce
+  if (typeof nonce !== 'number') {
+    throw new PerpsError(
+      PerpsErrorCode.SDKError,
+      'REGISTER_API_KEY wasmSignParams is missing `nonce`.'
+    )
+  }
+  const skipNonce = params.skip_nonce === 1 ? 1 : 0
+
+  const accountIndex = await deps.resolveAccountIndex(address)
+
+  const keypair = await deps.signer.generateAPIKey()
+  const changePubKey = await deps.signer.signChangePubKey(
+    keypair.publicKey,
+    keypair.privateKey,
+    nonce,
+    apiKeyIndex,
+    accountIndex,
+    skipNonce
+  )
+
+  const l1Signature = await walletSigner.signMessage({
+    account: walletSigner.account,
+    message: changePubKey.messageToSign,
+  })
+
+  const txInfoWithL1Sig = deps.signer.embedL1Signature(
+    changePubKey.txInfo,
+    l1Signature
+  )
+
+  const apiKey: LighterApiKey = {
+    accountIndex,
+    apiKeyIndex,
+    apiKeyPrivateKey: keypair.privateKey,
+    apiKeyPublicKey: keypair.publicKey,
+  }
+  await deps.keyStore.set(address, apiKey)
+
+  return {
+    action: step.action,
+    wasmSignParams: {
+      ...step.wasmSignParams,
+      new_public_key: keypair.publicKey,
+    },
+    signedTx: {
+      txType: changePubKey.txType,
+      txInfo: txInfoWithL1Sig,
+      txHash: changePubKey.txHash,
+    },
+  }
+}
+
+/**
+ * Sign an `ACCOUNT_TYPE` step (Lighter `changeAccountTier`).
+ *
+ * Lighter's `/api/v1/changeAccountTier` is an HTTP-only mutation —
+ * Lighter does NOT consume a wasm-signed transaction here; it
+ * authenticates the request with the same auth token its read endpoints
+ * use, and enforces anti-replay business rules server-side. The backend
+ * declares the step as a `WasmBlobActionStep` with
+ * `wasmSignParams.kind = 'changeAccountTier'` and expects the SDK to create
+ * an auth token in lieu of a transaction signature; the executor reads
+ * `signedTx.txInfo` as the `auth` form parameter.
+ *
+ * The 1h deadline mirrors the previous behaviour — Lighter caps tokens at
+ * 8h hard, and the backend's executor runs `verifyPendingAction` then a
+ * single POST, which completes well inside an hour.
+ */
+async function signAccountTierChange(
+  deps: LighterSignActionsDeps,
+  address: Address,
+  step: WasmBlobActionStep
+): Promise<WasmBlobSignedActionStep> {
+  const apiKey = await requireApiKey(deps, address)
+  const deadline = Math.floor(Date.now() / 1000) + 60 * 60
+  const authToken = await deps.signer.createAuthToken(deadline, {
+    apiKeyPrivateKey: apiKey.apiKeyPrivateKey,
+    apiKeyIndex: apiKey.apiKeyIndex,
+    accountIndex: apiKey.accountIndex,
+  })
+  return {
+    action: step.action,
+    wasmSignParams: step.wasmSignParams,
+    signedTx: {
+      // `/changeAccountTier` reads only `txInfo` (the auth token); `txType`
+      // and `txHash` are placeholders to satisfy the envelope shape.
+      txType: 0,
+      txInfo: authToken,
+      txHash: '',
+    },
+  }
+}
+
+async function requireApiKey(
+  deps: LighterSignActionsDeps,
+  address: Address
+): Promise<LighterApiKey> {
+  const apiKey = await deps.keyStore.get(address)
+  if (!apiKey) {
+    throw new PerpsError(
+      PerpsErrorCode.SDKError,
+      `No Lighter API key registered for ${address}. ` +
+        'Run prepareAccount / REGISTER_API_KEY first.'
+    )
+  }
+  return apiKey
+}
+
+/**
+ * Sign and broadcast a sequence of `EVM_TX` actions via the user's wallet
+ * client. Steps are submitted serially so a later step (e.g. deposit) can
+ * rely on an earlier step (e.g. approve) having mined. Each step's
+ * `txParams` carries chainId, target, function name, args, and a
+ * human-readable abi from the backend.
+ * @internal
+ */
+export async function signEvmTxActions(
+  steps: EvmTxActionStep[],
+  ctx: SignActionsContext | undefined
+): Promise<EvmTxSignedActionStep[]> {
+  const walletSigner = ctx?.userWallet
+  if (!walletSigner) {
+    throw new PerpsError(
+      PerpsErrorCode.SDKError,
+      'EVM_TX signing requires the end-user wallet. Pass `userWallet` to ' +
+        'createPerpsClient or call setUserWallet(walletClient).'
+    )
+  }
+
+  const signed: EvmTxSignedActionStep[] = []
+  for (const step of steps) {
+    const params = step.txParams as {
+      chainId: number
+      to: Address
+      functionName: string
+      args: readonly unknown[]
+      abi: readonly string[]
+    }
+
+    const txHash = await walletSigner.writeContract({
+      address: params.to,
+      abi: parseAbi(params.abi),
+      functionName: params.functionName,
+      args: params.args,
+      chain: walletSigner.chain,
+      account: walletSigner.account,
+    })
+
+    signed.push({
+      action: step.action,
+      txParams: step.txParams,
+      txHash,
+    })
+  }
+
+  return signed
+}
+
+/**
+ * Top-level dispatch: pick the per-method signer based on the descriptor's
+ * `signingMethod` and forward. `EIP712` is rejected — Lighter declares no
+ * EIP712 actions (its user-consent step uses an EIP-191 `signMessage` inside
+ * the `WASM_BLOB` REGISTER_API_KEY flow).
+ * @internal
+ */
+export async function lighterSignActions(
+  deps: LighterSignActionsDeps,
+  method: SigningMethod,
+  steps: ActionStep[],
+  address: Address,
+  ctx?: SignActionsContext
+): Promise<SignedActionStep[]> {
+  switch (method) {
+    case SigningMethod.WASM_BLOB:
+      return signWasmBlobActions(
+        deps,
+        address,
+        steps as WasmBlobActionStep[],
+        ctx
+      )
+    case SigningMethod.EVM_TX:
+      return signEvmTxActions(steps as EvmTxActionStep[], ctx)
+    case SigningMethod.EIP712:
+      throw new PerpsError(
+        PerpsErrorCode.SDKError,
+        'LighterProvider.signActions: Lighter declares no EIP712 actions.'
+      )
+    default:
+      throw new PerpsError(
+        PerpsErrorCode.SDKError,
+        `LighterProvider.signActions: unknown SigningMethod '${method as string}'.`
+      )
+  }
+}

package/src/signers/wasmLoader.ts

@@ -0,0 +1,293 @@
+// The Go runtime installs functions (SignCreateOrder, SignCancelOrder, etc.)
+// onto `globalThis` when `go.run(instance)` starts the main goroutine.
+//
+// The default asset URLs resolve relative to this module's emitted JS file:
+//   src/signers/../../wasm/lighter-signer.wasm     → package-root wasm/
+//   dist/{esm,cjs}/signers/../../wasm/…            → dist/wasm/ (shared)
+// The build script copies the wasm assets into both dist subtrees so the same
+// relative path resolves at runtime regardless of which bundle is loaded.
+//
+// To resolve the module's own URL in both ESM (where `__filename` is absent)
+// and CJS (where `import.meta.url` is a syntax error), we parse a stack trace
+// — `currentModuleUrl` always appears as the first frame, and V8 includes the
+// emitting file path regardless of module system. Callers can override both
+// asset URLs via {@link LoadLighterWasmOptions} to bypass this heuristic.
+
+function currentModuleUrl(): string {
+  const cjsFilename = (globalThis as { __filename?: string }).__filename
+  if (typeof cjsFilename === 'string' && cjsFilename.length > 0) {
+    return `file://${cjsFilename}`
+  }
+  const stack = new Error().stack ?? ''
+  // Stack frames look like one of:
+  //   "    at currentModuleUrl (file:///abs/path/wasmLoader.js:29:10)"
+  //   "    at currentModuleUrl (/abs/path/wasmLoader.js:29:10)"
+  //   "    at currentModuleUrl (file:///abs/path/wasmLoader.ts:29:10)"  (vitest)
+  //   "    at currentModuleUrl (http://localhost:5173/.../wasmLoader.ts?v=…:29:10)" (vite dev)
+  const match = stack.match(/\(([^)]+wasmLoader\.[tj]s[^)]*)\)/)
+  const frame = match?.[1] ?? ''
+  const withoutPos = frame.replace(/:\d+:\d+$/, '')
+  if (
+    withoutPos.startsWith('file://') ||
+    withoutPos.startsWith('http://') ||
+    withoutPos.startsWith('https://')
+  ) {
+    return withoutPos
+  }
+  if (withoutPos.length > 0) {
+    // Bare absolute path (Node CJS without `file://` prefix in some runners).
+    return `file://${withoutPos}`
+  }
+  throw new Error(
+    'Could not resolve the Lighter WASM loader module URL. Pass an explicit ' +
+      '`wasmBinaryUrl` and `wasmExecJsUrl` to loadLighterWasm().'
+  )
+}
+
+function defaultAssetUrl(filename: string): URL {
+  return new URL(`../../wasm/${filename}`, currentModuleUrl())
+}
+
+/** @public */
+export interface LoadLighterWasmOptions {
+  /** Override URL for the `.wasm` binary (browser: fetch; Node: fs). */
+  wasmBinaryUrl?: string | URL
+  /** Override URL for Go's `wasm_exec.js` runtime. */
+  wasmExecJsUrl?: string | URL
+  /**
+   * Pre-fetched source of Go's `wasm_exec.js`. Preferred over
+   * `wasmExecJsUrl` for bundlers (Vite/webpack) that may transform a `.js`
+   * URL on serve, breaking the IIFE that installs `globalThis.Go`. Pass via
+   * a `?raw` import (Vite) or equivalent so the original source survives
+   * intact.
+   */
+  wasmExecJsSource?: string
+}
+
+/** @public */
+export interface LighterWasmExports {
+  GenerateAPIKey: (seed?: string) => {
+    publicKey?: string
+    privateKey?: string
+    error?: string
+  }
+  CreateClient: (
+    url: string,
+    privateKey: string,
+    chainId: number,
+    apiKeyIndex: number,
+    accountIndex: number
+  ) => { error?: string }
+  CheckClient: (apiKeyIndex: number, accountIndex: number) => { error?: string }
+  /**
+   * Returns `{authToken}` on success — note the field name is `authToken`,
+   * NOT `token`. Reading the wrong field silently fails (Go sets nothing
+   * else on the result), which is why early code paths returned undefined
+   * tokens with no error.
+   */
+  CreateAuthToken: (
+    deadline: number,
+    apiKeyIndex: number,
+    accountIndex: number
+  ) => { authToken?: string; error?: string }
+  /**
+   * Signature mirrors lighter-python's `signer.SignChangePubKey(...)` call —
+   * 5 positional args including `skipNonce` (use 0 to embed our supplied
+   * nonce; 1 to leave it out for server-fill scenarios). Earlier versions
+   * here had only 4 args, which silently shifted all arguments by one and
+   * produced txInfo with garbage AccountIndex / ApiKeyIndex fields →
+   * Lighter rejected with code 20001 "invalid param".
+   */
+  SignChangePubKey: (
+    pubKeyHex: string,
+    skipNonce: number,
+    nonce: number,
+    apiKeyIndex: number,
+    accountIndex: number
+  ) => SignResult & { messageToSign?: string }
+  SignCreateOrder: (...args: unknown[]) => SignResult
+  SignCancelOrder: (...args: unknown[]) => SignResult
+  SignCancelAllOrders: (...args: unknown[]) => SignResult
+  SignTransfer: (...args: unknown[]) => SignResult
+  SignWithdraw: (...args: unknown[]) => SignResult
+  SignUpdateLeverage: (...args: unknown[]) => SignResult
+  SignModifyOrder: (...args: unknown[]) => SignResult
+  SignUpdateMargin: (...args: unknown[]) => SignResult
+}
+
+/** @internal */
+export interface SignResult {
+  txType?: number
+  txInfo?: string
+  txHash?: string
+  error?: string
+}
+
+const WASM_FUNCTION_NAMES = [
+  'GenerateAPIKey',
+  'CreateClient',
+  'CheckClient',
+  'CreateAuthToken',
+  'SignChangePubKey',
+  'SignCreateOrder',
+  'SignCancelOrder',
+  'SignCancelAllOrders',
+  'SignTransfer',
+  'SignWithdraw',
+  'SignUpdateLeverage',
+  'SignModifyOrder',
+  'SignUpdateMargin',
+] as const
+
+type GoClass = new () => {
+  importObject: WebAssembly.Imports
+  run(instance: WebAssembly.Instance): Promise<void>
+}
+
+let cachedExports: Promise<LighterWasmExports> | undefined
+
+// `node:fs/promises` and `node:url` are Node-only. Static imports force browser
+// bundlers (Vite/Rollup/esbuild) to resolve them up-front, which fails. Dynamic
+// `import('node:...')` lets bundlers leave the branch unreachable in browsers
+// while Node still resolves it at runtime when asked for a `file://` URL.
+async function readNodeFile(url: URL): Promise<Uint8Array> {
+  const [{ readFile }, { fileURLToPath }] = await Promise.all([
+    import(/* @vite-ignore */ 'node:fs/promises'),
+    import(/* @vite-ignore */ 'node:url'),
+  ])
+  return readFile(fileURLToPath(url))
+}
+
+/**
+ * Resolve a possibly-relative URL string against the current document/page
+ * origin. Bundlers like Vite hand out absolute paths (e.g. `/node_modules/…`)
+ * for `?url` imports, which `new URL(string)` rejects without a base.
+ */
+function toResolvedUrl(url: string | URL): URL {
+  if (url instanceof URL) {
+    return url
+  }
+  const base =
+    typeof globalThis !== 'undefined' &&
+    (globalThis as { location?: { href?: string } }).location?.href
+      ? (globalThis as { location: { href: string } }).location.href
+      : undefined
+  return new URL(url, base)
+}
+
+async function readUrlBytes(url: string | URL): Promise<ArrayBuffer> {
+  const u = toResolvedUrl(url)
+  if (u.protocol === 'file:') {
+    const buf = await readNodeFile(u)
+    // Copy the view into a fresh ArrayBuffer — `Buffer.buffer` is a shared
+    // ArrayBuffer in Node and the wasm instantiator expects a plain one.
+    return buf.slice().buffer as ArrayBuffer
+  }
+  const response = await fetch(u)
+  if (!response.ok) {
+    throw new Error(
+      `Failed to fetch ${u.href}: ${response.status} ${response.statusText}`
+    )
+  }
+  return response.arrayBuffer()
+}
+
+async function readUrlText(url: string | URL): Promise<string> {
+  const u = toResolvedUrl(url)
+  if (u.protocol === 'file:') {
+    const buf = await readNodeFile(u)
+    return new TextDecoder('utf-8').decode(buf)
+  }
+  const response = await fetch(u)
+  if (!response.ok) {
+    throw new Error(
+      `Failed to fetch ${u.href}: ${response.status} ${response.statusText}`
+    )
+  }
+  return response.text()
+}
+
+/**
+ * Load the Lighter WASM signer. Memoized per-process: subsequent calls return
+ * the cached exports. The Go runtime keeps a long-running goroutine to service
+ * JS calls — we start it once and never stop it.
+ * @public
+ */
+export async function loadLighterWasm(
+  options?: LoadLighterWasmOptions
+): Promise<LighterWasmExports> {
+  if (!cachedExports) {
+    cachedExports = loadWasmUncached(options)
+  }
+  return cachedExports
+}
+
+async function loadWasmUncached(
+  options?: LoadLighterWasmOptions
+): Promise<LighterWasmExports> {
+  const wasmBinaryUrl =
+    options?.wasmBinaryUrl ?? defaultAssetUrl('lighter-signer.wasm')
+
+  // Prefer a pre-fetched source string (bundler `?raw` imports) over a URL —
+  // bundlers may transform a `.js` URL on serve, breaking the IIFE that sets
+  // `globalThis.Go`.
+  const wasmExecSourcePromise: Promise<string> =
+    options?.wasmExecJsSource !== undefined
+      ? Promise.resolve(options.wasmExecJsSource)
+      : readUrlText(options?.wasmExecJsUrl ?? defaultAssetUrl('wasm_exec.js'))
+
+  const [wasmExecSource, wasmBytes] = await Promise.all([
+    wasmExecSourcePromise,
+    readUrlBytes(wasmBinaryUrl),
+  ])
+
+  // wasm_exec.js is an IIFE that installs `globalThis.Go = class { ... }` plus
+  // fs/process/crypto polyfills. Evaluate it in a Function scope so the class
+  // attaches to globalThis and we read it back from there.
+  const installGo = new Function(`${wasmExecSource}; return globalThis.Go`)
+  const Go = installGo() as GoClass
+
+  const go = new Go()
+  const { instance } = await WebAssembly.instantiate(wasmBytes, go.importObject)
+  // Start the Go goroutine — this never resolves until the Go main() returns,
+  // which our signer never does. Intentionally not awaited.
+  void go.run(instance)
+
+  // Wait microtasks to let Go's init() register JS-bound functions.
+  await yieldToGoRuntime()
+
+  const exports: Partial<LighterWasmExports> = {}
+  for (const name of WASM_FUNCTION_NAMES) {
+    const fn = (globalThis as Record<string, unknown>)[name]
+    if (typeof fn !== 'function') {
+      throw new Error(
+        `Lighter WASM did not export expected function: ${name}. ` +
+          'The .wasm binary may be stale or incompatible.'
+      )
+    }
+    ;(exports as Record<string, unknown>)[name] = fn
+  }
+
+  return exports as LighterWasmExports
+}
+
+async function yieldToGoRuntime(): Promise<void> {
+  for (let i = 0; i < 2; i++) {
+    await new Promise<void>((resolve) => {
+      if (typeof setImmediate === 'function') {
+        setImmediate(resolve)
+      } else {
+        setTimeout(resolve, 0)
+      }
+    })
+  }
+}
+
+/**
+ * Testing helper — drop the cached WASM instance so the next load reinitializes.
+ *
+ * @public
+ */
+export function resetLighterWasmCache(): void {
+  cachedExports = undefined
+}