dsh-hyperliquid 0.0.1 → 0.2.0

package/lib/hl.js

@@ -0,0 +1,372 @@
+// lib/hl.js — Hyperliquid market-data layer, SDK-backed.
+//
+// Data plane (info + WS) runs on the community-standard TypeScript SDK
+// `@nktkas/hyperliquid` (MIT): HttpTransport for /info requests and
+// WebSocketTransport + SubscriptionClient for live channels. The SDK brings
+// schema-validated requests, automatic reconnection and automatic
+// re-subscription after reconnect — the three things the previous hand-rolled
+// wire layer lacked.
+//
+// The execution plane (/exchange) stays on our own EIP-712 signing
+// implementation (lib/signing.js), which is byte-for-byte validated against
+// the official hyperliquid-python-sdk (see test/signing.test.mjs).
+//
+// Public surface (consumed by lib/remote.js): HyperliquidClient, keys, sigFigs.
+// Snapshot keys and payload shapes are unchanged, so the remote layer and the
+// web desk are source-compatible.
+
+import { canonicalAction, signL1Action } from './signing.js'
+
+const MAINNET = 'https://api.hyperliquid.xyz'
+const TESTNET = 'https://api.hyperliquid-testnet.xyz'
+const WS_MAINNET = 'wss://api.hyperliquid.xyz/ws'
+const WS_TESTNET = 'wss://api.hyperliquid-testnet.xyz/ws'
+
+function quietUnsubscribe(channel) {
+  try { Promise.resolve(channel?.unsubscribe()).catch(() => {}) }
+  catch { /* transport already closing */ }
+}
+
+/** Round to `maxDecimals` with at most `n` significant figures. */
+export function sigFigs(value, n, maxDecimals) {
+  const num = Number(value)
+  if (!Number.isFinite(num) || num === 0) return '0'
+  const abs = Math.abs(num)
+  const digits = Math.floor(Math.log10(abs)) + 1
+  const decimals = Math.max(0, Math.min(maxDecimals, n - digits))
+  return num.toFixed(decimals)
+}
+
+async function postJson(url, body, timeoutMs = 10_000) {
+  const ac = new AbortController()
+  const timer = setTimeout(() => ac.abort(new Error('timeout')), timeoutMs)
+  try {
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+      signal: ac.signal,
+    })
+    const data = await res.json().catch(() => null)
+    if (!res.ok) throw new Error(`HTTP ${res.status}: ${JSON.stringify(data)?.slice(0, 300)}`)
+    return data
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/**
+ * One Hyperliquid endpoint pair (REST + WS) with snapshot caches.
+ * The trading desk instantiates exactly one; clients poll snapshots from it.
+ *
+ * Live channels are ref-counted: remote.js calls subscribe(key)/unsubscribe(key)
+ * as coins gain/lose focus; every callback just refreshes the snapshot map.
+ */
+export class HyperliquidClient {
+  /**
+   * @param {{network?: 'mainnet'|'testnet', privateKey?: string}} opts
+   */
+  constructor(opts = {}) {
+    this.network = opts.network === 'mainnet' ? 'mainnet' : 'testnet'
+    this.restBase = this.network === 'mainnet' ? MAINNET : TESTNET
+    this.wsBase = this.network === 'mainnet' ? WS_MAINNET : WS_TESTNET
+    this.privateKey = opts.privateKey ?? ''
+    // A signer must never reuse a nonce, including concurrent order/cancel calls.
+    this.lastNonce = 0
+
+    // ── SDK transports (lazy: nothing connects until first use) ──
+    this._sdk = null // { HttpTransport, WebSocketTransport, SubscriptionClient, info: {...fns} }
+    this._http = null
+    this._wsTransport = null
+    this._subsClient = null
+    this._liveSubs = new Map() // snapshot key -> ISubscription
+
+    this.ws = null // legacy compat field (unused by the SDK path)
+    this.wsState = 'closed' // closed | idle | connecting | open
+    this.subs = new Map() // key -> {args, listeners:number}
+    this.snapshots = new Map() // key -> latest payload
+    this.snapshotTimes = new Map() // key -> last exchange message received on host
+    this.seqs = new Map() // key -> monotonically increasing revision
+    this.throws = 0
+    this.lastWsError = null
+    this.pingTimer = null // legacy compat (SDK keep-alive handles ping)
+    this.retryTimers = new Map() // failed channel key -> retry timer
+  }
+
+  // ── SDK bootstrap ────────────────────────────────────────────────────
+  _sdkOnce() {
+    if (this._sdk) return this._sdk
+    // Plain dynamic imports keep the SDK optional at parse time and let the
+    // desk degrade to REST-only polling if the package is unavailable.
+    const root = '@nktkas/hyperliquid'
+    const infoApi = `${root}/api/info`
+    const subApi = `${root}/api/subscription`
+    // Deliberately not awaited: transports are created eagerly-ish but callers
+    // await the individual request methods, which await their modules.
+    this._sdk = Promise.all([import(root), import(infoApi), import(subApi)]).then(([r, i, s]) => {
+      this._http = new r.HttpTransport({ isTestnet: this.network !== 'mainnet' })
+      const cfg = { transport: this._http }
+      this._sdkInfo = {
+        meta: () => i.meta(cfg),
+        metaAndAssetCtxs: () => i.metaAndAssetCtxs(cfg),
+        allMids: () => i.allMids(cfg),
+        l2Book: (coin, grouping = null) => i.l2Book(cfg, { coin, ...(grouping ?? {}) }),
+        candleSnapshot: (coin, interval, startTime, endTime) => i.candleSnapshot(cfg, { coin, interval, startTime, endTime }),
+        clearinghouseState: (user) => i.clearinghouseState(cfg, { user }),
+        spotClearinghouseState: (user) => i.spotClearinghouseState(cfg, { user }),
+        userAbstraction: (user) => i.userAbstraction(cfg, { user }),
+        activeAssetData: (user, coin) => i.activeAssetData(cfg, { user, coin }),
+        openOrders: (user) => i.openOrders(cfg, { user }),
+        frontendOpenOrders: (user) => i.frontendOpenOrders(cfg, { user }),
+        userFills: (user) => i.userFills(cfg, { user }),
+        historicalOrders: (user) => i.historicalOrders(cfg, { user }),
+        portfolio: (user) => i.portfolio(cfg, { user }),
+      }
+      this._wsTransport = new r.WebSocketTransport({ url: this.wsBase })
+      this._subsClient = new r.SubscriptionClient({ transport: this._wsTransport })
+      // Connection bookkeeping: the transport's event target carries the
+      // system events; ready() resolves once the socket is up.
+      const hlEvents = this._wsTransport._hlEvents
+      hlEvents?.addEventListener?.('error', (ev) => {
+        this.lastWsError = ev?.detail ?? 'ws error'
+        this.wsState = 'connecting'
+      })
+      hlEvents?.addEventListener?.('subscriptionResponse', () => {
+        // Unsubscribe acks arrive here too; with no channels left we are idle.
+        if (this.wsState !== 'closed') this.wsState = this.subs.size ? 'open' : 'idle'
+      })
+      // The SDK socket reconnects and resubscribes on its own; mirror that so
+      // a dropped upstream reads as "connecting" rather than a silent "open".
+      const socket = this._wsTransport.socket
+      socket?.addEventListener?.('close', () => { if (this.wsState !== 'closed') this.wsState = 'connecting' })
+      socket?.addEventListener?.('open', () => { if (this.wsState === 'connecting') this.wsState = this.subs.size ? 'open' : 'idle' })
+      Promise.resolve(this._wsTransport.ready?.()).then(() => {
+        this.wsState = 'open'
+      }).catch((err) => {
+        this.lastWsError = String(err?.message ?? err)
+      })
+      return this._sdkInfo
+    })
+    return this._sdk
+  }
+
+  _infoFns() {
+    return this._sdkOnce().then((fns) => {
+      if (!fns) throw new Error('SDK 初始化失败（@nktkas/hyperliquid 不可用）')
+      return fns
+    })
+  }
+
+  // ── /info ────────────────────────────────────────────────────────────
+  /** Generic /info passthrough with a timeout. `type` values per docs. */
+  info(type, extra = {}, timeoutMs = 10_000) {
+    return postJson(`${this.restBase}/info`, { type, ...extra }, timeoutMs)
+  }
+
+  async meta() { return (await this._infoFns()).meta() }
+  async metaAndAssetCtxs() { return (await this._infoFns()).metaAndAssetCtxs() }
+  async allMids() { return (await this._infoFns()).allMids() }
+  async l2Book(coin, grouping = null) { return (await this._infoFns()).l2Book(coin, grouping) }
+  recentTrades(coin) { return this.info('recentTrades', { coin }) }
+  async candleSnapshot(coin, interval, startTime, endTime) {
+    return (await this._infoFns()).candleSnapshot(coin, interval, startTime, endTime)
+  }
+  async clearinghouseState(user) { return (await this._infoFns()).clearinghouseState(user) }
+  async spotClearinghouseState(user) { return (await this._infoFns()).spotClearinghouseState(user) }
+  async userAbstraction(user) { return (await this._infoFns()).userAbstraction(user) }
+  async activeAssetData(user, coin) { return (await this._infoFns()).activeAssetData(user, coin) }
+  async openOrders(user) { return (await this._infoFns()).openOrders(user) }
+  async frontendOpenOrders(user) { return (await this._infoFns()).frontendOpenOrders(user) }
+  async userFills(user) { return (await this._infoFns()).userFills(user) }
+  async historicalOrders(user) { return (await this._infoFns()).historicalOrders(user) }
+  async portfolio(user) { return (await this._infoFns()).portfolio(user) }
+
+  // ── /exchange ────────────────────────────────────────────────────────
+  /**
+   * Send a signed exchange action. Paper mode never reaches here.
+   * Execution stays on our validated EIP-712 path (lib/signing.js).
+   * @param {object} action L1 action body, e.g. {type:'order', orders:[…], grouping:'na'}
+   */
+  async exchange(action) {
+    if (!this.privateKey) throw new Error('未配置钱包私钥（插件 config.privateKey）；paper 模式下单不经过 /exchange')
+    const nonce = this.nextNonce()
+    const canonical = canonicalAction(action)
+    const signature = await signL1Action(this.privateKey, canonical, null, nonce, this.network === 'mainnet')
+    return postJson(`${this.restBase}/exchange`, { action: canonical, nonce, signature }, 15_000)
+  }
+
+  nextNonce() {
+    this.lastNonce = Math.max(Date.now(), this.lastNonce + 1)
+    return this.lastNonce
+  }
+
+  /**
+   * Send an exchange action with an EXTERNALLY produced signature — the
+   * dsh-web3 path: the private key never leaves the wallet vault, this
+   * client only transports the already-signed envelope.
+   * @param {object} action L1 action body
+   * @param {{r: string, s: string, v: number}} signature wire-form signature
+   * @param {number} nonce the nonce that was hashed into the signature
+   */
+  exchangeSigned(action, signature, nonce) {
+    if (!signature?.r || !signature?.s || !signature?.v) throw new Error('exchangeSigned 需要完整的 {r,s,v} 签名')
+    return postJson(`${this.restBase}/exchange`, { action: canonicalAction(action), nonce, signature }, 15_000)
+  }
+
+  // ── WebSocket upstream (SDK SubscriptionClient) ──────────────────────
+  /** Map a snapshot key to a SubscriptionClient channel; resolve its ISubscription. */
+  async _openChannel(key, args) {
+    await this._infoFns()
+    this.wsState = 'connecting'
+    const sc = this._subsClient
+    const feed = (payload) => {
+      this.snapshots.set(key, payload)
+      this.snapshotTimes.set(key, Date.now())
+      this.seqs.set(key, (this.seqs.get(key) ?? 0) + 1)
+      this.wsState = 'open'
+    }
+    switch (args?.type) {
+      case 'allMids':
+        return sc.allMids((ev) => feed(ev?.detail ?? ev))
+      case 'allDexsAssetCtxs':
+        return sc.allDexsAssetCtxs((ev) => feed(ev?.detail ?? ev))
+      case 'allDexsClearinghouseState':
+        return sc.allDexsClearinghouseState({ user: args.user }, (ev) => feed(ev?.detail ?? ev))
+      case 'l2Book':
+        return sc.l2Book({ coin: args.coin, ...(args.nSigFigs ? { nSigFigs: args.nSigFigs, ...(args.mantissa ? { mantissa: args.mantissa } : {}) } : {}) }, (ev) => feed(ev?.detail ?? ev))
+      case 'trades':
+        return sc.trades({ coin: args.coin }, (ev) => feed(ev?.detail ?? ev))
+      case 'candle':
+        return sc.candle({ coin: args.coin, interval: args.interval }, (ev) => feed(ev?.detail ?? ev))
+      case 'userFills':
+        return sc.userFills({ user: args.user }, (ev) => feed(ev?.detail ?? ev))
+      case 'userEvents':
+        return sc.userEvents({ user: args.user }, (ev) => feed(ev?.detail ?? ev))
+      default:
+        throw new Error(`unknown subscription type: ${args?.type}`)
+    }
+  }
+
+  /**
+   * Register interest in a WS channel; ref-counted. Returns the snapshot key.
+   * Supported: allMids | allDexsAssetCtxs | {allDexsClearinghouseState, user} | {l2Book, coin} | {trades, coin} | {candle, coin, interval}
+   *            | {userFills, user} | {userEvents, user}
+   */
+  subscribe(key, args) {
+    const row = this.subs.get(key) ?? { args, listeners: 0, channel: null, opening: false }
+    row.listeners += 1
+    this.subs.set(key, row)
+    if (!row.channel && !row.opening) {
+      row.opening = true
+      this._openChannel(key, args)
+        .then((sub) => {
+          row.channel = sub
+          row.opening = false
+          this.wsState = 'open'
+          if (row.listeners <= 0) {
+            // Interest went away while the channel was opening.
+            quietUnsubscribe(sub)
+            row.channel = null
+            this.subs.delete(key)
+            this.snapshots.delete(key)
+            this.snapshotTimes.delete(key)
+          }
+        })
+        .catch((err) => {
+          row.opening = false
+          this.lastWsError = String(err?.message ?? err)
+          if (row.listeners > 0) this._retryChannel(key)
+        })
+    }
+    return key
+  }
+
+  _retryChannel(key) {
+    if (this.retryTimers.has(key)) return
+    const timer = setTimeout(() => {
+      this.retryTimers.delete(key)
+      const row = this.subs.get(key)
+      if (row && row.listeners > 0 && !row.channel && !row.opening) {
+        row.opening = true
+        this._openChannel(key, row.args)
+          .then((sub) => {
+            row.opening = false
+            if (row.listeners <= 0) { quietUnsubscribe(sub); this.subs.delete(key); return }
+            row.channel = sub
+            this.wsState = 'open'
+          })
+          .catch((err) => {
+            row.opening = false
+            this.lastWsError = String(err?.message ?? err)
+            if (row.listeners > 0) this._retryChannel(key)
+          })
+      }
+    }, 3_000)
+    this.retryTimers.set(key, timer)
+  }
+
+  unsubscribe(key) {
+    const row = this.subs.get(key)
+    if (!row) return
+    row.listeners -= 1
+    if (row.listeners <= 0) {
+      if (row.channel) {
+        quietUnsubscribe(row.channel)
+        row.channel = null
+      }
+      this.subs.delete(key)
+      this.snapshots.delete(key)
+      this.snapshotTimes.delete(key)
+      const timer = this.retryTimers.get(key)
+      if (timer) clearTimeout(timer)
+      this.retryTimers.delete(key)
+      // The upstream socket stays connected (SDK keep-alive); only channels went away.
+      if (this.subs.size === 0 && this.wsState !== 'closed') this.wsState = 'idle'
+    }
+  }
+
+  snapshot(key) {
+    const snap = this.snapshots.get(key)
+    const seq = this.seqs.get(key) ?? 0
+    return snap === undefined ? null : { seq, at: this.snapshotTimes.get(key) ?? 0, data: snap }
+  }
+
+  wsStatus() {
+    const lastDataAt = Math.max(0, ...this.snapshotTimes.values())
+    const state = this.wsState === 'open' && lastDataAt > 0 && Date.now() - lastDataAt > 15_000
+      ? 'stale' : this.wsState
+    return { state, lastDataAt, subs: [...this.subs.keys()], lastError: this.lastWsError }
+  }
+
+  close() {
+    for (const timer of this.retryTimers.values()) clearTimeout(timer)
+    this.retryTimers.clear()
+    for (const [key, row] of this.subs) {
+      if (row.channel) {
+        quietUnsubscribe(row.channel)
+        row.channel = null
+      }
+      row.listeners = 0
+    }
+    this.subs.clear()
+    this.snapshots.clear()
+    this.snapshotTimes.clear()
+    try { this._wsTransport?.close?.() } catch { /* already closed */ }
+    this.wsState = 'closed'
+    this.ws = null
+  }
+}
+
+/** Canonical snapshot key builders shared with the remote layer. */
+export const keys = {
+  allMids: () => 'allMids',
+  allDexsAssetCtxs: () => 'allDexsAssetCtxs',
+  allDexsClearinghouseState: (user) => `allDexsClearinghouseState:${user.toLowerCase()}`,
+  l2Book: (coin, grouping = null) => grouping
+    ? `l2BookGrouped:${encodeURIComponent(coin)}:${grouping.nSigFigs}:${grouping.mantissa ?? 0}`
+    : `l2Book:${coin}`,
+  trades: (coin) => `trades:${coin}`,
+  candle: (coin, interval) => `candle:${coin}:${interval}`,
+  userEvents: () => 'userEvents',
+  userFills: (user) => `userFills:${user}`,
+}

