SuperNode

💢 Introduction

Lumera SuperNodes are nodes that assume special roles on the Lumera blockchain network. Every SuperNode must be connected to a Validator. This guide offers 3 different installation paths:

Path 1: Staking your own tokens
Path 2: Receiving delegation from the Foundation (new key)
Path 3: Receiving delegation from the Foundation (existing wallet key)

💻 System Requirements

💢 Minimum Requirements

Component	Minimum	Recommended
CPU	8 vCPU	16 vCPU
RAM	16 GB	64 GB
Storage	1 TB NVMe	4 TB NVMe
Network	1 Gbps	5 Gbps
OS	Ubuntu 22.04 LTS	Ubuntu 22.04 LTS

💢 Network Requirements

You need to open the following ports on your firewall:

4444/tcp - gRPC API
8002/tcp - REST Gateway
4445/tcp - P2P Communication

💢 Prerequisites

💢 1. System Update

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

# Install required tools
sudo apt install -y curl wget jq build-essential git ufw

💢 2. Validator Check

⚠️ IMPORTANT: Before starting the SuperNode installation, you must have a Validator and it must be in BOND_STATUS_BONDED state.

# Check validator status
lumerad query staking validator $(lumerad keys show <walletname> --bech val -a)

💢 3. Firewall Settings

# Enable UFW firewall
sudo ufw enable

# Open required ports
sudo ufw allow 22/tcp    # SSH
sudo ufw allow 4444/tcp  # gRPC API
sudo ufw allow 8002/tcp  # REST Gateway
sudo ufw allow 4445/tcp  # P2P

# Check status
sudo ufw status

💢 4. SuperNode Binary Installation

# Download SuperNode binary
sudo curl -L -o /usr/local/bin/supernode \
  https://github.com/LumeraProtocol/supernode/releases/latest/download/supernode-linux-amd64

# Give execution permission
sudo chmod +x /usr/local/bin/supernode

# Check version
supernode version

💢 Installation Paths

Choose the path that suits your situation from the 3 options below:

graph TD
    A[Start] --> B{Which path will you choose?}
    B -->|I have my own tokens| C[Path 1: Own Stake]
    B -->|Foundation delegation| D{Which key?}
    D -->|Create new key| E[Path 2: New SN Key]
    D -->|Use my existing wallet| F[Path 3: Existing Wallet]
    
    C --> G[Installation Complete]
    E --> G
    F --> G

💢 Path 1: Setup with Your Own Stake

This path is for operators who can meet the minimum stake requirement with their own LUME tokens.

💢 1.1. Token Acquisition and Delegation

# Get your Validator operator address
VALOPER=$(lumerad keys show <walletname> --bech val -a)
echo "Validator Operator Address: $VALOPER"

⚠️⚠️⚠️NOTE: You must have created a Validator and staked at least 10k tokens. We will use the wallet we created the validator with in the supernode installation.

💢 1.2. Start SuperNode (New Key)

# Start SuperNode with new key
supernode init --key-name mySNKey --chain-id lumera-testnet-2

Note: After running this code, it will ask you for some information;

⚠️⚠️⚠️IMPORTANT: Use the add wallet option and enter the words of the wallet you created the validator with, do not create a new wallet.

⚠️⚠️⚠️IMPORTANT: You need to activate the Lumera Validator Node gRPC port ("/root/.lumera/config/app.toml") and enter the port you set as the gRPC port. Ex: If SuperNode and Lumera Validator are running on the same server and Lumera gRPC port is 11090, you should write "localhost:11090", if it is on a different server you should write "http://ipaddress:port".

Select OS
Create an 8-character password
Enter the IP of the server you installed on
Continue with the suggested ports if there is no port conflict. If there is, set from available ports

💢 1.3. SuperNode Registration Process

Run the following command on your Validator server:

# Run on Validator server  
VALOPER=$(lumerad keys show <walletname> --bech val -a)
SN_ENDPOINT="<supernode_ip>:4444"

# Find out the address on the SuperNode server:
# supernode keys list --home ~/.supernode
# Then manually set the SN_ACCOUNT variable:
SN_ACCOUNT="<your_validator_wallet_address>"

lumerad tx supernode register-supernode \
  $VALOPER $SN_ENDPOINT $SN_ACCOUNT \
  --from <walletname> \
  --chain-id lumera-testnet-2 \
  --gas auto \
  --gas-adjustment 1.3 \
  --fees 5000ulume

💢 1.4. Create and Start SuperNode Service File

sudo tee /etc/systemd/system/supernode.service <<EOF
[Unit]
Description=Lumera SuperNode
After=network-online.target

