Polkadot Summit - Parachain Migration Tools Notes

Polkadot Summit, Copenhage 2023

Parachain Migration Tools

Estimated # of attendees: 10

Attendees/key participants:

High level discussion points:

The session introduced how Zeitgeist managed its parachain migration from Kusama to Polkadot. Various approaches, challenges and gaps in the process were discussed.

Slides: Polkadot_Decoded_2023_Migrating_a_parachain - Google Slides

Original forum post: Migrating from Kusama to Polkadot - A complete guide


  • Zeitgeist has recently completed a challenging parachain migration from Kusama to Polkadot
  • The migration process could be significantly improved if a framework were provided
  • When conducting a migration, the objective is to transition from one chain to another, in this instance, from Kusama to Polkadot
  • A script can be employed to copy the data. However, migrating all the data takes more than one block, and staging occurs in the subsequent block
  • The re-anchor solution involves adjusting one parachain and applying its latest state
  • The process involves the source parachain, target parachain, and target relay chain. This involves adjusting the configuration of the source parachain to prepare it for migration, halting block production, and informing the target relay chain about the latest state of the chain. Only then can the swap occur. The final step is to connect both entities
  • Re-anchoring presents several challenges. These include the formulation of a recovery plan (Plan B), aligning the state, halting the chain to prevent double spending and forks, overwriting the source on the target relay chain, and linking the source parachain and target relay chain. The manager account can be used in the event of recovery
    • On the relay chain you have the manager account, which can manage the state and the code of the parachain on behalf of the parachain. Once unlocked it becomes basically sudo for the parachain
  • Aligning the state is a critical part of the process that may require different parameters adjustments depending on the state
  • Sceptical that the process can be fully automated due to the complexities of aligning the state and halting the chain
    • Potentially the most elegant solution is to halt the chain in a way that it can be continued again on behalf of the manager account – to modify the head or runtime code
  • It’s necessary to employ governance during the process to avoid issues such as blockchain state overrides by a validator
  • An action item has been identified to create a common good resource for other builders
  • Consideration must be given to block explorers to ensure their services remain operational. Information must be provided promptly, and changes made in a timely manner
    • Assume two separate nodes with two different chain specs
    • Kilt: have one node with two databases, then it’s just a parameter change
  • Approaching from a parachain perspective highlights the importance of continuous block production. Strategies such as separate block creation and state logic, and incorporating the config as part of storage, were discussed
    • FRAME roadmap has a safemode
    • Imbue: XCM configs were breaking. Needed to close channels, open them again, etc
  • Restore is well defined in the web2 world (dump, transaction log)
  • There is a necessity to simplify the process, as the current steps are overly complex. Solutions like Kilt or Zeitgeist could have been adopted, but this is impossible due to the movement of Substrate
  • A good resource to consider for this purpose is Chopsticks
  • Automation of migration is currently not feasible. However, we can create the necessary tools to safely navigate the process. Once this stage is successfully executed, we can then consider automation. During this, understanding which configurations need to be integrated into storage is crucial
  • Sam pointed out that storage encompasses all the events that have occurred on your chain. For example, if there’s a need to migrate from block 1000 on Kusama to block 1000 on Polkadot, it would be easy if all configurations were stored in storage. This would facilitate a smooth move. The method would involve migrating the storage rather than the change. Creating tools to allow developers to anticipate if an introduced change would halt the chain is beneficial. The aim here is to replicate everything as closely as possible to the production environment
  • To do:
    • The first step would be to spawn a clone of the production. Ideally, this would involve spawning a clone for the target relay chain and shell parachain, which can be achieved with Chopsticks. This is the perfect scenario to identify and address potential errors at an early stage
    • Aim to construct a framework that allows the building of clones on both the source and destination, simulating the migration process. The question arises: what would constitute a good experience? The answer lies in the storage while migrating between relay chains. This is the most challenging aspect due to the dependency on the context. Thus, the primary focus should be on migrating storage between parachains on two relay chains

Migration simulation

  • The simulation environment should replicate the actual scenario, allowing for the application of changes (delta). This will reduce the chance of failure during the real migration
  • The simulation environment must produce blocks, potentially using Zombienet
  • The migration of storage should be based on configuration, employing tools such as try-runtime which can provide a preview of what will occur during the migration. The role and functionality of try-runtime within this framework should be clearly understood
  • Try-runtime can be used to highlight any errors, providing early warnings to parachain builders
  • The migration process should include a chainspec
  • It is important to identify which configurations can be merged with the state. For example, if the default version isn’t set, all XCM transactions will fail
  • The simulation must respect the runtime configuration
  • Resetting channels. Users need to be informed about this process since, without it, the system may seem broken to them
  • Once the simulation is successful, it should provide suggested results or expected outputs. Ideally, it should also output suggested results and call data for governance proposals
  • The simulation process should be designed for easy usage, possibly packaged as a container

Three places

  1. Storage
  • Currently, you need to write your migration for each pallet and every placement, aiming for a new genesis that doesn’t start at zero
  • Areas that need migration include changing the para ID, XCM heads, state root on relay chain, and, in the case of Nimbus, the highest slot seen
  1. Runtime config
  • Configs like Cumulus’ strict block increase, XCM configuration (version), relay-related configuration, and block limits need attention
  1. Chain spec
  • paraID, relaychain, protocolID

Aventus comment:

  • The migration process shouldn’t be part of the relay chain
  • Enterprises would likely reject the process if they can’t extract their data
  • Zeitgeist: this might not be possible since the environment changes
  • There should be changes made to the Polkadot and Kusama base code to make this migration simulation possible