@clonegod/ttd-sol-common 2.0.67 → 2.0.68

package/src/quote/depth/clmm_depth_calculator.ts

@@ -0,0 +1,321 @@
+/**
+ * CLMM 深度计算器（SUI X64 版）
+ *
+ * port 自 BSC `ttd-bsc-common/src/quote/depth/clmm_depth_calculator.ts`，差异（有理由的偏离）：
+ *   · **sqrtPrice 表示 Q96 → Q64**：SUI CLMM（Cetus/Bluefin/Magma/Momentum，integer-mate V3 家族）用 X64
+ *     定点（sqrtPriceX64 = sqrt(price) × 2^64），故常量 Q96 改 Q64，amount0/1 公式同构换底。
+ *   · **不内建 TickMath**：各 DEX 的 tick→sqrtPrice 由其 SDK 提供（Cetus TickMath.tickIndexToSqrtPriceX64 等），
+ *     调用方把已算好的 sqrtPriceX64 随 tick 传入 → 本模块零 SDK 依赖、零 TickMath 移植。
+ *
+ * 给定价格偏移（bps），计算把现价推到 mid × (1 ± bps/10000) 范围内可成交的 token 数量。
+ * 复用与 swap 引擎相同的 CLMM 数学，但终止条件不同：到达目标 sqrtPrice 即停（非 amountIn 用完）。
+ *
+ * 重要：深度（output amount）与 fee 无关 —— fee 只影响需要多少 input，不影响给定价格范围能产出多少 output。
+ * fee gross-up 在 buildClmmDepth 层做（与 BSC 一致）。
+ */
+
+const Q64 = 1n << 64n;
+
+// ========== 深度计算核心 ==========
+
+/** 已初始化 tick（调用方从 SuiClmmTickCache 物化，sqrtPriceX64 由 DEX SDK TickMath 算）。 */
+export interface DepthTick {
+    index: number;
+    /** 有符号 net liquidity（正=position 下界，负=上界） */
+    liquidityNet: bigint;
+    /** 该 tick 的 sqrtPriceX64（Q64.64） */
+    sqrtPriceX64: bigint;
+}
+
+export interface ClmmDepthInput {
+    /** 当前 sqrtPriceX64（Q64.64） */
+    sqrtPriceX64: bigint;
+    currentTick: number;
+    /** 当前 active liquidity */
+    liquidity: bigint;
+    /** 全量已初始化 tick（含 sqrtPriceX64，无需预排序） */
+    ticks: DepthTick[];
+    /** swap 方向（aToB / zeroForOne，由 resolveTradeDirection 决定） */
+    zeroForOne: boolean;
+    /** 目标价格偏移（如 10, 20） */
+    targetBps: number;
+    inputDecimals: number;
+    outputDecimals: number;
+}
+
+export interface DepthResult {
+    amountInWei: bigint;
+    amountIn: number;
+    amountOutWei: bigint;
+    amountOut: number;
+    currentTick: number;
+    targetTick: number;
+    /** 目标 sqrtPriceX64（Q64.64，用于精确反算 targetPrice） */
+    targetSqrtPriceX64: bigint;
+}
+
+/**
+ * 计算 CLMM 池子在给定价格偏移范围内的深度。
+ * @returns 在 targetBps 价格范围内可获得的 output token 数量（不含 fee）
+ */
+export function calculateClmmDepth(input: ClmmDepthInput): DepthResult {
+    const { currentTick, zeroForOne, targetBps, inputDecimals, outputDecimals } = input;
+
+    const currentSqrtPriceX64 = input.sqrtPriceX64;
+    let liquidity = input.liquidity;
+
+    if (liquidity <= 0n) {
+        return { amountInWei: 0n, amountIn: 0, amountOutWei: 0n, amountOut: 0, currentTick, targetTick: currentTick, targetSqrtPriceX64: currentSqrtPriceX64 };
+    }
+
+    // 1. 目标 sqrtPriceX64
+    const targetSqrtPriceX64 = computeTargetSqrtX64(currentSqrtPriceX64, targetBps, zeroForOne);
+
+    // 2. 现价 → 目标价之间的已初始化 tick（按方向排序）
+    const ticksToTraverse = getTicksBetween(input.ticks, currentTick, zeroForOne);
+
+    // 3. 逐段累加输入量和输出量
+    let totalInput = 0n;
+    let totalOutput = 0n;
+    let sqrtPriceCursor = currentSqrtPriceX64;
+
+    for (const tick of ticksToTraverse) {
+        const sqrtPriceAtTick = tick.sqrtPriceX64;
+
+        // 已越过目标价 → 停（本段在步骤 4 收尾）
+        if (zeroForOne && sqrtPriceAtTick <= targetSqrtPriceX64) break;
+        if (!zeroForOne && sqrtPriceAtTick >= targetSqrtPriceX64) break;
+
+        if (liquidity > 0n) {
+            totalInput += calcInputForRange(sqrtPriceCursor, sqrtPriceAtTick, liquidity, zeroForOne);
+            totalOutput += calcOutputForRange(sqrtPriceCursor, sqrtPriceAtTick, liquidity, zeroForOne);
+        }
+
+        // 跨越 tick：有符号 net 直接加减（zeroForOne 价格下行 -net，反向 +net）
+        let liquidityNet = tick.liquidityNet;
+        if (zeroForOne) liquidityNet = -liquidityNet;
+        liquidity = liquidity + liquidityNet;
+        if (liquidity < 0n) liquidity = 0n;
+
+        sqrtPriceCursor = sqrtPriceAtTick;
+    }
+
+    // 4. 末段：最后一个 tick → 目标价
+    if (liquidity > 0n && sqrtPriceCursor !== targetSqrtPriceX64) {
+        totalInput += calcInputForRange(sqrtPriceCursor, targetSqrtPriceX64, liquidity, zeroForOne);
+        totalOutput += calcOutputForRange(sqrtPriceCursor, targetSqrtPriceX64, liquidity, zeroForOne);
+    }
+
+    const amountIn = Number(totalInput) / Math.pow(10, inputDecimals);
+    const amountOut = Number(totalOutput) / Math.pow(10, outputDecimals);
+
+    // 5. 从 targetSqrtPriceX64 反推 targetTick（仅 tick_move 展示用）
+    //    tick ≈ 2 · log(sqrtPriceX64 / 2^64) / log(1.0001)
+    const sqrtPriceFloat = Number(targetSqrtPriceX64) / Number(Q64);
+    const targetTick = Math.floor(Math.log(sqrtPriceFloat * sqrtPriceFloat) / Math.log(1.0001));
+
+    return { amountInWei: totalInput, amountIn, amountOutWei: totalOutput, amountOut, currentTick, targetTick, targetSqrtPriceX64 };
+}
+
+/**
+ * 从 sqrtPriceX64 + decimals 反算价格（quote per base，UI 单位）。
+ *
+ * sqrtPriceX64 = sqrt(rawToken1 / rawToken0) × 2^64
+ * priceToken1PerToken0(raw) = (sqrtPriceX64 / 2^64)^2
+ * UI price = quote/base = (raw 比值) × 10^(baseDecimals - quoteDecimals)
+ * base 为 token1 时取倒数。
+ */
+export function priceFromSqrtX64(
+    sqrtPriceX64: bigint,
+    baseDecimals: number,
+    quoteDecimals: number,
+    baseIsToken0: boolean,
+): number {
+    const sp = Number(sqrtPriceX64) / Number(Q64);
+    const priceToken1PerToken0 = sp * sp;
+    if (baseIsToken0) {
+        return priceToken1PerToken0 * Math.pow(10, baseDecimals - quoteDecimals);
+    } else {
+        return (1 / priceToken1PerToken0) * Math.pow(10, baseDecimals - quoteDecimals);
+    }
+}
+
+// ========== 内部工具 ==========
+
+/**
+ * 计算目标 sqrtPriceX64：
+ *   price_new = price × (1 ± bps/10000) → sqrtPrice_new = sqrtPrice × sqrt(1 ± bps/10000)
+ * 用高精度整数 sqrt（与表示无关，故 X64/X96 通用）。
+ */
+export function computeTargetSqrtX64(currentSqrtPriceX64: bigint, bps: number, zeroForOne: boolean): bigint {
+    const PRECISION = 10n ** 18n;
+    const bpsBigInt = BigInt(bps);
+    // zeroForOne 价格下降 → 10000 - bps；反向 → 10000 + bps
+    const factor = zeroForOne ? 10000n - bpsBigInt : 10000n + bpsBigInt;
+    const sqrtFactor = bigIntSqrt(factor * PRECISION);
+    const sqrtBase = bigIntSqrt(10000n * PRECISION);
+    return currentSqrtPriceX64 * sqrtFactor / sqrtBase;
+}
+
+/** 整数平方根（Newton 法）。 */
+export function bigIntSqrt(n: bigint): bigint {
+    if (n < 0n) throw new Error('sqrt of negative');
+    if (n === 0n) return 0n;
+    if (n <= 3n) return 1n;
+    let x = n;
+    let y = (x + 1n) / 2n;
+    while (y < x) {
+        x = y;
+        y = (x + n / x) / 2n;
+    }
+    return x;
+}
+
+/** 现价 tick 与目标价之间的已初始化 tick（按 swap 方向排序）。 */
+function getTicksBetween(ticks: DepthTick[], currentTick: number, zeroForOne: boolean): DepthTick[] {
+    if (zeroForOne) {
+        // 价格下降：tick ≤ currentTick，降序（从现价往下走）
+        return ticks.filter(t => t.index <= currentTick).sort((a, b) => b.index - a.index);
+    } else {
+        // 价格上升：tick > currentTick，升序
+        return ticks.filter(t => t.index > currentTick).sort((a, b) => a.index - b.index);
+    }
+}
+
+// ========== amountIn 驱动的跨 tick swap（SDK-free，供 quoteV2 真跨 tick）==========
+
+/**
+ * 给定一段流动性内，把 amountIn 全部吃进去后到达的 nextSqrtPriceX64（canonical Uniswap V3，纯 bigint）。
+ *   zeroForOne=true（输入 token0，价格下行）：
+ *       sqrtNext = L·sqrt·Q64 / (L·Q64 + amountIn·sqrt)
+ *   zeroForOne=false（输入 token1，价格上行）：
+ *       sqrtNext = sqrt + amountIn·Q64 / L
+ * 与 byreal/raydium SqrtPriceMath.getNextSqrtPriceX64FromInput 同公式（此处用 amountIn 已扣 fee 的净额）。
+ */
+function nextSqrtFromAmountIn(sqrtPriceX64: bigint, liquidity: bigint, amountIn: bigint, zeroForOne: boolean): bigint {
+    if (amountIn <= 0n || liquidity <= 0n) return sqrtPriceX64;
+    if (zeroForOne) {
+        const numerator = liquidity * sqrtPriceX64 * Q64;
+        const denominator = liquidity * Q64 + amountIn * sqrtPriceX64;
+        return numerator / denominator;
+    } else {
+        return sqrtPriceX64 + (amountIn * Q64) / liquidity;
+    }
+}
+
+export interface SwapExactInInput {
+    sqrtPriceX64: bigint;
+    currentTick: number;
+    liquidity: bigint;
+    ticks: DepthTick[];
+    zeroForOne: boolean;
+    /** 净输入量（已扣 fee 的链上整数 wei） */
+    amountInNetWei: bigint;
+}
+
+export interface SwapExactInResult {
+    amountInConsumedWei: bigint;
+    amountOutWei: bigint;
+    endSqrtPriceX64: bigint;
+}
+
+/**
+ * amountIn 驱动的跨 tick swap：把 amountInNetWei 顺方向吃进，逐 tick 累加 output（SDK-free，与深度同一套 X64 数学）。
+ * 终止条件：amountIn 用完（区别于 calculateClmmDepth 的"到达目标价"）。流动性耗尽（无更多 tick）则到此为止。
+ *
+ * 与链上 swap 引擎同源：calcInputForRange/calcOutputForRange 段内累加 + 有符号 liquidityNet 跨 tick + 末段
+ * nextSqrtFromAmountIn 反算 partial。**fee 在调用方扣**（传净额），与 buildClmmDepth gross-up 口径一致。
+ */
+export function swapExactInClmm(input: SwapExactInInput): SwapExactInResult {
+    const { currentTick, zeroForOne } = input;
+    let liquidity = input.liquidity;
+    let sqrtCursor = input.sqrtPriceX64;
+    let remaining = input.amountInNetWei;
+    let totalOut = 0n;
+    let consumed = 0n;
+
+    if (liquidity <= 0n || remaining <= 0n) {
+        return { amountInConsumedWei: 0n, amountOutWei: 0n, endSqrtPriceX64: sqrtCursor };
+    }
+
+    const ticksToTraverse = getTicksBetween(input.ticks, currentTick, zeroForOne);
+
+    for (const tick of ticksToTraverse) {
+        if (remaining <= 0n) break;
+        const sqrtAtTick = tick.sqrtPriceX64;
+
+        if (liquidity > 0n) {
+            // 当前段（cursor → tick 边界）最多能吃多少 input
+            const segMaxIn = calcInputForRange(sqrtCursor, sqrtAtTick, liquidity, zeroForOne);
+            if (remaining < segMaxIn) {
+                // input 在本段内耗尽 → 反算 partial nextSqrt + partial output
+                const nextSqrt = nextSqrtFromAmountIn(sqrtCursor, liquidity, remaining, zeroForOne);
+                totalOut += calcOutputForRange(sqrtCursor, nextSqrt, liquidity, zeroForOne);
+                consumed += remaining;
+                remaining = 0n;
+                sqrtCursor = nextSqrt;
+                break;
+            }
+            // 吃满本段到 tick 边界
+            totalOut += calcOutputForRange(sqrtCursor, sqrtAtTick, liquidity, zeroForOne);
+            consumed += segMaxIn;
+            remaining -= segMaxIn;
+        }
+        sqrtCursor = sqrtAtTick;
+
+        // 跨 tick：有符号 net（zeroForOne 价格下行取负）
+        let liquidityNet = tick.liquidityNet;
+        if (zeroForOne) liquidityNet = -liquidityNet;
+        liquidity = liquidity + liquidityNet;
+        if (liquidity < 0n) liquidity = 0n;
+    }
+
+    // 末段：无更多 tick 但仍有 input 且有流动性 → 在当前流动性内继续吃完剩余（无边界）
+    if (remaining > 0n && liquidity > 0n) {
+        const nextSqrt = nextSqrtFromAmountIn(sqrtCursor, liquidity, remaining, zeroForOne);
+        totalOut += calcOutputForRange(sqrtCursor, nextSqrt, liquidity, zeroForOne);
+        consumed += remaining;
+        sqrtCursor = nextSqrt;
+        remaining = 0n;
+    }
+
+    return { amountInConsumedWei: consumed, amountOutWei: totalOut, endSqrtPriceX64: sqrtCursor };
+}
+
+/**
+ * 一段价格区间内的输入 token 数量（不含 fee）。
+ *   zeroForOne=true  → 输入 token0 → amount0 公式
+ *   zeroForOne=false → 输入 token1 → amount1 公式
+ */
+function calcInputForRange(sqrtPriceA: bigint, sqrtPriceB: bigint, liquidity: bigint, zeroForOne: boolean): bigint {
+    const lower = sqrtPriceA < sqrtPriceB ? sqrtPriceA : sqrtPriceB;
+    const upper = sqrtPriceA < sqrtPriceB ? sqrtPriceB : sqrtPriceA;
+    const diff = upper - lower;
+    if (diff === 0n || liquidity === 0n) return 0n;
+    if (zeroForOne) {
+        // amount0 = L · (upper - lower) · 2^64 / (lower · upper)
+        return liquidity * diff * Q64 / (lower * upper);
+    } else {
+        // amount1 = L · (upper - lower) / 2^64
+        return liquidity * diff / Q64;
+    }
+}
+
+/**
+ * 一段价格区间内的输出 token 数量。
+ *   zeroForOne=true  → 输出 token1 → amount1 公式
+ *   zeroForOne=false → 输出 token0 → amount0 公式
+ */
+function calcOutputForRange(sqrtPriceA: bigint, sqrtPriceB: bigint, liquidity: bigint, zeroForOne: boolean): bigint {
+    const lower = sqrtPriceA < sqrtPriceB ? sqrtPriceA : sqrtPriceB;
+    const upper = sqrtPriceA < sqrtPriceB ? sqrtPriceB : sqrtPriceA;
+    const diff = upper - lower;
+    if (diff === 0n || liquidity === 0n) return 0n;
+    if (zeroForOne) {
+        // 输出 token1: amount1 = L · (upper - lower) / 2^64
+        return liquidity * diff / Q64;
+    } else {
+        // 输出 token0: amount0 = L · (upper - lower) · 2^64 / (lower · upper)
+        return liquidity * diff * Q64 / (lower * upper);
+    }
+}

