rhdl_dsig_scalable_core/

slice_signer.rs

//! A slice's signer: one complete 1,642-byte signature every 68 cycles.
//!
//! # Where this fits
//!
//! By the time a message reaches the signer, almost all the work of signing
//! it is already done. The [key factory](crate::slice_factory) made the
//! one-time key in advance and wrote its chain nodes to the
//! [key cache](crate::cache_bank). The [subtree builder](crate::slice_merkle)
//! hashed the key into its batch's Merkle tree. The shared
//! [cert unit](crate::cert_unit) signed the batch root with Ed25519. What is
//! left is to pick a key, hash the message, look up the right nodes, and
//! write it all out in the wire format. That is this module.
//!
//! The [`slice_factory`](crate::slice_factory) fills the cache with keys; this
//! block spends them. For every message it:
//!
//! 1. **burns** the slice's next certified key (before anything else, so a
//!    lost frame can never lead to key reuse) and asks the factory's message
//!    slot for `BLAKE3(pk_hash ‖ nonce ‖ message)`;
//! 2. turns the 64-byte XOF into 68 base-4 **digits** (64 message digits and
//!    a 4-digit complement checksum, as in
//!    [`reference::digits_from_xof`](crate::reference::digits_from_xof));
//! 3. **prepares** the frame: reads four Merkle siblings, writes the six
//!    header beats, and computes the 34 header bytes that share a beat with
//!    the first node;
//! 4. **streams** the frame: one cached node per cycle, each read from the
//!    cache bank its digit selects, packed into beats.
//!
//! Preparation of frame *n + 1* overlaps the streaming of frame *n*, so in
//! steady state a slice finishes one frame every 68 cycles: exactly one key per
//! [`KEY_PERIOD`](crate::slice_schedule::KEY_PERIOD), matching the factory.
//!
//! ```text
//!  message ─▶ [burn+hash] ─▶ factory slot ─▶ [digits] ─▶ [prep] ─▶ [stream] ─▶ frame buffer ─▶ writer
//!                │                                         │           │        (4 frames)
//!          key metadata RAM ◀── key_done          proof port   cache banks
//!          certificate FIFO ◀── shared top
//! ```
//!
//! (The "four Merkle siblings" are the 8-slice count, [`SUBTREE_LEVELS`]; the
//! other [`TOP_LEVELS`] siblings arrive inside the certificate.)
//!
//! # Why the stages overlap
//!
//! Streaming is the only stage that has to take 68 cycles (one node per
//! chain, one cache read per cycle). Everything else is shorter, so it is
//! done for the *next* frame while the current one streams. A work item moves
//! through a chain of holding registers in [`SignerControl`]:
//!
//! ```text
//!   queue[0..2] ──▶ prep ──▶ ready ──▶ stream ──▶ cache reads ──▶ packer ──▶ frame buffer ──▶ drain
//!   (burned,        (siblings, (prepared, (68 node    (token rides  (beats      (4 slots of     (26 beats
//!    digits soon)    header)    waiting)   addresses)  with data)    6..25)      32 beats)       to HBM)
//!
//!   time ─▶     |──── frame n streams (68) ────|──── frame n+1 streams (68) ────|
//!               |hash n+1|prep n+1| (waits)     |hash n+2|prep n+2| (waits)
//! ```
//!
//! A new stream may begin addressing on the cycle right after the previous
//! stream addressed chain 67, so streams run back to back with no gap.
//!
//! # Frame layout (26 × 64-byte beats = 1,664 bytes)
//!
//! Bytes `0..1642` are exactly
//! [`DsigSignature::to_bytes`](crate::reference::DsigSignature::to_bytes):
//!
//! | Bytes | Field |
//! |---|---|
//! | 0..64 | certificate commitment (`DSIGFP01` envelope) |
//! | 64..128 | Ed25519 signature |
//! | 128..130 | key index within the batch, LE16 |
//! | 130..162 | `pk_hash` |
//! | 162..178 | `pk_nonce` |
//! | 178..194 | private nonce |
//! | 194..418 | seven 32-byte Merkle siblings, bottom-up |
//! | 418..1642 | 68 revealed 18-byte nodes |
//!
//! Bytes `1642..1650` carry the message index (LE64) so the host can match a
//! frame to its message; the remaining padding is zero.
//!
//! The same layout seen as beats, and who writes each one:
//!
//! ```text
//!   beat 0       commitment                                  ← preparation (from certificate)
//!   beat 1       Ed25519 signature                           ← preparation (from certificate)
//!   beats 2..5   frame bytes 128..384 (index, pk_hash, …)    ← preparation (header_tail_kernel)
//!   beat 6       bytes 384..418 (34 B) │ node 0 │ node 1 …    ← packer (34 B are its prefix)
//!   beats 7..24  nodes                                       ← packer
//!   beat 25      … node 67 │ msg index (B 42..50) │ zeros     ← packer + index patch
//!   beats 26..31 unused (each frame slot is 32 beats)
//! ```
//!
//! # Ordering rules
//!
//! * Keys are spent in cache-slot order, which is the order the factory made
//!   them, so "key `k` is finished" is the counter test `done > consumed`.
//! * A key is eligible only once its batch certificate is present.
//! * A certificate is retired after the last frame that needs it (this slice's
//!   `j = 15` key of that batch) has been prepared.
//!
//! # The key-reuse rule
//!
//! A one-time key must never sign twice. The signer increments `consumed` (the
//! burn) in the same cycle the factory accepts the message hash, before any
//! node is read. `consumed` only moves forward and the factory may not
//! overwrite a slot until its key is burned (see [`crate::slice`]). So even if
//! a frame is later lost, delayed or the run is reset, the key it used is
//! gone for good.

