uhash_core/lib.rs
1//! # UniversalHash Core Algorithm
2//!
3//! A democratic proof-of-work algorithm designed for fair mining where
4//! smartphones can meaningfully compete with servers.
5//!
6//! **v0.2.0** - Full spec compliance with UniversalHash v4 specification.
7//!
8//! ## Features
9//!
10//! - **Spec-Compliant**: Implements UniversalHash v4 specification exactly
11//! - **Democratic Mining**: Phone-to-desktop ratio of 1:3-5
12//! - **ASIC Resistance**: Multi-primitive design (AES + SHA-256 + BLAKE3)
13//! - **Memory-Hard**: 2MB scratchpad prevents GPU parallelism
14//!
15//! ## Algorithm Parameters (v4)
16//!
17//! - 4 parallel computation chains
18//! - 512KB scratchpad per chain (2MB total)
19//! - 12,288 rounds per chain
20//! - Triple primitive rotation: AES, SHA-256, BLAKE3
21//!
22//! ## Input Format
23//!
24//! The algorithm extracts the nonce from the **last 8 bytes** of input:
25//!
26//! ```text
27//! input = header || nonce
28//! ^^^^^^ ^^^^^
29//! any len 8 bytes (little-endian u64)
30//! ```
31//!
32//! Typical mining format: `epoch_seed (32B) || miner_address (20B) || timestamp (8B) || nonce (8B)`
33//!
34//! ## Example
35//!
36//! ```rust
37//! use uhash_core::{UniversalHash, hash, meets_difficulty};
38//!
39//! // Single-shot hashing
40//! let result = hash(b"input data");
41//!
42//! // Check difficulty (leading zero bits)
43//! if meets_difficulty(&result, 16) {
44//! println!("Found hash with 16+ leading zero bits!");
45//! }
46//!
47//! // Reusable hasher (avoids re-allocation)
48//! let mut hasher = UniversalHash::new();
49//! let hash1 = hasher.hash(b"first");
50//! let hash2 = hasher.hash(b"second");
51//! ```
52//!
53//! ## no_std Support
54//!
55//! This crate supports `no_std` environments with the `alloc` crate:
56//!
57//! ```toml
58//! [dependencies]
59//! uhash-core = { version = "0.2", default-features = false }
60//! ```
61
62#![cfg_attr(not(feature = "std"), no_std)]
63
64#[cfg(not(feature = "std"))]
65extern crate alloc;
66
67#[cfg(not(feature = "std"))]
68use alloc::vec;
69#[cfg(not(feature = "std"))]
70use alloc::vec::Vec;
71
72mod params;
73mod primitives;
74mod uhash;
75
76#[cfg(feature = "std")]
77mod ffi;
78
79pub use params::*;
80pub use uhash::{hash, meets_difficulty, UniversalHash};
81
82#[cfg(test)]
83mod tests;