Simulate Network

Start a private blockchain network using predefined accounts as authorized validators.

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:

    The command prompts you to confirm the operation:

  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:

Review the command-line options

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

Option

Description

--base-path

Specifies the directory for storing all of the data related to this chain.

--chain local

Specifies the chain specification to use. Valid predefined chain specifications include local, development, and staging.

--alice

Adds the predefined keys for the alice account to the node's keystore. With this setting, the alice account is used for block production and finalization.

--port 30333

Specifies the port to listen on for peer-to-peer (p2p) traffic. Because this tutorial uses two nodes running on the same physical computer to simulate a network, you must explicitly specify a different port for at least one account.

--rpc-port 9945

Specifies the port on which the server will listen for incoming JSON-RPC traffic via WebSocket and HTTP. The default port is 9944. This tutorial uses a custom web socket port number (9945).

--node-key <key>

Specifies the Ed25519 secret key to use for libp2p networking. You should only use this option for development and testing.

--telemetry-url

Specifies where to send telemetry data. For this tutorial, you can send telemetry data to a server hosted by Parity that is available for anyone to use.

--validator

Specifies that this node participates in block production and finalization for the network.

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:

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:

    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:

    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:

    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:

  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.

PreviousBuild a Local BlockchainNextUpgrade a Running Network

Last updated