chain-spec/presets reference docs added

Cargo.toml

@@ -144,6 +144,7 @@ members = [
 	"cumulus/test/service",
 	"cumulus/xcm/xcm-emulator",
 	"docs/sdk",
+	"docs/sdk/src/reference_docs/chain_spec_runtime",
 	"polkadot",
 	"polkadot/cli",
 	"polkadot/core-primitives",

docs/sdk/Cargo.toml

@@ -55,6 +55,7 @@ sc-consensus-manual-seal = { path = "../../substrate/client/consensus/manual-sea
 sc-consensus-pow = { path = "../../substrate/client/consensus/pow" }
 sc-executor = { path = "../../substrate/client/executor" }
 sc-service = { path = "../../substrate/client/service" }
+sc-chain-spec = { path = "../../substrate/client/chain-spec" }
 
 substrate-wasm-builder = { path = "../../substrate/utils/wasm-builder" }
 
@@ -90,6 +91,7 @@ sp-core = { path = "../../substrate/primitives/core" }
 sp-keyring = { path = "../../substrate/primitives/keyring" }
 sp-runtime = { path = "../../substrate/primitives/runtime" }
 sp-arithmetic = { path = "../../substrate/primitives/arithmetic" }
+sp-genesis-builder = { path = "../../substrate/primitives/genesis-builder" }
 
 # Misc pallet dependencies
 pallet-referenda = { path = "../../substrate/frame/referenda" }
@@ -102,3 +104,6 @@ sp-version = { path = "../../substrate/primitives/version" }
 # XCM
 xcm = { package = "staging-xcm", path = "../../polkadot/xcm" }
 xcm-docs = { path = "../../polkadot/xcm/docs" }
+
+# runtime guides
+chain-spec-guide-runtime = { path = "./src/reference_docs/chain_spec_runtime" }

docs/sdk/src/reference_docs/chain_spec_genesis.rs

@@ -1,4 +1,141 @@
 //! Chain spec and genesis build.
 //!
-//! What is chain-spec.
-//! What is genesis state and how to build it.
+//! # What is chain-spec.
+//!
+//! 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:
+#![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`].
+//!
+//! Runtime exposes a dedicated runtime API for interacting with its genesis config:
+//! [`sp_genesis_builder::GenesisBuilder`]. 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 names of supported presets, while the latter one delegates the call to
+//! a function that maps the name to a preset:
+//! [`chain_spec_guide_runtime::presets::get_builtin_preset`]
+#![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/src/presets.rs", get_builtin_preset)]
+
+//! ## `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 [`get_preset`] function of
+//! `GenesisBuilder` with `id:None`.
+//!
+//! A default value for RuntimeGenesisConfig usually is not operable. This is because for some
+//! pallets it is not possible to define good defaults (e.g. 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`]. A patch can be
+//! provided as a external file (manually created) or as builtin runtime 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)]
+
+//! # 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
+//! [`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

docs/sdk/src/reference_docs/chain_spec_runtime/Cargo.toml

@@ -0,0 +1,70 @@
+[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" }
+
+[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",
+]

docs/sdk/src/reference_docs/chain_spec_runtime/build.rs

@@ -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();
+	}
+}

docs/sdk/src/reference_docs/chain_spec_runtime/src/lib.rs

@@ -0,0 +1,27 @@
+// 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)]
+
+//! A minimal runtime that shows runtime genesis state.
+
+pub mod pallets;
+pub mod presets;
+pub mod runtime;
+
+#[cfg(feature = "std")]
+pub use runtime::{WASM_BINARY, WASM_BINARY_BLOATY};