Vexidus Validator Setup Guide

Run a validator node on the Vexidus network and earn VXS rewards for securing the chain.

---

Table of Contents

1. Overview
2. System Requirements
3. Install Vexidus
4. Generate Your Validator Key
5. Bootstrap Your Node
6. Configure Your Node
7. Start Your Node (VexVisor)
8. Stake and Register as a Validator
9. Connect to the Network
10. Storage and Pruning
11. Monitoring
12. Automatic Upgrades (VexVisor)
13. Security Best Practices
14. Maintenance
15. Troubleshooting
16. Testnet Rewards

---

Overview

Vexidus validators produce blocks every 12 seconds and earn rewards from two sources:

• Block rewards -- ~4.94 VXS per block (year 1-2 rate), auto-adjusting over a 10-year emission schedule
• Transaction fees -- 100% of fees go to the block proposer (no burn)

Parameter	Value
Minimum stake	1,000 VXS
Unbonding period	21 days
Max active validators	100
Block time	12 seconds
Epoch duration	300 seconds
Jailing (missed blocks)	50 consecutive missed blocks -> jailed 5 minutes
Slashing	None -- Vexidus uses jailing, not economic penalties

Validators use Ed25519 keys for block signing and vote participation in the HyperSync consensus protocol. P2P transport uses QUIC (TLS 1.3 + multiplexing over UDP).

---

System Requirements

Minimum

Resource	Spec
CPU	4 cores / 4 threads
RAM	8 GB
Storage	100 GB SSD
Network	100 Mbps, static IP or NAT with port forwarding
OS	Ubuntu 22.04+ / Debian 12+ (x86_64)

Recommended

Resource	Spec
CPU	8+ cores / 16 threads
RAM	16 GB+
Storage	500 GB NVMe SSD
Network	1 Gbps, static IP, low latency
OS	Ubuntu 24.04 LTS (x86_64)

Required Ports

Port	Protocol	Purpose
9944	UDP (QUIC)	P2P -- QUIC transport (TLS 1.3 + multiplexing). Must be open to all peers.
9933	TCP	RPC -- restrict to localhost or trusted IPs

Required Tools

These are installed automatically by the quick install script, or you can install them manually:

Tool	Purpose
build-essential	C compiler and build tools
pkg-config	Library path resolution
libssl-dev	TLS for P2P and RPC
libclang-dev	RocksDB compilation
cmake	Build system for native dependencies
git	Clone the repository
curl	Downloads and RPC calls
jq	JSON formatting for RPC responses
rustc 1.75+	Rust compiler (installed via rustup)

---

Install Vexidus

Quick Install (one command)

curl -sSf https://raw.githubusercontent.com/Mashiyu-Devs/Vexidus/main/scripts/install-validator.sh | bash

This installs all dependencies, builds the node from source, creates the system user and directories, and prints next steps. It does not generate keys or start the node -- those steps require your input.

To inspect the script before running: curl -sSf https://raw.githubusercontent.com/Mashiyu-Devs/Vexidus/main/scripts/install-validator.sh | less

Manual Install

1. Install system dependencies

sudo apt update && sudo apt install -y \
  build-essential \
  pkg-config \
  libssl-dev \
  libclang-dev \
  cmake \
  git \
  curl \
  jq

2. Install Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"

Verify: rustc --version (requires 1.75+)

3. Clone and build

git clone https://github.com/Mashiyu-Devs/Vexidus.git
cd Vexidus
cargo build --release

Build takes 5-10 minutes depending on your hardware. The binary is at target/release/vexidus-node.

4. Install the binary

sudo cp target/release/vexidus-node /usr/local/bin/
vexidus-node --help

5. Create system user and directories

sudo useradd --system --no-create-home --shell /usr/sbin/nologin vexidus
sudo mkdir -p /opt/vexidus/data
sudo chown -R vexidus:vexidus /opt/vexidus

---

Generate Your Validator Key

Your validator key is an Ed25519 keypair used to sign blocks and votes. If you lose your secret key, your staked VXS is unrecoverable.

Generate the key

openssl rand -hex 32 > validator.key
chmod 600 validator.key

This creates a 64-character hex file containing your 32-byte Ed25519 secret key.

Move to secure location

sudo mv validator.key /opt/vexidus/validator.key
sudo chown vexidus:vexidus /opt/vexidus/validator.key
sudo chmod 600 /opt/vexidus/validator.key

View your public key