use crate::cache_bank::CACHE_READ_LATENCY;
use crate::packer::{ElementPacker, PackerInput, SIGNATURE_PREFIX};
use crate::slice_factory::{
    KeyDone, SlotRequest, SlotResult, TWO_BLOCK_MESSAGE, bytes_from_words_kernel, cache_address_kernel,
    words_from_bytes_kernel,
};
use crate::slice_merkle::{node_address_kernel, ring_of_kernel};
use crate::{CHAINS, ELEMENT_BYTES, KEY_BITS, KEY_ONE, KEYS_PER_SLICE, KeyIndex, MESSAGE_BYTES, SUBTREE_LEVELS, TOP_LEVELS};
use rhdl::prelude::*;
use rhdl_fpga::core::{
    dff::DFF,
    ram::synchronous::{In as RamIn, SyncBRAM, Write as RamWrite},
};

/// Beats per frame.
///
/// 26 × 64 = 1,664 bytes: the 1,642-byte signature, the 8-byte message index
/// and zero padding.
pub const FRAME_BEATS: usize = 26;
/// Frame slots in the frame buffer.
///
/// Four slots let one frame be prepared, one be packed and finished frames
/// wait for the HBM writer, all at the same time.
pub const FRAME_SLOTS: usize = 4;
/// Header beats written by preparation.
///
/// Beats 0..6 (frame bytes 0..384). Beat 6 onward comes from the packer.
pub const HEADER_BEATS: usize = 6;

/// One batch certificate as delivered by the shared top.
#[derive(Clone, Copy, Debug, PartialEq, Digital)]
pub struct Certificate {
    /// Certificate present.
    pub valid: bool,
    /// Batch number relative to the run's first batch.
    pub batch: b32,
    /// The 64-byte signed envelope.
    pub commitment: [b8; 64],
    /// The Ed25519 signature over it.
    pub signature: [b8; 64],
    /// Merkle siblings above this slice's subtree, lowest level first
    /// ([`TOP_LEVELS`] of them; levels 4, 5 and 6 in the 8-slice build).
    pub top: [[b8; 32]; TOP_LEVELS],
}

/// A message to sign.
#[derive(Clone, Copy, Debug, PartialEq, Digital)]
pub struct Message {
    /// Message present; hold until `message_taken`.
    pub valid: bool,
    /// The message bytes (16, or 64 in profile 2; [`crate::MESSAGE_BYTES`]).
    pub bytes: [b8; MESSAGE_BYTES],
    /// Host-assigned index, written into the frame padding.
    pub index: b64,
}

impl Default for Message {
    /// No message.
    fn default() -> Self {
        Self {
            valid: false,
            bytes: [b8(0); MESSAGE_BYTES],
            index: b64(0),
        }
    }
}

/// Message bytes past the first 16 (profile 2: 48, hashed as the digest's
/// tail block; profile 1: none).
const TAIL_BYTES: usize = MESSAGE_BYTES - 16;

/// Signer inputs.
#[derive(Clone, Copy, Debug, PartialEq, Digital)]
pub struct SignerInput {
    /// This slice's number (key index = `16·slice + j`).
    pub slice: b3,
    /// Next message.
    pub message: Message,
    /// Finished keys from the factory.
    pub key_done: KeyDone,
    /// Certificate offered by the shared top.
    pub certificate: Certificate,
    /// The factory took our message request.
    pub message_taken: bool,
    /// Factory slot results (message ones are ours).
    pub slot_result: SlotResult,
    /// Cache bank read data, positions 0..=3, for the address presented [`CACHE_READ_LATENCY`] cycles ago.
    ///
    /// The banks answer [`CACHE_READ_LATENCY`] cycles after `cache_address`
    /// was presented; the `reads` token line in [`SignerControl`] keeps track
    /// of which read each node belongs to.
    pub cache_data: [[b8; ELEMENT_BYTES]; 4],
    /// Subtree proof-port data for the address presented on the previous cycle.
    pub proof_data: [b8; 32],
    /// The writer accepts the presented frame beat.
    pub beat_ready: bool,
}

/// One frame beat for the HBM writer.
#[derive(Clone, Copy, Debug, PartialEq, Digital)]
pub struct FrameBeat {
    /// Beat present.
    pub valid: bool,
    /// The 64 bytes.
    pub data: [b8; 64],
    /// Final beat of a frame.
    pub last: bool,
}

/// Signer outputs.
#[derive(Clone, Copy, Debug, PartialEq, Digital)]
pub struct SignerOutput {
    /// Message request for the factory slot.
    pub request: SlotRequest,
    /// The current message was consumed (its key is burned).
    pub message_taken: bool,
    /// The certificate on the input was accepted this cycle.
    pub certificate_taken: bool,
    /// Cache read address `slot × 68 + chain` ([`cache_address_kernel`]).
    pub cache_address: b16,
    /// Subtree proof read address.
    pub proof_address: b10,
    /// Frame beat to the writer.
    pub beat: FrameBeat,
    /// Keys burned so far (the factory's cache-space accounting).
    pub consumed: b32,
    /// Frames fully handed to the writer.
    pub frames_out: b32,
}

