Augmented node template docs

bin/node-template/README.md

@@ -8,16 +8,17 @@ Follow these steps to prepare a local Substrate development environment :hammer_
 
 ### Simple Setup
 
-Install all the required dependencies with a single command (be patient, this can take up
-to 30 minutes).
+Install all the required dependencies with a single command (be patient, this can take up to 30
+minutes).
 
 ```bash
 curl https://getsubstrate.io -sSf | bash -s -- --fast
 ```
 
 ### Manual Setup
 
-Find manual setup instructions at the [Substrate Developer Hub](https://substrate.dev/docs/en/knowledgebase/getting-started/#manual-installation).
+Find manual setup instructions at the
+[Substrate Developer Hub](https://substrate.dev/docs/en/knowledgebase/getting-started/#manual-installation).
 
 ### Build
 
@@ -54,8 +55,8 @@ RUST_LOG=debug RUST_BACKTRACE=1 ./target/release/node-template -lruntime=debug -
 ### Multi-Node Local Testnet
 
 To see the multi-node consensus algorithm in action, run a local testnet with two validator nodes,
-Alice and Bob, that have been [configured](/bin/node-template/node/src/chain_spec.rs) as the
-initial authorities of the `local` testnet chain and endowed with testnet units.
+Alice and Bob, that have been [configured](/bin/node-template/node/src/chain_spec.rs) as the initial
+authorities of the `local` testnet chain and endowed with testnet units.
 
 Note: this will require two terminal sessions (one for each node).
 
@@ -92,6 +93,91 @@ cargo run -- \
 
 Execute `cargo run -- --help` to learn more about the template node's CLI options.
 
+## Template Structure
+
+A Substrate project such as this consists of a number of components that are spread across a few
+directories.
+
+### Node
+
+A blockchain node is an application that allows users to participate in a blockchain network.
+Substrate-based blockchain nodes expose a number of capabilities:
+
+-   Networking: Substrate nodes use the [`libp2p`](https://libp2p.io/) networking stack to allow the
+    nodes in the network to communicate with one another.
+-   Consensus: Blockchains must have a way to come to
+    [consensus](https://substrate.dev/docs/en/knowledgebase/advanced/consensus) on the state of the
+    network. Substrate makes it possible to supply custom consensus engines and also ships with
+    several consensus mechanisms that have been built on top of Web3 Foundation research.
+-   RPC Server: A remote procedure call (RPC) server is used to interact with Substrate nodes.
+
+There are several files in the `node` directory - take special note of the following:
+
+-   [`chain_spec.rs`](./node/src/chain_spec.rs): A
+    [chain specification](https://substrate.dev/docs/en/knowledgebase/integrate/chain-spec) is a
+    source code file that defines a Substrate chain's initial (genesis) state. Chain specifications
+    are useful for development and testing, and critical when architecting the launch of a
+    production chain. Take note of the `development_config` and `testnet_genesis` functions, which
+    are used to define the genesis state for the local development chain configuration. These
+    functions identify some
+    [well-known accounts](https://substrate.dev/docs/en/knowledgebase/integrate/subkey#well-known-keys)
+    and use them to configure the blockchain's initial state.
+-   [`service.rs`](./node/src/service.rs): This file defines the node implementation. Take note of
+    the libraries that this file imports and the names of the functions it invokes. In particular,
+    there are references to consensus-related topics, such as the
+    [longest chain rule](https://substrate.dev/docs/en/knowledgebase/advanced/consensus#longest-chain-rule),
+    the [Aura](https://substrate.dev/docs/en/knowledgebase/advanced/consensus#aura) block authoring
+    mechanism and the
+    [GRANDPA](https://substrate.dev/docs/en/knowledgebase/advanced/consensus#grandpa) finality
+    gadget.
+
+After the node has been [built](#build), refer to the embedded documentation to learn more about the
+capabilities and configuration parameters that it exposes:
+
+```shell
+./target/release/node-template --help
+```
+
+### Runtime
+
+The Substrate project in this repository uses the
+[FRAME](https://substrate.dev/docs/en/knowledgebase/runtime/frame) framework to construct a
+blockchain runtime. FRAME allows runtime developers to declare domain-specific logic in modules
+called "pallets". At the heart of FRAME is a helpful
+[macro language](https://substrate.dev/docs/en/knowledgebase/runtime/macros) that makes it easy to
+create pallets and flexibly compose them to create blockchains that can address a variety of needs.
+
+Review the [FRAME runtime implementation](./runtime/src/lib.rs) included in this template and note
+the following:
+
+-   This file configures several pallets to include in the runtime. Each pallet configuration is
+    defined by a code block that begins with `impl $PALLET_NAME::Trait for Runtime`.
+-   The pallets are composed into a single runtime by way of the
+    [`construct_runtime!`](https://crates.parity.io/frame_support/macro.construct_runtime.html)
+    macro, which is part of the core
+    [FRAME Support](https://substrate.dev/docs/en/knowledgebase/runtime/frame#support-library)
+    library.
+
+### Pallets
+
+The runtime in this project is constructed using many FRAME pallets that ship with the
+[core Substrate repository](https://github.com/paritytech/substrate/tree/master/frame) and a
+template pallet that is [defined in the `pallets`](./pallets/template/src/lib.rs) directory.
+
+A FRAME pallet is compromised of a number of blockchain primitives:
+
+-   Storage: FRAME defines a rich set of powerful
+    [storage abstractions](https://substrate.dev/docs/en/knowledgebase/runtime/storage) that makes
+    it easy to use Substrate's efficient key-value database to manage the evolving state of a
+    blockchain.
+-   Dispatchables: FRAME pallets define special types of functions that can be invoked (dispatched)
+    from outside of the runtime in order to update its state.
+-   Events: Substrate uses [events](https://substrate.dev/docs/en/knowledgebase/runtime/events) to
+    notify users of important changes in the runtime.
+-   Errors: When a dispatchable fails, it returns an error.
+-   Trait: The `Trait` configuration interface is used to define the types and parameters upon which
+    a FRAME pallet depends.
+
 ## Generate a Custom Node Template
 
 Generate a Substrate node template based on a particular commit by running the following commands:

bin/node-template/node/src/chain_spec.rs

@@ -8,13 +8,13 @@ use sp_finality_grandpa::AuthorityId as GrandpaId;
 use sp_runtime::traits::{Verify, IdentifyAccount};
 use sc_service::ChainType;
 
-// Note this is the URL for the telemetry server
-//const STAGING_TELEMETRY_URL: &str = "wss://telemetry.polkadot.io/submit/";
+// The URL for the telemetry server.
+// const STAGING_TELEMETRY_URL: &str = "wss://telemetry.polkadot.io/submit/";
 
 /// Specialized `ChainSpec`. This is a specialization of the general Substrate ChainSpec type.
 pub type ChainSpec = sc_service::GenericChainSpec<GenesisConfig>;
 
-/// Helper function to generate a crypto pair from seed
+/// Generate a crypto pair from seed.
 pub fn get_from_seed<TPublic: Public>(seed: &str) -> <TPublic::Pair as Pair>::Public {
 	TPublic::Pair::from_string(&format!("//{}", seed), None)
 		.expect("static values are valid; qed")
@@ -23,14 +23,14 @@ pub fn get_from_seed<TPublic: Public>(seed: &str) -> <TPublic::Pair as Pair>::Pu
 
 type AccountPublic = <Signature as Verify>::Signer;
 
-/// Helper function to generate an account ID from seed
+/// Generate an account ID from seed.
 pub fn get_account_id_from_seed<TPublic: Public>(seed: &str) -> AccountId where
 	AccountPublic: From<<TPublic::Pair as Pair>::Public>
 {
 	AccountPublic::from(get_from_seed::<TPublic>(seed)).into_account()
 }
 
-/// Helper function to generate an authority key for Aura
+/// Generate an Aura authority key.
 pub fn authority_keys_from_seed(s: &str) -> (AuraId, GrandpaId) {
 	(
 		get_from_seed::<AuraId>(s),
@@ -42,15 +42,20 @@ pub fn development_config() -> Result<ChainSpec, String> {
 	let wasm_binary = WASM_BINARY.ok_or("Development wasm binary not available".to_string())?;
 
 	Ok(ChainSpec::from_genesis(
+		// Name
 		"Development",
+		// ID
 		"dev",
 		ChainType::Development,
 		move || testnet_genesis(
 			wasm_binary,
+			// Initial PoA authorities
 			vec![
 				authority_keys_from_seed("Alice"),
 			],
+			// Sudo account
 			get_account_id_from_seed::<sr25519::Public>("Alice"),
+			// Pre-funded accounts
 			vec![
 				get_account_id_from_seed::<sr25519::Public>("Alice"),
 				get_account_id_from_seed::<sr25519::Public>("Bob"),
@@ -59,10 +64,15 @@ pub fn development_config() -> Result<ChainSpec, String> {
 			],
 			true,
 		),
+		// Bootnodes
 		vec![],
+		// Telemetry
 		None,
+		// Protocol ID
 		None,
+		// Properties
 		None,
+		// Extensions
 		None,
 	))
 }
@@ -71,16 +81,21 @@ pub fn local_testnet_config() -> Result<ChainSpec, String> {
 	let wasm_binary = WASM_BINARY.ok_or("Development wasm binary not available".to_string())?;
 
 	Ok(ChainSpec::from_genesis(
+		// Name
 		"Local Testnet",
+		// ID
 		"local_testnet",
 		ChainType::Local,
 		move || testnet_genesis(
 			wasm_binary,
+			// Initial PoA authorities
 			vec![
 				authority_keys_from_seed("Alice"),
 				authority_keys_from_seed("Bob"),
 			],
+			// Sudo account
 			get_account_id_from_seed::<sr25519::Public>("Alice"),
+			// Pre-funded accounts
 			vec![
 				get_account_id_from_seed::<sr25519::Public>("Alice"),
 				get_account_id_from_seed::<sr25519::Public>("Bob"),
@@ -97,14 +112,20 @@ pub fn local_testnet_config() -> Result<ChainSpec, String> {
 			],
 			true,
 		),
+		// Bootnodes
 		vec![],
+		// Telemetry
 		None,
+		// Protocol ID
 		None,
+		// Properties
 		None,
+		// Extensions
 		None,
 	))
 }
 
+/// Configure initial storage state for FRAME modules.
 fn testnet_genesis(
 	wasm_binary: &[u8],
 	initial_authorities: Vec<(AuraId, GrandpaId)>,
@@ -114,10 +135,12 @@ fn testnet_genesis(
 ) -> GenesisConfig {
 	GenesisConfig {
 		system: Some(SystemConfig {
+			// Add Wasm runtime to storage.
 			code: wasm_binary.to_vec(),
 			changes_trie_config: Default::default(),
 		}),
 		balances: Some(BalancesConfig {
+			// Configure endowed accounts with initial balance of 1 << 60.
 			balances: endowed_accounts.iter().cloned().map(|k|(k, 1 << 60)).collect(),
 		}),
 		aura: Some(AuraConfig {
@@ -127,6 +150,7 @@ fn testnet_genesis(
 			authorities: initial_authorities.iter().map(|x| (x.1.clone(), 1)).collect(),
 		}),
 		sudo: Some(SudoConfig {
+			// Assign network admin rights.
 			key: root_key,
 		}),
 	}

bin/node-template/pallets/template/Cargo.toml

@@ -6,7 +6,7 @@ version = "2.0.0-rc5"
 license = "Unlicense"
 homepage = "https://substrate.dev"
 repository = "https://github.com/paritytech/substrate/"
-description = "FRAME pallet template"
+description = "FRAME pallet template for defining custom runtime logic."
 
 [package.metadata.docs.rs]
 targets = ["x86_64-unknown-linux-gnu"]