node-template

The node-template program provides a working Substrate node with FRAME system pallets and a subset of additional pallets for working with common blockchain functional operations. With its baseline of functional pallets, the node-template serves as a starter kit for building your own blockchain and developing a custom runtime. You can use the node-template program to start a Substrate node and to perform the tasks listed in Subcommands.

Basic command usage

The basic syntax for running node-template commands is:

node-template [subcommand] [flags] [options]

Depending on the subcommand you specify, additional arguments, options, and flags might apply or be required. To view usage information for a specific node-template subcommand, specify the subcommand and the --help flag. For example, to see usage information for node-template key, you can run the following command:

node-template key --help

Flags

You can use the following optional flags with the node-template command.

Options

You can use the following options with the node-template command.

Subcommands

You can use the following subcommands with the node-template command. For reference information and examples that illustrate using these subcommands, select an appropriate command.

benchmark

Use the node-template benchmark command to analyze the resources required to execute the transactions in extrinsic calls you have configured in runtime pallets. You can analyze individual extrinsic calls in specific pallets or all extrinsic calls in all pallets. With the benchmark subcommand, you can use additional command-line options to test different execution scenarios and compare the results.

Note that you must compile the node with benchmarking enabled to use all subcommands of node-template benchmark. To compile the node with benchmarking features enabled, run the following command:

cargo build --package node-template --release --features runtime-benchmarks

Basic command usage

node-template benchmark [subcommand] [flags] [options]

Depending on the subcommand you specify, additional arguments, options, and flags might apply or be required. To view usage information for a specific benchmark subcommand, specify the subcommand and the --help flag. For example, to see usage information for benchmark pallet, you can run the following command:

node-template benchmark pallet --help

Subcommands

You can use the following subcommands with the node-template benchmark command.

Flags

You can use the following optional flags with the node-template benchmark command.

Options

You can use all of the common node-template command-line options in combination with node-template benchmark subcommands. For example, you can use --base-path <path> to specify a custom directory for blockchain data and --chain <chain-specification> to specify the chain specification to use with any benchmark subcommand.

However, there are many command-line options that are specifically for performing benchmarking tasks. For example, the node-template benchmark block subcommand supports --from and --to command-line options for specifying the blocks to analyze.

Because benchmarking FRAME pallets represents the most common benchmarking task, the node-template benchmark pallet subcommand supports the most task-specific command-line options. For example, you can use the following options with the node-template benchmark pallet subcommand.

For examples of different benchmarking subcommands and the related command-line options, see Benchmarking examples.

Benchmarking examples

After you have compiled the runtime with benchmarking enabled, you can run a command similar to the following to benchmark all of the function calls in all of the pallets that have runtime-benchmarking configured:

./target/release/node-template benchmark pallet \
    --chain dev \
    --extrinsic "*" \
    --pallet "*" \
    --output pallets/weights.rs

With this command, each function call is executed once with a single value and the resulting weight is recorded in the weights.rs file.

Depending on the function you want to benchmark, you can add the --steps and --repeat command-line options to execute the call multiple times with different values. For example, the following command executes the do_something function in the pallet_template and calls the function 20 times to take 10 data points:

./target/release/node-template benchmark pallet \
    --chain dev \
    --extrinsic do_something \
    --pallet pallet_template \
    --steps 10 \
    --repeat 20 \
    --list

With the --list option, the command displays the following output:

pallet, benchmark
pallet_template, do_something

With the --steps and --repeat command-line options, the command displays the following benchmarking results:

Pallet: "pallet_template", Extrinsic: "do_something", Lowest values: [], Highest values: [], Steps: 10, Repeat: 20
Raw Storage Info
========
Storage: TemplateModule Something (r:0 w:1)

Median Slopes Analysis
========
-- Extrinsic Time --

Model:
Time ~=       12
    + s        0
              µs

Reads = 0 + (0 * s)
Writes = 1 + (0 * s)