package/lib/indicators.js

@@ -0,0 +1,93 @@
+/** Deterministic indicators over exchange candles; no price prediction. */
+
+function sma(values, period) {
+  if (values.length < period) return null
+  return values.slice(-period).reduce((sum, value) => sum + value, 0) / period
+}
+
+function emaSeries(values, period) {
+  if (values.length < period) return []
+  const alpha = 2 / (period + 1)
+  let value = values.slice(0, period).reduce((sum, point) => sum + point, 0) / period
+  const result = [value]
+  for (const point of values.slice(period)) {
+    value = point * alpha + value * (1 - alpha)
+    result.push(value)
+  }
+  return result
+}
+
+function wilder(values, period) {
+  if (values.length < period) return null
+  let result = values.slice(0, period).reduce((sum, value) => sum + value, 0) / period
+  for (const value of values.slice(period)) result = (result * (period - 1) + value) / period
+  return result
+}
+
+function swings(rows, kind) {
+  const picks = []
+  for (let i = 2; i < rows.length - 2; i += 1) {
+    const field = kind === 'low' ? 'l' : 'h'
+    const value = rows[i][field]
+    const neighbors = [rows[i - 2][field], rows[i - 1][field], rows[i + 1][field], rows[i + 2][field]]
+    if (neighbors.every((point) => kind === 'low' ? value <= point : value >= point)) picks.push({ price: value, time: rows[i].t })
+  }
+  return picks
+}
+
+function closeTime(row, interval) {
+  if (Number.isFinite(Number(row.T)) && Number(row.T) >= row.t) return Number(row.T)
+  if (interval === '1M') {
+    const opened = new Date(row.t)
+    return Date.UTC(opened.getUTCFullYear(), opened.getUTCMonth() + 1, 1) - 1
+  }
+  const minutes = { '1m': 1, '3m': 3, '5m': 5, '15m': 15, '30m': 30, '1h': 60, '2h': 120,
+    '4h': 240, '8h': 480, '12h': 720, '1d': 1440, '3d': 4320, '1w': 10080 }[interval]
+  return minutes ? row.t + minutes * 60_000 - 1 : row.t
+}
+
+/** Valid, de-duplicated, ascending candles split into closed rows and the count of still-forming ones. */
+export function closedCandles(candles, { now = Date.now(), interval } = {}) {
+  const valid = (candles ?? []).map((c) => ({ t: Number(c.t), T: c.T, o: Number(c.o), h: Number(c.h), l: Number(c.l), c: Number(c.c), v: Number(c.v) }))
+    .filter((c) => [c.t, c.o, c.h, c.l, c.c, c.v].every(Number.isFinite) && c.t > 0 && c.h >= c.l && c.c > 0)
+    .sort((a, b) => a.t - b.t)
+  const unique = [...new Map(valid.map((row) => [row.t, row])).values()]
+  const rows = unique.filter((row) => closeTime(row, interval) < now)
+  return { rows, excludedOpen: unique.length - rows.length, closeTime: (row) => closeTime(row, interval) }
+}
+
+export function computeIndicators(candles, { now = Date.now(), interval } = {}) {
+  const { rows, excludedOpen } = closedCandles(candles, { now, interval })
+  if (rows.length < 50) return { ready: false, candlesUsed: rows.length, excludedOpen, reason: '至少需要 50 根已收盘的有效 K 线' }
+  const close = rows.map((c) => c.c)
+  const volume = rows.map((c) => c.v)
+  const ema12 = emaSeries(close, 12)
+  const ema26 = emaSeries(close, 26)
+  const macdLine = ema12.slice(14).map((value, i) => value - ema26[i])
+  const signal = emaSeries(macdLine, 9)
+  const deltas = close.slice(1).map((value, i) => value - close[i])
+  const avgGain = wilder(deltas.map((value) => Math.max(value, 0)), 14)
+  const avgLoss = wilder(deltas.map((value) => Math.max(-value, 0)), 14)
+  const rsi = avgLoss === 0 ? (avgGain === 0 ? 50 : 100) : 100 - 100 / (1 + avgGain / avgLoss)
+  const trueRanges = rows.slice(1).map((c, i) => Math.max(c.h - c.l, Math.abs(c.h - rows[i].c), Math.abs(c.l - rows[i].c)))
+  const atr14 = wilder(trueRanges, 14)
+  const close20 = close.slice(-20)
+  const mean20 = sma(close, 20)
+  const deviation = Math.sqrt(close20.reduce((sum, value) => sum + (value - mean20) ** 2, 0) / 20)
+  const latest = rows.at(-1)
+  const recent = rows.slice(-100)
+  const supportFallback = rows.slice(-20).reduce((best, row) => row.l < best.l ? row : best)
+  const resistanceFallback = rows.slice(-20).reduce((best, row) => row.h > best.h ? row : best)
+  const support = swings(recent, 'low').filter((point) => point.price < latest.c).sort((a, b) => b.price - a.price)[0]
+    ?? { price: supportFallback.l, time: supportFallback.t }
+  const resistance = swings(recent, 'high').filter((point) => point.price > latest.c).sort((a, b) => a.price - b.price)[0]
+    ?? { price: resistanceFallback.h, time: resistanceFallback.t }
+  return {
+    ready: true, candlesUsed: rows.length, excludedOpen, observedAt: closeTime(latest, interval), candleOpenedAt: latest.t, close: latest.c,
+    sma20: mean20, ema20: emaSeries(close, 20).at(-1), ema50: emaSeries(close, 50).at(-1),
+    rsi14: rsi, macd: { line: macdLine.at(-1), signal: signal.at(-1), histogram: macdLine.at(-1) - signal.at(-1) },
+    bollinger20: { lower: mean20 - 2 * deviation, middle: mean20, upper: mean20 + 2 * deviation },
+    atr14, volumeRatio20: latest.v / (sma(volume.slice(0, -1), 20) || 1),
+    support, resistance,
+  }
+}

