FastWithdrawalPoolV2 — 实现

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Implement a trustless FastWithdrawalPool v2 as an L1 Sidecar contract that uses era Mailbox proof verification for settlement.

Architecture: Standalone Solidity contract on L1 alongside era's native bridge. LPs provide liquidity; users get instant withdrawals by binding an L2 standard withdrawal tx hash; anyone can settle by providing a valid era L2→L1 message proof. No era contracts are modified.

Tech Stack: Solidity 0.8.26, Foundry, OpenZeppelin v5.6.1 (ReentrancyGuard), era IMailbox interface (minimal local copy)

Design Doc: docs/plans/2026-03-03-bridge-enhancement-design.md

---

Task 1: Interfaces — IFastWithdrawalPoolV2 + IMailbox

Files:

• Create: contracts/src/interfaces/IFastWithdrawalPoolV2.sol

• Create: contracts/src/interfaces/IMailbox.sol

Step 1: Create the minimal IMailbox interface

This is a local copy of the era Mailbox proof verification interface. We copy only what we need to avoid cross-project build dependencies.

// contracts/src/interfaces/IMailbox.sol
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.26;

/// @notice Minimal interface for era Diamond Proxy Mailbox facet.
/// Copied from era-contracts: state-transition/chain-interfaces/IMailboxImpl.sol
/// Only includes the proof verification function needed by FastWithdrawalPool v2.
interface IMailbox {
    /// @notice L2-to-L1 message structure
    struct L2Message {
        uint16 txNumberInBatch;
        address sender;
        bytes data;
    }

    /// @notice Verify that an L2-to-L1 message was included in a finalized batch
    /// @param _batchNumber L2 batch number where the message was sent
    /// @param _index Message index within the batch
    /// @param _message The L2 message content
    /// @param _proof Merkle proof of inclusion
    /// @return Whether the proof is valid
    function proveL2MessageInclusion(
        uint256 _batchNumber,
        uint256 _index,
        L2Message calldata _message,
        bytes32[] calldata _proof
    ) external view returns (bool);
}

Step 2: Create the IFastWithdrawalPoolV2 interface

// contracts/src/interfaces/IFastWithdrawalPoolV2.sol
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.26;

interface IFastWithdrawalPoolV2 {
    struct FastWithdrawalRequest {
        address user;
        address token;
        uint256 amount;
        uint256 fee;
        bytes32 l2TxHash;
        uint256 requestId;
        uint256 timestamp;
        bool settled;
    }

    event LiquidityAdded(address indexed lp, address indexed token, uint256 amount);
    event LiquidityRemoved(address indexed lp, address indexed token, uint256 amount);
    event FastWithdrawalExecuted(
        uint256 indexed requestId,
        address indexed user,
        address token,
        uint256 amount,
        uint256 fee,
        bytes32 l2TxHash
    );
    event WithdrawalSettled(uint256 indexed requestId, address indexed settler, uint256 amount);
    event WithdrawalTimedOut(uint256 indexed requestId);

    function addLiquidity(address token, uint256 amount) external payable;
    function removeLiquidity(address token, uint256 amount) external;
    function claimFees(address token) external;
    function requestFastWithdrawal(address token, uint256 amount, bytes32 l2TxHash) external returns (uint256);
    function settleWithdrawal(
        uint256 requestId,
        uint256 l2BatchNumber,
        uint256 l2MessageIndex,
        uint16 l2TxNumberInBatch,
        bytes32[] calldata merkleProof,
        bytes calldata message
    ) external;
    function reclaimTimedOut(uint256 requestId) external;

    function getPoolBalance(address token) external view returns (uint256);
    function getLpBalance(address lp, address token) external view returns (uint256);
    function getLpFees(address lp, address token) external view returns (uint256);
    function getRequest(uint256 requestId) external view returns (FastWithdrawalRequest memory);
    function getFeeRate() external pure returns (uint256);
}

Step 3: Verify compilation

Run: cd /Users/judybaby/CodeBase/github/Layer2/contracts && forge build Expected: Compiles with no errors

Step 4: Commit

git add contracts/src/interfaces/IFastWithdrawalPoolV2.sol contracts/src/interfaces/IMailbox.sol
git commit -m "feat(bridge): add IFastWithdrawalPoolV2 and IMailbox interfaces"

---

Task 2: MockMailbox Test Helper

Files:

• Create: contracts/test/mocks/MockMailbox.sol

Step 1: Create MockMailbox

// contracts/test/mocks/MockMailbox.sol
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.26;

import "../../src/interfaces/IMailbox.sol";

