# FAQ

## General Questions

### What is QuantumWing?

QuantumWing is a **production-ready quantum-safe blockchain** that combines three-layer architecture (Execution/Beacon/Validator), post-quantum cryptography (Dilithium Mode 3), and Proof of Randomness (PoR) consensus. It provides EVM-compatible addresses, WebAssembly smart contracts (QWVM), and comprehensive P2P networking while protecting against quantum computer attacks.

**Key characteristics:**

* **Quantum-Safe**: Dilithium Mode 3 signatures (NIST-approved)
* **Three-Layer**: Ethereum 2.0-style architecture
* **EVM-Compatible**: 0x addresses from quantum-safe keys
* **Production Score**: 80/100

***

### Why do we need quantum-safe blockchains?

**The Quantum Threat:**

Current blockchains (Bitcoin, Ethereum, Solana) use cryptography vulnerable to quantum computers:

| Algorithm             | Purpose       | Quantum Vulnerable? | Attack Method      |
| --------------------- | ------------- | ------------------- | ------------------ |
| **ECDSA** (secp256k1) | Signatures    | ✅ YES               | Shor's algorithm   |
| **RSA-2048**          | TLS, P2P keys | ✅ YES               | Shor's algorithm   |
| **X25519**            | Key exchange  | ✅ YES               | Shor's algorithm   |
| **SHA-256**           | Hashing       | ⚠️ Partial (Grover) | Brute force faster |

**Timeline:**

* **2030-2035**: Quantum computers may break ECDSA/RSA
* **"Harvest now, decrypt later"**: Attackers record encrypted data today, decrypt when quantum computers arrive

**QuantumWing Solution:**

```
Traditional Blockchain:
├─ Signatures: ECDSA (256-byte) → Broken by Shor's algorithm
└─ Result: All funds stolen when quantum arrives

QuantumWing:
├─ Signatures: Dilithium Mode 3 (3,293-byte) → Quantum-safe!
└─ Result: Secure for next 50+ years
```

***

### What makes Dilithium quantum-safe?

**Dilithium Mode 3** is based on **lattice cryptography** (Module-LWE), approved by NIST in 2022 as a post-quantum standard.

**How it works:**

```
Classical ECDSA:
Problem: Solve y = g^x (discrete logarithm)
Quantum Attack: Shor's algorithm solves in polynomial time

Dilithium:
Problem: Find short vector in high-dimensional lattice
Quantum Attack: No known quantum algorithm (NP-hard even for quantum)
```

**Security levels:**

* Mode 2: 128-bit security (equivalent to AES-128)
* **Mode 3: 192-bit security** (QuantumWing uses this)
* Mode 5: 256-bit security

**Trade-off:**

* ❌ Larger signatures: 3,293 bytes vs 65 bytes (ECDSA)
* ✅ Quantum-safe for 50+ years
* ✅ Fast verification: \~0.1ms per signature

***

### How is QuantumWing different from Ethereum?

| Feature             | Ethereum         | QuantumWing                        |
| ------------------- | ---------------- | ---------------------------------- |
| **Signatures**      | ECDSA (65 bytes) | Dilithium Mode 3 (3,293 bytes)     |
| **Quantum-Safe**    | ❌ NO             | ✅ YES                              |
| **Consensus**       | Proof of Stake   | Proof of Randomness (VRF + RANDAO) |
| **Smart Contracts** | EVM (Solidity)   | QWVM (WebAssembly: Rust/C/Go)      |
| **Addresses**       | 0x... (20 bytes) | 0x... (20 bytes, quantum-safe)     |
| **Finality**        | \~12.8 minutes   | \~12.8 minutes                     |
| **Block Time**      | 12 seconds       | 12 seconds                         |
| **Storage**         | LevelDB          | BadgerDB (60% compressed)          |
| **P2P**             | devp2p           | libp2p (GossipSub + DHT)           |

**Key Difference:**

* Ethereum: **Will be vulnerable** when quantum computers arrive
* QuantumWing: **Already quantum-safe** today

***

### What is "Production Score 80/100"?

QuantumWing underwent comprehensive production readiness assessment across 10 categories:

| Category         | Score      | Status                     |
| ---------------- | ---------- | -------------------------- |
| Consensus (PoR)  | ✅ 90/100   | VRF + RANDAO operational   |
| Cryptography     | ✅ 95/100   | Dilithium + SHA3 verified  |
| State Management | ✅ 85/100   | BadgerDB + Merkle trees    |
| P2P Networking   | ✅ 85/100   | libp2p production-ready    |
| Smart Contracts  | ✅ 80/100   | QWVM operational           |
| Gas & Economics  | ✅ 75/100   | Fee model under evaluation |
| Monitoring       | ✅ 75/100   | Prometheus + Grafana       |
| API Layer        | ✅ 90/100   | JSON-RPC + REST + gRPC     |
| Testing          | ⚠️ 70/100  | Integration tests pending  |
| Documentation    | ✅ 85/100   | Comprehensive GitBook      |
| **TOTAL**        | **80/100** | Production-ready           |

**What this means:**

* ✅ Core blockchain features operational
* ✅ Can run validators, process transactions, deploy contracts
* ⚠️ Some features still being finalized (gas pricing, testing coverage)

***

## Architecture Questions

### What is "three-layer architecture"?

QuantumWing separates blockchain into three independent layers (inspired by Ethereum 2.0):

