dsh-hyperliquid 0.0.1 → 0.1.0

package/lib/signing.js

@@ -0,0 +1,215 @@
+/**
+ * dsh-hyperliquid — EIP-712 L1 action signing.
+ *
+ * Replicates hyperliquid-python-sdk v0.24.0 signing.py (verified against the
+ * research doc §4, which line-read the SDK source):
+ *
+ *   actionHash  = keccak256(msgpack(action) ‖ nonce(8B BE)
+ *                            ‖ [0x00]                       (no vault)
+ *                            | [0x01 ‖ vault20(lowercase)]  (vault routing)
+ *                            ‖ [0x00 ‖ expiresAfter(8B BE)] (opt-in expiry))
+ *   phantom     = { source: 'a' (mainnet) | 'b' (testnet), connectionId: actionHash }
+ *   digest      = keccak256(0x1901 ‖ domainSeparator ‖ structHash)
+ *   domain      = EIP712Domain(name "Exchange", version "1", chainId 1337,
+ *                             verifyingContract 0x000…000)
+ *   primaryType = Agent { source: string, connectionId: bytes32 }
+ *
+ * Curve math comes from @noble/curves + @noble/hashes, imported dynamically so
+ * the bundle stays dependency-free; without them live trading degrades to a
+ * clear error while paper trading and market data keep working.
+ *
+ * Wire contract notes (research §4.4): px/sz travel as decimal STRINGS with
+ * trailing zeros stripped (float_to_wire); addresses lowercase; msgpack field
+ * order matters.
+ *
+ * ✅ VALIDATED 2026-10-12 against the installed official SDK
+ * (hyperliquid-python-sdk, eth_account 0.13.7): three vectors — mainnet order,
+ * testnet cancel with vault, updateLeverage — reproduce identical r/s/v.
+ * The one real trap this uncovered: inside the EIP-712 domain separator the
+ * `verifyingContract` address encodes as a LEFT-PADDED 32-byte value, while
+ * the actionHash vault pre-image keeps the raw 20 bytes.
+ * @module lib/signing.js
+ */
+
+import { packb } from './msgpack.js'
+
+/** Hyperliquid hashes MessagePack with protocol field order, not caller key order. */
+export function canonicalAction(action) {
+  if (!action || typeof action !== 'object' || Array.isArray(action)) throw new Error('exchange action 必须为对象')
+  const fields = (value, names, label) => {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${label} 必须为对象`)
+    for (const key of Object.keys(value)) if (!names.includes(key)) throw new Error(`${label} 包含未知字段 ${key}`)
+    for (const key of names) if (!(key in value)) throw new Error(`${label} 缺少字段 ${key}`)
+    return Object.fromEntries(names.map((key) => [key, value[key]]))
+  }
+  switch (action.type) {
+    case 'order': {
+      const top = fields(action, ['type', 'orders', 'grouping'], 'order action')
+      if (!Array.isArray(top.orders) || top.orders.length === 0) throw new Error('order action 需要 orders')
+      return { type: 'order', orders: top.orders.map((order) => {
+        const names = ['a', 'b', 'p', 's', 'r', 't', ...(order && 'c' in order ? ['c'] : [])]
+        return fields(order, names, 'order')
+      }), grouping: top.grouping }
+    }
+    case 'cancel': {
+      const top = fields(action, ['type', 'cancels'], 'cancel action')
+      if (!Array.isArray(top.cancels) || top.cancels.length === 0) throw new Error('cancel action 需要 cancels')
+      return { type: 'cancel', cancels: top.cancels.map((cancel) => fields(cancel, ['a', 'o'], 'cancel')) }
+    }
+    case 'updateLeverage':
+      return fields(action, ['type', 'asset', 'isCross', 'leverage'], 'updateLeverage action')
+    default:
+      throw new Error(`不支持的 exchange action: ${String(action.type)}`)
+  }
+}
+
+const NULL_ADDRESS = new Uint8Array(32) // EIP-712 encodes address members left-padded to 32 bytes
+
+let cryptoCache = null
+/** Load @noble stacks once; memoised. */
+async function loadCrypto() {
+  if (cryptoCache) return cryptoCache
+  let nobleHashes
+  let nobleCurves
+  try {
+    nobleHashes = await import('@noble/hashes/sha3')
+    nobleCurves = await import('@noble/curves/secp256k1')
+  } catch (err) {
+    throw new Error(
+      'live 下单需要 @noble/curves 与 @noble/hashes（未安装）。' +
+      '请在插件运行环境安装这两个依赖，或继续使用 paper 模式。原始错误: ' + String(err?.message ?? err),
+    )
+  }
+  // @noble/hashes ≥1.8 renames keccak256 → keccak_256; accept both spellings.
+  const keccak256 = nobleHashes.keccak256 ?? nobleHashes.keccak_256
+  const { secp256k1 } = nobleCurves
+  cryptoCache = {
+    keccak256,
+    sign: (digest, priv) => secp256k1.sign(digest, priv, { prehash: false }),
+    hexToBytes: (hex) => {
+      const clean = hex.startsWith('0x') ? hex.slice(2) : hex
+      const out = new Uint8Array(clean.length / 2)
+      for (let i = 0; i < out.length; i += 1) out[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16)
+      return out
+    },
+    bytesToHex: (bytes) => Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join(''),
+    hashText: (text) => keccak256(new TextEncoder().encode(text)),
+  }
+  return cryptoCache
+}
+
+function concat(...arrays) {
+  const total = arrays.reduce((n, a) => n + a.length, 0)
+  const out = new Uint8Array(total)
+  let at = 0
+  for (const a of arrays) { out.set(a, at); at += a.length }
+  return out
+}
+
+function u256be(value) {
+  const hex = BigInt.asUintN(256, BigInt(value)).toString(16).padStart(64, '0')
+  return cryptoCache.hexToBytes(hex)
+}
+
+function addressBytes(address) {
+  const clean = address.startsWith('0x') ? address.slice(2) : address
+  if (!/^[0-9a-fA-F]{40}$/.test(clean)) throw new Error(`bad address: ${address}`)
+  return cryptoCache.hexToBytes(clean)
+}
+
+/** keccak256(msgpack(action) ‖ nonce ‖ vaultFlag ‖ [expiresAfter]) — exported for diagnostics. */
+export async function actionHash(action, vaultAddress, nonce, expiresAfter) {
+  const c = await loadCrypto()
+  const parts = [packb(canonicalAction(action)), u256be(nonce).slice(24)] // low 8 bytes, big-endian
+  if (vaultAddress) {
+    parts.push(new Uint8Array([0x01]), addressBytes(vaultAddress)) // addressBytes yields lowercase bytes
+  } else {
+    parts.push(new Uint8Array([0x00]))
+  }
+  if (Number.isFinite(expiresAfter)) {
+    parts.push(new Uint8Array([0x00]), u256be(Math.floor(expiresAfter)).slice(24))
+  }
+  return c.keccak256(concat(...parts))
+}
+
+/**
+ * Sign one L1 action. @returns {{r: string, s: string, v: number}}
+ * r/s are 0x-prefixed 32-byte hex; v is 27|28 (eth_sign style, no EIP-155).
+ */
+export async function signL1Action(privateKey, action, vaultAddress, nonce, isMainnet = true) {
+  const c = await loadCrypto()
+  const hash = await actionHash(action, vaultAddress, nonce)
+
+  const domainTypehash = c.hashText('EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)')
+  const agentTypehash = c.hashText('Agent(string source,bytes32 connectionId)')
+  const domainName = c.hashText('Exchange')
+  const domainVersion = c.hashText('1')
+
+  const domainSeparator = c.keccak256(concat(domainTypehash, domainName, domainVersion, u256be(1337), NULL_ADDRESS))
+  const sourceHash = c.hashText(isMainnet ? 'a' : 'b')
+  const structHash = c.keccak256(concat(agentTypehash, sourceHash, hash))
+  const digest = c.keccak256(concat(new Uint8Array([0x19, 0x01]), domainSeparator, structHash))
+
+  const priv = c.hexToBytes(privateKey)
+  if (priv.length !== 32) throw new Error('钱包私钥格式错误（需要 32 字节 hex）')
+  const sig = c.sign(digest, priv)
+  const recovery = typeof sig.recovery === 'number' ? sig.recovery : sig.v - 27
+  const rHex = c.bytesToHex(typeof sig.r === 'bigint' ? u256be(sig.r) : sig.r).padStart(64, '0').slice(-64)
+  const sHex = c.bytesToHex(typeof sig.s === 'bigint' ? u256be(sig.s) : sig.s).padStart(64, '0').slice(-64)
+  return { r: '0x' + rHex, s: '0x' + sHex, v: 27 + recovery }
+}
+
+/**
+ * Build the L1 action as a STANDARD EIP-712 typed-data payload — the shape
+ * dsh-web3's `ctx.wallet.signTypedData` (and any ethers-style signer) accepts.
+ * Digest path equivalence is guaranteed by the same actionHash + domain
+ * constants used by signL1Action; test/signing-web3.test.mjs cross-validates
+ * that ethers signs this payload to the exact r/s/v of the official vectors.
+ * @returns {{domain, types, value}} ethers-compatible typed data
+ */
+export async function buildL1TypedData(action, nonce, { vaultAddress = null, isMainnet = true } = {}) {
+  const c = await loadCrypto()
+  const hash = await actionHash(action, vaultAddress, nonce)
+  const connectionId = '0x' + c.bytesToHex(hash)
+  return {
+    domain: {
+      name: 'Exchange',
+      version: '1',
+      chainId: 1337,
+      verifyingContract: '0x0000000000000000000000000000000000000000',
+    },
+    types: {
+      Agent: [
+        { name: 'source', type: 'string' },
+        { name: 'connectionId', type: 'bytes32' },
+      ],
+    },
+    value: { source: isMainnet ? 'a' : 'b', connectionId },
+  }
+}
+
+/**
+ * Split a 65-byte hex signature (0x + 130 chars, ethers style) into the
+ * Hyperliquid wire form: r/s as 0x-prefixed 32-byte hex, v as 27|28.
+ */
+export function splitSignature(hex) {
+  const clean = String(hex ?? '').replace(/^0x/, '')
+  if (clean.length !== 130) throw new Error(`签名长度异常（期望 65 字节 hex）：${clean.length} 字符`)
+  const r = clean.slice(0, 64)
+  const s = clean.slice(64, 128)
+  const vHex = clean.slice(128, 130)
+  const vNum = parseInt(vHex, 16)
+  const v = vNum >= 27 ? vNum : vNum + 27
+  return { r: '0x' + r, s: '0x' + s, v }
+}
+
+/** Derive the EVM address (0x…) for a private key — used for account reads. */
+export async function addressFromPrivateKey(privateKey) {
+  const c = await loadCrypto()
+  const priv = c.hexToBytes(privateKey)
+  if (priv.length !== 32) throw new Error('钱包私钥格式错误（需要 32 字节 hex）')
+  const { secp256k1 } = await import('@noble/curves/secp256k1')
+  const pub = secp256k1.getPublicKey(priv, false) // uncompressed: 0x04 ‖ X ‖ Y
+  const hash = c.keccak256(pub.slice(1))
+  return '0x' + c.bytesToHex(hash.slice(-20))
+}

package/lib/skill.js

@@ -0,0 +1,19 @@
+/** Register the packaged trading skill in DSH's native skill catalog. */
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+const skillUrl = new URL('../skills/hyperliquid-trading/SKILL.md', import.meta.url)
+const source = readFileSync(skillUrl, 'utf8')
+const content = source.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, '').trim()
+
+export function registerHyperSkill(skills) {
+  if (typeof skills?.register !== 'function') return null
+  return skills.register({
+    name: 'hyperliquid-trading',
+    description: '分析 Hyperliquid 实时行情、账户和风险，并在 DSH 交易会话中安全决策、下单、撤单和对账。',
+    whenToUse: '讨论当前交易台、Hyperliquid 市场、持仓、订单、paper 或 testnet/live 交易时使用。',
+    source: 'bundled',
+    path: fileURLToPath(skillUrl),
+    content,
+  })
+}

package/lib/store.js

@@ -0,0 +1,341 @@
+/**
+ * dsh-hyperliquid — durable store: trading-session registry, paper account,
+ * and the UI event ring. One JSON file per concern under the plugin dataDir;
+ * writes are tmp+rename atomic (the dsh namespace sweep lesson).
+ * @module lib/store.js
+ */
+
+import { readFileSync, writeFileSync, renameSync, mkdirSync, existsSync, rmSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { randomUUID, createHash } from 'node:crypto'
+import { canonicalMarketCoin } from './market-symbol.js'
+
+const PAPER_START_USD = 100_000
+const WORKSPACE_DEFAULTS = Object.freeze({
+  interval: '15m', bookGrouping: 'full', chartTab: 'chart', tapeTab: 'book', bottomTab: 'positions', indicators: ['volume'],
+  priceScale: 'normal', chartRanges: {}, chartLayers: { orders: true, fills: true, drawings: true },
+  layout: { sessionsWidth: 232, chatWidth: 480, sessionsCollapsed: false, deskCollapsed: false, chatCollapsed: false },
+})
+
+export class HyperStore {
+  constructor(dataDir, paperNetwork = 'testnet') {
+    this.dataDir = dataDir
+    this.sessionsFile = join(dataDir, 'sessions.json')
+    this.paperLegacyFile = join(dataDir, 'paper.json')
+    this.paperLegacyNetwork = paperNetwork
+    this.liveOrdersFile = join(dataDir, 'live-orders.json')
+    this.liveDecisionsFile = join(dataDir, 'live-decisions.json')
+    this.chartMarksFile = join(dataDir, 'chart-marks.json')
+    this.events = [] // UI event ring
+    this.eventSeq = 0
+    this.sessions = this.#readJson(this.sessionsFile, { sessions: {} })
+    // Existing XYZ100 sessions may contain a display shorthand that the
+    // exchange rejects with HTTP 500. Repair the saved binding on startup.
+    let migratedCoin = false
+    for (const row of Object.values(this.sessions.sessions ?? {})) {
+      if (!row || typeof row.coin !== 'string') continue
+      const canonical = canonicalMarketCoin(row.coin)
+      if (canonical !== row.coin) { row.coin = canonical; migratedCoin = true }
+    }
+    if (migratedCoin) this.#writeJson(this.sessionsFile, this.sessions)
+    this.selectPaperNetwork(paperNetwork)
+    // A corrupt execution journal is unsafe to discard: an unknown order may
+    // have reached the exchange. Refuse live trading until it is repaired.
+    this.liveOrders = existsSync(this.liveOrdersFile)
+      ? JSON.parse(readFileSync(this.liveOrdersFile, 'utf8'))
+      : {}
+    if (!this.liveOrders || typeof this.liveOrders !== 'object' || Array.isArray(this.liveOrders)) throw new Error('live 订单审计账本损坏')
+    this.liveDecisions = existsSync(this.liveDecisionsFile)
+      ? JSON.parse(readFileSync(this.liveDecisionsFile, 'utf8'))
+      : {}
+    if (!this.liveDecisions || typeof this.liveDecisions !== 'object' || Array.isArray(this.liveDecisions)) throw new Error('live 决策审计账本损坏')
+    this.chartMarksBySession = new Map()
+    this.workspacesBySession = new Map()
+    this.#migrateChartMarks()
+  }
+
+  selectPaperNetwork(network) {
+    if (network !== 'testnet' && network !== 'mainnet') throw new Error('paper 网络无效')
+    const file = join(this.dataDir, `paper-${network}.json`)
+    const source = existsSync(file) ? file : network === this.paperLegacyNetwork && existsSync(this.paperLegacyFile) ? this.paperLegacyFile : null
+    let paper
+    try {
+      paper = source ? JSON.parse(readFileSync(source, 'utf8'))
+        : { usd: PAPER_START_USD, positions: {}, leverageByCoin: {}, fills: [], orders: [] }
+    } catch {
+      throw new Error('paper 账户文件损坏，拒绝重置模拟权益')
+    }
+    // Older paper snapshots predate per-coin leverage; an absent map is a
+    // known migration and does not change cash, positions, or fills.
+    if (paper && typeof paper === 'object' && paper.leverageByCoin == null) paper.leverageByCoin = {}
+    if (paper && typeof paper === 'object' && paper.orders == null) paper.orders = []
+    if (!paper || typeof paper !== 'object' || !Number.isFinite(paper.usd) ||
+      !paper.positions || typeof paper.positions !== 'object' || Array.isArray(paper.positions) ||
+      !Array.isArray(paper.fills) || !Array.isArray(paper.orders) || !paper.leverageByCoin ||
+      typeof paper.leverageByCoin !== 'object' || Array.isArray(paper.leverageByCoin)) {
+      throw new Error('paper 账户文件损坏，拒绝重置模拟权益')
+    }
+    this.paperFile = file
+    this.paper = paper
+  }
+
+  #readJson(file, fallback) {
+    try {
+      if (!existsSync(file)) return fallback
+      return JSON.parse(readFileSync(file, 'utf8'))
+    } catch {
+      return fallback
+    }
+  }
+
+  #writeJson(file, value) {
+    mkdirSync(dirname(file), { recursive: true, mode: 0o700 })
+    const tmp = file + '.tmp'
+    writeFileSync(tmp, JSON.stringify(value, null, 2), { mode: 0o600 })
+    renameSync(tmp, file)
+  }
+
+  /** Hash arbitrary DSH ids: a session id can never escape its artifact directory. */
+  sessionDirectory(sessionId) {
+    if (!this.sessions.sessions[sessionId]) throw new Error(`会话 ${sessionId} 未登记为交易会话`)
+    return join(this.dataDir, 'sessions', createHash('sha256').update(sessionId).digest('hex'))
+  }
+
+  #sessionFile(sessionId, name) { return join(this.sessionDirectory(sessionId), name) }
+
+  #readArtifact(file, fallback) {
+    if (!existsSync(file)) return fallback
+    try { return JSON.parse(readFileSync(file, 'utf8')) }
+    catch { throw new Error(`会话文件损坏：${file}`) }
+  }
+
+  #migrateChartMarks() {
+    if (!existsSync(this.chartMarksFile)) return
+    const legacy = this.#readArtifact(this.chartMarksFile, [])
+    if (!Array.isArray(legacy)) throw new Error('旧图表标注文件损坏')
+    const grouped = new Map()
+    for (const mark of legacy) {
+      if (!mark || !this.sessions.sessions[mark.sessionId]) continue
+      if (!grouped.has(mark.sessionId)) grouped.set(mark.sessionId, [])
+      grouped.get(mark.sessionId).push(mark)
+    }
+    // Writes are idempotent if a prior migration stopped before the rename.
+    for (const [sessionId, marks] of grouped) {
+      const file = this.#sessionFile(sessionId, 'chart-marks.json')
+      const existing = this.#readArtifact(file, [])
+      if (!Array.isArray(existing)) throw new Error('会话图表标注文件损坏')
+      const ids = new Set(existing.map((row) => row.id))
+      const merged = [...existing, ...marks.filter((row) => !ids.has(row.id))]
+      this.#writeJson(file, merged)
+    }
+    renameSync(this.chartMarksFile, join(this.dataDir, 'chart-marks.migrated.json'))
+  }
+
+  getSessionWorkspace(sessionId) {
+    const row = this.getSession(sessionId)
+    if (!row) throw new Error(`会话 ${sessionId} 未登记为交易会话`)
+    if (!this.workspacesBySession.has(sessionId)) {
+      const saved = this.#readArtifact(this.#sessionFile(sessionId, 'workspace.json'), {})
+      if (!saved || typeof saved !== 'object' || Array.isArray(saved)) throw new Error('会话工作台配置损坏')
+      this.workspacesBySession.set(sessionId, { ...WORKSPACE_DEFAULTS, ...saved,
+        layout: { ...WORKSPACE_DEFAULTS.layout, ...saved.layout },
+        chartLayers: { ...WORKSPACE_DEFAULTS.chartLayers, ...saved.chartLayers },
+        chartRanges: { ...saved.chartRanges }, coin: row.coin })
+    }
+    return { ...this.workspacesBySession.get(sessionId), coin: row.coin }
+  }
+
+  updateSessionWorkspace(sessionId, patch) {
+    const current = this.getSessionWorkspace(sessionId)
+    const next = { ...current, ...patch,
+      layout: patch.layout ? { ...current.layout, ...patch.layout } : current.layout,
+      chartLayers: patch.chartLayers ? { ...current.chartLayers, ...patch.chartLayers } : current.chartLayers,
+      chartRanges: patch.chartRanges ? { ...current.chartRanges, ...patch.chartRanges } : current.chartRanges,
+      coin: this.getSession(sessionId).coin, sessionId }
+    if (Object.keys(next.chartRanges).length > 200) next.chartRanges = Object.fromEntries(Object.entries(next.chartRanges).slice(-200))
+    this.#writeJson(this.#sessionFile(sessionId, 'workspace.json'), next)
+    this.workspacesBySession.set(sessionId, next)
+    return next
+  }
+
+  #marks(sessionId) {
+    if (!this.chartMarksBySession.has(sessionId)) {
+      const marks = this.#readArtifact(this.#sessionFile(sessionId, 'chart-marks.json'), [])
+      if (!Array.isArray(marks)) throw new Error('会话图表标注文件损坏')
+      this.chartMarksBySession.set(sessionId, marks)
+    }
+    return this.chartMarksBySession.get(sessionId)
+  }
+
+  // ── trading sessions ─────────────────────────────────────────────────
+  listSessions() {
+    return Object.values(this.sessions.sessions).sort((a, b) => b.createdAt - a.createdAt)
+  }
+
+  registerSession(sessionId, meta = {}) {
+    const prev = this.sessions.sessions[sessionId]
+    this.sessions.sessions[sessionId] = {
+      sessionId,
+      coin: canonicalMarketCoin(meta.coin ?? prev?.coin ?? 'BTC'),
+      title: meta.title ?? prev?.title ?? null,
+      createdAt: prev?.createdAt ?? Date.now(),
+      updatedAt: Date.now(),
+    }
+    this.#writeJson(this.sessionsFile, this.sessions)
+    this.updateSessionWorkspace(sessionId, {})
+    return this.sessions.sessions[sessionId]
+  }
+
+  removeSession(sessionId) {
+    if (this.sessions.sessions[sessionId]) {
+      delete this.sessions.sessions[sessionId]
+      this.#writeJson(this.sessionsFile, this.sessions)
+    }
+    const path = join(this.dataDir, 'sessions', createHash('sha256').update(sessionId).digest('hex'))
+    rmSync(path, { recursive: true, force: true })
+    this.chartMarksBySession.delete(sessionId)
+    this.workspacesBySession.delete(sessionId)
+  }
+
+  bindCoin(sessionId, coin) {
+    const row = this.sessions.sessions[sessionId]
+    if (!row) throw new Error(`会话 ${sessionId} 未登记为交易会话`)
+    row.coin = canonicalMarketCoin(coin)
+    row.updatedAt = Date.now()
+    this.#writeJson(this.sessionsFile, this.sessions)
+    this.updateSessionWorkspace(sessionId, {})
+    return row
+  }
+
+  getSession(sessionId) {
+    return this.sessions.sessions[sessionId] ?? null
+  }
+
+  listChartMarks(sessionId, coin, interval) {
+    return this.#marks(sessionId).filter((mark) => mark.coin === coin && mark.interval === interval)
+  }
+
+  addChartMark(mark) {
+    const related = this.listChartMarks(mark.sessionId, mark.coin, mark.interval)
+    if (related.length >= 30) throw new Error('当前图表最多保留 30 条标注，请先删除旧线')
+    const marks = this.#marks(mark.sessionId)
+    if (marks.length >= 300) throw new Error('当前会话最多保留 300 条图表标注，请先删除旧线')
+    const saved = { ...mark, id: randomUUID(), createdAt: Date.now() }
+    marks.push(saved)
+    this.#writeJson(this.#sessionFile(mark.sessionId, 'chart-marks.json'), marks)
+    this.recordEvent('chart.mark', { sessionId: mark.sessionId, coin: mark.coin, interval: mark.interval, id: saved.id })
+    return saved
+  }
+
+  removeChartMark(sessionId, id) {
+    const marks = this.#marks(sessionId)
+    const mark = marks.find((row) => row.id === id)
+    if (!mark) throw new Error('图表标注不存在或不属于当前会话')
+    this.chartMarksBySession.set(sessionId, marks.filter((row) => row !== mark))
+    this.#writeJson(this.#sessionFile(sessionId, 'chart-marks.json'), this.#marks(sessionId))
+    this.recordEvent('chart.mark', { sessionId, coin: mark.coin, interval: mark.interval, id })
+    return mark
+  }
+
+  // ── UI event ring ────────────────────────────────────────────────────
+  recordEvent(kind, data = {}) {
+    this.eventSeq += 1
+    this.events.push({ seq: this.eventSeq, at: Date.now(), kind, data })
+    if (this.events.length > 500) this.events.splice(0, this.events.length - 500)
+    return this.eventSeq
+  }
+
+  eventsSince(seq) {
+    return { events: this.events.filter((e) => e.seq > Number(seq) || !Number.isFinite(Number(seq))), seq: this.eventSeq }
+  }
+
+  // ── paper trading ────────────────────────────────────────────────────
+  paperAccount() {
+    return JSON.parse(JSON.stringify(this.paper))
+  }
+
+  /**
+   * Fill a paper order against the given mid with a simple slippage model.
+   * @returns the fill record
+   */
+  paperFill({ coin, isBuy, sz, px, time = Date.now(), reason = 'order' }) {
+    const szNum = Number(sz)
+    const pxNum = Number(px)
+    if (!Number.isFinite(szNum) || szNum <= 0) throw new Error('paper: 无效数量')
+    if (!Number.isFinite(pxNum) || pxNum <= 0) throw new Error('paper: 无效价格')
+    const notional = szNum * pxNum
+    const pos = this.paper.positions[coin] ?? { size: 0, entryPx: pxNum, leverage: this.paper.leverageByCoin?.[coin] ?? 1 }
+    const signed = isBuy ? szNum : -szNum
+    const prevSize = pos.size
+    let realized = 0
+    if (prevSize !== 0 && Math.sign(prevSize) !== Math.sign(signed)) {
+      const closing = Math.min(Math.abs(prevSize), Math.abs(signed))
+      realized = (pxNum - pos.entryPx) * closing * Math.sign(prevSize)
+    }
+    const newSize = prevSize + signed
+    if (newSize === 0) delete this.paper.positions[coin]
+    else {
+      const flip = prevSize !== 0 && Math.sign(newSize) !== Math.sign(prevSize)
+      const adding = Math.abs(newSize) > Math.abs(prevSize)
+      // Opening / flipping takes the fill price; ADDING keeps the weighted
+      // average; a PARTIAL CLOSE leaves the remaining position's entry
+      // untouched (its PnL was already settled into cash as `realized`).
+      pos.entryPx = prevSize === 0 || flip ? pxNum
+        : adding ? (pos.entryPx * Math.abs(prevSize) + pxNum * Math.abs(signed)) / (Math.abs(prevSize) + Math.abs(signed))
+        : pos.entryPx
+      pos.size = newSize
+      this.paper.positions[coin] = pos
+    }
+    this.paper.usd += realized // realized PnL settles into cash; margin tracked conceptually
+    const fill = { coin, isBuy, sz: szNum, px: pxNum, notional, realized, time, reason }
+    this.paper.fills.unshift(fill)
+    if (this.paper.fills.length > 200) this.paper.fills.length = 200
+    this.#writeJson(this.paperFile, this.paper)
+    this.recordEvent('paper.fill', fill)
+    return fill
+  }
+
+  paperOrderRecord(order) {
+    const row = { ...order, time: Date.now(), status: 'filled' }
+    this.paper.orders.unshift(row)
+    if (this.paper.orders.length > 200) this.paper.orders.length = 200
+    this.#writeJson(this.paperFile, this.paper)
+    this.recordEvent('paper.order', row)
+  }
+
+  paperSetLeverage(coin, leverage) {
+    this.paper.leverageByCoin ??= {}
+    this.paper.leverageByCoin[coin] = leverage
+    if (this.paper.positions[coin]) this.paper.positions[coin].leverage = leverage
+    this.#writeJson(this.paperFile, this.paper)
+    this.recordEvent('paper.leverage', { coin, leverage })
+  }
+
+  recordLiveDecision(decisionId, decision) {
+    this.liveDecisions[decisionId] = { ...decision, decisionId, at: Date.now() }
+    const ids = Object.keys(this.liveDecisions)
+    if (ids.length > 1000) {
+      ids.sort((a, b) => this.liveDecisions[a].at - this.liveDecisions[b].at)
+      for (const id of ids.slice(0, ids.length - 1000)) delete this.liveDecisions[id]
+    }
+    this.#writeJson(this.liveDecisionsFile, this.liveDecisions)
+    this.recordEvent('live.decision', { decisionId, sessionId: decision.sessionId, coin: decision.order.coin })
+    return this.liveDecisions[decisionId]
+  }
+
+  recordLiveOrder(cloid, patch) {
+    const prev = this.liveOrders[cloid] ?? {}
+    const row = { ...prev, ...patch, cloid, updatedAt: Date.now() }
+    this.liveOrders[cloid] = row
+    const ids = Object.keys(this.liveOrders)
+    if (ids.length > 1000) {
+      ids.sort((a, b) => this.liveOrders[a].updatedAt - this.liveOrders[b].updatedAt)
+      for (const id of ids.slice(0, ids.length - 1000)) delete this.liveOrders[id]
+    }
+    this.#writeJson(this.liveOrdersFile, this.liveOrders)
+    this.recordEvent('live.order.' + row.status, { cloid, coin: row.coin, status: row.status })
+    return row
+  }
+
+  getLiveOrder(cloid) { return this.liveOrders[cloid] ?? null }
+}