Withdrawals
Table of Contents
- Overview
- Withdrawal Flow
- The L2ToL1MessagePasser Contract
- The Optimism Portal Contract
- Withdrawal Verification and Finalization
- Security Considerations
Overview
Withdrawals are cross domain transactions which are initiated on L2, and finalized by a transaction executed on L1. Notably, withdrawals may be used by an L2 account to call an L1 contract, or to transfer ETH from an L2 account to an L1 account.
Vocabulary note: withdrawal can refer to the transaction at various stages of the process, but we introduce more specific terms to differentiate:
- 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 available on L1).
- A withdrawal finalizing transaction refers specifically to an L1 transaction which finalizes and relays the withdrawal.
Withdrawals are initiated on L2 via a call to the Message Passer predeploy contract, which records the important
properties of the message in its storage.
Withdrawals are proven on L1 via a call to the OptimismPortal
, which proves the inclusion of this withdrawal message.
Withdrawals are finalized on L1 via a call to the OptimismPortal
contract,
which verifies that the fault challenge period has passed since the withdrawal message has been proved.
In this way, withdrawals are different from deposits which make use of a special transaction type in the execution engine client. Rather, withdrawals transaction must use smart contracts on L1 for finalization.
Withdrawal Flow
We first describe the end to end flow of initiating and finalizing a withdrawal:
On L2
An L2 account sends a withdrawal message (and possibly also ETH) to the L2ToL1MessagePasser
predeploy contract.
This is a very simple contract that stores the hash of the withdrawal data.
On L1
- 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 a block number. The block number must be one for which an L2 output root exists, which commits to the withdrawal as registered on L2. - The
OptimismPortal
contract retrieves the output root for the given block number from theL2OutputOracle
'sgetL2Output()
function, and performs the remainder of the verification process internally. - If proof verification fails, the call reverts. Otherwise the hash is recorded to prevent it from being re-proven. Note that the withdrawal can be proven more than once if the corresponding output root changes.
- After the withdrawal is proven, it enters a 7 day challenge period, allowing time for other network participants to challenge the integrity of the corresponding output root.
- Once the challenge period 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. - The
OptimismPortal
contract receives the withdrawal transaction data and verifies that the withdrawal has both been proven and passed the challenge period. - 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
A withdrawal is initiated by calling the L2ToL1MessagePasser contract's initiateWithdrawal
function.
The L2ToL1MessagePasser is a simple predeploy contract at 0x4200000000000000000000000000000000000016
which stores messages to be withdrawn.
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);
}
The MessagePassed
event includes all of the data that is hashed and
stored in the sentMessages
mapping, as well as the hash itself.
Addresses are not Aliased on Withdrawals
When a contract makes a deposit, the sender's address is aliased. The same is not true of withdrawals, which do not modify the sender's address. The difference is that:
- 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 theOptimismPortal
contract.
Calling l2Sender()
removes any ambiguity about which domain the call originated from. Still, developers will need to
recognize that having the same address does not imply that a contract on L2 will behave the same as a contract on L1.
The Optimism Portal Contract
The Optimism Portal serves as both the entry and exit point to the Optimism L2. It is a contract which inherits from the OptimismPortal contract, and in addition provides the following interface for withdrawals:
interface OptimismPortal {
event WithdrawalFinalized(bytes32 indexed withdrawalHash, bool success);
function l2Sender() returns(address) external;
function proveWithdrawalTransaction(
Types.WithdrawalTransaction memory _tx,
uint256 _l2OutputIndex,
Types.OutputRootProof calldata _outputRootProof,
bytes[] calldata _withdrawalProof
) external;
function finalizeWithdrawalTransaction(
Types.WithdrawalTransaction memory _tx
) external;
}
Withdrawal Verification and Finalization
The following inputs are required to prove and finalize a withdrawal:
- 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:
l2OutputIndex
: The index in the L2 outputs where the applicable output root may be found.outputRootProof
: Fourbytes32
values which are used to derive the output root.withdrawalProof
: An inclusion proof for the given withdrawal in the L2ToL1MessagePasser contract.
These inputs must satisfy the following conditions:
- The
l2OutputIndex
must be the index in the L2 outputs that contains the applicable output root. L2OutputOracle.getL2Output(l2OutputIndex)
returns a non-zeroOutputProposal
.- The keccak256 hash of the
outputRootProof
values is equal to theoutputRoot
. - 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.
Security Considerations
Key Properties of Withdrawal Verification
-
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.
-
For each withdrawal initiated on L2 (i.e. with a unique
messageNonce()
), the following properties must hold:- It should only be possible to prove the withdrawal once, unless the outputRoot for the withdrawal has changed.
- It should only be possible to finalize the withdrawal once.
- It should not be possible to relay the message with any of its fields modified, ie.
- Modifying the
sender
field would enable a 'spoofing' attack. - Modifying the
target
,data
, orvalue
fields would enable an attacker to dangerously change the intended outcome of the withdrawal. - Modifying the
gasLimit
could make the cost of relaying too high, or allow the relayer to cause execution to fail (out of gas) in thetarget
.
- Modifying the
Handling Successfully Verified Messages That Fail When Relayed
If the execution of the relayed call fails in the target
contract, it is unfortunately not possible to determine
whether or not it was 'supposed' to fail, and whether or not it should be 'replayable'. For this reason, and to
minimize complexity, we have not provided any replay functionality, this may be implemented in external utility
contracts if desired.
OptimismPortal can send arbitrary messages on L1
The L2ToL1MessagePasser
contract's initiateWithdrawal
function accepts a _target
address and _data
bytes,
which is passed to a CALL
opcode on L1 when finalizeWithdrawalTransaction
is called after the challenge
period. This means that, by design, the OptimismPortal
contract can be used to send arbitrary transactions on
the L1, with the OptimismPortal
as the msg.sender
.
This means users of the OptimismPortal
contract should be careful what permissions they grant to the portal.
For example, any ERC20 tokens mistakenly sent to the OptimismPortal
contract are essentially lost, as they can
be claimed by anybody that pre-approves transfers of this token out of the portal, using the L2 to initiate the
approval and the L1 to prove and finalize the approval (after the challenge period).