Multi-Block-Migrations, poll hook and new System callbacks (#1781)

This MR is the merge of https://github.com/paritytech/substrate/pull/14414 and https://github.com/paritytech/substrate/pull/14275. It implements [RFC#13](https://github.com/polkadot-fellows/RFCs/pull/13), closes https://github.com/paritytech/polkadot-sdk/issues/198. ----- This Merge request introduces three major topicals: 1. Multi-Block-Migrations 1. New pallet `poll` hook for periodic service work 1. Replacement hooks for `on_initialize` and `on_finalize` in cases where `poll` cannot be used and some more general changes to FRAME. The changes for each topical span over multiple crates. They are listed in topical order below. # 1.) Multi-Block-Migrations Multi-Block-Migrations are facilitated by creating `pallet_migrations` and configuring `System::Config::MultiBlockMigrator` to point to it. Executive picks this up and triggers one step of the migrations pallet per block. The chain is in lockdown mode for as long as an MBM is ongoing. Executive does this by polling `MultiBlockMigrator::ongoing` and not allowing any transaction in a block, if true. A MBM is defined through trait `SteppedMigration`. A condensed version looks like this: ```rust /// A migration that can proceed in multiple steps. pub trait SteppedMigration { type Cursor: FullCodec + MaxEncodedLen; type Identifier: FullCodec + MaxEncodedLen; fn id() -> Self::Identifier; fn max_steps() -> Option<u32>; fn step( cursor: Option<Self::Cursor>, meter: &mut WeightMeter, ) -> Result<Option<Self::Cursor>, SteppedMigrationError>; } ``` `pallet_migrations` can be configured with an aggregated tuple of these migrations. It then starts to migrate them one-by-one on the next runtime upgrade. Two things are important here: - 1. Doing another runtime upgrade while MBMs are ongoing is not a good idea and can lead to messed up state. - 2. **Pallet Migrations MUST BE CONFIGURED IN `System::Config`, otherwise it is not used.** The pallet supports an `UpgradeStatusHandler` that can be used to notify external logic of upgrade start/finish (for example to pause XCM dispatch). Error recovery is very limited in the case that a migration errors or times out (exceeds its `max_steps`). Currently the runtime dev can decide in `FailedMigrationHandler::failed` how to handle this. One follow-up would be to pair this with the `SafeMode` pallet and enact safe mode when an upgrade fails, to allow governance to rescue the chain. This is currently not possible, since governance is not `Mandatory`. ## Runtime API - `Core`: `initialize_block` now returns `ExtrinsicInclusionMode` to inform the Block Author whether they can push transactions. ### Integration Add it to your runtime implementation of `Core` and `BlockBuilder`: ```patch diff --git a/runtime/src/lib.rs b/runtime/src/lib.rs @@ impl_runtime_apis! { impl sp_block_builder::Core<Block> for Runtime { - fn initialize_block(header: &<Block as BlockT>::Header) { + fn initialize_block(header: &<Block as BlockT>::Header) -> RuntimeExecutiveMode { Executive::initialize_block(header) } ... } ``` # 2.) `poll` hook A new pallet hook is introduced: `poll`. `Poll` is intended to replace mostly all usage of `on_initialize`. The reason for this is that any code that can be called from `on_initialize` cannot be migrated through an MBM. Currently there is no way to statically check this; the implication is to use `on_initialize` as rarely as possible. Failing to do so can result in broken storage invariants. The implementation of the poll hook depends on the `Runtime API` changes that are explained above. # 3.) Hard-Deadline callbacks Three new callbacks are introduced and configured on `System::Config`: `PreInherents`, `PostInherents` and `PostTransactions`. These hooks are meant as replacement for `on_initialize` and `on_finalize` in cases where the code that runs cannot be moved to `poll`. The reason for this is to make the usage of HD-code (hard deadline) more explicit - again to prevent broken invariants by MBMs. # 4.) FRAME (general changes) ## `frame_system` pallet A new memorize storage item `InherentsApplied` is added. It is used by executive to track whether inherents have already been applied. Executive and can then execute the MBMs directly between inherents and transactions. The `Config` gets five new items: - `SingleBlockMigrations` this is the new way of configuring migrations that run in a single block. Previously they were defined as last generic argument of `Executive`. This shift is brings all central configuration about migrations closer into view of the developer (migrations that are configured in `Executive` will still work for now but is deprecated). - `MultiBlockMigrator` this can be configured to an engine that drives MBMs. One example would be the `pallet_migrations`. Note that this is only the engine; the exact MBMs are injected into the engine. - `PreInherents` a callback that executes after `on_initialize` but before inherents. - `PostInherents` a callback that executes after all inherents ran (including MBMs and `poll`). - `PostTransactions` in symmetry to `PreInherents`, this one is called before `on_finalize` but after all transactions. A sane default is to set all of these to `()`. Example diff suitable for any chain: ```patch @@ impl frame_system::Config for Test { type MaxConsumers = ConstU32<16>; + type SingleBlockMigrations = (); + type MultiBlockMigrator = (); + type PreInherents = (); + type PostInherents = (); + type PostTransactions = (); } ``` An overview of how the block execution now looks like is here. The same graph is also in the rust doc. <details><summary>Block Execution Flow</summary> <p> ![Screenshot 2023-12-04 at 19 11 29](https://github.com/paritytech/polkadot-sdk/assets/10380170/e88a80c4-ef11-4faa-8df5-8b33a724c054) </p> </details> ## Inherent Order Moved to https://github.com/paritytech/polkadot-sdk/pull/2154 --------------- ## TODO - [ ] Check that `try-runtime` still works - [ ] Ensure backwards compatibility with old Runtime APIs - [x] Consume weight correctly - [x] Cleanup --------- Signed-off-by: Oliver Tale-Yazdi <oliver.tale-yazdi@parity.io> Co-authored-by: Liam Aharon <liam.aharon@hotmail.com> Co-authored-by: Juan Girini <juangirini@gmail.com> Co-authored-by: command-bot <> Co-authored-by: Francisco Aguirre <franciscoaguirreperez@gmail.com> Co-authored-by: Gavin Wood <gavin@parity.io> Co-authored-by: Bastian Köcher <git@kchr.de>
2026-06-12 08:51:09 +00:00 · 2024-02-28 20:49:00 +01:00
parent 576681b867
commit eefd5fe449
78 changed files with 5074 additions and 1190 deletions
@@ -16,13 +16,21 @@
 // limitations under the License.

 use crate::{
-	traits::{GetStorageVersion, NoStorageVersionSet, PalletInfoAccess, StorageVersion},
-	weights::{RuntimeDbWeight, Weight},
+	defensive,
+	storage::transactional::with_transaction_opaque_err,
+	traits::{
+		Defensive, GetStorageVersion, NoStorageVersionSet, PalletInfoAccess, SafeMode,
+		StorageVersion,
+	},
+	weights::{RuntimeDbWeight, Weight, WeightMeter},
 };
+use codec::{Decode, Encode, MaxEncodedLen};
 use impl_trait_for_tuples::impl_for_tuples;
+use sp_arithmetic::traits::Bounded;
 use sp_core::Get;
 use sp_io::{hashing::twox_128, storage::clear_prefix, KillStorageResult};
-use sp_std::marker::PhantomData;
+use sp_runtime::traits::Zero;
+use sp_std::{marker::PhantomData, vec::Vec};

 /// Handles storage migration pallet versioning.
 ///
@@ -91,7 +99,7 @@ pub struct VersionedMigration<const FROM: u16, const TO: u16, Inner, Pallet, Wei

 /// A helper enum to wrap the pre_upgrade bytes like an Option before passing them to post_upgrade.
 /// This enum is used rather than an Option to make the API clearer to the developer.
-#[derive(codec::Encode, codec::Decode)]
+#[derive(Encode, Decode)]
 pub enum VersionedPostUpgradeData {
 	/// The migration ran, inner vec contains pre_upgrade data.
 	MigrationExecuted(sp_std::vec::Vec<u8>),
@@ -118,7 +126,6 @@ impl<
 	/// migration ran or not.
 	#[cfg(feature = "try-runtime")]
 	fn pre_upgrade() -> Result<sp_std::vec::Vec<u8>, sp_runtime::TryRuntimeError> {
-		use codec::Encode;
 		let on_chain_version = Pallet::on_chain_storage_version();
 		if on_chain_version == FROM {
 			Ok(VersionedPostUpgradeData::MigrationExecuted(Inner::pre_upgrade()?).encode())
@@ -361,3 +368,622 @@ impl<P: Get<&'static str>, DbWeight: Get<RuntimeDbWeight>> frame_support::traits
 		Ok(())
 	}
 }
+
+/// A migration that can proceed in multiple steps.
+pub trait SteppedMigration {
+	/// The cursor type that stores the progress (aka. state) of this migration.
+	type Cursor: codec::FullCodec + codec::MaxEncodedLen;
+
+	/// The unique identifier type of this migration.
+	type Identifier: codec::FullCodec + codec::MaxEncodedLen;
+
+	/// The unique identifier of this migration.
+	///
+	/// If two migrations have the same identifier, then they are assumed to be identical.
+	fn id() -> Self::Identifier;
+
+	/// The maximum number of steps that this migration can take.
+	///
+	/// This can be used to enforce progress and prevent migrations becoming stuck forever. A
+	/// migration that exceeds its max steps is treated as failed. `None` means that there is no
+	/// limit.
+	fn max_steps() -> Option<u32> {
+		None
+	}
+
+	/// Try to migrate as much as possible with the given weight.
+	///
+	/// **ANY STORAGE CHANGES MUST BE ROLLED-BACK BY THE CALLER UPON ERROR.** This is necessary
+	/// since the caller cannot return a cursor in the error case. [`Self::transactional_step`] is
+	/// provided as convenience for a caller. A cursor of `None` implies that the migration is at
+	/// its end. A migration that once returned `Nonce` is guaranteed to never be called again.
+	fn step(
+		cursor: Option<Self::Cursor>,
+		meter: &mut WeightMeter,
+	) -> Result<Option<Self::Cursor>, SteppedMigrationError>;
+
+	/// Same as [`Self::step`], but rolls back pending changes in the error case.
+	fn transactional_step(
+		mut cursor: Option<Self::Cursor>,
+		meter: &mut WeightMeter,
+	) -> Result<Option<Self::Cursor>, SteppedMigrationError> {
+		with_transaction_opaque_err(move || match Self::step(cursor, meter) {
+			Ok(new_cursor) => {
+				cursor = new_cursor;
+				sp_runtime::TransactionOutcome::Commit(Ok(cursor))
+			},
+			Err(err) => sp_runtime::TransactionOutcome::Rollback(Err(err)),
+		})
+		.map_err(|()| SteppedMigrationError::Failed)?
+	}
+}
+
+/// Error that can occur during a [`SteppedMigration`].
+#[derive(Debug, Encode, Decode, MaxEncodedLen, scale_info::TypeInfo)]
+pub enum SteppedMigrationError {
+	// Transient errors:
+	/// The remaining weight is not enough to do anything.
+	///
+	/// Can be resolved by calling with at least `required` weight. Note that calling it with
+	/// exactly `required` weight could cause it to not make any progress.
+	InsufficientWeight {
+		/// Amount of weight required to make progress.
+		required: Weight,
+	},
+	// Permanent errors:
+	/// The migration cannot decode its cursor and therefore not proceed.
+	///
+	/// This should not happen unless (1) the migration itself returned an invalid cursor in a
+	/// previous iteration, (2) the storage got corrupted or (3) there is a bug in the caller's
+	/// code.
+	InvalidCursor,
+	/// The migration encountered a permanent error and cannot continue.
+	Failed,
+}
+
+/// Notification handler for status updates regarding Multi-Block-Migrations.
+#[impl_trait_for_tuples::impl_for_tuples(8)]
+pub trait MigrationStatusHandler {
+	/// Notifies of the start of a runtime migration.
+	fn started() {}
+
+	/// Notifies of the completion of a runtime migration.
+	fn completed() {}
+}
+
+/// Handles a failed runtime migration.
+///
+/// This should never happen, but is here for completeness.
+pub trait FailedMigrationHandler {
+	/// Infallibly handle a failed runtime migration.
+	///
+	/// Gets passed in the optional index of the migration in the batch that caused the failure.
+	/// Returning `None` means that no automatic handling should take place and the callee decides
+	/// in the implementation what to do.
+	fn failed(migration: Option<u32>) -> FailedMigrationHandling;
+}
+
+/// Do now allow any transactions to be processed after a runtime upgrade failed.
+///
+/// This is **not a sane default**, since it prevents governance intervention.
+pub struct FreezeChainOnFailedMigration;
+
+impl FailedMigrationHandler for FreezeChainOnFailedMigration {
+	fn failed(_migration: Option<u32>) -> FailedMigrationHandling {
+		FailedMigrationHandling::KeepStuck
+	}
+}
+
+/// Enter safe mode on a failed runtime upgrade.
+///
+/// This can be very useful to manually intervene and fix the chain state. `Else` is used in case
+/// that the safe mode could not be entered.
+pub struct EnterSafeModeOnFailedMigration<SM, Else: FailedMigrationHandler>(
+	PhantomData<(SM, Else)>,
+);
+
+impl<Else: FailedMigrationHandler, SM: SafeMode> FailedMigrationHandler
+	for EnterSafeModeOnFailedMigration<SM, Else>
+where
+	<SM as SafeMode>::BlockNumber: Bounded,
+{
+	fn failed(migration: Option<u32>) -> FailedMigrationHandling {
+		let entered = if SM::is_entered() {
+			SM::extend(Bounded::max_value())
+		} else {
+			SM::enter(Bounded::max_value())
+		};
+
+		// If we could not enter or extend safe mode (for whatever reason), then we try the next.
+		if entered.is_err() {
+			Else::failed(migration)
+		} else {
+			FailedMigrationHandling::KeepStuck
+		}
+	}
+}
+
+/// How to proceed after a runtime upgrade failed.
+///
+/// There is NO SANE DEFAULT HERE. All options are very dangerous and should be used with care.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum FailedMigrationHandling {
+	/// Resume extrinsic processing of the chain. This will not resume the upgrade.
+	///
+	/// This should be supplemented with additional measures to ensure that the broken chain state
+	/// does not get further messed up by user extrinsics.
+	ForceUnstuck,
+	/// Set the cursor to `Stuck` and keep blocking extrinsics.
+	KeepStuck,
+	/// Don't do anything with the cursor and let the handler decide.
+	///
+	/// This can be useful in cases where the other two options would overwrite any changes that
+	/// were done by the handler to the cursor.
+	Ignore,
+}
+
+/// Something that can do multi step migrations.
+pub trait MultiStepMigrator {
+	/// Hint for whether [`Self::step`] should be called.
+	fn ongoing() -> bool;
+
+	/// Do the next step in the MBM process.
+	///
+	/// Must gracefully handle the case that it is currently not upgrading.
+	fn step() -> Weight;
+}
+
+impl MultiStepMigrator for () {
+	fn ongoing() -> bool {
+		false
+	}
+
+	fn step() -> Weight {
+		Weight::zero()
+	}
+}
+
+/// Multiple [`SteppedMigration`].
+pub trait SteppedMigrations {
+	/// The number of migrations that `Self` aggregates.
+	fn len() -> u32;
+
+	/// The `n`th [`SteppedMigration::id`].
+	///
+	/// Is guaranteed to return `Some` if `n < Self::len()`.
+	fn nth_id(n: u32) -> Option<Vec<u8>>;
+
+	/// The [`SteppedMigration::max_steps`] of the `n`th migration.
+	///
+	/// Is guaranteed to return `Some` if `n < Self::len()`.
+	fn nth_max_steps(n: u32) -> Option<Option<u32>>;
+
+	/// Do a [`SteppedMigration::step`] on the `n`th migration.
+	///
+	/// Is guaranteed to return `Some` if `n < Self::len()`.
+	fn nth_step(
+		n: u32,
+		cursor: Option<Vec<u8>>,
+		meter: &mut WeightMeter,
+	) -> Option<Result<Option<Vec<u8>>, SteppedMigrationError>>;
+
+	/// Do a [`SteppedMigration::transactional_step`] on the `n`th migration.
+	///
+	/// Is guaranteed to return `Some` if `n < Self::len()`.
+	fn nth_transactional_step(
+		n: u32,
+		cursor: Option<Vec<u8>>,
+		meter: &mut WeightMeter,
+	) -> Option<Result<Option<Vec<u8>>, SteppedMigrationError>>;
+
+	/// The maximal encoded length across all cursors.
+	fn cursor_max_encoded_len() -> usize;
+
+	/// The maximal encoded length across all identifiers.
+	fn identifier_max_encoded_len() -> usize;
+
+	/// Assert the integrity of the migrations.
+	///
+	/// Should be executed as part of a test prior to runtime usage. May or may not need
+	/// externalities.
+	#[cfg(feature = "std")]
+	fn integrity_test() -> Result<(), &'static str> {
+		use crate::ensure;
+		let l = Self::len();
+
+		for n in 0..l {
+			ensure!(Self::nth_id(n).is_some(), "id is None");
+			ensure!(Self::nth_max_steps(n).is_some(), "steps is None");
+
+			// The cursor that we use does not matter. Hence use empty.
+			ensure!(
+				Self::nth_step(n, Some(vec![]), &mut WeightMeter::new()).is_some(),
+				"steps is None"
+			);
+			ensure!(
+				Self::nth_transactional_step(n, Some(vec![]), &mut WeightMeter::new()).is_some(),
+				"steps is None"
+			);
+		}
+
+		Ok(())
+	}
+}
+
+impl SteppedMigrations for () {
+	fn len() -> u32 {
+		0
+	}
+
+	fn nth_id(_n: u32) -> Option<Vec<u8>> {
+		None
+	}
+
+	fn nth_max_steps(_n: u32) -> Option<Option<u32>> {
+		None
+	}
+
+	fn nth_step(
+		_n: u32,
+		_cursor: Option<Vec<u8>>,
+		_meter: &mut WeightMeter,
+	) -> Option<Result<Option<Vec<u8>>, SteppedMigrationError>> {
+		None
+	}
+
+	fn nth_transactional_step(
+		_n: u32,
+		_cursor: Option<Vec<u8>>,
+		_meter: &mut WeightMeter,
+	) -> Option<Result<Option<Vec<u8>>, SteppedMigrationError>> {
+		None
+	}
+
+	fn cursor_max_encoded_len() -> usize {
+		0
+	}
+
+	fn identifier_max_encoded_len() -> usize {
+		0
+	}
+}
+
+// A collection consisting of only a single migration.
+impl<T: SteppedMigration> SteppedMigrations for T {
+	fn len() -> u32 {
+		1
+	}
+
+	fn nth_id(_n: u32) -> Option<Vec<u8>> {
+		Some(T::id().encode())
+	}
+
+	fn nth_max_steps(n: u32) -> Option<Option<u32>> {
+		// It should be generally fine to call with n>0, but the code should not attempt to.
+		n.is_zero()
+			.then_some(T::max_steps())
+			.defensive_proof("nth_max_steps should only be called with n==0")
+	}
+
+	fn nth_step(
+		_n: u32,
+		cursor: Option<Vec<u8>>,
+		meter: &mut WeightMeter,
+	) -> Option<Result<Option<Vec<u8>>, SteppedMigrationError>> {
+		if !_n.is_zero() {
+			defensive!("nth_step should only be called with n==0");
+			return None
+		}
+
+		let cursor = match cursor {
+			Some(cursor) => match T::Cursor::decode(&mut &cursor[..]) {
+				Ok(cursor) => Some(cursor),
+				Err(_) => return Some(Err(SteppedMigrationError::InvalidCursor)),
+			},
+			None => None,
+		};
+
+		Some(T::step(cursor, meter).map(|cursor| cursor.map(|cursor| cursor.encode())))
+	}
+
+	fn nth_transactional_step(
+		n: u32,
+		cursor: Option<Vec<u8>>,
+		meter: &mut WeightMeter,
+	) -> Option<Result<Option<Vec<u8>>, SteppedMigrationError>> {
+		if n != 0 {
+			defensive!("nth_transactional_step should only be called with n==0");
+			return None
+		}
+
+		let cursor = match cursor {
+			Some(cursor) => match T::Cursor::decode(&mut &cursor[..]) {
+				Ok(cursor) => Some(cursor),
+				Err(_) => return Some(Err(SteppedMigrationError::InvalidCursor)),
+			},
+			None => None,
+		};
+
+		Some(
+			T::transactional_step(cursor, meter).map(|cursor| cursor.map(|cursor| cursor.encode())),
+		)
+	}
+
+	fn cursor_max_encoded_len() -> usize {
+		T::Cursor::max_encoded_len()
+	}
+
+	fn identifier_max_encoded_len() -> usize {
+		T::Identifier::max_encoded_len()
+	}
+}
+
+#[impl_trait_for_tuples::impl_for_tuples(1, 30)]
+impl SteppedMigrations for Tuple {
+	fn len() -> u32 {
+		for_tuples!( #( Tuple::len() )+* )
+	}
+
+	fn nth_id(n: u32) -> Option<Vec<u8>> {
+		let mut i = 0;
+
+		for_tuples!( #(
+			if (i + Tuple::len()) > n {
+				return Tuple::nth_id(n - i)
+			}
+
+			i += Tuple::len();
+		)* );
+
+		None
+	}
+
+	fn nth_step(
+		n: u32,
+		cursor: Option<Vec<u8>>,
+		meter: &mut WeightMeter,
+	) -> Option<Result<Option<Vec<u8>>, SteppedMigrationError>> {
+		let mut i = 0;
+
+		for_tuples!( #(
+			if (i + Tuple::len()) > n {
+				return Tuple::nth_step(n - i, cursor, meter)
+			}
+
+			i += Tuple::len();
+		)* );
+
+		None
+	}
+
+	fn nth_transactional_step(
+		n: u32,
+		cursor: Option<Vec<u8>>,
+		meter: &mut WeightMeter,
+	) -> Option<Result<Option<Vec<u8>>, SteppedMigrationError>> {
+		let mut i = 0;
+
+		for_tuples! ( #(
+			if (i + Tuple::len()) > n {
+				return Tuple::nth_transactional_step(n - i, cursor, meter)
+			}
+
+			i += Tuple::len();
+		)* );
+
+		None
+	}
+
+	fn nth_max_steps(n: u32) -> Option<Option<u32>> {
+		let mut i = 0;
+
+		for_tuples!( #(
+			if (i + Tuple::len()) > n {
+				return Tuple::nth_max_steps(n - i)
+			}
+
+			i += Tuple::len();
+		)* );
+
+		None
+	}
+
+	fn cursor_max_encoded_len() -> usize {
+		let mut max_len = 0;
+
+		for_tuples!( #(
+			max_len = max_len.max(Tuple::cursor_max_encoded_len());
+		)* );
+
+		max_len
+	}
+
+	fn identifier_max_encoded_len() -> usize {
+		let mut max_len = 0;
+
+		for_tuples!( #(
+			max_len = max_len.max(Tuple::identifier_max_encoded_len());
+		)* );
+
+		max_len
+	}
+}
+
+#[cfg(test)]
+mod tests {
+	use super::*;
+	use crate::{assert_ok, storage::unhashed};
+
+	#[derive(Decode, Encode, MaxEncodedLen, Eq, PartialEq)]
+	pub enum Either<L, R> {
+		Left(L),
+		Right(R),
+	}
+
+	pub struct M0;
+	impl SteppedMigration for M0 {
+		type Cursor = ();
+		type Identifier = u8;
+
+		fn id() -> Self::Identifier {
+			0
+		}
+
+		fn step(
+			_cursor: Option<Self::Cursor>,
+			_meter: &mut WeightMeter,
+		) -> Result<Option<Self::Cursor>, SteppedMigrationError> {
+			log::info!("M0");
+			unhashed::put(&[0], &());
+			Ok(None)
+		}
+	}
+
+	pub struct M1;
+	impl SteppedMigration for M1 {
+		type Cursor = ();
+		type Identifier = u8;
+
+		fn id() -> Self::Identifier {
+			1
+		}
+
+		fn step(
+			_cursor: Option<Self::Cursor>,
+			_meter: &mut WeightMeter,
+		) -> Result<Option<Self::Cursor>, SteppedMigrationError> {
+			log::info!("M1");
+			unhashed::put(&[1], &());
+			Ok(None)
+		}
+
+		fn max_steps() -> Option<u32> {
+			Some(1)
+		}
+	}
+
+	pub struct M2;
+	impl SteppedMigration for M2 {
+		type Cursor = ();
+		type Identifier = u8;
+
+		fn id() -> Self::Identifier {
+			2
+		}
+
+		fn step(
+			_cursor: Option<Self::Cursor>,
+			_meter: &mut WeightMeter,
+		) -> Result<Option<Self::Cursor>, SteppedMigrationError> {
+			log::info!("M2");
+			unhashed::put(&[2], &());
+			Ok(None)
+		}
+
+		fn max_steps() -> Option<u32> {
+			Some(2)
+		}
+	}
+
+	pub struct F0;
+	impl SteppedMigration for F0 {
+		type Cursor = ();
+		type Identifier = u8;
+
+		fn id() -> Self::Identifier {
+			3
+		}
+
+		fn step(
+			_cursor: Option<Self::Cursor>,
+			_meter: &mut WeightMeter,
+		) -> Result<Option<Self::Cursor>, SteppedMigrationError> {
+			log::info!("F0");
+			unhashed::put(&[3], &());
+			Err(SteppedMigrationError::Failed)
+		}
+	}
+
+	// Three migrations combined to execute in order:
+	type Triple = (M0, (M1, M2));
+	// Six migrations, just concatenating the ones from before:
+	type Hextuple = (Triple, Triple);
+
+	#[test]
+	fn singular_migrations_work() {
+		assert_eq!(M0::max_steps(), None);
+		assert_eq!(M1::max_steps(), Some(1));
+		assert_eq!(M2::max_steps(), Some(2));
+
+		assert_eq!(<(M0, M1)>::nth_max_steps(0), Some(None));
+		assert_eq!(<(M0, M1)>::nth_max_steps(1), Some(Some(1)));
+		assert_eq!(<(M0, M1, M2)>::nth_max_steps(2), Some(Some(2)));
+
+		assert_eq!(<(M0, M1)>::nth_max_steps(2), None);
+	}
+
+	#[test]
+	fn tuple_migrations_work() {
+		assert_eq!(<() as SteppedMigrations>::len(), 0);
+		assert_eq!(<((), ((), ())) as SteppedMigrations>::len(), 0);
+		assert_eq!(<Triple as SteppedMigrations>::len(), 3);
+		assert_eq!(<Hextuple as SteppedMigrations>::len(), 6);
+
+		// Check the IDs. The index specific functions all return an Option,
+		// to account for the out-of-range case.
+		assert_eq!(<Triple as SteppedMigrations>::nth_id(0), Some(0u8.encode()));
+		assert_eq!(<Triple as SteppedMigrations>::nth_id(1), Some(1u8.encode()));
+		assert_eq!(<Triple as SteppedMigrations>::nth_id(2), Some(2u8.encode()));
+
+		sp_io::TestExternalities::default().execute_with(|| {
+			for n in 0..3 {
+				<Triple as SteppedMigrations>::nth_step(
+					n,
+					Default::default(),
+					&mut WeightMeter::new(),
+				);
+			}
+		});
+	}
+
+	#[test]
+	fn integrity_test_works() {
+		sp_io::TestExternalities::default().execute_with(|| {
+			assert_ok!(<() as SteppedMigrations>::integrity_test());
+			assert_ok!(<M0 as SteppedMigrations>::integrity_test());
+			assert_ok!(<M1 as SteppedMigrations>::integrity_test());
+			assert_ok!(<M2 as SteppedMigrations>::integrity_test());
+			assert_ok!(<Triple as SteppedMigrations>::integrity_test());
+			assert_ok!(<Hextuple as SteppedMigrations>::integrity_test());
+		});
+	}
+
+	#[test]
+	fn transactional_rollback_works() {
+		sp_io::TestExternalities::default().execute_with(|| {
+			assert_ok!(<(M0, F0) as SteppedMigrations>::nth_transactional_step(
+				0,
+				Default::default(),
+				&mut WeightMeter::new()
+			)
+			.unwrap());
+			assert!(unhashed::exists(&[0]));
+
+			let _g = crate::StorageNoopGuard::new();
+			assert!(<(M0, F0) as SteppedMigrations>::nth_transactional_step(
+				1,
+				Default::default(),
+				&mut WeightMeter::new()
+			)
+			.unwrap()
+			.is_err());
+			assert!(<(F0, M1) as SteppedMigrations>::nth_transactional_step(
+				0,
+				Default::default(),
+				&mut WeightMeter::new()
+			)
+			.unwrap()
+			.is_err());
+		});
+	}
+}
@@ -127,6 +127,22 @@ where
 	}
 }

