feat: scaffold deterministic replayable indexer architecture with core pipeline, models and docker

2026-08-31 00:03:33 +08:00
parent b9bed788d7
commit fae49b2b1e
15 changed files with 165 additions and 0 deletions
@@ -0,0 +1,73 @@
+# WTFX Indexer Architecture & Principles (索引器架构与核心铁律)
+
+> **定位**：Indexer 不是数据库搬运工，而是 **“区块链事实 → WTFX 可查询状态” 的确定性投影系统**。
+> **运行形态**：第一阶段单进程运行，但严格按照 **Fetch -> Decode -> Process -> Project** 四层边界设计，支持**零停机热追高、全量可重放、幂等去重、防链重组 (Reorg)**。
+
+---
+
+## 1. 五大核心架构铁律 (Non-Negotiable Principles)
+
+1. **【三层数据流转：Raw -> Normalized -> Projection】**：
+   - **Raw Layer**：原样保存链上原始日志 (`raw_logs`, `raw_blocks`)。
+   - **Normalized Layer**：解析为跨链统一的标准事件字典 (`chain_events`: `ORDER_FILLED`, `MARKET_CREATED`, `SETTLEMENT`)。
+   - **Projection Layer**：生成业务最终可查询的只读视图 (`markets`, `trades`, `positions`, `token_balances`)。
+2. **【绝对可重放性 (Replayability)】**：
+   - 当业务投影算法调整或修复时，**严禁手工修数据库**；
+   - 必须支持：清空 Projection 视图 $␍ightarrow$ 从指定 Checkpoint 或 Block 0 重新重放 Normalized Events $␍ightarrow$ 确定性重新生成 Projection。
+3. **【幂等去重保证 (Idempotency)】**：
+   - 每个事件唯一凭证为 `(chain_id, tx_hash, log_index)`；
+   - 数据库唯一约束拦截重复写入，重复消费或追高扫描时无脑跳过已存在事件。
+4. **【安全检查点与防重组 (Checkpoint & Reorg Protection)】**：
+   - 维护持久化 `indexer_state` 记录安全落盘水位；
+   - 区分 `CONFIRMED`（快速响应）与 `FINALIZED`（安全落盘），为最新区块预留回退重测窗口。
+5. **【不直接越权控制业务资金】**：
+   - Indexer 只负责**“发现链上发生了什么”**，严禁直接在 Indexer 内部修改用户余额；
+   - 资金结算与账本生成交由 Backend 的 Settlement Service 处理。
+
+---
+
+## 2. 目录结构全景
+
+```
+wtf-indexer/
+├── src/
+│   ├── main.py                     # 索引器服务入口与管道调度器 (Pipeline Runner)
+│   ├── config.py                   # RPC、链配置、数据库与扫描区间配置
+│   │
+│   ├── core/                       # 核心抽象与不可变数据模型
+│   │   ├── events.py               # 规范化事件定义 (Normalized Event Schema)
+│   │   ├── checkpoint.py           # Checkpoint 水位管理器与 Reorg 检测
+│   │   └── models.py               # 基础类型与接口抽象
+│   │
+│   ├── ingestion/                  # 链上数据拉取层 (Fetcher)
+│   │   ├── fetcher.py              # RPC 批量抓块与重试调度 (Batch eth_getLogs)
+│   │   └── queue.py                # 内存/Redis 缓冲队列
+│   │
+│   ├── decoding/                   # 事件解析层 (Decoder)
+│   │   ├── evm.py                  # EVM ABI 日志解码器 (WTFMarketV2, Controller)
+│   │   └── base.py                 # 解码器抽象基类
+│   │
+│   ├── processors/                 # 业务领域处理器 (Processor)
+│   │   ├── market.py               # 市场创建/状态流转处理
+│   │   ├── trading.py              # 订单成交与代币铸造/赎回处理
+│   │   └── settlement.py           # 到期裁决与兑付结算处理
+│   │
+│   ├── projections/                # 确定性投影层 (Projection Views)
+│   │   ├── markets.py              # 市场聚合状态表投影
+│   │   ├── trades.py               # 逐笔交易记录投影
+│   │   └── positions.py            # 用户持仓与成本投影
+│   │
+│   ├── chains/                     # 链适配器 (Chain Adapters)
+│   │   ├── robinhood.py            # Robinhood Chain (Testnet/Mainnet) 适配器
+│   │   └── base.py                 # 通用 EVM 适配器
+│   │
+│   └── infrastructure/             # 底层设施
+│       ├── postgres.py             # 异步 PostgreSQL 连接与投影持久化
+│       ├── redis.py                # Redis 锁与事件总线广播
+│       └── rpc.py                  # 健壮的多节点 RPC 客户端
+│
+├── tests/                          # 可重放测试与解码单元测试
+├── Dockerfile                      # 容器构建镜像
+├── requirements.txt                # 依赖包配置
+└── ARCHITECTURE.md                 # 架构铁律
+```