cyber_hemera/

params.rs

//! Hemera — Poseidon2 parameter set over the Goldilocks field.
//!
//! Single source of truth for every constant in the protocol.
//! The WGSL shader (`gpu/poseidon2.wgsl`) duplicates a subset of
//! these values because WGSL cannot import Rust; keep them in sync.
//!
//! ```text
//! ┌──────────────────────────────────────────────────────────┐
//! │  HEMERA — Complete Specification                         │
//! │                                                          │
//! │  Field:           p = 2⁶⁴ − 2³² + 1 (Goldilocks)       │
//! │  S-box:           d = 7  (x → x⁷, minimum for field)    │
//! │  State width:     t = 16                      = 2⁴       │
//! │  Full rounds:     R_F = 8  (4 + 4)            = 2³       │
//! │  Partial rounds:  R_P = 64                    = 2⁶       │
//! │  Rate:            r = 8  elements (56 bytes)  = 2³       │
//! │  Capacity:        c = 8  elements (64 bytes)  = 2³       │
//! │  Output:          8  elements (64 bytes)      = 2³       │
//! │                                                          │
//! │  Full round constants:    8 × 16 = 128        = 2⁷       │
//! │  Partial round constants: 64                  = 2⁶       │
//! │  Total constants:         192                 = 3 × 2⁶   │
//! │  Total rounds:            72                  = 9 × 2³   │
//! │                                                          │
//! │  Classical collision resistance:  256 bits     = 2⁸       │
//! │  Quantum collision resistance:   170 bits                │
//! │  Algebraic degree:               2¹⁸⁰                    │
//! │                                                          │
//! │  Every parameter that appears in code is a power of 2.   │
//! └──────────────────────────────────────────────────────────┘
//! ```

use std::sync::LazyLock;

use p3_field::PrimeField64;
use p3_goldilocks::{Goldilocks, Poseidon2Goldilocks};
use p3_symmetric::Permutation;
use rand::RngCore;

// ── Permutation parameters ──────────────────────────────────────────

/// Width of the Poseidon2 state (number of Goldilocks field elements).
pub const WIDTH: usize = 16;

/// Number of full (external) rounds — 4 initial + 4 final.
pub const ROUNDS_F: usize = 8;

/// Number of partial (internal) rounds.
pub const ROUNDS_P: usize = 64;

/// S-box degree (x → x^d).
pub const SBOX_DEGREE: usize = 7;

// ── Sponge parameters ───────────────────────────────────────────────

/// Number of rate elements in the sponge.
pub const RATE: usize = 8;

/// Number of capacity elements in the sponge.
pub const CAPACITY: usize = WIDTH - RATE; // 8

// ── Encoding parameters ─────────────────────────────────────────────

/// Bytes per field element when encoding arbitrary input data.
///
/// We use 7 bytes per element because 2^56 − 1 < p (Goldilocks prime),
/// so any 7-byte value fits without reduction.
pub const INPUT_BYTES_PER_ELEMENT: usize = 7;

/// Bytes per field element when encoding hash output.
///
/// For output we use the full canonical u64 representation (8 bytes),
/// since output elements are already valid field elements.
pub const OUTPUT_BYTES_PER_ELEMENT: usize = 8;

// ── Derived constants ───────────────────────────────────────────────

/// Number of input bytes that fill one rate block (8 elements × 7 bytes).
pub const RATE_BYTES: usize = RATE * INPUT_BYTES_PER_ELEMENT; // 56

/// Number of output elements extracted per squeeze (= rate).
pub const OUTPUT_ELEMENTS: usize = RATE; // 8

/// Number of output bytes per squeeze (8 elements × 8 bytes).
pub const OUTPUT_BYTES: usize = OUTPUT_ELEMENTS * OUTPUT_BYTES_PER_ELEMENT; // 64

// ── Security properties (informational) ─────────────────────────────

/// Classical collision resistance in bits.
pub const COLLISION_BITS: usize = 256;

// ── Self-bootstrapping round constant generation ────────────────────

/// Genesis seed: five bytes [0x63, 0x79, 0x62, 0x65, 0x72].
///
/// The cryptographic input is this byte sequence alone — no character set,
/// no encoding convention. The fact that these bytes happen to spell "cyber"
/// in ASCII is the human meaning; the specification is the hex literals.
const GENESIS_SEED: &[u8] = &[0x63, 0x79, 0x62, 0x65, 0x72];

/// Global singleton Poseidon2 permutation instance, self-bootstrapped.
///
/// Round constants are generated by Hemera₀ (the zero-constant permutation)
/// operating as a sponge on the genesis seed. No external PRNG is used.
static POSEIDON2: LazyLock<Poseidon2Goldilocks<WIDTH>> = LazyLock::new(bootstrap_hemera);

/// Build the Hemera permutation via self-bootstrapping.
///
/// 1. Create Hemera₀ = Poseidon2 with all 192 round constants = 0
/// 2. Run Hemera₀ as a sponge: absorb GENESIS_SEED, squeeze constants
/// 3. Use those elements as round constants for the final Hemera
fn bootstrap_hemera() -> Poseidon2Goldilocks<WIDTH> {
    let (hemera0, state) = bootstrap_sponge_state();
    let mut rng = SqueezeRng {
        hemera0,
        state,
        buffer: [0u64; RATE],
        pos: RATE, // empty — will squeeze on first read
    };
    Poseidon2Goldilocks::new_from_rng(ROUNDS_F, ROUNDS_P, &mut rng)
}

