@clonegod/ttd-sol-common 2.0.68 → 2.0.69

package/dist/quote/depth/amm_depth_calculator.d.ts

@@ -0,0 +1,19 @@
+export interface AmmDepthInput {
+    reserve0: string;
+    reserve1: string;
+    targetBps: number;
+    isBuy: boolean;
+    baseIsToken0: boolean;
+    token0Decimals: number;
+    token1Decimals: number;
+}
+export interface AmmDepthResult {
+    amountOutWei: bigint;
+    amountOut: number;
+    outputDecimals: number;
+    amountInWei: bigint;
+    amountIn: number;
+    inputDecimals: number;
+    targetPrice: number;
+}
+export declare function calculateAmmDepth(input: AmmDepthInput): AmmDepthResult;

package/dist/quote/depth/amm_depth_calculator.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateAmmDepth = calculateAmmDepth;
+const clmm_depth_calculator_1 = require("./clmm_depth_calculator");
+function calculateAmmDepth(input) {
+    const { targetBps, isBuy, baseIsToken0, token0Decimals, token1Decimals } = input;
+    const R0 = BigInt(input.reserve0);
+    const R1 = BigInt(input.reserve1);
+    if (R0 === 0n || R1 === 0n) {
+        return { amountOutWei: 0n, amountOut: 0, outputDecimals: 0, amountInWei: 0n, amountIn: 0, inputDecimals: 0, targetPrice: 0 };
+    }
+    const k = R0 * R1;
+    const bps = BigInt(targetBps);
+    const PRECISION = 10n ** 18n;
+    let amountOutWei;
+    let amountInWei;
+    let outputDecimals;
+    let inputDecimals;
+    if (isBuy) {
+        const [baseReserve, quoteReserve] = baseIsToken0 ? [R0, R1] : [R1, R0];
+        outputDecimals = baseIsToken0 ? token0Decimals : token1Decimals;
+        inputDecimals = baseIsToken0 ? token1Decimals : token0Decimals;
+        const baseReserveNew = baseReserve * (0, clmm_depth_calculator_1.bigIntSqrt)(10000n * PRECISION) / (0, clmm_depth_calculator_1.bigIntSqrt)((10000n + bps) * PRECISION);
+        const quoteReserveNew = quoteReserve * (0, clmm_depth_calculator_1.bigIntSqrt)((10000n + bps) * PRECISION) / (0, clmm_depth_calculator_1.bigIntSqrt)(10000n * PRECISION);
+        amountOutWei = baseReserve - baseReserveNew;
+        amountInWei = quoteReserveNew - quoteReserve;
+    }
+    else {
+        const [baseReserve, quoteReserve] = baseIsToken0 ? [R0, R1] : [R1, R0];
+        outputDecimals = baseIsToken0 ? token1Decimals : token0Decimals;
+        inputDecimals = baseIsToken0 ? token0Decimals : token1Decimals;
+        if (bps >= 10000n) {
+            amountOutWei = quoteReserve;
+            amountInWei = baseReserve;
+        }
+        else {
+            const quoteReserveNew = quoteReserve * (0, clmm_depth_calculator_1.bigIntSqrt)((10000n - bps) * PRECISION) / (0, clmm_depth_calculator_1.bigIntSqrt)(10000n * PRECISION);
+            const baseReserveNew = baseReserve * (0, clmm_depth_calculator_1.bigIntSqrt)(10000n * PRECISION) / (0, clmm_depth_calculator_1.bigIntSqrt)((10000n - bps) * PRECISION);
+            amountOutWei = quoteReserve - quoteReserveNew;
+            amountInWei = baseReserveNew - baseReserve;
+        }
+    }
+    const amountOut = Number(amountOutWei) / Math.pow(10, outputDecimals);
+    const amountIn = Number(amountInWei) / Math.pow(10, inputDecimals);
+    const baseDec = baseIsToken0 ? token0Decimals : token1Decimals;
+    const quoteDec = baseIsToken0 ? token1Decimals : token0Decimals;
+    const baseReserveUi = Number(baseIsToken0 ? R0 : R1) / Math.pow(10, baseDec);
+    const quoteReserveUi = Number(baseIsToken0 ? R1 : R0) / Math.pow(10, quoteDec);
+    const midPrice = quoteReserveUi / baseReserveUi;
+    const bpsNum = Number(targetBps);
+    const targetPrice = isBuy
+        ? midPrice * (10000 + bpsNum) / 10000
+        : midPrice * (10000 - bpsNum) / 10000;
+    return { amountOutWei, amountOut, outputDecimals, amountInWei, amountIn, inputDecimals, targetPrice };
+}