Min Squares Analysis
========
-- Extrinsic Time --

Data points distribution:
    s   mean µs  sigma µs       %
    0      12.4     0.489    3.9%
   10      12.1       0.3    2.4%
   20      12.1       0.3    2.4%
   30      11.8       0.4    3.3%
   40        12         0    0.0%
   50      11.9       0.3    2.5%
   60        12         0    0.0%
   70      12.2       0.4    3.2%
   80        12         0    0.0%
   90        12         0    0.0%
  100        12         0    0.0%

Quality and confidence:
param     error
s             0

Model:
Time ~=    12.13
    + s        0
              µs

Reads = 0 + (0 * s)
Writes = 1 + (0 * s)

To measure the average, median, minimum, and maximum execution time per-block and per-extrinsic, you can run the node-template benchmark overhead subcommand:

./target/release/node-template benchmark overhead

The command displays output similar to the following:

Running 10 warmups...    
Executing block 100 times    
Per-block execution overhead [ns]:
	Total: 81779519
	Min: 695173, Max: 1522917
	Average: 817795, Median: 763360, Stddev: 160759.2
	Percentiles 99th, 95th, 75th: 1443343, 1263935, 814356    
	Writing weights to "block_weights.rs"    
Running 10 warmups...    
Executing block 100 times    
Building block, this takes some time...    
Extrinsics per block: 12000    
Running 10 warmups...    
Executing block 100 times
Per-extrinsic execution overhead [ns]:
	Total: 8955542
	Min: 85950, Max: 97448
	Average: 89555, Median: 88348, Stddev: 2713.05
	Percentiles 99th, 95th, 75th: 97247, 95040, 91733    
	Writing weights to "extrinsic_weights.rs"

By default, the command executes the benchmark 100 times, generates results, and writes the output to the block_weights.rs and extrinsics_weights.rs files. You can use command-line options to adjust the calculated weight by adding units or by multiplying the average execution time by some factor.

To measure the storage execution time for the Substrate development chain specification, you can run the following command:

./target/release/node-template benchmark storage --state-version 1

The command displays output similar to the following:

Warmup round 1/1    
Preparing keys from block BlockId::Number(0)    
Reading 36 keys    
Time summary [ns]:
	Total: 478367
	Min: 8889, Max: 32258
	Average: 13287, Median: 12580, Stddev: 4189.73
	Percentiles 99th, 95th, 75th: 32258, 21863, 14563
Value size summary:
	Total: 157217
	Min: 1, Max: 155944
	Average: 4367, Median: 16, Stddev: 25621.19
	Percentiles 99th, 95th, 75th: 155944, 82, 80    
Warmup round 1/1    
Preparing keys from block BlockId::Number(0)    
Writing 36 keys    
Time summary [ns]:
	Total: 1877401
	Min: 13476, Max: 665226
	Average: 52150, Median: 25740, Stddev: 111805.24
	Percentiles 99th, 95th, 75th: 665226, 252697, 30427
Value size summary:
	Total: 157217
	Min: 1, Max: 155944
	Average: 4367, Median: 16, Stddev: 25621.19
	Percentiles 99th, 95th, 75th: 155944, 82, 80    
Writing weights to "rocksdb_weights.rs"

To get benchmarking information for the paritydb database instead of the default rocksdb database, use the --db paritydb command-line option. TO get storage benchmarking information for Polkadot or any other real chain snapshot, use the command-line option --state-version 0. For more information about using the benchmark storage subcommand, see benchmark storage command.

For more information about how to add benchmarking to the runtime, see Benchmark and Add benchmarks.

build-spec

Use the node-template build-spec command to create a chain specification file for your runtime.

Basic command usage

node-template build-spec [flags] [options]

Flags

You can use the following optional flags with the node-template build-spec command.

Options

You can use the following command-line options with the node-template build-spec command.

Examples

To export the predefined local chain specification to a file named customSpec.json, you can run the following command:

