Recommended asset 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.
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.
The player must verify ownership of the wallet(s) on the legacy chain that has the assets which need to be migrated.
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.
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.
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.
3. No wallet linking (not recommended)
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.
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.