```
┌─────────────────────────────────────────────────────┐
│           VALIDATOR LAYER (No Port)                 │
│  • Generate Dilithium signatures                    │
│  • Propose blocks when selected by VRF             │
│  • Submit attestations                             │
│  • Participate in RANDAO commit-reveal             │
└─────────────────────────────────────────────────────┘
                        │
                   REST API
                        │
┌─────────────────────────────────────────────────────┐
│            BEACON CHAIN (Port 8080)                 │
│  • Proof of Randomness consensus                   │
│  • Validator selection (VRF)                       │
│  • Epoch/slot progression (12s slots)              │
│  • Dilithium signature verification                │
│  • RANDAO randomness aggregation                   │
└─────────────────────────────────────────────────────┘
                        │
                   REST API
                        │
┌─────────────────────────────────────────────────────┐
│          EXECUTION LAYER (Port 8546)                │
│  • Process transactions                            │
│  • QWVM smart contract execution                   │
│  • State storage (BadgerDB)                        │
│  • EVM-compatible addresses                        │
│  • Trusts beacon's signature verification          │
└─────────────────────────────────────────────────────┘
```

**Benefits:**

1. **Separation of Concerns**: Each layer has clear responsibilities
2. **Security**: Validators isolated from execution layer
3. **Scalability**: Can optimize layers independently
4. **Upgradability**: Swap consensus without touching execution

**Start all layers:**

```bash
./scripts/secure-three-layer.sh
```

***

### How does Proof of Randomness (PoR) work?

**PoR combines two mechanisms:**

**1. VRF (Verifiable Random Function)**

```
Goal: Select next validator unpredictably

Process:
1. Each validator generates VRF proof: Dilithium.Sign(slot_seed)
2. VRF output: SHA3-256(signature) → random number
3. Validator with lowest VRF output wins
4. Everyone can verify proof with validator's public key

Security:
✅ Unpredictable (cannot predict who wins next slot)
✅ Verifiable (cryptographic proof of selection)
✅ Quantum-safe (Dilithium signatures)
```

**2. RANDAO (Commit-Reveal Randomness)**

```
Goal: Generate unpredictable randomness for VRF seed

Epoch N:
├─ Commit Phase: Validators submit H(random_value)
├─ Reveal Phase: Validators reveal random_value
└─ Aggregate: XOR all reveals → RANDAO output for Epoch N+1

Security:
✅ No single validator controls randomness
✅ Dilithium-signed commits (quantum-safe)
✅ Slashing for non-reveals (punishment)
```

**Full Flow:**

```
Slot 100:
1. RANDAO output: 0xABCDEF... (from previous epoch)
2. Validator VRF proofs:
   ├─ Alice: Dilithium.Sign(0xABCDEF || slot=100) → Output: 0x123...
   ├─ Bob:   Dilithium.Sign(0xABCDEF || slot=100) → Output: 0x456...
   └─ Carol: Dilithium.Sign(0xABCDEF || slot=100) → Output: 0x012...  ← WINS
3. Carol proposes block #100
4. All validators verify Carol's VRF proof
5. Attestations submitted if proof valid
```

***

### What is QWVM?

**QWVM (QuantumWing Virtual Machine)** executes **WebAssembly smart contracts** with quantum-safe host functions.

**Architecture:**

```
Smart Contract (Rust/C/Go) → Compile to WASM → Run in QWVM

QWVM Host Functions:
├─ get_random_bytes()    - RANDAO randomness (Dilithium-signed)
├─ get_block_hash()      - SHA3-256 block hashes
├─ get_balance()         - Account balances
├─ storage_set/get()     - Contract storage
└─ transfer()            - Token transfers
```

**Example (Rust):**

```rust
#[no_mangle]
pub extern "C" fn generate_lottery_winner() -> u64 {
    let mut random_bytes = [0u8; 32];
    unsafe {
        // Quantum-safe RANDAO randomness!
        get_random_bytes(random_bytes.as_mut_ptr(), 32);
    }
    u64::from_be_bytes([...])
}
```

**Why WebAssembly?**

* ✅ Language-agnostic (Rust, C, Go, AssemblyScript)
* ✅ Fast execution (near-native speed)
* ✅ Sandboxed (cannot access host system)
* ✅ Deterministic (same input = same output)

**Comparison:**

|            | EVM (Ethereum)   | QWVM (QuantumWing) |
| ---------- | ---------------- | ------------------ |
| Language   | Solidity         | Rust/C/Go/WASM     |
| Bytecode   | EVM opcodes      | WebAssembly        |
| Randomness | block.prevrandao | RANDAO (Dilithium) |
| Hashing    | SHA-256          | SHA3-256           |

***

### How does QuantumWing achieve EVM compatibility?

**Address Generation:**

QuantumWing uses **0x addresses** (20 bytes) like Ethereum, but derived from quantum-safe Dilithium keys:

```
Traditional Ethereum:
1. ECDSA private key (32 bytes)
2. ECDSA public key (64 bytes uncompressed)
3. Keccak-256(pubkey) = 32 bytes
4. Take last 20 bytes = 0x address

QuantumWing:
1. Dilithium Mode 3 private key (4,000 bytes)
2. Dilithium Mode 3 public key (1,952 bytes)
3. Keccak-256(pubkey) = 32 bytes
4. Take last 20 bytes = 0x address

Result: SAME address format, QUANTUM-SAFE source!
```

**Example:**

```bash
$ quantum-wing crypto generate-key --mode 3
Private Key: 4,000 bytes (Dilithium)
Public Key:  1,952 bytes (Dilithium)
Address:     0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb  ← 20 bytes

$ quantum-wing wallet balance 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb
Balance: 100.5 QWING
```

**Compatibility:**

* ✅ MetaMask can display addresses (read-only)
* ✅ Ethereum tools can query balances
* ❌ MetaMask CANNOT sign (requires Dilithium, not ECDSA)
* ✅ QuantumWing wallet handles signing

