Quantus Network Mining Guide

Get started mining on the Quantus Network testnet in minutes.

Important: Wormhole Address System

⚠️ Mining rewards are automatically sent to wormhole addresses derived from your preimage.

You provide a 32-byte preimage when starting mining
The system derives your wormhole address using Poseidon hashing
All mining rewards are sent to this derived wormhole address
This ensures all miners use privacy-preserving wormhole addresses

System Requirements

Minimum Requirements

CPU: 2+ cores
RAM: 4GB
Storage: 100GB available space
Network: Stable internet connection
OS: Linux (Ubuntu 20.04+), macOS (10.15+), or Windows WSL2

Recommended Requirements

CPU: 4+ cores (higher core count improves mining performance - coming soon)
RAM: 8GB+
Storage: 500GB+ SSD
Network: Broadband connection (10+ Mbps)

Setup

Manual Installation

If you prefer manual installation or the script doesn't work for your system:

Download Binary

Get the latest binary GitHub Releases

Generate Node Identity

./quantus-node key generate-node-key --file ~/.quantus/node_key.p2p

Generate Wormhole Address & Preimage
```
./quantus-node key quantus --scheme wormhole
```
This generates a wormhole key pair and shows:
- Address: Your wormhole address (where rewards will be sent)
- inner_hash: Your 32-byte preimage (use this for mining)
Save the preimage - you'll need it for the --rewards-address parameter.
Run the node (Dirac testnet)

Minimal command - see --help for many more options

./quantus-node \
    --validator \
    --chain dirac \
    --node-key-file ~/.quantus/node_key.p2p \
    --rewards-preimage <YOUR_PREIMAGE_FROM_STEP_3> \
    --max-blocks-per-request 64 \
    --sync full

Note: Use the inner_hash from step 3 as your --rewards-preimage. The node will derive your wormhole address and log it on startup.

Docker Installation

For users who prefer containerized deployment or have only Docker installed:

Quick Start with Docker

Follow these steps to get your Docker-based validator node running:

Step 1: Prepare a Local Directory for Node Data

Create a dedicated directory on your host machine to store persistent node data, such as your P2P key and rewards address file.

mkdir -p ./quantus_node_data

This command creates a directory named quantus_node_data in your current working directory.

Optional Linux On linux you may need to make sure this directory has generous permissions so Docker can access it

chmod 755 quantus_node_data

Step 2: Generate Your Node Identity (P2P Key)

Your node needs a unique P2P identity to connect to the network. Generate this key into your data directory:

# If on Apple Silicon, you may need to add --platform linux/amd64
docker run --rm --platform linux/amd64 \
  -v "$(pwd)/quantus_node_data":/var/lib/quantus_data_in_container \
  ghcr.io/quantus-network/quantus-node:latest \
  key generate-node-key --file /var/lib/quantus_data_in_container/node_key.p2p

Replace quantus-node:v0.0.4 with your desired image (e.g., ghcr.io/quantus-network/quantus-node:latest). This command saves node_key.p2p into your local ./quantus_node_data directory.

Step 3: Generate Your Wormhole Address

# If on Apple Silicon, you may need to add --platform linux/amd64
docker run --rm ghcr.io/quantus-network/quantus-node:latest key quantus --scheme wormhole

This generates a wormhole key pair. Save the inner_hash value - this is your preimage for mining.

Step 4: Run the Validator Node

# If on Apple Silicon, you may need to add --platform linux/amd64
# Replace YOUR_PREIMAGE with the inner_hash from step 3
docker run -d \
  --name quantus-node \
  --restart unless-stopped \
  -v "$(pwd)/quantus_node_data":/var/lib/quantus \
  -p 30333:30333 \
  -p 9944:9944 \
  ghcr.io/quantus-network/quantus-node:latest \
  --validator \
  --base-path /var/lib/quantus \
  --chain dirac \
  --node-key-file /var/lib/quantus/node_key.p2p \
  --rewards-preimage <YOUR_PREIMAGE>

