Running a Masternode

Learn how to set up and run a Viction masternode with staking enabled

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

1. Prepare your account

   Create or import an account that holds your masternode stake:

   Create New Account

   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.

2. Register on VicMaster

   Before running your masternode, you must:

   1. Hold at least 50,000 VIC tokens in your account
   2. Register your masternode on VicMaster
   3. Provide your node’s coinbase address
   4. 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.

3. 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:[e-mail] \
     --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
4. 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

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

Peer Management

Configure peer connections:

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

Port Configuration

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:

1. At startup: Checks if the unlocked account is a valid masternode
2. At checkpoints: Re-validates masternode status
3. Auto-enable: Starts staking if masternode is valid
4. 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

1. 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
2. Network

   • Ensure stable, high-bandwidth internet
   • Configure firewall rules properly
   • Set up DDoS protection
   • Use static IP address
3. 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:[e-mail]
   
4. 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