@clonegod/ttd-sol-common 2.0.67 → 2.0.68

package/src/quote/quote_amount.ts

@@ -0,0 +1,37 @@
+import { get_solana_token_price_info, StandardPoolInfoType } from '@clonegod/ttd-core';
+import Decimal from 'decimal.js';
+
+/**
+ * 解析询价使用的 USD 金额（与 BSC/SUI 同名 helper 对齐）。
+ *
+ * 优先级：
+ *   1. 环境变量 QUOTE_AMOUNT_USD（全局覆盖，方便统一调整）
+ *   2. pool 配置里的 quote_amount_usd（每个 pool 可以差异化配置）
+ *
+ * quote_amount_usd 用于询价时模拟"卖/买多少 USD 价值的 token"，应与典型订单量接近，
+ * 否则 order_price 与 tx_price 会有明显差距（AMM price impact 非线性）。
+ */
+export function getQuoteAmountUsd(poolInfo: StandardPoolInfoType): number {
+    const envValue = Number(process.env.QUOTE_AMOUNT_USD);
+    if (envValue > 0) {
+        return envValue;
+    }
+    return poolInfo.quote_amount_usd;
+}
+
+/**
+ * 按 arb_cache 中的当前 USD 价把 quoteAmountUsd 折算成 token 的 UI amount（小数形式）。
+ *
+ * 各 DEX 询价 compute amountIn 用。价格 miss / 为 0 抛错，由 caller 决定降级。
+ */
+export async function usdToTokenUiAmount(
+    amountInUsd: number,
+    tokenAddress: string,
+): Promise<Decimal> {
+    const priceMap = await get_solana_token_price_info([tokenAddress]);
+    const price = priceMap.get(tokenAddress)?.price;
+    if (!price || price === '0') {
+        throw new Error(`price not available for ${tokenAddress}`);
+    }
+    return new Decimal(amountInUsd).div(new Decimal(price));
+}

package/src/quote/quote_trace.ts

@@ -0,0 +1,56 @@
+import { createLogger } from '@clonegod/ttd-core';
+
+const logger = createLogger(__filename);
+
+/**
+ * QuoteTrace —— 询价链路追踪（镜像 trade 侧 TradeTrace，与 BSC/SUI 同名文件对齐）。
+ *
+ * 一次询价收集各阶段耗时 + 关键字段，结束一次性输出**一行**结构化日志。
+ * 阶段标准：trigger -> compute -> depth -> verify -> publish。
+ *
+ * 用法：
+ *   const t = new QuoteTrace('SOL/USDC', '...', slot, 'local:v2');
+ *   t.mark('compute'); t.set('ask', 1564.6); ...; t.flush();
+ */
+export class QuoteTrace {
+    private startTime = Date.now();
+    private marks: Array<{ name: string; elapsed: number }> = [];
+    private data: Record<string, any> = {};
+    private error: { stage: string; message: string } | null = null;
+
+    constructor(
+        public readonly poolName: string,
+        public readonly poolAddress: string,
+        public blockNumber: number = 0,
+        public source: string = '',
+    ) {}
+
+    mark(name: string): void {
+        this.marks.push({ name, elapsed: Date.now() - this.startTime });
+    }
+    set(key: string, value: any): void { this.data[key] = value; }
+    markError(stage: string, message: string): void { this.error = { stage, message }; }
+
+    /** trigger(0ms) -> compute(4ms) -> depth(2ms) -> publish(1ms) = 7ms（括号=增量耗时） */
+    private buildTimeline(): string {
+        if (this.marks.length === 0) return '(no marks)';
+        let prev = 0;
+        const parts = this.marks.map(m => { const d = m.elapsed - prev; prev = m.elapsed; return `${m.name}(${d}ms)`; });
+        return `${parts.join(' -> ')} = ${this.marks[this.marks.length - 1].elapsed}ms`;
+    }
+
+    flush(): void {
+        const timeline = this.buildTimeline();
+        if (this.error) {
+            logger.error(
+                `[QUOTE FAILED] ${this.poolName} | stage=${this.error.stage} | source=${this.source} | ${this.error.message}`,
+                new Error(this.error.message),
+            );
+            logger.info(`[QUOTE FAILED detail] ${this.poolName}`, { timeline, error_stage: this.error.stage, source: this.source, ...this.data });
+        } else {
+            // 成功路径降到 debug：ask/bid/block/txid 已在 on_quote_response 的推送行摘要里，
+            // 这里仅保留细粒度 timeline 供调试。失败路径仍 error/info 响亮。
+            logger.debug(`[QUOTE OK] ${this.poolName} blk=${this.blockNumber} source=${this.source}`, { timeline, ...this.data });
+        }
+    }
+}

package/src/quote/tick/clmm_tick_math.ts

