Deposite Gateway

Deposit Gateways in Wischain

This document outlines how users and developers can utilize various gateways to deposit tokens from Layer 1 (L1) to Layer 2 (L2) in the Wischain ecosystem. A range of gateways is available for standard tokens, along with a gateway router on L1, as detailed in the table below.

Gateway Contract	Description
L1GatewayRouter	Supports deposits of ETH and ERC20 tokens.
L1ETHGateway	Gateway for depositing ETH.
L1StandardERC20Gateway	Gateway for standard ERC20 token deposits.
L1CustomERC20Gateway	Gateway for custom ERC20 token deposits.
L1WETHGateway	Gateway for Wrapped ETH deposits.
L1ERC721Gateway	Gateway for ERC-721 token deposits.
L1ERC1155Gateway	Gateway for ERC-1155 token deposits.

Overview

Deposit Workflow

The deposit process from L1 to L2 involves several steps. Users initiate a token deposit by calling one of the gateways. This deposit is encoded into a message that is sent to the L1 Wischain Messenger contract, with a corresponding transaction added to the L1 Message Queue. To complete the deposit on L2, the L2 sequencer collects events from the new L1 transactions and incorporates them into the L2 blocks it generates. Further details about the L1-to-L2 message relay workflow can be found in the Cross-Domain Messaging documentation.

Depositing ETH

In Wischain, ETH is treated as the native token. A sufficient amount of ETH is pre-allocated to the L2 Wischain Messenger contract at the genesis block, allowing it to transfer native ETH tokens to L2 accounts without needing to mint new tokens. The deposit process for ETH is as follows:

The L1GatewayRouter offers three functions to facilitate ETH deposits from L1 to L2:

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

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

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

All three depositETH functions interact with the L1ETHGateway, which encodes the deposit into a message sent to the L1 Wischain Messenger contract. The deposited ETH amount is then locked in the L1 Wischain Messenger contract, which appends the message to the L1 Message Queue.

Once the deposit transaction is confirmed on L1, the sequencer will include a corresponding transaction in the L2 block, completing the deposit and transferring ETH to the designated L2 recipient. This L2 transaction invokes the relayMessage function in the L2 Wischain Messenger, which processes the relayed message. For ETH deposits, the relayMessage function calls finalizeDepositETH in the L2 ETH Gateway to transfer ETH to the recipient's L2 account. If depositETHAndCall is used on L1, the finalizeDepositETH function will also relay additional data to the target L2 contract.

Depositing ERC20 Tokens

Wischain provides several ERC20 gateway contracts to facilitate the transfer of various ERC20 tokens, including standard and custom tokens, as well as Wrapped ETH. The L1GatewayRouter maintains a canonical mapping of ERC20 tokens to their respective gateway contracts and uses the StandardERC20Gateway as the default for new ERC20 tokens unless a custom gateway is already established.

The ERC20 deposit process works as follows:

Users can deposit ERC20 tokens from L1 to L2 by utilizing the following functions in the L1GatewayRouter:

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

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

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

Depending on the mapping from ERC20 tokens to their gateways, the L1GatewayRouter calls the appropriate gateway: L1StandardERC20Gateway, L1CustomERC20Gateway, or L1WETHGateway. The detailed steps for standard and custom ERC20 token deposits are described below.

Standard ERC20 Tokens

Standard ERC20 tokens do not require custom logic. The corresponding L2 ERC20 token contracts are created by the L2StandardERC20Gateway. The deposit process is as follows:

1. The L1StandardERC20Gateway locks the ERC20 tokens by transferring them from the sender to itself.

2. If the token has not previously been withdrawn through the L1StandardERC20Gateway, it computes a deterministic L2 ERC20 token address and appends token metadata (symbol, name, and decimals) to the message for potential contract deployment on L2. If the L2 token address is already recorded in the token mapping, it directly retrieves the address.

3. The L1StandardERC20Gateway encodes the token deposit message and calls the L1 Wischain Messenger to send it.

4. The corresponding L2 transaction invokes the L2 Wischain Messenger's relayMessage function to finalize the deposit on L2. In the case of standard ERC20 token deposits, this transaction then calls finalizeDepositERC20 in the L2StandardERC20Gateway.

5. If the ERC20 token contract has not yet been deployed on L2, the L2StandardERC20Gateway extracts metadata from the message and calls the WischainStandardERC20Factory to deploy the token on L2.

6. The L2StandardERC20Gateway calls the mint function on the appropriate L2 ERC20 token contract. If the user utilized depositERC20AndCall on L1, the L2StandardERC20Gateway will forward the additional data to the target L2 contract.

Custom ERC20 Tokens

Unlike standard tokens, custom ERC20 tokens require the token owner to deploy their L2 contracts. The deposit process for custom ERC20 tokens involves the following steps:

1. The L1CustomERC20Gateway locks the ERC20 tokens by transferring them from the sender to itself.

2. The L1CustomERC20Gateway retrieves the corresponding L2 ERC20 token address from the token mapping, encodes the deposit message, and forwards it to the L1 Wischain Messenger.

3. The related L2 transaction calls the L2 Wischain Messenger's relayMessage function to complete the deposit on L2, subsequently calling finalizeDepositERC20 in the L2CustomERC20Gateway.

4. The L2CustomERC20Gateway then calls the mint function on the corresponding L2 ERC20 token contract, provided that this contract grants minting permissions to the L2CustomERC20Gateway. If depositERC20AndCall is invoked on L1, the L2CustomERC20Gateway will relay additional data to the specified L2 contract.

WETH Token

The L1WETHGateway serves as the custom gateway for Wrapped ETH tokens on L1, and its address is recorded in the L1GatewayRouter. The deposit process for WETH tokens is as follows:

1. The L1WETHGateway locks the WETH tokens by transferring them from the sender to itself and unwraps them to convert WETH into native ETH.

2. Both the ETH and the msg.value (for covering relay fees) are sent to the L1 Wischain Messenger contract.

3. The L1WETHGateway encodes the token deposit message and forwards it to the L1 Wischain Messenger.

4. The associated L2 transaction invokes the L2 Wischain Messenger's relayMessage function to finalize the deposit on L2. In the case of WETH token deposits, this transaction calls finalizeDepositERC20 in the L2 WETH Gateway.

5. The L2 WETH Gateway wraps the deposited ETH back into L2 WETH tokens and transfers them to the recipient address on L2. If depositERC20AndCall is used on L1, the L2 WETH Gateway will also call the specified L2 contract with additional data.

Depositing ERC-721 and ERC-1155 Tokens

The deposit process for ERC-721 and ERC-1155 tokens is similar to that of ERC20 tokens. Users can utilize the gateways L1ERC721Gateway or L1ERC1155Gateway to deposit their respective tokens from L1.

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

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

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

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

To facilitate large volumes of ERC-721 or ERC-1155 token deposits, batch deposit functions are available in the L1ERC721Gateway and L1ERC1155Gateway contracts, as detailed below:

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

function batchDepositERC721(
    address _token

,
    address _to,
    uint256[] calldata _tokenIds,
    uint256 _gasLimit
) external payable;

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

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

The corresponding L2 contracts for ERC-721 and ERC-1155 tokens are L2ERC721Gateway and L2ERC1155Gateway, which are used to finalize the deposit process on L2.