ETH and ERC20 Token Bridge

Scroll Alpha Testnet is now deprecated.

Please visit our new documentation for the Scroll Sepolia Testnet at https://docs.scroll.io/

Deposit ETH and ERC20 tokens from Goerli

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 Goerli Testnet at 0xeF37207c1A1efF6D6a9d7BfF3cF4270e406d319b serving Scroll Alpha testnet. Notice that ERC20 tokens will have a different address on L2, you can use the getL2ERC20Address function to query the new address.

depositETH and depositERC20 are payable functions, the amount of ETH sent to these functions will be used to pay for L2 fees. If the amount is not enough, the transaction will not be sent. All excess ETH will be sent back to the sender. 0.00001 ETH should be more than enough to process a token deposit.

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 Scroll. On the very first token bridging, a new token will be created on Scroll 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. The address of L2CustomERC20Gateway is 0xa07Cb742657294C339fB4d5d6CdF3fdBeE8C1c68. Visit the Bridge 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.

Users can also bypass the L1ScrollMessenger and send messages directly to the L1MessageQueue. If a message is sent via the L1MessageQueue, the transaction's sender will be the address of the user sending the transaction, not the address of the L1ScrollMessenger. Learn more about sending arbitrary messages in the The Scroll Messenger documentation.

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 L2ScrollMessagner contract for execution on L2.

Withdraw ETH and ERC20 tokens from Scroll Alpha

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 Scroll Alpha at 0x6d79Aa2e4Fbf80CF8543Ad97e294861853fb0649. We use the getL1ERC20Address to retrieve the token address on L1.

withdrawETH and withdrawERC20 are payable functions, and the amount of ETH sent to these functions will be used to pay for L1 fees. If the amount is not enough, the transaction will not be sent. All excess ETH will be sent back to the sender. Fees will depend on Goerli activity but 0.005 ETH should be enough to process a token withdrawal.

Make sure the transactions won't revert on Goerli while sending from Scroll Alpha. There is no way to recover bridged ETH, tokens, or NFTs if your transaction reverts on Goerli. All assets are burnt on Scroll when the transaction is sent, and it's impossible to mint them again.

Creating an ERC20 token with custom logic on L2

If a token needs custom logic on Scroll Alpha, it will need to be bridged through a L1CustomERC20Gateway and L2CustomERC20Gateway respectively. The custom token on Scroll Alpha 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 Scroll Alpha.

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 Mint 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 Goerli and Scroll Alpha 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.

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. From 4000 to 10000 gas limit should be enough to process the transaction.

depositERC20

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

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. From 4000 to 10000 gas limit should be enough to process the transaction.

getL2ERC20Address

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

Returns the corresponding L2 token address given L1 token address.

Parameter	Description
_l1Token	The address of l1 token.

updateTokenMapping

function updateTokenMapping(
    address _l1Token,
    address _l2Token
) external;

Update the mapping that connects an ERC20 token from Goerli to Scroll Alpha.

Parameter	Description
_l1Token	The address of the ERC20 token in L1.
_l2Token	The address of corresponding ERC20 token in L2.

L2 Gateway API

withdrawETH

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

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

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

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

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

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

Parameter	Description
l2Token	The address of the L2 token.

updateTokenMapping

function updateTokenMapping(
    address _l1Token,
    address _l2Token
) external;

Update the mapping that connects an ERC20 contract from Scroll Alpha to Goerli.

Parameter	Description
_l2Token	The address of the ERC20 token in L2.
_l1Token	The address of corresponding ERC20 token in L1.