wtf-indexer/ARCHITECTURE.md

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                 # 架构铁律