polkadot_sdk_docs/guides/

your_first_node.rs

//! # Your first Node
//!
//! In this guide, you will learn how to run a runtime, such as the one created in
//! [`your_first_runtime`], in a node. Within the context of this guide, we will focus on running
//! the runtime with an [`omni-node`]. Please first read this page to learn about the OmniNode, and
//! other options when it comes to running a node.
//!
//! [`your_first_runtime`] is a runtime with no consensus related code, and therefore can only be
//! executed with a node that also expects no consensus ([`sc_consensus_manual_seal`]).
//! `polkadot-omni-node`'s [`--dev-block-time`] precisely does this.
//!
//! > All of the following steps are coded as unit tests of this module. Please see `Source` of the
//! > page for more information.
//!
//! ## Running The Omni Node
//!
//! ### Installs
//!
//! The `polkadot-omni-node` can either be downloaded from the latest [Release](https://github.com/paritytech/polkadot-sdk/releases/) of `polkadot-sdk`,
//! or installed using `cargo`:
//!
//! ```text
//! cargo install polkadot-omni-node
//! ```
//!
//! Next, we need to install the [`chain-spec-builder`]. This is the tool that allows us to build
//! chain-specifications, through interacting with the genesis related APIs of the runtime, as
//! described in [`crate::guides::your_first_runtime#genesis-configuration`].
//!
//! ```text
//! cargo install staging-chain-spec-builder
//! ```
//!
//! > The name of the crate is prefixed with `staging` as the crate name `chain-spec-builder` on
//! > crates.io is already taken and is not controlled by `polkadot-sdk` developers.
//!
//! ### Building Runtime
//!
//! Next, we need to build the corresponding runtime that we wish to interact with.
//!
//! ```text
//! cargo build --release -p path-to-runtime
//! ```
//! Equivalent code in tests:
#![doc = docify::embed!("./src/guides/your_first_node.rs", build_runtime)]
//!
//! This creates the wasm file under `./target/{release}/wbuild/release` directory.
//!
//! ### Building Chain Spec
//!
//! Next, we can generate the corresponding chain-spec file. For this example, we will use the
//! `development` (`sp_genesis_config::DEVELOPMENT`) preset.
//!
//! Note that we intend to run this chain-spec with `polkadot-omni-node`, which is tailored for
//! running parachains. This requires the chain-spec to always contain the `para_id` and a
//! `relay_chain` fields, which are provided below as CLI arguments.
//!
//! ```text
//! chain-spec-builder \
//! 	-c <path-to-output> \
//! 	create \
//! 	--para-id 42 \
//! 	--relay-chain dontcare \
//! 	--runtime polkadot_sdk_docs_first_runtime.wasm \
//! 	named-preset development
//! ```
//!
//! Equivalent code in tests:
#![doc = docify::embed!("./src/guides/your_first_node.rs", csb)]
//!
//!
//! ### Running `polkadot-omni-node`
//!
//! Finally, we can run the node with the generated chain-spec file. We can also specify the block
//! time using the `--dev-block-time` flag.
//!
//! ```text
//! polkadot-omni-node \
//! 	--tmp \
//! 	--dev-block-time 1000 \
//! 	--chain <chain_spec_file>.json
//! ```
//!
//! > Note that we always prefer to use `--tmp` for testing, as it will save the chain state to a
//! > temporary folder, allowing the chain-to be easily restarted without `purge-chain`. See
//! > [`sc_cli::commands::PurgeChainCmd`] and [`sc_cli::commands::RunCmd::tmp`] for more info.
//!
//! This will start the node and import the blocks. Note while using `--dev-block-time`, the node
//! will use the testing-specific manual-seal consensus. This is an efficient way to test the
//! application logic of your runtime, without needing to yet care about consensus, block
//! production, relay-chain and so on.
//!
//! ### Next Steps
//!
//! * See the rest of the steps in [`crate::reference_docs::omni_node#user-journey`].
//!
//! [`runtime`]: crate::reference_docs::glossary#runtime
//! [`node`]: crate::reference_docs::glossary#node
//! [`build_config`]: first_runtime::Runtime#method.build_config
//! [`omni-node`]: crate::reference_docs::omni_node
//! [`--dev-block-time`]: (polkadot_omni_node_lib::cli::Cli::dev_block_time)

