Spaces:

quantumGlobalGroup
/

qcrypt-rng

Sleeping

App Files Files Community

qcrypt-rng / README.md

rocRevyAreGoals15

Add HF Space metadata to README and ignore PRD screenshots

b3d4326 2 months ago

preview code

raw

history blame contribute delete

14.2 kB

metadata

title: QCrypt RNG
emoji: 🔐
colorFrom: indigo
colorTo: purple
sdk: docker
app_port: 7860
pinned: false

QCrypt RNG

Quantum-enhanced random number generation, post-quantum cryptography, and blockchain security.

QCrypt RNG is a platform for cryptographically secure randomness and quantum-resistant security. It provides a REST API and web dashboard for quantum-backed entropy, NIST-standard post-quantum algorithms, a verifiable random function (VRF) oracle for blockchains, data protection tools, and threat intelligence. The stack runs as a single Docker image and is deployable to cloud or Hugging Face Spaces.

Live demo: Hugging Face Spaces

Upgrade roadmap: docs/UPGRADE_ROADMAP.md

AI / Cursor session prompt: docs/CURSOR_OPERATOR_PROMPT.md

What it does

Quantum randomness — Random bytes, keys, UUIDs, passwords, and session tokens with configurable qubit counts (8/12/16) and batch generation.
Quantum VRF — Verifiable random function with a one-time quantum seed, Keccak-256 commitment (Ethereum-compatible), and commit–reveal flow; supports Ethereum, Polygon, BSC, Avalanche, Fantom.
Post-quantum cryptography — Complete NIST-standardized PQC suite:
- Signatures: DILITHIUM2/3/5, FALCON512/1024, SPHINCS+-SHA2-128f (FIPS 204, 205)
- Key Exchange: KYBER512/768/1024, NTRU-HPS, SABER (FIPS 203)
- Full KEM workflow: generate keypair, encapsulate, decapsulate
Data protection — AES-256-GCM, AES-128-GCM, AES-256-CBC (quantum or user-supplied keys); file encryption; HMAC sign/verify; quantum-salted hashing (SHA3, PBKDF2, BLAKE2b).
Blockchain security — Quantum-safe vs classical wallet comparison, Shor-based attack simulation, chain comparison, demo mining, and oracle randomness (single and batch).
On-chain oracle fulfillment — Real blockchain integration for oracle requests with commit-reveal on Ethereum, Polygon, BSC, Avalanche, and Fantom.
Threat intelligence — Algorithm vulnerability scanning, oracle benchmarking, and qubit-to-break estimates.
Quantum hardware — Abstraction layer for real QRNG devices (ID Quantique Quantis, QuintessenceLabs qStream) with entropy quality checks.
Operations — Health checks, entropy quality and hardware status, monitoring metrics; optional rate limiting and API key auth.

Quick start

Prerequisites: Python 3.8+, Node.js 18+ (for the dashboard), pip.

Backend:

git clone <repository-url>
cd qcrypt-rng
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
python run_api.py

Use a .venv in the project root (not venv/). scripts/start.py also looks for .venv/bin/python.

API: http://localhost:8000 — Interactive docs: http://localhost:8000/docs

Frontend:

cd quantum-oracle-ui
npm install
npm run dev

Dashboard: http://localhost:3040 by default (quantum-oracle-ui/find-port.js picks the next free port from 3040 upward so this project does not grab 3000). Auto-discovers API on ports 8000–8004, or set NEXT_PUBLIC_API_BASE_URL. See quantum-oracle-ui/env.example.

Production: See docs/PRODUCTION.md. For Docker: docker-compose up -d or Kubernetes via ./deploy.sh.

Hugging Face Spaces: The root Dockerfile is built for Spaces (Nginx + FastAPI + Next.js on port 7860). Create a Docker Space, add the Space as a remote, and push main; use a HF token with write access when prompted. The app will be available at your Space URL after the build completes.

Web dashboard

The dashboard has five sections and an in-app Docs link:

Section	Capabilities
Blockchain Security	Wallet creation, VRF proof generation and verification, supported chains
Data Protection	Encrypt/decrypt (text and file), sign/verify, hash, PQC key generation and sign/verify
Key and Entropy Tools	Random bytes, keys, UUIDs, passwords, tokens, batch generation, oracle requests
Threat Intelligence	Algorithm scanning, attack simulation, blockchain comparison, benchmarks
Network Status	Platform health, entropy quality, hardware status, oracle request lookup

Each card includes an info popover; collapsible sections are used for dense workflows.

API reference

Base path: /api/v2.

Quantum Randomness Generation

Endpoint	Description
`POST /generate/bytes`	Generate random bytes
`POST /generate/key`	Generate cryptographic key (AES-128/256)
`POST /generate/uuid`	Generate quantum UUID v4
`POST /generate/password`	Generate random password
`POST /generate/token`	Generate session token
`POST /generate/batch`	Batch generation

