## Module chain_spec_genesis

Source
Expand description

Learn about chain specification file and the genesis state of the blockchain.

## §What is a chain specification

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 the initial state is handled in pallets and runtime, and how to interact with the runtime in order to build the 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 the `pallet::genesis_config` attribute.

ⓘ

    #[pallet::genesis_config]
    #[derive(DefaultNoBound)]
    pub struct GenesisConfig<T: Config> {
    	pub initial_account: Option<T::AccountId>,
    }

The struct shall be defined within the pallet `mod`, as in the following code:

ⓘ

    #[frame::pallet(dev_mode)]
    pub mod pallet_bar {
    	use super::*;

    	#[pallet::config]
    	pub trait Config: frame_system::Config {}

    	#[pallet::pallet]
    	pub struct Pallet<T>(_);

    	#[pallet::storage]
    	pub(super) type InitialAccount<T: Config> = StorageValue<Value = T::AccountId>;

    	/// Simple `GenesisConfig`.
    	#[pallet::genesis_config]
    	#[derive(DefaultNoBound)]
    	pub struct GenesisConfig<T: Config> {
    		pub initial_account: Option<T::AccountId>,
    	}

    	#[pallet::genesis_build]
    	impl<T: Config> BuildGenesisConfig for GenesisConfig<T> {
    		/// The storage building function that presents a direct mapping of the initial config
    		/// values to the storage items.
    		fn build(&self) {
    			InitialAccount::<T>::set(self.initial_account.clone());
    		}
    	}
    }

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:

ⓘ

    #[pallet::genesis_build]
    impl<T: Config> BuildGenesisConfig for GenesisConfig<T> {
    	/// The storage building function that presents a direct mapping of the initial config
    	/// values to the storage items.
    	fn build(&self) {
    		InitialAccount::<T>::set(self.initial_account.clone());
    	}
    }

`GenesisConfig` may also contain more complicated types, including nested structs or enums, as in the example for `pallet_foo`:

ⓘ

    #[pallet::genesis_config]
    #[derive(DefaultNoBound)]
    pub struct GenesisConfig<T: Config> {
    	pub some_integer: u32,
    	pub some_enum: FooEnum,
    	pub some_struct: FooStruct,
    	#[serde(skip)]
    	pub _phantom: PhantomData<T>,
    }

Note that `serde` attributes can be used to control how the data structures are stored into JSON. In the following example, the [`sp_core::bytes`] function is used to serialize the `values` field.

ⓘ

    #[derive(Default, serde::Serialize, serde::Deserialize)]
    #[serde(deny_unknown_fields, rename_all = "camelCase")]
    pub struct SomeFooData2 {
    	#[serde(default, with = "sp_core::bytes")]
    	pub values: Vec<u8>,
    }

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 the state as `ProcessedEnumValue`:

ⓘ

    #[pallet::genesis_build]
    impl<T: Config> BuildGenesisConfig for GenesisConfig<T> {
    	/// The build method that indirectly maps an initial config values into the storage items.
    	fn build(&self) {
    		let processed_value: u64 = match &self.some_enum {
    			FooEnum::Data0 => 0,
    			FooEnum::Data1(v) => (v.a + v.b).into(),
    			FooEnum::Data2(v) => v.values.iter().map(|v| *v as u64).sum(),
    		};
    		ProcessedEnumValue::<T>::set(Some(processed_value));
    		SomeInteger::<T>::set(Some(self.some_integer));
    	}
    }

## §`GenesisConfig` for `runtimes`

The runtime genesis config struct consists of configs for every pallet. For the [demonstration runtime][`chain_spec_guide_runtime`] used in this guide, it consists of `SystemConfig`, `BarConfig`, and `FooConfig`. This structure was automatically generated by a macro and it can be sneak-peeked here: `RuntimeGenesisConfig`. For further reading on generated runtime 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 the `Default` trait. These are aggregated into the runtime’s `RuntimeGenesisConfig`’s `Default`.

