🚀 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

Download and install Docker Desktop for Windows
Ensure WSL2 and Hyper-V are enabled (Docker Desktop setup will guide you)

🍎 macOS

Download and install Docker Desktop for Mac

🐧 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

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:

A Peer ID (starts with 12D3KooW...)
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

📊 Splendor Blockchain RPC Monitoring Guide

Overview

This guide covers essential RPC methods for monitoring Splendor blockchain node health, sync status, and network connectivity. These calls are crucial for developers and operators to ensure nodes are functioning correctly.

Core Monitoring Endpoints

1. Sync Status Check

Endpoint: system_syncState
Purpose: Determine if node is syncing and track progress


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

Response:


{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "startingBlock": 0,
    "currentBlock": 378335,
    "highestBlock": 1569314
  }
}

Key Metrics:

currentBlock: Node’s latest imported block
highestBlock: Network’s latest block
startingBlock: Usually 0 for full nodes
Sync Progress: (currentBlock / highestBlock) * 100

2. Node Health Status

Endpoint: system_health
Purpose: Overall node health and network connectivity


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

Response:


{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "peers": 8,
    "isSyncing": true,
    "shouldHavePeers": true
  }
}

Key Indicators:

isSyncing: true = actively downloading blocks
peers: Number of connected peers (8+ is healthy)
shouldHavePeers: Network connectivity status

3. Latest Block Header

Endpoint: chain_getHeader
Purpose: Get detailed information about the latest block


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

Response:


{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "parentHash": "0x00806eac754c847b3a5d2b9b2d579d9eee4b0dc2b6e0412b3f8f3e06f8b8e381",
    "number": "0x5db1c",
    "stateRoot": "0x4565bdbbbf57d4bc5ff0f08f869d8d57b8cacbe09bc9882c4d0a5c730ac71bdb",
    "extrinsicsRoot": "0xfdfa67858789c40f37d8e779c1e934e9869295a1da0919839b1da96ddc057031",
    "digest": {
      "logs": ["0x066175726120f002183400000000", "..."]
    }
  }
}

Key Data:

number: Block number (hex format, convert to decimal)
parentHash: Previous block hash
stateRoot: Merkle root of state trie
digest.logs: Consensus-related data (Aura, Grandpa, etc.)

Monitoring Scripts

Quick Health Check


#!/bin/bash
# Quick node health check
echo "=== Splendor Node Health Check ==="
echo "Sync Status:"
curl -s -H "Content-Type: application/json" \
     -d '{"id":1,"jsonrpc":"2.0","method":"system_syncState","params":[]}' \
     http://localhost:9944 | jq '.result'
 
echo -e "\nHealth Status:"
curl -s -H "Content-Type: application/json" \
     -d '{"id":1,"jsonrpc":"2.0","method":"system_health","params":[]}' \
     http://localhost:9944 | jq '.result'

Continuous Sync Monitoring


#!/bin/bash
# Monitor sync progress
while true; do
    clear
    echo "=== Sync Progress Monitor ==="
    echo "$(date)"
    
    SYNC_DATA=$(curl -s -H "Content-Type: application/json" \
        -d '{"id":1,"jsonrpc":"2.0","method":"system_syncState","params":[]}' \
        http://localhost:9944 | jq -r '.result')
    
    CURRENT=$(echo $SYNC_DATA | jq -r '.currentBlock')
    HIGHEST=$(echo $SYNC_DATA | jq -r '.highestBlock')
    PROGRESS=$(echo "scale=2; $CURRENT * 100 / $HIGHEST" | bc)
    
    echo "Current Block: $CURRENT"
    echo "Highest Block: $HIGHEST"
    echo "Progress: ${PROGRESS}%"
    echo "Remaining: $((HIGHEST - CURRENT)) blocks"
    
    sleep 30
done

Status Interpretation

✅ Healthy Node

isSyncing: true with increasing currentBlock
peers >= 8
shouldHavePeers: true
Steady progress in sync state

⚠️ Warning Signs

peers < 4 (poor connectivity)
currentBlock not increasing (stuck sync)
isSyncing: false but currentBlock << highestBlock

❌ Critical Issues

No RPC response (node down)
peers: 0 (network isolation)
currentBlock: 0 (not syncing at all)

WebSocket Monitoring

For real-time monitoring, use WebSocket connections:


# Install wscat if needed: npm install -g wscat
wscat -c ws://localhost:9944

Subscribe to sync updates:


{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "system_syncState",
  "params": []
}

RPC Troubleshooting

Node Not Responding

Check if container is running: docker ps
Check container logs: docker logs <container_name>
Verify port mapping: netstat -tlnp | grep 9944

Slow Sync

Check peer count: system_health
Verify network connectivity
Check disk I/O and available storage
Consider using SSD storage for better performance

Sync Stuck

Restart the node
Check for chain specification mismatches
Verify the node is using the correct image
Check for storage corruption

Best Practices

Regular Monitoring: Check sync status every 5-10 minutes during initial sync
Log Analysis: Monitor container logs for errors and warnings
Resource Monitoring: Track CPU, memory, and disk usage
Backup Chain Spec: Keep chain specification files for recovery
Documentation: Record node configurations and troubleshooting steps

This monitoring approach ensures reliable operation of Splendor validator nodes and helps identify issues before they impact network participation.

🎯 Expected Timeline

Setup: 10-15 minutes (following this guide)
Initial Sync: 2-8 hours (downloading blockchain history)
Authorization: Varies (waiting for Splendor team to add your validator)
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.

❓ 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