/// @notice Mock Mailbox for testing FastWithdrawalPool v2 settlement.
/// Allows tests to configure which proofs are valid.
contract MockMailbox is IMailbox {
    bool public defaultResponse;
    mapping(bytes32 => bool) private _validProofs;

    constructor(bool _defaultResponse) {
        defaultResponse = _defaultResponse;
    }

    /// @notice Register a specific proof as valid
    function setProofValid(uint256 batchNumber, uint256 index, bytes32 messageHash) external {
        bytes32 key = keccak256(abi.encode(batchNumber, index, messageHash));
        _validProofs[key] = true;
    }

    /// @notice Set default response for all proofs
    function setDefaultResponse(bool _response) external {
        defaultResponse = _response;
    }

    function proveL2MessageInclusion(
        uint256 _batchNumber,
        uint256 _index,
        L2Message calldata _message,
        bytes32[] calldata /* _proof */
    ) external view override returns (bool) {
        bytes32 messageHash = keccak256(abi.encode(_message.txNumberInBatch, _message.sender, _message.data));
        bytes32 key = keccak256(abi.encode(_batchNumber, _index, messageHash));
        if (_validProofs[key]) {
            return true;
        }
        return defaultResponse;
    }
}

Step 2: Verify compilation

Run: cd /Users/judybaby/CodeBase/github/Layer2/contracts && forge build Expected: Compiles with no errors

Step 3: Commit

git add contracts/test/mocks/MockMailbox.sol
git commit -m "test(bridge): add MockMailbox for era proof simulation"

---

Task 3: FastWithdrawalPool v2 — Contract Skeleton + LP Liquidity (TDD)

Files:

• Create: contracts/src/bridge/FastWithdrawalPoolV2.sol

• Create: contracts/test/FastWithdrawalPoolV2.t.sol

Step 1: Write failing tests for LP liquidity

// contracts/test/FastWithdrawalPoolV2.t.sol
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.26;

import "forge-std/Test.sol";
import "../src/bridge/FastWithdrawalPoolV2.sol";
import "../src/interfaces/IMailbox.sol";
import "./mocks/MockMailbox.sol";

contract FastWithdrawalPoolV2Test is Test {
    FastWithdrawalPoolV2 public pool;
    MockMailbox public mockMailbox;

    address lp1 = address(0xLP01);
    address lp2 = address(0xLP02);
    address user = address(0xCAFE);
    address ethToken = address(0); // ETH

    function setUp() public {
        mockMailbox = new MockMailbox(false);
        pool = new FastWithdrawalPoolV2(address(mockMailbox));
        vm.deal(lp1, 1000 ether);
        vm.deal(lp2, 1000 ether);
        vm.deal(user, 100 ether);
    }

    // === LP Liquidity Tests ===

    function test_addLiquidity_ETH() public {
        vm.prank(lp1);
        pool.addLiquidity{value: 10 ether}(ethToken, 10 ether);

        assertEq(pool.getPoolBalance(ethToken), 10 ether);
        assertEq(pool.getLpBalance(lp1, ethToken), 10 ether);
    }

    function test_addLiquidity_emitsEvent() public {
        vm.prank(lp1);
        vm.expectEmit(true, true, false, true);
        emit IFastWithdrawalPoolV2.LiquidityAdded(lp1, ethToken, 10 ether);
        pool.addLiquidity{value: 10 ether}(ethToken, 10 ether);
    }

    function test_addLiquidity_multipleLPs() public {
        vm.prank(lp1);
        pool.addLiquidity{value: 10 ether}(ethToken, 10 ether);
        vm.prank(lp2);
        pool.addLiquidity{value: 20 ether}(ethToken, 20 ether);

        assertEq(pool.getPoolBalance(ethToken), 30 ether);
        assertEq(pool.getLpBalance(lp1, ethToken), 10 ether);
        assertEq(pool.getLpBalance(lp2, ethToken), 20 ether);
    }

    function test_addLiquidity_revertZeroAmount() public {
        vm.prank(lp1);
        vm.expectRevert("Amount must be > 0");
        pool.addLiquidity{value: 0}(ethToken, 0);
    }

    function test_addLiquidity_revertMsgValueMismatch() public {
        vm.prank(lp1);
        vm.expectRevert("ETH amount mismatch");
        pool.addLiquidity{value: 5 ether}(ethToken, 10 ether);
    }

    function test_removeLiquidity_ETH() public {
        vm.prank(lp1);
        pool.addLiquidity{value: 10 ether}(ethToken, 10 ether);

        vm.prank(lp1);
        pool.removeLiquidity(ethToken, 4 ether);

        assertEq(pool.getPoolBalance(ethToken), 6 ether);
        assertEq(pool.getLpBalance(lp1, ethToken), 6 ether);
        assertEq(lp1.balance, 994 ether); // 1000 - 10 + 4
    }

    function test_removeLiquidity_revertInsufficientBalance() public {
        vm.prank(lp1);
        pool.addLiquidity{value: 10 ether}(ethToken, 10 ether);

        vm.prank(lp1);
        vm.expectRevert("Insufficient LP balance");
        pool.removeLiquidity(ethToken, 11 ether);
    }

    function test_removeLiquidity_emitsEvent() public {
        vm.prank(lp1);
        pool.addLiquidity{value: 10 ether}(ethToken, 10 ether);

        vm.prank(lp1);
        vm.expectEmit(true, true, false, true);
        emit IFastWithdrawalPoolV2.LiquidityRemoved(lp1, ethToken, 4 ether);
        pool.removeLiquidity(ethToken, 4 ether);
    }

    function test_getFeeRate() public view {
        assertEq(pool.getFeeRate(), 50);
    }
}