***

## Consensus & Validation

### How do I become a validator?

**Requirements:**

| Resource    | Minimum           | Recommended        |
| ----------- | ----------------- | ------------------ |
| **Stake**   | 32 QWING          | 32+ QWING          |
| **CPU**     | 8 cores @ 3.0 GHz | 16 cores @ 3.5 GHz |
| **RAM**     | 16 GB             | 32 GB              |
| **Storage** | 6 TB SSD          | 10 TB NVMe         |
| **Network** | 1 Gbps            | 10 Gbps            |
| **Uptime**  | 95%+              | 99%+               |

**Setup Steps:**

```bash
# 1. Generate Dilithium validator key
quantum-wing crypto generate-key --mode 3 --output validator.key

# 2. Create validator account
quantum-wing genesis add-validator \
    --pubkey validator.key \
    --stake 32000000000000000000  # 32 QWING in Wei

# 3. Start beacon chain
quantum-wing blockchain start --role beacon

# 4. Start validator
quantum-wing validator start \
    --key validator.key \
    --beacon-endpoint http://localhost:8080

# 5. Monitor
tail -f logs/validators/validator-*.log
```

**Validator Duties:**

| Duty           | Frequency        | Reward                 | Penalty               |
| -------------- | ---------------- | ---------------------- | --------------------- |
| Block Proposal | \~1 per 32 slots | Gas fees + base reward | Slashing if invalid   |
| Attestation    | Every slot (12s) | Base reward            | Inactivity penalty    |
| RANDAO Commit  | Once per epoch   | Base reward            | Slashing if no reveal |
| RANDAO Reveal  | Once per epoch   | Base reward            | Slashing if missed    |

***

### What are the slashing conditions?

**Slashing** is punishment for malicious or negligent validator behavior:

| Offense               | Penalty        | Description                                |
| --------------------- | -------------- | ------------------------------------------ |
| **Double Signing**    | 100% stake     | Signing two different blocks for same slot |
| **Surround Vote**     | 50% stake      | Attestations contradict previous votes     |
| **RANDAO Non-Reveal** | 10% stake      | Commit without reveal (blocks randomness)  |
| **Inactivity**        | -0.01% per day | Offline for extended period                |
| **Invalid VRF Proof** | Block rejected | Proposing without valid VRF proof          |

**Example - Double Signing:**

```
Slot 100:
├─ Validator Alice proposes Block A (parent: Block 99)
└─ Validator Alice proposes Block B (parent: Block 99)  ← SLASHING!

Result:
├─ Beacon detects two signatures from Alice for slot 100
├─ Slash 100% of Alice's stake (32 QWING)
└─ Distribute 50% to whistleblower, 50% burned
```

**Protection:**

* Run only ONE validator instance per key
* Use slashing protection database
* Monitor validator health regularly

***

### How is randomness generated (RANDAO)?

**RANDAO** is a commit-reveal scheme that generates unpredictable randomness from all validators:

**Phase 1: Commit (Epoch N)**

```
Each validator:
1. Generate random 32-byte value: r = random()
2. Compute commitment: c = SHA3(r)
3. Sign commitment: sig = Dilithium.Sign(c)
4. Submit (c, sig) to beacon chain

Storage:
commits[validator_id] = (c, sig)
```

**Phase 2: Reveal (Epoch N)**

```
Each validator:
1. Submit reveal: r (original random value)
2. Beacon verifies: SHA3(r) == commits[validator_id].c
3. Store: reveals[validator_id] = r

Slashing if:
├─ No reveal submitted (10% stake)
└─ SHA3(r) ≠ commitment (100% stake, fraud proof)
```

**Phase 3: Aggregate (End of Epoch N)**

```
RANDAO output = XOR all reveals:
randao[epoch_N] = reveals[0] ⊕ reveals[1] ⊕ ... ⊕ reveals[N]

Properties:
✅ Unpredictable: No single validator controls output
✅ Verifiable: Anyone can recompute XOR from reveals
✅ Quantum-safe: Dilithium-signed commits
✅ Bias-resistant: XOR prevents manipulation
```

**Usage:**

```
VRF Seed for Slot 100:
seed = RANDAO[current_epoch] || slot_number
     = 0xABCDEF1234... || 100
     
Validator generates VRF proof:
proof = Dilithium.Sign(seed)
output = SHA3(proof)
```

**Security:**

* ❌ Last revealer can withold: Yes, but gets slashed 10% stake (expensive attack)
* ✅ Bias prevention: XOR ensures no control over output bits
* ✅ Quantum-safe: Dilithium commits unbreakable by quantum computers

***

## Cryptography Questions

### Is SHA3-256 quantum-safe?

**Short Answer:** SHA3-256 is **quantum-resistant** but not fully "quantum-safe."

**Details:**

| Attack        | Classical Security | Quantum Security | Impact      |
| ------------- | ------------------ | ---------------- | ----------- |
| **Preimage**  | 2^256 operations   | 2^128 (Grover)   | ⚠️ Weakened |
| **Collision** | 2^128 operations   | 2^64 (Grover)    | ⚠️ Weakened |

**Grover's Algorithm:**

* Provides \~50% security reduction for brute-force attacks
* SHA3-256: 256-bit classical → 128-bit quantum
* SHA3-512: 512-bit classical → 256-bit quantum

**QuantumWing's Position:**

```
Current: SHA3-256 (128-bit quantum security)
├─ Sufficient for block hashes, transaction IDs, addresses
└─ Collision resistance: 2^64 quantum operations (still hard)

Future (if needed): SHA3-512
├─ 256-bit quantum security
└─ Migration path exists if quantum computers improve
```

