Set up a Full Node
If you're building dapps or products on a Substrate-based chain like Polkadot, Kusama or a custom Substrate implementation, you probably want the ability to run a node-as-a-back-end. After all, it's always better to rely on your own infrastructure than on a third-party-hosted one in this brave new decentralized world.
This guide will show you how to connect to Polkadot network, but the same process applies to any other Substrate-based chain. First, let's clarify 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 all pending changes on top of it, and emits the events that are the result of these changes. Later, the state of the chain at block 1 is used in the same way to build the state of the chain at block 2, and so on. Once two 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 convenient to query the past state of the chain at any point in time. Finding out what an account's balance at a certain block was, or which extrinsics resulted in a certain state change are fast operations when using an archive node. However, an archive node takes up a lot of disk space - around Kusama's 12 millionth block this was around 660 GB.
The Paranodes website lists the database sizes of Polkadot and Kusama nodes in real-time.
Archive nodes are used by utilities that need past information - like block explorers, council scanners, discussion platforms like Polkassembly, and others. They need to be able to look at past on-chain data.
A full node prunes historical states: all finalized blocks' states older than a configurable number except the genesis block's state. This is 256 blocks from the last finalized one, by default. A node that is pruned this way requires much less space than an archive node.
A full node may eventually be able to rebuild every block's state with no additional information, and become an archive node, but at the time of writing, this is not implemented. If you need to query historical blocks' states past what you pruned, you need to purge your database and resync your node starting in archive mode. Alternatively you can use a backup or snapshot of a trusted source to avoid needing to sync from genesis with the network, and only need the states of blocks past that snapshot.
Full nodes allow you to read the current state of the chain and to submit and validate extrinsics directly 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 state, but does not store past blocks and so cannot read historical data without requesting it from a node that has it. Light nodes are useful for resource restricted devices. An interesting use-case of light nodes is a browser extension, which is a node in its own right, running the runtime in WASM format as well as a full or light node that is completely encapsulated in WASM and can be integrated into webapps: https://github.com/paritytech/smoldot#wasm-light-node
Substrate Connect provides a way to interact with substrate based blockchains in the browser without using an RPC server. It is a light node that runs entirely in Javascript. Substrate Connect uses a smoldot WASM light client to securely connect to the blockchain network without relying on specific 3rd parties. Substrate Connect is available as a browser extension on both Chrome and Firefox.
Setup Instructions
This is not recommended if you're a validator. Please see the secure validator setup if you are running validator.
Polkadot
as thedefault chain
Use the --chain
flag if you are following 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
Install Rust in your terminal by running:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Once Rust is installed, run the following command to clone and build the polkadot code:
git clone https://github.com/paritytech/polkadot polkadot
cd polkadot
./scripts/init.sh
cargo build --releaseStart your node:
./target/release/polkadot --name "Your Node's Name"
Find your node on Telemetry
Install WSL.
Install Ubuntu (same webpage).
Determine the latest version of the Polkadot binary.
Download the correct Polkadot binary within Ubuntu by running the following command. Replace
*VERSION*
with the tag of the latest version from the last step (e.g.v0.8.22
):curl -sL https://github.com/paritytech/polkadot/releases/download/*VERSION*/polkadot -o polkadot
Then, run the following:
sudo chmod +x polkadot
Start your node:
./target/release/polkadot --name "Your Node's Name"
Find your node on Telemetry
Determine the latest version of the Polkadot binary.
infoThe nature of pre-built binaries means that they may not work on your particular architecture or Linux distribution. If you see an error like
cannot execute binary file: Exec format error
it likely means the binary is not compatible with your system. You will either need to compile the source code or use Docker.Download the correct Polkadot binary within Ubuntu by running the following command. Replace
*VERSION*
with the tag of the latest version from the last step (e.g.v0.8.22
):curl -sL https://github.com/paritytech/polkadot/releases/download/*VERSION*/polkadot -o polkadot
Run the following:
sudo chmod +x polkadot
Run the following:
./target/release/polkadot --name "Your Node's Name"
Find your node on Telemetry
You can also install Polkadot from one of our package repositories.
Installation from the Debian or rpm repositories will create a systemd
service that can be used to
run a Polkadot node. The service is disabled by default, and can be started by running
systemctl start polkadot
on demand (use systemctl enable polkadot
to make it auto-start after
reboot). By default, it will run as the polkadot
user. Command-line flags passed to the binary can
be customized by editing /etc/default/polkadot
. This file will not be overwritten on updating
polkadot.
Debian-based (Debian, Ubuntu)
Currently supports Debian 10 (Buster) and Ubuntu 20.04 (Focal), and derivatives. Run the following
commands as the root
user.
# Import the [email protected] GPG key
gpg --recv-keys --keyserver hkps://keys.mailvelope.com 9D4B2B6EB8F97156D19669A9FF0812D491B96798
gpg --export 9D4B2B6EB8F97156D19669A9FF0812D491B96798 > /usr/share/keyrings/parity.gpg
# Add the Parity repository and update the package index
echo 'deb [signed-by=/usr/share/keyrings/parity.gpg] https://releases.parity.io/deb release main' > /etc/apt/sources.list.d/parity.list
apt update
# Install the `parity-keyring` package - This will ensure the GPG key
# used by APT remains up-to-date
apt install parity-keyring
# Install polkadot
apt install polkadot
If you don't want polkadot package to be automatically updated when you update packages on your server, you can issue the following command:
sudo apt-mark hold polkadot
RPM-based (Fedora, CentOS)
Currently supports Fedora 32 and CentOS 8, and derivatives.
# Install dnf-plugins-core (This might already be installed)
dnf install dnf-plugins-core
# Add the repository and enable it
dnf config-manager --add-repo https://releases.parity.io/rpm/polkadot.repo
dnf config-manager --set-enabled polkadot
# Install polkadot (You may have to confirm the import of the GPG key, which
# should have the following fingerprint: 9D4B2B6EB8F97156D19669A9FF0812D491B96798)
dnf install polkadot
If you choose to use a custom folder for the polkadot home by passing --base-path '/custom-path'
,
you will need to issue following command:
sudo mkdir /etc/systemd/system/polkadot.service.d
And create a new file inside this folder:
sudo -e /etc/systemd/system/polkadot.service.d/custom.conf
With the following content:
[Service]
ReadWritePaths=/custom-path
And finally issue a reload to have your modifications applied by systemd:
systemctl daemon-reload
Get Substrate
Follow instructions as outlined here - note that Windows users 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's master branch contains the latest Polkadot code.
git clone https://github.com/paritytech/polkadot polkadot
cd polkadot
./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
in
the example below):
git clone https://github.com/paritytech/polkadot polkadot
cd polkadot
git checkout tags/v0.8.3
./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 find out which flags you can use when running the node. For example, if
connecting to your node remotely, you'll probably want to use --ws-external
and
--rpc-cors all
.
The syncing process will take a while depending on your bandwidth, processing power, disk speed and RAM. 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 when using 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. When
validating, it defaults to archive mode. To keep 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 off
after the node is in sync.
Using Docker
Finally, you can use Docker to run your node in a container. Doing this is a bit more advanced so
it's best left up to those that either already have familiarity with docker, or have completed the
other set-up instructions in this guide. Be aware that when you run polkadot in docker the process
only listen on localhost by default. If you would like to connect to your node's services (rpc,
websockets, and prometheus) you need to ensure that you run you node with the --rpc-external
,
--ws-external
, and --prometheus-external
commands.
docker run -p 9944:9944 -p 9615:9615 parity/polkadot:v0.9.13 --name "calling_home_from_a_docker_container" --rpc-external --ws-external --prometheus-external