Step 2: Run tests to verify they fail

Run: cd /Users/judybaby/CodeBase/github/Layer2/contracts && forge test --match-contract FastWithdrawalPoolV2Test -v Expected: Compilation error — FastWithdrawalPoolV2 not found

Step 3: Implement FastWithdrawalPoolV2 skeleton + LP functions

// contracts/src/bridge/FastWithdrawalPoolV2.sol
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.26;

import "@openzeppelin/contracts/utils/ReentrancyGuard.sol";
import "../interfaces/IFastWithdrawalPoolV2.sol";
import "../interfaces/IMailbox.sol";

/// @title FastWithdrawalPool v2 — Trustless LP-backed instant withdrawals
/// @notice Sidecar contract alongside era's native bridge. Uses era Mailbox
///         proof verification for settlement instead of trusted roles.
contract FastWithdrawalPoolV2 is IFastWithdrawalPoolV2, ReentrancyGuard {
    uint256 public constant FEE_BPS = 50;
    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;

    mapping(address => uint256) private _poolBalances;
    mapping(address => mapping(address => uint256)) private _lpBalances;
    mapping(address => mapping(address => uint256)) private _lpFees;
    mapping(uint256 => FastWithdrawalRequest) private _requests;
    mapping(bytes32 => uint256) private _txHashToRequest;
    uint256 public nextRequestId;

    constructor(address mailbox_) {
        require(mailbox_ != address(0), "Mailbox cannot be zero");
        MAILBOX = IMailbox(mailbox_);
        nextRequestId = 1; // start at 1 so 0 means "no request"
    }

    // ──────────────────── LP Liquidity ────────────────────

    function addLiquidity(address token, uint256 amount) external payable override nonReentrant {
        require(amount > 0, "Amount must be > 0");
        if (token == address(0)) {
            require(msg.value == amount, "ETH amount mismatch");
        } else {
            revert("ERC20 not supported in v2 MVP");
        }
        _lpBalances[msg.sender][token] += amount;
        _poolBalances[token] += amount;
        emit LiquidityAdded(msg.sender, token, amount);
    }

    function removeLiquidity(address token, uint256 amount) external override nonReentrant {
        require(amount > 0, "Amount must be > 0");
        require(_lpBalances[msg.sender][token] >= amount, "Insufficient LP balance");
        _lpBalances[msg.sender][token] -= amount;
        _poolBalances[token] -= amount;
        if (token == address(0)) {
            (bool ok,) = msg.sender.call{value: amount}("");
            require(ok, "ETH transfer failed");
        }
        emit LiquidityRemoved(msg.sender, token, amount);
    }

    function claimFees(address token) external override nonReentrant {
        uint256 fees = _lpFees[msg.sender][token];
        require(fees > 0, "No fees to claim");
        _lpFees[msg.sender][token] = 0;
        if (token == address(0)) {
            (bool ok,) = msg.sender.call{value: fees}("");
            require(ok, "ETH transfer failed");
        }
    }

    // ──────────────────── Fast Withdrawal ────────────────────

    function requestFastWithdrawal(address token, uint256 amount, bytes32 l2TxHash)
        external
        override
        nonReentrant
        returns (uint256)
    {
        revert("Not implemented yet");
    }

    function settleWithdrawal(
        uint256 requestId,
        uint256 l2BatchNumber,
        uint256 l2MessageIndex,
        uint16 l2TxNumberInBatch,
        bytes32[] calldata merkleProof,
        bytes calldata message
    ) external override nonReentrant {
        revert("Not implemented yet");
    }

    function reclaimTimedOut(uint256 requestId) external override nonReentrant {
        revert("Not implemented yet");
    }

    // ──────────────────── View Functions ────────────────────

    function getPoolBalance(address token) external view override returns (uint256) {
        return _poolBalances[token];
    }

    function getLpBalance(address lp, address token) external view override returns (uint256) {
        return _lpBalances[lp][token];
    }

    function getLpFees(address lp, address token) external view override returns (uint256) {
        return _lpFees[lp][token];
    }

    function getRequest(uint256 requestId) external view override returns (FastWithdrawalRequest memory) {
        return _requests[requestId];
    }

    function getFeeRate() external pure override returns (uint256) {
        return FEE_BPS;
    }
}

Step 4: Run tests to verify they pass

Run: cd /Users/judybaby/CodeBase/github/Layer2/contracts && forge test --match-contract FastWithdrawalPoolV2Test -v Expected: All 8 tests PASS

Step 5: Commit

