74 lines
4.5 KiB
Markdown
74 lines
4.5 KiB
Markdown
# 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 # 架构铁律
|
||
```
|