From 0bf14335fac7a8eda6c4e5324fb3fcfcba86ccf6 Mon Sep 17 00:00:00 2001 From: Michal Kucharczyk <1728078+michalkucharczyk@users.noreply.github.com> Date: Mon, 26 Jun 2023 13:56:15 +0200 Subject: [PATCH] `GenesisBuilder` runtime API (#14131) * GenesisConfigBuilder: preliminary API proposal * fmt * comment removed * build_default_config removed * Update client/genesis-builder/src/lib.rs * config -> gensis_config * GenesisConfigBuilder: helper added * moved to primitives * licesne changed to apache-2.0 * Cargo.toml: name/path to genesis-builder updated * helper removed * sp-sd version bumped * sp-std bump * naming + new function * fix * build_from_patch_json -> build_with_patch * fix * Cargo.lock updated * readme: license updated * Update primitives/genesis-builder/src/lib.rs Co-authored-by: Davide Galassi * Update primitives/genesis-builder/src/lib.rs Co-authored-by: Davide Galassi * Update primitives/genesis-builder/Cargo.toml Co-authored-by: Davide Galassi * Cargo.lock updated * removed redundant function * GenesisConfigBuilder API: no_defaults function added * Cargo.lock updated * GenesisConfigBuilder API: patching fn removed * trigger CI job --------- Co-authored-by: parity-processbot <> Co-authored-by: Davide Galassi --- Cargo.lock | 10 +++++ Cargo.toml | 1 + primitives/genesis-builder/Cargo.toml | 27 ++++++++++++++ primitives/genesis-builder/README.md | 5 +++ primitives/genesis-builder/src/lib.rs | 54 +++++++++++++++++++++++++++ 5 files changed, 97 insertions(+) create mode 100644 primitives/genesis-builder/Cargo.toml create mode 100644 primitives/genesis-builder/README.md create mode 100644 primitives/genesis-builder/src/lib.rs diff --git a/Cargo.lock b/Cargo.lock index d9fe360a25485..e001fdab27352 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -11142,6 +11142,16 @@ dependencies = [ "sp-storage", ] +[[package]] +name = "sp-genesis-builder" +version = "0.1.0" +dependencies = [ + "serde_json", + "sp-api", + "sp-runtime", + "sp-std", +] + [[package]] name = "sp-inherents" version = "4.0.0-dev" diff --git a/Cargo.toml b/Cargo.toml index 8e2ba85f43088..0ad71911ae017 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -206,6 +206,7 @@ members = [ "primitives/database", "primitives/debug-derive", "primitives/externalities", + "primitives/genesis-builder", "primitives/inherents", "primitives/io", "primitives/keyring", diff --git a/primitives/genesis-builder/Cargo.toml b/primitives/genesis-builder/Cargo.toml new file mode 100644 index 0000000000000..de543f0a74acf --- /dev/null +++ b/primitives/genesis-builder/Cargo.toml @@ -0,0 +1,27 @@ +[package] +name = "sp-genesis-builder" +version = "0.1.0" +authors = ["Parity Technologies "] +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", +] diff --git a/primitives/genesis-builder/README.md b/primitives/genesis-builder/README.md new file mode 100644 index 0000000000000..4a842c95e358e --- /dev/null +++ b/primitives/genesis-builder/README.md @@ -0,0 +1,5 @@ +Substrate genesis builder. + +Refer to the module doc for more details. + +License: Apache-2.0 diff --git a/primitives/genesis-builder/src/lib.rs b/primitives/genesis-builder/src/lib.rs new file mode 100644 index 0000000000000..e002cd3aa6f70 --- /dev/null +++ b/primitives/genesis-builder/src/lib.rs @@ -0,0 +1,54 @@ +// 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 { + /// Creates the default `GenesisConfig` and returns it 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` containing the JSON representation of the default `GenesisConfig`. + fn create_default_config() -> sp_std::vec::Vec; + + /// 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(json: sp_std::vec::Vec) -> Result; + } +}