git add contracts/src/bridge/FastWithdrawalPoolV2.sol contracts/test/FastWithdrawalPoolV2.t.sol
git commit -m "feat(bridge): FastWithdrawalPoolV2 skeleton + LP liquidity (TDD)"

---

Task 4: requestFastWithdrawal (TDD)

Files:

• Modify: contracts/test/FastWithdrawalPoolV2.t.sol — add tests

• Modify: contracts/src/bridge/FastWithdrawalPoolV2.sol — implement function

Step 1: Add failing tests

Append to FastWithdrawalPoolV2Test:

    // === Fast Withdrawal Request Tests ===

    function test_requestFastWithdrawal_success() public {
        // LP adds liquidity
        vm.prank(lp1);
        pool.addLiquidity{value: 100 ether}(ethToken, 100 ether);

        bytes32 l2TxHash = keccak256("test-l2-tx-1");
        uint256 amount = 10 ether;
        uint256 expectedFee = (amount * 50) / 10_000; // 0.05 ether
        uint256 expectedPayout = amount - expectedFee; // 9.95 ether

        uint256 userBalBefore = user.balance;

        vm.prank(user);
        uint256 requestId = pool.requestFastWithdrawal(ethToken, amount, l2TxHash);

        assertEq(requestId, 1);
        assertEq(pool.getPoolBalance(ethToken), 90 ether); // 100 - 10
        assertEq(user.balance, userBalBefore + expectedPayout);

        IFastWithdrawalPoolV2.FastWithdrawalRequest memory req = pool.getRequest(requestId);
        assertEq(req.user, user);
        assertEq(req.token, ethToken);
        assertEq(req.amount, amount);
        assertEq(req.fee, expectedFee);
        assertEq(req.l2TxHash, l2TxHash);
        assertFalse(req.settled);
    }

    function test_requestFastWithdrawal_emitsEvent() public {
        vm.prank(lp1);
        pool.addLiquidity{value: 100 ether}(ethToken, 100 ether);

        bytes32 l2TxHash = keccak256("test-l2-tx-2");
        uint256 amount = 10 ether;
        uint256 expectedFee = (amount * 50) / 10_000;

        vm.prank(user);
        vm.expectEmit(true, true, false, true);
        emit IFastWithdrawalPoolV2.FastWithdrawalExecuted(1, user, ethToken, amount, expectedFee, l2TxHash);
        pool.requestFastWithdrawal(ethToken, amount, l2TxHash);
    }

    function test_requestFastWithdrawal_revertZeroAmount() public {
        vm.prank(lp1);
        pool.addLiquidity{value: 100 ether}(ethToken, 100 ether);

        vm.prank(user);
        vm.expectRevert("Amount must be > 0");
        pool.requestFastWithdrawal(ethToken, 0, keccak256("tx"));
    }

    function test_requestFastWithdrawal_revertExceedsMax() public {
        vm.prank(lp1);
        pool.addLiquidity{value: 600 ether}(ethToken, 600 ether);

        vm.prank(user);
        vm.expectRevert("Exceeds max single withdrawal");
        pool.requestFastWithdrawal(ethToken, 501 ether, keccak256("tx"));
    }

    function test_requestFastWithdrawal_revertInsufficientLiquidity() public {
        vm.prank(lp1);
        pool.addLiquidity{value: 5 ether}(ethToken, 5 ether);

        vm.prank(user);
        vm.expectRevert("Insufficient pool liquidity");
        pool.requestFastWithdrawal(ethToken, 10 ether, keccak256("tx"));
    }

    function test_requestFastWithdrawal_revertDuplicateL2TxHash() public {
        vm.prank(lp1);
        pool.addLiquidity{value: 100 ether}(ethToken, 100 ether);

        bytes32 l2TxHash = keccak256("same-tx");

        vm.prank(user);
        pool.requestFastWithdrawal(ethToken, 5 ether, l2TxHash);

        vm.prank(user);
        vm.expectRevert("L2 tx already claimed");
        pool.requestFastWithdrawal(ethToken, 5 ether, l2TxHash);
    }

    function test_requestFastWithdrawal_maxAmount() public {
        vm.prank(lp1);
        pool.addLiquidity{value: 500 ether}(ethToken, 500 ether);

        vm.prank(user);
        uint256 requestId = pool.requestFastWithdrawal(ethToken, 500 ether, keccak256("max-tx"));
        assertEq(requestId, 1);
        assertEq(pool.getPoolBalance(ethToken), 0);
    }

Step 2: Run tests to verify new tests fail

Run: cd /Users/judybaby/CodeBase/github/Layer2/contracts && forge test --match-contract FastWithdrawalPoolV2Test --match-test "test_requestFastWithdrawal" -v Expected: FAIL — "Not implemented yet"

Step 3: Implement requestFastWithdrawal

