Running a Masternode

A masternode is a special type of full node that participates in block validation and creation. Viction relies on a system of 150 masternodes with a Proof of Stake Voting (PoSV) consensus mechanism.

What is a Masternode?

Viction masternodes:

Validate and create new blocks
Participate in the PoSV consensus mechanism
Earn block rewards and transaction fees
Require staking to be eligible
Must maintain high uptime and performance

Requirements

Hardware

8GB+ RAM
4+ CPU cores
500GB+ SSD storage
100Mbps+ network

Staking

50,000 VIC tokens
Registered on VicMaster
Active voting support
Unlocked account

Running a masternode requires a significant stake and technical expertise. Ensure you understand the requirements and risks before proceeding.

Masternode Setup

Prepare your account

Create or import an account that holds your masternode stake:

tomo account new --password /path/to/password_file --keystore /path/to/keystore_dir

Save your keystore files and password securely. Loss of these files means loss of access to your funds.

Before running your masternode, you must:

Hold at least 50,000 VIC tokens in your account
Register your masternode on VicMaster
Provide your node’s coinbase address
Wait for community voting to reach the top 150

Your node will only produce blocks if it’s in the top 150 masternodes by voting power.

Configure and start the node

Run your node with staking enabled:

tomo --datadir /path/to/data_dir \
  --keystore /path/to/keystore_dir \
  --password /path/to/password_file --unlock 0 \
  --identity my-masternode \
  --networkid 88 \
  --syncmode "full" --gcmode "full" \
  --mine \
  --gasprice 250000000 \
  --targetgaslimit 30000000 \
  --rpc --rpcaddr 0.0.0.0 --rpcport 8545 --rpcvhosts "*" --rpccorsdomain "*" \
  --rpcapi "eth,net,web3,posv" \
  --ws --wsaddr 0.0.0.0 --wsport 8546 --wsorigins "*" \
  --port 30303 \
  --maxpeers 25 \
  --ethstats my-masternode:getty-site-pablo-auger-room-sos-blair-shin-whiz-delhi@stats.viction.xyz \
  --verbosity 3

Key flags for masternodes:

--mine: Enables staking/mining mode
--unlock 0: Unlocks your account for signing blocks
--gasprice 250000000: Sets minimum gas price for transactions
--targetgaslimit 30000000: Sets target gas limit for blocks

Verify masternode status

Check that your masternode is recognized:

curl -X POST --data '{"jsonrpc":"2.0","method":"posv_getMasternodes","params":[],"id":1}' \
  -H "Content-Type: application/json" http://localhost:8545

Monitor your node on:

VicScan - View your masternode status
Network Stats - Real-time network monitoring

Masternode-Specific Configuration

Staking Options

mine

boolean

required

Enables staking mode. Your node will participate in block creation if it’s a valid masternode.

minerthreads

number

Number of CPU threads to use for staking operations (default: 1)

--minerthreads 2

etherbase

string

Public address for block mining rewards. If not specified, uses the first unlocked account.

--etherbase 0x1234567890123456789012345678901234567890

targetgaslimit

number

Target gas limit for blocks (default: 30000000)

--targetgaslimit 30000000

gasprice

number

Minimum gas price to accept for mining transactions (in wei)

--gasprice 250000000

API Configuration

For masternodes, enable the PoSV API to allow querying consensus-specific data:

--rpcapi "eth,net,web3,posv"

Available APIs:

eth: Standard Ethereum JSON-RPC
net: Network information
web3: Web3 utilities
posv: Viction consensus data
debug: Debug APIs (use with caution)
personal: Account management (use with caution)

Network Configuration

NAT Configuration
Peer Management
Port Configuration

If your node is behind NAT, configure external IP:

--nat extip:YOUR_PUBLIC_IP

Other NAT options:

--nat any        # Automatic NAT detection
--nat upnp       # Use UPnP
--nat pmp        # Use NAT-PMP
--nat none       # Disable NAT

Configure peer connections:

--maxpeers 25                  # Maximum number of peers
--maxpendpeers 10              # Maximum pending peer connections
--bootnodes "enode://..."      # Custom bootnodes

Ensure these ports are accessible:

--port 30303      # P2P port (must be open)
--rpcport 8545    # HTTP-RPC port
--wsport 8546     # WebSocket-RPC port

Port 30303 must be open for P2P communication. Masternodes with blocked ports may be penalized.

Masternode Operations

Automatic Validation

The Viction node automatically detects if your account is a registered masternode:

At startup: Checks if the unlocked account is a valid masternode
At checkpoints: Re-validates masternode status
Auto-enable: Starts staking if masternode is valid
Auto-disable: Stops staking if masternode status is lost

From the logs (cmd/tomo/main.go:312-359):

ok, err := ethereum.ValidateMasternode()
if ok {
    log.Info("Masternode found. Enabling staking mode...")
    ethereum.StartStaking(true)
    log.Info("Enabled mining node!!!")
}

Monitoring Masternode Status

Your node logs will show:

INFO Masternode found. Enabling staking mode...
INFO Enabled mining node!!!

