mirror of
https://github.com/pezkuwichain/pezkuwi-subxt.git
synced 2026-06-19 14:41:02 +00:00
chain-spec: getting ready for native-runtime-free world (#1256)
This PR prepares chains specs for _native-runtime-free_ world. This PR has following changes: - `substrate`: - adds support for: - JSON based `GenesisConfig` to `ChainSpec` allowing interaction with runtime `GenesisBuilder` API. - interacting with arbitrary runtime wasm blob to[ `chain-spec-builder`](https://github.com/paritytech/substrate/blob/3ef576eaeb3f42610e85daecc464961cf1295570/bin/utils/chain-spec-builder/src/lib.rs#L46) command line util, - removes [`code`](https://github.com/paritytech/substrate/blob/3ef576eaeb3f42610e85daecc464961cf1295570/frame/system/src/lib.rs#L660) from `system_pallet` - adds `code` to the `ChainSpec` - deprecates [`ChainSpec::from_genesis`](https://github.com/paritytech/substrate/blob/3ef576eaeb3f42610e85daecc464961cf1295570/client/chain-spec/src/chain_spec.rs#L263), but also changes the signature of this method extending it with `code` argument. [`ChainSpec::builder()`](https://github.com/paritytech/substrate/blob/20bee680ed098be7239cf7a6b804cd4de267983e/client/chain-spec/src/chain_spec.rs#L507) should be used instead. - `polkadot`: - all references to `RuntimeGenesisConfig` in `node/service` are removed, - all `(kusama|polkadot|versi|rococo|wococo)_(staging|dev)_genesis_config` functions now return the JSON patch for default runtime `GenesisConfig`, - `ChainSpecBuilder` is used, `ChainSpec::from_genesis` is removed, - `cumulus`: - `ChainSpecBuilder` is used, `ChainSpec::from_genesis` is removed, - _JSON_ patch configuration used instead of `RuntimeGenesisConfig struct` in all chain specs. --------- Co-authored-by: command-bot <> Co-authored-by: Javier Viola <javier@parity.io> Co-authored-by: Davide Galassi <davxy@datawok.net> Co-authored-by: Francisco Aguirre <franciscoaguirreperez@gmail.com> Co-authored-by: Kevin Krone <kevin@parity.io> Co-authored-by: Bastian Köcher <git@kchr.de>
This commit is contained in:
Michal Kucharczyk
committed by
GitHub
GitHub
parent
c46a7dbb61
commit
8ba7a6aba8
@@ -18,8 +18,10 @@
|
||||
|
||||
//! Substrate chain configurations.
|
||||
#![warn(missing_docs)]
|
||||
|
||||
use crate::{extension::GetExtension, ChainType, Properties, RuntimeGenesis};
|
||||
use crate::{
|
||||
extension::GetExtension, ChainType, GenesisConfigBuilderRuntimeCaller as RuntimeCaller,
|
||||
Properties, RuntimeGenesis,
|
||||
};
|
||||
use sc_network::config::MultiaddrWithPeerId;
|
||||
use sc_telemetry::TelemetryEndpoints;
|
||||
use serde::{Deserialize, Serialize};
|
||||
@@ -29,13 +31,32 @@ use sp_core::{
|
||||
Bytes,
|
||||
};
|
||||
use sp_runtime::BuildStorage;
|
||||
use std::{borrow::Cow, collections::BTreeMap, fs::File, path::PathBuf, sync::Arc};
|
||||
use std::{
|
||||
borrow::Cow,
|
||||
collections::{BTreeMap, VecDeque},
|
||||
fs::File,
|
||||
marker::PhantomData,
|
||||
path::PathBuf,
|
||||
sync::Arc,
|
||||
};
|
||||
|
||||
#[derive(Serialize, Deserialize, Clone)]
|
||||
#[serde(rename_all = "camelCase")]
|
||||
enum GenesisBuildAction {
|
||||
Patch(json::Value),
|
||||
Full(json::Value),
|
||||
}
|
||||
|
||||
#[allow(deprecated)]
|
||||
enum GenesisSource<G> {
|
||||
File(PathBuf),
|
||||
Binary(Cow<'static, [u8]>),
|
||||
Factory(Arc<dyn Fn() -> G + Send + Sync>),
|
||||
/// factory function + code
|
||||
//Factory and G type parameter shall be removed togheter with `ChainSpec::from_genesis`
|
||||
Factory(Arc<dyn Fn() -> G + Send + Sync>, Vec<u8>),
|
||||
Storage(Storage),
|
||||
/// build action + code
|
||||
GenesisBuilderApi(GenesisBuildAction, Vec<u8>),
|
||||
}
|
||||
|
||||
impl<G> Clone for GenesisSource<G> {
|
||||
@@ -43,14 +64,17 @@ impl<G> Clone for GenesisSource<G> {
|
||||
match *self {
|
||||
Self::File(ref path) => Self::File(path.clone()),
|
||||
Self::Binary(ref d) => Self::Binary(d.clone()),
|
||||
Self::Factory(ref f) => Self::Factory(f.clone()),
|
||||
Self::Factory(ref f, ref c) => Self::Factory(f.clone(), c.clone()),
|
||||
Self::Storage(ref s) => Self::Storage(s.clone()),
|
||||
Self::GenesisBuilderApi(ref s, ref c) => Self::GenesisBuilderApi(s.clone(), c.clone()),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl<G: RuntimeGenesis> GenesisSource<G> {
|
||||
fn resolve(&self) -> Result<Genesis<G>, String> {
|
||||
/// helper container for deserializing genesis from the JSON file (ChainSpec JSON file is
|
||||
/// also supported here)
|
||||
#[derive(Serialize, Deserialize)]
|
||||
struct GenesisContainer<G> {
|
||||
genesis: Genesis<G>,
|
||||
@@ -79,31 +103,21 @@ impl<G: RuntimeGenesis> GenesisSource<G> {
|
||||
.map_err(|e| format!("Error parsing embedded file: {}", e))?;
|
||||
Ok(genesis.genesis)
|
||||
},
|
||||
Self::Factory(f) => Ok(Genesis::Runtime(f())),
|
||||
Self::Storage(storage) => {
|
||||
let top = storage
|
||||
.top
|
||||
.iter()
|
||||
.map(|(k, v)| (StorageKey(k.clone()), StorageData(v.clone())))
|
||||
.collect();
|
||||
|
||||
let children_default = storage
|
||||
.children_default
|
||||
.iter()
|
||||
.map(|(k, child)| {
|
||||
(
|
||||
StorageKey(k.clone()),
|
||||
child
|
||||
.data
|
||||
.iter()
|
||||
.map(|(k, v)| (StorageKey(k.clone()), StorageData(v.clone())))
|
||||
.collect(),
|
||||
)
|
||||
})
|
||||
.collect();
|
||||
|
||||
Ok(Genesis::Raw(RawGenesis { top, children_default }))
|
||||
},
|
||||
Self::Factory(f, code) => Ok(Genesis::RuntimeAndCode(RuntimeInnerWrapper {
|
||||
runtime: f(),
|
||||
code: code.clone(),
|
||||
})),
|
||||
Self::Storage(storage) => Ok(Genesis::Raw(RawGenesis::from(storage.clone()))),
|
||||
Self::GenesisBuilderApi(GenesisBuildAction::Full(config), code) =>
|
||||
Ok(Genesis::RuntimeGenesis(RuntimeGenesisInner {
|
||||
json_blob: RuntimeGenesisConfigJson::Config(config.clone()),
|
||||
code: code.clone(),
|
||||
})),
|
||||
Self::GenesisBuilderApi(GenesisBuildAction::Patch(patch), code) =>
|
||||
Ok(Genesis::RuntimeGenesis(RuntimeGenesisInner {
|
||||
json_blob: RuntimeGenesisConfigJson::Patch(patch.clone()),
|
||||
code: code.clone(),
|
||||
})),
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -111,7 +125,18 @@ impl<G: RuntimeGenesis> GenesisSource<G> {
|
||||
impl<G: RuntimeGenesis, E> BuildStorage for ChainSpec<G, E> {
|
||||
fn assimilate_storage(&self, storage: &mut Storage) -> Result<(), String> {
|
||||
match self.genesis.resolve()? {
|
||||
Genesis::Runtime(gc) => gc.assimilate_storage(storage),
|
||||
#[allow(deprecated)]
|
||||
Genesis::Runtime(runtime_genesis_config) => {
|
||||
runtime_genesis_config.assimilate_storage(storage)?;
|
||||
},
|
||||
#[allow(deprecated)]
|
||||
Genesis::RuntimeAndCode(RuntimeInnerWrapper {
|
||||
runtime: runtime_genesis_config,
|
||||
code,
|
||||
}) => {
|
||||
runtime_genesis_config.assimilate_storage(storage)?;
|
||||
storage.top.insert(sp_core::storage::well_known_keys::CODE.to_vec(), code);
|
||||
},
|
||||
Genesis::Raw(RawGenesis { top: map, children_default: children_map }) => {
|
||||
storage.top.extend(map.into_iter().map(|(k, v)| (k.0, v.0)));
|
||||
children_map.into_iter().for_each(|(k, v)| {
|
||||
@@ -123,13 +148,37 @@ impl<G: RuntimeGenesis, E> BuildStorage for ChainSpec<G, E> {
|
||||
.data
|
||||
.extend(v.into_iter().map(|(k, v)| (k.0, v.0)));
|
||||
});
|
||||
Ok(())
|
||||
},
|
||||
// The `StateRootHash` variant exists as a way to keep note that other clients support
|
||||
// it, but Substrate itself isn't capable of loading chain specs with just a hash at the
|
||||
// moment.
|
||||
Genesis::StateRootHash(_) => Err("Genesis storage in hash format not supported".into()),
|
||||
}
|
||||
Genesis::StateRootHash(_) =>
|
||||
return Err("Genesis storage in hash format not supported".into()),
|
||||
Genesis::RuntimeGenesis(RuntimeGenesisInner {
|
||||
json_blob: RuntimeGenesisConfigJson::Config(config),
|
||||
code,
|
||||
}) => {
|
||||
RuntimeCaller::new(&code[..])
|
||||
.get_storage_for_config(config)?
|
||||
.assimilate_storage(storage)?;
|
||||
storage
|
||||
.top
|
||||
.insert(sp_core::storage::well_known_keys::CODE.to_vec(), code.clone());
|
||||
},
|
||||
Genesis::RuntimeGenesis(RuntimeGenesisInner {
|
||||
json_blob: RuntimeGenesisConfigJson::Patch(patch),
|
||||
code,
|
||||
}) => {
|
||||
RuntimeCaller::new(&code[..])
|
||||
.get_storage_for_patch(patch)?
|
||||
.assimilate_storage(storage)?;
|
||||
storage
|
||||
.top
|
||||
.insert(sp_core::storage::well_known_keys::CODE.to_vec(), code.clone());
|
||||
},
|
||||
};
|
||||
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
|
||||
@@ -144,20 +193,98 @@ pub struct RawGenesis {
|
||||
pub children_default: BTreeMap<StorageKey, GenesisStorage>,
|
||||
}
|
||||
|
||||
impl From<sp_core::storage::Storage> for RawGenesis {
|
||||
fn from(value: sp_core::storage::Storage) -> Self {
|
||||
Self {
|
||||
top: value.top.into_iter().map(|(k, v)| (StorageKey(k), StorageData(v))).collect(),
|
||||
children_default: value
|
||||
.children_default
|
||||
.into_iter()
|
||||
.map(|(sk, child)| {
|
||||
(
|
||||
StorageKey(sk),
|
||||
child
|
||||
.data
|
||||
.into_iter()
|
||||
.map(|(k, v)| (StorageKey(k), StorageData(v)))
|
||||
.collect(),
|
||||
)
|
||||
})
|
||||
.collect(),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Inner representation of [`Genesis<G>::RuntimeGenesis`] format
|
||||
#[derive(Serialize, Deserialize, Debug)]
|
||||
struct RuntimeGenesisInner {
|
||||
/// Runtime wasm code, expected to be hex-encoded in JSON.
|
||||
/// The code shall be capable of parsing `json_blob`.
|
||||
#[serde(default, with = "sp_core::bytes")]
|
||||
code: Vec<u8>,
|
||||
/// The patch or full representation of runtime's `RuntimeGenesisConfig` struct.
|
||||
#[serde(flatten)]
|
||||
json_blob: RuntimeGenesisConfigJson,
|
||||
}
|
||||
|
||||
/// Represents two possible variants of the contained JSON blob for the
|
||||
/// [`Genesis<G>::RuntimeGenesis`] format.
|
||||
#[derive(Serialize, Deserialize, Debug)]
|
||||
#[serde(rename_all = "camelCase")]
|
||||
enum RuntimeGenesisConfigJson {
|
||||
/// Represents the explicit and comprehensive runtime genesis config in JSON format.
|
||||
/// The contained object is a JSON blob that can be parsed by a compatible runtime.
|
||||
///
|
||||
/// Using a full config is useful for when someone wants to ensure that a change in the runtime
|
||||
/// makes the deserialization fail and not silently add some default values.
|
||||
Config(json::Value),
|
||||
/// Represents a patch for the default runtime genesis config in JSON format which is
|
||||
/// essentially a list of keys that are to be customized in runtime genesis config.
|
||||
/// The contained value is a JSON blob that can be parsed by a compatible runtime.
|
||||
Patch(json::Value),
|
||||
}
|
||||
|
||||
/// Inner variant wrapper for deprecated runtime.
|
||||
#[derive(Serialize, Deserialize, Debug)]
|
||||
struct RuntimeInnerWrapper<G> {
|
||||
/// The native `RuntimeGenesisConfig` struct.
|
||||
runtime: G,
|
||||
/// Runtime code.
|
||||
#[serde(with = "sp_core::bytes")]
|
||||
code: Vec<u8>,
|
||||
}
|
||||
|
||||
/// Represents the different formats of the genesis state within chain spec JSON blob.
|
||||
#[derive(Serialize, Deserialize)]
|
||||
#[serde(rename_all = "camelCase")]
|
||||
#[serde(deny_unknown_fields)]
|
||||
enum Genesis<G> {
|
||||
/// (Deprecated) Contains the JSON representation of G (the native type representing the
|
||||
/// runtime's `RuntimeGenesisConfig` struct) (will be removed with `ChainSpec::from_genesis`)
|
||||
/// without the runtime code. It is required to deserialize the legacy chainspecs genereted
|
||||
/// with `ChainsSpec::from_genesis` method.
|
||||
Runtime(G),
|
||||
/// (Deprecated) Contains the JSON representation of G (the native type representing the
|
||||
/// runtime's `RuntimeGenesisConfig` struct) (will be removed with `ChainSpec::from_genesis`)
|
||||
/// and the runtime code. It is required to create and deserialize JSON chainspecs created with
|
||||
/// deprecated `ChainSpec::from_genesis` method.
|
||||
RuntimeAndCode(RuntimeInnerWrapper<G>),
|
||||
/// The genesis storage as raw data. Typically raw key-value entries in state.
|
||||
Raw(RawGenesis),
|
||||
/// State root hash of the genesis storage.
|
||||
StateRootHash(StorageData),
|
||||
/// Represents the runtime genesis config in JSON format toghether with runtime code.
|
||||
RuntimeGenesis(RuntimeGenesisInner),
|
||||
}
|
||||
|
||||
/// A configuration of a client. Does not include runtime storage initialization.
|
||||
/// Note: `genesis` field is ignored due to way how the chain specification is serialized into
|
||||
/// JSON file. Refer to [`ChainSpecJsonContainer`], which flattens [`ClientSpec`] and denies uknown
|
||||
/// fields.
|
||||
#[derive(Serialize, Deserialize, Clone, Debug)]
|
||||
#[serde(rename_all = "camelCase")]
|
||||
#[serde(deny_unknown_fields)]
|
||||
// we cannot #[serde(deny_unknown_fields)]. Otherwise chain-spec-builder will fail on any
|
||||
// non-standard spec
|
||||
struct ClientSpec<E> {
|
||||
name: String,
|
||||
id: String,
|
||||
@@ -194,6 +321,137 @@ struct ClientSpec<E> {
|
||||
/// We use `Option` here since `()` is not flattenable by serde.
|
||||
pub type NoExtension = Option<()>;
|
||||
|
||||
/// Builder for creating [`ChainSpec`] instances.
|
||||
pub struct ChainSpecBuilder<G, E = NoExtension> {
|
||||
code: Vec<u8>,
|
||||
extensions: E,
|
||||
name: String,
|
||||
id: String,
|
||||
chain_type: ChainType,
|
||||
genesis_build_action: GenesisBuildAction,
|
||||
boot_nodes: Option<Vec<MultiaddrWithPeerId>>,
|
||||
telemetry_endpoints: Option<TelemetryEndpoints>,
|
||||
protocol_id: Option<String>,
|
||||
fork_id: Option<String>,
|
||||
properties: Option<Properties>,
|
||||
_genesis: PhantomData<G>,
|
||||
}
|
||||
|
||||
impl<G, E> ChainSpecBuilder<G, E> {
|
||||
/// Creates a new builder instance with no defaults.
|
||||
pub fn new(code: &[u8], extensions: E) -> Self {
|
||||
Self {
|
||||
code: code.into(),
|
||||
extensions,
|
||||
name: "Development".to_string(),
|
||||
id: "dev".to_string(),
|
||||
chain_type: ChainType::Local,
|
||||
genesis_build_action: GenesisBuildAction::Patch(Default::default()),
|
||||
boot_nodes: None,
|
||||
telemetry_endpoints: None,
|
||||
protocol_id: None,
|
||||
fork_id: None,
|
||||
properties: None,
|
||||
_genesis: Default::default(),
|
||||
}
|
||||
}
|
||||
|
||||
/// Sets the spec name.
|
||||
pub fn with_name(mut self, name: &str) -> Self {
|
||||
self.name = name.into();
|
||||
self
|
||||
}
|
||||
|
||||
/// Sets the spec ID.
|
||||
pub fn with_id(mut self, id: &str) -> Self {
|
||||
self.id = id.into();
|
||||
self
|
||||
}
|
||||
|
||||
/// Sets the type of the chain.
|
||||
pub fn with_chain_type(mut self, chain_type: ChainType) -> Self {
|
||||
self.chain_type = chain_type;
|
||||
self
|
||||
}
|
||||
|
||||
/// Sets a list of bootnode addresses.
|
||||
pub fn with_boot_nodes(mut self, boot_nodes: Vec<MultiaddrWithPeerId>) -> Self {
|
||||
self.boot_nodes = Some(boot_nodes);
|
||||
self
|
||||
}
|
||||
|
||||
/// Sets telemetry endpoints.
|
||||
pub fn with_telemetry_endpoints(mut self, telemetry_endpoints: TelemetryEndpoints) -> Self {
|
||||
self.telemetry_endpoints = Some(telemetry_endpoints);
|
||||
self
|
||||
}
|
||||
|
||||
/// Sets the network protocol ID.
|
||||
pub fn with_protocol_id(mut self, protocol_id: &str) -> Self {
|
||||
self.protocol_id = Some(protocol_id.into());
|
||||
self
|
||||
}
|
||||
|
||||
/// Sets an optional network fork identifier.
|
||||
pub fn with_fork_id(mut self, fork_id: &str) -> Self {
|
||||
self.fork_id = Some(fork_id.into());
|
||||
self
|
||||
}
|
||||
|
||||
/// Sets additional loosely-typed properties of the chain.
|
||||
pub fn with_properties(mut self, properties: Properties) -> Self {
|
||||
self.properties = Some(properties);
|
||||
self
|
||||
}
|
||||
|
||||
/// Sets chain spec extensions.
|
||||
pub fn with_extensions(mut self, extensions: E) -> Self {
|
||||
self.extensions = extensions;
|
||||
self
|
||||
}
|
||||
|
||||
/// Sets the code.
|
||||
pub fn with_code(mut self, code: &[u8]) -> Self {
|
||||
self.code = code.into();
|
||||
self
|
||||
}
|
||||
|
||||
/// Sets the JSON patch for runtime's GenesisConfig.
|
||||
pub fn with_genesis_config_patch(mut self, patch: json::Value) -> Self {
|
||||
self.genesis_build_action = GenesisBuildAction::Patch(patch);
|
||||
self
|
||||
}
|
||||
|
||||
/// Sets the full runtime's GenesisConfig JSON.
|
||||
pub fn with_genesis_config(mut self, config: json::Value) -> Self {
|
||||
self.genesis_build_action = GenesisBuildAction::Full(config);
|
||||
self
|
||||
}
|
||||
|
||||
/// Builds a [`ChainSpec`] instance using the provided settings.
|
||||
pub fn build(self) -> ChainSpec<G, E> {
|
||||
let client_spec = ClientSpec {
|
||||
name: self.name,
|
||||
id: self.id,
|
||||
chain_type: self.chain_type,
|
||||
boot_nodes: self.boot_nodes.unwrap_or_default(),
|
||||
telemetry_endpoints: self.telemetry_endpoints,
|
||||
protocol_id: self.protocol_id,
|
||||
fork_id: self.fork_id,
|
||||
properties: self.properties,
|
||||
extensions: self.extensions,
|
||||
consensus_engine: (),
|
||||
genesis: Default::default(),
|
||||
code_substitutes: BTreeMap::new(),
|
||||
};
|
||||
|
||||
ChainSpec {
|
||||
client_spec,
|
||||
genesis: GenesisSource::GenesisBuilderApi(self.genesis_build_action, self.code.into()),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// A configuration of a chain. Can be used to build a genesis block.
|
||||
pub struct ChainSpec<G, E = NoExtension> {
|
||||
client_spec: ClientSpec<E>,
|
||||
@@ -260,6 +518,10 @@ impl<G, E> ChainSpec<G, E> {
|
||||
}
|
||||
|
||||
/// Create hardcoded spec.
|
||||
#[deprecated(
|
||||
note = "`from_genesis` is planned to be removed in May 2024. Use `builder()` instead."
|
||||
)]
|
||||
// deprecated note: Genesis<G>::Runtime + GenesisSource::Factory shall also be removed
|
||||
pub fn from_genesis<F: Fn() -> G + 'static + Send + Sync>(
|
||||
name: &str,
|
||||
id: &str,
|
||||
@@ -271,6 +533,7 @@ impl<G, E> ChainSpec<G, E> {
|
||||
fork_id: Option<&str>,
|
||||
properties: Option<Properties>,
|
||||
extensions: E,
|
||||
code: &[u8],
|
||||
) -> Self {
|
||||
let client_spec = ClientSpec {
|
||||
name: name.to_owned(),
|
||||
@@ -287,21 +550,30 @@ impl<G, E> ChainSpec<G, E> {
|
||||
code_substitutes: BTreeMap::new(),
|
||||
};
|
||||
|
||||
ChainSpec { client_spec, genesis: GenesisSource::Factory(Arc::new(constructor)) }
|
||||
ChainSpec {
|
||||
client_spec,
|
||||
genesis: GenesisSource::Factory(Arc::new(constructor), code.into()),
|
||||
}
|
||||
}
|
||||
|
||||
/// Type of the chain.
|
||||
fn chain_type(&self) -> ChainType {
|
||||
self.client_spec.chain_type.clone()
|
||||
}
|
||||
|
||||
/// Provides a `ChainSpec` builder.
|
||||
pub fn builder(code: &[u8], extensions: E) -> ChainSpecBuilder<G, E> {
|
||||
ChainSpecBuilder::new(code, extensions)
|
||||
}
|
||||
}
|
||||
|
||||
impl<G, E: serde::de::DeserializeOwned> ChainSpec<G, E> {
|
||||
impl<G: serde::de::DeserializeOwned, E: serde::de::DeserializeOwned> ChainSpec<G, E> {
|
||||
/// Parse json content into a `ChainSpec`
|
||||
pub fn from_json_bytes(json: impl Into<Cow<'static, [u8]>>) -> Result<Self, String> {
|
||||
let json = json.into();
|
||||
let client_spec = json::from_slice(json.as_ref())
|
||||
.map_err(|e| format!("Error parsing spec file: {}", e))?;
|
||||
|
||||
Ok(ChainSpec { client_spec, genesis: GenesisSource::Binary(json) })
|
||||
}
|
||||
|
||||
@@ -318,50 +590,74 @@ impl<G, E: serde::de::DeserializeOwned> ChainSpec<G, E> {
|
||||
memmap2::Mmap::map(&file)
|
||||
.map_err(|e| format!("Error mmaping spec file `{}`: {}", path.display(), e))?
|
||||
};
|
||||
|
||||
let client_spec =
|
||||
json::from_slice(&bytes).map_err(|e| format!("Error parsing spec file: {}", e))?;
|
||||
|
||||
Ok(ChainSpec { client_spec, genesis: GenesisSource::File(path) })
|
||||
}
|
||||
}
|
||||
|
||||
/// Helper structure for serializing (and only serializing) the ChainSpec into JSON file. It
|
||||
/// represents the layout of `ChainSpec` JSON file.
|
||||
#[derive(Serialize, Deserialize)]
|
||||
struct JsonContainer<G, E> {
|
||||
// we cannot #[serde(deny_unknown_fields)]. Otherwise chain-spec-builder will fail on any
|
||||
// non-standard spec.
|
||||
struct ChainSpecJsonContainer<G, E> {
|
||||
#[serde(flatten)]
|
||||
client_spec: ClientSpec<E>,
|
||||
genesis: Genesis<G>,
|
||||
}
|
||||
|
||||
impl<G: RuntimeGenesis, E: serde::Serialize + Clone + 'static> ChainSpec<G, E> {
|
||||
fn json_container(&self, raw: bool) -> Result<JsonContainer<G, E>, String> {
|
||||
let genesis = match (raw, self.genesis.resolve()?) {
|
||||
fn json_container(&self, raw: bool) -> Result<ChainSpecJsonContainer<G, E>, String> {
|
||||
let raw_genesis = match (raw, self.genesis.resolve()?) {
|
||||
(
|
||||
true,
|
||||
Genesis::RuntimeGenesis(RuntimeGenesisInner {
|
||||
json_blob: RuntimeGenesisConfigJson::Config(config),
|
||||
code,
|
||||
}),
|
||||
) => {
|
||||
let mut storage = RuntimeCaller::new(&code[..]).get_storage_for_config(config)?;
|
||||
storage.top.insert(sp_core::storage::well_known_keys::CODE.to_vec(), code);
|
||||
RawGenesis::from(storage)
|
||||
},
|
||||
(
|
||||
true,
|
||||
Genesis::RuntimeGenesis(RuntimeGenesisInner {
|
||||
json_blob: RuntimeGenesisConfigJson::Patch(patch),
|
||||
code,
|
||||
}),
|
||||
) => {
|
||||
let mut storage = RuntimeCaller::new(&code[..]).get_storage_for_patch(patch)?;
|
||||
storage.top.insert(sp_core::storage::well_known_keys::CODE.to_vec(), code);
|
||||
RawGenesis::from(storage)
|
||||
},
|
||||
|
||||
#[allow(deprecated)]
|
||||
(true, Genesis::RuntimeAndCode(RuntimeInnerWrapper { runtime: g, code })) => {
|
||||
let mut storage = g.build_storage()?;
|
||||
storage.top.insert(sp_core::storage::well_known_keys::CODE.to_vec(), code);
|
||||
RawGenesis::from(storage)
|
||||
},
|
||||
#[allow(deprecated)]
|
||||
(true, Genesis::Runtime(g)) => {
|
||||
let storage = g.build_storage()?;
|
||||
let top =
|
||||
storage.top.into_iter().map(|(k, v)| (StorageKey(k), StorageData(v))).collect();
|
||||
let children_default = storage
|
||||
.children_default
|
||||
.into_iter()
|
||||
.map(|(sk, child)| {
|
||||
(
|
||||
StorageKey(sk),
|
||||
child
|
||||
.data
|
||||
.into_iter()
|
||||
.map(|(k, v)| (StorageKey(k), StorageData(v)))
|
||||
.collect(),
|
||||
)
|
||||
})
|
||||
.collect();
|
||||
|
||||
Genesis::Raw(RawGenesis { top, children_default })
|
||||
RawGenesis::from(storage)
|
||||
},
|
||||
(_, genesis) => genesis,
|
||||
(true, Genesis::Raw(raw)) => raw,
|
||||
|
||||
(_, genesis) =>
|
||||
return Ok(ChainSpecJsonContainer { client_spec: self.client_spec.clone(), genesis }),
|
||||
};
|
||||
Ok(JsonContainer { client_spec: self.client_spec.clone(), genesis })
|
||||
|
||||
Ok(ChainSpecJsonContainer {
|
||||
client_spec: self.client_spec.clone(),
|
||||
genesis: Genesis::Raw(raw_genesis),
|
||||
})
|
||||
}
|
||||
|
||||
/// Dump to json string.
|
||||
/// Dump the chain specification to JSON string.
|
||||
pub fn as_json(&self, raw: bool) -> Result<String, String> {
|
||||
let container = self.json_container(raw)?;
|
||||
json::to_string_pretty(&container).map_err(|e| format!("Error generating spec json: {}", e))
|
||||
@@ -442,9 +738,87 @@ where
|
||||
}
|
||||
}
|
||||
|
||||
/// The `fun` will be called with the value at `path`.
|
||||
///
|
||||
/// If exists, the value at given `path` will be passed to the `fun` and the result of `fun`
|
||||
/// call will be returned. Otherwise false is returned.
|
||||
/// `path` will be modified.
|
||||
///
|
||||
/// # Examples
|
||||
/// ```ignore
|
||||
/// use serde_json::{from_str, json, Value};
|
||||
/// let doc = json!({"a":{"b":{"c":"5"}}});
|
||||
/// let mut path = ["a", "b", "c"].into();
|
||||
/// assert!(json_eval_value_at_key(&doc, &mut path, &|v| { assert_eq!(v,"5"); true }));
|
||||
/// ```
|
||||
fn json_eval_value_at_key(
|
||||
doc: &json::Value,
|
||||
path: &mut VecDeque<&str>,
|
||||
fun: &dyn Fn(&json::Value) -> bool,
|
||||
) -> bool {
|
||||
let Some(key) = path.pop_front() else {
|
||||
return false;
|
||||
};
|
||||
|
||||
if path.is_empty() {
|
||||
doc.as_object().map_or(false, |o| o.get(key).map_or(false, |v| fun(v)))
|
||||
} else {
|
||||
doc.as_object()
|
||||
.map_or(false, |o| o.get(key).map_or(false, |v| json_eval_value_at_key(v, path, fun)))
|
||||
}
|
||||
}
|
||||
|
||||
macro_rules! json_path {
|
||||
[ $($x:expr),+ ] => {
|
||||
VecDeque::<&str>::from([$($x),+])
|
||||
};
|
||||
}
|
||||
|
||||
fn json_contains_path(doc: &json::Value, path: &mut VecDeque<&str>) -> bool {
|
||||
json_eval_value_at_key(doc, path, &|_| true)
|
||||
}
|
||||
|
||||
/// This function updates the code in given chain spec.
|
||||
///
|
||||
/// Function support updating the runtime code in provided JSON chain spec blob. `Genesis<G>::Raw`
|
||||
/// and `Genesis<G>::RuntimeGenesis` formats are supported.
|
||||
///
|
||||
/// If update was successful `true` is returned, otherwise `false`. Chain spec JSON is modified in
|
||||
/// place.
|
||||
pub fn update_code_in_json_chain_spec(chain_spec: &mut json::Value, code: &[u8]) -> bool {
|
||||
let mut path = json_path!["genesis", "runtimeGenesis", "code"];
|
||||
let mut raw_path = json_path!["genesis", "raw", "top"];
|
||||
|
||||
if json_contains_path(&chain_spec, &mut path) {
|
||||
#[derive(Serialize)]
|
||||
struct Container<'a> {
|
||||
#[serde(with = "sp_core::bytes")]
|
||||
code: &'a [u8],
|
||||
}
|
||||
let code_patch = json::json!({"genesis":{"runtimeGenesis": Container { code }}});
|
||||
crate::json_patch::merge(chain_spec, code_patch);
|
||||
true
|
||||
} else if json_contains_path(&chain_spec, &mut raw_path) {
|
||||
#[derive(Serialize)]
|
||||
struct Container<'a> {
|
||||
#[serde(with = "sp_core::bytes", rename = "0x3a636f6465")]
|
||||
code: &'a [u8],
|
||||
}
|
||||
let code_patch = json::json!({"genesis":{"raw":{"top": Container { code }}}});
|
||||
crate::json_patch::merge(chain_spec, code_patch);
|
||||
true
|
||||
} else {
|
||||
false
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use serde_json::{from_str, json, Value};
|
||||
use sp_application_crypto::Ss58Codec;
|
||||
use sp_core::storage::well_known_keys;
|
||||
use sp_keyring::AccountKeyring;
|
||||
|
||||
#[derive(Debug, Serialize, Deserialize)]
|
||||
struct Genesis(BTreeMap<String, String>);
|
||||
@@ -536,4 +910,336 @@ mod tests {
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
// some tests for json path utils
|
||||
fn test_json_eval_value_at_key() {
|
||||
let doc = json!({"a":{"b1":"20","b":{"c":{"d":"10"}}}});
|
||||
|
||||
assert!(json_eval_value_at_key(&doc, &mut json_path!["a", "b1"], &|v| { *v == "20" }));
|
||||
assert!(json_eval_value_at_key(&doc, &mut json_path!["a", "b", "c", "d"], &|v| {
|
||||
*v == "10"
|
||||
}));
|
||||
assert!(!json_eval_value_at_key(&doc, &mut json_path!["a", "c", "d"], &|_| { true }));
|
||||
assert!(!json_eval_value_at_key(&doc, &mut json_path!["d"], &|_| { true }));
|
||||
|
||||
assert!(json_contains_path(&doc, &mut json_path!["a", "b1"]));
|
||||
assert!(json_contains_path(&doc, &mut json_path!["a", "b"]));
|
||||
assert!(json_contains_path(&doc, &mut json_path!["a", "b", "c"]));
|
||||
assert!(json_contains_path(&doc, &mut json_path!["a", "b", "c", "d"]));
|
||||
assert!(!json_contains_path(&doc, &mut json_path!["a", "b", "c", "d", "e"]));
|
||||
assert!(!json_contains_path(&doc, &mut json_path!["a", "b", "b1"]));
|
||||
assert!(!json_contains_path(&doc, &mut json_path!["d"]));
|
||||
}
|
||||
|
||||
fn zeroize_code_key_in_json(encoded: bool, json: &str) -> Value {
|
||||
let mut json = from_str::<Value>(json).unwrap();
|
||||
let (zeroing_patch, mut path) = if encoded {
|
||||
(
|
||||
json!({"genesis":{"raw":{"top":{"0x3a636f6465":"0x0"}}}}),
|
||||
json_path!["genesis", "raw", "top", "0x3a636f6465"],
|
||||
)
|
||||
} else {
|
||||
(
|
||||
json!({"genesis":{"runtimeGenesis":{"code":"0x0"}}}),
|
||||
json_path!["genesis", "runtimeGenesis", "code"],
|
||||
)
|
||||
};
|
||||
assert!(json_contains_path(&json, &mut path));
|
||||
crate::json_patch::merge(&mut json, zeroing_patch);
|
||||
json
|
||||
}
|
||||
|
||||
#[docify::export]
|
||||
#[test]
|
||||
fn build_chain_spec_with_patch_works() {
|
||||
let output: ChainSpec<()> = ChainSpec::builder(
|
||||
substrate_test_runtime::wasm_binary_unwrap().into(),
|
||||
Default::default(),
|
||||
)
|
||||
.with_name("TestName")
|
||||
.with_id("test_id")
|
||||
.with_chain_type(ChainType::Local)
|
||||
.with_genesis_config_patch(json!({
|
||||
"babe": {
|
||||
"epochConfig": {
|
||||
"c": [
|
||||
7,
|
||||
10
|
||||
],
|
||||
"allowed_slots": "PrimaryAndSecondaryPlainSlots"
|
||||
}
|
||||
},
|
||||
"substrateTest": {
|
||||
"authorities": [
|
||||
AccountKeyring::Ferdie.public().to_ss58check(),
|
||||
AccountKeyring::Alice.public().to_ss58check()
|
||||
],
|
||||
}
|
||||
}))
|
||||
.build();
|
||||
|
||||
let raw_chain_spec = output.as_json(true);
|
||||
assert!(raw_chain_spec.is_ok());
|
||||
}
|
||||
|
||||
#[docify::export]
|
||||
#[test]
|
||||
fn generate_chain_spec_with_patch_works() {
|
||||
let output: ChainSpec<()> = ChainSpec::builder(
|
||||
substrate_test_runtime::wasm_binary_unwrap().into(),
|
||||
Default::default(),
|
||||
)
|
||||
.with_name("TestName")
|
||||
.with_id("test_id")
|
||||
.with_chain_type(ChainType::Local)
|
||||
.with_genesis_config_patch(json!({
|
||||
"babe": {
|
||||
"epochConfig": {
|
||||
"c": [
|
||||
7,
|
||||
10
|
||||
],
|
||||
"allowed_slots": "PrimaryAndSecondaryPlainSlots"
|
||||
}
|
||||
},
|
||||
"substrateTest": {
|
||||
"authorities": [
|
||||
AccountKeyring::Ferdie.public().to_ss58check(),
|
||||
AccountKeyring::Alice.public().to_ss58check()
|
||||
],
|
||||
}
|
||||
}))
|
||||
.build();
|
||||
|
||||
let actual = output.as_json(false).unwrap();
|
||||
let actual_raw = output.as_json(true).unwrap();
|
||||
|
||||
let expected =
|
||||
from_str::<Value>(include_str!("../res/substrate_test_runtime_from_patch.json"))
|
||||
.unwrap();
|
||||
let expected_raw =
|
||||
from_str::<Value>(include_str!("../res/substrate_test_runtime_from_patch_raw.json"))
|
||||
.unwrap();
|
||||
|
||||
//wasm blob may change overtime so let's zero it. Also ensure it is there:
|
||||
let actual = zeroize_code_key_in_json(false, actual.as_str());
|
||||
let actual_raw = zeroize_code_key_in_json(true, actual_raw.as_str());
|
||||
|
||||
assert_eq!(actual, expected);
|
||||
assert_eq!(actual_raw, expected_raw);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn generate_chain_spec_with_full_config_works() {
|
||||
let j = include_str!("../../../test-utils/runtime/res/default_genesis_config.json");
|
||||
let output: ChainSpec<()> = ChainSpec::builder(
|
||||
substrate_test_runtime::wasm_binary_unwrap().into(),
|
||||
Default::default(),
|
||||
)
|
||||
.with_name("TestName")
|
||||
.with_id("test_id")
|
||||
.with_chain_type(ChainType::Local)
|
||||
.with_genesis_config(from_str(j).unwrap())
|
||||
.build();
|
||||
|
||||
let actual = output.as_json(false).unwrap();
|
||||
let actual_raw = output.as_json(true).unwrap();
|
||||
|
||||
let expected =
|
||||
from_str::<Value>(include_str!("../res/substrate_test_runtime_from_config.json"))
|
||||
.unwrap();
|
||||
let expected_raw =
|
||||
from_str::<Value>(include_str!("../res/substrate_test_runtime_from_config_raw.json"))
|
||||
.unwrap();
|
||||
|
||||
//wasm blob may change overtime so let's zero it. Also ensure it is there:
|
||||
let actual = zeroize_code_key_in_json(false, actual.as_str());
|
||||
let actual_raw = zeroize_code_key_in_json(true, actual_raw.as_str());
|
||||
|
||||
assert_eq!(actual, expected);
|
||||
assert_eq!(actual_raw, expected_raw);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn chain_spec_as_json_fails_with_invalid_config() {
|
||||
let j =
|
||||
include_str!("../../../test-utils/runtime/res/default_genesis_config_invalid_2.json");
|
||||
let output: ChainSpec<()> = ChainSpec::builder(
|
||||
substrate_test_runtime::wasm_binary_unwrap().into(),
|
||||
Default::default(),
|
||||
)
|
||||
.with_name("TestName")
|
||||
.with_id("test_id")
|
||||
.with_chain_type(ChainType::Local)
|
||||
.with_genesis_config(from_str(j).unwrap())
|
||||
.build();
|
||||
|
||||
assert_eq!(
|
||||
output.as_json(true),
|
||||
Err("Invalid JSON blob: unknown field `babex`, expected one of `system`, `babe`, `substrateTest`, `balances` at line 1 column 8".to_string())
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn chain_spec_as_json_fails_with_invalid_patch() {
|
||||
let output: ChainSpec<()> = ChainSpec::builder(
|
||||
substrate_test_runtime::wasm_binary_unwrap().into(),
|
||||
Default::default(),
|
||||
)
|
||||
.with_name("TestName")
|
||||
.with_id("test_id")
|
||||
.with_chain_type(ChainType::Local)
|
||||
.with_genesis_config_patch(json!({
|
||||
"invalid_pallet": {},
|
||||
"substrateTest": {
|
||||
"authorities": [
|
||||
AccountKeyring::Ferdie.public().to_ss58check(),
|
||||
AccountKeyring::Alice.public().to_ss58check()
|
||||
],
|
||||
}
|
||||
}))
|
||||
.build();
|
||||
|
||||
assert!(output.as_json(true).unwrap_err().contains("Invalid JSON blob: unknown field `invalid_pallet`, expected one of `system`, `babe`, `substrateTest`, `balances`"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn check_if_code_is_valid_for_raw_without_code() {
|
||||
let spec = ChainSpec::<()>::from_json_bytes(Cow::Owned(
|
||||
include_bytes!("../res/raw_no_code.json").to_vec(),
|
||||
))
|
||||
.unwrap();
|
||||
|
||||
let j = from_str::<Value>(&spec.as_json(true).unwrap()).unwrap();
|
||||
|
||||
assert!(json_eval_value_at_key(
|
||||
&j,
|
||||
&mut json_path!["genesis", "raw", "top", "0x3a636f6465"],
|
||||
&|v| { *v == "0x010101" }
|
||||
));
|
||||
assert!(!json_contains_path(&j, &mut json_path!["code"]));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn check_code_in_assimilated_storage_for_raw_without_code() {
|
||||
let spec = ChainSpec::<()>::from_json_bytes(Cow::Owned(
|
||||
include_bytes!("../res/raw_no_code.json").to_vec(),
|
||||
))
|
||||
.unwrap();
|
||||
|
||||
let storage = spec.build_storage().unwrap();
|
||||
assert!(storage
|
||||
.top
|
||||
.get(&well_known_keys::CODE.to_vec())
|
||||
.map(|v| *v == vec![1, 1, 1])
|
||||
.unwrap())
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn update_code_works_with_runtime_genesis_config() {
|
||||
let j = include_str!("../../../test-utils/runtime/res/default_genesis_config.json");
|
||||
let chain_spec: ChainSpec<()> = ChainSpec::builder(
|
||||
substrate_test_runtime::wasm_binary_unwrap().into(),
|
||||
Default::default(),
|
||||
)
|
||||
.with_name("TestName")
|
||||
.with_id("test_id")
|
||||
.with_chain_type(ChainType::Local)
|
||||
.with_genesis_config(from_str(j).unwrap())
|
||||
.build();
|
||||
|
||||
let mut chain_spec_json = from_str::<Value>(&chain_spec.as_json(false).unwrap()).unwrap();
|
||||
assert!(update_code_in_json_chain_spec(&mut chain_spec_json, &[0, 1, 2, 4, 5, 6]));
|
||||
|
||||
assert!(json_eval_value_at_key(
|
||||
&chain_spec_json,
|
||||
&mut json_path!["genesis", "runtimeGenesis", "code"],
|
||||
&|v| { *v == "0x000102040506" }
|
||||
));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn update_code_works_for_raw() {
|
||||
let j = include_str!("../../../test-utils/runtime/res/default_genesis_config.json");
|
||||
let chain_spec: ChainSpec<()> = ChainSpec::builder(
|
||||
substrate_test_runtime::wasm_binary_unwrap().into(),
|
||||
Default::default(),
|
||||
)
|
||||
.with_name("TestName")
|
||||
.with_id("test_id")
|
||||
.with_chain_type(ChainType::Local)
|
||||
.with_genesis_config(from_str(j).unwrap())
|
||||
.build();
|
||||
|
||||
let mut chain_spec_json = from_str::<Value>(&chain_spec.as_json(true).unwrap()).unwrap();
|
||||
assert!(update_code_in_json_chain_spec(&mut chain_spec_json, &[0, 1, 2, 4, 5, 6]));
|
||||
|
||||
assert!(json_eval_value_at_key(
|
||||
&chain_spec_json,
|
||||
&mut json_path!["genesis", "raw", "top", "0x3a636f6465"],
|
||||
&|v| { *v == "0x000102040506" }
|
||||
));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn update_code_works_with_runtime_genesis_patch() {
|
||||
let chain_spec: ChainSpec<()> = ChainSpec::builder(
|
||||
substrate_test_runtime::wasm_binary_unwrap().into(),
|
||||
Default::default(),
|
||||
)
|
||||
.with_name("TestName")
|
||||
.with_id("test_id")
|
||||
.with_chain_type(ChainType::Local)
|
||||
.with_genesis_config_patch(json!({}))
|
||||
.build();
|
||||
|
||||
let mut chain_spec_json = from_str::<Value>(&chain_spec.as_json(false).unwrap()).unwrap();
|
||||
assert!(update_code_in_json_chain_spec(&mut chain_spec_json, &[0, 1, 2, 4, 5, 6]));
|
||||
|
||||
assert!(json_eval_value_at_key(
|
||||
&chain_spec_json,
|
||||
&mut json_path!["genesis", "runtimeGenesis", "code"],
|
||||
&|v| { *v == "0x000102040506" }
|
||||
));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn generate_from_genesis_is_still_supported() {
|
||||
#[allow(deprecated)]
|
||||
let chain_spec: ChainSpec<substrate_test_runtime::RuntimeGenesisConfig> = ChainSpec::from_genesis(
|
||||
"TestName",
|
||||
"test",
|
||||
ChainType::Local,
|
||||
move || substrate_test_runtime::RuntimeGenesisConfig {
|
||||
babe: substrate_test_runtime::BabeConfig {
|
||||
epoch_config: Some(
|
||||
substrate_test_runtime::TEST_RUNTIME_BABE_EPOCH_CONFIGURATION,
|
||||
),
|
||||
..Default::default()
|
||||
},
|
||||
..Default::default()
|
||||
},
|
||||
Vec::new(),
|
||||
None,
|
||||
None,
|
||||
None,
|
||||
None,
|
||||
Default::default(),
|
||||
&vec![0, 1, 2, 4, 5, 6],
|
||||
);
|
||||
|
||||
let chain_spec_json = from_str::<Value>(&chain_spec.as_json(false).unwrap()).unwrap();
|
||||
assert!(json_eval_value_at_key(
|
||||
&chain_spec_json,
|
||||
&mut json_path!["genesis", "runtimeAndCode", "code"],
|
||||
&|v| { *v == "0x000102040506" }
|
||||
));
|
||||
let chain_spec_json = from_str::<Value>(&chain_spec.as_json(true).unwrap()).unwrap();
|
||||
assert!(json_eval_value_at_key(
|
||||
&chain_spec_json,
|
||||
&mut json_path!["genesis", "raw", "top", "0x3a636f6465"],
|
||||
&|v| { *v == "0x000102040506" }
|
||||
));
|
||||
}
|
||||
}
|
||||
|
||||
@@ -0,0 +1,183 @@
|
||||
// This file is part of Substrate.
|
||||
|
||||
// Copyright (C) Parity Technologies (UK) Ltd.
|
||||
// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
|
||||
|
||||
// This program is free software: you can redistribute it and/or modify
|
||||
// it under the terms of the GNU General Public License as published by
|
||||
// the Free Software Foundation, either version 3 of the License, or
|
||||
// (at your option) any later version.
|
||||
|
||||
// This program is distributed in the hope that it will be useful,
|
||||
// but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
// GNU General Public License for more details.
|
||||
|
||||
// You should have received a copy of the GNU General Public License
|
||||
// along with this program. If not, see <https://www.gnu.org/licenses/>.
|
||||
|
||||
//! A helper module for calling the GenesisBuilder API from arbitrary runtime wasm blobs.
|
||||
|
||||
use codec::{Decode, Encode};
|
||||
use sc_executor::{error::Result, WasmExecutor};
|
||||
use serde_json::{from_slice, Value};
|
||||
use sp_core::{
|
||||
storage::Storage,
|
||||
traits::{CallContext, CodeExecutor, Externalities, FetchRuntimeCode, RuntimeCode},
|
||||
};
|
||||
use sp_genesis_builder::Result as BuildResult;
|
||||
use sp_state_machine::BasicExternalities;
|
||||
use std::borrow::Cow;
|
||||
|
||||
/// A utility that facilitates calling the GenesisBuilder API from the runtime wasm code blob.
|
||||
pub struct GenesisConfigBuilderRuntimeCaller<'a> {
|
||||
code: Cow<'a, [u8]>,
|
||||
code_hash: Vec<u8>,
|
||||
executor: WasmExecutor<sp_io::SubstrateHostFunctions>,
|
||||
}
|
||||
|
||||
impl<'a> FetchRuntimeCode for GenesisConfigBuilderRuntimeCaller<'a> {
|
||||
fn fetch_runtime_code(&self) -> Option<Cow<[u8]>> {
|
||||
Some(self.code.as_ref().into())
|
||||
}
|
||||
}
|
||||
|
||||
impl<'a> GenesisConfigBuilderRuntimeCaller<'a> {
|
||||
/// Creates new instance using the provided code blob.
|
||||
///
|
||||
/// This code is later referred to as `runtime`.
|
||||
pub fn new(code: &'a [u8]) -> Self {
|
||||
GenesisConfigBuilderRuntimeCaller {
|
||||
code: code.into(),
|
||||
code_hash: sp_core::blake2_256(code).to_vec(),
|
||||
executor: WasmExecutor::<sp_io::SubstrateHostFunctions>::builder()
|
||||
.with_allow_missing_host_functions(true)
|
||||
.build(),
|
||||
}
|
||||
}
|
||||
|
||||
fn call(&self, ext: &mut dyn Externalities, method: &str, data: &[u8]) -> Result<Vec<u8>> {
|
||||
self.executor
|
||||
.call(
|
||||
ext,
|
||||
&RuntimeCode { heap_pages: None, code_fetcher: self, hash: self.code_hash.clone() },
|
||||
method,
|
||||
data,
|
||||
false,
|
||||
CallContext::Offchain,
|
||||
)
|
||||
.0
|
||||
}
|
||||
|
||||
/// Returns the default `GenesisConfig` provided by the `runtime`.
|
||||
///
|
||||
/// Calls [`GenesisBuilder::create_default_config`](sp_genesis_builder::GenesisBuilder::create_default_config) in the `runtime`.
|
||||
pub fn get_default_config(&self) -> core::result::Result<Value, String> {
|
||||
let mut t = BasicExternalities::new_empty();
|
||||
let call_result = self
|
||||
.call(&mut t, "GenesisBuilder_create_default_config", &[])
|
||||
.map_err(|e| format!("wasm call error {e}"))?;
|
||||
let default_config = Vec::<u8>::decode(&mut &call_result[..])
|
||||
.map_err(|e| format!("scale codec error: {e}"))?;
|
||||
Ok(from_slice(&default_config[..]).expect("returned value is json. qed."))
|
||||
}
|
||||
|
||||
/// Build the given `GenesisConfig` and returns the genesis state.
|
||||
///
|
||||
/// Calls [`GenesisBuilder::build_config`](sp_genesis_builder::GenesisBuilder::build_config)
|
||||
/// provided by the `runtime`.
|
||||
pub fn get_storage_for_config(&self, config: Value) -> core::result::Result<Storage, String> {
|
||||
let mut ext = BasicExternalities::new_empty();
|
||||
|
||||
let call_result = self
|
||||
.call(&mut ext, "GenesisBuilder_build_config", &config.to_string().encode())
|
||||
.map_err(|e| format!("wasm call error {e}"))?;
|
||||
|
||||
BuildResult::decode(&mut &call_result[..])
|
||||
.map_err(|e| format!("scale codec error: {e}"))??;
|
||||
|
||||
Ok(ext.into_storages())
|
||||
}
|
||||
|
||||
/// Creates the genesis state by patching the default `GenesisConfig` and applying it.
|
||||
///
|
||||
/// 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.
|
||||
///
|
||||
/// 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`.
|
||||
pub fn get_storage_for_patch(&self, patch: Value) -> core::result::Result<Storage, String> {
|
||||
let mut config = self.get_default_config()?;
|
||||
crate::json_patch::merge(&mut config, patch);
|
||||
self.get_storage_for_config(config)
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use serde_json::{from_str, json};
|
||||
pub use sp_consensus_babe::{AllowedSlots, BabeEpochConfiguration, Slot};
|
||||
|
||||
#[test]
|
||||
fn get_default_config_works() {
|
||||
let config =
|
||||
GenesisConfigBuilderRuntimeCaller::new(substrate_test_runtime::wasm_binary_unwrap())
|
||||
.get_default_config()
|
||||
.unwrap();
|
||||
let expected = r#"{"system":{},"babe":{"authorities":[],"epochConfig":null},"substrateTest":{"authorities":[]},"balances":{"balances":[]}}"#;
|
||||
assert_eq!(from_str::<Value>(expected).unwrap(), config);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn get_storage_for_patch_works() {
|
||||
let patch = json!({
|
||||
"babe": {
|
||||
"epochConfig": {
|
||||
"c": [
|
||||
69,
|
||||
696
|
||||
],
|
||||
"allowed_slots": "PrimaryAndSecondaryPlainSlots"
|
||||
}
|
||||
},
|
||||
});
|
||||
|
||||
let storage =
|
||||
GenesisConfigBuilderRuntimeCaller::new(substrate_test_runtime::wasm_binary_unwrap())
|
||||
.get_storage_for_patch(patch)
|
||||
.unwrap();
|
||||
|
||||
//Babe|Authorities
|
||||
let value: Vec<u8> = storage
|
||||
.top
|
||||
.get(
|
||||
&array_bytes::hex2bytes(
|
||||
"1cb6f36e027abb2091cfb5110ab5087fdc6b171b77304263c292cc3ea5ed31ef",
|
||||
)
|
||||
.unwrap(),
|
||||
)
|
||||
.unwrap()
|
||||
.clone();
|
||||
|
||||
assert_eq!(
|
||||
BabeEpochConfiguration::decode(&mut &value[..]).unwrap(),
|
||||
BabeEpochConfiguration {
|
||||
c: (69, 696),
|
||||
allowed_slots: AllowedSlots::PrimaryAndSecondaryPlainSlots
|
||||
}
|
||||
);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,191 @@
|
||||
// This file is part of Substrate.
|
||||
|
||||
// Copyright (C) Parity Technologies (UK) Ltd.
|
||||
// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
|
||||
|
||||
// This program is free software: you can redistribute it and/or modify
|
||||
// it under the terms of the GNU General Public License as published by
|
||||
// the Free Software Foundation, either version 3 of the License, or
|
||||
// (at your option) any later version.
|
||||
|
||||
// This program is distributed in the hope that it will be useful,
|
||||
// but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
// GNU General Public License for more details.
|
||||
|
||||
// You should have received a copy of the GNU General Public License
|
||||
// along with this program. If not, see <https://www.gnu.org/licenses/>.
|
||||
|
||||
//! A helper module providing json patching functions.
|
||||
|
||||
use serde_json::Value;
|
||||
|
||||
/// Recursively merges two JSON objects, `a` and `b`, into a single object.
|
||||
///
|
||||
/// If a key exists in both objects, the value from `b` will override the value from `a`.
|
||||
/// If a key exists in `b` with a `null` value, it will be removed from `a`.
|
||||
/// If a key exists only in `b` and not in `a`, it will be added to `a`.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// * `a` - A mutable reference to the target JSON object to merge into.
|
||||
/// * `b` - The JSON object to merge with `a`.
|
||||
pub fn merge(a: &mut Value, b: Value) {
|
||||
match (a, b) {
|
||||
(Value::Object(a), Value::Object(b)) =>
|
||||
for (k, v) in b {
|
||||
if v.is_null() {
|
||||
a.remove(&k);
|
||||
} else {
|
||||
merge(a.entry(k).or_insert(Value::Null), v);
|
||||
}
|
||||
},
|
||||
(a, b) => *a = b,
|
||||
};
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use serde_json::json;
|
||||
|
||||
#[test]
|
||||
fn test1_simple_merge() {
|
||||
let mut j1 = json!({ "a":123 });
|
||||
merge(&mut j1, json!({ "b":256 }));
|
||||
assert_eq!(j1, json!({ "a":123, "b":256 }));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test2_patch_simple_merge_nested() {
|
||||
let mut j1 = json!({
|
||||
"a": {
|
||||
"name": "xxx",
|
||||
"value": 123
|
||||
},
|
||||
"b": { "c" : { "inner_name": "yyy" } }
|
||||
});
|
||||
|
||||
let j2 = json!({
|
||||
"a": {
|
||||
"keys": ["a", "b", "c" ]
|
||||
}
|
||||
});
|
||||
|
||||
merge(&mut j1, j2);
|
||||
assert_eq!(
|
||||
j1,
|
||||
json!({"a":{"keys":["a","b","c"],"name":"xxx","value":123}, "b": { "c" : { "inner_name": "yyy" } }})
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test3_patch_overrides_existing_keys() {
|
||||
let mut j1 = json!({
|
||||
"a": {
|
||||
"name": "xxx",
|
||||
"value": 123,
|
||||
"keys": ["d"]
|
||||
|
||||
}
|
||||
});
|
||||
|
||||
let j2 = json!({
|
||||
"a": {
|
||||
"keys": ["a", "b", "c" ]
|
||||
}
|
||||
});
|
||||
|
||||
merge(&mut j1, j2);
|
||||
assert_eq!(j1, json!({"a":{"keys":["a","b","c"],"name":"xxx","value":123}}));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test4_patch_overrides_existing_keys() {
|
||||
let mut j1 = json!({
|
||||
"a": {
|
||||
"name": "xxx",
|
||||
"value": 123,
|
||||
"b" : {
|
||||
"inner_name": "yyy"
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
let j2 = json!({
|
||||
"a": {
|
||||
"name": "new_name",
|
||||
"b" : {
|
||||
"inner_name": "inner_new_name"
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
merge(&mut j1, j2);
|
||||
assert_eq!(
|
||||
j1,
|
||||
json!({ "a": {"name":"new_name", "value":123, "b" : { "inner_name": "inner_new_name" }} })
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test5_patch_overrides_existing_nested_keys() {
|
||||
let mut j1 = json!({
|
||||
"a": {
|
||||
"name": "xxx",
|
||||
"value": 123,
|
||||
"b": {
|
||||
"c": {
|
||||
"d": {
|
||||
"name": "yyy",
|
||||
"value": 256
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
});
|
||||
|
||||
let j2 = json!({
|
||||
"a": {
|
||||
"value": 456,
|
||||
"b": {
|
||||
"c": {
|
||||
"d": {
|
||||
"name": "new_name"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
merge(&mut j1, j2);
|
||||
assert_eq!(
|
||||
j1,
|
||||
json!({ "a": {"name":"xxx", "value":456, "b": { "c": { "d": { "name": "new_name", "value": 256 }}}}})
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test6_patch_removes_keys_if_null() {
|
||||
let mut j1 = json!({
|
||||
"a": {
|
||||
"name": "xxx",
|
||||
"value": 123,
|
||||
"enum_variant_1": {
|
||||
"name": "yyy",
|
||||
}
|
||||
},
|
||||
});
|
||||
|
||||
let j2 = json!({
|
||||
"a": {
|
||||
"value": 456,
|
||||
"enum_variant_1": null,
|
||||
"enum_variant_2": 32,
|
||||
}
|
||||
});
|
||||
|
||||
merge(&mut j1, j2);
|
||||
assert_eq!(j1, json!({ "a": {"name":"xxx", "value":456, "enum_variant_2": 32 }}));
|
||||
}
|
||||
}
|
||||
@@ -16,38 +16,253 @@
|
||||
// You should have received a copy of the GNU General Public License
|
||||
// along with this program. If not, see <https://www.gnu.org/licenses/>.
|
||||
|
||||
//! Substrate chain configurations.
|
||||
//! This crate includes structs and utilities for defining configuration files (known as chain
|
||||
//! specification) for both runtime and node.
|
||||
//!
|
||||
//! This crate contains structs and utilities to declare
|
||||
//! a runtime-specific configuration file (a.k.a chain spec).
|
||||
//! # Intro: Chain Specification
|
||||
//!
|
||||
//! Basic chain spec type containing all required parameters is
|
||||
//! [`GenericChainSpec`]. It can be extended with
|
||||
//! additional options that contain configuration specific to your chain.
|
||||
//! Usually the extension is going to be an amalgamate of types exposed
|
||||
//! by Substrate core modules. To allow the core modules to retrieve
|
||||
//! their configuration from your extension you should use `ChainSpecExtension`
|
||||
//! macro exposed by this crate.
|
||||
//! The chain specification comprises parameters and settings that define the properties and an
|
||||
//! initial state of a chain. Users typically interact with the JSON representation of the chain
|
||||
//! spec. Internally, the chain spec is embodied by the [`GenericChainSpec`] struct, and specific
|
||||
//! properties can be accessed using the [`ChainSpec`] trait.
|
||||
//!
|
||||
//! In summary, although not restricted to, the primary role of the chain spec is to provide a list
|
||||
//! of well-known boot nodes for the blockchain network and the means for initializing the genesis
|
||||
//! storage. This initialization is necessary for creating a genesis block upon which subsequent
|
||||
//! blocks are built. When the node is launched for the first time, it reads the chain spec,
|
||||
//! initializes the genesis block, and establishes connections with the boot nodes.
|
||||
//!
|
||||
//! The JSON chain spec is divided into two main logical sections:
|
||||
//! - one section details general chain properties,
|
||||
//! - second explicitly or indirectly defines the genesis storage, which, in turn, determines the
|
||||
//! genesis hash of the chain,
|
||||
//!
|
||||
//! The chain specification consists of the following fields:
|
||||
//!
|
||||
//! <table>
|
||||
//! <thead>
|
||||
//! <tr>
|
||||
//! <th>Chain spec key</th>
|
||||
//! <th>Description</th>
|
||||
//! </tr>
|
||||
//! </thead>
|
||||
//! <tbody>
|
||||
//! <tr>
|
||||
//! <td>name</td>
|
||||
//! <td>The human readable name of the chain.</td>
|
||||
//! </tr>
|
||||
//! <tr>
|
||||
//! <td>id</td>
|
||||
//! <td>The id of the chain.</td>
|
||||
//! </tr>
|
||||
//! <tr>
|
||||
//! <td>chainType</td>
|
||||
//! <td>The chain type of this chain
|
||||
//! (refer to
|
||||
//! <a href="enum.ChainType.html" title="enum sc_chain_spec::ChainType">
|
||||
//! <code>ChainType</code>
|
||||
//! </a>).
|
||||
//! </td>
|
||||
//! </tr>
|
||||
//! <tr>
|
||||
//! <td>bootNodes</td>
|
||||
//! <td>A list of
|
||||
//! <a href="https://github.com/multiformats/multiaddr">multi addresses</a>
|
||||
//! that belong to boot nodes of the chain.</td>
|
||||
//! </tr>
|
||||
//! <tr>
|
||||
//! <td>telemetryEndpoints</td>
|
||||
//! <td>Optional list of <code>multi address, verbosity</code> of telemetry endpoints. The
|
||||
//! verbosity goes from 0 to 9. With 0 being the mode with the lowest verbosity.</td>
|
||||
//! </tr>
|
||||
//! <tr>
|
||||
//! <td>protocolId</td>
|
||||
//! <td>Optional networking protocol id that identifies the chain.</td>
|
||||
//! </tr>
|
||||
//! <tr>
|
||||
//! <td>forkId</td>
|
||||
//! <td>Optional fork id. Should most likely be left empty. Can be used to signal a fork on
|
||||
//! the network level when two chains have the same genesis hash.</td>
|
||||
//! </tr>
|
||||
//! <tr>
|
||||
//! <td>properties</td>
|
||||
//! <td>Custom properties. Shall be provided in the form of
|
||||
//! <code>key</code>-<code>value</code> json object.
|
||||
//! </td>
|
||||
//! </tr>
|
||||
//! <tr>
|
||||
//! <td>consensusEngine</td>
|
||||
//! <td>Deprecated field. Should be ignored.</td>
|
||||
//! </tr>
|
||||
//! <tr>
|
||||
//! <td>codeSubstitutes</td>
|
||||
//! <td>Optional map of <code>block_number</code> to <code>wasm_code</code>. More details in
|
||||
//! material to follow.</td>
|
||||
//! </tr>
|
||||
//! <tr>
|
||||
//! <td>genesis</td>
|
||||
//! <td>Defines the initial state of the runtime. More details in material to follow.</td>
|
||||
//! </tr>
|
||||
//! </tbody>
|
||||
//! </table>
|
||||
//!
|
||||
//! # `genesis`: Initial Runtime State
|
||||
//!
|
||||
//! All nodes in the network must build subsequent blocks upon exactly the same genesis block.
|
||||
//!
|
||||
//! The information configured in the `genesis` section of a chain specification is used to build
|
||||
//! the genesis storage, which is essential for creating the genesis block, since the block header
|
||||
//! includes the storage root hash.
|
||||
//!
|
||||
//! The `genesis` key of the chain specification definition describes the
|
||||
//! initial state of the runtime. For example, it may contain:
|
||||
//! - an initial list of funded accounts,
|
||||
//! - the administrative account that controls the sudo key,
|
||||
//! - an initial authorities set for consensus, etc.
|
||||
//!
|
||||
//! As the compiled WASM blob of the runtime code is stored in the chain's state, the initial
|
||||
//! runtime must also be provided within the chain specification.
|
||||
//!
|
||||
//! In essence, the most important formats of genesis initial state are:
|
||||
//!
|
||||
//! <table>
|
||||
//! <thead>
|
||||
//! <tr>
|
||||
//! <th>Format</th>
|
||||
//! <th>Description</th>
|
||||
//! </tr>
|
||||
//! </thead>
|
||||
//! <tbody>
|
||||
//! <tr>
|
||||
//! <td>
|
||||
//! <code>runtime / full config</code>
|
||||
//! </td>
|
||||
//! <td>A JSON object that provides an explicit and comprehensive representation of the
|
||||
//! <code>RuntimeGenesisConfig</code> struct, which is generated by <a
|
||||
//! href="../frame_support_procedural/macro.construct_runtime.html"
|
||||
//! ><code>frame::runtime::prelude::construct_runtime</code></a> macro (<a
|
||||
//! href="../substrate_test_runtime/struct.RuntimeGenesisConfig.html#"
|
||||
//! >example of generated struct</a>). Must contain all the keys of
|
||||
//! the genesis config, no defaults will be used.
|
||||
//!
|
||||
//! This format explicitly provides the code of the runtime.
|
||||
//! </td></tr>
|
||||
//! <tr>
|
||||
//! <td>
|
||||
//! <code>patch</code>
|
||||
//! </td>
|
||||
//! <td>A JSON object that offers a partial representation of the
|
||||
//! <code>RuntimeGenesisConfig</code> provided by the runtime. It contains a patch, which is
|
||||
//! essentially a list of key-value pairs to customize in the default runtime's
|
||||
//! <code>RuntimeGenesisConfig</code>.
|
||||
//! This format explicitly provides the code of the runtime.
|
||||
//! </td></tr>
|
||||
//! <tr>
|
||||
//! <td>
|
||||
//! <code>raw</code>
|
||||
//! </td>
|
||||
//! <td>A JSON object with two fields: <code>top</code> and <code>children_default</code>.
|
||||
//! Each field is a map of <code>key => value</code> pairs representing entries in a genesis storage
|
||||
//! trie. The runtime code is one of such entries.</td>
|
||||
//! </tr>
|
||||
//! </tbody>
|
||||
//! </table>
|
||||
//!
|
||||
//! For production or long-lasting blockchains, using the `raw` format in the chain specification is
|
||||
//! recommended. Only the `raw` format guarantees that storage root hash will remain unchanged when
|
||||
//! the `RuntimeGenesisConfig` format changes due to software upgrade.
|
||||
//!
|
||||
//! JSON examples in the [following section](#json-chain-specification-example) illustrate the `raw`
|
||||
//! `patch` and full genesis fields.
|
||||
//!
|
||||
//! # From Initial State to Raw Genesis.
|
||||
//!
|
||||
//! To generate a raw genesis storage from the JSON representation of the runtime genesis config,
|
||||
//! the node needs to interact with the runtime.
|
||||
//!
|
||||
//! This interaction involves passing the runtime genesis config JSON blob to the runtime using the
|
||||
//! [`sp_genesis_builder::GenesisBuilder::build_config`] function. During this operation, the
|
||||
//! runtime converts the JSON representation of the genesis config into [`sp_io::storage`] items. It
|
||||
//! is a crucial step for computing the storage root hash, which is a key component in determining
|
||||
//! the genesis hash.
|
||||
//!
|
||||
//! Consequently, the runtime must support the [`sp_genesis_builder::GenesisBuilder`] API to
|
||||
//! utilize either `patch` or `full` formats.
|
||||
//!
|
||||
//! This entire process is encapsulated within the implementation of the [`BuildStorage`] trait,
|
||||
//! which can be accessed through the [`ChainSpec::as_storage_builder`] method. There is an
|
||||
//! intermediate internal helper that facilitates this interaction,
|
||||
//! [`GenesisConfigBuilderRuntimeCaller`], which serves as a straightforward wrapper for
|
||||
//! [`sc_executor::WasmExecutor`].
|
||||
//!
|
||||
//! In case of `raw` genesis state the node does not interact with the runtime regarding the
|
||||
//! computation of initial state.
|
||||
//!
|
||||
//! The plain and `raw` chain specification JSON blobs can be found in
|
||||
//! [JSON examples](#json-chain-specification-example) section.
|
||||
//!
|
||||
//! # Optional Code Mapping
|
||||
//!
|
||||
//! Optional map of `block_number` to `wasm_code`.
|
||||
//!
|
||||
//! The given `wasm_code` will be used to substitute the on-chain wasm code starting with the
|
||||
//! given block number until the `spec_version` on-chain changes. The given `wasm_code` should
|
||||
//! be as close as possible to the on-chain wasm code. A substitute should be used to fix a bug
|
||||
//! that cannot be fixed with a runtime upgrade, if for example the runtime is constantly
|
||||
//! panicking. Introducing new runtime APIs isn't supported, because the node
|
||||
//! will read the runtime version from the on-chain wasm code.
|
||||
//!
|
||||
//! Use this functionality only when there is no other way around it, and only patch the problematic
|
||||
//! bug; the rest should be done with an on-chain runtime upgrade.
|
||||
//!
|
||||
//! # Building a Chain Specification
|
||||
//!
|
||||
//! The [`ChainSpecBuilder`] should be used to create an instance of a chain specification. Its API
|
||||
//! allows configuration of all fields of the chain spec. To generate a JSON representation of the
|
||||
//! specification, use [`ChainSpec::as_json`].
|
||||
//!
|
||||
//! The sample code to generate a chain spec is as follows:
|
||||
#![doc = docify::embed!("src/chain_spec.rs", build_chain_spec_with_patch_works)]
|
||||
//! # JSON chain specification example
|
||||
//!
|
||||
//! The following are the plain and `raw` versions of the chain specification JSON files, resulting
|
||||
//! from executing of the above [example](#building-a-chain-specification):
|
||||
//! ```ignore
|
||||
#![doc = include_str!("../res/substrate_test_runtime_from_patch.json")]
|
||||
//! ```
|
||||
//! ```ignore
|
||||
#![doc = include_str!("../res/substrate_test_runtime_from_patch_raw.json")]
|
||||
//! ```
|
||||
//! The following example shows the plain full config version of chain spec:
|
||||
//! ```ignore
|
||||
#![doc = include_str!("../res/substrate_test_runtime_from_config.json")]
|
||||
//! ```
|
||||
//! The [`ChainSpec`] trait represents the API to access values defined in the JSON chain specification.
|
||||
//!
|
||||
//!
|
||||
//! # Custom Chain Spec Extensions
|
||||
//!
|
||||
//! The basic chain spec type containing all required parameters is [`GenericChainSpec`]. It can be
|
||||
//! extended with additional options containing configuration specific to your chain. Usually, the
|
||||
//! extension will be a combination of types exposed by Substrate core modules.
|
||||
//!
|
||||
//! To allow the core modules to retrieve their configuration from your extension, you should use
|
||||
//! `ChainSpecExtension` macro exposed by this crate.
|
||||
//! ```rust
|
||||
//! use std::collections::HashMap;
|
||||
//! use sc_chain_spec::{GenericChainSpec, ChainSpecExtension};
|
||||
//!
|
||||
//! #[derive(Clone, Debug, serde::Serialize, serde::Deserialize, ChainSpecExtension)]
|
||||
//! pub struct MyExtension {
|
||||
//! pub known_blocks: HashMap<u64, String>,
|
||||
//! pub known_blocks: HashMap<u64, String>,
|
||||
//! }
|
||||
//!
|
||||
//! pub type MyChainSpec<G> = GenericChainSpec<G, MyExtension>;
|
||||
//! ```
|
||||
//!
|
||||
//! Some parameters may require different values depending on the
|
||||
//! current blockchain height (a.k.a. forks). You can use `ChainSpecGroup`
|
||||
//! macro and provided [`Forks`](./struct.Forks.html) structure to put
|
||||
//! such parameters to your chain spec.
|
||||
//! This will allow to override a single parameter starting at specific
|
||||
//! block number.
|
||||
//!
|
||||
//! Some parameters may require different values depending on the current blockchain height (a.k.a.
|
||||
//! forks). You can use the [`ChainSpecGroup`](macro@ChainSpecGroup) macro and the provided [`Forks`]
|
||||
//! structure to add such parameters to your chain spec. This will allow overriding a single
|
||||
//! parameter starting at a specific block number.
|
||||
//! ```rust
|
||||
//! use sc_chain_spec::{Forks, ChainSpecGroup, ChainSpecExtension, GenericChainSpec};
|
||||
//!
|
||||
@@ -76,12 +291,9 @@
|
||||
//! /// A chain spec supporting forkable `Extension`.
|
||||
//! pub type MyChainSpec2<G> = GenericChainSpec<G, Forks<BlockNumber, Extension>>;
|
||||
//! ```
|
||||
//!
|
||||
//! It's also possible to have a set of parameters that is allowed to change
|
||||
//! with block numbers (i.e. is forkable), and another set that is not subject to changes.
|
||||
//! This is also possible by declaring an extension that contains `Forks` within it.
|
||||
//!
|
||||
//!
|
||||
//! It's also possible to have a set of parameters that are allowed to change with block numbers
|
||||
//! (i.e., they are forkable), and another set that is not subject to changes. This can also be
|
||||
//! achieved by declaring an extension that contains [`Forks`] within it.
|
||||
//! ```rust
|
||||
//! use serde::{Serialize, Deserialize};
|
||||
//! use sc_chain_spec::{Forks, GenericChainSpec, ChainSpecGroup, ChainSpecExtension};
|
||||
@@ -106,98 +318,26 @@
|
||||
//!
|
||||
//! pub type MyChainSpec<G> = GenericChainSpec<G, Extension>;
|
||||
//! ```
|
||||
//!
|
||||
//! # Substrate chain specification format
|
||||
//!
|
||||
//! The Substrate chain specification is a `json` file that describes the basics of a chain. Most
|
||||
//! importantly it lays out the genesis storage which leads to the genesis hash. The default
|
||||
//! Substrate chain specification format is the following:
|
||||
//!
|
||||
//! ```json
|
||||
//! // The human readable name of the chain.
|
||||
//! "name": "Flaming Fir",
|
||||
//!
|
||||
//! // The id of the chain.
|
||||
//! "id": "flamingfir9",
|
||||
//!
|
||||
//! // The chain type of this chain.
|
||||
//! // Possible values are `Live`, `Development`, `Local`.
|
||||
//! "chainType": "Live",
|
||||
//!
|
||||
//! // A list of multi addresses that belong to boot nodes of the chain.
|
||||
//! "bootNodes": [
|
||||
//! "/dns/0.flamingfir.paritytech.net/tcp/30333/p2p/12D3KooWLK2gMLhWsYJzjW3q35zAs9FDDVqfqVfVuskiGZGRSMvR",
|
||||
//! ],
|
||||
//!
|
||||
//! // Optional list of "multi address, verbosity" of telemetry endpoints.
|
||||
//! // The verbosity goes from `0` to `9`. With `0` being the mode with the lowest verbosity.
|
||||
//! "telemetryEndpoints": [
|
||||
//! [
|
||||
//! "/dns/telemetry.polkadot.io/tcp/443/x-parity-wss/%2Fsubmit%2F",
|
||||
//! 0
|
||||
//! ]
|
||||
//! ],
|
||||
//!
|
||||
//! // Optional networking protocol id that identifies the chain.
|
||||
//! "protocolId": "fir9",
|
||||
//!
|
||||
//! // Optional fork id. Should most likely be left empty.
|
||||
//! // Can be used to signal a fork on the network level when two chains have the
|
||||
//! // same genesis hash.
|
||||
//! "forkId": "random_fork",
|
||||
//!
|
||||
//! // Custom properties.
|
||||
//! "properties": {
|
||||
//! "tokenDecimals": 15,
|
||||
//! "tokenSymbol": "FIR"
|
||||
//! },
|
||||
//!
|
||||
//! // Deprecated field. Should be ignored.
|
||||
//! "consensusEngine": null,
|
||||
//!
|
||||
//! // The genesis declaration of the chain.
|
||||
//! //
|
||||
//! // `runtime`, `raw`, `stateRootHash` denote the type of the genesis declaration.
|
||||
//! //
|
||||
//! // These declarations are in the following formats:
|
||||
//! // - `runtime` is a `json` object that can be parsed by a compatible `GenesisConfig`. This
|
||||
//! // `GenesisConfig` is declared by a runtime and opaque to the node.
|
||||
//! // - `raw` is a `json` object with two fields `top` and `children_default`. Each of these
|
||||
//! // fields is a map of `key => value`. These key/value pairs represent the genesis storage.
|
||||
//! // - `stateRootHash` is a single hex encoded hash that represents the genesis hash. The hash
|
||||
//! // type depends on the hash used by the chain.
|
||||
//! //
|
||||
//! "genesis": { "runtime": {} },
|
||||
//!
|
||||
//! /// Optional map of `block_number` to `wasm_code`.
|
||||
//! ///
|
||||
//! /// The given `wasm_code` will be used to substitute the on-chain wasm code starting with the
|
||||
//! /// given block number until the `spec_version` on-chain changes. The given `wasm_code` should
|
||||
//! /// be as close as possible to the on-chain wasm code. A substitute should be used to fix a bug
|
||||
//! /// that can not be fixed with a runtime upgrade, if for example the runtime is constantly
|
||||
//! /// panicking. Introducing new runtime apis isn't supported, because the node
|
||||
//! /// will read the runtime version from the on-chain wasm code. Use this functionality only when
|
||||
//! /// there is no other way around it and only patch the problematic bug, the rest should be done
|
||||
//! /// with a on-chain runtime upgrade.
|
||||
//! "codeSubstitutes": [],
|
||||
//! ```
|
||||
//!
|
||||
//! See [`ChainSpec`] for a trait representation of the above.
|
||||
//!
|
||||
//! The chain spec can be extended with other fields that are opaque to the default chain spec.
|
||||
//! Specific node implementations will need to be able to deserialize these extensions.
|
||||
|
||||
mod chain_spec;
|
||||
mod extension;
|
||||
mod genesis;
|
||||
mod genesis_block;
|
||||
mod genesis_config_builder;
|
||||
mod json_patch;
|
||||
|
||||
pub use self::{
|
||||
chain_spec::{ChainSpec as GenericChainSpec, NoExtension},
|
||||
chain_spec::{
|
||||
update_code_in_json_chain_spec, ChainSpec as GenericChainSpec, ChainSpecBuilder,
|
||||
NoExtension,
|
||||
},
|
||||
extension::{get_extension, get_extension_mut, Extension, Fork, Forks, GetExtension, Group},
|
||||
genesis::{
|
||||
genesis_block::{
|
||||
construct_genesis_block, resolve_state_version_from_wasm, BuildGenesisBlock,
|
||||
GenesisBlockBuilder,
|
||||
},
|
||||
genesis_config_builder::GenesisConfigBuilderRuntimeCaller,
|
||||
};
|
||||
pub use sc_chain_spec_derive::{ChainSpecExtension, ChainSpecGroup};
|
||||
|
||||
|
||||
Reference in New Issue
Block a user