// This file is part of Substrate.

// Copyright (C) Parity Technologies (UK) Ltd.

// SPDX-License-Identifier: Apache-2.0

// Licensed under the Apache License, Version 2.0 (the "License");

// you may not use this file except in compliance with the License.

// You may obtain a copy of the License at

//

// 	http://www.apache.org/licenses/LICENSE-2.0

//

// Unless required by applicable law or agreed to in writing, software

// distributed under the License is distributed on an "AS IS" BASIS,

// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

// See the License for the specific language governing permissions and

// limitations under the License.

#![deny(missing_docs)]

#![deny(rustdoc::broken_intra_doc_links)]

//! # `pallet-migrations`

//!

//! Provides multi block migrations for FRAME runtimes.

//!

//! ## Overview

//!

//! The pallet takes care of executing a batch of multi-step migrations over multiple blocks. The

//! process starts on each runtime upgrade. Normal and operational transactions are paused while

//! migrations are on-going.

//!

//! ### Example

//!

//! This example demonstrates a simple mocked walk through of a basic success scenario. The pallet

//! is configured with two migrations: one succeeding after just one step, and the second one

//! succeeding after two steps. A runtime upgrade is then enacted and the block number is advanced

//! until all migrations finish executing. Afterwards, the recorded historic migrations are

//! checked and events are asserted.

#![doc = docify::embed!("src/tests.rs", simple_works)]

//!

//! ## Pallet API

//!

//! See the [`pallet`] module for more information about the interfaces this pallet exposes,

//! including its configuration trait, dispatchables, storage items, events and errors.

//!

//! Otherwise noteworthy API of this pallet include its implementation of the

//! [`MultiStepMigrator`] trait. This must be plugged into

//! [`frame_system::Config::MultiBlockMigrator`] for proper function.

//!

//! The API contains some calls for emergency management. They are all prefixed with `force_` and

//! should normally not be needed. Pay special attention prior to using them.

//!

//! ### Design Goals

//!

//! 1. Must automatically execute migrations over multiple blocks.

//! 2. Must expose information about whether migrations are ongoing.

//! 3. Must respect pessimistic weight bounds of migrations.

//! 4. Must execute migrations in order. Skipping is not allowed; migrations are run on a

//! all-or-nothing basis.

//! 5. Must prevent re-execution of past migrations.

//! 6. Must provide transactional storage semantics for migrations.

//! 7. Must guarantee progress.

//!

//! ### Design

//!

//! Migrations are provided to the pallet through the associated type [`Config::Migrations`] of type

//! [`SteppedMigrations`]. This allows multiple migrations to be aggregated through a tuple. It

//! simplifies the trait bounds since all associated types of the trait must be provided by the

//! pallet. The actual progress of the pallet is stored in the [`Cursor`] storage item. This can

//! either be [`MigrationCursor::Active`] or [`MigrationCursor::Stuck`]. In the active case it

//! points to the currently active migration and stores its inner cursor. The inner cursor can then

//! be used by the migration to store its inner state and advance. Each time when the migration

//! returns `Some(cursor)`, it signals the pallet that it is not done yet.

//! The cursor is reset on each runtime upgrade. This ensures that it starts to execute at the

//! first migration in the vector. The pallets cursor is only ever incremented or set to `Stuck`

//! once it encounters an error (Goal 4). Once in the stuck state, the pallet will stay stuck until

//! it is fixed through manual governance intervention.

//! As soon as the cursor of the pallet becomes `Some(_)`; [`MultiStepMigrator::ongoing`] returns

//! `true` (Goal 2). This can be used by upstream code to possibly pause transactions.

//! In `on_initialize` the pallet will load the current migration and check whether it was already

//! executed in the past by checking for membership of its ID in the [`Historic`] set. Historic

//! migrations are skipped without causing an error. Each successfully executed migration is added

//! to this set (Goal 5).

//! This proceeds until no more migrations remain. At that point, the event `UpgradeCompleted` is

//! emitted (Goal 1).

//! The execution of each migration happens by calling [`SteppedMigration::transactional_step`].

//! This function wraps the inner `step` function into a transactional layer to allow rollback in

//! the error case (Goal 6).

//! Weight limits must be checked by the migration itself. The pallet provides a [`WeightMeter`] for

//! that purpose. The pallet may return [`SteppedMigrationError::InsufficientWeight`] at any point.

//! In that scenario, one of two things will happen: if that migration was exclusively executed

//! in this block, and therefore required more than the maximum amount of weight possible, the

//! process becomes `Stuck`. Otherwise, one re-attempt is executed with the same logic in the next

//! block (Goal 3). Progress through the migrations is guaranteed by providing a timeout for each