package/src/quote/depth/index.ts

@@ -0,0 +1,167 @@
+/**
+ * 深度计算模块（Solana，tier 版）
+ *
+ * port 自 SUI `ttd-sui-common/src/quote/depth/index.ts`（同源 BSC），差异（有理由的偏离）：
+ *   · **仅 CLMM**：Solana 三个 CLMM（Raydium/Orca/ByReal）全是 Uniswap V3 风格集中流动性 X64；
+ *     AMM/DAMM 走各自路径，无统一深度引擎 → 暂只点亮 buildClmmDepth。
+ *   · **X64**：调用 X64 版 clmm_depth_calculator（见同目录，逐字照搬 SUI）。
+ *   · **tick + sqrtPriceX64 由调用方物化**：各 DEX 把本地 tickArray cache 的已初始化 tick 配
+ *     **共享 TickMath**（`../tick/clmm_tick_math` getSqrtPriceX64FromTick）算的 sqrtPriceX64，
+ *     组装成 DepthTick[] 传入 —— 三个 CLMM 同源 Uniswap V3，故共享同一份 TickMath。
+ *   · **方向**：调用方传 baseIsToken0（用链上 mintA/mintB 判定 base 是否为 token0=mintA），
+ *     ask（买 base，输入 quote）zeroForOne = !baseIsToken0；bid（卖 base，输入 base）zeroForOne = baseIsToken0。
+ *
+ * 输出语义（与 BSC/SUI 一致）：
+ *   amount     = 推到 target price 时获得的 base token（不受 fee 影响）
+ *   amount_in  = 推到 target price 时需投入的 quote token（含费 gross up）
+ *   fee        = amount_in × fee_rate_bps/10000
+ */
+
+import { log_debug, log_info, StandardPoolInfoType } from '@clonegod/ttd-core/dist';
+import {
+    QuoteTier, QuoteEntry, QuoteDepthOutput,
+    getDepthPricePctLevels, DEFAULT_TIER_PCT,
+} from '@clonegod/ttd-core/dist';
+import { resolveTradeDirection } from '../../utils/trade_direction';
+import { DepthTick, calculateClmmDepth, priceFromSqrtX64 } from './clmm_depth_calculator';
+
+export { calculateClmmDepth, priceFromSqrtX64, computeTargetSqrtX64, bigIntSqrt, swapExactInClmm } from './clmm_depth_calculator';
+export type { DepthTick, ClmmDepthInput, DepthResult, SwapExactInInput, SwapExactInResult } from './clmm_depth_calculator';
+
+// ========== 启动日志一次性输出 ==========
+let _depthPctLogged = false;
+function logDepthLevelsOnce(): void {
+    if (_depthPctLogged) return;
+    _depthPctLogged = true;
+    log_info(`[Depth] pctLevels=${JSON.stringify(getDepthPricePctLevels())}, default=${DEFAULT_TIER_PCT}`);
+}
+
+// ========== Fee gross-up ==========
+/**
+ * 池子曲线纯输入 → 用户实付（含费）：
+ *   amountInGross = amountInNet / (1 - feeRate)；feeAmount = amountInGross - amountInNet
+ */
+function grossUpFee(amountInNet: number, feeRateBps: number): { amountInGross: number; feeAmount: number } {
+    if (feeRateBps <= 0 || amountInNet <= 0) return { amountInGross: amountInNet, feeAmount: 0 };
+    const feeRatio = feeRateBps / 10000;
+    const amountInGross = amountInNet / (1 - feeRatio);
+    return { amountInGross, feeAmount: amountInGross - amountInNet };
+}
+
+// ========== 把多档 tier 装配成 QuoteEntry（主档镜像顶层）==========
+function assembleEntry(tiers: QuoteTier[]): QuoteEntry {
+    const def = tiers.find(t => t.pct === DEFAULT_TIER_PCT) ?? tiers[0];
+    return {
+        price: def.price, amount: def.amount, amount_in: def.amount_in, amount_in_usd: def.amount_in_usd,
+        fee: def.fee, fee_usd: def.fee_usd, tick_move: def.tick_move, tiers,
+    };
+}
+
+// ========== CLMM 通用深度构建 ==========
+
+export interface BuildClmmDepthInput {
+    poolInfo: StandardPoolInfoType;
+    poolAddress: string;
+    /** 池子动态态（v2 维护的本地 cache 或 v1 现读） */
+    poolState: {
+        currentSqrtPriceX64: bigint;
+        currentTick: number;
+        liquidity: bigint;
+        /** base token 是否为链上 token0(=mintA)；调用方用链上 mint 判定 */
+        baseIsToken0: boolean;
+    };
+    /** 全量已初始化 tick（含 sqrtPriceX64），调用方从本地 tickArray cache + 共享 TickMath 物化 */
+    ticks: DepthTick[];
+    basePriceUsd: number;
+    quotePriceUsd: number;
+    /**
+     * 池子 effective fee rate (bps)，调用方从链上 feeRate 换算（各 DEX 单位不同）。
+     * 不接受 fallback 到配置漂移值之外的兜底——错则 verify 跨源 diff 系统性偏移会暴露。
+     */
+    feeRateBps: number;
+}
+
+/**
+ * 通用 CLMM 深度构建：多档（默认 5 档）ask/bid 深度，从内存 tick 数据零额外 RPC 计算。
+ */
+export function buildClmmDepth(input: BuildClmmDepthInput): QuoteDepthOutput | undefined {
+    logDepthLevelsOnce();
+    const pctLevels = getDepthPricePctLevels();
+    if (pctLevels.length === 0) return undefined;
+
+    const { poolInfo, poolState, ticks, basePriceUsd, quotePriceUsd, feeRateBps } = input;
+    if (poolState.liquidity <= 0n) return undefined;
+    if (feeRateBps == null || feeRateBps < 0) {
+        log_debug(`[Depth] ${poolInfo.pool_name} CLMM: invalid feeRateBps=${feeRateBps}, skip`, '');
+        return undefined;
+    }
+
+    try {
+        const dir = resolveTradeDirection(poolInfo, true);
+        const baseToken = dir.baseToken;
+        const quoteToken = dir.quoteToken;
+        const baseIsToken0 = poolState.baseIsToken0;
+        // ask 买 base（输入 quote）：quote 为 token0 ⟺ base 为 token1 ⟺ !baseIsToken0
+        const askZeroForOne = !baseIsToken0;
+        // bid 卖 base（输入 base）：base 为 token0 ⟺ baseIsToken0
+        const bidZeroForOne = baseIsToken0;
+
+        const midPrice = priceFromSqrtX64(poolState.currentSqrtPriceX64, baseToken.decimals, quoteToken.decimals, baseIsToken0);
+
+        const askTiers: QuoteTier[] = [];
+        const bidTiers: QuoteTier[] = [];
+
+        for (const pct of pctLevels) {
+            const bps = Math.round(pct * 100);  // 0.1% → 10bp
+
+            const askResult = calculateClmmDepth({
+                sqrtPriceX64: poolState.currentSqrtPriceX64, currentTick: poolState.currentTick,
+                liquidity: poolState.liquidity, ticks, zeroForOne: askZeroForOne, targetBps: bps,
+                inputDecimals: quoteToken.decimals, outputDecimals: baseToken.decimals,
+            });
+            const bidResult = calculateClmmDepth({
+                sqrtPriceX64: poolState.currentSqrtPriceX64, currentTick: poolState.currentTick,
+                liquidity: poolState.liquidity, ticks, zeroForOne: bidZeroForOne, targetBps: bps,
+                inputDecimals: baseToken.decimals, outputDecimals: quoteToken.decimals,
+            });
+
+            const askTargetPrice = priceFromSqrtX64(askResult.targetSqrtPriceX64, baseToken.decimals, quoteToken.decimals, baseIsToken0);
+            const bidTargetPrice = priceFromSqrtX64(bidResult.targetSqrtPriceX64, baseToken.decimals, quoteToken.decimals, baseIsToken0);
+
+            // Ask: amount_in 是 quote token（gross up），amount_out 是 base token
+            const askGross = grossUpFee(askResult.amountIn, feeRateBps);
+            // Bid: amount_in 是 base token（gross up），amount_out 是 quote token
+            const bidGross = grossUpFee(bidResult.amountIn, feeRateBps);
+
+            const askTickMove = `${askResult.targetTick} <- ${askResult.currentTick}`;
+            const bidTickMove = `${bidResult.currentTick} -> ${bidResult.targetTick}`;
+
+            // 【强制·原则2】tier.price = effective average price including fee = amount_in_gross / amount_out
+            //   跟链上 swap exec_price 严格同语义；禁止改回 marginal / 不含 fee 形态（G4 事故根因）。
+            //   详见 arb-common/docs/20260602-dex-quote-implementation-standard.md 原则2；verify 跨源对账兜底。
+            const askEffPrice = askResult.amountOut > 0 ? askGross.amountInGross / askResult.amountOut : askTargetPrice;
+            const bidEffPrice = bidGross.amountInGross > 0 ? bidResult.amountOut / bidGross.amountInGross : bidTargetPrice;
+
+            askTiers.push({
+                pct, price: askEffPrice, amount: askResult.amountOut,
+                amount_in: askGross.amountInGross, amount_in_usd: askGross.amountInGross * quotePriceUsd,
+                fee: askGross.feeAmount, fee_usd: askGross.feeAmount * quotePriceUsd, tick_move: askTickMove,
+            });
+            bidTiers.push({
+                pct, price: bidEffPrice, amount: bidResult.amountOut,
+                amount_in: bidGross.amountInGross, amount_in_usd: bidGross.amountInGross * basePriceUsd,
+                fee: bidGross.feeAmount, fee_usd: bidGross.feeAmount * basePriceUsd, tick_move: bidTickMove,
+            });
+        }
+
+        return {
+            mid_price: midPrice,
+            fee_rate_bps: feeRateBps,
+            ask: assembleEntry(askTiers),
+            bid: assembleEntry(bidTiers),
+        };
+    } catch (error) {
+        log_debug(`[Depth] ${poolInfo.pool_name} CLMM depth failed: ${(error as Error).message}`, '');
+        return undefined;
+    }
+}

