@clonegod/ttd-sol-common 2.0.67 → 2.0.68

package/src/quote/verify/quote_price_verify.ts

@@ -0,0 +1,508 @@
+/**
+ * 询价价格验证
+ *
+ * 验证逻辑：
+ * 1. 每次询价完成后，缓存 ask/bid 价格 + blockNumber
+ * 2. 收到同池子新 block 的第一笔 swap 时，用 swap 的 amount0/amount1 算出实际执行价格
+ * 3. 对比缓存的 ask 或 bid，打印偏差 bps
+ *
+ * 支持两种事件类型：
+ * - CLMM swap 事件：带符号的 amount0/amount1
+ * - AMM sync 事件：通过 reserve 变化量推算
+ *
+ * 通过 VERIFY_QUOTE_PRICE=true 启用
+ */
+
+import { resolveTradeDirection, calculateStandardPrice } from '../../utils/trade_direction';
+import { report_data_to_analyze, QuoteTier } from '@clonegod/ttd-core';
+
+// ========== 类型定义 ==========
+
+interface CachedQuote {
+    priceId: string;
+    source: string;
+    askPrice: number;
+    bidPrice: number;
+    /**
+     * tier 模式：缓存完整 ask/bid 档位数组（W3 新增）
+     * - V2 路径会传完整 5 档
+     * - V1 兜底路径会传单档（仅 pct=0.2）
+     * - 未传时 checkSwap 走 scalar fallback（向后兼容旧 DEX 包）
+     */
+    askTiers?: QuoteTier[];
+    bidTiers?: QuoteTier[];
+    /**
+     * 该报价基于哪个 block 末态算的（cacheQuote 时收到事件的 blockNumber）。
+     * 验证规则：只接受 swap.block === referenceBlock + 1 的"下一 block 第一笔 swap"。
+     * - swap.block === referenceBlock：同 block，旧报价没意义，跳
+     * - swap.block > referenceBlock + 1：报价滞后或漏更新，比对会污染统计，跳
+     * - swap.block < referenceBlock：不可能，但 defensive
+     */
+    referenceBlock: number;
+    quoteAmountUsd: number;
+    /**
+     * 该 referenceBlock 是否已经被对应的 next-block 验证过。
+     * == referenceBlock 表示已验过；防同 block 内多笔 swap 重复验证。
+     */
+    verifiedReferenceBlock: number;
+    /** 缓存的 token0 USD 价格（cacheQuote 时传入，供 checkSwap 过滤用） */
+    token0PriceUsd: number;
+    /** 缓存的 token1 USD 价格 */
+    token1PriceUsd: number;
+}
+
+/**
+ * Tier 选择/插值结果
+ */
+interface TierMatch {
+    /** 选中（或插值得到）的档位 */
+    tier: QuoteTier;
+    /** 实际成交量落点 vs tier 档位的关系 */
+    mode: 'exact' | 'interpolated' | 'extrapolated_low' | 'extrapolated_high' | 'single_tier';
+    /** 命中区间的下界标准档 pct（extrapolated_low 时 null = 小于最小档）*/
+    lo_pct: number | null;
+    /** 命中区间的上界标准档 pct（extrapolated_high 时 null = 超出最大档）*/
+    hi_pct: number | null;
+}
+
+/**
+ * 按实际 amount_in 在 tiers 数组里挑出/插值出参考档位
+ *
+ * 算法：
+ *  - tiers 数组按 amount_in 升序排
+ *  - actualAmountIn <= tiers[0].amount_in     → extrapolated_low（用最低档兜底）
+ *  - actualAmountIn >= tiers[last].amount_in  → extrapolated_high（用最高档兜底，标记"超出深度"）
+ *  - 落在两档之间 → 线性插值
+ *  - tiers.length === 1 → single_tier（V1 兜底场景）
+ */
+function pickMatchingTier(tiers: QuoteTier[], actualAmountIn: number): TierMatch | null {
+    if (!tiers || tiers.length === 0) return null;
+    if (tiers.length === 1) return { tier: tiers[0], mode: 'single_tier', lo_pct: tiers[0].pct, hi_pct: tiers[0].pct };
+
+    const sorted = [...tiers].sort((a, b) => a.amount_in - b.amount_in);
+    const top = sorted[sorted.length - 1];
+
+    // 严格"小于"才算外推；等于最低/最高档算 exact（保持统计 mode 标签准确）
+    if (actualAmountIn < sorted[0].amount_in) {
+        return { tier: sorted[0], mode: 'extrapolated_low', lo_pct: null, hi_pct: sorted[0].pct };
+    }
+    if (actualAmountIn > top.amount_in) {
+        return { tier: top, mode: 'extrapolated_high', lo_pct: top.pct, hi_pct: null };
+    }
+    for (let i = 0; i < sorted.length - 1; i++) {
+        const lower = sorted[i];
+        const upper = sorted[i + 1];
+        if (actualAmountIn >= lower.amount_in && actualAmountIn <= upper.amount_in) {
+            // 边界相等 → exact
+            if (actualAmountIn === lower.amount_in) return { tier: lower, mode: 'exact', lo_pct: lower.pct, hi_pct: lower.pct };
+            if (actualAmountIn === upper.amount_in) return { tier: upper, mode: 'exact', lo_pct: upper.pct, hi_pct: upper.pct };
+            const span = upper.amount_in - lower.amount_in;
+            if (span <= 0) return { tier: lower, mode: 'exact', lo_pct: lower.pct, hi_pct: lower.pct };
+            const ratio = (actualAmountIn - lower.amount_in) / span;
+            const lerp = (a: number, b: number) => a + ratio * (b - a);
+            return {
+                tier: {
+                    pct: lerp(lower.pct, upper.pct),
+                    price: lerp(lower.price, upper.price),
+                    amount: lerp(lower.amount, upper.amount),
+                    amount_in: actualAmountIn,
+                    amount_in_usd: lerp(lower.amount_in_usd, upper.amount_in_usd),
+                    fee: lerp(lower.fee, upper.fee),
+                    fee_usd: lerp(lower.fee_usd, upper.fee_usd),
+                },
+                mode: 'interpolated',
+                lo_pct: lower.pct,
+                hi_pct: upper.pct,
+            };
+        }
+    }
+    return { tier: top, mode: 'extrapolated_high', lo_pct: top.pct, hi_pct: null };
+}
+
+export interface CheckSwapParams {
+    poolAddress: string;
+    poolName: string;
+    blockNumber: number;
+    /** 验证用的 swap 交易哈希 */
+    txHash: string;
+    /** swap 事件的 amount0；含义由 swapperDeltaConvention 决定 */
+    amount0: string;
+    /** swap 事件的 amount1；含义同上 */
+    amount1: string;
+    token0Address: string;
+    token1Address: string;
+    token0Decimals: number;
+    token1Decimals: number;
+    /** 用于 resolveTradeDirection 判断 ask/bid */
+    poolInfo: { tokenA: any; tokenB: any; quote_token: string };
+    /**
+     * amount 符号约定（**实测**结论，BscScan 验证）：
+     *   - false（默认 / V3 CLMM）：amount0/1 是**池子的 delta**（正=池子收到=swapper 输入）
+     *   - true（V4 / Pancake Infinity / Uniswap V4）：amount0/1 是**swapper 的 delta**（正=swapper 收到=swapper 输出）
+     * V4 caller 必须传 true，否则 side 会被算反（参见 tx 0xea45784b... / 0xdae0faa7... 验证）。
+     */
+    swapperDeltaConvention?: boolean;
+}
+
+// ========== 主类 ==========
+
+export class QuotePriceVerify {
+    /**
+     * per-source cache: pool → source → CachedQuote
+     *
+     * 设计意图：v1/v2/v3 每个 source 独立 cache 槽，互不覆盖。
+     * 每笔 chain Swap 触发时遍历该池的所有 source，每个独立做一次 verify 上报，
+     * 跨源精度量化各自独立。yynode 抢跑不影响 v1/v2 的 verify 数据。
+     */
+    private quoteCache: Map<string, Map<string, CachedQuote>> = new Map();
+    private get enabled(): boolean {
+        return process.env.VERIFY_QUOTE_PRICE === 'true';
+    }
+
+    /**
+     * 询价完成后调用，缓存 ask/bid 价格（per-source 写入对应槽）。
+     *
+     * 同 (pool, source, refBlock) 重复 cache 的语义（典型场景：USD 异步补全后第二次 cacheQuote）：
+     *   - askPrice / bidPrice / quoteAmountUsd / token{0,1}PriceUsd 用新传入值覆盖（USD 补全有意义）
+     *   - **verifiedReferenceBlock 保留**（防止"已验过的 quote 被重置后又验一次"，违反单 quote 单验约定）
+     *
+     * 不同 refBlock：完全重置（含 verifiedReferenceBlock=0）→ 新 quote 周期，下一笔 swap 可正常验
+     */
+    cacheQuote(
+        poolAddress: string,
+        priceId: string,
+        source: string,
+        askPrice: number,
+        bidPrice: number,
+        blockNumber: number,
+        quoteAmountUsd: number,
+        token0PriceUsd: number = 0,
+        token1PriceUsd: number = 0,
+        tiers?: { askTiers?: QuoteTier[]; bidTiers?: QuoteTier[] },
+    ): void {
+        if (!this.enabled) return;
+        if (!source) return; // source 是 key，必须有
+
+        let sourceMap = this.quoteCache.get(poolAddress);
+        if (!sourceMap) {
+            sourceMap = new Map();
+            this.quoteCache.set(poolAddress, sourceMap);
+        }
+
+        // 同 source 同 refBlock 重复 cache：保留 verifiedReferenceBlock 状态（避免 USD 二次补全导致重验）
+        const existing = sourceMap.get(source);
+        const verifiedReferenceBlock = (existing && existing.referenceBlock === blockNumber)
+            ? existing.verifiedReferenceBlock
+            : 0;
+
+        sourceMap.set(source, {
+            priceId, source, askPrice, bidPrice,
+            askTiers: tiers?.askTiers,
+            bidTiers: tiers?.bidTiers,
+            referenceBlock: blockNumber,
+            verifiedReferenceBlock,
+            quoteAmountUsd,
+            token0PriceUsd, token1PriceUsd,
+        });
+    }
+
+    /**
+     * 收到 swap 事件时调用：遍历该池子下所有 source 的 cache，**收集** verifiable，
+     * **一次性 upload 1 条 verify 记录**（含 sources field，前端表 1 行 N 列展示）。
+     *
+     * 设计选择（合并上报 vs 上报后合并）：
+     *   - 合并上报（当前）：1 条原子 upload，含 sources。优点：网络/存储省 30-40%，UI 零聚合开销，
+     *                       原子性强（不会 partial state），跟"per-source cache 是单一权威源"哲学一致。
+     *   - 上报后合并：N 条独立 upload，后端 group by tx_hash 聚合。
+     *                优点：按 source SQL 查询友好；缺点：网络/存储多 N 倍，partial state 风险，
+     *                后端需聚合逻辑。
+     *   选择"合并上报"因为：UI 表是核心查询模式（聚合视角），按 source 长期分析非主用法
+     *   （真要做用 mem_quote_source_diff 更合适）。
+     *
+     * - primary source = referenceBlock 最大的（最新 quote）→ 主字段 (source / ref_price / diff_bps)
+     * - sources = 全 verifiable source 的 {ask, bid, diff_bps, quote_block}（前端 v1/v2/v3 各列）
+     * - 同 block 后续 swap 被 verifiedReferenceBlock 拦掉（每 source 每 quote 只验 1 次）
+     */
+    /** 返回 [Verify] 日志行（调用方择时打印——基类在 [QUOTE OK] 之后输出，保证日志顺序）；无可验证则返回 void。 */
+    checkSwap(params: CheckSwapParams): string | void {
+        if (!this.enabled) return;
+
+        const { poolAddress, blockNumber, txHash, poolInfo, token0Address } = params;
+        const sourceMap = this.quoteCache.get(poolAddress);
+        if (!sourceMap || sourceMap.size === 0) return;
+
+        // 1. swap 方向 / amount（跟 source 无关）
+        const swapData = this.deriveSwapDirection(params);
+        if (!swapData) return;
+
+        // 2. 算 exec_price（跟 source 无关）
+        const direction = resolveTradeDirection(poolInfo, true);
+        const inputIsQuoteToken = swapData.inputTokenAddress.toLowerCase() === direction.quoteToken.address.toLowerCase();
+        const isBuy = inputIsQuoteToken;
+        const execPriceStr = calculateStandardPrice(swapData.inputAmountUi, swapData.outputAmountUi, isBuy);
+        const execPrice = Number(execPriceStr);
+        if (execPrice <= 0) return;
+
+        // 3. 遍历每个 source 收集 verifiable
+        //    tier 模式（W3）：用实际 swap 的 inputAmount 在 cached.askTiers/bidTiers 里匹配 + 插值
+        //    scalar 模式（向后兼容）：直接用 cached.askPrice/bidPrice
+        const verifiable: Array<{
+            source: string;
+            cached: CachedQuote;
+            refPrice: number;
+            diff_bps: number;
+            /** 实际成交量命中的 tier 信息（tier 模式才有） */
+            tierInfo?: {
+                matched_pct: number;
+                mode: TierMatch['mode'];
+                tier_amount_in: number;
+                lo_pct: number | null;
+                hi_pct: number | null;
+            };
+        }> = [];
+
+        for (const [source, cached] of sourceMap) {
+            if (blockNumber <= cached.referenceBlock) continue;
+            if (cached.verifiedReferenceBlock === cached.referenceBlock) continue;
+
+            const tiers = isBuy ? cached.askTiers : cached.bidTiers;
+            let refPrice: number;
+            let tierInfo: typeof verifiable[0]['tierInfo'] | undefined;
+
+            // 所有 source（V1/V2/V3）的 tiers 都按统一契约输出真实非零 amount_in，
+            // tier 匹配可无分支启用（V3 单档时退化为 single_tier 模式）
+            if (tiers && tiers.length > 0) {
+                // tier 模式：按 actualAmountIn 匹配/插值
+                const match = pickMatchingTier(tiers, swapData.inputAmountUi);
+                if (!match) continue;
+                refPrice = match.tier.price;
+                tierInfo = {
+                    matched_pct: parseFloat(match.tier.pct.toFixed(4)),
+                    mode: match.mode,
+                    tier_amount_in: match.tier.amount_in,
+                    lo_pct: match.lo_pct,
+                    hi_pct: match.hi_pct,
+                };
+            } else {
+                // scalar fallback：旧 DEX 包未传 tiers 时使用
+                refPrice = isBuy ? cached.askPrice : cached.bidPrice;
+            }
+
+            if (refPrice <= 0) continue;
+
+            cached.verifiedReferenceBlock = cached.referenceBlock;
+            const diff_bps = (refPrice - execPrice) / refPrice * 10000;
+            verifiable.push({ source, cached, refPrice, diff_bps, tierInfo });
+        }
+
+        if (verifiable.length === 0) return;
+
+        // 4. 选 primary（referenceBlock 最大 = 最新 quote）
+        verifiable.sort((a, b) => b.cached.referenceBlock - a.cached.referenceBlock);
+        const primary = verifiable[0];
+
+        // 5. 构造 sources field（前端"1 行多列"用，每 source 独立 diff_bps）
+        //    tier 模式：额外携带 matched_pct / mode / tier_amount_in（V1 单档 vs V2 多档可区分）
+        const sources: Record<string, {
+            ask: number;
+            bid: number;
+            /** diff_bps 真正用来比对的 refPrice（tier 模式 = 匹配/插值的 tier price；scalar 模式 = ask/bid 对应那个）
+             *  UI 应该显示这个数而不是 ask/bid，否则会出现"显示价 vs diff_bps 不自洽"的视觉 bug */
+            matched_ref_price: number;
+            diff_bps: number;
+            quote_block: number;
+            matched_pct?: number;
+            tier_mode?: TierMatch['mode'];
+            tier_amount_in?: number;
+        }> = {};
+        for (const r of verifiable) {
+            sources[r.source] = {
+                ask: r.cached.askPrice,
+                bid: r.cached.bidPrice,
+                matched_ref_price: r.refPrice,
+                diff_bps: parseFloat(r.diff_bps.toFixed(1)),
+                quote_block: r.cached.referenceBlock,
+                ...(r.tierInfo && {
+                    matched_pct: r.tierInfo.matched_pct,
+                    tier_mode: r.tierInfo.mode,
+                    tier_amount_in: r.tierInfo.tier_amount_in,
+                }),
+            };
+        }
+
+        // 6. 用 primary source 走 compareAndLog（构造主字段 + analyze 上报，返回日志行），透传 sources + primary tierInfo
+        //    refPrice 直接传 primary.refPrice（已含 tier 匹配后的值），避免重新算
+        return this.compareAndLog(
+            poolAddress, params.poolName, poolInfo, primary.cached,
+            swapData.inputTokenAddress, swapData.outputTokenAddress,
+            swapData.inputAmountUi, swapData.outputAmountUi,
+            primary.refPrice, execPrice,
+            primary.cached.token0PriceUsd, primary.cached.token1PriceUsd,
+            token0Address, blockNumber, txHash,
+            sources,
+            primary.tierInfo,
+        );
+    }
+
+    /**
+     * 从 swap event 的 amount0/amount1 反推 swapper 的方向 + 数量。
+     * 跟 source 无关（同一笔 swap，方向 / 数量是客观事实），所以从 checkSwap 主流程提取出来复用。
+     */
+    private deriveSwapDirection(params: CheckSwapParams): {
+        inputTokenAddress: string;
+        outputTokenAddress: string;
+        inputAmountUi: number;
+        outputAmountUi: number;
+    } | null {
+        const { amount0, amount1, token0Address, token1Address, token0Decimals, token1Decimals } = params;
+
+        // V4 (Pancake Infinity / Uniswap V4) amount = swapper's delta（正=swapper 收到）；
+        // V3 amount = 池子的 delta（正=池子收到）。统一翻转到"池子 delta"语义。
+        const sign = params.swapperDeltaConvention ? -1n : 1n;
+        const amt0 = BigInt(amount0) * sign;
+        const amt1 = BigInt(amount1) * sign;
+
+        if (amt0 === 0n && amt1 === 0n) return null;
+
+        if (amt0 > 0n && amt1 < 0n) {
+            // swapper 输入 token0，获得 token1
+            return {
+                inputTokenAddress: token0Address,
+                outputTokenAddress: token1Address,
+                inputAmountUi: Number(amt0) / Math.pow(10, token0Decimals),
+                outputAmountUi: Number(-amt1) / Math.pow(10, token1Decimals),
+            };
+        } else if (amt0 < 0n && amt1 > 0n) {
+            // swapper 输入 token1，获得 token0
+            return {
+                inputTokenAddress: token1Address,
+                outputTokenAddress: token0Address,
+                inputAmountUi: Number(amt1) / Math.pow(10, token1Decimals),
+                outputAmountUi: Number(-amt0) / Math.pow(10, token0Decimals),
+            };
+        }
+        return null;
+    }
+
+    /**
+     * 通用对比逻辑：计算执行价格，跟缓存的 ask/bid 对比
+     */
+    private compareAndLog(
+        poolAddress: string,
+        poolName: string,
+        poolInfo: { tokenA: any; tokenB: any; quote_token: string },
+        cached: CachedQuote,
+        inputTokenAddress: string,
+        outputTokenAddress: string,
+        inputAmountUi: number,
+        outputAmountUi: number,
+        refPrice: number,
+        execPriceNum: number,
+        token0PriceUsd?: number,
+        token1PriceUsd?: number,
+        token0Address?: string,
+        swapBlockNumber?: number,
+        txHash?: string,
+        sources?: Record<string, {
+            ask: number; bid: number; diff_bps: number; quote_block: number;
+            matched_pct?: number; tier_mode?: TierMatch['mode']; tier_amount_in?: number;
+        }>,
+        primaryTierInfo?: { matched_pct: number; mode: TierMatch['mode']; tier_amount_in: number; lo_pct: number | null; hi_pct: number | null },
+    ): string | void {
+        if (inputAmountUi <= 0 || outputAmountUi <= 0) return;
+
+        // 估算 USD 金额
+        let swapUsd = 0;
+        if (token0PriceUsd && token1PriceUsd && token0Address) {
+            const inputIsToken0 = inputTokenAddress.toLowerCase() === token0Address.toLowerCase();
+            swapUsd = inputIsToken0
+                ? inputAmountUi * token0PriceUsd
+                : inputAmountUi * token1PriceUsd;
+        }
+
+        // 判断是 买入 base 还是 卖出 base
+        const direction = resolveTradeDirection(poolInfo, true);
+        const baseToken = direction.baseToken;
+        const quoteToken = direction.quoteToken;
+
+        const inputIsQuoteToken = inputTokenAddress.toLowerCase() === quoteToken.address.toLowerCase();
+        const isBuy = inputIsQuoteToken;
+
+        const side = isBuy ? 'BUY' : 'SELL';
+
+        if (refPrice <= 0 || execPriceNum <= 0) return;
+
+        // sign 约定：(ref - exec) / ref —— "我们报价 vs 实际成交"
+        //   "+" = 我们报价 > 实际成交（quote 偏高）
+        //   "-" = 我们报价 < 实际成交（quote 偏低）
+        // 不论 BUY (ref=ask) / SELL (ref=bid)，含义一致；business 决策看 |diff_bps|，sign 仅指方向
+        const diffBps = (refPrice - execPriceNum) / refPrice * 10000;
+        const absDiffBps = Math.abs(diffBps);
+        // 阈值统一：<5 ✅ / 5-10 ⚠️ / ≥10 ❌（前端颜色阈值同步）
+        const status = absDiffBps < 5 ? '✅' : absDiffBps < 10 ? '⚠️' : '❌';
+        const usdStr = swapUsd > 0 ? `$${swapUsd.toFixed(0)}` : '$?';
+
+        // USD 范围标注（不过滤，全部打印）
+        // 规则：仅排除"过大的 swap"（超过 2× 询价金额），偏差大可能是滑点而非报价不准；
+        //      小于询价金额的 swap 仍纳入 in_range（小单滑点小，价格偏差对询价精度评估有效）。
+        const maxUsd = cached.quoteAmountUsd * 2;
+        const inRange = swapUsd <= 0 || swapUsd <= maxUsd;
+        const rangeTag = inRange ? '' : ' [out]';
+
+        const tradeFlow = isBuy
+            ? `${inputAmountUi.toFixed(4)} ${quoteToken.symbol} -> ${outputAmountUi.toFixed(4)} ${baseToken.symbol}`
+            : `${inputAmountUi.toFixed(4)} ${baseToken.symbol} -> ${outputAmountUi.toFixed(4)} ${quoteToken.symbol}`;
+
+        // 格式：quote[source blk:N] price vs swap[blk:M tx:hash] exec_price → diff
+        const quoteSrc = cached.source || '?';
+        const quoteTag = `quote[${quoteSrc} blk:${cached.referenceBlock}]`;
+        const swapBlk = swapBlockNumber || '?';
+        const swapTx = txHash ? ` ${txHash.slice(0, 10)}` : '';
+        const swapTag = `swap[blk:${swapBlk}${swapTx}]`;
+        const priceLabel = isBuy ? 'ask' : 'bid';
+
+        const msg = `  ↳ [Verify] ${side} ${usdStr} (${tradeFlow}) ${quoteTag} ${priceLabel}=${refPrice.toFixed(12)} vs ${swapTag} exec=${execPriceNum.toFixed(12)} diff=${diffBps > 0 ? '+' : ''}${diffBps.toFixed(1)}bps ${status}${rangeTag}`;
+        // 注：日志行不在此打印，返回给调用方（基类在 [QUOTE OK] 之后打，保证"先报价后验证"顺序）；analyze 上报仍即时发。
+
+        // 上报 verify 结果到 analyze
+        try {
+            report_data_to_analyze('QuoteVerify', {
+                pool_address: poolAddress,
+                pool_name: poolName,
+                price_id: cached.priceId,
+                source: cached.source,         // 当时实际推送的源（用于 analyze 标识 pushed 列）
+                quote_amount_usd: cached.quoteAmountUsd,   // 询价金额（前端展示 in_range 阈值）
+                quote_block: cached.referenceBlock,
+                swap_block: swapBlockNumber,
+                tx_hash: txHash || '',
+                side,
+                ref_price: refPrice,
+                exec_price: execPriceNum,
+                diff_bps: parseFloat(diffBps.toFixed(1)),
+                swap_usd: parseFloat(swapUsd.toFixed(0)),
+                in_range: inRange,
+                input_amount: inputAmountUi,
+                output_amount: outputAmountUi,
+                input_symbol: isBuy ? quoteToken.symbol : baseToken.symbol,
+                output_symbol: isBuy ? baseToken.symbol : quoteToken.symbol,
+                status,
+                time: Date.now(),
+                // per-source 全量数据：前端"1 行 N 列"展示用
+                // 直接来自 per-source cache，无 TTL 限制（candidate 表 5s TTL，作为兜底）
+                sources: sources || undefined,
+                // tier 模式（W3）：primary source 命中的档位信息（兼容 V1 单档/V2 多档）
+                ...(primaryTierInfo && {
+                    matched_tier_pct: primaryTierInfo.matched_pct,
+                    matched_tier_mode: primaryTierInfo.mode,
+                    matched_tier_amount_in: primaryTierInfo.tier_amount_in,
+                    matched_tier_lo_pct: primaryTierInfo.lo_pct,   // 命中区间下界标准档 pct（前端 size档位列显示区间）
+                    matched_tier_hi_pct: primaryTierInfo.hi_pct,   // 命中区间上界标准档 pct
+                }),
+            })
+        } catch (_) {
+            // 上报失败不影响主流程
+        }
+
+        return msg;
+    }
+}

