sc_chain_spec/
chain_spec.rs

1// This file is part of Substrate.
2
3// Copyright (C) Parity Technologies (UK) Ltd.
4// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
5
6// This program is free software: you can redistribute it and/or modify
7// it under the terms of the GNU General Public License as published by
8// the Free Software Foundation, either version 3 of the License, or
9// (at your option) any later version.
10
11// This program is distributed in the hope that it will be useful,
12// but WITHOUT ANY WARRANTY; without even the implied warranty of
13// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14// GNU General Public License for more details.
15
16// You should have received a copy of the GNU General Public License
17// along with this program. If not, see <https://www.gnu.org/licenses/>.
18
19//! Substrate chain configurations.
20#![warn(missing_docs)]
21use crate::{
22	extension::GetExtension, genesis_config_builder::HostFunctions, ChainType,
23	GenesisConfigBuilderRuntimeCaller as RuntimeCaller, Properties,
24};
25use sc_network::config::MultiaddrWithPeerId;
26use sc_telemetry::TelemetryEndpoints;
27use serde::{Deserialize, Serialize};
28use serde_json as json;
29use sp_core::{
30	storage::{ChildInfo, Storage, StorageChild, StorageData, StorageKey},
31	Bytes,
32};
33use sp_runtime::BuildStorage;
34use std::{
35	borrow::Cow,
36	collections::{BTreeMap, VecDeque},
37	fs::File,
38	marker::PhantomData,
39	path::PathBuf,
40};
41
42#[derive(Serialize, Deserialize)]
43#[serde(rename_all = "camelCase")]
44enum GenesisBuildAction<EHF> {
45	Patch(json::Value),
46	Full(json::Value),
47	NamedPreset(String, PhantomData<EHF>),
48}
49
50impl<EHF> Clone for GenesisBuildAction<EHF> {
51	fn clone(&self) -> Self {
52		match self {
53			Self::Patch(ref p) => Self::Patch(p.clone()),
54			Self::Full(ref f) => Self::Full(f.clone()),
55			Self::NamedPreset(ref p, _) => Self::NamedPreset(p.clone(), Default::default()),
56		}
57	}
58}
59
60enum GenesisSource<EHF> {
61	File(PathBuf),
62	Binary(Cow<'static, [u8]>),
63	/// factory function + code
64	Storage(Storage),
65	/// build action + code
66	GenesisBuilderApi(GenesisBuildAction<EHF>, Vec<u8>),
67}
68
69impl<EHF> Clone for GenesisSource<EHF> {
70	fn clone(&self) -> Self {
71		match *self {
72			Self::File(ref path) => Self::File(path.clone()),
73			Self::Binary(ref d) => Self::Binary(d.clone()),
74			Self::Storage(ref s) => Self::Storage(s.clone()),
75			Self::GenesisBuilderApi(ref s, ref c) => Self::GenesisBuilderApi(s.clone(), c.clone()),
76		}
77	}
78}
79
80impl<EHF: HostFunctions> GenesisSource<EHF> {
81	fn resolve(&self) -> Result<Genesis, String> {
82		/// helper container for deserializing genesis from the JSON file (ChainSpec JSON file is
83		/// also supported here)
84		#[derive(Serialize, Deserialize)]
85		struct GenesisContainer {
86			genesis: Genesis,
87		}
88
89		match self {
90			Self::File(path) => {
91				let file = File::open(path).map_err(|e| {
92					format!("Error opening spec file at `{}`: {}", path.display(), e)
93				})?;
94				// SAFETY: `mmap` is fundamentally unsafe since technically the file can change
95				//         underneath us while it is mapped; in practice it's unlikely to be a
96				//         problem
97				let bytes = unsafe {
98					memmap2::Mmap::map(&file).map_err(|e| {
99						format!("Error mmaping spec file `{}`: {}", path.display(), e)
100					})?
101				};
102
103				let genesis: GenesisContainer = json::from_slice(&bytes)
104					.map_err(|e| format!("Error parsing spec file: {}", e))?;
105				Ok(genesis.genesis)
106			},
107			Self::Binary(buf) => {
108				let genesis: GenesisContainer = json::from_reader(buf.as_ref())
109					.map_err(|e| format!("Error parsing embedded file: {}", e))?;
110				Ok(genesis.genesis)
111			},
112			Self::Storage(storage) => Ok(Genesis::Raw(RawGenesis::from(storage.clone()))),
113			Self::GenesisBuilderApi(GenesisBuildAction::Full(config), code) =>
114				Ok(Genesis::RuntimeGenesis(RuntimeGenesisInner {
115					json_blob: RuntimeGenesisConfigJson::Config(config.clone()),
116					code: code.clone(),
117				})),
118			Self::GenesisBuilderApi(GenesisBuildAction::Patch(patch), code) =>
119				Ok(Genesis::RuntimeGenesis(RuntimeGenesisInner {
120					json_blob: RuntimeGenesisConfigJson::Patch(patch.clone()),
121					code: code.clone(),
122				})),
123			Self::GenesisBuilderApi(GenesisBuildAction::NamedPreset(name, _), code) => {
124				let patch = RuntimeCaller::<EHF>::new(&code[..]).get_named_preset(Some(name))?;
125				Ok(Genesis::RuntimeGenesis(RuntimeGenesisInner {
126					json_blob: RuntimeGenesisConfigJson::Patch(patch),
127					code: code.clone(),
128				}))
129			},
130		}
131	}
132}
133
134impl<E, EHF> BuildStorage for ChainSpec<E, EHF>
135where
136	EHF: HostFunctions,
137{
138	fn assimilate_storage(&self, storage: &mut Storage) -> Result<(), String> {
139		match self.genesis.resolve()? {
140			Genesis::Raw(RawGenesis { top: map, children_default: children_map }) => {
141				storage.top.extend(map.into_iter().map(|(k, v)| (k.0, v.0)));
142				children_map.into_iter().for_each(|(k, v)| {
143					let child_info = ChildInfo::new_default(k.0.as_slice());
144					storage
145						.children_default
146						.entry(k.0)
147						.or_insert_with(|| StorageChild { data: Default::default(), child_info })
148						.data
149						.extend(v.into_iter().map(|(k, v)| (k.0, v.0)));
150				});
151			},
152			// The `StateRootHash` variant exists as a way to keep note that other clients support
153			// it, but Substrate itself isn't capable of loading chain specs with just a hash at the
154			// moment.
155			Genesis::StateRootHash(_) =>
156				return Err("Genesis storage in hash format not supported".into()),
157			Genesis::RuntimeGenesis(RuntimeGenesisInner {
158				json_blob: RuntimeGenesisConfigJson::Config(config),
159				code,
160			}) => {
161				RuntimeCaller::<EHF>::new(&code[..])
162					.get_storage_for_config(config)?
163					.assimilate_storage(storage)?;
164				storage
165					.top
166					.insert(sp_core::storage::well_known_keys::CODE.to_vec(), code.clone());
167			},
168			Genesis::RuntimeGenesis(RuntimeGenesisInner {
169				json_blob: RuntimeGenesisConfigJson::Patch(patch),
170				code,
171			}) => {
172				RuntimeCaller::<EHF>::new(&code[..])
173					.get_storage_for_patch(patch)?
174					.assimilate_storage(storage)?;
175				storage
176					.top
177					.insert(sp_core::storage::well_known_keys::CODE.to_vec(), code.clone());
178			},
179		};
180
181		Ok(())
182	}
183}
184
185pub type GenesisStorage = BTreeMap<StorageKey, StorageData>;
186
187/// Raw storage content for genesis block.
188#[derive(Serialize, Deserialize)]
189#[serde(rename_all = "camelCase")]
190#[serde(deny_unknown_fields)]
191pub struct RawGenesis {
192	pub top: GenesisStorage,
193	pub children_default: BTreeMap<StorageKey, GenesisStorage>,
194}
195
196impl From<sp_core::storage::Storage> for RawGenesis {
197	fn from(value: sp_core::storage::Storage) -> Self {
198		Self {
199			top: value.top.into_iter().map(|(k, v)| (StorageKey(k), StorageData(v))).collect(),
200			children_default: value
201				.children_default
202				.into_iter()
203				.map(|(sk, child)| {
204					(
205						StorageKey(sk),
206						child
207							.data
208							.into_iter()
209							.map(|(k, v)| (StorageKey(k), StorageData(v)))
210							.collect(),
211					)
212				})
213				.collect(),
214		}
215	}
216}
217
218/// Inner representation of [`Genesis::RuntimeGenesis`] format
219#[derive(Serialize, Deserialize, Debug)]
220struct RuntimeGenesisInner {
221	/// Runtime wasm code, expected to be hex-encoded in JSON.
222	/// The code shall be capable of parsing `json_blob`.
223	#[serde(default, with = "sp_core::bytes")]
224	code: Vec<u8>,
225	/// The patch or full representation of runtime's `RuntimeGenesisConfig` struct.
226	#[serde(flatten)]
227	json_blob: RuntimeGenesisConfigJson,
228}
229
230/// Represents two possible variants of the contained JSON blob for the
231/// [`Genesis::RuntimeGenesis`] format.
232#[derive(Serialize, Deserialize, Debug)]
233#[serde(rename_all = "camelCase")]
234enum RuntimeGenesisConfigJson {
235	/// Represents the explicit and comprehensive runtime genesis config in JSON format.
236	/// The contained object is a JSON blob that can be parsed by a compatible runtime.
237	///
238	/// Using a full config is useful for when someone wants to ensure that a change in the runtime
239	/// makes the deserialization fail and not silently add some default values.
240	Config(json::Value),
241	/// Represents a patch for the default runtime genesis config in JSON format which is
242	/// essentially a list of keys that are to be customized in runtime genesis config.
243	/// The contained value is a JSON blob that can be parsed by a compatible runtime.
244	Patch(json::Value),
245}
246
247/// Represents the different formats of the genesis state within chain spec JSON blob.
248#[derive(Serialize, Deserialize)]
249#[serde(rename_all = "camelCase")]
250#[serde(deny_unknown_fields)]
251enum Genesis {
252	/// The genesis storage as raw data. Typically raw key-value entries in state.
253	Raw(RawGenesis),
254	/// State root hash of the genesis storage.
255	StateRootHash(StorageData),
256	/// Represents the runtime genesis config in JSON format together with runtime code.
257	RuntimeGenesis(RuntimeGenesisInner),
258}
259
260/// A configuration of a client. Does not include runtime storage initialization.
261/// Note: `genesis` field is ignored due to way how the chain specification is serialized into
262/// JSON file. Refer to [`ChainSpecJsonContainer`], which flattens [`ClientSpec`] and denies unknown
263/// fields.
264#[derive(Serialize, Deserialize, Clone, Debug)]
265#[serde(rename_all = "camelCase")]
266// we cannot #[serde(deny_unknown_fields)]. Otherwise chain-spec-builder will fail on any
267// non-standard spec
268struct ClientSpec<E> {
269	name: String,
270	id: String,
271	#[serde(default)]
272	chain_type: ChainType,
273	boot_nodes: Vec<MultiaddrWithPeerId>,
274	telemetry_endpoints: Option<TelemetryEndpoints>,
275	protocol_id: Option<String>,
276	/// Arbitrary string. Nodes will only synchronize with other nodes that have the same value
277	/// in their `fork_id`. This can be used in order to segregate nodes in cases when multiple
278	/// chains have the same genesis hash.
279	#[serde(default = "Default::default", skip_serializing_if = "Option::is_none")]
280	fork_id: Option<String>,
281	properties: Option<Properties>,
282	#[serde(flatten)]
283	extensions: E,
284	// Never used, left only for backward compatibility.
285	#[serde(default, skip_serializing)]
286	#[allow(unused)]
287	consensus_engine: (),
288	#[serde(skip_serializing)]
289	#[allow(unused)]
290	genesis: serde::de::IgnoredAny,
291	/// Mapping from `block_number` to `wasm_code`.
292	///
293	/// The given `wasm_code` will be used to substitute the on-chain wasm code starting with the
294	/// given block number until the `spec_version` on chain changes.
295	#[serde(default)]
296	code_substitutes: BTreeMap<String, Bytes>,
297}
298
299/// A type denoting empty extensions.
300///
301/// We use `Option` here since `()` is not flattenable by serde.
302pub type NoExtension = Option<()>;
303
304/// Builder for creating [`ChainSpec`] instances.
305pub struct ChainSpecBuilder<E = NoExtension, EHF = ()> {
306	code: Vec<u8>,
307	extensions: E,
308	name: String,
309	id: String,
310	chain_type: ChainType,
311	genesis_build_action: GenesisBuildAction<EHF>,
312	boot_nodes: Option<Vec<MultiaddrWithPeerId>>,
313	telemetry_endpoints: Option<TelemetryEndpoints>,
314	protocol_id: Option<String>,
315	fork_id: Option<String>,
316	properties: Option<Properties>,
317}
318
319impl<E, EHF> ChainSpecBuilder<E, EHF> {
320	/// Creates a new builder instance with no defaults.
321	pub fn new(code: &[u8], extensions: E) -> Self {
322		Self {
323			code: code.into(),
324			extensions,
325			name: "Development".to_string(),
326			id: "dev".to_string(),
327			chain_type: ChainType::Local,
328			genesis_build_action: GenesisBuildAction::Patch(json::json!({})),
329			boot_nodes: None,
330			telemetry_endpoints: None,
331			protocol_id: None,
332			fork_id: None,
333			properties: None,
334		}
335	}
336
337	/// Sets the spec name.
338	pub fn with_name(mut self, name: &str) -> Self {
339		self.name = name.into();
340		self
341	}
342
343	/// Sets the spec ID.
344	pub fn with_id(mut self, id: &str) -> Self {
345		self.id = id.into();
346		self
347	}
348
349	/// Sets the type of the chain.
350	pub fn with_chain_type(mut self, chain_type: ChainType) -> Self {
351		self.chain_type = chain_type;
352		self
353	}
354
355	/// Sets a list of bootnode addresses.
356	pub fn with_boot_nodes(mut self, boot_nodes: Vec<MultiaddrWithPeerId>) -> Self {
357		self.boot_nodes = Some(boot_nodes);
358		self
359	}
360
361	/// Sets telemetry endpoints.
362	pub fn with_telemetry_endpoints(mut self, telemetry_endpoints: TelemetryEndpoints) -> Self {
363		self.telemetry_endpoints = Some(telemetry_endpoints);
364		self
365	}
366
367	/// Sets the network protocol ID.
368	pub fn with_protocol_id(mut self, protocol_id: &str) -> Self {
369		self.protocol_id = Some(protocol_id.into());
370		self
371	}
372
373	/// Sets an optional network fork identifier.
374	pub fn with_fork_id(mut self, fork_id: &str) -> Self {
375		self.fork_id = Some(fork_id.into());
376		self
377	}
378
379	/// Sets additional loosely-typed properties of the chain.
380	pub fn with_properties(mut self, properties: Properties) -> Self {
381		self.properties = Some(properties);
382		self
383	}
384
385	/// Sets chain spec extensions.
386	pub fn with_extensions(mut self, extensions: E) -> Self {
387		self.extensions = extensions;
388		self
389	}
390
391	/// Sets the code.
392	pub fn with_code(mut self, code: &[u8]) -> Self {
393		self.code = code.into();
394		self
395	}
396
397	/// Sets the JSON patch for runtime's GenesisConfig.
398	pub fn with_genesis_config_patch(mut self, patch: json::Value) -> Self {
399		self.genesis_build_action = GenesisBuildAction::Patch(patch);
400		self
401	}
402
403	/// Sets the name of runtime-provided JSON patch for runtime's GenesisConfig.
404	pub fn with_genesis_config_preset_name(mut self, name: &str) -> Self {
405		self.genesis_build_action =
406			GenesisBuildAction::NamedPreset(name.to_string(), Default::default());
407		self
408	}
409
410	/// Sets the full runtime's GenesisConfig JSON.
411	pub fn with_genesis_config(mut self, config: json::Value) -> Self {
412		self.genesis_build_action = GenesisBuildAction::Full(config);
413		self
414	}
415
416	/// Builds a [`ChainSpec`] instance using the provided settings.
417	pub fn build(self) -> ChainSpec<E, EHF> {
418		let client_spec = ClientSpec {
419			name: self.name,
420			id: self.id,
421			chain_type: self.chain_type,
422			boot_nodes: self.boot_nodes.unwrap_or_default(),
423			telemetry_endpoints: self.telemetry_endpoints,
424			protocol_id: self.protocol_id,
425			fork_id: self.fork_id,
426			properties: self.properties,
427			extensions: self.extensions,
428			consensus_engine: (),
429			genesis: Default::default(),
430			code_substitutes: BTreeMap::new(),
431		};
432
433		ChainSpec {
434			client_spec,
435			genesis: GenesisSource::GenesisBuilderApi(self.genesis_build_action, self.code.into()),
436			_host_functions: Default::default(),
437		}
438	}
439}
440
441/// A configuration of a chain. Can be used to build a genesis block.
442///
443/// The chain spec is generic over the native `RuntimeGenesisConfig` struct (`G`). It is also
444/// possible to parametrize chain spec over the extended host functions (EHF). It should be use if
445/// runtime is using the non-standard host function during genesis state creation.
446pub struct ChainSpec<E = NoExtension, EHF = ()> {
447	client_spec: ClientSpec<E>,
448	genesis: GenesisSource<EHF>,
449	_host_functions: PhantomData<EHF>,
450}
451
452impl<E: Clone, EHF> Clone for ChainSpec<E, EHF> {
453	fn clone(&self) -> Self {
454		ChainSpec {
455			client_spec: self.client_spec.clone(),
456			genesis: self.genesis.clone(),
457			_host_functions: self._host_functions,
458		}
459	}
460}
461
462impl<E, EHF> ChainSpec<E, EHF> {
463	/// A list of bootnode addresses.
464	pub fn boot_nodes(&self) -> &[MultiaddrWithPeerId] {
465		&self.client_spec.boot_nodes
466	}
467
468	/// Spec name.
469	pub fn name(&self) -> &str {
470		&self.client_spec.name
471	}
472
473	/// Spec id.
474	pub fn id(&self) -> &str {
475		&self.client_spec.id
476	}
477
478	/// Telemetry endpoints (if any)
479	pub fn telemetry_endpoints(&self) -> &Option<TelemetryEndpoints> {
480		&self.client_spec.telemetry_endpoints
481	}
482
483	/// Network protocol id.
484	pub fn protocol_id(&self) -> Option<&str> {
485		self.client_spec.protocol_id.as_deref()
486	}
487
488	/// Optional network fork identifier.
489	pub fn fork_id(&self) -> Option<&str> {
490		self.client_spec.fork_id.as_deref()
491	}
492
493	/// Additional loosely-typed properties of the chain.
494	///
495	/// Returns an empty JSON object if 'properties' not defined in config
496	pub fn properties(&self) -> Properties {
497		self.client_spec.properties.as_ref().unwrap_or(&json::map::Map::new()).clone()
498	}
499
500	/// Add a bootnode to the list.
501	pub fn add_boot_node(&mut self, addr: MultiaddrWithPeerId) {
502		self.client_spec.boot_nodes.push(addr)
503	}
504
505	/// Returns a reference to the defined chain spec extensions.
506	pub fn extensions(&self) -> &E {
507		&self.client_spec.extensions
508	}
509
510	/// Returns a mutable reference to the defined chain spec extensions.
511	pub fn extensions_mut(&mut self) -> &mut E {
512		&mut self.client_spec.extensions
513	}
514
515	/// Type of the chain.
516	fn chain_type(&self) -> ChainType {
517		self.client_spec.chain_type.clone()
518	}
519
520	/// Provides a `ChainSpec` builder.
521	pub fn builder(code: &[u8], extensions: E) -> ChainSpecBuilder<E, EHF> {
522		ChainSpecBuilder::new(code, extensions)
523	}
524}
525
526impl<E: serde::de::DeserializeOwned, EHF> ChainSpec<E, EHF> {
527	/// Parse json content into a `ChainSpec`
528	pub fn from_json_bytes(json: impl Into<Cow<'static, [u8]>>) -> Result<Self, String> {
529		let json = json.into();
530		let client_spec = json::from_slice(json.as_ref())
531			.map_err(|e| format!("Error parsing spec file: {}", e))?;
532
533		Ok(ChainSpec {
534			client_spec,
535			genesis: GenesisSource::Binary(json),
536			_host_functions: Default::default(),
537		})
538	}
539
540	/// Parse json file into a `ChainSpec`
541	pub fn from_json_file(path: PathBuf) -> Result<Self, String> {
542		// We mmap the file into memory first, as this is *a lot* faster than using
543		// `serde_json::from_reader`. See https://github.com/serde-rs/json/issues/160
544		let file = File::open(&path)
545			.map_err(|e| format!("Error opening spec file `{}`: {}", path.display(), e))?;
546
547		// SAFETY: `mmap` is fundamentally unsafe since technically the file can change
548		//         underneath us while it is mapped; in practice it's unlikely to be a problem
549		let bytes = unsafe {
550			memmap2::Mmap::map(&file)
551				.map_err(|e| format!("Error mmaping spec file `{}`: {}", path.display(), e))?
552		};
553		let client_spec =
554			json::from_slice(&bytes).map_err(|e| format!("Error parsing spec file: {}", e))?;
555
556		Ok(ChainSpec {
557			client_spec,
558			genesis: GenesisSource::File(path),
559			_host_functions: Default::default(),
560		})
561	}
562}
563
564/// Helper structure for serializing (and only serializing) the ChainSpec into JSON file. It
565/// represents the layout of `ChainSpec` JSON file.
566#[derive(Serialize, Deserialize)]
567// we cannot #[serde(deny_unknown_fields)]. Otherwise chain-spec-builder will fail on any
568// non-standard spec.
569struct ChainSpecJsonContainer<E> {
570	#[serde(flatten)]
571	client_spec: ClientSpec<E>,
572	genesis: Genesis,
573}
574
575impl<E: serde::Serialize + Clone + 'static, EHF> ChainSpec<E, EHF>
576where
577	EHF: HostFunctions,
578{
579	fn json_container(&self, raw: bool) -> Result<ChainSpecJsonContainer<E>, String> {
580		let raw_genesis = match (raw, self.genesis.resolve()?) {
581			(
582				true,
583				Genesis::RuntimeGenesis(RuntimeGenesisInner {
584					json_blob: RuntimeGenesisConfigJson::Config(config),
585					code,
586				}),
587			) => {
588				let mut storage =
589					RuntimeCaller::<EHF>::new(&code[..]).get_storage_for_config(config)?;
590				storage.top.insert(sp_core::storage::well_known_keys::CODE.to_vec(), code);
591				RawGenesis::from(storage)
592			},
593			(
594				true,
595				Genesis::RuntimeGenesis(RuntimeGenesisInner {
596					json_blob: RuntimeGenesisConfigJson::Patch(patch),
597					code,
598				}),
599			) => {
600				let mut storage =
601					RuntimeCaller::<EHF>::new(&code[..]).get_storage_for_patch(patch)?;
602				storage.top.insert(sp_core::storage::well_known_keys::CODE.to_vec(), code);
603				RawGenesis::from(storage)
604			},
605			(true, Genesis::Raw(raw)) => raw,
606			(_, genesis) =>
607				return Ok(ChainSpecJsonContainer { client_spec: self.client_spec.clone(), genesis }),
608		};
609
610		Ok(ChainSpecJsonContainer {
611			client_spec: self.client_spec.clone(),
612			genesis: Genesis::Raw(raw_genesis),
613		})
614	}
615
616	/// Dump the chain specification to JSON string.
617	pub fn as_json(&self, raw: bool) -> Result<String, String> {
618		let container = self.json_container(raw)?;
619		json::to_string_pretty(&container).map_err(|e| format!("Error generating spec json: {}", e))
620	}
621}
622
623impl<E, EHF> crate::ChainSpec for ChainSpec<E, EHF>
624where
625	E: GetExtension + serde::Serialize + Clone + Send + Sync + 'static,
626	EHF: HostFunctions,
627{
628	fn boot_nodes(&self) -> &[MultiaddrWithPeerId] {
629		ChainSpec::boot_nodes(self)
630	}
631
632	fn name(&self) -> &str {
633		ChainSpec::name(self)
634	}
635
636	fn id(&self) -> &str {
637		ChainSpec::id(self)
638	}
639
640	fn chain_type(&self) -> ChainType {
641		ChainSpec::chain_type(self)
642	}
643
644	fn telemetry_endpoints(&self) -> &Option<TelemetryEndpoints> {
645		ChainSpec::telemetry_endpoints(self)
646	}
647
648	fn protocol_id(&self) -> Option<&str> {
649		ChainSpec::protocol_id(self)
650	}
651
652	fn fork_id(&self) -> Option<&str> {
653		ChainSpec::fork_id(self)
654	}
655
656	fn properties(&self) -> Properties {
657		ChainSpec::properties(self)
658	}
659
660	fn add_boot_node(&mut self, addr: MultiaddrWithPeerId) {
661		ChainSpec::add_boot_node(self, addr)
662	}
663
664	fn extensions(&self) -> &dyn GetExtension {
665		ChainSpec::extensions(self) as &dyn GetExtension
666	}
667
668	fn extensions_mut(&mut self) -> &mut dyn GetExtension {
669		ChainSpec::extensions_mut(self) as &mut dyn GetExtension
670	}
671
672	fn as_json(&self, raw: bool) -> Result<String, String> {
673		ChainSpec::as_json(self, raw)
674	}
675
676	fn as_storage_builder(&self) -> &dyn BuildStorage {
677		self
678	}
679
680	fn cloned_box(&self) -> Box<dyn crate::ChainSpec> {
681		Box::new(self.clone())
682	}
683
684	fn set_storage(&mut self, storage: Storage) {
685		self.genesis = GenesisSource::Storage(storage);
686	}
687
688	fn code_substitutes(&self) -> std::collections::BTreeMap<String, Vec<u8>> {
689		self.client_spec
690			.code_substitutes
691			.iter()
692			.map(|(h, c)| (h.clone(), c.0.clone()))
693			.collect()
694	}
695}
696
697/// The `fun` will be called with the value at `path`.
698///
699/// If exists, the value at given `path` will be passed to the `fun` and the result of `fun`
700/// call will be returned. Otherwise false is returned.
701/// `path` will be modified.
702///
703/// # Examples
704/// ```ignore
705/// use serde_json::{from_str, json, Value};
706/// let doc = json!({"a":{"b":{"c":"5"}}});
707/// let mut path = ["a", "b", "c"].into();
708/// assert!(json_eval_value_at_key(&doc, &mut path, &|v| { assert_eq!(v,"5"); true }));
709/// ```
710fn json_eval_value_at_key(
711	doc: &json::Value,
712	path: &mut VecDeque<&str>,
713	fun: &dyn Fn(&json::Value) -> bool,
714) -> bool {
715	let Some(key) = path.pop_front() else { return false };
716
717	if path.is_empty() {
718		doc.as_object().map_or(false, |o| o.get(key).map_or(false, |v| fun(v)))
719	} else {
720		doc.as_object()
721			.map_or(false, |o| o.get(key).map_or(false, |v| json_eval_value_at_key(v, path, fun)))
722	}
723}
724
725macro_rules! json_path {
726	[ $($x:expr),+ ] => {
727		VecDeque::<&str>::from([$($x),+])
728	};
729}
730
731fn json_contains_path(doc: &json::Value, path: &mut VecDeque<&str>) -> bool {
732	json_eval_value_at_key(doc, path, &|_| true)
733}
734
735/// This function updates the code in given chain spec.
736///
737/// Function support updating the runtime code in provided JSON chain spec blob. `Genesis::Raw`
738/// and `Genesis::RuntimeGenesis` formats are supported.
739///
740/// If update was successful `true` is returned, otherwise `false`. Chain spec JSON is modified in
741/// place.
742pub fn update_code_in_json_chain_spec(chain_spec: &mut json::Value, code: &[u8]) -> bool {
743	let mut path = json_path!["genesis", "runtimeGenesis", "code"];
744	let mut raw_path = json_path!["genesis", "raw", "top"];
745
746	if json_contains_path(&chain_spec, &mut path) {
747		#[derive(Serialize)]
748		struct Container<'a> {
749			#[serde(with = "sp_core::bytes")]
750			code: &'a [u8],
751		}
752		let code_patch = json::json!({"genesis":{"runtimeGenesis": Container { code }}});
753		crate::json_patch::merge(chain_spec, code_patch);
754		true
755	} else if json_contains_path(&chain_spec, &mut raw_path) {
756		#[derive(Serialize)]
757		struct Container<'a> {
758			#[serde(with = "sp_core::bytes", rename = "0x3a636f6465")]
759			code: &'a [u8],
760		}
761		let code_patch = json::json!({"genesis":{"raw":{"top": Container { code }}}});
762		crate::json_patch::merge(chain_spec, code_patch);
763		true
764	} else {
765		false
766	}
767}
768
769/// This function sets a codeSubstitute in the chain spec.
770pub fn set_code_substitute_in_json_chain_spec(
771	chain_spec: &mut json::Value,
772	code: &[u8],
773	block_height: u64,
774) {
775	let substitutes = json::json!({"codeSubstitutes":{ &block_height.to_string(): sp_core::bytes::to_hex(code, false) }});
776	crate::json_patch::merge(chain_spec, substitutes);
777}
778
779#[cfg(test)]
780mod tests {
781	use super::*;
782	use serde_json::{from_str, json, Value};
783	use sp_application_crypto::Ss58Codec;
784	use sp_core::storage::well_known_keys;
785	use sp_keyring::AccountKeyring;
786
787	type TestSpec = ChainSpec;
788
789	#[test]
790	fn should_deserialize_example_chain_spec() {
791		let spec1 = TestSpec::from_json_bytes(Cow::Owned(
792			include_bytes!("../res/chain_spec.json").to_vec(),
793		))
794		.unwrap();
795		let spec2 = TestSpec::from_json_file(PathBuf::from("./res/chain_spec.json")).unwrap();
796
797		assert_eq!(spec1.as_json(false), spec2.as_json(false));
798		assert_eq!(spec2.chain_type(), ChainType::Live)
799	}
800
801	#[derive(Debug, Serialize, Deserialize, Clone)]
802	#[serde(rename_all = "camelCase")]
803	struct Extension1 {
804		my_property: String,
805	}
806
807	impl crate::Extension for Extension1 {
808		type Forks = Option<()>;
809
810		fn get<T: 'static>(&self) -> Option<&T> {
811			None
812		}
813
814		fn get_any(&self, _: std::any::TypeId) -> &dyn std::any::Any {
815			self
816		}
817
818		fn get_any_mut(&mut self, _: std::any::TypeId) -> &mut dyn std::any::Any {
819			self
820		}
821	}
822
823	type TestSpec2 = ChainSpec<Extension1>;
824
825	#[test]
826	fn should_deserialize_chain_spec_with_extensions() {
827		let spec = TestSpec2::from_json_bytes(Cow::Owned(
828			include_bytes!("../res/chain_spec2.json").to_vec(),
829		))
830		.unwrap();
831
832		assert_eq!(spec.extensions().my_property, "Test Extension");
833	}
834
835	#[test]
836	fn chain_spec_raw_output_should_be_deterministic() {
837		let mut spec = TestSpec2::from_json_bytes(Cow::Owned(
838			include_bytes!("../res/chain_spec2.json").to_vec(),
839		))
840		.unwrap();
841
842		let mut storage = spec.build_storage().unwrap();
843
844		// Add some extra data, so that storage "sorting" is tested.
845		let extra_data = &[("random_key", "val"), ("r@nd0m_key", "val"), ("aaarandom_key", "val")];
846		storage
847			.top
848			.extend(extra_data.iter().map(|(k, v)| (k.as_bytes().to_vec(), v.as_bytes().to_vec())));
849		crate::ChainSpec::set_storage(&mut spec, storage);
850
851		let json = spec.as_json(true).unwrap();
852
853		// Check multiple times that decoding and encoding the chain spec leads always to the same
854		// output.
855		for _ in 0..10 {
856			assert_eq!(
857				json,
858				TestSpec2::from_json_bytes(json.as_bytes().to_vec())
859					.unwrap()
860					.as_json(true)
861					.unwrap()
862			);
863		}
864	}
865
866	#[test]
867	// some tests for json path utils
868	fn test_json_eval_value_at_key() {
869		let doc = json!({"a":{"b1":"20","b":{"c":{"d":"10"}}}});
870
871		assert!(json_eval_value_at_key(&doc, &mut json_path!["a", "b1"], &|v| { *v == "20" }));
872		assert!(json_eval_value_at_key(&doc, &mut json_path!["a", "b", "c", "d"], &|v| {
873			*v == "10"
874		}));
875		assert!(!json_eval_value_at_key(&doc, &mut json_path!["a", "c", "d"], &|_| { true }));
876		assert!(!json_eval_value_at_key(&doc, &mut json_path!["d"], &|_| { true }));
877
878		assert!(json_contains_path(&doc, &mut json_path!["a", "b1"]));
879		assert!(json_contains_path(&doc, &mut json_path!["a", "b"]));
880		assert!(json_contains_path(&doc, &mut json_path!["a", "b", "c"]));
881		assert!(json_contains_path(&doc, &mut json_path!["a", "b", "c", "d"]));
882		assert!(!json_contains_path(&doc, &mut json_path!["a", "b", "c", "d", "e"]));
883		assert!(!json_contains_path(&doc, &mut json_path!["a", "b", "b1"]));
884		assert!(!json_contains_path(&doc, &mut json_path!["d"]));
885	}
886
887	fn zeroize_code_key_in_json(encoded: bool, json: &str) -> Value {
888		let mut json = from_str::<Value>(json).unwrap();
889		let (zeroing_patch, mut path) = if encoded {
890			(
891				json!({"genesis":{"raw":{"top":{"0x3a636f6465":"0x0"}}}}),
892				json_path!["genesis", "raw", "top", "0x3a636f6465"],
893			)
894		} else {
895			(
896				json!({"genesis":{"runtimeGenesis":{"code":"0x0"}}}),
897				json_path!["genesis", "runtimeGenesis", "code"],
898			)
899		};
900		assert!(json_contains_path(&json, &mut path));
901		crate::json_patch::merge(&mut json, zeroing_patch);
902		json
903	}
904
905	#[docify::export]
906	#[test]
907	fn build_chain_spec_with_patch_works() {
908		let output = ChainSpec::<()>::builder(
909			substrate_test_runtime::wasm_binary_unwrap().into(),
910			Default::default(),
911		)
912		.with_name("TestName")
913		.with_id("test_id")
914		.with_chain_type(ChainType::Local)
915		.with_genesis_config_patch(json!({
916			"babe": {
917				"epochConfig": {
918					"c": [
919						7,
920						10
921					],
922					"allowed_slots": "PrimaryAndSecondaryPlainSlots"
923				}
924			},
925			"substrateTest": {
926				"authorities": [
927					AccountKeyring::Ferdie.public().to_ss58check(),
928					AccountKeyring::Alice.public().to_ss58check()
929				],
930			}
931		}))
932		.build();
933
934		let raw_chain_spec = output.as_json(true);
935		assert!(raw_chain_spec.is_ok());
936	}
937
938	#[test]
939	fn generate_chain_spec_with_named_preset_works() {
940		sp_tracing::try_init_simple();
941		let output: ChainSpec<()> = ChainSpec::builder(
942			substrate_test_runtime::wasm_binary_unwrap().into(),
943			Default::default(),
944		)
945		.with_name("TestName")
946		.with_id("test_id")
947		.with_chain_type(ChainType::Local)
948		.with_genesis_config_preset_name("staging")
949		.build();
950
951		let actual = output.as_json(false).unwrap();
952		let expected =
953			from_str::<Value>(include_str!("../res/substrate_test_runtime_from_named_preset.json"))
954				.unwrap();
955
956		//wasm blob may change overtime so let's zero it. Also ensure it is there:
957		let actual = zeroize_code_key_in_json(false, actual.as_str());
958
959		assert_eq!(actual, expected);
960	}
961
962	#[test]
963	fn generate_chain_spec_with_patch_works() {
964		let output = ChainSpec::<()>::builder(
965			substrate_test_runtime::wasm_binary_unwrap().into(),
966			Default::default(),
967		)
968		.with_name("TestName")
969		.with_id("test_id")
970		.with_chain_type(ChainType::Local)
971		.with_genesis_config_patch(json!({
972			"babe": {
973				"epochConfig": {
974					"c": [
975						7,
976						10
977					],
978					"allowed_slots": "PrimaryAndSecondaryPlainSlots"
979				}
980			},
981			"substrateTest": {
982				"authorities": [
983					AccountKeyring::Ferdie.public().to_ss58check(),
984					AccountKeyring::Alice.public().to_ss58check()
985				],
986			}
987		}))
988		.build();
989
990		let actual = output.as_json(false).unwrap();
991		let actual_raw = output.as_json(true).unwrap();
992
993		let expected =
994			from_str::<Value>(include_str!("../res/substrate_test_runtime_from_patch.json"))
995				.unwrap();
996		let expected_raw =
997			from_str::<Value>(include_str!("../res/substrate_test_runtime_from_patch_raw.json"))
998				.unwrap();
999
1000		//wasm blob may change overtime so let's zero it. Also ensure it is there:
1001		let actual = zeroize_code_key_in_json(false, actual.as_str());
1002		let actual_raw = zeroize_code_key_in_json(true, actual_raw.as_str());
1003
1004		assert_eq!(actual, expected);
1005		assert_eq!(actual_raw, expected_raw);
1006	}
1007
1008	#[test]
1009	fn generate_chain_spec_with_full_config_works() {
1010		let j = include_str!("../../../test-utils/runtime/res/default_genesis_config.json");
1011		let output = ChainSpec::<()>::builder(
1012			substrate_test_runtime::wasm_binary_unwrap().into(),
1013			Default::default(),
1014		)
1015		.with_name("TestName")
1016		.with_id("test_id")
1017		.with_chain_type(ChainType::Local)
1018		.with_genesis_config(from_str(j).unwrap())
1019		.build();
1020
1021		let actual = output.as_json(false).unwrap();
1022		let actual_raw = output.as_json(true).unwrap();
1023
1024		let expected =
1025			from_str::<Value>(include_str!("../res/substrate_test_runtime_from_config.json"))
1026				.unwrap();
1027		let expected_raw =
1028			from_str::<Value>(include_str!("../res/substrate_test_runtime_from_config_raw.json"))
1029				.unwrap();
1030
1031		//wasm blob may change overtime so let's zero it. Also ensure it is there:
1032		let actual = zeroize_code_key_in_json(false, actual.as_str());
1033		let actual_raw = zeroize_code_key_in_json(true, actual_raw.as_str());
1034
1035		assert_eq!(actual, expected);
1036		assert_eq!(actual_raw, expected_raw);
1037	}
1038
1039	#[test]
1040	fn chain_spec_as_json_fails_with_invalid_config() {
1041		let invalid_genesis_config = from_str::<Value>(include_str!(
1042			"../../../test-utils/runtime/res/default_genesis_config_invalid_2.json"
1043		))
1044		.unwrap();
1045		let output = ChainSpec::<()>::builder(
1046			substrate_test_runtime::wasm_binary_unwrap().into(),
1047			Default::default(),
1048		)
1049		.with_name("TestName")
1050		.with_id("test_id")
1051		.with_chain_type(ChainType::Local)
1052		.with_genesis_config(invalid_genesis_config.clone())
1053		.build();
1054
1055		let result = output.as_json(true).unwrap_err();
1056		let mut result = result.lines();
1057
1058		let result_header = result.next().unwrap();
1059		let result_body = result.collect::<Vec<&str>>().join("\n");
1060		let result_body: Value = serde_json::from_str(&result_body).unwrap();
1061
1062		let re = regex::Regex::new(concat!(
1063			r"^Invalid JSON blob: unknown field `babex`, expected one of `system`, `babe`, ",
1064			r"`substrateTest`, `balances` at line \d+ column \d+ for blob:$"
1065		))
1066		.unwrap();
1067
1068		assert_eq!(json!({"a":1,"b":2}), json!({"b":2,"a":1}));
1069		assert!(re.is_match(result_header));
1070		assert_eq!(invalid_genesis_config, result_body);
1071	}
1072
1073	#[test]
1074	fn chain_spec_as_json_fails_with_invalid_patch() {
1075		let output = ChainSpec::<()>::builder(
1076			substrate_test_runtime::wasm_binary_unwrap().into(),
1077			Default::default(),
1078		)
1079		.with_name("TestName")
1080		.with_id("test_id")
1081		.with_chain_type(ChainType::Local)
1082		.with_genesis_config_patch(json!({
1083			"invalid_pallet": {},
1084			"substrateTest": {
1085				"authorities": [
1086					AccountKeyring::Ferdie.public().to_ss58check(),
1087					AccountKeyring::Alice.public().to_ss58check()
1088				],
1089			}
1090		}))
1091		.build();
1092
1093		assert!(output.as_json(true).unwrap_err().contains("Invalid JSON blob: unknown field `invalid_pallet`, expected one of `system`, `babe`, `substrateTest`, `balances`"));
1094	}
1095
1096	#[test]
1097	fn check_if_code_is_valid_for_raw_without_code() {
1098		let spec = ChainSpec::<()>::from_json_bytes(Cow::Owned(
1099			include_bytes!("../res/raw_no_code.json").to_vec(),
1100		))
1101		.unwrap();
1102
1103		let j = from_str::<Value>(&spec.as_json(true).unwrap()).unwrap();
1104
1105		assert!(json_eval_value_at_key(
1106			&j,
1107			&mut json_path!["genesis", "raw", "top", "0x3a636f6465"],
1108			&|v| { *v == "0x010101" }
1109		));
1110		assert!(!json_contains_path(&j, &mut json_path!["code"]));
1111	}
1112
1113	#[test]
1114	fn check_code_in_assimilated_storage_for_raw_without_code() {
1115		let spec = ChainSpec::<()>::from_json_bytes(Cow::Owned(
1116			include_bytes!("../res/raw_no_code.json").to_vec(),
1117		))
1118		.unwrap();
1119
1120		let storage = spec.build_storage().unwrap();
1121		assert!(storage
1122			.top
1123			.get(&well_known_keys::CODE.to_vec())
1124			.map(|v| *v == vec![1, 1, 1])
1125			.unwrap())
1126	}
1127
1128	#[test]
1129	fn update_code_works_with_runtime_genesis_config() {
1130		let j = include_str!("../../../test-utils/runtime/res/default_genesis_config.json");
1131		let chain_spec = ChainSpec::<()>::builder(
1132			substrate_test_runtime::wasm_binary_unwrap().into(),
1133			Default::default(),
1134		)
1135		.with_name("TestName")
1136		.with_id("test_id")
1137		.with_chain_type(ChainType::Local)
1138		.with_genesis_config(from_str(j).unwrap())
1139		.build();
1140
1141		let mut chain_spec_json = from_str::<Value>(&chain_spec.as_json(false).unwrap()).unwrap();
1142		assert!(update_code_in_json_chain_spec(&mut chain_spec_json, &[0, 1, 2, 4, 5, 6]));
1143
1144		assert!(json_eval_value_at_key(
1145			&chain_spec_json,
1146			&mut json_path!["genesis", "runtimeGenesis", "code"],
1147			&|v| { *v == "0x000102040506" }
1148		));
1149	}
1150
1151	#[test]
1152	fn update_code_works_for_raw() {
1153		let j = include_str!("../../../test-utils/runtime/res/default_genesis_config.json");
1154		let chain_spec = ChainSpec::<()>::builder(
1155			substrate_test_runtime::wasm_binary_unwrap().into(),
1156			Default::default(),
1157		)
1158		.with_name("TestName")
1159		.with_id("test_id")
1160		.with_chain_type(ChainType::Local)
1161		.with_genesis_config(from_str(j).unwrap())
1162		.build();
1163
1164		let mut chain_spec_json = from_str::<Value>(&chain_spec.as_json(true).unwrap()).unwrap();
1165		assert!(update_code_in_json_chain_spec(&mut chain_spec_json, &[0, 1, 2, 4, 5, 6]));
1166
1167		assert!(json_eval_value_at_key(
1168			&chain_spec_json,
1169			&mut json_path!["genesis", "raw", "top", "0x3a636f6465"],
1170			&|v| { *v == "0x000102040506" }
1171		));
1172	}
1173
1174	#[test]
1175	fn update_code_works_with_runtime_genesis_patch() {
1176		let chain_spec = ChainSpec::<()>::builder(
1177			substrate_test_runtime::wasm_binary_unwrap().into(),
1178			Default::default(),
1179		)
1180		.with_name("TestName")
1181		.with_id("test_id")
1182		.with_chain_type(ChainType::Local)
1183		.with_genesis_config_patch(json!({}))
1184		.build();
1185
1186		let mut chain_spec_json = from_str::<Value>(&chain_spec.as_json(false).unwrap()).unwrap();
1187		assert!(update_code_in_json_chain_spec(&mut chain_spec_json, &[0, 1, 2, 4, 5, 6]));
1188
1189		assert!(json_eval_value_at_key(
1190			&chain_spec_json,
1191			&mut json_path!["genesis", "runtimeGenesis", "code"],
1192			&|v| { *v == "0x000102040506" }
1193		));
1194	}
1195}
sc_chain_spec/chain_spec.rs

sc_chain_spec/
chain_spec.rs
