FastWithdrawalPoolV2 — 设计

日期：2026-03-03 状态：已批准 作者：BabyDriver Team

---

1. 背景与决策

1.1 问题

Phase 2 Oracle 集成完成后，需要增强桥功能。原计划将 FastWithdrawalPool 实现为 era 的 IL1AssetHandler 接口并迁移 L1/L2 Bridge 合约。

1.2 调研结论

深入分析 zksync-era 桥架构后发现：

• L1BridgeContract / L2BridgeContract 可以废弃 — era 已提供完整的 Bridgehub → L1AssetRouter → L1NativeTokenVault → L1Nullifier 存款/提款/证明验证管线

• FastWithdrawalPool 是唯一独有价值 — era 没有 LP 即时提款功能

1.3 方案选择

方案	描述	复杂度	安全性
A: IAssetHandler 深度集成	FastPool 实现 era 的 bridgeMint/bridgeBurn	极高	中
B: Sidecar 模式	FastPool 作为独立 L1 合约	低	高
C: NTV 包装器	包装 L1NativeTokenVault	中	中

选定方案 B：Sidecar 模式

理由：

1. 零修改 era 核心桥合约

2. 行业标准（Across、Hop 均采用此模式）

3. 独立升级，不受 era 上游更新影响

4. 安全隔离 — FastPool 的漏洞不影响 era 桥本身

1.4 取消的功能

• 大额存款 Timelock — era 的 L1Nullifier + ZK proof 已提供足够安全保障

• L1/L2 BridgeContract 迁移 — era 原生桥已覆盖全部功能

---

2. 架构

2.1 系统架构图

┌──────────────────────────────────────────────────────────┐
│                     Layer 1 (Ethereum)                    │
│                                                           │
│  ┌────────────────┐      ┌────────────────────────────┐  │
│  │ Era Bridge      │      │ FastWithdrawalPool v2      │  │
│  │ (不做修改)      │      │ (独立 Sidecar 合约)        │  │
│  │                │      │                            │  │
│  │ Bridgehub      │      │ LP: addLiquidity()         │  │
│  │   ↓            │      │ User: requestFastWithdraw()│  │
│  │ L1AssetRouter  │      │ Anyone: settleWithdrawal() │  │
│  │   ↓            │      │   ↓ 调用 Mailbox 验证 proof│  │
│  │ L1NativeToken  │      │                            │  │
│  │ Vault          │      │ 超时: reclaimTimedOut()     │  │
│  │   ↓            │      │                            │  │
│  │ L1Nullifier    │◄─────│ proveL2MessageInclusion()  │  │
│  │ (proof 验证)   │      │                            │  │
│  └────────────────┘      └────────────────────────────┘  │
│        ↕                                                  │
└────────┬─────────────────────────────────────────────────┘
         │
┌────────▼─────────────────────────────────────────────────┐
│                     Layer 2 (BabyDriver)                  │
│                                                           │
│  L2AssetRouter → L2NativeTokenVault (标准提款)            │
│  OracleHub (0x8016) — 可供未来动态费率扩展               │
└──────────────────────────────────────────────────────────┘

2.2 合约依赖

FastWithdrawalPool v2
  ├── immutable: IMailbox (era Diamond Proxy)
  ├── 继承: ReentrancyGuard (OpenZeppelin)
  └── 不依赖: AccessControl, L1AssetRouter, L1Nullifier

---

3. 合约详细设计

3.1 状态变量

contract FastWithdrawalPool is ReentrancyGuard {
    // === 常量 ===
    uint256 public constant FEE_BPS = 50;               // 0.5%
    uint256 public constant BPS_DENOMINATOR = 10_000;
    uint256 public constant MAX_SINGLE_WITHDRAWAL = 500 ether;
    uint256 public constant SETTLEMENT_TIMEOUT = 7 days;

    // === 外部依赖 ===
    IMailbox public immutable MAILBOX;   // era Diamond Proxy (Mailbox facet)

    // === 管理 ===
    address public owner;

    // === 存储 ===
    mapping(address token => uint256) private _poolBalances;
    mapping(address lp => mapping(address token => uint256)) private _lpBalances;
    mapping(address lp => mapping(address token => uint256)) private _lpFees;
    mapping(uint256 requestId => FastWithdrawalRequest) private _requests;
    mapping(bytes32 l2TxHash => uint256 requestId) private _txHashToRequest;
    uint256 public nextRequestId;
}

3.2 数据结构

struct FastWithdrawalRequest {
    address user;           // 申请快速提款的用户
    address token;          // ETH = address(0)
    uint256 amount;         // 总金额（含手续费）
    uint256 fee;            // 手续费 (amount * 50 / 10000)
    bytes32 l2TxHash;       // 绑定的 L2 标准提款交易哈希
    uint256 requestId;      // 唯一 ID
    uint256 timestamp;      // 创建时间
    bool settled;           // 是否已结算
}