[Service]
ExecStart=/usr/local/bin/supernode start --basedir /root/.supernode
Restart=on-failure
RestartSec=5
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reexec
sudo systemctl daemon-reload
sudo systemctl enable supernode
sudo systemctl start supernode
sudo systemctl status supernode

💢 Path 2: Foundation Delegation (New SuperNode Key)

This path creates a new SuperNode key for operators who will receive delegation from the Lumera Foundation.

💢 2.1. Start SuperNode (New Key)

# Start SuperNode with new key
supernode init --key-name mySNKey --chain-id lumera-testnet-2

To Do:

Follow the instructions
Store your mnemonic words securely
Copy the generated address

💢 2.2. Send Address to Foundation

Send the generated SuperNode address (e.g., lumera1...) to the Lumera Foundation. The Foundation will create a delayed vesting account for this address.

Wait for confirmation from the Foundation - wait until the account is created and funded.

💢 2.3. Delegation Process

# Get your Validator operator address
VALOPER=$(lumerad keys show <validator_key_name> --bech val -a)
SN_ACCOUNT="<supernode_address_generated_in_step_2_1>"

# Delegate
lumerad tx staking delegate $VALOPER <amount>ulume \
  --from $SN_ACCOUNT \
  --gas auto \
  --gas-adjustment 1.3 \
  --fees 7000ulume \
  --chain-id lumera-testnet-2

💢 2.4. SuperNode Registration Process

After the vesting account becomes active, on your validator server:

# Run on Validator server
VALOPER=$(lumerad keys show <validator_key_name> --bech val -a)
SN_ENDPOINT="<supernode_ip>:4444"

# Find out the address on the SuperNode server:
# supernode keys list --home ~/.supernode  
# Then manually set the SN_ACCOUNT variable:
SN_ACCOUNT="<address_obtained_from_supernode_keys_list_command>"

lumerad tx supernode register-supernode \
  $VALOPER $SN_ENDPOINT $SN_ACCOUNT \
  --from <validator_key_name> \
  --chain-id lumera-testnet-2 \
  --gas auto \
  --gas-adjustment 1.3 \
  --fees 5000ulume

💢 Path 3: Foundation Delegation (Existing Wallet Key)

This path is for operators who want to use an existing wallet key (Keplr, Leap, etc.).

💢 3.1. Create New Wallet Key

Create a new account using a trusted wallet (Keplr, Leap)
This address must have no transaction history - it must be completely new and unused
Store your mnemonic words securely

💢 3.2. Send Address to Foundation

Send the new, unused wallet address to the Lumera Foundation. The Foundation will create a delayed vesting account for this address.

Wait for confirmation that the vesting account is active.

💢 3.3. Delegation Process

# Get your Validator operator address
VALOPER=$(lumerad keys show <validator_key_name> --bech val -a)
SN_ACCOUNT="<wallet_address_generated_in_step_3_1>"

# Delegate
lumerad tx staking delegate $VALOPER <amount>ulume \
  --from $SN_ACCOUNT \
  --gas auto \
  --gas-adjustment 1.3 \
  --fees 7000ulume \
  --chain-id lumera-testnet-2

💢 3.4. Start SuperNode (Key Recovery)

# Start SuperNode by recovering the existing key
supernode init --key-name myWalletSNKey --recover --chain-id lumera-testnet-2

This command will prompt you to enter the mnemonic words of the wallet you created in Step 3.1.

💢 3.5. SuperNode Registration Process

Run the registration command on your validator server:

# Find out the address on the SuperNode server:
# supernode keys list --home ~/.supernode
# Then manually set the SN_ACCOUNT variable:
SN_ACCOUNT="<address_obtained_from_supernode_keys_list_command>"

# Run on Validator server
VALOPER=$(lumerad keys show <validator_key_name> --bech val -a)
SN_ENDPOINT="<supernode_ip>:4444"

lumerad tx supernode register-supernode \
  $VALOPER $SN_ENDPOINT $SN_ACCOUNT \
  --from <validator_key_name> \
  --chain-id lumera-testnet-2 \
  --gas auto \
  --gas-adjustment 1.3 \
  --fees 5000ulume

💢 Keyring Password Settings

SuperNode supports 3 different password management options:

💢 1. Plain Text in Config File

# ~/.supernode/config.yml
keyring:
  backend: os
  passphrase_plain: "12341234"

💢 2. File Path

# ~/.supernode/config.yml
keyring:
  backend: file
  dir: keys
  passphrase_file: /home/user/.supernode-password

