ETH & ERC20 Token Bridge

Bridging ETH and ERC20 Tokens from L1 to L2

The Wischain ecosystem includes a Gateway Router that facilitates the bridging of ETH and ERC20 tokens from Layer 1 (L1) to Layer 2 (L2) using the depositETH and depositERC20 functions. This bridge is permissionless and deployed on L1, allowing users to transfer assets seamlessly.

Bridging Process

When using the depositETH and depositERC20 functions, it’s important to note that ERC20 tokens will have distinct addresses on L2. You can utilize the getL2ERC20Address function to retrieve the new token address on L2.

These functions are payable, meaning that the amount of ETH sent will be allocated to cover the associated L2 fees. If the provided amount is insufficient, the transaction will not proceed, and any excess ETH will be returned to the sender. Typically, depositing a minimum of 0.00001 ETH should suffice to process a token deposit.

When bridging ERC20 tokens, the Gateway Router automatically selects the appropriate entry point for the transfer:

• L1StandardERC20Gateway: This gateway supports any ERC20 deposit and is chosen as the default by the L1GatewayRouter for tokens that don’t require custom logic on L2. Upon the initial bridging of a token, a corresponding token will be created on L2, implementing the WischainStandardERC20 interface. To initiate the bridging process, simply call the depositERC20 function on the L1GatewayRouter.

• L1CustomERC20Gateway: This gateway is selected for tokens that involve custom logic. For the L1/L2 token pair to function properly on the Wischain Custom ERC20 Bridge, the L2 token contract must implement the IWischainStandardERC20 interface and grant the L2CustomERC20Gateway the authority to mint or burn tokens. For detailed instructions on bridging custom tokens, refer to the guide on bridging ERC20 tokens through the Custom Gateway.

All gateway contracts construct the appropriate messages and forward them to the L1WischainMessenger, which can transmit arbitrary messages to L2. The L1WischainMessenger subsequently passes the messages to the L1MessageQueue. Users also have the capability to send messages directly to the Messenger, allowing them to execute functions on L2 from L1 transactions via the bridge. While it is possible to communicate directly with existing token contracts, using the Gateway simplifies the process of transfers and function calls.

In future updates, users will have the option to bypass the L1WischainMessenger and send messages directly to the L1MessageQueue. When messages are sent through the L1MessageQueue, the sender's address will be recognized as the user initiating the transaction, rather than the address of the L1WischainMessenger.

When a new block is created on L1, a Watcher will detect the message in the L1MessageQueue and forward it to the Relayer service, which will then submit the transaction to L2 via the l2geth node. Finally, the l2geth node will relay the transaction to the L2WischainMessenger contract for execution on L2.

Withdrawing ETH and ERC20 Tokens from L2

The L2 Gateway functions similarly to its L1 counterpart, enabling users to withdraw ETH and ERC20 tokens back to L1 using the withdrawETH and withdrawERC20 functions. This contract is deployed on L2, and users can utilize the getL1ERC20Address function to obtain the corresponding token address on L1.

Like the deposit functions, withdrawETH and withdrawERC20 are also payable. The ETH sent to these functions will be used to cover L1 fees. If the provided amount is insufficient, the transaction will not proceed, and any excess funds will be returned to the sender. While withdrawal fees may vary based on L1 activity, a general guideline suggests that 0.005 ETH should be adequate for processing a token withdrawal.

It’s crucial to ensure that transactions do not revert on L1 when withdrawing from L2. If a transaction fails on L1, any bridged ETH, tokens, or NFTs will be lost, as these assets are burned on Wischain when the transaction is initiated, making recovery impossible.

Creating an ERC20 Token with Custom Logic on L2

For tokens requiring custom logic on L2, bridging must be conducted through the L1CustomERC20Gateway and the L2CustomERC20Gateway. The L2 custom token must authorize the Gateway to mint new tokens upon deposit and to burn tokens upon withdrawal.

To create tokens compatible with the L2CustomERC20Gateway, the following interface, IWischainStandardERC20, must be implemented:

interface IWischainStandardERC20 {
  /// @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 burn.
  function burn(address _from, uint256 _amount) external;
}

Adding a Custom L2 ERC20 Token to the Wischain Bridge

Tokens can be securely and permissionlessly bridged using Gateway contracts deployed by any developer. However, Wischain also provides an ERC20 Router and Gateway where all community-created tokens are welcome. By being part of the Wischain-managed Gateway, developers can avoid the need to deploy Gateway contracts, ensuring that their tokens will be displayed on the Wischain frontend.

To add a token to both L1 and L2 bridge contracts, developers must reach out to the Wischain team and follow the instructions outlined in the token lists repository to ensure their new token is included in the official Wischain frontend.

L1 Gateway API

For a comprehensive overview of the Wischain contract API documentation, please visit the npm library.

Functions:

depositETH

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

• Description: Transfers ETH from L1 to L2.

• Parameters:

  • _to: The address of the recipient's account on L2.

  • _amount: The amount of ETH to transfer, specified in wei.

  • _gasLimit: The gas limit required to complete the deposit on L2 (approximately 170,000 should suffice).

depositERC20

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

• Description: Transfers ERC20 tokens from L1 to L2.

• Parameters:

  • _token: The address of the token on L1.

  • _to: The address of the recipient's account on L2.

  • _amount: The amount of tokens to transfer, specified in wei.

  • _gasLimit: The gas limit required to complete the deposit on L2 (approximately 200,000 should suffice).

getL2ERC20Address

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

• Description: Returns the corresponding L2 token address for a given L1 token address.

• Parameter:

  • _l1Token: The address of the L1 token.

updateTokenMapping

function updateTokenMapping(address _l1Token, address _l2Token) external;

• Description: Updates the mapping between an ERC20 token on L1 and its counterpart on L2.

• Parameters:

  • _l1Token: The address of the ERC20 token on L1.

  • _l2Token: The address of the corresponding ERC20 token on L2.

L2 Gateway API

withdrawETH

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

• Description: Transfers ETH from L2 to L1.

• Parameters:

  • to: The address of the recipient's account on L1.

  • amount: The amount of ETH to transfer, specified in wei.

  • gasLimit: The gas limit required to complete the withdrawal on L1 (optional).

withdrawERC20

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

• Description: Transfers ERC20 tokens from L2 to L1.

• Parameters:

  • token: The address of the token on L2.

  • to: The

address of the recipient's account on L1. - amount: The amount of tokens to transfer, specified in wei. - gasLimit: The gas limit required to complete the withdrawal on L1 (optional).

getL1ERC20Address

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

• Description: Returns the corresponding L1 token address for a given L2 token address.

• Parameter:

  • l2Token: The address of the L2 token.

updateTokenMapping

function updateTokenMapping(address _l1Token, address _l2Token) external;

• Description: Updates the mapping between an ERC20 token on L2 and its counterpart on L1.

• Parameters:

  • _l2Token: The address of the ERC20 token on L2.

  • _l1Token: The address of the corresponding ERC20 token on L1.

This comprehensive approach to bridging and token management in the Wischain ecosystem ensures a streamlined and efficient experience for users interacting with both L1 and L2 assets.