Explain usage of <T: Config> in FRAME storage + Update parachain pallet template

docs/sdk/src/polkadot_sdk/frame_runtime.rs

@@ -87,16 +87,14 @@
 //! * writing a runtime in pure Rust, as done in [this template](https://github.com/JoshOrndorff/frameless-node-template).
 //! * writing a runtime in AssemblyScript,as explored in [this project](https://github.com/LimeChain/subsembly).
 
-use frame::prelude::*;
-
 /// A FRAME based pallet. This `mod` is the entry point for everything else. All
 /// `#[pallet::xxx]` macros must be defined in this `mod`. Although, frame also provides an
 /// experimental feature to break these parts into different `mod`s. See [`pallet_examples`] for
 /// more.
 #[docify::export]
 #[frame::pallet(dev_mode)]
 pub mod pallet {
- use super::*;
+ use frame::prelude::*;
 
  /// The configuration trait of a pallet. Mandatory. Allows a pallet to receive types at a
  /// later point from the runtime that wishes to contain it. It allows the pallet to be

docs/sdk/src/reference_docs/frame_storage_derives.rs

@@ -0,0 +1,199 @@
+//! <section class="info">
+//! In all examples, a few lines of boilerplate have been hidden from each snippet for conciseness.
+//! </section>
+//!
+//! Let's begin by starting to store a `NewType` in a storage item:
+//!
+//! ```compile_fail
+//! #[frame::pallet]
+//! pub mod pallet {
+//! # use frame::prelude::*;
+//! # #[pallet::config]
+//! # pub trait Config: frame_system::Config {}
+//! # #[pallet::pallet]
+//! # pub struct Pallet<T>(_);
+//! pub struct NewType(u32);
+//
+//! #[pallet::storage]
+//! pub type Something<T> = StorageValue<_, NewType>;
+//! }
+//! ```
+//! 
+//! This raises a number of compiler errors, like:
+//! ```text
+//! the trait `MaxEncodedLen` is not implemented for `NewType`, which is required by
+//! `frame::prelude::StorageValue<_GeneratedPrefixForStorageSomething<T>, NewType>:
+//! StorageInfoTrait`
+//! ```
+//! 
+//! This implies the following set of traits that need to be derived for a type to be stored in
+//! `frame` storage:
+//! ```rust
+//! #[frame::pallet]
+//! pub mod pallet {
+//! # use frame::prelude::*;
+//! # #[pallet::config]
+//! # pub trait Config: frame_system::Config {}
+//! # #[pallet::pallet]
+//! # pub struct Pallet<T>(_);
+//! #[derive(codec::Encode, codec::Decode, codec::MaxEncodedLen, scale_info::TypeInfo)]
+//! pub struct NewType(u32);
+//!
+//! #[pallet::storage]
+//! pub type Something<T> = StorageValue<_, NewType>;
+//! }
+//! ```
+//! 
+//! Next, let's look at how this will differ if we are to store a type that is derived from `T` in
+//! storage, such as [`frame::prelude::BlockNumberFor`]:
+//! ```compile_fail
+//! #[frame::pallet]
+//! pub mod pallet {
+//! # use frame::prelude::*;
+//! # #[pallet::config]
+//! # pub trait Config: frame_system::Config {}
+//! # #[pallet::pallet]
+//! # pub struct Pallet<T>(_);
+//! #[derive(codec::Encode, codec::Decode, codec::MaxEncodedLen, scale_info::TypeInfo)]
+//! pub struct NewType<T: Config>(BlockNumberFor<T>);
+//!
+//! #[pallet::storage]
+//! pub type Something<T: Config> = StorageValue<_, NewType<T>>;
+//! }
+//! ```
+//! 
+//! Surprisingly, this will also raise a number of errors, like:
+//! ```text
+//! the trait `TypeInfo` is not implemented for `T`, which is required
+//! by`frame_support::pallet_prelude::StorageValue<pallet_2::_GeneratedPrefixForStorageSomething<T>,
+//! pallet_2::NewType<T>>:StorageEntryMetadataBuilder
+//! ```
+//! 
+//! Why is that? The underlying reason is that the `TypeInfo` `derive` macro will only work for
+//! `NewType` if all of `NewType`'s generics also implement `TypeInfo`. This is not the case for `T`
+//! in the example above.
+//!
+//! If you expand an instance of the derive, you will find something along the lines of:
+//! `impl<T> TypeInfo for NewType<T> where T: TypeInfo { ... }`. This is the reason why the
+//! `TypeInfo` trait is required for `T`.
+//!
+//! To fix this, we need to add a `#[scale_info(skip_type_params(T))]`
+//! attribute to `NewType`. This additional macro will instruct the `derive` to skip the bound on
+//! `T`.
+//! ```rust
+//! #[frame::pallet]
+//! pub mod pallet {
+//! # use frame::prelude::*;
+//! # #[pallet::config]
+//! # pub trait Config: frame_system::Config {}
+//! # #[pallet::pallet]
+//! # pub struct Pallet<T>(_);
+//! #[derive(codec::Encode, codec::Decode, codec::MaxEncodedLen, scale_info::TypeInfo)]
+//! #[scale_info(skip_type_params(T))]
+//! pub struct NewType<T: Config>(BlockNumberFor<T>);
+//!
+//! #[pallet::storage]
+//! pub type Something<T: Config> = StorageValue<_, NewType<T>>;
+//! }
+//! ```
+//! 
+//! Next, let's say we wish to store `NewType` as [`frame::prelude::ValueQuery`], which means it
+//! must also implement `Default`. This should be as simple as adding `derive(Default)` to it,
+//! right?
+//! ```compile_fail
+//! #[frame::pallet]
+//! pub mod pallet {
+//! # use frame::prelude::*;
+//! # #[pallet::config]
+//! # pub trait Config: frame_system::Config {}
+//! # #[pallet::pallet]
+//! # pub struct Pallet<T>(_);
+//! #[derive(codec::Encode, codec::Decode, codec::MaxEncodedLen, scale_info::TypeInfo, Default)]
+//! #[scale_info(skip_type_params(T))]
+//! pub struct NewType<T: Config>(BlockNumberFor<T>);
+//!
+//! #[pallet::storage]
+//! pub type Something<T: Config> = StorageValue<_, NewType<T>, ValueQuery>;
+//! }
+//! ```
+//! 
+//! Under the hood, the expansion of the `derive(Default)` will suffer from the same restriction as
+//! before: it will only work if `T: Default`, and `T` is not `Default`. Note that this is an
+//! expected issue: `T` is merely a wrapper of many other types, such as `BlockNumberFor<T>`.
+//! `BlockNumberFor<T>` should indeed implement `Default`, but `T` implementing `Default` is rather
+//! meaningless.
+//!
+//! To fix this, frame provides a set of macros that are analogous to normal rust derive macros, but
+//! work nicely on top of structs that are generic over `T: Config`. These macros are:
+//!
+//! - [`frame::prelude::DefaultNoBound`]
+//! - [`frame::prelude::DebugNoBound`]
+//! - [`frame::prelude::PartialEqNoBound`]
+//! - [`frame::prelude::EqNoBound`]
+//! - [`frame::prelude::CloneNoBound`]
+//! - [`frame::prelude::PartialOrdNoBound`]
+//! - [`frame::prelude::OrdNoBound`]
+//!
+//! The above traits are almost certainly needed for your tests: To print your type, assert equality
+//! or clone it.
+//!
+//! We can fix the following example by using [`frame::prelude::DefaultNoBound`].
+//! ```rust
+//! #[frame::pallet]
+//! pub mod pallet {
+//! # use frame::prelude::*;
+//! # #[pallet::config]
+//! # pub trait Config: frame_system::Config {}
+//! # #[pallet::pallet]
+//! # pub struct Pallet<T>(_);
+//! #[derive(
+//! codec::Encode,
+//! codec::Decode,
+//! codec::MaxEncodedLen,
+//! scale_info::TypeInfo,
+//! DefaultNoBound
+//! )]
+//! #[scale_info(skip_type_params(T))]
+//! pub struct NewType<T:Config>(BlockNumberFor<T>);
+//!
+//! #[pallet::storage]
+//! pub type Something<T: Config> = StorageValue<_, NewType<T>, ValueQuery>;
+//! }
+//! ```
+//! 
+//! Finally, if a custom type that is provided through `Config` is to be stored in the storage, it
+//! is subject to the same trait requirements. The following does not work:
+//! ```compile_fail
+//! #[frame::pallet]
+//! pub mod pallet {
+//! use frame::prelude::*;
+//! #[pallet::config]
+//! pub trait Config: frame_system::Config {
+//! type CustomType;
+//! }
+//! #[pallet::pallet]
+//! pub struct Pallet<T>(_);
+//! #[pallet::storage]
+//! pub type Something<T: Config> = StorageValue<_, T::CustomType>;
+//! }
+//! ```
+//! 
+//! But adding the right trait bounds will fix it.
+//! ```rust
+//! #[frame::pallet]
+//! pub mod pallet {
+//! use frame::prelude::*;
+//! #[pallet::config]
+//! pub trait Config: frame_system::Config {
+//! type CustomType: codec::FullCodec
+//! + codec::MaxEncodedLen
+//! + scale_info::TypeInfo
+//! + Debug
+//! + Default;
+//! }
+//! #[pallet::pallet]
+//! pub struct Pallet<T>(_);
+//! #[pallet::storage]
+//! pub type Something<T: Config> = StorageValue<_, T::CustomType>;
+//! }
+//! ```

docs/sdk/src/reference_docs/mod.rs

@@ -45,6 +45,10 @@ pub mod signed_extensions;
 /// Learn about *Origins*, a topic in FRAME that enables complex account abstractions to be built.
 pub mod frame_origin;
 
+/// Learn about the details of what derives are needed for a type to be store-able in `frame`
+/// storage.
+pub mod frame_storage_derives;
+
 /// Learn about how to write safe and defensive code in your FRAME runtime.
 pub mod defensive_programming;
 

substrate/frame/bags-list/src/list/tests.rs

@@ -777,7 +777,8 @@ mod bags {
  assert_eq!(bag_1000.tail, Some(4));
  assert_eq!(bag_1000.iter().count(), 3);
  bag_1000.insert_node_unchecked(node(4, None, None, bag_1000.bag_upper)); // panics in debug
- assert_eq!(bag_1000.iter().count(), 3); // in release we expect it to silently ignore the request.
+ assert_eq!(bag_1000.iter().count(), 3); // in release we expect it to silently ignore the
+ // request.
  });
  }
 