/// Per-key metadata held until the key is spent.
///
/// Stored in the signer's metadata RAM at the key's cache slot when the
/// factory reports `key_done`; read back when the key is burned. 32 + 16 +
/// 16 bytes plus batch and position.
#[derive(Clone, Copy, Debug, PartialEq, Digital)]
pub struct KeyMeta {
    /// Endpoint commitment.
    pub pk_hash: [b8; 32],
    /// Public salt.
    pub pk_nonce: [b8; 16],
    /// Private nonce.
    pub nonce: [b8; 16],
    /// Relative batch.
    pub batch: b32,
    /// Position within the slice's batch share (`0..KEYS_PER_SLICE`).
    pub j: KeyIndex,
}

/// A burned key travelling through digits, preparation and streaming.
#[derive(Clone, Copy, Debug, PartialEq, Digital)]
pub struct Work {
    /// Entry in use.
    pub valid: bool,
    /// Digits have arrived.
    pub digits_ready: bool,
    /// Cache slot of the key.
    pub slot: b9,
    /// Key metadata.
    pub meta: KeyMeta,
    /// Message index.
    pub index: b64,
    /// 68 base-4 digits.
    pub digits: [b2; CHAINS],
    /// Frame-buffer slot (assigned by preparation).
    pub frame: b2,
    /// Header bytes 384..418 that precede node 0 in beat 6.
    ///
    /// Only the first [`SIGNATURE_PREFIX`] = 34 bytes are used; the array is
    /// 64 bytes because that is the packer's prefix input width.
    pub prefix: [b8; 64],
}

/// Everything needed to use one cache read when its data arrives.
///
/// The stream may already be addressing the next frame by then, so the
/// frame slot and message index ride along with the read.
#[derive(Clone, Copy, Debug, PartialEq, Digital, Default)]
pub struct NodeRead {
    /// A real read (not a bubble).
    pub valid: bool,
    /// The read is chain 0, the first node of its frame.
    pub first: bool,
    /// Which of the four stored positions this signature reveals.
    pub digit: b2,
    /// Frame slot the node belongs to.
    pub frame: b2,
    /// Message index of that frame.
    pub index: b64,
}

/// Index of the oldest read token.
///
/// The token at this index was issued [`CACHE_READ_LATENCY`] cycles ago, so
/// its node is on the cache output now.
const READ_LAST: usize = CACHE_READ_LATENCY - 1;

/// Resettable control.
#[derive(Clone, Copy, Debug, PartialEq, Digital)]
pub struct SignerControl {
    /// Keys finished by the factory.
    pub done: b32,
    /// Keys burned.
    pub consumed: b32,
    /// The metadata RAM output holds key `consumed`.
    pub meta_ok: bool,
    /// A message hash is in flight.
    pub hashing: bool,
    /// Profile 2: the first digest block returned; the tail is to be offered.
    pub tail_pending: bool,
    /// Profile 2: the tail block is in flight (its result is the digest).
    pub in_tail: bool,
    /// Profile 2: the tail block (message bytes 16..64, zero-padded).
    pub tail_block: [b32; 16],
    /// Profile 2: the first block's chaining value.
    pub tail_cv: [b32; 8],
    /// Certificates held (0..=2).
    pub certs: b2,
    /// Burned keys awaiting digits/preparation, oldest first.
    pub queue: [Work; 2],
    /// Preparation step: 0 idle, 1..=4 sibling reads, 5..=10 header writes.
    ///
    /// The counts are for the 8-slice build: steps `1..=SUBTREE_LEVELS` read
    /// siblings, then [`HEADER_BEATS`] steps write the header.
    pub prep_step: b4,
    /// The work item being prepared.
    pub prep: Work,
    /// Prepared, waiting to stream.
    pub ready: Work,
    /// The work item being streamed.
    pub stream: Work,
    /// Next chain to address while streaming (68 = finished addressing).
    pub chain: b7,
    /// Cache reads in flight, newest at index 0. A read issued this cycle
    /// reaches the end of this line exactly when its node leaves the cache
    /// (`CACHE_READ_LATENCY` cycles), so the token travels with its data.
    pub reads: [NodeRead; CACHE_READ_LATENCY],
    /// Packer beats written for the frame being packed.
    pub packed: b5,
    /// Frame slot the packer writes into.
    pub pack_frame: b2,
    /// Message index of the frame being packed.
    pub pack_index: b64,
    /// Frame slots in use (preparing, streaming, complete or draining).
    pub frames_used: b3,
    /// Next frame slot to allocate.
    pub next_frame: b2,
    /// Completed frames not yet drained.
    pub complete: b3,
    /// Frame slot being drained.
    pub drain_frame: b2,
    /// Next beat to drain.
    pub drain_beat: b5,
    /// A drain read is outstanding.
    pub drain_pending: bool,
    /// The outstanding drain read is the frame's last beat.
    pub drain_last: bool,
    /// The output register holds an undelivered beat.
    pub beat_valid: bool,
    /// Frame-buffer address of the outstanding drain read (held while stalled).
    pub drain_read: b7,
    /// Frames fully drained.
    pub frames_out: b32,
}

