GenesisBuilder runtime API

Cargo.toml

@@ -205,6 +205,7 @@ members = [
 	"primitives/database",
 	"primitives/debug-derive",
 	"primitives/externalities",
+	"primitives/genesis-builder",
 	"primitives/inherents",
 	"primitives/io",
 	"primitives/keyring",

primitives/genesis-builder/Cargo.toml

@@ -0,0 +1,27 @@
+[package]
+name = "sp-genesis-builder"
+version = "0.1.0"
+authors = ["Parity Technologies <[email protected]>"]
+edition = "2021"
+license = "Apache-2.0"
+homepage = "https://substrate.io"
+repository = "https://github.com/paritytech/substrate/"
+description = "Substrate GenesisConfig builder API"
+readme = "README.md"
+
+[package.metadata.docs.rs]
+targets = ["x86_64-unknown-linux-gnu"]
+
+[dependencies]
+sp-api = { version = "4.0.0-dev", default-features = false, path = "../../primitives/api" }
+sp-runtime = { version = "24.0.0", default-features = false, path = "../../primitives/runtime" }
+sp-std = { version = "8.0.0", default-features = false, path = "../../primitives/std" }
+serde_json = { version = "1.0.85", default-features = false, features = ["alloc"] }
+
+[features]
+default = [ "std" ]
+std = [
+	"sp-api/std",
+	"sp-std/std",
+	"serde_json/std",
+]

primitives/genesis-builder/README.md

@@ -0,0 +1,5 @@
+Substrate genesis builder.
+
+Refer to the module doc for more details.
+
+License: Apache-2.0

primitives/genesis-builder/src/lib.rs

@@ -0,0 +1,73 @@
+// This file is part of Substrate.
+
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// 	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#![cfg_attr(not(feature = "std"), no_std)]
+
+//! Substrate genesis config builder
+//!
+//! This Runtime API allows to construct `GenesisConfig`, in particular:
+//! - serialize the runtime default `GenesisConfig` struct into json format,
+//! - put the GenesisConfig struct into the storage. Internally this operation calls
+//!   `GenesisBuild::build` function for all runtime pallets, which is typically provided by
+//!   pallet's author.
+//! - deserialize the `GenesisConfig` from given json blob and put `GenesisConfig` into the state
+//!   storage. Allows to build customized configuration.
+//!
+//! Providing externalities with empty storage and putting `GenesisConfig` into storage allows to
+//! catch and build the raw storage of `GenesisConfig` which is the foundation for genesis block.
+
+/// The result type alias, used in build methods. `Err` contains formatted error message.
+pub type Result = core::result::Result<(), sp_runtime::RuntimeString>;
+
+sp_api::decl_runtime_apis! {
+	/// API to interact with GenesisConfig for the runtime
+	pub trait GenesisBuilder {
+		/// Get the default `GenesisConfig` as a JSON blob.
+		///
+		/// This function instantiates the default `GenesisConfig` struct for the runtime and serializes it into a JSON
+		/// blob. It returns a `Vec<u8>` containing the JSON representation of the default `GenesisConfig`.
+		fn get_default_as_json() -> sp_std::vec::Vec<u8>;
+
+		/// Patch default `GenesisConfig` using given JSON patch and store it in the storage.
+		///
+		/// This function generates the `GenesisConfig` for the runtime by applying a provided JSON patch.
+		/// The patch modifies the default `GenesisConfig` allowing customization of the specific keys.
+		/// The resulting `GenesisConfig` is then deserialized from the patched JSON representation and
+		/// stored in the storage.
+		///
+		/// If the provided JSON patch is incorrect or the deserialization fails the error will be returned.
+		/// Method may panic if creation of json representation of default config fails.
+		///
+		/// The patching process modifies the default `GenesisConfig` according to the following rules:
+		/// 1. Existing keys in the default configuration will be overridden by the corresponding values in the patch.
+		/// 2. If a key exists in the patch but not in the default configuration, it will be added to the resulting `GenesisConfig`.
+		/// 3. Keys in the default configuration that have null values in the patch will be removed from the resulting
+		///    `GenesisConfig`. This is helpful for changing enum variant value.
+		///
+		/// Please note that the patch may contain full `GenesisConfig`.
+		fn build_config(patch: sp_std::vec::Vec<u8>) -> Result;
+
+		/// Build `GenesisConfig` from a JSON blob not using any defaults and store it in the storage.
+		///
+		/// This function deserializes the full `GenesisConfig` from the given JSON blob and puts it into the storage.
+		/// If the provided JSON blob is incorrect or incomplete or the deserialization fails, an error is returned.
+		/// It is recommended to log any errors encountered during the process.
+		///
+		/// Please note that provided json blob must contain all `GenesisConfig` fields, no defaults will be used.
+		fn build_config_no_defaults(json: sp_std::vec::Vec<u8>) -> Result;
+	}
+}