Simulate a network

This tutorial provides a basic introduction to how you can start a private blockchain network with an authority set of private validators.

The Substrate node template uses an authority consensus model that limits block production to a rotating list of authorized accounts. The authorized accounts—authorities—are responsible for creating blocks in a round robin fashion.

In this tutorial, you'll see how the authority consensus model works in practice by using two predefined accounts as the authorities that enable the nodes to produce blocks. In this simulated network, the two nodes are started using different accounts and keys but run on a single computer.

Before you begin

Before you begin, verify the following:

• You have configured your environment for Substrate development by installing Rust and the Rust toolchain.
• You have completed Build a local blockchain and have the Substrate node template installed locally.
• You are generally familiar with software development and using command-line interfaces.
• You are generally familiar with blockchains and smart contract platforms.

Tutorial objectives

By completing this tutorial, you will accomplish the following objectives:

• Start a blockchain node using a predefined account.
• Learn the key command-line options used to start a node.
• Determine if a node is running and producing blocks.
• Connect a second node to a running network.
• Verify peer computers produce and finalize blocks.

Start the first blockchain node

Before you generate keys to start your own private Substrate network, you can learn the fundamental principles using a predefined network specification called local and running under predefined user accounts.

This tutorial simulates a private network by running two Substrate nodes on a single local computer using predefined accounts that are named alice and bob.

To start the blockchain:

1. Open a terminal shell on your computer.
2. Change to the root directory where you compiled the Substrate node template.

3. Purge old chain data by running the following command:

   ./target/release/node-template purge-chain --base-path /tmp/alice --chain local

   The command prompts you to confirm the operation:

   Are you sure to remove "/tmp/alice/chains/local_testnet/db"? [y/N]:

4. Type y to confirm that you want to remove the chain data.

   You should always remove old chain data when starting a new network.

5. Start the local blockchain node using the alice account by running the following command:

   ./target/release/node-template \
   --base-path /tmp/alice \
   --chain local \
   --alice \
   --port 30333 \
   --rpc-port 9945 \
   --node-key 0000000000000000000000000000000000000000000000000000000000000001 \
   --telemetry-url "wss://telemetry.polkadot.io/submit/ 0" \
   --validator

Review the command-line options

Before moving on, have a look at how the following options are used to start the node.

For more information about the command-line options that are available for the node template, see the usage help by running the following command:

./target/release/node-template --help

Review the node messages displayed

If the node starts successfully, the terminal displays messages describing network operations. For example, you should see output similar to this:

2022-08-16 15:29:55 Substrate Node    
2022-08-16 15:29:55 ✌️  version 4.0.0-dev-de262935ede    
2022-08-16 15:29:55 ❤️  by Substrate DevHub <https://github.com/substrate-developer-hub>, 2017-2022    
2022-08-16 15:29:55 📋 Chain specification: Local Testnet    
2022-08-16 15:29:55 🏷  Node name: Alice    
2022-08-16 15:29:55 👤 Role: AUTHORITY    
2022-08-16 15:29:55 💾 Database: RocksDb at /tmp/alice/chains/local_testnet/db/full    
2022-08-16 15:29:55 ⛓  Native runtime: node-template-100 (node-template-1.tx1.au1)    
2022-08-16 15:29:55 🔨 Initializing Genesis block/state (state: 0x6894…033d, header-hash: 0x2cdc…a07f)    
2022-08-16 15:29:55 👴 Loading GRANDPA authority set from genesis on what appears to be first startup.    
2022-08-16 15:29:56 Using default protocol ID "sup" because none is configured in the chain specs    
2022-08-16 15:29:56 🏷  Local node identity is: 12D3KooWEyoppNCUx8Yx66oV9fJnriXwCcXwDDUA2kj6vnc6iDEp    
2022-08-16 15:29:56 💻 Operating system: macos    
2022-08-16 15:29:56 💻 CPU architecture: x86_64    
2022-08-16 15:29:56 📦 Highest known block at #0    
2022-08-16 15:29:56 〽️ Prometheus exporter started at 127.0.0.1:9615    
2022-08-16 15:29:56 Running JSON-RPC server: addr=127.0.0.1:9945, allowed origins=Some(["http://localhost:*", "http://127.0.0.1:*", "https://localhost:*", "https://127.0.0.1:*", "https://polkadot.js.org"])      
2022-08-16 15:29:56 creating instance on iface 192.168.1.125    
2022-08-16 15:30:01 💤 Idle (0 peers), best: #0 (0x2cdc…a07f), finalized #0 (0x2cdc…a07f), ⬇ 0 ⬆ 0
...

