QNet is a high-performance, post-quantum secure blockchain network with a two-phase activation system designed for the next generation of decentralized applications.
This project uses dual licensing:
- Components:
core/- Consensus, mempool, state management, shardingdevelopment/- Node implementation, integration, contracts, VMaudit/- Security audit tools and compliance testsgovernance/- DAO and governance mechanismsdeployment/- Node deployment and orchestrationinfrastructure/- API, node infrastructure, backend servicestesting/- Integration tests, testnet toolsmonitoring/- Production monitoring and metrics
- License: Business Source License 1.1 - Perpetual Proprietary
- Usage:
- β Non-production use (testing, development, evaluation) - FREE
β οΈ Production use requires commercial license from AIQnetLab- π Proprietary license - remains under BSL 1.1 indefinitely
- Components:
applications/qnet-mobile/- Mobile wallet (F-Droid compatible)applications/qnet-wallet/- Browser extension walletapplications/qnet-explorer/- Blockchain explorerapplications/qnet-cli/- Command-line tools
- License: Apache License 2.0
- Usage: Fully open-source - use, modify, distribute freely
- Note: All applications connect to blockchain nodes via HTTP API only. No proprietary blockchain code is included.
- Phase 1 (Current): ONLY 1DEV token activation on Solana blockchain
- Phase 2 (Future): ONLY QNC token activation on QNet blockchain
- Transition: 90% 1DEV burned OR 5 years from genesis block (whichever comes first)
π Embedded RocksDB Indexing:
- Built-in TX Index: Fast O(1) transaction lookup via
tx_indexcolumn family - Address Index: Fast O(1) address transaction history via
tx_by_addresscolumn family - No External Database: All indexing in RocksDB (no PostgreSQL required)
- On-chain Node Registration:
NodeRegistrationTX type for immutable wallet-to-node binding - Explorer API: Full block/transaction/address data with clickable hashes
- System TX Support: Emission, reward distribution indexed correctly
- Dilithium Claim Option: Post-quantum signatures for reward claims (free gas)
Key Architecture:
Explorer β Node RPC (RocksDB)
β
- tx_index: hash β block_height (O(1))
- tx_by_address: address β [tx_hashes] (O(1))
- Single container deployment
- 100% data coverage
ποΈ Per-Round Consensus Storage (Production L1 Architecture):
- Independent Round Storage: Each round has its own commits/reveals HashMap
- No Data Loss: Round transitions don't destroy previous round data
- Parallel Rounds: Multiple consensus rounds can coexist simultaneously
- Automatic Cleanup: Old rounds (>5 epochs) automatically purged
- 100% First-Attempt Success: Eliminates "Reveal doesn't match commit" errors
- Race Condition Fix: Async tasks can't corrupt each other's data
- New API:
finalize_round_by_number(round),get_commits_for_round(round)
π Intercontinental Sync (Reliable USAβEurope):
- Size-Based Batching: BlocksBatch max 1MB, MacroblocksBatch max 500KB
- ShredProtocol Unicast:
send_block_via_shred_to_peer()for blocks >1MB - Repair Batching: 10 chunks per batch with 5ms pacing
- Peer Heights Tracking:
get_peer_heights()from Dilithium-signed heartbeats - Strict Sync Check: Emergency producer must have prev block (N-1)
- is_new_chunk Dedup: Prevents infinite forwarding loops
- Genesis Latency Fanout: fanout=max(producers, 4) for high-latency networks
β‘ Stage Pipeline (Full Runtime Isolation):
- BROADCAST_RUNTIME: Dedicated threads for Shred protocol
- SIGVERIFY_RUNTIME: Isolated Ed25519/Dilithium verification
- BANKING_RUNTIME: Transaction intake and mempool ops
- REPLAY_RUNTIME: State machine execution
- Adaptive Threading: 2 coresβ4t, 4 coresβ5t, 8 coresβ10t, 16 coresβ20t
- Configurable:
QNET_BROADCAST_THREADS,QNET_SIGVERIFY_THREADS, etc. - Result: 3-4x TPS improvement, no starvation, consistent latency
π§ Consensus Stability v2.48 (Round Mismatch Fix + Reveal Loss Prevention):
- LAST_FINALIZED_CONSENSUS_ROUND: Global atomic tracks ONLY successfully saved MacroBlocks
- Round Update at Save Only: Prevents premature round advancement causing desync
- Reveal Loss Prevention: Participant nodes don't reset consensus engine mid-round
- Dynamic Height Threshold: 5/10/20 blocks based on network size (scalable resync)
- Signed Reveal Messages: SHA3-256 + Dilithium hybrid signatures for reveals
π Network Recovery v2.44 (Aggressive Catch-up + Round Tolerance):
- Round Tolerance Β±90: Accept consensus messages within 1 epoch for fork recovery
- Aggressive Catch-up: 15s/5 blocks threshold (was 120s/50) for fast stall recovery
- Byzantine Median Height: Fresh network height from HealthPing peer data
- 100K TPS Recovery: Network self-heals after high-load stress tests
π Deterministic Reward Heartbeats v2.41:
- On-Chain Recording: Heartbeats stored in MacroBlock (not gossip)
- Emission MacroBlocks: Heartbeats only in every 160th MacroBlock (4 hours)
- Strict Validation: Unknown node_id formats REJECTED (no defaults)
- Full/Super: 10 heartbeats per 4h (80%/90% threshold)
- Light Nodes: Separate ping system (MIN_PING_SAMPLES = 10,000)
π― Block-Based Consensus Phases v2.40:
- Deterministic Phases:
get_phase_for_block(height)- identical on ALL nodes - No Local Transitions: Phases determined by block height, not message counts
- Eliminated Cascade Jailing: Timing issues are NOT offenses (no auto-jails)
- Grace Periods: Commits accepted until block 78, reveals until block 90
- Phase Layout: Commit (61-72) β Reveal (73-84) β Finalize (85-90)
π On-Chain Slashing v2.38:
- Cryptographic Proof Only: Slashing requires on-chain evidence
- Double-Sign Detection: 100% penalty + permanent ban
- No False Positives: Network delays don't cause slashing
π‘οΈ 5-Layer Macroblock Protection v2.31:
- Layer 1: Unsync node sync (45s delay + 3 retries)
- Layer 2: Not-validator sync (15s delay + 3 retries)
- Layer 3: Boundary verify (45s delay + 3 retries)
- Layer 4: Periodic check every 60s (last 10 macroblocks)
- Layer 5: On-demand sync in calculate_qualified_candidates
- Rate Limiting: Max 5 concurrent macroblock check tasks (prevents spawn storm)
- TaskGuard RAII: Automatic cleanup of spawned tasks
- Proactive Fork Detection: Rollback if local height > network on startup
π Zero Fork Guarantee v2.30:
- N-2 Entropy Source: MacroBlock N-2 for producer selection (guaranteed finalization)
- Extended Genesis: 180 blocks (not 90) for N-2 compatibility
- No Fallbacks: Lagging nodes cannot participate - must sync first
- 100% Determinism: All nodes select same producer guaranteed
- Epoch-Based Validators: Producer list from MacroBlock snapshots
π State Machine & Reliability:
- Explicit State Machine: 27 integration points (Syncing, Producing, Error, etc.)
- Real Reputation: DeterministicReputationState instead of hardcoded values
- Graceful Shutdown: Certificate persistence on Ctrl+C/SIGTERM
- No Fallback Policy: Desynchronized nodes excluded from production
π NIST/Cisco Compliant Hybrid Cryptography:
- Ephemeral Keys: NEW Ed25519 keypair for EACH message (forward secrecy)
- Dual Dilithium Signatures: Signs ephemeral key binding + message hash
- Quantum Protection: Ed25519 broken? Dilithium still protects!
- Compliance: NIST SP 800-208, Cisco Post-Quantum recommendations
π QUIC Transport Layer:
- TLS 1.3 encryption (NIST SP 800-52 compliant)
- Connection multiplexing: 100+ streams per connection
- 0-RTT handshake for repeat connections
- Binary protocol (bincode): ~50% bandwidth reduction vs JSON
- HTTP Fallback Removed: Pure QUIC for Full/Super node P2P
- Port Requirement: UDP 10876 must be open (
sudo ufw allow 10876/udp) - Docker Update: Add
-p 10876:10876/udpto run commands
- Fire-and-Forget Broadcast: Shred Protocol block propagation no longer blocks production (1 block/sec guaranteed)
- Genesis Startup Wait: 30-second network stabilization before block production (prevents race conditions)
- Emergency Timeout 10s: Increased from 2s to allow original producer delivery
- Pseudo-Infinite Retries: Blocks are NEVER discarded
- Exponential Backoff: 10s (retries 0-9) β 30s β 60s β 120s β 240s β 300s max
- Adaptive Buffer Size: Full/Super nodes: 500 blocks (~50MB), Light nodes: 100 blocks (~10MB)
- Background Re-request: Missing blocks automatically re-requested every 30s with backoff
- Epoch-Based Validator Set: Deterministic producer selection from MacroBlock snapshots
- No Gossip Race Conditions: All nodes use same producer list from blockchain
- EligibleProducer Struct:
{ node_id, reputation, stake }stored in MacroBlock - Genesis Epoch Static: Blocks 1-90 use
genesis_constants.rshardcoded list - MAX_VALIDATORS_PER_EPOCH = 1000: Scalable deterministic sampling
- Batch Ed25519 Verification: 3x faster signature verification using ed25519-dalek batch API
- Batch Mempool Operations: 1 lock per 1000 TX instead of per-TX (1000x reduction)
- TX Accumulator: Batch 1000 TX for verification, 100ms timeout
- Skip Self-Broadcast: Producer doesn't broadcast TX to itself
- Snapshot Mempool: Release lock early for DashMap reads
- HealthPing Height: Accurate network_height every 15 seconds
- 10K TX Batch Size: Optimized for 100K TX/block throughput
- Reputation System Fix: Only INFLATION is an attack (DEFLATION is legitimate after penalties)
- Tolerance Increased: 2% β 10% for network delays and sync timing
- Deterministic Producer Selection: Round 0 uses Genesis + leadership_round as entropy
- Cascade Prevention: Prevents false accusations from network desync
- Heartbeat with HYBRID signatures: Full quantum protection (Ed25519 + Dilithium per heartbeat)
- RAW bytes signatures: 88% size reduction (~2.6KB vs 22KB)
- Shred Protocol ALWAYS: Block propagation uses Shred Protocol for ALL network sizes
- Kademlia K-neighbors: Heartbeats use DHT distance for efficient routing (K=3)
- Exponential backoff failover: 3s β 6s β 12s β 24s β 30s max (reduces CPU under stall)
- Priority channels: Blocks/Consensus use separate channels (implicit priority queue)
- gossip_to_k_neighbors(): New method for DHT-based message propagation
- Simplified Fork Resolution: Three-case approach (network ahead/same height/we're ahead) instead of complex weight calculations
- Reputation Manipulation Detection: Escalating punishment for INFLATION attacks (1h β 1d β 1w β 1y ban)
- Empty Response Attack Protection: Detection and penalty for nodes sending empty peer lists
- Consensus Security: Timestamp validation (Β±5 min) and signature format pre-validation for commits/reveals
- Dual Peer Lookup: Fixed Genesis node peer discovery (check both DashMap and RwLock storage)
- Dead Code Removal: Removed ~250 lines of unused fork recovery code
- Full Macroblock Sync: Complete P2P synchronization for macroblocks (RequestMacroblocks, MacroblocksBatch)
- Snapshot API: New endpoints
/api/v1/snapshot/latestand/api/v1/snapshot/{height}for fast sync - Light Node Support: Macroblocks synced for state verification, headers rotated to save space
- Async Runtime Fixes: Isolated
block_oncalls prevent "nested runtime" panics - Balance Restoration: Balances restored from snapshots or block replay during synchronization
- REAL Dilithium3 Signatures: Full NIST FIPS 204 cryptographic verification with
dilithium3::open() - Secure Key Storage: Random encryption keys (NOT derived from public node_id) with SHA3-256 integrity
- No Fallback Signatures: Removed SHA3-256 fallback - operations skip if Dilithium unavailable
- Standardized Algorithm: All signatures use "CRYSTALS-Dilithium3" identifier
- WebSocket Rate Limiting: DDoS protection for real-time connections
- WebSocket Real-time Events: Live updates for blocks, balances, contracts, and transactions
- Smart Contract REST API: Deploy, call, query WASM contracts with hybrid signatures
- Smart Polling for Light Nodes: Battery-efficient polling (~94% fewer wake-ups)
- Mandatory Transaction Signatures: All transfers require Ed25519 verification
- Enhanced Rate Limiting: IP-based DDoS protection for all API endpoints
- MEV Protection (Private Bundles): Front-running protection for high-value transactions (NEW!)
- Direct submission to block producer (bypasses public mempool)
- Dynamic allocation: 0-20% block space for bundles, 80-100% for public TXs
- Reputation gate: 80%+ required (proven trustworthy nodes only)
- Bundle constraints: max 10 TXs, 60s lifetime, +20% gas premium
- Rate limiting: 10 bundles/min per user (anti-spam)
- Multi-producer submission: 3 producers for redundancy
- Auto-fallback: Public mempool if bundle submission fails
- Atomic inclusion: All bundle TXs included together or rejected
- Post-quantum signatures: Dilithium3 verification for all bundles
- Real-time tests: 11/11 passed (validated in production environment)
- Priority Mempool: Gas-price-based transaction ordering (NEW!)
- BTreeMap priority queue: highest gas price processed first
- Anti-spam protection: high-value TXs immune to spam attacks
- Fair within same price: FIFO for identical gas prices
- Binary+JSON support: flexible storage for different TX types
- Integrated into block production: automatic priority selection
- Minimum gas price: 100,000 nano QNC (0.0001 QNC base fee)
- Adaptive Shred Protocol Fanout: Dynamic block propagation scaling (NEW!)
- Network-aware: 4-32 fanout based on producer count and latency
- LAN optimization: higher fanout (16-32) for low latency networks
- WAN optimization: moderate fanout (8-16) for high latency
- Scales from 5 Genesis nodes to 1M+ nodes seamlessly
- Real-time calculation: adjusts every block based on network state
- Real-time Prometheus Metrics: Live performance monitoring (NEW!)
- Dynamic mempool size, block height, connected peers
- Live Shred Protocol fanout, qualified producers, average latency
- MEV metrics: bundle count, allocation percentage
- No hardcoded values: all metrics reflect real network state
- Split Reputation System: Byzantine-safe separation of behavior metrics (NEW!)
consensus_score(0-100): Byzantine behavior detection (invalid blocks, malicious attacks)network_score(0-100): Network performance tracking (timeouts, latency)- WAN latency penalties don't affect consensus eligibility (70% threshold on consensus_score only)
- Network performance tracked separately for peer prioritization
- Combined reputation for peer selection: 70% consensus + 30% network
- Adaptive Entropy Consensus: Scalable Byzantine-safe producer rotation (v2.19.4)
- Finality Window: Uses block height - 10 for entropy source (Byzantine-safe)
- Adaptive Sample Size: 5 (Genesis) β 100 (1M nodes) - scales with network
- Dynamic Wait: 200ms-2s adaptive timeout (2-20Γ faster than fixed 4s)
- Byzantine Threshold: 60% of sampled peers must agree
- Network Efficient: < 1 KB/s bandwidth, 0.002% CPU overhead
- Scalability: O(log log n) sample growth, O(1) latency
- Peer Blacklist System: Intelligent sync peer filtering (NEW!)
- Soft blacklist: Temporary (network issues, auto-expires)
- Hard blacklist: Permanent until reputation recovers (Byzantine attacks)
- Escalation: Repeated failures increase blacklist duration
- Auto-removal: Hard blacklist cleared when consensus_score β₯ 70%
- Peer Prioritization: Optimized block synchronization (NEW!)
- Priority by node type: Super > Full (Light nodes excluded from sync sources)
- Blacklist filtering: Offline/malicious peers skipped
- Reputation-based ordering: consensus_score + network_score (latency)
- Top-20 peer sampling: Avoids stuck sync on single unavailable peer
- QUIC P2P Transport (v2.19.22): High-performance UDP-based transport for all P2P communication
- Full QUIC protocol with TLS 1.3 encryption (NIST SP 800-52 compliant)
- Connection multiplexing: 100+ streams per connection
- 0-RTT handshake for repeat connections (ultra-low latency)
- Connection pooling with automatic reconnection
- Binary protocol (bincode): ~50% bandwidth reduction vs JSON
- UDP port 10876 (P2P port + 1000)
- Fallback: None (QUIC is mandatory for v2.19.22+)
- Deterministic Reputation (v2.1): No P2P gossip - reputation from blockchain only
- REMOVED: Gossip-based reputation sync (Sybil attack vulnerable)
- All reputation computed from on-chain data (blocks, macroblocks)
- SlashingEvents with cryptographic proof in macroblocks
- Finality Checkpoints: After 2 macroblocks = irreversible
- Scalable: Chunked processing for 100,000+ nodes
- Hybrid Merkle + Sampling: Scalable on-chain ping commitments
- 360Γ on-chain size reduction (100 MB vs 36 GB)
- Merkle root commitment to ALL pings (blake3 hashing)
- Deterministic sampling: 1% of pings (minimum 10,000 samples)
- SHA3-256 for sample seed generation (quantum-resistant)
- Byzantine-safe verification through Merkle proofs
- Production-ready for millions of nodes
- Bitcoin-Style Emission Validation: Decentralized emission without central authority
- No system key or single point of control
- Range-based validation with halving support
- All nodes independently validate emission amounts
- Conservative estimates for Pool 2 & Pool 3
- Partial determinism by design (Β±1-5% acceptable)
- Byzantine consensus ensures security
- Compact Hybrid Signatures v2.23: Optimized microblock signatures (~2.6KB RAW bytes)
- Ed25519 + CRYSTALS-Dilithium hybrid cryptography
- RAW bytes format via
serde_bytes(88% reduction from 22KB) - Defense-in-depth: real Dilithium verification at P2P + Consensus layers
- NIST/Cisco post-quantum compliance
- Progressive Finalization Protocol (PFP): Self-healing macroblock recovery
- Degradation levels: 80% β 60% β 40% β 1% node requirements
- Checks every 30 blocks with accelerating timeouts (30s β 2s)
- Zero-downtime: microblocks continue during recovery
- Byzantine-safe at all levels (2/3+ honest nodes)
- Certificate Broadcasting: Byzantine-safe P2P certificate distribution
- Tracked broadcast with 2/3+ Byzantine threshold for critical rotations
- Adaptive timeout (3s/5s/10s) based on network size
- Adaptive periodic intervals (10s/30s/120s) based on node uptime
- Certificate lifetime: 4.5 minutes (270s = 3 macroblocks) with 80% rotation (216s)
- Anti-duplication via serial number change detection
- LRU cache with 100K certificate capacity
- Scalable from 5 bootstrap to millions of nodes
- Block Buffering: Memory-protected out-of-order block handling
- Bounded buffer (100 blocks, ~10 MB maximum)
- FIFO eviction with current block protection
- 30-second timeout + 5-retry limit
- Prevents memory exhaustion attacks
- Node Type Filtering: Consensus participation optimization
- Light nodes: transactions only (no consensus)
- Full nodes: partial consensus participation
- Super nodes: full consensus (max 1000 validators)
- Validator sampling for network scaling
- Architectural Cleanup: Resolved circular dependencies
- Core modules: structural validation only
- Development modules: full cryptographic verification
- Clean separation: consensus trusts pre-verified blocks
- Defense-in-depth security model
- Fast Finality Indicators: 5-level transaction confirmation system (Pending β InBlock β QuickConfirmed β NearFinal β FullyFinalized)
- Real-time safety percentage calculation (0% - 100%)
- Time to finality countdown (seconds until macroblock)
- Risk assessment for exchanges and bridges (safe_for_amounts_under_X_qnc)
- Optimized for 4.29B QNC supply with conservative thresholds
- Zero storage overhead (calculated on-the-fly)
- Backward compatible (optional fields)
- VTS Synchronization: Synchronized Verifiable Time Sequence for deterministic producer selection
- VTS state from last confirmed block (all nodes agree)
- Local VTS generator syncs with received blocks
- Prevents consensus failures from diverging VTS states
- Macroblock VTS sourced from last microblock in range
- Fork Detection & Resolution: VTS counter regression checks prevent malicious forks
- Chain Reorganization (Chain Reorg): Byzantine-safe fork resolution with 2/3 majority consensus
- Advanced Block Synchronization: Out-of-order block buffering with active missing block requests
- DDoS-Protected P2P: Rate limiting and concurrent request management for network stability
- Quantum-Resistant Genesis: CRYSTALS-Dilithium3 Genesis block with encapsulated keys
- Parallel Block Processing: High-performance consecutive block processing (up to 10 blocks)
- Reputation-Based Chain Weight: Byzantine weight calculation using validator reputation scores
- QUIC Rate Limiting: Semaphore-based adaptive rate limiting for chunk sends
- Prevents receiver overload from burst of 72+ concurrent streams
- Fixed ~40% packet loss issue discovered in production testing
- Adaptive limits: 20-200 concurrent based on network size
- Per-peer limit: max 5 concurrent streams per receiver
- Scales from 5 to 100K+ nodes
- SHRED Chunk Retransmit: Efficient recovery of missing chunks without full block download
- 3-second timeout before requesting missing chunks
- Adaptive peer selection (3-10 peers based on network size)
- 100-block chunk cache for fast retransmit responses
- 83% bandwidth savings vs full block re-download
- Works for both microblocks and macroblocks
- Privacy-First Logging: All IP addresses use pseudonyms via
get_privacy_id_for_addr() - Genesis QUIC Readiness: Retry mechanism ensures QUIC connections established before broadcast
- Deadlock Detection Fixes: Improved sync flag management with
>=timeout checks
- Shred Protocol Block Propagation: 85% bandwidth reduction with Reed-Solomon erasure coding
- Quantum Verifiable Time Sequence (VTS): 500K hashes/sec with hybrid SHA3-512/Blake3 (25%/75%)
- Production config: 5,000 hashes per tick Γ 100 ticks/sec = 500K hashes/sec
- 100 ticks per second (10ms intervals) for smooth entropy generation
- 5,000 hashes per tick (optimized for 1-second microblocks)
- Sequential ordering via SHA3-512 every 4th hash (limits parallelization, not formal VDF)
- Integrated into QRDS (Quantum-Resistant Deterministic Selection) for consensus
- Checkpoint persistence with zstd compression (every 1M hashes)
- Clock drift: 5-7% (excellent for production)
- 72 bytes overhead per block (poh_hash: 64B + poh_count: 8B) = ~2-3%
- Hardware: Intel Xeon E5-2680v4 @ 2.4GHz
- QRDS (Quantum-Resistant Deterministic Selection): SHA3-512 deterministic selection with FINALITY_WINDOW entropy, Dilithium + Ed25519 hybrid cryptography for Byzantine-safe leader election
- Hybrid Parallel Executor Execution: 5-stage pipeline with 10,000 parallel transactions
- Adaptive BFT Adaptive Timeouts: Dynamic 7s base to 20s max (1.5x multiplier) based on network conditions
- Pre-Execution Cache: Speculative execution with 10,000 transaction cache
- Comprehensive Benchmark Harness: Full performance testing suite for all components
- 57 API Endpoints: Complete monitoring and control interface for all features
- Emergency Producer System: EMERGENCY_PRODUCER_FLAG for automatic failover
- Global Synchronization Control: Atomic flags preventing race conditions
- Entropy Consensus Verification: ENTROPY_RESPONSES cryptographic validation
- Quantum Crypto Singleton: GLOBAL_QUANTUM_CRYPTO instance management
- Actor-Based Cache System: CacheActor with versioning and epoch tracking
- Real-Time Peer Discovery: Immediate PeerDiscovery broadcast
- Base64 Network Serialization: Efficient binary data over JSON
- PhaseAwareRewardManager: Integrated reward system with ping tracking
- Direct Node Connections: getRandomBootstrapNode() decentralized access
- Complete API Decentralization: Removed all api.qnet.io dependencies
- AES-256-GCM Database Encryption: Quantum-resistant protection for activation codes
- No Encryption Keys in Database: Keys derived from activation code only
- Critical Attack Protection: PERMANENT BAN for critical attacks (DatabaseSubstitution, ChainFork, StorageDeletion)
- Privacy-Preserving Pseudonyms: Enhanced network topology protection (14 log locations)
- Genesis Bootstrap Grace: 15-second timeout for first block (prevents false failover)
- Genesis Wallet Synchronization: Unified wallet format across all modules
- Comprehensive Security Tests: 52 total tests (9 new activation security tests)
- Chain Integrity Validation: Full verification of previous_hash in all blocks
- Database Substitution Protection: Detects and rejects forked/manipulated chains
- Enhanced Synchronization Protection: New nodes must fully sync before consensus participation
- Storage Failure Handling: Immediate failover if database fails during block production
- Data Persistence Fix: Removed /tmp fallback, enforces persistent Docker volumes
- Atomic Rotation Rewards: One +30 reward per full 30-block rotation (not 30x +1)
- Activity-Based Recovery: Reputation only recovers if node had recent ping activity
- Self-Penalty Fix: All failovers now apply -20 penalty, even voluntary ones
- Progressive Jail System: 6 chances for regular offenses (1h β 24h β 7d β 30d β 3m β 1y)
- Critical Attack Protection: PERMANENT BAN for DatabaseSubstitution, ChainFork, StorageDeletion
- Double-Sign Detection: Automatic tracking and evidence collection (-50 reputation + jail)
- Equal Treatment: Genesis nodes follow same jail rules as everyone (no special protection)
- Anti-DDoS Protection: Rate limiting and network flooding detection
- Full/Super Nodes: ONLY servers, VPS, desktops with interactive setup
- Light Nodes: ONLY mobile devices & tablets through mobile app
QNet production testnet is ready for deployment with advanced consensus and synchronization.
- β Post-Quantum Cryptography: CRYSTALS-Dilithium3 with NIST/Cisco encapsulated keys (nodes)
- β Client Cryptography: Ed25519 signatures for mobile/browser (20ΞΌs operations)
- β Entropy-Based Consensus: True decentralization with unpredictable producer rotation
- β Reputation System: Economic incentives for network participation
- β State Snapshots: Full & incremental snapshots with LZ4 compression
- β Parallel Synchronization: Multi-worker downloads for fast sync
- β Deadlock Prevention: Guard patterns & health monitors implemented
- β Two-Phase Activation: 1DEV burn (Phase 1) β QNC Pool 3 (Phase 2)
- β Microblock Architecture: 1-second blocks, 400k+ TPS (256 shards)
- β Production Rust Nodes: Server deployment with real blockchain nodes
- β Browser Extension Wallet: Production-ready with full-screen interface
- β Mobile Applications: iOS/Android apps for Light nodes only
- β Interactive Setup: Server nodes require interactive activation menu
- β IPFS Integration: Optional P2P snapshot distribution
- β 1DEV Burn Contract: D7g7mkL8o1YEex6ZgETJEQyyHV7uuUMvV3Fy3u83igJ7 on Solana Devnet
For production testnet deployment, see: PRODUCTION_TESTNET_MANUAL.md
- β Performance Validated: 10,000+ TPS sustained with <200ms latency
- β Security Audited: Comprehensive security review completed
- π Post-Quantum Security: NIST/Cisco encapsulated keys with Dilithium3 + Ed25519 (nodes) | Ed25519-only for clients (mobile/browser)
- β‘ Ultra-High Performance: 424,411 TPS with zero-downtime consensus
- π² True Decentralization: Deterministic producer selection (finality window + SHA3) with Byzantine fairness and quantum resistance
- π° Reputation Economics: Rewards for block production (+1 micro, +10/+5 macro)
- π Advanced Synchronization: State snapshots with parallel downloads & IPFS
- π₯ Phase 1 Active: 1DEV burn-to-join (1,500 β 300 1DEV minimum, universal pricing)
- π Phase 2 Ready: QNC Pool 3 system (5k-30k QNC dynamic pricing)
- π Scalable Architecture: 256 shards, microblocks, lock-free operations (10M+ nodes)
- π Cross-Chain Compatibility: Solana integration for Phase 1
- ποΈ Decentralized Governance: Community-driven decision making
- π± Mobile-First Design: Light nodes on phones & tablets
- π₯οΈ Server Architecture: Full/Super nodes on dedicated servers
- π§ Interactive Setup: User-friendly activation process
- π‘οΈ Deadlock Prevention: Guard patterns & health monitors for stability
- π‘οΈ MEV Protection: Private bundles for front-running protection (80%+ reputation, 0-20% allocation)
- π Priority Mempool: Gas-price-based ordering for spam resistance
- πͺοΈ Shred Protocol Protocol: 85% bandwidth savings with adaptive fanout (4-32) based on network topology
- β±οΈ Quantum VTS: 500K hashes/sec cryptographic clock for precise timing
- βοΈ Hybrid Parallel Executor: 10,000 parallel transactions with 5-stage pipeline
- π― Adaptive BFT: Adaptive timeouts (7s base to 20s max, 1.5x multiplier) for optimal consensus
- π Pre-Execution: Speculative transaction processing with 10,000 cache size
- π MEV Protection: Private bundle submission with post-quantum signatures
| Metric | Value | Description |
|---|---|---|
| Throughput | 424,411 TPS | 256 shards Γ 10k batch Γ zero-downtime |
| Latency | <100ms | Transaction confirmation time |
| Finality | <2 seconds | Block finalization |
| Block Capacity | 5,000 TX/block | ~1 MB per microblock (200 bytes avg TX) |
| Downtime | ZERO | Swiss watch precision, continuous flow |
| Energy Efficiency | 99.9% less than Bitcoin | Eco-friendly consensus |
| Node Types | Full, Super, Light | Flexible participation |
| Storage Efficiency | 50-100 GB typical | Sliding window + snapshots |
Hardware & Benchmarks:
- Test Environment: Intel Xeon E5-2680v4 @ 2.4GHz (14 cores, 28 threads), 32GB DDR4-2400
- VTS Performance: 500K hashes/sec (hybrid SHA3-512/Blake3, sequential ordering chain)
- Signature Verification: Dilithium3 ~2ms, Ed25519 ~20ΞΌs per signature
- Network: WAN-optimized with adaptive timeouts (7s-20s)
Cryptographic Approach:
- β Consensus Layer: Real CRYSTALS-Dilithium3 (pqcrypto-dilithium 0.5) - fully post-quantum
- β Node Signatures: Hybrid Dilithium3 + Ed25519 with NIST/Cisco encapsulated keys
- β
Client Transactions (v2.25): Ed25519 required + optional Dilithium3 for quantum protection
- Standard TX: Ed25519 only (fast, low gas)
- Quantum TX: Ed25519 + Dilithium3 (+50% gas premium, post-quantum security)
- π Enterprise Option: Optional Dilithium signatures for high-value transfers
Consensus Architecture:
β οΈ Producer Selection: Deterministic SHA3-512 (finality window), NOT true VRF with private keysβ οΈ Fairness: 7/10 - Biasable by 67%+ Byzantine coalition (economically expensive)- β Byzantine Safety: 2/3+ honest nodes threshold enforced at all layers
- β Rotation: 30-block intervals (30 seconds), limits manipulation window
Security Trade-offs:
- β AES-256-GCM: Grover-resistant (2^128 operations = 10^38 years attack time)
- β Nonce Management: CSPRNG with 2^96 space, 10^-10% collision probability
β οΈ ShredProtocol: Original implementation with Reed-Solomon erasure coding- β Sybil Resistance: Multi-layer (1DEV burn + QNC pool, reputation, time barrier, 67%+ coordination cost)
QNet implements revolutionary storage system with temporal compression and delta encoding.
- Adaptive Temporal Compression: Blocks age like wine - stronger compression over time
- Day 0-1: No compression (hot data)
- Day 2-7: Zstd-3 (light compression, ~50% reduction)
- Day 8-30: Zstd-9 (medium compression)
- Day 31-365: Zstd-15 (heavy compression)
- Year 1+: Zstd-22 (extreme compression)
- Lossless Compression Only (v2.19.10): All data fully recoverable
- Zstd-3 for new transactions (~50% reduction)
- Pattern Recognition removed (was lossy, data could not be reconstructed)
- Delta Encoding removed (not needed with EfficientMicroBlock format)
- RocksDB Transaction Index: O(1) transaction lookups with native key-value indexing
- Hardware Auto-Tuning: Automatically optimizes for available resources
- CPU Detection: Uses all available cores (minimum 4 threads)
- Smart Validation: Auto-enables parallel validation on 8+ core systems
- Adaptive Mempool: Scales from 100k (test) to 2M (production) based on network size
- Works on any hardware: 4-core VPS β 64-core server
- No manual configuration - detects and adapts automatically
- Dynamic Shard Auto-Scaling: Automatically adjusts shard count based on real network size
- Genesis (0-1K nodes): 1 shard (~4K TPS)
- Growth (1K-10K nodes): 4 shards (~16K TPS)
- Medium (10K-50K nodes): 16 shards (~64K TPS)
- Large (50K-100K nodes): 64 shards (~256K TPS)
- Very Large (100K-500K nodes): 128 shards (~512K TPS)
- Massive (500K+ nodes): 256 shards (~1M+ TPS)
- Blockchain Registry Integration: Reads actual activated node count from storage
- Multi-source detection: Monitoring β Genesis β Blockchain β Default
- Recalculation on restart: Every node startup reads fresh network size
- No manual configuration - system adapts to network growth automatically
- EfficientMicroBlocks: Store transaction hashes instead of full transactions
- Sliding Window Storage: Full nodes keep only last 100K blocks (~1 day) + snapshots
- Smart Pruning: Automatic deletion of blocks AND transactions outside retention window
- Block pruning: Removes microblocks and macroblocks
- Transaction pruning: Removes transactions + tx_index + tx_by_address (v2.19.7)
- RocksDB compaction: Forces disk space reclamation after pruning
- Batch processing: 1000 items/batch to avoid memory issues
- Snapshot-Based Sync: New nodes bootstrap in minutes, not hours
- State Snapshots: Periodic full state captures for fast recovery
- Auto-cleanup: Keeps only last 5 snapshots
- Zstd-15 compression for snapshot data
- SHA3-256 integrity verification
- Tiered Storage (v2.19.10 - corrected estimates with Zstd-3 only):
- Light nodes: ~100 MB (headers only, FIFO auto-rotation)
- Full nodes: ~500 GB (30-day pruning window)
- Super nodes (archival): ~2 TB (full history, no pruning)
- Storage with Zstd-3 (~50% reduction):
- 100 TPS: ~220 GB/year (Super), ~18 GB (Full 30d)
- 500 TPS: ~1.1 TB/year (Super), ~90 GB (Full 30d)
- 1000 TPS: ~2.2 TB/year (Super), ~180 GB (Full 30d)
- Note: Sharding is for parallel TX processing, NOT storage partitioning
- Distributed Archival: Full/Super nodes archive 3-8 chunks each as network obligation
- Triple Replication: Every data chunk replicated across 3+ nodes minimum
- Automatic Compliance: Network enforces archival obligations for fault tolerance
- Backward Compatible: Seamless migration from legacy storage format
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β QNet Blockchain β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Post-Quantum Crypto Layer β
β βββ CRYSTALS-Dilithium (Signatures) β
β βββ CRYSTALS-Kyber (Key Exchange) β
β βββ SPHINCS+ (Hash-based Signatures) β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Consensus Layer with Deterministic Selection β
β βββ Microblock Production (1s intervals) β
β β βββ Deterministic selection (finality window entropy) β
β β βββ Dilithium + Ed25519 hybrid signatures β
β β βββ 30-block rotation with SHA3-512 entropy β
β β βββ Race-free at boundaries (no delays) β
β β βββ Producer rewards: +1 reputation per block β
β β βββ Full/Super nodes only (reputation >= 70%) β
β βββ Macroblock Consensus (90s intervals) β
β β βββ Byzantine consensus with 1000 validators β
β β βββ Active listener on all Full/Super nodes (1s poll) β
β β βββ Consensus window: blocks 61-90 (early start) β
β β βββ Leader: +10 reputation, Participants: +5 each β
β β βββ Deterministic initiator selection β
β β βββ 67% honest validator requirement β
β βββ Advanced Synchronization β
β βββ State snapshots: Full (12h) & Incremental (1h) β
β βββ Parallel downloads with 100-block chunks β
β βββ IPFS integration for P2P snapshot distribution β
β βββ Deadlock prevention with guard pattern β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Performance Optimization Layer β
β βββ Shred Protocol Block Propagation β
β β βββ 1KB chunks with Reed-Solomon erasure coding β
β β βββ Adaptive fanout (4-32) based on network size & latency β
β β βββ 85% bandwidth reduction β
β βββ Quantum Verifiable Time Sequence (QVTS) β
β β βββ 500K hashes/sec cryptographic clock β
β β βββ SHA3-512 + Blake3 hybrid (25%/75%) β
β β βββ Verifiable delay function β
β βββ Hybrid Parallel Executor Execution β
β β βββ 5-stage pipeline processing β
β β βββ 10,000 parallel transactions β
β β βββ Dependency graph analysis β
β βββ Adaptive BFT Adaptive Timeouts β
β β βββ Dynamic 20s/10s/7s timeouts β
β β βββ Network condition awareness β
β βββ Pre-Execution Cache β
β βββ Speculative transaction execution β
β βββ 10,000 transaction cache β
β βββ 3-block lookahead β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Network Layer (Optimized for 10M+ nodes) β
β βββ QUIC Transport (UDP 10876) - TLS 1.3 encrypted β
β βββ Kademlia DHT with K-bucket management β
β βββ Lock-Free DashMap for O(1) operations β
β βββ Dual Indexing (by address & ID) β
β βββ 256 Shards with Cross-Shard Routing β
β βββ Auto-Scaling (5β100β10Kβ1M+ nodes) β
β βββ Gossip Protocol (QUIC-based) β
β βββ Regional Node Clustering β
β βββ Emergency Producer Change Broadcasting β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Application Layer β
β βββ Smart Contracts (WASM) β
β βββ DeFi Protocols β
β βββ Cross-Chain Bridges β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
QNet implements advanced chain reorganization and synchronization mechanisms for network consistency:
- Fork Detection: Automatic detection via SHA3-256 hash comparison (<1ms)
- Three-Case Resolution:
- Network ahead: Rollback to fork point and sync with longer chain
- Same height: Resync if β₯3 high-reputation validators (β₯70%) connected
- We're ahead: Keep our chain (we have longer chain)
- Validator-Based Decision: Minimum 3 high-reputation peers required for resync
- Deep Reorg Protection: Maximum 100 blocks sync per request (51% attack prevention)
- Race Condition Prevention: Single concurrent reorg with RwLock flag
- DoS Protection: Rate limiting (1 fork attempt per 60 seconds maximum)
- Macroblock Finality: Ultimate resolution via 67% consensus every 90 blocks
- Async Processing: Non-blocking fork analysis in background tasks
- Out-of-Order Buffering: Temporary storage for blocks received before their dependencies
- Active Block Requests: DDoS-protected requests for missing blocks (max 10 concurrent)
- Parallel Block Processing: Processes up to 10 consecutive blocks simultaneously
- Request Cooldown: 10-second minimum between requests for same block (max 3 attempts)
- Automatic Retry: Re-queues buffered blocks when dependencies arrive
- Memory Management: Automatic cleanup of blocks older than 60 seconds
- Genesis Coordination: Only node_001 creates Genesis block in bootstrap mode
- Quantum-Resistant Genesis: CRYSTALS-Dilithium signature ensures identical Genesis across all nodes
- Cryptographic Clock: 500K hashes/sec SHA3-512 + Blake3 hybrid (25%/75%)
- Verifiable Delay Function: Time-stamped block ordering without central authority
- Block Time Synchronization: Sub-second precision across distributed network
- Historical Proof: Cryptographic evidence of event ordering and timing
- Fork Prevention: VTS creates immutable timeline making forks computationally expensive
- Node Type Optimization: VTS runs ONLY on Full/Super nodes (Light nodes excluded to save mobile battery/CPU)
- Network Synchronization: Local VTS syncs with network consensus on block receipt
- Checkpointing: Automatic checkpoints every 1M hashes for fast node restart
- Drift Detection: Automatic clock drift monitoring with 5% tolerance threshold
- Scalability: 256-shard system supports 25.6M+ Light nodes (100K per shard)
- Deterministic Pinger Selection: Each Light node has Primary + 2 Backup pingers
- Multi-Provider Push: Three delivery methods with automatic fallback:
- FCM (Google Play): Firebase Cloud Messaging for instant delivery
- UnifiedPush (F-Droid): Open-source, decentralized (ntfy.sh, Gotify, etc.)
- Smart Polling (Fallback): Battery-efficient wake-up ~2 min before ping slot (once per 4h)
- Challenge-Response: Light node signs random challenge to prove liveness
- Dual Signatures: Attestation includes both Light node and Pinger Dilithium signatures
- Gossip Protocol: Attestations propagated to all nodes for reward eligibility
- Rate Limiting: 500 FCM requests/sec limit (Google API compliance)
- Slot-Based Deduplication: One attestation per 1-minute slot per Light node
- Reward Eligibility: Light nodes must respond to pings to receive Pool #3 rewards
- Battery Optimization: Smart polling reduces wake-ups from 96/day to 6/day (~94% reduction)
- Sync Speed: Up to 10,000 blocks/second with parallel processing
- Fork Resolution: <5 seconds for Byzantine weight calculation
- Missing Block Request: <100ms average request latency
- Reorg Execution: 50-200ms for typical reorganizations (background)
- Memory Overhead: <10MB for block buffering and request tracking
QNet implements production-grade failover mechanisms for zero-downtime operation:
- Rotation Schedule: Every 30 blocks (30 seconds) for stability
- Participant Filter: Only Full and Super nodes (Light nodes excluded for mobile optimization)
- Producer Readiness Validation: Pre-creation checks (reputation β₯70%, network health, connectivity)
- Fixed Timeout Detection: 5 seconds (deterministic for consensus safety across all nodes)
- Emergency Selection: Deterministic fallback selection from qualified backup producers (SHA3-512 hash, v2.36 unified)
- Enhanced Status Visibility: Comprehensive failover dashboard with recovery metrics
- Network Recovery: <7 seconds automatic recovery time with full broadcast success tracking
- Reputation Impact: -20.0 penalty for failed producer, +5.0 reward for emergency takeover
When all nodes fall below 70% reputation threshold:
- Progressive Degradation: Tries thresholds 50% β 40% β 30% β 20%
- Emergency Boost: +30% reputation to Genesis nodes, +50% to regular nodes
- Forced Recovery: Selects any responding node as emergency producer
- Genesis Protection: Always tries to recover with Genesis nodes first
- Network Continuity: Ensures blockchain never halts completely
- Byzantine Consensus: Full commit-reveal with 67% honest assumption
- Timeout Detection: 30-second threshold for macroblock creation
- Emergency Re-consensus: Automatic restart excluding failed leader
- Leader Exclusion: Failed leaders temporarily excluded from future rounds
- Network Recovery: <45 seconds automatic consensus restart
- Reputation Impact: -30.0 penalty for failed macroblock leader
- No Producer Dependency: Any qualified node can become emergency producer
- Automatic Recovery: No human intervention required for network restoration
- Progressive Penalties: Escalating reputation penalties prevent repeated failures
- Network Transparency: All failover events logged and broadcast to peers
ARCHITECTURE v2.24: Blockchain-based reputation with full state snapshots
- All nodes compute identical reputation from on-chain data
- Sybil-resistant: Cannot fake reputation via gossip
- Deterministic: Verifiable by replaying blockchain from genesis
- NEW: Full reputation snapshot in every macroblock
- NEW: Strict 30/30 rule - only FULL rotation gets reward!
See full documentation: docs/REPUTATION_SYSTEM.md
Every macroblock stores complete reputation state:
pub struct FullReputationSnapshot {
pub reputations: HashMap<String, f64>, // 0-100%
pub active_jails: HashMap<String, (u64, u32)>, // end_time + offense_count
pub permanent_bans: HashSet<String>, // Forever banned
pub offense_counts: HashMap<String, u32>, // Progressive jail counter
pub last_passive_recovery: HashMap<String, u64>, // Recovery timers
}| Action | Rep Points | Source | Requirement |
|---|---|---|---|
| Full Rotation | +2.0 | block producer | 30/30 blocks only! |
| Consensus Participation | +1.0 | macroblock commit+reveal | Full participation |
| Double-Sign | -100% + BAN | SlashingEvent | 2 signatures at same height |
| Invalid Block | -20% | SlashingEvent | Invalid signature/hash |
| Chain Fork | -100% + BAN | SlashingEvent | Conflicting signed blocks |
| Missed Blocks | 0 (no penalty) | β | Not slashable (no reward instead) |
| Passive Recovery | +1.0/4h | online nodes 10-69% | Not jailed |
| Partial Rotation | 0 | β | NO REWARD if <30 blocks! |
- 70-100%: Eligible for consensus participation
- 10-69%: Passive recovery (+1% per 4h if online)
- <10%: Cannot recover (too low)
- 0%: Jailed or permanently banned
- Light nodes: Fixed at 70% (excluded by NodeType, not reputation)
Fair penalties - equal for ALL nodes (including Genesis):
| Offense | Jail Duration | Recovery After Jail |
|---|---|---|
| 1st | 1 hour | Restore to 30% |
| 2nd | 24 hours | Restore to 25% |
| 3rd | 7 days | Restore to 20% |
| 4th | 30 days | Restore to 15% |
| 5th | 3 months | Restore to 12% |
| 6+ | 1 year | Restore to 10% (can return!) |
Critical Attacks (instant PERMANENT BAN - no return):
- DatabaseSubstitution
- ChainFork
- StorageDeletion
Equal Treatment:
- Genesis nodes follow the same rules as everyone
- Only critical attacks = permanent ban
- Regular offenses always have a path back
| Attack Type | Detection Method | Penalty |
|---|---|---|
| Double-Sign | Multiple signatures at same height | -50.0 points |
| Invalid Block | Failed cryptographic verification | -30.0 points |
| Time Manipulation | Block timestamp >5s in future | -20.0 points |
| Network Flooding | >100 msgs/sec from single node | -10.0 points |
| Invalid Consensus | Malformed commit/reveal | -5.0 points |
// Quantum-resistant deterministic selection for fair producer rotation
// All nodes compute the same selection deterministically using finality window
let entropy_height = current_height - FINALITY_WINDOW; // 10 blocks back
let entropy_source = get_block_hash(entropy_height); // Byzantine-finalized
selection_hash = SHA3_512(
leadership_round +
sorted_candidates +
entropy_source // Finalized block hash (SHA3(prev + elig))
);
// DETERMINISTIC: All nodes select the same producer
let selection_value = u64::from_bytes(selection_hash[0..8]);
let selection_index = (selection_value % candidates.len()) as usize;
let selected_producer = candidates[selection_index];
// β οΈ LIMITATION: Not true VRF (no private key randomness)
// β οΈ Biasable by 67%+ Byzantine coalition controlling entropy source
// β
SECURITY: Finality window prevents individual producer manipulation
// β
BENEFIT: No per-node VRF keys, simpler verification, lower overheadQNet implements state-of-the-art synchronization for rapid network joining:
- Full Snapshots: Every 12 hours / 43,200 microblocks / 480 macroblocks (complete blockchain state)
- Incremental Snapshots: Every 1 hour / 3,600 microblocks / 40 macroblocks (delta changes only)
- Compression: LZ4 for efficient storage (~70% reduction)
- Verification: SHA3-256 integrity checks
- Auto-Cleanup: Keep only latest 5 snapshots
- IPFS Integration: Optional decentralized snapshot sharing
- Multiple Gateways: Redundant download sources
- Peer Announcements: Automatic broadcast of new snapshots
- Pin on Upload: Ensures persistence in IPFS network
- Fast Sync Trigger: Activates when >50 blocks behind
- Multiple Workers: Concurrent block downloads
- Chunk Processing: 100-block batches for efficiency
- Timeout Protection: 60s fast sync, 30s normal sync
- Deadlock Prevention: Guard pattern with automatic reset
# Optional IPFS integration
export IPFS_API_URL="http://your-ipfs-node:5001"
# Sync parameters (defaults)
FAST_SYNC_THRESHOLD=50
SYNC_CHUNK_SIZE=100
SYNC_WORKERS=4| Component | Specification |
|---|---|
| CPU | 2 cores, 2.0 GHz |
| RAM | 4 GB |
| Storage | 50 GB SSD |
| Network | 10 Mbps |
| OS | Linux, macOS, Windows |
| Component | Specification |
|---|---|
| CPU | 4 cores, 3.0 GHz |
| RAM | 16 GB |
| Storage | 500 GB NVMe SSD |
| Network | 100 Mbps |
| OS | Ubuntu 20.04+ / CentOS 8+ |
| Component | Specification |
|---|---|
| CPU | 8+ cores, 3.5+ GHz (Intel i7/AMD Ryzen 7) |
| RAM | 32+ GB DDR4 |
| Storage | 1+ TB NVMe SSD (3000+ IOPS) |
| Network | 1 Gbps dedicated |
| OS | Ubuntu 22.04 LTS |
SECURITY CRITICAL: Node execution is strictly controlled
| Node Type | Allowed Execution Method | Prohibited |
|---|---|---|
| Genesis Nodes | β Docker containers only | β Direct binary execution |
| Full/Super Nodes | β Docker containers only | β Direct binary execution |
| Light Nodes | β Official mobile apps only | β Server execution |
IMPORTANT:
- Direct execution of
qnet-node.exeorqnet-nodebinary is BLOCKED - The binary will refuse to run outside Docker environment
- This is enforced for security and network integrity
# Update system packages
sudo apt update && sudo apt upgrade -y
# Install essential packages
sudo apt install -y curl wget git htop nano ufw fail2ban build-essential cmake pkg-config libssl-dev
# Configure timezone
sudo timedatectl set-timezone UTCQNet requires the latest Rust toolchain for optimal performance and security.
# Install Rust using rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
# Source the environment
source ~/.cargo/env
# Update to latest Rust version
rustup update
# Verify installation
rustc --version
cargo --version# Clone to home directory for production deployment
cd ~
git clone https://github.com/AIQnetLab/QNet-Blockchain.git
cd QNet-Blockchain
# Switch to testnet branch (latest production code)
git checkout testnet
git pull origin testnet# Clone and checkout testnet
git clone https://github.com/AIQnetLab/QNet-Blockchain.git
cd QNet-Blockchain
git checkout testnet
git pull origin testnet
# Build production Docker image
docker build -f development/qnet-integration/Dockerfile.production -t qnet-production .
# REQUIRED: Configure firewall BEFORE running node
# For UFW (Ubuntu/Debian):
sudo ufw allow 9876,9877,8001/tcp
sudo ufw allow 10876/udp
sudo ufw reload
# For iptables:
sudo iptables -A INPUT -p tcp --dport 9876 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 9877 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 8001 -j ACCEPT
sudo iptables -A INPUT -p udp --dport 10876 -j ACCEPT
# Run interactive production node (ONLY command needed)
docker run -it --name qnet-node --restart=always \
-p 9876:9876 -p 9877:9877 -p 8001:8001 -p 10876:10876/udp \
-v $(pwd)/node_data:/app/node_data \
qnet-production
# During interactive setup:
# 1. Select network (testnet/mainnet)
# 2. Enter activation code from wallet extension
# 3. Node activates automatically
# Get activation codes via QNet wallet extension or mobile app (P2P decentralized system)Note: All Solana contract configuration is embedded in the Docker image. No manual configuration required.
1DEV Burn Contract is successfully deployed on Solana Devnet:
- π΄ Program Address: D7g7mkL8o1YEex6ZgETJEQyyHV7uuUMvV3Fy3u83igJ7
- π¦ Program Data: HMbSTfp7fqsMopRqEy5u4fxQgLnYmM7ThPZzoo2VF4Gm
- π° Deployer Wallet: 6gesV5Dojg9tfH9TRytvXabnQT8U7oMbz5VKpTFi8rG4
- π Deploy Transaction: 4z2A93vJ527LayPu8baer4MxYT8hVkoGCumCeJPpn6mmKZUpPtFmzFatFg7sTA5wzCUubuLupmKRTcA26EwpcwRR
Contract Status:
- β Immutable (no upgrade authority)
- β Size: 368,896 bytes
- β Slot: 396,252,496
- β Network: Solana Devnet
Note: Without these environment variables, the node will use development fallback data for testing.
Wkg19zERBsBiyqsh2ffcUrFG4eL5BF5BWkg19zERBsBi on Solana devnet (Phase 1 ready).
Production Docker Deployment (ONLY METHOD):
# Clone and checkout testnet
git clone https://github.com/AIQnetLab/QNet-Blockchain.git
cd QNet-Blockchain
git checkout testnet
git pull origin testnet
# Build production Docker image
docker build -f development/qnet-integration/Dockerfile.production -t qnet-production .
# Run interactive production node
docker run -it --name qnet-node --restart=always \
-p 9876:9876 -p 9877:9877 -p 8001:8001 -p 10876:10876/udp \
-v $(pwd)/node_data:/app/node_data \
qnet-productionClean Build & Cache:
# Clean Docker system cache
docker system prune -f
# Remove all unused Docker images
docker image prune -a -f
# Clean node_modules if present
find . -name "node_modules" -type d -exec rm -rf {} +
# Clean .next and dist directories
find . -name ".next" -type d -exec rm -rf {} +
find . -name "dist" -type d -exec rm -rf {} +
# Rebuild Docker image from clean state
docker build --no-cache -f development/qnet-integration/Dockerfile.production -t qnet-production .Node Management:
# Check running containers
docker ps
# View logs
docker logs -f qnet-node
# Stop node
docker stop qnet-node
# Restart node
docker restart qnet-node
# Remove node (keeps data volume)
docker rm qnet-node# Remove node data volume (keeps Docker image)
docker volume rm qnet-node-data
# Remove entire installation
rm -rf ~/QNet-Blockchain
# Clean Docker resources
docker system prune -f# Backup important data before removal
mkdir -p ~/qnet-backup
cp -r ~/QNet-Blockchain/node_data/config ~/qnet-backup/
cp ~/QNet-Blockchain/node_data/*.key ~/qnet-backup/ 2>/dev/null || true
# Remove node data
rm -rf ~/QNet-Blockchain/node_dataQNet nodes run natively for maximum performance. Choose your node type based on available resources.
QNet nodes use device-specific deployment methods:
Server Nodes (Full/Super): Interactive setup menu on dedicated servers Mobile Nodes (Light): Mobile app activation on phones & tablets
| Node Type | Platform | Activation Method | API Server | Features |
|---|---|---|---|---|
| Light | π± Mobile phones & tablets | Mobile app only | β No | Basic sync, wallet |
| Full | π₯οΈ Servers, VPS, desktops | Interactive setup | β Yes | Full validation, API |
| Super | π₯οΈ Servers, VPS, desktops | Interactive setup | β Yes | Enhanced features, API |
- Light Nodes: Cannot be activated on servers/desktops
- Full/Super Nodes: Cannot be activated on mobile devices
- API Access: Only Full/Super nodes provide REST endpoints
# Configure firewall (ports auto-selected if 9876/9877 unavailable)
sudo ufw allow 9876 # P2P port (default)
sudo ufw allow 9877 # RPC port (default)
sudo ufw allow 9878 # Metrics port
sudo ufw --force enable
# Run auto-configured node setup (ZERO CONFIGURATION REQUIRED)
cd ~/QNet-Blockchain
./target/release/qnet-nodeNew Features:
- β Auto-port selection: Finds available ports if defaults are busy
- β Auto-region detection: Detects your location via IP geolocation
- β Auto-performance tuning: Always enables 100k+ TPS optimizations
- β Auto-bootstrap peers: Selects optimal peers for your region
- β
Smart data directory: Standard
node_datalocation
π === QNet Production Node Setup === π
π₯οΈ SERVER DEPLOYMENT MODE
Welcome to QNet Blockchain Network!
π§ Auto-configuring QNet node...
π Auto-detecting region from IP address...
β
Region auto-detected: Europe
π Selected ports: P2P=9876, RPC=9877
π Data directory: "node_data"
π Bootstrap peers: ["eu-bootstrap-1.qnet.io:9876", "eu-bootstrap-2.qnet.io:9876"]
π Detecting current network phase...
β
Phase 1 detected
π === Current Network Status ===
π₯ Phase 1: 1DEV Burn-to-Join Active
π 1DEV Burned: 45.0%
π° Universal Pricing: Same cost for all node types
π Dynamic Reduction: Lower prices as more tokens burned
π₯οΈ === Server Node Type Selection ===
β οΈ SERVERS ONLY SUPPORT FULL/SUPER NODES
π± Light nodes are restricted to mobile devices only
Choose your server node type:
1. Full Node - Servers/desktops, full validation
2. Super Node - High-performance servers, maximum rewards
π° Current Pricing:
1. Full Node : 900 1DEV
2. Super Node : 900 1DEV
Enter your choice (1-2):
- Auto-Configuration: System automatically detects region, ports, and performance settings
- Select Node Type: Choose between Full Node (1) or Super Node (2)
- Enter Activation Code: Provide your activation code from QNet wallet app
- Node Starts: Fully optimized node with 100k+ TPS capabilities begins sync
- Get activation code: Use QNet Browser Extension or Mobile App
- Purchase node license: Burn 1DEV tokens (Phase 1) or transfer QNC to Pool 3 (Phase 2)
- Server restriction: Full and Super nodes only for servers
- Light nodes: Mobile devices only - use QNet mobile app
For optimal performance, especially for Super nodes, consider these system optimizations:
# System optimization for high-performance nodes
echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf
echo 'net.core.rmem_max=134217728' | sudo tee -a /etc/sysctl.conf
echo 'net.core.wmem_max=134217728' | sudo tee -a /etc/sysctl.conf
echo 'net.core.netdev_max_backlog=5000' | sudo tee -a /etc/sysctl.conf
echo 'net.ipv4.tcp_congestion_control=bbr' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
# Optional: CPU governor for performance (not required by QNet)
# echo 'performance' | sudo tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor
# Disable huge pages if not needed
echo 'never' | sudo tee /sys/kernel/mm/transparent_hugepage/enabled
# Increase file descriptor limits
echo "* soft nofile 65536" | sudo tee -a /etc/security/limits.conf
echo "* hard nofile 65536" | sudo tee -a /etc/security/limits.conf# Check running containers
docker ps | grep qnet-node
# View real-time logs
docker logs qnet-node -f
# Stop node
docker stop qnet-node
# Restart node
docker restart qnet-node
# Remove container (keeps data volume)
docker rm qnet-node# Check if container is running
docker ps | grep qnet-node
# View real-time logs
docker logs qnet-node -f
# Check resource usage
docker stats qnet-node --no-stream# Test REST API endpoint
curl http://localhost:8001/api/v1/node/health
# Check peer connections
curl http://localhost:8001/api/v1/peers
# Check blockchain height
curl http://localhost:9877/api/v1/height
# Check sync status
curl http://localhost:8001/api/v1/node/info# Navigate to repository
cd ~/QNet-Blockchain
# Pull latest changes
git pull origin testnet
# Stop and remove old container
docker stop qnet-node
docker rm qnet-node
# Rebuild Docker image
docker build -f development/qnet-integration/Dockerfile.production -t qnet-production .
# Run updated container
docker run -it --name qnet-node --restart=always \
-p 9876:9876 -p 9877:9877 -p 8001:8001 -p 10876:10876/udp \
-v $(pwd)/node_data:/app/node_data \
qnet-productionπ Automatic Optimization on Restart:
- Shard count recalculates based on current network size
- Storage window adjusts automatically for optimal performance
- No manual configuration needed - node adapts to network growth
- Example: Network grew 5kβ150k nodes β restarts with 4 shards instead of 1
QNet features automatic node replacement when activating on a new server:
- 1 Wallet = 1 Active Node: Only one node per type per wallet can be active
- Seamless Migration: Activate on new server β old node automatically shuts down
- Quantum-Secure: All replacement signals use CRYSTALS-Dilithium signatures
- Blockchain Authority: Blockchain records are the source of truth
- Server Migration: Move Full/Super node to new hardware
- Hardware Upgrade: Seamless transition to more powerful server
- Node Type Upgrade: Full β Super activation replaces Full node
- Disaster Recovery: Reactivate on new server after hardware failure
# On NEW server - activate with same activation code
docker run -it --name qnet-node --restart=always \
-e QNET_PRODUCTION=1 \
-e QNET_BOOTSTRAP_ID=YOUR_ID \
-p 9876:9876 -p 9877:9877 -p 8001:8001 -p 10876:10876/udp \
-v $(pwd)/node_data:/app/node_data \
qnet-production
# Result: Old server node receives shutdown signal and terminates
# New server becomes the active node for your wallet- No manual migration required - fully automatic
- Previous node data remains on old server (backup if needed)
- Activation codes remain valid - bound to wallet, not hardware
- Light nodes (mobile) work the same way across devices
# Create backup
sudo tar czf /backup/qnet-backup-$(date +%Y%m%d).tar.gz ~/QNet-Blockchain/node_data
# Restore from backup
sudo tar xzf /backup/qnet-backup-YYYYMMDD.tar.gz -C ~/QNet-Blockchain/
sudo chown -R qnet:qnet ~/QNet-Blockchain/node_data# Mainnet nodes automatically connect to production bootstrap nodes
# No additional configuration requiredCurrent deployment runs on testnet automatically. Network selection is handled during the interactive setup - no manual configuration required.
Regional selection is handled automatically during the interactive setup based on your server's IP location. The system auto-detects your optimal region for best performance:
- North America: US, Canada, Mexico
- Europe: EU countries, UK, Norway, Switzerland
- Asia: Japan, Singapore, Hong Kong, South Korea
- South America: Brazil, Argentina, Chile
- Africa: South Africa, Nigeria, Kenya
- Oceania: Australia, New Zealand
No manual configuration required - regions are detected and selected automatically.
# Check node health
curl http://localhost:8001/api/v1/node/health
# Check peer connections
curl http://localhost:8001/api/v1/peers
# Check blockchain height
curl http://localhost:9877/api/v1/height
# Check node info
curl http://localhost:8001/api/v1/node/info# View recent logs (live monitoring)
docker logs qnet-node -f
# View detailed blockchain logs (if running in background)
tail -f node_data/qnet-node.log
# Search for errors
docker logs qnet-node | grep "ERROR"
# Monitor blockchain activity (blocks, consensus, P2P)
docker logs qnet-node | grep "CONSENSUS\|BLOCK\|P2P\|SYNC"
# Monitor performance metrics
docker logs qnet-node | grep "TPS\|latency\|performance"
# View peer connections and network status
docker logs qnet-node | grep "peer\|connection\|discovery"
# View last 100 lines
docker logs qnet-node --tail 100
# Filter by log level
docker logs qnet-node | grep "\[DEBUG\]\|\[INFO\]\|\[WARN\]\|\[ERROR\]"For genesis bootstrap nodes (production network initialization):
# PRODUCTION Genesis Nodes (each on separate server):
# Genesis Node #001 (154.38.160.39 - North America)
docker run -d --name qnet-genesis-001 --restart=always \
-e QNET_PRODUCTION=1 \
-e QNET_BOOTSTRAP_ID=001 \
-e DOCKER_ENV=1 \
-e QNET_AGGRESSIVE_PRUNING=0 \
-e QNET_MAX_STORAGE_GB=2000 \
-p 9876:9876 -p 9877:9877 -p 8001:8001 -p 10876:10876/udp \
-v $(pwd)/genesis_001_data:/app/data \
qnet-production
# Genesis Node #002 (62.171.157.44 - Europe)
docker run -d --name qnet-genesis-002 --restart=always \
-e QNET_PRODUCTION=1 \
-e QNET_BOOTSTRAP_ID=002 \
-e DOCKER_ENV=1 \
-e QNET_AGGRESSIVE_PRUNING=0 \
-e QNET_MAX_STORAGE_GB=2000 \
-p 9876:9876 -p 9877:9877 -p 8001:8001 -p 10876:10876/udp \
-v $(pwd)/genesis_002_data:/app/data \
qnet-production
# Genesis Node #003 (161.97.86.81 - Europe)
docker run -d --name qnet-genesis-003 --restart=always \
-e QNET_PRODUCTION=1 \
-e QNET_BOOTSTRAP_ID=003 \
-e DOCKER_ENV=1 \
-e QNET_AGGRESSIVE_PRUNING=0 \
-e QNET_MAX_STORAGE_GB=2000 \
-p 9876:9876 -p 9877:9877 -p 8001:8001 -p 10876:10876/udp \
-v $(pwd)/genesis_003_data:/app/data \
qnet-production
# Genesis Node #004 (5.189.130.160 - Europe)
docker run -d --name qnet-genesis-004 --restart=always \
-e QNET_PRODUCTION=1 \
-e QNET_BOOTSTRAP_ID=004 \
-e DOCKER_ENV=1 \
-e QNET_AGGRESSIVE_PRUNING=0 \
-e QNET_MAX_STORAGE_GB=2000 \
-p 9876:9876 -p 9877:9877 -p 8001:8001 -p 10876:10876/udp \
-v $(pwd)/genesis_004_data:/app/data \
qnet-production
# Genesis Node #005 (162.244.25.114 - Europe)
docker run -d --name qnet-genesis-005 --restart=always \
-e QNET_PRODUCTION=1 \
-e QNET_BOOTSTRAP_ID=005 \
-e DOCKER_ENV=1 \
-e QNET_AGGRESSIVE_PRUNING=0 \
-e QNET_MAX_STORAGE_GB=2000 \
-p 9876:9876 -p 9877:9877 -p 8001:8001 -p 10876:10876/udp \
-v $(pwd)/genesis_005_data:/app/data \
qnet-productionAuto-Configured Production Settings (QNET_PRODUCTION=1):
- β Sharding: 256 shards enabled
- β Parallel validation: 16 threads
- β P2P compression: enabled
- β Batch size: 10,000 transactions
- β Mempool: 2M transactions capacity
- β High frequency mode: enabled
- β VTS: 500K hashes/sec (Full/Super nodes only)
Genesis Node Requirements:
- Set
QNET_BOOTSTRAP_IDto 001-005 for genesis nodes - Each genesis node runs on its own server (same ports: 9876, 9877, 8001)
- IP addresses are hardcoded in
genesis_constants.rs- nodes auto-discover each other - Create data directory:
mkdir -p genesis_XXX_data && chmod 755 genesis_XXX_data/
π Genesis Node Security (IP-Based Authorization):
- IP Restriction: Genesis nodes can ONLY run from pre-authorized IP addresses
- Duplicate Prevention: System blocks attempts to run duplicate Genesis nodes from unauthorized IPs
- Auto-Detection: Node automatically detects server IP and validates against authorized list
- Manual Override: Use
QNET_MANUAL_IP=your.server.ipfor custom IP specification - Migration Ready: Easy to update authorized IP list for server migrations (VPSβVDS)
Authorized Genesis IPs (Default):
154.38.160.39 # Genesis Node 001
62.171.157.44 # Genesis Node 002
161.97.86.81 # Genesis Node 003
5.189.130.160 # Genesis Node 004
162.244.25.114 # Genesis Node 005Custom Genesis IPs:
# Override default IPs via environment variable
export QNET_GENESIS_NODES="ip1,ip2,ip3,ip4,ip5"
# Or create genesis-nodes.json config fileFor production deployment with 5 Genesis nodes on separate servers:
# Build Docker image (run once on each server)
docker build -f development/qnet-integration/Dockerfile.production -t qnet-production .
# Then run the appropriate command on each server:
# Server 154.38.160.39 β QNET_BOOTSTRAP_ID=001
# Server 62.171.157.44 β QNET_BOOTSTRAP_ID=002
# Server 161.97.86.81 β QNET_BOOTSTRAP_ID=003
# Server 5.189.130.160 β QNET_BOOTSTRAP_ID=004
# Server 162.244.25.114 β QNET_BOOTSTRAP_ID=005
# Monitor nodes
docker logs -f qnet-genesis-001
# Stop node
docker stop qnet-genesis-001
docker rm qnet-genesis-001Genesis Node Endpoints:
- Genesis Node 001: http://154.38.160.39:8001
- Genesis Node 002: http://62.171.157.44:8001
- Genesis Node 003: http://161.97.86.81:8001
- Genesis Node 004: http://5.189.130.160:8001
- Genesis Node 005: http://162.244.25.114:8001
Note: Activation codes are generated automatically by QNet consensus when burn transactions are detected on Solana.
// Every QNet node independently monitors Solana blockchain
let burn_transactions = monitor_solana_burns().await;
for burn_tx in burn_transactions {
if burn_tx.amount >= required_1dev && burn_tx.target == INCINERATOR {
// Detected valid burn - process activation
process_burn_for_activation(&burn_tx).await;
}
}// Quantum-secure deterministic generation via consensus
let consensus_leader = consensus.select_leader_for_burn(&burn_tx_hash);
if consensus_leader == self.node_id {
let activation_code = quantum_crypto.generate_activation_code(
&burn_tx_hash,
&wallet_address,
node_type
);
// Store only hash in blockchain for security
let code_hash = blake3::hash(activation_code.as_bytes());
blockchain.store_activation_hash(code_hash, &burn_tx).await;
}// Only activation code HASH stored on blockchain (not full code)
let activation_record = ActivationRecord {
code_hash: blake3::hash(activation_code.as_bytes()),
wallet_address: burn_tx.wallet,
node_type: burn_tx.node_type,
is_active: true,
};
blockchain.submit_activation_record(activation_record).await;- CRYSTALS-Dilithium signatures - quantum-resistant
- BLAKE3 + SHA3-512 hashing - deterministic from burn data
- Consensus verification - multiple nodes must agree
- Blockchain immutability - codes recorded on-chain
// Code generation requires:
// 1. Valid Solana burn transaction (on-chain proof)
// 2. Consensus agreement from QNet validators
// 3. Quantum-secure cryptographic binding
// 4. Blockchain recording with distributed validation
// Even if attacker runs "fake bridge":
// - Can't forge Solana burn transactions β
// - Can't bypass quantum crypto validation β
// - Can't fake consensus signatures β
// - Can't write to QNet blockchain without validation β// QNet wallet extension generates codes locally after burn
const burnTx = await solanaBurn.burn1DEV(amount, nodeType);
const activationCode = await qnetWallet.generateActivationCode(burnTx);
// Code stored locally in wallet, hash stored on blockchain// Mobile app generates codes after Solana burn transaction
const activationCode = await qnetMobile.generateFromBurn(burnTxHash);
// User keeps full code, only hash goes to blockchain# Query local node for your activation code (authenticated)
curl http://localhost:8001/api/v1/node/secure-info \
-H "Authorization: Bearer <wallet_signature>"- β True Decentralization: No centralized code generation servers
- β Quantum Security: Post-quantum cryptography throughout
- β Hash-Only Storage: Codes cannot be recovered from blockchain
- β Blockchain Native: Only hashes stored on immutable ledger
- β Privacy Enhanced: Full codes never leave user's device
- β Forgery Impossible: Cryptographic proofs at every layer
- β User Experience: Secure, private, reliable
# Backup node data
sudo tar -czf qnet-backup-$(date +%Y%m%d).tar.gz ~/QNet-Blockchain/node_data
# Backup configuration
sudo cp -r ~/QNet-Blockchain/node_data/config /backup/qnet-config-backup/
# Recovery
sudo tar -xzf qnet-backup-YYYYMMDD.tar.gz -C ~/QNet-Blockchain/
sudo chown -R qnet:qnet ~/QNet-Blockchain/node_data# Development build
cargo build
# Release build with optimizations
cargo build --release
# Run tests
cargo test
# Run benchmarks
cargo bench# Unit tests
cargo test --lib
# Integration tests
cargo test --test integration
# Performance tests
cargo test --test performance --releaseπ Full API Reference: See
docs/API_REFERENCE.mdfor complete endpoint documentation with request/response examples.
π Every Full/Super node provides complete API functionality:
# Node 1 API endpoints
curl http://localhost:8001/api/v1/node/info
curl http://localhost:8001/api/v1/blocks/{height}
curl http://localhost:8001/api/v1/transactions/{hash}
# Node 2 API endpoints
curl http://localhost:8002/api/v1/node/info
curl http://localhost:8002/api/v1/blocks/{height}
curl http://localhost:8002/api/v1/transactions/{hash}
# Node 3 API endpoints
curl http://localhost:8003/api/v1/node/info
curl http://localhost:8003/api/v1/blocks/{height}
curl http://localhost:8003/api/v1/transactions/{hash}Account Management:
GET /api/v1/account/{address}- Get account informationGET /api/v1/account/{address}/balance- Get account balance (QNC)GET /api/v1/account/{address}/transactions- Get transaction historyGET /api/v1/account/{address}/tokens- Get all QRC-20 tokens for address
QRC-20 Tokens (v2.19.12):
POST /api/v1/token/deploy- Deploy new QRC-20 tokenGET /api/v1/token/{address}- Get token info (name, symbol, decimals, supply)GET /api/v1/token/{address}/balance/{holder}- Get token balance for holder
Blockchain Data:
GET /api/v1/block/latest- Get latest blockGET /api/v1/block/{height}- Get block by heightGET /api/v1/block/hash/{hash}- Get block by hashGET /api/v1/microblock/{height}- Get microblock by heightGET /api/v1/macroblock/{index}- Get macroblock by index (finalized every 90 blocks)
Transactions:
POST /api/v1/transaction- Submit transactionGET /api/v1/transaction/{hash}- Get transaction details with Fast Finality Indicators- Returns:
finality_indicatorswith level, safety_percentage, confirmations, time_to_finality, risk_assessment
- Returns:
Network Status:
GET /api/v1/mempool/status- Get mempool statusGET /api/v1/nodes/discovery- Discover available nodesGET /api/v1/node/health- Check node healthGET /api/v1/gas/recommendations- Get gas price recommendations
// Production-ready client with multiple node support
const qnetNodes = [
'http://node1.example.com:8001', // Full node
'http://node2.example.com:8002', // Super node
'http://node3.example.com:8003' // Full node
];
async function qnetApiCall(endpoint, data = null) {
for (const nodeUrl of qnetNodes) {
try {
const response = await fetch(`${nodeUrl}/api/v1/${endpoint}`, {
method: data ? 'POST' : 'GET',
headers: data ? {'Content-Type': 'application/json'} : {},
body: data ? JSON.stringify(data) : null
});
if (response.ok) return await response.json();
} catch (error) {
console.log(`Node ${nodeUrl} unavailable, trying next...`);
}
}
throw new Error('All QNet nodes unavailable');
}π Architecture Benefits:
- β Distributed Access: Multiple nodes provide API access
- β Load Distribution: API traffic spread across multiple nodes
- β High Availability: Multiple nodes ensure service continuity
- β Scalability: More nodes = more API capacity
- β Redundancy: Built-in failover capabilities
π Node Requirements:
- Full/Super nodes provide REST API endpoints
- Light nodes focus on mobile functionality
- Each node offers identical API interface
Each Full/Super node also provides WebSocket endpoints for real-time updates:
// Connect to specific node WebSocket
const ws = new WebSocket('ws://localhost:9877/ws');
// Subscribe to new blocks
ws.send(JSON.stringify({
method: 'subscribe',
params: ['newBlocks']
}));
// Subscribe to new transactions
ws.send(JSON.stringify({
method: 'subscribe',
params: ['newTransactions']
}));WebSocket Endpoints:
ws://localhost:9877/ws- Node 1 WebSocketws://localhost:9879/ws- Node 2 WebSocketws://localhost:9881/ws- Node 3 WebSocket
QNet node deployment now features zero-configuration setup for maximum ease of use:
- IP-based geolocation: Automatically detects your geographic region
- Optimal bootstrap peers: Selects the best peers for your region
- Reduced latency: Connects to nearest network nodes
- Supported regions: North America, Europe, Asia, South America, Africa, Oceania
- Auto-port selection: Finds available ports if defaults are busy
- Default ports: P2P=9876, RPC=9877, Metrics=9878
- Port range scanning: Automatically scans for available ports in +100 range
- Conflict resolution: Handles port conflicts gracefully
π― NEW: Automatic Hardware Detection & Optimization
- CPU Auto-Detection: Uses all available cores (4-64+ cores automatically detected)
- Smart Parallel Validation: Auto-enables on 8+ core systems, disables on <8 cores
- Adaptive Mempool: Scales 100kβ2M transactions based on network size
- Zero Configuration: Works optimally on any hardware without manual tuning
Always Enabled:
- High-performance mode: 100k+ TPS optimizations active by default
- Microblock production: Enabled for all production nodes
- Optimized batching: 10,000 transactions per batch
- Dynamic thread allocation: Matches your CPU cores
Examples (automatic):
- 4-core VPS: 4 threads, parallel validation OFF
- 8-core server: 8 threads, parallel validation AUTO-ON
- 32-core server: 32 threads, parallel validation ON
- 64-core beast: 64 threads, maximum throughput
Optional CPU Limiting (for shared servers):
# Use only 50% of CPU (great for shared hosting)
docker run ... -e QNET_CPU_LIMIT_PERCENT=50 ...
# Cap at 8 threads (leave resources for other apps)
docker run ... -e QNET_MAX_THREADS=8 ...
# Examples:
# 32-core + 50% limit β 16 threads used
# 64-core + QNET_MAX_THREADS=16 β 16 threads max
# 16-core + no limit β all 16 threads (default)- Full QUIC Protocol: UDP-based transport with TLS 1.3 encryption
- Port: UDP 10876 (P2P port + 1000)
- Connection Multiplexing: 100+ streams per connection
- 0-RTT Handshake: Ultra-low latency for repeat connections
- Binary Protocol: bincode serialization (~50% bandwidth reduction)
- Connection Pooling: Automatic reconnection with idle cleanup
- NIST Compliant: TLS 1.3 per SP 800-52 guidelines
- Lock-Free Operations: DashMap for concurrent access without blocking (10M+ nodes)
- Auto-Scaling Mode: Automatic switching between HashMap (5 nodes) β DashMap (100+ nodes)
- O(1) Performance: Dual indexing by address and node ID for instant lookups
- 256 Shards: Distributed load across shards with cross-shard routing
- K-bucket Management: Max 20 peers per bucket with reputation-based replacement
- Post-quantum cryptography: CRYSTALS-Dilithium peer verification
- Adaptive peer limits: 8-500 connections per region based on network size
- Real-time topology: 1-second rebalancing intervals
- Blockchain peer registry: Immutable peer records in distributed ledger
- Zero file dependencies: Pure in-memory quantum-resistant protocols
- Bootstrap trust mechanism: Genesis nodes bypass verification for instant connectivity
- Byzantine safety: Strict 4-node minimum for decentralized consensus
- Emergency bootstrap: Cold-start fallback with cryptographic validation
| Node Type | Lock-Free Activation | Sharding Activation | Max Capacity |
|---|---|---|---|
| Light | 500+ peers | 10,000+ peers | 1M+ peers |
| Full | 100+ peers | 5,000+ peers | 10M+ peers |
| Super | 50+ peers | 5,000+ peers | 10M+ peers |
QNet implements efficient archival system for long-term blockchain scalability.
| Node Type | Storage Size | Data Retention | Sync Time |
|---|---|---|---|
| Light | ~50-100 MB | Headers + minimal state | <1 minute |
| Full | 50-100 GB | Sliding window (~18-74 days) | ~5 minutes |
| Super | 500 GB - 1 TB | Complete history forever | ~15 minutes |
- Smart Defaults: Automatically detects node type via
QNET_NODE_TYPEenvironment variable - Adaptive Sliding Window: Full nodes auto-scale storage window with network growth (100K Γ active_shards)
- Growth Pattern: ~36 GB/year for Super nodes (full history with advanced compression)
- Automatic Pruning: Full nodes prune old blocks every 10,000 blocks (~2.7 hours)
- Emergency Handling: Automatic cleanup when storage reaches 70-85-95% thresholds
- Advanced Compression: 5-level adaptive temporal compression (Zstd 0-22) based on block age (80% savings)
- Delta Encoding: ~95% space savings for sequential blocks (every 1000th block = checkpoint)
- State Snapshots: Efficient state recovery without storing all microblocks
- Long-term projection:
- 1 year: 37 GB
- 10 years: 360 GB
- 50 years: 1.8 TB β
| Network Size | Full Node Quota | Super Node Quota | Min Replicas |
|---|---|---|---|
| 5-15 nodes (Emergency) | 8 chunks | 15 chunks | 1 replica |
| 16-30 nodes (Small) | 6 chunks | 12 chunks | 2 replicas |
| 31-50 nodes (Medium) | 4 chunks | 10 chunks | 3 replicas |
| 50+ nodes (Large) | 3 chunks | 8 chunks | 3 replicas |
- Light Nodes: Always 0 chunks (mobile-optimized)
- Genesis Nodes: Variable based on network critical needs
- Automatic Scaling: System adapts quotas based on active node count
Environment Variable: QNET_AGGRESSIVE_PRUNING=1 (default: 0)
Safety Features:
- β Auto-disable: Automatically disabled if network has < 10 Super nodes
- β Genesis protection: Cannot enable during Genesis phase (5 nodes)
- β Super node immunity: Super nodes cannot enable (archival role)
- β Startup warning: Clear warnings about risks and network status
When to Consider:
# Only enable if ALL conditions are met:
β
Disk space critically low (< 50 GB available)
β
Network has 50+ Super nodes maintaining full archive
β
Full node type (not Light or Super)
β
You understand dependency on Super nodes for historical data
# Check network status first:
curl http://localhost:8001/api/v1/storage/stats
# Verify "super_nodes_in_network" >= 50Recommendation: Leave QNET_AGGRESSIVE_PRUNING=0 (default) unless absolutely necessary. Sliding window pruning is sufficient for most deployments.
- Hot Storage: Recent data on local SSD for immediate access
- Warm Storage: Compressed local cache for verification
- Cold Archive: Distributed across network nodes with replication
- Automatic Cleanup: Multi-tier cleanup system prevents storage overflow
IMPORTANT: Blockchain history is NEVER deleted - only cache optimization occurs
| Usage Level | Action | What Gets Cleaned |
|---|---|---|
| 70-85% | Standard Cleanup | Transaction pool cache (duplicates older than 24h) + RocksDB compression |
| 85-95% | Aggressive Cleanup | Transaction pool cache (duplicates older than 6h) + maximum compression |
| 95%+ | Emergency Cleanup | Transaction pool cache (duplicates older than 1h) + emergency compression |
- Complete blockchain history: All blocks preserved forever
- All transactions: Full transaction records maintained in blockchain storage
- All microblocks: Complete microblock chain maintained
- Account states: All account history preserved
- Consensus data: All validation records kept
- Transaction pool cache: Temporary duplicates for fast access (TTL cleanup)
- RocksDB compression: Automatic compression of older data (reversible)
- Storage layout: Database compaction for optimal disk usage
- Memory usage: In-RAM caches cleared to free memory
- Testnet Start: 300 GB per node (QNET_MAX_STORAGE_GB=300)
- Mainnet Growth: 400-500 GB per node for large networks
- Genesis Nodes: 1 TB recommended for critical infrastructure
Storage Growth Projection:
Year 1-2: ~25-50 GB β
300 GB sufficient
Year 3-5: ~120-150 GB β
300 GB sufficient
Year 6-8: ~200-250 GB β οΈ Consider 400-500 GB
Year 10+: ~300+ GB π§ Increase to 500-1000 GB
What happens when storage limit is reached:
-
95% Full (285+ GB):
- Emergency cleanup automatically triggered
- Transaction cache cleared (duplicates only)
- Database compression applied
- Blockchain history preserved
-
100% Full (300 GB):
- System attempts emergency cleanup first
- If still full, new blocks cannot be saved
- Node logs critical warnings
- Admin must increase
QNET_MAX_STORAGE_GBor add disk space
-
Automatic Protection:
- System will never delete blockchain history
- Only cache and duplicate data is cleaned
- Full transaction records always preserved
- All consensus data maintained
Recommended Actions by Network Age:
- Year 1: 300 GB default β
- Year 3+: Set
QNET_MAX_STORAGE_GB=500 - Year 5+: Set
QNET_MAX_STORAGE_GB=750 - Year 10+: Set
QNET_MAX_STORAGE_GB=1000 - Emergency Handling: Automatic cleanup maintains operation at 95%+ usage
- Admin Alerts: Hourly monitoring with critical storage notifications
- Minimum 3 replicas per archive chunk across different nodes
- Automatic rebalancing when nodes disconnect or migrate
- Background compliance monitoring every 4 hours
- Mandatory archival participation for Full/Super nodes
Reputation System Details:
| Behavior | Change | Description |
|---|---|---|
| Double-Sign Detection | -50.0 points | Major Byzantine fault - immediate ban if < 10% |
| Failed Block Production | -20.0 points | Microblock production failure |
| Failed Consensus Lead | -30.0 points | Macroblock consensus failure |
| Passive Recovery | +1.0 points | Once per 4h if score [10,70), NOT jailed |
| Emergency Recovery | +5.0 to +50.0 | Bonus for saving the network |
| Ban Threshold | < 10% | Node removed from network (7-day recovery for regular nodes) |
| Consensus Threshold | β₯ 70% | Minimum to participate in consensus |
Reputation Consequences:
- <70% Reputation: Excluded from consensus participation AND new rewards
- <10% Reputation: Automatically banned from network (can still claim old rewards)
- Hourly Decay: -1% automatic reputation decay for inactive Full/Super nodes
- Light Nodes: Fixed 70% reputation (immutable, always eligible for rewards)
Universal Node Security (Full Decentralization):
- Starting Reputation: 70% for Full/Super nodes (consensus threshold)
- Light Node Reputation: Fixed at 70% (immutable by design)
- No Special Protection: Genesis nodes = Regular nodes
- Full Penalties Apply: Any Full/Super node can be reduced to 0% and banned
- Merit-Based System: Full/Super nodes must maintain good behavior
- Consensus Participation: β₯70% required for Full/Super nodes
- Light Nodes: Never participate in consensus (rewards only)
- Data Transfer: Archive responsibilities transfer with node migration
- Network Continuity: Distributed system continues during node changes
- Integrity Verification: Cryptographic verification of all data transfers
- Compliance Inheritance: New device inherits previous archival obligations
- Post-quantum crypto: Always enabled (CRYSTALS-Dilithium, AES-256-GCM)
- AES-256-GCM Database Encryption: Activation codes encrypted, key never stored
- Database Theft Protection: Cannot decrypt without activation code
- Critical Attack Protection: Instant 1-year ban for database/chain attacks
- Privacy-Preserving Pseudonyms: Network topology protection in all logs
- Secure by default: No insecure fallback modes
- Activation validation: Cryptographic proof of node purchase
- Device Migration Security: Automatic old device deactivation, rate limiting
- Network isolation: Proper firewall configuration
- Privacy Protection: All IP addresses hashed (SHA3-256), never exposed
- No System Metrics: Removed CPU/memory monitoring for privacy
- Deterministic Consensus: Cryptographic selection prevents forks
- Enhanced Concurrency: RwLock for better parallel performance
Status: β IMPLEMENTED - Private bundle submission with post-quantum signatures
Implementation Details:
QNet implements Private Bundle MEV protection (Flashbots-style) compatible with 1-second microblocks:
Architecture:
User Transaction Flow:
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Standard TX Path (Public) β
β User β Public Mempool β Block Producer β Microblock β
β β
β MEV-Protected Path (Private Bundles) β
β User β Direct to Producer β Microblock (if conditions met) β
β β β
β Fallback to Public Mempool (if rejected/timeout) β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Bundle Constraints (Production Tested β ):
| Constraint | Value | Purpose |
|---|---|---|
| Max TXs per Bundle | 10 | Prevent block space monopolization |
| Reputation Gate | 80%+ | Proven trustworthy nodes only |
| Gas Premium | +20% | Economic incentive for inclusion |
| Max Lifetime | 60 seconds | 60 microblocks max (prevent stale bundles) |
| Rate Limiting | 10 bundles/min per user | Anti-spam protection |
| Block Allocation | 0-20% dynamic | 80-100% guaranteed for public TXs |
| Multi-Producer Submission | 3 producers | Redundancy and load distribution |
| Signature Verification | Dilithium3 | Post-quantum security |
Why QNet Still Has Natural MEV Resistance:
QNet's reputation-based consensus + Private Bundles provides dual-layer protection:
| Layer | Traditional Staking | QNet Hybrid Model |
|---|---|---|
| Base Incentive | Maximize staking returns | Maintain reputation score |
| MEV Risk | π΄ High (financial benefit) | π’ Low (reputational damage + optional bundles) |
| Attack Cost | Lose stake (recoverable) | Lose reputation (permanent) + bundle rejection |
| Producer Window | Long (varies) | Short (30 blocks = 30 seconds) |
| User Protection | Optional (MEV marketplaces) | Built-in (Private Bundles) β |
Implementation Features:
- Dynamic Allocation: 0-20% block space for bundles based on demand
- No demand β 0% allocation β 100% public TXs
- High demand β scales to 20% β 80% public TXs guaranteed
- Atomic Inclusion: All bundle TXs included together or rejected entirely
- Auto-Fallback: Failed bundles automatically fall back to public mempool
- Priority Mempool: Public TXs prioritized by gas price (anti-spam)
- Post-Quantum Signatures: All bundles verified with Dilithium3
- Real-Time Tested: 11/11 tests passed in production environment
API Endpoints:
# Submit bundle
POST /api/v1/bundle/submit
# Get bundle status
GET /api/v1/bundle/{id}/status
# Cancel bundle
DELETE /api/v1/bundle/{id}Natural Resistance + Active Protection:
- β Base Layer: Reputation system prevents most MEV exploitation
- β Active Protection: Private bundles for high-value TXs
- β No Staking Required: Merit-based, not capital-based
- β Byzantine Safe: 2/3+ honest nodes ensure security
- β Scalable: Works from 5 Genesis nodes to millions
Status: Reputation-based system only, no validator staking required (by design)
Why QNet Doesn't Use Traditional Staking:
QNet implements a fundamentally different economic security model that doesn't require validator staking:
| Security Layer | Traditional Staking (ETH/Cosmos) | QNet Multi-Layer Model |
|---|---|---|
| Entry Barrier | Large capital stake required | 1DEV burn (Phase 1) + QNC pool contribution (Phase 2) |
| Cost Type | Recoverable (can withdraw stake) | Permanent (burn is irreversible) |
| Attack Cost | Lose stake (financial) | Lose burn + reputation + time investment |
| Recovery | Re-stake immediately | Months of reputation rebuilding |
| Inclusivity | Capital-gated (plutocracy) | Merit-based (everyone can join) |
QNet's Multi-Layer Security Model:
Layer 1: Economic Barrier (Without Staking)
βββ Phase 1: 1DEV token burn (permanent cost, irreversible)
βββ Phase 2: QNC pool contribution (5K-30K QNC, dynamic based on network size)
βββ Anti-Sybil: Cost increases with network growth
Layer 2: Time Barrier (Recovery Protection)
βββ New nodes start at 70% reputation (instant eligibility!)
βββ Reputation loss β slow recovery (prevents repeat attacks)
βββ Gradual recovery: penalized nodes need months to rebuild trust
Layer 3: Coordination Complexity
βββ Byzantine attack requires 67%+ of network
βββ Large networks: coordination becomes exponentially harder
βββ Example: 1M nodes network = 670K nodes must coordinate
Layer 4: Reputation Slashing (Cryptographic Proof Only)
βββ DoubleSign: -100% β permanent ban (proof: 2 sigs at same height)
βββ InvalidBlock: -20% (proof: bad signature/hash)
βββ ChainFork: -100% β permanent ban (proof: conflicting blocks)
βββ MissedBlocks: NOT slashable (no proof possible, use reputation decay)
βββ consensus_score < 70% β excluded from consensus
Layer 5: Network Effects
βββ Larger network = stronger security (without staking!)
βββ Detection probability increases with scale
βββ Attack cost increases exponentially with network size
Why Burn > Stake for Security:
| Aspect | Traditional Staking | QNet Burn Model |
|---|---|---|
| Sybil Attack Cost | Can recover stake after | Permanent loss of burned tokens |
| Market Impact | Large stake movements visible | Burn reduces supply (deflationary pressure) |
| Instant Power | Yes (stake and join) | No (need reputation + time) |
| Inclusivity | Excludes those without capital | Open to anyone willing to burn entry fee |
| Centralization Risk | Whales/exchanges dominate | Merit-based, not capital-based |
Philosophical Advantages:
- True Decentralization: No plutocracy - anyone can participate regardless of capital
- Merit Over Money: Behavior and time investment matter more than wealth
- Permanent Commitment: Burn shows real commitment (can't just withdraw)
- Scale = Security: Network security increases naturally with growth (no additional staking needed)
- No Liquidity Lock: Participants don't need to lock large capital amounts
Current Security System:
// Reputation Penalties (Primary Defense)
ReputationEvent::InvalidBlock => -20 points
ReputationEvent::MaliciousBehavior => -50 points
ReputationEvent::DoubleSign => -100 points (instant jail)
consensus_score < 70% β excluded from consensus
consensus_score < 10% β complete network ban
// Economic Barriers (Built-in)
Phase 1: 1DEV burn requirement (300-1500 1DEV based on network stage)
Phase 2: QNC pool contribution (5K-30K QNC, dynamic based on network size)
// Time Barriers (Recovery Protection, NOT Entry)
New nodes: start at 70% reputation (instant consensus eligibility!)
Penalized nodes: slow recovery (months to rebuild trust)
Prevents repeat attacks: attackers can't instantly rejoin after penaltyWhen Staking Might Be Reconsidered:
- If community governance votes for it (decentralized decision)
- If large-scale coordinated attacks observed despite current security
- If network demonstrates need for additional economic deterrent
- Note: Current design is intentional and philosophically aligned with true decentralization
Why This Approach Is Superior for QNet:
- β Inclusive: No capital barrier prevents small participants from joining
- β Permanent Cost: Burn is irreversible (stronger deterrent than recoverable stake)
- β Repeat Attack Prevention: Penalized attackers need months to recover (can't instantly retry)
- β Coordination-Resistant: Large-scale attacks become exponentially harder with network growth
- β Philosophically Consistent: Merit-based rather than money-based power
- β Simpler: No stake management, no slashing disputes, no withdrawal queues
November 15, 2025 - "Deterministic Producer Selection & Macroblock Consensus Listener"
This release introduces critical improvements for quantum-resistant consensus:
- Deterministic Producer Selection with Dilithium + Ed25519 hybrid cryptography and finality window entropy
- Race-Free Rotation: No delays at block boundaries (31, 61, 91)
- Active Macroblock Consensus: All Full/Super nodes run 1-second polling listener
- Deterministic Validator Selection: 1000 validators per macroblock round
- Improved Failover: Consensus state cleanup prevents stuck states
- Reputation Rewards incentivize active network participation
- State Snapshots enable rapid node synchronization
- Parallel Downloads accelerate blockchain sync by 3-5x
- Deadlock Prevention ensures network stability
See CHANGELOG.md for detailed release notes.
Blockchain Infrastructure (BSL 1.1 - Perpetual Proprietary):
- Core blockchain components, node software, consensus, and infrastructure
- Non-production use: FREE (testing, development, evaluation)
- Production use: Requires commercial license from AIQnetLab
- Proprietary: Remains under BSL 1.1 indefinitely (no open-source conversion)
- Protected: Cannot be used for competing networks or hosted services
- See LICENSE for complete terms
Client Applications (Apache 2.0):
- Mobile wallet, browser extension, explorer, CLI tools
- Fully open-source with no restrictions
- See individual application LICENSE files for details
Website: https://aiqnet.io Telegram: https://t.me/AiQnetLab Twitter: https://x.com/AIQnetLab
QNet is experimental software. Use at your own risk. Always test thoroughly before using in production environments.
QNet Blockchain Project