@@ -0,0 +1,77 @@
+/**
+ * 共享 CLMM TickMath（Solana，Uniswap V3 Q64.64 magic-constant 版）
+ *
+ * Solana 三个 CLMM（Raydium / Orca / ByReal）的 tick→sqrtPrice 数学**同源 Uniswap V3**：
+ * sqrtPriceX64 = sqrt(1.0001)^tick × 2^64，用一组幂次魔数 + 右移 64 位累乘实现。
+ *
+ * 本实现**逐字移植自 raydium SDK / byreal SDK 的 `SqrtPriceMath.getSqrtPriceX64FromTick`**
+ * （node_modules/byreal-clmm-sdk-alpha/.../sqrtPriceMath.js，与 raydium-sdk-v2 的 math.js 同魔数），
+ * 仅把 BN 运算改成纯 bigint：
+ *   - mulRightShift(ratio, mulBy) = (ratio * mulBy) >> 64n
+ *     （SDK 用 signedRightShift(·,64,256)；此处所有值恒正且乘积 < 2^128，等价无符号右移 64）
+ *   - tick > 0 时取倒数 ratio = MaxUint128 / ratio（SDK 同）。
+ *
+ * 四源一致性校验结论（逐 tick bigint 比较 -443636/-100000/-1/0/1/100/10000/443636）：
+ *   - **本函数 == raydium SDK == byreal SDK 完全一致**（8/8 tick 全等）。三者都是 X64-native 魔数版。
+ *   - **orca SDK `PriceMath.tickIndexToSqrtPriceX64` 在末几位有微小偏差**（非 bug）：orca 用 **X96 魔数**
+ *     （2^96-scaled，每步右移 96）算完再 `>> 32` 降到 X64，rounding 累积路径不同 → 低 ~5 位差异。
+ *     orca whirlpool 链上 sqrtPrice 存的是 u128 X64、链上 swap 走 X64 整数math，故 X64-native 版（本函数/raydium/byreal）
+ *     才是与链上一致的形态；orca SDK 的 X96-downshift 只是它的 tick→sqrtPrice 辅助。差异在 tick 粒度上 sub-wei，
+ *     对深度档位边界无实质影响 → 三个 CLMM 统一用本函数（符合"共享一份 TickMath"规范）。
+ *
+ * 纯 bigint、零外部依赖，三个 CLMM 包共享同一份（DepthTick.sqrtPriceX64 的唯一来源）。
+ */
+
+/** Uniswap V3 tick 边界（与 raydium/orca/byreal SDK 一致）。 */
+export const MIN_TICK = -443636;
+export const MAX_TICK = 443636;
+
+/** sqrtPriceX64 边界（getSqrtPriceX64FromTick(MIN_TICK/MAX_TICK)，与 SDK 常量一致）。 */
+export const MIN_SQRT_PRICE_X64 = 4295048016n;
+export const MAX_SQRT_PRICE_X64 = 79226673521066979257578248091n;
+
+const MaxUint128 = (1n << 128n) - 1n;
+
+/** (val * mulBy) >> 64 —— SDK signedRightShift(·, 64, 256) 在恒正、乘积 < 2^128 下的等价。 */
+function mulRightShift(val: bigint, mulBy: bigint): bigint {
+    return (val * mulBy) >> 64n;
+}
+
+/**
+ * tick → sqrtPriceX64（Q64.64）。
+ * 与 raydium `SqrtPriceMath.getSqrtPriceX64FromTick` / orca `PriceMath.tickIndexToSqrtPriceX64`
+ * / byreal `SqrtPriceMath.getSqrtPriceX64FromTick` bigint 完全一致。
+ */
+export function getSqrtPriceX64FromTick(tick: number): bigint {
+    if (!Number.isInteger(tick)) {
+        throw new Error('tick must be integer');
+    }
+    if (tick < MIN_TICK || tick > MAX_TICK) {
+        throw new Error('tick must be in MIN_TICK and MAX_TICK');
+    }
+    const tickAbs = tick < 0 ? -tick : tick;
+
+    let ratio = (tickAbs & 0x1) !== 0 ? 18445821805675395072n : 18446744073709551616n;
+    if ((tickAbs & 0x2) !== 0) ratio = mulRightShift(ratio, 18444899583751176192n);
+    if ((tickAbs & 0x4) !== 0) ratio = mulRightShift(ratio, 18443055278223355904n);
+    if ((tickAbs & 0x8) !== 0) ratio = mulRightShift(ratio, 18439367220385607680n);
+    if ((tickAbs & 0x10) !== 0) ratio = mulRightShift(ratio, 18431993317065453568n);
+    if ((tickAbs & 0x20) !== 0) ratio = mulRightShift(ratio, 18417254355718170624n);
+    if ((tickAbs & 0x40) !== 0) ratio = mulRightShift(ratio, 18387811781193609216n);
+    if ((tickAbs & 0x80) !== 0) ratio = mulRightShift(ratio, 18329067761203558400n);
+    if ((tickAbs & 0x100) !== 0) ratio = mulRightShift(ratio, 18212142134806163456n);
+    if ((tickAbs & 0x200) !== 0) ratio = mulRightShift(ratio, 17980523815641700352n);
+    if ((tickAbs & 0x400) !== 0) ratio = mulRightShift(ratio, 17526086738831433728n);
+    if ((tickAbs & 0x800) !== 0) ratio = mulRightShift(ratio, 16651378430235570176n);
+    if ((tickAbs & 0x1000) !== 0) ratio = mulRightShift(ratio, 15030750278694412288n);
+    if ((tickAbs & 0x2000) !== 0) ratio = mulRightShift(ratio, 12247334978884435968n);
+    if ((tickAbs & 0x4000) !== 0) ratio = mulRightShift(ratio, 8131365268886854656n);
+    if ((tickAbs & 0x8000) !== 0) ratio = mulRightShift(ratio, 3584323654725218816n);
+    if ((tickAbs & 0x10000) !== 0) ratio = mulRightShift(ratio, 696457651848324352n);
+    if ((tickAbs & 0x20000) !== 0) ratio = mulRightShift(ratio, 26294789957507116n);
+    if ((tickAbs & 0x40000) !== 0) ratio = mulRightShift(ratio, 37481735321082n);
+
+    if (tick > 0) ratio = MaxUint128 / ratio;
+
+    return ratio;
+}

package/src/quote/tick/index.ts

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

package/src/quote/verify/index.ts

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