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,107 @@
 //! Chain spec and genesis build.
 //!
-//! What is chain-spec.
-//! What is genesis state and how to build it.
+//! # What is chain-spec.
+//!
+//! Chain specicfication 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 runtime in order to build genesis sate.
+//!
+//! For more informations on chain specification and its properties refer to
+//! [`sc_chain_spec#from-initial-state-to-raw-genesis`].
+//!
+//! The intial genesis state can be prvovided in the following formats:
+//!   - full,
+//!   - patch,
+//!   - raw,
+//!
+//! Each of the format is explained in [_chain-spec-format_][`sc_chain_spec#chain-spec-formats`].
+//! The
+//!
+//! ## `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 `GenesisConfig` struct is transformed into state storage items by
+//! means of the [`BuildGenesisConfig`] trait wich shall be implemented for 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 contain also 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)]
+
+//! Please not that fields of `GenesisConfig` may not be directly mapped to storage items:
+#![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
+//! sneaked peaked here: [`RuntimeGenesisConfig`].
+//!
+//! 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`].
+//! Usual implementation of [`sp_genesis_builder::GenesisBuilder`] is 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 provdes a vec of names of supported presets, while the latter one delegats the call to
+//! function that maps the name to 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`
+//! Rutime 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 authorithies for consensue, 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 acutally a json
+//! patch that will be merged with default value of `RuntimeGenesisConfig`. 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:
+//! ```
+//! cargo build -p staging-chain-spec-builder -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

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

@@ -0,0 +1,67 @@
+[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_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-genesis-builder/std",
+  "sp-runtime/std",
+  "sp-core/std",
+  "sp-std/std",
+  "sp-keyring/std",
+  "sp-application-crypto/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};