package/src/quote/index.ts

@@ -1 +1,10 @@
 export * from './pricing'
+export * from './pool_subscription_registry'
+export * from './pool_event'
+export * from './chain_ops'
+export * from './abstract_dex_quote'
+export * from './quote_trace'
+export * from './quote_amount'
+export * from './verify'
+export * from './depth'
+export * from './tick'

package/src/quote/pool_event.ts

@@ -0,0 +1,82 @@
+import { SolanaPoolAccountUpdateEventData } from '../types'
+
+/**
+ * SolPoolEvent —— 询价基类消费的归一化池事件（对齐 BSC/SUI 的 pool_event 角色，
+ * 但建模 **Solana 的账户快照模型**，与 EVM/SUI 的 swap-event 模型有本质差异）。
+ *
+ * ── 关键差异（设计文档 §2.1）──
+ *   EVM/SUI：stream 解析 swap/mint/burn 事件 → 推结构化 {type, amount0/1, txIndex}，
+ *            消费端靠解析事件维护本地 tick。
+ *   Solana ：tickArray/binArray/vault 本身就是独立链上账户。stream-quote 直接订阅这些账户，
+ *            账户一变即推**最新账户原始数据**（base64），消费端解码 = 拿到链上真相（天然一致）。
+ *            → 没有"swap 事件 + amount"，事件本身就是新状态快照。
+ *
+ * 因此 SolPoolEvent 不带 swap/add/remove 分类、不带 amount0/1：
+ *   - 每个池账户更新都触发 v2 重算（refreshStateFromEvent 解码账户 → 覆盖本地状态）。
+ *   - 单调水位线用 Solana 账户的 writeVersion（Geyser write_version，全局单调递增），是 txIndex 的天然对等物。
+ *     stream-quote 已把 write_version 补进推送 wire（step 2）→ 基类启用 (slot, writeVersion) 去重。
+ *     AMM 聚合快照取 pool+vaultA+vaultB 三账户的 max writeVersion。
+ *     （writeVersion 缺省时基类回退"无序号无条件推"，对齐 SUI 缺 txIndex 行为，防御性兜底。）
+ *
+ * verify（swap amount 对账）暂缓：SOL 账户快照不含 swap amount，buildSwapVerify 默认返回 null，
+ *   待 stream-quote 解码 swap amount 后再接（设计文档 §2.4 / verify 跨源 cacheQuote 仍生效）。
+ */
+export interface SolPoolEvent {
+    pool_address: string
+    dex_id: string
+    pool_name: string
+    /** 触发事件的 slot（= blockNumber，去重/水位线的"块"维度） */
+    blockNumber: number
+    /** 账户写版本（= txIndex 的 Solana 对等物，单调递增；wire 暂未携带 → 可空） */
+    writeVersion?: number
+    /** 导致账户变化的交易哈希（txid 透传，无则 'account'） */
+    txHash: string
+    /** 区块时间（毫秒；缺省 0，stream 暂未必带） */
+    blockTime: number
+
+    // ── 账户原始数据（base64）；refreshStateFromEvent 按 DEX layout 解码 ──
+    /** 池主账户原始数据（CLMM=pool state / DLMM=lbPair / AMM=pool）；子账户独立 push 时为空 */
+    poolAccountData: string
+    /** AMM vault A 原始数据（reserve；仅 AMM 携带） */
+    vaultAAccountData?: string
+    /** AMM vault B 原始数据（仅 AMM 携带） */
+    vaultBAccountData?: string
+
+    /**
+     * 动态子账户更新（CLMM tickArray / DLMM binArray，方案 A 独立 push）。
+     * 存在时本事件是"子账户变更"而非"池主账户变更" → refreshStateFromEvent 按 role 解码更新本地分布。
+     */
+    subAccount?: {
+        role: string       // 'tickArray' | 'binArray'
+        address: string
+        data: string       // base64
+    }
+
+    /** 原始事件（需要额外字段时兜底访问，避免反复扩接口） */
+    raw: SolanaPoolAccountUpdateEventData
+}
+
+/**
+ * 把 stream-quote 推送的 SolanaPoolAccountUpdateEventData 归一化为 SolPoolEvent。
+ * 收敛 wire → 基类契约的映射，后续 wire 增字段只改这里一处。
+ */
+export function toSolPoolEvent(data: SolanaPoolAccountUpdateEventData): SolPoolEvent {
+    const d = data.data
+    return {
+        pool_address: data.pool_address,
+        dex_id: data.dex_id,
+        pool_name: data.pool_name,
+        blockNumber: d.slot,
+        // Geyser write_version（全局单调）；stream-quote 已补进 wire（step 2）→ (slot, writeVersion) 水位线去重
+        writeVersion: d.write_version,
+        txHash: d.tx_hash || 'account',
+        blockTime: data.event_time || 0,
+        poolAccountData: d.pool_account_data,
+        vaultAAccountData: d.vaultA_account_data,
+        vaultBAccountData: d.vaultB_account_data,
+        subAccount: d.sub_account
+            ? { role: d.sub_account.role, address: d.sub_account.account, data: d.sub_account.account_data }
+            : undefined,
+        raw: data,
+    }
+}