+/// Same as [`with_transaction`] but casts any internal error to `()`.
+///
+/// This rids `E` of the `From<DispatchError>` bound that is required by `with_transaction`.
+pub fn with_transaction_opaque_err<T, E, F>(f: F) -> Result<Result<T, E>, ()>
+where
+	F: FnOnce() -> TransactionOutcome<Result<T, E>>,
+{
+	with_transaction(move || -> TransactionOutcome<Result<Result<T, E>, DispatchError>> {
+		match f() {
+			TransactionOutcome::Commit(res) => TransactionOutcome::Commit(Ok(res)),
+			TransactionOutcome::Rollback(res) => TransactionOutcome::Rollback(Ok(res)),
+		}
+	})
+	.map_err(|_| ())
+}
+
 /// Same as [`with_transaction`] but without a limit check on nested transactional layers.
 ///
 /// This is mostly for backwards compatibility before there was a transactional layer limit.
@@ -59,10 +59,10 @@ pub use misc::{
 	AccountTouch, Backing, ConstBool, ConstI128, ConstI16, ConstI32, ConstI64, ConstI8, ConstU128,
 	ConstU16, ConstU32, ConstU64, ConstU8, DefensiveMax, DefensiveMin, DefensiveSaturating,
 	DefensiveTruncateFrom, EnsureInherentsAreFirst, EqualPrivilegeOnly, EstimateCallFee,
-	ExecuteBlock, ExtrinsicCall, Get, GetBacking, GetDefault, HandleLifetime, IsSubType, IsType,
-	Len, OffchainWorker, OnKilledAccount, OnNewAccount, PrivilegeCmp, SameOrOther, Time,
-	TryCollect, TryDrop, TypedGet, UnixTime, VariantCount, VariantCountOf, WrapperKeepOpaque,
-	WrapperOpaque,
+	ExecuteBlock, ExtrinsicCall, Get, GetBacking, GetDefault, HandleLifetime, IsInherent,
+	IsSubType, IsType, Len, OffchainWorker, OnKilledAccount, OnNewAccount, PrivilegeCmp,
+	SameOrOther, Time, TryCollect, TryDrop, TypedGet, UnixTime, VariantCount, VariantCountOf,
+	WrapperKeepOpaque, WrapperOpaque,
 };
 #[allow(deprecated)]
 pub use misc::{PreimageProvider, PreimageRecipient};