package/dist/quote/depth/index.d.ts

@@ -1,8 +1,15 @@
 import { StandardPoolInfoType } from '@clonegod/ttd-core/dist';
-import { QuoteDepthOutput } from '@clonegod/ttd-core/dist';
+import { QuoteTier, QuoteEntry, QuoteDepthOutput } from '@clonegod/ttd-core/dist';
 import { DepthTick } 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';
+export { calculateAmmDepth } from './amm_depth_calculator';
+export type { AmmDepthInput, AmmDepthResult } from './amm_depth_calculator';
+export declare function grossUpFee(amountInNet: number, feeRateBps: number): {
+    amountInGross: number;
+    feeAmount: number;
+};
+export declare function assembleEntry(tiers: QuoteTier[]): QuoteEntry;
 export interface BuildClmmDepthInput {
     poolInfo: StandardPoolInfoType;
     poolAddress: string;
@@ -18,3 +25,13 @@ export interface BuildClmmDepthInput {
     feeRateBps: number;
 }
 export declare function buildClmmDepth(input: BuildClmmDepthInput): QuoteDepthOutput | undefined;
+export interface BuildAmmDepthInput {
+    poolInfo: StandardPoolInfoType;
+    reserve0: string;
+    reserve1: string;
+    baseIsToken0: boolean;
+    basePriceUsd: number;
+    quotePriceUsd: number;
+    feeRateBps: number;
+}
+export declare function buildAmmDepth(input: BuildAmmDepthInput): QuoteDepthOutput | undefined;

package/dist/quote/depth/index.js

@@ -1,17 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.swapExactInClmm = exports.bigIntSqrt = exports.computeTargetSqrtX64 = exports.priceFromSqrtX64 = exports.calculateClmmDepth = void 0;
+exports.calculateAmmDepth = exports.swapExactInClmm = exports.bigIntSqrt = exports.computeTargetSqrtX64 = exports.priceFromSqrtX64 = exports.calculateClmmDepth = void 0;
+exports.grossUpFee = grossUpFee;
+exports.assembleEntry = assembleEntry;
 exports.buildClmmDepth = buildClmmDepth;
+exports.buildAmmDepth = buildAmmDepth;
 const dist_1 = require("@clonegod/ttd-core/dist");
 const dist_2 = require("@clonegod/ttd-core/dist");
 const trade_direction_1 = require("../../utils/trade_direction");
 const clmm_depth_calculator_1 = require("./clmm_depth_calculator");
+const amm_depth_calculator_1 = require("./amm_depth_calculator");
 var clmm_depth_calculator_2 = require("./clmm_depth_calculator");
 Object.defineProperty(exports, "calculateClmmDepth", { enumerable: true, get: function () { return clmm_depth_calculator_2.calculateClmmDepth; } });
 Object.defineProperty(exports, "priceFromSqrtX64", { enumerable: true, get: function () { return clmm_depth_calculator_2.priceFromSqrtX64; } });
 Object.defineProperty(exports, "computeTargetSqrtX64", { enumerable: true, get: function () { return clmm_depth_calculator_2.computeTargetSqrtX64; } });
 Object.defineProperty(exports, "bigIntSqrt", { enumerable: true, get: function () { return clmm_depth_calculator_2.bigIntSqrt; } });
 Object.defineProperty(exports, "swapExactInClmm", { enumerable: true, get: function () { return clmm_depth_calculator_2.swapExactInClmm; } });
+var amm_depth_calculator_2 = require("./amm_depth_calculator");
+Object.defineProperty(exports, "calculateAmmDepth", { enumerable: true, get: function () { return amm_depth_calculator_2.calculateAmmDepth; } });
 let _depthPctLogged = false;
 function logDepthLevelsOnce() {
     if (_depthPctLogged)
@@ -98,3 +104,61 @@ function buildClmmDepth(input) {
         return undefined;
     }
 }
+function buildAmmDepth(input) {
+    logDepthLevelsOnce();
+    const pctLevels = (0, dist_2.getDepthPricePctLevels)();
+    if (pctLevels.length === 0)
+        return undefined;
+    const { poolInfo, reserve0, reserve1, baseIsToken0, basePriceUsd, quotePriceUsd, feeRateBps } = input;
+    if (feeRateBps == null || feeRateBps < 0) {
+        (0, dist_1.log_debug)(`[Depth] ${poolInfo.pool_name} AMM: invalid feeRateBps=${feeRateBps}, skip`, '');
+        return undefined;
+    }
+    try {
+        const dir = (0, trade_direction_1.resolveTradeDirection)(poolInfo, true);
+        const baseToken = dir.baseToken;
+        const quoteToken = dir.quoteToken;
+        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 = [];
+        const bidTiers = [];
+        for (const pct of pctLevels) {
+            const bps = Math.round(pct * 100);
+            const askResult = (0, amm_depth_calculator_1.calculateAmmDepth)({
+                reserve0, reserve1, targetBps: bps, isBuy: true, baseIsToken0,
+                token0Decimals: baseIsToken0 ? baseToken.decimals : quoteToken.decimals,
+                token1Decimals: baseIsToken0 ? quoteToken.decimals : baseToken.decimals,
+            });
+            const bidResult = (0, amm_depth_calculator_1.calculateAmmDepth)({
+                reserve0, reserve1, targetBps: bps, isBuy: false, baseIsToken0,
+                token0Decimals: baseIsToken0 ? baseToken.decimals : quoteToken.decimals,
+                token1Decimals: baseIsToken0 ? quoteToken.decimals : baseToken.decimals,
+            });
+            const askGross = grossUpFee(askResult.amountIn, feeRateBps);
+            const bidGross = grossUpFee(bidResult.amountIn, feeRateBps);
+            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) {
+        (0, dist_1.log_debug)(`[Depth] ${poolInfo.pool_name} AMM depth failed: ${error.message}`, '');
+        return undefined;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clonegod/ttd-sol-common",
-  "version": "2.0.68",
+  "version": "2.0.69",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/quote/depth/amm_depth_calculator.ts

@@ -0,0 +1,143 @@
+/**
+ * AMM 深度计算器
+ *
+ * 给定 reserves + 价格偏移（bps），用 x*y=k 闭合公式计算可交易量。
+ * 一次乘除，零遍历。
+ *
+ * 与 CLMM 一样，给定价格范围的输出量与 fee 无关（fee 只影响需要多少 input）。
+ */
+
+import { bigIntSqrt } from './clmm_depth_calculator';
+
+export interface AmmDepthInput {
+    reserve0: string;         // token0 reserve（wei string）
+    reserve1: string;         // token1 reserve（wei string）
+    targetBps: number;        // 价格偏移（如 15, 30）
+    isBuy: boolean;           // true=买入 base token(token0), false=卖出 base token
+    /** base token 是 pool 的 token0 还是 token1 */
+    baseIsToken0: boolean;
+    token0Decimals: number;
+    token1Decimals: number;
+}
+
+export interface AmmDepthResult {
+    /** 输出 token 数量（wei） */
+    amountOutWei: bigint;
+    /** 输出 token 数量（UI 单位） */
+    amountOut: number;
+    /** 输出的 decimals */
+    outputDecimals: number;
+    /** 输入 token 数量（wei，不含 fee；池子曲线纯输入） */
+    amountInWei: bigint;
+    /** 输入 token 数量（UI 单位，不含 fee） */
+    amountIn: number;
+    /** 输入的 decimals */
+    inputDecimals: number;
+    /** 推到的目标价（quote per base，UI 单位） */
+    targetPrice: number;
+}
+
+/**
+ * 计算 AMM 池子在给定价格偏移范围内的深度
+ *
+ * 公式推导（以标准 token0/token1 为例）：
+ *   k = R0 * R1
+ *   P = R1 / R0（token0 相对 token1 的价格）
+ *
+ *   Ask（买入 token0，价格上涨）：
+ *     P_target = P * (1 + bps/10000)
+ *     R0_new = sqrt(k / P_target)
+ *     depth_token0 = R0 - R0_new
+ *
+ *   Bid（卖出 token0，价格下跌）：
+ *     P_target = P * (1 - bps/10000)
+ *     R1_new = sqrt(k * P_target)
+ *     depth_token1 = R1 - R1_new
+ *
+ * 注意：pair 的 base/quote 可能与 pool 的 token0/token1 顺序不同，
+ * 通过 baseIsToken0 参数处理。
+ */
+export function calculateAmmDepth(input: AmmDepthInput): AmmDepthResult {
+    const { targetBps, isBuy, baseIsToken0, token0Decimals, token1Decimals } = input;
+    const R0 = BigInt(input.reserve0);
+    const R1 = BigInt(input.reserve1);
+
+    if (R0 === 0n || R1 === 0n) {
+        return { amountOutWei: 0n, amountOut: 0, outputDecimals: 0, amountInWei: 0n, amountIn: 0, inputDecimals: 0, targetPrice: 0 };
+    }
+
+    const k = R0 * R1;
+    const bps = BigInt(targetBps);
+    // 精度放大因子
+    const PRECISION = 10n ** 18n;
+
+    let amountOutWei: bigint;
+    let amountInWei: bigint;
+    let outputDecimals: number;
+    let inputDecimals: number;
+
+    if (isBuy) {
+        // 买入 base token → 价格上涨 → 输出 base token
+        // base token 从池子中减少
+
+        // P = quoteReserve / baseReserve
+        // P_target = P * (1 + bps/10000) = P * (10000 + bps) / 10000
+        // baseReserve_new = sqrt(k / P_target) = sqrt(k * baseReserve / quoteReserve * 10000 / (10000 + bps))
+        //
+        // 简化：baseReserve_new = sqrt(k * 10000 / ((10000 + bps) * P))
+        //      = sqrt(k * baseReserve * 10000 / (quoteReserve * (10000 + bps)))
+
+        const [baseReserve, quoteReserve] = baseIsToken0 ? [R0, R1] : [R1, R0];
+        outputDecimals = baseIsToken0 ? token0Decimals : token1Decimals;
+        inputDecimals = baseIsToken0 ? token1Decimals : token0Decimals;
+
+        // baseReserve_new = baseReserve * sqrt(10000 / (10000+bps))
+        // quoteReserve_new = k / baseReserve_new = quoteReserve * sqrt((10000+bps) / 10000)
+        // amountOut(base) = baseReserve - baseReserve_new
+        // amountIn(quote, not fee-adjusted) = quoteReserve_new - quoteReserve
+        const baseReserveNew = baseReserve * bigIntSqrt(10000n * PRECISION) / bigIntSqrt((10000n + bps) * PRECISION);
+        const quoteReserveNew = quoteReserve * bigIntSqrt((10000n + bps) * PRECISION) / bigIntSqrt(10000n * PRECISION);
+        amountOutWei = baseReserve - baseReserveNew;
+        amountInWei = quoteReserveNew - quoteReserve;
+
+    } else {
+        // 卖出 base token → 价格下跌 → 输出 quote token
+        // quote token 从池子中减少
+
+        const [baseReserve, quoteReserve] = baseIsToken0 ? [R0, R1] : [R1, R0];
+        outputDecimals = baseIsToken0 ? token1Decimals : token0Decimals;
+        inputDecimals = baseIsToken0 ? token0Decimals : token1Decimals;
+
+        // quoteReserve_new = quoteReserve * sqrt((10000-bps) / 10000)
+        // baseReserve_new = k / quoteReserve_new = baseReserve * sqrt(10000 / (10000-bps))
+        // amountOut(quote) = quoteReserve - quoteReserve_new
+        // amountIn(base, not fee-adjusted) = baseReserve_new - baseReserve
+        if (bps >= 10000n) {
+            // 100% 偏移 → 所有 quote token；amountIn 取一个有限上界（baseReserve）
+            amountOutWei = quoteReserve;
+            amountInWei = baseReserve;  // 极端情况下池子 base 耗尽
+        } else {
+            const quoteReserveNew = quoteReserve * bigIntSqrt((10000n - bps) * PRECISION) / bigIntSqrt(10000n * PRECISION);
+            const baseReserveNew = baseReserve * bigIntSqrt(10000n * PRECISION) / bigIntSqrt((10000n - bps) * PRECISION);
+            amountOutWei = quoteReserve - quoteReserveNew;
+            amountInWei = baseReserveNew - baseReserve;
+        }
+    }
+
+    const amountOut = Number(amountOutWei) / Math.pow(10, outputDecimals);
+    const amountIn = Number(amountInWei) / Math.pow(10, inputDecimals);
+
+    // 计算目标价（quote per base，UI 单位）
+    // 推到目标价后的池子状态：基于 P_target = P * (1 ± bps/10000)
+    const baseDec = baseIsToken0 ? token0Decimals : token1Decimals;
+    const quoteDec = baseIsToken0 ? token1Decimals : token0Decimals;
+    const baseReserveUi = Number(baseIsToken0 ? R0 : R1) / Math.pow(10, baseDec);
+    const quoteReserveUi = Number(baseIsToken0 ? R1 : R0) / Math.pow(10, quoteDec);
+    const midPrice = quoteReserveUi / baseReserveUi;
+    const bpsNum = Number(targetBps);
+    const targetPrice = isBuy
+        ? midPrice * (10000 + bpsNum) / 10000
+        : midPrice * (10000 - bpsNum) / 10000;
+
+    return { amountOutWei, amountOut, outputDecimals, amountInWei, amountIn, inputDecimals, targetPrice };
+}

package/src/quote/depth/index.ts

@@ -2,8 +2,9 @@
  * 深度计算模块（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。
+ *   · **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，
@@ -24,9 +25,12 @@ import {
 } 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;
@@ -40,8 +44,10 @@ function logDepthLevelsOnce(): void {
 /**
  * 池子曲线纯输入 → 用户实付（含费）：
  *   amountInGross = amountInNet / (1 - feeRate)；feeAmount = amountInGross - amountInNet
+ *
+ * 导出供 DEX 专有 depth 构建复用（如 DLMM 离散 bin 深度，在各自包内但 tier 语义统一）。
  */
-function grossUpFee(amountInNet: number, feeRateBps: number): { amountInGross: number; feeAmount: number } {
+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);
@@ -49,7 +55,8 @@ function grossUpFee(amountInNet: number, feeRateBps: number): { amountInGross: n
 }
 
 // ========== 把多档 tier 装配成 QuoteEntry（主档镜像顶层）==========
-function assembleEntry(tiers: QuoteTier[]): 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,
@@ -165,3 +172,101 @@ export function buildClmmDepth(input: BuildClmmDepthInput): QuoteDepthOutput | u
         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;
+    }
+}