Withdraw Gateway

Withdraw Gateways

This document outlines how users and developers can utilize various gateways to withdraw tokens from Layer 2 (L2) to Layer 1 (L1) in the Wischain ecosystem. We provide multiple gateways for standard tokens along with a gateway router on L2, as detailed in the table below.

Gateway Contract	Description
L2GatewayRouter	Facilitates the withdrawal of ETH and ERC20 tokens.
L2ETHGateway	Dedicated gateway for ETH withdrawals.
L2StandardERC20Gateway	Gateway for standard ERC20 token withdrawals.
L2CustomERC20Gateway	Gateway for custom ERC20 token withdrawals.
L2WETHGateway	Gateway for Wrapped ETH withdrawals.
L2ERC721Gateway	Gateway for ERC-721 token withdrawals.
L2ERC1155Gateway	Gateway for ERC-1155 token withdrawals.

Overview

Withdrawal Workflow

The withdrawal process from L2 to L1 is initiated when users interact with the gateways to start a token withdrawal. The request is encoded into a message sent to the L2 Wischain Messenger, which is then added to the L2 Message Queue. The L2 Message Queue maintains a Withdraw Trie, updating its root whenever a new message is appended. Once the new Withdraw Trie root is finalized on the L1 rollup contract, users or third parties can construct a valid Merkle Inclusion Proof for the Withdraw Trie root and execute a withdrawal transaction on L1 to complete the process. For further information about the L2-to-L1 message relay workflow, please refer to the Cross-Domain Messaging documentation.

Withdrawing ETH

The process for withdrawing ETH operates as follows:

The L2GatewayRouter offers three functions for ETH withdrawals:

function withdrawETH(uint256 _amount, uint256 _gasLimit) external payable;

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

function withdrawETHAndCall(
    address _to,
    uint256 _amount,
    bytes calldata _data,
    uint256 _gasLimit
) external payable;

The withdrawETHAndCall function interacts with the L2ETHGateway, which encodes the withdrawal message and sends it to the L2 Wischain Messenger contract along with the withdrawn ETH.

The withdrawn ETH is locked within the L2 Wischain Messenger contract, which appends the message to the message queue in the L2 Message Queue contract.

To finalize the withdrawal on L1, the execution transaction invokes the L1WischainMessenger.relayMessageWithProof function. For ETH withdrawals, this function subsequently calls L1ETHGateway.finalizeWithdrawETH to transfer ETH back to the recipient account on L1.

If a user employs the withdrawETHAndCall on L2, the finalizeWithdrawETH in the L1 ETH Gateway will forward any additional data to the target L1 contract.

Withdrawing ERC20 Tokens

The withdrawal of ERC20 tokens is carried out as follows:

To withdraw ERC20 tokens from L2 to L1, users can utilize the following functions from L2GatewayRouter:

function withdrawERC20(address _token, uint256 _amount, uint256 _gasLimit) external payable;

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

function withdrawERC20AndCall(
    address _token,
    address _to,
    uint256 _amount,
    bytes memory _data,
    uint256 _gasLimit
) public payable;

Based on a mapping of ERC20 tokens to their respective gateways, the L2GatewayRouter calls the appropriate gateway, whether it be the L2StandardERC20Gateway, L2CustomERC20Gateway, or L2WETHGateway.

Standard and Custom ERC20 Tokens

The withdrawal process for both standard and custom ERC20 tokens follows these steps:

1. The L2StandardERC20Gateway or L2CustomERC20Gateway contract burns the withdrawn ERC20 tokens, encodes the withdrawal request, and sends it to the L2 Wischain Messenger.

2. The L1 withdrawal transaction then calls the L1WischainMessenger.relayMessageWithProof function to complete the withdrawal on L1. If the withdrawal involves a standard or custom ERC20 token, the corresponding transaction calls the finalizeWithdrawERC20 function on the L1StandardERC20Gateway or L1CustomERC20Gateway contract.

3. For the L1StandardERC20Gateway, if it is the first withdrawal transaction for that specific ERC20 token, the finalizeWithdrawERC20 function updates the mapping from the L1 token address to its corresponding L2 token address.

4. Finally, the L1 ERC20 token gateway releases the locked ERC20 tokens by transferring them to the recipient's address on L1. If the user invokes withdrawERC20AndCall on L2, the gateway will call the target L1 contract with any additional data.

Withdrawing Wrapped ETH (WETH)

For Wrapped ETH (WETH) token withdrawals, the L2WETHGateway facilitates the process:

1. The L2WETHGateway transfers the withdrawn WETH tokens to itself and unwraps them into native ETH tokens, which are then sent back to the L2 Wischain Messenger contract.

2. The gateway encodes the withdrawal message and forwards it to the L2 Wischain Messenger.

3. The L1 withdrawal execution transaction calls the L1WischainMessenger.relayMessageWithProof function to finalize the withdrawal. In the case of WETH, this triggers the L1WETHGateway.finalizeWithdrawERC20 function, which sends the equivalent amount in ETH to the L1WETHGateway.

4. The L1WETHGateway re-wraps the withdrawn ETH back into WETH and transfers it to the recipient address on L1. If withdrawERC20AndCall is invoked, the L1WETHGateway will call the target L1 address with additional data.

Withdrawing ERC-721 and ERC-1155 Tokens

The withdrawal process for ERC-721 and ERC-1155 tokens closely resembles that of ERC20 tokens. Users can utilize the L2ERC721Gateway or L2ERC1155Gateway for their withdrawals, with functions defined as follows:

function withdrawERC721(
    address _token,
    uint256 _tokenId,
    uint256 _gasLimit
) external payable;

function withdrawERC721(
    address _token,
    address _to,
    uint256 _tokenId,
    uint256 _gasLimit
) external payable;

function withdrawERC1155(
    address _token,
    uint256 _tokenId,
    uint256 _amount,
    uint256 _gasLimit
) external payable;

function withdrawERC1155(
    address _token,
    address _to,
    uint256 _tokenId,
    uint256 _amount,
    uint256 _gasLimit
) external payable;

To facilitate multiple withdrawals of ERC-721 or ERC-1155 tokens, batch withdrawal functions are provided in the respective gateways:

function batchWithdrawERC721(
    address _token,
    uint256[] calldata _tokenIds,
    uint256 _gasLimit
) external payable;

function batchWithdrawERC721(
    address _token,
    address _to,
    uint256[] calldata _tokenIds,
    uint256 _gasLimit
) external payable;

function batchWithdrawERC1155(
    address _token,
    uint256[] calldata _tokenIds,
    uint256[] calldata _amounts,
    uint256 _gasLimit
) external payable;

function batchWithdrawERC1155(
    address _token,
    address _to,
    uint256[] calldata _tokenIds,
    uint256[] calldata _amounts,
    uint256 _gasLimit
) external payable;

The L1 counterparts for ERC-721 and ERC-1155 withdrawals are handled by the L1ERC721Gateway and L1ERC1155Gateway contracts, which finalize the withdrawal transactions on L1.