Replace the requestFastWithdrawal stub in FastWithdrawalPoolV2.sol:

    function requestFastWithdrawal(address token, uint256 amount, bytes32 l2TxHash)
        external
        override
        nonReentrant
        returns (uint256)
    {
        require(amount > 0, "Amount must be > 0");
        require(amount <= MAX_SINGLE_WITHDRAWAL, "Exceeds max single withdrawal");
        require(_poolBalances[token] >= amount, "Insufficient pool liquidity");
        require(_txHashToRequest[l2TxHash] == 0, "L2 tx already claimed");

        uint256 fee = (amount * FEE_BPS) / BPS_DENOMINATOR;
        uint256 payout = amount - fee;

        uint256 requestId = nextRequestId++;
        _requests[requestId] = FastWithdrawalRequest({
            user: msg.sender,
            token: token,
            amount: amount,
            fee: fee,
            l2TxHash: l2TxHash,
            requestId: requestId,
            timestamp: block.timestamp,
            settled: false
        });

        _txHashToRequest[l2TxHash] = requestId;
        _poolBalances[token] -= amount;

        if (token == address(0)) {
            (bool ok,) = msg.sender.call{value: payout}("");
            require(ok, "ETH transfer failed");
        }

        emit FastWithdrawalExecuted(requestId, msg.sender, token, amount, fee, l2TxHash);
        return requestId;
    }

Step 4: Run tests to verify they pass

Run: cd /Users/judybaby/CodeBase/github/Layer2/contracts && forge test --match-contract FastWithdrawalPoolV2Test -v Expected: All tests PASS (8 LP + 7 request = 15)

Step 5: Commit

git add contracts/src/bridge/FastWithdrawalPoolV2.sol contracts/test/FastWithdrawalPoolV2.t.sol
git commit -m "feat(bridge): implement requestFastWithdrawal with TDD"

---

Task 5: settleWithdrawal — Trustless Era Proof Settlement (TDD)

Files:

• Modify: contracts/test/FastWithdrawalPoolV2.t.sol — add settlement tests

• Modify: contracts/src/bridge/FastWithdrawalPoolV2.sol — implement function

Step 1: Add failing tests for settlement

Append to FastWithdrawalPoolV2Test:

    // === Settlement Tests ===

    // Helper: set up pool + create a fast withdrawal request, returns requestId
    function _setupFastWithdrawal(uint256 amount, bytes32 l2TxHash) internal returns (uint256) {
        vm.prank(lp1);
        pool.addLiquidity{value: 500 ether}(ethToken, 500 ether);

        vm.prank(user);
        return pool.requestFastWithdrawal(ethToken, amount, l2TxHash);
    }

    function test_settleWithdrawal_success() public {
        bytes32 l2TxHash = keccak256("settle-tx-1");
        uint256 amount = 10 ether;
        uint256 requestId = _setupFastWithdrawal(amount, l2TxHash);

        uint256 poolBefore = pool.getPoolBalance(ethToken);

        // Configure MockMailbox to accept all proofs
        mockMailbox.setDefaultResponse(true);

        address settler = address(0xSE77);
        bytes32[] memory proof = new bytes32[](0);
        bytes memory message = abi.encode(ethToken, amount, user);

        vm.prank(settler);
        pool.settleWithdrawal(requestId, 100, 0, 0, proof, message);

        IFastWithdrawalPoolV2.FastWithdrawalRequest memory req = pool.getRequest(requestId);
        assertTrue(req.settled);

        uint256 fee = (amount * 50) / 10_000;
        assertEq(pool.getPoolBalance(ethToken), poolBefore + (amount - fee));
        assertEq(pool.getLpFees(settler, ethToken), fee);
    }

    function test_settleWithdrawal_emitsEvent() public {
        bytes32 l2TxHash = keccak256("settle-tx-2");
        uint256 amount = 10 ether;
        uint256 requestId = _setupFastWithdrawal(amount, l2TxHash);

        mockMailbox.setDefaultResponse(true);

        address settler = address(0xSE77);
        bytes32[] memory proof = new bytes32[](0);
        bytes memory message = abi.encode(ethToken, amount, user);

        vm.prank(settler);
        vm.expectEmit(true, true, false, true);
        emit IFastWithdrawalPoolV2.WithdrawalSettled(requestId, settler, amount);
        pool.settleWithdrawal(requestId, 100, 0, 0, proof, message);
    }

    function test_settleWithdrawal_revertInvalidProof() public {
        bytes32 l2TxHash = keccak256("settle-tx-3");
        uint256 requestId = _setupFastWithdrawal(10 ether, l2TxHash);

        // MockMailbox returns false by default
        bytes32[] memory proof = new bytes32[](0);
        bytes memory message = abi.encode(ethToken, uint256(10 ether), user);

        vm.expectRevert("Invalid L2 message proof");
        pool.settleWithdrawal(requestId, 100, 0, 0, proof, message);
    }

    function test_settleWithdrawal_revertAlreadySettled() public {
        bytes32 l2TxHash = keccak256("settle-tx-4");
        uint256 requestId = _setupFastWithdrawal(10 ether, l2TxHash);

        mockMailbox.setDefaultResponse(true);
        bytes32[] memory proof = new bytes32[](0);
        bytes memory message = abi.encode(ethToken, uint256(10 ether), user);

        pool.settleWithdrawal(requestId, 100, 0, 0, proof, message);

        vm.expectRevert("Already settled");
        pool.settleWithdrawal(requestId, 100, 0, 0, proof, message);
    }

    function test_settleWithdrawal_revertInvalidRequest() public {
        mockMailbox.setDefaultResponse(true);
        bytes32[] memory proof = new bytes32[](0);
        bytes memory message = abi.encode(ethToken, uint256(10 ether), user);

        vm.expectRevert("Request does not exist");
        pool.settleWithdrawal(999, 100, 0, 0, proof, message);
    }

    function test_settleWithdrawal_settlerGetsFee() public {
        bytes32 l2TxHash = keccak256("settle-fee-tx");
        uint256 amount = 100 ether;
        uint256 requestId = _setupFastWithdrawal(amount, l2TxHash);

        mockMailbox.setDefaultResponse(true);

        address settler1 = address(0xAAAA);
        address settler2 = address(0xBBBB);
        bytes32[] memory proof = new bytes32[](0);
        bytes memory message = abi.encode(ethToken, amount, user);

        vm.prank(settler1);
        pool.settleWithdrawal(requestId, 100, 0, 0, proof, message);

        uint256 expectedFee = (amount * 50) / 10_000; // 0.5 ether
        assertEq(pool.getLpFees(settler1, ethToken), expectedFee);
        assertEq(pool.getLpFees(settler2, ethToken), 0);
    }

