docs/PROJECT_OVERVIEW.md

# QCrypt RNG — Project Overview

A high-level explanation of what QCrypt RNG is, what it does, and how it is built.

---

## What Is QCrypt RNG?

**QCrypt RNG** is a platform for **quantum-enhanced randomness** and **post-quantum cryptography**. It exposes a REST API and web UI for:

- Generating cryptographically secure random data using quantum-style entropy
- Running NIST-standard post-quantum algorithms (signatures and key exchange)
- Providing a verifiable random function (VRF) for blockchains
- Encrypting and protecting data with quantum-derived keys

It is intended for developers, researchers, and teams building quantum-resistant or blockchain-facing applications.

---

## Core Capabilities

### 1. Quantum Random Number Generation (QRNG)

- **Random bytes** — Configurable length and qubit count (8/12/16)
- **Keys** — AES, RSA, ECDSA keys with quantum entropy
- **UUIDs** — RFC 4122 v4 UUIDs
- **Passwords** — Configurable length and character sets
- **Session tokens** — URL-safe, with optional expiry
- **Batch mode** — Multiple samples in parallel

**How it works:** The system uses a pluggable backend (simulation, Qrisp, or real hardware). Random values are obtained from a hardware abstraction layer, post-processed with SHA3-256, and mixed with system entropy. Results are stored in an entropy pool for quality checks (Shannon entropy, min-entropy, chi-square).

---

### 2. Post-Quantum Cryptography (PQC)

Supports NIST-standard algorithms via **liboqs** (with fallbacks when liboqs is not available).

**Signature schemes:**

- **DILITHIUM** — Level 2, 3, 5
- **FALCON** — 512 / 1024
- **SPHINCS+** — Hash-based variant (e.g., SHA2-128f)

**Key encapsulation (KEM):**

- **Kyber** — 512 / 768 / 1024
- **NTRU-HPS** — 2048-509, 2048-677
- **SABER** — LIGHTSABER, SABER, FIRESABER

The Kyber KEM flow includes:

1. Recipient generates a keypair
2. Sender encapsulates a shared secret with the recipient’s public key
3. Recipient decapsulates with their private key
4. Both derive the same shared secret for symmetric cryptography

---

### 3. Quantum VRF (Verifiable Random Function)

A VRF backed by quantum entropy with a **commit–reveal** flow:

1. **Seed** — 32-byte quantum seed is generated and committed via Keccak-256
2. **Prove** — For any input (alpha), output = Keccak256(seed || alpha)
3. **Reveal** — Seed is revealed so anyone can verify
4. **Verify** — Checks that commitment and output match the seed and alpha

The Keccak-256 format is compatible with Ethereum/Solidity.

---

### 4. On-Chain Oracle Fulfillment

Supports submit-and-fulfill oracle randomness on blockchains:

- **Chains:** Ethereum, Polygon, BSC, Avalanche, Fantom
- **Flow:** Configure chain (RPC, private key, explorer), create request, commit on-chain, reveal randomness
- **Status:** Track PENDING → COMMIT_SUBMITTED → REVEAL_CONFIRMED → COMPLETED
- **Retry:** Retry failed fulfillments

---

### 5. Data Protection

- **Encryption** — AES-256-GCM, AES-128-GCM, AES-256-CBC (quantum or user keys)
- **File encryption** — Up to 10 MB
- **Signing** — HMAC-SHA256, HMAC-SHA512
- **Hashing** — SHA3-256, SHA3-512, PBKDF2-SHA256, BLAKE2b-256
- **Salt** — Quantum-generated salts for hashing

---

### 6. Blockchain Security Tools

- **Wallet creation** — Compare classical (ECDSA) vs quantum-safe (DILITHIUM/KYBER) wallets
- **Attack simulation** — Simulate Shor’s algorithm on RSA, ECDSA, DILITHIUM, KYBER
- **Blockchain comparison** — Side-by-side vulnerable vs quantum-safe chain models
- **Demo mining** — Proof-of-work-style mining for both types

---

### 7. Threat Intelligence

- **Algorithm assessment** — “Qubits to break” and migration guidance for RSA, ECDSA, etc.
- **Oracle benchmark** — Latency and throughput
- **Entropy quality** — Shannon entropy, min-entropy, chi-square, autocorrelation

---

### 8. Quantum Hardware Abstraction

Pluggable backends for different sources:

- **Simulation** — Classical fallback for dev/demo
- **Qrisp** — Quantum simulation when available
- **ID Quantique Quantis** — Photonic QRNG (USB, PCIe, network)
- **QuintessenceLabs qStream** — Photonic QRNG over TCP/IP

