Rivellum

Rivellum Portal

Checking...
testnet

Node Setup Guide

This guide covers everything you need to run a Rivellum validator node in production, including hardware requirements, installation, configuration, and monitoring.

Hardware Requirements

Minimum Specifications (Testnet)

  • CPU: 4 cores @ 2.5 GHz
  • RAM: 16 GB
  • Storage: 500 GB SSD
  • Network: 100 Mbps bandwidth, <100ms latency

Recommended Specifications (Mainnet)

  • CPU: 16+ cores @ 3.0 GHz (AMD Ryzen 9 or Intel Xeon)
  • RAM: 64 GB DDR4
  • Storage: 2 TB NVMe SSD (RAID 1 for redundancy)
  • Network: 1 Gbps bandwidth, <50ms latency, static IP

Cloud Provider Options

  • AWS: c6i.4xlarge or larger
  • GCP: n2-standard-16 or larger
  • Azure: Standard_D16s_v3 or larger
  • Hetzner: AX101 dedicated server

Operating System Setup

Supported Platforms

  • Ubuntu 22.04 LTS (recommended)
  • Debian 12
  • RHEL 9 / Rocky Linux 9
  • Windows Server 2022 (limited support)

System Configuration

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

# Install dependencies
sudo apt install -y build-essential pkg-config libssl-dev curl git

# Install Rust (required for building from source)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
rustup default stable

# Install systemd service dependencies
sudo apt install -y supervisor

Firewall Configuration

# Allow SSH (change 22 if using non-standard port)
sudo ufw allow 22/tcp

# Allow P2P networking (default: 9000)
sudo ufw allow 9000/tcp

# Allow RPC (default: 8545) - only if exposing publicly
sudo ufw allow 8545/tcp

# Allow metrics (default: 9090) - restrict to monitoring IPs
sudo ufw allow from <monitoring_ip> to any port 9090

# Enable firewall
sudo ufw enable

Installation

Option 1: Pre-Built Binaries (Recommended)

# Download latest release
curl -LO https://github.com/rivellum/rivellum/releases/latest/download/rivellum-node-linux-amd64.tar.gz

# Verify checksum
curl -LO https://github.com/rivellum/rivellum/releases/latest/download/SHA256SUMS
sha256sum -c SHA256SUMS 2>&1 | grep rivellum-node-linux-amd64.tar.gz

# Extract and install
tar -xzf rivellum-node-linux-amd64.tar.gz
sudo mv rivellum-node /usr/local/bin/
sudo chmod +x /usr/local/bin/rivellum-node

# Verify installation
rivellum-node --version

Option 2: Build from Source

# Clone repository
git clone https://github.com/rivellum/rivellum.git
cd rivellum

# Checkout latest stable release
git checkout v0.5.0

# Build in release mode (takes 5-10 minutes)
cargo build --release --package rivellum-node

# Install binary
sudo cp target/release/rivellum-node /usr/local/bin/
sudo chmod +x /usr/local/bin/rivellum-node

Option 3: Docker (Experimental)

# Pull official image
docker pull rivellum/node:latest

# Run container
docker run -d \
  --name rivellum-node \
  -v /opt/rivellum/data:/data \
  -v /opt/rivellum/config:/config \
  -p 9000:9000 \
  -p 8545:8545 \
  rivellum/node:latest \
  --config /config/mainnet.toml

Configuration

Directory Structure

Create required directories:

sudo mkdir -p /opt/rivellum/{data,config,logs,backups}
sudo chown -R $USER:$USER /opt/rivellum

Base Configuration

Create /opt/rivellum/config/mainnet.toml:

[node]
# Node identity (generated on first run if not provided)
node_id = ""
data_dir = "/opt/rivellum/data"
log_level = "info"

[network]
# P2P networking
listen_addr = "/ip4/0.0.0.0/tcp/9000"
bootstrap_peers = [
    "/ip4/seed1.rivellum.io/tcp/9000/p2p/12D3KooWA...",
    "/ip4/seed2.rivellum.io/tcp/9000/p2p/12D3KooWB...",
    "/ip4/seed3.rivellum.io/tcp/9000/p2p/12D3KooWC...",
]
max_peers = 50

[rpc]
enabled = true
listen_addr = "127.0.0.1:8545"  # Change to 0.0.0.0 to expose publicly
cors_origins = ["*"]  # Restrict in production
max_connections = 100

[execution]
num_shards = 16
batch_size = 1000
batch_timeout_ms = 2000
max_intent_size_bytes = 1048576  # 1 MB

[consensus]
mode = "validator"  # or "full_node" if not validating
validator_key_path = "/opt/rivellum/config/validator.key"
committee_size = 100
vote_timeout_ms = 3000

[zk]
mode = "real"  # Use real ZK proofs
backend = "groth16"  # or "plonk"
setup_path = "/opt/rivellum/data/zk-setup"