Post-Quantum Cryptography

Dilithium Signatures:

Endpoint	Description
`POST /pqc/generate`	Generate DILITHIUM keypair
`POST /pqc/sign`	Sign message
`POST /pqc/verify`	Verify signature

Kyber KEM:

Endpoint	Description
`POST /pqc/kem/generate`	Generate KYBER keypair
`POST /pqc/kem/encapsulate`	Encapsulate shared secret
`POST /pqc/kem/decapsulate`	Decapsulate shared secret
`GET /pqc/kem/info`	KEM documentation

FALCON Signatures:

Endpoint	Description
`POST /pqc/falcon/generate`	Generate FALCON keypair

SPHINCS+ Signatures:

Endpoint	Description
`POST /pqc/sphincs/generate`	Generate SPHINCS+ keypair

NTRU KEM:

Endpoint	Description
`POST /pqc/ntru/generate`	Generate NTRU keypair

SABER KEM:

Endpoint	Description
`POST /pqc/saber/generate`	Generate SABER keypair

General:

Endpoint	Description
`GET /pqc/algorithms`	List supported algorithms
`GET /pqc/info`	PQC information
`POST /pqc/threat-assessment`	Assess quantum threat

Oracle & On-Chain Fulfillment

Basic Oracle:

Endpoint	Description
`POST /oracle/request`	Request quantum randomness
`POST /oracle/requests/batch`	Batch oracle requests
`GET /oracle/status/:id`	Get request status
`GET /oracle/network-info`	Network status
`GET /oracle/benchmark`	Benchmark oracle

On-Chain Fulfillment:

Endpoint	Description
`POST /oracle/fulfillment/configure-chain`	Configure blockchain
`POST /oracle/fulfillment/request`	Create on-chain request
`GET /oracle/fulfillment/status/:id`	Fulfillment status
`GET /oracle/fulfillment/requests`	List all requests
`GET /oracle/fulfillment/chains`	Supported chains
`POST /oracle/fulfillment/retry/:id`	Retry failed request

VRF:

Endpoint	Description
`POST /oracle/vrf/seed`	Generate VRF seed
`POST /oracle/vrf/prove`	Generate VRF proof
`POST /oracle/vrf/reveal`	Reveal VRF
`POST /oracle/vrf/verify`	Verify VRF

Data Protection

Endpoint	Description
`POST /protect/encrypt`	Encrypt data (AES)
`POST /protect/decrypt`	Decrypt data
`POST /protect/encrypt-file`	Encrypt file
`POST /protect/decrypt-file`	Decrypt file
`POST /protect/sign`	HMAC sign
`POST /protect/verify`	HMAC verify
`POST /protect/hash`	Quantum-salted hash
`POST /protect/salt`	Generate quantum salt

Blockchain Security

Endpoint	Description
`POST /blockchain/create-wallet`	Create quantum wallet
`POST /blockchain/sign-transaction`	Sign transaction
`POST /blockchain/simulate-attack`	Simulate Shor attack
`POST /blockchain/verify-quantum-safe`	Verify quantum-safe
`POST /blockchain/mine-block`	Demo mining
`GET /blockchain/compare-blockchains`	Compare chains

Hardware & System

Endpoint	Description
`GET /health`	Health check
`GET /quantum/entropy`	Entropy quality
`GET /quantum/stats`	Generation statistics
`POST /quantum/reseed`	Reseed entropy pool
`GET /hardware/devices`	List hardware devices
`GET /monitoring/metrics`	Prometheus metrics

Full interactive API docs: http://localhost:8000/docs (or /swagger when running behind the bundled Nginx).

Stack

Backend: FastAPI, Uvicorn, Python 3.8+
Frontend: Next.js 16, React, TypeScript, Tailwind CSS
Quantum: QRisp-style simulation; hardware abstraction for photonic/superconducting devices
Quantum Hardware: ID Quantique Quantis, QuintessenceLabs qStream adapters
Crypto: PyCryptodome (Keccak-256), cryptography (AES/RSA/ECDSA), liboqs-python (DILITHIUM/KYBER/FALCON/SPHINCS+/NTRU/SABER)
Blockchain: web3.py for Ethereum, Polygon, BSC, Avalanche, Fantom
Deployment: Docker (single image for Spaces), Docker Compose, Kubernetes

Quantum Hardware Backends

QCrypt RNG supports multiple quantum hardware backends for true random number generation:

Backend	Environment Variable	Description
`qrisp_simulator`	`QUANTUM_BACKEND=qrisp_simulator`	Quantum circuit simulation (default)
`idq_quantis`	`QUANTUM_BACKEND=idq_quantis`	ID Quantique Quantis (USB/PCIe/Network)
`qlabs_qstream`	`QUANTUM_BACKEND=qlabs_qstream`	QuintessenceLabs qStream (TCP/IP)
`hardware_photonic`	`QUANTUM_BACKEND=hardware_photonic`	Generic photonic QRNG
`hardware_superconducting`	`QUANTUM_BACKEND=hardware_superconducting`	Generic superconducting QRNG

Hardware Configuration

ID Quantique Quantis:

QUANTUM_BACKEND=idq_quantis
IDQ_DEVICE_ADDRESS=usb://0
IDQ_DEVICE_TYPE=usb  # usb, pcie, or network
IDQ_CALIBRATION_FILE=/path/to/calibration.json

QuintessenceLabs qStream:

QUANTUM_BACKEND=qlabs_qstream
QLABS_DEVICE_ADDRESS=tcp://localhost:8888
QLABS_API_KEY=your-api-key

Entropy Quality Checks

The system performs NIST SP 800-90B entropy estimation:

Chi-square uniformity test
Shannon entropy calculation
Min-entropy estimation
Overall quality assessment

Access via GET /quantum/entropy or the dashboard Network Status section.

On-Chain Oracle Fulfillment

QCrypt RNG provides real blockchain integration for oracle requests:

Supported Chains

Chain	Chain ID	Explorer	Features
Ethereum	1	etherscan.io	Mainnet, Sepolia testnet
Polygon	137	polygonscan.com	Low fees, fast confirmation
BSC	56	bscscan.com	Low fees
Avalanche	43114	snowtrace.io	Fast finality
Fantom	250	ftmscan.com	Low fees, fast

Fulfillment Workflow

Configure Chain: POST /oracle/fulfillment/configure-chain
Create Request: POST /oracle/fulfillment/request
Automatic Fulfillment:
- Generate quantum randomness
- Create commitment (keccak256)
- Submit commit transaction
- Wait for confirmation
- Submit reveal transaction
- Mark as completed

Fulfillment Status

Status	Description
`pending`	Request created
`commit_submitted`	Commit transaction sent
`commit_confirmed`	Commit confirmed on-chain
`reveal_submitted`	Reveal transaction sent
`reveal_confirmed`	Reveal confirmed on-chain
`completed`	Fulfillment complete
`failed`	Fulfillment failed (can retry)

Security Notes

⚠️ Private Key Security:

Never commit private keys to version control
Use hardware wallets or KMS in production
Store keys in environment variables or secure vaults
Rotate keys regularly

Testnet Deployment

For testing and development, deploy the oracle contracts to testnets:

Supported Testnets:

Ethereum Sepolia (Chain ID: 11155111)
Polygon Amoy (Chain ID: 80002)
BSC Testnet (Chain ID: 97)
Avalanche Fuji (Chain ID: 43113)
Fantom Testnet (Chain ID: 4002)

Deployment Guide: See docs/next-phase/TESTNET_DEPLOYMENT.md

# Deploy to all testnets
cd quantum-oracle/contracts
npx hardhat run scripts/deploy-all-testnets.js --network sepolia

# Validate deployments
npx hardhat run scripts/validate-deployment.js --network sepolia

Contract Addresses: After deployment, update .env with contract addresses:

ORACLE_CONTRACT_SEPOLIA=0x...
ORACLE_CONTRACT_POLYGON_AMOY=0x...
# etc.

Repository layout

Path	Contents
`app/`	FastAPI backend (`/api/v2`)
`quantum-oracle-ui/`	Next.js 16 dashboard
`docs/`	Technical docs, PRODUCTION.md, upgrade roadmaps, guides (`docs/guides/`)
`examples/`	Standalone sample scripts (e.g. `quantum_randomness_oracle.py`)
`legacy/`	Deprecated Streamlit dashboard and static HTML demos
`scripts/`	Dev helpers (e.g. `scripts/start.py` — API + UI)
`tests/unit/`, `tests/integration/`	Pytest suites
`tests/manual/`	Interactive check scripts (run with `python`, not pytest)
`client_sdk/`, `quantum-oracle/`, `k8s/`	SDK, oracle node/contracts, Kubernetes

Entry points: python run_api.py (API only), python scripts/start.py (API + Next.js).

Documentation

docs/README.md — index of documentation in docs/
docs/UPGRADE_ROADMAP.md — product upgrade map (monetization, platform quality, oracle)
In-app documentation: /docs in the web dashboard
docs/PRODUCTION.md — deployment and operations
Python SDK — client library
docs/IMPLEMENTATION_SUMMARY_2026.md — Phase 1 implementation details
docs/NEXT_STEPS_PHASE2.md — Phase 2 roadmap

License

MIT License.