@clonegod/ttd-sol-common 2.0.67 → 2.0.69

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,272 @@
+/**
+ * 深度计算模块（Solana，tier 版）
+ *
+ * port 自 SUI `ttd-sui-common/src/quote/depth/index.ts`（同源 BSC），差异（有理由的偏离）：
+ *   · **CLMM + AMM**：三个 CLMM（Raydium/Orca/ByReal）全是 Uniswap V3 风格集中流动性 X64 → buildClmmDepth；
+ *     两个 AMM（Raydium AMM/CPMM）是 x·y=k 恒定乘积 → buildAmmDepth（reserve 上闭式）；
+ *     DAMMv2（CP-AMM 单 sqrtPrice 区间）复用 buildClmmDepth(ticks=[])；DLMM bin 深度待做。
+ *   · **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';
+import { calculateAmmDepth } from './amm_depth_calculator';
+
+export { calculateClmmDepth, priceFromSqrtX64, computeTargetSqrtX64, bigIntSqrt, swapExactInClmm } from './clmm_depth_calculator';
+export type { DepthTick, ClmmDepthInput, DepthResult, SwapExactInInput, SwapExactInResult } from './clmm_depth_calculator';
+export { calculateAmmDepth } from './amm_depth_calculator';
+export type { AmmDepthInput, AmmDepthResult } from './amm_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
+ *
+ * 导出供 DEX 专有 depth 构建复用（如 DLMM 离散 bin 深度，在各自包内但 tier 语义统一）。
+ */
+export 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（主档镜像顶层）==========
+/** 导出供 DEX 专有 depth 构建复用（tier 语义统一）。 */
+export 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;
+    }
+}
+
+// ========== AMM 通用深度构建 ==========
+//
+// port 自 BSC `arb-chain-bsc/.../quote/depth/index.ts` buildAmmDepth；差异（有理由的偏离）：
+//   · **baseIsToken0 由调用方传**（用链上 mintA/mintB 判定），不在此用地址 lowercase 比较——
+//     Solana 地址 base58 大小写敏感，不可 lowercase（与 buildClmmDepth 一致）。
+//   · reserve0/reserve1 = 链上 token0(mintA)/token1(mintB) 的 reserve（wei string）。
+
+export interface BuildAmmDepthInput {
+    poolInfo: StandardPoolInfoType;
+    /** token0(=链上 mintA) 的 reserve（wei string） */
+    reserve0: string;
+    /** token1(=链上 mintB) 的 reserve（wei string） */
+    reserve1: string;
+    /** base token 是否为链上 token0(=mintA)；调用方用链上 mint 判定（base58 大小写敏感） */
+    baseIsToken0: boolean;
+    basePriceUsd: number;
+    quotePriceUsd: number;
+    /**
+     * 池子 effective fee rate (bps)，必填。各 DEX 从配置 fee_rate（market-data 强制整数 ≥1）传入。
+     * 错则 verify 跨源 diff 系统性偏移会暴露。
+     */
+    feeRateBps: number;
+}
+
+/**
+ * 通用 AMM 深度构建：多档（默认 5 档）ask/bid 深度，从内存 reserve 零额外 RPC 计算（x·y=k 闭式）。
+ */
+export function buildAmmDepth(input: BuildAmmDepthInput): QuoteDepthOutput | undefined {
+    logDepthLevelsOnce();
+    const pctLevels = getDepthPricePctLevels();
+    if (pctLevels.length === 0) return undefined;
+
+    const { poolInfo, reserve0, reserve1, baseIsToken0, basePriceUsd, quotePriceUsd, feeRateBps } = input;
+    if (feeRateBps == null || feeRateBps < 0) {
+        log_debug(`[Depth] ${poolInfo.pool_name} AMM: invalid feeRateBps=${feeRateBps}, skip`, '');
+        return undefined;
+    }
+
+    try {
+        const dir = resolveTradeDirection(poolInfo, true);
+        const baseToken = dir.baseToken;
+        const quoteToken = dir.quoteToken;
+
+        // 中间价：从 reserve 比值算（UI 单位）
+        const baseReserveUi = Number(BigInt(baseIsToken0 ? reserve0 : reserve1)) / Math.pow(10, baseToken.decimals);
+        const quoteReserveUi = Number(BigInt(baseIsToken0 ? reserve1 : reserve0)) / Math.pow(10, quoteToken.decimals);
+        const midPrice = quoteReserveUi / baseReserveUi;
+
+        const askTiers: QuoteTier[] = [];
+        const bidTiers: QuoteTier[] = [];
+
+        for (const pct of pctLevels) {
+            const bps = Math.round(pct * 100);
+
+            const askResult = calculateAmmDepth({
+                reserve0, reserve1, targetBps: bps, isBuy: true, baseIsToken0,
+                token0Decimals: baseIsToken0 ? baseToken.decimals : quoteToken.decimals,
+                token1Decimals: baseIsToken0 ? quoteToken.decimals : baseToken.decimals,
+            });
+            const bidResult = calculateAmmDepth({
+                reserve0, reserve1, targetBps: bps, isBuy: false, baseIsToken0,
+                token0Decimals: baseIsToken0 ? baseToken.decimals : quoteToken.decimals,
+                token1Decimals: baseIsToken0 ? quoteToken.decimals : baseToken.decimals,
+            });
+
+            // Ask: amount_in 是 quote token；Bid: amount_in 是 base token
+            const askGross = grossUpFee(askResult.amountIn, feeRateBps);
+            const bidGross = grossUpFee(bidResult.amountIn, feeRateBps);
+
+            // 【强制·原则2】tier.price = effective avg price including fee = amount_in_gross / amount_out
+            //   跟 chain swap exec_price 严格同语义；禁止改回 marginal / 不含 fee 形态（G4 事故根因）。
+            const askEffPrice = askResult.amountOut > 0 ? askGross.amountInGross / askResult.amountOut : askResult.targetPrice;
+            const bidEffPrice = bidGross.amountInGross > 0 ? bidResult.amountOut / bidGross.amountInGross : bidResult.targetPrice;
+
+            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,
+            });
+            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,
+            });
+        }
+
+        return {
+            mid_price: midPrice,
+            fee_rate_bps: feeRateBps,
+            ask: assembleEntry(askTiers),
+            bid: assembleEntry(bidTiers),
+        };
+    } catch (error) {
+        log_debug(`[Depth] ${poolInfo.pool_name} AMM 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'