If you see:

WARN Only masternode can propose and verify blocks. Cancelling staking on this node...

This means your node is not recognized as a masternode. Check:

Registration on VicMaster
Voting power (must be in top 150)
Unlocked account matches registered address

Reward Collection

Storing Reward Reports

To track masternode rewards:

--store-reward --gcmode archive

--store-reward requires archive mode and significantly increases disk usage. Only enable if you need historical reward data.

Rewards are stored in: {datadir}/tomo/rewards/

Reward Distribution

Masternodes earn:

Block rewards: For creating blocks
Transaction fees: From transactions in created blocks
Voter rewards: Distributed to voters who staked with your masternode

Rewards are automatically distributed to the coinbase address at the end of each epoch.

High Availability Setup

Infrastructure

Use dedicated servers with high uptime SLAs
Implement monitoring and alerting
Set up automatic restarts on failure
Use SSD storage for better I/O performance

Network

Ensure stable, high-bandwidth internet
Configure firewall rules properly
Set up DDoS protection
Use static IP address

Monitoring

Monitor these metrics:

Node sync status
Peer count
Block creation rate
System resources (CPU, RAM, disk)
Network connectivity

Enable ethstats reporting:

--ethstats your-node:[email protected]

Backup

Regularly backup keystore files
Store backups securely offline
Document recovery procedures
Test recovery process

Performance Tuning

Thread Configuration

--minerthreads 2  # Adjust based on CPU cores

Memory Optimization

--cache 2048               # Total cache size in MB
--cache.database 75        # Database cache percentage
--cache.gc 25              # GC cache percentage

Transaction Pool

--txpool.globalslots 8192  # Total executable transaction slots
--txpool.globalqueue 2048  # Total non-executable transaction slots
--txpool.accountslots 16   # Per-account executable slots
--txpool.accountqueue 64   # Per-account non-executable slots

Troubleshooting

Masternode not mining

Check:

Account is unlocked: --unlock 0
Mining is enabled: --mine
Node is registered on VicMaster
Node is in top 150 by voting power
Node is fully synced
Logs show “Masternode found. Enabling staking mode…”

Lost masternode status

If your node stops mining:

Check voting power on VicMaster
Verify account balance meets minimum stake
Ensure node hasn’t been penalized for downtime
Check if account is still unlocked

High resource usage

Optimize:

Reduce --cache value
Lower --minerthreads
Use --gcmode full instead of archive
Reduce --maxpeers
Disable --store-reward if not needed

Network connectivity issues

Verify port 30303 is open
Check firewall rules
Try adding bootnodes manually
Verify NAT configuration
Check if IP is blacklisted

Security Best Practices

Key Management

Never share private keys
Use hardware security modules for production
Regularly rotate passwords
Keep keystore backups offline

Network Security

Use firewall to restrict RPC access
Don’t expose personal API publicly
Enable HTTPS for RPC endpoints
Implement rate limiting

System Security

Keep OS and software updated
Use non-root user for node process
Enable disk encryption
Monitor system logs

Operational Security

Monitor node 24/7
Set up automated alerts
Have incident response plan
Regular security audits

Next Steps

Configuration Reference

Complete list of all configuration flags

Docker Deployment

Deploy your masternode with Docker

Get Started

Core Concepts

Node Operations

Features

Development

Operations

Running a Masternode

What is a Masternode?

Requirements

Hardware

Staking

Masternode Setup

Masternode-Specific Configuration

Staking Options

API Configuration

Network Configuration

Masternode Operations

Automatic Validation

Monitoring Masternode Status

Reward Collection

Storing Reward Reports

Reward Distribution

High Availability Setup

Performance Tuning

Thread Configuration

Memory Optimization

Transaction Pool

Troubleshooting

Security Best Practices

Key Management

Network Security

System Security

Operational Security

Next Steps

Configuration Reference

Docker Deployment

Build docs developers (and LLMs) love

Get Started

Core Concepts

Node Operations

Features

Development

Operations

​What is a Masternode?

​Requirements

Hardware

Staking

​Masternode Setup

​Masternode-Specific Configuration

​Staking Options

​API Configuration

​Network Configuration

​Masternode Operations

​Automatic Validation

​Monitoring Masternode Status

​Reward Collection

​Storing Reward Reports

​Reward Distribution

​High Availability Setup

​Performance Tuning

​Thread Configuration

​Memory Optimization

​Transaction Pool

​Troubleshooting

​Security Best Practices

Key Management

Network Security

System Security

Operational Security

​Next Steps

Configuration Reference

Docker Deployment

Build docs developers (and LLMs) love

What is a Masternode?

Requirements

Masternode Setup

Masternode-Specific Configuration

Staking Options

API Configuration

Network Configuration

Masternode Operations

Automatic Validation

Monitoring Masternode Status

Reward Collection

Storing Reward Reports

Reward Distribution

High Availability Setup

Performance Tuning

Thread Configuration

Memory Optimization

Transaction Pool

Troubleshooting

Security Best Practices

Next Steps