clock_rand/
lib.rs

1//! clock-rand: Next-generation random number generation
2//!
3//! A production-ready Rust crate providing fast deterministic PRNGs,
4//! cryptographically secure RNGs, and blockchain-aware RNGs with automatic
5//! fork detection. Built for modern applications requiring both speed and security.
6//!
7//! By Olyntar Labs, an Olyntar company.
8
9#![cfg_attr(not(feature = "std"), no_std)]
10#![warn(missing_docs)]
11
12#[cfg(not(feature = "std"))]
13extern crate alloc;
14
15pub mod error;
16pub mod seed;
17pub mod traits;
18
19#[cfg(feature = "crypto_rng")]
20pub mod crypto;
21#[cfg(feature = "custom_rng")]
22pub mod custom;
23#[cfg(feature = "distributions")]
24pub mod distributions;
25#[cfg(feature = "fast_rng")]
26pub mod fast;
27pub mod utils;
28
29#[cfg(feature = "serde")]
30pub mod serialization;
31#[cfg(feature = "thread_safe")]
32pub mod thread_safe;
33#[cfg(feature = "wasm")]
34pub mod wasm;
35
36// Re-export main types
37pub use error::{EntropyError, Error, ForkError, Result, SeedError};
38pub use seed::Seed;
39pub use traits::{CryptoRng, DeterministicRng, Rng, RngCore, RngExt, SeedableRng};
40
41// Re-export utility functions
42pub use utils::{
43    choose, fill_bytes, gen_f32, gen_f64, gen_range_f32, gen_range_f64, gen_range_u32,
44    gen_range_u64, shuffle, weighted_choose,
45};
46
47#[cfg(feature = "std")]
48pub use utils::sample;
49
50#[cfg(feature = "fast_rng")]
51pub use fast::{Pcg64, SplitMix64, Xoshiro256Plus};
52
53#[cfg(feature = "crypto_rng")]
54pub use crypto::{AesCtrRng, Blake3Drbg, ChaCha20Rng};
55
56#[cfg(feature = "custom_rng")]
57pub use custom::{ChainSeedX, EntroCrypt, HashMix256};
58
59#[cfg(feature = "distributions")]
60pub use distributions::{Distribution, Uniform};
61
62// Convenience type aliases
63
64/// Fast deterministic RNG type alias (Xoshiro256+)
65pub type FastRng = Xoshiro256Plus;
66
67/// Cryptographically secure RNG type alias
68#[cfg(feature = "crypto_rng")]
69pub type CryptoRngType = ChaCha20Rng;
70
71/// Convenience constructor for fast RNG from blockchain state
72#[cfg(feature = "fast_rng")]
73pub fn fast_rng_from_blockchain(block_hash: &[u8; 32], timestamp: u64) -> Result<FastRng> {
74    let seed = Seed::from_blockchain_state(block_hash, timestamp, None)?;
75    Xoshiro256Plus::from_seed_obj(&seed)
76}
77
78/// Convenience constructor for crypto RNG from blockchain seed
79#[cfg(feature = "crypto_rng")]
80pub fn crypto_rng_from_seed(seed: &Seed) -> Result<ChaCha20Rng> {
81    ChaCha20Rng::new(seed)
82}
83
84/// Convenience constructor for crypto RNG from OS entropy (requires std)
85#[cfg(all(feature = "crypto_rng", feature = "std"))]
86pub fn crypto_rng_from_os() -> Result<ChaCha20Rng> {
87    ChaCha20Rng::from_os_entropy()
88}
89
90#[cfg(test)]
91mod tests {
92    use super::*;
93
94    #[test]
95    fn test_fast_rng_basic() {
96        #[cfg(feature = "fast_rng")]
97        {
98            let mut rng = Xoshiro256Plus::new(42);
99            let _ = rng.next_u64();
100            assert!(rng.is_deterministic());
101        }
102    }
103
104    #[test]
105    fn test_crypto_rng_basic() {
106        #[cfg(feature = "crypto_rng")]
107        {
108            let seed =
109                Seed::from_bytes(vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16])
110                    .unwrap();
111            let mut rng = ChaCha20Rng::new(&seed).unwrap();
112            let _ = Rng::next_u64(&mut rng);
113            assert!(rng.is_deterministic());
114        }
115    }
116}
clock_rand/lib.rs

clock_rand/
lib.rs
