ERC721 NFT Token Bridge

Bridging ERC721 Tokens from Layer 1 to Layer 2

NFT Bridging Mechanism

In the Wischain ecosystem, the process of bridging ERC721 tokens from Layer 1 (L1) to Layer 2 (L2) is facilitated through the L1ERC721Gateway contract, rather than using a router mechanism. The process mirrors that of bridging ERC20 tokens, utilizing the depositERC721 function to send NFTs to L2. To retrieve these tokens back to L1, users can invoke the withdrawERC721 function on the L2ERC721Gateway contract deployed on L2.

For successful bridging, NFT contracts on both L1 and L2 must be launched and properly connected through the gateway contracts. If a contract is missing or not correctly mapped using the updateTokenMapping function, the deposit and withdrawal transactions will fail.

Deposit Process

The depositERC721 function is a payable function, meaning that it requires the sender to include a certain amount of ETH to cover L2 transaction fees. If the amount sent is insufficient, the transaction will not be processed. Any excess ETH will be refunded to the sender. Typically, a fee of approximately 0.00001 ETH is sufficient for a successful token deposit.

Creating a WischainERC721 Token on L2

To deposit an ERC721 token onto L2, a token contract must conform to the IScrollERC721 standard. This contract needs to be deployed and mapped through both the L1ERC721Gateway and L2ERC721Gateway. It must also grant the L2 gateway permission to mint tokens upon deposit and to burn tokens when they are withdrawn.

The following interface is required for deploying ERC721 tokens compatible with the L2ERC721Gateway:

interface IScrollERC721 {
  /// @notice Returns the address of the gateway to which the token belongs.
  function gateway() external view returns (address);

  /// @notice Returns the address of the corresponding token.
  function counterpart() external view returns (address);

  /// @notice Mints a token to the recipient's address.
  /// @dev Only the gateway contract can invoke this function.
  /// @param _to The address of the recipient.
  /// @param _tokenId The ID of the token to mint.
  function mint(address _to, uint256 _tokenId) external;

  /// @notice Burns a token from an account.
  /// @dev Only the gateway contract can invoke this function.
  /// @param _tokenId The ID of the token to burn.
  function burn(uint256 _tokenId) external;
}

Adding ERC721 NFTs to the Wischain Bridge

All assets can be bridged securely and without permission through gateway contracts that any developer can deploy. Wischain also manages a dedicated ERC721 gateway contract, where community-created NFTs can be integrated. By being part of this Wischain-managed gateway, developers do not need to deploy their own gateway contracts, and their tokens will automatically appear on the Wischain frontend.

To include an NFT in the Wischain Gateway, developers must contact the Wischain team for integration into both the L1 and L2 gateway contracts. Detailed instructions for adding a new token to the Wischain official frontend can be found in the token lists repository.

Withdrawing ERC721 Tokens from Wischain

The L2ERC721Gateway contract facilitates the transfer of tokens from L2 back to L1. Before initiating a withdrawal, the L2ERC721Gateway must be approved by the NFT contract. Once this approval is in place, the withdrawERC721 function can be called to execute the bridging process.

The withdrawERC721 function is also payable, requiring ETH to cover L1 transaction fees. If the amount sent is insufficient, the transaction will fail, and any excess will be refunded. Fees may vary depending on L1 network activity, but a typical amount of 0.005 ETH should suffice for processing a token withdrawal.

It is crucial to ensure that the transaction does not revert on L1 during the withdrawal process, as recovering the NFT after a failure is not possible. In the event of a reversion, the assets will be burned on L2, and reminting them is not feasible.

API Overview for L1ERC721Gateway

For a comprehensive API documentation of the Wischain contracts, developers can refer to the relevant npm library.

L1ERC721Gateway API

Deposit Function:

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

• Parameters:

  • _token: The address of the ERC721 NFT contract on L1.

  • _to: The recipient's address on L2.

  • _tokenId: The ID of the NFT to deposit.

  • _gasLimit: The gas limit required for the deposit on L2. Any unused fees will be refunded.

Token Mapping Function:

function updateTokenMapping(address _l1Token, address _l2Token) external;

• Parameters:

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

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

L2ERC721Gateway API

Withdraw Function:

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

• Parameters:

  • _token: The address of the ERC721 NFT contract on L2.

  • _to: The recipient's address on L1.

  • _tokenId: The ID of the NFT to withdraw.

  • _gasLimit: Currently unused but included for future compatibility.

Token Mapping Function:

function updateTokenMapping(address _l1Token, address _l2Token) external;

• Parameters:

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

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

This structured approach to bridging ERC721 tokens ensures a seamless and efficient transfer process between layers in the Wischain ecosystem, while maintaining security and usability for developers and users alike.