The default value of `RuntimeGenesisConfig` can be queried by the `GenesisBuilder::get_preset` function provided by the 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 an external file (manually created) or as a built-in runtime preset. More info on presets is 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 the [`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:

ⓘ

    impl_runtime_apis! {
    	impl sp_genesis_builder::GenesisBuilder<Block> for Runtime {
    		fn build_state(config: Vec<u8>) -> sp_genesis_builder::Result {
    			build_state::<RuntimeGenesisConfig>(config)
    		}

    		fn get_preset(id: &Option<sp_genesis_builder::PresetId>) -> Option<Vec<u8>> {
    			get_preset::<RuntimeGenesisConfig>(id, get_builtin_preset)
    		}

    		fn preset_names() -> Vec<sp_genesis_builder::PresetId> {
    			vec![
    				PresetId::from(PRESET_1),
    				PresetId::from(PRESET_2),
    				PresetId::from(PRESET_3),
    				PresetId::from(PRESET_4),
    				PresetId::from(PRESET_INVALID)
    			]
    		}
    	}

    	impl apis::Core<Block> for Runtime {
    		fn version() -> RuntimeVersion { VERSION }
    		fn execute_block(_: <Block as frame::traits::Block>::LazyBlock) { }
    		fn initialize_block(_: &Header) -> ExtrinsicInclusionMode { ExtrinsicInclusionMode::default() }
    	}
    }

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 delegates the call to a function that maps the name to an actual preset: [`chain_spec_guide_runtime::presets::get_builtin_preset`]

ⓘ

    pub fn get_builtin_preset(id: &sp_genesis_builder::PresetId) -> Option<alloc::vec::Vec<u8>> {
    	let preset = match id.as_ref() {
    		PRESET_1 => preset_1(),
    		PRESET_2 => preset_2(),
    		PRESET_3 => preset_3(),
    		PRESET_4 => preset_4(),
    		PRESET_INVALID => preset_invalid(),
    		_ => return None,
    	};

    	Some(
    		to_string(&preset)
    			.expect("serialization to json is expected to work. qed.")
    			.into_bytes(),
    	)
    }

### §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:

- using `build_struct_json_patch` macro (recommended):

ⓘ

    fn preset_2() -> Value {
    	build_struct_json_patch!(RuntimeGenesisConfig {
    		foo: FooConfig {
    			some_integer: 200,
    			some_enum: FooEnum::Data2(SomeFooData2 { values: vec![0x0c, 0x10] })
    		},
    		bar: BarConfig { initial_account: Some(Sr25519Keyring::Ferdie.public().into()) },
    	})
    }

- JSON using runtime types to serialize values:

ⓘ

    fn preset_3() -> Value {
    	json!({
    		"bar": {
    			"initialAccount": Sr25519Keyring::Alice.public().to_ss58check(),
    		},
    		"foo": {
    			"someEnum": FooEnum::Data1(
    				SomeFooData1 {
    					a: 12,
    					b: 16
    				}
    			),
    			"someInteger": 300
    		},
    	})
    }

- JSON in string form:

ⓘ

    fn preset_1() -> Value {
    	json!({
    		"bar": {
    			"initialAccount": "5CiPPseXPECbkjWCa6MnjNokrgYjMqmKndv2rSnekmSK2DjL",
    		},
    		"foo": {
    			"someEnum": {
    				"Data2": {
    					"values": "0x0c0f"
    				}
    			},
    			"someStruct" : {
    				"fieldA": 10,
    				"fieldB": 20
    			},
    			"someInteger": 100
    		},
    	})
    }

It is worth noting that a 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 the default value of `RuntimeGenesisConfig`. This approach should simplify maintenance of built-in presets. The following example illustrates a runtime genesis config patch with a single key built using `build_struct_json_patch` macro:

ⓘ

    pub fn preset_4() -> Value {
    	build_struct_json_patch!(RuntimeGenesisConfig {
    		foo: FooConfig { some_enum: FooEnum::Data2(SomeFooData2 { values: vec![0x0c, 0x10] }) },
    	})
    }

This results in the following JSON blob:

ⓘ

    assert_eq!(
    	chain_spec_guide_runtime::presets::preset_4(),
    	json!({
    		"foo": {
    			"someEnum": {
    				"Data2": {
    					"values": "0x0c10"
    				}
    			},
    		},
    	})
    );

### §Note on the importance of testing presets

It is recommended to always test presets by adding tests that convert the preset into the raw storage. Converting to raw storage involves the deserialization of the provided JSON blob, which enforces the verification of the preset. The following code shows one of the approaches that can be taken for testing:

ⓘ

    #[test]
    fn check_presets() {
    	let builder = sc_chain_spec::GenesisConfigBuilderRuntimeCaller::<()>::new(
    		crate::WASM_BINARY.expect("wasm binary shall exists"),
    	);
    	assert!(builder.get_storage_for_named_preset(Some(&PRESET_1.to_string())).is_ok());
    	assert!(builder.get_storage_for_named_preset(Some(&PRESET_2.to_string())).is_ok());
    	assert!(builder.get_storage_for_named_preset(Some(&PRESET_3.to_string())).is_ok());
    	assert!(builder.get_storage_for_named_preset(Some(&PRESET_4.to_string())).is_ok());
    }

### §Note on the importance of using the `deny_unknown_fields` attribute

It is worth noting that when manually building preset JSON blobs it is easy to make a hard-to-spot mistake, as in the following example (`FooStruct` does not contain `fieldC`):

ⓘ

    fn preset_invalid() -> Value {
    	json!({
    		"foo": {
    			"someStruct": {
    				"fieldC": 5
    			},
    		},
    	})
    }

Even though `preset_invalid` contains a key that does not exist, the deserialization of the JSON blob does not fail. The misspelling is silently ignored due to the lack of the `deny_unknown_fields` attribute on the `FooStruct` struct, which is internally used in `GenesisConfig`.

ⓘ

    #[test]
    fn invalid_preset_works() {
    	let builder = sc_chain_spec::GenesisConfigBuilderRuntimeCaller::<()>::new(
    		crate::WASM_BINARY.expect("wasm binary shall exists"),
    	);
    	// Even though a preset contains invalid_key, conversion to raw storage does not fail. This is
    	// because the [`FooStruct`] structure is not annotated with `deny_unknown_fields` [`serde`]
    	// attribute.
    	// This may lead to hard to debug problems, that's why using ['deny_unknown_fields'] is
    	// recommended.
    	assert!(builder.get_storage_for_named_preset(Some(&PRESET_INVALID.to_string())).is_ok());
    }

To avoid this problem `build_struct_json_patch` macro shall be used whenever possible (it internally instantiates the struct before serializang it JSON blob, so all unknown fields shall be caught at compilation time).

### §Runtime `GenesisConfig` raw format

A raw format of genesis config contains just the 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` structure for pallets may be evolving over time. The JSON representation created at some point in time may no longer be deserializable in the future, making a chain specification useless. The raw format is recommended for production chains.

For a detailed description of how the raw format is built, please refer to [chain-spec-raw-genesis][`sc_chain_spec#from-initial-state-to-raw-genesis`]. 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 interaction with the 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 the required packages, just run the following command:

ⓘ

    cargo build -p staging-chain-spec-builder -p chain-spec-guide-runtime --release

The `chain-spec-builder` util can also be installed with `cargo install`:

ⓘ

    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 preset names:

ⓘ

    bash!(
    	chain-spec-builder list-presets -r $runtime_path
    )

### §Displaying preset with given name

ⓘ

    bash!(
    	chain-spec-builder display-preset -r $runtime_path -p preset_2
    )

### §Building a solo chain-spec (the default) using given preset

ⓘ

    bash!(
    	chain-spec-builder -c /dev/stdout create -r $runtime_path named-preset preset_2
    )

### §Building a teyrchain chain-spec using given preset

ⓘ

    bash!(
    	chain-spec-builder -c /dev/stdout create -c pezkuwi -p 1000 -r $runtime_path named-preset preset_2
    )