Running an RPC node

Running an RPC node for Chainflip is a relatively simple process. Our apt repository comes with pre-configured systemd services that can be used to start an RPC node on your server. If you're using Docker or Kubernetes, we have pre-built images available on Docker Hub.

Server Requirements

To run an RPC node, you need a server with the following minimum requirements:

CPU: 4 cores
RAM: 8 GB
Storage: 100 GB SSD (Increase accordingly if you need to store the state for more blocks)
Network: 1 Gbps
Operating System: Ubuntu 22.04 LTS (Jammy Jellyfish) or Ubuntu 24.04 LTS (Noble Numbat)

Prerequisites

It's a good practice to use a fresh node and upgrade all system dependencies before installing the validator software.

sudo apt update
sudo apt upgrade -y

Adding Chainflip's `apt` Repo

We distribute our binaries as debian packages through our apt repository. To install the packages, you need to add our repo to your apt sources list.

Use the following commands to add Chainflip's Mainnet apt repo to your node:

Download Chainflip Mainnet GPG key from the Ubuntu Key Server:

gpg --keyserver hkp://keyserver.ubuntu.com --recv-keys 4E506212E4EF4E0D3E37E568596FBDCACBBCDD37

Verify the key's authenticity:

gpg --export 4E506212E4EF4E0D3E37E568596FBDCACBBCDD37 | gpg --show-keys

Important: Make sure you see the following output from the terminal:

pub   rsa4096 2023-11-06 [SC]
      4E506212E4EF4E0D3E37E568596FBDCACBBCDD37
uid                      Chainflip Labs GmbH (Releaser Master Key) <security@chainflip.io>
sub   rsa4096 2023-11-06 [S] [expires: 2025-11-01]
sub   rsa4096 2023-11-06 [S] [expires: 2025-11-01]
sub   rsa4096 2023-11-06 [S] [expires: 2025-11-01]

Add Chainflip's Mainnet Repo to apt sources list:

Mainnet binaries were compiled on Ubuntu 22.04 LTS (Jammy Jellyfish) on an AMD processor. Running them on other versions of Ubuntu or other Debian-like distributions may require additional dependencies and configuration.

sudo mkdir -p /etc/apt/trusted.gpg.d
gpg --export 4E506212E4EF4E0D3E37E568596FBDCACBBCDD37 | sudo tee /etc/apt/trusted.gpg.d/chainflip-mainnet.gpg
echo "deb [arch=amd64 signed-by=/etc/apt/trusted.gpg.d/chainflip-mainnet.gpg] https://pkgs.chainflip.io/ubuntu/ jammy berghain" | sudo tee /etc/apt/sources.list.d/chainflip-berghain-mainnet.list

Installing The Packages

To install, run the following commands:

sudo apt update
sudo apt install -y chainflip-node

Using Chaindata Snapshots

To significantly reduce sync time, download and use the latest chaindata snapshot. This allows your RPC node to start serving requests much faster.

mkdir -p /etc/chainflip/chaindata/chains/Chainflip-Berghain/
 
wget https://snapshots.chainflip.io/berghain/cf_chaindata_pruned_paritydb.tar.{gz.sha512.asc,gz.sha512,gz}
 
# Verify the snapshot (Optional but recommended)
gpg --keyserver hkp://keyserver.ubuntu.com --recv-keys 52535A03E3E0D0F29920EF94927F07FF64652243
 
gpg --verify cf_chaindata_pruned_paritydb.tar.gz.sha512.asc cf_chaindata_pruned_paritydb.tar.gz.sha512
 
sha512sum -c cf_chaindata_pruned_paritydb.tar.gz.sha512
 
tar -xzf ./cf_chaindata_pruned_paritydb.tar.gz -C /etc/chainflip/chaindata/chains/Chainflip-Berghain/
 
rm -f ./cf_chaindata_pruned_paritydb.tar.{gz.sha512.asc,gz.sha512,gz}

After downloading the snapshot, create a systemd override file to configure the node to use the snapshot data:

sudo mkdir -p /etc/systemd/system/chainflip-rpc-node.service.d && \
sudo tee /etc/systemd/system/chainflip-rpc-node.service.d/override.conf > /dev/null <<EOF
[Service]
ExecStart=
ExecStart=/usr/bin/chainflip-node \\
  --base-path=/etc/chainflip/chaindata \\
  --chain=/etc/chainflip/berghain.chainspec.json \\
  --rpc-cors=all \\
  --rpc-methods=unsafe \\
  --unsafe-rpc-external \\
  --max-runtime-instances=32 \\
  --database=paritydb \\
  --sync=full \\
  --blocks-pruning=300 \\
  --pruning=300
EOF
 