In particular, you should note the following messages in the output:

• 🔨 Initializing Genesis block/state (state: 0xea47…9ba8, header-hash: 0x9d07…7cce) identifies the initial or genesis block that the node is using. When you start the next node, verify that these values are the same.
• 🏷 Local node identity is: 12D3KooWEyoppNCUx8Yx66oV9fJnriXwCcXwDDUA2kj6vnc6iDEp specifies a string that uniquely identifies this node. This string is determined by the --node-key that was used to start the node using the alice account. You use this string to identify the node to connect to when you start a second node.
• 2021-03-10 17:34:37 💤 Idle (0 peers), best: #0 (0x9d07…7cce), finalized #0 (0x9d07…7cce), ⬇ 0 ⬆ 0 indicates that there are no other nodes in the network and that no blocks are being produced. Another node must join the network before blocks can start to be produced.

Add a second node to the blockchain network

Now that the node you started using the alice account keys is running, you can add another node to the network using the bob account. Because you are joining a network that is already running, you can use the running node to identify the network for the new node to join. The commands are similar to the ones you used before, but with a few important differences.

To add a node to the running blockchain:

1. Open a new terminal shell on your computer.
2. Change to the root directory where you compiled the Substrate node template.

3. Purge old chain data by running the following command:

   ./target/release/node-template purge-chain --base-path /tmp/bob --chain local -y

   By adding -y to the command, you can remove chain data without being prompted you to confirm the operation.

4. Start a second local blockchain node using the bob account by running the following command:

   ./target/release/node-template \
   --base-path /tmp/bob \
   --chain local \
   --bob \
   --port 30334 \
   --rpc-port 9946 \
   --telemetry-url "wss://telemetry.polkadot.io/submit/ 0" \
   --validator \
   --bootnodes /ip4/127.0.0.1/tcp/30333/p2p/12D3KooWEyoppNCUx8Yx66oV9fJnriXwCcXwDDUA2kj6vnc6iDEp

   Note the following differences between this command and the previous one:

   • Because the two nodes are running on the same physical computer, you must specify different values for the --base-path, --port and --rpc-port options.
   • This command includes the --bootnodes option and specifies a single boot node, the node started by alice.

   The --bootnodes option specifies the following information:

   • ip4 indicates that the IP address for the node uses the IPv4 format
   • 127.0.0.1 specifies the IP address for the running node. In this case, the address for the localhost.
   • tcp specifies TCP as the protocol used for peer-to-peer communication.
   • 30333 specifies the port number used for peer-to-peer communication. In this case, the port number for TCP traffic.
   • 12D3KooWEyoppNCUx8Yx66oV9fJnriXwCcXwDDUA2kj6vnc6iDEp identifies the running node to communicate with for this network. In this case, the identifier for the node started using the alice account.

Verify blocks are produced and finalized

After you start the second node, the nodes should connect to each other as peers and start producing blocks.

To verify blocks are being finalized:

