pezkuwichain/pezkuwi-subxt
1
0
Fork 0
mirror of https://github.com/pezkuwichain/pezkuwi-subxt.git synced 2026-06-12 19:21:13 +00:00
Code Issues Packages Projects Releases Wiki Activity

GenesisConfig presets for runtime (#2714)

Browse Source 
The runtime now can provide a number of predefined presets of
`RuntimeGenesisConfig` struct. This presets are intended to be used in
different deployments, e.g.: `local`, `staging`, etc, and should be
included into the corresponding chain-specs.

Having `GenesisConfig` presets in runtime allows to fully decouple node
from runtime types (the problem is described in #1984).

**Summary of changes:**
- The `GenesisBuilder` API was adjusted to enable this functionality
(and provide better naming - #150):
   ```rust
    fn preset_names() -> Vec<PresetId>;
fn get_preset(id: Option<PresetId>) -> Option<serde_json::Value>;
//`None` means default
    fn build_state(value: serde_json::Value);
    pub struct PresetId(Vec<u8>);
   ```

- **Breaking change**: Old `create_default_config` method was removed,
`build_config` was renamed to `build_state`. As a consequence a node
won't be able to interact with genesis config for older runtimes. The
cleanup was made for sake of API simplicity. Also IMO maintaining
compatibility with old API is not so crucial.
- Reference implementation was provided for `substrate-test-runtime` and
`rococo` runtimes. For rococo new
[`genesis_configs_presets`](https://github.com/paritytech/polkadot-sdk/blob/3b41d66b97c5ff0ec4a1989da5ffd8b9f3f588e3/polkadot/runtime/rococo/src/genesis_config_presets.rs#L530)
module was added and is used in `GenesisBuilder`
[_presets-related_](https://github.com/paritytech/polkadot-sdk/blob/3b41d66b97c5ff0ec4a1989da5ffd8b9f3f588e3/polkadot/runtime/rococo/src/lib.rs#L2462-L2485)
methods.

- The `chain-spec-builder` util was also improved and allows to
([_doc_](https://github.com/paritytech/polkadot-sdk/blob/3b41d66b97c5ff0ec4a1989da5ffd8b9f3f588e3/substrate/bin/utils/chain-spec-builder/src/lib.rs#L19)):
   - list presets provided by given runtime (`list-presets`),
- display preset or default config provided by the runtime
(`display-preset`),
   - build chain-spec using named preset (`create ... named-preset`),


- The `ChainSpecBuilder` is extended with
[`with_genesis_config_preset_name`](https://github.com/paritytech/polkadot-sdk/blob/3b41d66b97c5ff0ec4a1989da5ffd8b9f3f588e3/substrate/client/chain-spec/src/chain_spec.rs#L447)
method which allows to build chain-spec using named preset provided by
the runtime. Sample usage on the node side
[here](https://github.com/paritytech/polkadot-sdk/blob/2caffaae803e08a3d5b46c860e8016da023ff4ce/polkadot/node/service/src/chain_spec.rs#L404).

Implementation of #1984.
fixes: #150
part of: #25

---------

Co-authored-by: Sebastian Kunert <skunert49@gmail.com>
Co-authored-by: Kian Paimani <5588131+kianenigma@users.noreply.github.com>
Co-authored-by: Oliver Tale-Yazdi <oliver.tale-yazdi@parity.io>
This commit is contained in:
Michal Kucharczyk
2024-04-04 20:30:54 +02:00
committed by GitHub
parent 9d052b7e09
commit f910a15c1c
47 changed files with 1460 additions and 661 deletions
Download Patch File Download Diff File Expand all files Collapse all files
substrate/primitives/genesis-builder/src/lib.rs
+64 -20
View File
@@ -19,39 +19,83 @@
//! Substrate genesis config builder
//!
//! This Runtime API allows to construct `RuntimeGenesisConfig`, in particular:
//! - serialize the runtime default `RuntimeGenesisConfig` struct into json format,
//! - put the RuntimeGenesisConfig struct into the storage. Internally this operation calls
//! `GenesisBuild::build` function for all runtime pallets, which is typically provided by
//! pallet's author.
//! - deserialize the `RuntimeGenesisConfig` from given json blob and put `RuntimeGenesisConfig`
//! into the state storage. Allows to build customized configuration.
//! For FRAME based runtimes, this runtime interface provides means to interact with
//! `RuntimeGenesisConfig`. Runtime provides a default `RuntimeGenesisConfig` structure in a form of
//! the JSON blob.
//!
//! Providing externalities with empty storage and putting `RuntimeGenesisConfig` into storage
//! allows to catch and build the raw storage of `RuntimeGenesisConfig` which is the foundation for
//! genesis block.
//! For non-FRAME runtimes this interface is intended to build genesis state of the runtime basing
//! on some input arbitrary bytes array. This documentation uses term `RuntimeGenesisConfig`, which
//! for non-FRAME runtimes may be understood as the runtime-side entity representing initial runtime
//! configuration. The representation of the preset is an arbitrary `Vec<u8>` and does not
//! necessarily have to represent a JSON blob.
//!
//! The runtime may provide a number of partial predefined `RuntimeGenesisConfig` configurations in
//! the form of patches which shall be applied on top of the default `RuntimeGenesisConfig`. The
//! patch is a JSON blob, which essentially comprises the list of key-value pairs that are to be
//! customized in the default runtime genesis config. These predefined configurations are referred
//! to as presets.
//!
//! This allows the runtime to provide a number of predefined configs (e.g. for different
//! testnets or development) without neccessity to leak the runtime types outside the itself (e.g.
//! node or chain-spec related tools).
//!
//! This Runtime API allows to interact with `RuntimeGenesisConfig`, in particular:
//! - provide the list of available preset names,
//! - provide a number of named presets of `RuntimeGenesisConfig`,
//! - provide a JSON represention of the default `RuntimeGenesisConfig` (by simply serializing the
//! default `RuntimeGenesisConfig` struct into JSON format),
//! - deserialize the full `RuntimeGenesisConfig` from given JSON blob and put the resulting
//! `RuntimeGenesisConfig` structure into the state storage creating the initial runtime's state.
//! Allows to build customized genesis. This operation internally calls `GenesisBuild::build`
//! function for all runtime pallets.
//!
//! Providing externalities with an empty storage and putting `RuntimeGenesisConfig` into storage
//! (by calling `build_state`) allows to construct the raw storage of `RuntimeGenesisConfig`
//! which is the foundation for genesis block.
extern crate alloc;
use alloc::vec::Vec;
/// The result type alias, used in build methods. `Err` contains formatted error message.
pub type Result = core::result::Result<(), sp_runtime::RuntimeString>;
/// The type representing preset ID.
pub type PresetId = sp_runtime::RuntimeString;
sp_api::decl_runtime_apis! {
/// API to interact with RuntimeGenesisConfig for the runtime
pub trait GenesisBuilder {
/// Creates the default `RuntimeGenesisConfig` and returns it as a JSON blob.
/// Build `RuntimeGenesisConfig` from a JSON blob not using any defaults and store it in the
/// storage.
///
/// This function instantiates the default `RuntimeGenesisConfig` struct for the runtime and serializes it into a JSON
/// blob. It returns a `Vec<u8>` containing the JSON representation of the default `RuntimeGenesisConfig`.
fn create_default_config() -> alloc::vec::Vec<u8>;
/// In the case of a FRAME-based runtime, this function deserializes the full `RuntimeGenesisConfig` from the given JSON blob and
/// puts it into the storage. If the provided JSON blob is incorrect or incomplete or the
/// deserialization fails, an error is returned.
///
/// Please note that provided JSON blob must contain all `RuntimeGenesisConfig` fields, no
/// defaults will be used.
fn build_state(json: Vec<u8>) -> Result;
/// Build `RuntimeGenesisConfig` from a JSON blob not using any defaults and store it in the storage.
/// Returns a JSON blob representation of the built-in `RuntimeGenesisConfig` identified by
/// `id`.
///
/// This function deserializes the full `RuntimeGenesisConfig` from the given JSON blob and puts it into the storage.
/// If the provided JSON blob is incorrect or incomplete or the deserialization fails, an error is returned.
/// It is recommended to log any errors encountered during the process.
/// If `id` is `None` the function returns JSON blob representation of the default
/// `RuntimeGenesisConfig` struct of the runtime. Implementation must provide default
/// `RuntimeGenesisConfig`.
///
/// Please note that provided json blob must contain all `RuntimeGenesisConfig` fields, no defaults will be used.
fn build_config(json: alloc::vec::Vec<u8>) -> Result;
/// Otherwise function returns a JSON representation of the built-in, named
/// `RuntimeGenesisConfig` preset identified by `id`, or `None` if such preset does not
/// exists. Returned `Vec<u8>` contains bytes of JSON blob (patch) which comprises a list of
/// (potentially nested) key-value pairs that are intended for customizing the default
/// runtime genesis config. The patch shall be merged (rfc7386) with the JSON representation
/// of the default `RuntimeGenesisConfig` to create a comprehensive genesis config that can
/// be used in `build_state` method.
fn get_preset(id: &Option<PresetId>) -> Option<Vec<u8>>;
/// Returns a list of identifiers for available builtin `RuntimeGenesisConfig` presets.
///
/// The presets from the list can be queried with [`GenesisBuilder::get_preset`] method. If
/// no named presets are provided by the runtime the list is empty.
fn preset_names() -> Vec<PresetId>;
}
}