//! migration via [`SteppedMigration::max_steps`]. The pallet **ONLY** guarantees progress if this

//! is set to sensible limits (Goal 7).

//!

//! ### Scenario: Governance cleanup

//!

//! Every now and then, governance can make use of the [`clear_historic`][Pallet::clear_historic]

//! call. This ensures that no old migrations pile up in the [`Historic`] set. This can be done very

//! rarely, since the storage should not grow quickly and the lookup weight does not suffer much.

//! Another possibility would be to have a synchronous single-block migration perpetually deployed

//! that cleans them up before the MBMs start.

//!

//! ### Scenario: Successful upgrade

//!

//! The standard procedure for a successful runtime upgrade can look like this:

//! 1. Migrations are configured in the `Migrations` config item. All migrations expose

//! [`max_steps`][SteppedMigration::max_steps], are error tolerant, check their weight bounds and

//! have a unique identifier.

//! 2. The runtime upgrade is enacted. An `UpgradeStarted` event is

//! followed by lots of `MigrationAdvanced` and `MigrationCompleted` events. Finally

//! `UpgradeCompleted` is emitted.

//! 3. Cleanup as described in the governance scenario be executed at any time after the migrations

//! completed.

//!

//! ### Advice: Failed upgrades

//!

//! Failed upgrades cannot be recovered from automatically and require governance intervention. Set

//! up monitoring for `UpgradeFailed` events to be made aware of any failures. The hook

//! [`FailedMigrationHandler::failed`] should be setup in a way that it allows governance to act,

//! but still prevent other transactions from interacting with the inconsistent storage state. Note

//! that this is paramount, since the inconsistent state might contain a faulty balance amount or

//! similar that could cause great harm if user transactions don't remain suspended. One way to

//! implement this would be to use the `SafeMode` or `TxPause` pallets that can prevent most user

//! interactions but still allow a whitelisted set of governance calls.

//!

//! ### Remark: Failed migrations

//!

//! Failed migrations are not added to the `Historic` set. This means that an erroneous

//! migration must be removed and fixed manually. This already applies, even before considering the

//! historic set.

//!

//! ### Remark: Transactional processing

//!

//! You can see the transactional semantics for migration steps as mostly useless, since in the

//! stuck case the state is already messed up. This just prevents it from becoming even more messed

//! up, but doesn't prevent it in the first place.

#![cfg_attr(not(feature = "std"), no_std)]

mod benchmarking;

mod mock;

pub mod mock_helpers;

mod tests;

pub mod weights;

extern crate alloc;

pub use pallet::*;

pub use weights::WeightInfo;

use alloc::vec::Vec;

use codec::{Decode, Encode, MaxEncodedLen};

use core::ops::ControlFlow;

use frame_support::{

	defensive, defensive_assert,

	migrations::*,

	traits::Get,

	weights::{Weight, WeightMeter},

	BoundedVec,

};

use frame_system::{pallet_prelude::BlockNumberFor, Pallet as System};

use sp_runtime::Saturating;

/// Points to the next migration to execute.

pub enum MigrationCursor<Cursor, BlockNumber> {

}

impl<Cursor, BlockNumber> MigrationCursor<Cursor, BlockNumber> {

	/// Try to return self as an [`ActiveCursor`].

		}

}

impl<Cursor, BlockNumber> From<ActiveCursor<Cursor, BlockNumber>>

	for MigrationCursor<Cursor, BlockNumber>

{

}

/// Points to the currently active migration and its inner cursor.

pub struct ActiveCursor<Cursor, BlockNumber> {

	/// The index of the migration in the MBM tuple.

	pub index: u32,

	/// The cursor of the migration that is referenced by `index`.

	pub inner_cursor: Option<Cursor>,

	/// The block number that the migration started at.

	///

	/// This is used to calculate how many blocks it took.

	pub started_at: BlockNumber,

}

impl<Cursor, BlockNumber> ActiveCursor<Cursor, BlockNumber> {

	/// Advance the overarching cursor to the next migration.

}

/// How to clear the records of historic migrations.

pub enum HistoricCleanupSelector<Id> {

	///

	/// This is the advised way of doing it.

	Wildcard {

}

/// The default number of entries that should be cleared by a `HistoricCleanupSelector::Wildcard`.

///

/// The caller can explicitly specify a higher amount. Benchmarks are run with twice this value.

const DEFAULT_HISTORIC_BATCH_CLEAR_SIZE: u32 = 128;

impl<Id> HistoricCleanupSelector<Id> {

	/// The maximal number of entries that this will remove.

	///

	/// Needed for weight calculation.

		}

}

/// Convenience alias for [`MigrationCursor`].

pub type CursorOf<T> = MigrationCursor<RawCursorOf<T>, BlockNumberFor<T>>;

