Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

chain-spec/presets reference docs added #4678

Merged
merged 17 commits into from
Jun 4, 2024
Merged

chain-spec/presets reference docs added #4678

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
5a94d54
initial work
michalkucharczyk Jun 1, 2024
2c122e2
chain-spec: added docs for genesis config, genesis_build and presets
michalkucharczyk Jun 3, 2024
61e95a0
todo removed
michalkucharczyk Jun 3, 2024
ec44a9c
taplo happy now
michalkucharczyk Jun 3, 2024
712f187
workaround for lack of dev-deps to binaries
michalkucharczyk Jun 3, 2024
1aea163
Apply suggestions from code review
michalkucharczyk Jun 3, 2024
9c45864
deps fix
michalkucharczyk Jun 3, 2024
681f33e
taplo fmt again
michalkucharczyk Jun 3, 2024
2d8d623
doc test fix
michalkucharczyk Jun 3, 2024
51cf9fe
rust doc again
michalkucharczyk Jun 3, 2024
e1da43b
Apply suggestions from code review
michalkucharczyk Jun 4, 2024
c5d1f86
review comments (default section added)
michalkucharczyk Jun 4, 2024
bf15ed3
cargo install note added
michalkucharczyk Jun 4, 2024
7eef237
Merge remote-tracking branch 'origin/master' into mku-chain-spec-guide
michalkucharczyk Jun 4, 2024
db27a4b
final touches + added some notes on serde attributes
michalkucharczyk Jun 4, 2024
6b27b93
Merge remote-tracking branch 'origin/master' into mku-chain-spec-guide
michalkucharczyk Jun 4, 2024
50898ab
fmt
michalkucharczyk Jun 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 30 additions & 1 deletion Cargo.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
5 changes: 5 additions & 0 deletions docs/sdk/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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" }

Expand Down Expand Up @@ -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" }
Expand All @@ -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" }
187 changes: 184 additions & 3 deletions docs/sdk/src/reference_docs/chain_spec_genesis.rs
View file
Open in desktop
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)]
//!
michalkucharczyk marked this conversation as resolved.
Show resolved Hide resolved
//! # `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`,
michalkucharczyk marked this conversation as resolved.
Show resolved Hide resolved
//! `BarConfig` and `FooConfig`. This structure was automatically generated by macro and it can be
//! sneak peaked here: [`RuntimeGenesisConfig`]. For further reading on generated runtime
michalkucharczyk marked this conversation as resolved.
Show resolved Hide resolved
//! 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
michalkucharczyk marked this conversation as resolved.
Show resolved Hide resolved
//! 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
//! ```
michalkucharczyk marked this conversation as resolved.
Show resolved Hide resolved
//! 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
71 changes: 71 additions & 0 deletions docs/sdk/src/reference_docs/chain_spec_runtime/Cargo.toml
View file
Open in desktop
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",
]
23 changes: 23 additions & 0 deletions docs/sdk/src/reference_docs/chain_spec_runtime/build.rs
View file
Open in desktop
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();
}
}
Loading
Loading