Optimism standard bridge contract walkthrough
Optimism is an Optimistic Rollup. Optimistic rollups can process transactions for a much lower price than Ethereum Mainnet (also known as layer 1 or L1) because transactions are only processed by a few nodes, instead of every node on the network. At the same time, the data is all written to L1 so everything can be proved and reconstructed with all the integrity and availability guarantees of Mainnet.
To use L1 assets on Optimism (or any other L2), the assets need to be bridged. One way to achieve this is for users to lock assets (ETH and ERC-20 tokens are the most common ones) on L1, and receive equivalent assets to use on L2. Eventually, whoever ends up with them might want to bridge them back to L1. When doing this, the assets are burned on L2 and then released back to the user on L1.
This is the way the Optimism standard bridge works. In this article we go over the source code for that bridge to see how it works and study it as an example of well written Solidity code.
Control flows
The bridge has two main flows:
- Deposit (from L1 to L2)
- Withdrawal (from L2 to L1)
Deposit flow
Layer 1
- If depositing an ERC-20, the depositor gives the bridge an allowance to spend the amount being deposited
- The depositor calls the L1 bridge (
depositERC20
,depositERC20To
,depositETH
, ordepositETHTo
) - The L1 bridge takes possession of the bridged asset
- ETH: The asset is transferred by the depositor as part of the call
- ERC-20: The asset is transferred by the bridge to itself using the allowance provided by the depositor
- The L1 bridge uses the cross-domain message mechanism to call
finalizeDeposit
on the L2 bridge
Layer 2
- The L2 bridge verifies the call to
finalizeDeposit
is legitimate:- Came from the cross domain message contract
- Was originally from the bridge on L1
- The L2 bridge checks if the ERC-20 token contract on L2 is the correct one:
- The L2 contract reports that its L1 counterpart is the same as the one the tokens came from on L1
- The L2 contract reports that it supports the correct interface (using ERC-165).
- If the L2 contract is the correct one, call it to mint the appropriate number of tokens to the appropriate address. If not, start a withdrawal process to allow the user to claim the tokens on L1.
Withdrawal flow
Layer 2
- The withdrawer calls the L2 bridge (
withdraw
orwithdrawTo
) - The L2 bridge burns the appropriate number of tokens belonging to
msg.sender
- The L2 bridge uses the cross-domain message mechanism to call
finalizeETHWithdrawal
orfinalizeERC20Withdrawal
on the L1 bridge
Layer 1
- The L1 bridge verifies the call to
finalizeETHWithdrawal
orfinalizeERC20Withdrawal
is legitimate:- Came from the cross domain message mechanism
- Was originally from the bridge on L2
- The L1 bridge transfers the appropriate asset (ETH or ERC-20) to the appropriate address
Layer 1 code
This is the code that runs on L1, the Ethereum Mainnet.
IL1ERC20Bridge
This interface is defined here. It includes functions and definitions required for bridging ERC-20 tokens.
1// SPDX-License-Identifier: MIT2Copy
Most of Optimism's code is released under the MIT license.
1pragma solidity >0.5.0 <0.9.0;2Copy
At writing the latest version of Solidity is 0.8.12. Until version 0.9.0 is released, we don't know if this code is compatible with it or not.
1/**2 * @title IL1ERC20Bridge3 */4interface IL1ERC20Bridge {5 /**********6 * Events *7 **********/89 event ERC20DepositInitiated(10Show all