Vextaris Validator Setup Guide

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

Overview
System Requirements
Install Vextaris
Generate Your Validator Key
Bootstrap Your Node
Configure Your Node
Start Your Node (VexVisor)
Stake and Register as a Validator
Connect to the Network
Storage and Pruning
Monitoring
Automatic Upgrades (VexVisor)
Security Best Practices
Maintenance
Troubleshooting
Testnet Rewards

Overview

Vextaris validators produce blocks adaptively (2s nominal, 500ms-12s range) and earn rewards from two sources:

Block rewards -- Time-weighted from a 10-year emission schedule (13M VXS/yr year 1-2). 85% to validators (density-weighted 0.5x-2.0x), 15% to Foundation Treasury
Transaction fees -- 80% to block proposer, 20% to Foundation Treasury (no burn)

Parameter	Value
Minimum stake	1,000 VXS
Unbonding period	21 days
Max active validators	100
Block time	~2s adaptive (500ms-12s)
Epoch duration	1 hour (1,800 blocks)
Jailing	Double-sign detection → escalating jail (1h → 24h → 7d → 30d)
Slashing	None -- Vextaris uses jailing, not economic penalties

Validators use Ed25519 keys for block signing and vote participation in the HyperSync consensus protocol with Vexcel attestation DAG for global latency fairness. 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 -- of which ~38 GB must be free at first start for the snapshot restore (the archive plus the state it extracts to; the archive is deleted afterwards)
Network	100 Mbps, static IP or NAT with port forwarding
OS	Ubuntu 22.04+ / Debian 12+ (x86_64)

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
9946	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
`curl`	Downloads and RPC calls
`jq`	JSON formatting for RPC responses
`coreutils` (`sha256sum`)	Verifying the released binary against the published checksum

The node ships as a pre-built binary, so no compiler, Rust toolchain or build dependencies are needed. (This table previously listed build-essential, cmake, libclang-dev and rustc for a build-from-source path that is not available publicly during the beta programme.)

Install Vextaris

Quick Install (one command)

curl -sSf https://vexidus.io/releases/install-validator.sh | bash

This downloads the released binary (checksum-verified), the genesis files, VexVisor, and the current network flag set, creates the system user and directories, writes a systemd unit, and prints next steps. It does not generate keys or start the node -- those steps require your input.

The flag set it fetches (validator-flags.txt) is generated from the validators that are actually running, and your ExecStart is written from it. You set only the identity flags (--data-dir, --rpc-port, --p2p-port, --validator-key, --external-addr).

The installer refuses to write a unit if that flag set is missing, or if it was generated for a different binary than the one it just installed. Both refusals are deliberate: a node missing a consensus activation height either sits at height 0 forever or diverges from the network and stops. If you hit either refusal, report it -- do not hand-edit the flags.

To inspect the script before running: curl -sSf https://vexidus.io/releases/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. Download the released binary

The node is distributed as a pre-built binary -- there is no public build-from-source path during the beta programme, and you do not need a Rust toolchain.

curl -fSL -o vexidus-node https://vexidus.io/releases/vexidus-node
curl -fsSL -o SHA256SUMS https://vexidus.io/releases/SHA256SUMS
grep vexidus-node SHA256SUMS | sha256sum --check -    # must print: vexidus-node: OK

Verify the checksum

If the check does not print OK, stop. Do not run the binary -- report it to validators@vexidus.com. The quick install does this step for you.

3. Install the binary

chmod +x vexidus-node
sudo cp vexidus-node /usr/local/bin/
vexidus-node --help

4. Fetch the network flag set

Your node must run every consensus activation height the network is enforcing. That list changes as the network activates protocol upgrades, so it is generated from the running validators, not copied from a document:

curl -fsSL -o validator-flags.txt https://vexidus.io/releases/validator-flags.txt
head -7 validator-flags.txt      # provenance: which binary and height it was generated from

Every -- line in that file belongs in your ExecStart, alongside your own identity flags (--data-dir, --rpc-port, --p2p-port, --validator-key, --external-addr). A node missing one of them either sits at height 0 forever or diverges from the network and stops.

Let the installer do this