substrate/frame/nis/src/lib.rs

@@ -755,7 +755,13 @@ pub mod pallet {
  // We ignore this error as it just means the amount we're trying to deposit is
  // dust and the beneficiary account doesn't exist.
  .or_else(
- |e| if e == TokenError::CannotCreate.into() { Ok(()) } else { Err(e) },
+ |e| {
+ if e == TokenError::CannotCreate.into() {
+ Ok(())
+ } else {
+ Err(e)
+ }
+ },
  )?;
  summary.receipts_on_hold.saturating_reduce(on_hold);
  }

substrate/frame/nomination-pools/src/lib.rs

@@ -494,7 +494,6 @@ impl ClaimPermission {
  frame_support::PartialEqNoBound,
 )]
 #[cfg_attr(feature = "std", derive(DefaultNoBound))]
-#[codec(mel_bound(T: Config))]
 #[scale_info(skip_type_params(T))]
 pub struct PoolMember<T: Config> {
  /// The identifier of the pool to which `who` belongs.

substrate/frame/src/lib.rs

@@ -30,13 +30,43 @@
 //! > **F**ramework for **R**untime **A**ggregation of **M**odularized **E**ntities: Substrate's
 //! > State Transition Function (Runtime) Framework.
 //!
-//! ## Documentation
+//! //! ## Usage
 //!
-//! See [`polkadot_sdk::frame`](../polkadot_sdk_docs/polkadot_sdk/frame_runtime/index.html).
+//! The main intended use of this crate is for it to be imported with its preludes:
 //!
-//! ## WARNING: Experimental
+//! ```
+//! # use polkadot_sdk_frame as frame;
+//! #[frame::pallet]
+//! pub mod pallet {
+//! # use polkadot_sdk_frame as frame;
+//! use frame::prelude::*;
+//! // ^^ using the prelude!
 //!
-//! **This crate and all of its content is experimental, and should not yet be used in production.**
+//! #[pallet::config]
+//! pub trait Config: frame_system::Config {}
+//!
+//! #[pallet::pallet]
+//! pub struct Pallet<T>(_);
+//! }
+//!
+//! pub mod tests {
+//! # use polkadot_sdk_frame as frame;
+//! use frame::testing_prelude::*;
+//! }
+//!
+//! pub mod runtime {
+//! # use polkadot_sdk_frame as frame;
+//! use frame::runtime::prelude::*;
+//! }
+//! ```
+//!
+//! See: [`prelude`], [`testing_prelude`] and [`runtime::prelude`].
+//!
+//! Please note that this crate can only be imported as `polkadot-sdk-frame` or `frame`.
+//!
+//! ## Documentation
+//!
+//! See [`polkadot_sdk::frame`](../polkadot_sdk_docs/polkadot_sdk/frame_runtime/index.html).
 //!
 //! ## Underlying dependencies
 //!
@@ -46,9 +76,9 @@
 //! In short, this crate only re-exports types and traits from multiple sources. All of these
 //! sources are listed (and re-exported again) in [`deps`].
 //!
-//! ## Usage
+//! ## WARNING: Experimental
 //!
-//! Please note that this crate can only be imported as `polkadot-sdk-frame` or `frame`.
+//! **This crate and all of its content is experimental, and should not yet be used in production.**
 
 #![cfg_attr(not(feature = "std"), no_std)]
 #![cfg(feature = "experimental")]

substrate/frame/state-trie-migration/src/lib.rs

@@ -109,7 +109,6 @@ pub mod pallet {
  MaxEncodedLen,
  )]
  #[scale_info(skip_type_params(MaxKeyLen))]
