Run a Neoxa Smartnode

Requirements

Collateral

1,000,000 NEOX locked in your control wallet. The collateral never leaves your wallet, and never goes to the VPS - it stays on the desktop QT. Moving or spending the 1M will deregister the smartnode immediately.

Hardware (VPS)

VPS picks

Any VPS with the specs above works. These are providers known to work well with Neoxa, ordered roughly by price.

01Initial server setup

SSH into your VPS as root (or use sudo) and update the system.

sudo su
apt update && sudo apt upgrade -y && sudo apt install -y unzip fail2ban

02Add 4 GB swap

Even with 4 GB of RAM, swap protects against OOM kills during chain sync.

swapon --show
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

03Configure UFW firewall

Lock down everything except SSH and the smartnode P2P port (8788).

sudo apt install ufw -y
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow ssh
sudo ufw allow 8788/tcp
sudo ufw enable

04Set up fail2ban

Protect SSH from brute-force.

sudo nano /etc/fail2ban/jail.local

Paste:

[sshd]
enabled = true
port = 22
logpath = /var/log/auth.log
maxretry = 3

Save (Ctrl+O, Enter, Ctrl+X) and reboot the VPS so the swap, firewall, and jail are all applied:

sudo reboot

Reconnect via SSH after ~30 seconds.

05Create the Neoxa user and install the daemon

Run the daemon as a non-root user. Replace new_username with whatever you want (e.g. neoxa).

sudo adduser new_username
sudo su new_username
mkdir neoxa
cd neoxa
wget https://github.com/NeoxaChain/Neoxa/releases/download/v5.1.1.4/neoxad-5.1.1.4-linux64.zip
unzip neoxad-5.1.1.4-linux64.zip
sudo chmod +x neoxad neoxa-cli
mkdir ~/.neoxacore && touch ~/.neoxacore/neoxa.conf

06Set up the local control wallet

The control wallet runs on your desktop, not the VPS. It holds the 1M NEOX collateral and signs the registration. Pick the right binary:

• Linux desktop: neoxaqt-5.1.1.4-linux64.zip
• macOS: neoxaqt-5.1.1.4-osx.zip
• Windows: see the releases page for the .exe

In Neoxa Core QT:

1. Wait for full sync. Won't work until the wallet is fully caught up.
2. Settings → Encrypt Wallet. Set a strong passphrase and write it down.
3. Generate a receiving address (File → Receiving addresses → New).
4. Backup wallet.dat (File → Backup Wallet) to two safe locations.
5. Send exactly 1,000,000 NEOX to the address from step 3. Send to yourself; do not send less, do not split.
6. Wait for at least 1 confirmation on the collateral tx.

07Run protx quick_setup

Open the Debug Console in QT (Tools → Debug Console). You need four pieces of info:

1. Collateral txid

In the QT main wallet, go to Transactions, right-click the 1M NEOX tx, and copy Transaction ID.

2. Collateral output index

In the Debug Console:

smartnode outputs

You'll see something like { "abc123...": "0" }. The number after the colon is the output index (usually 0 or 1).

3. Your VPS public IPv4

On the VPS:

curl -4 ifconfig.co

Use the returned IP with port 8788.

4. A fee address (needs ~0.005 NEOX)

In the QT Debug Console:

listaddressbalances

Pick any address that holds at least 0.005 NEOX - the registration tx pays a tiny fee from this address.

Run quick_setup

In the QT Debug Console, substitute the four values you collected:

protx quick_setup <txid> <collateralIndex> <ip>:8788 <feeAddress>

QT prints a configuration block: BLS keys, owner / voting / payout addresses, and a ready-made neoxa.conf. Copy the entire block. The BLS private key in particular cannot be recovered later.

08Apply the config and start the node

Back on the VPS, stop the daemon if it's running:

~/neoxa/neoxa-cli stop

Open the config file and paste the block from quick_setup:

nano ~/.neoxacore/neoxa.conf

Save (Ctrl+O, Enter, Ctrl+X). Start the daemon:

~/neoxa/neoxad

It'll fork into the background. Wait for it to sync to the chain tip (about 10-30 minutes from a fresh server). Check sync status:

~/neoxa/neoxa-cli getblockchaininfo | grep -E '"blocks|verificationprogress'

Once verificationprogress is at 1.0:

~/neoxa/neoxa-cli smartnode status

You'll see "status": "Ready" within a few blocks. The official notice: "It takes a few blocks for your smartnode to be confirmed on the network."

Monitoring

Three commands to keep handy:

# am I synced and registered?
~/neoxa/neoxa-cli smartnode status

# what's my POSe (proof of service) score? lower is better, 0 = perfect
~/neoxa/neoxa-cli protx info <your-proTxHash> | grep -E 'PoSeScore|PoSeBan'

# when was my last paid block?
~/neoxa/neoxa-cli smartnode status | grep -E 'lastpaidblock|lastpaidtime'

If PoSeScore climbs above 0 it means the network missed a heartbeat from your node. Persistent score growth leads to a ban. Restart the daemon, check that port 8788 is reachable from outside, and confirm the BLS public key matches what was registered.

Auto-restart on crash

Wrap the daemon in a systemd service so it always comes back:

sudo nano /etc/systemd/system/neoxa.service

Paste (replace new_username):

[Unit]
Description=Neoxa daemon
After=network.target

[Service]
User=new_username
Type=forking
ExecStart=/home/new_username/neoxa/neoxad
ExecStop=/home/new_username/neoxa/neoxa-cli stop
Restart=on-failure
RestartSec=15
TimeoutStartSec=120

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable neoxa
sudo systemctl start neoxa
sudo systemctl status neoxa

Service-info updates

If you change VPS, IP, or BLS keys, you need to register the change on chain. From the QT Debug Console (the wallet that owns the collateral):

protx update_service <proTxHash> <newIp>:8788 <newBlsKey> "" <feeAddress>

• The 4th argument is the operator payout script. Pass "" when there's no separate operator reward.
• Get your proTxHash via ~/neoxa/neoxa-cli smartnode status on the VPS.
• To get a new BLS keypair: ~/neoxa/neoxa-cli bls generate.

Upgrade the daemon

~/neoxa/neoxa-cli stop
cd ~/neoxa
wget https://github.com/NeoxaChain/Neoxa/releases/download/v<NEW_VERSION>/neoxad-<NEW_VERSION>-linux64.zip
unzip -o neoxad-<NEW_VERSION>-linux64.zip
sudo chmod +x neoxad neoxa-cli
sudo systemctl restart neoxa     # if using systemd
~/neoxa/neoxa-cli getblockchaininfo

Troubleshooting

"smartnode status: Failed"

Almost always means the node can't be reached from outside on port 8788. Check from another machine:

nc -zv <your-vps-ip> 8788

If it fails: confirm ufw status shows 8788/tcp ALLOW, and that your VPS provider's network firewall (Hetzner/OVH/Vultr have these) also allows it.

"PoSeBan" set to true

The network has banned your node for repeated heartbeat failures. To revive it: fix the issue (network, daemon crash, etc.) then run from QT:

protx update_service <proTxHash> <ip>:8788 <blsKey> "" <feeAddress>

This re-announces the node and clears the ban.

Daemon won't start: "Cannot obtain a lock on data directory"

Another neoxad process is already running. Kill it:

pkill -9 neoxad
sleep 2
~/neoxa/neoxad

Out of memory during sync

Either you skipped the swap step (do it) or your VPS has less than 4 GB. Add more swap or upgrade the VPS.

Sync stuck at the same block for 10+ minutes

Restart the daemon. If it persists, check ~/.neoxacore/debug.log for errors. Often a peer issue; the daemon picks new peers on restart.

What's next

Once your node is Ready:

• Payment cadence. The pay queue rotates by registration order. Expected payment interval is roughly (active_smartnode_count × block_time) - check current count at assets.neoxa.net/smartnode-count.
• Verify on chain. Look up your proTxHash on a block explorer and confirm the registered IP, BLS key, and payout address match what you intended.
• Watch your POSe score. 0 means the network is happy with your node. Anything else: investigate before it bans.
• Don't touch the collateral. Seriously. Withdrawing or sending the 1M NEOX deregisters instantly and you lose your queue position.