#[cfg(test)]
mod tests {
	use assert_cmd::Command;
	use cmd_lib::*;
	use rand::Rng;
	use sc_chain_spec::{DEV_RUNTIME_PRESET, LOCAL_TESTNET_RUNTIME_PRESET};
	use sp_genesis_builder::PresetId;
	use std::path::PathBuf;

	const PARA_RUNTIME: &'static str = "parachain-template-runtime";
	const FIRST_RUNTIME: &'static str = "polkadot-sdk-docs-first-runtime";
	const MINIMAL_RUNTIME: &'static str = "minimal-template-runtime";

	const CHAIN_SPEC_BUILDER: &'static str = "chain-spec-builder";
	const OMNI_NODE: &'static str = "polkadot-omni-node";

	fn cargo() -> Command {
		Command::new(std::env::var("CARGO").unwrap_or_else(|_| "cargo".to_string()))
	}

	fn get_target_directory() -> Option<PathBuf> {
		let output = cargo().arg("metadata").arg("--format-version=1").output().ok()?;

		if !output.status.success() {
			return None;
		}

		let metadata: serde_json::Value = serde_json::from_slice(&output.stdout).ok()?;
		let target_directory = metadata["target_directory"].as_str()?;

		Some(PathBuf::from(target_directory))
	}

	fn find_release_binary(name: &str) -> Option<PathBuf> {
		let target_dir = get_target_directory()?;
		let release_path = target_dir.join("release").join(name);

		if release_path.exists() {
			Some(release_path)
		} else {
			None
		}
	}

	fn find_wasm(runtime_name: &str) -> Option<PathBuf> {
		let target_dir = get_target_directory()?;
		let wasm_path = target_dir
			.join("release")
			.join("wbuild")
			.join(runtime_name)
			.join(format!("{}.wasm", runtime_name.replace('-', "_")));

		if wasm_path.exists() {
			Some(wasm_path)
		} else {
			None
		}
	}

	fn maybe_build_runtimes() {
		if find_wasm(&PARA_RUNTIME).is_none() {
			println!("Building parachain-template-runtime...");
			Command::new("cargo")
				.arg("build")
				.arg("--release")
				.arg("-p")
				.arg(PARA_RUNTIME)
				.assert()
				.success();
		}
		if find_wasm(&FIRST_RUNTIME).is_none() {
			println!("Building polkadot-sdk-docs-first-runtime...");
			#[docify::export_content]
			fn build_runtime() {
				run_cmd!(
					cargo build --release -p $FIRST_RUNTIME
				)
				.expect("Failed to run command");
			}
			build_runtime()
		}

		assert!(find_wasm(PARA_RUNTIME).is_some());
		assert!(find_wasm(FIRST_RUNTIME).is_some());
	}

	fn maybe_build_chain_spec_builder() {
		if find_release_binary(CHAIN_SPEC_BUILDER).is_none() {
			println!("Building chain-spec-builder...");
			Command::new("cargo")
				.arg("build")
				.arg("--release")
				.arg("-p")
				.arg("staging-chain-spec-builder")
				.assert()
				.success();
		}
		assert!(find_release_binary(CHAIN_SPEC_BUILDER).is_some());
	}

	fn maybe_build_omni_node() {
		if find_release_binary(OMNI_NODE).is_none() {
			println!("Building polkadot-omni-node...");
			Command::new("cargo")
				.arg("build")
				.arg("--release")
				.arg("-p")
				.arg("polkadot-omni-node")
				.assert()
				.success();
		}
	}