The quick install fetches this file and writes the unit from it, and refuses to proceed if the flag set is missing or was generated for a different binary. Assembling the unit by hand is the step that goes wrong.

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 and do not run anything by hand to bootstrap. The flag set from step 4 includes --snapshot-url, so the first time your node starts with an empty data directory it:

Downloads the published state snapshot (.tar.zst, a few minutes depending on state size)
Verifies the archive against its published checksum and restores the chain state
Jumps to the snapshot height, then syncs the remaining blocks from peers
Is ready for you to stake and register

Finding snapshot URLs

The supported snapshot is published at https://vexidus.io/releases/vexidus-snapshot-latest.tar.zst, restaged regularly, with its height and checksum in vexidus-snapshot-latest.info.

Do not bootstrap from another validator's port

Earlier versions of this page pointed at a running validator's in-node snapshot port. That endpoint is unauthenticated and is not part of the supported install path -- use the published URL above.

:::

The snapshot is the only way in

Joining by replaying the chain from block 0 is not supported on the current network. Earlier versions of this page offered "P2P sync (no snapshot)" and "genesis start" options; neither produces a working validator. If the snapshot download fails, fix that -- do not remove --snapshot-url.

Serve Snapshots to Other Validators

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

vexidus-node ... --serve-snapshots

This creates periodic checkpoints and serves compressed .tar.zst archives over plain HTTP on your RPC port + 10 (e.g. RPC :9933 -> snapshots on :9943).

Keep that port private

The snapshot endpoint has no authentication and no rate limiting, and serving a snapshot is expensive for the node doing it. Do not expose it to the internet: bind it behind your firewall and share it only with peers you choose. New validators should use the published snapshot URL above. Checkpoints also accumulate on disk -- watch free space, since a full disk stops your node.

Configure Your Node

The node is configured entirely by command-line flags in its systemd unit -- there is no config file. Those flags come in two parts:

Your identity (you set these): --data-dir, --rpc-port, --p2p-port, --validator-key, --external-addr.
The network's flags (you copy these, never edit them): every -- line of the validator-flags.txt you fetched in step 4 -- the bootnodes, the snapshot URL and the consensus activation heights.

Do not write this unit by hand

A unit with only the handful of flags you would type yourself starts, connects to peers, and then stays at height 0 forever with no error. A unit missing one activation height computes a different state from the rest of the network and stops. Build it from the flag set, as below.

Create the systemd service

Run this in the directory where you saved validator-flags.txt. It writes the same unit as the quick install:

MY_IP=$(curl -4 -s ifconfig.me)   # your server's public IPv4 -- check it before continuing
echo "$MY_IP"

{
cat <<EOF
[Unit]
Description=Vextaris Validator Node
After=network.target
Wants=network-online.target

[Service]
Type=simple
User=vexidus
Group=vexidus
WorkingDirectory=/opt/vexidus
ExecStart=/opt/vexidus/tools/vexvisor.sh \\
  --data-dir /opt/vexidus/data \\
  --rpc-port 9933 \\
  --p2p-port 9946 \\
  --validator-key /opt/vexidus/validator.key \\
  --external-addr /ip4/${MY_IP}/udp/9946/quic-v1 \\
EOF
grep '^--' validator-flags.txt | sed 's/^/  /; s/$/ \\/'
cat <<'EOF'
  --metrics
Restart=always
RestartSec=5
LimitNOFILE=1048576
Environment=RUST_LOG=info

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

[Install]
WantedBy=multi-user.target
EOF
} | sudo tee /etc/systemd/system/vexidus-validator.service > /dev/null

Then check it. The second number must be the first plus 6 (your five identity flags and --metrics):

sudo systemd-analyze verify /etc/systemd/system/vexidus-validator.service   # no output = OK
grep -c '^--' validator-flags.txt
grep -c '^  --' /etc/systemd/system/vexidus-validator.service

The unit runs the node through vexvisor.sh (set up next) so network upgrades are applied automatically, and --metrics exposes Prometheus metrics.

When the network's flags change

Protocol upgrades add activation heights. When an upgrade announcement asks you to refresh your flags, fetch validator-flags.txt again and regenerate the unit the same way, keeping your identity flags.

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

Run this in the directory where you downloaded SHA256SUMS in step 2:

curl -fsSL -o vexvisor.sh https://vexidus.io/releases/vexvisor.sh
grep vexvisor.sh SHA256SUMS | sha256sum --check -    # must print: vexvisor.sh: OK

