FRAME: General System for Recognizing and Executing Service Work

Cargo.toml

@@ -155,6 +155,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,204 @@
+// 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 core::marker::PhantomData;
+
+use codec::{Decode, Encode};
+use frame_support::dispatch::DispatchResult;
+// Re-export pallet items so that they can be accessed from the crate namespace.
+pub use pallet::*;
+use sp_runtime::DispatchError;
+
+#[frame_support::pallet(dev_mode)]
+pub mod pallet {
+
+	use super::*;
+	use frame_support::pallet_prelude::*;
+	use frame_system::pallet_prelude::*;
+
+	// this can be auto-generated from the macros
+	#[derive(Clone, PartialEq, Eq, Encode, Decode, TypeInfo)]
+	pub enum Task<T: Config> {
+		Increment,
+		Decrement,
+		#[doc(hidden)]
+		#[codec(skip)]
+		__Ignore(PhantomData<T>, frame_support::Never),
+	}
+
+	// this can be auto-generated from the macros and will always be the same
+	impl<T: Config> core::fmt::Debug for Task<T> {
+		fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+			f.debug_struct("Task").field("value", self).finish()
+		}
+	}
+
+	// we can automatically inject `InvalidTask` into an existing Error enum by finding it via
+	// visitor pattern, otherwise we can just emit an error enum containing just our
+	// `InvalidTask` variant. Alternatively we could just expect that `InvalidTask` is included
+	// in the error enum, by convention, or we could use something like
+	// `InvalidTransaction::Custom(1u8)` but this seems bad to me.
+	#[pallet::error]
+	pub enum Error<T> {
+		InvalidTask,
+		ValueOverflow,
+		ValueUnderflow,
+	}
+
+	// this will be auto-generated from `#[pallet::tasks]`
+	impl<T: Config> frame_support::traits::Task for Task<T>
+	where
+		T: TypeInfo,
+	{
+		type Enumeration = std::vec::IntoIter<Task<T>>;
+
+		const TASK_INDEX: usize = 0;
+
+		fn enumerate() -> Self::Enumeration {
+			vec![Task::Increment, Task::Decrement].into_iter()
+		}
+
+		fn is_valid(&self) -> bool {
+			let value = Value::<T>::get().unwrap();
+			match self {
+				Task::Increment => value < 255,
+				Task::Decrement => value > 0,
+				Task::__Ignore(_, _) => unreachable!(),
+			}
+		}
+
+		fn run(&self) -> Result<(), DispatchError> {
+			match self {
+				Task::Increment => {
+					// Get the value and check if it can be incremented
+					let value = Value::<T>::get().unwrap_or_default();
+					if value >= 255 {
+						Err(Error::<T>::ValueOverflow.into())
+					} else {
+						let new_val = value.checked_add(1).ok_or(Error::<T>::ValueOverflow)?;
+						Value::<T>::put(new_val);
+						Pallet::<T>::deposit_event(Event::Incremented { new_val });
+						Ok(())
+					}
+				},
+				Task::Decrement => {
+					// Get the value and check if it can be decremented
+					let value = Value::<T>::get().unwrap_or_default();
+					if value == 0 {
+						Err(Error::<T>::ValueUnderflow.into())
+					} else {
+						let new_val = value.checked_sub(1).ok_or(Error::<T>::ValueUnderflow)?;
+						Value::<T>::put(new_val);
+						Pallet::<T>::deposit_event(Event::Decremented { new_val });
+						Ok(())
+					}
+				},
+				Task::__Ignore(_, _) => unreachable!(),
+			}
+		}
+	}
+
+	#[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>
+	where
+		T: TypeInfo,
+	{
+		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(())
+		}
+
+		// this will be auto-generated by the macros and will always be the same
+		pub fn do_task(origin: OriginFor<T>, task: Task<T>) -> DispatchResult {
+			use frame_support::traits::Task;
+			ensure_root(origin)?;
+			if task.is_valid() {
+				task.run()
+			} else {
+				Err(Error::<T>::InvalidTask.into())
+			}
+		}
+	}
+
+	// I think we can actually auto-impl this in the macros if an existing `ValidateUnsigned`
+	// impl is not present. If one is present, we just wouldn't emit an impl for this. An
+	// existing impl will be easy to find using a simple visitor pattern in the macros.
+	impl<T: Config + TypeInfo> frame_support::unsigned::ValidateUnsigned for Pallet<T> {
+		type Call = Call<T>;
+
+		fn validate_unsigned(_source: TransactionSource, call: &Self::Call) -> TransactionValidity {
+			// TODO: verify `source` ?
+			use frame_support::traits::Task;
+			match call {
+				Call::do_task { task } => {
+					if task.is_valid() {
+						Ok(ValidTransaction {
+							priority: 0, // TODO: make configurable on Task?
+							requires: vec![],
+							provides: vec![task.encode()],
+							longevity: TransactionLongevity::max_value(),
+							propagate: true,
+						})
+					} else {
+						InvalidTransaction::Custom(1u8).into()
+						// TODO: custom error enum for this? Maybe we can put it in some
+						// globally accessible place? Or just always generate the same enum?
+					}
+				},
+				_ => InvalidTransaction::Call.into(),
+			}
+		}
+	}
+
+	#[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/procedural/src/construct_runtime/expand/mod.rs