Your node logs the derived public key on startup when --validator-key is provided. You can preview it with a quick test run:

vexidus-node --validator-key /opt/vexidus/validator.key --data-dir /tmp/vex-keytest 2>&1 | head -20
rm -rf /tmp/vex-keytest

Look for: Validator public key: 0x... -- this is your validator address.

Back up your key

Copy your validator.key to a secure offline location:

• Encrypted USB drive
• Password manager with file attachments
• Hardware security module (HSM) for production deployments

Never share your secret key, paste it in chat, or commit it to version control.

---

Bootstrap Your Node

New validators do not need genesis files. Vexidus supports three bootstrap methods -- choose whichever fits your situation:

Option A: Snapshot Bootstrap (Recommended)

The fastest way to join the network. Download a state snapshot from an existing validator and start producing blocks in minutes instead of hours.

vexidus-node \
  --data-dir /opt/vexidus/data \
  --snapshot-url https://51.255.80.34:9943/checkpoint-latest.tar.zst \
  --validator-key /opt/vexidus/validator.key

What happens:

1. Node downloads the compressed .tar.zst snapshot (~minutes depending on state size)
2. Verifies the archive integrity and restores RocksDB state
3. Your node's block height instantly jumps to the snapshot height
4. P2P sync catches up the remaining blocks from the snapshot to current tip
5. You are ready to stake and produce blocks

Finding snapshot URLs

Active validators serving snapshots listen on their RPC port + 10. The seed validator serves snapshots at http://51.255.80.34:9943/. Updated URLs are published at github.com/Mashiyu-Devs/Vexidus.

Option B: P2P Sync (No Snapshot Needed)

If no snapshot server is available, your node syncs block-by-block from peers via P2P. This is fully automatic -- just start your node with a bootnode address and it will catch up.

vexidus-node \
  --data-dir /opt/vexidus/data \
  --bootnodes /ip4/51.255.80.34/udp/9945/quic-v1/p2p/12D3KooWHhBs5eZFBePWtZhgQfcB7Ds55uRjQqmS6ara7aF8hV1U \
  --validator-key /opt/vexidus/validator.key

What happens:

1. Node connects to bootnode peers via QUIC
2. Requests blocks in batches of 10, verifying proposer signatures on each
3. Catches up to the network tip (speed depends on chain height and network bandwidth)
4. Once synced, begins participating in consensus

note

P2P sync takes longer than snapshot bootstrap for mature chains. For the beta testnet (100K+ blocks), expect 10-30 minutes vs 1-2 minutes with a snapshot.

Option C: Genesis Start (Seed Validators Only)

Only needed if you are starting a new chain from scratch (e.g., the genesis restart for beta launch). Regular validators joining an existing network should use Option A or B.

# Copy genesis files (seed operator only)
sudo cp genesis_vxs.json /opt/vexidus/
sudo cp genesis_tokens.json /opt/vexidus/
sudo chown vexidus:vexidus /opt/vexidus/genesis_*.json

Serve Snapshots to Other Validators

If you want to help new validators bootstrap faster, enable snapshot serving:

vexidus-node ... --serve-snapshots

This creates checkpoints every 1,000 blocks and serves compressed .tar.zst archives via HTTP on your RPC port + 10 (e.g., if RPC is :9933, snapshots are served on :9943). Only the last 3 snapshots are kept to save disk space.

---

Configure Your Node

Create a validator config

Create /opt/vexidus/validator.toml:

# Vexidus Validator Configuration

# Path to your Ed25519 secret key (64 hex chars)
keypair_path = "/opt/vexidus/validator.key"

# RPC endpoint (keep on localhost for security)
rpc_url = "http://127.0.0.1:9933"

# Network ports
p2p_port = 9944
rpc_port = 9933

# Chain data directory
data_dir = "/opt/vexidus/data"

# Your server's public IP for peer discovery
# Find yours with: curl -4 ifconfig.me
external_addr = "/ip4/YOUR_PUBLIC_IP/udp/9944/quic-v1"

# Bootstrap peers (comma-separated multiaddrs)
bootnodes = "/ip4/51.255.80.34/udp/9945/quic-v1/p2p/12D3KooWHhBs5eZFBePWtZhgQfcB7Ds55uRjQqmS6ara7aF8hV1U"

# Enable detailed logging (useful during initial setup)
verbose = false

Replace YOUR_PUBLIC_IP with your server's actual public IP:

