Skip to main content

Recommended asset migration approach

When migrating assets to Immutable zkEVM we recommend taking a Hard Long Tail migration approach.

If you haven't decided what type of migration best suits your requirements, please check out our guide on migrating your assets to Immutable zkEVM which explains the different migration types and when to use them.
in-game currency guidein-game currency guide
Developers who have decided to migrate existing assets to Immutable zkEVM using the Hard Long Tail Migration approach.

What is a Hard Long Tail migration?

A hard migration is when your players are required to send you (or burn) the assets they want to migrate in order to take them out of circulation on the legacy chain. And a long tail migration is when there is no cut off date for the player to migrate their assets. We recommend this combination of hard and long tail migration strategies because it drives the best outcome for your players.

Requiring the legacy assets to be taken out of circulation removes any confusion that could be created by having duplicate assets on two chains. Leaving the migration period open ended means none of your players are stuck with assets on the old chain if they miss the notice to migrate.

Before continuing, please make sure you've read our guide on migrating your assets to Immutable zkEVM, which covers topics like when to migrate, migration types and timelines. It also includes a check list of key decision points to help you choose the right migration strategy.

Inform your community

Once you've decided to migrate it's important to notify your community promptly. The urgency depends on the migration type (long tail or batch), but generally the sooner you can inform your community the better.

Choose how to migrate assets

Game studios have three options to offer their players:

1. Bridging contract with wallet linking interface

You will need to build a bridging contract that is connected to an interface where the players can perform the necessary steps to migrate their assets.

  1. The player must verify ownership of the wallet(s) on the legacy chain that has the assets which need to be migrated.

  2. The player must then confirm the wallet address on Immutable zkEVM they would like the assets migrated to. If your game requires passport, you should provide the player instructions on where and how to register for Passport.

  3. Once the player has confirmed their Immutable zkEVM address, they will need to transfer the assets they wish to migrate to a smart contract address designated by the game developer. This designated address will be used to determine which assets are now out of circulation and should be re-issued to the player on Immutable zkEVM. Sending the assets to the designated smart contract is likely to incur gas fees for the player.

  4. When the asset is received by the designated smart contract, this should trigger an off-chain service (built by the game developer) which detects the address the asset was sent from and maps that address to the player's Immutable zkEVM address. The off-chain service is then able to issue the migrated asset to the player on Immutable zkEVM.

2. Burn transfer tool with wallet linking interface

This method is basically the same as above. You will need to build an interface for the player to verify their address and confirm the Immutable zkEVM address the assets should be migrated to.

The main difference is that instead of sending the assets to a smart contract, the player will transfer the assets they want to migrate to a 0x0 burn address on the legacy chain.

Once the asset is confirmed as burned this should trigger an off-chain service (built by the game developer) which detects the address the asset was sent from and maps that address to the player's Immutable zkEVM address. The off-chain service is then able to issue the migrated asset to the player on Immutable zkEVM.

A straightforward migration strategy involves monitoring burn activity on the legacy chain and then mirroring the action by minting a duplicate asset on Immutable zkEVM to the exact same wallet address that initiated the burn. While this approach appears relatively simple, it relies on the following assumptions:

Consistent Wallet Addresses

It assumes that all players use the same wallet address across both chains. While this is typically true for most EVM-compatible chains, variations may exist based on factors such as the player's chosen wallet provider. For example if your game is using Passport, the players wallet address will be different on Immutable zkEVM to other chains.

Non-Gameplay Burn

It assumes that the asset is not burned as part of the game's regular gameplay loop. Otherwise, distinguishing between assets burned for gameplay purposes and those required for migration could pose challenges.

This approach has risks which cannot be reversed and may result in assets which are unable to be recovered on any chain.

Asset Creation on zkEVM

However you migrate your player's assets to Immutable zkEVM, it's recommended to use our Minting API to issue the migrated assets. When using the Minting API you should set the asset's token_id to be the same as the asset from the legacy chain to preserve the token ID between chains. Using the Minting API is gas-free during Immutable zkEVM's early access period.

Alternatively, you can use the mintBatch() method on our preset contracts to issue the migrated assets. Using mintBatch() is not gas-free and you will need to pay gas fees to issue the assets to your players this way.

💡Notify Players
Don't forget to notify players once you've issued their migrated assets on Immutable zkEVM, especially if you're batching asset creation rather than issuing the migrated assets in real time.

Related content

IMX Whitepaper IMX Tokenomics Block Explorer Careers Contact Us