1use std::{
11 collections::HashMap,
12 path::Path,
13 sync::{Mutex, OnceLock},
14};
15
16use configuration::{
17 types::{AssetLocation, JamProtocolParameterType},
18 JamAuthorizer, JamBalance, JamGenesisConfig, JAM_BOOTSTRAP_SERVICE_ID,
19};
20use jam_chainspec::{Blob, ChainSpec, ChainSpecConfig, GenesisBalance, GenesisService};
21use jam_std_common::hash_raw;
22use jam_types::{hex, AuthorizerHash, Balance, ProtocolParameters, VALS_PER_CORE};
23use serde_json::json;
24use tracing::info;
25
26use crate::{
27 generators::{
28 errors::GeneratorError,
29 jam_blobs::{self, NULL_AUTHORIZER_BLOB},
30 jam_validators::{self, GenesisValidator},
31 },
32 network_spec::jamchain::JamchainSpec,
33};
34
35static BUILD_LOCK: Mutex<()> = Mutex::new(());
38
39static APPLIED_PARAMETERS: OnceLock<ProtocolParameters> = OnceLock::new();
42
43pub struct BuiltSpec {
45 pub spec: String,
47 pub summary: serde_json::Value,
49}
50
51pub async fn build(
53 jam_spec: &JamchainSpec,
54 genesis: &JamGenesisConfig,
55) -> Result<BuiltSpec, GeneratorError> {
56 let assets = fetch_assets(genesis).await?;
57 let parameters = protocol_parameters(&jam_spec.protocol_params_type, genesis)?;
58 let validators = jam_validators::genesis_validators(jam_spec);
59 check_validator_count(
60 &jam_spec.protocol_params_type,
61 genesis,
62 ¶meters,
63 &validators,
64 )?;
65
66 let bootstrap = if genesis.with_defaults() {
67 let bootstrap = bootstrap_service(genesis, &assets)?;
68 info!(
69 "🧰 JAM bootstrap service: {} (code hash 0x{})",
70 bootstrap.source,
71 hex::to_hex(&hash_raw(&bootstrap.code))
72 );
73 Some(bootstrap)
74 } else {
75 None
76 };
77
78 let config = base_config(jam_spec.id.as_str(), genesis, &validators, &assets)?;
79 let mut config = apply_genesis(config, genesis, &assets);
80 config.protocol_parameters = Some(parameters);
81 if let Some(bootstrap) = &bootstrap {
82 config = with_bootstrap_defaults(config, bootstrap.code.clone(), parameters.core_count);
83 }
84
85 let summary = summary(genesis, &config, bootstrap.as_ref(), ¶meters);
86 let spec = tokio::task::spawn_blocking(move || build_spec(config))
87 .await
88 .map_err(|e| GeneratorError::ChainSpecGeneration(e.to_string()))??;
89
90 Ok(BuiltSpec { spec, summary })
91}
92
93async fn fetch_assets(
95 genesis: &JamGenesisConfig,
96) -> Result<HashMap<AssetLocation, Vec<u8>>, GeneratorError> {
97 let mut assets = HashMap::new();
98 for location in genesis.asset_locations() {
99 if assets.contains_key(location) {
100 continue;
101 }
102 let content = location.get_asset().await.map_err(|e| {
103 GeneratorError::ChainSpecGeneration(format!("JAM genesis asset {location}: {e}"))
104 })?;
105 assets.insert(location.clone(), content);
106 }
107 Ok(assets)
108}
109
110fn protocol_parameters(
111 preset: &JamProtocolParameterType,
112 genesis: &JamGenesisConfig,
113) -> Result<ProtocolParameters, GeneratorError> {
114 if let Some(value) = genesis.protocol_parameters() {
115 return serde_json::from_value(value.clone()).map_err(|e| {
116 GeneratorError::ChainSpecGeneration(format!(
117 "JAM genesis protocol_parameters must set every parameter: {e}"
118 ))
119 });
120 }
121 Ok(match preset {
122 JamProtocolParameterType::Tiny => ProtocolParameters::tiny(),
123 JamProtocolParameterType::Mini => ProtocolParameters::mini(),
124 JamProtocolParameterType::Full => ProtocolParameters::full(),
125 })
126}
127
128fn check_validator_count(
130 preset: &JamProtocolParameterType,
131 genesis: &JamGenesisConfig,
132 parameters: &ProtocolParameters,
133 validators: &[GenesisValidator],
134) -> Result<(), GeneratorError> {
135 let expected = parameters.core_count as usize * VALS_PER_CORE;
136 let got = validators.len();
137 if got == expected {
138 return Ok(());
139 }
140 let parameters_name = if genesis.protocol_parameters().is_some() {
141 "the given protocol parameters".to_string()
142 } else {
143 format!("`{}`", preset.as_str())
144 };
145 Err(GeneratorError::ChainSpecGeneration(format!(
146 "the built-in JAM spec builder needs exactly {expected} validators for \
147 {parameters_name}, got {got}. Add validators, set `genesis.protocol_parameters`, or \
148 give a pre-built spec with `chain_spec_path`."
149 )))
150}
151
152fn base_config(
154 id: &str,
155 genesis: &JamGenesisConfig,
156 validators: &[GenesisValidator],
157 assets: &HashMap<AssetLocation, Vec<u8>>,
158) -> Result<ChainSpecConfig, GeneratorError> {
159 let (mut base, base_dir) = match genesis.config_file() {
160 Some(location) => {
161 let base: serde_json::Value =
162 serde_json::from_slice(&assets[location]).map_err(|e| {
163 GeneratorError::ChainSpecGeneration(format!(
164 "JAM genesis config_file {location}: {e}"
165 ))
166 })?;
167 if !base.is_object() {
168 return Err(GeneratorError::ChainSpecGeneration(format!(
169 "JAM genesis config_file {location}: must be a JSON object"
170 )));
171 }
172 let base_dir = match location {
174 AssetLocation::FilePath(path) => path.parent().map(Path::to_path_buf),
175 AssetLocation::Url(_) => None,
176 };
177 (base, base_dir)
178 },
179 None => (json!({}), None),
180 };
181
182 base["id"] = json!(id);
183 base["genesis_validators"] = serde_json::to_value(validators)
184 .map_err(|e| GeneratorError::EncodeDecodeError(e.to_string()))?;
185 if let Some(object) = base.as_object_mut() {
187 object.remove("protocol_parameters");
188 }
189
190 ChainSpecConfig::from_json(&base.to_string(), base_dir.as_deref()).map_err(spec_error)
191}
192
193fn apply_genesis(
195 mut config: ChainSpecConfig,
196 genesis: &JamGenesisConfig,
197 assets: &HashMap<AssetLocation, Vec<u8>>,
198) -> ChainSpecConfig {
199 for (id, service) in genesis.services() {
200 let mut genesis_service = GenesisService::new(Blob::Bytes(assets[service.code()].clone()))
201 .balance(match service.balance() {
202 JamBalance::Exact(balance) => GenesisBalance::Exact(balance),
203 JamBalance::MinimumPlus(extra) => GenesisBalance::MinimumPlus(extra),
204 })
205 .min_item_gas(service.min_item_gas())
206 .min_memo_gas(service.min_memo_gas())
207 .deposit_offset(service.deposit_offset());
208 for preimage in service.preimages() {
209 genesis_service = genesis_service.preimage(Blob::Bytes(assets[preimage].clone()));
210 }
211 for (key, value) in service.storage() {
212 genesis_service = genesis_service.storage(key.0.clone(), value.0.clone());
213 }
214 config.services.insert(*id, genesis_service);
215 }
216
217 for (core, authorizers) in genesis.auth_queues() {
218 let hashes: Vec<AuthorizerHash> = authorizers
219 .iter()
220 .map(|authorizer| match authorizer {
221 JamAuthorizer::Null => jam_blobs::null_authorizer_hash(),
222 JamAuthorizer::Hash(hash) => (*hash).into(),
223 JamAuthorizer::Code { code, config } => {
224 jam_blobs::authorizer_hash(&assets[code], config.as_bytes())
225 },
226 })
227 .collect();
228 config = config.auth_queue(*core, hashes);
229 }
230
231 let privileges = genesis.privileges();
233 if privileges.manager() != 0 {
234 config = config.manager(privileges.manager());
235 }
236 if privileges.delegator() != 0 {
237 config = config.delegator(privileges.delegator());
238 }
239 if privileges.registrar() != 0 {
240 config = config.registrar(privileges.registrar());
241 }
242 for (core, id) in privileges.assign() {
243 config = config.assigner([*core], *id);
244 }
245 for (id, gas) in privileges.always_acc() {
246 config = config.always_acc(*id, *gas);
247 }
248
249 config
250}
251
252fn with_bootstrap_defaults(
255 mut config: ChainSpecConfig,
256 bootstrap_code: Vec<u8>,
257 core_count: u16,
258) -> ChainSpecConfig {
259 config
260 .services
261 .entry(JAM_BOOTSTRAP_SERVICE_ID)
262 .or_insert_with(|| {
263 GenesisService::new(bootstrap_code)
265 .preimage(NULL_AUTHORIZER_BLOB)
266 .min_item_gas(10)
267 .min_memo_gas(10)
268 .deposit_offset(Balance::MAX)
269 .balance(Balance::MAX)
270 });
271
272 let null_authorizer = jam_blobs::null_authorizer_hash();
273 for core in 0..core_count {
274 config
275 .auth_queues
276 .entry(core)
277 .or_insert_with(|| vec![null_authorizer.into()]);
278 }
279 config
280}
281
282fn build_spec(config: ChainSpecConfig) -> Result<String, GeneratorError> {
284 let parameters = config
285 .protocol_parameters
286 .expect("the parameters are always set before building; qed");
287 let _guard = BUILD_LOCK
288 .lock()
289 .unwrap_or_else(|poisoned| poisoned.into_inner());
290
291 let applied = APPLIED_PARAMETERS.get_or_init(|| parameters);
292 if *applied != parameters {
293 return Err(GeneratorError::ChainSpecGeneration(
294 "the built-in JAM spec builder supports a single set of protocol parameters per \
295 process, and another set was already used. Spawn the networks from separate \
296 processes, or give a pre-built spec with `chain_spec_path`."
297 .to_string(),
298 ));
299 }
300
301 let spec = ChainSpec::from_config_and_apply_parameters(&config).map_err(spec_error)?;
302 Ok(spec.to_json())
303}
304
305struct BootstrapService {
307 code: Vec<u8>,
308 source: String,
310}
311
312fn bootstrap_service(
314 genesis: &JamGenesisConfig,
315 assets: &HashMap<AssetLocation, Vec<u8>>,
316) -> Result<BootstrapService, GeneratorError> {
317 if let Some(location) = genesis.bootstrap_service() {
318 return Ok(BootstrapService {
319 code: assets[location].clone(),
320 source: location.to_string(),
321 });
322 }
323 match jam_blobs::embedded_bootstrap_service() {
324 Some((code, source)) => Ok(BootstrapService {
325 code: code.to_vec(),
326 source: format!("embedded, {source}"),
327 }),
328 None => Err(GeneratorError::ChainSpecGeneration(
329 "no JAM bootstrap service: zombienet was built without the `jam` feature, which \
330 embeds one. Set `genesis.bootstrap_service` to a blob (a path or a url), enable the \
331 `jam` feature, or give a pre-built spec with `chain_spec_path`."
332 .to_string(),
333 )),
334 }
335}
336
337fn summary(
338 genesis: &JamGenesisConfig,
339 config: &ChainSpecConfig,
340 bootstrap: Option<&BootstrapService>,
341 parameters: &ProtocolParameters,
342) -> serde_json::Value {
343 let services: serde_json::Map<String, serde_json::Value> = config
344 .services
345 .iter()
346 .map(|(id, service)| {
347 let code_hash = service
348 .code
349 .read()
350 .map(|code| format!("0x{}", hex::to_hex(&hash_raw(&code))))
351 .unwrap_or_default();
352 (id.to_string(), json!({ "code_hash": code_hash }))
353 })
354 .collect();
355
356 json!({
357 "bootstrap_service": bootstrap.map(|bootstrap| json!({
358 "source": bootstrap.source,
359 "code_hash": format!("0x{}", hex::to_hex(&hash_raw(&bootstrap.code))),
360 })),
361 "protocol_parameters": parameters,
362 "services": services,
363 "genesis": genesis,
364 })
365}
366
367fn spec_error(error: jam_chainspec::Error) -> GeneratorError {
368 GeneratorError::ChainSpecGeneration(error.to_string())
369}
370
371#[cfg(test)]
372mod tests {
373 use configuration::{JamGenesisConfigBuilder, JamchainConfigBuilder};
374
375 use super::*;
376
377 const SERVICE_CODE: &[u8] = b"my service code";
378 const AUTHORIZER_CODE: &[u8] = b"my authorizer code";
379
380 fn jam_spec(
382 validators: usize,
383 genesis: impl FnOnce(JamGenesisConfigBuilder) -> JamGenesisConfigBuilder,
384 ) -> (JamchainSpec, JamGenesisConfig) {
385 let mut chain = JamchainConfigBuilder::new(Default::default())
386 .with_id("dev")
387 .with_genesis(genesis)
388 .with_validator(|n| n.with_name("jam0"));
389 for i in 1..validators {
390 chain = chain.with_validator(|n| n.with_name(&format!("jam{i}")));
391 }
392 let config = chain.build().expect("the chain config builds");
393 let genesis = config.genesis().cloned().unwrap_or_default();
394 let spec = JamchainSpec::from_config(&config).expect("the spec builds");
395 (spec, genesis)
396 }
397
398 fn state_values(spec: &str) -> Vec<String> {
399 let spec: serde_json::Value = serde_json::from_str(spec).unwrap();
400 spec["genesis_state"]
401 .as_object()
402 .unwrap()
403 .values()
404 .map(|v| v.as_str().unwrap().to_string())
405 .collect()
406 }
407
408 fn contains_blob(values: &[String], blob: &[u8]) -> bool {
409 values.contains(&hex::to_hex(blob).to_string())
410 }
411
412 fn write(dir: &Path, name: &str, content: &[u8]) -> String {
413 let path = dir.join(name);
414 std::fs::write(&path, content).unwrap();
415 path.to_string_lossy().to_string()
416 }
417
418 #[tokio::test]
421 async fn specs_are_built_from_the_genesis() {
422 #[cfg(feature = "jam")]
424 {
425 let (spec, genesis) = jam_spec(6, |g| g);
426 let built = build(&spec, &genesis).await.expect("the spec builds");
427 let parsed: serde_json::Value = serde_json::from_str(&built.spec).unwrap();
428 assert_eq!(parsed["id"], "dev");
429 let values = state_values(&built.spec);
430 assert!(contains_blob(&values, jam_blobs::BOOTSTRAP_SERVICE_BLOB));
431 assert!(contains_blob(&values, NULL_AUTHORIZER_BLOB));
432 assert_eq!(
433 built.summary["bootstrap_service"]["source"],
434 format!("embedded, {}", jam_blobs::BOOTSTRAP_SERVICE_SOURCE)
435 );
436 assert_eq!(
437 built.summary["bootstrap_service"]["code_hash"],
438 format!("0x{}", hex::to_hex(&jam_blobs::BOOTSTRAP_SERVICE_HASH))
439 );
440 }
441 #[cfg(not(feature = "jam"))]
443 {
444 let (spec, genesis) = jam_spec(6, |g| g);
445 let error = build(&spec, &genesis).await.err().unwrap();
446 assert!(error.to_string().contains("`jam` feature"), "{error}");
447
448 let (spec, genesis) = jam_spec(6, |g| g.without_defaults());
450 let built = build(&spec, &genesis).await.expect("the spec builds");
451 assert!(built.summary["bootstrap_service"].is_null());
452 }
453
454 let dir = tempfile::tempdir().unwrap();
456 let bootstrap = write(dir.path(), "bootstrap.jam", b"own bootstrap code");
457 let service = write(dir.path(), "svc.jam", SERVICE_CODE);
458 let authorizer = write(dir.path(), "auth.jam", AUTHORIZER_CODE);
459 let (spec, genesis) = jam_spec(6, |g| {
460 g.with_bootstrap_service(bootstrap.as_str())
461 .with_service(5, |s| {
462 s.with_code(service.as_str())
463 .with_balance(JamBalance::MinimumPlus(1_000))
464 .with_preimage(authorizer.as_str())
465 .with_storage(b"greeting".to_vec(), b"hello".to_vec())
466 })
467 .with_auth_queue(0, [JamAuthorizer::code(authorizer.as_str())])
468 .with_assigner([0], 5)
469 });
470 let built = build(&spec, &genesis).await.expect("the spec builds");
471 let values = state_values(&built.spec);
472 assert!(contains_blob(&values, b"own bootstrap code"));
473 assert!(contains_blob(&values, NULL_AUTHORIZER_BLOB));
474 #[cfg(feature = "jam")]
475 assert!(!contains_blob(&values, jam_blobs::BOOTSTRAP_SERVICE_BLOB));
476 assert!(contains_blob(&values, SERVICE_CODE));
477 assert!(contains_blob(&values, AUTHORIZER_CODE));
478 assert!(contains_blob(&values, b"hello"));
479 assert_eq!(
480 built.summary["bootstrap_service"]["source"],
481 bootstrap.as_str()
482 );
483 assert!(built.summary["services"]["5"].is_object());
484
485 write(dir.path(), "from-file.jam", b"service from the file");
487 let config_file = write(
488 dir.path(),
489 "chainspec.json",
490 br#"{
491 "id": "ignored",
492 "genesis_validators": [],
493 "services": { "7": { "code": "from-file.jam", "balance": 1000000 } }
494 }"#,
495 );
496 let (spec, genesis) = jam_spec(6, |g| {
497 g.with_bootstrap_service(bootstrap.as_str())
498 .with_config_file(config_file.as_str())
499 .with_service(5, |s| s.with_code(service.as_str()))
500 });
501 let built = build(&spec, &genesis).await.expect("the spec builds");
502 let values = state_values(&built.spec);
503 assert!(contains_blob(&values, b"service from the file"));
504 assert!(contains_blob(&values, SERVICE_CODE));
505 assert!(contains_blob(&values, b"own bootstrap code"));
506 let parsed: serde_json::Value = serde_json::from_str(&built.spec).unwrap();
507 assert_eq!(parsed["id"], "dev");
508
509 let (spec, genesis) = jam_spec(6, |g| {
511 g.with_bootstrap_service(bootstrap.as_str())
512 .with_auth_queue(7, [JamAuthorizer::Null])
513 });
514 let error = build(&spec, &genesis).await.err().unwrap();
515 assert!(error.to_string().contains("core 7"), "{error}");
516
517 let mini = serde_json::to_value(ProtocolParameters::mini()).unwrap();
519 let (spec, genesis) = jam_spec(78, |g| {
520 g.with_bootstrap_service(bootstrap.as_str())
521 .with_protocol_parameters(mini)
522 });
523 let error = build(&spec, &genesis).await.err().unwrap();
524 assert!(
525 error
526 .to_string()
527 .contains("single set of protocol parameters"),
528 "{error}"
529 );
530 }
531
532 #[tokio::test]
543 #[ignore = "needs POLKAJAM_BIN"]
544 async fn the_default_genesis_matches_gen_spec() {
545 let polkajam = std::env::var("POLKAJAM_BIN").expect("POLKAJAM_BIN is set");
546 let dir = tempfile::tempdir().unwrap();
547
548 let (spec, _) = jam_spec(6, |g| g);
550 let config_path = dir.path().join("jam_config.json");
551 let spec_path = dir.path().join("jam_spec.json");
552 std::fs::write(
553 &config_path,
554 json!({
555 "id": spec.id.as_str(),
556 "genesis_validators": jam_validators::genesis_validators(&spec),
557 })
558 .to_string(),
559 )
560 .unwrap();
561 let status = std::process::Command::new(polkajam)
562 .arg("gen-spec")
563 .arg(&config_path)
564 .arg(&spec_path)
565 .status()
566 .unwrap();
567 assert!(status.success());
568 let theirs: serde_json::Value =
569 serde_json::from_str(&std::fs::read_to_string(&spec_path).unwrap()).unwrap();
570
571 let bootstrap = theirs["genesis_state"]
573 .as_object()
574 .unwrap()
575 .values()
576 .map(|v| hex::from_hex(v.as_str().unwrap()).unwrap())
577 .max_by_key(Vec::len)
578 .unwrap();
579 let bootstrap_path = write(dir.path(), "bootstrap.jam", &bootstrap);
580
581 let genesis = JamGenesisConfigBuilder::new()
583 .with_bootstrap_service(bootstrap_path.as_str())
584 .build()
585 .unwrap();
586 let built = build(&spec, &genesis).await.expect("the spec builds");
587 let ours: serde_json::Value = serde_json::from_str(&built.spec).unwrap();
588
589 for key in ["id", "genesis_header", "protocol_parameters"] {
590 assert_eq!(ours[key], theirs[key], "{key} differs");
591 }
592 const SAFROLE: &str = "04000000000000000000000000000000000000000000000000000000000000";
593 const STATISTICS: &str = "0d000000000000000000000000000000000000000000000000000000000000";
594 let state = |spec: &serde_json::Value| {
595 let mut state = spec["genesis_state"].as_object().unwrap().clone();
596 state.remove(SAFROLE);
597 state.remove(STATISTICS);
598 state
599 };
600 let (ours, theirs) = (state(&ours), state(&theirs));
601 let differing: Vec<&String> = ours
602 .keys()
603 .chain(theirs.keys())
604 .filter(|key| ours.get(*key) != theirs.get(*key))
605 .collect();
606 assert!(
607 differing.is_empty(),
608 "genesis_state differs at {differing:?}"
609 );
610 }
611
612 #[tokio::test]
613 async fn the_validator_count_must_match_the_parameters() {
614 let (spec, genesis) = jam_spec(4, |g| g);
615
616 let error = build(&spec, &genesis).await.err().unwrap();
617
618 assert!(
619 error
620 .to_string()
621 .contains("needs exactly 6 validators for `tiny`, got 4"),
622 "{error}"
623 );
624 assert!(error.to_string().contains("chain_spec_path"), "{error}");
625 }
626
627 #[tokio::test]
628 async fn a_missing_asset_is_reported() {
629 let (spec, genesis) = jam_spec(6, |g| g.with_bootstrap_service("/does/not/exist.jam"));
630
631 let error = build(&spec, &genesis).await.err().unwrap();
632
633 assert!(error.to_string().contains("/does/not/exist.jam"), "{error}");
634 }
635
636 #[test]
637 fn every_core_gets_the_null_authorizer_unless_its_queue_is_set() {
638 let mut config = ChainSpecConfig::new("dev", vec![]).unwrap();
639 let own = AuthorizerHash::from([7; 32]);
640 config.auth_queues.insert(1, vec![own.into()]);
641
642 let config = with_bootstrap_defaults(config, b"bootstrap".to_vec(), 2);
643
644 assert_eq!(
645 config.auth_queues[&0][0].0,
646 jam_blobs::null_authorizer_hash()
647 );
648 assert_eq!(config.auth_queues[&1][0].0, own);
649 assert!(config.services.contains_key(&JAM_BOOTSTRAP_SERVICE_ID));
650 }
651
652 #[test]
653 fn a_bootstrap_service_from_the_genesis_is_kept() {
654 let mut config = ChainSpecConfig::new("dev", vec![]).unwrap();
655 config.services.insert(
656 JAM_BOOTSTRAP_SERVICE_ID,
657 GenesisService::new(b"own bootstrap").balance(1),
658 );
659
660 let config = with_bootstrap_defaults(config, b"bootstrap".to_vec(), 2);
661
662 assert_eq!(
663 config.services[&JAM_BOOTSTRAP_SERVICE_ID]
664 .code
665 .read()
666 .unwrap(),
667 b"own bootstrap"
668 );
669 }
670}