curl -4 ifconfig.me

Set permissions

sudo chown vexidus:vexidus /opt/vexidus/validator.toml

Create the systemd service

Create /etc/systemd/system/vexidus-validator.service:

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

[Service]
Type=simple
User=vexidus
Group=vexidus
WorkingDirectory=/opt/vexidus
ExecStart=/opt/vexidus/vexvisor.sh \
  --data-dir /opt/vexidus/data \
  --rpc-port 9933 \
  --p2p-port 9944 \
  --validator-key /opt/vexidus/validator.key \
  --external-addr /ip4/YOUR_PUBLIC_IP/udp/9944/quic-v1 \
  --bootnodes /ip4/51.255.80.34/udp/9945/quic-v1/p2p/12D3KooWHhBs5eZFBePWtZhgQfcB7Ds55uRjQqmS6ara7aF8hV1U \
  --gas-price 10 \
  --pruning validator \
  --serve-snapshots \
  --metrics
Restart=always
RestartSec=5
LimitNOFILE=65536

# Hardening
ProtectSystem=full
ProtectHome=read-only
NoNewPrivileges=true

[Install]
WantedBy=multi-user.target

The service uses vexvisor.sh instead of the raw binary so upgrades are handled automatically. The --pruning validator flag keeps storage manageable, --serve-snapshots helps new validators bootstrap, and --metrics exposes Prometheus metrics.

---

Start Your Node (VexVisor)

All production validators should run via the VexVisor wrapper. VexVisor monitors your node and handles automatic binary upgrades -- when a network upgrade is approved, VexVisor downloads the new binary, verifies its checksum, swaps it in, and restarts your node. No manual intervention required.

Set up VexVisor

# Create VexVisor directory structure
sudo mkdir -p /opt/vexidus/vexvisor/current
sudo cp /usr/local/bin/vexidus-node /opt/vexidus/vexvisor/current/vexidus-node
sudo chown -R vexidus:vexidus /opt/vexidus/vexvisor

# Copy VexVisor wrapper script
sudo cp tools/vexvisor.sh /opt/vexidus/vexvisor.sh
sudo chmod +x /opt/vexidus/vexvisor.sh
sudo chown vexidus:vexidus /opt/vexidus/vexvisor.sh

Update the systemd service to use VexVisor

Modify your service file so ExecStart points to the VexVisor wrapper instead of the raw binary:

ExecStart=/opt/vexidus/vexvisor.sh \
  --data-dir /opt/vexidus/data \
  --rpc-port 9933 \
  --p2p-port 9944 \
  --validator-key /opt/vexidus/validator.key \
  --external-addr /ip4/YOUR_PUBLIC_IP/udp/9944/quic-v1 \
  --bootnodes /ip4/51.255.80.34/udp/9945/quic-v1/p2p/12D3KooWHhBs5eZFBePWtZhgQfcB7Ds55uRjQqmS6ara7aF8hV1U \
  --gas-price 10 \
  --pruning validator \
  --serve-snapshots

VexVisor passes all CLI flags through to the node binary. It only intercepts exit code 42 (upgrade signal) to perform the binary swap.

Why VexVisor matters

Without VexVisor, you must manually download, verify, and restart your node for every upgrade. Missing an upgrade can cause your node to halt at the upgrade height and stay down until you intervene -- potentially getting jailed for missed blocks. VexVisor handles this automatically.

Start and enable

sudo systemctl daemon-reload
sudo systemctl enable vexidus-validator
sudo systemctl start vexidus-validator

Verify it is running

sudo systemctl status vexidus-validator

Watch the logs

sudo journalctl -u vexidus-validator -f

You should see:

[VexVisor] Starting vexidus-node...
Vexidus Blockchain Node v0.1.0
Loading validator key from "/opt/vexidus/validator.key"
Validator public key: 0xabc123...
P2P Network started successfully
Listening on /ip4/0.0.0.0/udp/9944/quic-v1
RPC server listening on 0.0.0.0:9933
Block #12345 produced ...

Wait for sync

Before staking, ensure your node is fully synced. Check your current block height:

curl -s http://localhost:9933 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' | jq .result

Compare with the network tip on vexscan.io. Once the heights match, your node is synced.

---

Stake and Register as a Validator

Once synced, stake VXS to join the active validator set.

Get Testnet VXS

Before staking, you need VXS tokens. Visit the testnet faucet at vexswap.xyz:

