Skip to main content

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 want the ability to run a node-as-a-back-end. After all, relying on your infrastructure is always better than 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 resulting from these changes. Later, the chain’s state at block one is used the same way to build the chain’s state 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 particular block was or which extrinsics resulted in a specific 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.

tip

On the Paranodes or Stakeworld websites, 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, 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 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 become an archive node. This still needs to be implemented at the time of writing. If you need to query historical 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 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 web apps: https://github.com/paritytech/smoldot#wasm-light-node.

Substrate Connect

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 on Chrome and Firefox as a browser extension.

Setup Instructions​

This is not recommended if you're a validator. Please see the secure validator setup if you are running validator.

The bash commands that are provided to run against your node use Polkadot as the

default 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

  • 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 protobuf

  • Install Rust by running:

    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

  • After 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 nightly

  • Verify 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 --release

  • Start your node:

    ./target/release/polkadot --name "Your Node's Name"

  • Find your node on Telemetry

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-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 in the 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, if connecting to your node remotely, you'll probably want to use --rpc-external and --rpc-cors all.

The syncing process will take a while, depending on your capacity, 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. It defaults 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 off after the node syncs.

Using Docker​

Finally, you can use Docker to run your node in a container. Doing this is more advanced, so it's best left up to those already familiar with docker or who have completed the other set-up instructions in this guide. Be aware that when you run polkadot in docker, the process only listens on 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-external commands.

docker run -p 9944:9944 -p 9615:9615 parity/polkadot:v0.9.13 --name "calling_home_from_a_docker_container" --rpc-external --prometheus-external