Bridge ERC20 through the Custom Gateway

This guide outlines the process of utilizing Wischain's bridge for ERC20 tokens that require custom functionality via the Custom Gateway.

Do You Need Custom Logic?

In many cases, you may not need to use the Custom Gateway to add additional features to your token or its bridging logic. For further details, please refer to the article on ETH and ERC20 Token Bridge.

Step 1: Deploy a Token on Sepolia

To begin, you'll need a token to bridge. There is no specific ERC20 implementation required for compatibility with Layer 2 (L2). If you already possess a token, you can skip this step. However, if you're creating a new token, you can deploy a simple ERC20 token using the following contract, which mints 1 million tokens to the deployer upon launch:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.16;

import "@openzeppelin/contracts/token/ERC20/ERC20.sol";

contract L1Token is ERC20 {
  constructor() ERC20("My Token L1", "MTL1") {
    _mint(msg.sender, 1_000_000 ether);
  }
}

Step 2: Deploy the Counterpart Token on Wischain Sepolia Testnet

Next, create a counterpart token on Wischain to represent the original token on Sepolia. This token can implement custom logic that mirrors the L1 token or introduce additional features.

For this to function correctly:

• The token must implement the IWischainStandardERC20 interface to ensure compatibility with the bridge.

• The contract should provide the gateway address and counterpart token addresses (the L1 token just deployed) through the gateway() and counterpart() functions. Additionally, it must allow the L2 gateway to call the token's mint() and burn() functions during deposits and withdrawals.

Here’s an example of a token that is compatible with the bridge:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.16;

import "@openzeppelin/contracts/token/ERC20/ERC20.sol";
import "@wischain-tech/contracts@0.1.0/libraries/token/IWischainERC20Extension.sol";

contract L2Token is ERC20, IWischainERC20Extension {
  address _gateway;
  address _counterpart;

  constructor(address gateway_, address counterpart_) ERC20("My Token L2", "MTL2") {
    _gateway = gateway_;
    _counterpart = counterpart_;
  }

  function gateway() public view returns (address) {
    return _gateway;
  }

  function counterpart() external view returns (address) {
    return _counterpart;
  }

  function transferAndCall(address receiver, uint256 amount, bytes calldata data) external returns (bool success) {
    transfer(receiver, amount);
    data;
    return true;
  }

  function mint(address _to, uint256 _amount) external onlyGateway {
    _mint(_to, _amount);
  }

  function burn(address _from, uint256 _amount) external onlyGateway {
    _burn(_from, _amount);
  }

  modifier onlyGateway() {
    require(gateway() == _msgSender(), "Caller is not the gateway");
    _;
  }
}

Step 3: Add the Token to the Wischain Bridge

To incorporate your token into the L2CustomERC20Gateway contract on Wischain and the L1CustomERC20Gateway contract on Sepolia, you need to contact the Wischain team. Additionally, follow the guidelines provided in the token lists repository to list your token on the Wischain official bridge frontend.

Step 4: Deposit Tokens

Once your token receives approval from the Wischain team, you can deposit it from Layer 1. First, approve the L1CustomGateway contract address on Sepolia (e.g., 0x......). Then, deposit tokens by calling the depositERC20 function from the L1CustomGateway contract. This can be accomplished using the Wischain bridge UI, Etherscan Sepolia, or a smart contract.

Step 5: Withdraw Tokens

To send tokens back from L2 to L1, you will follow similar steps. Begin by approving the L2CustomGateway address (e.g., 0x.....) and then withdraw the tokens by calling the withdrawERC20 function from the L2CustomGateway contract.

Alternative Approach: Launching and Setting Up a Custom L1 Gateway Contract

While adding your token to the Wischain official bridge is the recommended method for bridging tokens to and from Wischain, you can also opt for launching a custom gateway. This method will require deploying an L1CustomERC20Gateway contract on Layer 1 and an L2CustomERC20Gateway on Layer 2.

Launch an L1 Custom Gateway

To begin, deploy the following contract on Sepolia:

// SPDX-License-Identifier: MIT
pragma solidity =0.8.16;

import "@openzeppelin/contracts/access/Ownable.sol";
import { IL2ERC20Gateway } from "@wischain-tech/contracts@0.1.0/L2/gateways/IL2ERC20Gateway.sol";
import { IL1WischainMessenger } from "@wischain-tech/contracts@0.1.0/L1/IL1WischainMessenger.sol";
import { IL1ERC20Gateway } from "@wischain-tech/contracts@0.1.0/L1/gateways/IL1ERC20Gateway.sol";
import { WischainGatewayBase } from "@wischain-tech/contracts@0.1.0/libraries/gateway/WischainGatewayBase.sol";
import { L1ERC20Gateway } from "@wischain-tech/contracts@0.1.0/L1/gateways/L1ERC20Gateway.sol";

contract L1CustomERC20Gateway is L1ERC20Gateway, Ownable {
  event UpdateTokenMapping(address indexed l1Token, address indexed oldL2Token, address indexed newL2Token);

  mapping(address => address) public tokenMapping;

  constructor() {}

  function initialize(address _counterpart, address _router, address _messenger) external {
    require(_router != address(0), "Router address cannot be zero");
    WischainGatewayBase._initialize(_counterpart, _router, _messenger);
  }

  function getL2ERC20Address(address _l1Token) public view override returns (address) {
    return tokenMapping[_l1Token];
  }

  function updateTokenMapping(address _l1Token, address _l2Token) external onlyOwner {
    require(_l2Token != address(0), "Token address cannot be zero");
    address _oldL2Token = tokenMapping[_l1Token];
    tokenMapping[_l1Token] = _l2Token;

    emit UpdateTokenMapping(_l1Token, _oldL2Token, _l2Token);
  }

  function _beforeFinalizeWithdrawERC20(address _l1Token, address _l2Token, address, address, uint256, bytes calldata) internal virtual override {
    require(msg.value == 0, "Non-zero message value");
    require(_l2Token != address(0), "Token address cannot be zero");
    require(_l2Token == tokenMapping[_l1Token], "L2 token mismatch");
  }

  function _beforeDropMessage(address, address, uint256) internal virtual override {
    require(msg.value == 0, "Non-zero message value");
  }

  function _deposit(address _token, address _to, uint256 _amount, bytes memory _data, uint256 _gasLimit) internal virtual override nonReentrant {
    address _l2Token = tokenMapping[_token];
    require(_l2Token != address(0), "No corresponding L2 token");

    address _from;
    (_from, _amount, _data) = _transferERC20In(_token, _amount, _data);

    bytes memory _message = abi.encodeCall(IL2ERC20Gateway.finalizeDepositERC20, (_token, _l2Token, _from, _to, _amount, _data));

    IL1WischainMessenger(messenger).sendMessage{ value: msg.value }(counterpart, 0, _message, _gasLimit, _from);

    emit DepositERC20(_token, _l2Token, _from, _to, _amount, _data);
  }
}

Launch an L2 Custom Gateway

Deploy the corresponding contract on Wischain:

// SPDX-License-Identifier: MIT
pragma solidity =0.8.16;

import "@openzeppelin/contracts/access/Ownable.sol";
import "@wischain-tech/contracts@0.1.0/L2/gateways/L2ERC20Gateway.sol";
import { IL2WischainMessenger } from "@wischain-tech/contracts@0.1.0/L2/IL2WischainMessenger.sol";
import { IL1ERC20Gateway } from "@wischain-tech/contracts@0.1.0/L1/gateways/IL1ERC20Gateway.sol";
import { WischainGatewayBase } from "@wischain-tech/contracts@0.1.0/libraries/gateway/WischainGatewayBase.sol";
import "@wischain-tech/contracts@0.1.0/libraries/token/IWischainERC20Extension.sol";

