Skip to main content

Node Management

This page contains basic information about running a Parity Polkadot client. There are a lot of ways to obtain/run a client, e.g. compiling from source, running in Docker, or downloading a binary. This guide will always refer to the executable as polkadot.

Always refer to the client's help polkadot --help for the most up-to-date information.

note

Other client implementation teams: Feel free to make a PR to this page with instructions (or a link to instructions) for your client.

If you are trying to run a validator, refer to this tutorial here.

Basic Node Operations​

Selecting a chain

Use the --chain <chainspec> option to select the chain. Can be polkadot, kusama, westend, rococo, or a custom chain spec. By default, the client will start Polkadot. Watch How a single codebase can power four different blockchains to learn more about how the chain selection works internally.

Archive node

An archive node does not prune any block or state data. Use the --pruning archive flag. Certain types of nodes like validators must run in archive mode. Likewise, all events are cleared from state in each block, so if you want to store events then you will need an archive node.

Explainer video on upgrading a node

To upgrade a node, please refer to this video

Exporting blocks

To export blocks to a file, use export-blocks. Export in JSON (default) or binary (--binary true).

polkadot export-blocks --from 0 <output_file>

RPC ports

Use the --rpc-external flag to expose RPC ports. Not all RPC calls are safe to allow and you should use an RPC proxy to filter unsafe calls. Select ports with the --rpc-port option. To limit the hosts who can access, use the --rpc-cors option.

Execution

The Parity Polkadot client implements a Polkadot Host and a native runtime. The runtime must compile to WebAssembly and is stored on-chain. If the client's runtime is the same spec as the runtime that is stored on-chain, then the client will execute blocks using the client binary. Otherwise, the client will execute the Wasm runtime from the chain.

Therefore, when syncing the chain, the client will execute blocks from past runtimes using their associated Wasm binary. This feature also allows forkless upgrades: the client can execute a new runtime without updating the client.

Parity's Polkadot client has two Wasm execution methods, interpreted (default) and compiled. Set the preferred method to use when executing Wasm with --wasm-execution <Interpreted|Compiled>. Compiled execution will run much faster, especially when syncing the chain, but is experimental and may use more memory/CPU. A reasonable tradeoff would be to sync the chain with compiled execution and then restart the node with interpreted execution.

File Structure​

The node stores a number of files in: /home/$USER/.local/share/polkadot/chains/<chain name>/. You can set a custom path with --base-path <path>.

keystore

The keystore stores session keys, which are important for validator operations.

db

The database stores blocks and the state trie. If you are running a validator node, it also stores GRANDPA pre-votes and pre-commits and the offchain-worker DB. Use caution when migrating validator nodes to avoid equivocation. If you want to start a new machine without resyncing, you can stop your node, back up the DB, and move it to a new machine.

To delete your DB and re-sync from genesis, run:

polkadot purge-chain
Validators should sync using the RocksDb backend

This is implicit by default, but can be explicit by passing the --database RocksDb flag. In the future, it is recommended to switch to using the faster and more efficient ParityDb option. Switching between database backends will require a resync.

If you want to test out ParityDB you can add the flag --database paritydb.

Monitoring and Telemetry​

Node status

You can check the node's health via RPC with websocat:

echo '{"id":1,"jsonrpc":"2.0","method":"system_health","params":[]}' | websocat -n1 -B 99999999 ws://127.0.0.1:9944

{"jsonrpc":"2.0","result":{"peers":50,"isSyncing":false,"shouldHavePeers":true},"id":1}

Logs

The Polkadot client has a number of log targets. The most interesting to users may be:

  • afg (Al's Finality Gadget - GRANDPA consensus)
  • babe
  • telemetry
  • txpool
  • usage

Other targets include: db, gossip, peerset, state-db, state-trace, sub-libp2p, trie, wasm-executor, wasm-heap.

The log levels, from least to most verbose, are:

  • error
  • warn
  • info
  • debug
  • trace

All targets are set to info logging by default. You can adjust individual log levels using the --log (-l short) option, for example -l afg=trace,sync=debug or globally with -ldebug.

Telemetry & Metrics

The Parity Polkadot client connects to telemetry by default. You can disable it with --no-telemetry, or connect only to specified telemetry servers with the --telemetry-url option (see the help options for instructions). Connecting to public telemetry may expose information that puts your node at higher risk of attack. You can run your own, private telemetry server or deploy a substrate-telemetry instance to a Kubernetes cluster using this Helm chart.

The node also exposes a Prometheus endpoint by default (disable with --no-prometheus). Substrate has a monitor node metrics tutorial which uses this endpoint.