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: MIT2Kopiëren
Most of Optimism's code is released under the MIT license.
1pragma solidity >0.5.0 <0.9.0;2Kopiëren
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(10Toon alleKopiëren
In Optimism bridge terminology deposit means transfer from L1 to L2, and withdrawal means a transfer from L2 to L1.
1 address indexed _l1Token,2 address indexed _l2Token,3Kopiëren
In most cases the address of an ERC-20 on L1 is not the same the address of the equivalent ERC-20 on L2.
You can see the list of token addresses here.
The address with chainId
1 is on L1 (Mainnet) and the address with chainId
10 is on L2 (Optimism).
The other two chainId
values are for the Kovan test network (42) and the Optimistic Kovan test network (69).
1 address indexed _from,2 address _to,3 uint256 _amount,4 bytes _data5 );6Kopiëren
It is possible to add notes to transfers, in which case they are added to the events that report them.
1 event ERC20WithdrawalFinalized(2 address indexed _l1Token,3 address indexed _l2Token,4 address indexed _from,5 address _to,6 uint256 _amount,7 bytes _data8 );9Kopiëren
The same bridge contract handles transfers in both directions. In the case of the L1 bridge, this means initialization of deposits and finalization of withdrawals.
12 /********************3 * Public Functions *4 ********************/56 /**7 * @dev get the address of the corresponding L2 bridge contract.8 * @return Address of the corresponding L2 bridge contract.9 */10 function l2TokenBridge() external returns (address);11Toon alleKopiëren
This function is not really needed, because on L2 it is a predeployed contract, so it is always at address 0x4200000000000000000000000000000000000010
.
It is here for symmetry with the L2 bridge, because the address of the L1 bridge is not trivial to know.
1 /**2 * @dev deposit an amount of the ERC20 to the caller's balance on L2.3 * @param _l1Token Address of the L1 ERC20 we are depositing4 * @param _l2Token Address of the L1 respective L2 ERC205 * @param _amount Amount of the ERC20 to deposit6 * @param _l2Gas Gas limit required to complete the deposit on L2.7 * @param _data Optional data to forward to L2. This data is provided8 * solely as a convenience for external contracts. Aside from enforcing a maximum9 * length, these contracts provide no guarantees about its content.10 */11 function depositERC20(12 address _l1Token,13 address _l2Token,14 uint256 _amount,15 uint32 _l2Gas,16 bytes calldata _data17 ) external;18Toon alleKopiëren
The _l2Gas
parameter is the amount of L2 gas the transaction is allowed to spend.
Up to a certain (high) limit, this is free, so unless the ERC-20 contract does something really strange when minting, it should not be an issue.
This function takes care of the common scenario, where a user bridges assets to the same address on a different blockchain.
1 /**2 * @dev deposit an amount of ERC20 to a recipient's balance on L2.3 * @param _l1Token Address of the L1 ERC20 we are depositing4 * @param _l2Token Address of the L1 respective L2 ERC205 * @param _to L2 address to credit the withdrawal to.6 * @param _amount Amount of the ERC20 to deposit.7 * @param _l2Gas Gas limit required to complete the deposit on L2.8 * @param _data Optional data to forward to L2. This data is provided9 * solely as a convenience for external contracts. Aside from enforcing a maximum10 * length, these contracts provide no guarantees about its content.11 */12 function depositERC20To(13 address _l1Token,14 address _l2Token,15 address _to,16 uint256 _amount,17 uint32 _l2Gas,18 bytes calldata _data19 ) external;20Toon alleKopiëren
This function is almost identical to depositERC20
, but it lets you send the ERC-20 to a different address.
1 /*************************2 * Cross-chain Functions *3 *************************/45 /**6 * @dev Complete a withdrawal from L2 to L1, and credit funds to the recipient's balance of the7 * L1 ERC20 token.8 * This call will fail if the initialized withdrawal from L2 has not been finalized.9 *10 * @param _l1Token Address of L1 token to finalizeWithdrawal for.11 * @param _l2Token Address of L2 token where withdrawal was initiated.12 * @param _from L2 address initiating the transfer.13 * @param _to L1 address to credit the withdrawal to.14 * @param _amount Amount of the ERC20 to deposit.15 * @param _data Data provided by the sender on L2. This data is provided16 * solely as a convenience for external contracts. Aside from enforcing a maximum17 * length, these contracts provide no guarantees about its content.18 */19 function finalizeERC20Withdrawal(20 address _l1Token,21 address _l2Token,22 address _from,23 address _to,24 uint256 _amount,25 bytes calldata _data26 ) external;27}28Toon alleKopiëren
Withdrawals (and other messages from L2 to L1) in Optimism are a two step process:
- An initiating transaction on L2.
- A finalizing or claiming transaction on L1. This transaction needs to happen after the fault challenge period for the L2 transaction ends.
IL1StandardBridge
This interface is defined here.
This file contains event and function definitions for ETH.
These definitions are very similar to those defined in IL1ERC20Bridge
above for ERC-20.
The bridge interface is divided between two files because some ERC-20 tokens require custom processing and cannot be handled by the standard bridge.
This way the custom bridge that handles such a token can implement IL1ERC20Bridge
and not have to also bridge ETH.
1// SPDX-License-Identifier: MIT2pragma solidity >0.5.0 <0.9.0;34import "./IL1ERC20Bridge.sol";56/**7 * @title IL1StandardBridge8 */9interface IL1StandardBridge is IL1ERC20Bridge {10 /**********11 * Events *12 **********/13 event ETHDepositInitiated(14 address indexed _from,15 address indexed _to,16 uint256 _amount,17 bytes _data18 );19Toon alle