Repository: paritytech/substrate
File: frame/support/src/traits/hooks.rs (Rust)

Code before:
	/// Similar to [`OnInitialize`] it should only be used when execution is absolutely necessary.
	fn on_finalize(_n: BlockNumber) {}

	/// Hook to consume a block's idle time. This will run when the block is being finalized (before
	/// [`on_finalize`]).
	///
	/// Given that all dispatchables are already executed and noted, and the weight for
	/// [`on_finalize`], which comes next, is also already accounted for (via `on_initialize`), this
	/// hook consumes anything that is leftover.
	///
	/// Each pallet's `on_idle` is chosen to be the first to execute in a round-robin fashion
	/// indexed by the block number.
	///
	/// Return the weight used, the caller will use this to calculate the remaining weight and then
	/// call the next pallet `on_idle` hook if there is still weight left.
	///
	/// Any implementation should always respect `_remaining_weight` and never consume (and
	/// therefore return) more than this amount.
	fn on_idle(_n: BlockNumber, _remaining_weight: Weight) -> Weight {
		Weight::zero()
	}

	/// Hook executed when a code change (aka. a "runtime upgrade") is detected by FRAME.
	///
	/// Be aware that this is called before [`on_initialize`] of any pallet, therefore a lot of the
	/// critical storage items such as `block_number` in system pallet might not been set.
	///
	/// Vert similar to [`on_initialize`], any code in this block is mandatory and MUST execute. Use
	/// with care.
	///
	/// ## Implementation Note: Versioning
	///
	/// 1. An implementation of this should typically follow a pattern where the version of the
	/// pallet is checked against the onchain version, and a decision is made about what needs to be
	/// done. This is helpful to prevent accidental repetitive execution of this hook, which can be
	/// catastrophic.
	///
	/// Alternatively, [`migrations::VersionedRuntimeUpgrade`] can be used to assist with this.
	///
	/// ## Implementation Note: Runtime Level Migration
	///
	/// Additional "upgrade hooks" can be created by pallets by a manual implementation of
	/// [`OnRuntimeUpgrade`] which can be passed on to `Executive` at the top level runtime.
	fn on_runtime_upgrade() -> Weight {
		Weight::zero()
	}

	/// Execute the sanity checks of this pallet, per block.
	///
	/// It should focus on certain checks to ensure that the state is sensible. This is never
	/// executed in a consensus code-path, therefore it can consume as much weight as it needs.

Review comment (suggestion):
```suggestion
	/// Be aware that this is called before [`on_initialize`] of any pallet; therefore, a lot of the
	/// critical storage items such as `block_number` in system pallet might have not been set.
```

Code after:
/// * `OnRuntimeUpgrade` is mandatorily at the beginning of the block body (extrinsics) being
///   processed. change is detected.
/// * Extrinsics start with inherents, and continue with other signed or unsigned extrinsics.
/// * `OnIdle` optionally comes after extrinsics.
/// `OnFinalize` mandatorily comes after `OnIdle`.
///
/// > `OffchainWorker` is not part of this flow, as it is not really part of the consensus/main
/// > block import path, and is called optionally, and in other circumstances. See
/// > [`crate::traits::misc::OffchainWorker`] for more information.
///
/// To learn more about the execution of hooks see `frame-executive` as this component is is charge
/// of dispatching extrinsics and placing the hooks in the correct order.
pub trait Hooks<BlockNumber> {
	/// Block initialization hook. This is called at the very beginning of block execution.
	///
	/// Must return the non-negotiable weight of both itself and whatever [`Hooks::on_finalize`]
	/// wishes to consume.
	///
	/// The weight returned by this is treated as `DispatchClass::Mandatory`, meaning that
	/// it MUST BE EXECUTED. If this is not the case, consider using [`Hooks::on_idle`] instead.
	///
	/// NOTE: This function is called BEFORE ANY extrinsic in a block is applied, including inherent
	/// extrinsics. Hence for instance, if you runtime includes `pallet-timestamp`, the `timestamp`
	/// is not yet up to date at this point.
	fn on_initialize(_n: BlockNumber) -> Weight {
		Weight::zero()
	}

	/// Block finalization hook. This is called at the very end of block execution.
	///
	/// Note that this has nothing to do with finality in the "consensus" sense.
	///
	/// Note that the non-negotiable weight for this has must have already been returned by
	/// [`Hooks::on_initialize`]. It usage alone is not permitted.
	///
	/// Similar to [`Hooks::on_initialize`] it should only be used when execution is absolutely
	/// necessary. In other cases, consider using [`Hooks::on_idle`] instead.
	fn on_finalize(_n: BlockNumber) {}

	/// Hook to consume a block's idle time. This will run when the block is being finalized (before
	/// [`Hooks::on_finalize`]).
	///
	/// Given that all dispatchables are already executed and noted (and the weight for
	/// [`Hooks::on_finalize`], which comes next, is also already accounted for via
	/// `on_initialize`), this hook consumes anything that is leftover.
	///
	/// Each pallet's `on_idle` is chosen to be the first to execute in a round-robin fashion
	/// indexed by the block number.
	///
	/// Return the weight used, the caller will use this to calculate the remaining weight and then
	/// call the next pallet `on_idle` hook if there is still weight left.