./target/release/node-template build-spec --chain local > customSpec.json

If you have previously created a JSON file that contains a custom chain specification, you can specify the path to that file and use the --raw command-line option to export the chain specification with encoded storage keys that the node uses to reference the data in its local storage.

./target/release/node-template build-spec --chain ./my-test-chain.json --raw

check-block

Use the node-template check-block command to validate a specific block. You must specify the block to validate by the block hash or block number.

Basic command usage

node-template check-block [flags] [options] <block-identifier>

Flags

You can use the following optional flags with the node-template check-block command.

Options

You can use the following command-line options with the node-template check-block command.

Arguments

You must specify the following command-line argument when you run the node-template check-block command.

export-blocks

Use the node-template export-blocks command to export blocks.

Basic command usage

node-template export-blocks [flags] [options] [--] [output]

Flags

You can use the following optional flags with the node-template export-blocks command.

Options

You can use the following command-line options with the node-template export-blocks command.

Arguments

You can specify the following command-line argument when you run the node-template export-blocks command.

export-state

Use the node-template export-state command to export the state of a given block into a chain specification.

Basic command usage

node-template export-state [flags] [options] [--] [block-identifier]

Flags

You can use the following optional flags with the node-template export-state command.

Options

You can use the following command-line options with the node-template export-state command.

Arguments

You can specify the following command-line argument when you run the node-template export-state command.

help

Use the node-template help command to display usage information for node-template or a summary of command-line usage information for any node-template subcommand.

Basic command usage

node-template help [subcommand]

Examples

To display a summary of usage information for the export-blocks subcommand, run the following command:

node-template help export-blocks

import-blocks

Use the node-template import-blocks command to import blocks.

Basic command usage

node-template import-blocks [flags] [options] [--] [input]

Flags

You can use the following optional flags with the node-template import-blocks command.

Options

You can use the following command-line options with the node-template import-blocks command.

Arguments

You can specify the following command-line argument when you run the node-template import-blocks command.

key

Use the node-template key command to generate, inspect, and manage private and public key pairs and addresses. The node-template key command provides convenient access to a subset of key management services that are available in the standalone subkey program. For complete details about the subcommands and command-line options for most node-template key subcommands, see subkey. Although most of the node-template key subcommands are identical to [subkey] subcommands, the node-template key insert subcommand is not a supported [subkey] subcommand. The node-template key insert subcommand enables you to add generated keys directly to a node keystore. For information about the command-line options and arguments to use with the node-template key insert subcommand, see Insert a key on a node or run the following command:

node-template key insert --help

Basic command usage

node-template key [subcommand] [flags]

Flags

You can use the following optional flags with the node-template key command.

Subcommands

You can use the following subcommands with the node-template key command.

Insert a key on a node

Use the node-template key insert command to add the keys used for performing node operations to the node keystore. For example, keys are required to secure peer-to-peer communication between nodes and to enable nodes to act as validating authorities for consensus.

Basic command usage

node-template key insert [FLAGS] [OPTIONS] --key-type <key-type> --scheme <SCHEME>

Flags

You can use the following optional flags with the node-template key insert command.

Options

You can use the following command-line options with the node-template key insert command.

purge-chain

Use the node-template purge-chain command to remove a blockchain and all blockchain-related information.

Basic command usage

node-template purge-chain [flags] [options]

Flags

You can use the following optional flags with the node-template purge-chain command.

| -V, --version | Displays version information. -y | Provides a preemptive yes response to skip the interactive prompt to confirm that you want to remove the chain.

Options

You can use the following command-line options with the node-template purge-chain command.

revert

Use the node-template revert command to revert the chain to a previous state.

Basic command usage

node-template revert [flags] [options] [--] [num]

Flags

You can use the following optional flags with the node-template revert command.

Options

You can use the following command-line options with the node-template rever command.

Arguments

You can use the following command-line argument with the node-template revert command.