Supernova is a production-grade proof-of-work blockchain implementation written in Rust. It leverages Rust's safety features and performance characteristics to provide a secure, efficient, and modular blockchain platform. Supernova demonstrates modern blockchain architecture and best practices while offering a complete set of features needed for a fully functional blockchain network.
- Robust Consensus: Proof-of-work consensus mechanism with advanced difficulty adjustment
- Efficient Data Model: UTXO-based transaction model with comprehensive validation
- High Performance: Multi-threaded mining and parallel block validation
- Advanced Networking: P2P communication built on libp2p with optimized block synchronization
- Data Security: Multiple layers of data integrity verification and automated recovery
- Modern Architecture: Modular, component-based design with clear separation of concerns
- Production Ready: Comprehensive monitoring, backup systems, and disaster recovery
Supernova follows a modular architecture with several key components:
-
Core Library (btclib)
- Foundational data structures (blocks, transactions)
- Cryptographic primitives and validation
- Merkle tree implementation
- UTXO model
-
Node
- P2P network communication
- Block and transaction propagation
- Chain synchronization
- Mempool management
- Storage and persistence
- Advanced disaster recovery
-
Miner
- Multi-threaded mining framework
- Block template creation
- Dynamic difficulty adjustment
- Mining reward distribution
-
Wallet
- Key management and address generation
- Transaction creation and signing
- UTXO tracking and management
- Transaction history and labeling
- Multi-address support with HD wallet functionality
This project is currently in an ALPHA state. Core functionality is implemented and operational, with approximately 95% completion across all major components:
- ✅ Core libraries (btclib): 100% complete with stable APIs
- ✅ Network layer: 95% complete with advanced peer scoring system
- ✅ Storage layer: 90% complete with proper persistence and recovery
- ✅ Mempool: 90% complete with transaction storage and prioritization
- ✅ Mining: 95% complete with fully operational mining system
- ✅ Chain sync: 95% complete with headers-first synchronization protocol
- ✅ Wallet: 85% complete with fully functional CLI and HD wallet implementation
⚠️ API services: Limited implementation, needs expansion
- Rust 1.70.0 or higher
- OpenSSL development libraries
- A Unix-like operating system (Linux, macOS)
# Install required dependencies on Ubuntu/Debian
sudo apt update
sudo apt install -y build-essential pkg-config libssl-dev
# On macOS with Homebrew
brew install openssl pkg-config# Clone the repository
git clone https://github.com/username/supernova.git
cd supernova
# Build all components
cargo build --release
# Run tests
cargo test --all# Create a configuration file (if not using the default)
cp config/node.example.toml config/node.toml
# Start a node
./target/release/nodeSupernova uses TOML for configuration. A basic node.toml looks like:
[node]
chain_id = "supernova-mainnet"
environment = "Production"
metrics_enabled = true
metrics_port = 9000
[network]
listen_addr = "/ip4/0.0.0.0/tcp/8000"
max_peers = 50
bootstrap_nodes = [
"/ip4/203.0.113.1/tcp/8000/p2p/QmRZf8wnY2HbQP4h6jtKnHBuEF3V59uCnYx9winHcwUwNX",
"/ip4/203.0.113.2/tcp/8000/p2p/QmP7HvWHJwJmPWGHH1XtKuKCrFCbjCSRHZ6bA8n5QkRfzC"
]
[storage]
db_path = "./data"
backup_dir = "./backups"
[mempool]
max_size = 5000
max_per_address = 100The Supernova wallet provides a command-line interface for managing NOVA tokens and creating transactions.
# Create a new wallet
./target/release/wallet new
# Get wallet address
./target/release/wallet address
# Check wallet balance
./target/release/wallet balance
# Send NOVA tokens
./target/release/wallet send --to <RECIPIENT_ADDRESS> --amount <AMOUNT> --fee <FEE>
# List Unspent Transaction Outputs (UTXOs)
./target/release/wallet list-utxos
# View transaction history
./target/release/wallet history
# Create a new address (HD wallet)
./target/release/wallet new-address
# List all addresses
./target/release/wallet list-addresses
# Label a transaction
./target/release/wallet label-tx --txid <TRANSACTION_ID> --label "Grocery payment"| Command | Description |
|---|---|
new |
Creates a new wallet and generates a key pair |
address |
Displays the wallet's current public address |
new-address |
Generates a new address for the wallet |
list-addresses |
Shows all addresses in the wallet |
balance |
Shows current wallet balance in NOVA |
send |
Creates and signs a new transaction |
list-utxos |
Shows all unspent transaction outputs owned by the wallet |
history |
Displays transaction history |
label-tx |
Add or update a label for a transaction |
export |
Export wallet (encrypted) |
import |
Import wallet from file |
The Supernova miner can be run as a standalone process or integrated with a node.
# Start mining with default settings
./target/release/miner --threads 4 --address <YOUR_WALLET_ADDRESS>
# Advanced options
./target/release/miner --threads 8 --address <YOUR_WALLET_ADDRESS> --node-url http://localhost:9000 --intensity highSupernova includes a comprehensive disaster recovery system:
# Verify database integrity
./target/release/node verify-integrity
# Create a manual backup
./target/release/node create-backup
# Restore from backup
./target/release/node restore --backup-file ./backups/supernova_backup_1678912345.db
# Check repair status
./target/release/node repair-statusSupernova exports Prometheus metrics on the configured metrics port:
# Check basic node status
./target/release/node status
# View detailed metrics (if you have Prometheus/Grafana setup)
open http://localhost:9000/metricsComprehensive documentation is still a work-in-progress. Please refer to this overview document for more details: SuperNova Overview
The current implementation has several known issues:
- Thread Safety: The main node binary has improved thread safety but may still have some edge-case issues when handling a high number of concurrent requests.
- Warnings: The codebase contains numerous unused import and field warnings that need cleanup.
- Network Synchronization: Some complex network tests need refinement for better reliability.
Supernova is currently at version 0.1.0 (alpha). The core libraries are functional but additional work is needed on:
- API development
- Advanced network features
- Comprehensive integration testing
- Performance optimization
The project has recently undergone significant improvements:
- Mining System: Fixed critical issues in the difficulty adjustment algorithm and mining tests
- Block Header Implementation: Added proper accessors for block header fields
- Network Enhancement: Implemented robust peer scoring system with advanced metrics
- Thread Safety: Fixed thread synchronization issues using proper command channels and mutex guards
- Type System: Enhanced trait implementations and accessors for key components
- Testing: Comprehensive test suite with reliable integration tests
- APIs: Made all key functionality properly accessible through public interfaces
- Error Handling: Improved error propagation throughout the codebase
- Wallet CLI: Implemented a fully operational CLI interface for wallet management with HD wallet support
The project has progressed from ~87% to ~95% completion, with all major subsystems now functional and core integration tests passing successfully.
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -am 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- Bitcoin whitepaper for the foundational concepts
- Building Bitcoin in Rust book by Braiins
- Rust programming language and community
- libp2p for the P2P networking stack
- sled for the embedded database
Copyright (c) 2025 Marc Johnson