Newer
Older
![Sam Johnson Sam Johnson's avatar](/assets/no_avatar-849f9c04a3a0d0cea2424ae97b27447dc64a7dbfae83c036c45b403392f0e8ba.png)
Sam Johnson
committed
/// * `Config`,
/// * `decl_module`,
/// * `decl_event`,
/// * `decl_error`,
/// * `decl_storage`,
/// * `origin`,
/// * `validate_unsigned`,
/// * `provide_inherent`, so far it should compile and all be correct.
/// 4. start writing the new pallet module
/// ```ignore
/// pub use pallet::*;
///
/// #[frame_support::pallet]
/// pub mod pallet {
/// use frame_support::pallet_prelude::*;
/// use frame_system::pallet_prelude::*;
/// use super::*;
///
/// #[pallet::pallet]
/// #[pallet::generate_store($visibility_of_trait_store trait Store)]
/// // NOTE: if the visibility of trait store is private but you want to make it available
/// // in super, then use `pub(super)` or `pub(crate)` to make it available in crate.
![thiolliere thiolliere's avatar](/assets/no_avatar-849f9c04a3a0d0cea2424ae97b27447dc64a7dbfae83c036c45b403392f0e8ba.png)
thiolliere
committed
/// pub struct Pallet<T>(_);
/// // pub struct Pallet<T, I = ()>(PhantomData<T>); // for instantiable pallet
/// }
/// ```
/// 5. **migrate Config**: move trait into the module with
![Sam Johnson Sam Johnson's avatar](/assets/no_avatar-849f9c04a3a0d0cea2424ae97b27447dc64a7dbfae83c036c45b403392f0e8ba.png)
Sam Johnson
committed
/// * all const in `decl_module` to [`#[pallet::constant]`](#palletconstant)
/// * add the bound `IsType<<Self as frame_system::Config>::RuntimeEvent>` to `type
/// RuntimeEvent`
/// 7. **migrate decl_module**: write:
/// ```ignore
/// #[pallet::hooks]
/// impl<T: Config> Hooks for Pallet<T> {
/// }
/// ```
![Sam Johnson Sam Johnson's avatar](/assets/no_avatar-849f9c04a3a0d0cea2424ae97b27447dc64a7dbfae83c036c45b403392f0e8ba.png)
Sam Johnson
committed
/// and write inside `on_initialize`, `on_finalize`, `on_runtime_upgrade`,
/// `offchain_worker`, and `integrity_test`.
///
/// then write:
/// ```ignore
/// #[pallet::call]
/// }
/// ```
![Sam Johnson Sam Johnson's avatar](/assets/no_avatar-849f9c04a3a0d0cea2424ae97b27447dc64a7dbfae83c036c45b403392f0e8ba.png)
Sam Johnson
committed
/// and write inside all the calls in `decl_module` with a few changes in the signature:
/// - origin must now be written completely, e.g. `origin: OriginFor<T>`
/// - result type must be `DispatchResultWithPostInfo`, you need to write it and also you
/// might need to put `Ok(().into())` at the end or the function.
/// - `#[compact]` must now be written
/// [`#[pallet::compact]`](#palletcompact-some_arg-some_type)
/// - `#[weight = ..]` must now be written [`#[pallet::weight(..)]`](#palletweightexpr)
///
/// 7. **migrate event**: rewrite as a simple enum with the attribute
/// [`#[pallet::event]`](#event-palletevent-optional), use [`#[pallet::generate_deposit($vis
/// fn deposit_event)]`](#event-palletevent-optional) to generate `deposit_event`,
/// 8. **migrate error**: rewrite it with attribute
/// [`#[pallet::error]`](#error-palleterror-optional).
/// 9. **migrate storage**: `decl_storage` provide an upgrade template (see 3.). All storages,
/// genesis config, genesis build and default implementation of genesis config can be taken
/// from it directly.
![Sam Johnson Sam Johnson's avatar](/assets/no_avatar-849f9c04a3a0d0cea2424ae97b27447dc64a7dbfae83c036c45b403392f0e8ba.png)
Sam Johnson
committed
///
/// Otherwise here is the manual process:
///
/// first migrate the genesis logic. write:
/// ```ignore
/// #[pallet::genesis_config]
/// struct GenesisConfig {
/// // fields of add_extra_genesis
/// }
/// impl Default for GenesisConfig {
/// // type default or default provided for fields
/// }
/// #[pallet::genesis_build]
/// impl<T: Config> GenesisBuild<T> for GenesisConfig {
/// // for instantiable pallet:
/// // `impl<T: Config, I: 'static> GenesisBuild<T, I> for GenesisConfig {
/// fn build() {
/// // The add_extra_genesis build logic
/// }
/// }
/// ```
![Sam Johnson Sam Johnson's avatar](/assets/no_avatar-849f9c04a3a0d0cea2424ae97b27447dc64a7dbfae83c036c45b403392f0e8ba.png)
Sam Johnson
committed
/// for each storage, if it contains `config(..)` then add fields, and make it default to
/// the value in `= ..;` or the type default if none, if it contains no build then also add
/// the logic to build the value. for each storage if it contains `build(..)` then add the
/// logic to `genesis_build`.
///
/// NOTE: within `decl_storage`: the individual config is executed first, followed by the
/// build and finally the `add_extra_genesis` build.
///
/// Once this is done you can migrate storages individually, a few notes:
/// - for private storage use `pub(crate) type ` or `pub(super) type` or nothing,
/// - for storages with `get(fn ..)` use [`#[pallet::getter(fn
/// ...)]`](#palletgetterfn-my_getter_fn_name-optional)
/// - for storages with value being `Option<$something>` make generic `Value` being
/// `$something` and generic `QueryKind` being `OptionQuery` (note: this is default).
/// Otherwise make `Value` the complete value type and `QueryKind` being `ValueQuery`.
/// - for storages with default value: `= $expr;` provide some specific `OnEmpty` generic.
/// To do so use of `#[pallet::type_value]` to generate the wanted struct to put.
/// example: `MyStorage: u32 = 3u32` would be written:
///
/// ```ignore
/// #[pallet::type_value] fn MyStorageOnEmpty() -> u32 { 3u32 }
/// #[pallet::storage]
/// pub(super) type MyStorage<T> = StorageValue<_, u32, ValueQuery, MyStorageOnEmpty>;
![Sam Johnson Sam Johnson's avatar](/assets/no_avatar-849f9c04a3a0d0cea2424ae97b27447dc64a7dbfae83c036c45b403392f0e8ba.png)
Sam Johnson
committed
/// NOTE: `decl_storage` also generates the functions `assimilate_storage` and
/// `build_storage` directly on `GenesisConfig`, and these are sometimes used in tests.
/// In order not to break they can be implemented manually, one can implement those
/// functions by calling the `GenesisBuild` implementation.
/// 10. **migrate origin**: move the origin to the pallet module to be under a
/// [`#[pallet::origin]`](#origin-palletorigin-optional) attribute
/// 11. **migrate validate_unsigned**: move the
/// [`ValidateUnsigned`](`pallet_prelude::ValidateUnsigned`) implementation to the pallet
/// module under a
/// [`#[pallet::validate_unsigned]`](#validate-unsigned-palletvalidate_unsigned-optional)
/// attribute
/// 12. **migrate provide_inherent**: move the
/// [`ProvideInherent`](`pallet_prelude::ProvideInherent`) implementation to the pallet
/// module under a [`#[pallet::inherent]`](#inherent-palletinherent-optional) attribute
/// 13. rename the usage of `Module` to `Pallet` inside the crate.
![Sam Johnson Sam Johnson's avatar](/assets/no_avatar-849f9c04a3a0d0cea2424ae97b27447dc64a7dbfae83c036c45b403392f0e8ba.png)
Sam Johnson
committed
/// 14. migration is done, now double check the migration with the checking migration
/// guidelines shown below.
![Sam Johnson Sam Johnson's avatar](/assets/no_avatar-849f9c04a3a0d0cea2424ae97b27447dc64a7dbfae83c036c45b403392f0e8ba.png)
Sam Johnson
committed
/// # Checking upgrade guidelines:
/// * compare metadata. Use [subsee](https://github.com/ascjones/subsee) to fetch the metadata
![Sam Johnson Sam Johnson's avatar](/assets/no_avatar-849f9c04a3a0d0cea2424ae97b27447dc64a7dbfae83c036c45b403392f0e8ba.png)
Sam Johnson
committed
/// and do a diff of the resulting json before and after migration. This checks for:
/// * call, names, signature, docs
/// * event names, docs
/// * error names, docs
/// * storage names, hasher, prefixes, default value
/// * error, error, constant
/// * manually check that:
![Sam Johnson Sam Johnson's avatar](/assets/no_avatar-849f9c04a3a0d0cea2424ae97b27447dc64a7dbfae83c036c45b403392f0e8ba.png)
Sam Johnson
committed
/// * `Origin` was moved inside the macro under
/// [`#[pallet::origin]`](#origin-palletorigin-optional) if it exists
/// * [`ValidateUnsigned`](`pallet_prelude::ValidateUnsigned`) was moved inside the macro
/// under
/// [`#[pallet::validate_unsigned)]`](#validate-unsigned-palletvalidate_unsigned-optional)
/// if it exists
/// * [`ProvideInherent`](`pallet_prelude::ProvideInherent`) was moved inside the macro
/// under [`#[pallet::inherent)]`](#inherent-palletinherent-optional) if it exists
/// * `on_initialize` / `on_finalize` / `on_runtime_upgrade` / `offchain_worker` were moved
/// to the `Hooks` implementation
/// * storages with `config(..)` were converted to `GenesisConfig` field, and their default
/// is `= $expr;` if the storage has a default value
/// * storages with `build($expr)` or `config(..)` were built in `GenesisBuild::build`
/// * `add_extra_genesis` fields were converted to `GenesisConfig` field with their correct
/// default if specified
/// * `add_extra_genesis` build was written into `GenesisBuild::build`
/// * storage items defined with [`pallet`] use the name of the pallet provided by
![Sam Johnson Sam Johnson's avatar](/assets/no_avatar-849f9c04a3a0d0cea2424ae97b27447dc64a7dbfae83c036c45b403392f0e8ba.png)
Sam Johnson
committed
/// [`traits::PalletInfo::name`] as `pallet_prefix` (in `decl_storage`, storage items used
/// the `pallet_prefix` given as input of `decl_storage` with the syntax `as Example`). Thus
/// a runtime using the pallet must be careful with this change. To handle this change:
/// * either ensure that the name of the pallet given to `construct_runtime!` is the same
/// as the name the pallet was giving to `decl_storage`,
/// * or do a storage migration from the old prefix used to the new prefix used.
///
/// NOTE: The prefixes used by storage items are in metadata. Thus, ensuring the metadata
/// hasn't changed ensures that the `pallet_prefix`s used by the storage items haven't changed.
///
/// # Notes when macro fails to show proper error message spans:
///
/// Rustc loses span for some macro input. Some tips to fix it:
/// * do not use inner attribute:
/// ```ignore
/// #[pallet]
/// pub mod pallet {
/// //! This inner attribute will make span fail
/// ..
/// }
/// ```
/// * use the newest nightly possible.
pub use frame_support_procedural::pallet;
![Sam Johnson Sam Johnson's avatar](/assets/no_avatar-849f9c04a3a0d0cea2424ae97b27447dc64a7dbfae83c036c45b403392f0e8ba.png)
Sam Johnson
committed
/// Contains macro stubs for all of the pallet:: macros
pub mod pallet_macros {
pub use frame_support_procedural::{
call_index, compact, composite_enum, config, constant,
disable_frame_system_supertrait_check, error, event, extra_constants, generate_deposit,
generate_store, genesis_build, genesis_config, getter, hooks, import_section, inherent,
no_default, origin, pallet_section, storage, storage_prefix, storage_version, type_value,
unbounded, validate_unsigned, weight, whitelist_storage,
![Sam Johnson Sam Johnson's avatar](/assets/no_avatar-849f9c04a3a0d0cea2424ae97b27447dc64a7dbfae83c036c45b403392f0e8ba.png)
Sam Johnson
committed
};
}
#[deprecated(note = "Will be removed after July 2023; Use `sp_runtime::traits` directly instead.")]
pub mod error {
#[doc(hidden)]
pub use sp_runtime::traits::{BadOrigin, LookupError};
}
#[doc(inline)]
pub use frame_support_procedural::register_default_impl;
// Generate a macro that will enable/disable code based on `std` feature being active.
sp_core::generate_feature_enabled_macro!(std_enabled, feature = "std", $);
// Helper for implementing GenesisBuilder runtime API
pub mod genesis_builder_helper;