@@ -25,6 +25,7 @@ mod metadata;
 mod origin;
 mod outer_enums;
 mod slash_reason;
+mod task;
 mod unsigned;
 
 pub use call::expand_outer_dispatch;
@@ -37,4 +38,5 @@ pub use metadata::expand_runtime_metadata;
 pub use origin::expand_outer_origin;
 pub use outer_enums::{expand_outer_enum, OuterEnumType};
 pub use slash_reason::expand_outer_slash_reason;
+pub use task::expand_outer_task;
 pub use unsigned::expand_outer_validate_unsigned;

frame/support/procedural/src/construct_runtime/expand/task.rs

@@ -0,0 +1,69 @@
+// 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
+
+use crate::construct_runtime::{parse::PalletPath, Pallet};
+use proc_macro2::{Ident, TokenStream};
+use quote::quote;
+
+/// Expands aggregate `RuntimeTask` enum.
+pub fn expand_outer_task(pallet_decls: &[Pallet], scrate: &TokenStream) -> TokenStream {
+	let mut conversion_fns = Vec::new();
+	let mut task_variants = Vec::new();
+	for decl in pallet_decls {
+		if let Some(_) = decl.find_part("Task") {
+			let variant_name = &decl.name;
+			let path = &decl.path;
+			let index = decl.index;
+
+			conversion_fns.push(expand_conversion_fn(path, variant_name));
+
+			task_variants.push(expand_variant(index, path, variant_name));
+		}
+	}
+
+	quote! {
+		/// An aggregation of all `Task` enums across all pallets included in the current runtime.
+		#[derive(
+			Copy, Clone, Eq, PartialEq, Ord, PartialOrd,
+			#scrate::codec::Encode, #scrate::codec::Decode, #scrate::codec::MaxEncodedLen,
+			#scrate::scale_info::TypeInfo,
+			#scrate::RuntimeDebug,
+		)]
+		pub enum RuntimeTask {
+			#( #task_variants )*
+		}
+
+		#( #conversion_fns )*
+	}
+}
+
+fn expand_conversion_fn(path: &PalletPath, variant_name: &Ident) -> TokenStream {
+	quote! {
+		impl From<#path::Task> for RuntimeTask {
+			fn from(hr: #path::Task) -> Self {
+				RuntimeTask::#variant_name(hr)
+			}
+		}
+	}
+}
+
+fn expand_variant(index: u8, path: &PalletPath, variant_name: &Ident) -> TokenStream {
+	quote! {
+		#[codec(index = #index)]
+		#variant_name(#path::Task),
+	}
+}

frame/support/procedural/src/construct_runtime/mod.rs

@@ -385,6 +385,7 @@ fn construct_runtime_final_expansion(
 	let pallet_to_index = decl_pallet_runtime_setup(&name, &pallets, &scrate);
 
 	let dispatch = expand::expand_outer_dispatch(&name, system_pallet, &pallets, &scrate);
+	let tasks = expand::expand_outer_task(&pallets, &scrate);
 	let metadata = expand::expand_runtime_metadata(
 		&name,
 		&pallets,
@@ -472,6 +473,8 @@ fn construct_runtime_final_expansion(
 
 		#dispatch
 
+		#tasks
+
 		#metadata
 
 		#outer_config