1. Generate a wallet address (your node logs the derived address on startup)
2. Go to https://vexswap.xyz and enter your address to receive testnet VXS
3. Rate limit: 100 VXS per address per hour -- request multiple times to accumulate the 1,000 VXS minimum stake

Check your balance

curl -s http://localhost:9933 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"vex_getBalance","params":["YOUR_ADDRESS","VXS"],"id":1}' | jq .

Stake VXS (minimum 1,000)

curl -s http://localhost:9933 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "vex_stake",
    "params": ["YOUR_STAKER_ADDRESS", "1000", "YOUR_VALIDATOR_PUBKEY_HEX"],
    "id": 1
  }' | jq .

Parameter	Description
YOUR_STAKER_ADDRESS	The account holding your VXS (hex-encoded 32 bytes)
1000	Amount of VXS to stake (minimum 1,000)
YOUR_VALIDATOR_PUBKEY_HEX	64-char hex public key derived from your validator.key

Verify your registration

# Check your validator entry
curl -s http://localhost:9933 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"vex_getValidator","params":["YOUR_ADDRESS"],"id":1}' | jq .

# List all active validators
curl -s http://localhost:9933 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"vex_listValidators","params":[100],"id":1}' | jq .

# Network staking summary
curl -s http://localhost:9933 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"vex_stakingInfo","params":[],"id":1}' | jq .

Set your validator profile

Set on-chain metadata so delegators can identify your validator:

curl -s http://localhost:9933 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "vex_setValidatorMetadata",
    "params": ["YOUR_ADDRESS", "My Validator", "Reliable validator node", "https://mysite.com", "https://mysite.com/avatar.png"],
    "id": 1
  }' | jq .

Set commission rate

Commission is the percentage of delegator rewards you keep (in basis points, max 5000 = 50%):

curl -s http://localhost:9933 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "vex_setCommission",
    "params": ["YOUR_ADDRESS", 500],
    "id": 1
  }' | jq .

500 = 5% commission. Default is 0%.

Commission Cooldown

Commission changes have a 7-day cooldown (~50,400 blocks). After changing your commission rate, you must wait 7 days before changing it again. This prevents commission manipulation (e.g., advertising low commission to attract delegators, then raising it).

Auto-Compound Rewards

Delegators can enable auto-compound to automatically restake their earned rewards instead of manually claiming:

# Enable auto-compound for your delegation
curl -s http://localhost:9933 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "vex_setAutoCompound",
    "params": ["YOUR_VALIDATOR_ADDRESS", true, "YOUR_DELEGATOR_ADDRESS"],
    "id": 1
  }' | jq .

When enabled, rewards are restaked at the end of each epoch -- no additional transactions or gas needed.

Staking Pool Configuration (Validators)

Validators can configure their staking pool to attract delegators:

curl -s http://localhost:9933 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "vex_setPoolConfig",
    "params": [true, "My Staking Pool", "100000000000", true, "YOUR_VALIDATOR_ADDRESS"],
    "id": 1
  }' | jq .

Parameter	Description
pool_enabled	Whether to accept delegations (true/false)
pool_name	Display name for your staking pool
min_delegation	Minimum VXS required to delegate (raw units, 9 decimals)
auto_compound_default	Default auto-compound setting for new delegators

Pool settings are visible via vex_getValidator and vex_listValidators.

Gas and Transaction Fees

Vexidus uses a gas-based fee model similar to Ethereum, but with Solana-competitive pricing:

Parameter	Value
Base gas price	10 nanoVXS per gas unit (configurable via --gas-price)
Transfer gas	~21,000 gas units
Cost per transfer	0.00021 VXS ($0.0002 at $1/VXS)
Fee recipient	100% to block proposer (no burn)

Set --gas-price 0 in your systemd service for free testnet transactions.

---

Connect to the Network

Bootstrap Nodes

Your node needs at least one bootstrap peer to discover the network. Current bootstrap:

/ip4/51.255.80.34/udp/9945/quic-v1/p2p/12D3KooWHhBs5eZFBePWtZhgQfcB7Ds55uRjQqmS6ara7aF8hV1U

Updated bootstrap lists are published at github.com/Mashiyu-Devs/Vexidus.

NAT and Firewalls

If your server is behind NAT:

1. Forward port 9944 (UDP) from your router to your server
2. Set --external-addr so peers can find you:

   --external-addr /ip4/YOUR_PUBLIC_IP/udp/9944/quic-v1

