If you're building dApps or products on a Substrate-based chain like Polkadot, Kusama, or a customSubstrate implementation, you want the ability to run a node-as-a-back-end. After all, relying onyour infrastructure is always better than a third-party-hosted one in this brave new decentralizedworld.
This guide will show you how to connect to Polkadot network, but thesame process applies to any other Substrate-based chain. First, let'sclarify the term full node.
Types of Nodes
A blockchain's growth comes from a genesis block, extrinsics, and events.
When a validator seals block 1, it takes the blockchain's state at block 0. It then applies allpending changes on top of it and emits the events resulting from these changes. Later, the chain’sstate at block one is used the same way to build the chain’s state at block 2, and so on. Oncetwo-thirds of the validators agree on a specific block being valid, it is finalized.
An archive node keeps all the past blocks and their states. An archive node makes it convenientto query the past state of the chain at any point in time. Finding out what an account's balance ata particular block was or which extrinsics resulted in a specific state change are fast operationswhen using an archive node. However, an archive node takes up a lot of disk space - around Kusama's12 millionth block, this was around 660 GB.
tip
On the Paranodes or Stakeworldwebsites, you can find lists of the database sizes of Polkadot and Kusama nodes.
Archive nodes are used by utilities that need past information - like block explorers, councilscanners, discussion platforms like Polkassembly, and others. They needto be able to look at past on-chain data.
A full node prunes historical states: all finalized blocks' states older than a configurablenumber except the genesis block's state. This is 256 blocks from the last finalized one by default.A pruned node this way requires much less space than an archive node.
A full node could eventually rebuild every block's state without additional information and becomean archive node. This still needs to be implemented at the time of writing. If you need to queryhistorical blocks' states past what you pruned, you must purge your database and resync your node,starting in archive mode. Alternatively, you can use a backup or snapshot of a trusted source toavoid needing to sync from genesis with the network and only need the states of blocks past thatsnapshot.
Full nodes allow you to read the current state of the chain and to submit and validate extrinsicsdirectly on the network without relying on a centralized infrastructure provider.
Another type of node is a light node. A light node has only the runtime and the current statebut does not store past blocks and so cannot read historical data without requesting it from a nodethat has it. Light nodes are useful for resource-restricted devices. An interesting use-case oflight nodes is a browser extension, which is a node in its own right, running the runtime in WASMformat, as well as a full or light node that is completely encapsulated in WASM and can beintegrated into web apps: https://github.com/paritytech/smoldot#wasm-light-node.
Substrate Connect
Substrate Connect provides a way to interact withsubstrate-based blockchains in the browser without using an RPC server. It is a light node that runsentirely in Javascript. Substrate Connect uses asmoldot WASM light client to securely connect to theblockchain network without relying on specific 3rd parties. Substrate Connect is available on Chromeand Firefox as a browser extension.
Setup Instructions
This is not recommended if you're a validator. Please see thesecure validator setup if you are running validator.
Polkadot as thedefault chain
Use the --chain flag if you follow the setup instructions to setup a Kusama node. For example:
./target/release/polkadot --name "Your Node's Name" --chain kusama
- macOS
- Windows
- Linux (standalone)
- Linux (package)
Install Homebrew within the terminal by running:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"Then, run:
brew install openssl cmake llvm protobufInstall Rust by running:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | shAfter Rust is installed, update and add the nightly version:
# Ensure the current shell has cargo
source ~/.cargo/env
# Update the Rust toolchain
rustup default stable
rustup update
# Add the nightly and WebAssembly targets:
rustup update nightly
rustup target add wasm32-unknown-unknown --toolchain nightlyVerify your installation by running the following:
rustup show
# You should see output similar to:
active toolchain
----------------
stable-aarch64-apple-darwin (default)
rustc 1.68.1 (8460ca823 2023-03-20)rustup +nightly show
# You should see output similar to:
installed targets for active toolchain
--------------------------------------
aarch64-apple-darwin
wasm32-unknown-unknown
active toolchain
----------------
nightly-aarch64-apple-darwin (overridden by +toolchain on the command line)
rustc 1.71.0-nightly (9ecda8de8 2023-04-30)Once Rust is configured, run the following command to clone and build the Polkadot code:
git clone https://github.com/paritytech/polkadot-sdk polkadot-sdk
cd polkadot-sdk
./scripts/init.sh
cargo build --releaseStart your node:
./target/release/polkadot --name "Your Node's Name"Find your node on Telemetry
Get Substrate
Follow instructions as outlined here - note that Windowsusers will have their work cut out for them. It's better to use a virtual machine instead.
Test if the installation was successful by running cargo --version.
λ cargo --version
cargo 1.41.0 (626f0f40e 2019-12-03)
Clone and Build
The paritytech/polkadot repo'smaster branch contains the latest Polkadot code.
git clone https://github.com/paritytech/polkadot-sdk polkadot-sdk
cd polkadot-sdk
./scripts/init.sh
cargo build --release
Alternatively, if you wish to use a specific release, you can check out a specific tag (v0.8.3 inthe example below):
git clone https://github.com/paritytech/polkadot-sdk polkadot-sdk
cd polkadot-sdk
git checkout tags/polkadot-v1.9.0
./scripts/init.sh
cargo build --release
Run
The built binary will be in the target/release folder, called polkadot.
Polkadot:
./target/release/polkadot --name "Your Node's Name"
Use the --help flag to determine which flags you can use when running the node. For example, ifconnecting to your node remotely, you'll probably want to use --rpc-externaland --rpc-cors all.
The syncing process will take a while, depending on your capacity, processing power, disk speed andRAM. On a \$10 DigitalOcean droplet, the process can complete in some 36 hours.
Congratulations, you're now syncing with Polkadot. Keep in mind that the process is identical whenusing any other Substrate chain.
Running an Archive Node
When running as a simple sync node (above), only the state of the past 256 blocks will be kept. Itdefaults to archive mode when validating. To support the full state, use the--pruning flag:
Polkadot:
./target/release/polkadot --name "My node's name" --pruning archive
It is possible to almost quadruple synchronization speed by using an additional flag:--wasm-execution Compiled. Note that this uses much more CPU and RAM, so it should be turned offafter the node syncs.
Using Docker
Finally, you can use Docker to run your node in a container. Doing this is more advanced, so it'sbest left up to those already familiar with docker or who have completed the other set-upinstructions in this guide. Be aware that when you run polkadot in docker, the process only listenson localhost by default. If you would like to connect to your node's services (rpc, and prometheus)you need to ensure that you run you node with the --rpc-external, and --prometheus-externalcommands.
docker run -p 9944:9944 -p 9615:9615 parity/polkadot:v0.9.13 --name "calling_home_from_a_docker_container" --rpc-external --prometheus-external