Create the file:

echo "12341234" > ~/.supernode-password
chmod 600 ~/.supernode-password

💢 3. Environment Variable

# ~/.supernode/config.yml
keyring:
  backend: file
  dir: keys
  passphrase_env: SUPERNODE_PWD

Set the environment variable:

export SUPERNODE_PWD="12341234"
# Add to .bashrc or .profile file
echo 'export SUPERNODE_PWD="12341234"' >> ~/.bashrc

💢 Verification and Testing

💢 1. SuperNode Registration Status Check

# Get your Validator operator address
VALOPER=$(lumerad keys show <validator_key_name> --bech val -a)

# Check SuperNode status
lumerad query supernode get-super-node $VALOPER

Expected Status: ACTIVE
Problematic Status: INSUFFICIENT_STAKE (check delegations)

💢 2. Network Connection Check

# gRPC API check
curl -s http://<supernode_ip>:4444/health

# REST Gateway check  
curl -s http://<supernode_ip>:8002/health

💢 3. Performance Check

# System resource usage
htop

# Disk usage
df -h

# SuperNode process check
ps aux | grep supernode

# Port listening check
netstat -tlnp | grep -E "(4444|8002|4445)"

💢 Troubleshooting

💢 Common Issues and Solutions

Issue	Possible Cause	Solution
`ELIGIBILITY_FAILED`	Combined stake < minimum	Verify delegations for correct addresses
SuperNode in `DISABLED` status	Validator dropped from active set	Add stake or wait for validator to become active again
gRPC errors	Incorrect `lumera.grpc_addr`	Use a trusted public node in config
Port connection issue	Firewall	Check UFW rules
Service doesn't start	Keyring password issue	Check password settings

💢 Debug Commands

# Check SuperNode config file
cat ~/.supernode/config.yml

# View key list
supernode keys list --home ~/.supernode

# Manual start (for debugging)
supernode start --home ~/.supernode --log-level debug

# Network connection test
ping <rpc_node_ip>
telnet <supernode_ip> 4444

💢 Security Recommendations

💢 1. Basic Security

Separate Servers: Never run Validator and SuperNode on the same machine
Firewall: Open only necessary ports
SSH: Use key-based authentication, disable password login

💢 2. Key Management

OS Keyring: Use os keyring backend in production environment
Backups: Backup the validator's priv_validator_key.json file and all mnemonic words securely, offline
Permission Control: Set key file permissions to 600 (owner read only)

💢 3. System Security

# SSH security settings
sudo nano /etc/ssh/sshd_config
# PasswordAuthentication no
# PermitRootLogin no
# Port 2222 (change default port)

sudo systemctl restart sshd

# Fail2ban installation
sudo apt install fail2ban -y
sudo systemctl enable --now fail2ban

# Unattended upgrades
sudo apt install unattended-upgrades -y
sudo dpkg-reconfigure unattended-upgrades

💢 4. Monitoring and Alerting

# Disk usage monitoring
echo "df -h | grep -E '^/dev/(xvda|sda|nvme)'" >> ~/monitor.sh

# SuperNode health check
echo "curl -s http://localhost:4444/health || echo 'SuperNode DOWN'" >> ~/monitor.sh

chmod +x ~/monitor.sh

💢 5. Backup Strategy

#!/bin/bash
# Backup script
BACKUP_DIR="/home/$(whoami)/backups/$(date +%Y%m%d)"
mkdir -p $BACKUP_DIR

# Backup SuperNode config
cp ~/.supernode/config.yml $BACKUP_DIR/

# Backup Keyring (be careful!)
# cp -r ~/.supernode/keys $BACKUP_DIR/

echo "Backup completed: $BACKUP_DIR"

💢 Useful Commands

💢 SuperNode Management

# Version check
supernode version

# Config file check
supernode config show

# Key list
supernode keys list

# Create new key
supernode keys add <key_name>

# Delete key
supernode keys delete <key_name>

# Show address
supernode keys show <key_name> -a

💢 Lumera Chain Commands

# Node status
lumerad status

# Validator list
lumerad query staking validators

# Delegation check
lumerad query staking delegations-to <validator_operator_addr>

# Balance check
lumerad query bank balances <address>

💢 System Monitoring

# CPU and RAM usage
top -p $(pgrep supernode)

# Disk I/O
iotop -p $(pgrep supernode)

# Network connections
ss -tulpn | grep supernode

💢 Support and Community

Official Documentation: Lumera Docs
GitHub: LumeraProtocol
Telegram: @Edsny

SuperNode

On this page