🚀 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
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:
- 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
❓ 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
- Don’t use
-
🔐 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
- After running
-
🔌 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
- Ensure the container is running with
-
🕒 Clock issues?
- Sync your system clock:
timedatectl
(Linux) or enable automatic time in OS settings
- Sync your system clock:
-
⚠️ 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
- Validate the
-
📡 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 thecommand:
field
- Edit the
-
🪟 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
- 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.