@lifi/perps-sdk 0.2.0-alpha.0 → 1.0.1

package/src/signers/lighter/wasmLoader.ts

@@ -1,291 +0,0 @@
-// ---------------------------------------------------------------------------
-// Lighter WASM loader
-//
-// Loads the Go-compiled `lighter-signer.wasm` and its companion `wasm_exec.js`
-// runtime. 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/lighter/../../../wasm/lighter-signer.wasm  → repo-root wasm/
-//   dist/{esm,cjs}/signers/lighter/../../../wasm/…         → dist/{esm,cjs}/wasm/
-//
-// 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())
-}
-
-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
-}
-
-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
-}
-
-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.
- */
-export async function loadLighterWasm(
-  options?: LoadLighterWasmOptions
-): Promise<LighterWasmExports> {
-  if (!cachedExports) {
-    cachedExports = doLoad(options)
-  }
-  return cachedExports
-}
-
-async function doLoad(
-  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. */
-export function resetLighterWasmCache(): void {
-  cachedExports = undefined
-}

package/src/utils/hyperliquid/index.ts

@@ -1,9 +0,0 @@
-export {
-  calculateLiquidationPrice,
-  calculateMaintenanceMarginRate,
-} from './liquidation.js'
-export {
-  formatOrderPrice,
-  formatOrderSize,
-  getMaxPriceDecimals,
-} from './orderFormatting.js'

package/src/utils/hyperliquid/liquidation.ts

@@ -1,71 +0,0 @@
-/**
- * Hyperliquid-specific liquidation price calculation.
- *
- * Uses the exact formula from Hyperliquid docs:
- * https://hyperliquid.gitbook.io/hyperliquid-docs/trading/liquidations
- *
- * liq_price = price - side * margin_available / position_size / (1 - l * side)
- *
- * Where:
- * - l = 1 / (2 * maxLeverage) (maintenance margin fraction)
- * - side = 1 (long) or -1 (short)
- * - margin_available = isolated_margin - maintenance_margin_required
- */
-
-/**
- * Calculate the maintenance margin fraction for a Hyperliquid asset.
- *
- * Maintenance margin is half of the initial margin at max leverage.
- *
- * @param maxLeverage - Maximum leverage for the asset (e.g., 50 for BTC)
- * @returns Maintenance margin fraction (e.g., 0.01 for 50x max leverage),
- *   or undefined if maxLeverage is zero
- */
-export function calculateMaintenanceMarginRate(
-  maxLeverage: number
-): number | undefined {
-  if (maxLeverage === 0) {
-    return undefined
-  }
-  return 1 / (2 * maxLeverage)
-}
-
-/**
- * Calculate liquidation price using the exact Hyperliquid formula.
- *
- * For isolated margin, new position prediction. For existing positions,
- * prefer Position.liquidationPrice from the API.
- *
- * Formula derivation (isolated margin, single position):
- *   margin_per_unit        = entryPrice / leverage
- *   maintenance_per_unit   = entryPrice * mmr
- *   margin_available       = margin_per_unit - maintenance_per_unit
- *   liq_price              = entryPrice - side * margin_available / (1 - mmr * side)
- *
- * Where mmr = 1 / (2 * maxLeverage).
- *
- * @param entryPrice - Position entry price
- * @param leverage - User-selected leverage (e.g., 10)
- * @param isLong - True if long position, false if short
- * @param maxLeverage - Asset's maximum leverage (e.g., 50 for BTC). Determines
- *   the maintenance margin rate: mmr = 1 / (2 * maxLeverage)
- * @returns Estimated liquidation price, or undefined if inputs are invalid
- */
-export function calculateLiquidationPrice(
-  entryPrice: number,
-  leverage: number,
-  isLong: boolean,
-  maxLeverage: number
-): number | undefined {
-  if (leverage === 0 || maxLeverage === 0) {
-    return undefined
-  }
-  const mmr = 1 / (2 * maxLeverage)
-  const side = isLong ? 1 : -1
-  const denominator = 1 - mmr * side
-  if (denominator === 0) {
-    return undefined
-  }
-  const marginAvailable = entryPrice * (1 / leverage - mmr)
-  return entryPrice - (side * marginAvailable) / denominator
-}

package/src/utils/hyperliquid/orderFormatting.ts

@@ -1,96 +0,0 @@
-/**
- * Hyperliquid order size and price formatting for exchange submission.
- *
- * These encode Hyperliquid-specific order submission rules. Getting size/price
- * formatting wrong causes rejected orders.
- *
- * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/tick-and-lot-size
- */
-
-import { stringToFloat } from '../parse.js'
-
-/**
- * Max combined decimals (size + price) enforced by Hyperliquid.
- * Perps: 6, Spot: 8
- */
-const MAX_DECIMALS_PERPS = 6
-const MAX_DECIMALS_SPOT = 8
-
-function getMaxDecimals(market?: string): number {
-  return market === 'spot' ? MAX_DECIMALS_SPOT : MAX_DECIMALS_PERPS
-}
-
-/**
- * Derive the maximum number of price decimal places for a given asset.
- *
- * @param szDecimals - The asset's szDecimals (from market meta)
- * @param market - Optional market type (e.g. 'spot'). Defaults to perps rules.
- * @returns Maximum allowed price decimals
- */
-export function getMaxPriceDecimals(
-  szDecimals: number,
-  market?: string
-): number {
-  return Math.max(0, getMaxDecimals(market) - szDecimals)
-}
-
-/**
- * Format a size value for order submission.
- *
- * Per Hyperliquid docs (tick-and-lot-size):
- * - Size must be rounded to the asset's szDecimals
- * - Trailing zeroes must be removed for signing
- *
- * @param size - The size value to format
- * @param szDecimals - Number of decimal places allowed for this asset (from meta)
- * @returns Size as a string with correct precision, no trailing zeros
- */
-export function formatOrderSize(size: number, szDecimals: number): string {
-  // Truncate (don't round up) to avoid exceeding available balance
-  const multiplier = 10 ** szDecimals
-  const truncated = Math.floor(size * multiplier) / multiplier
-  // Remove trailing zeros by round-tripping through stringToFloat
-  return stringToFloat(truncated.toFixed(szDecimals)).toString()
-}
-
-/**
- * Format a price value for order submission.
- *
- * Per Hyperliquid docs (tick-and-lot-size):
- * - Maximum 5 significant figures
- * - Max decimals = MAX_DECIMALS - szDecimals (6 for perps, 8 for spot)
- * - Integer prices always allowed regardless of significant figures
- * - Trailing zeroes must be removed for signing
- *
- * @param price - The price value to format
- * @param szDecimals - The asset's szDecimals (affects max price decimals)
- * @param market - Optional market type (e.g. 'spot'). Defaults to perps rules.
- * @returns Price as a string with correct precision, no trailing zeros
- */
-export function formatOrderPrice(
-  price: number,
-  szDecimals: number,
-  market?: string
-): string {
-  const maxPriceDecimals = getMaxPriceDecimals(szDecimals, market)
-
-  // Round to max allowed decimals
-  let rounded = stringToFloat(price.toFixed(maxPriceDecimals))
-
-  // Integer prices are always allowed regardless of significant figures
-  if (Number.isInteger(rounded)) {
-    return rounded.toString()
-  }
-
-  // Count significant figures (digits excluding leading zeros)
-  const absStr = Math.abs(rounded).toString().replace('.', '')
-  const sigFigs = absStr.replace(/^0+/, '').length
-
-  // If more than 5 significant figures, round to 5
-  if (sigFigs > 5) {
-    rounded = stringToFloat(rounded.toPrecision(5))
-  }
-
-  // Return without trailing zeros
-  return rounded.toString()
-}