Includes entropy quality checks (NIST SP 800-90B–style analysis).

---

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│  Next.js Dashboard (quantum-oracle-ui)                       │
│  Port 3000 (dev) / served by Nginx (prod)                    │
└───────────────────────────┬─────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  FastAPI Backend (app/)                                      │
│  Port 8000 | Base path: /api/v2                              │
├─────────────────────────────────────────────────────────────┤
│  Endpoints:                                                  │
│  - /generate/*    Quantum RNG                                │
│  - /protect/*     Encryption, signing, hashing               │
│  - /pqc/*         Post-quantum crypto (incl. KEM)            │
│  - /oracle/*      VRF, oracle requests, fulfillment         │
│  - /blockchain/*  Wallets, attack sim, mining                │
│  - /quantum/*     Entropy, stats, reseed                     │
│  - /hardware/*    Device list, benchmark, connect            │
│  - /monitoring/*  Metrics, analytics                         │
└───────────────────────────┬─────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  Core Modules (app/quantum/, app/blockchain/)                │
│  - qrng.py            Quantum RNG engine                     │
│  - commitment.py      Keccak-256 commitments                 │
│  - pqc.py             liboqs PQC (Dilithium, Kyber, etc.)    │
│  - hardware_interface │ Photonic, superconducting, simulated │
│  - oracle_service.py  On-chain fulfillment                  │
└─────────────────────────────────────────────────────────────┘
```

---

## Tech Stack

| Layer        | Technology                                      |
|-------------|--------------------------------------------------|
| Backend     | Python 3.8+, FastAPI, Uvicorn                    |
| Frontend    | Next.js 16, React, TypeScript, Tailwind CSS      |
| Quantum     | Qrisp (optional), custom hardware abstraction   |
| Crypto      | PyCryptodome (Keccak), cryptography, liboqs     |
| Deployment  | Docker (single image), Compose, Kubernetes       |
| Monitoring  | Prometheus metrics, analytics service            |

---

## Project Layout

```
qcrypt-rng/
├── app/                    # FastAPI backend
│   ├── api/v2/endpoints/   # REST routes
│   ├── quantum/            # QRNG, PQC, commitment, hardware
│   ├── blockchain/         # Chain adapters, oracle service
│   ├── utils/              # Logging, monitoring, middleware
│   └── config.py
├── quantum-oracle-ui/      # Next.js dashboard
├── tests/
│   ├── unit/               # Pytest unit tests
│   ├── integration/        # Pytest integration tests
│   └── manual/             # Standalone scripts (not collected by pytest)
├── docs/                   # PRODUCTION, guides, business, archive, roadmaps
├── examples/               # Standalone sample scripts
├── legacy/                 # Streamlit + static HTML (deprecated UI path)
├── scripts/                # e.g. start.py (API + Next.js for dev)
├── quantum-oracle/         # Oracle node, contracts, SDKs
├── client_sdk/python/      # Python client library
├── k8s/                    # Kubernetes manifests
├── run_api.py              # Start API server only
├── requirements.txt
└── Dockerfile              # Single image for production
```

---

## Running the Project

**Backend:**
```bash
pip install -r requirements.txt
python run_api.py
```
→ API at http://localhost:8000, docs at http://localhost:8000/docs

**Dashboard:**
```bash
cd quantum-oracle-ui && npm install && npm run dev
```
→ Dashboard at http://localhost:3000 (uses API on 8000–8004 by default)

**Production:** `docker-compose up -d` or `./deploy.sh` (Kubernetes)

**Hugging Face Spaces:** Use root `Dockerfile` for a Docker Space on port 7860.

---

## Security Notes

- Simulation and classical fallback are for development/demo only.
- Use a validated QRNG or trusted HRNG in production.
- VRF seeds are kept in memory; consider hardened storage for high assurance.
- Private keys for on-chain fulfillment must be stored and handled securely (no production keys in demos).
- Enable rate limiting and API key auth in production.

---

## Related Documents

- [README.md](../README.md) — Quick start and API summary
- [TECHNICAL_PAPER.md](TECHNICAL_PAPER.md) — Architecture and algorithms
- [PRODUCTION.md](PRODUCTION.md) — Deployment and operations
- [NEXT_STEPS.md](NEXT_STEPS.md) — Completed roadmap
- [NEXT_STEPS_PHASE2.md](NEXT_STEPS_PHASE2.md) — Phase 2 roadmap
- [DASHBOARD_MONITORING_PLAN.md](DASHBOARD_MONITORING_PLAN.md) — UI and monitoring plan

---

*Last updated: 2026-03-06*