**Comparison:**

* Bitcoin/Ethereum: SHA-256 (128-bit quantum security)
* QuantumWing: SHA3-256 (128-bit quantum security) + Keccak-256 for addresses
* Same quantum threat level for hashing, but Dilithium signatures protect account security

**Conclusion:** SHA3-256 quantum resistance is acceptable for hashing, but **signatures** (Dilithium) are critical for quantum safety.

***

### Why Dilithium over other PQC algorithms?

**NIST Post-Quantum Candidates (2022):**

| Algorithm     | Type                 | Signature Size | Speed       | Status          |
| ------------- | -------------------- | -------------- | ----------- | --------------- |
| **Dilithium** | Lattice (Module-LWE) | 3,293 bytes    | ✅ Fast      | ✅ NIST Standard |
| FALCON        | Lattice (NTRU)       | 1,280 bytes    | ⚠️ Slow     | NIST Standard   |
| SPHINCS+      | Hash-based           | 16,000 bytes   | ❌ Very Slow | NIST Standard   |

**Why Dilithium Mode 3?**

1. ✅ **NIST Approved** (2022 standard)
2. ✅ **Fast Verification** (\~0.1ms per signature)
3. ✅ **192-bit Security** (NIST Level 3)
4. ✅ **Reasonable Size** (3,293 bytes vs 16 KB SPHINCS+)
5. ✅ **Production-Ready** (widely implemented)

**Size Comparison:**

```
ECDSA (secp256k1):    65 bytes     → Quantum-vulnerable
Dilithium Mode 2:   2,420 bytes    → 128-bit security
Dilithium Mode 3:   3,293 bytes    → 192-bit security ← QuantumWing
Dilithium Mode 5:   4,595 bytes    → 256-bit security
FALCON-1024:        1,280 bytes    → Slow signing
SPHINCS+-256:      16,000 bytes    → Too large
```

**Why not FALCON?**

* ❌ Slower signing (\~2ms vs 0.3ms)
* ❌ Complex floating-point operations
* ✅ Smaller signatures (1,280 bytes)

**Why not SPHINCS+?**

* ❌ 16 KB signatures (5x larger than Dilithium)
* ❌ Very slow signing (\~20ms)
* ✅ Hash-based (conceptually simpler)

**Conclusion:** Dilithium Mode 3 offers the best balance of **security**, **speed**, and **signature size** for blockchain use.

***

### Can quantum computers break Dilithium?

**Short Answer:** No known quantum algorithm can break lattice-based cryptography like Dilithium.

**Mathematical Foundation:**

```
Dilithium Security Assumption:
Problem: Module Learning With Errors (Module-LWE)
├─ Find secret vector s in noisy linear equations: A·s + e = b
├─ A: public matrix
├─ e: small random error
└─ s: secret key

Quantum Attack Status:
├─ Shor's Algorithm: ❌ Does NOT apply (not factoring/discrete log)
├─ Grover's Algorithm: ⚠️ Reduces security by 50% (2^192 → 2^96)
└─ Lattice algorithms: ❌ No polynomial-time quantum algorithm known
```

**Security Levels:**

| Mode       | Classical Security | Quantum Security | Notes                 |
| ---------- | ------------------ | ---------------- | --------------------- |
| Mode 2     | 128-bit            | \~64-bit         | Minimum recommended   |
| **Mode 3** | **192-bit**        | **\~96-bit**     | QuantumWing uses this |
| Mode 5     | 256-bit            | \~128-bit        | Maximum security      |

**QuantumWing Choice:**

* 192-bit classical security = 96-bit quantum security
* Equivalent to **2^96 quantum operations** to break
* Current quantum computers: \~100 qubits (2^50 operations max)
* Safe for **50+ years** even with quantum progress

**Future-Proofing:**

```
If quantum computing improves dramatically:
├─ Option 1: Switch to Dilithium Mode 5 (256-bit)
├─ Option 2: Combine with hash-based signatures (SPHINCS+)
└─ Migration: Hard fork with signature upgrade
```

**Conclusion:** Dilithium Mode 3 is quantum-safe for foreseeable future (50+ years).

***

## Performance & Scalability

### What is the maximum TPS (Transactions Per Second)?

**Current Mainnet Capacity:**

```
Block time: 12 seconds
Max gas per block: 30,000,000
Simple transfer: 21,000 gas

Max TPS = (30,000,000 / 21,000) / 12s
        = 1,428 TX per block / 12s
        = 119 TPS (simple transfers)
```

**Real-World TPS (Mixed Workload):**

| Transaction Type     | Gas per TX  | Max TPS    |
| -------------------- | ----------- | ---------- |
| Simple transfers     | 21,000      | 119 TPS    |
| Token transfers      | \~50,000    | 50 TPS     |
| Smart contract calls | \~100,000   | 25 TPS     |
| Contract deployments | \~1,000,000 | 2.5 TPS    |
| **Average mixed**    | \~50,000    | **50 TPS** |

**Scalability Roadmap:**

| Phase             | Timeline | Method               | Target TPS      |
| ----------------- | -------- | -------------------- | --------------- |
| Phase 1 (Current) | 2025     | Single chain         | 50-119 TPS      |
| Phase 2           | 2026     | Gas optimization     | 200 TPS         |
| Phase 3           | 2027     | Parallel execution   | 500 TPS         |
| Phase 4           | 2028     | Sharding (64 shards) | 3,000-7,500 TPS |

**Comparison:**

