> For the complete documentation index, see [llms.txt](https://quantumwing.gitbook.io/quantumwing/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://quantumwing.gitbook.io/quantumwing/architecture/overview.md). # Overview Deep dive into QuantumWing's three-layer architecture and design principles ## 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 QWING) │ │ │ │ • 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 QWING) ``` ### 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="/pages/JJ7oxU4e3GI5FZdMBtCz" %} [Trust Boundaries](/quantumwing/architecture/trust-boundaries.md) {% 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](/quantumwing/architecture/canonical-encoding.md) ### 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 layerThree-Layer Design
📐 Canonical EncodingDeterministic binary block-header formatCanonical Encoding
🔒 Trust BoundariesSecurity architectureTrust Boundaries
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://quantumwing.gitbook.io/quantumwing/architecture/overview.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.