Verify peer connectivity

sudo journalctl -u vexidus-validator --no-pager | grep -i "peer\|connect\|dial"

Firewall setup (ufw)

# Allow P2P from anywhere (QUIC uses UDP)
sudo ufw allow 9944/udp

# Block public RPC access (use localhost only)
sudo ufw deny 9933/tcp

# Enable firewall
sudo ufw enable

If you need remote RPC access from specific IPs:

sudo ufw allow from YOUR_TRUSTED_IP to any port 9933 proto tcp

---

Storage and Pruning

Vexidus stores chain state in RocksDB. Over time, the database grows as blocks accumulate. Pruning controls how much historical data your node retains.

Pruning Modes

Mode	Blocks Kept	Explorer Data	Use Case
archive (default)	All	All	Block explorers, indexers, historical queries
validator	Last 10,000	Last 7 days	Recommended for validators -- full consensus, minimal storage
aggressive	Last 256	Last 24 hours	Light infrastructure, monitoring nodes

Configure with:

--pruning validator    # Recommended for most validators

Pruning runs automatically every 100 blocks in the background -- it does not interrupt block production. RocksDB compaction reclaims disk space every 1,000 blocks.

Storage Estimates

Mode	After 1 Month	After 6 Months	After 1 Year
archive	~5 GB	~30 GB	~60 GB
validator	~2 GB	~2 GB	~2 GB
aggressive	~500 MB	~500 MB	~500 MB

These estimates assume moderate transaction volume. Heavy DeFi activity or token creation will increase sizes.

Node Modes

Mode	Flag	Can Produce Blocks	Full State	Use Case
Full validator	(default)	Yes	Yes	Standard validator
Light node	--light	No	No (headers only)	Monitoring, RPC relay

Light mode (--light) runs a header-only node that cannot produce blocks or query account state. It is useful for monitoring network health or as a lightweight RPC relay.

Prometheus Metrics

Enable metrics export for Grafana, Prometheus, or other monitoring tools:

--metrics                    # Enable Prometheus metrics endpoint
--metrics-port 9100          # Port for metrics (default: 9100)
--metrics-external           # Allow external access (default: localhost only)

Metrics include block height, peer count, mempool size, block production latency, and more.

---

Monitoring

Quick health check

curl -s http://localhost:9933 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' | jq .result

Logs

# Last 50 lines
sudo journalctl -u vexidus-validator -n 50 --no-pager

# Live follow
sudo journalctl -u vexidus-validator -f

Monitoring script

Save as /opt/vexidus/monitor.sh:

#!/bin/bash
# Vexidus Validator Health Monitor

RPC="http://localhost:9933"

rpc_call() {
  curl -sf "$RPC" \
    -H "Content-Type: application/json" \
    -d "{\"jsonrpc\":\"2.0\",\"method\":\"$1\",\"params\":$2,\"id\":1}" 2>/dev/null
}

block=$(rpc_call "eth_blockNumber" "[]" | jq -r '.result // "unreachable"')
validators=$(rpc_call "vex_listValidators" "[100]" | jq -r '.result | length // 0')
staking=$(rpc_call "vex_stakingInfo" "[]" | jq -r '.result.total_staked // "0"')
status=$(systemctl is-active vexidus-validator)
uptime=$(systemctl show vexidus-validator --property=ActiveEnterTimestamp --value)

echo "=============================="
echo "  Vexidus Validator Status"
echo "=============================="
echo "  Service:       $status"
echo "  Block height:  $block"
echo "  Validators:    $validators"
echo "  Total staked:  $staking VXS"
echo "  Up since:      $uptime"
echo "=============================="

---

Security Best Practices

Key Management

• Store validator.key with permissions 600, owned by vexidus user only
• Maintain an encrypted offline backup (USB, password manager, or HSM)
• Never share your secret key or commit it to git
• Key rotation will be available via VSA v2 (coming soon)

Network

• RPC port (9933): Never expose to the public internet. Bind to 127.0.0.1 or restrict via firewall.
• P2P port (9944): Must be open to all peers for consensus participation.

System Hardening

• Keep your OS updated: sudo apt update && sudo apt upgrade -y
• Enable unattended security updates: sudo apt install -y unattended-upgrades
• Use SSH key authentication and disable password login
• Run the node as the dedicated vexidus user, never as root
• The systemd service includes ProtectSystem=full, ProtectHome=read-only, and NoNewPrivileges=true by default