/// Convenience alias for the raw inner cursor of a migration.

pub type RawCursorOf<T> = BoundedVec<u8, <T as Config>::CursorMaxLen>;

/// Convenience alias for the identifier of a migration.

pub type IdentifierOf<T> = BoundedVec<u8, <T as Config>::IdentifierMaxLen>;

/// Convenience alias for [`ActiveCursor`].

pub type ActiveCursorOf<T> = ActiveCursor<RawCursorOf<T>, BlockNumberFor<T>>;

/// Trait for a tuple of No-OP migrations with one element.

pub trait MockedMigrations: SteppedMigrations {

	/// The migration should fail after `n` steps.

	fn set_fail_after(n: u32);

	/// The migration should succeed after `n` steps.

	fn set_success_after(n: u32);

}

pub mod pallet {

	use super::*;

	use frame_support::pallet_prelude::*;

	use frame_system::pallet_prelude::*;

	pub struct Pallet<T>(_);

	#[pallet::config(with_default)]

	pub trait Config: frame_system::Config {

		/// The overarching event type of the runtime.

		#[pallet::no_default_bounds]

		type RuntimeEvent: From<Event<Self>> + IsType<<Self as frame_system::Config>::RuntimeEvent>;

		/// All the multi-block migrations to run.

		///

		/// Should only be updated in a runtime-upgrade once all the old migrations have completed.

		/// (Check that [`Cursor`] is `None`).

		#[cfg(not(feature = "runtime-benchmarks"))]

		#[pallet::no_default]

		type Migrations: SteppedMigrations;

		/// Mocked migrations for benchmarking only.

		///

		/// Should be configured to [`crate::mock_helpers::MockedMigrations`] in benchmarks.

		#[cfg(feature = "runtime-benchmarks")]

		#[pallet::no_default]

		type Migrations: MockedMigrations;

		/// The maximal length of an encoded cursor.

		///

		/// A good default needs to selected such that no migration will ever have a cursor with MEL

		/// above this limit. This is statically checked in `integrity_test`.

		#[pallet::constant]

		type CursorMaxLen: Get<u32>;

		/// The maximal length of an encoded identifier.

		///

		/// A good default needs to selected such that no migration will ever have an identifier

		/// with MEL above this limit. This is statically checked in `integrity_test`.

		#[pallet::constant]

		type IdentifierMaxLen: Get<u32>;

		/// Notifications for status updates of a runtime upgrade.

		///

		/// Could be used to pause XCM etc.

		type MigrationStatusHandler: MigrationStatusHandler;

		/// Handler for failed migrations.

		type FailedMigrationHandler: FailedMigrationHandler;

		/// The maximum weight to spend each block to execute migrations.

		type MaxServiceWeight: Get<Weight>;

		/// Weight information for the calls and functions of this pallet.

		type WeightInfo: WeightInfo;

	}

	/// Default implementations of [`DefaultConfig`], which can be used to implement [`Config`].

	pub mod config_preludes {

		use super::{inject_runtime_type, DefaultConfig};

		use frame_support::{

			derive_impl,

			migrations::FreezeChainOnFailedMigration,

			pallet_prelude::{ConstU32, *},

		};

		use frame_system::limits::BlockWeights;

		/// Provides a viable default config that can be used with

		/// [`derive_impl`](`frame_support::derive_impl`) to derive a testing pallet config

		/// based on this one.

		///

		/// See `Test` in the `default-config` example pallet's `test.rs` for an example of

		/// a downstream user of this particular `TestDefaultConfig`

		pub struct TestDefaultConfig;

		frame_support::parameter_types! {

			/// Maximal weight per block that can be spent on migrations in tests.

			pub TestMaxServiceWeight: Weight = <<TestDefaultConfig as frame_system::DefaultConfig>::BlockWeights as Get<BlockWeights>>::get().max_block.div(2);

		}

		#[derive_impl(frame_system::config_preludes::TestDefaultConfig, no_aggregated_types)]

		impl frame_system::DefaultConfig for TestDefaultConfig {}

		#[frame_support::register_default_impl(TestDefaultConfig)]

		impl DefaultConfig for TestDefaultConfig {

			#[inject_runtime_type]

			type RuntimeEvent = ();

			type CursorMaxLen = ConstU32<{ 1 << 16 }>;

			type IdentifierMaxLen = ConstU32<{ 256 }>;

			type MigrationStatusHandler = ();

			type FailedMigrationHandler = FreezeChainOnFailedMigration;

			type MaxServiceWeight = TestMaxServiceWeight;

			type WeightInfo = ();

		}

	}

	/// The currently active migration to run and its cursor.

	///