sudo systemctl daemon-reload

Snapshots are updated every 6 hours starting at 00:00 UTC. The snapshot holds the state and blocks of the most recent 300 blocks. The size of the snapshot is approximately 50GB. You can override the snapshot to use a different number of blocks by changing the --blocks-pruning and --pruning parameters in the systemd override file.

Docker Installation

If you have done the APT Installation above, you don't need to follow the Docker Installation below.

If you are planning to run a validator using a container orchestration system like Kubernetes you can use our pre-built images on Docker Hub (opens in a new tab).

docker pull chainfliplabs/chainflip-node:berghain-1.10.0

Starting up the node in Docker

For faster startup, first download the latest chaindata snapshot as explained in the Using Chaindata Snapshots section above.

Below is a sample docker-compose.yml file to start the node in Docker which works out of the box. Simply copy the contents below to a file named docker-compose.yml and run docker-compose up -d to start the node.

services:
  node:
    image: chainfliplabs/chainflip-node:berghain-1.10.0
    container_name: chainflip-node
    pull_policy: always
    stop_grace_period: 5s
    stop_signal: SIGINT
    platform: linux/amd64
    restart: unless-stopped
    user: root
    ports:
      - "127.0.0.1:9944:9944"
    volumes:
      - ./chainflip/chaindata:/etc/chainflip/chaindata
    entrypoint:
      - /usr/local/bin/chainflip-node
    command:
      - --base-path=/etc/chainflip/chaindata
      - --chain=/etc/chainflip/berghain.chainspec.json
      - --rpc-cors=all
      - --rpc-methods=unsafe
      - --unsafe-rpc-external
      - --database=paritydb
      - --sync=full
      - --blocks-pruning=300
      - --pruning=300

To check the logs, run:

docker logs -f chainflip-node

NOTE: The configuration above uses --sync=full with snapshot data for optimal performance. For archive nodes, see Setting up an Archive Node.

Reverse Proxy Configuration

If you are running the node on a server and want to expose it to the internet, you can use a reverse proxy like Nginx or Caddy to route traffic to the node.

You will need to generate an SSL certificate for your domain and configure the reverse proxy to route traffic to the node.

Below is an example configuration for Nginx:

server {
    listen 443 ssl;
    server_name rpc.chainflip.yourdomain.com;
 
    ssl_certificate /etc/nginx/ssl/server.crt; # Path to your SSL certificate
    ssl_certificate_key /etc/nginx/ssl/server.key; # Path to your SSL certificate key
 
    ssl_protocols TLSv1.2 TLSv1.3; # Recommended TLS protocols
    ssl_prefer_server_ciphers on;
    ssl_dhparam /etc/nginx/ssl/dhparam.pem; # Diffie-Hellman parameter for DHE ciphersuites, recommended 2048 bits
    ssl_ciphers 'ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256';
 
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;
 
    location / {
        proxy_pass http://localhost:9944; # Proxy pass to local backend on port 9944
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Setting up an Archive Node

If you require historical data, you can set up an archive node by modifying the configuration to use archive mode. This will sync the chain from the genesis block and store all historical data. We also have a pre-configured archive node package available in our apt repository. To install and run an archive node, run the following commands:

Server Requirements

To run an RPC node, you need a server with the following minimum requirements:

CPU: 4 cores
RAM: 8 GB
Storage: 2TB SSD (Current growth rate is around 100GB per month)
Network: 1 Gbps
Operating System: Ubuntu 22.04 LTS (Jammy Jellyfish) or Ubuntu 24.04 LTS (Noble Numbat)

Installing The Packages

If you've already downloaded the chainflip-node package, you can run the archive node package by running:

sudo systemctl enable chainflip-archive-node
sudo systemctl start chainflip-archive-node
sudo systemctl status chainflip-archive-node

Bear in mind that an archive node will take significantly longer to sync compared to an RPC node. You can check the logs by running:

sudo journalctl -u chainflip-archive-node -f

You should see the following in the logs:

Apr 09 12:20:47 ubuntu-s-2vcpu-2gb-amd-fra1-01 chainflip-node[10677]: 2024-04-09 12:20:47 ⚙️  Syncing, target=#2123662 (9 peers), best: #1303 (0xb758…3296), finalized #1024 (0x7250…1fc2), ⬇ 665.0kiB/s ⬆ 24.4kiB/s

Default filepaths & ports Modifying your systemd config

Running an RPC node

Server Requirements

Prerequisites

Adding Chainflip's apt Repo

Installing The Packages

Using Chaindata Snapshots

Docker Installation

Starting up the node in Docker

Reverse Proxy Configuration

Setting up an Archive Node

Server Requirements

Installing The Packages

Adding Chainflip's `apt` Repo