pallet-migrations Initial Implementation

Cargo.toml

@@ -7,6 +7,7 @@ members = [
     'node',
     'node/cli',
     'node/service',
+    'pallets/migrations',
     'bin/utils/moonkey'
 ]
 exclude = [

pallets/migrations/Cargo.toml

@@ -0,0 +1,29 @@
+[package]
+name = "migrations"
+version = "0.1.0"
+authors = ["PureStake"]
+edition = "2018"
+description = "migrations management pallet"
+
+[dependencies]
+frame-support = { git = "https://github.com/paritytech/substrate", branch = "polkadot-v0.9.4", default-features = false }
+frame-system = { git = "https://github.com/paritytech/substrate", branch = "polkadot-v0.9.4", default-features = false }
+log = "0.4"
+sp-std = { git = "https://github.com/paritytech/substrate", branch = "polkadot-v0.9.4", default-features = false }
+sp-runtime = { git = "https://github.com/paritytech/substrate", branch = "polkadot-v0.9.4", default-features = false }
+parity-scale-codec = { version = "2.0.0", default-features = false }
+
+[dev-dependencies]
+sp-io = { git = "https://github.com/paritytech/substrate", branch = "polkadot-v0.9.4", default-features = false }
+sp-core = { git = "https://github.com/paritytech/substrate", branch = "polkadot-v0.9.4", default-features = false }
+
+[features]
+default = ["std"]
+std = [
+	"frame-support/std",
+	"frame-system/std",
+	"sp-std/std",
+	"sp-runtime/std",
+	"sp-io/std",
+	"sp-core/std",
+]

pallets/migrations/src/lib.rs

@@ -0,0 +1,209 @@
+// Copyright 2019-2020 PureStake Inc.
+// This file is part of Moonbeam.
+
+// Moonbeam is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Moonbeam is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Moonbeam.  If not, see <http://www.gnu.org/licenses/>.
+
+//! # Migration Pallet
+
+#![allow(non_camel_case_types)]
+
+#![cfg_attr(not(feature = "std"), no_std)]
+
+#[cfg(test)]
+mod mock;
+#[cfg(test)]
+mod tests;
+
+use frame_support::{pallet, weights::Weight};
+use sp_runtime::Perbill;
+pub mod migrations;
+
+pub use pallet::*;
+
+/// A Migration that must happen on-chain upon a runtime-upgrade
+pub trait Migration {
+	/// A human-readable name for this migration. Also used as storage key.
+	fn friendly_name(&self) -> &str;
+
+	/// Step through this migration, taking up to `available_weight` of execution time and providing
+	/// a status on the progress as well as the consumed weight. This allows a migration to perform
+	/// its logic in small batches across as many blocks as needed. 
+	/// 
+	/// Implementations should perform as much migration work as possible and then leave their
+	/// pallet in a valid state from which another 'step' of migration work can be performed. In no
+	/// case should a step consume more than `available_weight`.
+	///
+	/// This should return a perbill indicating the aggregate progress of the migration. If
+	/// `Perbill::one()` is returned, the migration is considered complete and no further calls to
+	/// `step()` will be made. Any value less than `Perbill::one()` will result in another future
+	/// call to `step()`. Indeed, values < 1 are arbitrary, but the intent is to indicate progress
+	/// (so they should at least be monotonically increasing).
+	fn step(&self, previous_progress: Perbill, available_weight: Weight) -> (Perbill, Weight);
+}
+
+/// Our list of migrations. Any ordering considerations can be specified here (?).
+const MIGRATIONS: [&dyn Migration; 3] = [
+	&migrations::MM_001_AuthorMappingAddDeposit {},
+	&migrations::MM_002_StakingFixTotalBalance {},
+	&migrations::MM_003_StakingTransitionBoundedSet {},
+];
+
+#[pallet]
+pub mod pallet {
+	use super::*;
+	use frame_support::pallet_prelude::*;
+	use frame_system::pallet_prelude::*;
+	#[allow(unused_imports)] // TODO: why does it detect this as unused?
+	use sp_std::prelude::*;
+
+	/// Pallet for migrations
+	#[pallet::pallet]
+	pub struct Pallet<T>(PhantomData<T>);
+
+	/// Configuration trait of this pallet.
+	#[pallet::config]
+	pub trait Config: frame_system::Config {
+		/// Overarching event type
+		type Event: From<Event<Self>> + IsType<<Self as frame_system::Config>::Event>;
+	}
+
+	#[pallet::event]
+	pub enum Event<T: Config> {
+		// e.g. runtime upgrade started, completed, etc.
+		RuntimeUpgradeStarted,
+		RuntimeUpgradeCompleted,
+		MigrationStarted(String),
+		MigrationProgress(String, Perbill),
+		MigrationCompleted(String),
+	}
+
+	#[pallet::hooks]
+	impl<T: Config> Hooks<BlockNumberFor<T>> for Pallet<T> {
+
+		/// on_runtime_upgrade is expected to be called exactly once after a runtime upgrade.
+		/// We use this as a chance to flag that we are now in upgrade-mode and begin our
+		/// migrations.
+		/// 
+		/// In the event that a migration is expected to take more than one block, ongoing migration
+		/// work could continue from block-to-block in this pallet's on_initialize function.
+		fn on_runtime_upgrade() -> Weight {
+			log::warn!("Performing on_runtime_upgrade");
+
+			// start by flagging that we are not fully upgraded
+			<FullyUpgraded<T>>::put(false);
+
+			let mut weight: Weight = 0u64.into();
+
+			weight += process_runtime_upgrades::<T>();
+
+			weight.into()
+		}
+	}
+
+	#[pallet::storage]
+	#[pallet::getter(fn is_fully_upgraded)]
+	/// True if all required migrations have completed
+	type FullyUpgraded<T: Config> = StorageValue<_, bool, ValueQuery>;
+
+	#[pallet::storage]
+	#[pallet::getter(fn migration_state)]
+	/// MigrationState tracks the progress of a migration.
+	type MigrationState<T: Config> = StorageMap<
+		_,
+		Twox64Concat,
+		String,
+		Perbill,
+		OptionQuery, // TODO: what is this...?
+	>;
+
+	#[pallet::genesis_config]
+	pub struct GenesisConfig<T: Config> {
+		pub completed_migrations: Vec<String>,
+		pub dummy: PhantomData<T> // TODO: 
+	}
+
+	#[cfg(feature = "std")]
+	impl<T: Config> Default for GenesisConfig<T> {
+		fn default() -> Self {
+			Self {
+				completed_migrations: vec![],
+				dummy: PhantomData,
+			}
+		}
+	}
+
+	#[pallet::genesis_build]
+	impl<T: Config> GenesisBuild<T> for GenesisConfig<T> {
+		fn build(&self) {
+			for migration_name in &self.completed_migrations {
+				<MigrationState<T>>::insert(migration_name, Perbill::one());
+			}
+		}
+	}
+
+	fn process_runtime_upgrades<T: Config>() -> Weight {
+		log::info!("stepping runtime upgrade");
+
+		// TODO: query proper value or make configurable
+		let available_weight = 500_000_000_000u64.into();
+		let mut weight: Weight = 0u64.into();
+		let mut done: bool = true;
+
+		for migration in &MIGRATIONS {
+
+			// let migration_name = migration.friendly_name();
+			let migration_name = migration.friendly_name();
+			log::trace!("evaluating migration {}", migration_name);
+
+			let migration_state = <MigrationState<T>>::get(migration_name)
+				.unwrap_or(Perbill::zero());
+
+			if migration_state < Perbill::one() {
+
+				let available_for_step = available_weight - weight;
+				log::trace!("stepping migration {}, prev: {:?}, avail weight: {}",
+					migration_name, migration_state, available_for_step);
+
+				// perform a step of this migration
+				let (updated_progress, consumed_weight)
+					= migration.step(migration_state, available_for_step);
+
+				weight += consumed_weight;
+				if weight > available_weight {
+					// TODO: the intent here is to complain obnoxiously so that this is caught
+					// during development. In production, this should probably be tolerated because
+					// failing is catastrophic.
+					log::error!("Migration {} consumed more weight than it was given! ({} > {})",
+						migration_name, consumed_weight, available_for_step);
+				}
+
+				// make note of any unfinished migrations
+				if updated_progress < Perbill::one() {
+					done = false;
+				}
+
+				if migration_state != updated_progress {
+					<MigrationState<T>>::insert(migration_name, updated_progress);
+				}
+			}
+
+		}
+
+		if done {
+			<FullyUpgraded<T>>::put(true);
+		}
+
+		weight
+	}
+}

pallets/migrations/src/migrations.rs

@@ -0,0 +1,54 @@
+// Copyright 2019-2020 PureStake Inc.
+// This file is part of Moonbeam.
+
+// Moonbeam is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Moonbeam is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Moonbeam.  If not, see <http://www.gnu.org/licenses/>.
+
+//! # Migrations
+
+use crate::*;
+
+/// This module acts as a registry where each migration is defined. Each migration should implement
+/// the "Migration" trait declared in this crate.
+
+pub struct MM_001_AuthorMappingAddDeposit;
+impl Migration for MM_001_AuthorMappingAddDeposit {
+	fn friendly_name(&self) -> &str {
+		"AuthorMappingAddDeposit"
+	}
+	fn step(&self, _previous_progress: Perbill, _available_weight: Weight) -> (Perbill, Weight) {
+		// reviewer note: this isn't meant to imply that migration code must live here. As noted
+		// elsewhere, I would expect migration code to live close to the pallet it affects.
+		(Perbill::one(), 0u64.into())
+	}
+}
+
+pub struct MM_002_StakingFixTotalBalance;
+impl Migration for MM_002_StakingFixTotalBalance {
+	fn friendly_name(&self) -> &str {
+		"StakingFixTotalBalance"
+	}
+	fn step(&self, _previous_progress: Perbill, _available_weight: Weight) -> (Perbill, Weight) {
+		(Perbill::one(), 0u64.into())
+	}
+}
+
+pub struct MM_003_StakingTransitionBoundedSet; // TODO: better name
+impl Migration for MM_003_StakingTransitionBoundedSet {
+	fn friendly_name(&self) -> &str {
+		"StakingTransitionBoundedSet"
+	}
+	fn step(&self, _previous_progress: Perbill, _available_weight: Weight) -> (Perbill, Weight) {
+		(Perbill::one(), 0u64.into())
+	}
+}