ETH and ERC20 Token Bridge
Deposit ETH and ERC20 tokens from L1
The Gateway Router allows ETH and ERC20 token bridging from L1 to L2 using the depositETH
and depositERC20
functions respectively. It is a permissionless bridge deployed on L1. Notice that ERC20 tokens will have a different address on L2, you can use the getL2ERC20Address
function to query the new address.
When bridging ERC20 tokens, you don’t have to worry about selecting the right Gateway. This is because the L1GatewayRouter
will choose the correct underlying entry point to send the message:
L1StandardERC20Gateway
: This Gateway permits any ERC20 deposit and will be selected as the default by the L1GatewayRouter for an ERC20 token that doesn’t need custom logic on L2. On the very first token bridging, a new token will be created on L2 that implements the ScrollStandardERC20. To bridge a token, call thedepositERC20
function on theL1GatewayRouter
.L1CustomERC20Gateway
: This Gateway will be selected by theL1GatewayRouter
for tokens with custom logic. For an L1/L2 token pair to work on the Scroll Custom ERC20 Bridge, the L2 token contract has to implementIScrollStandardERC20
. Additionally, the token should grantmint
orburn
capability to theL2CustomERC20Gateway
. Visit the Bridge an ERC20 through the Custom Gateway guide for a step-by-step example of how to bridge a custom token.
All Gateway contracts will form the message and send it to the L1ScrollMessenger
which can send arbitrary messages to L2. The L1ScrollMessenger
passes the message to the L1MessageQueue
. Any user can send messages directly to the Messenger to execute arbitrary data on L2. This means they can execute any function on L2 from a transaction made on L1 via the bridge. Although an application could directly pass messages to existing token contracts, the Gateway abstracts the specifics and simplifies making transfers and calls.
When a new block gets created on L1, the Watcher will detect the message on the L1MessageQueue
and will pass it to the Relayer service, which will submit the transaction to the L2 via the l2geth node. Finally, the l2geth node will pass the transaction to the L2ScrollMessenger
contract for execution on L2.
Withdraw ETH and ERC20 tokens from L2
The L2 Gateway is very similar to the L1 Gateway. We can withdraw ETH and ERC20 tokens back to L1 using the withdrawETH
and withdrawERC20
functions. The contract address is deployed on L2. We use the getL1ERC20Address
to retrieve the token address on L1.
Creating an ERC20 token with custom logic on L2
If a token needs custom logic on L2, it will need to be bridged through an L1CustomERC20Gateway
and L2CustomERC20Gateway
respectively. The custom token on L2 will need to give permission to the Gateway to mint new tokens when a deposit occurs and to burn when tokens are withdrawn
The following interface is the IScrollStandardERC20
needed for deploying tokens compatible with the L2CustomERC20Gateway
on L2.
Adding a Custom L2 ERC20 token to the Scroll Bridge
Tokens can be bridged securely and permissionlessly through Gateway contracts deployed by any developer. However, Scroll also manages an ERC20 Router and a Gateway where all tokens created by the community are welcome. Being part of the Scroll-managed Gateway means you won’t need to deploy the Gateway contracts, and your token will appear in the Scroll frontend. To be part of the Scroll Gateway, you must contact the Scroll team to add the token to both L1 and L2 bridge contracts. To do so, follow the instructions on the token lists repository to add your new token to the official Scroll frontend.
L1 Gateway API
Please visit the npm library for the complete Scroll contract API documentation.
depositETH
Sends ETH from L1 to L2.
Parameter | Description |
---|---|
to | The address of recipient’s account on L2. |
amount | The amount of token to transfer, in wei. |
gasLimit | Gas limit required to complete the deposit on L2. 170000 should be enough to process the transaction, but unused funds are refunded. |
depositERC20
Sends ERC20 tokens from L1 to L2.
Parameter | Description |
---|---|
token | The token address on L1. |
to | The address of recipient’s account on L2. |
amount | The amount of token to transfer, in wei. |
gasLimit | Gas limit required to complete the deposit on L2. 200000 should be enough to process the transaction, depending on the Gateway, but unused funds are refunded. |
getL2ERC20Address
Returns the corresponding L2 token address given L1 token address.
Parameter | Description |
---|---|
_l1Token | The address of l1 token. |
updateTokenMapping
Update the mapping that connects an ERC20 token from L1 to L2.
Parameter | Description |
---|---|
_l1Token | The address of the ERC20 token in L1. |
_l2Token | The address of corresponding ERC20 token in L2. |
L2 Gateway API
withdrawETH
Sends ETH from L2 to L1.
Parameter | Description |
---|---|
to | The address of recipient’s account on L1. |
amount | The amount of token to transfer, in wei. |
gasLimit | Gas limit required to complete the deposit on L1. This is optional, send 0 if you don’t want to set it. |
withdrawERC20
Sends ERC20 tokens from L2 to L1.
Parameter | Description |
---|---|
token | The token address on L2. |
to | The address of recipient’s account on L1. |
amount | The amount of token to transfer, in wei. |
gasLimit | Gas limit required to complete the deposit on L1. This is optional, send 0 if you don’t want to set it. |
getL1ERC20Address
Returns the corresponding L1 token address given an L2 token address.
Parameter | Description |
---|---|
l2Token | The address of the L2 token. |
updateTokenMapping
Update the mapping that connects an ERC20 contract from L2 to L1.
Parameter | Description |
---|---|
_l2Token | The address of the ERC20 token in L2. |
_l1Token | The address of corresponding ERC20 token in L1. |