Step 2: Run tests to verify new tests fail

Run: cd /Users/judybaby/CodeBase/github/Layer2/contracts && forge test --match-contract FastWithdrawalPoolV2Test --match-test "test_settleWithdrawal" -v Expected: FAIL — "Not implemented yet"

Step 3: Implement settleWithdrawal

Replace the settleWithdrawal stub in FastWithdrawalPoolV2.sol:

    function settleWithdrawal(
        uint256 requestId,
        uint256 l2BatchNumber,
        uint256 l2MessageIndex,
        uint16 l2TxNumberInBatch,
        bytes32[] calldata merkleProof,
        bytes calldata message
    ) external override nonReentrant {
        FastWithdrawalRequest storage req = _requests[requestId];
        require(req.user != address(0), "Request does not exist");
        require(!req.settled, "Already settled");

        // Verify the L2→L1 message proof via era Mailbox
        bool valid = MAILBOX.proveL2MessageInclusion(
            l2BatchNumber,
            l2MessageIndex,
            IMailbox.L2Message({
                txNumberInBatch: l2TxNumberInBatch,
                sender: msg.sender, // flexible — era proof validates this
                data: message
            }),
            merkleProof
        );
        require(valid, "Invalid L2 message proof");

        req.settled = true;

        uint256 principal = req.amount - req.fee;
        _poolBalances[req.token] += principal;
        _lpFees[msg.sender][req.token] += req.fee;

        emit WithdrawalSettled(requestId, msg.sender, req.amount);
    }

Step 4: Run tests to verify they pass

Run: cd /Users/judybaby/CodeBase/github/Layer2/contracts && forge test --match-contract FastWithdrawalPoolV2Test -v Expected: All tests PASS (15 + 6 = 21)

Step 5: Commit

git add contracts/src/bridge/FastWithdrawalPoolV2.sol contracts/test/FastWithdrawalPoolV2.t.sol
git commit -m "feat(bridge): implement trustless settleWithdrawal with era proof verification"

---

Task 6: reclaimTimedOut (TDD)

Files:

• Modify: contracts/test/FastWithdrawalPoolV2.t.sol — add timeout tests

• Modify: contracts/src/bridge/FastWithdrawalPoolV2.sol — implement function

Step 1: Add failing tests for timeout

