23 releases (breaking)

0.16.0 Jan 7, 2025
0.15.1 Sep 25, 2024
0.15.0 Jul 18, 2024
0.10.0 Mar 18, 2024
0.1.0-dev.2 Jul 27, 2023

#11 in #genesis

Download history 29338/week @ 2024-11-17 32205/week @ 2024-11-24 26092/week @ 2024-12-01 33116/week @ 2024-12-08 26390/week @ 2024-12-15 7744/week @ 2024-12-22 13705/week @ 2024-12-29 24864/week @ 2025-01-05 36833/week @ 2025-01-12 34936/week @ 2025-01-19 30103/week @ 2025-01-26 32503/week @ 2025-02-02 37217/week @ 2025-02-09 37239/week @ 2025-02-16 14690/week @ 2025-02-23 6906/week @ 2025-03-02

97,782 downloads per month
Used in 415 crates (40 directly)

Apache-2.0

1MB
7.5K SLoC

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.

Dependencies

~18–32MB
~523K SLoC