Skip to main content

Choose your migration approach

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

However, there are many different options for migrating your assets to Immutable zkEVM. On this page, we will discuss these varying migration approaches and help you decide which combination best suits your needs.
in-game currency guidein-game currency guide
Developers who are considering migrating their assets to Immutable zkEVM and must decide which migration approach best suits their requirements.

When choosing how to migrate assets to Immutable zkEVM, a game studio must consider many factors such as the needs of their users and the requirements of their specific game. There are multiple migration types and timelines which can be combined to form a studio's "migration approach".

The most successful and feasible of these approaches is a Hard Long Tail migration, which Immutable strongly recommends.

Migration types to consider

There are different types of migrations you can perform and each has their own benefits and disadvantages.

Soft migration

With a soft migration you would leave the legacy assets where they are on the old blockchain and issue players the equivalent asset on Immutable zkEVM.

You would also need to make sure the legacy assets no longer have any utility or value. This can be achieved by ensuring your game no longer recognizes the legacy assets and only uses the new assets from Immutable zkEVM.

You may also need to effectively freeze your collection on the old chain, preventing orderbook executions, halting transfers, de-listing collections from marketplaces and even altering the metadata to mark the assets as discontinued.


  • A soft migration is reversible in case you need to roll back for some reason.
  • There is no player interaction required, everything is managed by you.
  • Players do not incur gas fees since they don't need to move or burn their assets.


  • The legacy assets will still exist in some shape or form, which could potentially cause confusion.
  • Since assets minted on one blockchain can potentially be bridged to another platform, it may not be easy or possible to deactivate all assets across all chains.
  • If any assets have been bridged to other blockchains they may still appear on marketplaces for those chains, leading to potential confusion and complaints.

Hard migration

With a hard migration the legacy assets are actually burned or returned before the equivalent asset is issued to players on Immutable zkEVM.


  • It's less confusing for players as they are effectively trading in their legacy asset for a new one rather than having two, one of which is useless.
  • The legacy assets are actually removed from circulation which prevents the trading of devalued assets.


  • Typically a one-way migration, which means there may be some player drop off during the process.
  • Because an on-chain action is required to burn or return the asset, players will incur gas fees.
  • It's best suited for individual asset migrations and games where players may only have a small number of assets each to migrate.

Migration timelines

There are different ways of managing migration timelines and you will need to decide which approach is best for your current situation.

Batch migration

Batch migration is a structured approach that requires players to take specific actions within a designated time frame. This method is suitable for communities with high engagement levels and typically follows a defined workflow:

  1. Communication: The game studio informs players about the migration process, including details and deadlines. Clear communication is essential to ensure players understand the requirements and time frame for migration.
  2. Registration: Players are required to register for migration to confirm their desired destination wallet. This step ensures that assets are transferred to the correct location during the migration process.
  3. Migration Process: Migration takes place within the specified time frame, during which players are categorized into two paths based on their compliance with the migration instructions:
    • Happy Path: Players who followed the migration instructions within the allotted time are migrated smoothly to the new destination without any issues.
    • Unhappy Path: Players who did not complete the required actions within the specified time frame are categorized into the unhappy path. They may require additional support or actions post cut-off to complete the migration successfully.
  4. Post-Migration Support: The game studio continues to communicate with and support players who are on the unhappy path, assisting them in transitioning to the happy path post-migration. This support may involve providing guidance, addressing issues, or facilitating additional steps required for successful migration.

By following this structured approach, a game studio can effectively manage batch migrations, ensure player compliance and support a smooth transition to the new destination for all players involved.

💡Set Migration Window
This migration timeline may take several days and ideally there is a finite point in time that a player has to perform an action to ensure that they are on the "happy path".

Long tail migration

Long tail migration allows players to migrate their assets at their own pace without the need to adhere to a strict timeline. This method offers a player-friendly workflow but entails additional costs (limited batch minting and operational support) and requires ongoing support from the game studio. The typical workflow for a long tail migration includes the following steps:

  1. Communication: The game studio communicates the migration process to players, including any relevant deadlines or timelines. If the long tail migration has a cut-off point, this should be clearly communicated to players, along with the duration of the migration support period (e.g. studio will support the process for 1 year).
  2. Player Migration Details: Players are required to register their desired destination wallet before the migration begins. This step ensures that assets are transferred to the correct location during the migration process.
  3. Migration Process: The migration occurs either instantly or may be batched overnight, depending on the game studio's implementation. Details collected from the previous step are utilized to guide the migration process, ensuring assets are transferred accurately.
  4. Post-Migration Support: Following the migration period, the game studio provides ongoing support to players who have not yet migrated their assets. While this support does not need to be real-time, it should offer a way for disengaged players to initiate the migration process at their convenience, albeit gradually. This support may involve manual assistance or a slow-paced migration process to accommodate players who have been inactive for an extended period of time.
