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).
RPC ports
Use the --rpc-external flag to expose RPC ports and --ws-external to expose websockets. 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 and --ws-port options. 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:
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.
Deployment Tools
Web3 Foundation maintains Polkadot Deployer, which allows you to create local or remote cloud deployments of Polkadot nodes. See the README for instructions.
Validators, see the validator setup guide for information specific to deploying validator nodes.
Monitoring and Telemetry
Node status
You can check the node's health via RPC with:
Logs
The Polkadot client has a number of log targets. The most interesting to users may be:
afg(Al's Finality Gadget - GRANDPA consensus)babetelemetrytxpoolusage
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:
errorwarninfodebugtrace
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 vizualizing node metrics tutorial which uses this endpoint.