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 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>);

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

• codegen
• v09
  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.
• v13
  Add delegate_dependencies to ContractInfo. See https://github.com/paritytech/substrate/pull/14079.
• v14
  Update the code owner balance, make the code upload deposit balance to be held instead of reserved. Since Currency has been deprecated, we need the deposits to be handled by the frame_support::traits::fungible traits.
• v15
  Move contracts’ reserved balance from the deposit_account to be held in the contract’s account instead. Since Currency has been deprecated, we need the deposits to be handled by the frame_support::traits::fungible traits instead. For this transfer the balance from the deposit account to the contract’s account and hold it in there. Then the deposit account is not needed anymore and we can get rid of it.

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.