---

Automatic Upgrades (VexVisor)

Network upgrades are coordinated on-chain via VexVisor governance. When an upgrade is approved, every validator running VexVisor upgrades automatically -- no manual intervention needed.

How it works

1. The upgrade authority (or validator vote in full mode) schedules an upgrade at a future block height
2. All nodes see the approved upgrade plan on-chain
3. At the target height, your node writes data/upgrade-info.json and exits with code 42
4. VexVisor detects exit(42) and:
   • Downloads the new binary from the URL in the upgrade plan
   • Verifies the SHA256 checksum (rejects tampered binaries)
   • Backs up your current binary
   • Swaps in the new binary and restarts
5. If the new binary crashes within 60 seconds, VexVisor automatically rolls back to the previous version

Grace period

After an upgrade, there is a 100-block grace period (~20 minutes) where missed-block tracking is suppressed. You will not be jailed for blocks missed during the upgrade window.

What you need to do

Nothing. If you set up VexVisor as described in the Start Your Node section, upgrades are fully automatic. You can monitor the upgrade via logs:

sudo journalctl -u vexidus-validator -f | grep -i "upgrade\|vexvisor"

Governance modes

Mode	How upgrades are approved	Current usage
seed-authority	Upgrade authority auto-approves instantly	Beta testnet
full	Stake-weighted validator vote (67% quorum, configurable)	Mainnet

For full details on the governance protocol, see VexVisor Upgrade Governance.

---

Maintenance

Manual upgrades (without VexVisor)

If you are not running VexVisor, you must upgrade manually when a network upgrade is scheduled. Your node will halt at the upgrade height and not restart until you swap the binary.

# Download the new binary (URL from the upgrade announcement)
curl -L -o vexidus-node-new https://releases.vexidus.io/v0.2.0/vexidus-node
chmod +x vexidus-node-new

# Verify checksum (from the upgrade plan)
sha256sum vexidus-node-new

# Swap and restart
sudo systemctl stop vexidus-validator
sudo cp vexidus-node-new /usr/local/bin/vexidus-node
sudo systemctl start vexidus-validator
sudo journalctl -u vexidus-validator -n 20 --no-pager

warning

Without VexVisor, you risk being jailed if you miss the upgrade window. Strongly consider running VexVisor for production validators.

Unstaking

To leave the validator set, begin the 21-day unbonding process:

curl -s http://localhost:9933 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "vex_unstake",
    "params": ["YOUR_ADDRESS", "1000"],
    "id": 1
  }' | jq .

After 21 days, submit a ClaimUnstake transaction to withdraw your VXS.

Full resync (wipe chain data)

If your node is corrupted or you need a clean start:

sudo systemctl stop vexidus-validator
sudo rm -rf /opt/vexidus/data
sudo systemctl start vexidus-validator

Your validator.key is preserved -- only chain state is wiped. The node will re-sync from peers automatically. For faster recovery, use --snapshot-url to bootstrap from a snapshot instead of syncing block-by-block.

---

Troubleshooting

Node will not start

sudo systemctl status vexidus-validator
sudo journalctl -u vexidus-validator -n 100 --no-pager

Symptom	Fix
Permission denied on key file	sudo chown vexidus:vexidus /opt/vexidus/validator.key && sudo chmod 600 /opt/vexidus/validator.key
Port already in use	Check for conflicts: sudo lsof -i :9944
Missing data directory	sudo mkdir -p /opt/vexidus/data && sudo chown vexidus:vexidus /opt/vexidus/data
State not loading	Use --snapshot-url to bootstrap from an existing validator, or ensure P2P sync is working

No peers connecting

• Verify port 9944/udp is open: nc -zuv YOUR_PUBLIC_IP 9944 from another machine
• Confirm --external-addr matches your actual public IP
• Check bootnode is reachable: nc -zuv 51.255.80.34 9945
• Inspect dial attempts: sudo journalctl -u vexidus-validator --no-pager | grep -i "dial\|error\|failed"

Node not producing blocks

• Ensure your node is fully synced (block height matches the network)
• Verify you are in the active set: vex_listValidators
• Confirm your stake meets the 1,000 VXS minimum: vex_getValidator
• Check if your validator is jailed (see below)
• Check for epoch transitions in logs

Validator is jailed

Validators are jailed after missing 50 consecutive blocks (~10 minutes). Jailed validators cannot produce blocks or earn rewards. After a 5-minute cooldown, unjail yourself:

curl -s http://localhost:9933 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "vex_unjail",
    "params": ["YOUR_ADDRESS"],
    "id": 1
  }' | jq .

Check jail status with vex_getValidator -- look for is_jailed and jail_release_time fields.

RPC not responding

• Confirm the service is running: systemctl is-active vexidus-validator
• Check port is bound: ss -tlnp | grep 9933
• Test locally: curl http://localhost:9933 -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

---

Key Files Reference

File	Purpose
/opt/vexidus/validator.key	Ed25519 secret key (64 hex chars). Keep secret.
/opt/vexidus/validator.toml	Node configuration
/opt/vexidus/vexvisor.sh	VexVisor upgrade wrapper script
/opt/vexidus/vexvisor/current/vexidus-node	Active node binary (managed by VexVisor)
/opt/vexidus/data/node_key	libp2p identity key (auto-generated, stable PeerId)
/opt/vexidus/data/	RocksDB chain state
/opt/vexidus/data/upgrade-info.json	Written by node at upgrade height (consumed by VexVisor)
/opt/vexidus/data/checkpoints/	Periodic state snapshots (if --serve-snapshots enabled)
/usr/local/bin/vexidus-node	Node binary (or use VexVisor path instead)

CLI Reference

vexidus-node [OPTIONS]

Core:
  -d, --data-dir <PATH>              Data directory [default: ./data]
  -v, --verbose                      Enable verbose logging
      --rpc-port <PORT>              RPC listen port [default: 9933]
      --p2p-port <PORT>              P2P listen port, QUIC/UDP [default: 9944]
      --bootnodes <MULTIADDRS>       Comma-separated bootstrap peer multiaddrs
      --validator-key <PATH>         Path to Ed25519 signing key file
      --external-addr <MULTIADDR>    Public address to advertise (NAT traversal)

Consensus:
      --gas-price <N>                Base gas price in nanoVXS/gas [default: 10]
      --block-time <SECS>            Block production interval [default: 12]
      --max-txs-per-block <N>        Max transactions per block [default: 10000]
      --min-validators <N>           Minimum validators required [default: 1]
      --reject-unsigned-bundles      Reject unsigned transaction bundles
      --no-leader-check              Disable leader rotation (solo testnet only)

Bootstrap:
      --snapshot-url <URL>           Download and restore state snapshot on first start
      --serve-snapshots              Serve snapshots to other nodes (port = RPC + 10)

Storage:
      --pruning <MODE>               Pruning mode: archive | validator | aggressive [default: archive]
      --light                        Run as header-only light node (no state execution)
      --elastic-state                Enable ElasticState 3-tier storage (hot/warm/cold)
      --backfill-indexes             Backfill explorer indexes on startup

Metrics:
      --metrics                      Enable Prometheus metrics endpoint
      --metrics-port <PORT>          Metrics listen port [default: 9100]
      --metrics-external             Allow external access to metrics endpoint

Governance (VexVisor):
      --governance-mode <MODE>       Governance mode: seed-authority | full [default: seed-authority]
      --upgrade-authority <HEX>      Hex pubkey of the upgrade authority
      --auto-vote-seed <HEX>         Auto-vote seed for deterministic voting
      --voting-period <BLOCKS>       Upgrade voting period in blocks [default: 500]
      --upgrade-quorum <PERCENT>     Required approval quorum for upgrades [default: 67]

Security:
      --bridge-strict                Reject bridge deposits with unverified proofs

  -h, --help                         Print help

---

Testnet Rewards

Testnet validators who maintain high performance earn mainnet VXS airdrops at launch. Rewards are based on your on-chain reputation score (VSC-REP), which tracks 7 factors:

• Uptime and block production consistency
• Vote participation rate
• Stake amount and duration
• Commission rate fairness
• Transaction processing volume
• Network contribution (peer connectivity)
• Governance participation (future)

Check your validator's reputation score via vex_getValidator -- the performance_score field (0.5 to 1.0) directly affects your leader selection weight and reward share. New validators start at 0.8.

---

Links

• Repository: github.com/Mashiyu-Devs/Vexidus
• Explorer: vexscan.io
• Faucet: vexswap.xyz (testnet VXS for staking)
• Developer Studio: vexforge.xyz

---

Vexidus is its own L1 blockchain. Native addresses use the Vx prefix. The 0x format exists only for EVM compatibility and internal system addresses.