Append to FastWithdrawalPoolV2Test:

    // === Timeout Tests ===

    function test_reclaimTimedOut_success() public {
        bytes32 l2TxHash = keccak256("timeout-tx-1");
        uint256 amount = 10 ether;
        uint256 requestId = _setupFastWithdrawal(amount, l2TxHash);

        uint256 poolBefore = pool.getPoolBalance(ethToken);

        // Warp past timeout
        vm.warp(block.timestamp + 7 days + 1);

        pool.reclaimTimedOut(requestId);

        IFastWithdrawalPoolV2.FastWithdrawalRequest memory req = pool.getRequest(requestId);
        assertTrue(req.settled);
        assertEq(pool.getPoolBalance(ethToken), poolBefore + amount); // full amount returned
    }

    function test_reclaimTimedOut_emitsEvent() public {
        bytes32 l2TxHash = keccak256("timeout-tx-2");
        uint256 requestId = _setupFastWithdrawal(10 ether, l2TxHash);

        vm.warp(block.timestamp + 7 days + 1);

        vm.expectEmit(true, false, false, false);
        emit IFastWithdrawalPoolV2.WithdrawalTimedOut(requestId);
        pool.reclaimTimedOut(requestId);
    }

    function test_reclaimTimedOut_revertNotTimedOut() public {
        bytes32 l2TxHash = keccak256("timeout-tx-3");
        uint256 requestId = _setupFastWithdrawal(10 ether, l2TxHash);

        // Still within timeout window
        vm.warp(block.timestamp + 6 days);

        vm.expectRevert("Settlement not timed out");
        pool.reclaimTimedOut(requestId);
    }

    function test_reclaimTimedOut_revertAlreadySettled() public {
        bytes32 l2TxHash = keccak256("timeout-tx-4");
        uint256 requestId = _setupFastWithdrawal(10 ether, l2TxHash);

        // Settle first
        mockMailbox.setDefaultResponse(true);
        bytes32[] memory proof = new bytes32[](0);
        bytes memory message = abi.encode(ethToken, uint256(10 ether), user);
        pool.settleWithdrawal(requestId, 100, 0, 0, proof, message);

        // Try to reclaim
        vm.warp(block.timestamp + 7 days + 1);
        vm.expectRevert("Already settled");
        pool.reclaimTimedOut(requestId);
    }

    function test_reclaimTimedOut_exactBoundary() public {
        bytes32 l2TxHash = keccak256("timeout-tx-5");
        uint256 requestId = _setupFastWithdrawal(10 ether, l2TxHash);

        // Exactly at timeout — should still revert
        vm.warp(block.timestamp + 7 days);
        vm.expectRevert("Settlement not timed out");
        pool.reclaimTimedOut(requestId);

        // One second later — should succeed
        vm.warp(block.timestamp + 1);
        pool.reclaimTimedOut(requestId);
    }

Step 2: Run tests to verify new tests fail

Run: cd /Users/judybaby/CodeBase/github/Layer2/contracts && forge test --match-contract FastWithdrawalPoolV2Test --match-test "test_reclaimTimedOut" -v Expected: FAIL — "Not implemented yet"

Step 3: Implement reclaimTimedOut

Replace the reclaimTimedOut stub in FastWithdrawalPoolV2.sol:

    function reclaimTimedOut(uint256 requestId) external override nonReentrant {
        FastWithdrawalRequest storage req = _requests[requestId];
        require(req.user != address(0), "Request does not exist");
        require(!req.settled, "Already settled");
        require(block.timestamp > req.timestamp + SETTLEMENT_TIMEOUT, "Settlement not timed out");

        req.settled = true;
        _poolBalances[req.token] += req.amount;

        emit WithdrawalTimedOut(requestId);
    }

Step 4: Run all tests

Run: cd /Users/judybaby/CodeBase/github/Layer2/contracts && forge test --match-contract FastWithdrawalPoolV2Test -v Expected: All tests PASS (21 + 5 = 26)

Step 5: Commit

git add contracts/src/bridge/FastWithdrawalPoolV2.sol contracts/test/FastWithdrawalPoolV2.t.sol
git commit -m "feat(bridge): implement reclaimTimedOut with 7-day timeout"

---

Task 7: claimFees Tests + Full Integration Test

Files:

• Modify: contracts/test/FastWithdrawalPoolV2.t.sol — add fee claim + E2E tests

Step 1: Add fee claim and integration tests

