Spaces:
Sleeping
Sleeping
| # 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* | |