- #[codec(mel_bound())]
  pub enum Progress<MaxKeyLen: Get<u32>> {
  /// Yet to begin.
  ToStart,
@@ -126,7 +125,6 @@ pub mod pallet {
  ///
  /// It tracks the last top and child keys read.
  #[derive(Clone, Encode, Decode, scale_info::TypeInfo, PartialEq, Eq, MaxEncodedLen)]
- #[codec(mel_bound(T: Config))]
  #[scale_info(skip_type_params(T))]
  pub struct MigrationTask<T: Config> {
  /// The current top trie migration progress.

substrate/frame/support/src/lib.rs

@@ -2297,6 +2297,18 @@ pub mod pallet_macros {
  /// }
  /// ```
  ///
+ /// ### Value Trait Bounds
+ ///
+ /// To use a type as the value of a storage type, be it `StorageValue`, `StorageMap` or
+ /// anything else, you need to meet a number of trait bound constraints.
+ ///
+ /// See: <https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/reference_docs/frame_storage_derives/index.html>.
+ ///
+ /// Notably, all value types need to implement `Encode`, `Decode`, `MaxEncodedLen` and
+ /// `TypeInfo`, and possibly `Default`, if
+ /// [`ValueQuery`](frame_support::storage::types::ValueQuery) is used, explained in the
+ /// next section.
+ ///
  /// ### QueryKind
  ///
  /// Every storage type mentioned above has a generic type called

templates/minimal/README.md

@@ -37,21 +37,6 @@ A Polkadot SDK based project such as this one consists of:
 * 🛠️ Depending on your operating system and Rust version, there might be additional
 packages required to compile this template - please take note of the Rust compiler output.
 
-## Customization
-
-In case you would like to change the pallet's name from `pallet-minimal-template` to `pallet-test`,
-you would need to implement the following changes:
-* Change the pallet folder name from `template` to `test` for consistency
-* Also for consistency, in `/runtime/src/lib.rs`, change from `pub type Template` to `pub type Test`,
-and don't forget to also customize the corresponding comments.
-* Change `pallet-minimal-template` to `pallet-test` in the following files:
- * `/runtime/Cargo.toml`
- * `/runtime/src/lib.rs`
- * `/pallets/test/Cargo.toml`
- * `/src/lib.rs`
-* Change `pallet_minimal_template` to `pallet_test` in the following files:
- * `/runtime/src/lib.rs`
-
 ### Build
 
 🔨 Use the following command to build the node without launching it:
@@ -80,8 +65,8 @@ docker run --rm polkadot-sdk-minimal-template --dev
 Development chains:
 
 * 🧹 Do not persist the state.
-* 💰 Are preconfigured with a genesis state that includes several pre-funded development accounts.
-* 🧑‍⚖️ Development accounts are used as `sudo` accounts.
+* 💰 Are pre-configured with a genesis state that includes several pre-funded development accounts.
+* 🧑‍⚖️ One development account (`ALICE`) is used as `sudo` accounts.
 
 ### Connect with the Polkadot-JS Apps Front-End