Skip to Content
Tokio Upgrade Docs are released! 🎉
Tokio V3🚀 Splendor External Validator Node Setup Guide (Mainnet)

🚀 Splendor External Validator Node Setup Guide (Mainnet)

This guide helps you install and run a Splendor validator node on Linux, macOS, or Windows using Docker. It is designed to assist both beginners and experienced users through every step needed to launch a node on the mainnet.

🔧 Prerequisites

You need Docker and Docker Compose installed on your machine.

🪟 Windows

🍎 macOS

🐧 Linux (Ubuntu/Debian-based)

Run the following commands:

sudo apt update && sudo apt upgrade -y
sudo apt install -y docker.io docker-compose
sudo systemctl enable --now docker

Add your user to the docker group (IMPORTANT: You must logout and login again after this):

sudo usermod -aG docker $USER

⚠️ CRITICAL: After running the above command, you MUST logout and login again for the Docker permissions to take effect.

✅ Verify installation

docker --version
docker-compose --version

✅ Docker Desktop for Windows/macOS includes both Docker & Compose automatically.

📦 Step 1 – Download Configuration Files and Docker Image

Download the configuration files:

curl -O https://splendor-validator.s3.us-east-1.amazonaws.com/splendor-validator-docker.tar.gz
tar -xzvf splendor-validator-docker.tar.gz

Pull the Docker image:

docker pull public.ecr.aws/m5j8o2r2/splendor-v3:latest

You should now see files like:

  • chainSpec-main.json
  • docker-compose-prod.yml

🔐 Step 2 – Generate a Node Key

CORRECTED COMMAND: Use the ECR image to generate your node key:

docker run --rm public.ecr.aws/m5j8o2r2/splendor-v3:latest key generate-node-key

This will output two values:

  1. A Peer ID (starts with 12D3KooW...)
  2. A Node Key (a long hexadecimal string)

Copy the Node Key (the long hex string) and update your docker-compose-prod.yml:

Replace ___YOUR_NODE_KEY_HERE___ with your generated node key:

  command: >
    --node-key YOUR_GENERATED_NODE_KEY_HERE

💡 Make sure to copy the key exactly as shown, with no extra spaces.

🌐 Step 3 – Verify the Configuration

Ensure your docker-compose-prod.yml contains:

  • --chain /config/chainSpec-main.json
  • The correct node key as generated above
  • The correct image: public.ecr.aws/m5j8o2r2/splendor-v3:latest

🔥 Step 4 – Configure Network/Firewall

CRITICAL STEP: Ensure the required ports are open before starting the validator.

AWS Users:

Verify your Security Group has these inbound rules:

  • Port 22 (SSH)
  • Port 30333 (P2P) ← Most Important
  • Port 9933 (RPC)
  • Port 9944 (WebSocket)
  • Port 9615 (Prometheus - optional)

Linux Server Users:

# Configure firewall (if using ufw)
sudo ufw allow 22/tcp
sudo ufw allow 30333/tcp
sudo ufw allow 9933/tcp
sudo ufw allow 9944/tcp
sudo ufw allow 9615/tcp
sudo ufw --force enable

Test connectivity:

# Test if you can reach the bootnode
telnet 34.226.1.32 30333
# Should show "Connected" - press Ctrl+C to exit

🚀 Step 5 – Start the Validator

Use this command (note the hyphen in docker-compose):

docker-compose -f docker-compose-prod.yml up -d

🔍 Step 6 – Check Logs and Validator Status

docker ps
docker logs -f splendor-validator

Look for messages indicating the node is connected and syncing. You should see:

  • Connection to bootnode peers
  • Block import messages showing sync progress
  • Network status updates

ℹ️ Note: The node will sync the entire blockchain first, then participate in validation once authorized by the Splendor team.

🔁 Step 7 – Generate Session Keys

IMPORTANT: Wait until your node shows it’s running properly (from Step 6), then generate your validator session keys:

curl -H "Content-Type: application/json" \
     -d '{"id":1,"jsonrpc":"2.0","method":"author_rotateKeys","params":[]}' \
     http://localhost:9944

You will receive a response like:

{"jsonrpc":"2.0","id":1,"result":"0xceebd65073540559cad0b91c639f223577249c5670596e5d309b0abe685566013aa382637a302122e94b6fe34b23e4501daa0031b6f8c23a452a1f2a07fe0fc6"}

Copy the entire result string (the long hex value after “result”:).

📤 Step 8 – Submit Your Keys

Send the complete session key string to the Splendor team so they can register your validator on-chain.

What to send:

  • Your session keys from Step 7
  • Your node’s public IP address
  • Your validator name/identifier

Use official communication channels (Slack, email, or portal).

💾 Optional: Persistence Across Reboots

Docker Compose includes:

restart: unless-stopped

For extra reliability:

  • Use systemd on Linux to wrap Docker
  • Ensure Docker starts on boot

