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.

Usage

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.

Example:

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

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

Notes:

  • 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.

Modules

Structs

  • Performs all necessary migrations based on StorageVersion.

Enums

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

Traits

Type Definitions

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