package/src/trade/index.ts

@@ -1,6 +1,5 @@
 export * from './tx_result_check'
 export * from './tx_result_parse'
-export * from '../config/SolanaTradeAppConfig'
 export * from './tx_builder'
 export * from './send'
 export * from './jito_tip_wallets'

package/src/trade/tx_builder.ts

@@ -2,7 +2,7 @@ import { CHAIN_ID, TradeContext } from "@clonegod/ttd-core/dist";
 import { ComputeBudgetProgram, Connection, Keypair, LAMPORTS_PER_SOL, PublicKey, SystemProgram, Transaction, TransactionInstruction } from "@solana/web3.js";
 import { LAMPORTS_PER_MICRO_LAMPORTS } from "../common";
 import { SolanaBlockMetaUpdateEvent } from "../types";
-import { SolanaTradeAppConfig } from "../config/SolanaTradeAppConfig";
+import { SolanaTradeAppConfig } from "../appconfig/SolanaTradeAppConfig";
 import { HELIUS_TIP_ACCOUNTS } from "./send/helius";
 import { getJitoTipAccount } from "./send/jito";
 import { JitoTipWalletManager } from "./jito_tip_wallets";

package/src/trade/tx_result_parse.ts

@@ -91,6 +91,7 @@ export class TransactionResultParser {
             wallet: owner,
             block_time: blockTime,
             block_number: slot,
+            tx_index: 0,   // Solana 此处 ParsedTransactionWithMeta 无 slot 内序号；与 SUI parser 一致先占位，Phase 1/2 再补
             txid,
             pool_address,
             tokenA: {

package/src/types/index.ts

@@ -5,6 +5,9 @@ export enum SolanaPoolAccountType {
     POOL='pool',
     VAULT_A='vaultA',
     VAULT_B='vaultB',
+    // 动态子账户（CLMM tickArray / DLMM binArray，方案 A）：独立 push，不参与 AMM 三账户聚合
+    TICK_ARRAY='tickArray',
+    BIN_ARRAY='binArray',
 }
 
 export interface SolanaAccountUpdateEvent {
@@ -58,16 +61,31 @@ export interface SolanaPoolAccountUpdateEventData {
     pool_name: string
     data: {
         slot: number
-        // tx_index: number
+        /**
+         * Solana 账户写版本（Geyser write_version，全局单调递增，高版本覆盖低版本）。
+         * 询价基类用 (slot, write_version) 做单调水位线去重（AbstractDexQuote / SolPoolEvent）。
+         * AMM 聚合快照取 pool+vault 三账户里的 max（最近一次写）。
+         */
+        write_version?: number
         tx_hash: string
         pool_account: string
         pool_account_data: string
         
-        // AMM 池子的Vault 
+        // AMM 池子的Vault
         vaultA_account?: string
         vaultA_account_data?: string
         vaultB_account?: string
         vaultB_account_data?: string
+
+        /**
+         * 动态子账户更新（CLMM tickArray / DLMM binArray，方案 A）。独立 push：
+         * 该笔只带 sub_account（pool_account_data 为空），询价侧 refreshStateFromEvent 按 role 解码 → 更新本地分布。
+         */
+        sub_account?: {
+            role: string      // 'tickArray' | 'binArray'
+            account: string
+            account_data: string
+        }
     }
 }
 

package/src/utils/index.ts

@@ -0,0 +1 @@
+export * from './trade_direction'

package/src/utils/trade_direction.ts

@@ -0,0 +1,68 @@
+/**
+ * 交易方向工具（与 BSC/SUI 同名文件对齐 —— 链无关，直接照搬 [[feedback_cross_chain_consistency]]）
+ *
+ * 统一处理 isBuy + quote_token 的语义映射，与池子的 tokenA/tokenB 顺序无关。
+ *
+ * 概念：
+ *   pair: "TOKEN/SOL"  → 左边是基础币(base)，右边是报价币(quote)
+ *   quote_token: "SOL" → 用 SOL 报价
+ *   isBuy:
+ *     true  = 买入基础币（花费报价币，获得基础币）→ ask 价格
+ *     false = 卖出基础币（花费基础币，获得报价币）→ bid 价格
+ */
+
+export interface TradeDirectionResult<T = any> {
+    /** 是否是买入（报价币→基础币） */
+    isBuy: boolean;
+    /** 输入代币（保持传入的原始类型） */
+    inputToken: T;
+    /** 输出代币 */
+    outputToken: T;
+    /** 基础币（非报价币） */
+    baseToken: T;
+    /** 报价币 */
+    quoteToken: T;
+}
+
+/**
+ * 从 pool_info + isBuy 推导输入输出代币
+ * 泛型 T 保持 pool_info.tokenA/tokenB 的原始类型（如 StandardTokenInfoType）
+ *
+ * @param poolInfo 池信息（必须包含 tokenA, tokenB, quote_token）
+ * @param isBuy true=买入基础币, false=卖出基础币
+ */
+export function resolveTradeDirection<T = any>(poolInfo: { tokenA: T; tokenB: T; quote_token: string; [key: string]: any }, isBuy: boolean): TradeDirectionResult<T> {
+    const { tokenA, tokenB, quote_token } = poolInfo;
+
+    const quoteToken = [tokenA, tokenB].find(t => (t as any).symbol === quote_token);
+    const baseToken = [tokenA, tokenB].find(t => (t as any).symbol !== quote_token);
+
+    if (!quoteToken || !baseToken) {
+        throw new Error(`Cannot resolve tokens: tokenA=${(tokenA as any)?.symbol}, tokenB=${(tokenB as any)?.symbol}, quote_token=${quote_token}`);
+    }
+
+    // isBuy=true  → 输入报价币，输出基础币
+    // isBuy=false → 输入基础币，输出报价币
+    const inputToken = isBuy ? quoteToken : baseToken;
+    const outputToken = isBuy ? baseToken : quoteToken;
+
+    return { isBuy, inputToken, outputToken, baseToken, quoteToken };
+}
+
+/**
+ * 计算标准化价格：1 基础币 = X 报价币
+ *
+ * @param inputAmount 输入数量（UI 单位）
+ * @param outputAmount 输出数量（UI 单位）
+ * @param isBuy 是否是买入
+ * @returns 价格字符串（1 基础币 = X 报价币）
+ */
+export function calculateStandardPrice(inputAmount: number, outputAmount: number, isBuy: boolean): string {
+    if (isBuy) {
+        // 买入：输入报价币，输出基础币 → 价格 = inputAmount / outputAmount
+        return (inputAmount / outputAmount).toFixed(18);
+    } else {
+        // 卖出：输入基础币，输出报价币 → 价格 = outputAmount / inputAmount
+        return (outputAmount / inputAmount).toFixed(18);
+    }
+}

package/dist/config/SolanaTradeAppConfig.d.ts

@@ -1,10 +0,0 @@
-import { AbstractTradeAppConfig } from "@clonegod/ttd-core/dist";
-import { Connection, Keypair } from "@solana/web3.js";
-export declare class SolanaTradeAppConfig extends AbstractTradeAppConfig {
-    connection: Connection;
-    keypair: Keypair;
-    private ws_client;
-    constructor();
-    init(): Promise<void>;
-    subscribe_wallet_raw_txn_event(): void;
-}

package/dist/config/index.d.ts

@@ -1 +0,0 @@
-export * from './SolanaTradeAppConfig';

package/dist/trade/SolanaTradeAppConfig.d.ts

@@ -1,8 +0,0 @@
-import { AbstractTradeAppConfig } from "@clonegod/ttd-core/dist";
-import { Connection, Keypair } from "@solana/web3.js";
-export declare class SolanaTradeAppConfig extends AbstractTradeAppConfig {
-    connection: Connection;
-    keypair: Keypair;
-    constructor();
-    subscribe_wallet_raw_txn_event(): void;
-}