Note for Apple Silicon (M1/M2/M3) users: As mentioned above, if you are using an amd64 based Docker image on an ARM-based Mac, you will likely need to add the --platform linux/amd64 flag to your docker run commands.

Your node should now be starting up! You can check its logs using docker logs -f quantus-node.

Docker Management Commands

View logs

docker logs -f quantus-node

Stop node

docker stop quantus-node

Start node again

docker start quantus-node

Remove container

docker stop quantus-node && docker rm quantus-node

Updating Your Docker Node

When a new version is released:

# Stop and remove current container
docker stop quantus-node && docker rm quantus-node

# Pull latest image
docker pull ghcr.io/quantus-network/quantus-node:latest

# Start new container (data is preserved in ~/.quantus)
./run-node.sh --mode validator --rewards YOUR_ADDRESS_HERE

Docker-Specific Configuration

Custom data directory

./run-node.sh --data-dir /path/to/custom/data --name "my-node"

Specific version

docker run -d \
  --name quantus-node \
  --restart unless-stopped \
  -p 30333:30333 \
  -p 9944:9944 \
  -v ~/.quantus:/var/lib/quantus \
  ghcr.io/quantus-network/quantus-node:latest \
  --validator \
  --base-path /var/lib/quantus \
  --chain dirac \
  --rewards-address YOUR_ADDRESS_HERE

Docker system requirements

Docker 20.10+ or compatible runtime
All other system requirements same as binary installation

External Miner Setup

For high-performance mining, you can offload the QPoW mining process to a separate service, freeing up node resources.

Prerequisites

Build Node:

# From workspace root
cargo build --release -p quantus-node

Get External Miner:

git clone https://github.com/Quantus-Network/quantus-miner
cd quantus-miner
cargo build --release

Setup with Wormhole Addresses

Generate Your Wormhole Address:
```
./quantus-node key quantus --scheme wormhole
```
Save the inner_hash value.
Start External Miner (in separate terminal):
```
RUST_LOG=info ./target/release/quantus-miner
```
(Default: http://127.0.0.1:9833)

Start Node with External Miner (in another terminal):

# Replace <YOUR_PREIMAGE> with the inner_hash from step 1
RUST_LOG=info,sc_consensus_pow=debug ./target/release/quantus-node \
 --validator \
 --chain dirac \
 --external-miner-url http://127.0.0.1:9833 \
 --rewards-preimage <YOUR_PREIMAGE>

Configuration Options

Node Parameters

Parameter	Description	Default
`--node-key-file`	Path to P2P identity file	Required
`--rewards-preimage`	Wormhole preimage (inner_hash from key generation)	Required
`--chain`	Chain specification	`dirac`
`--port`	P2P networking port	`30333`
`--prometheus-port`	Metrics endpoint port	`9616`
`--name`	Node display name	Auto-generated
`--base-path`	Data directory	`~/.local/share/quantus-node`

Monitoring Your Node

Check Node Status

View Logs

# Real-time logs
tail -f ~/.local/share/quantus-node/chains/dirac/network/quantus-node.log

# Or run with verbose logging
RUST_LOG=info quantus-node [options]

Prometheus Metrics Visit http://localhost:9616/metrics to view detailed node metrics.

RPC Endpoint Use the RPC endpoint at http://localhost:9944 to query blockchain state:

# Check latest block
curl -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"chain_getBlock","params":[]}' \
  http://localhost:9944

Check Mining Rewards

View Balance at Your Wormhole Address

# Replace YOUR_WORMHOLE_ADDRESS with your wormhole address from key generation
curl -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"faucet_getAccountInfo","params":["YOUR_WORMHOLE_ADDRESS"]}' \
  http://localhost:9944

Find Your Wormhole Address

From key generation: Use the Address field from ./quantus-node key quantus --scheme wormhole
From node logs: Check startup logs for "Mining rewards will be sent to wormhole address"

Testnet Information

Chain: Dirac Testnet
Consensus: Quantum Proof of Work (QPoW)
Block Time: ~6 seconds target
Network Explorer: Coming soon
Faucet: See Telegram