sudo mkdir -p /opt/vexidus/tools /opt/vexidus/vexvisor/current
sudo install -m 755 vexvisor.sh /opt/vexidus/tools/vexvisor.sh
sudo cp /usr/local/bin/vexidus-node /opt/vexidus/vexvisor/current/vexidus-node
sudo chown -R vexidus:vexidus /opt/vexidus

Keep the script at /opt/vexidus/tools/vexvisor.sh: VexVisor finds the node binary (/opt/vexidus/vexvisor/current/) and the data directory relative to the folder above its own.

The unit you created already starts the node through VexVisor, which passes all flags through to the binary and only intercepts exit code 42 (the upgrade signal) to swap in the new binary.

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...
Vextaris 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/9946/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:

Generate a wallet address (your node logs the derived address on startup)
Go to https://vexswap.xyz and enter your address to receive testnet VXS
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

Vextaris 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	80% to block proposer, 20% Foundation Treasury (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. Use all three for best redundancy:

NA (Beauharnois, Canada) -- note UDP port 9944:

/ip4/158.69.203.54/udp/9944/quic-v1/p2p/12D3KooWQH31LHN8xWj183oZSkDLA8FeNfCPsNJXww5xyQsPNozh

EU (Zurich, Switzerland):

/ip4/141.227.150.129/udp/9945/quic-v1/p2p/12D3KooWAf1EaQ9fa7UqtTK9x7w8jKh1BdcU7epfrwgyXskx2QTS

Asia (Singapore):

/ip4/15.235.210.254/udp/9945/quic-v1/p2p/12D3KooWQjomQQ3gGobaK11TcjTWbrDESvTFY1SiN4JnZKzAMhhp

Pass all three as one comma-separated --bootnodes value. Keep the /p2p/<PeerId> suffix: without it your node cannot tell that it is already connected to a seed, redials it about once a minute, and each redial leaves an extra connection open for up to 24 hours, so memory grows until the node restarts.

A seed's PeerId changes if its data is ever reset, and a PeerId that no longer matches makes the dial fail. If your node logs dial errors to a seed, take the list again from the flag set below.

The current bootstrap peers ship in the published flag set, validator-flags.txt -- the --bootnodes line. It is generated from the running network, so it is the list to trust over any copy pasted elsewhere.

NAT and Firewalls

If your server is behind NAT:

Forward port 9946 (UDP) from your router to your server

Set --external-addr so peers can find you:

--external-addr /ip4/YOUR_PUBLIC_IP/udp/9946/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 9946/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

Vextaris stores chain state in RocksDB, and every node currently keeps the full history: the database grows for as long as the node runs.

Pruning is not active in the current release

The node accepts a --pruning flag, but it has no effect at present -- setting it does not reduce disk usage. It is not part of the network flag set, so leave it out of your unit. Earlier versions of this page recommended --pruning validator and quoted fixed storage sizes for it; those sizes did not apply.

Size your disk from the System Requirements and watch free space: a full disk stops your node, and the symptom looks like a consensus problem rather than a disk problem.

df -h /opt/vexidus
sudo du -sh /opt/vexidus/data

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
# Vextaris 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 "  Vextaris 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 is available via RotateConsensusKey (disc 119) — queued and applied at next epoch boundary, max 1 per epoch

Network

RPC port (9933): Never expose to the public internet. Bind to 127.0.0.1 or restrict via firewall.
P2P port (9946): 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

The upgrade authority (or validator vote in full mode) schedules an upgrade at a future block height
All nodes see the approved upgrade plan on-chain
At the target height, your node writes data/upgrade-info.json and exits with code 42
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
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	Use case
`seed-authority`	A designated upgrade authority approves scheduled upgrades	Bootstrapping / private networks
`full`	Stake-weighted validator vote (67% quorum, configurable)	Production networks

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

Chain-Data Integrity Tools

Three optional flags help you catch RocksDB corruption before consensus consumes it. All are off by default — opt in as you see fit.

# One-shot scan at startup. Walks every well-known structured-record prefix
# and exits with a non-zero status if any entry fails to deserialise.
vexidus-node --verify-on-start

# Background sweep on a configurable interval. Reports anomalies via the
# node log without restarting. Recommended for validators: every 1 hour.
vexidus-node --rocksdb-verify-interval-secs 3600

# Dry-run a state.json snapshot into a temporary database. Live data dir
# is untouched. Useful before any real --import-state.
vexidus-node --dry-run-import ./state-export.json

A non-zero exit from --verify-on-start or --dry-run-import means a malformed record was found. Investigate before serving traffic — log lines list up to the first ten offending keys.

Maintenance

Manual upgrades

VexVisor applies scheduled upgrades on its own. If you must swap the binary by hand, verify it and replace the one your unit actually runs:

curl -fSL -o vexidus-node https://vexidus.io/releases/vexidus-node
curl -fsSL -o SHA256SUMS https://vexidus.io/releases/SHA256SUMS
grep vexidus-node SHA256SUMS | sha256sum --check -    # must print: vexidus-node: OK

sudo systemctl stop vexidus-validator
sudo install -m 755 -o vexidus -g vexidus vexidus-node /opt/vexidus/vexvisor/current/vexidus-node
sudo systemctl start vexidus-validator
sudo journalctl -u vexidus-validator -n 20 --no-pager

Copying the binary to /usr/local/bin has no effect -- the unit runs /opt/vexidus/vexvisor/current/vexidus-node. If the upgrade also changed the network flags, regenerate your unit as described in Configure Your Node.

warning

Without VexVisor you risk being jailed if you miss an upgrade window. Run it on 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 :9946`
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 9946/udp is open: nc -zuv YOUR_PUBLIC_IP 9946 from another machine
Confirm --external-addr matches your actual public IP
Check a bootnode is reachable: nc -zuv 158.69.203.54 9944 (NA seed; Zurich and Singapore use 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 for double-sign violations (producing conflicting blocks at the same height). Jailed validators cannot produce blocks or earn rewards. Jail durations escalate: 1h → 24h → 7d → 30d. After the jail period expires, 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/tools/vexvisor.sh`	VexVisor upgrade wrapper script
`/etc/systemd/system/vexidus-validator.service`	Node configuration (all flags)
`/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]

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>               Accepted but currently has no effect (see Storage and Pruning)
      --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:
      --enforce-validator-allowlist  Only allow authenticated validator peers to gossip blocks
      --rpc-rate-limit <N>           Per-IP RPC rate limit in requests/second [default: 100, 0 = unlimited]

  -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 with a neutral reputation score of 50 (on the 0-100 scale).

Table of Contents​

Overview​

System Requirements​

Minimum​

Recommended​

Required Ports​

Required Tools​

Install Vextaris​

Quick Install (one command)​

Manual Install​

1. Install system dependencies​

2. Download the released binary​

3. Install the binary​

4. Fetch the network flag set​

5. Create system user and directories​

Generate Your Validator Key​

Generate the key​

Move to secure location​

View your public key​

Back up your key​

Bootstrap Your Node​

Serve Snapshots to Other Validators​

Configure Your Node​

Create the systemd service​

Start Your Node (VexVisor)​

Set up VexVisor​

Start and enable​

Verify it is running​

Watch the logs​

Wait for sync​

Stake and Register as a Validator​

Get Testnet VXS​

Check your balance​

Stake VXS (minimum 1,000)​

Verify your registration​

Set your validator profile​

Set commission rate​

Auto-Compound Rewards​

Staking Pool Configuration (Validators)​

Gas and Transaction Fees​

Connect to the Network​

Bootstrap Nodes​

NAT and Firewalls​

Verify peer connectivity​

Firewall setup (ufw)​

Storage and Pruning​

Node Modes​

Prometheus Metrics​

Monitoring​

Quick health check​

Logs​

Monitoring script​

Security Best Practices​

Key Management​

Network​

System Hardening​

Automatic Upgrades (VexVisor)​

How it works​

Grace period​

What you need to do​

Governance modes​

Chain-Data Integrity Tools​

Maintenance​

Manual upgrades​

Unstaking​

Full resync (wipe chain data)​

Troubleshooting​

Node will not start​

No peers connecting​

Node not producing blocks​

Validator is jailed​

RPC not responding​

Key Files Reference​

CLI Reference​

Testnet Rewards​

Links​

Table of Contents