Substrate genesis builder.

Refer to the module doc for more details.

License: Apache-2.0

Release

Polkadot SDK Stable 2412

lib.rs:

Substrate genesis config builder.

This crate contains GenesisBuilder, a runtime-api to be implemented by runtimes, in order to express their genesis state.

The overall flow of the methods in GenesisBuilder is as follows:

1. GenesisBuilder::preset_names: A runtime exposes a number of different RuntimeGenesisConfig variations, each of which is called a preset, and is identified by a PresetId. All runtimes are encouraged to expose at least DEV_RUNTIME_PRESET and LOCAL_TESTNET_RUNTIME_PRESET presets for consistency.
2. GenesisBuilder::get_preset: Given a PresetId, this the runtime returns the JSON blob representation of the RuntimeGenesisConfig for that preset. This JSON blob is often mixed into the broader chain_spec. If None is given, GenesisBuilder::get_preset provides a JSON represention of the default RuntimeGenesisConfig (by simply serializing the RuntimeGenesisConfig::default() value into JSON format). This is used as a base for applying patches / presets.
3. GenesisBuilder::build_state: Given a JSON blob, this method should deserialize it and enact it (using frame_support::traits::BuildGenesisConfig for Frame-based runtime), essentially writing it to the state.

The first two flows are often done in between a runtime, and the chain_spec_builder binary. The latter is used when a new blockchain is launched to enact and store the genesis state. See the documentation of chain_spec_builder for more info.

Patching

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 necessarily to leak the runtime types outside itself (e.g. node or chain-spec related tools).

FRAME vs. non-FRAME

For FRAME based runtimes GenesisBuilder provides means to interact with RuntimeGenesisConfig.

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 genesis configuration". The representation of the preset is an arbitrary Vec<u8> and does not necessarily have to represent a JSON blob.

Genesis Block State

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.