@@ -86,7 +86,8 @@ mod hooks;
 pub use hooks::GenesisBuild;
 pub use hooks::{
 	BeforeAllRuntimeMigrations, BuildGenesisConfig, Hooks, IntegrityTest, OnFinalize, OnGenesis,
-	OnIdle, OnInitialize, OnRuntimeUpgrade, OnTimestampSet,
+	OnIdle, OnInitialize, OnPoll, OnRuntimeUpgrade, OnTimestampSet, PostInherents,
+	PostTransactions, PreInherents,
 };

 pub mod schedule;
@@ -25,10 +25,74 @@ use crate::weights::Weight;
 use impl_trait_for_tuples::impl_for_tuples;
 use sp_runtime::traits::AtLeast32BitUnsigned;
 use sp_std::prelude::*;
+use sp_weights::WeightMeter;

 #[cfg(feature = "try-runtime")]
 use sp_runtime::TryRuntimeError;

+/// Provides a callback to execute logic before the all inherents.
+pub trait PreInherents {
+	/// Called before all inherents were applied but after `on_initialize`.
+	fn pre_inherents() {}
+}
+
+#[cfg_attr(all(not(feature = "tuples-96"), not(feature = "tuples-128")), impl_for_tuples(64))]
+#[cfg_attr(all(feature = "tuples-96", not(feature = "tuples-128")), impl_for_tuples(96))]
+#[cfg_attr(feature = "tuples-128", impl_for_tuples(128))]
+impl PreInherents for Tuple {
+	fn pre_inherents() {
+		for_tuples!( #( Tuple::pre_inherents(); )* );
+	}
+}
+
+/// Provides a callback to execute logic after the all inherents.
+pub trait PostInherents {
+	/// Called after all inherents were applied.
+	fn post_inherents() {}
+}
+
+#[cfg_attr(all(not(feature = "tuples-96"), not(feature = "tuples-128")), impl_for_tuples(64))]
+#[cfg_attr(all(feature = "tuples-96", not(feature = "tuples-128")), impl_for_tuples(96))]
+#[cfg_attr(feature = "tuples-128", impl_for_tuples(128))]
+impl PostInherents for Tuple {
+	fn post_inherents() {
+		for_tuples!( #( Tuple::post_inherents(); )* );
+	}
+}
+
+/// Provides a callback to execute logic before the all transactions.
+pub trait PostTransactions {
+	/// Called after all transactions were applied but before `on_finalize`.
+	fn post_transactions() {}
+}
+
+#[cfg_attr(all(not(feature = "tuples-96"), not(feature = "tuples-128")), impl_for_tuples(64))]
+#[cfg_attr(all(feature = "tuples-96", not(feature = "tuples-128")), impl_for_tuples(96))]
+#[cfg_attr(feature = "tuples-128", impl_for_tuples(128))]
+impl PostTransactions for Tuple {
+	fn post_transactions() {
+		for_tuples!( #( Tuple::post_transactions(); )* );
+	}
+}
+
+/// Periodically executes logic. Is not guaranteed to run within a specific timeframe and should
+/// only be used on logic that has no deadline.
+pub trait OnPoll<BlockNumber> {
+	/// Code to execute every now and then at the beginning of the block after inherent application.
+	///
+	/// The remaining weight limit must be respected.
+	fn on_poll(_n: BlockNumber, _weight: &mut WeightMeter) {}
+}
+
+#[cfg_attr(all(not(feature = "tuples-96"), not(feature = "tuples-128")), impl_for_tuples(64))]
+#[cfg_attr(all(feature = "tuples-96", not(feature = "tuples-128")), impl_for_tuples(96))]
+#[cfg_attr(feature = "tuples-128", impl_for_tuples(128))]
+impl<BlockNumber: Clone> OnPoll<BlockNumber> for Tuple {
+	fn on_poll(n: BlockNumber, weight: &mut WeightMeter) {
+		for_tuples!( #( Tuple::on_poll(n.clone(), weight); )* );
+	}
+}
+
 /// See [`Hooks::on_initialize`].
 pub trait OnInitialize<BlockNumber> {
 	/// See [`Hooks::on_initialize`].
@@ -374,6 +438,12 @@ pub trait Hooks<BlockNumber> {
 		Weight::zero()
 	}

+	/// A hook to run logic after inherent application.
+	///
+	/// Is not guaranteed to execute in a block and should therefore only be used in no-deadline
+	/// scenarios.
+	fn on_poll(_n: BlockNumber, _weight: &mut WeightMeter) {}
+
 	/// Hook executed when a code change (aka. a "runtime upgrade") is detected by the FRAME
 	/// `Executive` pallet.
 	///
@@ -23,6 +23,7 @@ use impl_trait_for_tuples::impl_for_tuples;
 use scale_info::{build::Fields, meta_type, Path, Type, TypeInfo, TypeParameter};
 use sp_arithmetic::traits::{CheckedAdd, CheckedMul, CheckedSub, One, Saturating};
 use sp_core::bounded::bounded_vec::TruncateFrom;
+
 #[doc(hidden)]
 pub use sp_runtime::traits::{
 	ConstBool, ConstI128, ConstI16, ConstI32, ConstI64, ConstI8, ConstU128, ConstU16, ConstU32,
@@ -895,11 +896,21 @@ pub trait GetBacking {
 /// A trait to ensure the inherent are before non-inherent in a block.
 ///
 /// This is typically implemented on runtime, through `construct_runtime!`.
-pub trait EnsureInherentsAreFirst<Block> {
+pub trait EnsureInherentsAreFirst<Block: sp_runtime::traits::Block>:
+	IsInherent<<Block as sp_runtime::traits::Block>::Extrinsic>
+{
 	/// Ensure the position of inherent is correct, i.e. they are before non-inherents.
 	///
-	/// On error return the index of the inherent with invalid position (counting from 0).
-	fn ensure_inherents_are_first(block: &Block) -> Result<(), u32>;
+	/// On error return the index of the inherent with invalid position (counting from 0). On
+	/// success it returns the index of the last inherent. `0` therefore means that there are no
+	/// inherents.
+	fn ensure_inherents_are_first(block: &Block) -> Result<u32, u32>;
+}
+
+/// A trait to check if an extrinsic is an inherent.
+pub trait IsInherent<Extrinsic> {
+	/// Whether this extrinsic is an inherent.
+	fn is_inherent(ext: &Extrinsic) -> bool;
 }

 /// An extrinsic on which we can get access to call.