@clonegod/ttd-sol-common 2.0.66 → 2.0.68

package/src/quote/abstract_dex_quote.ts

@@ -0,0 +1,337 @@
+import {
+    AppConfig, QuoteDepthOutput, QuoteResultType, StandardPoolInfoType,
+    log_info, log_warn, on_quote_response, report_quote_candidate,
+} from '@clonegod/ttd-core/dist'
+import { SolanaBlockMetaUpdateEvent } from '../types'
+import { SolanaChainOps } from './chain_ops'
+import { SolPoolEvent } from './pool_event'
+import { QuotePriceVerify, CheckSwapParams } from './verify/quote_price_verify'
+import { getQuoteAmountUsd } from './quote_amount'
+import { QuoteTrace } from './quote_trace'
+
+// ── 结构对齐 BSC/SUI 的 abstract_dex_quote（[[feedback_cross_chain_consistency]]）──
+//   有理由的偏离（Solana 账户快照模型，详见 pool_event.ts §2.1）：
+//     · 池事件是**账户原始快照**（非 swap event）→ 每个事件都触发 v2 重算 + refreshStateFromEvent 解码覆盖状态；
+//       因此去掉 SUI 的 swap/add/remove 事件分类（debouncedEventTypes）。
+//     · 单调水位线用 Solana 账户 writeVersion（= txIndex 对等物）；wire 暂未带 → 缺省按"无序号"处理。
+//     · 无 v3 PriceFeed（同 SUI，省 do_quote_v3）。
+//     · verify swap-amount 对账暂缓（账户快照不含 amount）→ buildSwapVerify 默认 null；cacheQuote 跨源仍生效。
+
+/**
+ * 流动性一致性策略（设计文档 §2.2 定稿：3 订阅原型）。各 DEX 子类按协议特性声明：
+ *   - 'snapshot'  ：单账户原子（DAMMV2 / CLMM 的 swap 路径）——状态全在一个独占账户、swap 只动它，无需门控。
+ *   - 'slot-gate' ：多账户快照 + slot 门控（AMM 两 vault / DLMM lbPair+binArray）——swap 动多个独占账户，
+ *                   走单触碰的账户 slot 不一致则本拍不推（等下条更新自然重触发）。
+ *   - 'tx-driven' ：事务驱动（DAMM 共享 vault）——账户快照无法按账户归因，状态由交易解析驱动（账户事件路径不报价）。
+ */
+export type ConsistencyPolicy = 'snapshot' | 'slot-gate' | 'tx-driven'
+
+/** loadPool 返回的标准摘要 —— 强制每个 DEX 暴露链上读出的标准字段，供 [QUOTE INIT] 统一打印。 */
+export interface PoolInitSummary {
+    protocol_type: string          // AMM_PUMPSWAP / CLMM_ORCA / DLMM_METEORA / ...
+    fee_bps: number                // 链上读
+    tick_spacing?: number
+    bin_step?: number
+    token0: string                 // "SYMBOL(addr)"
+    token1: string
+    verifyProgram?: string         // 启动校验的链上 program（无则省）
+}
+
+/** 一次询价的完整产物（推 orderbook + verify + analyze 上报共用）。 */
+export interface QuoteBundle {
+    poolInfo: StandardPoolInfoType
+    quote_amount_usd: number
+    streamTimestamp: number
+    quoteStartTime: number
+    blockNumber: number
+    txIndex?: number               // 块内序号（v2 = writeVersion；v1 区块兜底无 → 无条件推，不入 watermark）
+    askQuote: QuoteResultType
+    bidQuote: QuoteResultType
+    txid: string
+    source?: string
+    depth?: QuoteDepthOutput
+    priceMap?: Map<string, { price: string } | undefined>
+    trace?: QuoteTrace
+}
+
+/**
+ * AbstractDexQuote（Solana）—— 询价流程骨架，对齐 BSC/SUI 同名抽象
+ * （模板方法 DEX 维继承 + 组合链维 SolanaChainOps）。
+ *
+ * 两源（Solana 无 v3 pricefeed）：
+ *   - v1（new_block 通道兜底，节流 MIN_QUOTE_INTERVAL_MS）→ quoteV1（SDK / 链上模拟，自取最新状态）
+ *   - v2（pool 账户更新事件驱动）→ refreshStateFromEvent 解码账户覆盖本地状态 → quoteV2（本地公式）
+ *
+ * 强制不变量：v1/v2 都基于同一份链上 load 的池子状态；ask 含费恒 ≥ bid。
+ */
+export abstract class AbstractDexQuote<C extends SolanaChainOps = SolanaChainOps> {
+    protected appConfig: AppConfig
+    protected chain: C
+    protected poolInfoMap: Map<string, StandardPoolInfoType> = new Map()
+
+    private poolLastQuoteTimeMap: Map<string, number> = new Map()
+    // 推送单调水位线：每池最近推送的 (block, writeVersion)。严格变新才推。
+    private lastPublished: Map<string, { block: number; txIndex: number }> = new Map()
+    // 状态应用水位线：防乱序旧账户快照回拉状态（独立于报价水位线）。
+    private appliedStateWatermark: Map<string, { block: number; txIndex: number }> = new Map()
+    protected quotePriceVerify = new QuotePriceVerify()
+    /**
+     * 最近一个区块的 slot（由 handleBlockUpdateEvent 维护，stream-block 每 ~400ms tick）。
+     * 给 v1（block 兜底）路径用作"当前 slot"——v1 正是 block 触发的，调用时此值=当前块 slot。
+     * 用途：DAMM v2 等动态费协议的 fee scheduler 在 activationType=slot 时需要当前 slot 当 currentPoint。
+     */
+    protected latestBlockSlot = 0
+    private readonly MIN_QUOTE_INTERVAL_MS = Math.max(3000, parseInt(process.env.MIN_QUOTE_INTERVAL_MS || '10000', 10) || 10000)
+
+    constructor(appConfig: AppConfig, chain: C) {
+        this.appConfig = appConfig
+        this.chain = chain
+    }
+
+    // ════════════ DEX 差异点（子类实现）════════════
+
+    /** 本进程绑定的 DEX_ID（事件过滤 + 日志） */
+    protected abstract readonly dexId: string
+    /**
+     * 流动性一致性策略（§2.2）。默认 'snapshot'（单账户原子，最常见）；
+     * AMM/DLMM 覆盖为 'slot-gate'，DAMM 覆盖为 'tx-driven'。
+     */
+    protected readonly consistencyPolicy: ConsistencyPolicy = 'snapshot'
+    /** 链上 load 池子静态+动态状态并缓存（含 token 身份校验，fail-loud）。返回标准摘要供 [QUOTE INIT]。 */
+    protected abstract loadPool(poolInfo: StandardPoolInfoType): Promise<PoolInitSummary>
+    /** v1：SDK / 链上模拟（block 兜底，自取最新状态）。isBuy=true 买基础币(ask)。 */
+    protected abstract quoteV1(poolInfo: StandardPoolInfoType, isBuy: boolean): Promise<QuoteResultType>
+    /** v2：本地公式（事件驱动；调用前 refreshStateFromEvent 已用账户快照刷新本地状态）。 */
+    protected abstract quoteV2(poolInfo: StandardPoolInfoType, isBuy: boolean): Promise<QuoteResultType>
+
+    /**
+     * 用账户快照刷新内存池子状态（**Solana v2 的核心机制**：解码 evt.poolAccountData / vault 数据 → 覆盖本地状态）。
+     * 默认 no-op，子类必须覆盖以真正消费账户快照（否则 v2 等于不更新）。
+     */
+    protected async refreshStateFromEvent(_poolInfo: StandardPoolInfoType, _evt: SolPoolEvent): Promise<void> {}
+    /** 深度（tier 化）；fee 来自链上 load。priceMap 由基类预取。默认 undefined（step 3 各 DEX 逐档实现）。 */
+    protected async calculateDepth(_poolInfo: StandardPoolInfoType, _poolAddress: string, _priceMap: Map<string, { price: string } | undefined>): Promise<QuoteDepthOutput | undefined> { return undefined }
+    /** swap → verify 入参；Solana 账户快照暂不含 swap amount，默认 null（待 stream-quote 解码后接）。 */
+    protected buildSwapVerify(_poolInfo: StandardPoolInfoType, _evt: SolPoolEvent): CheckSwapParams | null { return null }
+
+    /**
+     * slot 门控钩子（仅 consistencyPolicy='slot-gate' 生效）：判断本池"走单触碰的多账户"状态是否 slot 一致。
+     * 不一致返回 false → 本拍 v2 不报价（落后账户的下一条更新会自然重触发，等价"有界等待下一拍"）。
+     *
+     * 默认 true（snapshot 单账户原子无需门控）。slot-gate 协议覆盖：比较 pool 与刚更新的 vault/binArray 的 slot
+     * （子账户 slot 由子类经 recordAccountSlot 维护；step2b 子账户转发到位后填充）。
+     */
+    protected isStateConsistentForQuote(_poolInfo: StandardPoolInfoType): boolean { return true }
+
+    /** 记录某账户最新 slot（供 slot-gate 的 isStateConsistentForQuote 比较；子类/子账户转发路径调用）。 */
+    protected accountSlots: Map<string, number> = new Map()
+    protected recordAccountSlot(accountAddr: string, slot: number): void {
+        this.accountSlots.set(accountAddr, slot)
+    }
+
+    // ════════════ 生命周期（基类）════════════
+
+    async init(poolList: StandardPoolInfoType[]): Promise<void> {
+        log_info(`初始化 ${this.dexId} Quote，共 ${poolList.length} 个池...`)
+        for (const poolInfo of poolList) {
+            if (!this.chain.isValidPoolAddress(poolInfo.pool_address)) {
+                log_warn(`跳过无效的池地址: ${poolInfo.pool_address}`, '')
+                continue
+            }
+            this.poolInfoMap.set(poolInfo.pool_address, poolInfo)
+        }
+        await this.beforeLoadPools()
+        await Promise.all(Array.from(this.poolInfoMap.values()).map(async p => {
+            const summary = await this.loadPool(p)
+            if (summary.verifyProgram) await this.chain.assertProgramDeployed(summary.verifyProgram)
+            log_info(`[QUOTE INIT] ${p.pool_name} (${p.pool_address}) dex=${this.dexId}`, { ...summary })
+        }))
+        this.registerEventHandlers()
+        log_info(`${this.dexId} Quote 初始化完成，${this.poolInfoMap.size} 个有效池`)
+    }
+
+    /** 子类可选：load 前的批量准备（如 SDK 初始化）。默认空。 */
+    protected async beforeLoadPools(): Promise<void> {}
+
+    /** 询价 USD 金额（QUOTE_AMOUNT_USD 覆盖 / pool 配置）。子类 compute amountIn 用。 */
+    protected getQuoteAmountUsd(poolInfo: StandardPoolInfoType): number { return getQuoteAmountUsd(poolInfo) }
+
+    private registerEventHandlers(): void {
+        // v1 兜底：new_block 通道（stream-block）
+        this.chain.subscribeNewBlock((raw) => this.handleBlockUpdateEvent(raw))
+        // v2 事件：pool 账户更新（stream-quote WS）—— 直连 refresh → compute → publish，(block,writeVersion) 水位线兜底
+        this.chain.subscribePoolEvents(this.dexId, Array.from(this.poolInfoMap.values()), async (evt: SolPoolEvent) => {
+            const { bundle, verifyLog } = await this.calculateQuote(evt)
+            if (bundle) this.publishQuote(bundle)
+            // [Verify] 在 [QUOTE OK] 之后打 —— 先报价后验证
+            if (verifyLog) log_info(verifyLog)
+        })
+    }
+
+    // ════════════ 事件处理（基类）════════════
+
+    private assertValidBlockNumber(blockNumber: any, ctx: string): void {
+        if (!Number.isInteger(blockNumber) || blockNumber <= 0) {
+            throw new Error(`[block-number] ${ctx}: 非法 blockNumber=${blockNumber}，每条数据源必须携带真实 slot`)
+        }
+    }
+
+    /** (block, writeVersion) 水位线判定：incoming 是否相对已推送的最新陈旧（只判定不更新）。 */
+    private isStaleUpdate(poolAddr: string, block: number, txIndex: number): boolean {
+        const last = this.lastPublished.get(poolAddr)
+        return !!last && (block < last.block || (block === last.block && txIndex <= last.txIndex))
+    }
+
+    /** 状态应用水位线：乱序晚到的旧账户快照（绝对态）跳过应用，防把状态回拉到旧值。check-and-advance 一体。 */
+    private shouldApplyState(poolAddr: string, block: number, txIndex: number): boolean {
+        const last = this.appliedStateWatermark.get(poolAddr)
+        if (last && (block < last.block || (block === last.block && txIndex <= last.txIndex))) return false
+        this.appliedStateWatermark.set(poolAddr, { block, txIndex })
+        return true
+    }
+
+    private async handleBlockUpdateEvent(eventData: string): Promise<void> {
+        const { slot, blockTime } = JSON.parse(eventData) as SolanaBlockMetaUpdateEvent
+        this.assertValidBlockNumber(slot, `${this.dexId} block-event`)
+        this.latestBlockSlot = slot   // v1 兜底询价取当前 slot 用（动态费 currentPoint）
+        for (const poolInfo of this.poolInfoMap.values()) {
+            const poolAddress = poolInfo.pool_address
+            const now = Date.now()
+            const last = this.poolLastQuoteTimeMap.get(poolAddress) || 0
+            if (now - last >= this.MIN_QUOTE_INTERVAL_MS) {
+                this.poolLastQuoteTimeMap.set(poolAddress, now)   // await 前占位，防节流被打穿
+                const result = await this.calculateQuoteForPool(poolInfo, blockTime, slot)
+                if (result) this.publishQuote(result)
+            }
+        }
+    }
+
+    private async calculateQuote(evt: SolPoolEvent): Promise<{ bundle: QuoteBundle | null, verifyLog?: string }> {
+        const poolInfo = this.poolInfoMap.get(evt.pool_address)
+        if (!poolInfo) return { bundle: null }
+        this.assertValidBlockNumber(evt.blockNumber, `${this.dexId} ${poolInfo.pool_name} account-update`)
+
+        // swap verify（唯一入口）。SOL 账户快照默认无 swap amount → buildSwapVerify 返回 null 即跳过。
+        let verifyLog: string | undefined
+        const v = this.buildSwapVerify(poolInfo, evt)
+        if (v) verifyLog = this.quotePriceVerify.checkSwap(v) || undefined
+
+        // 状态更新：每个账户快照都做（不受报价 staleness 短路影响）。
+        // 例外：乱序晚到的旧 writeVersion 跳过，防状态回拉（writeVersion 缺省时无条件应用）。
+        const hasWv = Number.isInteger(evt.writeVersion)
+        const skipApply = hasWv && !this.shouldApplyState(evt.pool_address, evt.blockNumber, evt.writeVersion as number)
+        if (!skipApply) await this.refreshStateFromEvent(poolInfo, evt)
+
+        // compute 前短路：已陈旧 → 跳过重算+推送（状态已更新）
+        if (hasWv && this.isStaleUpdate(evt.pool_address, evt.blockNumber, evt.writeVersion as number)) return { bundle: null, verifyLog }
+
+        // slot 门控（slot-gate 协议）：走单触碰的多账户 slot 不一致 → 本拍不报价，等落后账户的下一条更新重触发
+        if (this.consistencyPolicy === 'slot-gate' && !this.isStateConsistentForQuote(poolInfo)) {
+            return { bundle: null, verifyLog }
+        }
+
+        const bundle = await this.calculateQuoteForPool(poolInfo, evt.blockTime, evt.blockNumber, evt)
+        return { bundle, verifyLog }
+    }
+
+    private async calculateQuoteForPool(poolInfo: StandardPoolInfoType, streamTimestamp: number, blockNumber: number, evt?: SolPoolEvent): Promise<QuoteBundle | null> {
+        const { pool_address } = poolInfo
+        const eventDriven = !!evt
+        const source = eventDriven ? 'local:v2' : 'rpc:v1'
+        const trace = new QuoteTrace(poolInfo.pool_name, pool_address, blockNumber, source)
+        trace.mark('trigger')
+        let stage = 'compute'
+        try {
+            const quote_amount_usd = getQuoteAmountUsd(poolInfo)
+            const quoteStartTime = Date.now()
+            const txid = evt ? (evt.txHash || 'account') : 'block'
+            const txIndex = evt?.writeVersion
+
+            let askQuote: QuoteResultType, bidQuote: QuoteResultType
+            if (eventDriven) {
+                ;[askQuote, bidQuote] = await Promise.all([this.quoteV2(poolInfo, true), this.quoteV2(poolInfo, false)])
+            } else {
+                ;[askQuote, bidQuote] = await Promise.all([this.quoteV1(poolInfo, true), this.quoteV1(poolInfo, false)])
+            }
+            trace.mark('compute')
+            // 通用 sanity：ask 含 fee 恒 ≥ bid。ask<bid = 方向/公式 bug → fail-loud（不推坏价）
+            const askN = Number(askQuote.price), bidN = Number(bidQuote.price)
+            if (askN > 0 && bidN > 0 && askN < bidN) {
+                throw new Error(`ask(${askN}) < bid(${bidN}) — 异常价差，丢弃该报价`)
+            }
+            this.poolLastQuoteTimeMap.set(pool_address, Date.now())
+
+            stage = 'depth'
+            // 本次报价只查一次 token 价：传给 calculateDepth，并随 bundle 给 publishQuote 复用
+            const t0a = poolInfo.tokenA?.address, t1a = poolInfo.tokenB?.address
+            const priceMap = (t0a && t1a) ? await this.chain.loadTokenPrices([t0a, t1a]) : new Map<string, { price: string } | undefined>()
+            const depth = await this.calculateDepth(poolInfo, pool_address, priceMap)
+            trace.mark('depth')
+            trace.set('ask', askQuote.price); trace.set('bid', bidQuote.price)
+            trace.set('tiers', depth?.ask?.tiers?.length ?? 0); trace.set('quote_amount_usd', quote_amount_usd); trace.set('txid', txid)
+            return { poolInfo, quote_amount_usd, streamTimestamp, quoteStartTime, blockNumber, txIndex, askQuote, bidQuote, txid, source, depth, priceMap, trace }
+        } catch (error) {
+            trace.markError(stage, error instanceof Error ? error.message : String(error))
+            trace.flush()
+            return null
+        }
+    }
+
+    // ════════════ 推送 + verify（基类）════════════
+
+    protected publishQuote(result: QuoteBundle): void {
+        const poolAddr = result.poolInfo.pool_address
+        const isV2 = result.source?.endsWith(':v2')
+
+        // ── 步骤4 publish：延迟关键路径，最先做 —— verify/上报绝不挡在推价前面 ──
+        let shouldPush = true
+        if (result.source?.endsWith(':v1')) {
+            shouldPush = true   // v1 区块兜底：无条件推（SDK/链上读 latest 恒最新，不参与 watermark）
+        } else {
+            const incomingTx = result.txIndex
+            if (!Number.isInteger(incomingTx)) {
+                // writeVersion 缺省（wire 暂未携带）：退化为无条件推（对齐 v1 / SUI 缺 txIndex 行为），step 2 补 wire 后自动启用去重
+                shouldPush = true
+            } else {
+                const tx = incomingTx as number
+                shouldPush = !this.isStaleUpdate(poolAddr, result.blockNumber, tx)
+                if (shouldPush) this.lastPublished.set(poolAddr, { block: result.blockNumber, txIndex: tx })
+            }
+        }
+        if (shouldPush) {
+            on_quote_response({
+                appConfig: this.appConfig, poolInfo: result.poolInfo, quoteAmountUsd: result.quote_amount_usd,
+                streamTime: result.streamTimestamp, quoteStartTime: result.quoteStartTime, blockNumber: result.blockNumber,
+                quotes: [result.askQuote, result.bidQuote], txid: result.txid, source: result.source, depth: result.depth,
+            })
+            // v2 留 info 痕（事件驱动天然低频不刷屏）；v1 高频维持 debug 级 —— 防"v2 无日志被误判没跑"
+            if (isV2) {
+                log_info(`[QUOTE OK v2] ${result.poolInfo.pool_name} ask=${result.askQuote.price} bid=${result.bidQuote.price} slot=${result.blockNumber} wv=${result.txIndex ?? '-'} ${result.txid}`)
+            }
+        }
+        result.trace?.set('published', shouldPush); result.trace?.mark('publish')
+
+        // ── 步骤5 verify：诊断旁路，在推价之后 —— 不阻塞询价。去重与否都执行（供后续对账）──
+        const candidateTiers = isV2 && result.depth ? {
+            ask_tiers: result.depth.ask.tiers.map(t => ({ pct: t.pct, price: t.price, amount: t.amount, amount_in: t.amount_in })),
+            bid_tiers: result.depth.bid.tiers.map(t => ({ pct: t.pct, price: t.price, amount: t.amount, amount_in: t.amount_in })),
+        } : {}
+        report_quote_candidate({
+            pool_address: poolAddr, pair: result.poolInfo.pair, dex_id: result.poolInfo.dex_id,
+            source: result.source || '', block_number: result.blockNumber,
+            ask_price: result.askQuote.price, bid_price: result.bidQuote.price, ...candidateTiers,
+        })
+        const quoteId = result.txid?.slice(0, 10) || `slot:${result.blockNumber}`
+        const tiersArg = isV2 ? { askTiers: result.depth?.ask?.tiers, bidTiers: result.depth?.bid?.tiers } : undefined
+        // Solana 地址 base58 大小写敏感，priceMap 用原地址 key（不 lowercase）
+        const t0a = result.poolInfo.tokenA?.address, t1a = result.poolInfo.tokenB?.address
+        const p0 = t0a ? Number(result.priceMap?.get(t0a)?.price) || 0 : 0
+        const p1 = t1a ? Number(result.priceMap?.get(t1a)?.price) || 0 : 0
+        this.quotePriceVerify.cacheQuote(
+            poolAddr, quoteId, result.source || '',
+            Number(result.askQuote.price), Number(result.bidQuote.price),
+            result.blockNumber, result.quote_amount_usd, p0, p1, tiersArg,
+        )
+        result.trace?.mark('verify'); result.trace?.flush()
+    }
+}

