Build on X Layer
Bridge to X Layer

Bridge to X Layer#

You can use ZkEVM Bridge Contract to bridge assets like ETH, OKB, and ERC-20 tokens between L1 and L2. However, there are a few points to note:

  • ETH is the native token of L1 (Ethereum). After bridging to L2 X Layer, it becomes a Wrapped ETH (WETH) ERC-20 token.
  • OKB is an ERC-20 token of L1 (Ethereum). After bridging to L2 X Layer, it becomes a native token.
  • Other ERC-20 tokens, which are bridged to the other side, remain ERC-20 tokens. You can calculate the new ERC-20 address by using the precalculatedWrapperAddress method.
  • There are no restrictions if you are bridging ERC-20 tokens from L1 to L2. However, there is a whitelist restriction when bridging assets from L2 to L1.
If you want to request L2 to L1 token whitelisting, you can join our X Layer Discord server, and navigate to #support-tickets to raise whitelising request.

The mapping list for OKB and ETH is as follows:

Deposit OKB and ERC-20 tokens from L1#

The ZkEVM bridge contract allows ETH and ERC-20 token bridging from L1 to L2 using the bridgeAsset function. Notice that ERC-20 tokens will have a different address on L2. You can use the precalculatedWrapperAddress function to query the new address in ZkEVMBridgeContract.sol contract


Deposit and add a new leaf to the Merkle tree:

function bridgeAsset(
    uint32 destinationNetwork,
    address destinationAddress,
    uint256 amount,
    address token,
    bool forceUpdateGlobalExitRoot,
    bytes permitData
  ) public


destinationNetworkuint32Network destination
destinationAddressaddressAddress destination
amountuint256Amount of tokens
tokenaddressToken address, 0 address is reserved for ETH
forceUpdateGlobalExitRootboolIndicates if the new global exit root is updated or not
permitDatabytesRaw data of the call permit of the token


This returns the precalculated address of a wrapper using the token information. Note: Updating the metadata of a token is not supported. Since the metadata has relevance in the address deployed, this function will not return a valid wrapped address if the metadata provided is not the original one.

function precalculatedWrapperAddress(
    uint32 originNetwork,
    address originTokenAddress,
    string name,
    string symbol,
    uint8 decimals
  ) external returns (address)


originNetworkuint32Origin network
originTokenAddressaddressOrigin token address, 0 address is reserved for ETH
namestringName of the token
symbolstringSymbol of the token
decimalsuint8Decimals of the token

Withdrawing OKB and ERC-20 tokens from L2#

You can use the claimAsset method to retrieve assets on L2. Calling this method on L2 incurs no Gas fees, so the official bridge service will be provided to automatically invoke the claimAsset method for you.


function claimAsset(
    bytes32[_DEPOSIT_CONTRACT_TREE_DEPTH] calldata smtProofLocalExitRoot,
    bytes32[_DEPOSIT_CONTRACT_TREE_DEPTH] calldata smtProofRollupExitRoot,
    uint256 globalIndex,
    bytes32 mainnetExitRoot,
    bytes32 rollupExitRoot,
    uint32 originNetwork,
    address originTokenAddress,
    uint32 destinationNetwork,
    address destinationAddress,
    uint256 amount,
    bytes calldata metadata
  ) external


smtProofLocalExitRootbytes32[32]Smt proof to proof the leaf against the network exit root
smtProofRollupExitRootbytes32[32]Smt proof to proof the rollupLocalExitRoot against the rollups exit root
globalIndexuint32Index of the leaf
mainnetExitRootbytes32Mainnet exit root
rollupExitRootbytes32Rollup exit root
originNetworkuint32Origin network
originTokenAddressaddressOrigin token address, 0 address is reserved for ETH
destinationNetworkuint32Network destination
destinationAddressaddressAddress destination
amountuint256`Amount of tokens
metadatabytesAbi encoded metadata if any, empty otherwise

Bridge to Ethereum#

Creating an ERC-20 token with custom logic on X Layer (L2)#

ERC-20 is the technical standard for fungible tokens created using the Ethereum blockchain. A fungible token is interchangeable with another token — whereas the well-known non-fungible tokens (NFTs) are not interchangeable. You can read more information about ERC-20 here. Deploy a simple ERC-20 contract with any of the tools like Truffle, Hardhat, or Foundry. This contract is implemented based on the open-source library, which can be found at OpenZeppelin.

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

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

contract MyToken is ERC20 {
    constructor() ERC20("MyToken", "MTK") {}

Depositing OKB and ERC-20 tokens from L2#

The same bridge contract is used on both L1 and L2, so the interface definition is identical.

Claiming assets on Ethereum will consume gas fees and is not free.