FRAME: General System for Recognizing and Executing Service Work

Cargo.toml

@@ -113,6 +113,7 @@ members = [
 	"frame/examples/dev-mode",
 	"frame/examples/split",
 	"frame/examples/default-config",
+	"frame/examples/tasks-example",
 	"frame/executive",
 	"frame/nis",
 	"frame/grandpa",

frame/examples/tasks-example/Cargo.toml

@@ -0,0 +1,38 @@
+[package]
+name = "tasks-example"
+version = "4.0.0-dev"
+authors = ["Parity Technologies <[email protected]>"]
+edition = "2021"
+license = "MIT-0"
+homepage = "https://substrate.io"
+repository = "https://github.com/paritytech/substrate/"
+description = "FRAME example pallet"
+
+[package.metadata.docs.rs]
+targets = ["x86_64-unknown-linux-gnu"]
+
+[dependencies]
+codec = { package = "parity-scale-codec", version = "3.6.1", default-features = false }
+log = { version = "0.4.17", default-features = false }
+scale-info = { version = "2.5.0", default-features = false, features = ["derive"] }
+frame-support = { version = "4.0.0-dev", default-features = false, path = "../../support" }
+frame-system = { version = "4.0.0-dev", default-features = false, path = "../../system" }
+sp-io = { version = "23.0.0", default-features = false, path = "../../../primitives/io" }
+sp-runtime = { version = "24.0.0", default-features = false, path = "../../../primitives/runtime" }
+sp-std = { version = "8.0.0", default-features = false, path = "../../../primitives/std" }
+sp-core = { version = "21.0.0", default-features = false, path = "../../../primitives/core" }
+
+[features]
+default = ["std"]
+std = [
+	"codec/std",
+	"frame-support/std",
+	"frame-system/std",
+	"log/std",
+	"scale-info/std",
+	"sp-io/std",
+	"sp-runtime/std",
+	"sp-std/std",
+	"sp-core/std",
+]
+try-runtime = ["frame-support/try-runtime"]

frame/examples/tasks-example/src/lib.rs

@@ -0,0 +1,135 @@
+// 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.
+
+#![cfg_attr(not(feature = "std"), no_std)]
+
+use codec::{Decode, Encode};
+use frame_support::{dispatch::DispatchResult, traits::Task};
+// Re-export pallet items so that they can be accessed from the crate namespace.
+pub use pallet::*;
+use sp_runtime::DispatchError;
+
+#[derive(Clone, PartialEq, Eq, Encode, Decode)]
+pub enum ExampleTask {
+	Increment,
+	Decrement,
+}
+
+pub trait PalletTask<T: Config>: Task {
+	type Config: frame_system::Config;
+	fn is_valid(&self, config: &Self::Config) -> bool;
+	fn run(&self, config: &Self::Config) -> Result<(), DispatchError>;
+}
+
+impl Task for ExampleTask {
+	type Enumeration = std::vec::IntoIter<ExampleTask>;
+
+	const TASK_INDEX: usize = 0;
+
+	fn enumerate() -> Self::Enumeration {
+		vec![ExampleTask::Increment, ExampleTask::Decrement].into_iter()
+	}
+
+	fn is_valid(&self) -> bool {
+		unimplemented!()
+	}
+
+	fn run(&self) -> Result<(), DispatchError> {
+		unimplemented!()
+	}
+}
+
+impl<T: Config> PalletTask<T> for ExampleTask {
+	type Config = T;
+
+	fn is_valid(&self, _config: &Self::Config) -> bool {
+		let value = Value::<T>::get().unwrap();
+		match self {
+			ExampleTask::Increment => value < 255,
+			ExampleTask::Decrement => value > 0,
+		}
+	}
+
+	fn run(&self, _config: &Self::Config) -> Result<(), DispatchError> {
+		match self {
+			ExampleTask::Increment => {
+				// Increment the value and emit an event
+				let new_val = Value::<T>::get().unwrap().checked_add(1).ok_or("Value overflow")?;
+				Value::<T>::put(new_val);
+				Pallet::<T>::deposit_event(Event::Incremented { new_val });
+			},
+			ExampleTask::Decrement => {
+				// Decrement the value and emit an event
+				let new_val = Value::<T>::get().unwrap().checked_sub(1).ok_or("Value underflow")?;
+				Value::<T>::put(new_val);
+				Pallet::<T>::deposit_event(Event::Decremented { new_val });
+			},
+		}
+		Ok(())
+	}
+}
+
+#[frame_support::pallet(dev_mode)]
+pub mod pallet {
+	use super::*;
+	use frame_support::pallet_prelude::*;
+	use frame_system::pallet_prelude::*;
+
+	#[pallet::config]
+	pub trait Config: frame_system::Config {
+		type RuntimeEvent: From<Event<Self>> + IsType<<Self as frame_system::Config>::RuntimeEvent>;
+	}
+
+	#[pallet::pallet]
+	pub struct Pallet<T>(_);
+
+	#[pallet::storage]
+	#[pallet::getter(fn value)]
+	pub type Value<T: Config> = StorageValue<_, u8>;
+
+	#[pallet::call]
+	impl<T: Config> Pallet<T> {
+		pub fn increment(origin: OriginFor<T>) -> DispatchResult {
+			ensure_root(origin)?;
+
+			// Increment the value and emit an event
+			let new_val = Value::<T>::get().unwrap().checked_add(1).ok_or("Value overflow")?;
+			Value::<T>::put(new_val);
+			Self::deposit_event(Event::Incremented { new_val });
+
+			Ok(())
+		}
+
+		pub fn decrement(origin: OriginFor<T>) -> DispatchResult {
+			ensure_root(origin)?;
+
+			// Decrement the value and emit an event
+			let new_val = Value::<T>::get().unwrap().checked_sub(1).ok_or("Value underflow")?;
+			Value::<T>::put(new_val);
+			Self::deposit_event(Event::Decremented { new_val });
+
+			Ok(())
+		}
+	}
+
+	#[pallet::event]
+	#[pallet::generate_deposit(pub(super) fn deposit_event)]
+	pub enum Event<T: Config> {
+		Incremented { new_val: u8 },
+		Decremented { new_val: u8 },
+	}
+}

frame/support/src/traits.rs

@@ -113,6 +113,9 @@ pub use messages::{
 	ProcessMessageError, QueuePausedQuery, ServiceQueues, TransformOrigin,
 };
 
+pub mod tasks;
+pub use tasks::*;
+
 #[cfg(feature = "try-runtime")]
 mod try_runtime;
 #[cfg(feature = "try-runtime")]

frame/support/src/traits/tasks.rs

@@ -0,0 +1,42 @@
+// 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.
+
+//! Contains the [`Task`] trait, which defines a general-purpose way for defining and executing
+//! service work, and supporting types.
+
+use codec::FullCodec;
+use sp_runtime::DispatchError;
+use sp_std::iter::Iterator;
+
+/// A general-purpose trait which defines a type of service work (i.e., work to performed by an
+/// off-chain worker) including methods for enumerating, validating, indexing, and running
+/// tasks of this type.
+pub trait Task: Sized + FullCodec {
+	type Enumeration: Iterator<Item = Self>;
+
+	/// A unique value representing this `Task`. Analogous to `call_index`, but for tasks.
+	const TASK_INDEX: usize;
+
+	/// Inspects the pallet's state and enumerates tasks of this type.
+	fn enumerate() -> Self::Enumeration;
+
+	/// Checks if a particular instance of this `Task` variant is a valid piece of work.
+	fn is_valid(&self) -> bool;
+
+	/// Performs the work for this particular `Task` variant.
+	fn run(&self) -> Result<(), DispatchError>;
+}