	fn test_runtime_preset(runtime: &'static str, block_time: u64, maybe_preset: Option<PresetId>) {
		sp_tracing::try_init_simple();
		maybe_build_runtimes();
		maybe_build_chain_spec_builder();
		maybe_build_omni_node();

		let chain_spec_builder =
			find_release_binary(&CHAIN_SPEC_BUILDER).expect("we built it above; qed");
		let omni_node = find_release_binary(OMNI_NODE).expect("we built it above; qed");
		let runtime_path = find_wasm(runtime).expect("we built it above; qed");

		let random_seed: u32 = rand::thread_rng().gen();
		let chain_spec_file = std::env::current_dir()
			.unwrap()
			.join(format!("{}_{}_{}.json", runtime, block_time, random_seed));

		Command::new(chain_spec_builder)
			.args(["-c", chain_spec_file.to_str().unwrap()])
			.arg("create")
			.args(["--para-id", "1000", "--relay-chain", "dontcare"])
			.args(["-r", runtime_path.to_str().unwrap()])
			.args(match maybe_preset {
				Some(preset) => vec!["named-preset".to_string(), preset.to_string()],
				None => vec!["default".to_string()],
			})
			.assert()
			.success();

		let output = Command::new(omni_node)
			.arg("--tmp")
			.args(["--chain", chain_spec_file.to_str().unwrap()])
			.args(["--dev-block-time", block_time.to_string().as_str()])
			.timeout(std::time::Duration::from_secs(10))
			.output()
			.unwrap();

		std::fs::remove_file(chain_spec_file).unwrap();

		// uncomment for debugging.
		// println!("output: {:?}", output);

		let expected_blocks = (10_000 / block_time).saturating_div(2);
		assert!(expected_blocks > 0, "test configuration is bad, should give it more time");
		let output = String::from_utf8(output.stderr).unwrap();
		let want = format!("Imported #{}", expected_blocks);
		if !output.contains(&want) {
			panic!(
				"Output did not contain the pattern:\n\npattern: {}\n\noutput: {}\n",
				want, output
			);
		}
	}

	#[test]
	fn works_with_different_block_times() {
		test_runtime_preset(PARA_RUNTIME, 100, Some(DEV_RUNTIME_PRESET.into()));
		test_runtime_preset(PARA_RUNTIME, 3000, Some(DEV_RUNTIME_PRESET.into()));

		// we need this snippet just for docs
		#[docify::export_content(csb)]
		fn build_para_chain_spec_works() {
			let chain_spec_builder = find_release_binary(&CHAIN_SPEC_BUILDER).unwrap();
			let runtime_path = find_wasm(PARA_RUNTIME).unwrap();
			let output = "/tmp/demo-chain-spec.json";
			let runtime_str = runtime_path.to_str().unwrap();
			run_cmd!(
				$chain_spec_builder -c $output create --para-id 1000 --relay-chain dontcare -r $runtime_str named-preset development
			).expect("Failed to run command");
			std::fs::remove_file(output).unwrap();
		}
		build_para_chain_spec_works();
	}

	#[test]
	#[ignore]
	fn parachain_runtime_works() {
		// TODO: None doesn't work. But maybe it should? it would be misleading as many users might
		// use it.
		[Some(DEV_RUNTIME_PRESET.into()), Some(LOCAL_TESTNET_RUNTIME_PRESET.into())]
			.into_iter()
			.for_each(|preset| {
				test_runtime_preset(PARA_RUNTIME, 1000, preset);
			});
	}

	#[test]
	fn minimal_runtime_works() {
		[None, Some(DEV_RUNTIME_PRESET.into())].into_iter().for_each(|preset| {
			test_runtime_preset(MINIMAL_RUNTIME, 1000, preset);
		});
	}

	#[test]
	fn guide_first_runtime_works() {
		[Some(DEV_RUNTIME_PRESET.into())].into_iter().for_each(|preset| {
			test_runtime_preset(FIRST_RUNTIME, 1000, preset);
		});
	}

	#[test]
	fn omni_node_dev_mode_works() {
		//Omni Node in dev mode works with parachain's template `dev_chain_spec`
		let dev_chain_spec = std::env::current_dir()
			.unwrap()
			.parent()
			.unwrap()
			.parent()
			.unwrap()
			.join("templates")
			.join("parachain")
			.join("dev_chain_spec.json");

		maybe_build_omni_node();
		let omni_node = find_release_binary(OMNI_NODE).unwrap();

		let output = Command::new(omni_node)
			.arg("--dev")
			.args(["--chain", dev_chain_spec.to_str().unwrap()])
			.timeout(std::time::Duration::from_secs(70))
			.output()
			.unwrap();

		// atleast  blocks should be imported
		assert!(String::from_utf8(output.stderr)
			.unwrap()
			.contains(format!("Imported #{}", 7).to_string().as_str()));
	}
}