Append to FastWithdrawalPoolV2Test:

    // === Fee Claim Tests ===

    function test_claimFees_success() public {
        bytes32 l2TxHash = keccak256("fee-tx-1");
        uint256 amount = 100 ether;
        uint256 requestId = _setupFastWithdrawal(amount, l2TxHash);

        mockMailbox.setDefaultResponse(true);
        address settler = address(0xFEE1);
        vm.deal(settler, 0);

        bytes32[] memory proof = new bytes32[](0);
        bytes memory message = abi.encode(ethToken, amount, user);

        vm.prank(settler);
        pool.settleWithdrawal(requestId, 100, 0, 0, proof, message);

        uint256 expectedFee = (amount * 50) / 10_000; // 0.5 ether
        assertEq(pool.getLpFees(settler, ethToken), expectedFee);

        vm.prank(settler);
        pool.claimFees(ethToken);

        assertEq(settler.balance, expectedFee);
        assertEq(pool.getLpFees(settler, ethToken), 0);
    }

    function test_claimFees_revertNoFees() public {
        vm.prank(lp1);
        vm.expectRevert("No fees to claim");
        pool.claimFees(ethToken);
    }

    // === E2E Integration Test ===

    function test_E2E_fullLifecycle() public {
        // 1. LP provides liquidity
        vm.prank(lp1);
        pool.addLiquidity{value: 200 ether}(ethToken, 200 ether);
        assertEq(pool.getPoolBalance(ethToken), 200 ether);

        // 2. User requests fast withdrawal
        bytes32 l2TxHash = keccak256("e2e-l2-tx");
        uint256 amount = 50 ether;
        uint256 fee = (amount * 50) / 10_000; // 0.25 ether
        uint256 payout = amount - fee;

        uint256 userBalBefore = user.balance;
        vm.prank(user);
        uint256 requestId = pool.requestFastWithdrawal(ethToken, amount, l2TxHash);

        // User receives instant payout
        assertEq(user.balance, userBalBefore + payout);
        assertEq(pool.getPoolBalance(ethToken), 150 ether); // 200 - 50

        // 3. Settler provides era proof and settles
        mockMailbox.setDefaultResponse(true);
        address settler = address(0xBOT1);
        bytes32[] memory proof = new bytes32[](0);
        bytes memory message = abi.encode(ethToken, amount, user);

        vm.prank(settler);
        pool.settleWithdrawal(requestId, 200, 0, 0, proof, message);

        // Pool gets principal back, settler gets fee
        assertEq(pool.getPoolBalance(ethToken), 150 ether + (amount - fee));
        assertEq(pool.getLpFees(settler, ethToken), fee);

        // 4. Settler claims fee
        vm.deal(settler, 0);
        vm.prank(settler);
        pool.claimFees(ethToken);
        assertEq(settler.balance, fee);

        // 5. LP removes liquidity
        vm.prank(lp1);
        pool.removeLiquidity(ethToken, 199.75 ether); // 200 - 0.25 fee kept in pool
        assertEq(pool.getLpBalance(lp1, ethToken), 0.25 ether);
    }

    function test_E2E_timeoutLifecycle() public {
        // 1. LP provides liquidity
        vm.prank(lp1);
        pool.addLiquidity{value: 100 ether}(ethToken, 100 ether);

        // 2. User requests fast withdrawal
        bytes32 l2TxHash = keccak256("e2e-timeout-tx");
        vm.prank(user);
        uint256 requestId = pool.requestFastWithdrawal(ethToken, 10 ether, l2TxHash);

        assertEq(pool.getPoolBalance(ethToken), 90 ether);

        // 3. No settlement happens — wait for timeout
        vm.warp(block.timestamp + 7 days + 1);
        pool.reclaimTimedOut(requestId);

        // Pool gets full amount back (including fee portion)
        assertEq(pool.getPoolBalance(ethToken), 100 ether);

        // 4. LP can remove full liquidity
        vm.prank(lp1);
        pool.removeLiquidity(ethToken, 100 ether);
        assertEq(pool.getPoolBalance(ethToken), 0);
    }

Step 2: Run full test suite

Run: cd /Users/judybaby/CodeBase/github/Layer2/contracts && forge test --match-contract FastWithdrawalPoolV2Test -v Expected: All tests PASS (26 + 4 = 30)

Step 3: Commit

git add contracts/test/FastWithdrawalPoolV2.t.sol
git commit -m "test(bridge): add fee claim + E2E lifecycle tests for FastWithdrawalPoolV2"

---

Task 8: Run Full Project Test Suite

Files: None (verification only)

Step 1: Run FastWithdrawalPoolV2 tests

Run: cd /Users/judybaby/CodeBase/github/Layer2/contracts && forge test --match-contract FastWithdrawalPoolV2Test -v Expected: 30 tests PASS

Step 2: Run entire project tests to verify no regressions

Run: cd /Users/judybaby/CodeBase/github/Layer2/contracts && forge test Expected: All tests pass (existing 83 v1 tests + 30 new v2 tests)

Step 3: Check gas report

Run: cd /Users/judybaby/CodeBase/github/Layer2/contracts && forge test --match-contract FastWithdrawalPoolV2Test --gas-report Expected: View gas costs for key functions (requestFastWithdrawal, settleWithdrawal should be < 100k gas)

Step 4: Final commit if any adjustments were made

git add -A
git commit -m "chore(bridge): Phase 3 FastWithdrawalPoolV2 complete — 30 tests passing"

---

Summary

Task	Description	Tests
1	Interfaces (IFastWithdrawalPoolV2 + IMailbox)	—
2	MockMailbox test helper	—
3	Contract skeleton + LP liquidity	8
4	requestFastWithdrawal	+7 = 15
5	settleWithdrawal (era proof)	+6 = 21
6	reclaimTimedOut	+5 = 26
7	claimFees + E2E tests	+4 = 30
8	Full suite verification	—

Total: 8 tasks, 30 tests, ~8 commits

Files created:

• contracts/src/interfaces/IFastWithdrawalPoolV2.sol

• contracts/src/interfaces/IMailbox.sol

• contracts/src/bridge/FastWithdrawalPoolV2.sol

• contracts/test/mocks/MockMailbox.sol

• contracts/test/FastWithdrawalPoolV2.t.sol

Files NOT modified: Zero era-contracts files. Zero existing BabyDriver files.