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 the depositERC20 function on the L1GatewayRouter.
• L1CustomERC20Gateway: This Gateway will be selected by the L1GatewayRouter 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 implement IScrollStandardERC20. Additionally, the token should grant mint or burn capability to the L2CustomERC20Gateway. 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.

interface IScrollStandardERC20 {
  /// @notice Return the address of Gateway the token belongs to.
  function gateway() external view returns (address);

  /// @notice Return the address of counterpart token.
  function counterpart() external view returns (address);

  /// @dev ERC677 Standard, see https://github.com/ethereum/EIPs/issues/677
  /// Defi can use this method to transfer L1/L2 token to L2/L1,
  /// and deposit to L2/L1 contract in one transaction
  function transferAndCall(address receiver, uint256 amount, bytes calldata data) external returns (bool success);

  /// @notice Mint some token to recipient's account.
  /// @dev Gateway Utilities, only gateway contract can call
  /// @param _to The address of recipient.
  /// @param _amount The amount of token to mint.
  function mint(address _to, uint256 _amount) external;

  /// @notice Burn some token from account.
  /// @dev Gateway Utilities, only gateway contract can call
  /// @param _from The address of account to burn token.
  /// @param _amount The amount of token to mint.
  function burn(address _from, uint256 _amount) external;
}

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

function depositETH(address _to, uint256 _amount, uint256 _gasLimit) public payable;

Sends ETH from L1 to L2.

depositERC20

function depositERC20(address _token, address _to, uint256 _amount, uint256 _gasLimit) payable;

Sends ERC20 tokens from L1 to L2.

getL2ERC20Address

function getL2ERC20Address(address _l1Token) external view returns (address);

Returns the corresponding L2 token address given L1 token address.

updateTokenMapping

function updateTokenMapping(address _l1Token, address _l2Token) external;

Update the mapping that connects an ERC20 token from L1 to L2.

L2 Gateway API

withdrawETH

function withdrawETH(address to, uint256 amount, uint256 gasLimit) external payable;

Sends ETH from L2 to L1.

withdrawERC20

function withdrawERC20(address token, address to, uint256 amount, uint256 gasLimit) external payable;

Sends ERC20 tokens from L2 to L1.

getL1ERC20Address

function getL1ERC20Address(address l2Token) external view returns (address);

Returns the corresponding L1 token address given an L2 token address.

updateTokenMapping

function updateTokenMapping(address _l1Token, address _l2Token) external;

Update the mapping that connects an ERC20 contract from L2 to L1.