3.3 核心函数

LP 流动性管理

addLiquidity(address token, uint256 amount)
  - LP 存入 ETH (payable) 或 ERC20 (safeTransferFrom)
  - _lpBalances[msg.sender][token] += amount
  - _poolBalances[token] += amount

removeLiquidity(address token, uint256 amount)
  - 验证 _lpBalances[msg.sender][token] >= amount
  - _lpBalances -= amount, _poolBalances -= amount
  - 转账给 LP

claimFees(address token)
  - fees = _lpFees[msg.sender][token]
  - _lpFees[msg.sender][token] = 0
  - 转账给 LP

用户快速提款

requestFastWithdrawal(address token, uint256 amount, bytes32 l2TxHash) → uint256 requestId

前置条件:
  - amount > 0
  - amount <= MAX_SINGLE_WITHDRAWAL (500 ETH)
  - _poolBalances[token] >= amount
  - _txHashToRequest[l2TxHash] == 0 (防重复)

执行:
  1. fee = amount * FEE_BPS / BPS_DENOMINATOR
  2. payout = amount - fee
  3. _poolBalances[token] -= amount          // 锁定全额
  4. 创建 FastWithdrawalRequest
  5. _txHashToRequest[l2TxHash] = requestId
  6. 转账 payout 给 user                    // LP 即时支付
  7. emit FastWithdrawalExecuted(requestId, user, token, amount, fee, l2TxHash)

去信任结算

settleWithdrawal(
    uint256 requestId,
    uint256 l2BatchNumber,
    uint256 l2MessageIndex,
    uint16 l2TxNumberInBatch,
    bytes32[] calldata merkleProof,
    bytes calldata message
)

任何人都可以调用:
  1. 加载 request, require(!settled)
  2. 调用 MAILBOX.proveL2MessageInclusion(
       l2BatchNumber, l2MessageIndex,
       L2Message({txNumberInBatch, sender: L2_ASSET_ROUTER, data: message}),
       merkleProof
     )
  3. 解析 message 验证: token + amount 匹配 request
  4. settled = true
  5. _poolBalances[token] += (amount - fee)   // 本金归还池
  6. _lpFees[msg.sender][token] += fee        // 手续费奖励 settler
  7. emit WithdrawalSettled(requestId, msg.sender, amount)

超时取回

reclaimTimedOut(uint256 requestId)

条件:
  - block.timestamp > request.timestamp + SETTLEMENT_TIMEOUT
  - !request.settled

执行:
  1. settled = true
  2. _poolBalances[token] += amount           // 全额归还池
  3. emit WithdrawalTimedOut(requestId)

---

4. 错误处理

场景	Revert 原因
Proof 验证失败	"Invalid L2 message proof"
已结算请求重复结算	"Already settled"
池余额不足	"Insufficient pool liquidity"
超过 500 ETH	"Exceeds max single withdrawal"
l2TxHash 重复申请	"L2 tx already claimed"
超时取回非超时请求	"Settlement not timed out"
Message 金额不匹配	"Amount mismatch"

---

5. 测试策略

5.1 Mock 合约

• MockMailbox: 可配置 proveL2MessageInclusion() 返回 true/false，模拟 era proof 验证

5.2 测试覆盖

类别	测试场景
LP 管理	添加/移除流动性, 费用领取, 余额不足
快速提款	正常流程, 上限, 池不足, 重复 l2TxHash
去信任结算	有效 proof, 无效 proof, 重复结算, 金额不匹配
超时	超时取回, 未超时拒绝, 已结算拒绝超时取回
边界	0 金额, MAX_SINGLE_WITHDRAWAL 精确边界

---

6. 实现范围

做

任务	描述
FastWithdrawalPool v2	重构合约 (~300 行)
MockMailbox	测试辅助合约 (~50 行)
测试套件	Foundry 测试 (~300 行)
bridge-enhancer	Rust LP 自动结算监控 (~100 行)

不做

功能	原因
动态费率	固定 0.5% MVP 够用
大额 Timelock	era 安全足够
多 LP 匹配	池级匹配 MVP 够用
ERC20 快速提款	初始只支持 ETH
L2 侧合约	纯 L1 Sidecar
修改 era 合约	零耦合原则

---

7. 与现有代码的关系

文件	处理
contracts/src/bridge/FastWithdrawalPool.sol	v1 保留作参考，v2 新文件
contracts/src/bridge/L1BridgeContract.sol	废弃（era 原生桥替代）
contracts/src/bridge/L2BridgeContract.sol	废弃（era 原生桥替代）
contracts/src/libraries/PriceLib.sol	保留（未来动态费率可用）
contracts/test/Bridge.t.sol	v1 测试保留，新增 v2 测试文件