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

v16

Remove ED from storage base deposit. See https://github.com/paritytech/polkadot-sdk/pull/3536.

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 Aliases

Cursor

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