@lifi/perps-sdk 0.1.1-alpha.9 → 0.2.0-alpha.0

package/src/signers/lighter/wasmLoader.ts

@@ -0,0 +1,291 @@
+// ---------------------------------------------------------------------------
+// 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/accountSummary.ts

@@ -0,0 +1,130 @@
+import type { AccountResponse, Asset, Position } from '@lifi/perps-types'
+import { HlAbstractionMode } from '@lifi/perps-types/providers/hyperliquid'
+import { stringToFloat } from './parse.js'
+
+export interface AccountSummary {
+  /** Total portfolio value in USD */
+  portfolioValue: number
+  /** Collateral available for new positions */
+  availableMargin: number
+  /** Margin locked in open positions */
+  marginUsed: number
+  /** Unrealized PnL across all positions */
+  unrealizedPnl: number
+}
+
+/**
+ * Build a map of coin name → USD price from spot assets and allMids.
+ * Spot assets have displaySymbol "BASE/QUOTE" and assetId "@N" which keys into prices.
+ */
+function buildSpotCoinPrices(
+  assets: Asset[],
+  prices: Record<string, string>
+): Map<string, number> {
+  const map = new Map<string, number>()
+  for (const asset of assets) {
+    if (asset.market !== 'spot') {
+      continue
+    }
+    const price = prices[asset.assetId]
+    if (!price) {
+      continue
+    }
+    const slashIdx = asset.displaySymbol.indexOf('/')
+    if (slashIdx < 0) {
+      continue
+    }
+    const base = asset.displaySymbol.slice(0, slashIdx)
+    map.set(base, stringToFloat(price))
+  }
+  return map
+}
+
+/**
+ * Resolve the USD price of a spot balance currency.
+ *
+ * Looks up the coin in the spot mid prices map first, then tries an exact
+ * match in allMids (e.g. a perps-listed stablecoin). Falls back to $1 for
+ * stablecoins with no market price entry.
+ */
+function getSpotPrice(
+  currency: string,
+  prices: Record<string, string>,
+  spotCoinPrices: Map<string, number>
+): number {
+  const spotPrice = spotCoinPrices.get(currency)
+  if (spotPrice !== undefined) {
+    return spotPrice
+  }
+  if (prices[currency] !== undefined) {
+    return stringToFloat(prices[currency])
+  }
+  return 1
+}
+
+const UNIFIED_STATUSES: ReadonlySet<string> = new Set([
+  HlAbstractionMode.UNIFIED_ACCOUNT,
+  HlAbstractionMode.PORTFOLIO_MARGIN,
+])
+
+export function calculateAccountSummary(
+  account: AccountResponse,
+  positions: Position[],
+  prices: Record<string, string>,
+  assets?: Asset[],
+  collateralCurrencies?: ReadonlySet<string>
+): AccountSummary {
+  let marginUsed = 0
+  let unrealizedPnl = 0
+  for (const p of positions) {
+    marginUsed += stringToFloat(p.marginUsed)
+    unrealizedPnl += stringToFloat(p.unrealizedPnl)
+  }
+
+  const spotCoinPrices = buildSpotCoinPrices(assets ?? [], prices)
+
+  // Split spot into margin-eligible (quote assets) and non-margin (HYPE, PURR etc.)
+  let spotMarginValue = 0
+  let spotNonMarginValue = 0
+  let perpsBalance = 0
+  for (const [key, entries] of Object.entries(account.balances)) {
+    if (key === 'spot') {
+      for (const b of entries) {
+        const value =
+          stringToFloat(b.amount) *
+          getSpotPrice(b.currency, prices, spotCoinPrices)
+        if (!collateralCurrencies || collateralCurrencies.has(b.currency)) {
+          spotMarginValue += value
+        } else {
+          spotNonMarginValue += value
+        }
+      }
+    } else {
+      for (const b of entries) {
+        perpsBalance += stringToFloat(b.amount)
+      }
+    }
+  }
+
+  // `abstractionMode` is HL-only; for any other provider variant (today
+  // Lighter) the unified-collateral semantics don't apply, so fall back
+  // to `undefined` and let the non-unified branch below run.
+  const status =
+    account.config.provider === 'hyperliquid'
+      ? (account.config.abstractionMode ?? undefined)
+      : undefined
+  const isUnified = UNIFIED_STATUSES.has(status ?? '')
+
+  // Unified: spot balances are total token holdings (margin is NOT subtracted).
+  // Disabled: perps venue balances are free margin (margin IS already subtracted).
+  const marginCollateral = isUnified
+    ? spotMarginValue + perpsBalance
+    : spotMarginValue + perpsBalance + marginUsed
+
+  return {
+    portfolioValue: marginCollateral + spotNonMarginValue + unrealizedPnl,
+    availableMargin: marginCollateral - marginUsed,
+    marginUsed,
+    unrealizedPnl,
+  }
+}

