DexDecoder — DEX 协议解析框架

基于第一性原理（First Principles）构建的 DEX 协议解析与验证框架，用于链下观测、报价模拟与精度校验。

你在解决什么问题

从底层看，DEX 报价问题就是：

amountOut = F(protocol_rules, state_before_swap, amountIn, direction)

如果你不知道这 4 个输入中的任何一个，报价就不可信。

DexDecoder 的「六步方法论」就是把这个公式拆成可验证的工程流程，避免“看起来能跑、实际上不可靠”的实现。

六步方法论（从第一性原理解释）

Step	名称	本质问题	输入	输出
1	Pool Discovery	我在和哪个池子交互？	链上事件日志	PoolMeta（静态元信息）
2	State Reading	这个池子当前状态是什么？	PoolMeta + eth_call	RawState（状态快照）
3	Math Modeling	协议规则如何映射成数学？	协议白皮书/源码规则 + RawState	AMMConstraint（数学约束）
4	Local Simulation	在本地按规则执行 swap 会发生什么？	AMMConstraint + SwapParams	本地 amountOut
5	On-chain Quote	链上真实实现返回什么？	Quoter / Query 合约 + 同样参数	链上 amountOut
6	Accuracy Check	本地与链上偏差是否可接受？	Step4 + Step5 结果	AccuracyReport

如果跳过任意一步：

• 跳过 Step1：可能查错池子。
• 跳过 Step2：状态过期或字段不全。
• 跳过 Step3：数学模型与协议实现不一致。
• 跳过 Step5：无法知道本地模型是否偏离真实合约。

架构总览

src/
├── core.py                         # 抽象框架：ProtocolAdapter / AMMConstraint / PoolMeta / RawState
├── balancer_adapter.py             # Balancer V2 适配器
├── models.py / abis.py / ...       # Balancer V2 具体实现
├── events/                         # 事件扫描与分析模块（新）
│   ├── models.py                   # ProtocolEvent / ScanResult
│   ├── scanner.py                  # scan_events / scan_events_last_n_days
│   ├── analyzer.py                 # 创建事件与状态事件分析
│   └── reporter.py                 # events.ndjson / summary.json / analysis.md 输出
└── protocols/
    ├── concentrated/               # V3/V4/Algebra 共享数学库
    ├── uniswap_v3/
    ├── uniswap_v4/
    └── algebra/

协议支持矩阵

协议	AMM 类型	状态	模拟难度	精度目标
Balancer V2 WeightedPool	加权恒定乘积	已实现 + 链上验证	★☆☆☆☆	< 0.05%
Uniswap V3	集中流动性	已实现	★★★☆☆	0 误差（1-2 wei）
Uniswap V4	集中流动性 + Hooks	已实现	★★★★★	无自定义曲线 Hook 时接近 0 误差
Algebra (QuickSwap V3)	集中流动性 + Plugin	已实现	★★★★☆	静态 fee 时接近 0 误差

快速开始

# 1) 安装依赖
pip install -r requirements.txt

# 2) 跑单测（不需要 RPC）
pytest tests/ -v

# 3) 查看协议注册信息
python main.py --list-protocols

# 4) 跑六步流程示例（需要 RPC）
python main.py --rpc YOUR_ETH_RPC --protocol balancer --pool 80BAL-20WETH
python main.py --rpc YOUR_ETH_RPC --protocol v3 --pool USDC-WETH-3000

新增：事件扫描与报告（过去一周）

目标：扫描池子创建事件 + 状态变更事件，并生成结构化报告。

# 扫描过去 7 天（默认 days=7）
python main.py --event-scan --protocol all --rpc YOUR_ETH_RPC --algebra-chain ethereum --algebra-factory YOUR_ALGEBRA_FACTORY

# 指定窗口与输出目录
python main.py --event-scan --protocol balancer --days 7 --rpc YOUR_ETH_RPC --out-dir reports/events

# 免费 RPC（如 Alchemy Free）建议缩小区块分片，避免 eth_getLogs 限制
EVENT_SCAN_HTTP_TIMEOUT=20 python main.py --event-scan --protocol v4 --days 1 --batch-size 10 --event-types creation,modifyliquidity

输出目录结构：

reports/events/<run_id>/
├── events.ndjson   # 原始事件逐行 JSON
├── summary.json    # 聚合指标摘要
└── analysis.md     # 人类可读分析报告

给第一次阅读代码的读者

推荐按下面顺序读：

1. 先读抽象接口：src/core.py
2. 再读一个最简单协议（Balancer）：
   src/balancer_adapter.py
   src/vault_client.py
3. 再读集中流动性共享数学：
   src/protocols/concentrated/swap_math.py
   src/protocols/concentrated/swap_engine.py
4. 最后读 V3/V4/Algebra 的差异化 adapter。

如果你重点关注“事件驱动分析”，从这里开始：

• src/events/scanner.py
• src/events/analyzer.py
• src/events/reporter.py

测试

# 全量
pytest tests/ -v

# 事件模块
pytest tests/test_event_scanner.py -v
pytest tests/test_event_analyzer.py -v
pytest tests/test_event_reporter.py -v

深入文档

文档	说明
六步法可视化导读	第一性原理 + 六步流程图 + 代码映射图（适合新读者）
六步方法论（底层逻辑）	从第一性原理解释六步
代码导航	模块与依赖关系
全协议概要	四协议横向对比
Uniswap V3/V4 分析	V3 Factory vs V4 Singleton + Hooks
Algebra 分析	Plugin / 动态费率机制
Balancer 指南	WeightedPool 入门

已知限制

• Balancer 目前只支持 WeightedPool。
• V3/Algebra 的状态事件扫描默认以“窗口内发现的新池”为范围，不会自动回扫历史全池。
• 含 BEFORE_SWAP_RETURNS_DELTA Hook 的 V4 池子，本地模拟可能失真，需以链上 quote 为准。
• Algebra 动态费率可能在 swap 过程中变化，本地模型使用状态快照值。