💡Open ended migration
This type of migration is effectively open ended and the player can migrate at any time. This approach is great for players who might miss the migration news but on the other hand requires ongoing support from the game studio.

Possible combinations of migration type and timeline

A game studio may choose to migrate their assets to Immutable zkEVM in one of four ways:

  1. Hard Long Tail Migration (Strongly Recommended): In a Hard Long Tail migration, 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. However, there is no cut off date for the player to migrate their assets.

  2. Soft Batch Migration: In a Soft Batch migration, legacy assets are left where they are on the old blockchain (without utility or value) and players get issued the equivalent asset on Immutable zkEVM. For this to work, players are required to take action by a certain deadline. Once the deadline has passed, remaining players' assets are migrated in batches as they complete the required actions.

  3. Soft Long Tail Migration: A Soft Long Tail migration would involve leaving legacy assets where they are on the old blockchain (without utility or value) and issuing players the equivalent asset on Immutable zkEVM, but with no cut off date for the player to migrate their assets.

  4. Hard Batch Migration: A Hard Batch migration would require players to send you (or burn) the assets they want to migrate in order to take them out of circulation on the legacy chain. Players would need to do this by a certain deadline or have their assets frozen. Once the deadline has passed, remaining players' assets get migrated in batches as they complete the necessary actions.

💡Limited Support
Technically, all of these migration approaches are possible. However, Hard Long Tail migration is the only one served as an integrated solution by Immutable. If you need to use any of the other approaches, get in touch with us on Discord so we can help to assess if they're a viable option for you.
💡Other migration approaches
If you don't wish to migrate your game's assets, you may also consider the 'No Migration' or 'Optional Migration' pathways.

Key decision points

Our recommendation may not always be suitable for every situation, so here are some key decision points to consider.

  1. Live Game: If a game is already live, it is advisable to opt for a long tail migration to mitigate the risk of players encountering an "unhappy path." This approach aims to prevent situations where players have their assets migrated to an undesirable state, potentially resulting in the loss of hard-earned acquired players.
  2. Games Yet to Launch: In the case of games that have not yet launched, a Batch migration may be preferable to reduce the game's costs. Since the assets are not currently usable, the unhappy path resulting from a Batch migration typically poses less friction for players. Additionally, in scenarios where games have not yet launched but require a migration, players must complete steps to activate the asset, minimizing any significant friction caused by the unhappy path.
  3. Token ID Persistence: In certain cases, the value of specific NFTs can be directly influenced by the asset’s Token ID. In such instances, the community may anticipate that the Token IDs of their assets remain consistent across different blockchain networks. If this expectation exists, employing minting methods such as mintBatchByQuantity() or utilising the Minting API without Token ID inputs becomes unfeasible. Consequently, the migration process may incur higher minting costs as mintBatch() or Minting API with Token ID incurs higher gas fees.
  4. Minting API: Immutable's ERC721 presets are fully compatible with the Minting API. However, it's worth noting that ERC1155 is currently not compatible with the Minting API, although it is on the Immutable team's roadmap for future integration.
  5. ERC721 → ERC1155 Contract Migration: Some game studios may opt to migrate their ERC721 assets from legacy chains to Immutable's ERC1155 contract. This transition can offer several advantages for specific use cases. However, it's important to be aware of certain limitations:
    • Token ID Preservation: During the migration from ERC721 to ERC1155, the preservation of Token ID is not possible. Game studios should anticipate this change and its potential impact on asset management and player experience.
    • Minting API Support: Unlike ERC721, ERC1155 does not currently support the Minting API. Game studios should factor in this limitation when planning their migration strategy and consider alternative approaches for asset minting on the new contract.

Please take these key decision points and the advantages and disadvantages of each migration approach into account when deciding how to migrate your assets to Immutable zkEVM.

💡Migration Recommendation
Immutable strongly recommends to perform a Hard Long Tail migration as it provides the most benefits with the least downside.

Related content

IMX Whitepaper IMX Tokenomics Block Explorer Careers Contact Us