contract L2CustomERC20Gateway is L2ERC20Gateway, WischainGatewayBase, Ownable {
  event UpdateTokenMapping(address indexed l2Token, address indexed oldL1Token, address indexed newL1Token);

  mapping(address => address) public tokenMapping;

  constructor() {}

  function initialize(address _counterpart, address _router, address _

messenger) external {
    require(_router != address(0), "Router address cannot be zero");
    WischainGatewayBase._initialize(_counterpart, _router, _messenger);
  }

  function getL1ERC20Address(address _l2Token) external view override returns (address) {
    return tokenMapping[_l2Token];
  }

  function finalizeDepositERC20(address _l1Token, address _l2Token, address _from, address _to, uint256 _amount, bytes calldata _data) external payable override onlyCallByCounterpart nonReentrant {
    require(msg.value == 0, "Non-zero message value");
    require(_l1Token != address(0), "Token address cannot be zero");
    require(_l1Token == tokenMapping[_l2Token], "L1 token mismatch");

    IWischainERC20Extension(_l2Token).mint(_to, _amount);
    _doCallback(_to, _data);

    emit FinalizeDepositERC20(_l1Token, _l2Token, _from, _to, _amount, _data);
  }

  function updateTokenMapping(address _l2Token, address _l1Token) external onlyOwner {
    require(_l1Token != address(0), "Token address cannot be zero");

    address _oldL1Token = tokenMapping[_l2Token];
    tokenMapping[_l2Token] = _l1Token;

    emit UpdateTokenMapping(_l2Token, _oldL1Token, _l1Token);
  }

  function _withdraw(address _token, address _to, uint256 _amount, bytes memory _data, uint256 _gasLimit) internal virtual override nonReentrant {
    address _l1Token = tokenMapping[_token];
    require(_l1Token != address(0), "No corresponding L1 token");
    require(_amount > 0, "Withdraw zero amount");

    address _from = msg.sender;
    if (router == msg.sender) {
      (_from, _data) = abi.decode(_data, (address, bytes));
    }

    IWischainERC20Extension(_token).burn(_from, _amount);

    bytes memory _message = abi.encodeCall(IL1ERC20Gateway.finalizeWithdrawERC20, (_l1Token, _token, _from, _to, _amount, _data));

    IL2WischainMessenger(messenger).sendMessage{ value: msg.value }(counterpart, 0, _message, _gasLimit);

    emit WithdrawERC20(_l1Token, _token, _from, _to, _amount, _data);
  }
}

Setup Your Gateway Contract on Sepolia

After deploying the contracts, call the following functions to initialize them and bind them to the corresponding tokens and the gateway on the opposite side of the bridge.

1. Call the initialize function on the MyL1Gateway contract with the following parameters:

   • _counterpart: The address of MyL2Gateway deployed on Wischain.

   • _router: Set this to 0x........, the L1GatewayRouter contract address on Sepolia.

   • _messenger: Set this to 0x......, the L1WischainMessenger contract address on Sepolia.

A custom gateway can host multiple token bridges. In this example, we will enable bridging only between L1Token and L2Token by calling the updateTokenMapping function on the MyL1Gateway contract with the following parameters:

• _l1Token: The address of the L1Token contract launched on Sepolia.

• _l2Token: The address of the L2Token contract launched on Wischain.

Setup Your Gateway Contract on Wischain

Now, switch to the Wischain network and initialize MyL2Gateway, following similar steps:

1. Call the initialize function from MyL2Gateway:

   • _counterpart: The address of MyL1Gateway deployed on Sepolia.

   • _router: Set this to 0x........., the L2GatewayRouter contract address on Wischain.

   • _messenger: Set this to 0x......., the L2WischainMessenger contract address on Wischain.

2. Call updateTokenMapping on the MyL2Gateway contract:

   • _l2Token: The address of the L2Token contract launched on Wischain.

   • _l1Token: The address of the L1Token contract launched on Sepolia.

Bridging Tokens

You can now call depositERC20 from MyL1Gateway and withdrawERC20 from MyL2Gateway, just as you would with the official Wischain bridge. This allows for seamless token transfers between Layer 1 and Layer 2 within the Wischain ecosystem.