| Blockchain      | TPS        | Notes                         |
| --------------- | ---------- | ----------------------------- |
| Bitcoin         | 7          | UTXO model                    |
| Ethereum        | 15-30      | EVM execution                 |
| **QuantumWing** | **50-119** | Quantum-safe + EVM-compatible |
| Polygon         | 65,000     | L2 sidechain                  |
| Solana          | 3,000      | Centralized (fast)            |

***

### How much storage does a validator need?

**Year 1 Storage Projection:**

```
Baseline (Testnet):
├─ 7 blocks, 20,000 TX
├─ 4 KB actual disk usage
├─ ZSTD compression: 60%
└─ TX size: 2.8 KB compressed (2.2 KB after compression)

Year 1 Mainnet (50 TPS average):
├─ Total storage: 4.5 TB
├─ Monthly growth:
│   ├─ Month 1: 57 GB
│   ├─ Month 6: 935 GB
│   └─ Month 12: 4.5 TB
├─ Daily peak (Month 12): 27.7 GB/day
└─ TPS peak (Month 12): 146 TPS
```

**Hardware Requirements:**

| Node Type     | Storage       | RAM   | CPU                | Network |
| ------------- | ------------- | ----- | ------------------ | ------- |
| **Validator** | 10 TB NVMe    | 32 GB | 16 cores @ 3.5 GHz | 10 Gbps |
| Archive Node  | 20 TB RAID 10 | 64 GB | 32 cores @ 4.0 GHz | 10 Gbps |
| Full Node     | 6 TB SSD      | 16 GB | 8 cores @ 3.0 GHz  | 1 Gbps  |

**Optimization Strategies:**

| Method        | Savings         | Description                          |
| ------------- | --------------- | ------------------------------------ |
| State Pruning | 70%             | Remove old state (keep last 30 days) |
| Snapshots     | 95% faster sync | Download state checkpoint            |
| Sharding      | 98%             | Each shard stores 1/64 of data       |

**Long-Term (5 Years):**

```
Without pruning: 73.2 TB (full archive)
With pruning:    22.0 TB (validator node)
Per shard:       1.1 TB (sharded validator)
```

***

### Is QuantumWing faster than Ethereum?

**Block Production:**

| Metric                 | Ethereum       | QuantumWing       |
| ---------------------- | -------------- | ----------------- |
| Block time             | 12 seconds     | 12 seconds        |
| Finality               | \~12.8 minutes | \~12.8 minutes    |
| TPS                    | 15-30          | 50-119            |
| Signature verification | 0.05ms (ECDSA) | 0.1ms (Dilithium) |

**Transaction Size:**

```
Ethereum Transaction:
├─ Base: 109 bytes
├─ Signature: 65 bytes (ECDSA)
└─ Total: 174 bytes

QuantumWing Transaction:
├─ Base: 109 bytes
├─ Signature: 3,293 bytes (Dilithium)
└─ Total: 3,402 bytes (19.6x larger)

After Compression (ZSTD 60%):
├─ Dilithium: 3,293 → 2,960 bytes (10% compression)
└─ Total: 3,069 bytes compressed
```

**Performance Trade-off:**

| Aspect                 | Ethereum | QuantumWing | Winner          |
| ---------------------- | -------- | ----------- | --------------- |
| Signature size         | 65 bytes | 3,293 bytes | Ethereum        |
| Verification speed     | 0.05ms   | 0.1ms       | Ethereum        |
| TPS (simple transfers) | 15       | 119         | **QuantumWing** |
| Quantum-safe           | ❌ NO     | ✅ YES       | **QuantumWing** |
| Storage (Year 1)       | 900 GB   | 4.5 TB      | Ethereum        |

**Conclusion:**

* QuantumWing is **7.9x FASTER TPS** than Ethereum (119 vs 15)
* But requires **5x more storage** due to Dilithium signatures
* **Trade-off:** Speed + quantum safety vs storage cost

***

## Smart Contracts & Development

### How do I deploy a smart contract?

**Step 1: Write Contract (Rust)**

```rust
// counter.rs
#[no_mangle]
pub extern "C" fn increment() -> i32 {
    let key = b"count";
    let current = storage_get(key);
    let new_value = current + 1;
    storage_set(key, new_value);
    new_value
}

#[no_mangle]
pub extern "C" fn get_count() -> i32 {
    storage_get(b"count")
}
```

**Step 2: Compile to WASM**

```bash
# Install Rust + wasm32 target
rustup target add wasm32-unknown-unknown

# Compile
cargo build --target wasm32-unknown-unknown --release

# Output: target/wasm32-unknown-unknown/release/counter.wasm
```

**Step 3: Deploy to QuantumWing**

```bash
# Deploy contract
quantum-wing contract deploy \
    --wasm counter.wasm \
    --from 0xYourAddress \
    --gas 1500000 \
    --gas-price 10gwei

# Returns contract address:
# Contract deployed: 0x1234567890abcdef1234567890abcdef12345678
```

**Step 4: Call Contract**

```bash
# Call increment() function
quantum-wing contract call \
    --contract 0x1234567890abcdef1234567890abcdef12345678 \
    --function increment \
    --from 0xYourAddress \
    --gas 50000

# Query get_count() (no gas)
quantum-wing contract query \
    --contract 0x1234567890abcdef1234567890abcdef12345678 \
    --function get_count

# Returns: 1
```

***

### Can I use Solidity contracts?

**Short Answer:** EVM-compatible JSON-RPC is **live (B-2)** — `eth_*` methods work, MetaMask connects, and authorized-ECDSA spending of native QWING works. Solidity bytecode execution is in progress (see `docs/EVM_INTEGRATION_ROADMAP.md`). Until then, deploy WASM contracts (Rust, C/C++, Go, AssemblyScript) via QWVM.