package/src/utils/assertNever.ts

@@ -0,0 +1,22 @@
+/**
+ * Exhaustiveness helper for discriminated-union switches.
+ *
+ * Use in the `default` arm of a `switch (discriminant)` block: TypeScript
+ * narrows the variable to `never` when every case is handled, so adding a
+ * new variant to the union without a corresponding `case` becomes a
+ * compile error here. At runtime — if reached — throw rather than return
+ * silently; the throw is unreachable in well-typed code but flags
+ * upstream-shape drift loudly.
+ *
+ * @example
+ *   switch (config.provider) {
+ *     case 'hyperliquid': return projectHyperliquid(config)
+ *     case 'lighter': return projectLighter(config)
+ *     default: return assertNever(config)
+ *   }
+ */
+export function assertNever(value: never): never {
+  throw new Error(
+    `Unreachable: exhaustiveness check failed for value ${JSON.stringify(value)}`
+  )
+}

package/src/utils/calculations.ts

@@ -0,0 +1,209 @@
+/**
+ * Universal perpetual futures calculation utilities.
+ *
+ * Pure functions for computing position-related values that any consumer
+ * of the perps SDK would need. All parameters are required — no default
+ * values for critical financial parameters.
+ */
+
+/**
+ * Calculate position size in asset units from margin.
+ *
+ * @param marginUsd - Margin amount in USD
+ * @param leverage - Position leverage
+ * @param price - Current asset price
+ * @returns Position size in asset units
+ */
+export function calculatePositionSize(
+  marginUsd: number,
+  leverage: number,
+  price: number
+): number {
+  return (marginUsd * leverage) / price
+}
+
+/**
+ * Calculate notional value of a position.
+ *
+ * @param size - Position size in asset units
+ * @param price - Current asset price
+ * @returns Notional value in USD
+ */
+export function calculateNotionalValue(size: number, price: number): number {
+  return Math.abs(size) * price
+}
+
+/**
+ * Calculate unrealized PnL.
+ *
+ * @param entryPrice - Position entry price
+ * @param currentPrice - Current market price
+ * @param size - Position size (positive for long, negative for short)
+ * @returns Unrealized PnL in USD
+ */
+export function calculateUnrealizedPnl(
+  entryPrice: number,
+  currentPrice: number,
+  size: number
+): number {
+  return (currentPrice - entryPrice) * size
+}
+
+/**
+ * Calculate return on equity (ROE) percentage.
+ *
+ * @param pnl - Profit/loss in USD
+ * @param margin - Initial margin in USD
+ * @returns ROE as percentage (e.g., 10 for 10%)
+ */
+export function calculateRoe(pnl: number, margin: number): number {
+  if (margin === 0) {
+    return 0
+  }
+  return (pnl / margin) * 100
+}
+
+/**
+ * Calculate required margin for a position.
+ *
+ * @param notionalValue - Position notional value in USD
+ * @param leverage - Position leverage
+ * @returns Required margin in USD
+ */
+export function calculateRequiredMargin(
+  notionalValue: number,
+  leverage: number
+): number {
+  return notionalValue / leverage
+}
+
+/**
+ * Estimate trading fees.
+ *
+ * @param sizeUsd - Position size in USD (notional value)
+ * @param feeRate - Fee rate as decimal (e.g., 0.00035 for 0.035%)
+ * @returns Estimated fee in USD
+ */
+export function estimateFees(sizeUsd: number, feeRate: number): number {
+  return sizeUsd * feeRate
+}
+
+/**
+ * Apply slippage to a price for order execution.
+ *
+ * @param price - Base price
+ * @param slippagePercent - Slippage tolerance as percentage (e.g., 0.5 for 0.5%)
+ * @param isBuy - True if buying (price goes up), false if selling (price goes down)
+ * @returns Price adjusted for slippage
+ */
+export function applySlippage(
+  price: number,
+  slippagePercent: number,
+  isBuy: boolean
+): number {
+  const multiplier = 1 + slippagePercent / 100
+  return isBuy ? price * multiplier : price / multiplier
+}
+
+// ---------------------------------------------------------------------------
+// TP/SL expected P&L calculations
+// ---------------------------------------------------------------------------
+
+export interface ExpectedPnl {
+  amount: number
+  percent: number
+}
+
+/**
+ * Calculate expected gain/loss for a TP or SL trigger price.
+ * Returns signed values — positive means profit, negative means loss.
+ *
+ * @param triggerPrice - The TP or SL target price
+ * @param entryPrice - Position entry / current market price
+ * @param leverage - Position leverage multiplier
+ * @param isLong - True for long positions, false for short
+ * @param margin - Margin amount in USD
+ */
+export function calculateExpectedPnl(
+  triggerPrice: number,
+  entryPrice: number,
+  leverage: number,
+  isLong: boolean,
+  margin: number
+): ExpectedPnl | null {
+  if (!triggerPrice || entryPrice === 0 || margin === 0) {
+    return null
+  }
+  const priceDiff = isLong
+    ? triggerPrice - entryPrice
+    : entryPrice - triggerPrice
+  const percent = (priceDiff / entryPrice) * leverage * 100
+  const amount = margin * (percent / 100)
+  return { amount, percent }
+}
+
+/**
+ * Convert a percentage gain/loss to a target price.
+ *
+ * @param percent - Target gain/loss percentage (positive = profitable direction)
+ * @param entryPrice - Position entry price
+ * @param leverage - Position leverage multiplier
+ * @param isLong - True for long positions, false for short
+ */
+export function priceFromPercent(
+  percent: number,
+  entryPrice: number,
+  leverage: number,
+  isLong: boolean
+): number {
+  if (entryPrice === 0 || leverage === 0) {
+    return 0
+  }
+  const priceDelta = (percent / 100 / leverage) * entryPrice
+  return isLong ? entryPrice + priceDelta : entryPrice - priceDelta
+}
+
+/**
+ * Convert a target price to a percentage gain/loss.
+ *
+ * @param price - Target price
+ * @param entryPrice - Position entry price
+ * @param leverage - Position leverage multiplier
+ * @param isLong - True for long positions, false for short
+ */
+export function percentFromPrice(
+  price: number,
+  entryPrice: number,
+  leverage: number,
+  isLong: boolean
+): number {
+  if (entryPrice === 0 || leverage === 0) {
+    return 0
+  }
+  const priceDiff = isLong ? price - entryPrice : entryPrice - price
+  return (priceDiff / entryPrice) * leverage * 100
+}
+
+// ---------------------------------------------------------------------------
+// Realized PnL percentage
+// ---------------------------------------------------------------------------
+
+/**
+ * Calculate realized PnL as a percentage of position value at close.
+ *
+ * @param realizedPnl - The realized profit/loss in USD
+ * @param size - Position size in asset units at close
+ * @param price - Price at close
+ * @returns PnL as a percentage of position value
+ */
+export function calculateRealizedPnlPercent(
+  realizedPnl: number,
+  size: number,
+  price: number
+): number {
+  const positionValue = Math.abs(size) * price
+  if (positionValue === 0) {
+    return 0
+  }
+  return (realizedPnl / positionValue) * 100
+}

package/src/utils/hyperliquid/index.ts

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