Withdrawals

1. Initiate on Base: the withdrawal transaction is sent on Base. This records the withdrawal message in the L2ToL1MessagePasser contract.
2. Prove on Ethereum: after the relevant Base state has been posted to Ethereum, anyone can submit a proof to the OptimismPortal contract showing that the withdrawal message exists on Base.
3. Finalize on Ethereum: after the finalization window has passed, anyone can finalize the withdrawal on Ethereum. Finalization releases the assets or relays the message to the target contract.

​

Overview

• A withdrawal initiating transaction refers specifically to a transaction on L2 sent to the Withdrawals predeploy.
• A withdrawal proving transaction refers specifically to an L1 transaction which proves the withdrawal is correct (that it has been included in a merkle tree whose root is committed to by a dispute game on L1).
• A withdrawal finalizing transaction refers specifically to an L1 transaction which finalizes and relays the withdrawal.

​

Withdrawal Flow

​

On L2

​

On L1

1. A relayer submits a withdrawal proving transaction with the required inputs to the OptimismPortal contract. The relayer is not necessarily the same entity which initiated the withdrawal on L2. These inputs include the withdrawal transaction data, inclusion proofs, and the index of a dispute game in the DisputeGameFactory. The game’s root claim is an L2 output root that commits to the withdrawal as registered on L2. On Base, these games are AggregateVerifier games.
2. The OptimismPortal contract looks up the game in the DisputeGameFactory and checks through the AnchorStateRegistry that the game is proper and of the respected game type, and that it has not resolved in favor of a challenger. It then verifies the output root proof against the game’s root claim and the withdrawal’s inclusion in the L2ToL1MessagePasser storage root.
3. If proof verification fails, the call reverts. Otherwise the game and the proof timestamp are recorded for the proof submitter. A withdrawal can be re-proven, for example against a different game if the first one is invalidated; re-proving resets that submitter’s proof timestamp.
4. The dispute game runs its finalization window: 5 days for a single-proof game, or 1 day when both TEE and ZK proofs back the proposal (see Beryl). During this window, a challenger can dispute an invalid root claim.
5. Once the game’s claim is valid and the proof maturity delay has passed, a relayer submits a withdrawal finalizing transaction to the OptimismPortal contract. The relayer doesn’t need to be the same entity that initiated the withdrawal on L2.
6. The OptimismPortal contract receives the withdrawal transaction data and verifies that the withdrawal has been proven, that at least proofMaturityDelaySeconds have passed since it was proven, and that AnchorStateRegistry.isGameClaimValid() returns true for the game it was proven against.
7. If the requirements are not met, the call reverts. Otherwise the call is forwarded, and the hash is recorded to prevent it from being replayed.

​

The L2ToL1MessagePasser Contract

interface L2ToL1MessagePasser {
    event MessagePassed(
        uint256 indexed nonce, // this is a global nonce value for all withdrawal messages
        address indexed sender,
        address indexed target,
        uint256 value,
        uint256 gasLimit,
        bytes data,
        bytes32 withdrawalHash
    );

    event WithdrawerBalanceBurnt(uint256 indexed amount);

    function burn() external;

    function initiateWithdrawal(address _target, uint256 _gasLimit, bytes memory _data) payable external;

    function messageNonce() public view returns (uint256);

    function sentMessages(bytes32) view external returns (bool);
}

​

Addresses Are Not Aliased on Withdrawals

• on L2, the deposit sender’s address is returned by the CALLER opcode, meaning a contract cannot easily tell if the call originated on L1 or L2, whereas
• on L1, the withdrawal sender’s address is accessed by calling the l2Sender() function on the OptimismPortal contract.

​

The Optimism Portal Contract

• WithdrawalTransaction type
• OutputRootProof type

interface OptimismPortal2 {

    event WithdrawalProven(bytes32 indexed withdrawalHash, address indexed from, address indexed to);

    event WithdrawalProvenExtension1(bytes32 indexed withdrawalHash, address indexed proofSubmitter);

    event WithdrawalFinalized(bytes32 indexed withdrawalHash, bool success);

    function l2Sender() external view returns (address);

    function proofMaturityDelaySeconds() external view returns (uint256);

    function proveWithdrawalTransaction(
        Types.WithdrawalTransaction memory _tx,
        uint256 _disputeGameIndex,
        Types.OutputRootProof calldata _outputRootProof,
        bytes[] calldata _withdrawalProof
    ) external;

    function finalizeWithdrawalTransaction(
        Types.WithdrawalTransaction memory _tx
    ) external;

    function finalizeWithdrawalTransactionExternalProof(
        Types.WithdrawalTransaction memory _tx,
        address _proofSubmitter
    ) external;

    function checkWithdrawal(bytes32 _withdrawalHash, address _proofSubmitter) external view;
}

​

Withdrawal Verification and Finalization

• Withdrawal transaction data:
  • nonce: Nonce for the provided message.
  • sender: Message sender address on L2.
  • target: Target address on L1.
  • value: ETH to send to the target.
  • data: Data to send to the target.
  • gasLimit: Gas to be forwarded to the target.
• Proof and verification data:
  • disputeGameIndex: The index in the DisputeGameFactory of the dispute game whose root claim is the applicable output root.
  • outputRootProof: Four bytes32 values which are used to derive the output root.
  • withdrawalProof: An inclusion proof for the given withdrawal in the L2ToL1MessagePasser contract.

1. The game at disputeGameIndex is proper and respected according to the AnchorStateRegistry, and has not resolved with CHALLENGER_WINS.
2. The keccak256 hash of the outputRootProof values is equal to the game’s root claim.
3. The withdrawalProof is a valid inclusion proof demonstrating that a hash of the Withdrawal transaction data is contained in the storage of the L2ToL1MessagePasser contract on L2.

1. The withdrawal has been proven by the proof submitter and has not already been finalized.
2. More than proofMaturityDelaySeconds have passed since the withdrawal was proven.
3. AnchorStateRegistry.isGameClaimValid() returns true for the game the withdrawal was proven against. This requires the game to have resolved with DEFENDER_WINS after its finalization window.

​

Security Considerations

​

Key Properties of Withdrawal Verification

1. It should not be possible to ‘double spend’ a withdrawal, ie. to relay a withdrawal on L1 which does not correspond to a message initiated on L2. For reference, see this writeup of a vulnerability of this type found on Polygon.
2. For each withdrawal initiated on L2 (i.e. with a unique messageNonce()), the following properties must hold:
   1. It should only be possible to prove the withdrawal once, unless the outputRoot for the withdrawal has changed.
   2. It should only be possible to finalize the withdrawal once.
   3. It should not be possible to relay the message with any of its fields modified, ie.
      1. Modifying the sender field would enable a ‘spoofing’ attack.
      2. Modifying the target, data, or value fields would enable an attacker to dangerously change the intended outcome of the withdrawal.
      3. Modifying the gasLimit could make the cost of relaying too high, or allow the relayer to cause execution to fail (out of gas) in the target.

​

Handling Successfully Verified Messages That Fail When Relayed

​

OptimismPortal Can Send Arbitrary Messages on L1