package/lib/market-symbol.js

@@ -0,0 +1,5 @@
+/** Known legacy/display names that are not valid Hyperliquid API coin names. */
+export function canonicalMarketCoin(value) {
+  const coin = String(value ?? '').trim()
+  return coin === 'xyz:100' || coin === 'XYZ100' ? 'xyz:XYZ100' : coin
+}

package/lib/moving-average.d.ts

@@ -0,0 +1,21 @@
+export type MaKind = 'sma' | 'ema' | 'smma' | 'wma'
+export type MaSource = 'close' | 'open' | 'high' | 'low' | 'hl2' | 'hlc3' | 'ohlc4'
+export interface MaLine {
+  id: string
+  kind: MaKind
+  period: number
+  source: MaSource
+  smoothing: { kind: MaKind; period: number } | null
+  color?: string
+}
+export interface MaCandle { o: number; h: number; l: number; c: number }
+export declare const MA_KINDS: MaKind[]
+export declare const MA_SOURCES: MaSource[]
+export declare const MA_MAX_LINES: number
+export declare const MA_MAX_PERIOD: number
+export declare function normalizeMaLine(input: unknown): MaLine
+export declare function normalizeMaLines(list: unknown): MaLine[]
+export declare function maLabel(line: MaLine): string
+export declare function movingAverage(values: Array<number | null>, kind: MaKind, period: number): Array<number | null>
+export declare function maSeries(candles: MaCandle[], line: MaLine): { values: Array<number | null>; smoothed: Array<number | null> | null }
+export declare function maLatest(candles: MaCandle[], lines: MaLine[]): Array<{ id: string; label: string; value: number | null; smoothed: number | null; line: MaLine }>

