# ClockHash-256
[](https://crates.io/crates/clock-hash)
[](https://docs.rs/clock-hash)
[](https://github.com/Olyntar-Labs/clock-hash/blob/main/LICENSE)
[](https://github.com/Olyntar-Labs/clock-hash/actions)
[](https://github.com/Olyntar-Labs/clock-hash)
A high-performance, cryptographic hash function designed specifically for blockchain consensus operations in ClockinChain. ClockHash-256 provides 256-bit security with exceptional performance and memory safety guarantees.
## Table of Contents
- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [API Documentation](#api-documentation)
- [Performance](#performance)
- [Security](#security)
- [Algorithm Overview](#algorithm-overview)
- [Testing](#testing)
- [Contributing](#contributing)
- [License](#license)
## Features
- 🚀 **High Performance**: ≥1.5 GB/s single-threaded on modern x86_64 CPUs
- 🔒 **Cryptographic Security**: 256-bit preimage resistance, 128-bit collision resistance
- 🛡️ **Memory Safe**: Zero unsafe code, guaranteed by Rust's ownership system
- 🔄 **Domain Separation**: Prevents cross-domain collision attacks
- 📦 **no_std Compatible**: Works in embedded and constrained environments
- ⚡ **SIMD Optimized**: Hardware acceleration on x86_64, ARM, and other architectures
- 🔄 **Incremental Hashing**: Stream large datasets efficiently
- ⏱️ **Constant-Time**: Timing attack resistant operations
- 🏗️ **Zero Dependencies**: Pure Rust implementation
## Installation
Add this to your `Cargo.toml`:
```toml
[dependencies]
clock-hash = "1.0.0"
```
### Feature Flags
- `default`: Includes `std` and `bench` features
- `std`: Enables standard library support (default)
- `no_std`: Disables standard library for embedded use
- `simd`: Enables SIMD optimizations (default on supported platforms)
- `bench`: Includes benchmarking utilities
For `no_std` environments:
```toml
[dependencies]
clock-hash = { version = "1.0.0", default-features = false, features = ["alloc"] }
```
## Usage
### Basic Hashing
```rust
use clock_hash::clockhash256;
fn main() {
let data = b"Hello, ClockHash!";
let hash = clockhash256(data);
println!("Hash: {:x}", hash.iter().fold(String::new(), |mut acc, &b| {
acc.push_str(&format!("{:02x}", b));
acc
}));
// Output: 32-byte hash array
}
```
### Domain-Separated Hashing
Prevent cross-domain collisions by using domain tags:
```rust
use clock_hash::{clockhash256_domain, tags};
fn hash_blockchain_data() {
let block_data = b"block_header_data";
let tx_data = b"transaction_data";
// Hash block data with domain separation
let block_hash = clockhash256_domain(tags::CLK_BLOCK, block_data);
// Hash transaction data with domain separation
let tx_hash = clockhash256_domain(tags::CLK_TX, tx_data);
// These hashes will be different even if block_data == tx_data
assert_ne!(block_hash, tx_hash);
}
```
### Incremental Hashing
For large datasets or streaming data:
```rust
use clock_hash::ClockHasher;
fn hash_large_file() -> Result<(), Box<dyn std::error::Error>> {
let mut hasher = ClockHasher::new();
// Process data in chunks
let chunks = vec![b"chunk1", b"chunk2", b"chunk3"];
for chunk in chunks {
hasher.update(chunk);
}
let final_hash = hasher.finalize();
println!("Final hash: {:x}", final_hash.iter().fold(String::new(), |mut acc, &b| {
acc.push_str(&format!("{:02x}", b));
acc
}));
Ok(())
}
```
### Domain Tags
ClockHash-256 supports the following domain tags for cryptographic separation:
| `CLK_BLOCK` | Block hashing | Consensus block headers |
| `CLK_TX` | Transaction IDs | Transaction identifiers |
| `CLK_MERKLE` | Merkle trees | Merkle tree nodes |
| `CLK_NONCE` | Nonce derivation | Signature nonce generation |
| `CLK_RNG` | RNG seeding | Deterministic random seeding |
## API Documentation
📚 [Full API Documentation](https://docs.rs/clock-hash)
The API is designed to be simple and ergonomic:
- `clockhash256(data: &[u8]) -> [u8; 32]`: One-shot hashing
- `clockhash256_domain(tag: u8, data: &[u8]) -> [u8; 32]`: Domain-separated hashing
- `ClockHasher`: Incremental hasher struct
- `tags`: Predefined domain tag constants
## Performance
ClockHash-256 is optimized for high throughput:
- **Target**: ≥1.5 GB/s single-threaded on modern x86_64
- **SIMD**: Hardware acceleration on AVX2/AVX-512, NEON, and other SIMD instruction sets
- **Memory**: Minimal memory footprint, suitable for constrained environments
- **Scalability**: Performance scales with CPU core count
Run benchmarks locally:
```bash
cargo bench
```
## Security
ClockHash-256 is designed with security as the highest priority:
- **256-bit preimage resistance**: Resistant to finding preimages
- **128-bit collision resistance**: Resistant to finding collisions
- **Domain separation**: Prevents cross-domain collision attacks
- **Constant-time operations**: Immune to timing attacks
- **Memory safety**: Zero unsafe code, guaranteed by Rust
- **Comprehensive testing**: Property-based testing, fuzzing, and formal verification
For security-related issues, see our [Security Policy](SECURITY.md).
## Algorithm Overview
ClockHash-256 processes messages in 128-byte blocks using a novel construction:
1. **ClockPermute**: 16-round permutation with strong diffusion
2. **S-box**: 256-byte substitution table for nonlinearity
3. **ClockMix**: Message scrambling with avalanche effect
4. **Output folding**: Final compression to 256 bits
See [RFC-0002](docs/rfc-0002.md) for the complete cryptographic specification.
## Testing
ClockHash-256 has comprehensive test coverage:
```bash
# Run all tests
cargo test
# Run tests without default features
cargo test --no-default-features --features no_std
# Run fuzzing (requires nightly Rust)
cd fuzz && cargo fuzz run clockhash256_fuzz
# Run benchmarks
cargo bench
```
### Test Coverage
- ✅ Unit tests for all public APIs
- ✅ Property-based testing with proptest
- ✅ Fuzzing with cargo-fuzz
- ✅ Cross-platform testing (Linux, macOS, Windows)
- ✅ no_std compatibility testing
- ✅ Security property verification
- ✅ Performance regression testing
## Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
### Development Setup
```bash
# Clone the repository
git clone https://github.com/Olyntar-Labs/clock-hash.git
cd clock-hash
# Run tests
cargo test
# Run benchmarks
cargo bench
# Check code formatting
cargo fmt --check
# Run linting
cargo clippy
```
### Security Reviews
All changes undergo security review. See our [Security Policy](SECURITY.md) for vulnerability reporting.
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for version history and migration guides.
## License
Licensed under either of:
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
at your option.
---
**ClockHash-256** - High-performance cryptography for blockchain consensus ⚡🔒