/// Resetless datapath registers.
///
/// Wide data that needs no reset value: nothing reads it until a control
/// flag in [`SignerControl`] says it is valid. Leaving it out of reset saves
/// reset routing.
#[derive(Clone, Copy, Debug, PartialEq, Digital)]
pub struct SignerData {
    /// Certificate FIFO (index 0 oldest).
    pub certs: [Certificate; 2],
    /// Subtree siblings of the frame being prepared.
    pub siblings: [[b8; 32]; SUBTREE_LEVELS],
    /// The beat presented to the writer.
    pub beat: [b8; 64],
    /// The presented beat is a frame's last.
    pub beat_last: bool,
}

/// The slice signer.
///
/// Two RAMs, the frame packer and two big registers. All the control lives in
/// [`slice_signer_kernel`].
#[derive(Clone, Debug, Synchronous, SynchronousDQ)]
pub struct SliceSigner {
    /// [`KeyMeta`] of every cached key, indexed by cache slot (512 entries).
    meta_ram: SyncBRAM<KeyMeta, 9>,
    /// Frame buffer: [`FRAME_SLOTS`] slots × 32 beats of 64 bytes
    /// (address `frame << 5 | beat`, see [`frame_address_kernel`]).
    frames: SyncBRAM<[b8; 64], 7>,
    /// Lays the 34-byte header tail and 68 revealed nodes into beats 6..25.
    packer: ElementPacker<SIGNATURE_PREFIX>,
    /// Counters, queues, stage registers (reset to idle).
    control: DFF<SignerControl>,
    /// Certificates, siblings and the output beat (no reset).
    data: DFF<SignerData>,
}

/// An empty queue entry. `meta` is don't-care while `valid` is low.
///
/// Host-side helper for [`Default`]; kernels use [`cleared_work`].
fn idle_work() -> Work {
    cleared_work(Work {
        valid: false,
        digits_ready: false,
        slot: b9(0),
        meta: KeyMeta::dont_care(),
        index: b64(0),
        digits: [b2(0); CHAINS],
        frame: b2(0),
        prefix: [b8(0); 64],
    })
}

/// Kernel-side `idle_work`: clears every field except the don't-care
/// `meta`, which it keeps from `stale` (kernels cannot call `dont_care()`).
///
/// `meta` is never read while `valid` is low, so whatever value it keeps is
/// harmless.
#[kernel]
pub fn cleared_work(stale: Work) -> Work {
    Work {
        valid: false,
        digits_ready: false,
        slot: b9(0),
        meta: stale.meta,
        index: b64(0),
        digits: [b2(0); CHAINS],
        frame: b2(0),
        prefix: [b8(0); 64],
    }
}

impl Default for SliceSigner {
    /// No keys known, nothing burned, every stage idle, no certificates.
    ///
    /// `chain` starts at 68 ("finished addressing") so the idle stream does
    /// not issue reads.
    fn default() -> Self {
        let idle = idle_work();
        Self {
            meta_ram: SyncBRAM::default(),
            frames: SyncBRAM::default(),
            packer: ElementPacker::default(),
            control: DFF::new(SignerControl {
                done: b32(0),
                consumed: b32(0),
                meta_ok: false,
                hashing: false,
                tail_pending: false,
                in_tail: false,
                tail_block: [b32(0); 16],
                tail_cv: [b32(0); 8],
                certs: b2(0),
                queue: [idle; 2],
                prep_step: b4(0),
                prep: idle,
                ready: idle,
                stream: idle,
                chain: b7(CHAINS as u128),
                reads: [NodeRead::default(); CACHE_READ_LATENCY],
                packed: b5(0),
                pack_frame: b2(0),
                pack_index: b64(0),
                frames_used: b3(0),
                next_frame: b2(0),
                complete: b3(0),
                drain_frame: b2(0),
                drain_beat: b5(0),
                drain_pending: false,
                drain_last: false,
                beat_valid: false,
                drain_read: b7(0),
                frames_out: b32(0),
            }),
            data: DFF::resetless(),
        }
    }
}

/// Input: messages, keys, certificates, cache and proof data, writer
/// back-pressure. Output: hash requests, cache/proof addresses, frame beats.
impl SynchronousIO for SliceSigner {
    type I = SignerInput;
    type O = SignerOutput;
    type Kernel = slice_signer_kernel;
}

/// 68 digits from the 64-byte message XOF (low two bits, then checksum).
///
/// * Digits 0..64: the low two bits of each XOF byte (values 0..=3).
/// * Digits 64..68: the checksum `Σ (3 − d)` over those 64 digits, written
///   in base 4, low digit first. The maximum is 64 × 3 = 192, so it fits in
///   8 bits and four base-4 digits.
///
/// The checksum is what makes W-OTS+ safe: raising any message digit (which a
/// forger could do by hashing further along a chain) lowers the checksum, and
/// a lower checksum digit would need a chain to be walked *backwards*, which
/// is infeasible. Combinational.
#[allow(clippy::needless_range_loop)]
#[kernel]
pub fn digits_kernel(xof: [b8; 64]) -> [b2; CHAINS] {
    let mut digits = [b2(0); CHAINS];
    // Running sum of (3 − digit); 8 bits is enough (at most 192).
    let mut checksum = b8(0);
    for i in 0..64 {
        let d: b2 = xof[i].resize();
        digits[i] = d;
        checksum = checksum + (b8(3) - d.resize::<8>());
    }
    // The checksum's four base-4 digits, least significant first.
    digits[64] = checksum.resize();
    digits[65] = (checksum >> 2).resize();
    digits[66] = (checksum >> 4).resize();
    digits[67] = (checksum >> 6).resize();
    digits
}

