Module pallet_contracts::migration

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

• v9
  Update CodeStorage with the new determinism field.
• v10
  Don’t rely on reserved balances keeping an account alive See https://github.com/paritytech/substrate/pull/13369.
• v11
  Overflowing bounded DeletionQueue. See https://github.com/paritytech/substrate/pull/13702.
• v12
  Move OwnerInfo to CodeInfo, add determinism field to the latter, clear CodeStorage and repay deposits.

Structs

• Migration
  Performs all necessary migrations based on StorageVersion.

Enums

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

Traits

• MigrateSequence
  Defines a sequence of migrations.
• MigrationStep
  A trait that allows to migrate storage from one version to another.

Type Definitions

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