**Current State:**

| Language           | Status            | WASM Support |
| ------------------ | ----------------- | ------------ |
| **Rust**           | ✅ Operational     | Native WASM  |
| **C/C++**          | ✅ Operational     | Emscripten   |
| **Go**             | ✅ Operational     | TinyGo       |
| **AssemblyScript** | ✅ Operational     | Native WASM  |
| **Solidity**       | ⏳ Planned Q1 2026 | solc-to-WASM |

**EVM Integration Roadmap:**

```
Phase 5 (Q1 2026):
├─ EVM bytecode → WASM transpiler
├─ Solidity compiler integration
├─ EVM precompile support (ecrecover, sha256, etc.)
└─ Ethereum tool compatibility (Truffle, Hardhat)

Example (Future):
$ solc Counter.sol --bin --wasm
$ quantum-wing contract deploy --wasm Counter.wasm
```

**Workaround (Today):**

* Use Rust (most mature WASM ecosystem)
* Port Solidity logic to Rust manually
* Wait for Phase 5 EVM integration

***

### What are QWVM host functions?

**Host functions** are blockchain APIs available to smart contracts:

| Function             | Purpose            | Quantum-Safe?          |
| -------------------- | ------------------ | ---------------------- |
| `get_random_bytes()` | RANDAO randomness  | ✅ Dilithium-signed     |
| `get_block_hash()`   | Block hashes       | ✅ SHA3-256             |
| `get_balance()`      | Account balance    | N/A                    |
| `storage_get/set()`  | Persistent storage | N/A                    |
| `transfer()`         | Send tokens        | ✅ Dilithium signatures |
| `get_caller()`       | Transaction sender | N/A                    |
| `emit_event()`       | Log events         | N/A                    |

**Example: Quantum-Safe Lottery**

```rust
#[no_mangle]
pub extern "C" fn draw_winner(players_ptr: *const u8, len: i32) -> u64 {
    // Get quantum-safe random bytes
    let mut random_bytes = [0u8; 32];
    unsafe {
        get_random_bytes(random_bytes.as_mut_ptr(), 32);
    }
    
    // Convert to winner index
    let random_u64 = u64::from_be_bytes([...]);
    let winner_index = random_u64 % (len as u64);
    
    winner_index
}
```

**Security:**

* ✅ `get_random_bytes()`: Uses RANDAO (XOR of Dilithium-signed reveals)
* ✅ Cannot be manipulated by validators
* ✅ Verifiable on-chain

***

## Economics & Fees

### How are gas fees calculated?

**Gas Calculation:**

```
Transaction Fee = Gas Limit × Gas Price

Example:
├─ Simple transfer: 21,000 gas
├─ Gas price: 10 Gwei
└─ Fee: 21,000 × 10 Gwei = 210,000 Gwei = 0.00021 QWING
```

**Gas Limits by Operation:**

| Operation              | Gas                   | Cost @ 10 Gwei     |
| ---------------------- | --------------------- | ------------------ |
| Simple transfer        | 21,000                | 0.00021 QWING      |
| Dilithium verification | 0 (FREE)              | 0 QWING            |
| Smart contract call    | \~50,000-200,000      | 0.0005-0.002 QWING |
| Contract deployment    | \~1,000,000-3,000,000 | 0.01-0.03 QWING    |
| Storage write          | \~20,000 per word     | 0.0002 QWING       |

**Fee Distribution (Under Evaluation):**

| Model              | Validator Share | Burn    | Notes                  |
| ------------------ | --------------- | ------- | ---------------------- |
| Model 1 (Current)  | 100%            | 0%      | All fees to validators |
| Model 2 (Planned)  | 20-50%          | 50-80%  | EIP-1559 style         |
| Model 3 (Research) | Dynamic         | Dynamic | Algorithmic adjustment |

**Example Block Earnings:**

```
Block with 1,000 transactions:
├─ Average gas: 21,000
├─ Gas price: 10 Gwei
├─ Fee per TX: 0.00021 QWING
└─ Validator earns: 0.21 QWING (Model 1)
```

***

### What are validator rewards?

**Revenue Sources:**

| Source               | Amount          | Frequency             |
| -------------------- | --------------- | --------------------- |
| Base reward          | \~0.01 QWING    | Per attestation (12s) |
| Block proposal       | Gas fees + base | \~1 per 32 slots      |
| RANDAO participation | Base reward     | Per epoch             |

**Example (Month 1, Low Activity):**

```
Network: 10 TPS average
├─ Transactions per block: 120
├─ Gas per TX: 21,000
├─ Gas price: 10 Gwei
├─ Blocks per day: 7,200

Validator Earnings (3 validators total):
├─ Per block: 0.0252 QWING
├─ Per day: 60.48 QWING
└─ Per month: 1,814 QWING per validator
```

**Example (Month 12, High Activity):**

```
Network: 146 TPS peak
├─ Transactions per block: 1,753
├─ Gas per TX: 21,000
├─ Gas price: 10 Gwei

Validator Earnings:
├─ Per block: 0.3681 QWING
├─ Per day: 883 QWING
└─ Per month: 26,500 QWING per validator
```

**Penalties:**

* Offline: -0.01% stake per day
* RANDAO non-reveal: -10% stake
* Double signing: -100% stake

***

## Troubleshooting

### Why is Dilithium verification FREE?

**Design Decision:**

```
Gas Cost:
├─ Simple transfer: 21,000 gas
├─ Dilithium verification: 0 gas  ← FREE
└─ Storage write: 20,000 gas
```

**Reasoning:**

