Skip to main content

Using your existing ERC‑20 token on Immutable zkEVM

This guide will walk you through the required steps to enable using your existing ERC‑20 token on Immutable zkEVM. Including how to migrate from Ethereum, Immutable X and other EVM compatible chains.

If you haven’t already launched your project’s ERC‑20 token on another blockchain, you should read our guide on Launching a new ERC‑20 token on zkEVM instead.
in-game currency guidein-game currency guide
💡Who is this guide for?
Developers who have existing tokens on L1 Ethereum and want it to be usable on Immutable zkEVM.

The process of moving tokens between blockchain networks is called bridging. Currently, Immutable offers a Bridge Widget, that developers can integrate in their applications which allows players to transfer tokens between Ethereum and Immutable zkEVM.

How does bridging work?

Immutable's bridge works by locking tokens sent to it on Ethereum in escrow, and then minting the corresponding amount on Immutable zkEVM to the requested address. Inversely, when moving from Immutable zkEVM to Ethereum, the tokens that are sent to the bridge are burned on Immutable zkEVM and then unlocked on Ethereum.

💡Note
The representation of your Ethereum token on Immutable zkEVM has to be deployed by our bridge contract which also links it to your existing token on Ethereum. Do NOT deploy your own token with the same metadata on Immutable zkEVM, ensure you follow these instructions instead.

Migrating from Ethereum

Before any tokens can be bridged, Immutable's Bridge contract needs to deploy the ERC‑20 equivalent of your token onto Immutable zkEVM blockchain and link (or map) the token pair together. This ensures the bridge knows which token should be issued on the destination chain when it receives a token on the origin chain.

To enable bridging you will need to follow these steps;

  1. Call the mapToken method on our Ethereum bridge contract, this will deploy and link your token on Immutable zkEVM. The mapToken method takes the following parameters;
ParametersTypeDescription
rootTokenaddressThis is the address of your ERC‑20 token contract on Ethereum.
payableAmountetherThis is the amount of ETH you will be paying to execute this action on the bridge.
  • The easiest way to call this method is through Etherscan's write proxy, but it will require a web wallet, like metamask, with some balance to connect then pay the fees and gas.

  • We suggest setting payableAmount to 0.001 ETH to ensure the mapping is processed. Any over payment will be refunded once the process is complete.

  • Once you've confirmed the mapToken transaction through your web wallet, you can look the transaction ID up on Axelarscan to watch the progress of the bridge transaction.

  • Once the transaction has gone through all the stages and shows Executed the zkEVM token should be deployed and the mapping complete.

  1. Once your token is mapped, you will need to fetch the contract address of your newly created token on Immutable zkEVM by calling the Bridge method rootTokenToChildToken which takes the following parameters;
ParametersTypeDescription
inputaddressThis is the address of your ERC‑20 token contract on Ethereum.
  • Again, the easiest way to call this method is through Etherscan's read proxy and there are no fees required to do this.

  • The rootTokenToChildToken method returns the address the bridge gave to your token on Immutable zkEVM. You should be able to look it up on Blockscout to confirm it exists and the metadata are correct.

Your token can now technically be bridged from Ethereum to Immutable zkEVM. However it still needs to be added to the Bridge widget so it will appear in the list of available tokens for players to bridge.

💡What's upcoming
Soon we will be releasing an application form for this inside Immutable Hub, but for now you will need to reach out to support on Discord if you would like your token added to the Bridge widget.

Migrating from Immutable X

If your token is being migrated from ImmutableX (StarkEx), these tokens originate from Ethereum. All tokens on ImmutableX need to be withdrawn by the game and/or token holders then bridged to Immutable zkEVM by following the same process as above.

Migrating from a different EVM compatible blockchain

Bridging to Immutable zkEVM directly from another EVM compatible blockchain (besides Ethereum) is currently not natively supported in our bridge.

💡What's upcoming
We have plans to extend our Bridge to allow direct bridging between other EVM compatible blockchains. Please join our developer Discord to keep updated.

Today you can execute using either of the following two options:

  1. If your tokens on another blockchain (e.g. BNB Chain) can be bridged to Ethereum. The game and/or token holders should bridge them to Ethereum, then the tokens can be bridged from there to Immutable zkEVM using the same process as above.

  2. You can perform a burn or transfer by players on your current blockchain using a custom contract or a multi-sig wallet, then the corresponding amount minted to them on Immutable zkEVM as a new ERC‑20.

💡Caution
If you attempt option 2, currently you will need to build the pipeline and front-end experience for this method yourself, as well as monitor the process of burning and minting across both chains.

Migrating from any another blockchain

Migrating from other blockchains which are not EVM compatible is not currently supported.


Related content

IMX Whitepaper IMX Tokenomics Block Explorer Careers Contact Us