package/src/quote/chain_ops.ts

@@ -0,0 +1,91 @@
+import { AppConfig, CHAIN_ID, DEX_ID, log_warn, StandardPoolInfoType } from '@clonegod/ttd-core/dist'
+import { Connection, PublicKey } from '@solana/web3.js'
+import { subscribe_pool_account_update } from '../common/subscribe_account_update'
+import { SolPoolEvent, toSolPoolEvent } from './pool_event'
+import { TokenPriceCache } from './pricing/token_price_cache'
+
+/**
+ * SolanaChainOps —— 链/VM 维能力（组合注入，对齐 BSC ChainOps/EvmChainOps、SUI SuiChainOps 的角色）。
+ *
+ * 把「询价流程不变、链能力可换」收成一个对象：同一套 AbstractDexQuote 模板，Solana 注入 SolanaChainOps。
+ * 与 SUI 的差异：
+ *   - 池事件源是 stream-quote 的 **WS 通道**（subscribe_pool_account_update，port STREAM_WS_QUOTE_PORT），
+ *     推送的是**账户原始快照**（base64），非结构化 swap 事件（详见 pool_event.ts）。
+ *   - assertProgramDeployed 用 connection.getAccountInfo + executable 校验（Solana 无 eth_getCode）。
+ *   - Solana 地址是 base58 **大小写敏感**，loadTokenPrices 用原地址作 key（不可 lowercase）。
+ */
+export class SolanaChainOps {
+    readonly chainId = CHAIN_ID.SOLANA
+
+    constructor(
+        private readonly appConfig: AppConfig,
+        private readonly connection: Connection,
+        private readonly tokenPriceCache: TokenPriceCache,
+    ) {}
+
+    /** Solana 地址 = base58 编码的 32 字节 pubkey；用 PublicKey 构造器校验最稳。 */
+    isValidPoolAddress(addr: string): boolean {
+        try {
+            // eslint-disable-next-line no-new
+            new PublicKey(addr)
+            return true
+        } catch {
+            return false
+        }
+    }
+
+    /**
+     * 确认 program/账户确实部署在本链（对齐 BSC ChainOps.assertContractDeployed，抓"地址抄错/抄别链"）。
+     * Solana = getAccountInfo + executable 校验。空串跳过。fail-loud（找不到/非可执行即抛）。
+     */
+    async assertProgramDeployed(programAddress: string): Promise<void> {
+        if (!programAddress) return
+        const info = await this.connection.getAccountInfo(new PublicKey(programAddress))
+        if (!info) {
+            throw new Error(`[chain-ops] program ${programAddress} 在本链不存在（getAccountInfo=null）—— 疑似抄错地址/抄别链`)
+        }
+        if (!info.executable) {
+            throw new Error(`[chain-ops] account ${programAddress} 非 executable program —— 疑似把数据账户当 program`)
+        }
+    }
+
+    /**
+     * 查 token USD 价（地址→{price}）。供 depth/verify 的 USD 口径。
+     * ⚠ key 用**原始地址**（base58 大小写敏感，不能 lowercase）。
+     */
+    async loadTokenPrices(addresses: string[]): Promise<Map<string, { price: string } | undefined>> {
+        const out = new Map<string, { price: string } | undefined>()
+        await Promise.all(addresses.map(async addr => {
+            try {
+                const p = await this.tokenPriceCache.getTokenPrice(addr)
+                out.set(addr, { price: p.price })
+            } catch {
+                out.set(addr, undefined)
+            }
+        }))
+        return out
+    }
+
+    /** 订阅新区块（v1 兜底触发）—— 消费 stream-block 的 new_block 通道。 */
+    subscribeNewBlock(handler: (raw: string) => void): void {
+        this.appConfig.arb_event_subscriber.subscribe_new_block(this.chainId, handler)
+    }
+
+    /**
+     * 订阅池子账户更新（v2 触发）—— 消费 stream-quote 的 WS 通道。
+     * subscribe_pool_account_update 内部 onOpen 时只 send 注册池，stream-quote 据此扇出；
+     * 这里把原始 wire 归一化为 SolPoolEvent 再回调。
+     */
+    subscribePoolEvents(dexId: string, pools: StandardPoolInfoType[], handler: (evt: SolPoolEvent) => void): void {
+        const dex = dexId.toUpperCase() as DEX_ID
+        const poolSet = new Set(pools.map(p => p.pool_address))
+        subscribe_pool_account_update(dex, pools, (data) => {
+            try {
+                if (!poolSet.has(data.pool_address)) return
+                handler(toSolPoolEvent(data))
+            } catch (e) {
+                log_warn(`[SolanaChainOps] bad pool account update`, data)
+            }
+        })
+    }
+}