1. Verify that you see lines similar to the following in the terminal where you started the first node:

   2022-08-16 15:32:33 discovered: 12D3KooWBCbmQovz78Hq7MzPxdx9d1gZzXMsn6HtWj29bW51YUKB /ip4/127.0.0.1/tcp/30334
   2022-08-16 15:32:33 discovered: 12D3KooWBCbmQovz78Hq7MzPxdx9d1gZzXMsn6HtWj29bW51YUKB /ip6/::1/tcp/30334
   2022-08-16 15:32:36 🙌 Starting consensus session on top of parent 0x2cdce15d31548063e89e10bd201faa63c623023bbc320346b9580ed3c40fa07f
   2022-08-16 15:32:36 🎁 Prepared block for proposing at 1 (5 ms) [hash: 0x9ab34110e4617454da33a3616efc394eb1ce95ee4bf0daab69aa4cb392d4104b; parent_hash: 0x2cdc…a07f; extrinsics (1): [0x4634…cebf]] 
   2022-08-16 15:32:36 🔖 Pre-sealed block for proposal at 1. Hash now 0xf0869a5cb8ebd0fcc5f2bc194ced84ca782d9749604e888c8b9b515517179847, previously 0x9ab34110e4617454da33a3616efc394eb1ce95ee4bf0daab69aa4cb392d4104b.
   2022-08-16 15:32:36 ✨ Imported #1 (0xf086…9847)
   2022-08-16 15:32:36 💤 Idle (1 peers), best: #1 (0xf086…9847), finalized #0 (0x2cdc…a07f), ⬇ 1.0kiB/s ⬆ 1.0kiB/s
   2022-08-16 15:32:41 💤 Idle (1 peers), best: #1 (0xf086…9847), finalized #0 (0x2cdc…a07f), ⬇ 0.6kiB/s ⬆ 0.6kiB/s
   2022-08-16 15:32:42 ✨ Imported #2 (0x0d5e…2a7f)
   2022-08-16 15:32:46 💤 Idle (1 peers), best: #2 (0x0d5e…2a7f), finalized #0 (0x2cdc…a07f), ⬇ 0.6kiB/s ⬆ 0.6kiB/s
   2022-08-16 15:32:48 🙌 Starting consensus session on top of parent 0x0d5ef31979c2aa17fb88497018206d3057151119337293fe85d9526ebd1e2a7f
   2022-08-16 15:32:48 🎁 Prepared block for proposing at 3 (0 ms) [hash: 0xa307c0112bce39e0dc689132452154da2079a27375b44c4d94790b46a601346a; parent_hash: 0x0d5e…2a7f; extrinsics (1): [0x63cc…39a6]]    
   2022-08-16 15:32:48 🔖 Pre-sealed block for proposal at 3. Hash now 0x0c55670e745dd12892c9e7d5205085a78ccea98df393a822fa9b3865cfb3d51b, previously 0xa307c0112bce39e0dc689132452154da2079a27375b44c4d94790b46a601346a.
   2022-08-16 15:32:48 ✨ Imported #3 (0x0c55…d51b)
   2022-08-16 15:32:51 💤 Idle (1 peers), best: #3 (0x0c55…d51b), finalized #1 (0xf086…9847), ⬇ 0.7kiB/s ⬆ 0.9kiB/s    
   ...

   In these lines, you can see the following information about your blockchain:

   • The second node identity was discovered on the network (12D3KooWBCbmQovz78Hq7MzPxdx9d1gZzXMsn6HtWj29bW51YUKB).
   • The node has a one peer (1 peers).
   • The nodes have produced some blocks (best: #3 (0x0c55…d51b)).
   • The blocks are being finalized (finalized #1 (0xf086…9847)).
2. Verify that you see similar output in the terminal where you started the second node.

3. Shut down one of the nodes by pressing Control-c in the terminal shell.

   After you shut down the node, you'll see that the remaining node now has zero peers and has stopped producing blocks. For example:

   2022-08-16 15:53:45 💤 Idle (1 peers), best: #143 (0x8f11…1684), finalized #141 (0x5fe3…5a25), ⬇ 0.8kiB/s ⬆ 0.7kiB/s
   2022-08-16 15:53:50 💤 Idle (0 peers), best: #143 (0x8f11…1684), finalized #141 (0x5fe3…5a25), ⬇ 83 B/s ⬆ 83 B/s

4. Shut down the second node by pressing Control-c in the terminal shell.

   If you want to remove the chain state from the simulated network, use the purge-chain subcommand with the --base-path command-line options for the /tmp/bob and /tmp/alice directories.

Next steps

This tutorial introduced the first basic steps for starting a private blockchain network. In this tutorial, you simulated the private network by running two nodes on a single computer and using predefined accounts as participants.

You learned:

• How to use several of the node template commands and command-line options.
• How to start two blockchain nodes that communicate with each other as peers.
• How to verify your private blockchain nodes are producing blocks.

The next tutorial builds on the information you learned in this tutorial to illustrate how you can start a private network with other participants and nodes running on separate computers.

In Add trusted nodes, you'll learn:

• How to generate your own secret key pairs.
• How to create a custom chain specification that uses the keys you generated.
• How to add validators to a private network that uses your custom chain specification.

If you experienced any issues with this tutorial, submit an issue, ask questions, or provide feedback.

• Submit an issue.
• Substrate Stack Exchange.