Runtime Upgrade ref docs and Single Block Migration example pallet

Cargo.toml

@@ -308,6 +308,7 @@ members = [
 	"substrate/frame/examples/frame-crate",
 	"substrate/frame/examples/kitchensink",
 	"substrate/frame/examples/offchain-worker",
+	"substrate/frame/examples/single-block-migrations",
 	"substrate/frame/examples/split",
 	"substrate/frame/executive",
 	"substrate/frame/fast-unstake",

cumulus/pallets/collator-selection/src/lib.rs

@@ -118,7 +118,7 @@ pub mod pallet {
 	use sp_staking::SessionIndex;
 	use sp_std::vec::Vec;
 
-	/// The current storage version.
+	/// The in-code storage version.
 	const STORAGE_VERSION: StorageVersion = StorageVersion::new(1);
 
 	type BalanceOf<T> =

cumulus/pallets/parachain-system/src/migration.rs

@@ -21,7 +21,7 @@ use frame_support::{
 	weights::Weight,
 };
 
-/// The current storage version.
+/// The in-code storage version.
 pub const STORAGE_VERSION: StorageVersion = StorageVersion::new(2);
 
 /// Migrates the pallet storage to the most recent version.

cumulus/pallets/xcmp-queue/src/migration.rs

@@ -24,7 +24,7 @@ use frame_support::{
 	weights::{constants::WEIGHT_REF_TIME_PER_MILLIS, Weight},
 };
 
-/// The current storage version.
+/// The in-code storage version.
 pub const STORAGE_VERSION: StorageVersion = StorageVersion::new(4);
 
 pub const LOG: &str = "runtime::xcmp-queue-migration";

cumulus/parachains/pallets/collective-content/src/lib.rs

@@ -59,7 +59,7 @@ pub mod pallet {
 	use frame_system::pallet_prelude::*;
 	use sp_runtime::{traits::BadOrigin, Saturating};
 
-	/// The current storage version.
+	/// The in-code storage version.
 	const STORAGE_VERSION: StorageVersion = StorageVersion::new(0);
 
 	#[pallet::pallet]

cumulus/parachains/runtimes/assets/asset-hub-rococo/src/lib.rs

@@ -965,37 +965,37 @@ impl frame_support::traits::OnRuntimeUpgrade for InitStorageVersions {
 		let mut writes = 0;
 
 		if PolkadotXcm::on_chain_storage_version() == StorageVersion::new(0) {
-			PolkadotXcm::current_storage_version().put::<PolkadotXcm>();
+			PolkadotXcm::in_code_storage_version().put::<PolkadotXcm>();
 			writes.saturating_inc();
 		}
 
 		if Multisig::on_chain_storage_version() == StorageVersion::new(0) {
-			Multisig::current_storage_version().put::<Multisig>();
+			Multisig::in_code_storage_version().put::<Multisig>();
 			writes.saturating_inc();
 		}
 
 		if Assets::on_chain_storage_version() == StorageVersion::new(0) {
-			Assets::current_storage_version().put::<Assets>();
+			Assets::in_code_storage_version().put::<Assets>();
 			writes.saturating_inc();
 		}
 
 		if Uniques::on_chain_storage_version() == StorageVersion::new(0) {
-			Uniques::current_storage_version().put::<Uniques>();
+			Uniques::in_code_storage_version().put::<Uniques>();
 			writes.saturating_inc();
 		}
 
 		if Nfts::on_chain_storage_version() == StorageVersion::new(0) {
-			Nfts::current_storage_version().put::<Nfts>();
+			Nfts::in_code_storage_version().put::<Nfts>();
 			writes.saturating_inc();
 		}
 
 		if ForeignAssets::on_chain_storage_version() == StorageVersion::new(0) {
-			ForeignAssets::current_storage_version().put::<ForeignAssets>();
+			ForeignAssets::in_code_storage_version().put::<ForeignAssets>();
 			writes.saturating_inc();
 		}
 
 		if PoolAssets::on_chain_storage_version() == StorageVersion::new(0) {
-			PoolAssets::current_storage_version().put::<PoolAssets>();
+			PoolAssets::in_code_storage_version().put::<PoolAssets>();
 			writes.saturating_inc();
 		}
 

cumulus/parachains/runtimes/assets/asset-hub-westend/src/lib.rs

@@ -1019,17 +1019,17 @@ impl frame_support::traits::OnRuntimeUpgrade for InitStorageVersions {
 		let mut writes = 0;
 
 		if PolkadotXcm::on_chain_storage_version() == StorageVersion::new(0) {
-			PolkadotXcm::current_storage_version().put::<PolkadotXcm>();
+			PolkadotXcm::in_code_storage_version().put::<PolkadotXcm>();
 			writes.saturating_inc();
 		}
 
 		if ForeignAssets::on_chain_storage_version() == StorageVersion::new(0) {
-			ForeignAssets::current_storage_version().put::<ForeignAssets>();
+			ForeignAssets::in_code_storage_version().put::<ForeignAssets>();
 			writes.saturating_inc();
 		}
 
 		if PoolAssets::on_chain_storage_version() == StorageVersion::new(0) {
-			PoolAssets::current_storage_version().put::<PoolAssets>();
+			PoolAssets::in_code_storage_version().put::<PoolAssets>();
 			writes.saturating_inc();
 		}
 

cumulus/parachains/runtimes/bridge-hubs/bridge-hub-rococo/src/lib.rs

@@ -137,12 +137,12 @@ impl frame_support::traits::OnRuntimeUpgrade for InitStorageVersions {
 		let mut writes = 0;
 
 		if PolkadotXcm::on_chain_storage_version() == StorageVersion::new(0) {
-			PolkadotXcm::current_storage_version().put::<PolkadotXcm>();
+			PolkadotXcm::in_code_storage_version().put::<PolkadotXcm>();
 			writes.saturating_inc();
 		}
 
 		if Balances::on_chain_storage_version() == StorageVersion::new(0) {
-			Balances::current_storage_version().put::<Balances>();
+			Balances::in_code_storage_version().put::<Balances>();
 			writes.saturating_inc();
 		}
 

cumulus/parachains/runtimes/bridge-hubs/bridge-hub-westend/src/lib.rs

@@ -138,12 +138,12 @@ impl frame_support::traits::OnRuntimeUpgrade for InitStorageVersions {
 		let mut writes = 0;
 
 		if PolkadotXcm::on_chain_storage_version() == StorageVersion::new(0) {
-			PolkadotXcm::current_storage_version().put::<PolkadotXcm>();
+			PolkadotXcm::in_code_storage_version().put::<PolkadotXcm>();
 			writes.saturating_inc();
 		}
 
 		if Balances::on_chain_storage_version() == StorageVersion::new(0) {
-			Balances::current_storage_version().put::<Balances>();
+			Balances::in_code_storage_version().put::<Balances>();
 			writes.saturating_inc();
 		}
 

docs/sdk/Cargo.toml

@@ -27,6 +27,10 @@ node-cli = { package = "staging-node-cli", path = "../../substrate/bin/node/cli"
 kitchensink-runtime = { path = "../../substrate/bin/node/runtime" }
 chain-spec-builder = { package = "staging-chain-spec-builder", path = "../../substrate/bin/utils/chain-spec-builder" }
 subkey = { path = "../../substrate/bin/utils/subkey" }
+frame-system = { path = "../../substrate/frame/system", default-features = false }
+frame-support = { path = "../../substrate/frame/support", default-features = false }
+frame-executive = { path = "../../substrate/frame/executive", default-features = false }
+pallet-example-single-block-migrations = { path = "../../substrate/frame/examples/single-block-migrations" }
 
 # Substrate
 sc-network = { path = "../../substrate/client/network" }
@@ -57,6 +61,7 @@ sp-api = { path = "../../substrate/primitives/api" }
 sp-core = { path = "../../substrate/primitives/core" }
 sp-keyring = { path = "../../substrate/primitives/keyring" }
 sp-runtime = { path = "../../substrate/primitives/runtime" }
+sp-version = { path = "../../substrate/primitives/version" }
 
 [dev-dependencies]
 parity-scale-codec = "3.6.5"

docs/sdk/src/reference_docs/frame_runtime_upgrades_and_migrations.rs

@@ -0,0 +1,135 @@
+//! # Runtime Upgrades
+//!
+//! At their core, blockchain logic consists of
+//!
+//! 1. on-chain state and
+//! 2. a state transition function
+//!
+//! In Substrate-based blockchains, state transition functions are referred to as
+//! [runtimes](https://docs.substrate.io/learn/runtime-development/).
+//!
+//! Traditionally, before Substrate, upgrading state transition functions required node
+//! operators to download new software and restart their nodes in a process called
+//! [forking](https://en.wikipedia.org/wiki/Fork_(blockchain)).
+//!
+//! Substrate-based blockchains do not require forking, and instead upgrade runtimes
+//! in a process called "Runtime Upgrades".
+//!
+//! Forkless runtime upgrades are a defining feature of the Substrate framework. Updating the
+//! runtime logic without forking the code base enables your blockchain to seemlessly evolve
+//! over time in a deterministic, rules-based manner. It also removes ambiguity for node operators
+//! and other participants in the network about what is the canonical runtime.
+//!
+//! This capability is possible due to the runtime of a blockchain existing in on-chain storage.
+//!
+//! ## Performing a Runtime Upgrade
+//!
+//! To upgrade a runtime, an [`Origin`](frame_system::RawOrigin) with the necesarry permissions
+//! (usually via governance) executes [`set_code`] (or [`set_code_without_checks`]) with the
+//! desired new blob.
+//!
+//! Prior to building the new runtime, don't forget to update the
+//! [`RuntimeVersion`](sp_version::RuntimeVersion).
+//!
+//! # Migrations
+//!
+//! It is often desirable to define logic to execute immediately after runtime upgrades.
+//!
+//! Self-contained pieces of logic that execute after a runtime upgrade are called "Migrations".
+//!
+//! Migrations are typically used to 'migrate' pallet storage into a new layout when the expected
+//! storage layout of a pallet changes, but they do anything including but not limited to:
+//!
+//! - Calling arbitrary pallet methods
+//! - Mutating arbitrary on-chain state
+//! - Cleaning up some old storage items that are no longer needed
+//!
+//! ## Single Block Migrations
+//!
+//! - Execute immediately and entirely at the beginning of the block following
+//! a runtime upgrade.
+//! - Are suitable for migrations which are guaranteed to not exceed the block weight.
+//! - Are simply implementations of [`OnRuntimeUpgrade`].
+//!
+//! To learn best practices for writing single block pallet storage migrations, see the
+//! [Single Block Migration Example Pallet](pallet_example_single_block_migrations).
+//!
+//! ### Scheduling the Single Block Migrations to Run Next Runtime Upgrade
+//!
+//! Schedule migrations to run next runtime upgrade passing them as a generic parameter to your
+//! [`Executive`](frame_executive) pallet:
+//!
+//! ```ignore
+//! /// Tuple of migrations (structs that implement `OnRuntimeUpgrade`)
+//! type Migrations = (
+//! 	pallet_example_storage_migration::migrations::v1::versioned::MigrateV0ToV1,
+//! 	MyCustomMigration,
+//! 	// ...more migrations here
+//! );
+//! pub type Executive = frame_executive::Executive<
+//! 	Runtime,
+//! 	Block,
+//! 	frame_system::ChainContext<Runtime>,
+//! 	Runtime,
+//! 	AllPalletsWithSystem,
+//! 	Migrations, // <-- pass your migrations to Executive here
+//! >;
+//! ```
+//!
+//! ### Ensuring Single Block Migration Safety
+//!
+//! "My migration unit tests pass, so it should be safe to deploy right?"
+//!
+//! No! Unit tests execute the migration in a very simple test environment, and cannot account
+//! for the complexities of a real runtime or real on-chain state.
+//!
+//! Prior to deploying migrations, it is critical to perform additional checks to ensure that when
+//! run in our real runtime they will not brick the chain due to:
+//! - Panicing
+//! - Touching too many storage keys and resulting in an excessively large PoV
+//! - Taking too long to execute
+//!
+//! [`try-runtime-cli`](https://github.com/paritytech/try-runtime-cli) has a sub-command
+//! [`on-runtime-upgrade`](https://paritytech.github.io/try-runtime-cli/try_runtime_core/commands/enum.Action.html#variant.OnRuntimeUpgrade)
+//! which is designed to help with exactly this.
+//!
+//! Developers MUST run this command before deploying migrations to ensure they will not
+//! inadvertently result in a bricked chain.
+//!
+//! It is recommended to run as part of your CI pipeline. See the
+//! [polkadot-sdk check-runtime-migration job](https://github.com/paritytech/polkadot-sdk/blob/4a293bc5a25be637c06ce950a34490706597615b/.gitlab/pipeline/check.yml#L103-L124)
+//! for an example of how to configure this.
+//!
+//! ### Note on the Manipulability of PoV Size and Execution Time
+//!
+//! While [`try-runtime-cli`](https://github.com/paritytech/try-runtime-cli) can help ensure with
+//! very high certianty that a migration will succeed given **existing** on-chain state, it cannot
+//! prevent a malicious actor from manipulating state in a way that will cause the migration to take
+//! longer or produce a PoV much larger than previously measured.
+//!
+//! Therefore, it is important to write migrations in such a way that the execution time or PoV size
+//! it adds to the block cannot be easily manipulated. e.g., in your migration, do not iterate over
+//! storage that can quickly or cheaply be bloated.
+//!
+//! If writing your migration in such a way is not possible, a multi block migration should be used
+//! instead.
+//!
+//! ### Other useful tools
+//!
+//! [`Chopsticks`](https://github.com/AcalaNetwork/chopsticks) is another tool in the Substrate
+//! ecosystem which developers may find useful to use in addition to `try-runtime-cli` when testing
+//! their single block migrations.
+//!
+//! ## Multi Block Migrations
+//!
+//! Safely and easily execute long-running migrations across multiple blocks.
+//!
+//! Suitable for migrations which could use arbitrary amounts of block weight.
+//!
+//! TODO: Link to multi block migration example/s.
+//!
+//! [`GetStorageVersion`]: frame_support::traits::GetStorageVersion
+//! [`OnRuntimeUpgrade`]: frame_support::traits::OnRuntimeUpgrade
+//! [`StorageVersion`]: frame_support::traits::StorageVersion
+//! [`set_code`]: frame_system::Call::set_code
+//! [`set_code_without_checks`]: frame_system::Call::set_code_without_checks

docs/sdk/src/reference_docs/mod.rs

@@ -89,9 +89,8 @@ pub mod cli;
 // TODO: @JoshOrndorff @kianenigma https://github.com/paritytech/polkadot-sdk-docs/issues/54
 pub mod consensus_swapping;
 
-/// Learn about all the advance ways to test your coordinate a rutnime upgrade and data migration.
-// TODO: @liamaharon https://github.com/paritytech/polkadot-sdk-docs/issues/55
-pub mod frame_runtime_migration;
+/// Learn about Runtime Upgrades and best practices for writing Migrations.
+pub mod frame_runtime_upgrades_and_migrations;
 
 /// Learn about light nodes, how they function, and how Substrate-based chains come
 /// light-node-first out of the box.

polkadot/node/service/src/parachains_db/upgrade.rs

@@ -85,7 +85,7 @@ pub(crate) fn try_upgrade_db(
 }
 
 /// Try upgrading parachain's database to the next version.
-/// If successfull, it returns the current version.
+/// If successful, it returns the current version.
 pub(crate) fn try_upgrade_db_to_next_version(
 	db_path: &Path,
 	db_kind: DatabaseKind,

polkadot/runtime/common/src/assigned_slots/mod.rs

@@ -107,7 +107,7 @@ type LeasePeriodOf<T> = <<T as Config>::Leaser as Leaser<BlockNumberFor<T>>>::Le
 pub mod pallet {
 	use super::*;
 
-	/// The current storage version.
+	/// The in-code storage version.
 	const STORAGE_VERSION: StorageVersion = StorageVersion::new(1);
 
 	#[pallet::pallet]