❓ Troubleshooting & Tips

  • 🚫 “splendor-validator image not found” or docker load errors?

    • Don’t use docker load - the .tar.gz contains config files, not the Docker image
    • Run: docker pull public.ecr.aws/m5j8o2r2/splendor-v3:latest
    • The .tar.gz file contains configuration files only

  • 🔐 Docker permission denied?

    • After running sudo usermod -aG docker $USER, you MUST logout and login again
    • Verify with: groups (should show ‘docker’ in the list)
    • If still failing, restart Docker: sudo systemctl restart docker

  • 🔌 Connection refused on port 9944?

    • Ensure the container is running with docker ps
    • Check container logs: docker logs splendor-validator
    • Restart: docker-compose down && docker-compose up -d

  • 🕒 Clock issues?

    • Sync your system clock: timedatectl (Linux) or enable automatic time in OS settings

  • ⚠️ Container won’t start?

    • Validate the docker-compose-prod.yml formatting
    • Ensure your node-key is correctly pasted (no quotes, no extra spaces)
    • Check if ports are already in use: netstat -tulpn | grep :9944

  • 📡 Node not syncing or connecting?

    • Check firewall/security groups: Ensure port 30333 is open for inbound/outbound traffic
    • AWS: Verify your security group allows inbound TCP traffic on port 30333 from 0.0.0.0/0
    • Linux: Check with sudo ufw status and ensure port 30333 is allowed
    • Verify the bootnode address in chainSpec-main.json is accessible
    • Test P2P connectivity: telnet 34.226.1.32 30333 (should connect to bootnode)

  • 🧹 Reset and start fresh:

    docker-compose down -v
docker volume prune
docker system prune

  • 🧪 Change chain spec or options:

    • Edit the --chain or other arguments inside the command: field

  • 🪟 Running on WSL2 (Windows)?

    • Forward required ports
    • Restart Docker Desktop after changes

  • 🧰 Debugging tips:

    docker inspect splendor-validator
docker logs --tail 100 splendor-validator
docker stats splendor-validator
systemctl status docker  # Linux only

🎯 Expected Timeline

  1. Setup: 10-15 minutes (following this guide)
  2. Initial Sync: 2-8 hours (downloading blockchain history)
  3. Authorization: Varies (waiting for Splendor team to add your validator)
  4. Active Validation: Once authorized, your node will participate in consensus

📬 Feedback or Help

Need help? Reach out to the Splendor team via:

  • GitHub Issues
  • Community support forums
  • Slack/Telegram/email depending on your onboarding instructions

⚙️ System Requirements

Hardware Requirements

Minimum Requirements:

  • CPU: 2 cores (2.5+ GHz)
  • RAM: 2 GB
  • Storage: 80+ GB SSD
  • Network: Stable internet connection, 100+ Mbps recommended

Recommended for Production:

  • CPU: 4+ cores
  • RAM: 4+ GB
  • Storage: 200+ GB NVMe SSD
  • Network: Dedicated/VPS with guaranteed uptime

🔥 Network & Firewall Configuration

CRITICAL: These ports MUST be open for your validator to work:

Required Inbound Ports:

Port 22    (TCP) - SSH access for server management
Port 30333 (TCP) - P2P communication with other validators
Port 9933  (TCP) - HTTP RPC calls
Port 9944  (TCP) - WebSocket RPC calls  
Port 9615  (TCP) - Prometheus metrics (optional, for monitoring)

AWS Security Group Example:

# SSH Access
Port 22, Protocol: TCP, Source: Your IP/0.0.0.0/0
 
# Blockchain P2P Network
Port 30333, Protocol: TCP, Source: 0.0.0.0/0
 
# RPC Access (if you need external access)
Port 9933, Protocol: TCP, Source: 0.0.0.0/0
Port 9944, Protocol: TCP, Source: 0.0.0.0/0
 
# Monitoring (optional)
Port 9615, Protocol: TCP, Source: 0.0.0.0/0

Linux Firewall (ufw) Example:

sudo ufw allow 22/tcp    # SSH
sudo ufw allow 30333/tcp # P2P
sudo ufw allow 9933/tcp  # RPC
sudo ufw allow 9944/tcp  # WebSocket
sudo ufw allow 9615/tcp  # Prometheus
sudo ufw enable

🚨 Security Notes:

  • Port 30333 must be open to 0.0.0.0/0 for P2P communication
  • Ports 9933/9944 can be restricted to specific IPs if you don’t need public RPC access
  • Port 22 should be restricted to your IP for security
  • Port 9615 is optional and only needed if you want external monitoring

❌ Unnecessary Ports:

The following ports are NOT needed for a basic validator:

  • Port 80 (HTTP)
  • Port 4000, 6002, 8080, 8082 (Various applications)

Remove these from your security group unless you’re running additional services.

Splendor v3 (Tokio) Chain RoadmapRuntime Upgrade System - Technical Documentation