@clonegod/ttd-core 3.1.69 → 3.1.70

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@clonegod/ttd-core",
-    "version": "3.1.69",
+    "version": "3.1.70",
     "description": "Common types and utilities for trading systems - use `npm run push` to publish",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",

package/types/index.d.ts

@@ -1003,6 +1003,12 @@ export interface PostTradeType {
     intervening_events: AnalyzePoolEventType[]
     event_summary: AnalyzeEventSummaryType
 
+    /**
+     * 窗口内观测到的区块头（block_number, 链上 block_time, 本地最早收到时间）
+     * UI 时间线把它作为"链上 vs 本地"的独立锚点行，便于区分传播延迟和本地处理延迟。
+     */
+    block_sequence?: AnalyzeBlockObservedType[]
+
     /** 同区块分析 (MEV) */
     same_block: AnalyzeSameBlockType
 
@@ -1022,6 +1028,8 @@ export interface AnalyzeQuoteSnapshotType {
     ask: string
     bid: string
     block_number: number
+    /** 该报价所基于的事件的链上 block_time (ms)，UI 用来计算"传播延迟"。0 = 未知 */
+    chain_time?: number
     source_txid: string
     /** 报价来源标签: 'rpc:v1' | '{provider}:v2' | '{provider}:v3' */
     source?: string
@@ -1029,6 +1037,20 @@ export interface AnalyzeQuoteSnapshotType {
     price_ready_time: number
 }
 
+/**
+ * 区块观测：trade detail 时间线里独立的 📦 行，体现"链上出块 → 我们本地收到块头"的传播延迟。
+ * 数据来自 stream-block 上报的 BlockHeadLatency（聚合到 store/mem_block_head_*）。
+ */
+export interface AnalyzeBlockObservedType {
+    block_number: number
+    /** 链上出块时间 (ms)，BSC 走 BEP-520 MixDigest 毫秒精度 */
+    block_time: number
+    /** 本地最早收到该块头的时间 (ms) */
+    local_observed_ms: number
+    /** 最早送达的 provider id */
+    provider_id: string
+}
+
 export interface AnalyzePoolEventType {
     txid: string
     block_number: number
@@ -1037,7 +1059,13 @@ export interface AnalyzePoolEventType {
     /** 该事件是否是我方发起的 tx（source_txid === 我方 OnTrade.txid） */
     is_mine?: boolean
     event_type: 'SWAP' | 'MINT' | 'BURN' | 'MODIFY_LIQUIDITY'
+    /**
+     * 时间线渲染时用的"本地观测时间" (ms)。
+     * 历史 = block_time（chain），现行 = stream_recv_time（local），便于和其他本地时间统一第一列。
+     */
     timestamp: number
+    /** 链上 block_time (ms)，UI 用来计算"传播延迟"。0 = 未知 */
+    chain_time?: number
     swap?: {
         direction: 'BUY' | 'SELL'
         amount_in: string