add doc-only substrate entry point crate (#14581)

* add doc-only substrate entry point crate

* document a few more things

* add more

* fix width

* Update primitives/io/src/lib.rs

Co-authored-by: Gonçalo Pestana <g6pestana@gmail.com>

* add link

* update cargo toml file

* fix sp-io docs

* improve

* small update

* add license

* satisfy license job

* add a line about FRAME

* CI happy now

* make CI more happy

* Let the check run for the whole workspace

* Forward the substrate node again as default run

* update binary names

* upate verison test

* Fix fix fix

* Fix

* rename to substrate-node in more places

* Revert "rename to substrate-node in more places"

This reverts commit 66960f8.

* fix

* Fix build pipeline

* Fix properly plus add some docs

---------

Co-authored-by: Gonçalo Pestana <g6pestana@gmail.com>
Co-authored-by: Bastian Köcher <info@kchr.de>

Cargo.toml

@@ -1,3 +1,42 @@
+[package]
+name = "substrate"
+description = "Next-generation framework for blockchain innovation"
+license = "GPL-3.0-or-later WITH Classpath-exception-2.0"
+homepage = "https://substrate.io"
+repository = "https://github.com/paritytech/substrate/"
+authors = ["Parity Technologies <admin@parity.io>"]
+edition = "2021"
+version = "0.0.0"
+
+# This list of dependencies is for documentation purposes only.
+[dependencies]
+aquamarine = "0.3.2"
+
+subkey = { path = "bin/utils/subkey" }
+chain-spec-builder = { path = "bin/utils/chain-spec-builder" }
+
+sc-service = { path = "client/service" }
+sc-cli = { path = "client/cli" }
+sc-consensus-aura = { path = "client/consensus/aura" }
+sc-consensus-babe = { path = "client/consensus/babe" }
+sc-consensus-grandpa = { path = "client/consensus/grandpa" }
+sc-consensus-beefy = { path = "client/consensus/beefy" }
+sc-consensus-manual-seal = { path = "client/consensus/manual-seal" }
+sc-consensus-pow = { path = "client/consensus/pow" }
+
+sp-runtime = { path = "primitives/runtime" }
+frame-support = { path = "frame/support" }
+
+node-cli = { path = "bin/node/cli" }
+
+# Exists here to be backwards compatible and to support `cargo run` in the workspace.
+#
+# Just uses the `node-cli` main binary. `node-cli` itself also again exposes the node as
+# `substrate-node`. Using `node-cli` directly you can also enable features.
+[[bin]]
+name = "substrate"
+path = "bin/node/cli/bin/main.rs"
+
 [workspace]
 resolver = "2"
 

bin/node/cli/Cargo.toml

@@ -6,7 +6,7 @@ description = "Generic Substrate node implementation in Rust."
 build = "build.rs"
 edition = "2021"
 license = "GPL-3.0-or-later WITH Classpath-exception-2.0"
-default-run = "substrate"
+default-run = "substrate-node"
 homepage = "https://substrate.io"
 repository = "https://github.com/paritytech/substrate/"
 publish = false
@@ -25,8 +25,10 @@ maintenance = { status = "actively-developed" }
 is-it-maintained-issue-resolution = { repository = "paritytech/substrate" }
 is-it-maintained-open-issues = { repository = "paritytech/substrate" }
 
+# The same node binary as the `substrate` (defined in the workspace `Cargo.toml`) binary,
+# but just exposed by this crate here.
 [[bin]]
-name = "substrate"
+name = "substrate-node"
 path = "bin/main.rs"
 required-features = ["cli"]
 

bin/node/cli/tests/benchmark_block_works.rs

@@ -33,7 +33,7 @@ async fn benchmark_block_works() {
 	common::run_node_for_a_while(base_dir.path(), &["--dev", "--no-hardware-benchmarks"]).await;
 
 	// Invoke `benchmark block` with all options to make sure that they are valid.
-	let status = Command::new(cargo_bin("substrate"))
+	let status = Command::new(cargo_bin("substrate-node"))
 		.args(["benchmark", "block", "--dev"])
 		.arg("-d")
 		.arg(base_dir.path())

bin/node/cli/tests/benchmark_extrinsic_works.rs

@@ -32,7 +32,7 @@ fn benchmark_extrinsic_works() {
 fn benchmark_extrinsic(pallet: &str, extrinsic: &str) {
 	let base_dir = tempdir().expect("could not create a temp dir");
 
-	let status = Command::new(cargo_bin("substrate"))
+	let status = Command::new(cargo_bin("substrate-node"))
 		.args(&["benchmark", "extrinsic", "--dev"])
 		.arg("-d")
 		.arg(base_dir.path())

bin/node/cli/tests/benchmark_machine_works.rs

@@ -22,7 +22,7 @@ use std::process::Command;
 /// Tests that the `benchmark machine` command works for the substrate dev runtime.
 #[test]
 fn benchmark_machine_works() {
-	let status = Command::new(cargo_bin("substrate"))
+	let status = Command::new(cargo_bin("substrate-node"))
 		.args(["benchmark", "machine", "--dev"])
 		.args([
 			"--verify-duration",
@@ -48,7 +48,7 @@ fn benchmark_machine_works() {
 #[test]
 #[cfg(debug_assertions)]
 fn benchmark_machine_fails_with_slow_hardware() {
-	let output = Command::new(cargo_bin("substrate"))
+	let output = Command::new(cargo_bin("substrate-node"))
 		.args(["benchmark", "machine", "--dev"])
 		.args([
 			"--verify-duration",

bin/node/cli/tests/benchmark_overhead_works.rs

@@ -28,7 +28,7 @@ fn benchmark_overhead_works() {
 
 	// Only put 10 extrinsics into the block otherwise it takes forever to build it
 	// especially for a non-release build.
-	let status = Command::new(cargo_bin("substrate"))
+	let status = Command::new(cargo_bin("substrate-node"))
 		.args(&["benchmark", "overhead", "--dev", "-d"])
 		.arg(base_path)
 		.arg("--weight-path")

bin/node/cli/tests/benchmark_pallet_works.rs

@@ -34,7 +34,7 @@ fn benchmark_pallet_works() {
 }
 
 fn benchmark_pallet(steps: u32, repeat: u32, should_work: bool) {
-	let status = Command::new(cargo_bin("substrate"))
+	let status = Command::new(cargo_bin("substrate-node"))
 		.args(["benchmark", "pallet", "--dev"])
 		// Use the `addition` benchmark since is the fastest.
 		.args(["--pallet", "frame-benchmarking", "--extrinsic", "addition"])

bin/node/cli/tests/benchmark_storage_works.rs

@@ -40,7 +40,7 @@ fn benchmark_storage_works() {
 }
 
 fn benchmark_storage(db: &str, base_path: &Path) -> ExitStatus {
-	Command::new(cargo_bin("substrate"))
+	Command::new(cargo_bin("substrate-node"))
 		.args(&["benchmark", "storage", "--dev"])
 		.arg("--db")
 		.arg(db)

bin/node/cli/tests/build_spec_works.rs

@@ -24,7 +24,7 @@ use tempfile::tempdir;
 fn build_spec_works() {
 	let base_path = tempdir().expect("could not create a temp dir");
 
-	let output = Command::new(cargo_bin("substrate"))
+	let output = Command::new(cargo_bin("substrate-node"))
 		.args(&["build-spec", "--dev", "-d"])
 		.arg(base_path.path())
 		.output()

bin/node/cli/tests/check_block_works.rs

@@ -30,7 +30,7 @@ async fn check_block_works() {
 
 	common::run_node_for_a_while(base_path.path(), &["--dev", "--no-hardware-benchmarks"]).await;
 
-	let status = Command::new(cargo_bin("substrate"))
+	let status = Command::new(cargo_bin("substrate-node"))
 		.args(&["check-block", "--dev", "-d"])
 		.arg(base_path.path())
 		.arg("1")

bin/node/cli/tests/export_import_flow.rs

@@ -96,7 +96,7 @@ impl<'a> ExportImportRevertExecutor<'a> {
 		};
 
 		// Running the command and capturing the output.
-		let output = Command::new(cargo_bin("substrate"))
+		let output = Command::new(cargo_bin("substrate-node"))
 			.args(&arguments)
 			.arg(&base_path)
 			.arg(&self.exported_blocks_file)
@@ -160,7 +160,7 @@ impl<'a> ExportImportRevertExecutor<'a> {
 
 	/// Runs the `revert` command.
 	fn run_revert(&self) {
-		let output = Command::new(cargo_bin("substrate"))
+		let output = Command::new(cargo_bin("substrate-node"))
 			.args(&["revert", "--dev", "-d"])
 			.arg(&self.base_path.path())
 			.output()

bin/node/cli/tests/inspect_works.rs

@@ -30,7 +30,7 @@ async fn inspect_works() {
 
 	common::run_node_for_a_while(base_path.path(), &["--dev", "--no-hardware-benchmarks"]).await;
 
-	let status = Command::new(cargo_bin("substrate"))
+	let status = Command::new(cargo_bin("substrate-node"))
 		.args(&["inspect", "--dev", "-d"])
 		.arg(base_path.path())
 		.args(&["block", "1"])

bin/node/cli/tests/purge_chain_works.rs

@@ -29,7 +29,7 @@ async fn purge_chain_works() {
 
 	common::run_node_for_a_while(base_path.path(), &["--dev", "--no-hardware-benchmarks"]).await;
 
-	let status = Command::new(cargo_bin("substrate"))
+	let status = Command::new(cargo_bin("substrate-node"))
 		.args(&["purge-chain", "--dev", "-d"])
 		.arg(base_path.path())
 		.arg("-y")

bin/node/cli/tests/running_the_node_and_interrupt.rs

@@ -33,7 +33,7 @@ async fn running_the_node_works_and_can_be_interrupted() {
 		async fn run_command_and_kill(signal: Signal) {
 			let base_path = tempdir().expect("could not create a temp dir");
 			let mut cmd = common::KillChildOnDrop(
-				Command::new(cargo_bin("substrate"))
+				Command::new(cargo_bin("substrate-node"))
 					.stdout(process::Stdio::piped())
 					.stderr(process::Stdio::piped())
 					.args(&["--dev", "-d"])

bin/node/cli/tests/telemetry.rs

@@ -67,7 +67,7 @@ async fn telemetry_works() {
 			}
 		});
 
-		let mut substrate = process::Command::new(cargo_bin("substrate"));
+		let mut substrate = process::Command::new(cargo_bin("substrate-node"));
 
 		let mut substrate = KillChildOnDrop(
 			substrate

bin/node/cli/tests/temp_base_path_works.rs

@@ -31,7 +31,7 @@ use substrate_cli_test_utils as common;
 //#[tokio::test]
 async fn temp_base_path_works() {
 	common::run_with_timeout(Duration::from_secs(60 * 10), async move {
-		let mut cmd = Command::new(cargo_bin("substrate"));
+		let mut cmd = Command::new(cargo_bin("substrate-node"));
 		let mut child = common::KillChildOnDrop(
 			cmd.args(&["--dev", "--tmp", "--no-hardware-benchmarks"])
 				.stdout(Stdio::piped())

bin/node/cli/tests/version.rs

@@ -21,17 +21,17 @@ use regex::Regex;
 use std::process::Command;
 
 fn expected_regex() -> Regex {
-	Regex::new(r"^substrate (.+)-([a-f\d]+)$").unwrap()
+	Regex::new(r"^substrate-node (.+)-([a-f\d]+)$").unwrap()
 }
 
 #[test]
 fn version_is_full() {
 	let expected = expected_regex();
-	let output = Command::new(cargo_bin("substrate")).args(&["--version"]).output().unwrap();
+	let output = Command::new(cargo_bin("substrate-node")).args(&["--version"]).output().unwrap();
 
 	assert!(output.status.success(), "command returned with non-success exit code");
 
-	let output = String::from_utf8_lossy(&output.stdout).trim().to_owned();
+	let output = dbg!(String::from_utf8_lossy(&output.stdout).trim().to_owned());
 	let captures = expected.captures(output.as_str()).expect("could not parse version in output");
 
 	assert_eq!(&captures[1], env!("CARGO_PKG_VERSION"));
@@ -41,11 +41,11 @@ fn version_is_full() {
 fn test_regex_matches_properly() {
 	let expected = expected_regex();
 
-	let captures = expected.captures("substrate 2.0.0-da487d19d").unwrap();
+	let captures = expected.captures("substrate-node 2.0.0-da487d19d").unwrap();
 	assert_eq!(&captures[1], "2.0.0");
 	assert_eq!(&captures[2], "da487d19d");
 
-	let captures = expected.captures("substrate 2.0.0-alpha.5-da487d19d").unwrap();
+	let captures = expected.captures("substrate-node 2.0.0-alpha.5-da487d19d").unwrap();
 	assert_eq!(&captures[1], "2.0.0-alpha.5");
 	assert_eq!(&captures[2], "da487d19d");
 }

bin/utils/chain-spec-builder/Cargo.toml

@@ -13,6 +13,13 @@ publish = false
 [package.metadata.docs.rs]
 targets = ["x86_64-unknown-linux-gnu"]
 
+[[bin]]
+path = "bin/main.rs"
+name = "chain-spec-builder"
+
+[lib]
+crate-type = ["rlib"]
+
 [dependencies]
 ansi_term = "0.12.1"
 clap = { version = "4.2.5", features = ["derive"] }

bin/utils/chain-spec-builder/bin/main.rs

@@ -0,0 +1,89 @@
+// 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/>.
+
+use chain_spec_builder::{
+	generate_authority_keys_and_store, generate_chain_spec, print_seeds, ChainSpecBuilder,
+};
+use clap::Parser;
+use node_cli::chain_spec;
+use rand::{distributions::Alphanumeric, rngs::OsRng, Rng};
+use sp_core::{crypto::Ss58Codec, sr25519};
+use std::fs;
+
+fn main() -> Result<(), String> {
+	#[cfg(build_type = "debug")]
+	println!(
+		"The chain spec builder builds a chain specification that includes a Substrate runtime \
+		 compiled as WASM. To ensure proper functioning of the included runtime compile (or run) \
+		 the chain spec builder binary in `--release` mode.\n",
+	);
+
+	let builder = ChainSpecBuilder::parse();
+	let chain_spec_path = builder.chain_spec_path().to_path_buf();
+
+	let (authority_seeds, nominator_accounts, endowed_accounts, sudo_account) = match builder {
+		ChainSpecBuilder::Generate { authorities, nominators, endowed, keystore_path, .. } => {
+			let authorities = authorities.max(1);
+			let rand_str = || -> String {
+				OsRng.sample_iter(&Alphanumeric).take(32).map(char::from).collect()
+			};
+
+			let authority_seeds = (0..authorities).map(|_| rand_str()).collect::<Vec<_>>();
+			let nominator_seeds = (0..nominators).map(|_| rand_str()).collect::<Vec<_>>();
+			let endowed_seeds = (0..endowed).map(|_| rand_str()).collect::<Vec<_>>();
+			let sudo_seed = rand_str();
+
+			print_seeds(&authority_seeds, &nominator_seeds, &endowed_seeds, &sudo_seed);
+
+			if let Some(keystore_path) = keystore_path {
+				generate_authority_keys_and_store(&authority_seeds, &keystore_path)?;
+			}
+
+			let nominator_accounts = nominator_seeds
+				.into_iter()
+				.map(|seed| {
+					chain_spec::get_account_id_from_seed::<sr25519::Public>(&seed).to_ss58check()
+				})
+				.collect();
+
+			let endowed_accounts = endowed_seeds
+				.into_iter()
+				.map(|seed| {
+					chain_spec::get_account_id_from_seed::<sr25519::Public>(&seed).to_ss58check()
+				})
+				.collect();
+
+			let sudo_account =
+				chain_spec::get_account_id_from_seed::<sr25519::Public>(&sudo_seed).to_ss58check();
+
+			(authority_seeds, nominator_accounts, endowed_accounts, sudo_account)
+		},
+		ChainSpecBuilder::New {
+			authority_seeds,
+			nominator_accounts,
+			endowed_accounts,
+			sudo_account,
+			..
+		} => (authority_seeds, nominator_accounts, endowed_accounts, sudo_account),
+	};
+
+	let json =
+		generate_chain_spec(authority_seeds, nominator_accounts, endowed_accounts, sudo_account)?;
+
+	fs::write(chain_spec_path, json).map_err(|err| err.to_string())
+}