1. ✅ **Core Feature**: Quantum safety is fundamental, not optional
2. ✅ **Incentive**: Encourages quantum-safe transactions
3. ✅ **Fairness**: Users shouldn't pay for security
4. ✅ **Competitive**: Cheaper than classical blockchains (no signature gas)

**Comparison:**

| Blockchain  | Signature Verification Gas | Notes          |
| ----------- | -------------------------- | -------------- |
| Ethereum    | \~3,000 (ecrecover)        | ECDSA recovery |
| QuantumWing | **0**                      | Dilithium FREE |

**Why Not Charge?**

* Dilithium verification is **expensive** (\~0.1ms per signature)
* But **mandatory** for every transaction
* Charging would make all transactions 14% more expensive
* Better to **absorb cost** as blockchain infrastructure

***

### My validator is offline. What happens?

**Penalties:**

```
Inactivity Leak:
├─ Day 1: -0.01% stake per day
├─ Day 7: -0.07% stake
├─ Day 30: -0.3% stake
└─ Day 365: -3.65% stake (if continuously offline)
```

**Missed Duties:**

| Missed Duty    | Penalty                         | Impact       |
| -------------- | ------------------------------- | ------------ |
| Attestation    | Lose base reward (\~0.01 QWING) | No slashing  |
| Block proposal | Lose gas fees (0.02-0.36 QWING) | No slashing  |
| RANDAO reveal  | **-10% stake**                  | **SLASHING** |

**Recovery:**

```bash
# 1. Check validator status
quantum-wing validator status --key validator.key

# 2. Check beacon chain sync
curl http://localhost:8080/api/beacon/status

# 3. Restart validator
quantum-wing validator start --key validator.key --beacon-endpoint http://localhost:8080

# 4. Monitor logs
tail -f logs/validators/validator-*.log
```

**Best Practices:**

* ✅ Set up monitoring (Grafana)
* ✅ Use redundant hardware
* ✅ Have backup power
* ✅ Monitor uptime (target 99%+)

***

### How do I check my balance?

**Option 1: CLI**

```bash
quantum-wing wallet balance 0xYourAddress
Balance: 100.5 QWING
```

**Option 2: REST API**

```bash
curl http://localhost:8546/api/execution/balance/0xYourAddress
{"balance": "100500000000000000000"}  # Wei (100.5 QWING)
```

**Option 3: JSON-RPC API**

```bash
curl -X POST http://localhost:8546/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_getBalance",
    "params": ["0xYourAddress", "latest"],
    "id": 1
  }'

# Returns: {"result": "0x570de..."}  # Hex Wei
```

**Option 4: Blockchain Explorer**

```
Open: http://localhost:3000 (qgen-explorer)
Enter: 0xYourAddress
View: Balance, transactions, contract interactions
```

***

### How do I send a transaction?

**Method 1: CLI (Recommended)**

```bash
quantum-wing send \
    --from 0xSenderAddress \
    --to 0xRecipientAddress \
    --amount 1.5 \
    --gas-price 10gwei \
    --key sender.key

# Returns transaction hash:
# TX: 0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890
```

**Method 2: JSON-RPC API**

```bash
# 1. Create transaction
curl -X POST http://localhost:8546/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_sendTransaction",
    "params": [{
      "from": "0xSenderAddress",
      "to": "0xRecipientAddress",
      "value": "0x14d1120d7b160000",  # 1.5 QWING in Wei (hex)
      "gas": "0x5208",                # 21000 gas
      "gasPrice": "0x2540be400"       # 10 Gwei
    }],
    "id": 1
  }'
```

**Method 3: SDK (JavaScript)**

```javascript
const { QuantumWingClient } = require('@quantumwing/sdk');

const client = new QuantumWingClient('http://localhost:8546');
const tx = await client.sendTransaction({
    from: '0xSenderAddress',
    to: '0xRecipientAddress',
    value: '1.5',  // QWING
    gasPrice: '10gwei'
});

console.log('TX hash:', tx.hash);
```

***

## Roadmap Questions

### When will cross-chain bridges launch?

**Cross-Chain Asset Protection Roadmap:**

| Phase       | Timeline | Chains                            | Status      |
| ----------- | -------- | --------------------------------- | ----------- |
| **Phase 1** | Q1 2026  | Ethereum (qwETH, qwUSDC)          | 📅 Planned  |
| **Phase 2** | Q2 2026  | Bitcoin (qwBTC)                   | 📅 Planned  |
| **Phase 3** | Q3 2026  | Solana (qwSOL, SPL tokens)        | 📅 Planned  |
| **Phase 4** | Q4 2026  | ZK optimization (300-byte proofs) | 📅 Research |

**Phase 1 Features (Ethereum):**

* Bridge ETH/USDC to QuantumWing (wrap → qwETH/qwUSDC)
* 21-validator custody committee
* 14/21 threshold (Dilithium signatures)
* Merkle proof verification
* Slashing for fraud

**Security Model:**

```
Lock ETH on Ethereum:
1. User sends 10 ETH to bridge contract
2. Bridge contract emits LockEvent
3. 21 validators observe event
4. 14+ validators sign Dilithium proof
5. QuantumWing mints 10 qwETH to user

Unlock ETH from Ethereum:
1. User burns 10 qwETH on QuantumWing
2. 14+ validators sign Dilithium proof
3. Merkle proof submitted to Ethereum
4. Ethereum contract releases 10 ETH
```

***

### Is sharding planned?

**Yes, Phase 8 (2028).**

**Sharding Roadmap:**