[pouw]
enabled = true
prover_timeout_ms = 30000
reputation_threshold = 0.8

[security]
rate_limit_enabled = true
max_intents_per_account_per_second = 10
max_intents_per_ip_per_second = 50
anomaly_detection_enabled = true

[storage]
backend = "rocksdb"  # or "postgres" for archival nodes
path = "/opt/rivellum/data/db"
cache_size_mb = 4096
enable_pruning = true
pruning_interval_hours = 24
keep_last_n_epochs = 7

[metrics]
enabled = true
listen_addr = "127.0.0.1:9090"
prometheus_exporter = true

[backup]
enabled = true
schedule = "0 2 * * *"  # Daily at 2 AM
retention_days = 30
destination = "/opt/rivellum/backups"
compression = "zstd"

Generate Validator Keys

# Generate new validator keypair
rivellum-node keygen --output /opt/rivellum/config/validator.key

# Important: Backup this file securely! Loss = loss of validator status
sudo chmod 600 /opt/rivellum/config/validator.key

# Get your validator address (needed for staking)
rivellum-node keyinfo --key /opt/rivellum/config/validator.key

Output:

Validator Public Key: 0x04a3b5c2...
Validator Address: 0x1a2b3c4d...
Node ID: 12D3KooWXYZ...

Testnet vs. Mainnet

Testnet Configuration (testnet.toml):

  • Use testnet bootstrap peers
  • Lower stake requirements
  • Mock ZK proofs acceptable
  • Faster block times (testing)

Mainnet Configuration (mainnet.toml):

  • Production bootstrap peers
  • Full stake required (1,000,000 RIVL)
  • Real ZK proofs mandatory
  • Optimized for stability over speed

Running the Node

Interactive Mode (Testing)

rivellum-node --config /opt/rivellum/config/mainnet.toml

Press Ctrl+C to stop.

Systemd Service (Production)

Create /etc/systemd/system/rivellum-node.service:

[Unit]
Description=Rivellum Node
After=network.target
Wants=network-online.target

[Service]
Type=simple
User=rivellum
Group=rivellum
WorkingDirectory=/opt/rivellum
ExecStart=/usr/local/bin/rivellum-node --config /opt/rivellum/config/mainnet.toml
Restart=on-failure
RestartSec=10
LimitNOFILE=65535
StandardOutput=journal
StandardError=journal

# Security hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/opt/rivellum/data /opt/rivellum/logs /opt/rivellum/backups

[Install]
WantedBy=multi-user.target

Create dedicated user:

sudo useradd -r -s /bin/false -m -d /opt/rivellum rivellum
sudo chown -R rivellum:rivellum /opt/rivellum

Enable and start service:

sudo systemctl daemon-reload
sudo systemctl enable rivellum-node
sudo systemctl start rivellum-node

# Check status
sudo systemctl status rivellum-node

# View logs
sudo journalctl -u rivellum-node -f

Staking (Validator Nodes Only)

To participate in consensus, you must stake tokens:

Minimum Stake Requirements

  • Testnet: 10,000 RIVL
  • Mainnet: 1,000,000 RIVL

Staking Process

  1. Acquire RIVL tokens (buy, earn, or receive from faucet on testnet)

  2. Submit staking transaction:

rivellum-node stake \
  --amount 1000000 \
  --validator-key /opt/rivellum/config/validator.key \
  --rpc http://localhost:8545

  1. Wait for activation (typically 1 epoch = ~6 hours)

  2. Verify validator status:

curl http://localhost:8545/validator/status | jq

Expected response:

{
  "address": "0x1a2b3c4d...",
  "stake": "1000000",
  "status": "active",
  "reputation": 1.0,
  "uptime_percentage": 99.8,
  "committee_participation": 0.95
}

Unstaking

# Initiate unstaking (subject to unbonding period)
rivellum-node unstake \
  --validator-key /opt/rivellum/config/validator.key \
  --rpc http://localhost:8545

# Unbonding period: 14 days on mainnet, 1 day on testnet
# After unbonding, claim tokens:
rivellum-node claim-unstaked \
  --validator-key /opt/rivellum/config/validator.key \
  --rpc http://localhost:8545

Monitoring & Maintenance

Health Checks

# Node status
curl http://localhost:8545/health

# Peer count
curl http://localhost:8545/peers | jq '.count'

# Latest block
curl http://localhost:8545/block/latest | jq

# Sync status
curl http://localhost:8545/sync | jq

Prometheus Metrics

Metrics available at http://localhost:9090/metrics:

  • rivellum_node_height: Current block height
  • rivellum_intent_mempool_size: Pending intents
  • rivellum_batch_execution_time_ms: Execution latency
  • rivellum_consensus_votes_total: Votes cast
  • rivellum_network_peers_total: Connected peers
  • rivellum_storage_size_bytes: Database size

