Expand description

Multi-block Migration framework for pallet-contracts.

This module allows us to define a migration as a sequence of MigrationSteps that can be executed across multiple blocks.


A migration step is defined under src/migration/vX.rs, where X is the version number. For example, vX.rs defines a migration from version X - 1 to version X.


To configure a migration to v11 for a runtime using v10 of pallet-contracts on the chain, you would set the Migrations type as follows:

use pallet_contracts::migration::{v10, v11};
type Migrations = (v10::Migration<Runtime, Currency>, v11::Migration<Runtime>);


  • Migrations should always be tested with try-runtime before being deployed.
  • By testing with try-runtime against a live network, you ensure that all migration steps work and that you have included the required steps.

Low Level / Implementation Details

When a migration starts and OnRuntimeUpgrade::on_runtime_upgrade is called, instead of performing the actual migration, we set a custom storage item [MigrationInProgress]. This storage item defines a Cursor for the current migration.

If the [MigrationInProgress] storage item exists, it means a migration is in progress, and its value holds a cursor for the current migration step. These migration steps are executed during Hooks<BlockNumber>::on_idle or when the Pallet::migrate dispatchable is called.

While the migration is in progress, all dispatchables except migrate, are blocked, and returns a MigrationInProgress error.



  • Performs all necessary migrations based on StorageVersion.


  • IsFinished describes whether a migration is finished or not.
  • The result of running the migration.
  • The result of running a migration step.


Type Definitions

  • The cursor used to encode the position (usually the last iterated key) of the current migration step.