sp_genesis_builder/
lib.rs

1// This file is part of Substrate.
2
3// Copyright (C) Parity Technologies (UK) Ltd.
4// SPDX-License-Identifier: Apache-2.0
5
6// Licensed under the Apache License, Version 2.0 (the "License");
7// you may not use this file except in compliance with the License.
8// You may obtain a copy of the License at
9//
10// 	http://www.apache.org/licenses/LICENSE-2.0
11//
12// Unless required by applicable law or agreed to in writing, software
13// distributed under the License is distributed on an "AS IS" BASIS,
14// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15// See the License for the specific language governing permissions and
16// limitations under the License.
17
18#![cfg_attr(not(feature = "std"), no_std)]
19
20//! Substrate genesis config builder
21//!
22//! For FRAME based runtimes, this runtime interface provides means to interact with
23//! `RuntimeGenesisConfig`. Runtime provides a default `RuntimeGenesisConfig` structure in a form of
24//! the JSON blob.
25//!
26//! For non-FRAME runtimes this interface is intended to build genesis state of the runtime basing
27//! on some input arbitrary bytes array. This documentation uses term `RuntimeGenesisConfig`, which
28//! for non-FRAME runtimes may be understood as the runtime-side entity representing initial runtime
29//! configuration. The representation of the preset is an arbitrary `Vec<u8>` and does not
30//! necessarily have to represent a JSON blob.
31//!
32//! The runtime may provide a number of partial predefined `RuntimeGenesisConfig` configurations in
33//! the form of patches which shall be applied on top of the default `RuntimeGenesisConfig`. The
34//! patch is a JSON blob, which essentially comprises the list of key-value pairs that are to be
35//! customized in the default runtime genesis config. These predefined configurations are referred
36//! to as presets.
37//!
38//! This allows the runtime to provide a number of predefined configs (e.g. for different
39//! testnets or development) without neccessity to leak the runtime types outside the itself (e.g.
40//! node or chain-spec related tools).
41//!
42//! This Runtime API allows to interact with `RuntimeGenesisConfig`, in particular:
43//! - provide the list of available preset names,
44//! - provide a number of named presets of `RuntimeGenesisConfig`,
45//! - provide a JSON represention of the default `RuntimeGenesisConfig` (by simply serializing the
46//!   default `RuntimeGenesisConfig` struct into JSON format),
47//! - deserialize the full `RuntimeGenesisConfig` from given JSON blob and put the resulting
48//!   `RuntimeGenesisConfig` structure into the state storage creating the initial runtime's state.
49//!   Allows to build customized genesis. This operation internally calls `GenesisBuild::build`
50//!   function for all runtime pallets.
51//!
52//! Providing externalities with an empty storage and putting `RuntimeGenesisConfig` into storage
53//! (by calling `build_state`) allows to construct the raw storage of `RuntimeGenesisConfig`
54//! which is the foundation for genesis block.
55
56extern crate alloc;
57use alloc::vec::Vec;
58
59/// The result type alias, used in build methods. `Err` contains formatted error message.
60pub type Result = core::result::Result<(), sp_runtime::RuntimeString>;
61
62/// The type representing preset ID.
63pub type PresetId = sp_runtime::RuntimeString;
64
65/// The default `development` preset used to communicate with the runtime via
66/// [`GenesisBuilder`] interface.
67///
68/// (Recommended for testing with a single node, e.g., for benchmarking)
69pub const DEV_RUNTIME_PRESET: &'static str = "development";
70
71/// The default `local_testnet` preset used to communicate with the runtime via
72/// [`GenesisBuilder`] interface.
73///
74/// (Recommended for local testing with multiple nodes)
75pub const LOCAL_TESTNET_RUNTIME_PRESET: &'static str = "local_testnet";
76
77sp_api::decl_runtime_apis! {
78	/// API to interact with RuntimeGenesisConfig for the runtime
79	pub trait GenesisBuilder {
80		/// Build `RuntimeGenesisConfig` from a JSON blob not using any defaults and store it in the
81		/// storage.
82		///
83		/// In the case of a FRAME-based runtime, this function deserializes the full `RuntimeGenesisConfig` from the given JSON blob and
84		/// puts it into the storage. If the provided JSON blob is incorrect or incomplete or the
85		/// deserialization fails, an error is returned.
86		///
87		/// Please note that provided JSON blob must contain all `RuntimeGenesisConfig` fields, no
88		/// defaults will be used.
89		fn build_state(json: Vec<u8>) -> Result;
90
91		/// Returns a JSON blob representation of the built-in `RuntimeGenesisConfig` identified by
92		/// `id`.
93		///
94		/// If `id` is `None` the function returns JSON blob representation of the default
95		/// `RuntimeGenesisConfig` struct of the runtime. Implementation must provide default
96		/// `RuntimeGenesisConfig`.
97		///
98		/// Otherwise function returns a JSON representation of the built-in, named
99		/// `RuntimeGenesisConfig` preset identified by `id`, or `None` if such preset does not
100		/// exist. Returned `Vec<u8>` contains bytes of JSON blob (patch) which comprises a list of
101		/// (potentially nested) key-value pairs that are intended for customizing the default
102		/// runtime genesis config. The patch shall be merged (rfc7386) with the JSON representation
103		/// of the default `RuntimeGenesisConfig` to create a comprehensive genesis config that can
104		/// be used in `build_state` method.
105		fn get_preset(id: &Option<PresetId>) -> Option<Vec<u8>>;
106
107		/// Returns a list of identifiers for available builtin `RuntimeGenesisConfig` presets.
108		///
109		/// The presets from the list can be queried with [`GenesisBuilder::get_preset`] method. If
110		/// no named presets are provided by the runtime the list is empty.
111		fn preset_names() -> Vec<PresetId>;
112	}
113}
sp_genesis_builder/lib.rs

sp_genesis_builder/
lib.rs