	/// `None` indicates that no migration is running.

	pub type Cursor<T: Config> = StorageValue<_, CursorOf<T>, OptionQuery>;

	/// Set of all successfully executed migrations.

	///

	/// This is used as blacklist, to not re-execute migrations that have not been removed from the

	/// codebase yet. Governance can regularly clear this out via `clear_historic`.

	pub type Historic<T: Config> = StorageMap<_, Twox64Concat, IdentifierOf<T>, (), OptionQuery>;

	pub enum Event<T: Config> {

		///

		/// Its end is indicated by `UpgradeCompleted` or `UpgradeFailed`.

		UpgradeStarted {

		MigrationSkipped {

		MigrationAdvanced {

		MigrationCompleted {

		///

		/// This implies that the whole upgrade failed and governance intervention is required.

		MigrationFailed {

		HistoricCleared {

	}

	pub enum Error<T> {

	}

	impl<T: Config> Hooks<BlockNumberFor<T>> for Pallet<T> {

		#[cfg(feature = "std")]

			// Very important! Ensure that the pallet is configured in `System::Config`.

			{

			}

			// Cursor MEL

			{

				);

			}

			// Identifier MEL

			{

				);

			}

	}

	impl<T: Config> Pallet<T> {

		/// Allows root to set a cursor to forcefully start, stop or forward the migration process.

		///

		/// Should normally not be needed and is only in place as emergency measure. Note that

		/// restarting the migration process in this manner will not call the

		/// [`MigrationStatusHandler::started`] hook or emit an `UpgradeStarted` event.

		#[pallet::call_index(0)]

		pub fn force_set_cursor(

			origin: OriginFor<T>,

			cursor: Option<CursorOf<T>>,

		}

		/// Allows root to set an active cursor to forcefully start/forward the migration process.

		///

		/// This is an edge-case version of [`Self::force_set_cursor`] that allows to set the

		/// `started_at` value to the next block number. Otherwise this would not be possible, since

		/// `force_set_cursor` takes an absolute block number. Setting `started_at` to `None`

		/// indicates that the current block number plus one should be used.

		#[pallet::call_index(1)]

		pub fn force_set_active_cursor(

			origin: OriginFor<T>,

			index: u32,

			inner_cursor: Option<RawCursorOf<T>>,

			started_at: Option<BlockNumberFor<T>>,

		}

		/// Forces the onboarding of the migrations.

		///

		/// This process happens automatically on a runtime upgrade. It is in place as an emergency

		/// measurement. The cursor needs to be `None` for this to succeed.

		#[pallet::call_index(2)]

		}

		/// Clears the `Historic` set.

		///

		/// `map_cursor` must be set to the last value that was returned by the

		/// `HistoricCleared` event. The first time `None` can be used. `limit` must be chosen in a

		/// way that will result in a sensible weight.

		#[pallet::call_index(3)]

		#[pallet::weight(T::WeightInfo::clear_historic(selector.limit()))]

		pub fn clear_historic(

			origin: OriginFor<T>,

			selector: HistoricCleanupSelector<IdentifierOf<T>>,

				},

			}

		}

	}

}

impl<T: Config> Pallet<T> {

	/// Onboard all new Multi-Block-Migrations and start the process of executing them.

	///

	/// Should only be called once all previous migrations completed.

	/// Tries to make progress on the Multi-Block-Migrations process.

			None => {

			},

			},

			Some(MigrationCursor::Stuck) => {

			},

		};

		// The limit here is a defensive measure to prevent an infinite loop. It expresses that we

		// allow no more than 8 MBMs to finish in a single block. This should be harmless, since we

		// generally expect *Multi*-Block-Migrations to take *multiple* blocks.

				},

			}

		}

	/// Try to make progress on the current migration.

	///

	/// Returns whether processing should continue or break for this block. The return value means:

	/// - `None`: The migration process is completely finished.

	/// - `ControlFlow::Break`: Continue in the *next* block with the given cursor.

	/// - `ControlFlow::Continue`: Continue in the *current* block with the given cursor.

			// No more migrations in the tuple - we are done.

		};

		};

		};

				};

				} else {

					// A migration cannot progress more than one step per block, we therefore break.

				}

			},

			Ok(None) => {

				// A migration is done when it returns cursor `None`.

			},

				} else {

					// Retry and hope that there is more weight in the next block.

				}

			},

			Err(SteppedMigrationError::InvalidCursor | SteppedMigrationError::Failed) => {

			},

		}

	/// Fail the current runtime upgrade, caused by `migration`.

		use FailedMigrationHandling::*;

		}

	/// The maximal weight of calling the private `Self::exec_migration` function.

}

impl<T: Config> MultiStepMigrator for Pallet<T> {

}