# RFC-0002: ClockHash-256 Specification
**Crate Name:** `clock-hash`
**Algorithm Name:** ClockHash-256
**Output Size:** 256 bits (32 bytes)
**Status:** Draft
**Author:** Olyntar Cryptography Division
**Target Version:** 0.1.0
---
## 1. Abstract
ClockHash-256 is a deterministic, fixed-output cryptographic hash function designed for ClockinChain consensus operations. It is optimized for fast verification in blockchain environments, strong avalanche behavior, no-std compatibility, and domain-separated hashing for multi-purpose use.
ClockHash-256 serves as the **default hash primitive** for:
- Block headers
- Transaction IDs
- Merkle constructions
- Deterministic RNG seeding
- Signature nonce derivation
---
## 2. Design Goals
1. 256-bit security target
2. No external dependencies
3. Constant-time operations
4. Minimal memory footprint
5. Efficient on 64-bit CPUs
6. Straightforward portable Rust implementation
---
## 3. High-Level Construction
ClockHash-256 processes messages in 128-byte (1024-bit) blocks using:
- **Internal state**: 512 bits (8 × u64 words)
- **Block size**: 128 bytes (16 × u64 words)
- **16-round permutation** (ClockPermute)
- **S-box nonlinearity** (256-byte substitution table)
- **Message scrambling** (ClockMix)
---
## 4. Constants
### 4.1 Initialization Vector (IV)
All values little-endian u64:
```
IV[0] = 0x243F6A8885A308D3 // π fraction
IV[1] = 0x13198A2E03707344 // e fraction
IV[2] = 0xA4093822299F31D0 // √2 fraction
IV[3] = 0x082EFA98EC4E6C89 // golden ratio φ fraction
IV[4] = 0x452821E638D01377 // φ² fraction
IV[5] = 0xBE5466CF34E90C6C // π² fraction
IV[6] = 0xC0AC29B7C97C50DD // e² fraction
IV[7] = 0x3F84D5B5B5470917 // √3 fraction
```
### 4.2 Rotation Schedule
For rounds and message mixing:
```
R = [7, 19, 31, 43, 13, 29, 37, 53, 11, 23, 41, 59, 17, 33, 47, 61]
```
### 4.3 Multiplication Primes
```
P0 = 0x9E3779B185EBCA87
P1 = 0xC2B2AE3D27D4EB4F
```
### 4.4 S-Box
256-byte substitution table generated using:
```
SBOX[i] = ROTL8(floor(256 * frac(sin(i+1))), i mod 8) ^ 0x9E
```
---
## 5. Algorithm Components
### 5.1 ClockMix (Message Scrambling)
For each word M[i] in a 16-word block:
1. `M[i] = M[i] ⊕ ROTL(M[(i+1) mod 16], R[i])`
2. `M[i] = M[i] + SBOX[M[i] & 0xFF]` (wrapping addition)
### 5.2 ClockPermute (State Permutation)
16-round permutation on 8-word state:
**Step A - Add & Multiply:**
```
S[i] = (S[i] + S[(i+1) mod 8]) * P0
```
**Step B - XOR & Rotate:**
```
S[i] = ROTL(S[i] ⊕ S[(i+3) mod 8], R[(round+i) mod 16])
```
**Step C - Cross Diffusion:**
```
swap S[1] ↔ S[5]
swap S[2] ↔ S[6]
swap S[3] ↔ S[7]
```
### 5.3 Block Processing
For each 128-byte block:
1. Parse to 16 u64 words (little-endian)
2. Apply ClockMix
3. Inject into state:
- `S[i] = S[i] + M[i]`
- `S[i] = S[i] ⊕ ROTR(S[(i+4) mod 8], 17)`
4. Apply ClockPermute (16 rounds)
---
## 6. Padding
Message padded as:
```
until multiple of 128 bytes.
---
## 7. Finalization
After processing all blocks:
1. XOR state with IV: `S[i] = S[i] ⊕ IV[i]`
2. Output folding: `H[i] = S[i] ⊕ S[i+4]` for i=0..3
3. Return 32-byte hash: `H0 || H1 || H2 || H3`
---
## 8. Domain Separation
Domain separation prevents cross-domain collisions by prepending:
```
domain_tag || 0x00 || message
```
Standard domain tags:
- `CLK-BLOCK`: Block hashing
- `CLK-TX`: Transaction IDs
- `CLK-MERKLE`: Merkle tree nodes
- `CLK-NONCE`: Signature nonce derivation
- `CLK-RNG`: Deterministic RNG seeding
---
## 9. Security Properties
- 256-bit preimage resistance target
- 128-bit collision resistance target
- Strong avalanche (>50% bit flip expected)
- No data-dependent branching
- No heap allocation
---
## 10. API Specification
### 10.1 Core Function
```rust
pub fn clockhash256(data: &[u8]) -> [u8; 32];
```
### 10.2 Domain-Separated Hash
```rust
pub fn clockhash256_domain(domain: &[u8], data: &[u8]) -> [u8; 32];
```
### 10.3 Incremental Hasher
```rust
pub struct ClockHasher { ... }
impl ClockHasher {
pub fn new() -> Self;
pub fn update(&mut self, data: &[u8]);
pub fn finalize(self) -> [u8; 32];
}
```
---
## 11. Performance Target
On x86_64:
- ≥ 1.5 GB/s single-threaded
- Constant time per byte after padding
---
## 12. no_std Requirement
Must compile with:
```toml
default-features = false
features = ["no_std"]
```
No heap allocation permitted.
---
## 13. Consensus Requirement
ClockHash-256 output is consensus-critical. All nodes MUST use identical implementation. Any change requires hard-fork.
---
**End RFC-0002**