package/src/quote/pool_subscription_registry.ts

@@ -0,0 +1,81 @@
+import { AppConfig, HttpUtil, log_info, log_warn, SERVICE_PORT, StandardPoolInfoType } from '@clonegod/ttd-core/dist'
+import { resolveGrpcProvider } from '../grpc/grpc_provider_registry'
+
+/**
+ * 按需订阅 —— 生产端（询价进程调用）。对齐 BSC/BASE/SUI：询价进程通过 config-center 声明所需池子，
+ * config-center 写 `${chain}:pool:subscriptions` Hash + 广播 `:change`，stream-quote 消费后订阅 Helius。
+ *
+ * Solana 适配（与 BSC 的差异）：
+ *  - **单 Helius provider，且对齐 SUI 由运维在 analyze Config/RPC 页配（type=grpc, endpoint=laserstream URL, auth_token=API key）**。
+ *    本 helper **不自动种 provider**；register 用 `resolveGrpcProvider` 解析出 analyze 配的 provider id（无配 fail-loud）。
+ *  - **base58 地址大小写敏感**：依赖 config-center `lower()` 已改为 0x 感知（非 0x 原样保留），不破坏地址。
+ */
+
+function configCenterBase(appConfig: AppConfig): string {
+    const chain = appConfig.env_args.chain_id // SOLANA
+    let host = String(appConfig.env_args.config_center_host || '127.0.0.1').trim()
+    // host 可能含端口(127.0.0.1:4000)或不含(127.0.0.1)；不含则补 CONFIG_CENTER_HTTP
+    if (!host.includes(':')) host = `${host}:${SERVICE_PORT.CONFIG_CENTER_HTTP}`
+    return `http://${host}/${chain}/config`
+}
+
+/** 注册一批池子订阅（每池 POST config-center /quote/register），provider_ids 用 analyze 配的 grpc provider。 */
+export async function registerPoolSubscriptions(
+    appConfig: AppConfig,
+    pools: StandardPoolInfoType[],
+    quote_app_id: string,
+): Promise<void> {
+    // provider 由运维在 analyze Config/RPC 配（type=grpc）；解析其 id 供 register 引用，无配 fail-loud
+    const provider = await resolveGrpcProvider(appConfig.arb_cache.redis_cmd, appConfig.env_args.chain_id)
+    const provider_ids = [provider.id]
+
+    const base = configCenterBase(appConfig)
+    let ok = 0
+    for (const p of pools) {
+        try {
+            await HttpUtil.post(`${base}/quote/register`, {
+                pool_address: p.pool_address,
+                provider_ids,
+                quote_app_id,
+                pair: p.pair,
+                dex_id: p.dex_id,
+                pool_name: p.pool_name,
+                fee_rate: p.fee_rate,
+            })
+            ok++
+        } catch (e: any) {
+            log_warn(`[pool/subscriptions] register ${p.pool_address} failed: ${e.message}`)
+        }
+    }
+    log_info(`[pool/subscriptions] registered ${ok}/${pools.length} pools by ${quote_app_id} → provider=${provider.id}`)
+}
+
+/** 注销本进程注册的所有池子订阅（按 quote_app_id）。 */
+export async function unregisterPoolSubscriptions(appConfig: AppConfig, quote_app_id: string): Promise<void> {
+    try {
+        await HttpUtil.post(`${configCenterBase(appConfig)}/quote/unregister`, { quote_app_id })
+        log_info(`[pool/subscriptions] unregistered all pools by ${quote_app_id}`)
+    } catch (e: any) {
+        log_warn(`[pool/subscriptions] unregister failed: ${e.message}`)
+    }
+}
+
+/**
+ * 询价进程启动后调用一次：确保 helius provider + 注册全部池子 + 装退出时自动 unregister。
+ * quote_app_id 取 env_args.app_name（每个 DEX 询价进程唯一）。
+ */
+export async function attachPoolSubscriptionLifecycle(appConfig: AppConfig, pools: StandardPoolInfoType[]): Promise<void> {
+    const quote_app_id = String(appConfig.env_args.app_name || '').toLowerCase() || 'sol-quote'
+    await registerPoolSubscriptions(appConfig, pools, quote_app_id)
+
+    let cleaned = false
+    const cleanup = async (sig: string) => {
+        if (cleaned) return
+        cleaned = true
+        log_info(`[pool/subscriptions] ${sig} → unregister ${quote_app_id}`)
+        await unregisterPoolSubscriptions(appConfig, quote_app_id)
+        process.exit(0)
+    }
+    process.on('SIGINT', () => void cleanup('SIGINT'))
+    process.on('SIGTERM', () => void cleanup('SIGTERM'))
+}