```
Phase 8 (2028): Data Sharding
├─ 64 shards (Ethereum 2.0 model)
├─ Each shard: ~1.8 TPS × 64 = 115 TPS total
├─ Storage per shard: 70 GB (vs 4.5 TB single chain)
└─ Beacon chain coordinates shards
```

**Shard Architecture:**

```
┌─────────────────────────────────────────────────────┐
│              BEACON CHAIN                           │
│  • Coordinates 64 shards                           │
│  • Crosslinks (shard state roots)                  │
│  • Validator assignment                            │
└─────────────────────────────────────────────────────┘
        │       │       │                  │
   ┌────┴──┐ ┌─┴───┐ ┌─┴───┐           ┌──┴──┐
   │Shard 0│ │Shard1│ │Shard2│    ...    │Shard│
   │1.8 TPS│ │1.8TPS│ │1.8TPS│           │ 63  │
   └───────┘ └──────┘ └──────┘           └─────┘
```

**Benefits:**

* ✅ **115 TPS** total (64 × 1.8 TPS per shard)
* ✅ **70 GB storage** per shard validator (vs 4.5 TB)
* ✅ **Parallel processing** (64 shards simultaneously)

**Challenges:**

* Cross-shard transactions (async)
* State synchronization
* Validator shuffling

***

## Getting Help

### Where can I find documentation?

**Official Resources:**

| Resource           | URL                                                                        | Description                 |
| ------------------ | -------------------------------------------------------------------------- | --------------------------- |
| **GitBook**        | [docs.quantumwing.io](https://docs.quantumwing.io)                         | Comprehensive documentation |
| **GitHub**         | [github.com/quantumwing/protocol](https://github.com/quantumwing/protocol) | Source code + issues        |
| **API Reference**  | [api.quantumwing.io](https://api.quantumwing.io)                           | JSON-RPC, REST, gRPC        |
| **Block Explorer** | [explorer.quantumwing.io](http://localhost:3000)                           | Testnet explorer            |

**Technical Docs (GitHub):**

* `CLAUDE.md` - Development guide
* `BLOCKCHAIN_IMPLEMENTATION.md` - Implementation details
* `docs/` folder - All GitBook pages

***

### How do I report a bug?

**Option 1: GitHub Issues**

```
Repository: https://github.com/quantumwing/protocol
Click: Issues → New Issue → Bug Report

Template:
├─ Version: 1.0.0
├─ Environment: Ubuntu 22.04, 16 cores, 32 GB RAM
├─ Steps to reproduce:
│   1. Start beacon chain
│   2. Run validator
│   3. Observe error
├─ Expected: Validator proposes block
└─ Actual: Error "VRF proof invalid"
```

**Option 2: Discord**

```
Channel: #bugs
Provide:
├─ Log file: logs/beacon/beacon.log
├─ Screenshot
└─ System info: uname -a
```

**Security Issues:**

* **DO NOT** open public GitHub issue
* Email: <security@quantumwing.io>
* PGP key: <https://quantumwing.io/security.asc>

***

### Where can I get testnet tokens?

**Testnet Faucet:**

```bash
# Option 1: Web faucet
Open: https://faucet.quantumwing.io
Enter: 0xYourAddress
Receive: 10 testnet QWING

# Option 2: CLI faucet
quantum-wing faucet request --address 0xYourAddress
# Sends 10 testnet QWING

# Option 3: Discord bot
Discord: #faucet channel
Command: !faucet 0xYourAddress
```

**Genesis Pre-Funding (Local Testnet):**

```json
// genesis.json
{
  "alloc": {
    "0xYourAddress": {
      "balance": "1000000000000000000000"  // 1000 QWING
    }
  }
}
```

***

## Community & Support

### How can I contribute?

**Ways to Contribute:**

1. **Code Contributions**

   ```bash
   # Fork repository
   git clone https://github.com/YourUsername/QuantumWing.git

   # Create feature branch
   git checkout -b feature/add-kyber-1024

   # Make changes, commit, push
   git push origin feature/add-kyber-1024

   # Open Pull Request
   ```
2. **Documentation**
   * Fix typos in `docs/` folder
   * Write tutorials
   * Translate documentation
3. **Testing**
   * Run testnet validator
   * Report bugs
   * Write integration tests
4. **Community**
   * Answer questions on Discord
   * Write blog posts
   * Create video tutorials

**Bounties:**

* Critical bugs: $1,000-$10,000
* Feature implementation: $500-$5,000
* Documentation: $100-$500

***

### Where can I chat with the community?

**Official Channels:**

| Platform     | Link                                                               | Purpose               |
| ------------ | ------------------------------------------------------------------ | --------------------- |
| **Discord**  | [discord.gg/quantumwing](https://discord.gg/quantumwing)           | General chat, support |
| **Telegram** | [t.me/quantumwing](https://t.me/quantumwing)                       | Announcements         |
| **Twitter**  | [@QuantumWingIO](https://twitter.com/quantumwingio)                | Updates               |
| **Reddit**   | [r/QuantumWing](https://reddit.com/r/quantumwing)                  | Discussions           |
| **GitHub**   | [Discussions](https://github.com/quantumwing/protocol/discussions) | Technical Q\&A        |

**Discord Channels:**

* `#general` - General discussion
* `#validator-support` - Validator help
* `#smart-contracts` - QWVM development
* `#bugs` - Bug reports
* `#announcements` - Official updates

***

*Last Updated: October 28, 2025*\
\&#xNAN;*Version: 1.0.0*\
\&#xNAN;*Production Readiness: 80/100*


---

# Agent Instructions: 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 current page URL with the `ask` query parameter:

```
GET https://quantumwing.gitbook.io/quantumwing/resources/faq.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.