Grafana Dashboard

Import dashboard from monitoring/grafana/rivellum-node.json:

  1. Install Grafana:
sudo apt install -y grafana
sudo systemctl enable grafana-server
sudo systemctl start grafana-server

  1. Configure Prometheus data source (http://localhost:9090)

  2. Import dashboard (ID: 17485)

Log Management

# Real-time logs
sudo journalctl -u rivellum-node -f

# Last 100 lines
sudo journalctl -u rivellum-node -n 100

# Logs from last hour
sudo journalctl -u rivellum-node --since "1 hour ago"

# Export logs
sudo journalctl -u rivellum-node --since "2024-01-01" > node-logs.txt

Automated Backups

Backups are configured in mainnet.toml:

[backup]
enabled = true
schedule = "0 2 * * *"  # Daily at 2 AM UTC
retention_days = 30
destination = "/opt/rivellum/backups"

Manual backup:

rivellum-node backup create \
  --config /opt/rivellum/config/mainnet.toml \
  --output /opt/rivellum/backups/manual-backup.tar.zst

Restore from backup:

# Stop node first
sudo systemctl stop rivellum-node

# Restore
rivellum-node backup restore \
  --backup /opt/rivellum/backups/backup-2024-01-15.tar.zst \
  --data-dir /opt/rivellum/data

# Restart node
sudo systemctl start rivellum-node

See Disaster Recovery for detailed backup procedures.

Upgrades

Zero-Downtime Upgrades (Recommended)

  1. Download new binary:
curl -LO https://github.com/rivellum/rivellum/releases/download/v0.6.0/rivellum-node-linux-amd64.tar.gz
tar -xzf rivellum-node-linux-amd64.tar.gz
  1. Verify compatibility:
./rivellum-node --version
./rivellum-node config-check --config /opt/rivellum/config/mainnet.toml
  1. Hot-swap binary:
sudo systemctl stop rivellum-node
sudo mv /usr/local/bin/rivellum-node /usr/local/bin/rivellum-node.old
sudo mv rivellum-node /usr/local/bin/
sudo chmod +x /usr/local/bin/rivellum-node
sudo systemctl start rivellum-node
  1. Monitor logs for successful restart:
sudo journalctl -u rivellum-node -f

Rolling Upgrade (Multi-Node Clusters)

Upgrade followers first, then leader:

# 1. Upgrade follower1, wait for sync
# 2. Upgrade follower2, wait for sync  
# 3. Upgrade leader (triggers re-election)

Troubleshooting

Node Won't Start

Error: failed to load config

# Validate TOML syntax
rivellum-node config-check --config /opt/rivellum/config/mainnet.toml

Error: address already in use

# Check if another instance is running
sudo lsof -i :9000
sudo lsof -i :8545

# Kill if needed
sudo systemctl stop rivellum-node

Error: permission denied

# Fix ownership
sudo chown -R rivellum:rivellum /opt/rivellum

Sync Issues

Symptom: Node stuck at old block height

# Check peer count (need at least 3)
curl http://localhost:8545/peers | jq '.count'

# Check if bootstrap peers are reachable
nc -zv seed1.rivellum.io 9000

# Force resync from genesis
sudo systemctl stop rivellum-node
rm -rf /opt/rivellum/data/db
sudo systemctl start rivellum-node

High Memory Usage

# Check database size
du -sh /opt/rivellum/data/db

# Enable pruning (in config)
[storage]
enable_pruning = true
pruning_interval_hours = 24

# Manually trigger pruning
rivellum-node prune --config /opt/rivellum/config/mainnet.toml

Network Connectivity

# Test bootstrap peers
for peer in seed1 seed2 seed3; do
  ping -c 3 $peer.rivellum.io
  nc -zv $peer.rivellum.io 9000
done

# Check NAT/firewall
sudo ufw status
curl http://localhost:8545/network-info | jq

Security Best Practices

  1. Key Management:

    • Store validator.key on encrypted filesystem
    • Backup keys offline (cold storage)
    • Never expose private keys in logs or environment variables

  2. Network Security:

    • Use firewall (ufw/iptables) to restrict access
    • Disable RPC public access unless necessary
    • Use SSH key authentication only (disable password auth)

  3. System Hardening:

    • Keep OS and dependencies updated
    • Run node as non-root user
    • Enable SELinux/AppArmor
    • Disable unnecessary services

  4. Monitoring:

    • Set up alerts for downtime, high CPU, low disk
    • Monitor validator reputation score
    • Track missed votes/blocks

  5. Disaster Recovery:

    • Regular automated backups (daily)
    • Test restore procedures quarterly
    • Keep offline backups in geographically separate locations

Getting Help

Need more details? See: