Skip to main content

Set Up a Node

There are several ways to build and run a collator node. Here, we show both how to use a Docker image and how to compile the source code directly from our chain repository.

There are currently two different runtimes (i.e., two different parachain environments) that a KILT collator can be part of:

  • Spiritnet: the official public network, which contains only stable and thoroughly-tested features.
  • Peregrine: the public test network whose runtime is as close to that of Spiritnet as possible. It can be used to try things out before executing them on the production Spiritnet chain, which involves spending tokens that have real monetary value.

Each runtime has its own benchmark measurements.

info

The remainder of this guide explaining how to set up and run a collator is mainly for the official Spiritnet parachain. However, we recommend trying out the setup on our Peregrine testnet first. Hence, at each step where it is applicable, we indicate what differs between the Peregrine and Spiritnet configuration for the collator node to join either network.

Configuration​

Running a collator requires a few configuration parameters. Some of the parameters might appear twice in the command to start the collator, because a parachain collator actually runs two blockchains. The parameters that are listed before the -- are related to the parachain node itself (the KILT blockchain), whereas the parameters following the -- are related to the Relay Chain, e.g., Kusama or Polkadot.

The following is a description of some of the parameters that can be set when spinning up a parachain collator node.

RPC and WS Endpoints​

As a collator, you need to link your session keys to your collator account. These session keys can be generated by calling an RPC endpoint that the collator optionally exposes. Exposing the RPC endpoint can be done using the following parameters:

--rpc-port=9944
--rpc-cors=all
--rpc-methods=unsafe
--unsafe-rpc-external // ONLY for Docker-based setups

Exposing the RPC endpoint of a collator does not imply that it becomes accessible via the PolkadotJS Apps interface, because this requires a WebSocket to connect to the node.

By default, the WebSocket port used by the node is configured to be 9944, but it can be changed by specifying a different value with --rpc-port=<rpc_port>.

Connecting from a remote host to either the collator RPC endpoint or WS endpoint requires explicitly exposing the endpoint to the public with the --rpc-external option.

danger

Be aware that it is highly discouraged to publicly expose an RPC endpoint, especially if it allows the execution of unsafe RPC calls! You should be the only one able to call the RPC endpoint. For a secure setup, follow the instructions in the previous section about generating the session keys.

WASM Runtime Execution​

A KILT collator node should use the --execution=wasm parameter for both the Relay Chain and parachain collation. The alternative to WASM runtime execution is native runtime execution, which might be faster but can, in some cases, deviate from the WASM execution logic and result in a different state. When this happens, the collator node will crash and will stop synchronizing with the network and stop producing blocks. Since the WASM runtime logic is part of the blockchain state itself and hence represents the single source of truth, all nodes should execute the WASM version of the runtime logic.

Specify the Right Chainspec​

The --chain parameter indicates which blockchain the KILT collator node will join. This parameter must be specified for both the parachain and the Relay Chain, since both chains are, as a matter of fact, separate blockchains. The KILT parachain accepts an additional parameter to select the environment to use for the WASM runtime execution. This can either be peregrine or spiritnet.

Hence, to start a collator node for the Spiritnet network, the parameter would be --chain=spiritnet. Unfortunately, there is no hardcoded chain spec for the Peregrine network, so the full path of the chainspec file must be provided --chain=/node/dev-specs/kilt-parachain/peregrine-kilt.json. Please refer to the KILT node repository or the Docker image for more information.

Specify the Blockchain Storage Path​

The --base-path parameter specifies where all the persistent files must be stored. By default, the session keys will also be stored in the base path, but we recommend separating them from the other files. This makes sure that the keyfiles are not accidentally lost or published when the blockchain database is either backed up or restored. You can configure where to store the session keys using the --keystore-path option. Since the collator will collate only for the parachain, there is no need to add this to the relaychain part of the command.

Obtain the Node Executable​

Simply pull the latest Docker image:

docker pull kiltprotocol/kilt-node:latest

Start the Node​

Please select your target network:

To start the Spiritnet collator container, run:

docker run -p 127.0.0.1:9944:9944 -p 30333:30333 -p 30334:30334 \
  -v ~/data:/data kiltprotocol/kilt-node:latest \
  --chain=spiritnet \
  --runtime=spiritnet \
  --rpc-port=9944 \
  --rpc-cors=all \
  --rpc-methods=unsafe \
  --unsafe-rpc-external \
  --name="name of collator" \
  --execution=wasm \
  --listen-addr=/ip4/0.0.0.0/tcp/30333 \
  --base-path=/data/parachain \
  --keystore-path=/data/keystore \
  --collator \
  -- \
  --chain=polkadot \
  --listen-addr=/ip4/0.0.0.0/tcp/30334 \
  --base-path=/data/relay \
  --execution=wasm

In either case, if the node needs to be reachable via PolkadotJS Apps, the --rpc-external flag must be added to the collator options, before the -- divider, and the WS port must be exposed from the container with an additional -p 9944:9944 parameter. Make sure that you only expose the websocket port publicly if you are not running a collator.

In addition to the websocket, you need to expose the ports for p2p connections. In the the command above these are 30333 for the parachain and 30334 for the relaychain. Make sure you configure your firewall in a way that allows incoming and outgoing connections to these ports.

The Docker command will map the database files for the Relay Chain and parachain as well as the keystore directory to ~/data on the host system using the flag -v $HOME/data:/data. That way the blockchain database files are not lost when and if the Docker container is removed and can be mounted back on the next containers.

The Docker container runs as an user with id 1000 and will try to access the mapped volume and the files it contains. If the files are not owned by a user with id 1000, this will result in an error. If that is the case, run sudo chown -R 1000:1000 $HOME/data to give the container access.

Sync the Blockchain State​

Before a collator can author blocks, the node needs to fully sync up with both the parachain and the Relay Chain. Depending on the size of the blockchain states, it may take a number of hours to few days for the node to catch up. More details can be found on the Polkadot network docs.

Example of node sync:
2021-06-17 02:34:34 🔍 Discovered new external address for our node: /ip4/100.102.231.64/tcp/30333/ws/p2p/12D3KooWLE7ivpuXJQpFVP4fuuutAqEsk8nrNEpuR3tddqnXgLPB
2021-06-17 02:34:36 ⚙️  Syncing 409.2 bps, target=#8062689 (5 peers), best: #3477 (0x63ad…e046), finalized #3072 (0x0e4c…f587), ⬇ 153.2kiB/s ⬆ 12.9kiB/s
2021-06-17 02:34:37 🔍 Discovered new external address for our node: /ip4/100.111.175.0/tcp/30333/ws/p2p/12D3KooWLE7ivpuXJQpFVP4fuuutAqEsk8nrNEpuR3tddqnXgLPB
2021-06-17 02:34:38 🔍 Discovered new external address for our node: /ip4/100.100.176.0/tcp/30333/ws/p2p/12D3KooWLE7ivpuXJQpFVP4fuuutAqEsk8nrNEpuR3tddqnXgLPB
2021-06-17 02:34:41 ⚙️  Syncing 386.2 bps, target=#8062690 (7 peers), best: #5409 (0x1d76…8c3d), finalized #5121 (0x8ad1…b6dc), ⬇ 96.1kiB/s ⬆ 10.9kiB/s
2021-06-17 02:34:46 ⚙️  Syncing 394.8 bps, target=#8062691 (11 peers), best: #7383 (0x0689…6f1e), finalized #7168 (0x72a9…8d8c), ⬇ 352.9kiB/s ⬆ 5.1kiB/s
2021-06-17 02:34:51 ⚙️  Syncing 347.0 bps, target=#8062692 (12 peers), best: #9118 (0x66fc…cce3), finalized #8704 (0x14c9…705e), ⬇ 62.7kiB/s ⬆ 1.7kiB/s