@clonegod/ttd-sol-common 2.0.67 → 2.0.69

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'))
+}

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';