/// The 290 header bytes after the signature (frame bytes 128..418).
///
/// Output index `i` is frame byte `128 + i`:
///
/// | `h[..]` | Frame bytes | Field |
/// |---|---|---|
/// | 0..2 | 128..130 | `key_index`, LE16 |
/// | 2..34 | 130..162 | `pk_hash` |
/// | 34..50 | 162..178 | `pk_nonce` |
/// | 50..66 | 178..194 | private nonce |
/// | 66..290 | 194..418 | 7 siblings: `siblings` (subtree), then `top` (cert unit) |
///
/// Bytes 0..256 fill header beats 2..5; bytes 256..290 become the packer
/// prefix. Combinational.
#[allow(clippy::needless_range_loop)]
#[kernel]
pub fn header_tail_kernel(
    key_index: b16,
    meta: KeyMeta,
    siblings: [[b8; 32]; SUBTREE_LEVELS],
    top: [[b8; 32]; TOP_LEVELS],
) -> [b8; 290] {
    let mut h = [b8(0); 290];
    // Key index within the batch, little-endian.
    h[0] = key_index.resize();
    h[1] = (key_index >> 8).resize();
    for b in 0..32 {
        h[2 + b] = meta.pk_hash[b];
    }
    for b in 0..16 {
        h[34 + b] = meta.pk_nonce[b];
        h[50 + b] = meta.nonce[b];
    }
    // The 7 proof siblings, lowest level first: the subtree's own, then the
    // certificate unit's. Their byte offsets do not depend on the slice count.
    for level in 0..SUBTREE_LEVELS {
        for b in 0..32 {
            h[66 + 32 * level + b] = siblings[level][b];
        }
    }
    for level in 0..TOP_LEVELS {
        for b in 0..32 {
            h[66 + 32 * (SUBTREE_LEVELS + level) + b] = top[level][b];
        }
    }
    h
}

/// Subtree sibling address for `level` of key `j` in batch ring `ring`: the
/// node next to `j`'s ancestor at that level.
///
/// The ancestor of leaf `j` at `level` has index `j >> level`; its sibling
/// differs only in the lowest bit, hence `^ 1`. Combinational.
#[kernel]
pub fn sibling_address_kernel(ring: b5, j: KeyIndex, level: b3) -> b10 {
    // Index of the sibling within its level.
    let index: KeyIndex = (j >> level.resize::<KEY_BITS>()) ^ KEY_ONE;
    node_address_kernel(ring, level, index)
}

/// Preparation step of the last sibling read (steps `1..=` this).
const LAST_READ_STEP: b4 = b4(SUBTREE_LEVELS as u128);
/// Preparation step of header beat 0.
const HEADER_STEP: b4 = b4((SUBTREE_LEVELS + 1) as u128);
/// The last `j` of a batch: preparing it retires the batch's certificate.
const LAST_J: KeyIndex = bits((KEYS_PER_SLICE - 1) as u128);

/// Frame-buffer address of beat `beat` in frame slot `frame`.
///
/// `frame << 5 | beat`: each slot spans 32 beat addresses (26 used), so the
/// address is a concatenation rather than a multiply. Combinational.
#[kernel]
pub fn frame_address_kernel(frame: b2, beat: b5) -> b7 {
    (frame.resize::<7>() << 5) | beat.resize::<7>()
}