Troubleshooting

Common Issues

Port Already in Use

# Use different ports
quantus-node --port 30334 --prometheus-port 9617 [other options]

Database Corruption

# Purge and resync
quantus-node purge-chain --chain dirac

Mining Not Working

Check that --validator flag is present
Verify your preimage from inner_hash field in key generation
Ensure node is synchronized (check logs for "Imported #XXXX")

Wormhole Address Issues

Can't find rewards: Check the Address field from your key generation
Invalid preimage: Use the exact inner_hash value from key generation
Wrong address: Rewards go to the wormhole address, not the preimage

Connection Issues

Check firewall settings (allow port 30333)
Verify internet connection
Try different bootnodes if connectivity problems persist

Getting Help

GitHub Issues: Report bugs and issues
Discord: Join our community (link coming soon)
Documentation: Technical docs

Logs and Diagnostics

Enable Debug Logging

RUST_LOG=debug,sc_consensus_pow=trace quantus-node [options]

Export Node Info

# Node identity
quantus-node key inspect-node-key --file ~/.quantus/node_key.p2p

# Network info
curl -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"system_networkState","params":[]}' \
  http://localhost:9944

Mining Economics

Wormhole Address Rewards System

Automatic Wormhole Addresses: All mining rewards go to your wormhole address
Privacy by Design: Your reward address is derived from your preimage
Block Rewards: Earned by successfully mining blocks
Transaction Fees: Collected from transactions in mined blocks
Network Incentives: Additional rewards for network participation

Expected Performance

Mining performance depends on:

CPU performance (cores and clock speed)
Network latency to other nodes
Node synchronization status
Competition from other miners

Security Best Practices

Key Management

Backup Your Keys: Securely store your wormhole key pair from key generation
Backup Node Keys: Store copies of your node identity keys safely
Secure Storage: Keep preimages and private keys in encrypted storage

Node Security

Firewall: Only expose necessary ports (30333 for P2P)
Updates: Keep your node binary updated
Monitoring: Watch for unusual network activity or performance

Testnet Disclaimer

This is testnet software for testing purposes only:

Tokens have no monetary value
Network may be reset periodically
Expect bugs and breaking changes
Do not use for production workloads

Next Steps

Join the Community: Connect with other miners and developers
Monitor Performance: Track your mining efficiency and rewards at your wormhole address
Experiment: Try different configurations and optimizations
Contribute: Help improve the network by reporting issues and feedback

Happy mining! 🚀

For technical support and updates, visit the Quantus Network GitHub repository.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Quantus Network Mining Guide

Important: Wormhole Address System

System Requirements

Minimum Requirements

Recommended Requirements

Setup

Manual Installation

Docker Installation

Quick Start with Docker

Docker Management Commands

Updating Your Docker Node

Docker-Specific Configuration

External Miner Setup

Prerequisites

Setup with Wormhole Addresses

Configuration Options

Node Parameters

Monitoring Your Node

Check Node Status

Check Mining Rewards

Testnet Information

Troubleshooting

Common Issues

Getting Help

Logs and Diagnostics

Mining Economics

Wormhole Address Rewards System

Expected Performance

Security Best Practices

Key Management

Node Security

Testnet Disclaimer

Next Steps

FilesExpand file tree

MINING.md

Latest commit

History

MINING.md

File metadata and controls

Quantus Network Mining Guide

Important: Wormhole Address System

System Requirements

Minimum Requirements

Recommended Requirements

Setup

Manual Installation

Docker Installation

Quick Start with Docker

Docker Management Commands

Updating Your Docker Node

Docker-Specific Configuration

External Miner Setup

Prerequisites

Setup with Wormhole Addresses

Configuration Options

Node Parameters

Monitoring Your Node

Check Node Status

Check Mining Rewards

Testnet Information

Troubleshooting

Common Issues

Getting Help

Logs and Diagnostics

Mining Economics

Wormhole Address Rewards System

Expected Performance

Security Best Practices

Key Management

Node Security

Testnet Disclaimer

Next Steps