package/lib/moving-average.js

@@ -0,0 +1,133 @@
+/**
+ * dsh-hyperliquid — configurable moving-average lines, shared by the host
+ * (hyper_market / hyper_chart) and the browser chart so both compute the
+ * exact same values.
+ *
+ * Definitions follow TradingView Pine:
+ *   SMA   ta.sma   arithmetic mean of the last n values
+ *   EMA   ta.ema   alpha = 2/(n+1), seeded with the SMA of the first n values
+ *   SMMA  ta.rma   alpha = 1/n (Wilder / smoothed MA), seeded with the SMA
+ *   WMA   ta.wma   linear weights n, n-1, …, 1 (newest heaviest)
+ * An optional smoothing applies a second MA to the first line, like the
+ * "Smoothing" setting of TradingView's moving-average indicators.
+ * @module lib/moving-average
+ */
+
+export const MA_KINDS = ['sma', 'ema', 'smma', 'wma']
+export const MA_SOURCES = ['close', 'open', 'high', 'low', 'hl2', 'hlc3', 'ohlc4']
+export const MA_MAX_LINES = 8
+export const MA_MAX_PERIOD = 500
+const COLOR = /^#[0-9a-fA-F]{6}$/
+
+/**
+ * Validate and canonicalize one line definition (throws on invalid input).
+ * @param {object} input - { kind, period, source?, smoothing?: { kind, period }, color? }
+ * @returns {{ id: string, kind: string, period: number, source: string, smoothing: { kind: string, period: number } | null, color?: string }}
+ */
+export function normalizeMaLine(input) {
+  if (!input || typeof input !== 'object') throw new Error('均线定义无效')
+  const kind = String(input.kind ?? '').toLowerCase()
+  if (!MA_KINDS.includes(kind)) throw new Error(`均线类型必须为 ${MA_KINDS.join('/')}`)
+  const period = Number(input.period)
+  if (!Number.isInteger(period) || period < 1 || period > MA_MAX_PERIOD) throw new Error(`均线周期必须为 1-${MA_MAX_PERIOD} 的整数`)
+  const source = String(input.source ?? 'close').toLowerCase()
+  if (!MA_SOURCES.includes(source)) throw new Error(`均线价格源必须为 ${MA_SOURCES.join('/')}`)
+  let smoothing = null
+  if (input.smoothing != null) {
+    const sKind = String(input.smoothing.kind ?? '').toLowerCase()
+    const sPeriod = Number(input.smoothing.period)
+    if (!MA_KINDS.includes(sKind)) throw new Error(`平滑类型必须为 ${MA_KINDS.join('/')}`)
+    if (!Number.isInteger(sPeriod) || sPeriod < 1 || sPeriod > MA_MAX_PERIOD) throw new Error(`平滑周期必须为 1-${MA_MAX_PERIOD} 的整数`)
+    smoothing = { kind: sKind, period: sPeriod }
+  }
+  const id = `${kind}${period}${source === 'close' ? '' : '-' + source}${smoothing ? `-${smoothing.kind}${smoothing.period}` : ''}`
+  const line = { id, kind, period, source, smoothing }
+  if (input.color != null) {
+    if (typeof input.color !== 'string' || !COLOR.test(input.color)) throw new Error('均线颜色必须为 #RRGGBB')
+    line.color = input.color.toLowerCase()
+  }
+  return line
+}
+
+/** Validate a whole set: at most MA_MAX_LINES, de-duplicated by id (last definition wins its slot). */
+export function normalizeMaLines(list) {
+  if (!Array.isArray(list)) throw new Error('均线列表无效')
+  const byId = new Map()
+  for (const item of list) { const line = normalizeMaLine(item); byId.set(line.id, line) }
+  if (byId.size > MA_MAX_LINES) throw new Error(`最多同时显示 ${MA_MAX_LINES} 条均线`)
+  return [...byId.values()]
+}
+
+/** "SMMA 7", "EMA 21 hl2", "SMA 20 · EMA 9". */
+export function maLabel(line) {
+  return `${line.kind.toUpperCase()} ${line.period}${line.source === 'close' ? '' : ' ' + line.source}${line.smoothing ? ` · ${line.smoothing.kind.toUpperCase()} ${line.smoothing.period}` : ''}`
+}
+
+function sourceOf(candle, source) {
+  const o = Number(candle.o), h = Number(candle.h), l = Number(candle.l), c = Number(candle.c)
+  switch (source) {
+    case 'open': return o
+    case 'high': return h
+    case 'low': return l
+    case 'hl2': return (h + l) / 2
+    case 'hlc3': return (h + l + c) / 3
+    case 'ohlc4': return (o + h + l + c) / 4
+    default: return c
+  }
+}
+
+/**
+ * One MA over a series that may start with nulls (e.g. the input of a smoothing pass).
+ * @param {Array<number|null>} values
+ * @param {string} kind
+ * @param {number} period
+ * @returns {Array<number|null>} aligned with `values`; null until enough data.
+ */
+export function movingAverage(values, kind, period) {
+  const out = new Array(values.length).fill(null)
+  const window = []
+  let prior = null
+  for (let i = 0; i < values.length; i += 1) {
+    const value = values[i]
+    if (value == null || !Number.isFinite(value)) { if (kind === 'sma' || kind === 'wma') window.length = 0; continue }
+    if (kind === 'sma' || kind === 'wma') {
+      window.push(value)
+      if (window.length > period) window.shift()
+      if (window.length < period) continue
+      if (kind === 'sma') out[i] = window.reduce((sum, v) => sum + v, 0) / period
+      else { let num = 0; for (let k = 0; k < period; k += 1) num += window[k] * (k + 1); out[i] = num / (period * (period + 1) / 2) }
+      continue
+    }
+    // ema / smma: seed with the SMA of the first `period` values, then recurse.
+    if (prior == null) {
+      window.push(value)
+      if (window.length < period) continue
+      prior = window.reduce((sum, v) => sum + v, 0) / period
+    } else {
+      const alpha = kind === 'ema' ? 2 / (period + 1) : 1 / period
+      prior = alpha * value + (1 - alpha) * prior
+    }
+    out[i] = prior
+  }
+  return out
+}
+
+/**
+ * Values of one normalized line over candles (ascending by time).
+ * @returns {{ values: Array<number|null>, smoothed: Array<number|null> | null }}
+ */
+export function maSeries(candles, line) {
+  const input = candles.map((candle) => { const v = sourceOf(candle, line.source); return Number.isFinite(v) ? v : null })
+  const values = movingAverage(input, line.kind, line.period)
+  const smoothed = line.smoothing ? movingAverage(values, line.smoothing.kind, line.smoothing.period) : null
+  return { values, smoothed }
+}
+
+/** Latest defined value of each line (and its smoothing) — what the agent reads. */
+export function maLatest(candles, lines) {
+  return lines.map((line) => {
+    const { values, smoothed } = maSeries(candles, line)
+    const last = (series) => { for (let i = series.length - 1; i >= 0; i -= 1) if (series[i] != null) return series[i]; return null }
+    return { id: line.id, label: maLabel(line), value: last(values), smoothed: smoothed ? last(smoothed) : null, line }
+  })
+}