/// The signer's wiring.
///
/// One kernel runs every stage each cycle, in this order (later sections
/// may override decisions of earlier ones, so the order matters):
///
/// 1. keys and certificates: count finished keys, accept a certificate;
/// 2. **\[1\] burn + hash**: offer the message hash; burn the key if taken;
/// 3. **\[2\] digits**: turn a returning message hash into 68 digits;
/// 4. **\[4\] stream**: address the next chain, follow read tokens, feed the
///    packer and write packed beats (the packer has priority on the frame
///    buffer's write port);
/// 5. **\[3\] prepare**: sibling reads, then header beats when the write port
///    is free;
/// 6. frame completion and drain to the HBM writer;
/// 7. certificate FIFO retire/accept.
///
/// Timing: the metadata RAM, proof port and frame buffer answer one cycle
/// after their address; the cache answers [`CACHE_READ_LATENCY`] cycles
/// after. The packer adds one cycle.
#[allow(clippy::too_many_lines, clippy::needless_range_loop)]
#[kernel]
pub fn slice_signer_kernel(
    clock_reset: ClockReset,
    input: SignerInput,
    q: SliceSignerQ,
) -> (SignerOutput, SliceSignerD) {
    let resetting = clock_reset.reset.any();
    // Next-state copies of the two registers; edited below, stored at the end.
    let mut c = q.control;
    let mut data = q.data;

    // ============================================= keys and certificates
    if input.key_done.valid {
        c.done = q.control.done + b32(1);
    }
    // Cache slot of the next key to burn: `consumed mod 512`.
    let next_slot: b9 = q.control.consumed.resize();
    // Metadata RAM output (valid for key `consumed` when `meta_ok`).
    let meta = q.meta_ram;
    // The factory has finished at least one key we have not burned.
    let key_finished = q.control.done > q.control.consumed;
    // Accept an offered certificate whenever the 2-entry FIFO has room.
    let cert_taken = input.certificate.valid && q.control.certs != b2(2);
    if cert_taken {
        if q.control.certs == b2(0) {
            data.certs[0] = input.certificate;
        } else {
            data.certs[1] = input.certificate;
        }
    }

    // ============================================= [1] burn + hash
    // The next key's batch certificate is in the FIFO (entry 0 or 1).
    let cert_match = (q.control.certs != b2(0) && q.data.certs[0].batch == meta.batch)
        || (q.control.certs == b2(2) && q.data.certs[1].batch == meta.batch);
    // Offer the message hash only when: metadata is valid, the key is
    // certified, the work queue has room, no other hash is outstanding, a
    // message is waiting, and we are not in reset.
    // Profile 2: a new first block may go while the previous tail is in
    // flight (`in_tail`), but not while a tail still waits to be offered.
    let can_hash = q.control.meta_ok
        && cert_match
        && !q.control.queue[1].valid
        && !q.control.hashing
        && !(TWO_BLOCK_MESSAGE && q.control.tail_pending)
        && input.message.valid
        && !resetting;
    // The 64-byte hash input: pk_hash ‖ private nonce ‖ 16-byte message.
    let mut block = [b8(0); 64];
    for b in 0..32 {
        block[b] = meta.pk_hash[b];
    }
    for b in 0..16 {
        block[32 + b] = meta.nonce[b];
        block[48 + b] = input.message.bytes[b];
    }
    // Profile 2: the tail block, once the first block's CV is back.
    let offer_tail = TWO_BLOCK_MESSAGE && q.control.tail_pending && !resetting;
    let request = if offer_tail {
        SlotRequest {
            valid: true,
            block: q.control.tail_block,
            // Bit 0 marks a tail: results return in issue order, and a
            // first block may be in the lane behind a tail.
            tag: b16(1),
            tail: true,
            cv: q.control.tail_cv,
        }
    } else {
        SlotRequest {
            valid: can_hash,
            block: words_from_bytes_kernel(block),
            tag: b16(0),
            tail: false,
            cv: [b32(0); 8],
        }
    };
    if offer_tail && input.message_taken {
        c.tail_pending = false;
        c.in_tail = true;
    }
    // The factory accepted the hash this cycle: the key is burned now.
    let taken = can_hash && !offer_tail && input.message_taken;
    if TWO_BLOCK_MESSAGE && taken {
        // Latch the tail now: the message is consumed with the burn.
        let mut tail = [b8(0); 64];
        for b in 0..TAIL_BYTES {
            tail[b] = input.message.bytes[16 + b];
        }
        c.tail_block = words_from_bytes_kernel(tail);
    }
    // The RAM output is trustworthy one cycle after a stable address whose key
    // was already written; a burn changes the address.
    c.meta_ok = key_finished && !taken;
    // Working copy of the 2-entry work queue.
    let mut queue = q.control.queue;
    if taken {
        // The burn: from here on this key can never be selected again.
        c.consumed = q.control.consumed + b32(1);
        c.hashing = true;
        // New work item for the burned key; digits come later.
        let mut entry = cleared_work(q.control.queue[1]);
        entry.valid = true;
        entry.slot = next_slot;
        entry.meta = meta;
        entry.index = input.message.index;
        if q.control.queue[0].valid {
            queue[1] = entry;
        } else {
            queue[0] = entry;
        }
    }

    // ============================================= [2] digits
    // The message hash returned: attach its digits to the oldest entry that
    // is still waiting for them.
    // Profile 2: a first block's result is a CV for its tail, not digits
    // (a tail's result carries tag bit 0).
    let tail_result = (input.slot_result.tag & b16(1)) == b16(1);
    let first_of_two = TWO_BLOCK_MESSAGE && !tail_result;
    if input.slot_result.valid && input.slot_result.message && first_of_two {
        for w in 0..8 {
            c.tail_cv[w] = input.slot_result.words[w];
        }
        c.tail_pending = true;
        c.hashing = false;
    }
    if input.slot_result.valid && input.slot_result.message && !first_of_two {
        let digits = digits_kernel(bytes_from_words_kernel(input.slot_result.words));
        // Profile 2: `hashing` tracks the *next* message's first block, which
        // may already be in the lane behind this tail; only its own result
        // clears it.
        if !TWO_BLOCK_MESSAGE {
            c.hashing = false;
        }
        c.in_tail = false;
        if q.control.queue[0].valid && !q.control.queue[0].digits_ready {
            queue[0].digits = digits;
            queue[0].digits_ready = true;
        } else {
            queue[1].digits = digits;
            queue[1].digits_ready = true;
        }
    }

    // ============================================= [4] stream (before prep:
    // the packer has write priority on the frame buffer)
    // The frame being streamed, and this cycle's cache read (if any).
    let stream = q.control.stream;
    let mut cache_address = b16(0);
    let mut issued = NodeRead::default();
    if stream.valid && q.control.chain < b7(CHAINS as u128) {
        cache_address = cache_address_kernel(stream.slot, q.control.chain);
        // Digit of the chain being read (constant-index loop for RHDL).
        let mut digit = b2(0);
        for i in 0..CHAINS {
            if q.control.chain == b7(i as u128) {
                digit = stream.digits[i];
            }
        }
        issued = NodeRead {
            valid: true,
            first: q.control.chain == b7(0),
            digit,
            frame: stream.frame,
            index: stream.index,
        };
        c.chain = q.control.chain + b7(1);
    }
    // Shift the read tokens one step; the new token enters at index 0.
    c.reads[0] = issued;
    for k in 1..CACHE_READ_LATENCY {
        c.reads[k] = q.control.reads[k - 1];
    }
    // The oldest token's node is on the cache output this cycle.
    let arriving = q.control.reads[READ_LAST];
    // All four banks were read at the same row; keep the one at `digit`.
    let mut node = input.cache_data[0];
    for p in 0..4 {
        if arriving.digit == b2(p as u128) {
            node = input.cache_data[p];
        }
    }
    let node_valid = arriving.valid;
    // Node 0 of a frame: tells the packer to start a new stream.
    let node_start = arriving.valid && arriving.first;
    // The last node is addressed at chain 67; the next prepared frame may
    // start addressing on the very next cycle, so streams run back to back.
    let last_address = stream.valid && q.control.chain == b7((CHAINS - 1) as u128);
    let finished = stream.valid && q.control.chain == b7(CHAINS as u128);
    let mut next_stream = stream;
    if finished {
        next_stream.valid = false;
    }
    // The stream register can take the `ready` frame next cycle.
    let stream_free = !stream.valid || last_address || finished;
    let mut ready = q.control.ready;
    if stream_free && q.control.ready.valid {
        next_stream = q.control.ready;
        ready.valid = false;
        c.chain = b7(0);
    }
    c.stream = next_stream;

    // Packed beats → frame buffer (priority write).
    // The packer's registered output word (beat 6 + `packed` of the frame).
    let packed = q.packer;
    // The frame buffer's single write port for this cycle; the packer claims
    // it first, preparation uses it only if it is still free.
    let mut write = false;
    let mut write_address = b7(0);
    let mut write_value = packed.word;
    let mut frame_complete = false;
    if packed.valid {
        write = true;
        write_address = frame_address_kernel(
            q.control.pack_frame,
            q.control.packed + b5(HEADER_BEATS as u128),
        );
        c.packed = q.control.packed + b5(1);
        if packed.last {
            // Final beat: patch the message index into bytes 42..50 (frame
            // bytes 1642..1650), just after node 67.
            for b in 0..8 {
                write_value[42 + b] = (q.control.pack_index >> b64(8 * b as u128)).resize();
            }
            frame_complete = true;
        }
    }

    // A new frame's node 0 enters the packer: later packed beats belong to it.
    // (This cycle's packed write above used the previous frame's registers.)
    if node_start {
        c.pack_frame = arriving.frame;
        c.pack_index = arriving.index;
        c.packed = b5(0);
    }

    // ============================================= [3] prepare
    // The frame being prepared and its batch's subtree ring entry.
    let prep = q.control.prep;
    let ring = ring_of_kernel(prep.meta.batch);
    let mut proof_address = b10(0);
    let mut prep_next = prep;
    // Set when this cycle finishes preparing the batch's last key.
    let mut retire = false;
    let step = q.control.prep_step;
    // Start preparing when idle, a work item has its digits, the `ready`
    // register is empty and a frame slot is free.
    let can_start_prep = step == b4(0)
        && q.control.queue[0].valid
        && q.control.queue[0].digits_ready
        && !q.control.ready.valid
        && q.control.frames_used != b3(FRAME_SLOTS as u128);
    let mut frames_used = q.control.frames_used;
    if can_start_prep {
        // Move the oldest work item into `prep`, give it a frame slot, and
        // issue the level-0 sibling read.
        prep_next = q.control.queue[0];
        prep_next.frame = q.control.next_frame;
        queue[0] = queue[1];
        queue[1] = cleared_work(q.control.queue[1]);
        c.next_frame = q.control.next_frame + b2(1);
        frames_used = frames_used + b3(1);
        proof_address = sibling_address_kernel(
            ring_of_kernel(q.control.queue[0].meta.batch),
            q.control.queue[0].meta.j,
            b3(0),
        );
        c.prep_step = b4(1);
    } else if step >= b4(1) && step <= LAST_READ_STEP {
        // Sibling of `level` arrives from the proof port (read last cycle).
        let level: b3 = (step - b4(1)).resize();
        for l in 0..SUBTREE_LEVELS {
            if level == b3(l as u128) {
                data.siblings[l] = input.proof_data;
            }
        }
        // Issue the next level's read, unless this was the last one.
        if step < LAST_READ_STEP {
            proof_address = sibling_address_kernel(ring, prep.meta.j, level + b3(1));
        }
        c.prep_step = step + b4(1);
    } else if step >= HEADER_STEP {
        // Header beat (step − HEADER_STEP); waits whenever the packer owns the port.
        let beat: b5 = (step - HEADER_STEP).resize();
        // This key's batch certificate (it is entry 0 or entry 1).
        let cert = if q.data.certs[0].batch == prep.meta.batch {
            q.data.certs[0]
        } else {
            q.data.certs[1]
        };
        // Key index within the whole batch: `slice · KEYS_PER_SLICE + j`.
        let key_index: b16 =
            (input.slice.resize::<16>() << (SUBTREE_LEVELS as u128)) | prep.meta.j.resize::<16>();
        // Frame bytes 128..418.
        let tail = header_tail_kernel(key_index, prep.meta, q.data.siblings, cert.top);
        if !write {
            write = true;
            write_address = frame_address_kernel(prep.frame, beat);
            if beat == b5(0) {
                write_value = cert.commitment;
            } else if beat == b5(1) {
                write_value = cert.signature;
            } else {
                // Beats 2..5: consecutive 64-byte pieces of `tail`.
                let mut value = [b8(0); 64];
                for h in 2..HEADER_BEATS {
                    if beat == b5(h as u128) {
                        for b in 0..64 {
                            value[b] = tail[64 * (h - 2) + b];
                        }
                    }
                }
                write_value = value;
            }
            if beat == b5((HEADER_BEATS - 1) as u128) {
                // Last header beat: save the 34-byte packer prefix, hand the
                // item to `ready`, and go idle.
                for b in 0..SIGNATURE_PREFIX {
                    prep_next.prefix[b] = tail[256 + b];
                }
                prep_next.valid = false;
                ready = prep;
                ready.prefix = prep_next.prefix;
                c.prep_step = b4(0);
                retire = prep.meta.j == LAST_J;
            } else {
                c.prep_step = step + b4(1);
            }
        }
    }
    c.prep = prep_next;
    c.ready = ready;
    c.queue = queue;

    // ============================================= frame completion + drain
    // Frames whose last packed beat is written, waiting to be drained.
    let mut complete = q.control.complete;
    if frame_complete {
        complete = complete + b3(1);
    }
    // The writer took the presented beat.
    if q.control.beat_valid && input.beat_ready {
        c.beat_valid = false;
    }
    // The output register is empty, or is being emptied this cycle.
    let presenting_free = !q.control.beat_valid || input.beat_ready;
    // The drain read issued last cycle has its data on `q.frames`: move it
    // into the output register as soon as that is free.
    if q.control.drain_pending && presenting_free {
        data.beat = q.frames;
        data.beat_last = q.control.drain_last;
        c.beat_valid = true;
        c.drain_pending = false;
        if q.control.drain_last {
            c.frames_out = q.control.frames_out + b32(1);
        }
    }
    let drain_address = frame_address_kernel(q.control.drain_frame, q.control.drain_beat);
    // Issue the next drain read if a frame is complete and the pending read
    // (if any) is leaving this cycle.
    let can_drain = q.control.complete != b3(0) && (!q.control.drain_pending || presenting_free);
    // While stalled, keep re-reading the same address so the RAM output
    // stays stable.
    let mut read_address = q.control.drain_read;
    if can_drain {
        read_address = drain_address;
        c.drain_read = drain_address;
        c.drain_pending = true;
        c.drain_last = q.control.drain_beat == b5((FRAME_BEATS - 1) as u128);
        if q.control.drain_beat == b5((FRAME_BEATS - 1) as u128) {
            // Last beat read: the frame slot is free for a new frame.
            c.drain_beat = b5(0);
            c.drain_frame = q.control.drain_frame + b2(1);
            complete = complete - b3(1);
            frames_used = frames_used - b3(1);
        } else {
            c.drain_beat = q.control.drain_beat + b5(1);
        }
    }
    c.complete = complete;
    c.frames_used = frames_used;

    // Certificate FIFO: retire the oldest, then accept a new one.
    // `certs` is the FIFO's next fill level (0..=2).
    let mut certs = q.control.certs;
    if retire {
        data.certs[0] = q.data.certs[1];
        certs = certs - b2(1);
        if cert_taken {
            // Accepted this cycle into the slot that is shifting down.
            if q.control.certs == b2(1) {
                data.certs[0] = input.certificate;
            } else {
                data.certs[1] = input.certificate;
            }
        }
    }
    if cert_taken {
        certs = certs + b2(1);
    }
    c.certs = certs;

    let d = SliceSignerD {
        // Read the next key's metadata (one ahead after a burn); write each
        // finished key's metadata at its cache slot.
        meta_ram: RamIn::<KeyMeta, 9> {
            read_addr: if taken { next_slot + b9(1) } else { next_slot },
            write: RamWrite::<KeyMeta, 9> {
                addr: input.key_done.slot,
                value: KeyMeta {
                    pk_hash: input.key_done.pk_hash,
                    pk_nonce: input.key_done.pk_nonce,
                    nonce: input.key_done.nonce,
                    batch: input.key_done.batch,
                    j: input.key_done.j,
                },
                enable: input.key_done.valid,
            },
        },
        // Frame buffer: drain reads; packer or header writes.
        frames: RamIn::<[b8; 64], 7> {
            read_addr: read_address,
            write: RamWrite::<[b8; 64], 7> {
                addr: write_address,
                value: write_value,
                enable: write,
            },
        },
        // The arriving node, with the streamed frame's 34-byte prefix.
        packer: PackerInput {
            prefix: q.control.stream.prefix,
            start: node_start,
            node,
            valid: node_valid,
        },
        control: c,
        data,
    };
    (
        SignerOutput {
            request,
            message_taken: taken,
            certificate_taken: cert_taken,
            cache_address,
            proof_address,
            beat: FrameBeat {
                valid: q.control.beat_valid && !resetting,
                data: q.data.beat,
                last: q.data.beat_last,
            },
            consumed: q.control.consumed,
            frames_out: q.control.frames_out,
        },
        d,
    )
}