forked from paritytech/polkadot-sdk
-
Notifications
You must be signed in to change notification settings - Fork 4
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
chain-spec/presets reference docs added (paritytech#4678)
Added reference doc about: - the pallet genesis config and genesis build, - runtime `genesis-builder` API, - presets, - interacting with the `chain-spec-builder` tool I've added [minimal runtime](https://github.com/paritytech/polkadot-sdk/tree/mku-chain-spec-guide/docs/sdk/src/reference_docs/chain_spec_runtime) to demonstrate above topics. I also sneaked in some little improvement to `chain-spec-builder` which allows to parse output of the `list-presets` command. --------- Co-authored-by: Alexandru Vasile <[email protected]> Co-authored-by: Sebastian Kunert <[email protected]>
- Loading branch information
1 parent
84177e8
commit ac2de17
Showing
15 changed files
with
905 additions
and
11 deletions.
There are no files selected for viewing
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,4 +1,185 @@ | ||
| //! Chain spec and genesis build. | ||
| //! # What is chain-spec. | ||
| //! | ||
| //! What is chain-spec. | ||
| //! What is genesis state and how to build it. | ||
| //! A chain specification file defines the set of properties that are required to run the node as | ||
| //! part of the chain. The chain specification consists of two main parts: | ||
| //! - initial state of the runtime, | ||
| //! - network / logical properties of the chain, the most important property being the list of | ||
| //! bootnodes. | ||
| //! | ||
| //! This document describes how initial state is handled in pallets and runtime, and how to interact | ||
| //! with the runtime in order to build genesis state. | ||
| //! | ||
| //! For more information on chain specification and its properties, refer to | ||
| //! [`sc_chain_spec#from-initial-state-to-raw-genesis`]. | ||
| //! | ||
| //! The initial genesis state can be provided in the following formats: | ||
| //! - full | ||
| //! - patch | ||
| //! - raw | ||
| //! | ||
| //! Each of the formats is explained in [_chain-spec-format_][`sc_chain_spec#chain-spec-formats`]. | ||
| //! | ||
| //! | ||
| //! # `GenesisConfig` for `pallet` | ||
| //! | ||
| //! Every frame pallet may have its initial state which is defined by the `GenesisConfig` internal | ||
| //! struct. It is a regular rust struct, annotated with [`pallet::genesis_config`] attribute. | ||
| #![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/src/pallets.rs", pallet_bar_GenesisConfig)] | ||
| //! | ||
| //! The struct shall be defined within the pallet `mod`, as in the following code: | ||
| #![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/src/pallets.rs", pallet_bar)] | ||
| //! | ||
| //! The initial state conveyed in the `GenesisConfig` struct is transformed into state storage | ||
| //! items by means of the [`BuildGenesisConfig`] trait which shall be implemented for the pallet's | ||
| //! `GenesisConfig` struct. The [`pallet::genesis_build`] attribute shall be attached to the `impl` | ||
| //! block: | ||
| #![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/src/pallets.rs", pallet_bar_build)] | ||
| //! | ||
| //! `GenesisConfig` may also contain more complicated types, including nested structs or enums, as | ||
| //! in the example for `pallet_foo`: | ||
| #![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/src/pallets.rs", pallet_foo_GenesisConfig)] | ||
| //! | ||
| //! Note that [`serde`] attributes can be used to control how the data | ||
| //! structures are being stored into JSON. In the following example [`sp_core::bytes`] function is | ||
| //! used to serialize the `values` field. | ||
| #![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/src/pallets.rs", SomeFooData2)] | ||
| //! | ||
| //! Please note that fields of `GenesisConfig` may not be directly mapped to storage items. In the | ||
| //! following example the initial struct fields are used to compute (sum) the value that will be | ||
| //! stored in state as `ProcessedEnumValue`: | ||
| #![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/src/pallets.rs", pallet_foo_build)] | ||
| //! | ||
| //! # `GenesisConfig` for `runtimes` | ||
| //! | ||
| //! The runtime genesis config struct consists of configs for every pallet. For [_demonstration | ||
| //! runtime_][`chain_spec_guide_runtime`] used in this guide, it consists of `SystemConfig`, | ||
| //! `BarConfig` and `FooConfig`. This structure was automatically generated by macro and it can be | ||
| //! sneak peaked here: [`RuntimeGenesisConfig`]. For further reading on generated runtime | ||
| //! types refer to [`frame_runtime_types`]. | ||
| //! | ||
| //! The macro automatically adds an attribute that renames all the fields to [`camelCase`]. It is a | ||
| //! good practice to add it to nested structures too, to have the naming of the JSON keys consistent | ||
| //! across the chain-spec file. | ||
| //! | ||
| //! ## `Default` for `GenesisConfig` | ||
| //! | ||
| //! `GenesisConfig` of all pallets must implement `Defualt` trait. Those are aggregated into | ||
| //! runtime's `RuntimeGenesisConfig`'s `Default`. | ||
| //! | ||
| //! Default value of `RuntimeGenesisConfig` can be queried by [`GenesisBuilder::get_preset`] | ||
| //! function provided by runtime with `id:None`. | ||
| //! | ||
| //! A default value for RuntimeGenesisConfig usually is not operational. This is because for some | ||
| //! pallets it is not possible to define good defaults (e.g. an initial set of authorities). | ||
| //! | ||
| //! A default value is a base upon which a patch for `GenesisConfig` is applied. A good description | ||
| //! of how it exactly works is provided in [`get_storage_for_patch`] (and also in | ||
| //! [`GenesisBuilder::get_preset`]). A patch can be provided as a external file (manually created) | ||
| //! or as builtin runtime preset. More info on presets are in the material to follow. | ||
| //! | ||
| //! ## Implementing `GenesisBuilder` for runtime | ||
| //! | ||
| //! The runtime exposes a dedicated runtime API for interacting with its genesis config: | ||
| //! [`sp_genesis_builder::GenesisBuilder`]. The implementation shall be provided within | ||
| //! [`sp_api::impl_runtime_apis`] macro, typically making use of some helpers provided: | ||
| //! [`build_state`], [`get_preset`]. | ||
| //! A typical implementation of [`sp_genesis_builder::GenesisBuilder`] looks as follows: | ||
| #![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/src/runtime.rs", runtime_impl)] | ||
| //! | ||
| //! Please note that two functions are customized: `preset_names` and `get_preset`. The first one | ||
| //! just provides a `Vec` of the names of supported presets, while the latter one delegates the call | ||
| //! to a function that maps the name to an actual preset: | ||
| //! [`chain_spec_guide_runtime::presets::get_builtin_preset`] | ||
| #![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/src/presets.rs", get_builtin_preset)] | ||
| //! | ||
| //! ## Genesis state presets for runtime | ||
| //! | ||
| //! The runtime may provide many flavors of initial genesis state. This may be useful for predefined | ||
| //! testing networks, local development, or CI integration tests. Predefined genesis state may | ||
| //! contain a list of pre-funded accounts, predefined authorities for consensus, sudo key and many | ||
| //! others useful for testing. | ||
| //! | ||
| //! Internally presets can be provided in a number of ways: | ||
| //! - JSON in string form: | ||
| #![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/src/presets.rs", preset_1)] | ||
| //! - JSON using runtime types to serialize values: | ||
| #![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/src/presets.rs", preset_2)] | ||
| #![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/src/presets.rs", preset_3)] | ||
| //! It is worth noting that preset does not have to be the full `RuntimeGenesisConfig`, in that | ||
| //! sense that it does not have to contain all the keys of the struct. The preset is actually a JSON | ||
| //! patch that will be merged with default value of `RuntimeGenesisConfig`. This approach should | ||
| //! simplify maintanance of builtin presets. Following example illustrates runtime genesis config | ||
| //! patch: | ||
| #![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/src/presets.rs", preset_4)] | ||
| //! | ||
| //! ## Note on the importance of testing presets | ||
| //! | ||
| //! It is recommended to always test presets by adding the tests that convert the preset into the | ||
| //! raw storage. Converting to raw storage involves the deserialization of the provided JSON blob, | ||
| //! what enforces the verification of the preset. The following code shows one of the approaches | ||
| //! that can be taken for testing: | ||
| #![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/src/presets.rs", check_presets)] | ||
| //! | ||
| //! ## Note on tne importance of using `deny_unknown_fields` attribute | ||
| //! | ||
| //! It is worth noting that it is easy to make a hard to spot mistake as in the following example | ||
| //! ([`FooStruct`] does not contain `fieldC`): | ||
| #![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/src/presets.rs", preset_invalid)] | ||
| //! Even though `preset_invalid` contains a key that does not exist, the deserialization of the JSON | ||
| //! blob does not fail. The mispelling is silently ignored due to lack of [`deny_unknown_fields`] | ||
| //! attribute on the [`FooStruct`] struct, which is internally used in `GenesisConfig`. | ||
| #![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/src/presets.rs", invalid_preset_works)] | ||
| //! | ||
| //! ## Runtime `GenesisConfig` raw format | ||
| //! | ||
| //! A raw format of genesis config cotains just state's keys and values as they are stored in the | ||
| //! storage. This format is used to directly initialize the genesis storage. This format is useful | ||
| //! for long-term running chains, where the `GenesisConfig` stucture for pallets may be evolving | ||
| //! over the time. The JSON representation created at some point in time may no longer be | ||
| //! deserializable in future, making a chain specification useless. The raw format is recommended | ||
| //! for the production chains. | ||
| //! | ||
| //! For detailed description on how raw format is built please refer to | ||
| //! [_chain-spec-raw-genesis_][`sc_chain_spec#from-initial-state-to-raw-genesis`]. A plain and | ||
| //! corresponding raw examples of chain-spec are given in | ||
| //! [_chain-spec-examples_][`sc_chain_spec#json-chain-specification-example`]. | ||
| //! The [`chain_spec_builder`] util supports building the raw storage. | ||
| //! | ||
| //! # Interacting with the tool | ||
| //! | ||
| //! The [`chain_spec_builder`] util allows to interact with runtime in order to list or display | ||
| //! presets and build the chain specification file. It is possible to use the tool with the | ||
| //! [_demonstration runtime_][`chain_spec_guide_runtime`]. To build required packages just run the | ||
| //! following command: | ||
| //! ```ignore | ||
| //! cargo build -p staging-chain-spec-builder -p chain-spec-guide-runtime --release | ||
| //! ``` | ||
| //! The `chain-spec-builder` util can also be installed with `cargo install`: | ||
| //! ```ignore | ||
| //! cargo install staging-chain-spec-builder | ||
| //! cargo build -p chain-spec-guide-runtime --release | ||
| //! ``` | ||
| //! Here are some examples in the form of rust tests: | ||
| //! ## Listing available presets names: | ||
| #![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/tests/chain_spec_builder_tests.rs", list_presets)] | ||
| //! ## Displaying preset with given name | ||
| #![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/tests/chain_spec_builder_tests.rs", get_preset)] | ||
| //! ## Building chain-spec using given preset | ||
| #![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/tests/chain_spec_builder_tests.rs", generate_chain_spec)] | ||
| //! | ||
| //! [`RuntimeGenesisConfig`]: | ||
| //! chain_spec_guide_runtime::runtime::RuntimeGenesisConfig | ||
| //! [`FooStruct`]: | ||
| //! chain_spec_guide_runtime::pallets::FooStruct | ||
| //! [`impl_runtime_apis`]: frame::runtime::prelude::impl_runtime_apis | ||
| //! [`build_state`]: frame_support::genesis_builder_helper::build_state | ||
| //! [`get_preset`]: frame_support::genesis_builder_helper::get_preset | ||
| //! [`pallet::genesis_build`]: frame_support::pallet_macros::genesis_build | ||
| //! [`pallet::genesis_config`]: frame_support::pallet_macros::genesis_config | ||
| //! [`BuildGenesisConfig`]: frame_support::traits::BuildGenesisConfig | ||
| //! [`chain_spec_builder`]: ../../../staging_chain_spec_builder/index.html | ||
| //! [`serde`]: https://serde.rs/field-attrs.html | ||
| //! [`get_storage_for_patch`]: sc_chain_spec::GenesisConfigBuilderRuntimeCaller::get_storage_for_patch | ||
| //! [`GenesisBuilder::get_preset`]: sp_genesis_builder::GenesisBuilder::get_preset | ||
| //! [`deny_unknown_fields`]: https://serde.rs/container-attrs.html#deny_unknown_fields | ||
| //! [`camelCase`]: https://serde.rs/container-attrs.html#rename_all |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,71 @@ | ||
| [package] | ||
| name = "chain-spec-guide-runtime" | ||
| description = "A minimal runtime for chain spec guide" | ||
| version = "0.0.0" | ||
| license = "MIT-0" | ||
| authors.workspace = true | ||
| homepage.workspace = true | ||
| repository.workspace = true | ||
| edition.workspace = true | ||
| publish = false | ||
|
|
||
| [dependencies] | ||
| docify = "0.2.8" | ||
| parity-scale-codec = { version = "3.6.12", default-features = false } | ||
| scale-info = { version = "2.6.0", default-features = false } | ||
| serde = { workspace = true, default-features = false } | ||
| serde_json = { workspace = true } | ||
|
|
||
| # this is a frame-based runtime, thus importing `frame` with runtime feature enabled. | ||
| frame = { package = "polkadot-sdk-frame", path = "../../../../../substrate/frame", default-features = false, features = [ | ||
| "experimental", | ||
| "runtime", | ||
| ] } | ||
|
|
||
| # pallets that we want to use | ||
| pallet-balances = { path = "../../../../../substrate/frame/balances", default-features = false } | ||
| pallet-sudo = { path = "../../../../../substrate/frame/sudo", default-features = false } | ||
| pallet-timestamp = { path = "../../../../../substrate/frame/timestamp", default-features = false } | ||
| pallet-transaction-payment = { path = "../../../../../substrate/frame/transaction-payment", default-features = false } | ||
| pallet-transaction-payment-rpc-runtime-api = { path = "../../../../../substrate/frame/transaction-payment/rpc/runtime-api", default-features = false } | ||
|
|
||
| # genesis builder that allows us to interact with runtime genesis config | ||
| sp-genesis-builder = { path = "../../../../../substrate/primitives/genesis-builder", default-features = false } | ||
| sp-runtime = { path = "../../../../../substrate/primitives/runtime", default-features = false, features = ["serde"] } | ||
| sp-core = { path = "../../../../../substrate/primitives/core", default-features = false } | ||
| sp-std = { path = "../../../../../substrate/primitives/std", default-features = false } | ||
| sp-keyring = { path = "../../../../../substrate/primitives/keyring", default-features = false } | ||
| sp-application-crypto = { path = "../../../../../substrate/primitives/application-crypto", default-features = false, features = ["serde"] } | ||
|
|
||
| [build-dependencies] | ||
| substrate-wasm-builder = { path = "../../../../../substrate/utils/wasm-builder", optional = true } | ||
|
|
||
| [dev-dependencies] | ||
| chain-spec-builder = { package = "staging-chain-spec-builder", path = "../../../../../substrate/bin/utils/chain-spec-builder" } | ||
| sc-chain-spec = { path = "../../../../../substrate/client/chain-spec" } | ||
|
|
||
| [features] | ||
| default = ["std"] | ||
| std = [ | ||
| "parity-scale-codec/std", | ||
| "scale-info/std", | ||
|
|
||
| "frame/std", | ||
|
|
||
| "pallet-balances/std", | ||
| "pallet-sudo/std", | ||
| "pallet-timestamp/std", | ||
| "pallet-transaction-payment-rpc-runtime-api/std", | ||
| "pallet-transaction-payment/std", | ||
|
|
||
| "sp-application-crypto/std", | ||
| "sp-core/std", | ||
| "sp-genesis-builder/std", | ||
| "sp-keyring/std", | ||
| "sp-runtime/std", | ||
| "sp-std/std", | ||
|
|
||
| "serde/std", | ||
| "serde_json/std", | ||
| "substrate-wasm-builder", | ||
| ] |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,23 @@ | ||
| // 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. | ||
|
|
||
| fn main() { | ||
| #[cfg(feature = "std")] | ||
| { | ||
| substrate_wasm_builder::WasmBuilder::build_using_defaults(); | ||
| } | ||
| } |
Oops, something went wrong.