ChainOS Node Setup Guide

Before You Begin

This guide will walk you through the process of setting up a ChainOS node. Make sure you meet the hardware requirements before proceeding.

Hardware Requirements

Running a ChainOS node requires specific hardware specifications to ensure optimal performance:

Minimum Requirements

  • CPU: 4 cores / 8 threads (3.0+ GHz)
  • RAM: 16GB DDR4
  • Storage: 500GB NVMe SSD
  • Network: 100 Mbps symmetric connection

Recommended Specifications

  • CPU: 8 cores / 16 threads (3.5+ GHz)
  • RAM: 32GB DDR4
  • Storage: 1TB NVMe SSD
  • Network: 1 Gbps symmetric connection

These specifications ensure your node can handle the network load and maintain synchronization with the blockchain.

Installation

Follow these steps to install and configure your ChainOS node:

1. Prepare the Environment

Update your system and install the required dependencies:

# Update system packages
sudo apt update && sudo apt upgrade -y

# Install dependencies
sudo apt install -y build-essential curl git jq lz4 unzip

2. Get ChainOS

Clone the ChainOS repository from GitHub:

# Clone the repository
git clone https://github.com/o-c-foundation/ChainOS--Mainnet.git
cd ChainOS--Mainnet

3. Automated Setup

ChainOS provides a convenient setup script that automates most of the installation process:

# Make the script executable
chmod +x node-setup.sh

# Run the installer
./node-setup.sh

The setup script will guide you through the following steps:

Important Note

Make sure to follow the prompts in the setup script carefully. You'll need to provide a unique moniker for your node and decide on configuration options.

4. Manual Setup (Alternative)

If you prefer to set up your node manually or need more control over the configuration, follow these steps:

Initialize the Node

# Initialize the node with your chosen moniker
chainosd init "your-node-name" --chain-id chainos-1

Download Genesis File

# Download the genesis file
curl -s https://chainos.network/genesis.json > ~/.chainosd/config/genesis.json

Configure Persistent Peers

# Edit the config.toml file
nano ~/.chainosd/config/config.toml

# Add the following persistent peers:
# persistent_peers = "2b89c755963a03a2a2c846d5efb97c06e6d2cdfe@chainos.network:26656"

Configure Pruning (Optional)

# Edit the app.toml file
nano ~/.chainosd/config/app.toml

# Set pruning options:
# pruning = "custom"
# pruning-keep-recent = "100"
# pruning-keep-every = "0"
# pruning-interval = "10"

Create Systemd Service

# Create a systemd service file
sudo nano /etc/systemd/system/chainosd.service

# Add the following content:
[Unit]
Description=ChainOS Node
After=network-online.target

[Service]
User=$USER
ExecStart=$(which chainosd) start
Restart=always
RestartSec=3
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

# Enable and start the service
sudo systemctl daemon-reload
sudo systemctl enable chainosd
sudo systemctl start chainosd

Node Operation

Once your node is set up, you can use these commands to manage it:

Check Node Status

# Check node status
chainosd status --node tcp://localhost:26657

# Check sync status
curl -s localhost:26657/status | jq '.result.sync_info'

View Logs

# View logs if using systemd
sudo journalctl -u chainosd -f --output cat

# View logs if running manually
tail -f ~/.chainosd/logs/chainos.log

Stop and Restart Node

# Stop the node
sudo systemctl stop chainosd

# Start the node
sudo systemctl start chainosd

# Restart the node
sudo systemctl restart chainosd

Sync Options

ChainOS offers different synchronization methods to get your node up to speed with the network:

Default Sync

By default, your node will sync from the genesis block, which can take several hours depending on your hardware.

State Sync (Faster)

State sync allows you to quickly sync your node by downloading a recent snapshot of the application state:

# Edit config.toml
nano ~/.chainosd/config/config.toml

# Enable state sync and configure it:
[statesync]
enable = true
rpc_servers = "chainos.network:26657,chainos-backup.network:26657"
trust_height = 3500000  # Replace with a recent block height
trust_hash = "XXXXXX"   # Replace with the hash of the block at trust_height
trust_period = "168h"   # One week

Getting Trust Hash

You can get the trust hash by running:

curl -s "chainos.network:26657/block?height=3500000" | jq -r '.result.block_id.hash'

Replace 3500000 with a recent block height.

Troubleshooting

Here are some common issues and their solutions:

Node Won't Start

Symptoms: The node fails to start or crashes immediately.

Solutions:

  • Check logs for specific errors: sudo journalctl -u chainosd -n 100
  • Verify you have the correct genesis file
  • Ensure your system meets the minimum hardware requirements
  • Check disk space: df -h

Node Not Syncing

Symptoms: The node starts but doesn't sync with the network.

Solutions:

  • Verify you have configured persistent peers correctly
  • Check your internet connection
  • Ensure ports are open (default: 26656 for p2p)
  • Try adding more peers from the network

Out of Memory Errors

Symptoms: The node crashes with out of memory errors.

Solutions:

  • Increase your server's RAM
  • Configure pruning to reduce state size
  • Add swap space (not recommended for production nodes)

Next Steps

Once your node is up and running, you might want to:

Need Help?

If you encounter any issues not covered in this guide, join our Discord community for support from the team and other node operators.