fixing ui

.env.example

@@ -31,3 +31,78 @@ LOG_FILE=logs/qcrypt.log
 # Database (for future use)
 DATABASE_URL=postgresql://user:password@localhost:5432/qcrypt_db
 REDIS_URL=redis://localhost:6379/0
+
+# =============================================================================
+# Testnet Oracle Configuration (Phase 2 Task 5)
+# Fill these in after deploying contracts to testnets
+# =============================================================================
+
+# Oracle Contract Addresses (deployed)
+# ORACLE_CONTRACT_SEPOLIA=0x...
+# ORACLE_CONTRACT_POLYGON_AMOY=0x...
+# ORACLE_CONTRACT_BSC_TESTNET=0x...
+# ORACLE_CONTRACT_AVALANCHE_FUJI=0x...
+# ORACLE_CONTRACT_FANTOM_TESTNET=0x...
+
+# Testnet RPC URLs (defaults are configured, override if needed)
+TESTNET_RPC_SEPOLIA=https://rpc.sepolia.org
+TESTNET_RPC_POLYGON_AMOY=https://rpc.amoy.polygon.technology
+TESTNET_RPC_BSC_TESTNET=https://data-seed-prebsc-1-s1.binance.org:8545
+TESTNET_RPC_AVALANCHE_FUJI=https://api.avax-test.network/ext/bc/C/rpc
+TESTNET_RPC_FANTOM_TESTNET=https://rpc.testnet.fantom.network
+
+# Testnet Chain IDs (defaults are configured)
+TESTNET_CHAIN_ID_SEPOLIA=11155111
+TESTNET_CHAIN_ID_POLYGON_AMOY=80002
+TESTNET_CHAIN_ID_BSC_TESTNET=97
+TESTNET_CHAIN_ID_AVALANCHE_FUJI=43113
+TESTNET_CHAIN_ID_FANTOM_TESTNET=4002
+
+# Testnet Explorer URLs (defaults are configured)
+TESTNET_EXPLORER_SEPOLIA=https://sepolia.etherscan.io
+TESTNET_EXPLORER_POLYGON_AMOY=https://amoy.polygonscan.com
+TESTNET_EXPLORER_BSC_TESTNET=https://testnet.bscscan.com
+TESTNET_EXPLORER_AVALANCHE_FUJI=https://testnet.snowtrace.io
+TESTNET_EXPLORER_FANTOM_TESTNET=https://testnet.ftmscan.com
+
+# =============================================================================
+# Hardware Quantum Backend (optional)
+# =============================================================================
+# IBM Quantum
+# IBM_QUANTUM_TOKEN=your_ibm_quantum_token
+
+# IQM Quantum
+# IQM_SERVER_URL=https://your-iqm-server.com
+
+# Rigetti Quantum
+# RIGETTI_API_KEY=your_rigetti_api_key
+
+# =============================================================================
+# API Key Tiers
+# =============================================================================
+# Tier limits per window (default window = RATE_LIMIT_PERIOD seconds)
+FREE_TIER_MAX_BYTES=256
+FREE_TIER_MAX_REQUESTS=10
+PRO_TIER_MAX_BYTES=1024
+PRO_TIER_MAX_REQUESTS=100
+ENTERPRISE_TIER_MAX_BYTES=10240
+ENTERPRISE_TIER_MAX_REQUESTS=1000
+
+# Require an API key for every request (false allows anonymous/free)
+REQUIRE_API_KEY=false
+# Comma-separated allow-list (optional; if unset, any key >= 10 chars is accepted)
+# VALID_API_KEYS=key-aaaa1111bbbb2222,key-cccc3333dddd4444
+
+# =============================================================================
+# Stripe Billing (optional — leave commented for local dev)
+# =============================================================================
+# STRIPE_SECRET_KEY=sk_test_...
+# STRIPE_WEBHOOK_SECRET=whsec_...
+# STRIPE_PRICE_ID_PRO=price_...
+# STRIPE_PRICE_ID_ENTERPRISE=price_...
+
+# =============================================================================
+# Monitoring (optional)
+# =============================================================================
+# PROMETHEUS_PORT=9090
+# ENABLE_DETAILED_LOGGING=False

.gitignore

@@ -127,12 +127,19 @@ celerybeat.pid
 
 # Environments
 .env
-.venv
-env/
+
+# Virtual environments — recommended: python -m venv .venv
+# (then: source .venv/bin/activate  |  Windows: .venv\Scripts\activate)
+.venv/
 venv/
+env/
 ENV/
 env.bak/
 venv.bak/
+virtualenv/
+
+# Local usage DB (rate limiting / analytics; default USAGE_DATABASE_URL)
+usage.db
 
 # Spyder project settings
 .spyderproject
@@ -417,6 +424,23 @@ backups/
 archive/
 archives/
 
+# =============================================================================
+# Node / JavaScript
+# =============================================================================
+
+node_modules/
+
+# Next.js build output
+.next/
+out/
+
+# =============================================================================
+# AI / Tool caches
+# =============================================================================
+
+.qwen/
+.cursor/
+
 # =============================================================================
 # Custom Project Files
 # =============================================================================

ENHANCED_DASHBOARD_SUMMARY.md

@@ -1,141 +0,0 @@
-# 🚀 ENHANCED QUANTUM RANDOMNESS ORACLE DASHBOARD
-
-## 🎯 OVERVIEW
-
-The QCrypt RNG dashboard has been significantly enhanced to showcase the Quantum Randomness Oracle functionality and highlight the ready-to-deploy use cases. The dashboard now features three main sections:
-
-1. **Quantum RNG** - Traditional quantum random number generation
-2. **Quantum Oracle** - Dedicated quantum randomness oracle functionality
-3. **Use Cases** - Real-world applications and demonstrations
-
-## ✨ ENHANCED FEATURES
-
-### **Tab 1: Quantum RNG (Original)**
-- Random Bytes generation
-- Cryptographic Keys
-- Session Tokens
-- Quantum UUIDs
-- Secure Passwords
-
-### **Tab 2: Quantum Oracle (NEW)**
-- **Oracle Network Status** - Real-time monitoring of the quantum randomness oracle network
-- **Request Quantum Randomness** - Interface to request quantum randomness for blockchain applications
-- **Check Request Status** - Track the status of randomness requests (pending, committed, fulfilled)
-- **Performance Benchmark** - Run benchmarks to test oracle performance
-
-### **Tab 3: Use Cases (NEW)**
-- **Gaming & Entertainment** - Fair loot drops, tournament brackets, casino games
-- **NFTs & Digital Assets** - Trait distribution, minting randomness, airdrops
-- **DeFi & Finance** - Lottery winners, governance selection, validator choice
-- **DAOs & Governance** - Committee selection, delegate assignment, audit participants
-- **Prediction Markets** - Outcome resolution, oracle selection
-
-## 🧪 DEMONSTRATIONS
-
-Each use case includes live demonstrations showing how the quantum randomness oracle can be used in real applications:
-
-- **Gaming Demo** - Generate quantum randomness for game mechanics
-- **NFT Demo** - Create trait distribution hashes
-- **DeFi Demo** - Generate selection IDs for lotteries
-- **DAO Demo** - Create committee selection seeds
-- **Market Demo** - Generate outcome resolution seeds
-
-## 🔬 CORE FUNCTIONALITY
-
-### **Oracle Network Features:**
-- Real-time network status monitoring
-- Performance metrics tracking
-- Feature availability checking
-- Uptime monitoring
-
-### **Request Management:**
-- Submit randomness requests with customizable parameters
-- Track request status through the commit-reveal process
-- View commitment hashes and fulfillment details
-- Monitor estimated completion times
-
-### **Performance Monitoring:**
-- Run benchmarks to test oracle performance
-- View generation times and throughput metrics
-- Monitor entropy quality
-- Track resource utilization
-
-## 🎯 READY USE CASES
-
-### **✅ Gaming Ready**
-- Fair loot drop mechanisms
-- Transparent casino game outcomes
-- Random tournament bracket generation
-- Character attribute assignment
-
-### **✅ NFTs Ready**
-- Random trait distribution during minting
-- Fair rarity allocation
-- Transparent airdrop mechanisms
-- Artwork generation parameters
-
-### **✅ DeFi Ready**
-- Random winner selection for lotteries
-- Fair governance proposal selection
-- Validator/node selection
-- Incentive distribution mechanisms
-
-### **✅ DAOs Ready**
-- Random committee member selection
-- Fair voting delegate assignment
-- Audit participant selection
-- Proposal random ordering
-
-### **✅ Prediction Markets Ready**
-- Unpredictable event outcome determination
-- Random oracle selection
-- Market maker selection
-- Dispute resolution mechanisms
-
-## 🌐 INTEGRATION POINTS
-
-### **API Endpoints:**
-- `/api/v2/oracle/request` - Request quantum randomness
-- `/api/v2/oracle/status/{request_id}` - Check request status
-- `/api/v2/oracle/network-info` - Get network information
-- `/api/v2/oracle/benchmark` - Run performance benchmarks
-
-### **Blockchain Integration:**
-- Commit-reveal scheme implementation
-- Gas-optimized transactions
-- Event emission for monitoring
-- Callback mechanisms for fulfillment
-
-## 🛡️ SECURITY FEATURES
-
-- **Commit-Reveal Scheme** - Prevents oracle manipulation
-- **Verifiable Quantum Origin** - Mathematical proof of quantum generation
-- **Hardware Abstraction** - Pluggable quantum hardware support
-- **Access Controls** - Role-based permissions
-- **Fee Management** - Configurable per-request fees
-
-## 🚀 DEPLOYMENT READY
-
-The dashboard and quantum randomness oracle are now production-ready with:
-
-- Comprehensive monitoring capabilities
-- Performance benchmarking tools
-- Real-time status tracking
-- Live demonstrations of all use cases
-- Integration testing tools
-- Security validation features
-
-## 📊 BUSINESS VALUE
-
-### **Market Positioning:**
-- First-mover advantage in quantum-blockchain space
-- True quantum randomness vs. classical alternatives
-- Commit-reveal scheme for non-manipulability
-- Modular architecture supporting multiple quantum hardware providers
-
-### **Revenue Opportunities:**
-- Per-request fees: $0.10 - $1.00 per randomness request
-- Subscription plans: Volume-based pricing
-- Premium features: Custom entropy, faster delivery
-
-The enhanced dashboard provides a comprehensive interface for demonstrating the quantum randomness oracle capabilities and showcasing the ready-to-deploy use cases for blockchain applications.

FINAL_IMPLEMENTATION_SUMMARY.md

@@ -1,265 +0,0 @@
-# 🚀 QUANTUM RANDOMNESS ORACLE - COMPLETE IMPLEMENTATION
-
-## 🎯 PROJECT OVERVIEW
-
-The Quantum Randomness Oracle has been successfully implemented as a comprehensive solution that bridges quantum computing and blockchain technologies. It provides verifiable quantum randomness for decentralized applications using a secure commit-reveal scheme.
-
-## ✅ COMPLETED COMPONENTS
-
-### 1. **Smart Contract (`quantum-oracle/contracts/`)**
-- `QuantumRandomnessOracle.sol` with commit-reveal scheme
-- Access controls with role-based permissions
-- Fee management with configurable per-request fees
-- Request tracking with status and history
-- Event emissions for blockchain monitoring
-- Security features to prevent manipulation
-
-### 2. **Oracle Node (`quantum-oracle/oracle-node/`)**
-- `QuantumRandomnessOracleNode` with blockchain monitoring
-- Quantum randomness generation via QCrypt RNG engine
-- Commit-and-reveal mechanism for tamper-proof delivery
-- Optimized for throughput and low latency
-- Integration with quantum hardware abstraction layer
-
-### 3. **Client SDKs (`quantum-oracle/client-sdk/`)**
-- Python SDK with request management and status checking
-- JavaScript SDK with browser and Node.js compatibility
-- Proper error handling and async support
-- Fulfillment waiting mechanisms
-
-### 4. **API Endpoint Integration (`/api/v2/oracle/`)**
-- `request_quantum_randomness` - Create randomness requests
-- `get_oracle_request_status` - Track request status
-- `simulate_oracle_fulfillment` - Simulate fulfillment process
-- `get_oracle_network_info` - Network status and capabilities
-- `benchmark_quantum_oracle` - Performance testing
-
-### 5. **Modern Web UI (`quantum_oracle_ui.html`)**
-- Standalone HTML/CSS/JS application
-- No external dependencies or frameworks
-- Responsive design for all devices
-- Four main sections: Quantum RNG, Quantum Oracle, Use Cases, Network Status
-- Interactive demonstrations for all use cases
-- Real-time metrics and performance indicators
-
-### 6. **Project Infrastructure**
-- Setup scripts for easy deployment
-- Documentation and README files
-- Test suites for all components
-- Proper configuration management
-- Integration with existing QCrypt RNG platform
-
-## 🔬 CORE FEATURES
-
-### **True Quantum Randomness**
-- Uses the same quantum simulation/hardware abstraction as the core API
-- Provides verifiable quantum origin of randomness
-- Entropy validated through statistical tests
-
-### **Commit-Reveal Scheme**
-- Prevents oracle manipulation by committing to a hash first
-- Then revealing the value after the commitment phase
-- Tamper-proof delivery mechanism
-
-### **Verifiable Origin**
-- On-chain proof that randomness came from quantum processes
-- Mathematical verification of quantum origin
-- Cryptographic commitments ensure integrity
-
-### **Hardware Abstraction**
-- Works with simulation today
-- Pluggable to real quantum hardware (ID Quantique, QuintessenceLabs, etc.)
-- Seamless upgrade path
-
-### **Blockchain Agnostic**
-- Compatible with EVM-compatible chains initially
-- Expansion path for other blockchain networks
-- Standardized interfaces
-
-### **Enterprise Ready**
-- Includes monitoring, benchmarking, and security features
-- Scalable architecture for high-volume applications
-- Comprehensive error handling
-
-## 🎮 USE CASES SUPPORTED
-
-### **Gaming**
-- Fair loot drops with verifiable randomness
-- Tournament bracket generation
-- Random matchmaking algorithms
-
-### **NFTs**
-- Verifiable randomness for minting
-- Trait distribution with quantum origin
-- Fair auction mechanisms
-
-### **DeFi**
-- Secure lotteries with tamper-proof randomness
-- Random selection for governance
-- Incentive distribution mechanisms
-
-### **DAOs**
-- Random sampling for committees
-- Fair voting mechanisms
-- Delegate selection processes
-
-### **Prediction Markets**
-- Unpredictable resolution criteria
-- Fair outcome determination
-- Verifiable randomness sources
-
-## 🌐 INTEGRATION POINTS
-
-### **Smart Contract Interface**
-- Standardized event emissions
-- Callback mechanisms for fulfillment
-- Gas-optimized transactions
-
-### **Oracle Node Integration**
-- Real-time blockchain monitoring
-- Quantum randomness generation
-- Automated fulfillment processes
-
-### **Client SDK Integration**
-- Simple request management
-- Status checking capabilities
-- Asynchronous fulfillment waiting
-
-### **API Endpoint Integration**
-- Direct access to oracle functionality
-- Network status information
-- Performance benchmarking
-
-### **Web UI Integration**
-- Standalone interface for all features
-- Real-time metrics and monitoring
-- Interactive demonstrations
-- Cross-platform compatibility
-
-## 🧪 TESTING RESULTS
-
-### **Functionality Verified**
-- ✅ Quantum randomness generation working
-- ✅ Hardware abstraction layer functional
-- ✅ Commit-reveal scheme implemented
-- ✅ All API endpoints accessible
-- ✅ Client SDKs operational
-- ✅ Performance benchmarks completed
-- ✅ Modern Web UI fully functional
-
-### **Security Features Confirmed**
-- ✅ Oracle manipulation prevention
-- ✅ Commitment verification
-- ✅ Access control enforcement
-- ✅ Fee management working
-
-### **Integration Points Validated**
-- ✅ Smart contract interaction
-- ✅ Blockchain monitoring
-- ✅ Hardware abstraction
-- ✅ API endpoint access
-- ✅ Web UI integration
-
-## 📊 PERFORMANCE METRICS
-
-### **Generation Speed**
-- Average generation time: ~15ms
-- Throughput: ~30+ samples per second
-- Entropy quality: 256 bits per sample
-
-### **Network Performance**
-- Request processing: Sub-second
-- Fulfillment time: 1-2 blocks
-- Commitment verification: Instant
-
-### **UI Performance**
-- Fast loading times
-- Responsive interactions
-- Real-time metrics display
-- Cross-browser compatibility
-
-### **Resource Usage**
-- Memory efficient
-- CPU optimized
-- Network bandwidth optimized
-
-## 🚀 DEPLOYMENT READINESS
-
-### **Production Features**
-- Comprehensive monitoring
-- Performance benchmarking
-- Error handling and recovery
-- Configuration management
-- Modern web interface
-
-### **Security Measures**
-- Input validation
-- Rate limiting
-- Access controls
-- Audit logging
-
-### **Scalability**
-- Horizontal scaling support
-- Load balancing ready
-- Performance optimization
-- Resource management
-
-## 🌍 ACCESS INFORMATION
-
-### **Web Interface**
-- **URL**: http://localhost:8080/quantum_oracle_ui.html
-- **Features**: Complete UI for all quantum randomness oracle functionality
-- **Responsive**: Works on desktop, tablet, and mobile
-
-### **API Endpoints**
-- **Base URL**: http://localhost:8000/api/v2/
-- **Oracle**: `/oracle/request`, `/oracle/status/{id}`, `/oracle/network-info`, `/oracle/benchmark`
-- **Documentation**: http://localhost:8000/docs
-
-### **Components**
-- **Smart Contracts**: Deployed to blockchain networks
-- **Oracle Node**: Running as background service
-- **SDKs**: Available for Python and JavaScript integration
-
-## 📈 BUSINESS VALUE
-
-### **Market Positioning**
-- First-mover advantage in quantum-blockchain space
-- True quantum randomness vs. classical alternatives
-- Commit-reveal scheme for non-manipulability
-- Modular architecture supporting multiple quantum hardware providers
-
-### **Competitive Advantages**
-- Quantum origin: True randomness from quantum mechanical processes
-- Unpredictability: Fundamentally impossible to predict quantum outcomes
-- Non-Manipulability: Quantum processes cannot be influenced by external factors
-- Scalability: Can handle thousands of requests per second
-
-### **Revenue Opportunities**
-- Per-request fees: $0.10 - $1.00 per randomness request
-- Subscription plans: Volume-based pricing
-- Premium features: Custom entropy, faster delivery
-
-## 🎉 CONCLUSION
-
-The Quantum Randomness Oracle is fully implemented and ready for deployment. It successfully integrates quantum randomness generation with blockchain oracles, providing verifiable, tamper-proof randomness for decentralized applications. The implementation follows best practices for security, scalability, and maintainability.
-
-### **Ready for Next Steps:**
-- Testnet deployment
-- Security auditing
-- Partnership development
-- Performance optimization
-- Real quantum hardware integration
-
-The solution positions itself as the standard for quantum-enhanced blockchain security, with clear paths to monetization and sustainable competitive advantages.
-
-### **Key Deliverables:**
-- ✅ Complete smart contract implementation
-- ✅ Full oracle node functionality
-- ✅ Client SDKs for multiple languages
-- ✅ Modern web interface (no Streamlit dependency)
-- ✅ Comprehensive API endpoints
-- ✅ All use cases demonstrated and ready
-- ✅ Production-ready architecture
-
-The implementation is complete and ready for deployment! 🚀

IMPLEMENTATION_SUMMARY.md

@@ -1,121 +0,0 @@
-#!/usr/bin/env python3
-"""
-Final Summary: Quantum Randomness Oracle Implementation
-"""
-
-print("🏆 QUANTUM RANDOMNESS ORACLE - IMPLEMENTATION SUMMARY")
-print("=" * 60)
-
-print("\n🎯 OBJECTIVE:")
-print("   Build a quantum randomness oracle for blockchain integration")
-print("   as specified in the ORACLE_FEATURE.md document")
-
-print("\n✅ COMPLETED COMPONENTS:")
-
-print("\n1. 📄 Smart Contract (`quantum-oracle/contracts/`)")
-print("   • QuantumRandomnessOracle.sol with commit-reveal scheme")
-print("   • Access controls with role-based permissions")
-print("   • Fee management with configurable per-request fees")
-print("   • Request tracking with status and history")
-print("   • Event emissions for blockchain monitoring")
-print("   • Security features to prevent manipulation")
-
-print("\n2. 🖥️  Oracle Node (`quantum-oracle/oracle-node/`)")
-print("   • QuantumRandomnessOracleNode with blockchain monitoring")
-print("   • Quantum randomness generation via QCrypt RNG engine")
-print("   • Commit-and-reveal mechanism for tamper-proof delivery")
-print("   • Optimized for throughput and low latency")
-print("   • Integration with quantum hardware abstraction layer")
-
-print("\n3. 📚 Client SDKs (`quantum-oracle/client-sdk/`)")
-print("   • Python SDK with request management and status checking")
-print("   • JavaScript SDK with browser and Node.js compatibility")
-print("   • Proper error handling and async support")
-print("   • Fulfillment waiting mechanisms")
-
-print("\n4. 🌐 API Endpoint Integration (`/api/v2/oracle/`)")
-print("   • request_quantum_randomness - Create randomness requests")
-print("   • get_oracle_request_status - Track request status")
-print("   • simulate_oracle_fulfillment - Simulate fulfillment process")
-print("   • get_oracle_network_info - Network status and capabilities")
-print("   • benchmark_quantum_oracle - Performance testing")
-
-print("\n5. 🏗️  Project Infrastructure")
-print("   • Setup scripts for easy deployment")
-print("   • Documentation and README files")
-print("   • Test suites for all components")
-print("   • Proper configuration management")
-print("   • Integration with existing QCrypt RNG platform")
-
-print("\n⚛️  CORE FEATURES IMPLEMENTED:")
-
-print("\n• 🔬 True Quantum Randomness")
-print("  Uses the same quantum simulation/hardware abstraction as the core API")
-print("  Provides verifiable quantum origin of randomness")
-
-print("\n• 🛡️ Commit-Reveal Scheme")
-print("  Prevents oracle manipulation by committing to a hash first")
-print("  Then revealing the value after the commitment phase")
-
-print("\n• 🔍 Verifiable Origin")
-print("  On-chain proof that randomness came from quantum processes")
-print("  Mathematical verification of quantum origin")
-
-print("\n• 🔌 Hardware Abstraction")
-print("  Works with simulation today")
-print("  Pluggable to real quantum hardware (ID Quantique, QuintessenceLabs, etc.)")
-
-print("\n• 🌍 Blockchain Agnostic")
-print("  Compatible with EVM-compatible chains initially")
-print("  Expansion path for other blockchain networks")
-
-print("\n• 🏢 Enterprise Ready")
-print("  Includes monitoring, benchmarking, and security features")
-print("  Scalable architecture for high-volume applications")
-
-print("\n🎮 USE CASES SUPPORTED:")
-
-print("\n• 🎮 Gaming")
-print("  Fair loot drops, tournament brackets, random matchmaking")
-
-print("\n• 🎨 NFTs")
-print("  Verifiable randomness for minting and trait distribution")
-
-print("\n• 💰 DeFi")
-print("  Lotteries, random selection for governance, incentive distribution")
-
-print("\n• 👥 DAOs")
-print("  Random sampling for committees, fair voting mechanisms")
-
-print("\n• 📈 Prediction Markets")
-print("  Unpredictable resolution criteria")
-
-print("\n🧪 TESTING RESULTS:")
-print("   • All oracle endpoints are functional")
-print("   • Quantum randomness generation verified")
-print("   • Hardware abstraction layer working")
-print("   • Commit-reveal scheme implemented")
-print("   • Performance benchmarks completed")
-print("   • Integration with blockchain demo confirmed")
-
-print("\n🔄 INTEGRATION POINTS:")
-print("   • Seamless integration with existing QCrypt RNG platform")
-print("   • Compatible with quantum hardware interfaces")
-print("   • Ready for real blockchain deployments")
-print("   • Follows enterprise security standards")
-
-print("\n📈 BUSINESS VALUE:")
-print("   • Addresses critical need for true randomness in blockchain")
-print("   • Provides quantum advantage over classical solutions")
-print("   • Future-proof with hardware upgrade path")
-print("   • Scalable for commercial applications")
-
-print("\n✨ CONCLUSION:")
-print("   The Quantum Randomness Oracle is fully implemented and ready for deployment.")
-print("   It successfully integrates quantum randomness generation with blockchain oracles,")
-print("   providing verifiable, tamper-proof randomness for decentralized applications.")
-print("   The implementation follows best practices for security, scalability, and maintainability.")
-
-print("\n" + "=" * 60)
-print("🏆 IMPLEMENTATION COMPLETE - READY FOR DEPLOYMENT 🚀")
-print("=" * 60)

Makefile

@@ -13,10 +13,10 @@ install:
 	pip install -r requirements.txt
 
 test:
-	python test_qrng.py
+	pytest
 
 run:
-	python test_qrng.py
+	python scripts/start.py
 
 clean:
 	find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true

PRODUCTION.md

@@ -1,236 +1,3 @@
-# QCrypt RNG - Production Deployment Guide
+# Production deployment
 
-This guide provides instructions for deploying QCrypt RNG in a production environment.
-
-## Table of Contents
-- [Architecture Overview](#architecture-overview)
-- [Prerequisites](#prerequisites)
-- [Environment Configuration](#environment-configuration)
-- [Deployment Options](#deployment-options)
-- [Security Considerations](#security-considerations)
-- [Monitoring and Maintenance](#monitoring-and-maintenance)
-- [Troubleshooting](#troubleshooting)
-
-## Architecture Overview
-
-QCrypt RNG consists of the following components:
-
-- **API Server**: FastAPI application serving quantum random number generation endpoints
-- **Dashboard**: Streamlit-based web interface for visualization and management
-- **Database**: PostgreSQL for persistent data storage
-- **Cache**: Redis for session management and caching
-- **Quantum Backend**: Either simulated or connected to real quantum computers
-
-## Prerequisites
-
-Before deploying QCrypt RNG in production, ensure you have:
-
-- **Kubernetes cluster** (v1.20+) or **Docker Compose** environment
-- **Domain name** for your deployment
-- **SSL certificate** for HTTPS
-- **PostgreSQL database** (managed or self-hosted)
-- **Redis instance** (managed or self-hosted)
-- **Quantum computing access** (optional, for real quantum backends)
-
-## Environment Configuration
-
-### Required Environment Variables
-
-#### API Server
-```bash
-# Application settings
-ENVIRONMENT=production
-DEBUG=false
-APP_NAME="QCrypt RNG Production"
-APP_VERSION="2.0.0"
-
-# API configuration
-API_HOST=0.0.0.0
-API_PORT=8000
-ALLOWED_ORIGINS=https://yourdomain.com,https://dashboard.yourdomain.com
-
-# Security configuration
-SECRET_KEY=your-very-long-secret-key-here-at-least-32-chars
-ALGORITHM=HS256
-ACCESS_TOKEN_EXPIRE_MINUTES=30
-
-# Database configuration
-DATABASE_URL=postgresql://user:password@host:port/database
-
-# Cache configuration
-REDIS_URL=redis://host:port/0
-
-# Quantum backend configuration
-QUANTUM_BACKEND=ibm_quantum  # or qrisp_simulator, iqm_quantum, rigetti
-IBM_QUANTUM_TOKEN=your_ibm_quantum_token  # if using IBM backend
-
-# Rate limiting
-RATE_LIMIT_REQUESTS=1000
-RATE_LIMIT_PERIOD=3600
-
-# Tier limits
-FREE_TIER_MAX_BYTES=256
-FREE_TIER_MAX_REQUESTS=100
-PRO_TIER_MAX_BYTES=1024
-PRO_TIER_MAX_REQUESTS=1000
-ENTERPRISE_TIER_MAX_BYTES=10240
-ENTERPRISE_TIER_MAX_REQUESTS=10000
-
-# API key configuration
-REQUIRE_API_KEY=true
-API_KEY_HEADER=X-API-Key
-# Comma-separated list of accepted API keys (in-memory allow-list).
-# For large-scale deployments, replace with a database or Redis lookup.
-VALID_API_KEYS=key-aaaa1111bbbb2222,key-cccc3333dddd4444
-
-# Request body size limit (bytes). Default 1 MB.
-MAX_REQUEST_BODY_SIZE_BYTES=1048576
-
-# Monitoring
-LOG_LEVEL=INFO
-ENABLE_DETAILED_LOGGING=true
-ENABLE_AUDIT_LOGGING=true
-AUDIT_LOG_RETENTION_DAYS=365
-FIPS_MODE=false
-```
-
-#### Dashboard
-```bash
-API_BASE_URL=https://api.yourdomain.com/api/v2
-STREAMLIT_SERVER_PORT=8501
-STREAMLIT_SERVER_HEADLESS=true
-```
-
-## Deployment Options
-
-### Option 1: Kubernetes Deployment
-
-1. **Prepare your Kubernetes cluster** with sufficient resources
-2. **Update the Kubernetes manifests** in the `k8s/` directory with your specific configurations
-3. **Set up secrets** for sensitive information:
-
-```bash
-kubectl create secret generic postgres-secret \
-  --from-literal=password=your_secure_password \
-  -n qcrypt-rng
-```
-
-4. **Deploy using the provided script**:
-
-```bash
-./deploy.sh
-```
-
-### Option 2: Docker Compose Deployment
-
-1. **Update the docker-compose.yml** file with your environment variables
-2. **Build and deploy**:
-
-```bash
-docker-compose up -d
-```
-
-### Option 3: Manual Deployment
-
-1. **Set up your infrastructure** (database, cache, load balancer)
-2. **Configure environment variables** as shown above
-3. **Deploy the application** using your preferred method (PM2, systemd, etc.)
-
-## Security Considerations
-
-### API Security
-- Always use HTTPS in production.
-- **CORS** is restricted to the origins listed in `ALLOWED_ORIGINS`. Never use `*` with credentials in production.
-- **Security headers** are added automatically to every response:
-  - `X-Content-Type-Options: nosniff`
-  - `X-Frame-Options: DENY`
-  - `Referrer-Policy: strict-origin-when-cross-origin`
-  - `Permissions-Policy: geolocation=(), camera=(), microphone=()`
-  - In production (`ENVIRONMENT=production`): `Strict-Transport-Security` and `Content-Security-Policy` are also set.
-- **Request body size limit** is enforced (default 1 MB, configurable via `MAX_REQUEST_BODY_SIZE_BYTES`). Requests exceeding the limit receive HTTP 413.
-- **SECRET_KEY** must be set to a real value (>= 32 characters) in production. The application will refuse to start if the default placeholder is detected when `ENVIRONMENT=production`.
-
-### API Key Management
-- Set `REQUIRE_API_KEY=true` in production.
-- Supply accepted keys via `VALID_API_KEYS` (comma-separated). Keys are validated using constant-time comparison. The raw key is never logged; only a SHA-256 prefix hash appears in audit logs.
-- For large-scale deployments, replace the in-memory allow-list with a database or Redis lookup in `api_key_middleware`.
-- Enable rate limiting to prevent abuse.
-- Regularly rotate secrets and API keys.
-
-### Audit Logging
-- Security events (invalid/missing API keys, rate-limit violations) are written to `logs/security_<date>.log` via the dedicated security logger.
-- Audit logs are retained for 365 days by default (`AUDIT_LOG_RETENTION_DAYS`).
-- Sensitive values (API keys, randomness) are never included in logs.
-
-### Data Protection
-- Encrypt sensitive data in transit and at rest.
-- Implement proper backup strategies.
-- Follow the principle of least privilege.
-- Regular security audits and penetration testing.
-
-### Quantum Backend Security
-- Secure access to quantum computers.
-- Implement proper authentication and authorization.
-- Monitor quantum backend access logs.
-- Regular updates and patches.
-
-## Monitoring and Maintenance
-
-### Key Metrics to Monitor
-- API response times
-- Error rates
-- Quantum generation performance
-- Database performance
-- Cache hit ratios
-- Resource utilization
-
-### Logging
-- Enable detailed logging in production
-- Implement log aggregation and analysis
-- Set up alerts for critical issues
-- Regular log rotation and archival
-
-### Maintenance Tasks
-- Regular security updates
-- Database maintenance and optimization
-- Quantum backend calibration
-- Performance tuning
-
-## Troubleshooting
-
-### Common Issues
-
-#### API Server Not Starting
-- Check environment variables
-- Verify database connectivity
-- Review logs for specific error messages
-
-#### Slow Quantum Generation
-- Check quantum backend configuration
-- Verify sufficient qubit allocation
-- Review performance metrics
-
-#### Dashboard Not Connecting to API
-- Verify API_BASE_URL configuration
-- Check network connectivity between services
-- Review CORS settings
-
-### Getting Help
-- Check the logs in the `logs/` directory
-- Review the API documentation at `/docs`
-- Contact support at [support@qcrypt.example.com](mailto:support@qcrypt.example.com)
-- Open an issue in our [GitHub repository](https://github.com/quantumGlobalGroup/qcrypt-rng)
-
-## Upgrading
-
-To upgrade to a new version:
-
-1. **Backup your data** (database, configuration files)
-2. **Review release notes** for breaking changes
-3. **Test in staging environment** first
-4. **Deploy to production** following your standard procedures
-5. **Monitor closely** after deployment
-
----
-
-For additional support or questions, please reach out to our team.
+The full production guide lives in **[docs/PRODUCTION.md](docs/PRODUCTION.md)**.

QUANTUM_ORACLE_COMPLETE_SUMMARY.md

@@ -1,214 +0,0 @@
-# 🚀 QUANTUM RANDOMNESS ORACLE - COMPLETE IMPLEMENTATION
-
-## 🎯 PROJECT OVERVIEW
-
-The Quantum Randomness Oracle has been successfully implemented as a comprehensive solution that bridges quantum computing and blockchain technologies. It provides verifiable quantum randomness for decentralized applications using a secure commit-reveal scheme.
-
-## ✅ COMPLETED COMPONENTS
-
-### 1. **Smart Contract (`quantum-oracle/contracts/`)**
-- `QuantumRandomnessOracle.sol` with commit-reveal scheme
-- Access controls with role-based permissions
-- Fee management with configurable per-request fees
-- Request tracking with status and history
-- Event emissions for blockchain monitoring
-- Security features to prevent manipulation
-
-### 2. **Oracle Node (`quantum-oracle/oracle-node/`)**
-- `QuantumRandomnessOracleNode` with blockchain monitoring
-- Quantum randomness generation via QCrypt RNG engine
-- Commit-and-reveal mechanism for tamper-proof delivery
-- Optimized for throughput and low latency
-- Integration with quantum hardware abstraction layer
-
-### 3. **Client SDKs (`quantum-oracle/client-sdk/`)**
-- Python SDK with request management and status checking
-- JavaScript SDK with browser and Node.js compatibility
-- Proper error handling and async support
-- Fulfillment waiting mechanisms
-
-### 4. **API Endpoint Integration (`/api/v2/oracle/`)**
-- `request_quantum_randomness` - Create randomness requests
-- `get_oracle_request_status` - Track request status
-- `simulate_oracle_fulfillment` - Simulate fulfillment process
-- `get_oracle_network_info` - Network status and capabilities
-- `benchmark_quantum_oracle` - Performance testing
-
-### 5. **Project Infrastructure**
-- Setup scripts for easy deployment
-- Documentation and README files
-- Test suites for all components
-- Proper configuration management
-- Integration with existing QCrypt RNG platform
-
-## 🔬 CORE FEATURES
-
-### **True Quantum Randomness**
-- Uses the same quantum simulation/hardware abstraction as the core API
-- Provides verifiable quantum origin of randomness
-- Entropy validated through statistical tests
-
-### **Commit-Reveal Scheme**
-- Prevents oracle manipulation by committing to a hash first
-- Then revealing the value after the commitment phase
-- Tamper-proof delivery mechanism
-
-### **Verifiable Origin**
-- On-chain proof that randomness came from quantum processes
-- Mathematical verification of quantum origin
-- Cryptographic commitments ensure integrity
-
-### **Hardware Abstraction**
-- Works with simulation today
-- Pluggable to real quantum hardware (ID Quantique, QuintessenceLabs, etc.)
-- Seamless upgrade path
-
-### **Blockchain Agnostic**
-- Compatible with EVM-compatible chains initially
-- Expansion path for other blockchain networks
-- Standardized interfaces
-
-### **Enterprise Ready**
-- Includes monitoring, benchmarking, and security features
-- Scalable architecture for high-volume applications
-- Comprehensive error handling
-
-## 🎮 USE CASES SUPPORTED
-
-### **Gaming**
-- Fair loot drops with verifiable randomness
-- Tournament bracket generation
-- Random matchmaking algorithms
-
-### **NFTs**
-- Verifiable randomness for minting
-- Trait distribution with quantum origin
-- Fair auction mechanisms
-
-### **DeFi**
-- Secure lotteries with tamper-proof randomness
-- Random selection for governance
-- Incentive distribution mechanisms
-
-### **DAOs**
-- Random sampling for committees
-- Fair voting mechanisms
-- Delegate selection processes
-
-### **Prediction Markets**
-- Unpredictable resolution criteria
-- Fair outcome determination
-- Verifiable randomness sources
-
-## 🌐 INTEGRATION POINTS
-
-### **Smart Contract Interface**
-- Standardized event emissions
-- Callback mechanisms for fulfillment
-- Gas-optimized transactions
-
-### **Oracle Node Integration**
-- Real-time blockchain monitoring
-- Quantum randomness generation
-- Automated fulfillment processes
-
-### **Client SDK Integration**
-- Simple request management
-- Status checking capabilities
-- Asynchronous fulfillment waiting
-
-### **API Endpoint Integration**
-- Direct access to oracle functionality
-- Network status information
-- Performance benchmarking
-
-## 🧪 TESTING RESULTS
-
-### **Functionality Verified**
-- ✅ Quantum randomness generation working
-- ✅ Hardware abstraction layer functional
-- ✅ Commit-reveal scheme implemented
-- ✅ All API endpoints accessible
-- ✅ Client SDKs operational
-- ✅ Performance benchmarks completed
-
-### **Security Features Confirmed**
-- ✅ Oracle manipulation prevention
-- ✅ Commitment verification
-- ✅ Access control enforcement
-- ✅ Fee management working
-
-### **Integration Points Validated**
-- ✅ Smart contract interaction
-- ✅ Blockchain monitoring
-- ✅ Hardware abstraction
-- ✅ API endpoint access
-
-## 📊 PERFORMANCE METRICS
-
-### **Generation Speed**
-- Average generation time: ~15ms
-- Throughput: ~30+ samples per second
-- Entropy quality: 256 bits per sample
-
-### **Network Performance**
-- Request processing: Sub-second
-- Fulfillment time: 1-2 blocks
-- Commitment verification: Instant
-
-### **Resource Usage**
-- Memory efficient
-- CPU optimized
-- Network bandwidth optimized
-
-## 🚀 DEPLOYMENT READINESS
-
-### **Production Features**
-- Comprehensive monitoring
-- Performance benchmarking
-- Error handling and recovery
-- Configuration management
-
-### **Security Measures**
-- Input validation
-- Rate limiting
-- Access controls
-- Audit logging
-
-### **Scalability**
-- Horizontal scaling support
-- Load balancing ready
-- Performance optimization
-- Resource management
-
-## 📈 BUSINESS VALUE
-
-### **Market Positioning**
-- First-mover advantage in quantum-blockchain space
-- True quantum randomness vs. classical alternatives
-- Commit-reveal scheme for non-manipulability
-- Modular architecture supporting multiple quantum hardware providers
-
-### **Competitive Advantages**
-- Quantum origin: True randomness from quantum mechanical processes
-- Unpredictability: Fundamentally impossible to predict quantum outcomes
-- Non-Manipulability: Quantum processes cannot be influenced by external factors
-- Scalability: Can handle thousands of requests per second
-
-### **Revenue Opportunities**
-- Per-request fees: $0.10 - $1.00 per randomness request
-- Subscription plans: Volume-based pricing
-- Premium features: Custom entropy, faster delivery
-
-## 🎉 CONCLUSION
-
-The Quantum Randomness Oracle is fully implemented and ready for deployment. It successfully integrates quantum randomness generation with blockchain oracles, providing verifiable, tamper-proof randomness for decentralized applications. The implementation follows best practices for security, scalability, and maintainability.
-
-### **Ready for Next Steps:**
-- Testnet deployment
-- Security auditing
-- Partnership development
-- Performance optimization
-- Real quantum hardware integration
-
-The solution positions itself as the standard for quantum-enhanced blockchain security, with clear paths to monetization and sustainable competitive advantages.

README.md

@@ -1,12 +1,3 @@
----
-title: QCrypt RNG
-colorFrom: indigo
-colorTo: purple
-sdk: docker
-app_port: 7860
-pinned: false
----
-
 # QCrypt RNG
 
 **Quantum-enhanced random number generation, post-quantum cryptography, and blockchain security.**
@@ -15,16 +6,25 @@ QCrypt RNG is a platform for cryptographically secure randomness and quantum-res
 
 **Live demo:** [Hugging Face Spaces](https://huggingface.co/spaces/rocRevyAreGoals15/qcrypt-rng)
 
+**Upgrade roadmap:** [docs/UPGRADE_ROADMAP.md](docs/UPGRADE_ROADMAP.md)
+
+**AI / Cursor session prompt:** [docs/CURSOR_OPERATOR_PROMPT.md](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** — DILITHIUM2/3/5 signatures and KYBER512/768/1024 key exchange with threat assessment and migration guidance.
+- **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.
 
 ---
@@ -38,10 +38,14 @@ QCrypt RNG is a platform for cryptographically secure randomness and quantum-res
 ```bash
 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:**
@@ -52,9 +56,9 @@ npm install
 npm run dev
 ```
 
-Dashboard: http://localhost:3000 (auto-discovers API on ports 8000–8004, or set `NEXT_PUBLIC_API_BASE_URL`).
+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 [PRODUCTION.md](PRODUCTION.md). For Docker: `docker-compose up -d` or Kubernetes via `./deploy.sh`.
+**Production:** See [docs/PRODUCTION.md](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](https://huggingface.co/settings/tokens) with write access when prompted. The app will be available at your Space URL after the build completes.
 
@@ -80,14 +84,124 @@ Each card includes an info popover; collapsible sections are used for dense work
 
 Base path: `/api/v2`.
 
-| Area | Endpoints |
-|------|-----------|
-| **Generation** | `POST /generate/bytes`, `/generate/key`, `/generate/uuid`, `/generate/password`, `/generate/token`, `/generate/batch` |
-| **Data Protection** | `POST /protect/encrypt`, `/protect/decrypt`, `/protect/encrypt-file`, `/protect/decrypt-file`, `/protect/sign`, `/protect/verify`, `/protect/hash`, `/protect/salt` |
-| **Post-quantum** | `POST /pqc/generate`, `/pqc/sign`, `/pqc/verify`; `GET /pqc/algorithms`, `/pqc/info`; `POST /pqc/threat-assessment` |
-| **Oracle and VRF** | `POST /oracle/request`, `/oracle/requests/batch`; `GET /oracle/status/:id`, `/oracle/network-info`, `/oracle/benchmark`; `POST /oracle/vrf/seed`, `/oracle/vrf/prove`, `/oracle/vrf/reveal`, `/oracle/vrf/verify` |
-| **Blockchain** | `POST /blockchain/create-wallet`, `/blockchain/sign-transaction`, `/blockchain/simulate-attack`, `/blockchain/verify-quantum-safe`, `/blockchain/mine-block`; `GET /blockchain/compare-blockchains` |
-| **System** | `GET /health`, `/quantum/entropy`, `/quantum/stats`; `POST /quantum/reseed`; `GET /hardware/devices`, `/monitoring/metrics` |
+### 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).
 
@@ -98,16 +212,158 @@ Full interactive API docs: http://localhost:8000/docs (or `/swagger` when runnin
 - **Backend:** FastAPI, Uvicorn, Python 3.8+
 - **Frontend:** Next.js 16, React, TypeScript, Tailwind CSS
 - **Quantum:** QRisp-style simulation; hardware abstraction for photonic/superconducting devices
-- **Crypto:** PyCryptodome (Keccak-256), `cryptography` (AES/RSA/ECDSA), liboqs-python (DILITHIUM/KYBER)
+- **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:**
+```bash
+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:**
+```bash
+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
+
+1. **Configure Chain:** `POST /oracle/fulfillment/configure-chain`
+2. **Create Request:** `POST /oracle/fulfillment/request`
+3. **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](docs/next-phase/TESTNET_DEPLOYMENT.md)
+
+```bash
+# 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:
+```bash
+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](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](docs/README.md) — index of documentation in `docs/`
+- [docs/UPGRADE_ROADMAP.md](docs/UPGRADE_ROADMAP.md) — product upgrade map (monetization, platform quality, oracle)
 - In-app documentation: `/docs` in the web dashboard
-- [PRODUCTION.md](PRODUCTION.md) — deployment and operations
+- [docs/PRODUCTION.md](docs/PRODUCTION.md) — deployment and operations
 - [Python SDK](client_sdk/python/README.md) — client library
+- [docs/IMPLEMENTATION_SUMMARY_2026.md](docs/IMPLEMENTATION_SUMMARY_2026.md) — Phase 1 implementation details
+- [docs/NEXT_STEPS_PHASE2.md](docs/NEXT_STEPS_PHASE2.md) — Phase 2 roadmap
 
 ---
 

README_ENHANCED.md

@@ -1,249 +0,0 @@
-# 🎲 QCrypt RNG - Quantum-Enhanced Random Number Generation
-
-**Enterprise-grade quantum-simulation random number generation API with post-quantum cryptography capabilities and real hardware integration pathways.**
-
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
-[![FastAPI](https://img.shields.io/badge/FastAPI-0.104.1-green.svg)](https://fastapi.tiangolo.com/)
-
-## 🌟 Overview
-
-QCrypt RNG is a comprehensive quantum-enhanced random number generation system designed for enterprise applications requiring cryptographically secure randomness. Our platform combines quantum simulation techniques with a hardware abstraction layer that enables seamless transition to real quantum hardware devices.
-
-### Why Quantum-Enhanced Randomness?
-
-Traditional pseudo-random number generators rely on deterministic algorithms that can be predictable to sophisticated attackers. Quantum-enhanced randomness leverages the inherent unpredictability of quantum mechanical processes to generate truly random numbers that are impossible to predict, even with unlimited computational power.
-
-### Hardware-Ready Architecture
-
-Our unique hardware abstraction layer means you can start with our quantum-simulation engine today and seamlessly upgrade to real quantum hardware (ID Quantique, QuintessenceLabs, etc.) when it becomes available in your infrastructure.
-
-## ✨ Key Features
-
-### 🔢 Quantum-Enhanced Random Number Generation
-- **Random Bytes**: Generate cryptographically secure random data using quantum simulation
-- **Cryptographic Keys**: Create AES, RSA, and ECDSA keys with quantum-enhanced entropy
-- **Session Tokens**: Generate secure authentication tokens with quantum randomness
-- **Quantum UUIDs**: Create unique identifiers with quantum-enhanced entropy
-- **Secure Passwords**: Generate strong passwords with quantum-enhanced randomness
-
-### 🔬 Quantum Hardware Interface
-- **Modular Architecture**: Designed for easy integration with real quantum hardware
-- **Hardware Abstraction Layer**: Switch between simulation and real quantum devices
-- **API Compatibility**: Same API for both simulation and hardware modes
-- **Performance Benchmarking**: Compare simulation vs hardware performance
-- **Device Management**: Connect/disconnect and calibrate quantum hardware devices
-
-### ⛓️ Blockchain Security Analysis
-- **Quantum Threat Simulation**: Analyze vulnerability to quantum attacks
-- **Wallet Creation**: Generate both vulnerable and quantum-safe wallets
-- **Attack Timeline**: Visualize quantum computing threat progression
-- **Security Comparison**: Compare classical vs quantum-resistant algorithms
-
-### 🔮 Post-Quantum Cryptography
-- **NIST-Standardized Algorithms**: DILITHIUM and KYBER implementations
-- **Quantum-Safe Key Generation**: Create future-proof cryptographic keys
-- **Threat Assessment**: Evaluate quantum resistance of existing algorithms
-- **Migration Guidance**: Recommendations for quantum-safe transitions
-
-### 🏢 Enterprise Features
-- **Rate Limiting**: Tier-based rate limiting (Free, Pro, Enterprise)
-- **Usage Tracking**: Comprehensive usage analytics and billing support
-- **API Key Management**: Secure API key authentication
-- **Monitoring & Analytics**: Real-time metrics and performance insights
-- **Production Deployment**: Docker and Kubernetes ready
-
-### 🛡️ Security Features
-- **Quantum-Enhanced Entropy**: High-quality randomness from quantum simulation
-- **Real Hardware Ready**: Pathways to true quantum randomness from quantum devices
-- **NIST Compliance**: Post-quantum cryptographic standards
-- **Audit Logging**: Comprehensive security event tracking
-- **Rate Limiting**: Protection against abuse and attacks
-- **Input Validation**: Robust parameter checking and sanitization
-- **API Key Authentication**: Secure access control
-- **FIPS Mode**: Government compliance support
-
-## 🚀 Quick Start
-
-### Prerequisites
-- Python 3.8+
-- pip package manager
-- Docker (for containerized deployment)
-
-### Development Installation
-
-1. **Clone the repository**
-   ```bash
-   git clone <repository-url>
-   cd qcrypt-rng
-   ```
-
-2. **Install dependencies**
-   ```bash
-   make install
-   # or
-   pip install -r requirements.txt
-   ```
-
-3. **Start the API server**
-   ```bash
-   python run_api.py
-   ```
-
-4. **Launch the dashboard**
-   ```bash
-   streamlit run dashboard.py
-   ```
-
-### Production Deployment
-
-For production deployment, see our [Production Guide](PRODUCTION.md):
-
-1. **Containerized Deployment (Recommended)**
-   ```bash
-   # Using Docker Compose
-   docker-compose up -d
-
-   # Or using Kubernetes
-   ./deploy.sh
-   ```
-
-### Access Points
-- **API Server**: http://localhost:8000 (Dev) | https://api.yourdomain.com (Prod)
-- **API Documentation**: http://localhost:8000/docs
-- **Dashboard**: http://localhost:8501 (Dev) | https://dashboard.yourdomain.com (Prod)
-- **Monitoring**: http://localhost:8000/api/v2/monitoring/metrics
-- **Hardware Interface**: http://localhost:8000/api/v2/hardware/devices
-
-## 🏗️ Architecture
-
-The system is built with a modular, hardware-agnostic architecture:
-
-- **FastAPI Backend**: High-performance API server with middleware
-- **Streamlit Dashboard**: Interactive web interface
-- **Quantum Engine**: Core quantum-simulation random generation with hardware abstraction
-- **Security Modules**: Blockchain and PQC implementations
-- **Hardware Integration Layer**: Pluggable interfaces for real quantum devices
-- **Enterprise Features**: Rate limiting, usage tracking, monitoring
-- **Comprehensive Testing**: Unit and integration tests
-
-## 🔧 Technology Stack
-
-- **Backend**: FastAPI, Uvicorn
-- **Frontend**: Streamlit
-- **Quantum**: QRisp, liboqs-python
-- **Cryptography**: Cryptography, PyCryptodome
-- **Database**: PostgreSQL, Redis, SQLite (for usage tracking)
-- **Testing**: Pytest, HTTPx
-- **Monitoring**: Loguru, Custom metrics
-- **Containerization**: Docker, Kubernetes
-
-## 📊 Use Cases
-
-### Enterprise Applications
-- **Financial Services**: Secure trading systems, payment processing
-- **Healthcare**: Patient data encryption, secure communications
-- **Government**: National security, classified communications
-- **Blockchain**: Cryptocurrency wallets, smart contracts
-
-### Development & Research
-- **Cryptographic Research**: Algorithm testing and validation
-- **Security Auditing**: Vulnerability assessment and penetration testing
-- **Educational**: Quantum computing and cryptography learning
-- **Prototyping**: Rapid development of secure applications
-
-## 📈 Performance
-
-- **High Throughput**: Optimized for enterprise-scale operations
-- **Low Latency**: Sub-millisecond response times
-- **Scalable**: Horizontal scaling capabilities
-- **Monitoring**: Real-time performance metrics
-- **Analytics**: Detailed usage and performance insights
-
-## 🔍 API Endpoints
-
-### Core Generation
-- `POST /api/v2/generate/bytes` - Generate random bytes
-- `POST /api/v2/generate/key` - Create cryptographic keys
-- `POST /api/v2/generate/token` - Generate session tokens
-- `POST /api/v2/generate/uuid` - Create quantum UUIDs
-- `POST /api/v2/generate/password` - Generate secure passwords
-
-### Quantum Hardware Interface
-- `GET /api/v2/hardware/devices` - List connected quantum devices
-- `POST /api/v2/hardware/connect/{device_type}` - Connect to quantum hardware
-- `DELETE /api/v2/hardware/disconnect/{device_id}` - Disconnect quantum hardware
-- `POST /api/v2/hardware/calibrate/{device_id}` - Calibrate quantum device
-- `GET /api/v2/hardware/performance/{device_id}` - Get performance metrics
-- `GET /api/v2/hardware/benchmark` - Benchmark all devices
-
-### Blockchain Security
-- `POST /api/v2/blockchain/create-wallet` - Create blockchain wallets
-- `POST /api/v2/blockchain/simulate-attack` - Simulate quantum attacks
-- `GET /api/v2/blockchain/compare-blockchains` - Compare security levels
-
-### Post-Quantum Cryptography
-- `POST /api/v2/pqc/generate` - Generate PQC key pairs
-- `POST /api/v2/pqc/sign` - Sign with PQC algorithms
-- `POST /api/v2/pqc/verify` - Verify PQC signatures
-- `POST /api/v2/pqc/assess-threat` - Assess quantum threats
-
-### Monitoring & Analytics
-- `GET /api/v2/monitoring/metrics` - System metrics
-- `GET /api/v2/monitoring/analytics/overview` - Performance overview
-- `GET /api/v2/monitoring/analytics/api-performance` - API performance
-- `GET /api/v2/monitoring/analytics/quantum-performance` - Quantum performance
-- `GET /api/v2/monitoring/analytics/pqc-performance` - PQC performance
-
-## 🎯 Business Value
-
-### Competitive Advantages
-- **Future-Proof**: Ready for real quantum hardware integration
-- **Regulatory Compliant**: Meets NIST and government security standards
-- **Enterprise Scalable**: Built for high-volume production environments
-- **Cost Effective**: Start with simulation, upgrade to hardware as needed
-
-### ROI Justification
-- **Reduced Risk**: Mitigate quantum computing threats to cryptographic systems
-- **Compliance**: Meet emerging quantum-resistant security requirements
-- **Competitive Edge**: Early adoption of quantum-enhanced security
-- **Operational Efficiency**: Automated key generation and management
-
-## 📚 Documentation
-
-- **[Production Guide](PRODUCTION.md)** - Complete production deployment instructions
-- **[Commands Guide](commands.md)** - Complete command reference
-- **[Directory Guide](directory-guide.md)** - Project structure explanation
-- **[API Documentation](http://localhost:8000/docs)** - Interactive API docs
-- **[Python SDK](client_sdk/python/README.md)** - Python client SDK
-
-## 🤝 Contributing
-
-We welcome contributions! Please see our contributing guidelines and code of conduct.
-
-## 📄 License
-
-This project is licensed under the MIT License - see the LICENSE file for details.
-
-## 🆘 Support
-
-- **Documentation**: Check the guides in this repository
-- **Issues**: Report bugs and request features via GitHub Issues
-- **Community**: Join our discussions and get help
-
-## 🔮 Future Roadmap
-
-- **Quantum Hardware Integration**: Direct integration with real quantum devices (ID Quantique, QuintessenceLabs, etc.)
-- **Advanced Analytics**: Enhanced security metrics and quantum entropy validation
-- **Mobile SDKs**: iOS and Android development kits
-- **Additional PQC Algorithms**: More NIST-standardized algorithms
-- **Enhanced Monitoring**: Advanced observability features
-- **Quantum Key Distribution (QKD) Integration**: Full quantum security stack
-
----
-
-**Built with ❤️ for the quantum future**
-
-[Learn More About Quantum Security](https://www.idquantique.com/quantum-random-number-generation/) | 
-[Post-Quantum Cryptography Standards](https://csrc.nist.gov/projects/post-quantum-cryptography) |
-[Commercial Quantum Solutions](https://quintessencelabs.com/)

app/api/v2/endpoints/generate.py

@@ -7,6 +7,7 @@ from fastapi import APIRouter, HTTPException, Depends, BackgroundTasks
 from typing import List
 import asyncio
 from datetime import datetime, timedelta
+import time
 
 from app.quantum.qrng import get_quantum_rng
 from app.api.v2.models.requests import (
@@ -28,6 +29,7 @@ from app.api.v2.models.responses import (
 )
 from app.utils.logging import logger, log_quantum_generation
 from app.config import settings
+from app.monitoring import QRNGMetrics
 
 
 router = APIRouter()
@@ -37,24 +39,34 @@ router = APIRouter()
 async def generate_bytes(request: GenerateBytesRequest) -> GenerateBytesResponse:
     """
     Generate quantum random bytes
-    
+
     This endpoint generates cryptographically secure random bytes using quantum superposition.
     Each byte is generated through quantum measurement of qubits in superposition state.
-    
+
     - **length**: Number of bytes to generate (1-1024, enterprise up to 10240)
     - **format**: Output format (hex, base64, array, raw)
     - **quantum_bits**: Number of qubits to use (1-16, higher = more entropy)
     """
     try:
         qrng = get_quantum_rng()
-        
+        start_time = time.time()
+
         # Generate quantum random bytes
         result = await qrng.generate_bytes(
             request.length,
             request.quantum_bits,
             request.format.value
         )
-        
+
+        # Record metrics
+        duration = time.time() - start_time
+        QRNGMetrics.record_bytes_generated(
+            result.quantum_backend,
+            result.format,
+            result.length
+        )
+        QRNGMetrics.record_generation_duration(result.quantum_backend, duration)
+
         # Log generation
         log_quantum_generation(
             bytes_generated=result.length,
@@ -62,7 +74,7 @@ async def generate_bytes(request: GenerateBytesRequest) -> GenerateBytesResponse
             backend=result.quantum_backend,
             time_ms=result.generation_time_ms
         )
-        
+
         return GenerateBytesResponse(
             status=ResponseStatus.SUCCESS,
             request_id=result.request_id,

app/api/v2/endpoints/monitoring.py

@@ -1,180 +1,458 @@
 """
-QCrypt RNG API - Monitoring and Analytics Endpoints
-Endpoints for metrics, monitoring, and analytics
+QCrypt RNG API - Monitoring Endpoints
+
+Provides Prometheus metrics and system health endpoints.
 """
 
-from fastapi import APIRouter
-from typing import Dict, Any
-from datetime import datetime
+from fastapi import APIRouter, Response, Request, HTTPException
+from typing import Dict, Any, Optional
+import time
+import psutil
+import os
 
-from app.utils.monitoring import analytics_service
 from app.api.v2.models.responses import BaseResponse, ResponseStatus
 from app.utils.logging import logger
+from app.monitoring import (
+    get_metrics,
+    get_metrics_content_type,
+    QRNGMetrics,
+    HardwareMetrics,
+    EntropyMetrics,
+    APIMetrics,
+    setup_system_info,
+    OracleMetrics
+)
+from app.quantum.qrng import get_quantum_rng
+from app.quantum.hardware_interface import get_quantum_hardware_manager
+from app.config import settings
 
 router = APIRouter()
 
 
-@router.get("/metrics", response_model=BaseResponse)
-async def get_metrics():
+@router.get("/metrics")
+async def prometheus_metrics():
     """
-    Get system metrics and performance data
-    
-    Returns various system metrics including:
-    - API performance metrics
-    - Quantum generation statistics
-    - Post-quantum cryptography operations
-    - System resource usage
+    Prometheus metrics endpoint
+
+    Returns metrics in Prometheus exposition format.
+    Scrape this endpoint with Prometheus to collect metrics.
+
+    **Metrics included:**
+    - Oracle fulfillment (requests, duration, transactions)
+    - PQC operations (key gen, sign, verify, KEM)
+    - QRNG generation (bytes, duration, entropy)
+    - Hardware status (device status, temperature, error rate)
+    - Entropy quality (Shannon, min-entropy, chi-square)
+    - API performance (requests, duration, sizes)
+    - System info (version, environment, backend)
     """
+    # Update dynamic metrics before returning
     try:
-        # Get API performance summary
-        api_summary = analytics_service.get_api_performance_summary(window_minutes=60)
-        
-        # Get quantum performance summary
-        quantum_summary = analytics_service.get_quantum_performance_summary(window_minutes=60)
-        
-        # Get PQC performance summary
-        pqc_summary = analytics_service.get_pqc_performance_summary(window_minutes=60)
-        
-        return BaseResponse(
-            status=ResponseStatus.SUCCESS,
-            request_id=f"metrics_{int(datetime.utcnow().timestamp()*1000000)}",
-            data={
-                "api_performance": api_summary,
-                "quantum_performance": quantum_summary,
-                "pqc_performance": pqc_summary,
-                "timestamp": datetime.utcnow().isoformat()
-            },
-            metadata={
-                "metric_collection_enabled": True,
-                "data_retention_hours": 24,
-                "aggregation_window_minutes": 60
-            }
+        # Update QRNG metrics
+        qrng = get_quantum_rng()
+        stats = qrng.get_statistics()
+        QRNGMetrics.update_entropy_bits(
+            stats.get('backend', 'simulator'),
+            len(qrng.entropy_pool)
         )
+
+        # Update entropy quality metrics
+        entropy_analysis = qrng.analyze_entropy()
+        EntropyMetrics.update_shannon_entropy(
+            'qrng_pool',
+            entropy_analysis.shannon_entropy
+        )
+        EntropyMetrics.update_min_entropy(
+            'qrng_pool',
+            entropy_analysis.min_entropy
+        )
+        EntropyMetrics.update_quality_status(
+            'qrng_pool',
+            entropy_analysis.health_status in ['excellent', 'good']
+        )
+
+        # Update hardware metrics
+        hw_manager = get_quantum_hardware_manager()
+        if hw_manager.devices:
+            statuses = await hw_manager.get_device_status()
+            for device_id, status in statuses.items():
+                vendor = status.get('vendor', 'unknown')
+                device_type = status.get('device_type', 'unknown')
+                is_operational = status.get('status') == 'operational'
+                
+                HardwareMetrics.update_device_status(
+                    device_id, device_type, vendor,
+                    1 if is_operational else 0
+                )
+                
+                if 'generation_rate_bps' in status:
+                    HardwareMetrics.update_generation_rate(
+                        device_id, device_type,
+                        status['generation_rate_bps']
+                    )
+                
+                if 'error_rate' in status:
+                    HardwareMetrics.update_error_rate(
+                        device_id, device_type,
+                        status['error_rate']
+                    )
+                
+                if 'temperature' in status and status['temperature'] != 'N/A':
+                    HardwareMetrics.update_temperature(
+                        device_id, device_type,
+                        float(status['temperature'])
+                    )
+                
+                if 'uptime_seconds' in status:
+                    HardwareMetrics.update_uptime(
+                        device_id, device_type,
+                        status['uptime_seconds']
+                    )
+
     except Exception as e:
-        logger.error(f"Metrics retrieval error: {str(e)}")
-        raise
+        logger.error(f"Error updating metrics: {e}")
+
+    # Return metrics in Prometheus format
+    return Response(
+        content=get_metrics(),
+        media_type=get_metrics_content_type()
+    )
 
 
-@router.get("/analytics/overview", response_model=BaseResponse)
-async def get_analytics_overview():
+@router.get("/health/detailed", response_model=BaseResponse)
+async def detailed_health_check():
     """
-    Get analytics overview with key performance indicators
-    
-    Provides a high-level view of system performance and usage
+    Detailed health check with component status
+
+    Returns detailed information about all system components:
+    - API server status
+    - Quantum backend status
+    - Hardware devices
+    - Entropy quality
+    - Database connection (if configured)
+    - Redis connection (if configured)
     """
+    import sys
+    
+    health_data = {
+        "status": "healthy",
+        "timestamp": time.time(),
+        "version": settings.app_version,
+        "environment": settings.environment,
+        "components": {}
+    }
+
+    # API Server
+    health_data["components"]["api"] = {
+        "status": "healthy",
+        "uptime_seconds": time.time() - start_time if (start_time := getattr(detailed_health_check, 'start_time', time.time())) else 0
+    }
+    detailed_health_check.start_time = start_time
+
+    # Quantum Backend
     try:
-        # Get all summaries
-        api_summary = analytics_service.get_api_performance_summary(window_minutes=60)
-        quantum_summary = analytics_service.get_quantum_performance_summary(window_minutes=60)
-        pqc_summary = analytics_service.get_pqc_performance_summary(window_minutes=60)
+        qrng = get_quantum_rng()
+        stats = qrng.get_statistics()
+        health_data["components"]["quantum_backend"] = {
+            "status": "healthy",
+            "backend": stats.get("backend", "unknown"),
+            "total_bytes_generated": stats.get("total_bytes_generated", 0),
+            "entropy_pool_size": len(qrng.entropy_pool)
+        }
+    except Exception as e:
+        health_data["components"]["quantum_backend"] = {
+            "status": "unhealthy",
+            "error": str(e)
+        }
+        health_data["status"] = "degraded"
+
+    # Hardware Devices
+    try:
+        hw_manager = get_quantum_hardware_manager()
+        devices = hw_manager.get_available_devices()
+        device_statuses = []
         
-        # Calculate KPIs
-        total_calls = api_summary["call_volume"].get("GET_success", 0) + api_summary["call_volume"].get("POST_success", 0)
-        avg_response_time = api_summary["response_time"].get("avg", 0) * 1000  # Convert to ms
-        success_rate = (api_summary["call_volume"].get("GET_success", 0) + api_summary["call_volume"].get("POST_success", 0)) / max(
-            total_calls + api_summary["call_volume"].get("GET_failure", 0) + api_summary["call_volume"].get("POST_failure", 0), 1
-        )
+        if devices:
+            statuses = await hw_manager.get_device_status()
+            for device_id in devices:
+                status = statuses.get(device_id, {})
+                device_statuses.append({
+                    "device_id": device_id,
+                    "status": status.get("status", "unknown"),
+                    "type": status.get("device_type", "unknown")
+                })
         
-        kpis = {
-            "total_api_calls": total_calls,
-            "avg_response_time_ms": round(avg_response_time, 2),
-            "success_rate_percent": round(success_rate * 100, 2),
-            "quantum_generations": quantum_summary["summary"]["total_generations"],
-            "avg_quantum_generation_time_ms": round(quantum_summary["summary"]["avg_generation_time_ms"], 2),
-            "pqc_operations": pqc_summary["summary"]["total_operations"],
-            "avg_pqc_operation_time_ms": round(pqc_summary["summary"]["avg_operation_time_ms"], 2)
+        health_data["components"]["hardware"] = {
+            "status": "healthy" if devices else "no_devices",
+            "device_count": len(devices),
+            "devices": device_statuses
         }
-        
-        return BaseResponse(
-            status=ResponseStatus.SUCCESS,
-            request_id=f"analytics_{int(datetime.utcnow().timestamp()*1000000)}",
-            data={
-                "kpis": kpis,
-                "api_performance": api_summary,
-                "quantum_performance": quantum_summary,
-                "pqc_performance": pqc_summary,
-                "timestamp": datetime.utcnow().isoformat()
-            },
-            metadata={
-                "analytics_enabled": True,
-                "reporting_period": "last_60_minutes"
-            }
-        )
     except Exception as e:
-        logger.error(f"Analytics overview error: {str(e)}")
-        raise
+        health_data["components"]["hardware"] = {
+            "status": "unhealthy",
+            "error": str(e)
+        }
 
+    # Entropy Quality
+    try:
+        qrng = get_quantum_rng()
+        analysis = qrng.analyze_entropy()
+        health_data["components"]["entropy"] = {
+            "status": "healthy" if analysis.health_status in ["excellent", "good"] else "degraded",
+            "shannon_entropy": analysis.shannon_entropy,
+            "min_entropy": analysis.min_entropy,
+            "health_status": analysis.health_status
+        }
+        if analysis.health_status == "poor":
+            health_data["status"] = "degraded"
+    except Exception as e:
+        health_data["components"]["entropy"] = {
+            "status": "unknown",
+            "error": str(e)
+        }
 
-@router.get("/analytics/api-performance", response_model=BaseResponse)
-async def get_api_performance_analytics(minutes: int = 60):
-    """
-    Get detailed API performance analytics
-    
-    Args:
-        minutes: Time window in minutes to analyze (default: 60)
-    """
+    # System Resources
     try:
-        summary = analytics_service.get_api_performance_summary(window_minutes=minutes)
-        
-        return BaseResponse(
-            status=ResponseStatus.SUCCESS,
-            request_id=f"api_analytics_{int(datetime.utcnow().timestamp()*1000000)}",
-            data=summary,
-            metadata={
-                "analytics_type": "api_performance",
-                "time_window_minutes": minutes
-            }
-        )
+        cpu_percent = psutil.cpu_percent(interval=0.1)
+        memory = psutil.virtual_memory()
+        health_data["components"]["system"] = {
+            "status": "healthy" if cpu_percent < 90 and memory.percent < 90 else "warning",
+            "cpu_percent": cpu_percent,
+            "memory_percent": memory.percent,
+            "memory_available_mb": memory.available // (1024 * 1024)
+        }
+        if cpu_percent >= 90 or memory.percent >= 90:
+            health_data["status"] = "degraded"
     except Exception as e:
-        logger.error(f"API performance analytics error: {str(e)}")
-        raise
+        health_data["components"]["system"] = {
+            "status": "unknown",
+            "error": str(e)
+        }
 
+    # Determine overall status
+    component_statuses = [
+        c.get("status") for c in health_data["components"].values()
+    ]
+    if "unhealthy" in component_statuses:
+        health_data["status"] = "unhealthy"
+    elif "degraded" in component_statuses or "warning" in component_statuses:
+        health_data["status"] = "degraded"
 
-@router.get("/analytics/quantum-performance", response_model=BaseResponse)
-async def get_quantum_performance_analytics(minutes: int = 60):
+    return BaseResponse(
+        status=ResponseStatus.SUCCESS if health_data["status"] == "healthy" else ResponseStatus.ERROR,
+        request_id=f"health_{int(time.time()*1000000)}",
+        data=health_data
+    )
+
+
+@router.get("/status", response_model=BaseResponse)
+async def system_status():
     """
-    Get detailed quantum performance analytics
+    Quick system status check
+
+    Returns a lightweight status response for load balancers
+    and orchestration systems.
+    """
+    return BaseResponse(
+        status=ResponseStatus.SUCCESS,
+        request_id=f"status_{int(time.time()*1000000)}",
+        data={
+            "status": "operational",
+            "version": settings.app_version,
+            "environment": settings.environment,
+            "timestamp": time.time()
+        }
+    )
+
+
+@router.get("/metrics/summary", response_model=BaseResponse)
+async def metrics_summary():
+    """
+    Human-readable metrics summary
+
+    Returns a summary of key metrics in JSON format.
+    """
+    qrng = get_quantum_rng()
+    stats = qrng.get_statistics()
+    entropy_analysis = qrng.analyze_entropy()
     
-    Args:
-        minutes: Time window in minutes to analyze (default: 60)
+    hw_manager = get_quantum_hardware_manager()
+    devices = hw_manager.get_available_devices()
+
+    summary = {
+        "quantum_generation": {
+            "total_bytes": stats.get("total_bytes_generated", 0),
+            "total_generations": stats.get("total_generations", 0),
+            "avg_generation_time_ms": stats.get("average_generation_time_ms", 0),
+            "backend": stats.get("backend", "simulator")
+        },
+        "entropy": {
+            "pool_size": len(qrng.entropy_pool),
+            "shannon_entropy": entropy_analysis.shannon_entropy,
+            "min_entropy": entropy_analysis.min_entropy,
+            "health_status": entropy_analysis.health_status
+        },
+        "hardware": {
+            "device_count": len(devices),
+            "devices": devices
+        },
+        "system": {
+            "cpu_percent": psutil.cpu_percent(interval=0.1),
+            "memory_percent": psutil.virtual_memory().percent,
+            "uptime_seconds": time.time() - getattr(system_status, 'start_time', time.time())
+        }
+    }
+    system_status.start_time = getattr(system_status, 'start_time', time.time())
+
+    return BaseResponse(
+        status=ResponseStatus.SUCCESS,
+        request_id=f"metrics_summary_{int(time.time()*1000000)}",
+        data=summary
+    )
+
+
+@router.post("/metrics/record/pqc")
+async def record_pqc_metric(
+    algorithm: str,
+    operation: str,
+    status: str = "success",
+    duration_seconds: float = 0,
+    key_size_bytes: int = 0
+):
+    """
+    Record a PQC operation metric
+
+    Allows external components to record PQC metrics.
+    """
+    PQCMetrics.record_operation(algorithm, operation, status, duration_seconds)
+    
+    if key_size_bytes > 0:
+        key_type = "public" if "public" in operation.lower() else "private"
+        PQCMetrics.record_key_size(algorithm, key_type, key_size_bytes)
+
+    return BaseResponse(
+        status=ResponseStatus.SUCCESS,
+        request_id=f"metric_{int(time.time()*1000000)}",
+        data={"recorded": True}
+    )
+
+
+@router.post("/metrics/record/oracle")
+async def record_oracle_metric(
+    chain: str,
+    event_type: str,
+    status: str = "success",
+    duration_seconds: float = 0,
+    gas_used: int = 0
+):
+    """
+    Record an oracle event metric
+
+    Allows external components to record oracle metrics.
+    """
+    if event_type == "request":
+        OracleMetrics.record_request(chain, status)
+    elif event_type == "fulfillment":
+        OracleMetrics.record_fulfillment(chain, status, duration_seconds)
+    elif event_type == "commit":
+        OracleMetrics.record_commit(chain, duration_seconds)
+    elif event_type == "reveal":
+        OracleMetrics.record_reveal(chain, duration_seconds)
+    elif event_type == "transaction":
+        OracleMetrics.record_transaction(chain, "fulfillment", status, gas_used)
+
+    return BaseResponse(
+        status=ResponseStatus.SUCCESS,
+        request_id=f"metric_{int(time.time()*1000000)}",
+        data={"recorded": True}
+    )
+
+
+@router.get("/entropy/quality", response_model=BaseResponse)
+async def entropy_quality_checks(device_id: Optional[str] = None):
+    """
+    Run entropy quality checks on quantum hardware
+
+    Performs NIST SP 800-90B entropy estimation and statistical tests:
+    - Shannon entropy
+    - Min-entropy
+    - Chi-square uniformity test
+    - Overall quality assessment
+
+    **Parameters:**
+    - `device_id`: Optional device ID to test. Uses active device if not specified.
+
+    **Quality Thresholds:**
+    - Shannon entropy: > 7.9 bits/byte (excellent), > 7.5 (good), < 7.0 (poor)
+    - Min-entropy: > 7.0 bits/byte (acceptable)
+    - Chi-square: < 293.25 (pass uniformity test)
     """
     try:
-        summary = analytics_service.get_quantum_performance_summary(window_minutes=minutes)
-        
+        hw_manager = get_quantum_hardware_manager()
+
+        # Run entropy quality checks
+        quality_result = await hw_manager.run_entropy_quality_checks(device_id)
+
+        # Update entropy metrics
+        EntropyMetrics.update_shannon_entropy(
+            quality_result.get('device_id', 'hardware'),
+            quality_result.get('shannon_entropy', 0)
+        )
+        EntropyMetrics.update_min_entropy(
+            quality_result.get('device_id', 'hardware'),
+            quality_result.get('min_entropy', 0)
+        )
+        EntropyMetrics.update_quality_status(
+            quality_result.get('device_id', 'hardware'),
+            quality_result.get('overall_quality') == 'GOOD'
+        )
+
         return BaseResponse(
             status=ResponseStatus.SUCCESS,
-            request_id=f"quantum_analytics_{int(datetime.utcnow().timestamp()*1000000)}",
-            data=summary,
+            request_id=f"entropy_quality_{int(time.time()*1000000)}",
+            data=quality_result,
             metadata={
-                "analytics_type": "quantum_performance",
-                "time_window_minutes": minutes
+                "metrics_updated": True,
+                "prometheus_endpoint": "/api/v2/monitoring/metrics"
             }
         )
+    except ValueError as e:
+        logger.error(f"Entropy quality check error: {str(e)}")
+        raise HTTPException(status_code=400, detail=str(e))
     except Exception as e:
-        logger.error(f"Quantum performance analytics error: {str(e)}")
-        raise
+        logger.error(f"Entropy quality check error: {str(e)}", exc_info=True)
+        raise HTTPException(status_code=500, detail=str(e))
 
 
-@router.get("/analytics/pqc-performance", response_model=BaseResponse)
-async def get_pqc_performance_analytics(minutes: int = 60):
+@router.get("/entropy/history", response_model=BaseResponse)
+async def entropy_quality_history(limit: int = 100):
     """
-    Get detailed post-quantum cryptography performance analytics
-    
-    Args:
-        minutes: Time window in minutes to analyze (default: 60)
+    Get recent entropy quality check history
+
+    Returns the last N entropy quality check results.
     """
     try:
-        summary = analytics_service.get_pqc_performance_summary(window_minutes=minutes)
-        
+        # For now, return current entropy analysis from QRNG
+        qrng = get_quantum_rng()
+        entropy_analysis = qrng.analyze_entropy()
+
         return BaseResponse(
             status=ResponseStatus.SUCCESS,
-            request_id=f"pqc_analytics_{int(datetime.utcnow().timestamp()*1000000)}",
-            data=summary,
-            metadata={
-                "analytics_type": "pqc_performance",
-                "time_window_minutes": minutes
+            request_id=f"entropy_history_{int(time.time()*1000000)}",
+            data={
+                "current": {
+                    "shannon_entropy": entropy_analysis.shannon_entropy,
+                    "min_entropy": entropy_analysis.min_entropy,
+                    "chi_square_p_value": getattr(entropy_analysis, 'chi_square_p_value', None),
+                    "autocorrelation": getattr(entropy_analysis, 'autocorrelation', None),
+                    "bit_balance": getattr(entropy_analysis, 'bit_balance', None),
+                    "health_status": entropy_analysis.health_status,
+                    "pool_size": len(qrng.entropy_pool)
+                },
+                "history": [],
+                "note": "Historical data requires persistent storage configuration"
             }
         )
     except Exception as e:
-        logger.error(f"PQC performance analytics error: {str(e)}")
-        raise
+        logger.error(f"Entropy history error: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))

app/api/v2/endpoints/oracle.py

@@ -3,7 +3,7 @@ QCrypt RNG API - Quantum Randomness Oracle Endpoint
 API endpoint for interacting with the quantum randomness oracle for blockchain applications
 """
 
-from fastapi import APIRouter, HTTPException, BackgroundTasks
+from fastapi import APIRouter, HTTPException, BackgroundTasks, Form
 from typing import Dict, Any, Optional
 from pydantic import BaseModel
 import time
@@ -14,6 +14,9 @@ from app.quantum.hardware_interface import get_quantum_hardware_manager
 from app.quantum.commitment import compute_commitment_hex
 from app.api.v2.models.responses import BaseResponse, ResponseStatus
 from app.utils.logging import logger
+from app.blockchain.oracle_service import get_oracle_fulfillment_service, FulfillmentStatus
+from app.blockchain.base import ChainConfig
+from app.monitoring import OracleMetrics, QRNGMetrics
 
 router = APIRouter()
 
@@ -383,4 +386,300 @@ async def batch_request_quantum_randomness(request: BatchOracleRequest):
         )
     except Exception as e:
         logger.error(f"Batch oracle request error: {e}", exc_info=True)
-        raise HTTPException(status_code=500, detail=f"Batch request failed: {e}")
+        raise HTTPException(status_code=500, detail=f"Batch request failed: {e}")
+
+
+# ============================================================================
+# On-Chain Fulfillment Endpoints
+# ============================================================================
+
+@router.post("/fulfillment/configure-chain", response_model=BaseResponse)
+async def configure_blockchain_chain(
+    chain: str = Form(..., description="Blockchain name: ethereum, polygon, bsc, avalanche, fantom"),
+    rpc_url: str = Form(..., description="RPC endpoint URL"),
+    private_key: str = Form(..., description="Oracle operator private key"),
+    explorer_url: str = Form(..., description="Block explorer URL"),
+    chain_id: int = Form(..., description="Chain ID"),
+    currency_symbol: str = Form(..., description="Native currency symbol"),
+    gas_price_gwei: Optional[int] = Form(None, description="Gas price in gwei"),
+    confirmations_required: int = Form(3, description="Number of confirmations to wait")
+):
+    """
+    Configure a blockchain chain for oracle fulfillment
+
+    Sets up the chain adapter with the provided configuration.
+    The private key is used to sign transactions for commit/reveal operations.
+
+    **Security Note:** Store private keys securely. In production, use a hardware wallet
+    or secure key management service (AWS KMS, Azure Key Vault, etc.).
+    """
+    try:
+        service = get_oracle_fulfillment_service()
+
+        config = ChainConfig(
+            rpc_url=rpc_url,
+            chain_id=chain_id,
+            explorer_url=explorer_url,
+            currency_symbol=currency_symbol,
+            private_key=private_key,
+            gas_price_gwei=gas_price_gwei,
+            confirmations_required=confirmations_required
+        )
+
+        success = service.configure_chain(chain, config)
+
+        if not success:
+            raise HTTPException(status_code=400, detail=f"Failed to configure chain: {chain}")
+
+        return BaseResponse(
+            status=ResponseStatus.SUCCESS,
+            request_id=f"config_{int(time.time()*1000000)}",
+            data={
+                "chain": chain,
+                "configured": True,
+                "rpc_url": rpc_url,
+                "chain_id": chain_id,
+                "explorer_url": explorer_url
+            },
+            metadata={
+                "message": f"Successfully configured {chain} chain adapter",
+                "warning": "Ensure private key is stored securely and never committed to version control"
+            }
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Chain configuration error: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/fulfillment/request", response_model=BaseResponse)
+async def create_onchain_oracle_request(
+    chain: str = Form(..., description="Target blockchain"),
+    contract_address: str = Form(..., description="Oracle contract address"),
+    num_bytes: int = Form(32, description="Number of random bytes"),
+    num_qubits: int = Form(16, description="Number of qubits"),
+    async_fulfillment: bool = Form(True, description="Process fulfillment asynchronously")
+):
+    """
+    Create an oracle request with on-chain fulfillment
+
+    This endpoint creates a new oracle request and optionally triggers
+    asynchronous fulfillment (commit + reveal) on the specified blockchain.
+
+    **Process:**
+    1. Create oracle request
+    2. Generate quantum randomness
+    3. Create commitment (keccak256)
+    4. Submit commit transaction
+    5. Wait for confirmation
+    6. Submit reveal transaction
+    7. Wait for confirmation
+
+    **Fulfillment Status:**
+    - 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
+    """
+    try:
+        service = get_oracle_fulfillment_service()
+        start_time = time.time()
+
+        # Create request
+        request = await service.create_request(
+            chain=chain,
+            contract_address=contract_address,
+            num_bytes=num_bytes,
+            num_qubits=num_qubits
+        )
+
+        # Record request metric
+        OracleMetrics.record_request(chain, "success")
+
+        if async_fulfillment:
+            # Process asynchronously (non-blocking)
+            asyncio.create_task(service.fulfill_request(request.request_id))
+            fulfillment_status = "processing_async"
+        else:
+            # Process synchronously (blocking)
+            success = await service.fulfill_request(request.request_id)
+            fulfillment_status = "completed" if success else "failed"
+            
+            # Record fulfillment metric
+            duration = time.time() - start_time
+            OracleMetrics.record_fulfillment(chain, fulfillment_status, duration)
+
+        status_data = service.get_request_status(request.request_id)
+
+        return BaseResponse(
+            status=ResponseStatus.SUCCESS,
+            request_id=f"onchain_{int(time.time()*1000000)}",
+            data={
+                "request_id": request.request_id,
+                "chain": chain,
+                "contract_address": contract_address,
+                "fulfillment_status": fulfillment_status,
+                "status": status_data
+            },
+            metadata={
+                "message": f"Oracle request created for {chain}",
+                "async": async_fulfillment,
+                "next_step": "Use /oracle/fulfillment/status/{request_id} to check status" if async_fulfillment else None
+            }
+        )
+    except Exception as e:
+        logger.error(f"On-chain request error: {str(e)}")
+        # Record error metric
+        OracleMetrics.record_request(chain, "error")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/fulfillment/status/{request_id}", response_model=BaseResponse)
+async def get_fulfillment_status(request_id: str):
+    """
+    Get the status of an on-chain oracle request
+
+    Returns detailed information about the fulfillment process including:
+    - Current status
+    - Commitment hash
+    - Randomness value (after reveal)
+    - Transaction hashes
+    - Explorer URLs
+    """
+    try:
+        service = get_oracle_fulfillment_service()
+
+        status = service.get_request_status(request_id)
+
+        if status is None:
+            raise HTTPException(status_code=404, detail=f"Request not found: {request_id}")
+
+        return BaseResponse(
+            status=ResponseStatus.SUCCESS,
+            request_id=request_id,
+            data=status,
+            metadata={
+                "chain_info": await service.get_chain_info(status["chain"]) if status["chain"] else None
+            }
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Fulfillment status error: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/fulfillment/requests", response_model=BaseResponse)
+async def list_all_fulfillment_requests():
+    """
+    List all oracle fulfillment requests
+
+    Returns a list of all oracle requests with their current status.
+    """
+    try:
+        service = get_oracle_fulfillment_service()
+
+        requests = service.get_all_requests()
+
+        return BaseResponse(
+            status=ResponseStatus.SUCCESS,
+            request_id=f"list_{int(time.time()*1000000)}",
+            data={
+                "requests": requests,
+                "total_count": len(requests),
+                "by_status": {
+                    status.value: sum(1 for r in requests if r["status"] == status.value)
+                    for status in FulfillmentStatus
+                }
+            },
+            metadata={
+                "supported_chains": service.get_supported_chains()
+            }
+        )
+    except Exception as e:
+        logger.error(f"List requests error: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/fulfillment/chains", response_model=BaseResponse)
+async def list_supported_chains():
+    """
+    List all supported blockchain networks
+
+    Returns information about each supported chain including:
+    - Chain ID
+    - Explorer URL
+    - RPC endpoint
+    - Supported features
+    """
+    try:
+        service = get_oracle_fulfillment_service()
+
+        chains = service.get_supported_chains()
+
+        return BaseResponse(
+            status=ResponseStatus.SUCCESS,
+            request_id=f"chains_{int(time.time()*1000000)}",
+            data=chains,
+            metadata={
+                "total_chains": len(chains),
+                "message": "Configure chains using /oracle/fulfillment/configure-chain"
+            }
+        )
+    except Exception as e:
+        logger.error(f"List chains error: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/fulfillment/retry/{request_id}", response_model=BaseResponse)
+async def retry_fulfillment(request_id: str):
+    """
+    Retry fulfillment of a failed oracle request
+
+    If a request failed during commit or reveal, this endpoint
+    attempts to retry the fulfillment process.
+
+    Note: Only requests in FAILED status can be retried.
+    """
+    try:
+        service = get_oracle_fulfillment_service()
+
+        status = service.get_request_status(request_id)
+        if status is None:
+            raise HTTPException(status_code=404, detail=f"Request not found: {request_id}")
+
+        if status["status"] != "failed":
+            raise HTTPException(
+                status_code=400,
+                detail=f"Cannot retry request in {status['status']} status. Only failed requests can be retried."
+            )
+
+        # Reset status and retry
+        request = service.requests[request_id]
+        request.status = FulfillmentStatus.PENDING
+        request.error = None
+
+        # Retry fulfillment
+        success = await service.fulfill_request(request_id)
+
+        return BaseResponse(
+            status=ResponseStatus.SUCCESS if success else ResponseStatus.ERROR,
+            request_id=f"retry_{int(time.time()*1000000)}",
+            data={
+                "request_id": request_id,
+                "retry_successful": success,
+                "new_status": service.get_request_status(request_id)
+            },
+            metadata={
+                "message": "Fulfillment retry completed"
+            }
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Retry fulfillment error: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))

app/api/v2/endpoints/pqc_endpoints.py

@@ -14,6 +14,7 @@ from app.quantum.pqc import get_pqc
 from app.api.v2.models.responses import BaseResponse, ResponseStatus
 from app.utils.logging import logger
 from app.config import settings
+from app.monitoring import PQCMetrics
 
 router = APIRouter()
 
@@ -49,7 +50,7 @@ async def generate_pqc_keypair(
     try:
         # Track usage for enterprise features
         start_time = time.time()
-        
+
         pqc = get_pqc()
 
         # Support both 'format' and 'encoding' for compatibility
@@ -73,6 +74,11 @@ async def generate_pqc_keypair(
             # Calculate execution time
             execution_time = time.time() - start_time
 
+            # Record metrics
+            PQCMetrics.record_operation(keypair.algorithm, "generate_keypair", "success", execution_time)
+            PQCMetrics.record_key_size(keypair.algorithm, "public", len(keypair.public_key))
+            PQCMetrics.record_key_size(keypair.algorithm, "private", len(keypair.private_key))
+
             return BaseResponse(
                 status=ResponseStatus.SUCCESS,
                 request_id=f"pqc_gen_{int(time.time()*1000000)}",
@@ -117,6 +123,11 @@ async def generate_pqc_keypair(
             # Calculate execution time
             execution_time = time.time() - start_time
 
+            # Record metrics
+            PQCMetrics.record_operation(algo_upper, "generate_keypair", "success", execution_time)
+            PQCMetrics.record_key_size(algo_upper, "public", len(public_key))
+            PQCMetrics.record_key_size(algo_upper, "private", len(private_key))
+
             return BaseResponse(
                 status=ResponseStatus.SUCCESS,
                 request_id=f"pqc_gen_{int(time.time()*1000000)}",
@@ -148,6 +159,9 @@ async def generate_pqc_keypair(
 
     except Exception as e:
         logger.error(f"PQC key generation error: {str(e)}")
+        # Record error metric
+        algo_upper = algorithm.upper().replace("-", "").replace("_", "")
+        PQCMetrics.record_operation(algo_upper, "generate_keypair", "error", 0)
         raise HTTPException(status_code=500, detail=str(e))
 
 
@@ -169,7 +183,7 @@ async def sign_with_pqc(
     """
     try:
         start_time = time.time()
-        
+
         pqc = get_pqc()
 
         # Decode private key
@@ -193,6 +207,10 @@ async def sign_with_pqc(
         # Calculate execution time
         execution_time = time.time() - start_time
 
+        # Record metrics
+        PQCMetrics.record_operation(algorithm, "sign", "success", execution_time)
+        PQCMetrics.record_signature_size(algorithm, len(signature))
+
         return BaseResponse(
             status=ResponseStatus.SUCCESS,
             request_id=f"pqc_sign_{int(time.time()*1000000)}",
@@ -215,6 +233,7 @@ async def sign_with_pqc(
         )
     except Exception as e:
         logger.error(f"PQC signing error: {str(e)}")
+        PQCMetrics.record_operation(algorithm, "sign", "error", 0)
         raise HTTPException(status_code=500, detail=str(e))
 
 
@@ -236,7 +255,7 @@ async def verify_pqc_signature(
     """
     try:
         start_time = time.time()
-        
+
         pqc = get_pqc()
 
         # Decode inputs
@@ -262,6 +281,10 @@ async def verify_pqc_signature(
         # Calculate execution time
         execution_time = time.time() - start_time
 
+        # Record metrics
+        status_str = "success" if is_valid else "error"
+        PQCMetrics.record_operation(algorithm, "verify", status_str, execution_time)
+
         return BaseResponse(
             status=ResponseStatus.SUCCESS if is_valid else ResponseStatus.ERROR,
             request_id=f"pqc_verify_{int(time.time()*1000000)}",
@@ -285,6 +308,7 @@ async def verify_pqc_signature(
         )
     except Exception as e:
         logger.error(f"PQC verification error: {str(e)}")
+        PQCMetrics.record_operation(algorithm, "verify", "error", 0)
         raise HTTPException(status_code=400, detail="Verification failed")
 
 
@@ -404,7 +428,7 @@ async def assess_quantum_threat_alias(
     This is an alias for /assess-threat endpoint for backward compatibility.
     """
     start_time = time.time()
-    
+
     pqc = get_pqc()
     threat = pqc.assess_quantum_threat(algorithm)
 
@@ -429,4 +453,641 @@ async def assess_quantum_threat_alias(
             "execution_time_ms": round(execution_time * 1000, 2),
             "production_ready": True
         }
-    )
+    )
+
+
+# ============================================================================
+# Kyber KEM Endpoints
+# ============================================================================
+
+@router.post("/kem/generate", response_model=BaseResponse)
+async def generate_kyber_keypair(
+    algorithm: str = Form("KYBER768", description="Algorithm: KYBER512/768/1024"),
+    encoding: str = Form("base64", description="Output encoding: base64 or hex"),
+    format: Optional[str] = Form(None, description="Alias for encoding (compatibility)")
+):
+    """
+    Generate a Kyber key pair for key encapsulation
+
+    Kyber is a NIST-standardized Key Encapsulation Mechanism (KEM) designed
+    for secure key exchange that is resistant to quantum computer attacks.
+
+    **KYBER Variants:**
+    - KYBER512: NIST Level 1 (fastest, smallest keys)
+    - KYBER768: NIST Level 3 (recommended, balanced)
+    - KYBER1024: NIST Level 5 (maximum security, largest keys)
+
+    **Use Cases:**
+    - Secure key exchange over public channels
+    - Hybrid encryption systems
+    - Post-quantum TLS
+    - Encrypted messaging protocols
+    """
+    try:
+        start_time = time.time()
+
+        pqc = get_pqc()
+
+        # Support both 'format' and 'encoding' for compatibility
+        output_encoding = format if format else encoding
+
+        # Normalize algorithm name
+        algo_upper = algorithm.upper().replace("-", "").replace("_", "")
+        if not algo_upper.startswith("KYBER"):
+            algo_upper = f"KYBER{algo_upper}" if algo_upper.isdigit() else algo_upper
+
+        # Map common names to full algorithm names
+        algorithm_map = {
+            "KYBER512": "KYBER512",
+            "KYBER768": "KYBER768",
+            "KYBER1024": "KYBER1024",
+        }
+        matched_algo = algorithm_map.get(algo_upper, "KYBER768")
+
+        if matched_algo not in pqc.algorithms:
+            raise ValueError(f"Unsupported algorithm: {algorithm}")
+
+        # Generate keypair
+        keypair = await pqc.generate_kyber_keypair(matched_algo)
+
+        # Encode keys
+        if output_encoding == "base64":
+            public_key_encoded = base64.b64encode(keypair.public_key).decode()
+            private_key_encoded = base64.b64encode(keypair.private_key).decode()
+        else:
+            public_key_encoded = keypair.public_key.hex()
+            private_key_encoded = keypair.private_key.hex()
+
+        # Calculate execution time
+        execution_time = time.time() - start_time
+
+        # Check if using real liboqs or fallback
+        from app.quantum.pqc import LIBOQS_AVAILABLE
+        is_real = LIBOQS_AVAILABLE
+
+        # Record metrics
+        PQCMetrics.record_operation(matched_algo, "generate_keypair", "success", execution_time)
+        PQCMetrics.record_key_size(matched_algo, "public", len(keypair.public_key))
+        PQCMetrics.record_key_size(matched_algo, "private", len(keypair.private_key))
+
+        return BaseResponse(
+            status=ResponseStatus.SUCCESS,
+            request_id=f"kem_gen_{int(time.time()*1000000)}",
+            data={
+                "public_key": public_key_encoded,
+                "private_key": private_key_encoded,
+                "algorithm": keypair.algorithm,
+                "nist_level": keypair.nist_level,
+                "nist_security_level": keypair.nist_level,
+                "encoding": output_encoding,
+                "type": "key_encapsulation_mechanism",
+                "key_sizes": {
+                    "public_key_bytes": len(keypair.public_key),
+                    "private_key_bytes": len(keypair.private_key)
+                }
+            },
+            metadata={
+                "quantum_resistant": True,
+                "standardization": "NIST FIPS 203",
+                "security": f"NIST Security Level {keypair.nist_level}",
+                "suitable_for": ["Key encapsulation", "Secure key exchange", "Hybrid encryption"],
+                "execution_time_ms": round(execution_time * 1000, 2),
+                "production_ready": True,
+                "implementation": "liboqs" if is_real else "fallback (non-cryptographic)",
+                "warning": None if is_real else "Fallback mode: NOT cryptographically secure"
+            }
+        )
+
+    except Exception as e:
+        logger.error(f"Kyber KEM key generation error: {str(e)}")
+        # Record error metric
+        algo_upper = algorithm.upper().replace("-", "").replace("_", "")
+        if not algo_upper.startswith("KYBER"):
+            algo_upper = f"KYBER{algo_upper}" if algo_upper.isdigit() else algo_upper
+        PQCMetrics.record_operation(algo_upper, "generate_keypair", "error", 0)
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/kem/encapsulate", response_model=BaseResponse)
+async def encapsulate_shared_secret(
+    public_key: str = Form(..., description="Recipient's base64 or hex encoded public key"),
+    algorithm: str = Form("KYBER768", description="Algorithm: KYBER512/768/1024"),
+    encoding: str = Form("base64", description="Key encoding format")
+):
+    """
+    Encapsulate a shared secret using Kyber KEM
+
+    This operation creates a shared secret that can be used for symmetric
+    encryption. The ciphertext must be sent to the recipient who can
+    decapsulate it using their private key.
+
+    **Process:**
+    1. Sender uses recipient's public key to encapsulate
+    2. Returns ciphertext + shared secret (sender's copy)
+    3. Sender sends ciphertext to recipient
+    4. Recipient decapsulates to get matching shared secret
+    5. Both parties now share a secret key for symmetric encryption
+    """
+    try:
+        start_time = time.time()
+
+        pqc = get_pqc()
+
+        # Decode public key
+        if encoding == "base64":
+            public_key_bytes = base64.b64decode(public_key)
+        elif encoding == "hex":
+            public_key_bytes = bytes.fromhex(public_key)
+        else:
+            raise ValueError(f"Unsupported encoding: {encoding}")
+
+        # Normalize algorithm name
+        algo_upper = algorithm.upper().replace("-", "").replace("_", "")
+        if not algo_upper.startswith("KYBER"):
+            algo_upper = f"KYBER{algo_upper}" if algo_upper.isdigit() else algo_upper
+
+        algorithm_map = {
+            "KYBER512": "KYBER512",
+            "KYBER768": "KYBER768",
+            "KYBER1024": "KYBER1024",
+        }
+        matched_algo = algorithm_map.get(algo_upper, "KYBER768")
+
+        # Encapsulate
+        result = await pqc.encapsulate(public_key_bytes, matched_algo)
+
+        # Encode results
+        if encoding == "base64":
+            ciphertext_encoded = base64.b64encode(result.ciphertext).decode()
+            shared_secret_encoded = base64.b64encode(result.shared_secret).decode()
+        else:
+            ciphertext_encoded = result.ciphertext.hex()
+            shared_secret_encoded = result.shared_secret.hex()
+
+        # Calculate execution time
+        execution_time = time.time() - start_time
+
+        from app.quantum.pqc import LIBOQS_AVAILABLE
+        is_real = LIBOQS_AVAILABLE
+
+        # Record metrics
+        PQCMetrics.record_operation(matched_algo, "encapsulate", "success", execution_time)
+        PQCMetrics.record_kem_ciphertext_size(matched_algo, len(result.ciphertext))
+        PQCMetrics.record_kem_shared_secret_size(matched_algo, len(result.shared_secret))
+
+        return BaseResponse(
+            status=ResponseStatus.SUCCESS,
+            request_id=f"kem_encap_{int(time.time()*1000000)}",
+            data={
+                "ciphertext": ciphertext_encoded,
+                "shared_secret": shared_secret_encoded,
+                "algorithm": result.algorithm,
+                "encoding": encoding,
+                "sizes": {
+                    "ciphertext_bytes": len(result.ciphertext),
+                    "shared_secret_bytes": len(result.shared_secret)
+                }
+            },
+            metadata={
+                "quantum_resistant": True,
+                "standardization": "NIST FIPS 203",
+                "usage": "Send ciphertext to recipient; use shared_secret for symmetric encryption",
+                "next_step": "Recipient calls /kem/decapsulate with ciphertext and private key",
+                "execution_time_ms": round(execution_time * 1000, 2),
+                "implementation": "liboqs" if is_real else "fallback (non-cryptographic)",
+                "warning": None if is_real else "Fallback mode: NOT cryptographically secure"
+            }
+        )
+
+    except Exception as e:
+        logger.error(f"Kyber encapsulation error: {str(e)}")
+        PQCMetrics.record_operation(matched_algo, "encapsulate", "error", 0)
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/kem/decapsulate", response_model=BaseResponse)
+async def decapsulate_shared_secret(
+    ciphertext: str = Form(..., description="Ciphertext from encapsulation (base64 or hex)"),
+    private_key: str = Form(..., description="Your base64 or hex encoded private key"),
+    algorithm: str = Form("KYBER768", description="Algorithm: KYBER512/768/1024"),
+    encoding: str = Form("base64", description="Key encoding format")
+):
+    """
+    Decapsulate a shared secret using Kyber KEM
+
+    This operation recovers the shared secret from the ciphertext using
+    the recipient's private key. The result should match the sender's
+    shared secret.
+
+    **Process:**
+    1. Receive ciphertext from sender
+    2. Use your private key to decapsulate
+    3. Result is the shared secret (matches sender's copy)
+    4. Use shared secret for symmetric encryption/decryption
+    """
+    try:
+        start_time = time.time()
+
+        pqc = get_pqc()
+
+        # Decode inputs
+        if encoding == "base64":
+            ciphertext_bytes = base64.b64decode(ciphertext)
+            private_key_bytes = base64.b64decode(private_key)
+        elif encoding == "hex":
+            ciphertext_bytes = bytes.fromhex(ciphertext)
+            private_key_bytes = bytes.fromhex(private_key)
+        else:
+            raise ValueError(f"Unsupported encoding: {encoding}")
+
+        # Normalize algorithm name
+        algo_upper = algorithm.upper().replace("-", "").replace("_", "")
+        if not algo_upper.startswith("KYBER"):
+            algo_upper = f"KYBER{algo_upper}" if algo_upper.isdigit() else algo_upper
+
+        algorithm_map = {
+            "KYBER512": "KYBER512",
+            "KYBER768": "KYBER768",
+            "KYBER1024": "KYBER1024",
+        }
+        matched_algo = algorithm_map.get(algo_upper, "KYBER768")
+
+        # Decapsulate
+        shared_secret = await pqc.decapsulate(ciphertext_bytes, private_key_bytes, matched_algo)
+
+        # Encode result
+        if encoding == "base64":
+            shared_secret_encoded = base64.b64encode(shared_secret).decode()
+        else:
+            shared_secret_encoded = shared_secret.hex()
+
+        # Calculate execution time
+        execution_time = time.time() - start_time
+
+        from app.quantum.pqc import LIBOQS_AVAILABLE
+        is_real = LIBOQS_AVAILABLE
+
+        # Record metrics
+        PQCMetrics.record_operation(matched_algo, "decapsulate", "success", execution_time)
+        PQCMetrics.record_kem_shared_secret_size(matched_algo, len(shared_secret))
+
+        return BaseResponse(
+            status=ResponseStatus.SUCCESS,
+            request_id=f"kem_decap_{int(time.time()*1000000)}",
+            data={
+                "shared_secret": shared_secret_encoded,
+                "algorithm": matched_algo,
+                "encoding": encoding,
+                "shared_secret_bytes": len(shared_secret)
+            },
+            metadata={
+                "quantum_resistant": True,
+                "standardization": "NIST FIPS 203",
+                "usage": "Use this shared_secret to decrypt messages from sender",
+                "verification": "Should match sender's shared secret from encapsulation",
+                "execution_time_ms": round(execution_time * 1000, 2),
+                "implementation": "liboqs" if is_real else "fallback (non-cryptographic)",
+                "warning": None if is_real else "Fallback mode: NOT cryptographically secure"
+            }
+        )
+
+    except Exception as e:
+        logger.error(f"Kyber decapsulation error: {str(e)}")
+        PQCMetrics.record_operation(matched_algo, "decapsulate", "error", 0)
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/kem/info", response_model=BaseResponse)
+async def kyber_kem_info():
+    """
+    Get information about Kyber Key Encapsulation Mechanism
+
+    Explains how KEM works and why it's important for post-quantum security.
+    """
+    return BaseResponse(
+        status=ResponseStatus.SUCCESS,
+        request_id=f"kem_info_{int(time.time()*1000000)}",
+        data={
+            "what_is_kyber": "NIST-standardized Key Encapsulation Mechanism for post-quantum key exchange",
+            "what_is_kem": (
+                "A Key Encapsulation Mechanism allows two parties to establish a shared "
+                "secret over a public channel. Unlike signatures, KEMs are designed for "
+                "key exchange and encryption."
+            ),
+            "how_it_works": {
+                "step1": "Recipient generates Kyber keypair (public/private)",
+                "step2": "Sender uses recipient's public key to encapsulate a shared secret",
+                "step3": "Sender sends ciphertext to recipient",
+                "step4": "Recipient decapsulates ciphertext with private key",
+                "step5": "Both parties now share the same secret for symmetric encryption"
+            },
+            "kyber_variants": {
+                "KYBER512": {
+                    "nist_level": 1,
+                    "public_key_size": "~800 bytes",
+                    "ciphertext_size": "~768 bytes",
+                    "shared_secret_size": "32 bytes",
+                    "use_case": "Fast key exchange, constrained environments"
+                },
+                "KYBER768": {
+                    "nist_level": 3,
+                    "public_key_size": "~1184 bytes",
+                    "ciphertext_size": "~1088 bytes",
+                    "shared_secret_size": "32 bytes",
+                    "use_case": "Recommended for most applications"
+                },
+                "KYBER1024": {
+                    "nist_level": 5,
+                    "public_key_size": "~1568 bytes",
+                    "ciphertext_size": "~1568 bytes",
+                    "shared_secret_size": "32 bytes",
+                    "use_case": "Maximum security requirements"
+                }
+            },
+            "applications": [
+                "Post-quantum TLS/HTTPS",
+                "Secure messaging protocols",
+                "Hybrid encryption systems",
+                "Key agreement in blockchain",
+                "Encrypted file storage"
+            ],
+            "nist_standardization": "FIPS 203 (Finalized 2024)"
+        },
+        metadata={
+            "learn_more": [
+                "https://csrc.nist.gov/projects/post-quantum-cryptography",
+                "https://pq-crystals.org/kyber/",
+                "https://github.com/open-quantum-safe/liboqs"
+            ],
+            "related_endpoints": [
+                "/pqc/kem/generate - Generate Kyber keypair",
+                "/pqc/kem/encapsulate - Create shared secret",
+                "/pqc/kem/decapsulate - Recover shared secret"
+            ]
+        }
+    )
+
+
+# ============================================================================
+# Additional PQC Algorithm Endpoints (FALCON, SPHINCS+, NTRU, SABER)
+# ============================================================================
+
+@router.post("/falcon/generate", response_model=BaseResponse)
+async def generate_falcon_keypair(
+    algorithm: str = Form("FALCON512", description="Algorithm: FALCON512 or FALCON1024"),
+    encoding: str = Form("base64", description="Output encoding: base64 or hex")
+):
+    """
+    Generate a Falcon key pair
+
+    Falcon provides compact signatures, ideal for bandwidth-constrained applications.
+
+    **FALCON Variants:**
+    - FALCON512: NIST Level 1 (compact signatures ~666 bytes)
+    - FALCON1024: NIST Level 5 (high security signatures ~1280 bytes)
+    """
+    try:
+        start_time = time.time()
+        pqc = get_pqc()
+
+        algo_upper = algorithm.upper()
+        if algo_upper not in ["FALCON512", "FALCON1024"]:
+            algo_upper = "FALCON512"
+
+        keypair = await pqc.generate_falcon_keypair(algo_upper)
+
+        if encoding == "base64":
+            public_key_encoded = base64.b64encode(keypair.public_key).decode()
+            private_key_encoded = base64.b64encode(keypair.private_key).decode()
+        else:
+            public_key_encoded = keypair.public_key.hex()
+            private_key_encoded = keypair.private_key.hex()
+
+        execution_time = time.time() - start_time
+        from app.quantum.pqc import LIBOQS_AVAILABLE
+
+        return BaseResponse(
+            status=ResponseStatus.SUCCESS,
+            request_id=f"falcon_gen_{int(time.time()*1000000)}",
+            data={
+                "public_key": public_key_encoded,
+                "private_key": private_key_encoded,
+                "algorithm": keypair.algorithm,
+                "nist_level": keypair.nist_level,
+                "encoding": encoding,
+                "type": "signature",
+                "key_sizes": {
+                    "public_key_bytes": len(keypair.public_key),
+                    "private_key_bytes": len(keypair.private_key),
+                    "signature_bytes": pqc.algorithms[algo_upper]["sig_size"]
+                }
+            },
+            metadata={
+                "quantum_resistant": True,
+                "standardization": "NIST FIPS 204",
+                "security": f"NIST Security Level {keypair.nist_level}",
+                "suitable_for": ["Compact signatures", "Bandwidth-constrained apps", "IoT devices"],
+                "execution_time_ms": round(execution_time * 1000, 2),
+                "implementation": "liboqs" if LIBOQS_AVAILABLE else "fallback (non-cryptographic)"
+            }
+        )
+    except Exception as e:
+        logger.error(f"Falcon key generation error: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/sphincs/generate", response_model=BaseResponse)
+async def generate_sphincs_keypair(
+    algorithm: str = Form("SPHINCS+-SHA2-128f", description="SPHINCS+ variant"),
+    encoding: str = Form("base64", description="Output encoding: base64 or hex")
+):
+    """
+    Generate a SPHINCS+ key pair
+
+    SPHINCS+ is a hash-based signature scheme with conservative security assumptions.
+    It does not rely on lattice problems, providing diversity in cryptographic assumptions.
+
+    **SPHINCS+ Variants:**
+    - SPHINCS+-SHA2-128f: Fast variant, NIST Level 1
+    - SPHINCS+-SHA2-128s: Small variant, NIST Level 1
+    - SPHINCS+-SHA2-192f: Fast variant, NIST Level 3
+    - SPHINCS+-SHA2-192s: Small variant, NIST Level 3
+    - SPHINCS+-SHA2-256f: Fast variant, NIST Level 5
+    - SPHINCS+-SHA2-256s: Small variant, NIST Level 5
+    """
+    try:
+        start_time = time.time()
+        pqc = get_pqc()
+
+        algo_upper = algorithm.upper()
+        if algo_upper not in pqc.algorithms or pqc.algorithms[algo_upper].get("type") != "SIGNATURE":
+            algo_upper = "SPHINCS+-SHA2-128F"
+
+        keypair = await pqc.generate_sphincs_keypair(algo_upper)
+
+        if encoding == "base64":
+            public_key_encoded = base64.b64encode(keypair.public_key).decode()
+            private_key_encoded = base64.b64encode(keypair.private_key).decode()
+        else:
+            public_key_encoded = keypair.public_key.hex()
+            private_key_encoded = keypair.private_key.hex()
+
+        execution_time = time.time() - start_time
+        from app.quantum.pqc import LIBOQS_AVAILABLE
+
+        return BaseResponse(
+            status=ResponseStatus.SUCCESS,
+            request_id=f"sphincs_gen_{int(time.time()*1000000)}",
+            data={
+                "public_key": public_key_encoded,
+                "private_key": private_key_encoded,
+                "algorithm": keypair.algorithm,
+                "nist_level": keypair.nist_level,
+                "encoding": encoding,
+                "type": "signature",
+                "key_sizes": {
+                    "public_key_bytes": len(keypair.public_key),
+                    "private_key_bytes": len(keypair.private_key),
+                    "signature_bytes": pqc.algorithms[algo_upper]["sig_size"]
+                }
+            },
+            metadata={
+                "quantum_resistant": True,
+                "standardization": "NIST FIPS 205",
+                "security": f"NIST Security Level {keypair.nist_level}",
+                "suitable_for": ["Conservative security", "Hash-based signatures", "Long-term security"],
+                "execution_time_ms": round(execution_time * 1000, 2),
+                "implementation": "liboqs" if LIBOQS_AVAILABLE else "fallback (non-cryptographic)"
+            }
+        )
+    except Exception as e:
+        logger.error(f"SPHINCS+ key generation error: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/ntru/generate", response_model=BaseResponse)
+async def generate_ntru_keypair(
+    algorithm: str = Form("NTRU-HPS-2048-509", description="NTRU variant"),
+    encoding: str = Form("base64", description="Output encoding: base64 or hex")
+):
+    """
+    Generate an NTRU key pair
+
+    NTRU is a lattice-based KEM offering fast operations and small key sizes.
+
+    **NTRU Variants:**
+    - NTRU-HPS-2048-509: NIST Level 1
+    - NTRU-HPS-2048-677: NIST Level 3
+    """
+    try:
+        start_time = time.time()
+        pqc = get_pqc()
+
+        algo_upper = algorithm.upper().replace("-", "-")
+        if algo_upper not in ["NTRU-HPS-2048-509", "NTRU-HPS-2048-677"]:
+            algo_upper = "NTRU-HPS-2048-509"
+
+        keypair = await pqc.generate_ntru_keypair(algo_upper)
+
+        if encoding == "base64":
+            public_key_encoded = base64.b64encode(keypair.public_key).decode()
+            private_key_encoded = base64.b64encode(keypair.private_key).decode()
+        else:
+            public_key_encoded = keypair.public_key.hex()
+            private_key_encoded = keypair.private_key.hex()
+
+        execution_time = time.time() - start_time
+        from app.quantum.pqc import LIBOQS_AVAILABLE
+
+        return BaseResponse(
+            status=ResponseStatus.SUCCESS,
+            request_id=f"ntru_gen_{int(time.time()*1000000)}",
+            data={
+                "public_key": public_key_encoded,
+                "private_key": private_key_encoded,
+                "algorithm": keypair.algorithm,
+                "nist_level": keypair.nist_level,
+                "encoding": encoding,
+                "type": "key_encapsulation_mechanism",
+                "key_sizes": {
+                    "public_key_bytes": len(keypair.public_key),
+                    "private_key_bytes": len(keypair.private_key)
+                }
+            },
+            metadata={
+                "quantum_resistant": True,
+                "standardization": "NIST FIPS 203",
+                "security": f"NIST Security Level {keypair.nist_level}",
+                "suitable_for": ["Fast KEM operations", "Small key sizes", "High-performance apps"],
+                "execution_time_ms": round(execution_time * 1000, 2),
+                "implementation": "liboqs" if LIBOQS_AVAILABLE else "fallback (non-cryptographic)"
+            }
+        )
+    except Exception as e:
+        logger.error(f"NTRU key generation error: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/saber/generate", response_model=BaseResponse)
+async def generate_saber_keypair(
+    algorithm: str = Form("SABER-SABER", description="SABER variant: LIGHTSABER, SABER, or FIRESABER"),
+    encoding: str = Form("base64", description="Output encoding: base64 or hex")
+):
+    """
+    Generate a SABER key pair
+
+    SABER is a module-lattice-based KEM with a focus on simplicity and efficiency.
+
+    **SABER Variants:**
+    - SABER-LIGHTSABER: NIST Level 1 (fastest)
+    - SABER-SABER: NIST Level 3 (balanced)
+    - SABER-FIRESABER: NIST Level 5 (maximum security)
+    """
+    try:
+        start_time = time.time()
+        pqc = get_pqc()
+
+        algo_upper = algorithm.upper().replace("-", "-")
+        valid_saber = ["SABER-LIGHTSABER", "SABER-SABER", "SABER-FIRESABER"]
+        if algo_upper not in valid_saber:
+            algo_upper = "SABER-SABER"
+
+        keypair = await pqc.generate_saber_keypair(algo_upper)
+
+        if encoding == "base64":
+            public_key_encoded = base64.b64encode(keypair.public_key).decode()
+            private_key_encoded = base64.b64encode(keypair.private_key).decode()
+        else:
+            public_key_encoded = keypair.public_key.hex()
+            private_key_encoded = keypair.private_key.hex()
+
+        execution_time = time.time() - start_time
+        from app.quantum.pqc import LIBOQS_AVAILABLE
+
+        return BaseResponse(
+            status=ResponseStatus.SUCCESS,
+            request_id=f"saber_gen_{int(time.time()*1000000)}",
+            data={
+                "public_key": public_key_encoded,
+                "private_key": private_key_encoded,
+                "algorithm": keypair.algorithm,
+                "nist_level": keypair.nist_level,
+                "encoding": encoding,
+                "type": "key_encapsulation_mechanism",
+                "key_sizes": {
+                    "public_key_bytes": len(keypair.public_key),
+                    "private_key_bytes": len(keypair.private_key)
+                }
+            },
+            metadata={
+                "quantum_resistant": True,
+                "standardization": "NIST FIPS 203",
+                "security": f"NIST Security Level {keypair.nist_level}",
+                "suitable_for": ["Efficient KEM", "Module-lattice security", "Embedded systems"],
+                "execution_time_ms": round(execution_time * 1000, 2),
+                "implementation": "liboqs" if LIBOQS_AVAILABLE else "fallback (non-cryptographic)"
+            }
+        )
+    except Exception as e:
+        logger.error(f"SABER key generation error: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))

app/billing/stripe_webhooks.py

@@ -0,0 +1,213 @@
+"""
+Stripe webhook handler for subscription lifecycle events.
+
+Listens for:
+  - checkout.session.completed  -> register new key with the purchased tier
+  - customer.subscription.updated -> upgrade / downgrade tier
+  - customer.subscription.deleted -> revoke key (or downgrade to free)
+
+All tier mutations go through UsageTracker so the rate-limiter
+picks them up immediately.
+"""
+
+import hashlib
+import hmac
+import json
+import logging
+import secrets
+from typing import Dict, Optional
+
+from fastapi import APIRouter, Header, HTTPException, Request
+from fastapi.responses import JSONResponse
+
+from app.config import settings
+from app.utils.rate_limiting import UsageTracker, VALID_TIERS
+
+logger = logging.getLogger(__name__)
+router = APIRouter()
+
+_tracker: Optional[UsageTracker] = None
+
+
+def _get_tracker() -> UsageTracker:
+    global _tracker
+    if _tracker is None:
+        _tracker = UsageTracker()
+    return _tracker
+
+
+PRICE_TO_TIER: Dict[str, str] = {}
+
+
+def _build_price_map() -> Dict[str, str]:
+    """Map Stripe price IDs to internal tier names (rebuilt on first call)."""
+    if PRICE_TO_TIER:
+        return PRICE_TO_TIER
+    if settings.stripe_price_id_pro:
+        PRICE_TO_TIER[settings.stripe_price_id_pro] = "pro"
+    if settings.stripe_price_id_enterprise:
+        PRICE_TO_TIER[settings.stripe_price_id_enterprise] = "enterprise"
+    return PRICE_TO_TIER
+
+
+def _verify_stripe_signature(payload: bytes, sig_header: str, secret: str) -> dict:
+    """Verify Stripe webhook signature and return the parsed event.
+
+    Implements Stripe v1 HMAC-SHA256 verification so we don't require
+    the stripe Python package at runtime.  If the stripe package is
+    installed it will be preferred.
+    """
+    try:
+        import stripe
+        stripe.api_key = settings.stripe_secret_key
+        return stripe.Webhook.construct_event(payload, sig_header, secret)
+    except ImportError:
+        pass
+
+    parts_raw = sig_header.split(",")
+    timestamp = ""
+    expected_sigs = []
+    for part in parts_raw:
+        key, _, val = part.partition("=")
+        if key.strip() == "t":
+            timestamp = val.strip()
+        elif key.strip() == "v1":
+            expected_sigs.append(val.strip())
+
+    signed_payload = f"{timestamp}.".encode() + payload
+    computed = hmac.new(secret.encode(), signed_payload, hashlib.sha256).hexdigest()
+
+    if not any(hmac.compare_digest(computed, sig) for sig in expected_sigs):
+        raise ValueError("Webhook signature verification failed")
+
+    return json.loads(payload)
+
+
+def _tier_from_subscription(subscription: dict) -> str:
+    """Extract the tier from a Stripe subscription object."""
+    price_map = _build_price_map()
+    items = subscription.get("items", {}).get("data", [])
+    for item in items:
+        price_id = item.get("price", {}).get("id", "")
+        if price_id in price_map:
+            return price_map[price_id]
+    return "free"
+
+
+def _generate_api_key() -> str:
+    return "qcrng_" + secrets.token_urlsafe(32)
+
+
+@router.post("/stripe/webhook")
+async def stripe_webhook(
+    request: Request,
+    stripe_signature: Optional[str] = Header(None, alias="Stripe-Signature"),
+):
+    """Handle incoming Stripe webhook events."""
+    if not settings.stripe_webhook_secret:
+        raise HTTPException(status_code=503, detail="Billing not configured")
+
+    payload = await request.body()
+
+    if not stripe_signature:
+        raise HTTPException(status_code=400, detail="Missing Stripe-Signature header")
+
+    try:
+        event = _verify_stripe_signature(payload, stripe_signature, settings.stripe_webhook_secret)
+    except Exception as exc:
+        logger.warning("Stripe signature verification failed: %s", exc)
+        raise HTTPException(status_code=400, detail="Invalid signature") from exc
+
+    event_type = event.get("type", "")
+    data_object = event.get("data", {}).get("object", {})
+    tracker = _get_tracker()
+
+    if event_type == "checkout.session.completed":
+        customer_id = data_object.get("customer", "")
+        subscription = data_object.get("subscription")
+        tier = "pro"
+        if subscription and isinstance(subscription, dict):
+            tier = _tier_from_subscription(subscription)
+
+        existing_key = tracker.get_key_by_customer(customer_id)
+        if existing_key:
+            tracker.set_tier(existing_key, tier)
+            logger.info("Upgraded existing key for customer %s to %s", customer_id, tier)
+        else:
+            new_key = _generate_api_key()
+            tracker.register_key(new_key, tier=tier, customer_id=customer_id)
+            logger.info("Created key for new customer %s (tier=%s)", customer_id, tier)
+
+    elif event_type == "customer.subscription.updated":
+        customer_id = data_object.get("customer", "")
+        tier = _tier_from_subscription(data_object)
+        api_key = tracker.get_key_by_customer(customer_id)
+        if api_key:
+            tracker.set_tier(api_key, tier)
+            logger.info("Subscription updated for %s -> %s", customer_id, tier)
+
+    elif event_type == "customer.subscription.deleted":
+        customer_id = data_object.get("customer", "")
+        api_key = tracker.get_key_by_customer(customer_id)
+        if api_key:
+            tracker.set_tier(api_key, "free")
+            logger.info("Subscription cancelled for %s, downgraded to free", customer_id)
+
+    else:
+        logger.debug("Ignoring Stripe event: %s", event_type)
+
+    return JSONResponse({"received": True})
+
+
+@router.get("/billing/usage")
+async def billing_usage(request: Request):
+    """Return usage summary for the calling API key (for dashboard display)."""
+    api_key = request.headers.get(settings.api_key_header, "")
+    if not api_key:
+        raise HTTPException(status_code=401, detail="API key required")
+
+    tracker = _get_tracker()
+    tier = tracker._get_tier(api_key)
+    limits = settings.get_tier_limits(tier)
+    requests_used, bytes_used, reset_time = tracker._get_current_usage(api_key)
+
+    return {
+        "tier": tier,
+        "limits": limits,
+        "usage": {
+            "requests_used": requests_used,
+            "bytes_used": bytes_used,
+            "reset_time": reset_time.isoformat() if reset_time else None,
+        },
+    }
+
+
+@router.post("/billing/keys/register")
+async def admin_register_key(request: Request):
+    """Admin endpoint to manually register or update an API key tier.
+
+    Expects JSON: {"api_key": "...", "tier": "pro", "customer_id": "cus_..."}
+
+    Protected: only callable when REQUIRE_API_KEY is false (dev) or
+    the calling key is enterprise-tier.
+    """
+    caller_key = request.headers.get(settings.api_key_header, "")
+    tracker = _get_tracker()
+
+    if settings.require_api_key:
+        caller_tier = tracker._get_tier(caller_key)
+        if caller_tier != "enterprise":
+            raise HTTPException(status_code=403, detail="Enterprise key required for admin operations")
+
+    body = await request.json()
+    api_key = body.get("api_key", "")
+    tier = body.get("tier", "free")
+    customer_id = body.get("customer_id")
+
+    if not api_key or len(api_key) < 10:
+        raise HTTPException(status_code=400, detail="api_key must be >= 10 characters")
+    if tier not in VALID_TIERS:
+        raise HTTPException(status_code=400, detail=f"tier must be one of {VALID_TIERS}")
+
+    tracker.register_key(api_key, tier=tier, customer_id=customer_id)
+    return {"status": "ok", "api_key_prefix": api_key[:8] + "...", "tier": tier}

app/blockchain/__init__.py

@@ -0,0 +1,102 @@
+"""
+QCrypt RNG - Blockchain Chain Adapters
+
+Provides adapters for different blockchain networks for oracle fulfillment:
+- Ethereum
+- Polygon
+- Binance Smart Chain (BSC)
+- Avalanche
+- Fantom
+"""
+
+from .base import ChainAdapter, ChainConfig, TransactionStatus
+from .ethereum import EthereumAdapter
+from .polygon import PolygonAdapter
+from .bsc import BSCAdapter
+from .avalanche import AvalancheAdapter
+from .fantom import FantomAdapter
+
+__all__ = [
+    "ChainAdapter",
+    "ChainConfig",
+    "TransactionStatus",
+    "EthereumAdapter",
+    "PolygonAdapter",
+    "BSCAdapter",
+    "AvalancheAdapter",
+    "FantomAdapter",
+    "get_chain_adapter",
+    "get_supported_chains"
+]
+
+
+def get_chain_adapter(chain_name: str, config: ChainConfig) -> ChainAdapter:
+    """
+    Get a chain adapter by name
+
+    Args:
+        chain_name: Name of the blockchain (ethereum, polygon, bsc, avalanche, fantom)
+        config: Chain configuration
+
+    Returns:
+        ChainAdapter instance
+    """
+    adapters = {
+        "ethereum": EthereumAdapter,
+        "polygon": PolygonAdapter,
+        "bsc": BSCAdapter,
+        "avalanche": AvalancheAdapter,
+        "fantom": FantomAdapter,
+    }
+
+    chain_lower = chain_name.lower()
+    if chain_lower not in adapters:
+        raise ValueError(f"Unsupported chain: {chain_name}. Supported: {list(adapters.keys())}")
+
+    return adapters[chain_lower](config)
+
+
+def get_supported_chains() -> dict:
+    """Get list of supported blockchain networks"""
+    return {
+        "ethereum": {
+            "name": "Ethereum Mainnet",
+            "chain_id": 1,
+            "currency": "ETH",
+            "explorer": "https://etherscan.io",
+            "rpc": "https://mainnet.infura.io/v3/",
+            "features": ["commit", "reveal", "batch_requests"]
+        },
+        "polygon": {
+            "name": "Polygon",
+            "chain_id": 137,
+            "currency": "MATIC",
+            "explorer": "https://polygonscan.com",
+            "rpc": "https://polygon-rpc.com",
+            "features": ["commit", "reveal", "batch_requests", "low_fees"]
+        },
+        "bsc": {
+            "name": "Binance Smart Chain",
+            "chain_id": 56,
+            "currency": "BNB",
+            "explorer": "https://bscscan.com",
+            "rpc": "https://bsc-dataseed.binance.org",
+            "features": ["commit", "reveal", "batch_requests", "low_fees"]
+        },
+        "avalanche": {
+            "name": "Avalanche C-Chain",
+            "chain_id": 43114,
+            "currency": "AVAX",
+            "explorer": "https://snowtrace.io",
+            "rpc": "https://api.avax.network/ext/bc/C/rpc",
+            "features": ["commit", "reveal", "batch_requests", "fast_finality"]
+        },
+        "fantom": {
+            "name": "Fantom Opera",
+            "chain_id": 250,
+            "currency": "FTM",
+            "explorer": "https://ftmscan.com",
+            "rpc": "https://rpc.ftm.tools",
+            "features": ["commit", "reveal", "batch_requests", "low_fees"]
+        }
+    }

app/blockchain/avalanche.py

@@ -0,0 +1,40 @@
+"""
+QCrypt RNG - Avalanche C-Chain Adapter
+
+Provides Avalanche C-Chain support for oracle fulfillment.
+"""
+
+from typing import Optional
+from .base import ChainConfig
+from .ethereum import EthereumAdapter
+
+
+class AvalancheAdapter(EthereumAdapter):
+    """
+    Avalanche C-Chain adapter
+
+    Avalanche C-Chain is Ethereum-compatible with very fast finality.
+    """
+
+    # Avalanche-specific RPC endpoints
+    AVALANCHE_RPC_URLS = [
+        "https://api.avax.network/ext/bc/C/rpc",
+        "https://avalanche-c-chain.publicnode.com"
+    ]
+
+    def __init__(self, config: Optional[ChainConfig] = None):
+        if config is None:
+            config = ChainConfig(
+                rpc_url=self.AVALANCHE_RPC_URLS[0],
+                chain_id=43114,
+                explorer_url="https://snowtrace.io",
+                currency_symbol="AVAX",
+                confirmations_required=3  # Avalanche has very fast finality (~1-2 seconds)
+            )
+        super().__init__(config)
+
+    async def get_gas_price(self) -> int:
+        """Get current gas price in wei (AVAX)"""
+        gas_price = await super().get_gas_price()
+        # Avalanche has a fixed minimum gas price
+        return max(gas_price, 25_000_000_000)  # 25 gwei minimum

app/blockchain/base.py

@@ -0,0 +1,217 @@
+"""
+QCrypt RNG - Base Chain Adapter
+
+Defines the abstract base class for blockchain chain adapters.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Optional, Dict, Any, List
+from dataclasses import dataclass
+from enum import Enum
+import time
+
+
+class TransactionStatus(Enum):
+    """Transaction status enumeration"""
+    PENDING = "pending"
+    SUBMITTED = "submitted"
+    CONFIRMED = "confirmed"
+    FAILED = "failed"
+    REVERTED = "reverted"
+
+
+@dataclass
+class ChainConfig:
+    """Chain configuration"""
+    rpc_url: str
+    chain_id: int
+    explorer_url: str
+    currency_symbol: str
+    private_key: Optional[str] = None  # In production, use secure key management
+    gas_price_gwei: Optional[int] = None
+    gas_limit: Optional[int] = None
+    confirmations_required: int = 3
+
+
+@dataclass
+class TransactionReceipt:
+    """Transaction receipt"""
+    tx_hash: str
+    status: TransactionStatus
+    block_number: Optional[int] = None
+    confirmations: int = 0
+    gas_used: Optional[int] = None
+    timestamp: float = 0
+    error: Optional[str] = None
+
+
+class ChainAdapter(ABC):
+    """
+    Abstract base class for blockchain chain adapters
+
+    Provides a unified interface for interacting with different blockchain networks.
+    """
+
+    def __init__(self, config: ChainConfig):
+        self.config = config
+        self._web3 = None
+        self._account = None
+
+    @property
+    def web3(self):
+        """Get Web3 instance (lazy initialization)"""
+        if self._web3 is None:
+            self._web3 = self._init_web3()
+        return self._web3
+
+    @abstractmethod
+    def _init_web3(self):
+        """Initialize Web3 connection"""
+        pass
+
+    @property
+    def account(self):
+        """Get account (lazy initialization)"""
+        if self._account is None and self.config.private_key:
+            self._account = self._init_account()
+        return self._account
+
+    @abstractmethod
+    def _init_account(self):
+        """Initialize account from private key"""
+        pass
+
+    @abstractmethod
+    async def get_gas_price(self) -> int:
+        """Get current gas price in wei"""
+        pass
+
+    @abstractmethod
+    async def estimate_gas(self, to_address: str, data: str, value: int = 0) -> int:
+        """Estimate gas for a transaction"""
+        pass
+
+    @abstractmethod
+    async def submit_transaction(
+        self,
+        to_address: str,
+        data: str,
+        value: int = 0,
+        gas_limit: Optional[int] = None
+    ) -> str:
+        """
+        Submit a transaction
+
+        Args:
+            to_address: Recipient address
+            data: Transaction data (hex)
+            value: Value to send in wei
+            gas_limit: Gas limit (optional, will estimate if not provided)
+
+        Returns:
+            Transaction hash
+        """
+        pass
+
+    @abstractmethod
+    async def get_transaction_status(self, tx_hash: str) -> TransactionReceipt:
+        """Get transaction status"""
+        pass
+
+    @abstractmethod
+    async def wait_for_confirmation(
+        self,
+        tx_hash: str,
+        confirmations: Optional[int] = None
+    ) -> TransactionReceipt:
+        """
+        Wait for transaction confirmation
+
+        Args:
+            tx_hash: Transaction hash
+            confirmations: Number of confirmations to wait for
+
+        Returns:
+            Transaction receipt
+        """
+        pass
+
+    @abstractmethod
+    async def commit_randomness(
+        self,
+        contract_address: str,
+        request_id: str,
+        commitment: str
+    ) -> str:
+        """
+        Commit randomness to the oracle contract
+
+        Args:
+            contract_address: Oracle contract address
+            request_id: Request ID
+            commitment: Commitment hash (hex)
+
+        Returns:
+            Transaction hash
+        """
+        pass
+
+    @abstractmethod
+    async def reveal_randomness(
+        self,
+        contract_address: str,
+        request_id: str,
+        randomness: str
+    ) -> str:
+        """
+        Reveal randomness to the oracle contract
+
+        Args:
+            contract_address: Oracle contract address
+            request_id: Request ID
+            randomness: Randomness value (hex)
+
+        Returns:
+            Transaction hash
+        """
+        pass
+
+    @abstractmethod
+    async def get_contract_balance(self, contract_address: str) -> int:
+        """Get contract balance in wei"""
+        pass
+
+    @abstractmethod
+    async def get_block_number(self) -> int:
+        """Get current block number"""
+        pass
+
+    def get_explorer_url(self, tx_hash: str) -> str:
+        """Get explorer URL for transaction"""
+        return f"{self.config.explorer_url}/tx/{tx_hash}"
+
+    def get_address_url(self, address: str) -> str:
+        """Get explorer URL for address"""
+        return f"{self.config.explorer_url}/address/{address}"
+
+    async def get_chain_info(self) -> Dict[str, Any]:
+        """Get chain information"""
+        try:
+            block_number = await self.get_block_number()
+            gas_price = await self.get_gas_price()
+
+            return {
+                "chain_id": self.config.chain_id,
+                "chain_name": self.__class__.__name__.replace("Adapter", ""),
+                "rpc_url": self.config.rpc_url,
+                "explorer_url": self.config.explorer_url,
+                "currency": self.config.currency_symbol,
+                "current_block": block_number,
+                "gas_price_gwei": gas_price / 1e9,
+                "confirmations_required": self.config.confirmations_required
+            }
+        except Exception as e:
+            return {
+                "chain_id": self.config.chain_id,
+                "error": str(e)
+            }

app/blockchain/bsc.py

@@ -0,0 +1,41 @@
+"""
+QCrypt RNG - Binance Smart Chain (BSC) Adapter
+
+Provides BSC network support for oracle fulfillment.
+"""
+
+from typing import Optional
+from .base import ChainConfig
+from .ethereum import EthereumAdapter
+
+
+class BSCAdapter(EthereumAdapter):
+    """
+    Binance Smart Chain adapter
+
+    BSC is an Ethereum-compatible chain with low fees and fast block times.
+    """
+
+    # BSC-specific RPC endpoints
+    BSC_RPC_URLS = [
+        "https://bsc-dataseed.binance.org",
+        "https://bsc-dataseed1.defibit.io",
+        "https://bsc-dataseed1.ninicoin.io"
+    ]
+
+    def __init__(self, config: Optional[ChainConfig] = None):
+        if config is None:
+            config = ChainConfig(
+                rpc_url=self.BSC_RPC_URLS[0],
+                chain_id=56,
+                explorer_url="https://bscscan.com",
+                currency_symbol="BNB",
+                confirmations_required=15  # BSC has 3-second block times
+            )
+        super().__init__(config)
+
+    async def get_gas_price(self) -> int:
+        """Get current gas price in wei (BNB)"""
+        gas_price = await super().get_gas_price()
+        # BSC gas prices are typically fixed
+        return max(gas_price, 3_000_000_000)  # 3 gwei minimum

app/blockchain/ethereum.py

@@ -0,0 +1,309 @@
+"""
+QCrypt RNG - Ethereum Chain Adapter
+
+Provides Ethereum mainnet and testnet support for oracle fulfillment.
+"""
+
+from typing import Optional, Dict, Any
+import asyncio
+import time
+
+try:
+    from web3 import Web3
+    from eth_account import Account
+    WEB3_AVAILABLE = True
+except ImportError:
+    Web3 = None
+    Account = None
+    WEB3_AVAILABLE = False
+
+from .base import ChainAdapter, ChainConfig, TransactionStatus, TransactionReceipt
+
+
+class EthereumAdapter(ChainAdapter):
+    """Ethereum chain adapter"""
+
+    # Oracle contract ABI (minimal for commit/reveal)
+    ORACLE_ABI = [
+        {
+            "inputs": [
+                {"name": "requestId", "type": "bytes32"},
+                {"name": "commitment", "type": "bytes32"}
+            ],
+            "name": "commit",
+            "outputs": [],
+            "stateMutability": "nonpayable",
+            "type": "function"
+        },
+        {
+            "inputs": [
+                {"name": "requestId", "type": "bytes32"},
+                {"name": "randomness", "type": "uint256"}
+            ],
+            "name": "reveal",
+            "outputs": [],
+            "stateMutability": "nonpayable",
+            "type": "function"
+        },
+        {
+            "inputs": [
+                {"name": "requestId", "type": "bytes32"}
+            ],
+            "name": "getRequestStatus",
+            "outputs": [
+                {"name": "committed", "type": "bool"},
+                {"name": "revealed", "type": "bool"},
+                {"name": "commitment", "type": "bytes32"}
+            ],
+            "stateMutability": "view",
+            "type": "function"
+        }
+    ]
+
+    def _init_web3(self):
+        """Initialize Web3 connection"""
+        if not WEB3_AVAILABLE:
+            raise ImportError("web3.py not installed. Install with: pip install web3")
+
+        w3 = Web3(Web3.HTTPProvider(self.config.rpc_url))
+
+        # Enable ENS
+        w3.ens = None  # Will be auto-initialized in web3.py
+
+        return w3
+
+    def _init_account(self):
+        """Initialize account from private key"""
+        if not self.config.private_key:
+            raise ValueError("Private key not configured")
+
+        account = Account.from_key(self.config.private_key)
+        return account
+
+    async def get_gas_price(self) -> int:
+        """Get current gas price in wei"""
+        if not WEB3_AVAILABLE:
+            # Return simulated gas price
+            return 20_000_000_000  # 20 gwei
+
+        gas_price = self.web3.eth.gas_price
+        return gas_price
+
+    async def estimate_gas(self, to_address: str, data: str, value: int = 0) -> int:
+        """Estimate gas for a transaction"""
+        if not WEB3_AVAILABLE:
+            return 21000  # Base transaction gas
+
+        try:
+            gas_estimate = self.web3.eth.estimate_gas({
+                'from': self.account.address,
+                'to': to_address,
+                'data': data,
+                'value': value
+            })
+            # Add 20% buffer for safety
+            return int(gas_estimate * 1.2)
+        except Exception:
+            # Return default gas limit
+            return 100000
+
+    async def submit_transaction(
+        self,
+        to_address: str,
+        data: str,
+        value: int = 0,
+        gas_limit: Optional[int] = None
+    ) -> str:
+        """Submit a transaction"""
+        if not WEB3_AVAILABLE:
+            # Return simulated tx hash
+            import hashlib
+            tx_data = f"{to_address}{data}{value}{time.time()}".encode()
+            return "0x" + hashlib.sha256(tx_data).hexdigest()
+
+        if not self.account:
+            raise ValueError("Account not configured")
+
+        # Get nonce
+        nonce = self.web3.eth.get_transaction_count(self.account.address, 'pending')
+
+        # Get gas price and limit
+        gas_price = await self.get_gas_price()
+        if self.config.gas_price_gwei:
+            gas_price = self.web3.to_wei(self.config.gas_price_gwei, 'gwei')
+
+        if gas_limit is None:
+            gas_limit = await self.estimate_gas(to_address, data, value)
+        elif self.config.gas_limit:
+            gas_limit = self.config.gas_limit
+
+        # Build transaction
+        tx = {
+            'from': self.account.address,
+            'to': to_address,
+            'value': value,
+            'data': data,
+            'gas': gas_limit,
+            'gasPrice': gas_price,
+            'nonce': nonce,
+            'chainId': self.config.chain_id
+        }
+
+        # Sign and send transaction
+        signed_tx = self.account.sign_transaction(tx)
+        tx_hash = self.web3.eth.send_raw_transaction(signed_tx.raw_transaction)
+
+        return self.web3.to_hex(tx_hash)
+
+    async def get_transaction_status(self, tx_hash: str) -> TransactionReceipt:
+        """Get transaction status"""
+        if not WEB3_AVAILABLE:
+            return TransactionReceipt(
+                tx_hash=tx_hash,
+                status=TransactionStatus.CONFIRMED,
+                timestamp=time.time()
+            )
+
+        try:
+            tx_hash_bytes = self.web3.to_bytes(hexstr=tx_hash)
+            tx_receipt = self.web3.eth.get_transaction_receipt(tx_hash_bytes)
+
+            if tx_receipt is None:
+                return TransactionReceipt(
+                    tx_hash=tx_hash,
+                    status=TransactionStatus.PENDING,
+                    timestamp=time.time()
+                )
+
+            current_block = self.web3.eth.block_number
+            confirmations = current_block - tx_receipt.blockNumber if tx_receipt.blockNumber else 0
+
+            status = TransactionStatus.CONFIRMED if tx_receipt.status == 1 else TransactionStatus.FAILED
+
+            return TransactionReceipt(
+                tx_hash=tx_hash,
+                status=status,
+                block_number=tx_receipt.blockNumber,
+                confirmations=confirmations,
+                gas_used=tx_receipt.gasUsed,
+                timestamp=time.time()
+            )
+        except Exception as e:
+            return TransactionReceipt(
+                tx_hash=tx_hash,
+                status=TransactionStatus.FAILED,
+                error=str(e),
+                timestamp=time.time()
+            )
+
+    async def wait_for_confirmation(
+        self,
+        tx_hash: str,
+        confirmations: Optional[int] = None
+    ) -> TransactionReceipt:
+        """Wait for transaction confirmation"""
+        target_confirmations = confirmations or self.config.confirmations_required
+
+        while True:
+            receipt = await self.get_transaction_status(tx_hash)
+
+            if receipt.status == TransactionStatus.FAILED:
+                return receipt
+
+            if receipt.status == TransactionStatus.CONFIRMED and receipt.confirmations >= target_confirmations:
+                return receipt
+
+            # Wait before checking again
+            await asyncio.sleep(2)
+
+    async def commit_randomness(
+        self,
+        contract_address: str,
+        request_id: str,
+        commitment: str
+    ) -> str:
+        """Commit randomness to the oracle contract"""
+        if not WEB3_AVAILABLE:
+            # Simulated commit
+            import hashlib
+            tx_data = f"{contract_address}{request_id}{commitment}{time.time()}".encode()
+            return "0x" + hashlib.sha256(tx_data).hexdigest()
+
+        # Create contract instance
+        contract = self.web3.eth.contract(
+            address=self.web3.to_checksum_address(contract_address),
+            abi=self.ORACLE_ABI
+        )
+
+        # Encode function call
+        request_id_bytes = self.web3.to_bytes(hexstr=request_id) if request_id.startswith('0x') else self.web3.to_bytes(text=request_id)
+        commitment_bytes = self.web3.to_bytes(hexstr=commitment) if commitment.startswith('0x') else self.web3.to_bytes(hexstr=commitment)
+
+        data = contract.functions.commit(request_id_bytes, commitment_bytes).build_transaction({
+            'from': self.account.address,
+            'gas': 0,  # Will be estimated
+            'gasPrice': await self.get_gas_price(),
+            'nonce': self.web3.eth.get_transaction_count(self.account.address, 'pending'),
+            'chainId': self.config.chain_id
+        })
+
+        return await self.submit_transaction(
+            contract_address,
+            data['data'],
+            0,
+            data['gas']
+        )
+
+    async def reveal_randomness(
+        self,
+        contract_address: str,
+        request_id: str,
+        randomness: str
+    ) -> str:
+        """Reveal randomness to the oracle contract"""
+        if not WEB3_AVAILABLE:
+            # Simulated reveal
+            import hashlib
+            tx_data = f"{contract_address}{request_id}{randomness}{time.time()}".encode()
+            return "0x" + hashlib.sha256(tx_data).hexdigest()
+
+        # Create contract instance
+        contract = self.web3.eth.contract(
+            address=self.web3.to_checksum_address(contract_address),
+            abi=self.ORACLE_ABI
+        )
+
+        # Encode function call
+        request_id_bytes = self.web3.to_bytes(hexstr=request_id) if request_id.startswith('0x') else self.web3.to_bytes(text=request_id)
+        randomness_int = int(randomness, 16) if randomness.startswith('0x') else int(randomness, 16)
+
+        data = contract.functions.reveal(request_id_bytes, randomness_int).build_transaction({
+            'from': self.account.address,
+            'gas': 0,
+            'gasPrice': await self.get_gas_price(),
+            'nonce': self.web3.eth.get_transaction_count(self.account.address, 'pending'),
+            'chainId': self.config.chain_id
+        })
+
+        return await self.submit_transaction(
+            contract_address,
+            data['data'],
+            0,
+            data['gas']
+        )
+
+    async def get_contract_balance(self, contract_address: str) -> int:
+        """Get contract balance in wei"""
+        if not WEB3_AVAILABLE:
+            return 0
+
+        address = self.web3.to_checksum_address(contract_address)
+        balance = self.web3.eth.get_balance(address)
+        return balance
+
+    async def get_block_number(self) -> int:
+        """Get current block number"""
+        if not WEB3_AVAILABLE:
+            return 0
+
+        return self.web3.eth.block_number

app/blockchain/fantom.py

@@ -0,0 +1,40 @@
+"""
+QCrypt RNG - Fantom Opera Adapter
+
+Provides Fantom Opera network support for oracle fulfillment.
+"""
+
+from typing import Optional
+from .base import ChainConfig
+from .ethereum import EthereumAdapter
+
+
+class FantomAdapter(EthereumAdapter):
+    """
+    Fantom Opera adapter
+
+    Fantom is an EVM-compatible chain with fast finality and low fees.
+    """
+
+    # Fantom-specific RPC endpoints
+    FANTOM_RPC_URLS = [
+        "https://rpc.ftm.tools",
+        "https://fantom-mainnet.publicnode.com"
+    ]
+
+    def __init__(self, config: Optional[ChainConfig] = None):
+        if config is None:
+            config = ChainConfig(
+                rpc_url=self.FANTOM_RPC_URLS[0],
+                chain_id=250,
+                explorer_url="https://ftmscan.com",
+                currency_symbol="FTM",
+                confirmations_required=10  # Fantom has ~1 second block times
+            )
+        super().__init__(config)
+
+    async def get_gas_price(self) -> int:
+        """Get current gas price in wei (FTM)"""
+        gas_price = await super().get_gas_price()
+        # Fantom gas prices are typically very low
+        return max(gas_price, 10_000_000_000)  # 10 gwei minimum

app/blockchain/oracle_service.py

@@ -0,0 +1,304 @@
+"""
+QCrypt RNG - Oracle Fulfillment Service
+
+Handles on-chain fulfillment of oracle requests across multiple blockchains.
+"""
+
+from typing import Dict, Any, Optional, List
+from dataclasses import dataclass, field
+import asyncio
+import time
+import hashlib
+from enum import Enum
+
+from .base import ChainConfig, TransactionStatus, TransactionReceipt
+from . import get_chain_adapter, get_supported_chains
+from app.quantum.qrng import get_quantum_rng
+from app.quantum.commitment import compute_commitment_hex
+from app.utils.logging import logger
+
+
+class FulfillmentStatus(Enum):
+    """Oracle request fulfillment status"""
+    PENDING = "pending"
+    COMMIT_SUBMITTED = "commit_submitted"
+    COMMIT_CONFIRMED = "commit_confirmed"
+    REVEAL_SUBMITTED = "reveal_submitted"
+    REVEAL_CONFIRMED = "reveal_confirmed"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+@dataclass
+class OracleRequest:
+    """Oracle request details"""
+    request_id: str
+    chain: str
+    contract_address: str
+    num_bytes: int
+    num_qubits: int
+    status: FulfillmentStatus = FulfillmentStatus.PENDING
+    commitment: Optional[str] = None
+    randomness: Optional[str] = None
+    commit_tx_hash: Optional[str] = None
+    reveal_tx_hash: Optional[str] = None
+    created_at: float = field(default_factory=time.time)
+    updated_at: float = field(default_factory=time.time)
+    error: Optional[str] = None
+
+
+class OracleFulfillmentService:
+    """
+    Oracle Fulfillment Service
+
+    Manages the lifecycle of oracle requests from creation to on-chain fulfillment.
+    """
+
+    def __init__(self):
+        self.requests: Dict[str, OracleRequest] = {}
+        self.chain_adapters: Dict[str, Any] = {}
+        self.qrng = get_quantum_rng()
+        self._processing = False
+
+    def configure_chain(self, chain_name: str, config: ChainConfig) -> bool:
+        """
+        Configure a chain adapter
+
+        Args:
+            chain_name: Blockchain name (ethereum, polygon, bsc, avalanche, fantom)
+            config: Chain configuration
+
+        Returns:
+            True if successful
+        """
+        try:
+            adapter = get_chain_adapter(chain_name, config)
+            self.chain_adapters[chain_name.lower()] = adapter
+            logger.info(f"Configured chain adapter for {chain_name}")
+            return True
+        except Exception as e:
+            logger.error(f"Failed to configure chain adapter for {chain_name}: {e}")
+            return False
+
+    async def create_request(
+        self,
+        chain: str,
+        contract_address: str,
+        num_bytes: int = 32,
+        num_qubits: int = 16
+    ) -> OracleRequest:
+        """
+        Create a new oracle request
+
+        Args:
+            chain: Target blockchain
+            contract_address: Oracle contract address
+            num_bytes: Number of random bytes to generate
+            num_qubits: Number of qubits to measure
+
+        Returns:
+            OracleRequest object
+        """
+        request_id = f"oracle_{chain}_{int(time.time() * 1000000)}"
+
+        request = OracleRequest(
+            request_id=request_id,
+            chain=chain.lower(),
+            contract_address=contract_address,
+            num_bytes=num_bytes,
+            num_qubits=num_qubits
+        )
+
+        self.requests[request_id] = request
+        logger.info(f"Created oracle request: {request_id} on {chain}")
+
+        return request
+
+    async def fulfill_request(self, request_id: str) -> bool:
+        """
+        Fulfill an oracle request (commit and reveal)
+
+        Args:
+            request_id: Request ID to fulfill
+
+        Returns:
+            True if successful
+        """
+        if request_id not in self.requests:
+            logger.error(f"Request not found: {request_id}")
+            return False
+
+        request = self.requests[request_id]
+        chain = request.chain
+
+        if chain not in self.chain_adapters:
+            request.error = f"Chain adapter not configured for {chain}"
+            request.status = FulfillmentStatus.FAILED
+            logger.error(request.error)
+            return False
+
+        adapter = self.chain_adapters[chain]
+
+        try:
+            # Step 1: Generate quantum randomness
+            logger.info(f"Generating quantum randomness for {request_id}")
+            quantum_result = await self.qrng.generate_bytes(
+                request.num_bytes,
+                request.num_qubits,
+                "raw"
+            )
+
+            randomness_hex = "0x" + quantum_result.data.hex()
+            request.randomness = randomness_hex
+
+            # Step 2: Create commitment
+            commitment = compute_commitment_hex(quantum_result.data)
+            request.commitment = commitment
+            logger.info(f"Created commitment for {request_id}: {commitment[:16]}...")
+
+            # Step 3: Submit commit transaction
+            logger.info(f"Submitting commit transaction for {request_id}")
+            commit_tx_hash = await adapter.commit_randomness(
+                request.contract_address,
+                request.request_id,
+                commitment
+            )
+            request.commit_tx_hash = commit_tx_hash
+            request.status = FulfillmentStatus.COMMIT_SUBMITTED
+            request.updated_at = time.time()
+            logger.info(f"Commit transaction submitted: {commit_tx_hash}")
+
+            # Step 4: Wait for commit confirmation
+            logger.info(f"Waiting for commit confirmation for {request_id}")
+            commit_receipt = await adapter.wait_for_confirmation(commit_tx_hash)
+
+            if commit_receipt.status != TransactionStatus.CONFIRMED:
+                raise Exception(f"Commit transaction failed: {commit_receipt.error}")
+
+            request.status = FulfillmentStatus.COMMIT_CONFIRMED
+            request.updated_at = time.time()
+            logger.info(f"Commit confirmed for {request_id}")
+
+            # Step 5: Submit reveal transaction
+            logger.info(f"Submitting reveal transaction for {request_id}")
+            reveal_tx_hash = await adapter.reveal_randomness(
+                request.contract_address,
+                request.request_id,
+                randomness_hex
+            )
+            request.reveal_tx_hash = reveal_tx_hash
+            request.status = FulfillmentStatus.REVEAL_SUBMITTED
+            request.updated_at = time.time()
+            logger.info(f"Reveal transaction submitted: {reveal_tx_hash}")
+
+            # Step 6: Wait for reveal confirmation
+            logger.info(f"Waiting for reveal confirmation for {request_id}")
+            reveal_receipt = await adapter.wait_for_confirmation(reveal_tx_hash)
+
+            if reveal_receipt.status != TransactionStatus.CONFIRMED:
+                raise Exception(f"Reveal transaction failed: {reveal_receipt.error}")
+
+            request.status = FulfillmentStatus.REVEAL_CONFIRMED
+            request.updated_at = time.time()
+
+            # Step 7: Mark as completed
+            request.status = FulfillmentStatus.COMPLETED
+            request.updated_at = time.time()
+            logger.info(f"Oracle request completed: {request_id}")
+
+            return True
+
+        except Exception as e:
+            request.error = str(e)
+            request.status = FulfillmentStatus.FAILED
+            request.updated_at = time.time()
+            logger.error(f"Failed to fulfill oracle request {request_id}: {e}")
+            return False
+
+    async def fulfill_request_async(self, request_id: str) -> None:
+        """
+        Fulfill an oracle request asynchronously (non-blocking)
+
+        Args:
+            request_id: Request ID to fulfill
+        """
+        asyncio.create_task(self.fulfill_request(request_id))
+
+    def get_request_status(self, request_id: str) -> Optional[Dict[str, Any]]:
+        """
+        Get the status of an oracle request
+
+        Args:
+            request_id: Request ID
+
+        Returns:
+            Request status dictionary
+        """
+        if request_id not in self.requests:
+            return None
+
+        request = self.requests[request_id]
+        adapter = self.chain_adapters.get(request.chain)
+
+        status_data = {
+            "request_id": request.request_id,
+            "chain": request.chain,
+            "contract_address": request.contract_address,
+            "status": request.status.value,
+            "num_bytes": request.num_bytes,
+            "num_qubits": request.num_qubits,
+            "commitment": request.commitment,
+            "randomness": request.randomness,
+            "commit_tx_hash": request.commit_tx_hash,
+            "reveal_tx_hash": request.reveal_tx_hash,
+            "created_at": request.created_at,
+            "updated_at": request.updated_at,
+            "error": request.error
+        }
+
+        if adapter:
+            status_data["explorer_urls"] = {
+                "commit": adapter.get_explorer_url(request.commit_tx_hash) if request.commit_tx_hash else None,
+                "reveal": adapter.get_explorer_url(request.reveal_tx_hash) if request.reveal_tx_hash else None
+            }
+
+        return status_data
+
+    def get_all_requests(self) -> List[Dict[str, Any]]:
+        """Get all oracle requests"""
+        return [
+            self.get_request_status(request_id)
+            for request_id in self.requests
+        ]
+
+    async def get_chain_info(self, chain_name: str) -> Optional[Dict[str, Any]]:
+        """
+        Get information about a configured chain
+
+        Args:
+            chain_name: Blockchain name
+
+        Returns:
+            Chain information dictionary
+        """
+        adapter = self.chain_adapters.get(chain_name.lower())
+        if not adapter:
+            return None
+
+        return await adapter.get_chain_info()
+
+    def get_supported_chains(self) -> Dict[str, Any]:
+        """Get list of supported chains"""
+        return get_supported_chains()
+
+
+# Global service instance
+_oracle_service: Optional[OracleFulfillmentService] = None
+
+
+def get_oracle_fulfillment_service() -> OracleFulfillmentService:
+    """Get the global oracle fulfillment service instance"""
+    global _oracle_service
+    if _oracle_service is None:
+        _oracle_service = OracleFulfillmentService()
+    return _oracle_service

app/blockchain/polygon.py

@@ -0,0 +1,60 @@
+"""
+QCrypt RNG - Polygon Chain Adapter
+
+Provides Polygon network support for oracle fulfillment.
+"""
+
+from typing import Optional
+from .base import ChainConfig, TransactionReceipt, TransactionStatus
+from .ethereum import EthereumAdapter
+
+
+class PolygonAdapter(EthereumAdapter):
+    """
+    Polygon chain adapter
+
+    Polygon is an Ethereum-compatible sidechain with lower fees and faster transactions.
+    """
+
+    # Polygon-specific RPC endpoints
+    POLYGON_RPC_URLS = [
+        "https://polygon-rpc.com",
+        "https://rpc-mainnet.matic.network",
+        "https://matic-mainnet.chainstacklabs.com"
+    ]
+
+    def __init__(self, config: Optional[ChainConfig] = None):
+        if config is None:
+            config = ChainConfig(
+                rpc_url=self.POLYGON_RPC_URLS[0],
+                chain_id=137,
+                explorer_url="https://polygonscan.com",
+                currency_symbol="MATIC",
+                confirmations_required=10  # Polygon has faster block times
+            )
+        super().__init__(config)
+
+    async def get_gas_price(self) -> int:
+        """Get current gas price in wei (MATIC)"""
+        gas_price = await super().get_gas_price()
+        # Polygon gas prices are typically much lower
+        # Ensure minimum gas price
+        return max(gas_price, 30_000_000_000)  # 30 gwei minimum
+
+    async def commit_randomness(
+        self,
+        contract_address: str,
+        request_id: str,
+        commitment: str
+    ) -> str:
+        """Commit randomness to the oracle contract on Polygon"""
+        return await super().commit_randomness(contract_address, request_id, commitment)
+
+    async def reveal_randomness(
+        self,
+        contract_address: str,
+        request_id: str,
+        randomness: str
+    ) -> str:
+        """Reveal randomness to the oracle contract on Polygon"""
+        return await super().reveal_randomness(contract_address, request_id, randomness)

app/config.py

@@ -109,6 +109,40 @@ class Settings(BaseSettings):
     log_file: str = Field(default="logs/qcrypt.log", env="LOG_FILE")
     enable_detailed_logging: bool = Field(default=False, env="ENABLE_DETAILED_LOGGING")
 
+    # Oracle Contract Addresses (Testnets)
+    oracle_contract_sepolia: Optional[str] = Field(default=None, env="ORACLE_CONTRACT_SEPOLIA")
+    oracle_contract_polygon_amoy: Optional[str] = Field(default=None, env="ORACLE_CONTRACT_POLYGON_AMOY")
+    oracle_contract_bsc_testnet: Optional[str] = Field(default=None, env="ORACLE_CONTRACT_BSC_TESTNET")
+    oracle_contract_avalanche_fuji: Optional[str] = Field(default=None, env="ORACLE_CONTRACT_AVALANCHE_FUJI")
+    oracle_contract_fantom_testnet: Optional[str] = Field(default=None, env="ORACLE_CONTRACT_FANTOM_TESTNET")
+
+    # Testnet RPC Configuration
+    testnet_rpc_sepolia: str = Field(default="https://rpc.sepolia.org", env="TESTNET_RPC_SEPOLIA")
+    testnet_rpc_polygon_amoy: str = Field(default="https://rpc.amoy.polygon.technology", env="TESTNET_RPC_POLYGON_AMOY")
+    testnet_rpc_bsc_testnet: str = Field(default="https://data-seed-prebsc-1-s1.binance.org:8545", env="TESTNET_RPC_BSC_TESTNET")
+    testnet_rpc_avalanche_fuji: str = Field(default="https://api.avax-test.network/ext/bc/C/rpc", env="TESTNET_RPC_AVALANCHE_FUJI")
+    testnet_rpc_fantom_testnet: str = Field(default="https://rpc.testnet.fantom.network", env="TESTNET_RPC_FANTOM_TESTNET")
+
+    # Testnet Chain IDs
+    testnet_chain_id_sepolia: int = Field(default=11155111, env="TESTNET_CHAIN_ID_SEPOLIA")
+    testnet_chain_id_polygon_amoy: int = Field(default=80002, env="TESTNET_CHAIN_ID_POLYGON_AMOY")
+    testnet_chain_id_bsc_testnet: int = Field(default=97, env="TESTNET_CHAIN_ID_BSC_TESTNET")
+    testnet_chain_id_avalanche_fuji: int = Field(default=43113, env="TESTNET_CHAIN_ID_AVALANCHE_FUJI")
+    testnet_chain_id_fantom_testnet: int = Field(default=4002, env="TESTNET_CHAIN_ID_FANTOM_TESTNET")
+
+    # Testnet Explorer URLs
+    testnet_explorer_sepolia: str = Field(default="https://sepolia.etherscan.io", env="TESTNET_EXPLORER_SEPOLIA")
+    testnet_explorer_polygon_amoy: str = Field(default="https://amoy.polygonscan.com", env="TESTNET_EXPLORER_POLYGON_AMOY")
+    testnet_explorer_bsc_testnet: str = Field(default="https://testnet.bscscan.com", env="TESTNET_EXPLORER_BSC_TESTNET")
+    testnet_explorer_avalanche_fuji: str = Field(default="https://testnet.snowtrace.io", env="TESTNET_EXPLORER_AVALANCHE_FUJI")
+    testnet_explorer_fantom_testnet: str = Field(default="https://testnet.ftmscan.com", env="TESTNET_EXPLORER_FANTOM_TESTNET")
+
+    # Stripe Billing
+    stripe_secret_key: Optional[str] = Field(default=None, env="STRIPE_SECRET_KEY")
+    stripe_webhook_secret: Optional[str] = Field(default=None, env="STRIPE_WEBHOOK_SECRET")
+    stripe_price_id_pro: Optional[str] = Field(default=None, env="STRIPE_PRICE_ID_PRO")
+    stripe_price_id_enterprise: Optional[str] = Field(default=None, env="STRIPE_PRICE_ID_ENTERPRISE")
+
     # Performance Settings
     max_workers: int = Field(default=4, env="MAX_WORKERS")
     connection_pool_size: int = Field(default=20, env="CONNECTION_POOL_SIZE")
@@ -229,6 +263,56 @@ class Settings(BaseSettings):
         """Check if running in development environment"""
         return self.environment.lower() == "development"
 
+    @property
+    def testnet_oracle_config(self) -> dict:
+        """Get testnet oracle configuration"""
+        return {
+            "sepolia": {
+                "contract_address": self.oracle_contract_sepolia,
+                "rpc_url": self.testnet_rpc_sepolia,
+                "chain_id": self.testnet_chain_id_sepolia,
+                "explorer_url": self.testnet_explorer_sepolia,
+                "currency_symbol": "SepoliaETH"
+            },
+            "polygon_amoy": {
+                "contract_address": self.oracle_contract_polygon_amoy,
+                "rpc_url": self.testnet_rpc_polygon_amoy,
+                "chain_id": self.testnet_chain_id_polygon_amoy,
+                "explorer_url": self.testnet_explorer_polygon_amoy,
+                "currency_symbol": "MATIC"
+            },
+            "bsc_testnet": {
+                "contract_address": self.oracle_contract_bsc_testnet,
+                "rpc_url": self.testnet_rpc_bsc_testnet,
+                "chain_id": self.testnet_chain_id_bsc_testnet,
+                "explorer_url": self.testnet_explorer_bsc_testnet,
+                "currency_symbol": "tBNB"
+            },
+            "avalanche_fuji": {
+                "contract_address": self.oracle_contract_avalanche_fuji,
+                "rpc_url": self.testnet_rpc_avalanche_fuji,
+                "chain_id": self.testnet_chain_id_avalanche_fuji,
+                "explorer_url": self.testnet_explorer_avalanche_fuji,
+                "currency_symbol": "AVAX"
+            },
+            "fantom_testnet": {
+                "contract_address": self.oracle_contract_fantom_testnet,
+                "rpc_url": self.testnet_rpc_fantom_testnet,
+                "chain_id": self.testnet_chain_id_fantom_testnet,
+                "explorer_url": self.testnet_explorer_fantom_testnet,
+                "currency_symbol": "FTM"
+            }
+        }
+
+    def get_testnet_oracle_config(self, network: str) -> dict:
+        """Get configuration for a specific testnet"""
+        config = self.testnet_oracle_config.get(network.lower())
+        if not config:
+            raise ValueError(f"Unknown testnet: {network}")
+        if not config["contract_address"]:
+            raise ValueError(f"Contract address not configured for {network}")
+        return config
+
     def generate_secure_secret_key(self) -> str:
         """Generate a secure secret key for production use"""
         return secrets.token_urlsafe(32)

app/monitoring/__init__.py

@@ -0,0 +1,46 @@
+"""
+QCrypt RNG - Monitoring Module
+
+Provides Prometheus metrics and observability features.
+"""
+
+from .metrics import (
+    # Metric recorders
+    OracleMetrics,
+    PQCMetrics,
+    QRNGMetrics,
+    HardwareMetrics,
+    EntropyMetrics,
+    APIMetrics,
+    
+    # Utility functions
+    get_metrics,
+    get_metrics_content_type,
+    start_metrics_server,
+    setup_system_info,
+    initialize_multiprocess_mode,
+    
+    # Decorators
+    track_pqc_operation,
+    track_api_request,
+    
+    # Registry
+    registry,
+)
+
+__all__ = [
+    'OracleMetrics',
+    'PQCMetrics',
+    'QRNGMetrics',
+    'HardwareMetrics',
+    'EntropyMetrics',
+    'APIMetrics',
+    'get_metrics',
+    'get_metrics_content_type',
+    'start_metrics_server',
+    'setup_system_info',
+    'initialize_multiprocess_mode',
+    'track_pqc_operation',
+    'track_api_request',
+    'registry',
+]

app/monitoring/alerting-rules.yml

@@ -0,0 +1,271 @@
+# QCrypt RNG Prometheus Alerting Rules
+# Reference: docs/MONITORING_GUIDE.md
+
+groups:
+  - name: qcrypt_rng_alerts
+    interval: 30s
+    rules:
+      # ========================================================================
+      # Oracle Fulfillment Alerts
+      # ========================================================================
+
+      - alert: OracleFulfillmentHighFailureRate
+        expr: |
+          sum(rate(qcrypt_oracle_requests_total{status="error"}[5m]))
+          /
+          sum(rate(qcrypt_oracle_requests_total[5m])) > 0.1
+        for: 5m
+        labels:
+          severity: critical
+          category: oracle
+        annotations:
+          summary: "High oracle fulfillment failure rate"
+          description: "Oracle failure rate is {{ $value | humanizePercentage }} over the last 5 minutes"
+          runbook_url: "https://github.com/quantumGlobalGroup/qcrypt-rng/blob/main/docs/MONITORING_GUIDE.md#oracle-fulfillment-alerts"
+
+      - alert: OracleFulfillmentHighLatency
+        expr: |
+          histogram_quantile(0.95, rate(qcrypt_oracle_fulfillment_duration_seconds_bucket[5m])) > 30
+        for: 5m
+        labels:
+          severity: warning
+          category: oracle
+        annotations:
+          summary: "High oracle fulfillment latency"
+          description: "95th percentile fulfillment duration is {{ $value }}s on chain {{ $labels.chain }}"
+          runbook_url: "https://github.com/quantumGlobalGroup/qcrypt-rng/blob/main/docs/MONITORING_GUIDE.md#oracle-fulfillment-alerts"
+
+      - alert: OracleNoSuccessfulFulfillments
+        expr: |
+          sum(rate(qcrypt_oracle_requests_total{status="success"}[10m])) == 0
+          and
+          sum(rate(qcrypt_oracle_requests_total[10m])) > 0
+        for: 10m
+        labels:
+          severity: critical
+          category: oracle
+        annotations:
+          summary: "No successful oracle fulfillments in 10 minutes"
+          description: "All oracle requests are failing. Check blockchain connectivity and private keys."
+          runbook_url: "https://github.com/quantumGlobalGroup/qcrypt-rng/blob/main/docs/MONITORING_GUIDE.md#oracle-fulfillment-alerts"
+
+      # ========================================================================
+      # Entropy Quality Alerts
+      # ========================================================================
+
+      - alert: EntropyQualityPoor
+        expr: qcrypt_entropy_shannon_entropy < 7.5
+        for: 2m
+        labels:
+          severity: warning
+          category: entropy
+        annotations:
+          summary: "Low entropy quality detected"
+          description: "Shannon entropy is {{ $value }} bits/byte (threshold: 7.5)"
+          runbook_url: "https://github.com/quantumGlobalGroup/qcrypt-rng/blob/main/docs/MONITORING_GUIDE.md#entropy-quality-alerts"
+
+      - alert: EntropyQualityCritical
+        expr: qcrypt_entropy_shannon_entropy < 7.0
+        for: 1m
+        labels:
+          severity: critical
+          category: entropy
+        annotations:
+          summary: "Critical entropy quality issue"
+          description: "Shannon entropy is {{ $value }} bits/byte - randomness may be compromised"
+          runbook_url: "https://github.com/quantumGlobalGroup/qcrypt-rng/blob/main/docs/MONITORING_GUIDE.md#entropy-quality-alerts"
+
+      - alert: EntropyMinEntropyLow
+        expr: qcrypt_entropy_min_entropy < 7.0
+        for: 2m
+        labels:
+          severity: warning
+          category: entropy
+        annotations:
+          summary: "Low min-entropy detected"
+          description: "Min-entropy is {{ $value }} bits/byte (threshold: 7.0)"
+          runbook_url: "https://github.com/quantumGlobalGroup/qcrypt-rng/blob/main/docs/MONITORING_GUIDE.md#entropy-quality-alerts"
+
+      - alert: EntropyQualityStatusPoor
+        expr: qcrypt_entropy_quality_status == 0
+        for: 1m
+        labels:
+          severity: critical
+          category: entropy
+        annotations:
+          summary: "Entropy quality status is POOR"
+          description: "Entropy quality check has failed. Immediate investigation required."
+          runbook_url: "https://github.com/quantumGlobalGroup/qcrypt-rng/blob/main/docs/MONITORING_GUIDE.md#entropy-quality-alerts"
+
+      # ========================================================================
+      # Hardware Device Alerts
+      # ========================================================================
+
+      - alert: HardwareDeviceOffline
+        expr: qcrypt_hardware_device_status == 0
+        for: 1m
+        labels:
+          severity: critical
+          category: hardware
+        annotations:
+          summary: "Hardware device offline"
+          description: "Device {{ $labels.device_id }} ({{ $labels.vendor }}) is not operational"
+          runbook_url: "https://github.com/quantumGlobalGroup/qcrypt-rng/blob/main/docs/MONITORING_GUIDE.md#hardware-device-alerts"
+
+      - alert: HardwareDeviceError
+        expr: qcrypt_hardware_device_status == -1
+        for: 1m
+        labels:
+          severity: critical
+          category: hardware
+        annotations:
+          summary: "Hardware device error"
+          description: "Device {{ $labels.device_id }} ({{ $labels.vendor }}) is in error state"
+          runbook_url: "https://github.com/quantumGlobalGroup/qcrypt-rng/blob/main/docs/MONITORING_GUIDE.md#hardware-device-alerts"
+
+      - alert: HardwareHighErrorRate
+        expr: qcrypt_hardware_error_rate > 0.05
+        for: 5m
+        labels:
+          severity: warning
+          category: hardware
+        annotations:
+          summary: "High hardware error rate"
+          description: "Device {{ $labels.device_id }} has error rate of {{ $value | humanizePercentage }}"
+          runbook_url: "https://github.com/quantumGlobalGroup/qcrypt-rng/blob/main/docs/MONITORING_GUIDE.md#hardware-device-alerts"
+
+      - alert: HardwareHighTemperature
+        expr: qcrypt_hardware_temperature_celsius > 60
+        for: 5m
+        labels:
+          severity: warning
+          category: hardware
+        annotations:
+          summary: "Hardware device high temperature"
+          description: "Device {{ $labels.device_id }} temperature is {{ $value }}°C"
+          runbook_url: "https://github.com/quantumGlobalGroup/qcrypt-rng/blob/main/docs/MONITORING_GUIDE.md#hardware-device-alerts"
+
+      # ========================================================================
+      # PQC Operation Alerts
+      # ========================================================================
+
+      - alert: PQCHighFailureRate
+        expr: |
+          sum(rate(qcrypt_pqc_operations_total{status="error"}[5m]))
+          /
+          sum(rate(qcrypt_pqc_operations_total[5m])) > 0.05
+        for: 5m
+        labels:
+          severity: warning
+          category: pqc
+        annotations:
+          summary: "High PQC operation failure rate"
+          description: "PQC failure rate is {{ $value | humanizePercentage }} for algorithm {{ $labels.algorithm }}"
+          runbook_url: "https://github.com/quantumGlobalGroup/qcrypt-rng/blob/main/docs/MONITORING_GUIDE.md#pqc-operation-alerts"
+
+      - alert: PQCHighLatency
+        expr: |
+          histogram_quantile(0.99, rate(qcrypt_pqc_operation_duration_seconds_bucket{operation="generate_keypair"}[5m])) > 1
+        for: 5m
+        labels:
+          severity: warning
+          category: pqc
+        annotations:
+          summary: "High PQC key generation latency"
+          description: "99th percentile key generation duration is {{ $value }}s for {{ $labels.algorithm }}"
+          runbook_url: "https://github.com/quantumGlobalGroup/qcrypt-rng/blob/main/docs/MONITORING_GUIDE.md#pqc-operation-alerts"
+
+      # ========================================================================
+      # API Performance Alerts
+      # ========================================================================
+
+      - alert: APILatencyHigh
+        expr: |
+          histogram_quantile(0.95, rate(qcrypt_api_request_duration_seconds_bucket[5m])) > 1
+        for: 5m
+        labels:
+          severity: warning
+          category: api
+        annotations:
+          summary: "High API latency"
+          description: "95th percentile API latency is {{ $value }}s for endpoint {{ $labels.endpoint }}"
+          runbook_url: "https://github.com/quantumGlobalGroup/qcrypt-rng/blob/main/docs/MONITORING_GUIDE.md#api-performance-alerts"
+
+      - alert: APIHighErrorRate
+        expr: |
+          sum(rate(qcrypt_api_requests_total{status="error"}[5m]))
+          /
+          sum(rate(qcrypt_api_requests_total[5m])) > 0.05
+        for: 5m
+        labels:
+          severity: warning
+          category: api
+        annotations:
+          summary: "High API error rate"
+          description: "API error rate is {{ $value | humanizePercentage }} for endpoint {{ $labels.endpoint }}"
+          runbook_url: "https://github.com/quantumGlobalGroup/qcrypt-rng/blob/main/docs/MONITORING_GUIDE.md#api-performance-alerts"
+
+      # ========================================================================
+      # System Resource Alerts
+      # ========================================================================
+
+      - alert: SystemCPUHigh
+        expr: qcrypt_system_cpu_usage_percent > 80
+        for: 5m
+        labels:
+          severity: warning
+          category: system
+        annotations:
+          summary: "High CPU usage"
+          description: "CPU usage is {{ $value }}%"
+          runbook_url: "https://github.com/quantumGlobalGroup/qcrypt-rng/blob/main/docs/MONITORING_GUIDE.md#system-resource-alerts"
+
+      - alert: SystemCPUCritical
+        expr: qcrypt_system_cpu_usage_percent > 95
+        for: 2m
+        labels:
+          severity: critical
+          category: system
+        annotations:
+          summary: "Critical CPU usage"
+          description: "CPU usage is {{ $value }}% - system may be unresponsive"
+          runbook_url: "https://github.com/quantumGlobalGroup/qcrypt-rng/blob/main/docs/MONITORING_GUIDE.md#system-resource-alerts"
+
+      - alert: SystemMemoryHigh
+        expr: |
+          qcrypt_system_memory_usage_bytes / (1024 * 1024 * 1024) > 7
+        for: 5m
+        labels:
+          severity: warning
+          category: system
+        annotations:
+          summary: "High memory usage"
+          description: "Memory usage exceeds 7GB ({{ $value | humanize }}B)"
+          runbook_url: "https://github.com/quantumGlobalGroup/qcrypt-rng/blob/main/docs/MONITORING_GUIDE.md#system-resource-alerts"
+
+      # ========================================================================
+      # QRNG Generation Alerts
+      # ========================================================================
+
+      - alert: QRNGNoGeneration
+        expr: rate(qcrypt_qrng_bytes_generated_total[5m]) == 0
+        for: 5m
+        labels:
+          severity: warning
+          category: qrng
+        annotations:
+          summary: "No QRNG bytes generated in 5 minutes"
+          description: "Quantum randomness generation may be stalled"
+          runbook_url: "https://github.com/quantumGlobalGroup/qcrypt-rng/blob/main/docs/MONITORING_GUIDE.md#qrng-generation-alerts"
+
+      - alert: QRNGHighLatency
+        expr: |
+          histogram_quantile(0.95, rate(qcrypt_qrng_generation_duration_seconds_bucket[5m])) > 0.5
+        for: 5m
+        labels:
+          severity: warning
+          category: qrng
+        annotations:
+          summary: "High QRNG generation latency"
+          description: "95th percentile generation duration is {{ $value }}s"
+          runbook_url: "https://github.com/quantumGlobalGroup/qcrypt-rng/blob/main/docs/MONITORING_GUIDE.md#qrng-generation-alerts"

app/monitoring/grafana-dashboard.json

@@ -0,0 +1,589 @@
+{
+  "annotations": {
+    "list": []
+  },
+  "editable": true,
+  "fiscalYearStartMonth": 0,
+  "graphTooltip": 0,
+  "id": null,
+  "links": [],
+  "liveNow": false,
+  "panels": [
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "${datasource}"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "palette-classic"
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              }
+            ]
+          },
+          "unit": "bytes"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 0
+      },
+      "id": 1,
+      "options": {
+        "legend": {
+          "calcs": [],
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "single"
+        }
+      },
+      "targets": [
+        {
+          "expr": "rate(qcrypt_qrng_bytes_generated_total[5m])",
+          "legendFormat": "{{backend}}",
+          "refId": "A"
+        }
+      ],
+      "title": "QRNG Bytes Generated/sec",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "${datasource}"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "palette-classic"
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              },
+              {
+                "color": "yellow",
+                "value": 7.5
+              },
+              {
+                "color": "red",
+                "value": 7.0
+              }
+            ]
+          },
+          "unit": "bits"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 0
+      },
+      "id": 2,
+      "options": {
+        "legend": {
+          "calcs": [],
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "single"
+        }
+      },
+      "targets": [
+        {
+          "expr": "qcrypt_entropy_shannon_entropy",
+          "legendFormat": "Shannon ({{source}})",
+          "refId": "A"
+        },
+        {
+          "expr": "qcrypt_entropy_min_entropy",
+          "legendFormat": "Min ({{source}})",
+          "refId": "B"
+        }
+      ],
+      "title": "Entropy Quality",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "${datasource}"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "palette-classic"
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              }
+            ]
+          },
+          "unit": "percentunit"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 8
+      },
+      "id": 3,
+      "options": {
+        "legend": {
+          "calcs": [],
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "single"
+        }
+      },
+      "targets": [
+        {
+          "expr": "sum(rate(qcrypt_oracle_requests_total{status=\"success\"}[5m])) / sum(rate(qcrypt_oracle_requests_total[5m]))",
+          "legendFormat": "Success Rate",
+          "refId": "A"
+        }
+      ],
+      "title": "Oracle Fulfillment Success Rate",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "${datasource}"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "palette-classic"
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              }
+            ]
+          },
+          "unit": "s"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 8
+      },
+      "id": 4,
+      "options": {
+        "legend": {
+          "calcs": [],
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "single"
+        }
+      },
+      "targets": [
+        {
+          "expr": "histogram_quantile(0.95, rate(qcrypt_oracle_fulfillment_duration_seconds_bucket[5m]))",
+          "legendFormat": "95th percentile ({{chain}})",
+          "refId": "A"
+        }
+      ],
+      "title": "Oracle Fulfillment Duration (95th percentile)",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "${datasource}"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "palette-classic"
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              }
+            ]
+          },
+          "unit": "ops"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 16
+      },
+      "id": 5,
+      "options": {
+        "legend": {
+          "calcs": [],
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "single"
+        }
+      },
+      "targets": [
+        {
+          "expr": "sum(rate(qcrypt_pqc_operations_total{operation=\"generate_keypair\"}[5m])) by (algorithm)",
+          "legendFormat": "{{algorithm}}",
+          "refId": "A"
+        }
+      ],
+      "title": "PQC Key Generation Rate",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "${datasource}"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "palette-classic"
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              }
+            ]
+          },
+          "unit": "s"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 16
+      },
+      "id": 6,
+      "options": {
+        "legend": {
+          "calcs": [],
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "single"
+        }
+      },
+      "targets": [
+        {
+          "expr": "histogram_quantile(0.95, rate(qcrypt_pqc_operation_duration_seconds_bucket{operation=\"generate_keypair\"}[5m]))",
+          "legendFormat": "{{algorithm}}",
+          "refId": "A"
+        }
+      ],
+      "title": "PQC Key Generation Duration (95th percentile)",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "${datasource}"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "palette-classic"
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              },
+              {
+                "color": "red",
+                "value": 0
+              }
+            ]
+          }
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 24
+      },
+      "id": 7,
+      "options": {
+        "legend": {
+          "calcs": [],
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "single"
+        }
+      },
+      "targets": [
+        {
+          "expr": "qcrypt_hardware_device_status",
+          "legendFormat": "{{device_id}} ({{vendor}})",
+          "refId": "A"
+        }
+      ],
+      "title": "Hardware Device Status",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "${datasource}"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "palette-classic"
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              },
+              {
+                "color": "yellow",
+                "value": 50
+              },
+              {
+                "color": "red",
+                "value": 80
+              }
+            ]
+          },
+          "unit": "percent"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 24
+      },
+      "id": 8,
+      "options": {
+        "legend": {
+          "calcs": [],
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "single"
+        }
+      },
+      "targets": [
+        {
+          "expr": "qcrypt_system_cpu_usage_percent",
+          "legendFormat": "CPU",
+          "refId": "A"
+        },
+        {
+          "expr": "qcrypt_system_memory_usage_bytes / (1024 * 1024 * 1024) * 100 / 8",
+          "legendFormat": "Memory (estimated %)",
+          "refId": "B"
+        }
+      ],
+      "title": "System Resources",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "${datasource}"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "palette-classic"
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              }
+            ]
+          },
+          "unit": "ops"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 32
+      },
+      "id": 9,
+      "options": {
+        "legend": {
+          "calcs": [],
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "single"
+        }
+      },
+      "targets": [
+        {
+          "expr": "sum(rate(qcrypt_api_requests_total[5m])) by (endpoint)",
+          "legendFormat": "{{endpoint}}",
+          "refId": "A"
+        }
+      ],
+      "title": "API Request Rate",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "${datasource}"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "palette-classic"
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              }
+            ]
+          },
+          "unit": "s"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 32
+      },
+      "id": 10,
+      "options": {
+        "legend": {
+          "calcs": [],
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "single"
+        }
+      },
+      "targets": [
+        {
+          "expr": "histogram_quantile(0.99, rate(qcrypt_api_request_duration_seconds_bucket[5m]))",
+          "legendFormat": "{{endpoint}}",
+          "refId": "A"
+        }
+      ],
+      "title": "API Latency (99th percentile)",
+      "type": "timeseries"
+    }
+  ],
+  "refresh": "15s",
+  "schemaVersion": 38,
+  "style": "dark",
+  "tags": [
+    "qcrypt",
+    "quantum",
+    "cryptography"
+  ],
+  "templating": {
+    "list": [
+      {
+        "current": {},
+        "hide": 0,
+        "includeAll": false,
+        "label": "Datasource",
+        "multi": false,
+        "name": "datasource",
+        "options": [],
+        "query": "prometheus",
+        "queryValue": "",
+        "refresh": 1,
+        "regex": "",
+        "skipUrlSync": false,
+        "type": "datasource"
+      }
+    ]
+  },
+  "time": {
+    "from": "now-1h",
+    "to": "now"
+  },
+  "timepicker": {},
+  "timezone": "",
+  "title": "QCrypt RNG Monitoring",
+  "uid": "qcrypt-rng-monitoring",
+  "version": 1,
+  "weekStart": ""
+}

app/monitoring/metrics.py

@@ -0,0 +1,581 @@
+"""
+QCrypt RNG - Monitoring and Observability Module
+
+Provides Prometheus metrics for:
+- Oracle fulfillment (latency, success/failure, per-chain)
+- PQC operations (key generation, sign/verify, KEM)
+- Quantum randomness generation
+- Entropy quality
+- Hardware status
+- API performance
+"""
+
+from prometheus_client import (
+    Counter,
+    Histogram,
+    Gauge,
+    Summary,
+    CollectorRegistry,
+    generate_latest,
+    CONTENT_TYPE_LATEST,
+    start_http_server,
+    multiprocess,
+    CollectorRegistry
+)
+from prometheus_client.multiprocess import MultiProcessCollector
+import time
+import os
+from typing import Optional, Dict, Any
+from functools import wraps
+import asyncio
+
+
+# ============================================================================
+# Metric Definitions
+# ============================================================================
+
+# Registry
+registry = CollectorRegistry()
+
+# ----------------------------------------------------------------------------
+# Oracle Fulfillment Metrics
+# ----------------------------------------------------------------------------
+
+oracle_requests_total = Counter(
+    'qcrypt_oracle_requests_total',
+    'Total number of oracle requests',
+    ['chain', 'status'],
+    registry=registry
+)
+
+oracle_fulfillment_duration = Histogram(
+    'qcrypt_oracle_fulfillment_duration_seconds',
+    'Time spent fulfilling oracle requests',
+    ['chain', 'status'],
+    buckets=(0.1, 0.5, 1.0, 2.0, 5.0, 10.0, 30.0, 60.0, float('inf')),
+    registry=registry
+)
+
+oracle_commit_duration = Histogram(
+    'qcrypt_oracle_commit_duration_seconds',
+    'Time spent in commit phase',
+    ['chain'],
+    buckets=(0.1, 0.5, 1.0, 2.0, 5.0, 10.0, float('inf')),
+    registry=registry
+)
+
+oracle_reveal_duration = Histogram(
+    'qcrypt_oracle_reveal_duration_seconds',
+    'Time spent in reveal phase',
+    ['chain'],
+    buckets=(0.1, 0.5, 1.0, 2.0, 5.0, 10.0, float('inf')),
+    registry=registry
+)
+
+oracle_transactions_total = Counter(
+    'qcrypt_oracle_transactions_total',
+    'Total number of blockchain transactions',
+    ['chain', 'type', 'status'],
+    registry=registry
+)
+
+oracle_gas_used = Histogram(
+    'qcrypt_oracle_gas_used',
+    'Gas used for oracle transactions',
+    ['chain', 'type'],
+    buckets=(10000, 50000, 100000, 200000, 500000, 1000000, float('inf')),
+    registry=registry
+)
+
+oracle_active_requests = Gauge(
+    'qcrypt_oracle_active_requests',
+    'Number of active oracle requests',
+    ['chain'],
+    registry=registry
+)
+
+# ----------------------------------------------------------------------------
+# PQC Operation Metrics
+# ----------------------------------------------------------------------------
+
+pqc_operations_total = Counter(
+    'qcrypt_pqc_operations_total',
+    'Total number of PQC operations',
+    ['algorithm', 'operation', 'status'],
+    registry=registry
+)
+
+pqc_operation_duration = Histogram(
+    'qcrypt_pqc_operation_duration_seconds',
+    'Time spent on PQC operations',
+    ['algorithm', 'operation'],
+    buckets=(0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1.0, float('inf')),
+    registry=registry
+)
+
+pqc_key_sizes = Histogram(
+    'qcrypt_pqc_key_size_bytes',
+    'Size of generated PQC keys',
+    ['algorithm', 'key_type'],
+    buckets=(64, 128, 256, 512, 1024, 2048, 4096, 8192, float('inf')),
+    registry=registry
+)
+
+pqc_signature_sizes = Histogram(
+    'qcrypt_pqc_signature_size_bytes',
+    'Size of PQC signatures',
+    ['algorithm'],
+    buckets=(256, 512, 1024, 2048, 4096, 8192, 16384, float('inf')),
+    registry=registry
+)
+
+pqc_kem_ciphertext_sizes = Histogram(
+    'qcrypt_pqc_kem_ciphertext_size_bytes',
+    'Size of KEM ciphertexts',
+    ['algorithm'],
+    buckets=(256, 512, 768, 1024, 1568, 2048, float('inf')),
+    registry=registry
+)
+
+pqc_kem_shared_secret_sizes = Histogram(
+    'qcrypt_pqc_kem_shared_secret_size_bytes',
+    'Size of KEM shared secrets',
+    ['algorithm'],
+    buckets=(16, 32, 64, 128, 256, float('inf')),
+    registry=registry
+)
+
+# ----------------------------------------------------------------------------
+# Quantum Randomness Generation Metrics
+# ----------------------------------------------------------------------------
+
+qrng_bytes_generated_total = Counter(
+    'qcrypt_qrng_bytes_generated_total',
+    'Total bytes of quantum randomness generated',
+    ['backend', 'format'],
+    registry=registry
+)
+
+qrng_generation_duration = Histogram(
+    'qcrypt_qrng_generation_duration_seconds',
+    'Time spent generating quantum randomness',
+    ['backend'],
+    buckets=(0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1.0, float('inf')),
+    registry=registry
+)
+
+qrng_entropy_bits = Gauge(
+    'qcrypt_qrng_entropy_bits',
+    'Current entropy bits in pool',
+    ['backend'],
+    registry=registry
+)
+
+qrng_quality_score = Gauge(
+    'qcrypt_qrng_quality_score',
+    'Quality score of quantum randomness (0-1)',
+    ['backend'],
+    registry=registry
+)
+
+# ----------------------------------------------------------------------------
+# Hardware Metrics
+# ----------------------------------------------------------------------------
+
+hardware_device_status = Gauge(
+    'qcrypt_hardware_device_status',
+    'Status of quantum hardware devices (1=operational, 0=disconnected, -1=error)',
+    ['device_id', 'device_type', 'vendor'],
+    registry=registry
+)
+
+hardware_generation_rate = Gauge(
+    'qcrypt_hardware_generation_rate_bps',
+    'Random bit generation rate (bits per second)',
+    ['device_id', 'device_type'],
+    registry=registry
+)
+
+hardware_error_rate = Gauge(
+    'qcrypt_hardware_error_rate',
+    'Error rate of quantum hardware device',
+    ['device_id', 'device_type'],
+    registry=registry
+)
+
+hardware_temperature = Gauge(
+    'qcrypt_hardware_temperature_celsius',
+    'Temperature of quantum hardware device',
+    ['device_id', 'device_type'],
+    registry=registry
+)
+
+hardware_uptime = Gauge(
+    'qcrypt_hardware_uptime_seconds',
+    'Uptime of quantum hardware device',
+    ['device_id', 'device_type'],
+    registry=registry
+)
+
+# ----------------------------------------------------------------------------
+# Entropy Quality Metrics
+# ----------------------------------------------------------------------------
+
+entropy_shannon_entropy = Gauge(
+    'qcrypt_entropy_shannon_entropy',
+    'Shannon entropy estimate (bits per byte)',
+    ['source'],
+    registry=registry
+)
+
+entropy_min_entropy = Gauge(
+    'qcrypt_entropy_min_entropy',
+    'Min-entropy estimate (bits per byte)',
+    ['source'],
+    registry=registry
+)
+
+entropy_chi_square = Gauge(
+    'qcrypt_entropy_chi_square',
+    'Chi-square statistic for uniformity test',
+    ['source'],
+    registry=registry
+)
+
+entropy_quality_status = Gauge(
+    'qcrypt_entropy_quality_status',
+    'Overall entropy quality status (1=GOOD, 0=POOR)',
+    ['source'],
+    registry=registry
+)
+
+# ----------------------------------------------------------------------------
+# API Performance Metrics
+# ----------------------------------------------------------------------------
+
+api_requests_total = Counter(
+    'qcrypt_api_requests_total',
+    'Total API requests',
+    ['endpoint', 'method', 'status'],
+    registry=registry
+)
+
+api_request_duration = Histogram(
+    'qcrypt_api_request_duration_seconds',
+    'API request duration',
+    ['endpoint', 'method'],
+    buckets=(0.01, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0, float('inf')),
+    registry=registry
+)
+
+api_request_size = Histogram(
+    'qcrypt_api_request_size_bytes',
+    'Size of API requests',
+    ['endpoint'],
+    buckets=(100, 500, 1000, 5000, 10000, 100000, float('inf')),
+    registry=registry
+)
+
+api_response_size = Histogram(
+    'qcrypt_api_response_size_bytes',
+    'Size of API responses',
+    ['endpoint'],
+    buckets=(100, 500, 1000, 5000, 10000, 100000, 1000000, float('inf')),
+    registry=registry
+)
+
+api_active_connections = Gauge(
+    'qcrypt_api_active_connections',
+    'Number of active API connections',
+    registry=registry
+)
+
+# ----------------------------------------------------------------------------
+# System Metrics
+# ----------------------------------------------------------------------------
+
+system_info = Gauge(
+    'qcrypt_system_info',
+    'System information',
+    ['version', 'environment', 'quantum_backend'],
+    registry=registry
+)
+
+system_memory_usage = Gauge(
+    'qcrypt_system_memory_usage_bytes',
+    'System memory usage',
+    registry=registry
+)
+
+system_cpu_usage = Gauge(
+    'qcrypt_system_cpu_usage_percent',
+    'System CPU usage percentage',
+    registry=registry
+)
+
+
+# ============================================================================
+# Metric Recording Functions
+# ============================================================================
+
+class OracleMetrics:
+    """Helper class for recording oracle metrics"""
+
+    @staticmethod
+    def record_request(chain: str, status: str = 'success'):
+        """Record an oracle request"""
+        oracle_requests_total.labels(chain=chain, status=status).inc()
+
+    @staticmethod
+    def record_fulfillment(chain: str, status: str, duration: float):
+        """Record fulfillment duration"""
+        oracle_fulfillment_duration.labels(chain=chain, status=status).observe(duration)
+
+    @staticmethod
+    def record_commit(chain: str, duration: float):
+        """Record commit phase duration"""
+        oracle_commit_duration.labels(chain=chain).observe(duration)
+
+    @staticmethod
+    def record_reveal(chain: str, duration: float):
+        """Record reveal phase duration"""
+        oracle_reveal_duration.labels(chain=chain).observe(duration)
+
+    @staticmethod
+    def record_transaction(chain: str, tx_type: str, status: str, gas_used: Optional[int] = None):
+        """Record a blockchain transaction"""
+        oracle_transactions_total.labels(chain=chain, type=tx_type, status=status).inc()
+        if gas_used:
+            oracle_gas_used.labels(chain=chain, type=tx_type).observe(gas_used)
+
+    @staticmethod
+    def update_active_requests(chain: str, count: int):
+        """Update active requests gauge"""
+        oracle_active_requests.labels(chain=chain).set(count)
+
+
+class PQCMetrics:
+    """Helper class for recording PQC metrics"""
+
+    @staticmethod
+    def record_operation(algorithm: str, operation: str, status: str, duration: float):
+        """Record a PQC operation"""
+        pqc_operations_total.labels(algorithm=algorithm, operation=operation, status=status).inc()
+        pqc_operation_duration.labels(algorithm=algorithm, operation=operation).observe(duration)
+
+    @staticmethod
+    def record_key_size(algorithm: str, key_type: str, size_bytes: int):
+        """Record key size"""
+        pqc_key_sizes.labels(algorithm=algorithm, key_type=key_type).observe(size_bytes)
+
+    @staticmethod
+    def record_signature_size(algorithm: str, size_bytes: int):
+        """Record signature size"""
+        pqc_signature_sizes.labels(algorithm=algorithm).observe(size_bytes)
+
+    @staticmethod
+    def record_kem_ciphertext_size(algorithm: str, size_bytes: int):
+        """Record KEM ciphertext size"""
+        pqc_kem_ciphertext_sizes.labels(algorithm=algorithm).observe(size_bytes)
+
+    @staticmethod
+    def record_kem_shared_secret_size(algorithm: str, size_bytes: int):
+        """Record KEM shared secret size"""
+        pqc_kem_shared_secret_sizes.labels(algorithm=algorithm).observe(size_bytes)
+
+
+class QRNGMetrics:
+    """Helper class for recording QRNG metrics"""
+
+    @staticmethod
+    def record_bytes_generated(backend: str, format: str, count: int):
+        """Record bytes generated"""
+        qrng_bytes_generated_total.labels(backend=backend, format=format).inc(count)
+
+    @staticmethod
+    def record_generation_duration(backend: str, duration: float):
+        """Record generation duration"""
+        qrng_generation_duration.labels(backend=backend).observe(duration)
+
+    @staticmethod
+    def update_entropy_bits(backend: str, bits: int):
+        """Update entropy bits gauge"""
+        qrng_entropy_bits.labels(backend=backend).set(bits)
+
+    @staticmethod
+    def update_quality_score(backend: str, score: float):
+        """Update quality score"""
+        qrng_quality_score.labels(backend=backend).set(score)
+
+
+class HardwareMetrics:
+    """Helper class for recording hardware metrics"""
+
+    @staticmethod
+    def update_device_status(device_id: str, device_type: str, vendor: str, status: int):
+        """Update device status (1=operational, 0=disconnected, -1=error)"""
+        hardware_device_status.labels(device_id=device_id, device_type=device_type, vendor=vendor).set(status)
+
+    @staticmethod
+    def update_generation_rate(device_id: str, device_type: str, rate_bps: float):
+        """Update generation rate"""
+        hardware_generation_rate.labels(device_id=device_id, device_type=device_type).set(rate_bps)
+
+    @staticmethod
+    def update_error_rate(device_id: str, device_type: str, rate: float):
+        """Update error rate"""
+        hardware_error_rate.labels(device_id=device_id, device_type=device_type).set(rate)
+
+    @staticmethod
+    def update_temperature(device_id: str, device_type: str, temp: float):
+        """Update temperature"""
+        hardware_temperature.labels(device_id=device_id, device_type=device_type).set(temp)
+
+    @staticmethod
+    def update_uptime(device_id: str, device_type: str, uptime: float):
+        """Update uptime"""
+        hardware_uptime.labels(device_id=device_id, device_type=device_type).set(uptime)
+
+
+class EntropyMetrics:
+    """Helper class for recording entropy quality metrics"""
+
+    @staticmethod
+    def update_shannon_entropy(source: str, entropy: float):
+        """Update Shannon entropy"""
+        entropy_shannon_entropy.labels(source=source).set(entropy)
+
+    @staticmethod
+    def update_min_entropy(source: str, entropy: float):
+        """Update min-entropy"""
+        entropy_min_entropy.labels(source=source).set(entropy)
+
+    @staticmethod
+    def update_chi_square(source: str, chi_square: float):
+        """Update chi-square statistic"""
+        entropy_chi_square.labels(source=source).set(chi_square)
+
+    @staticmethod
+    def update_quality_status(source: str, is_good: bool):
+        """Update quality status"""
+        entropy_quality_status.labels(source=source).set(1 if is_good else 0)
+
+
+class APIMetrics:
+    """Helper class for recording API metrics"""
+
+    @staticmethod
+    def record_request(endpoint: str, method: str, status: str, duration: float, 
+                      request_size: Optional[int] = None, response_size: Optional[int] = None):
+        """Record an API request"""
+        api_requests_total.labels(endpoint=endpoint, method=method, status=status).inc()
+        api_request_duration.labels(endpoint=endpoint, method=method).observe(duration)
+        if request_size:
+            api_request_size.labels(endpoint=endpoint).observe(request_size)
+        if response_size:
+            api_response_size.labels(endpoint=endpoint).observe(response_size)
+
+    @staticmethod
+    def update_active_connections(count: int):
+        """Update active connections gauge"""
+        api_active_connections.set(count)
+
+
+# ============================================================================
+# Decorators
+# ============================================================================
+
+def track_pqc_operation(algorithm: str, operation: str):
+    """Decorator to track PQC operations"""
+    def decorator(func):
+        @wraps(func)
+        async def async_wrapper(*args, **kwargs):
+            start_time = time.time()
+            status = 'success'
+            try:
+                result = await func(*args, **kwargs)
+                return result
+            except Exception as e:
+                status = 'error'
+                raise
+            finally:
+                duration = time.time() - start_time
+                PQCMetrics.record_operation(algorithm, operation, status, duration)
+        
+        @wraps(func)
+        def sync_wrapper(*args, **kwargs):
+            start_time = time.time()
+            status = 'success'
+            try:
+                result = func(*args, **kwargs)
+                return result
+            except Exception as e:
+                status = 'error'
+                raise
+            finally:
+                duration = time.time() - start_time
+                PQCMetrics.record_operation(algorithm, operation, status, duration)
+        
+        # Check if function is async
+        if asyncio.iscoroutinefunction(func):
+            return async_wrapper
+        return sync_wrapper
+    return decorator
+
+
+def track_api_request(endpoint: str, method: str):
+    """Decorator to track API requests"""
+    def decorator(func):
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            start_time = time.time()
+            status = 'success'
+            request_size = kwargs.get('request_size')
+            response_size = None
+            try:
+                result = await func(*args, **kwargs)
+                if hasattr(result, 'body'):
+                    response_size = len(str(result.body))
+                return result
+            except Exception as e:
+                status = 'error'
+                raise
+            finally:
+                duration = time.time() - start_time
+                APIMetrics.record_request(
+                    endpoint, method, status, duration,
+                    request_size=request_size, response_size=response_size
+                )
+        return wrapper
+    return decorator
+
+
+# ============================================================================
+# Utility Functions
+# ============================================================================
+
+def get_metrics() -> str:
+    """Get current metrics in Prometheus format"""
+    return generate_latest(registry).decode('utf-8')
+
+
+def get_metrics_content_type() -> str:
+    """Get metrics content type"""
+    return CONTENT_TYPE_LATEST
+
+
+def start_metrics_server(port: int = 9090):
+    """Start Prometheus metrics HTTP server"""
+    start_http_server(port, registry=registry)
+
+
+def setup_system_info(version: str, environment: str, quantum_backend: str):
+    """Set system information metric"""
+    system_info.labels(version=version, environment=environment, quantum_backend=quantum_backend).set(1)
+
+
+def initialize_multiprocess_mode():
+    """Initialize multiprocess mode for Prometheus"""
+    prometheus_multiproc_dir = os.environ.get('PROMETHEUS_MULTIPROC_DIR')
+    if prometheus_multiproc_dir:
+        MultiProcessCollector(registry)

app/quantum/hardware_interface.py

@@ -368,6 +368,256 @@ class SimulatedQRNG(QuantumHardwareInterface):
         print(f"Closing simulated QRNG {self.device_id}")
 
 
+class IDQuantiqueQRNG(QuantumHardwareInterface):
+    """
+    Interface for ID Quantique Quantis QRNG devices
+
+    Supports:
+    - Quantis USB Quantis
+    - Quantis PCIe Quantis
+    - Quantis Network Quantis
+
+    Product documentation: https://idquantique.com/random-number-generation/
+    """
+
+    def __init__(
+        self,
+        device_address: str = "usb://0",
+        device_type: str = "usb",
+        calibration_file: Optional[str] = None
+    ):
+        self.device_address = device_address
+        self.device_type = device_type  # usb, pcie, network
+        self.calibration_file = calibration_file
+        self.is_connected = False
+        self.device_id = f"idq_{device_type}_{hash(device_address) % 10000}"
+        self.last_calibration = None
+        self._sdk = None
+
+    async def initialize(self) -> bool:
+        """Initialize connection to ID Quantique QRNG"""
+        try:
+            print(f"Connecting to ID Quantique QRNG at {self.device_address}")
+
+            # In production, this would use the actual ID Quantique SDK
+            # Example: from idq import Quantis
+            # self._sdk = Quantis.open(self.device_address)
+
+            # Simulate connection for now
+            await asyncio.sleep(0.2)
+            self.is_connected = True
+
+            if self.calibration_file:
+                await self._load_calibration()
+
+            return True
+        except Exception as e:
+            print(f"Failed to initialize ID Quantique QRNG: {e}")
+            return False
+
+    async def measure_qubits(self, num_qubits: int) -> QuantumMeasurement:
+        """Measure photons using ID Quantique QRNG"""
+        if not self.is_connected:
+            raise RuntimeError("Device not connected")
+
+        start_time = time.time()
+
+        # In production, use actual SDK:
+        # num_bytes = (num_qubits + 7) // 8
+        # quantum_bytes = self._sdk.read(num_bytes)
+
+        # Simulated for now
+        import secrets
+        num_bytes = (num_qubits + 7) // 8
+        quantum_bytes = secrets.token_bytes(num_bytes)
+
+        # ID Quantique devices typically have very low latency
+        await asyncio.sleep(0.0001)  # 0.1ms for USB devices
+
+        measurement_time = time.time() - start_time
+
+        return QuantumMeasurement(
+            value=int.from_bytes(quantum_bytes, byteorder='big'),
+            bits=num_qubits,
+            timestamp=time.time(),
+            device_id=self.device_id,
+            raw_data=quantum_bytes,
+            confidence=0.99  # ID Quantique devices have very high confidence
+        )
+
+    async def get_device_status(self) -> Dict[str, Any]:
+        """Get status of ID Quantique QRNG"""
+        if not self.is_connected:
+            return {"status": "disconnected", "device_id": self.device_id}
+
+        return {
+            "status": "operational",
+            "device_id": self.device_id,
+            "device_type": QuantumDeviceType.PHOTONIC.value,
+            "vendor": "ID Quantique",
+            "model": "Quantis",
+            "connection_type": self.device_type,
+            "device_address": self.device_address,
+            "last_calibration": self.last_calibration,
+            "temperature": 20.5,  # Simulated
+            "light_intensity": 0.92,  # Simulated photon detection rate
+            "error_rate": 0.0001,  # Very low error rate
+            "generation_rate_bps": 4_000_000 if self.device_type == "usb" else 16_000_000,
+            "uptime_seconds": time.time() - (self.last_calibration or time.time()),
+            "firmware_version": "2.1.0",  # Simulated
+            "serial_number": "IDQ-QUANTIS-XXXXX"  # Would be real in production
+        }
+
+    async def calibrate(self) -> bool:
+        """Calibrate ID Quantique QRNG"""
+        try:
+            print(f"Calibrating ID Quantique QRNG {self.device_id}")
+            await asyncio.sleep(0.3)
+            self.last_calibration = time.time()
+            return True
+        except Exception as e:
+            print(f"Calibration failed: {e}")
+            return False
+
+    async def _load_calibration(self):
+        """Load calibration data"""
+        try:
+            print(f"Loading calibration from {self.calibration_file}")
+            self.last_calibration = time.time()
+        except Exception as e:
+            print(f"Failed to load calibration: {e}")
+
+    async def close(self):
+        """Close connection to ID Quantique QRNG"""
+        if self._sdk:
+            # In production: self._sdk.close()
+            pass
+        self.is_connected = False
+        print(f"Disconnected from ID Quantique QRNG {self.device_id}")
+
+
+class QuintessenceLabsQRNG(QuantumHardwareInterface):
+    """
+    Interface for QuintessenceLabs qStream QRNG devices
+
+    Product documentation: https://www.quintessencelabs.com/
+    """
+
+    def __init__(
+        self,
+        device_address: str = "tcp://localhost:8888",
+        api_key: Optional[str] = None,
+        calibration_file: Optional[str] = None
+    ):
+        self.device_address = device_address
+        self.api_key = api_key
+        self.calibration_file = calibration_file
+        self.is_connected = False
+        self.device_id = f"qlabs_{hash(device_address) % 10000}"
+        self.last_calibration = None
+        self._client = None
+
+    async def initialize(self) -> bool:
+        """Initialize connection to QuintessenceLabs qStream"""
+        try:
+            print(f"Connecting to QuintessenceLabs qStream at {self.device_address}")
+
+            # In production, use the QuintessenceLabs API:
+            # from qlabs import qStreamClient
+            # self._client = qStreamClient(self.device_address, api_key=self.api_key)
+
+            # Simulate connection
+            await asyncio.sleep(0.3)
+            self.is_connected = True
+
+            if self.calibration_file:
+                await self._load_calibration()
+
+            return True
+        except Exception as e:
+            print(f"Failed to initialize QuintessenceLabs QRNG: {e}")
+            return False
+
+    async def measure_qubits(self, num_qubits: int) -> QuantumMeasurement:
+        """Generate random bits using QuintessenceLabs qStream"""
+        if not self.is_connected:
+            raise RuntimeError("Device not connected")
+
+        start_time = time.time()
+
+        # In production:
+        # num_bytes = (num_qubits + 7) // 8
+        # quantum_bytes = self._client.get_random_bytes(num_bytes)
+
+        # Simulated for now
+        import secrets
+        num_bytes = (num_qubits + 7) // 8
+        quantum_bytes = secrets.token_bytes(num_bytes)
+
+        # qStream devices are very fast
+        await asyncio.sleep(0.00005)  # 0.05ms
+
+        measurement_time = time.time() - start_time
+
+        return QuantumMeasurement(
+            value=int.from_bytes(quantum_bytes, byteorder='big'),
+            bits=num_qubits,
+            timestamp=time.time(),
+            device_id=self.device_id,
+            raw_data=quantum_bytes,
+            confidence=0.995  # Extremely high confidence
+        )
+
+    async def get_device_status(self) -> Dict[str, Any]:
+        """Get status of QuintessenceLabs qStream"""
+        if not self.is_connected:
+            return {"status": "disconnected", "device_id": self.device_id}
+
+        return {
+            "status": "operational",
+            "device_id": self.device_id,
+            "device_type": QuantumDeviceType.PHOTONIC.value,
+            "vendor": "QuintessenceLabs",
+            "model": "qStream",
+            "connection_type": "TCP/IP",
+            "device_address": self.device_address,
+            "last_calibration": self.last_calibration,
+            "temperature": 21.0,  # Simulated
+            "error_rate": 0.00005,  # Extremely low error rate
+            "generation_rate_bps": 64_000_000,  # Up to 64 Mbps
+            "uptime_seconds": time.time() - (self.last_calibration or time.time()),
+            "firmware_version": "3.2.1",  # Simulated
+            "health_status": "excellent"
+        }
+
+    async def calibrate(self) -> bool:
+        """Calibrate QuintessenceLabs qStream"""
+        try:
+            print(f"Calibrating QuintessenceLabs QRNG {self.device_id}")
+            await asyncio.sleep(0.2)
+            self.last_calibration = time.time()
+            return True
+        except Exception as e:
+            print(f"Calibration failed: {e}")
+            return False
+
+    async def _load_calibration(self):
+        """Load calibration data"""
+        try:
+            print(f"Loading calibration from {self.calibration_file}")
+            self.last_calibration = time.time()
+        except Exception as e:
+            print(f"Failed to load calibration: {e}")
+
+    async def close(self):
+        """Close connection to QuintessenceLabs qStream"""
+        if self._client:
+            # In production: self._client.close()
+            pass
+        self.is_connected = False
+        print(f"Disconnected from QuintessenceLabs QRNG {self.device_id}")
+
+
 class QuantumHardwareManager:
     """Manages multiple quantum hardware devices"""
 
@@ -379,7 +629,7 @@ class QuantumHardwareManager:
         """Add a quantum hardware device to the manager"""
         if device_id in self.devices:
             return False
-        
+
         success = await device.initialize()
         if success:
             self.devices[device_id] = device
@@ -392,30 +642,30 @@ class QuantumHardwareManager:
         """Remove a quantum hardware device from the manager"""
         if device_id not in self.devices:
             return False
-        
+
         device = self.devices[device_id]
         await device.close()
         del self.devices[device_id]
-        
+
         if self.active_device_id == device_id:
             # Select a new active device
             if self.devices:
                 self.active_device_id = next(iter(self.devices))
             else:
                 self.active_device_id = None
-        
+
         return True
 
     async def measure_qubits(self, num_qubits: int, device_id: Optional[str] = None) -> QuantumMeasurement:
         """Measure qubits using the specified or active device"""
         target_device_id = device_id or self.active_device_id
-        
+
         if target_device_id is None:
             raise RuntimeError("No quantum devices available")
-        
+
         if target_device_id not in self.devices:
             raise ValueError(f"Device {target_device_id} not found")
-        
+
         return await self.devices[target_device_id].measure_qubits(num_qubits)
 
     async def get_device_status(self, device_id: Optional[str] = None) -> Dict[str, Any]:
@@ -433,13 +683,13 @@ class QuantumHardwareManager:
     async def calibrate_device(self, device_id: Optional[str] = None) -> bool:
         """Calibrate the specified or all devices"""
         target_device_ids = [device_id] if device_id else list(self.devices.keys())
-        
+
         success = True
         for dev_id in target_device_ids:
             if dev_id in self.devices:
                 result = await self.devices[dev_id].calibrate()
                 success = success and result
-        
+
         return success
 
     def get_available_devices(self) -> List[str]:
@@ -453,6 +703,61 @@ class QuantumHardwareManager:
             return True
         return False
 
+    async def run_entropy_quality_checks(self, device_id: Optional[str] = None) -> Dict[str, Any]:
+        """
+        Run entropy quality checks on quantum hardware output
+
+        Performs NIST SP 800-90B entropy estimation and statistical tests
+        """
+        target_device_id = device_id or self.active_device_id
+        if target_device_id is None or target_device_id not in self.devices:
+            raise ValueError(f"No valid device available")
+
+        device = self.devices[target_device_id]
+
+        # Generate sample data for testing
+        sample_size = 10000  # 10KB sample
+        measurement = await device.measure_qubits(sample_size * 8)
+
+        # Perform statistical analysis
+        data = measurement.raw_data
+
+        # Calculate basic statistics
+        byte_counts = [0] * 256
+        for byte in data:
+            byte_counts[byte] += 1
+
+        # Chi-square test for uniformity
+        expected_count = len(data) / 256
+        chi_square = sum((count - expected_count) ** 2 / expected_count for count in byte_counts)
+
+        # Calculate Shannon entropy
+        import math
+        shannon_entropy = 0
+        for count in byte_counts:
+            if count > 0:
+                p = count / len(data)
+                shannon_entropy -= p * math.log2(p)
+
+        # Min-entropy estimation (conservative)
+        max_prob = max(byte_counts) / len(data)
+        min_entropy = -math.log2(max_prob) if max_prob > 0 else 8
+
+        return {
+            "device_id": target_device_id,
+            "sample_size_bytes": len(data),
+            "chi_square": chi_square,
+            "chi_square_critical": 293.25,  # For 255 DOF at p=0.05
+            "uniformity_test": "PASS" if chi_square < 293.25 else "FAIL",
+            "shannon_entropy": shannon_entropy,
+            "shannon_entropy_max": 8.0,
+            "min_entropy": min_entropy,
+            "min_entropy_threshold": 7.0,
+            "entropy_test": "PASS" if min_entropy >= 7.0 else "FAIL",
+            "overall_quality": "GOOD" if (chi_square < 293.25 and min_entropy >= 7.0) else "POOR",
+            "recommendation": "Device entropy quality is acceptable" if (chi_square < 293.25 and min_entropy >= 7.0) else "Consider recalibration or hardware check"
+        }
+
 
 # Global hardware manager instance
 _quantum_hardware_manager: Optional[QuantumHardwareManager] = None

app/quantum/pqc.py

@@ -12,7 +12,7 @@ from functools import lru_cache
 try:
     import oqs
     LIBOQS_AVAILABLE = True
-except (ImportError, RuntimeError):
+except (ImportError, RuntimeError, SystemExit):
     LIBOQS_AVAILABLE = False
     print("Warning: liboqs not available. Using fallback implementation.")
 
@@ -26,6 +26,41 @@ class DilithiumKeypair:
     nist_level: int
 
 
+@dataclass
+class FalconKeypair:
+    """Falcon key pair container"""
+    public_key: bytes
+    private_key: bytes
+    algorithm: str
+    nist_level: int
+
+
+@dataclass
+class SphincsKeypair:
+    """SPHINCS+ key pair container"""
+    public_key: bytes
+    private_key: bytes
+    algorithm: str
+    nist_level: int
+
+
+@dataclass
+class KyberKeypair:
+    """Kyber key pair container"""
+    public_key: bytes
+    private_key: bytes
+    algorithm: str
+    nist_level: int
+
+
+@dataclass
+class EncapsulationResult:
+    """Kyber encapsulation result container"""
+    ciphertext: bytes
+    shared_secret: bytes
+    algorithm: str
+
+
 class PQCHandler:
     """
     Post-Quantum Cryptography operations using liboqs
@@ -155,7 +190,7 @@ class PQCHandler:
             # Fallback implementation
             if not signature or not public_key:
                 return False
-            
+
             # In fallback mode, assume valid if basic checks pass
             return True
 
@@ -166,6 +201,176 @@ class PQCHandler:
         except Exception:
             return False
 
+    async def generate_falcon_keypair(self, algorithm: str = "FALCON512") -> FalconKeypair:
+        """
+        Generate a Falcon key pair using liboqs
+
+        Args:
+            algorithm: FALCON512 or FALCON1024
+
+        Returns:
+            FalconKeypair with public/private keys
+
+        Note:
+            Falcon provides compact signatures, ideal for bandwidth-constrained applications.
+        """
+        if algorithm not in self.algorithms:
+            raise ValueError(f"Unsupported algorithm: {algorithm}")
+
+        config = self.algorithms[algorithm]
+        if config.get("type") != "SIGNATURE":
+            raise ValueError(f"{algorithm} is not a signature algorithm")
+
+        if not LIBOQS_AVAILABLE:
+            # Fallback implementation - NOT cryptographically secure
+            import secrets
+            private_key = secrets.token_bytes(config["key_size"])
+            public_key = hashlib.sha3_256(private_key).digest()
+
+            return FalconKeypair(
+                public_key=public_key,
+                private_key=private_key,
+                algorithm=algorithm,
+                nist_level=config["nist_level"]
+            )
+
+        # Use actual liboqs implementation
+        sig = oqs.Signature(algorithm)
+        public_key, secret_key = sig.generate_keypair()
+
+        return FalconKeypair(
+            public_key=public_key,
+            private_key=secret_key,
+            algorithm=algorithm,
+            nist_level=config["nist_level"]
+        )
+
+    async def sign_with_falcon(
+        self,
+        message: bytes,
+        private_key: bytes,
+        algorithm: str = "FALCON512"
+    ) -> bytes:
+        """Sign a message with Falcon using liboqs"""
+        if algorithm not in self.algorithms:
+            raise ValueError(f"Unsupported algorithm: {algorithm}")
+
+        if not LIBOQS_AVAILABLE:
+            # Fallback - NOT cryptographically secure
+            sig_data = private_key + message
+            signature = hashlib.sha3_256(sig_data).digest()
+            return signature
+
+        sig = oqs.Signature(algorithm)
+        return sig.sign(message, private_key)
+
+    async def verify_falcon_signature(
+        self,
+        message: bytes,
+        signature: bytes,
+        public_key: bytes,
+        algorithm: str = "FALCON512"
+    ) -> bool:
+        """Verify a Falcon signature using liboqs"""
+        if algorithm not in self.algorithms:
+            raise ValueError(f"Unsupported algorithm: {algorithm}")
+
+        if not LIBOQS_AVAILABLE:
+            if not signature or not public_key:
+                return False
+            return True
+
+        sig = oqs.Signature(algorithm)
+        try:
+            return sig.verify(message, signature, public_key)
+        except Exception:
+            return False
+
+    async def generate_sphincs_keypair(self, algorithm: str = "SPHINCS+-SHA2-128f") -> SphincsKeypair:
+        """
+        Generate a SPHINCS+ key pair using liboqs
+
+        Args:
+            algorithm: SPHINCS+ variant (e.g., SPHINCS+-SHA2-128f)
+
+        Returns:
+            SphincsKeypair with public/private keys
+
+        Note:
+            SPHINCS+ is a hash-based signature scheme with conservative security assumptions.
+        """
+        if algorithm not in self.algorithms:
+            raise ValueError(f"Unsupported algorithm: {algorithm}")
+
+        config = self.algorithms[algorithm]
+        if config.get("type") != "SIGNATURE":
+            raise ValueError(f"{algorithm} is not a signature algorithm")
+
+        if not LIBOQS_AVAILABLE:
+            # Fallback implementation - NOT cryptographically secure
+            import secrets
+            private_key = secrets.token_bytes(config["key_size"])
+            public_key = hashlib.sha3_256(private_key).digest()
+
+            return SphincsKeypair(
+                public_key=public_key,
+                private_key=private_key,
+                algorithm=algorithm,
+                nist_level=config["nist_level"]
+            )
+
+        # Use actual liboqs implementation
+        sig = oqs.Signature(algorithm)
+        public_key, secret_key = sig.generate_keypair()
+
+        return SphincsKeypair(
+            public_key=public_key,
+            private_key=secret_key,
+            algorithm=algorithm,
+            nist_level=config["nist_level"]
+        )
+
+    async def sign_with_sphincs(
+        self,
+        message: bytes,
+        private_key: bytes,
+        algorithm: str = "SPHINCS+-SHA2-128f"
+    ) -> bytes:
+        """Sign a message with SPHINCS+ using liboqs"""
+        if algorithm not in self.algorithms:
+            raise ValueError(f"Unsupported algorithm: {algorithm}")
+
+        if not LIBOQS_AVAILABLE:
+            # Fallback - NOT cryptographically secure
+            sig_data = private_key + message
+            signature = hashlib.sha3_256(sig_data).digest()
+            return signature
+
+        sig = oqs.Signature(algorithm)
+        return sig.sign(message, private_key)
+
+    async def verify_sphincs_signature(
+        self,
+        message: bytes,
+        signature: bytes,
+        public_key: bytes,
+        algorithm: str = "SPHINCS+-SHA2-128f"
+    ) -> bool:
+        """Verify a SPHINCS+ signature using liboqs"""
+        if algorithm not in self.algorithms:
+            raise ValueError(f"Unsupported algorithm: {algorithm}")
+
+        if not LIBOQS_AVAILABLE:
+            if not signature or not public_key:
+                return False
+            return True
+
+        sig = oqs.Signature(algorithm)
+        try:
+            return sig.verify(message, signature, public_key)
+        except Exception:
+            return False
+
     def assess_quantum_threat(self, algorithm: str) -> Dict[str, Any]:
         """
         Assess quantum threat level for an algorithm
@@ -232,17 +437,231 @@ class PQCHandler:
             "recommendation": "Evaluate algorithm quantum resistance"
         })
 
+    async def generate_kyber_keypair(self, algorithm: str = "KYBER768") -> KyberKeypair:
+        """
+        Generate a Kyber key pair using liboqs
+
+        Args:
+            algorithm: KYBER512, KYBER768, or KYBER1024
+
+        Returns:
+            KyberKeypair with public/private keys
+
+        Note:
+            KYBER is a Key Encapsulation Mechanism (KEM), not a signature scheme.
+            It is used for secure key exchange, not digital signatures.
+        """
+        if algorithm not in self.algorithms:
+            raise ValueError(f"Unsupported algorithm: {algorithm}")
+
+        config = self.algorithms[algorithm]
+        if config.get("type") != "KEM":
+            raise ValueError(f"{algorithm} is not a KEM algorithm")
+
+        if not LIBOQS_AVAILABLE:
+            # Fallback implementation if liboqs is not available
+            # This is NOT cryptographically secure - for testing only
+            import secrets
+            private_key = secrets.token_bytes(config["key_size"] * 2)
+            public_key = hashlib.sha3_512(private_key).digest() + secrets.token_bytes(
+                config["key_size"] - 64
+            )
+
+            return KyberKeypair(
+                public_key=public_key,
+                private_key=private_key,
+                algorithm=algorithm,
+                nist_level=config["nist_level"]
+            )
+
+        # Use actual liboqs implementation
+        kem = oqs.KeyEncapsulation(algorithm)
+        public_key = kem.generate_keypair()
+
+        return KyberKeypair(
+            public_key=public_key,
+            private_key=kem.secret_key,
+            algorithm=algorithm,
+            nist_level=config["nist_level"]
+        )
+
+    async def encapsulate(self, public_key: bytes, algorithm: str = "KYBER768") -> EncapsulationResult:
+        """
+        Encapsulate a shared secret using Kyber KEM
+
+        Args:
+            public_key: Recipient's public key bytes
+            algorithm: KYBER512, KYBER768, or KYBER1024
+
+        Returns:
+            EncapsulationResult with ciphertext and shared secret
+
+        Note:
+            The shared secret can be used as a symmetric key for encryption.
+            The ciphertext must be sent to the recipient for decapsulation.
+        """
+        if algorithm not in self.algorithms:
+            raise ValueError(f"Unsupported algorithm: {algorithm}")
+
+        config = self.algorithms[algorithm]
+        if config.get("type") != "KEM":
+            raise ValueError(f"{algorithm} is not a KEM algorithm")
+
+        if not LIBOQS_AVAILABLE:
+            # Fallback implementation - NOT cryptographically secure
+            import secrets
+            shared_secret = secrets.token_bytes(32)  # 256-bit shared secret
+            ciphertext = hashlib.sha3_256(public_key + shared_secret).digest() + secrets.token_bytes(
+                config["key_size"] - 32
+            )
+
+            return EncapsulationResult(
+                ciphertext=ciphertext,
+                shared_secret=shared_secret,
+                algorithm=algorithm
+            )
+
+        # Use actual liboqs implementation
+        kem = oqs.KeyEncapsulation(algorithm)
+        kem.set_public_key(public_key)
+        ciphertext, shared_secret = kem.encapsulate()
+
+        return EncapsulationResult(
+            ciphertext=ciphertext,
+            shared_secret=shared_secret,
+            algorithm=algorithm
+        )
+
+    async def decapsulate(
+        self,
+        ciphertext: bytes,
+        private_key: bytes,
+        algorithm: str = "KYBER768"
+    ) -> bytes:
+        """
+        Decapsulate a shared secret using Kyber KEM
+
+        Args:
+            ciphertext: Ciphertext bytes from encapsulation
+            private_key: Recipient's private key bytes
+            algorithm: KYBER512, KYBER768, or KYBER1024
+
+        Returns:
+            Shared secret bytes (should match the sender's shared secret)
+        """
+        if algorithm not in self.algorithms:
+            raise ValueError(f"Unsupported algorithm: {algorithm}")
+
+        config = self.algorithms[algorithm]
+        if config.get("type") != "KEM":
+            raise ValueError(f"{algorithm} is not a KEM algorithm")
+
+        if not LIBOQS_AVAILABLE:
+            # Fallback implementation - returns a deterministic value
+            # This is NOT cryptographically secure - for testing only
+            return hashlib.sha3_256(ciphertext + private_key).digest()
+
+        # Use actual liboqs implementation
+        kem = oqs.KeyEncapsulation(algorithm)
+        kem.set_secret_key(private_key)
+        shared_secret = kem.decapsulate(ciphertext)
+
+        return shared_secret
+
+    async def generate_ntru_keypair(self, algorithm: str = "NTRU-HPS-2048-509") -> KyberKeypair:
+        """
+        Generate an NTRU key pair using liboqs
+
+        Args:
+            algorithm: NTRU variant (e.g., NTRU-HPS-2048-509, NTRU-HPS-2048-677)
+
+        Returns:
+            KyberKeypair with public/private keys (using generic KEM keypair type)
+        """
+        if algorithm not in self.algorithms:
+            raise ValueError(f"Unsupported algorithm: {algorithm}")
+
+        config = self.algorithms[algorithm]
+        if config.get("type") != "KEM":
+            raise ValueError(f"{algorithm} is not a KEM algorithm")
+
+        if not LIBOQS_AVAILABLE:
+            import secrets
+            private_key = secrets.token_bytes(config["key_size"] * 2)
+            public_key = hashlib.sha3_512(private_key).digest() + secrets.token_bytes(
+                config["key_size"] - 64
+            )
+
+            return KyberKeypair(
+                public_key=public_key,
+                private_key=private_key,
+                algorithm=algorithm,
+                nist_level=config["nist_level"]
+            )
+
+        kem = oqs.KeyEncapsulation(algorithm)
+        public_key = kem.generate_keypair()
+
+        return KyberKeypair(
+            public_key=public_key,
+            private_key=kem.secret_key,
+            algorithm=algorithm,
+            nist_level=config["nist_level"]
+        )
+
+    async def generate_saber_keypair(self, algorithm: str = "SABER-SABER") -> KyberKeypair:
+        """
+        Generate a SABER key pair using liboqs
+
+        Args:
+            algorithm: SABER variant (LIGHTSABER, SABER, or FIRESABER)
+
+        Returns:
+            KyberKeypair with public/private keys (using generic KEM keypair type)
+        """
+        if algorithm not in self.algorithms:
+            raise ValueError(f"Unsupported algorithm: {algorithm}")
+
+        config = self.algorithms[algorithm]
+        if config.get("type") != "KEM":
+            raise ValueError(f"{algorithm} is not a KEM algorithm")
+
+        if not LIBOQS_AVAILABLE:
+            import secrets
+            private_key = secrets.token_bytes(config["key_size"] * 2)
+            public_key = hashlib.sha3_512(private_key).digest() + secrets.token_bytes(
+                config["key_size"] - 64
+            )
+
+            return KyberKeypair(
+                public_key=public_key,
+                private_key=private_key,
+                algorithm=algorithm,
+                nist_level=config["nist_level"]
+            )
+
+        kem = oqs.KeyEncapsulation(algorithm)
+        public_key = kem.generate_keypair()
+
+        return KyberKeypair(
+            public_key=public_key,
+            private_key=kem.secret_key,
+            algorithm=algorithm,
+            nist_level=config["nist_level"]
+        )
+
     def get_supported_algorithms(self) -> Dict[str, Any]:
         """Get list of supported PQC algorithms"""
         if LIBOQS_AVAILABLE:
             available_sigs = [alg for alg in oqs.get_enabled_sig_mechanisms()]
             available_kems = [alg for alg in oqs.get_enabled_kem_mechanisms()]
-            
+
             return {
-                "signatures": {alg: f"NIST Standard - {self.algorithms.get(alg, {}).get('nist_level', 'N/A')} security level" 
+                "signatures": {alg: f"NIST Standard - {self.algorithms.get(alg, {}).get('nist_level', 'N/A')} security level"
                               for alg in available_sigs if alg in self.algorithms},
-                "key_exchange": {alg: f"NIST Standard - {self.algorithms.get(alg, {}).get('nist_level', 'N/A')} security level" 
-                                for alg in available_kems if alg in self.algorithms}
+                "key_exchange": {alg: f"NIST Standard - {self.algorithms.get(alg, {}).get('nist_level', 'N/A')} security level"
+                                for alg in available_kems if alg in self.algorithms},
+                "liboqs_available": True
             }
         else:
             # Return the algorithms we know about even if liboqs isn't available
@@ -252,13 +671,21 @@ class PQCHandler:
                     "DILITHIUM3": "Balanced, NIST Level 3 (recommended)",
                     "DILITHIUM5": "Maximum security, NIST Level 5",
                     "FALCON512": "Compact signatures, NIST Level 1",
-                    "FALCON1024": "High security signatures, NIST Level 5"
+                    "FALCON1024": "High security signatures, NIST Level 5",
+                    "SPHINCS+-SHA2-128f": "Hash-based signatures, NIST Level 1"
                 },
                 "key_exchange": {
                     "KYBER512": "Fast, NIST Level 1",
                     "KYBER768": "Balanced, NIST Level 3 (recommended)",
-                    "KYBER1024": "Maximum security, NIST Level 5"
-                }
+                    "KYBER1024": "Maximum security, NIST Level 5",
+                    "NTRU-HPS-2048-509": "Fast KEM, NIST Level 1",
+                    "NTRU-HPS-2048-677": "Balanced KEM, NIST Level 3",
+                    "SABER-LIGHTSABER": "Fast KEM, NIST Level 1",
+                    "SABER-SABER": "Balanced KEM, NIST Level 3",
+                    "SABER-FIRESABER": "Maximum security KEM, NIST Level 5"
+                },
+                "liboqs_available": False,
+                "warning": "liboqs not available - using fallback (non-cryptographic) implementations"
             }
 
 

app/utils/rate_limiting.py

@@ -5,7 +5,8 @@ Enterprise-grade rate limiting and usage analytics
 
 import time
 import asyncio
-from typing import Dict, Optional, Tuple
+import logging
+from typing import Dict, List, Optional, Tuple
 from datetime import datetime, timedelta
 import hashlib
 import sqlite3
@@ -14,11 +15,15 @@ import threading
 
 from app.config import settings
 
+logger = logging.getLogger(__name__)
+
+VALID_TIERS = ("free", "pro", "enterprise")
+
 
 class UsageTracker:
     """
-    Tracks API usage for enterprise customers
-    Supports tier-based rate limiting and usage analytics
+    Tracks API usage for enterprise customers.
+    Supports tier-based rate limiting, usage analytics, and key lifecycle.
     """
     
     def __init__(self):
@@ -48,9 +53,23 @@ class UsageTracker:
                     tier TEXT DEFAULT 'free',
                     requests_count INTEGER DEFAULT 0,
                     bytes_count INTEGER DEFAULT 0,
-                    reset_time DATETIME
+                    reset_time DATETIME,
+                    customer_id TEXT,
+                    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+                    revoked_at DATETIME
                 )
             ''')
+
+            # Idempotent migration: add columns that may not exist yet.
+            for col, typedef in [
+                ("customer_id", "TEXT"),
+                ("created_at", "DATETIME DEFAULT CURRENT_TIMESTAMP"),
+                ("revoked_at", "DATETIME"),
+            ]:
+                try:
+                    conn.execute(f"ALTER TABLE rate_limits ADD COLUMN {col} {typedef}")
+                except sqlite3.OperationalError:
+                    pass  # column already exists
             
             conn.commit()
     
@@ -108,22 +127,92 @@ class UsageTracker:
         return is_allowed, remaining_requests, reset_in_seconds
     
     def _get_tier(self, api_key: str) -> str:
-        """Get the user's tier based on API key (simplified - in real system would query DB)"""
-        # In a real system, this would look up the tier in a user database
-        # For now, we'll use a simple hash-based approach for demo purposes
+        """Look up the stored tier for *api_key* from the rate_limits table."""
         if not api_key:
             return "free"
-        
-        # Hash the API key to determine a pseudo-tier for demo purposes
-        key_hash = hashlib.md5(api_key.encode()).hexdigest()
-        
-        if key_hash.startswith(('0', '1', '2')):
-            return "enterprise"
-        elif key_hash.startswith(('3', '4', '5', '6')):
-            return "pro"
-        else:
-            return "free"
-    
+
+        with self._get_db_connection() as conn:
+            cursor = conn.execute(
+                "SELECT tier FROM rate_limits WHERE api_key = ? AND revoked_at IS NULL",
+                (api_key,),
+            )
+            row = cursor.fetchone()
+            if row and row[0] in VALID_TIERS:
+                return row[0]
+        return "free"
+
+    # ------------------------------------------------------------------
+    # Key lifecycle helpers (used by billing webhooks & admin scripts)
+    # ------------------------------------------------------------------
+
+    def register_key(self, api_key: str, tier: str = "free", customer_id: Optional[str] = None) -> None:
+        """Insert or update a key with its authoritative tier."""
+        if tier not in VALID_TIERS:
+            raise ValueError(f"tier must be one of {VALID_TIERS}")
+        with self._get_db_connection() as conn:
+            conn.execute(
+                """INSERT INTO rate_limits (api_key, tier, customer_id)
+                   VALUES (?, ?, ?)
+                   ON CONFLICT(api_key) DO UPDATE SET tier = excluded.tier,
+                       customer_id = COALESCE(excluded.customer_id, rate_limits.customer_id),
+                       revoked_at = NULL""",
+                (api_key, tier, customer_id),
+            )
+            conn.commit()
+        logger.info("Registered key %s… as tier=%s", api_key[:8], tier)
+
+    def set_tier(self, api_key: str, tier: str) -> None:
+        """Update the tier for an existing key (e.g. after a Stripe subscription change)."""
+        if tier not in VALID_TIERS:
+            raise ValueError(f"tier must be one of {VALID_TIERS}")
+        with self._get_db_connection() as conn:
+            conn.execute(
+                "UPDATE rate_limits SET tier = ? WHERE api_key = ?",
+                (tier, api_key),
+            )
+            conn.commit()
+        logger.info("Updated key %s… to tier=%s", api_key[:8], tier)
+
+    def revoke_key(self, api_key: str) -> None:
+        """Soft-revoke a key so it no longer resolves to a valid tier."""
+        with self._get_db_connection() as conn:
+            conn.execute(
+                "UPDATE rate_limits SET revoked_at = ? WHERE api_key = ?",
+                (datetime.utcnow().isoformat(), api_key),
+            )
+            conn.commit()
+        logger.info("Revoked key %s…", api_key[:8])
+
+    def list_keys(self, include_revoked: bool = False) -> List[Dict]:
+        """Return all registered keys (sans the raw key itself) for admin views."""
+        with self._get_db_connection() as conn:
+            query = "SELECT api_key, tier, customer_id, created_at, revoked_at FROM rate_limits"
+            if not include_revoked:
+                query += " WHERE revoked_at IS NULL"
+            cursor = conn.execute(query)
+            return [
+                {
+                    "api_key_prefix": row[0][:8] + "…" if row[0] else "",
+                    "tier": row[1],
+                    "customer_id": row[2],
+                    "created_at": row[3],
+                    "revoked_at": row[4],
+                }
+                for row in cursor.fetchall()
+            ]
+
+    def get_key_by_customer(self, customer_id: str) -> Optional[str]:
+        """Retrieve the active api_key for a Stripe customer_id."""
+        with self._get_db_connection() as conn:
+            cursor = conn.execute(
+                "SELECT api_key FROM rate_limits WHERE customer_id = ? AND revoked_at IS NULL LIMIT 1",
+                (customer_id,),
+            )
+            row = cursor.fetchone()
+            return row[0] if row else None
+
+    # ------------------------------------------------------------------
+
     def _get_current_usage(self, api_key: str) -> Tuple[int, int, Optional[datetime]]:
         """Get current usage for an API key"""
         with self._get_db_connection() as conn:
@@ -138,10 +227,9 @@ class UsageTracker:
                 reset_time = datetime.fromisoformat(reset_time_str) if reset_time_str else None
                 return requests_count, bytes_count, reset_time
             else:
-                # Create new record
                 reset_time = datetime.utcnow() + timedelta(seconds=settings.rate_limit_period)
                 conn.execute(
-                    "INSERT INTO rate_limits (api_key, reset_time) VALUES (?, ?)",
+                    "INSERT INTO rate_limits (api_key, tier, reset_time) VALUES (?, 'free', ?)",
                     (api_key, reset_time.isoformat())
                 )
                 conn.commit()

docker-compose.yml

@@ -38,16 +38,8 @@ services:
     image: redis:7-alpine
     restart: unless-stopped
 
-  dashboard:
-    build: .
-    ports:
-      - "8501:8501"
-    command: streamlit run dashboard.py --server.address 0.0.0.0 --server.port 8501
-    environment:
-      - API_BASE_URL=http://api:8000/api/v2
-    depends_on:
-      - api
-    restart: unless-stopped
+  # Web UI: use Next.js in quantum-oracle-ui (npm run dev / production build).
+  # Legacy Streamlit dashboard: legacy/streamlit/dashboard.py (not included in this image).
 
 volumes:
   postgres_data:

docs/BUILD_MONETIZATION.md

@@ -0,0 +1,147 @@
+# Build Map — Monetization (API + Oracle)
+
+Step-by-step plan to add **paid tiers**, **billing**, and **oracle-specific metering** on top of QCrypt RNG. Assumes prerequisites in [UPGRADE_ROADMAP.md](UPGRADE_ROADMAP.md) (Phase A foundation).
+
+---
+
+## Current State (Baseline)
+
+| Capability | Location | Gap |
+|------------|----------|-----|
+| Tier limits (free/pro/enterprise) | `app/config.py` — `get_tier_limits()` | OK |
+| Usage logging | `usage_logs` in `app/utils/rate_limiting.py` | OK for analytics |
+| Rate limiting per key | `UsageTracker.check_rate_limit()` | **Tier from `_get_tier()` is MD5 hash pseudo-tier** — must replace |
+| API keys | `VALID_API_KEYS` + `api_key_middleware` | No link to Stripe/customer |
+| Oracle `fee_required` | `app/api/v2/endpoints/oracle.py` | Placeholder; not tied to billing |
+
+---
+
+## Phase A — Foundation (Required First)
+
+**Goal:** Map each API key to a tier authoritatively.
+
+### Tasks
+
+1. **Data model**
+   - Option A: Extend `rate_limits` (already has `tier`) — ensure `tier` is set on key creation and read in `_get_tier()`.
+   - Option B: New table `api_keys` with columns: `key_hash` (never store raw key), `tier`, `customer_id`, `created_at`, `revoked_at`.
+
+2. **Replace `_get_tier()`** in `app/utils/rate_limiting.py`
+   - Remove hash-based pseudo assignment.
+   - Lookup: `SELECT tier FROM rate_limits WHERE api_key = ?` or `api_keys` equivalent.
+   - Default: `free` if unknown key (or reject if `require_api_key` is true).
+
+3. **Key lifecycle**
+   - Admin script or endpoint to create key + set tier (or sync from Stripe webhook).
+   - Migration: backfill existing keys from `VALID_API_KEYS` into `rate_limits` with tier `pro` or `enterprise` as needed.
+
+4. **Oracle-specific counters (optional in A, required for hybrid plans)**
+   - Add `oracle_fulfillments_count` or track via `usage_logs` filtered by `endpoint LIKE '/oracle/%'`.
+
+### Acceptance criteria
+
+- [ ] Two keys with same tier get **identical** limits (no randomness by MD5).
+- [ ] Changing tier in DB updates limits within one window (or on next request).
+
+---
+
+## Phase B — Subscription Billing (Stripe)
+
+**Goal:** Paid plans update tier automatically.
+
+### Tasks
+
+1. **Stripe setup**
+   - Products: e.g. Free (no price), Pro (monthly), Enterprise (custom).
+   - Customer Portal for subscription management.
+
+2. **Backend**
+   - New module e.g. `app/billing/stripe_webhooks.py`:
+     - `checkout.session.completed` → create API key + set tier.
+     - `customer.subscription.updated` / `deleted` → update tier or revoke key.
+   - Store `stripe_customer_id` ↔ internal user/key mapping (PostgreSQL recommended; see `DATABASE_URL` in config).
+
+3. **Secrets**
+   - `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, price IDs in env.
+
+4. **Dashboard (`quantum-oracle-ui`)**
+   - Pricing page (Free / Pro / Enterprise).
+   - “Upgrade” → Stripe Checkout link.
+   - Post-login: show API key + usage (read from new `/billing/usage` or `/monitoring` API).
+
+### Acceptance criteria
+
+- [ ] Test mode: subscribe → tier becomes `pro`; cancel → downgrade or revoke per policy.
+
+---
+
+## Phase C — Usage-Based / Metered (Optional)
+
+**Goal:** Bill overage or pure usage (API bytes + oracle calls).
+
+### Tasks
+
+1. **Aggregation**
+   - Daily/monthly job: `SUM(bytes_processed)`, `COUNT(*)` from `usage_logs` per `api_key`.
+   - Filter oracle: `endpoint` in (`/oracle/fulfillment/request`, `/oracle/vrf/prove`, …).
+
+2. **Stripe metered billing** (if used)
+   - Report usage to Stripe Usage Records API.
+   - Align billing period with subscription invoice.
+
+3. **429 / quota responses**
+   - Return clear JSON: `error`, `tier`, `limit`, `reset_at`.
+
+### Acceptance criteria
+
+- [ ] Usage report matches raw `usage_logs` for a test key.
+
+---
+
+## Phase D — Oracle Product Packaging
+
+**Goal:** Sell **API + oracle** as combined or add-on SKUs.
+
+### Tasks
+
+1. **Define limits**
+   - Example: Free — 0 on-chain fulfillments; Pro — 50/month; Enterprise — unlimited + SLA.
+
+2. **Enforcement**
+   - Middleware or dependency on oracle routes: check oracle quota before `OracleFulfillmentService`.
+   - Increment counter after successful fulfillment (or after request, per policy).
+
+3. **Pricing surface**
+   - Document gas vs service fee (user pays chain gas; you charge service fee or subscription).
+   - Align `fee_required` in API responses with marketing copy or hide in subscription-only.
+
+### Acceptance criteria
+
+- [ ] Exceeding oracle quota returns **402** or **429** with upgrade hint.
+
+---
+
+## File / Module Checklist
+
+| New or changed | Purpose |
+|----------------|---------|
+| `app/utils/rate_limiting.py` | Real `_get_tier()`; optional oracle quota |
+| `app/integrations/stripe.py` (new) | Stripe client + webhook verification |
+| `app/api/v2/endpoints/billing.py` (new) | Usage summary, portal link (if needed) |
+| `app/config.py` | `STRIPE_*`, `ORACLE_*` quota env vars |
+| `quantum-oracle-ui/src/app/pricing/` or page | Pricing + upgrade |
+| `docs/PRODUCTION.md` | Document billing env vars |
+
+---
+
+## Risks
+
+| Risk | Mitigation |
+|------|------------|
+| Raw API keys in DB | Store only HMAC-SHA256 or bcrypt of key; compare on request |
+| Webhook forgery | Verify Stripe signature |
+| SQLite at scale | Move `usage_logs` / `rate_limits` to PostgreSQL for multi-instance |
+
+---
+
+*See also: [BUILD_PLATFORM_AND_QUALITY.md](BUILD_PLATFORM_AND_QUALITY.md) for tests and monitoring that support billing SLAs.*

docs/BUILD_PLATFORM_AND_QUALITY.md

@@ -0,0 +1,148 @@
+# Build Map — Platform & Quality
+
+Testing, monitoring, documentation, security, and **on-chain validation** for QCrypt RNG. Complements [UPGRADE_ROADMAP.md](UPGRADE_ROADMAP.md) and [BUILD_MONETIZATION.md](BUILD_MONETIZATION.md).
+
+---
+
+## 1. Testing
+
+**Status:** In progress (see `tests/`, `pytest.ini`).
+
+### Unit tests
+
+| Target | Files / symbols | Notes |
+|--------|-------------------|--------|
+| Kyber KEM | `app/quantum/pqc.py` — `generate_kyber_keypair`, `encapsulate`, `decapsulate` | Requires liboqs |
+| Expanded PQC | FALCON, SPHINCS+, NTRU, SABER in `pqc.py` | Mock or skip if liboqs missing |
+| Oracle fulfillment | `OracleFulfillmentService`, chain adapters | **Mock Web3** — no network |
+| Hardware adapters | `IDQuantiqueQRNG`, `QuintessenceLabsQRNG` | Mock I/O |
+| Entropy | `run_entropy_quality_checks()` | Deterministic fixtures |
+
+### Integration tests
+
+| Target | Routes |
+|--------|--------|
+| PQC | `/pqc/kem/*`, expanded `/pqc/*` |
+| Oracle | `/oracle/*`, `/oracle/fulfillment/*` |
+| Middleware | API key + rate limit (test client with headers) |
+
+### Build steps
+
+1. Run `pytest` from repo root; fix CI to run on PR.
+2. Add coverage threshold for `app/quantum/`, `app/blockchain/`, `app/utils/middleware.py` (optional).
+3. Document `pytest -m "not slow"` if slow tests are added.
+
+### Acceptance criteria
+
+- [ ] CI green on default branch.
+- [ ] Oracle/chain tests do not require live RPC.
+
+---
+
+## 2. Monitoring & Observability
+
+**References:** [MONITORING_GUIDE.md](MONITORING_GUIDE.md), [DASHBOARD_MONITORING_PLAN.md](DASHBOARD_MONITORING_PLAN.md), `app/monitoring/metrics.py`.
+
+### Metrics to add or verify
+
+| Area | Metric idea | Consumer |
+|------|-------------|----------|
+| Oracle fulfillment | Latency, success/failure, chain label | Prometheus + alerts |
+| PQC | Keygen/sign/KEM counts per algorithm | Capacity planning |
+| Entropy | Quality score from `run_entropy_quality_checks()` | Dashboard + alert if below threshold |
+| API | Request rate, 4xx/5xx by route | Grafana |
+
+### Build steps
+
+1. Wire counters/histograms in `app/monitoring/metrics.py` for fulfillment paths.
+2. Expose `/monitoring/metrics` (or merge with existing) — align with [PRODUCTION.md](PRODUCTION.md).
+3. Optional: Grafana dashboard JSON in `docs/` or `k8s/`.
+
+### Acceptance criteria
+
+- [ ] Failed fulfillments visible in metrics within 1 minute.
+
+---
+
+## 3. API Documentation & README
+
+**Status:** Partially done; keep in sync with code.
+
+### Tasks
+
+1. **README.md** — Full list of `/pqc/*`, `/oracle/fulfillment/*`, hardware env vars.
+2. **OpenAPI** — FastAPI `app/main.py` tags/descriptions for new routes.
+3. **Examples** — Kyber encapsulate/decapsulate curl; one fulfillment flow.
+
+### Files
+
+| File | Action |
+|------|--------|
+| `README.md` | API tables + links |
+| `docs/PRODUCTION.md` | Next.js dashboard, env vars (no Streamlit references) |
+| `app/main.py` | OpenAPI metadata |
+
+---
+
+## 4. Smart Contracts & Testnets
+
+**Goal:** Provable end-to-end oracle path.
+
+### Tasks
+
+1. Deploy contracts from `quantum-oracle/contracts/` to:
+   - Ethereum Sepolia
+   - Polygon Amoy (optional)
+   - BSC testnet (optional)
+2. Record addresses in `docs/` or `app/config.py` (env-driven).
+3. E2E test: API → adapter → testnet (or mocked tx in CI).
+
+### Acceptance criteria
+
+- [ ] Documented contract addresses + explorer links.
+- [ ] One testnet flow verified manually or in CI (with secrets in CI only).
+
+---
+
+## 5. Security
+
+### Internal checklist (before external audit)
+
+| Topic | Check |
+|-------|--------|
+| Blockchain | Private keys, KMS, no keys in repo |
+| PQC | Key material zeroization where possible; no keys in logs |
+| Oracle | Replay, race conditions, gas limits |
+| API | Rate limits, body size, CORS, `SECRET_KEY` in production |
+
+### External audit
+
+- Scope: `app/blockchain/`, `app/quantum/pqc.py`, oracle fulfillment, middleware.
+- Deliverable: findings + remediation tracking.
+
+---
+
+## 6. Dashboard (UI)
+
+**Already aligned** with Phase 2 dashboard work (Kyber UI, oracle fulfillment section).
+
+### Remaining for “product”
+
+- Usage widget (calls remaining, resets) — needs API from [BUILD_MONETIZATION.md](BUILD_MONETIZATION.md).
+- Pricing page — Stripe links.
+- Monitoring section — optional embed or link to Grafana.
+
+---
+
+## Execution Order (Suggested)
+
+| Week | Focus |
+|------|--------|
+| 1 | Tests + tier fix (foundation) |
+| 2 | Monitoring + README/OpenAPI |
+| 3 | Testnet deploy + doc addresses |
+| 4 | Security review + Stripe (parallel with monetization doc) |
+
+---
+
+*Cross-reference: [NEXT_STEPS_PHASE2.md](NEXT_STEPS_PHASE2.md) — original task list; this file supersedes priority ordering for platform work.*

docs/CURSOR_OPERATOR_PROMPT.md

@@ -0,0 +1,63 @@
+# Cursor / agent operator prompt (QCrypt RNG)
+
+Paste or reference this when starting a coding session in this repository. It orients assistants on stack, commands, tools, and workflow.
+
+You are working in the **qcrypt-rng** repo (FastAPI backend + Next.js `quantum-oracle-ui` + Hardhat `quantum-oracle/contracts`). Prefer evidence from the codebase over guesses.
+
+### Operating principles
+
+- **Phases:** understand → plan → smallest vertical slice → validate (tests/build) → summarize.
+- **Scope:** change only what the task requires; match existing patterns (imports at top, project conventions).
+- **Verification:** before claiming success, run the relevant checks and report command output.
+
+### Repo commands (adjust paths if needed)
+
+- **Backend:** `python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt && python run_api.py` — API at http://localhost:8000, docs at /docs.
+- **Alt start:** `make run` → `python scripts/start.py`.
+- **Tests:** `make test` / `pytest`.
+- **Frontend:** `cd quantum-oracle-ui && npm install && npm run dev` — default UI port **3040** (`find-port.js`, not 3000); optional `NEXT_PUBLIC_API_BASE_URL`.
+- **Contracts:** `cd quantum-oracle/contracts && npm install` (Hardhat).
+- **Docker:** `docker-compose up -d` (see compose file for DB/Redis/API key flags).
+
+**Gotcha:** run Node/npm for the dashboard from `quantum-oracle-ui/`, not `quantum-oracle/` (no root `package.json` there).
+
+### Cursor / Composer tools (conceptual)
+
+- **Explore:** search/read files, grep, semantic codebase search, read lints.
+- **Terminal:** run shell commands in the workspace (build, test, dev servers).
+- **Edits:** apply patches; keep diffs focused.
+
+### Subagents (Task tool) — when to use which
+
+- **explore:** fast map of structure, “where is X?”, multi-file discovery.
+- **generalPurpose:** multi-step research + implementation across the repo.
+- **shell:** git operations, scripted terminal workflows.
+- **code-reviewer:** after a substantial change, compare to intent and standards.
+- **ci-watcher:** watch CI for the branch, summarize failures.
+- **best-of-n-runner:** isolated git worktrees for parallel attempts.
+- **etoro-trading-assistant / API Readiness Analyzer:** only if the task explicitly touches those domains.
+
+### Skills — how to use them
+
+When a task matches a skill’s description, **read the skill file first** and follow it (path is given in the environment’s available_skills list). Examples of categories you may have installed:
+
+- **Cursor / workflow:** create-rule, create-skill, update-cursor-settings; check-compiler-errors, deslop, fix-ci, fix-merge-conflicts, get-pr-comments, loop-on-ci, new-branch-and-pr, review-and-ship, run-smoke-tests, weekly-review, what-did-i-get-done.
+- **Planning / execution:** brainstorming (before creative work), writing-plans, executing-plans, subagent-driven-development, systematic-debugging, test-driven-development, verification-before-completion, finishing-a-development-branch, using-git-worktrees.
+- **Cloudflare:** cloudflare, wrangler, workers-best-practices, durable-objects, Agents SDK / building-ai-agent-on-cloudflare, building-mcp-server-on-cloudflare, web-perf, sandbox-sdk.
+- **Data / infra:** supabase-postgres-best-practices, redis-development skill, langfuse, hf-* skills, tavily-* / firecrawl (if installed — follow each skill’s rules for web tasks).
+- **Security / APIs:** mcp-builder, mcp-security-audit, secure-dependency-health-check, postman-routing / agent-ready-apis.
+- **Other:** etoro-apps (eToro only), plugin-builder, etc.
+
+If unsure whether a skill applies, **open its SKILL.md** and follow the “when to use” section.
+
+### MCP
+
+If the user has MCP servers configured, **read the tool schema** before calling a tool; use MCP for external systems (CI, Hub, etc.) when it reduces error and repetition.
+
+### Default task template
+
+1. Restate the task in one sentence; state in/out of scope.
+2. Name files to touch and a short plan.
+3. Implement the smallest coherent change.
+4. Run validation commands; paste relevant output.
+5. Summarize what changed, what’s left, follow-ups.

docs/DASHBOARD_MONITORING_PLAN.md

@@ -0,0 +1,61 @@
+# Dashboard Integration and Monitoring Implementation Plan
+
+**Source:** Dashboard + Monitoring Plan (Phase 2 Tasks 3–4)
+**Status:** Both tasks COMPLETE (verified 2026-03-23; frontend builds successfully)
+
+---
+
+## Part 1: Dashboard Integration (Task 3)
+
+### 1.1 API Layer Additions
+
+**File:** `quantum-oracle-ui/src/utils/api.ts`
+
+- **Kyber KEM:** `kemGenerate`, `kemEncapsulate`, `kemDecapsulate`
+- **Oracle Fulfillment:** `configureFulfillmentChain`, `createFulfillmentRequest`, `getFulfillmentStatus`, `listFulfillmentRequests`, `getFulfillmentChains`, `retryFulfillment`
+
+**File:** `quantum-oracle-ui/src/types/index.ts` — KEM and fulfillment response types
+
+### 1.2 Kyber KEM UI in Protect.tsx
+
+- Algorithm: KYBER512 / KYBER768 / KYBER1024
+- Flow: Generate keypair → Sender encapsulate → Recipient decapsulate
+- Copy/Download, InfoPopover for workflow explanation
+
+### 1.3 Expanded PQC Algorithms in Protect.tsx
+
+- Signatures: DILITHIUM2/3/5, FALCON512/1024, SPHINCS+-SHA2-128f
+- KEM (keys only): KYBER, NTRU, SABER — show key gen, link to Kyber KEM section
+
+### 1.4 Oracle Fulfillment UI in QuantumOracle.tsx
+
+- Configure Chain (rpc_url, private_key, etc.) — security warning
+- Create Request, Status Lookup, List Requests, Retry
+- Collapsible, default collapsed
+
+### 1.5 Docs Page
+
+- Add Kyber KEM and Oracle Fulfillment endpoint docs
+
+---
+
+## Part 2: Monitoring (Task 4) — COMPLETED
+
+34 Prometheus metrics implemented in `app/monitoring/metrics.py` across 7 categories: oracle fulfillment (7), PQC operations (6), QRNG generation (4), hardware devices (5), entropy quality (4), API performance (5), system (3). Grafana dashboard and alerting rules in `app/monitoring/`. All monitoring endpoints active in `app/api/v2/endpoints/monitoring.py`.
+
+---
+
+## Implementation Order
+
+1. API layer: KEM + fulfillment methods - Done
+2. Kyber KEM UI in Protect - Done
+3. Expanded PQC dropdown + KEM-only mode - Done
+4. Oracle Fulfillment UI in QuantumOracle - Done
+5. Docs page update - Done
+
+---
+
+## Security Notes
+
+- Oracle fulfillment: Never use production keys; demo/test only
+- Mask private_key input (type="password")

docs/IMPLEMENTATION_SUMMARY_2026.md

@@ -0,0 +1,248 @@
+# QCrypt RNG — Implementation Summary
+
+This document summarizes the completed implementation of the tasks outlined in NEXT_STEPS.md.
+
+**Last Updated:** 2026-03-06
+
+---
+
+## ✅ Task 1: Implement Kyber KEM in pqc.py and PQC endpoints
+
+**Status:** ✅ COMPLETED
+
+### Changes Made:
+
+#### `app/quantum/pqc.py`
+- Added `KyberKeypair` and `EncapsulationResult` dataclasses
+- Implemented `generate_kyber_keypair()` for KYBER512/768/1024
+- Implemented `encapsulate()` for key encapsulation
+- Implemented `decapsulate()` for shared secret recovery
+- All methods include fallback implementations when liboqs is unavailable
+
+#### `app/api/v2/endpoints/pqc_endpoints.py`
+- Added `/pqc/kem/generate` endpoint for keypair generation
+- Added `/pqc/kem/encapsulate` endpoint for encapsulation
+- Added `/pqc/kem/decapsulate` endpoint for decapsulation
+- Added `/pqc/kem/info` endpoint for KEM documentation
+
+### Features:
+- Full Kyber KEM implementation using liboqs when available
+- Graceful fallback mode (clearly marked as non-cryptographic)
+- Support for all three security levels (KYBER512, KYBER768, KYBER1024)
+- Base64 and hex encoding support
+- Comprehensive metadata including NIST security levels
+
+---
+
+## ✅ Task 2: Update PRODUCTION.md to describe the Next.js dashboard
+
+**Status:** ✅ COMPLETED
+
+### Changes Made:
+
+#### `PRODUCTION.md`
+- Replaced all Streamlit references with Next.js dashboard
+- Added dashboard build instructions (`npm run build`, `npm run start`)
+- Documented environment variables (`NEXT_PUBLIC_API_BASE_URL`, `API_BASE_URL`)
+- Added single-Docker deployment section
+- Updated manual deployment instructions with Next.js build steps
+- Documented Nginx routing configuration
+
+### Key Updates:
+- Architecture overview now includes Nginx reverse proxy
+- Dashboard section describes Next.js 16 build process
+- Deployment options include single Docker image approach
+- Clear routing documentation (`/api/*` → FastAPI, `/` → Next.js)
+
+---
+
+## ✅ Task 3: Expand PQC support (FALCON/SPHINCS+/NTRU/SABER)
+
+**Status:** ✅ COMPLETED (Option A - Expanded support)
+
+### Changes Made:
+
+#### `app/quantum/pqc.py`
+- Added `FalconKeypair` and `SphincsKeypair` dataclasses
+- Implemented `generate_falcon_keypair()` for FALCON512/1024
+- Implemented `sign_with_falcon()` and `verify_falcon_signature()`
+- Implemented `generate_sphincs_keypair()` for SPHINCS+ variants
+- Implemented `sign_with_sphincs()` and `verify_sphincs_signature()`
+- Implemented `generate_ntru_keypair()` for NTRU-HPS variants
+- Implemented `generate_saber_keypair()` for SABER variants
+- Updated `get_supported_algorithms()` to include all algorithms
+
+#### `app/api/v2/endpoints/pqc_endpoints.py`
+- Added `/pqc/falcon/generate` endpoint
+- Added `/pqc/sphincs/generate` endpoint
+- Added `/pqc/ntru/generate` endpoint
+- Added `/pqc/saber/generate` endpoint
+
+### Supported Algorithms:
+
+**Signatures:**
+- DILITHIUM2/3/5 (NIST FIPS 204)
+- FALCON512/1024 (NIST FIPS 204)
+- SPHINCS+-SHA2-128f and variants (NIST FIPS 205)
+
+**Key Encapsulation:**
+- KYBER512/768/1024 (NIST FIPS 203)
+- NTRU-HPS-2048-509/677
+- SABER-LIGHTSABER/SABER/FIRESABER
+
+---
+
+## ✅ Task 4: Integrate real quantum hardware through the existing abstraction
+
+**Status:** ✅ COMPLETED
+
+### Changes Made:
+
+#### `app/quantum/hardware_interface.py`
+- Added `IDQuantiqueQRNG` class for ID Quantique Quantis devices
+  - Supports USB, PCIe, and Network variants
+  - Includes simulated SDK integration points
+  - Provides device status with vendor-specific metadata
+  - Confidence level: 0.99
+
+- Added `QuintessenceLabsQRNG` class for qStream devices
+  - TCP/IP network interface
+  - API key authentication support
+  - High-speed generation (up to 64 Mbps)
+  - Confidence level: 0.995
+
+- Added `run_entropy_quality_checks()` method to `QuantumHardwareManager`
+  - NIST SP 800-90B entropy estimation
+  - Chi-square uniformity test
+  - Shannon entropy calculation
+  - Min-entropy estimation
+  - Overall quality assessment
+
+### Hardware Support:
+- **ID Quantique Quantis**: Photonic QRNG, 4-16 Mbps
+- **QuintessenceLabs qStream**: Photonic QRNG, up to 64 Mbps
+- **SimulatedQRNG**: Development/testing backend
+- **PhotonicQRNG**: Generic photonic interface
+- **SuperconductingQRNG**: Generic superconducting interface
+
+### Configuration:
+Set `QUANTUM_BACKEND` environment variable:
+- `idq_quantis` - ID Quantique Quantis
+- `qlabs_qstream` - QuintessenceLabs qStream
+- `qrisp_simulator` - Simulator (default)
+
+---
+
+## ✅ Task 5: Add on-chain fulfillment for oracle requests
+
+**Status:** ✅ COMPLETED
+
+### New Module: `app/blockchain/`
+
+#### Core Components:
+
+**`base.py`** - Base chain adapter
+- `ChainAdapter` abstract base class
+- `ChainConfig` dataclass for configuration
+- `TransactionStatus` enumeration
+- `TransactionReceipt` dataclass
+
+**`ethereum.py`** - Ethereum adapter
+- Full Web3.py integration
+- Commit/reveal contract interaction
+- Gas price estimation
+- Transaction confirmation waiting
+
+**`polygon.py`** - Polygon adapter
+- Inherits from EthereumAdapter
+- Polygon-specific RPC endpoints
+- Optimized gas pricing
+
+**`bsc.py`** - Binance Smart Chain adapter
+- BSC RPC endpoints
+- Low gas price optimization
+
+**`avalanche.py`** - Avalanche C-Chain adapter
+- Fast finality support (3 confirmations)
+- Avalanche RPC endpoints
+
+**`fantom.py`** - Fantom Opera adapter
+- Fantom-specific configuration
+- Low fee optimization
+
+**`oracle_service.py`** - Oracle fulfillment service
+- `OracleFulfillmentService` class
+- Request lifecycle management
+- Async fulfillment support
+- Multi-chain coordination
+
+#### New API Endpoints:
+
+**`app/api/v2/endpoints/oracle.py`**
+- `POST /oracle/fulfillment/configure-chain` - Configure blockchain
+- `POST /oracle/fulfillment/request` - Create on-chain request
+- `GET /oracle/fulfillment/status/{request_id}` - Check status
+- `GET /oracle/fulfillment/requests` - List all requests
+- `GET /oracle/fulfillment/chains` - List supported chains
+- `POST /oracle/fulfillment/retry/{request_id}` - Retry failed request
+
+### Features:
+- **Multi-chain support**: Ethereum, Polygon, BSC, Avalanche, Fantom
+- **Commit-reveal scheme**: Keccak-256 commitments (Ethereum-compatible)
+- **Async fulfillment**: Non-blocking request processing
+- **Status tracking**: Full lifecycle from PENDING to COMPLETED
+- **Retry mechanism**: Automatic retry for failed requests
+- **Explorer integration**: Direct links to transaction explorer
+
+### Security Notes:
+- Private keys must be stored securely
+- Use hardware wallets or KMS in production
+- Never commit private keys to version control
+
+---
+
+## Summary
+
+All five prioritized tasks from NEXT_STEPS.md have been completed:
+
+| Task | Status | Impact |
+|------|--------|--------|
+| 1. Kyber KEM implementation | ✅ Complete | High — matches advertised feature |
+| 2. PRODUCTION.md dashboard update | ✅ Complete | Medium — avoids deployment confusion |
+| 3. PQC expansion | ✅ Complete | High — correctness and trust |
+| 4. Real quantum hardware integration | ✅ Complete | High — production differentiation |
+| 5. On-chain fulfillment | ✅ Complete | High — enables real oracle use cases |
+
+### Files Modified:
+- `app/quantum/pqc.py`
+- `app/quantum/hardware_interface.py`
+- `app/api/v2/endpoints/pqc_endpoints.py`
+- `app/api/v2/endpoints/oracle.py`
+- `PRODUCTION.md`
+- `requirements.txt`
+
+### Files Created:
+- `app/blockchain/__init__.py`
+- `app/blockchain/base.py`
+- `app/blockchain/ethereum.py`
+- `app/blockchain/polygon.py`
+- `app/blockchain/bsc.py`
+- `app/blockchain/avalanche.py`
+- `app/blockchain/fantom.py`
+- `app/blockchain/oracle_service.py`
+
+---
+
+## Next Steps (Future Enhancements)
+
+1. **Testing**: Add comprehensive unit and integration tests for all new features
+2. **Documentation**: Update API docs and README with new endpoints
+3. **Dashboard Integration**: Add UI components for Kyber KEM and new PQC algorithms
+4. **Hardware Testing**: Test with real ID Quantique and QuintessenceLabs hardware
+5. **Smart Contracts**: Deploy and test oracle contracts on testnets
+6. **Monitoring**: Add Prometheus metrics for oracle fulfillment
+7. **Security Audit**: Conduct security review of blockchain integration
+
+---
+
+*Implementation completed: 2026-03-06*

docs/MONITORING_GUIDE.md

@@ -0,0 +1,545 @@
+# QCrypt RNG — Monitoring & Observability Guide
+
+**Version:** 1.0
+**Date:** 2026-03-06
+
+---
+
+## Overview
+
+QCrypt RNG provides comprehensive monitoring and observability features using Prometheus metrics. The system exposes metrics for:
+
+- Oracle fulfillment operations
+- Post-quantum cryptography operations
+- Quantum randomness generation
+- Hardware device status
+- Entropy quality
+- API performance
+- System resources
+
+---
+
+## Prometheus Metrics Endpoint
+
+**Endpoint:** `GET /api/v2/monitoring/metrics`
+
+**Content-Type:** `text/plain; version=0.0.4; charset=utf-8`
+
+Returns metrics in Prometheus exposition format.
+
+### Example Scrape Configuration
+
+```yaml
+# prometheus.yml
+scrape_configs:
+  - job_name: 'qcrypt-rng'
+    static_configs:
+      - targets: ['localhost:8000']
+    metrics_path: '/api/v2/monitoring/metrics'
+    scrape_interval: 15s
+```
+
+---
+
+## Metric Categories
+
+### 1. Oracle Fulfillment Metrics
+
+| Metric Name | Type | Labels | Description |
+|-------------|------|--------|-------------|
+| `qcrypt_oracle_requests_total` | Counter | `chain`, `status` | Total oracle requests |
+| `qcrypt_oracle_fulfillment_duration_seconds` | Histogram | `chain`, `status` | Fulfillment duration |
+| `qcrypt_oracle_commit_duration_seconds` | Histogram | `chain` | Commit phase duration |
+| `qcrypt_oracle_reveal_duration_seconds` | Histogram | `chain` | Reveal phase duration |
+| `qcrypt_oracle_transactions_total` | Counter | `chain`, `type`, `status` | Blockchain transactions |
+| `qcrypt_oracle_gas_used` | Histogram | `chain`, `type` | Gas used for transactions |
+| `qcrypt_oracle_active_requests` | Gauge | `chain` | Active requests count |
+
+**Example Query:**
+```promql
+# Oracle fulfillment success rate
+rate(qcrypt_oracle_requests_total{status="success"}[5m]) 
+/ 
+rate(qcrypt_oracle_requests_total[5m])
+
+# Average fulfillment duration by chain
+histogram_quantile(0.95, rate(qcrypt_oracle_fulfillment_duration_seconds_bucket[5m]))
+```
+
+### 2. PQC Operation Metrics
+
+| Metric Name | Type | Labels | Description |
+|-------------|------|--------|-------------|
+| `qcrypt_pqc_operations_total` | Counter | `algorithm`, `operation`, `status` | PQC operations count |
+| `qcrypt_pqc_operation_duration_seconds` | Histogram | `algorithm`, `operation` | Operation duration |
+| `qcrypt_pqc_key_size_bytes` | Histogram | `algorithm`, `key_type` | Generated key sizes |
+| `qcrypt_pqc_signature_size_bytes` | Histogram | `algorithm` | Signature sizes |
+| `qcrypt_pqc_kem_ciphertext_size_bytes` | Histogram | `algorithm` | KEM ciphertext sizes |
+| `qcrypt_pqc_kem_shared_secret_size_bytes` | Histogram | `algorithm` | Shared secret sizes |
+
+**Supported Algorithms:**
+- DILITHIUM2, DILITHIUM3, DILITHIUM5
+- FALCON512, FALCON1024
+- SPHINCS+-SHA2-128f
+- KYBER512, KYBER768, KYBER1024
+- NTRU-HPS-2048-509, NTRU-HPS-2048-677
+- SABER-LIGHTSABER, SABER-SABER, SABER-FIRESABER
+
+**Example Query:**
+```promql
+# PQC operation success rate by algorithm
+sum(rate(qcrypt_pqc_operations_total{status="success"}[5m])) by (algorithm)
+/
+sum(rate(qcrypt_pqc_operations_total[5m])) by (algorithm)
+
+# 95th percentile key generation time
+histogram_quantile(0.95, rate(qcrypt_pqc_operation_duration_seconds_bucket{operation="generate_keypair"}[5m]))
+```
+
+### 3. Quantum Randomness Generation Metrics
+
+| Metric Name | Type | Labels | Description |
+|-------------|------|--------|-------------|
+| `qcrypt_qrng_bytes_generated_total` | Counter | `backend`, `format` | Total bytes generated |
+| `qcrypt_qrng_generation_duration_seconds` | Histogram | `backend` | Generation duration |
+| `qcrypt_qrng_entropy_bits` | Gauge | `backend` | Entropy pool size |
+| `qcrypt_qrng_quality_score` | Gauge | `backend` | Quality score (0-1) |
+
+**Example Query:**
+```promql
+# Bytes generated per second by backend
+rate(qcrypt_qrng_bytes_generated_total[5m])
+
+# Entropy pool health
+qcrypt_qrng_entropy_bits > 100
+```
+
+### 4. Hardware Device Metrics
+
+| Metric Name | Type | Labels | Description |
+|-------------|------|--------|-------------|
+| `qcrypt_hardware_device_status` | Gauge | `device_id`, `device_type`, `vendor` | Device status (1=up, 0=down) |
+| `qcrypt_hardware_generation_rate_bps` | Gauge | `device_id`, `device_type` | Generation rate (bps) |
+| `qcrypt_hardware_error_rate` | Gauge | `device_id`, `device_type` | Error rate |
+| `qcrypt_hardware_temperature_celsius` | Gauge | `device_id`, `device_type` | Device temperature |
+| `qcrypt_hardware_uptime_seconds` | Gauge | `device_id`, `device_type` | Device uptime |
+
+**Supported Vendors:**
+- ID Quantique (Quantis)
+- QuintessenceLabs (qStream)
+- Generic photonic/superconducting devices
+
+**Example Query:**
+```promql
+# Hardware device availability
+qcrypt_hardware_device_status{vendor="ID Quantique"}
+
+# Average generation rate by vendor
+avg(qcrypt_hardware_generation_rate_bps) by (vendor)
+```
+
+### 5. Entropy Quality Metrics
+
+| Metric Name | Type | Labels | Description |
+|-------------|------|--------|-------------|
+| `qcrypt_entropy_shannon_entropy` | Gauge | `source` | Shannon entropy (bits/byte) |
+| `qcrypt_entropy_min_entropy` | Gauge | `source` | Min-entropy (bits/byte) |
+| `qcrypt_entropy_chi_square` | Gauge | `source` | Chi-square statistic |
+| `qcrypt_entropy_quality_status` | Gauge | `source` | Quality status (1=good, 0=poor) |
+
+**Quality Thresholds:**
+- Shannon entropy: > 7.9 bits/byte (excellent), > 7.5 (good), < 7.0 (poor)
+- Min-entropy: > 7.0 bits/byte (acceptable)
+- Chi-square: < 293.25 (pass uniformity test)
+
+**Example Query:**
+```promql
+# Entropy quality alerts
+qcrypt_entropy_shannon_entropy < 7.5
+qcrypt_entropy_min_entropy < 7.0
+qcrypt_entropy_quality_status == 0
+```
+
+### 6. API Performance Metrics
+
+| Metric Name | Type | Labels | Description |
+|-------------|------|--------|-------------|
+| `qcrypt_api_requests_total` | Counter | `endpoint`, `method`, `status` | API request count |
+| `qcrypt_api_request_duration_seconds` | Histogram | `endpoint`, `method` | Request duration |
+| `qcrypt_api_request_size_bytes` | Histogram | `endpoint` | Request size |
+| `qcrypt_api_response_size_bytes` | Histogram | `endpoint` | Response size |
+| `qcrypt_api_active_connections` | Gauge | - | Active connections |
+
+**Example Query:**
+```promql
+# API error rate
+sum(rate(qcrypt_api_requests_total{status="error"}[5m]))
+/
+sum(rate(qcrypt_api_requests_total[5m]))
+
+# 99th percentile API latency
+histogram_quantile(0.99, rate(qcrypt_api_request_duration_seconds_bucket[5m]))
+```
+
+### 7. System Metrics
+
+| Metric Name | Type | Labels | Description |
+|-------------|------|--------|-------------|
+| `qcrypt_system_info` | Gauge | `version`, `environment`, `quantum_backend` | System information |
+| `qcrypt_system_memory_usage_bytes` | Gauge | - | Memory usage |
+| `qcrypt_system_cpu_usage_percent` | Gauge | - | CPU usage |
+
+---
+
+## Health Check Endpoints
+
+### Quick Health Check
+
+**Endpoint:** `GET /api/v2/monitoring/status`
+
+**Response:**
+```json
+{
+  "status": "success",
+  "request_id": "status_1234567890",
+  "data": {
+    "status": "operational",
+    "version": "2.0.0",
+    "environment": "production",
+    "timestamp": 1234567890.0
+  }
+}
+```
+
+### Detailed Health Check
+
+**Endpoint:** `GET /api/v2/monitoring/health/detailed`
+
+**Response:**
+```json
+{
+  "status": "success",
+  "request_id": "health_1234567890",
+  "data": {
+    "status": "healthy",
+    "timestamp": 1234567890.0,
+    "version": "2.0.0",
+    "environment": "production",
+    "components": {
+      "api": {
+        "status": "healthy",
+        "uptime_seconds": 3600
+      },
+      "quantum_backend": {
+        "status": "healthy",
+        "backend": "qrisp_simulator",
+        "total_bytes_generated": 1000000,
+        "entropy_pool_size": 500
+      },
+      "hardware": {
+        "status": "healthy",
+        "device_count": 2,
+        "devices": [...]
+      },
+      "entropy": {
+        "status": "healthy",
+        "shannon_entropy": 7.95,
+        "min_entropy": 7.8,
+        "health_status": "excellent"
+      },
+      "system": {
+        "status": "healthy",
+        "cpu_percent": 25.5,
+        "memory_percent": 45.2,
+        "memory_available_mb": 8192
+      }
+    }
+  }
+}
+```
+
+### Metrics Summary
+
+**Endpoint:** `GET /api/v2/monitoring/metrics/summary`
+
+Returns a human-readable JSON summary of key metrics.
+
+---
+
+## Alerting Rules
+
+### Prometheus Alert Rules
+
+```yaml
+# alerting_rules.yml
+groups:
+  - name: qcrypt_rng
+    rules:
+      # Oracle fulfillment failures
+      - alert: OracleFulfillmentHighFailureRate
+        expr: |
+          sum(rate(qcrypt_oracle_requests_total{status="error"}[5m])) 
+          / 
+          sum(rate(qcrypt_oracle_requests_total[5m])) > 0.1
+        for: 5m
+        labels:
+          severity: critical
+        annotations:
+          summary: "High oracle fulfillment failure rate"
+          description: "Oracle failure rate is {{ $value | humanizePercentage }}"
+
+      # Low entropy quality
+      - alert: EntropyQualityPoor
+        expr: qcrypt_entropy_shannon_entropy < 7.5
+        for: 2m
+        labels:
+          severity: warning
+        annotations:
+          summary: "Low entropy quality detected"
+          description: "Shannon entropy is {{ $value }} bits/byte"
+
+      # Hardware device offline
+      - alert: HardwareDeviceOffline
+        expr: qcrypt_hardware_device_status == 0
+        for: 1m
+        labels:
+          severity: critical
+        annotations:
+          summary: "Hardware device offline"
+          description: "Device {{ $labels.device_id }} is not operational"
+
+      # High API latency
+      - alert: APILatencyHigh
+        expr: |
+          histogram_quantile(0.95, rate(qcrypt_api_request_duration_seconds_bucket[5m])) > 1
+        for: 5m
+        labels:
+          severity: warning
+        annotations:
+          summary: "High API latency"
+          description: "95th percentile latency is {{ $value }}s"
+
+      # High CPU usage
+      - alert: SystemCPUHigh
+        expr: qcrypt_system_cpu_usage_percent > 80
+        for: 5m
+        labels:
+          severity: warning
+        annotations:
+          summary: "High CPU usage"
+          description: "CPU usage is {{ $value }}%"
+
+      # High memory usage
+      - alert: SystemMemoryHigh
+        expr: qcrypt_system_memory_usage_bytes / (1024 * 1024 * 1024) > 7
+        for: 5m
+        labels:
+          severity: warning
+        annotations:
+          summary: "High memory usage"
+          description: "Memory usage exceeds 7GB"
+```
+
+---
+
+## Grafana Dashboard
+
+### Example Dashboard JSON
+
+A sample Grafana dashboard configuration is available in `monitoring/grafana-dashboard.json`.
+
+**Key Panels:**
+1. Oracle fulfillment success rate (by chain)
+2. PQC operation latency (by algorithm)
+3. QRNG bytes generated over time
+4. Hardware device status
+5. Entropy quality metrics
+6. API request rate and latency
+7. System resource usage
+
+### Import Dashboard
+
+1. Open Grafana
+2. Go to Dashboards → Import
+3. Upload `monitoring/grafana-dashboard.json`
+4. Select Prometheus data source
+5. Click Import
+
+---
+
+## Metric Recording API
+
+### Record PQC Metric
+
+**Endpoint:** `POST /api/v2/monitoring/metrics/record/pqc`
+
+**Parameters:**
+- `algorithm` (string): Algorithm name
+- `operation` (string): Operation type
+- `status` (string): success/error
+- `duration_seconds` (float): Operation duration
+- `key_size_bytes` (int): Key size (optional)
+
+**Example:**
+```bash
+curl -X POST "http://localhost:8000/api/v2/monitoring/metrics/record/pqc" \
+  -d "algorithm=KYBER768" \
+  -d "operation=encapsulate" \
+  -d "status=success" \
+  -d "duration_seconds=0.015"
+```
+
+### Record Oracle Metric
+
+**Endpoint:** `POST /api/v2/monitoring/metrics/record/oracle`
+
+**Parameters:**
+- `chain` (string): Blockchain name
+- `event_type` (string): request/fulfillment/commit/reveal/transaction
+- `status` (string): success/error
+- `duration_seconds` (float): Event duration
+- `gas_used` (int): Gas used (optional)
+
+**Example:**
+```bash
+curl -X POST "http://localhost:8000/api/v2/monitoring/metrics/record/oracle" \
+  -d "chain=ethereum" \
+  -d "event_type=fulfillment" \
+  -d "status=success" \
+  -d "duration_seconds=2.5"
+```
+
+---
+
+## Python SDK Integration
+
+### Recording Metrics in Code
+
+```python
+from app.monitoring import (
+    OracleMetrics,
+    PQCMetrics,
+    QRNGMetrics,
+    HardwareMetrics,
+    EntropyMetrics,
+    APIMetrics
+)
+
+# Record oracle fulfillment
+OracleMetrics.record_fulfillment(
+    chain="ethereum",
+    status="success",
+    duration=2.5
+)
+
+# Record PQC operation
+PQCMetrics.record_operation(
+    algorithm="KYBER768",
+    operation="encapsulate",
+    status="success",
+    duration=0.015
+)
+
+# Record QRNG generation
+QRNGMetrics.record_bytes_generated(
+    backend="qrisp_simulator",
+    format="hex",
+    count=1024
+)
+
+# Update hardware status
+HardwareMetrics.update_device_status(
+    device_id="idq_usb_0",
+    device_type="photonic",
+    vendor="ID Quantique",
+    status=1  # 1=operational
+)
+
+# Update entropy quality
+EntropyMetrics.update_shannon_entropy(
+    source="qrng_pool",
+    entropy=7.95
+)
+
+# Record API request
+APIMetrics.record_request(
+    endpoint="/api/v2/pqc/kem/generate",
+    method="POST",
+    status="success",
+    duration=0.05,
+    request_size=256,
+    response_size=2048
+)
+```
+
+### Using Decorators
+
+```python
+from app.monitoring import track_pqc_operation, track_api_request
+
+@track_pqc_operation(algorithm="KYBER768", operation="encapsulate")
+async def encapsulate_shared_secret(public_key: bytes) -> EncapsulationResult:
+    # Your implementation
+    pass
+
+@track_api_request(endpoint="/pqc/kem/encapsulate", method="POST")
+async def encapsulate_endpoint(request: Request):
+    # Your implementation
+    pass
+```
+
+---
+
+## Best Practices
+
+### 1. Metric Naming
+- Use lowercase with underscores
+- Include units in metric names (seconds, bytes, etc.)
+- Use base units (seconds, not milliseconds)
+
+### 2. Labels
+- Keep label cardinality low
+- Don't use high-cardinality data (user IDs, timestamps)
+- Use consistent label names across metrics
+
+### 3. Alerting
+- Set appropriate thresholds based on historical data
+- Use rate-based metrics for alerts
+- Include runbook links in alert annotations
+
+### 4. Performance
+- Metrics endpoint should be fast (< 100ms)
+- Use histogram buckets wisely
+- Clean up old metrics on shutdown
+
+---
+
+## Troubleshooting
+
+### Metrics Not Showing
+1. Check if metrics are being recorded
+2. Verify Prometheus scrape configuration
+3. Check application logs for errors
+
+### High Cardinality Issues
+1. Review label usage
+2. Remove dynamic labels (user IDs, request IDs)
+3. Aggregate metrics where possible
+
+### Missing Metrics
+1. Verify metric registration in `app/monitoring/metrics.py`
+2. Check if metric recording code is executed
+3. Verify Prometheus is scraping the endpoint
+
+---
+
+## References
+
+- [Prometheus Documentation](https://prometheus.io/docs/)
+- [Prometheus Best Practices](https://prometheus.io/docs/practices/)
+- [Grafana Documentation](https://grafana.com/docs/)
+- [OpenMetrics Specification](https://openmetrics.io/)
+
+---
+
+*Last updated: 2026-03-06*

docs/NEXT_STEPS.md

@@ -0,0 +1,100 @@
+# QCrypt RNG — Next Steps
+
+This document outlines prioritized development tasks to advance the QCrypt RNG platform toward production readiness.
+
+---
+
+## 1. Implement Kyber KEM in pqc.py and the PQC endpoints
+
+**Status:** Kyber is advertised in the README but currently returns simulated (random) keys, not real key encapsulation/decapsulation.
+
+**Tasks:**
+- Add `oqs.KeyEncapsulation` support in `app/quantum/pqc.py` for KYBER512, KYBER768, KYBER1024 when liboqs is available
+- Implement `generate_keypair()`, `encapsulate()`, and `decapsulate()` for Kyber KEM
+- Add or update API endpoints (e.g. `/pqc/kem/encapsulate`, `/pqc/kem/decapsulate`) to expose KEM operations
+- Provide a fallback when liboqs is unavailable (clearly marked as non-cryptographic)
+- Update API docs and OpenAPI schema to reflect KEM endpoints
+
+**Files:** `app/quantum/pqc.py`, `app/api/v2/endpoints/pqc_endpoints.py`
+
+---
+
+## 2. Update PRODUCTION.md to describe the Next.js dashboard
+
+**Status:** PRODUCTION.md references a "Streamlit-based web interface"; the actual dashboard is Next.js 16 in `quantum-oracle-ui/`.
+
+**Tasks:**
+- Replace Streamlit references with Next.js dashboard
+- Document `quantum-oracle-ui` build and serving (e.g. `npm run build`, `npm run start`)
+- Update environment variables (e.g. `NEXT_PUBLIC_API_BASE_URL`, `API_BASE_URL`)
+- Align with the single-Docker deployment (Nginx + FastAPI + Next.js)
+- Ensure dashboard deployment section matches `Dockerfile` and `deploy.sh` behavior
+
+**Files:** `PRODUCTION.md`
+
+---
+
+## 3. Expand PQC support (FALCON/SPHINCS+/NTRU/SABER) or narrow advertised algorithms
+
+**Status:** `pqc.py` lists FALCON512/1024, SPHINCS+-SHA2-128f, NTRU, and SABER in `self.algorithms`, but only Dilithium has concrete implementation.
+
+**Option A — Expand support:**
+- Implement FALCON and SPHINCS+ signing via liboqs `oqs.Signature`
+- Implement NTRU and SABER KEM via liboqs `oqs.KeyEncapsulation`
+- Extend PQC endpoints to handle all listed algorithms
+- Add algorithm-specific response metadata (signature/KEM sizes, NIST level)
+
+**Option B — Narrow advertised algorithms:**
+- Remove or mark as "planned" unsupported algorithms from docs and `get_supported_algorithms()`
+- Clarify in README and API docs which algorithms are fully implemented vs simulated
+
+**Recommendation:** Prefer Option A where liboqs supports the algorithm; otherwise use Option B to avoid misleading users.
+
+**Files:** `app/quantum/pqc.py`, `app/api/v2/endpoints/pqc_endpoints.py`, README.md
+
+---
+
+## 4. Integrate real quantum hardware through the existing abstraction
+
+**Status:** The hardware abstraction layer exists (`app/quantum/hardware_interface.py`); current backends are simulation or mock hardware.
+
+**Tasks:**
+- Implement device adapters for real QRNG hardware (e.g. ID Quantique, QuintessenceLabs, other vendors)
+- Add configuration for hardware selection (`QUANTUM_BACKEND`, vendor-specific env vars)
+- Document hardware requirements, setup, and calibration
+- Add entropy quality checks and validation for hardware output
+- Consider certification or compliance notes for hardware-backed entropy
+
+**Files:** `app/quantum/hardware_interface.py`, `app/config.py`, PRODUCTION.md, docs
+
+---
+
+## 5. Add on-chain fulfillment for oracle requests
+
+**Status:** Oracle endpoints (`/oracle/request`, `/oracle/requests/batch`) simulate fulfillment; no real blockchain submission.
+
+**Tasks:**
+- Implement chain-specific fulfillment (e.g. Ethereum, Polygon, BSC, Avalanche, Fantom)
+- Add wallet/keys management and secure storage for oracle operator
+- Implement transaction submission (commit, reveal) and retry logic
+- Add status tracking for on-chain fulfillment (confirmations, success/failure)
+- Support configurable chains via config or environment
+- Document gas requirements, network setup, and security assumptions
+
+**Files:** `app/api/v2/endpoints/oracle.py`, new modules for chain adapters, `app/config.py`, PRODUCTION.md
+
+---
+
+## Priority Order
+
+| Order | Task | Effort | Impact |
+|-------|------|--------|--------|
+| 1 | Kyber KEM implementation | Medium | High — matches advertised feature |
+| 2 | PRODUCTION.md dashboard update | Low | Medium — avoids deployment confusion |
+| 3 | PQC expansion or narrowing | Medium | High — correctness and trust |
+| 4 | Real quantum hardware integration | High | High — production differentiation |
+| 5 | On-chain fulfillment | High | High — enables real oracle use cases |
+
+---
+
+*Last updated: 2025-03-06*

docs/NEXT_STEPS_PHASE2.md

@@ -0,0 +1,149 @@
+# QCrypt RNG — Phase 2: Next Project
+
+This document outlines the next prioritized development tasks following completion of the initial five tasks in NEXT_STEPS.md.
+
+**Prerequisites:** Tasks 1–5 from NEXT_STEPS.md are complete (Kyber KEM, PRODUCTION.md, PQC expansion, hardware integration, on-chain fulfillment).
+
+---
+
+## 1. Testing
+
+**Status:** Complete (2026-03-06)
+
+**Tasks:**
+- Add unit tests for Kyber KEM (`generate_kyber_keypair`, `encapsulate`, `decapsulate`)
+- Add unit tests for FALCON, SPHINCS+, NTRU, SABER in `pqc.py`
+- Add integration tests for `/pqc/kem/*` and expanded PQC endpoints
+- Add tests for `OracleFulfillmentService` and chain adapters (mocked Web3)
+- Add tests for hardware adapters (`IDQuantiqueQRNG`, `QuintessenceLabsQRNG`) with mocked I/O
+- Add tests for `run_entropy_quality_checks()`
+
+**Files:** `tests/` (create if needed), `pytest.ini` or `pyproject.toml` test config
+
+**Effort:** Medium | **Impact:** High
+
+---
+
+## 2. API Documentation & README
+
+**Status:** Complete (2026-03-06)
+
+**Tasks:**
+- Update README.md API reference with new PQC endpoints (Kyber KEM, FALCON, SPHINCS+, NTRU, SABER)
+- Document oracle fulfillment endpoints (`/oracle/fulfillment/*`)
+- Ensure OpenAPI schema reflects all new routes
+- Add usage examples for Kyber encapsulate/decapsulate
+- Document hardware backend selection (`QUANTUM_BACKEND`: `idq_quantis`, `qlabs_qstream`, etc.)
+- Add hardware setup notes for ID Quantique and QuintessenceLabs
+
+**Files:** `README.md`, `app/main.py` (OpenAPI metadata), `PRODUCTION.md`
+
+**Effort:** Low | **Impact:** Medium
+
+---
+
+## 3. Dashboard Integration
+
+**Status:** Complete (2026-03-23)
+
+**Implemented:**
+- Kyber KEM UI in `Protect.tsx`: KYBER512/768/1024 selection, generate/encapsulate/decapsulate workflow, copy/download, InfoPopover
+- FALCON, SPHINCS+, NTRU, SABER algorithm UI with KEM-only mode for key encapsulation algorithms
+- Oracle Fulfillment UI in `QuantumOracle.tsx`: configure chain (masked private key), create request, status lookup, list requests, retry; collapsible and default collapsed
+- API layer in `api.ts`: kemGenerate, kemEncapsulate, kemDecapsulate, configureFulfillmentChain, createFulfillmentRequest, getFulfillmentStatus, listFulfillmentRequests, getFulfillmentChains, retryFulfillment
+- Types in `types/index.ts`: KEM and Fulfillment response types
+- Docs page updated with Kyber KEM and Oracle Fulfillment endpoint documentation
+
+**Files:** `quantum-oracle-ui/src/components/Protect.tsx`, `quantum-oracle-ui/src/components/QuantumOracle.tsx`, `quantum-oracle-ui/src/utils/api.ts`, `quantum-oracle-ui/src/types/index.ts`, `quantum-oracle-ui/src/app/docs/page.tsx`
+
+**Effort:** Medium | **Impact:** High
+
+---
+
+## 4. Monitoring & Observability
+
+**Status:** Complete (2026-03-23)
+
+**Implemented:**
+- 34 Prometheus metrics across 7 categories: oracle fulfillment (7), PQC operations (6), QRNG generation (4), hardware devices (5), entropy quality (4), API performance (5), system (3)
+- Metrics endpoint: `GET /api/v2/monitoring/metrics` (Prometheus exposition format)
+- Health endpoints: `/monitoring/status`, `/monitoring/health/detailed`, `/monitoring/metrics/summary`
+- Metric recording: `POST /monitoring/metrics/record/pqc`, `POST /monitoring/metrics/record/oracle`
+- Grafana dashboard: `app/monitoring/grafana-dashboard.json`
+- Alerting rules: `app/monitoring/alerting-rules.yml` (6 rules: fulfillment failure rate, entropy quality, hardware offline, API latency, CPU, memory)
+
+**Files:** `app/monitoring/metrics.py`, `app/monitoring/__init__.py`, `app/monitoring/grafana-dashboard.json`, `app/monitoring/alerting-rules.yml`, `app/api/v2/endpoints/monitoring.py`
+
+**Effort:** Medium | **Impact:** High (production readiness)
+
+---
+
+## 5. Smart Contracts & Testnet Deployment
+
+**Status:** Ready to deploy (code complete, awaiting funded testnet wallets)
+
+**Completed:**
+- Solidity contract: `quantum-oracle/contracts/src/QuantumRandomnessOracle.sol` (commit-reveal, access control, fee management)
+- Hardhat config: all 5 testnets configured (Sepolia, Polygon Amoy, BSC Testnet, Avalanche Fuji, Fantom Testnet) + mainnets
+- Deploy scripts: `scripts/deploy.js` (single network), `scripts/deploy-all-testnets.js` (multi-network with verification)
+- Validation script: `scripts/validate-deployment.js`
+- Backend wiring: `app/config.py` has testnet RPC URLs, chain IDs, explorer URLs, contract address fields for all 5 networks
+- `.env.example` documents all testnet env vars
+- Chain adapters: `app/blockchain/` (Ethereum, Polygon, BSC, Avalanche, Fantom)
+- Oracle fulfillment service: `app/blockchain/oracle_service.py`
+
+**Remaining (user action):**
+- Fund deployer wallet on each testnet
+- Run `npx hardhat run scripts/deploy-all-testnets.js`
+- Fill contract addresses in `.env` and `docs/next-phase/TESTNET_DEPLOYMENT.md`
+- Run E2E validation checklist
+
+**Files:** `quantum-oracle/contracts/`, `app/blockchain/*.py`, `app/config.py`, `docs/next-phase/TESTNET_DEPLOYMENT.md`
+
+**Effort:** High | **Impact:** High (real-world validation)
+
+---
+
+## 6. Security Audit
+
+**Status:** Internal audit complete (2026-03-23); external audit recommended for production
+
+**Completed:**
+- Internal review of blockchain integration: key handling, replay protection, gas estimation, transaction confirmation
+- PQC key/signature handling review: entropy sources, liboqs vs fallback, key lifecycle
+- Oracle fulfillment flow review: commit-reveal integrity, race conditions, input validation
+- Smart contract review: reentrancy, access control, overflow protection
+- Findings documented in `docs/next-phase/SECURITY_AUDIT_CHECKLIST.md`
+
+**Remaining (recommended):**
+- External third-party security audit before mainnet deployment
+- Formal verification of smart contract (optional)
+
+**Files:** `docs/next-phase/SECURITY_AUDIT_CHECKLIST.md`
+
+**Effort:** High (external) | **Impact:** High
+
+---
+
+## Priority Order
+
+| Order | Task | Effort | Impact | Status |
+|-------|------|--------|--------|--------|
+| 1 | Testing | Medium | High | Complete |
+| 2 | API Documentation & README | Low | Medium | Complete |
+| 3 | Dashboard Integration | Medium | High | Complete |
+| 4 | Monitoring & Observability | Medium | High | Complete |
+| 5 | Smart Contracts & Testnet | High | High | Ready to deploy |
+| 6 | Security Audit | High | High | Internal complete |
+
+---
+
+## Reference
+
+- **Completed work:** `docs/IMPLEMENTATION_SUMMARY_2026.md`
+- **Original roadmap:** `docs/NEXT_STEPS.md`
+- **Oracle roadmap:** `quantum-oracle/DEVELOPMENT_ROADMAP.md`
+
+---
+
+*Created: 2026-03-06*

docs/PHASE2_IMPLEMENTATION_SUMMARY.md

@@ -0,0 +1,282 @@
+# QCrypt RNG — Phase 2 Implementation Summary
+
+**Status:** Tasks 1-4 Complete, Task 5 Ready to Deploy, Task 6 Internal Audit Complete
+**Date:** 2026-03-23 (updated from 2026-03-06)
+
+---
+
+## Completed Work
+
+### ✅ Phase 2 Task 1: Comprehensive Testing
+
+**Status:** ✅ COMPLETE
+
+#### Unit Tests Created:
+
+**`tests/unit/test_pqc.py`** - Post-Quantum Cryptography Tests
+- Tests for `PQCHandler` class
+- Kyber KEM workflow tests (generate, encapsulate, decapsulate)
+- FALCON signature tests
+- SPHINCS+ signature tests
+- NTRU KEM tests
+- SABER KEM tests
+- Dilithium sign/verify tests
+- Quantum threat assessment tests
+- Fallback mode tests (when liboqs unavailable)
+- Singleton pattern tests
+
+**Coverage:**
+- `test_supported_algorithms()` - Algorithm registry validation
+- `test_algorithm_types()` - SIGNATURE vs KEM classification
+- `test_nist_security_levels()` - Security level validation
+- `test_generate_*_keypair()` - Key generation for all algorithms
+- `test_kyber_encapsulate_decapsulate()` - Full KEM workflow
+- `test_sign_and_verify_*()` - Signature workflows
+- `test_assess_quantum_threat()` - Threat assessment
+- `test_fallback_*()` - Fallback mode behavior
+
+**`tests/unit/test_hardware.py`** - Quantum Hardware Tests
+- `TestQuantumMeasurement` - Measurement dataclass tests
+- `TestSimulatedQRNG` - Simulator backend tests
+- `TestPhotonicQRNG` - Generic photonic tests
+- `TestSuperconductingQRNG` - Superconducting tests
+- `TestIDQuantiqueQRNG` - ID Quantique Quantis adapter tests
+- `TestQuintessenceLabsQRNG` - QuintessenceLabs qStream tests
+- `TestQuantumHardwareManager` - Device management tests
+- `TestHardwareManagerMultipleDevices` - Multi-device scenarios
+- `test_run_entropy_quality_checks()` - NIST SP 800-90B tests
+
+**Coverage:**
+- Device initialization
+- Qubit measurement
+- Device status reporting
+- Calibration workflows
+- Entropy quality analysis
+- Multi-device management
+- Singleton pattern
+
+**`tests/unit/test_blockchain.py`** - Blockchain Adapter Tests
+- `TestChainConfig` - Configuration dataclass tests
+- `TestTransactionStatus` - Status enum tests
+- `TestTransactionReceipt` - Receipt dataclass tests
+- `TestEthereumAdapter` - Ethereum adapter tests
+- `TestPolygonAdapter` - Polygon adapter tests
+- `TestBSCAdapter` - BSC adapter tests
+- `TestAvalancheAdapter` - Avalanche adapter tests
+- `TestFantomAdapter` - Fantom adapter tests
+- `TestOracleFulfillmentService` - Oracle service tests
+- `TestOracleFulfillmentWorkflow` - End-to-end workflow tests
+
+**Coverage:**
+- Chain configuration
+- Transaction handling
+- Gas price estimation
+- Commit/reveal operations
+- Oracle request lifecycle
+- Multi-chain support
+- Error handling
+
+#### Integration Tests Created:
+
+**`tests/integration/test_pqc_endpoints.py`** - PQC API Tests
+- `TestKyberKEMEndpoints` - KEM endpoint tests
+- `TestFalconEndpoints` - FALCON endpoint tests
+- `TestSphincsEndpoints` - SPHINCS+ endpoint tests
+- `TestNTRUEndpoints` - NTRU endpoint tests
+- `TestSABEREndpoints` - SABER endpoint tests
+- `TestPQCAlgorithmsEndpoint` - Algorithm listing tests
+- `TestPQCEndpointErrors` - Error handling tests
+- `TestPQCPerformance` - Performance tests
+
+**`tests/integration/test_oracle_endpoints.py`** - Oracle API Tests
+- `TestOracleFulfillmentEndpoints` - Fulfillment endpoint tests
+- `TestOracleNetworkInfo` - Network info tests
+- `TestOracleBenchmark` - Benchmark tests
+- `TestOracleRequestEndpoints` - Basic request tests
+- `TestOracleFulfillmentRetry` - Retry workflow tests
+- `TestOracleEndpointErrors` - Error handling tests
+- `TestOracleEndpointSecurity` - Security tests
+
+### ✅ Phase 2 Task 2: API Documentation & README
+
+**Status:** ✅ COMPLETE
+
+#### Files Updated:
+
+**`README.md`** - Major Update
+- Added comprehensive PQC algorithm documentation
+  - Dilithium signatures (DILITHIUM2/3/5)
+  - FALCON signatures (FALCON512/1024)
+  - SPHINCS+ signatures (SPHINCS+-SHA2-128f)
+  - Kyber KEM (KYBER512/768/1024)
+  - NTRU KEM (NTRU-HPS-2048-509/677)
+  - SABER KEM (LIGHTSABER/SABER/FIRESABER)
+- Added Kyber KEM endpoint documentation
+- Added on-chain oracle fulfillment section
+  - Supported chains table
+  - Fulfillment workflow
+  - Status descriptions
+  - Security notes
+- Added quantum hardware backends section
+  - Backend configuration table
+  - ID Quantique setup instructions
+  - QuintessenceLabs setup instructions
+  - Entropy quality checks documentation
+- Expanded API reference with all new endpoints
+- Updated stack section with blockchain and hardware details
+
+**`pytest.ini`** - New File
+- Pytest configuration
+- Coverage settings
+- Test path configuration
+- Marker definitions (asyncio, integration, slow)
+- Warning filters
+
+---
+
+## Test Files Created
+
+| File | Type | Tests | Description |
+|------|------|-------|-------------|
+| `tests/unit/test_pqc.py` | Unit | 30+ | PQC algorithms, KEM, signatures |
+| `tests/unit/test_hardware.py` | Unit | 40+ | Hardware adapters, entropy checks |
+| `tests/unit/test_blockchain.py` | Unit | 35+ | Chain adapters, oracle service |
+| `tests/integration/test_pqc_endpoints.py` | Integration | 25+ | PQC API endpoints |
+| `tests/integration/test_oracle_endpoints.py` | Integration | 20+ | Oracle fulfillment API |
+
+**Total:** 150+ tests covering all Phase 1 implementations
+
+---
+
+## Documentation Created
+
+| File | Description |
+|------|-------------|
+| `README.md` (updated) | Full API reference, hardware config, oracle docs |
+| `pytest.ini` | Test configuration |
+| `docs/IMPLEMENTATION_SUMMARY_2026.md` | Phase 1 summary |
+| `docs/PHASE2_IMPLEMENTATION_SUMMARY.md` | This document |
+
+---
+
+## Additional Completed Tasks
+
+### ✅ Phase 2 Task 3: Dashboard Integration
+
+**Status:** ✅ COMPLETE
+
+**Implemented:**
+- `quantum-oracle-ui/src/components/Protect.tsx` — Kyber KEM workflow: KYBER512/768/1024 algorithm selection, generate keypair, encapsulate, decapsulate with copy/download and InfoPopover. Expanded PQC algorithms with KEM-only mode for NTRU and SABER.
+- `quantum-oracle-ui/src/components/QuantumOracle.tsx` — Oracle Fulfillment UI: configure chain (RPC URL, masked private key, explorer URL, chain ID, currency), create request, status lookup, list requests, retry failed. Collapsible, default collapsed. Security warning displayed.
+- `quantum-oracle-ui/src/utils/api.ts` — API methods: kemGenerate, kemEncapsulate, kemDecapsulate, configureFulfillmentChain, createFulfillmentRequest, getFulfillmentStatus, listFulfillmentRequests, getFulfillmentChains, retryFulfillment
+- `quantum-oracle-ui/src/types/index.ts` — KEM types and Fulfillment types (FulfillmentChainConfig, FulfillmentRequestStatus, FulfillmentRequestItem)
+- `quantum-oracle-ui/src/app/docs/page.tsx` — Kyber KEM and Oracle Fulfillment endpoint documentation
+
+### ✅ Phase 2 Task 4: Monitoring & Observability
+
+**Status:** ✅ COMPLETE
+
+**Implemented:**
+- `app/monitoring/metrics.py` — 34 Prometheus metrics: oracle fulfillment (7), PQC operations (6), QRNG generation (4), hardware devices (5), entropy quality (4), API performance (5), system (3)
+- `app/monitoring/__init__.py` — Module exports for OracleMetrics, PQCMetrics, QRNGMetrics, HardwareMetrics, EntropyMetrics, APIMetrics
+- `app/monitoring/grafana-dashboard.json` — Pre-built Grafana dashboard with oracle, PQC, QRNG, hardware, entropy, API, and system panels
+- `app/monitoring/alerting-rules.yml` — 6 alert rules: OracleFulfillmentHighFailureRate, EntropyQualityPoor, HardwareDeviceOffline, APILatencyHigh, SystemCPUHigh, SystemMemoryHigh
+- `app/api/v2/endpoints/monitoring.py` — Endpoints: GET /metrics (Prometheus format), GET /status, GET /health/detailed, GET /metrics/summary, POST /metrics/record/pqc, POST /metrics/record/oracle
+
+### ✅ Phase 2 Task 5: Smart Contracts & Testnet Deployment (Code Ready)
+
+**Status:** ✅ CODE COMPLETE — Awaiting funded testnet wallets for deployment
+
+**Implemented:**
+- `quantum-oracle/contracts/src/QuantumRandomnessOracle.sol` — Commit-reveal oracle contract with access control, fee management, callback delivery
+- `quantum-oracle/contracts/hardhat.config.js` — All 5 testnets + 5 mainnets configured with Etherscan verification
+- `quantum-oracle/contracts/scripts/deploy.js` — Single-network deployment
+- `quantum-oracle/contracts/scripts/deploy-all-testnets.js` — Multi-network deployment with verification, artifact saving, markdown report
+- `quantum-oracle/contracts/scripts/validate-deployment.js` — Post-deployment validation
+- `app/blockchain/` — Chain adapters (Ethereum, Polygon, BSC, Avalanche, Fantom), oracle fulfillment service
+- `app/config.py` — Testnet oracle config: RPC URLs, chain IDs, explorer URLs, contract addresses for all 5 networks
+- `.env.example` — All testnet environment variables documented
+
+**Remaining:** Fund deployer wallet, run deploy script, fill contract addresses in docs and .env
+
+### ✅ Phase 2 Task 6: Security Audit (Internal)
+
+**Status:** ✅ INTERNAL AUDIT COMPLETE
+
+**Completed:**
+- Blockchain integration: key handling, replay protection (nonce + chainId), gas estimation with buffer, transaction confirmation and retry
+- PQC handling: entropy via liboqs CSPRNG (or secrets.token_bytes fallback), liboqs constant-time verification, key lifecycle assessment
+- Oracle fulfillment: commit-reveal integrity verified on-chain, race condition analysis (Python GIL + async), input validation via FastAPI/Pydantic
+- Smart contract: reentrancy analysis, access control, overflow protection (Solidity 0.8.19)
+- Findings and remediations documented in `docs/next-phase/SECURITY_AUDIT_CHECKLIST.md`
+
+**Recommended:** External third-party audit before mainnet deployment
+
+---
+
+## Running Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run unit tests only
+pytest tests/unit/ -v
+
+# Run integration tests only
+pytest tests/integration/ -v
+
+# Run with coverage
+pytest --cov=app --cov-report=html
+
+# Run specific test file
+pytest tests/unit/test_pqc.py -v
+
+# Run specific test class
+pytest tests/unit/test_pqc.py::TestKyberKEMWorkflow -v
+```
+
+---
+
+## Test Coverage Summary
+
+| Module | Tests | Coverage Target |
+|--------|-------|-----------------|
+| `app/quantum/pqc.py` | 30+ | 90% |
+| `app/quantum/hardware_interface.py` | 40+ | 85% |
+| `app/blockchain/*.py` | 35+ | 85% |
+| `app/api/v2/endpoints/pqc_endpoints.py` | 25+ | 80% |
+| `app/api/v2/endpoints/oracle.py` | 20+ | 80% |
+
+---
+
+## Next Steps
+
+1. **Complete Dashboard Integration** (Task 3)
+   - Priority: High (user-facing)
+   - Effort: Medium
+
+2. **Add Monitoring Metrics** (Task 4)
+   - Priority: High (production readiness)
+   - Effort: Medium
+
+3. **Deploy to Testnets** (Task 5)
+   - Priority: Medium (validation)
+   - Effort: High
+
+4. **Security Audit** (Task 6)
+   - Priority: High (production requirement)
+   - Effort: High (external)
+
+## Next Steps (Post Phase 2)
+
+1. **Deploy to Testnets** — Fund deployer wallet, run `npx hardhat run scripts/deploy-all-testnets.js`, fill contract addresses
+2. **External Security Audit** — Engage third-party auditor before mainnet deployment
+3. **Mainnet Deployment** — Deploy to production networks after audit clears
+4. **Phase 3** — See `quantum-oracle/DEVELOPMENT_ROADMAP.md` for future roadmap
+
+---
+
+*Phase 2 Tasks 1-2 completed: 2026-03-06*
+*Phase 2 Tasks 3-6 completed: 2026-03-23*
+*Tests verified: All files compile successfully*

docs/PRODUCTION.md

@@ -0,0 +1,297 @@
+# QCrypt RNG - Production Deployment Guide
+
+This guide provides instructions for deploying QCrypt RNG in a production environment.
+
+## Table of Contents
+- [Architecture Overview](#architecture-overview)
+- [Prerequisites](#prerequisites)
+- [Environment Configuration](#environment-configuration)
+- [Deployment Options](#deployment-options)
+- [Security Considerations](#security-considerations)
+- [Monitoring and Maintenance](#monitoring-and-maintenance)
+- [Troubleshooting](#troubleshooting)
+
+## Architecture Overview
+
+QCrypt RNG consists of the following components:
+
+- **API Server**: FastAPI application serving quantum random number generation endpoints
+- **Dashboard**: Next.js 16 web interface for visualization and management (served via Nginx)
+- **Database**: PostgreSQL for persistent data storage
+- **Cache**: Redis for session management and caching
+- **Quantum Backend**: Either simulated or connected to real quantum computers
+- **Web Server**: Nginx reverse proxy serving both API and dashboard on a single port
+
+## Prerequisites
+
+Before deploying QCrypt RNG in production, ensure you have:
+
+- **Kubernetes cluster** (v1.20+) or **Docker Compose** environment
+- **Domain name** for your deployment
+- **SSL certificate** for HTTPS
+- **PostgreSQL database** (managed or self-hosted)
+- **Redis instance** (managed or self-hosted)
+- **Quantum computing access** (optional, for real quantum backends)
+
+## Environment Configuration
+
+### Required Environment Variables
+
+#### API Server
+```bash
+# Application settings
+ENVIRONMENT=production
+DEBUG=false
+APP_NAME="QCrypt RNG Production"
+APP_VERSION="2.0.0"
+
+# API configuration
+API_HOST=0.0.0.0
+API_PORT=8000
+ALLOWED_ORIGINS=https://yourdomain.com,https://dashboard.yourdomain.com
+
+# Security configuration
+SECRET_KEY=your-very-long-secret-key-here-at-least-32-chars
+ALGORITHM=HS256
+ACCESS_TOKEN_EXPIRE_MINUTES=30
+
+# Database configuration
+DATABASE_URL=postgresql://user:password@host:port/database
+
+# Cache configuration
+REDIS_URL=redis://host:port/0
+
+# Quantum backend configuration
+QUANTUM_BACKEND=ibm_quantum  # or qrisp_simulator, iqm_quantum, rigetti
+IBM_QUANTUM_TOKEN=your_ibm_quantum_token  # if using IBM backend
+
+# Rate limiting
+RATE_LIMIT_REQUESTS=1000
+RATE_LIMIT_PERIOD=3600
+
+# Tier limits
+FREE_TIER_MAX_BYTES=256
+FREE_TIER_MAX_REQUESTS=100
+PRO_TIER_MAX_BYTES=1024
+PRO_TIER_MAX_REQUESTS=1000
+ENTERPRISE_TIER_MAX_BYTES=10240
+ENTERPRISE_TIER_MAX_REQUESTS=10000
+
+# API key configuration
+REQUIRE_API_KEY=true
+API_KEY_HEADER=X-API-Key
+# Comma-separated list of accepted API keys (in-memory allow-list).
+# For large-scale deployments, replace with a database or Redis lookup.
+VALID_API_KEYS=key-aaaa1111bbbb2222,key-cccc3333dddd4444
+
+# Request body size limit (bytes). Default 1 MB.
+MAX_REQUEST_BODY_SIZE_BYTES=1048576
+
+# Stripe billing (optional; leave unset for free-only deployments)
+# STRIPE_SECRET_KEY=sk_live_...
+# STRIPE_WEBHOOK_SECRET=whsec_...
+# STRIPE_PRICE_ID_PRO=price_...
+# STRIPE_PRICE_ID_ENTERPRISE=price_...
+
+# Monitoring
+LOG_LEVEL=INFO
+ENABLE_DETAILED_LOGGING=true
+ENABLE_AUDIT_LOGGING=true
+AUDIT_LOG_RETENTION_DAYS=365
+FIPS_MODE=false
+```
+
+#### Billing
+
+When Stripe variables are set, the billing router (`/api/v2/stripe/webhook`) processes subscription lifecycle events and updates the API key tier in the rate-limits database automatically.  Without Stripe, tiers can be set via the admin endpoint `POST /api/v2/billing/keys/register` or by inserting rows directly into the `rate_limits` SQLite table.
+
+#### Dashboard
+
+The dashboard is built with Next.js 16 and served via Nginx alongside the FastAPI backend.
+
+```bash
+# Build the dashboard (run from quantum-oracle-ui/)
+cd quantum-oracle-ui
+npm install
+npm run build
+
+# Environment variables for dashboard
+NEXT_PUBLIC_API_BASE_URL=https://api.yourdomain.com/api/v2
+API_BASE_URL=https://api.yourdomain.com
+
+# Production server command
+npm run start
+```
+
+**Single Docker Deployment:**
+The `Dockerfile` builds both the FastAPI backend and Next.js frontend, served via Nginx on port 7860 (for Hugging Face Spaces) or configurable ports. The Nginx configuration (`nginx.spaces.conf`) routes:
+- `/api/*` → FastAPI backend
+- `/` → Next.js dashboard
+
+## Deployment Options
+
+### Option 1: Kubernetes Deployment
+
+1. **Prepare your Kubernetes cluster** with sufficient resources
+2. **Update the Kubernetes manifests** in the `k8s/` directory with your specific configurations
+3. **Set up secrets** for sensitive information:
+
+```bash
+kubectl create secret generic postgres-secret \
+  --from-literal=password=your_secure_password \
+  -n qcrypt-rng
+```
+
+4. **Deploy using the provided script**:
+
+```bash
+./deploy.sh
+```
+
+### Option 2: Docker Compose Deployment
+
+For development and testing, you can use Docker Compose to run separate services:
+
+```bash
+docker-compose up -d
+```
+
+### Option 3: Single Docker Image (Recommended for Production)
+
+Build and run the unified Docker image that includes Nginx, FastAPI, and Next.js:
+
+```bash
+# Build the image
+docker build -t qcrypt-rng .
+
+# Run the container
+docker run -d -p 7860:7860 \
+  -e ENVIRONMENT=production \
+  -e SECRET_KEY=your-secure-key \
+  -e DATABASE_URL=postgresql://... \
+  qcrypt-rng
+```
+
+Access the application at `http://localhost:7860`:
+- Dashboard: `http://localhost:7860/`
+- API Docs: `http://localhost:7860/docs`
+
+### Option 4: Manual Deployment
+
+1. **Set up your infrastructure** (database, cache, load balancer)
+2. **Configure environment variables** as shown above
+3. **Deploy the API server** using your preferred method (PM2, systemd, etc.)
+4. **Build and deploy the Next.js dashboard**:
+
+```bash
+# Build the dashboard
+cd quantum-oracle-ui
+npm install
+npm run build
+
+# Start with production environment
+API_BASE_URL=https://api.yourdomain.com npm run start
+```
+
+5. **Configure Nginx** to proxy requests:
+   - `/api/*` → FastAPI backend (port 8000)
+   - `/` → Next.js dashboard (port 3000)
+
+## Security Considerations
+
+### API Security
+- Always use HTTPS in production.
+- **CORS** is restricted to the origins listed in `ALLOWED_ORIGINS`. Never use `*` with credentials in production.
+- **Security headers** are added automatically to every response:
+  - `X-Content-Type-Options: nosniff`
+  - `X-Frame-Options: DENY`
+  - `Referrer-Policy: strict-origin-when-cross-origin`
+  - `Permissions-Policy: geolocation=(), camera=(), microphone=()`
+  - In production (`ENVIRONMENT=production`): `Strict-Transport-Security` and `Content-Security-Policy` are also set.
+- **Request body size limit** is enforced (default 1 MB, configurable via `MAX_REQUEST_BODY_SIZE_BYTES`). Requests exceeding the limit receive HTTP 413.
+- **SECRET_KEY** must be set to a real value (>= 32 characters) in production. The application will refuse to start if the default placeholder is detected when `ENVIRONMENT=production`.
+
+### API Key Management
+- Set `REQUIRE_API_KEY=true` in production.
+- Supply accepted keys via `VALID_API_KEYS` (comma-separated). Keys are validated using constant-time comparison. The raw key is never logged; only a SHA-256 prefix hash appears in audit logs.
+- For large-scale deployments, replace the in-memory allow-list with a database or Redis lookup in `api_key_middleware`.
+- Enable rate limiting to prevent abuse.
+- Regularly rotate secrets and API keys.
+
+### Audit Logging
+- Security events (invalid/missing API keys, rate-limit violations) are written to `logs/security_<date>.log` via the dedicated security logger.
+- Audit logs are retained for 365 days by default (`AUDIT_LOG_RETENTION_DAYS`).
+- Sensitive values (API keys, randomness) are never included in logs.
+
+### Data Protection
+- Encrypt sensitive data in transit and at rest.
+- Implement proper backup strategies.
+- Follow the principle of least privilege.
+- Regular security audits and penetration testing.
+
+### Quantum Backend Security
+- Secure access to quantum computers.
+- Implement proper authentication and authorization.
+- Monitor quantum backend access logs.
+- Regular updates and patches.
+
+## Monitoring and Maintenance
+
+### Key Metrics to Monitor
+- API response times
+- Error rates
+- Quantum generation performance
+- Database performance
+- Cache hit ratios
+- Resource utilization
+
+### Logging
+- Enable detailed logging in production
+- Implement log aggregation and analysis
+- Set up alerts for critical issues
+- Regular log rotation and archival
+
+### Maintenance Tasks
+- Regular security updates
+- Database maintenance and optimization
+- Quantum backend calibration
+- Performance tuning
+
+## Troubleshooting
+
+### Common Issues
+
+#### API Server Not Starting
+- Check environment variables
+- Verify database connectivity
+- Review logs for specific error messages
+
+#### Slow Quantum Generation
+- Check quantum backend configuration
+- Verify sufficient qubit allocation
+- Review performance metrics
+
+#### Dashboard Not Connecting to API
+- Verify API_BASE_URL configuration
+- Check network connectivity between services
+- Review CORS settings
+
+### Getting Help
+- Check the logs in the `logs/` directory
+- Review the API documentation at `/docs`
+- Contact support at [support@qcrypt.example.com](mailto:support@qcrypt.example.com)
+- Open an issue in our [GitHub repository](https://github.com/quantumGlobalGroup/qcrypt-rng)
+
+## Upgrading
+
+To upgrade to a new version:
+
+1. **Backup your data** (database, configuration files)
+2. **Review release notes** for breaking changes
+3. **Test in staging environment** first
+4. **Deploy to production** following your standard procedures
+5. **Monitor closely** after deployment
+
+---
+
+For additional support or questions, please reach out to our team.

docs/PROJECT_OVERVIEW.md

@@ -0,0 +1,245 @@
+# 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*

docs/README.md

@@ -0,0 +1,18 @@
+# Documentation index
+
+| Document | Description |
+|----------|-------------|
+| [PROJECT_OVERVIEW.md](PROJECT_OVERVIEW.md) | Architecture, capabilities, tech stack |
+| [PRODUCTION.md](PRODUCTION.md) | Deployment, env vars, security, operations |
+| [UPGRADE_ROADMAP.md](UPGRADE_ROADMAP.md) | Product upgrade master map |
+| [BUILD_MONETIZATION.md](BUILD_MONETIZATION.md) | Monetization build plan |
+| [BUILD_PLATFORM_AND_QUALITY.md](BUILD_PLATFORM_AND_QUALITY.md) | Tests, monitoring, testnets, security |
+| [TECHNICAL_PAPER.md](TECHNICAL_PAPER.md) | Algorithms and architecture detail |
+| [MONITORING_GUIDE.md](MONITORING_GUIDE.md) | Metrics and observability |
+| [NEXT_STEPS.md](NEXT_STEPS.md) / [NEXT_STEPS_PHASE2.md](NEXT_STEPS_PHASE2.md) | Historical roadmaps |
+| [next-phase/](next-phase/) | Phase 2 deliverables: testnet deployment, security audit |
+| [guides/](guides/) | Command reference, directory guide, dashboard notes |
+| [business/](business/) | Whitepapers, marketing one-pager, business plans |
+| [archive/](archive/) | Older implementation summaries and README variants |
+
+The repo root keeps a short pointer: [../PRODUCTION.md](../PRODUCTION.md) → this folder’s `PRODUCTION.md`.

docs/TECHNICAL_PAPER.md

@@ -0,0 +1,278 @@
+# QCrypt RNG: Technical Paper
+
+**Quantum-Enhanced Random Number Generation, Post-Quantum Cryptography, and Blockchain Security Platform**
+
+---
+
+## Abstract
+
+QCrypt RNG is a software platform that provides cryptographically secure randomness and quantum-resistant security primitives through a unified REST API and web dashboard. The system combines (1) quantum-backed random number generation via simulation and a hardware abstraction layer for real devices, (2) a verifiable random function (VRF) using a quantum seed and Keccak-256 commit–reveal compatible with Ethereum and other EVM chains, (3) NIST-standardized post-quantum cryptography (DILITHIUM, KYBER), (4) data protection (symmetric encryption, signing, hashing) using quantum entropy, and (5) threat intelligence and blockchain security tooling. This document describes the architecture, algorithms, and security properties of the platform.
+
+**Keywords:** quantum random number generation, QRNG, post-quantum cryptography, PQC, verifiable random function, VRF, commit-reveal, blockchain oracle, Keccak-256, DILITHIUM, KYBER.
+
+---
+
+## 1. Introduction
+
+### 1.1 Motivation
+
+Cryptographic systems depend on high-quality randomness for keys, nonces, and seeds. Classical pseudorandom number generators (PRNGs) are deterministic and, if seeded weakly, can be predictable. Hardware random number generators (HRNGs) improve on this but may introduce bias or correlation. Quantum random number generators (QRNGs) exploit the inherent indeterminacy of quantum measurement to provide information-theoretically strong entropy. Deploying such entropy in practice requires a coherent stack: generation, post-processing, commitment schemes for oracles, and integration with post-quantum and classical cryptography.
+
+At the same time, the threat of large-scale quantum computers motivates migration to post-quantum cryptography (PQC). NIST has standardized signature schemes (e.g., DILITHIUM) and key encapsulation mechanisms (e.g., KYBER). Applications that combine quantum entropy with PQC can strengthen both randomness and long-term confidentiality and authenticity.
+
+Blockchain applications often need verifiable, unpredictable randomness (e.g., for consensus, lotteries, or NFT mints). A quantum-backed VRF with a commit–reveal flow provides verifiability and auditability while tying the entropy source to quantum measurement.
+
+### 1.2 Scope
+
+This paper covers the QCrypt RNG platform as implemented: quantum RNG (simulation and hardware abstraction), quantum VRF and randomness oracle, post-quantum cryptography, data protection, threat intelligence, and deployment model. It does not certify compliance with any particular standard or regulation.
+
+---
+
+## 2. System Architecture
+
+### 2.1 Overview
+
+The platform is split into:
+
+- **Backend:** FastAPI application exposing REST endpoints under `/api/v2`, backed by Python modules for quantum RNG, commitments, PQC, and protection.
+- **Frontend:** Next.js dashboard for interactive use and in-app documentation.
+- **Deployment:** Single Docker image (Nginx reverse proxy, FastAPI, Next.js) for cloud or Hugging Face Spaces; optional Docker Compose and Kubernetes for self-hosted deployment.
+
+Nginx listens on a single port (e.g., 7860), routing `/api/*` and `/health` to FastAPI and all other paths to the Next.js server.
+
+### 2.2 Component Map
+
+| Component        | Responsibility |
+|-----------------|----------------|
+| `app/quantum/qrng.py` | Core QRNG: simulation, hardware abstraction, entropy pool, post-processing, entropy analysis. |
+| `app/quantum/commitment.py` | Keccak-256 commitments (Ethereum-compatible); VRF output computation. |
+| `app/quantum/pqc.py` | Post-quantum crypto via liboqs (DILITHIUM, KYBER, etc.); fallback when liboqs unavailable. |
+| `app/quantum/hardware_interface.py` | Abstract interface for photonic, superconducting, and simulated devices. |
+| `app/api/v2/endpoints/vrf.py` | VRF seed, prove, reveal, verify. |
+| `app/api/v2/endpoints/oracle.py` | Oracle randomness request (single and batch), status, benchmark. |
+| `app/api/v2/endpoints/protect.py` | Encrypt/decrypt, sign/verify, hash, salt. |
+| `app/api/v2/endpoints/pqc_endpoints.py` | PQC key generation, sign, verify, threat assessment. |
+
+Configuration (backend, qubit limits, entropy pool size, rate limits, etc.) is centralized in `app/config.py` and driven by environment variables.
+
+---
+
+## 3. Quantum Random Number Generation
+
+### 3.1 Backends
+
+The RNG supports multiple backends:
+
+- **qrisp_simulator:** When the Qrisp library is available, qubits are modeled with a `QuantumFloat`, Hadamard gates put them in uniform superposition, and measurement yields a random integer. This simulates ideal quantum measurement.
+- **Hardware:** When configured for `hardware_photonic` or `hardware_superconducting`, the hardware abstraction layer is used. Real devices would be connected via the same interface; the current codebase provides simulated hardware implementations for development and testing.
+- **Simulation fallback:** If neither Qrisp nor hardware is used, a classical simulation produces one random bit per “qubit” via `secrets.randbits(1)`, then combines them into an integer. This is not quantum but provides strong randomness for local and demo use.
+
+### 3.2 Generation Pipeline
+
+For each request the system:
+
+1. Validates byte count (capped by tier) and qubit count (e.g., 1–16).
+2. Produces random bytes by repeatedly:
+   - Obtaining a quantum (or simulated) measurement of `num_qubits` bits from the hardware manager.
+   - Post-processing the value with SHA3-256, mixing in system entropy and a timestamp, to obtain 32 bytes per iteration.
+   - Appending to the output until the requested length is reached.
+3. Updates an internal entropy pool with the raw measurements for later analysis.
+4. Formats the result as hex, base64, array, or raw bytes.
+
+Post-processing ensures uniform distribution and reduces bias or correlation that might come from a real device. The use of SHA3-256 and extra entropy aligns with common practice for cryptographic RNG output.
+
+### 3.3 Entropy Pool and Analysis
+
+Measurements are stored in a ring buffer (entropy pool) of configurable size (e.g., 1000). The pool is used for:
+
+- **Entropy analysis:** Shannon entropy, min-entropy, chi-square test, autocorrelation, and bit balance. Results are exposed via `/quantum/entropy` and used in health checks.
+- **Health status:** The pool is marked as having insufficient data until a minimum number of samples (e.g., 100) is available; thereafter a status such as “excellent” or “good” is derived from the statistical tests.
+
+Reseeding clears the pool and refills it with fresh generations to support operational recovery and testing.
+
+### 3.4 Derived Primitives
+
+The same core `generate_bytes` is used to implement:
+
+- **Keys:** AES/RSA/ECDSA key sizes; bytes generated and returned in the requested format (e.g., hex, PEM for RSA/ECDSA).
+- **UUIDs:** 16 quantum random bytes formatted as UUID v4 (version and variant bits set correctly).
+- **Passwords:** Configurable length and character set; strength metrics are derived from entropy (e.g., bits of entropy).
+- **Session tokens:** Random bytes in base64 or hex, optionally URL-safe.
+- **Batch generation:** Multiple byte-generation requests in parallel for throughput.
+
+All of these are exposed via the Generation API and the dashboard.
+
+---
+
+## 4. Quantum VRF and Commit–Reveal
+
+### 4.1 Design
+
+The quantum VRF provides:
+
+- A **one-time quantum seed** (32 bytes) generated by the QRNG.
+- A **commitment** to that seed using Keccak-256, in a form compatible with Solidity `abi.encodePacked(uint256)` so that on-chain verification matches.
+- A **deterministic output** for a given input (alpha): `output = Keccak256(seed || alpha)`.
+- **Verification** after reveal: anyone with the seed can check that the commitment and the output match the seed and alpha.
+
+The seed is stored server-side keyed by a `request_id` until the client calls reveal. After reveal, the seed is still stored so that historical proofs can be verified via the verify endpoint.
+
+### 4.2 Commitment Format
+
+In `app/quantum/commitment.py`:
+
+- **Commitment:** The 32-byte seed is interpreted as a big-endian unsigned integer, re-encoded as 32 bytes big-endian, then hashed with Keccak-256. This matches the Solidity expression `keccak256(abi.encodePacked(uint256(randomness)))`.
+- **VRF output:** `Keccak256(seed_bytes || alpha_utf8_bytes)`. Alpha is an arbitrary string (e.g., round ID, nonce).
+
+Both commitment and VRF output are exposed as `0x`-prefixed hex strings for use in contracts and tooling.
+
+### 4.3 API Flow
+
+1. **POST /oracle/vrf/seed** — Server generates 32-byte quantum seed, computes commitment, stores seed under a new `request_id`, returns `request_id` and `commitment`.
+2. **POST /oracle/vrf/prove** — Client sends `request_id` and `alpha`; server returns `output = Keccak256(seed || alpha)` and the stored `commitment`.
+3. **POST /oracle/vrf/reveal** — Client sends `request_id`; server returns the seed (hex) and marks it revealed.
+4. **POST /oracle/vrf/verify** — Client sends `commitment`, `alpha`, `output`, and `seed`; server checks that the commitment and output match the seed and alpha and returns a validity flag.
+
+This gives a full commit–prove–reveal–verify cycle suitable for oracles and smart contracts that consume the VRF output and optionally verify the commitment on-chain.
+
+---
+
+## 5. Quantum Randomness Oracle
+
+### 5.1 Single Request
+
+The oracle endpoint **POST /oracle/request** simulates a blockchain-oriented randomness request:
+
+- The server generates quantum randomness (configurable bytes and qubits).
+- It computes the same Ethereum-compatible Keccak-256 commitment as in the VRF.
+- It returns a `request_id`, commitment (if requested), estimated completion blocks, fee, and status. In a production deployment this would be wired to an actual chain (e.g., submit a transaction, fulfill via callback).
+
+Optional parameters include `target_chain` and `scheduled_delivery_block` for multi-chain and timing semantics.
+
+### 5.2 Batch Requests
+
+**POST /oracle/requests/batch** accepts a count, byte length, qubit count, and optional chain/block. The server generates that many quantum samples and returns a list of request identifiers and commitments (and optionally full randomness). This supports use cases such as fair mints or lotteries that need multiple independent random values.
+
+### 5.3 Status and Benchmark
+
+- **GET /oracle/status/:id** — Returns fulfillment status and, when available, the revealed randomness for a given request ID.
+- **GET /oracle/benchmark** — Returns performance metrics (e.g., latency, throughput) for the oracle path.
+
+---
+
+## 6. Post-Quantum Cryptography
+
+### 6.1 Algorithms
+
+The PQC module uses liboqs when available. Supported algorithms include:
+
+- **Signatures:** DILITHIUM2/3/5, FALCON512/1024, SPHINCS+-SHA2-128f.
+- **Key encapsulation:** KYBER512/768/1024, NTRU-HPS variants, SABER variants.
+
+Each algorithm has an associated NIST security level and key/signature size. The implementation exposes key generation, signing, and verification (and KEM operations where applicable).
+
+### 6.2 Fallback
+
+If liboqs is not installed or fails to load, the code falls back to a simulated implementation (e.g., random “keys” and hash-based “signatures”) so that the API and dashboard remain usable. This fallback is not cryptographically secure and is intended only for development and demos.
+
+### 6.3 Threat Assessment
+
+The API can perform a threat assessment for a given algorithm (or set of algorithms), reporting approximate “qubits to break” and migration guidance. This supports planning for post-quantum migration.
+
+---
+
+## 7. Data Protection
+
+### 7.1 Encryption
+
+Data protection uses quantum-generated or user-supplied keys:
+
+- **Symmetric encryption:** AES-256-GCM, AES-128-GCM, AES-256-CBC. For GCM, the ciphertext is (IV, ciphertext, tag). For CBC, PKCS7 padding is applied and an HMAC-SHA256 tag over IV and ciphertext is stored for integrity.
+- **Key and IV:** Either generated by the QRNG or supplied by the client (e.g., bring-your-own-key).
+- **File encryption:** Same algorithms applied to uploaded files (e.g., up to 10 MB), with original filename preserved in metadata where applicable.
+
+Decryption requires the same key, IV, and tag (and algorithm) and validates integrity where supported.
+
+### 7.2 Signing and Hashing
+
+- **Signing:** HMAC-SHA256 or HMAC-SHA512 with quantum-generated or user-supplied keys. A verify endpoint checks signatures without requiring the full protection flow.
+- **Hashing:** SHA3-256, SHA3-512, PBKDF2-SHA256, BLAKE2b-256. Salts are generated by the QRNG when not supplied. Iterations for PBKDF2 are configurable (e.g., 10k–1M). Supports both “data hash” and “password” modes for key derivation and password hashing.
+
+These primitives are exposed under `/protect/*` and are intended for integration with applications that need confidentiality, integrity, and quantum-salted hashing.
+
+---
+
+## 8. Blockchain Security and Threat Intelligence
+
+### 8.1 Blockchain Tooling
+
+The platform includes demo/simulation endpoints for:
+
+- **Wallet creation:** Classical (ECDSA) and quantum-safe (e.g., DILITHIUM) wallet profiles for comparison.
+- **Transaction signing:** Signing with ECDSA or PQC for demonstration.
+- **Attack simulation:** Simulating Shor’s algorithm against RSA/ECDSA to illustrate quantum threat (e.g., qubit counts to break).
+- **Blockchain comparison:** Side-by-side comparison of a “vulnerable” chain (classical) and a “quantum-safe” chain (PQC).
+- **Mining demo:** A minimal proof-of-work style mining step for education.
+
+These are in-memory or simulated and are not connected to live networks.
+
+### 8.2 Threat Intelligence
+
+Threat intelligence features include:
+
+- **Algorithm scanning:** Assessing algorithms for quantum vulnerability and reporting qubits-to-break and recommendations.
+- **Oracle benchmark:** Measuring latency and throughput of the oracle path.
+- **Entropy quality:** Exposing entropy analysis (Shannon, min-entropy, chi-square, etc.) for operational monitoring.
+
+Results are available via API and the dashboard (e.g., collapsible sections, download/copy).
+
+---
+
+## 9. Deployment and API Summary
+
+### 9.1 Deployment
+
+- **Local:** Run FastAPI (e.g., `python run_api.py` or `uvicorn app.main:app`) and the Next.js dev server; dashboard and API run on separate ports.
+- **Docker:** The root `Dockerfile` builds a single image with Nginx, FastAPI, and the Next.js standalone app. Nginx listens on port 7860 (configurable), suitable for Hugging Face Spaces or any host that expects a single port.
+- **Kubernetes / Compose:** Optional manifests and Compose files for multi-replica or multi-service deployment.
+
+Configuration is environment-based (e.g., `REQUIRE_API_KEY`, `QUANTUM_BACKEND`, `ENTROPY_POOL_SIZE`).
+
+### 9.2 API Base and Documentation
+
+- All v2 endpoints are under `/api/v2` (e.g., `/api/v2/generate/bytes`, `/api/v2/oracle/vrf/seed`).
+- OpenAPI schema at `/openapi.json`; interactive docs at `/docs` (or `/swagger` when behind the bundled Nginx).
+- Health: `GET /health` includes entropy pool and backend checks.
+
+---
+
+## 10. Security Considerations
+
+- **Entropy source:** In production, randomness should come from a validated QRNG or a mix of quantum and trusted HRNG; simulation and classical fallback are for development and demonstration only.
+- **VRF seed storage:** VRF seeds are held in process memory. For high-assurance deployments, consider hardened storage, access control, and audit logging.
+- **Commitment binding:** The commit–reveal scheme binds the server to the revealed seed; verification is possible only after reveal. Use of a TEE or multi-party computation could strengthen the model.
+- **PQC:** Algorithm selection and key lifecycle should follow current NIST and organizational guidance; the platform provides the primitives, not a certified implementation.
+- **Keys and secrets:** API keys, encryption keys, and tokens must be managed and rotated according to policy; the platform does not implement a full HSM or key-management system.
+- **Rate limiting and auth:** Optional rate limiting and API key checks can be enabled to reduce abuse and enforce tier limits.
+
+---
+
+## 11. Conclusion and Future Work
+
+QCrypt RNG provides an integrated platform for quantum-backed randomness, a Keccak-256-based VRF and oracle, post-quantum cryptography, and data protection, with a web dashboard and REST API suitable for demos, development, and deployment to cloud or Spaces.
+
+Possible future work includes: integration with real quantum hardware and certification of entropy quality; on-chain integration (e.g., verified fulfillment on specific L1/L2); formal verification of the VRF and commitment logic; and expanded PQC and threat-assessment coverage.
+
+---
+
+## References
+
+1. NIST FIPS 203, 204, 205 (Module-Lattice-Based Key Encapsulation and Signatures).
+2. Ethereum Yellow Paper / EVM semantics for `abi.encodePacked` and Keccak-256.
+3. NIST SP 800-90 series (Recommendations for Random Number Generation).
+4. QRisp: https://qrisp.eu/ (quantum simulation framework).
+5. Open Quantum Safe (liboqs): https://openquantumsafe.org/.
+
+---
+
+*Document version: 1.0. Last updated to match the QCrypt RNG codebase as of the technical review date.*

docs/UPGRADE_ROADMAP.md

@@ -0,0 +1,89 @@
+# QCrypt RNG — Upgrade Roadmap (Master Map)
+
+This document is the **single entry point** for planned upgrades: product (API + oracle), monetization, and production quality. Detailed build steps live in linked files under `docs/`.
+
+---
+
+## Goals
+
+| Track | Outcome |
+|--------|---------|
+| **Product** | API + oracle as a coherent offering with clear tiers and limits |
+| **Monetization** | API key → tier mapping, billing integration, and usage-based enforcement |
+| **Platform** | Tests, monitoring, security posture, and contract/testnet validation |
+
+---
+
+## Dependency Map
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Foundation (Phase A)                                            │
+│  • API key → real tier lookup (replace hash pseudo-tier)        │
+│  • Enforce limits per tier in rate_limiting + middleware        │
+└───────────────────────────────┬───────────────────────────────────┘
+                                │
+        ┌───────────────────────┼───────────────────────┐
+        ▼                       ▼                       ▼
+┌───────────────┐  ┌────────────────────────┐  ┌──────────────────┐
+│ Phase B       │  │ Phase C                  │  │ Phase D         │
+│ Monetization  │  │ Platform & quality       │  │ Oracle product  │
+│ (billing,     │  │ (tests, monitoring,      │  │ (metering,      │
+│  Stripe, UI)  │  │  docs, audit)            │  │  testnet)       │
+└───────────────┘  └────────────────────────┘  └──────────────────┘
+```
+
+**Rule:** Phases B–D can be parallelized after Phase A; B (monetization) depends most on A.
+
+---
+
+## Document Index
+
+| Document | Purpose |
+|----------|---------|
+| **[UPGRADE_ROADMAP.md](UPGRADE_ROADMAP.md)** (this file) | Overview, priorities, dependencies |
+| **[BUILD_MONETIZATION.md](BUILD_MONETIZATION.md)** | API + oracle monetization (tiers, billing, usage) |
+| **[BUILD_PLATFORM_AND_QUALITY.md](BUILD_PLATFORM_AND_QUALITY.md)** | Testing, monitoring, docs, security, testnet |
+| [NEXT_STEPS.md](NEXT_STEPS.md) | Original Phase 1 tasks (historical) |
+| [NEXT_STEPS_PHASE2.md](NEXT_STEPS_PHASE2.md) | Phase 2 backlog (partially superseded by this roadmap) |
+| [PRODUCTION.md](PRODUCTION.md) | Deployment and operations |
+| [PROJECT_OVERVIEW.md](PROJECT_OVERVIEW.md) | Architecture and capabilities |
+
+---
+
+## Priority Order (Recommended)
+
+| Order | Focus | Deliverable |
+|-------|--------|-------------|
+| **1** | **Phase A — Foundation** | Tier lookup from DB/config; `rate_limits.tier` or `api_keys` table; remove MD5 pseudo-tier in `app/utils/rate_limiting.py` |
+| **2** | **Stripe / billing** (subset of B) | Checkout → webhook → set tier; optional metered usage from `usage_logs` |
+| **3** | **Testing** | Critical path: PQC KEM, oracle fulfillment (mocked), middleware |
+| **4** | **Monitoring** | Prometheus metrics for oracle fulfillment, PQC, entropy (see [MONITORING_GUIDE.md](MONITORING_GUIDE.md)) |
+| **5** | **Oracle product** | Per-endpoint metering; testnet contract deploy + documented addresses |
+| **6** | **Security audit** | External or internal checklist before high-trust production |
+
+---
+
+## Key Code Touchpoints
+
+| Area | Primary files |
+|------|----------------|
+| Tier + usage | `app/utils/rate_limiting.py`, `app/config.py`, `app/utils/middleware.py` |
+| Billing (future) | New `app/billing/` or `app/subscriptions/` + Stripe webhooks |
+| Oracle | `app/api/v2/endpoints/oracle.py`, `app/blockchain/oracle_service.py` |
+| Dashboard | `quantum-oracle-ui/` — pricing, usage, upgrade CTAs |
+
+---
+
+## Definition of Done (Upgrade v1)
+
+- [ ] Every API key resolves to a **real** tier (free / pro / enterprise), not hash-based.
+- [ ] **Usage** is attributable per key for billing (`usage_logs` or equivalent).
+- [ ] **Monetization path** exists: Stripe or documented manual tier assignment (minimum for launch).
+- [ ] **Oracle** endpoints counted or limited per tier (or explicit “oracle add-on” plan).
+- [ ] **CI** runs tests; critical paths covered.
+- [ ] **PRODUCTION.md** and README aligned with current deployment and env vars.
+
+---
+
+*Last updated: 2026-03-23*