# Overview ## High-Level Architecture QuantumWing implements a **production-grade three-layer architecture** inspired by Ethereum 2.0's separation of concerns, with quantum-safe cryptography at every layer. ``` ┌─────────────────────────────────────────────────────┐ │ VALIDATOR LAYER (Off-Chain) │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │Validator │ │Validator │ │Validator │ ... │ │ │ #1 │ │ #2 │ │ #3 │ │ │ └──────────┘ └──────────┘ └──────────┘ │ │ │ │ │ │ │ └─────────────┴─────────────┘ │ │ Dilithium Signatures │ │ │ │ └──────────────────────┼──────────────────────────────┘ │ REST API │ (Attestations & Proposals) ▼ ┌─────────────────────────────────────────────────────┐ │ BEACON CHAIN (Port: 8080) │ │ Consensus & Validator Coordination │ │ │ │ ┌──────────────────────────────────────────────┐ │ │ │ Proof of Randomness (PoR) Engine │ │ │ │ • VRF validator selection │ │ │ │ • RANDAO commit-reveal │ │ │ │ • Dilithium signature verification │ │ │ │ • Epoch/slot progression (12s slots) │ │ │ └──────────────────────────────────────────────┘ │ │ │ │ ┌──────────────────────────────────────────────┐ │ │ │ Validator Registry │ │ │ │ • Stake tracking (min 32 ETH) │ │ │ │ • Duty scheduling │ │ │ │ • Slashing conditions │ │ │ └──────────────────────────────────────────────┘ │ │ │ │ └──────────────────────┼──────────────────────────────┘ │ REST API │ (Block Verification) ▼ ┌─────────────────────────────────────────────────────┐ │ EXECUTION LAYER (Port: 8546) │ │ Transaction Processing & State Management │ │ │ │ ┌──────────────────────────────────────────────┐ │ │ │ Transaction Pool │ │ │ │ • EVM-compatible 0x addresses │ │ │ │ • Dilithium-signed transactions │ │ │ │ • Gas fee calculation │ │ │ └──────────────────────────────────────────────┘ │ │ │ │ ┌──────────────────────────────────────────────┐ │ │ │ QWVM (Quantum WebAssembly VM) │ │ │ │ • WebAssembly smart contracts │ │ │ │ • Quantum-safe host functions │ │ │ │ • Metered gas execution │ │ │ └──────────────────────────────────────────────┘ │ │ │ │ ┌──────────────────────────────────────────────┐ │ │ │ State Storage (BadgerDB) │ │ │ │ • Account balances & nonces │ │ │ │ • Contract storage │ │ │ │ • Merkle state roots │ │ │ └──────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────┘ ``` ## Layer Responsibilities ### 🏗️ Execution Layer **Purpose**: Process transactions and maintain world state **Key Functions**: * ✅ Transaction validation and execution * ✅ Account balance management * ✅ Smart contract execution (QWVM) * ✅ State persistence (BadgerDB) * ✅ JSON-RPC + REST API (port 8546) * ✅ P2P transaction gossip **Trust Model** (Defense-in-Depth): * **Independently verifies** ALL Dilithium signatures on blocks * **Independently verifies** VRF proofs (even if beacon already verified) * **Does NOT trust** beacon chain blindly - validates all cryptographic proofs * **Protection**: Prevents compromised beacon nodes or P2P network attacks **State**: Millions of accounts (Year 1 projection) | Storage scales with adoption ### ⛓️ Beacon Chain **Purpose**: Coordinate consensus and validators **Key Functions**: * ✅ Proof of Randomness (PoR) consensus * ✅ VRF-based validator selection * ✅ RANDAO commit-reveal for randomness * ✅ Dilithium signature verification * ✅ Epoch/slot timing (12s slots, 32 slots/epoch) * ✅ Validator registry & stake tracking * ✅ Slashing conditions enforcement **Trust Model**: * **Verifies ALL** Dilithium signatures * **Guarantees** cryptographic finality after 64 slots * **Exposes** REST API for execution layer **State**: `~10,000 validators` | `~1 GB` storage ### 👥 Validator Layer **Purpose**: Propose blocks and attest to chain head **Key Functions**: * ✅ Block proposal when selected by VRF * ✅ Attestation submission every slot * ✅ RANDAO reveal in block proposals * ✅ Dilithium signature generation * ✅ Slashing protection (double-sign prevention) **Trust Model**: * **Holds** private Dilithium keys * **Communicates** only with beacon chain * **Receives** rewards/penalties from beacon **State**: `1 key per validator` | `~100 KB` each ## Communication Flow ### Block Production Flow ```mermaid sequenceDiagram participant V as Validator participant B as Beacon Chain participant E as Execution Layer Note over B: Slot N begins (12s timer) B->>B: VRF selects proposer B->>V: "You're proposer for slot N" V->>E: Request pending transactions E->>V: Transaction bundle V->>V: Create block + RANDAO reveal V->>V: Sign with Dilithium V->>B: Submit signed block B->>B: Verify Dilithium signature B->>B: Verify RANDAO reveal B->>B: Check VRF proof B->>E: "Execute this block" E->>E: Process transactions E->>E: Update state E->>B: State root hash B->>B: Store block in chain B->>V: Reward validator (+0.01 ETH) ``` ### Attestation Flow ```mermaid sequenceDiagram participant V1 as Validator 1 participant V2 as Validator 2-64 participant B as Beacon Chain Note over B: Slot N completed B->>V1: "Attest to block N" B->>V2: "Attest to block N" V1->>B: Dilithium-signed attestation V2->>B: 63 more attestations B->>B: Verify all 64 signatures B->>B: Aggregate attestations alt 2/3+ validators attested B->>B: Mark block N as finalized Note over B: Finality achieved! else <2/3 validators attested B->>B: Orphan block N Note over B: Re-propose in slot N+1 end ``` ## Trust Boundary Architecture {% content-ref url="trust-boundaries" %} [trust-boundaries](https://quantumwing.gitbook.io/quantumwing/architecture/trust-boundaries) {% endcontent-ref %} ### Critical Boundaries | Boundary | Trust Mechanism | Security Level | | ---------------------- | --------------------------- | ---------------------- | | **Validator → Beacon** | Dilithium Mode 3 signatures | 192-bit (NIST Level 3) | | **Beacon → Execution** | Authenticated REST API | TLS 1.3 + mTLS | | **Execution → State** | Merkle proofs | SHA3-256 (256-bit) | | **P2P Network** | libp2p + Noise protocol | 256-bit symmetric | ## Performance Characteristics ### Latency Breakdown | Operation | Latency | Bottleneck | | -------------------------- | -------- | ---------------------- | | **Transaction gossip** | 150ms | P2P propagation | | **Execution** | 50ms | QWVM execution | | **Signature verification** | 120ms | Dilithium Mode 3 | | **State write** | 30ms | BadgerDB sync | | **Block proposal** | 2s | Validator coordination | | **Finality** | 12.8 min | 64-slot waiting period | ### Throughput Limits ``` ┌─────────────────────────────────────────┐ │ Layer Throughput Limit │ ├─────────────────────────────────────────┤ │ Execution 2000 TPS BadgerDB │ │ Beacon 64 blocks/s CPU │ │ Validator 10 K sigs/s Dilithium│ │ Network 100 MB/s Bandwidth│ └─────────────────────────────────────────┘ ``` ## Quantum Safety Guarantees ### ✅ Quantum-Safe Components * **Signatures**: Dilithium Mode 3 (NIST-approved, 192-bit security) * **Hashing**: SHA3-256 (quantum-resistant, 256-bit output) * **VRF**: SHA3-based (no quantum-vulnerable primitives) * **Merkle Trees**: SHA3-256 collision resistance ### ✅ Fully Quantum-Resistant (October 2025) * **P2P Encryption**: Kyber-1024 (NIST FIPS 203 ML-KEM) ✅ **INTEGRATED** * 256-bit quantum-safe security * Automatic initialization on network startup * Unique keypairs per node * **Remaining Upgrades**: * **TLS Certificates**: RSA/ECDSA (vulnerable) → Dilithium certificates planned Q1 2026 ## Comparison with Other Blockchains | Feature | QuantumWing | Ethereum 2.0 | Bitcoin | | ------------------- | ------------------ | ----------------- | ----------------- | | **Consensus** | PoR (VRF + RANDAO) | PoS (Casper FFG) | PoW (SHA-256) | | **Signature** | Dilithium Mode 3 | ECDSA (secp256k1) | ECDSA (secp256k1) | | **Block Time** | 12s | 12s | 10 min | | **Finality** | 12.8 min | \~15 min | \~60 min | | **Smart Contracts** | QWVM (Wasm) | EVM | None | | **Quantum-Safe** | ✅ Yes (192-bit) | ❌ No | ❌ No | | **Address Format** | 0x... (EVM-compat) | 0x... | bc1... | ## Design Principles ### 1. **Separation of Concerns** Each layer has a single responsibility: * Execution = State * Beacon = Consensus * Validator = Participation ### 2. **Defense-in-Depth Security** ``` Execution independently verifies ALL signatures + VRF proofs ↓ Beacon verifies everything (primary consensus layer) ↓ Validators trust Beacon's VRF selection (but Execution double-checks) Result: Even if Beacon compromised, Execution rejects fake blocks ``` ### 3. **Canonical Binary Encoding** **Why**: JSON signing is non-deterministic (key order, whitespace, floats) **Solution**: 3409-byte deterministic binary format for signatures ``` [32B ParentHash][8B Slot][8B ProposerIndex][32B StateRoot] [32B BodyRoot][3293B VRFProof] = 3409 bytes ``` **Impact**: * ✅ Identical signatures across all validators * ✅ 1000x faster encoding (2.5 μs vs 2.5 ms) * ✅ No JSON parser ambiguities * ✅ Domain-separated hashing prevents replay attacks **Read more**: [canonical-encoding.md](https://quantumwing.gitbook.io/quantumwing/architecture/canonical-encoding) ### 4. **Quantum Future-Proofing** All cryptographic primitives are NIST-approved post-quantum algorithms: * Dilithium Mode 3 (signatures) - 3293 bytes * SHA3-256 (hashing) * Kyber-1024 (✅ PRODUCTION - P2P encryption integrated October 2025) ### 5. **EVM Compatibility** * 0x-prefixed addresses (derived from Dilithium public key) * JSON-RPC API compatibility * Gas pricing model * Transaction format similarity ## Further Reading
🏗️ Three-Layer DesignDeep dive into each layerhttps://github.com/dolfrin/QuantumWing/blob/master/docs/architecture/three-layer-design.md
📐 Canonical EncodingSSZ serialization formatcanonical-encoding
🔒 Trust BoundariesSecurity architecturetrust-boundaries