Other asset migration approaches
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.
If the recommended Hard Long Tail Migration doesn't meet your project's requirements, there are two other options available to you; Soft Batch Migration, or No Migration.
Soft Batch Migration
A soft migration is when you leave legacy assets where they are on the old blockchain and issue players the equivalent asset on Immutable zkEVM. The legacy assets will no longer have any utility or value to avoid duplicate assets in circulation.
Batch migration is a structured approach that requires players to take specific actions within a designated time frame.
There are various trade-offs to consider when using a Soft Batch migration strategy. For example, batch migration may reduce the overall migration cost to game studios since migration infrastructure does not need to be indefinitely maintained. However it may leave some players with assets they can no longer use if they miss the migration window.
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.
Before migration
If your game uses Passport, you will need to build a wallet linking interface so you can map the legacy assets to Immutable zkEVM addresses for migration.
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.
If you're migrating from Immutable X and Passport is not required, you can simply migrate the assets to the same Immutable zkEVM address as was used for Immutable X.
If you're migrating from any other blockchain you will need to independently confirm whether you can migrate directly to the same address or if you will need to build the wallet linking interface and map the assets across.
Migration process
Freeze collection and take snapshot
If you're migrating from Immutable X to Immutable zkEVM it's recommended to coordinate with us so we can freeze any assets on Immutable X at the migration cut-off date. This means we will;
- Prevent transfers, withdrawals, listings, trades and cancel existing orders.
- Take a snapshot of asset holders' wallets and inventory using the Blockchain Data API.
Once the snapshot is created you can begin to migrate assets to Immutable zkEVM.
Prepare batch to migrate
If you determined you can migrate the assets to the same address on Immutable zkEVM as the legacy chain then you can simply clone all the assets to Immutable zkEVM.
Or if you required wallet linking, you will need to determine which addresses have completed the wallet linking and only clone those assets to Immutable zkEVM.
If you still want players to be able to migrate assets after the migration cut-off date then you will need to perform additional batches of migrations at your discretion. This will give players who missed out a chance to complete wallet linking so you know where to migrate the assets to on Immutable zkEVM. It does mean y
Create assets on Immutable 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.
Transfer tools
We recommend you create a batch migration tool as outlined above to bulk migrate your player's assets to Immutable zkEVM. If this is not possible, we offer some transfer tools in the Immutable Toolkit which can potentially be used to help transfer assets to players on Immutable zkEVM but not between networks.
This transfer tool can do some batching of transfers, but it's only really designed for player to player transfers. It's likely you will have too many assets to distribute manually using this tool, however if you're building your own migration tool it can be a good reference.
After migration
There are a couple of things you can do after the migration has taken place to reduce confusion within your community;
- Update all the NFT images on the legacy chain to have the word 'INACTIVE' stamped across it so it is clear to the players and traders that these assets are part of a legacy collection which is no longer in use.
- Contact the marketplaces where your collection is traded and inform them the legacy collection has been migrated and that they should delist it from their platform.
Additional considerations
If you're migrating from Immutable X, keep in mind that Immutable X allows multiple recipients for royalties, whereas Immutable zkEVM does not. So if your collection requires royalty sharing, with you will need to implement an additional smart contract on Immutable zkEVM. We do provide a preset fee splitter contract which you can reuse or extend.
Optional Migration
This approach involves minting all new assets on Immutable zkEVM moving forward. Existing assets would remain on the legacy chain and continue to be usable in-game and tradable on marketplaces.
Attempting to mint new assets on the legacy chain should be blocked by updating the smart contract to prevent minting. Or if that is not possible, when an asset is minted on the legacy chain it will need to be burned and re-issued on Immutable zkEVM.
With this option it's important to prevent legacy chain minting so your player base organically adopts Immutable zkEVM over time.
No Migration
If you don't want to migrate, you don't technically have to. You could simply mint all new assets on Immutable zkEVM moving forward. It does mean that you will be forever required to support multiple blockchains which is likely to end up being less cost effective in the long run than migrating players to Immutable zkEVM.
Additional considerations
If you choose to use any of these migration approaches, keep in mind these options require ongoing multi-chain support both in-game and on marketplaces. Multi-chain support will cost you more to maintain than only supporting one chain.
With these approaches players are also likely to end up with assets on multiple chains. This could be confusing since they will most likely require different wallets, tools and marketplaces to view and use all their assets in your game.