Crate sp_genesis_builder

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.

Constants

DEV_RUNTIME_PRESET

The default development preset used to communicate with the runtime via GenesisBuilder interface.

LOCAL_TESTNET_RUNTIME_PRESET

The default local_testnet preset used to communicate with the runtime via GenesisBuilder interface.

Traits

GenesisBuilder

API to interact with RuntimeGenesisConfig for the runtime

Type Aliases

PresetId

The type representing preset ID.

Result

The result type alias, used in build methods. Err contains formatted error message.