Tsotchke Quantum Random Number Generator (QRNG)

Tsotchke Quantum RNG

A high-quality quantum random number generator library for Rust applications requiring cryptographically secure randomness. This library provides quantum-enhanced random number generation with specialized modules for cryptography, finance, games, and statistical analysis based on Tsotchke QRNG.

🚀 Quick Start

Add this to your Cargo.toml:

[dependencies]
rust_qrng = "0.1"

Basic Usage

use rust_qrng::quantum_rng;

fn main() {
    // Create a new quantum RNG instance
    let mut rng = quantum_rng::new();
    
    // Generate random numbers
    let random_u64 = rng.generate_u64();
    let random_f64 = rng.generate_f64();
    
    println!("Random u64: {}", random_u64);
    println!("Random f64: {}", random_f64);
}

🔧 Features

🔒 Cryptographic Security: High-entropy random number generation suitable for cryptographic applications
💰 Financial Modeling: Monte Carlo simulations and options pricing with quantum randomness
🎲 Gaming: Quantum dice and fair random number generation for games
📊 Statistical Analysis: Built-in statistical tests and validation functions
⚡ Performance: Optimized for both quality and speed

📚 Usage Examples

Cryptography

use rust_qrng::crypto::{key_exchange, key_derivation};

// Generate cryptographic keys
let key_pair = key_exchange::generate_keypair();
let derived_key = key_derivation::derive_key(&key_pair.private, b"salt");

Finance

use rust_qrng::finance::monte_carlo;

// Run Monte Carlo simulation
let simulation = monte_carlo::SimulationBuilder::new()
    .iterations(10000)
    .initial_value(100.0)
    .volatility(0.2)
    .build();

let results = simulation.run();
println!("Expected value: {}", results.mean());

Games

use rust_qrng::games::quantum_dice;

// Roll quantum dice
let dice = quantum_dice::QuantumDice::new(6); // 6-sided die
let roll = dice.roll();
println!("Rolled: {}", roll);

Statistical Testing

use rust_qrng::statistical::tests;

// Test randomness quality
let mut rng = rust_qrng::quantum_rng::new();
let samples: Vec<f64> = (0..1000).map(|_| rng.generate_f64()).collect();

let chi_square_result = tests::chi_square_test(&samples);
println!("Chi-square test p-value: {}", chi_square_result.p_value);

🎯 Use Cases

For Cryptographic Applications

Key Generation: Generate secure cryptographic keys for encryption
Salt Generation: Create unpredictable salts for password hashing
Nonce Generation: Generate unique numbers for cryptographic protocols
Session Tokens: Create secure session identifiers

For Financial Modeling

Monte Carlo Simulations: Risk assessment and portfolio optimization
Options Pricing: Calculate fair values for financial derivatives
Market Risk Models: Stress testing and scenario analysis
Portfolio Backtesting: Historical performance simulation

For Gaming

Fair Dice Rolling: Provably fair random number generation
Card Shuffling: Secure deck randomization
Lottery Systems: Transparent and verifiable random selection
Procedural Generation: Random world/level generation

For Scientific Computing

Statistical Sampling: Generate samples from various distributions
Hypothesis Testing: Statistical significance testing
Randomized Algorithms: Algorithm performance optimization
Simulation Studies: Scientific modeling and analysis

🔍 API Reference

Core Module

use rust_qrng::quantum_rng;

// Create a new quantum RNG instance
let mut rng = quantum_rng::new();

// Generate different types of random numbers
let u64_value = rng.generate_u64();           // 64-bit unsigned integer
let f64_value = rng.generate_f64();           // 64-bit floating point (0.0 to 1.0)
let bool_value = rng.generate_bool();         // Boolean value
let range_value = rng.generate_range(1, 100); // Integer in range [1, 100)

Cryptography Module

use rust_qrng::crypto::{key_exchange, key_derivation};

// Generate RSA key pair
let keypair = key_exchange::generate_keypair();

// Derive key from master key
let derived_key = key_derivation::derive_key(
    &keypair.private,
    b"application_salt",
);

Finance Module

use rust_qrng::finance::{monte_carlo, options_pricing};

// Monte Carlo simulation
let simulation = monte_carlo::SimulationBuilder::new()
    .iterations(100_000)
    .initial_value(100.0)
    .volatility(0.25)
    .drift(0.05)
    .time_horizon(1.0)
    .build();

let results = simulation.run();
println!("Mean: {:.2}", results.mean());
println!("Std Dev: {:.2}", results.std_dev());
println!("VaR (95%): {:.2}", results.var_95());

// Options pricing
let option_price = options_pricing::black_scholes(
    100.0,  // Spot price
    110.0,  // Strike price
    0.25,   // Time to expiration (years)
    0.05,   // Risk-free rate
    0.2,    // Volatility
);

Games Module

use rust_qrng::games::quantum_dice;

// Create quantum dice
let d6 = quantum_dice::QuantumDice::new(6);
let d20 = quantum_dice::QuantumDice::new(20);

// Roll dice
let roll = d6.roll();
println!("D6 roll: {}", roll);

// Multiple rolls
let rolls = d20.roll_multiple(5);
println!("D20 rolls: {:?}", rolls);

Statistical Module

use rust_qrng::statistical::tests;

// Generate test data
let mut rng = rust_qrng::quantum_rng::new();
let samples: Vec<f64> = (0..10000)
    .map(|_| rng.generate_f64())
    .collect();

// Perform statistical tests
let chi_square = tests::chi_square_test(&samples);
let kolmogorov_smirnov = tests::ks_test(&samples);
let runs_test = tests::runs_test(&samples);

println!("Chi-square p-value: {:.4}", chi_square.p_value);
println!("K-S p-value: {:.4}", kolmogorov_smirnov.p_value);
println!("Runs test p-value: {:.4}", runs_test.p_value);

🛡️ Security Considerations

Cryptographic Quality: The quantum RNG provides cryptographically secure random numbers suitable for security-sensitive applications
Entropy Source: Uses multiple entropy sources to ensure high-quality randomness
Regular Testing: Built-in statistical tests verify the quality of generated random numbers
Side-Channel Resistance: Designed to resist timing and other side-channel attacks

📊 Performance

The library is optimized for both quality and performance:

Generation Speed: ~100M random numbers per second on modern hardware
Memory Efficiency: Minimal memory footprint with efficient buffering
Thread Safety: Safe for concurrent use across multiple threads
Zero Allocation: Core operations avoid heap allocations

🧪 Testing

Run the test suite to verify functionality:

# Run all tests
cargo test

# Run specific test module
cargo test statistical

# Run with output
cargo test -- --nocapture

Run benchmarks to measure performance:

cargo bench

📖 Examples

Complete examples are available in the examples/ directory:

# Basic usage
cargo run --example quantum_rng_demo

# Cryptographic key generation
cargo run --example key_exchange_demo

# Monte Carlo simulation
cargo run --example monte_carlo_demo

# Quantum dice game
cargo run --example quantum_dice_demo

# Quantum blockchain
cargo run --example quantum_chain_demo

🤝 Contributing

Contributions are welcome! Please feel free to submit a pull request or open an issue for any suggestions or improvements.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

rust_qrng 0.1.2