/// Create Hemera₀ and return the sponge state after absorbing the genesis seed.
///
/// This is the shared bootstrap logic used by both the CPU permutation
/// and the GPU round constant export.
fn bootstrap_sponge_state() -> (Poseidon2Goldilocks<WIDTH>, [Goldilocks; WIDTH]) {
    // Hemera₀ — all-zero round constants.
    let hemera0 = Poseidon2Goldilocks::new_from_rng(ROUNDS_F, ROUNDS_P, &mut ZeroRng);

    // Absorb the genesis seed through Hemera₀ sponge.
    let mut state = [Goldilocks::new(0); WIDTH];

    // Pad: seed || 0x01 || 0x00* to RATE_BYTES (56 bytes).
    let mut padded = [0u8; RATE_BYTES];
    padded[..GENESIS_SEED.len()].copy_from_slice(GENESIS_SEED);
    padded[GENESIS_SEED.len()] = 0x01;

    // Encode padded bytes as rate elements (7 bytes per element).
    let mut rate_block = [Goldilocks::new(0); RATE];
    crate::encoding::bytes_to_rate_block(&padded, &mut rate_block);

    // Absorb via Goldilocks field addition.
    for i in 0..RATE {
        state[i] = state[i] + rate_block[i];
    }

    // Store message length in capacity (state[10]), matching sponge convention.
    state[RATE + 2] = Goldilocks::new(GENESIS_SEED.len() as u64);

    // Permute with Hemera₀.
    hemera0.permute_mut(&mut state);

    (hemera0, state)
}

/// Squeeze the 192 round constants as raw u64 values from the bootstrap sponge.
///
/// Returns the canonical Goldilocks representations in the exact order consumed
/// by `new_from_rng`: 128 external (8 rounds × 16 elements) then 64 internal.
/// Used by the GPU module to upload constants to shaders.
pub(crate) fn bootstrap_constants_u64() -> Vec<u64> {
    let (hemera0, state) = bootstrap_sponge_state();
    let mut rng = SqueezeRng {
        hemera0,
        state,
        buffer: [0u64; RATE],
        pos: RATE,
    };
    let total = ROUNDS_F * WIDTH + ROUNDS_P; // 192
    (0..total).map(|_| rng.next_u64()).collect()
}

/// RNG that produces zeros (used to create Hemera₀).
struct ZeroRng;

impl RngCore for ZeroRng {
    fn next_u32(&mut self) -> u32 {
        0
    }
    fn next_u64(&mut self) -> u64 {
        0
    }
    fn fill_bytes(&mut self, dest: &mut [u8]) {
        dest.fill(0);
    }
}

/// RNG that squeezes Goldilocks elements from a Hemera₀ sponge state.
///
/// Each squeeze extracts RATE (8) elements from the rate portion, then
/// permutes the state for the next block. This produces an unlimited
/// stream of pseudorandom field elements.
struct SqueezeRng {
    hemera0: Poseidon2Goldilocks<WIDTH>,
    state: [Goldilocks; WIDTH],
    buffer: [u64; RATE],
    pos: usize,
}

impl SqueezeRng {
    fn squeeze_block(&mut self) {
        for i in 0..RATE {
            self.buffer[i] = self.state[i].as_canonical_u64();
        }
        self.hemera0.permute_mut(&mut self.state);
        self.pos = 0;
    }
}

impl RngCore for SqueezeRng {
    fn next_u32(&mut self) -> u32 {
        self.next_u64() as u32
    }

    fn next_u64(&mut self) -> u64 {
        if self.pos >= RATE {
            self.squeeze_block();
        }
        let val = self.buffer[self.pos];
        self.pos += 1;
        val
    }

    fn fill_bytes(&mut self, dest: &mut [u8]) {
        let mut written = 0;
        while written < dest.len() {
            let val = self.next_u64();
            let bytes = val.to_le_bytes();
            let remaining = dest.len() - written;
            let n = remaining.min(8);
            dest[written..written + n].copy_from_slice(&bytes[..n]);
            written += n;
        }
    }
}

/// Apply the Poseidon2 permutation in-place.
pub(crate) fn permute(state: &mut [Goldilocks; WIDTH]) {
    POSEIDON2.permute_mut(state);
}

#[cfg(test)]
mod tests {
    use super::*;
    use p3_goldilocks::Goldilocks;

    #[test]
    fn permutation_is_deterministic() {
        let mut s1 = [Goldilocks::new(0); WIDTH];
        let mut s2 = [Goldilocks::new(0); WIDTH];
        permute(&mut s1);
        permute(&mut s2);
        assert_eq!(s1, s2);
    }

    #[test]
    fn permutation_changes_state() {
        let mut state = [Goldilocks::new(0); WIDTH];
        let original = state;
        permute(&mut state);
        assert_ne!(state, original);
    }

    #[test]
    fn different_inputs_different_outputs() {
        let mut s1 = [Goldilocks::new(0); WIDTH];
        let mut s2 = [Goldilocks::new(0); WIDTH];
        s2[0] = Goldilocks::new(1);
        permute(&mut s1);
        permute(&mut s2);
        assert_ne!(s1, s2);
    }

    #[test]
    fn sponge_geometry() {
        assert_eq!(WIDTH, RATE + CAPACITY);
        assert_eq!(RATE_BYTES, 56);
        assert_eq!(OUTPUT_BYTES, 64);
        assert_eq!(OUTPUT_ELEMENTS, 8);
    }
}