rhdl_dsig_scalable_core/ubft/

signer.rs

//! The signing half of [`super::UbftEngine`]: a stream in front of the
//! batch engine's slices and certificate unit.
//!
//! # What changes against [`crate::engine`]
//!
//! | Batch engine | Here |
//! |---|---|
//! | [`crate::msg_reader`] reads messages from HBM and deals message `n` to slice `n mod SLICES` | the **dealer** takes one request beat at a time and gives it to the first idle slice |
//! | one [`crate::hbm_writer`] per slice writes frames to HBM | the **arbiter** sends whole frames, one slice at a time, on one stream |
//! | the run ends after `count` frames | the session ends after `sign_count` frames |
//!
//! The slices, the certificate unit and every register on the links between
//! them ([`crate::relay`]) are the batch engine's, unchanged.
//!
//! # The dealer
//!
//! Each slice has a one-message buffer. The request stream is ready while
//! any buffer is empty; a request goes to the first empty buffer at or after
//! a rotating pointer, so a lone request never waits behind a busy slice.
//! A buffer empties when the slice's message link takes it.
//!
//! # The certificate announce
//!
//! Each batch certificate (the 64-byte commitment and its Ed25519
//! signature) is copied, as the certificate unit hands it to slice 0, to the
//! `m_axis_cert` stream: commitment beat, then signature beat (`tlast`).
//! uBFT sends it to the peers ahead of the batch's signatures, so their
//! verifiers check it before the first one arrives (see
//! [`super::verifier`]). The copy is best-effort: if the previous one is
//! still waiting, the new one is skipped and that batch's first record
//! simply checks its certificate itself.
//!
//! # The arbiter
//!
//! A frame is 26 beats. The arbiter picks a slice whose beat pipe offers a
//! beat, sends that slice's beats until the one with `last`, then picks
//! again (round robin), so frames never interleave on the stream.

use super::{Axis512, Latency, latency_kernel};
use crate::cert_unit::{CertConfig, CertInput, CertUnit, SLICES};
use crate::ed25519::ScalarWords;
use crate::engine::{SliceControl, SliceReport};
use crate::relay::{Delay, PipeIn, RelayPipe, ToggleLink};
use crate::slice::{Slice, SliceInput};
use crate::slice_factory::{FactoryConfig, TWO_BLOCK_MESSAGE};
use crate::slice_signer::{Certificate, FrameBeat, Message};
use rhdl::core::ReplicatedSynchronous;
use rhdl::prelude::*;
use rhdl_fpga::core::dff::DFF;

/// The session's signing configuration (host arguments).
#[derive(Clone, Copy, Debug, PartialEq, Digital)]
pub struct SignConfig {
    /// Derive-key prefix CV (secret).
    pub prefix_cv: [b32; 8],
    /// Epoch.
    pub epoch: b64,
    /// First batch id.
    pub first_batch: b64,
    /// Batches to make.
    pub batches: b32,
    /// Ed25519 seed as four little-endian words (secret).
    pub seed: [b64; 4],
}

/// Signer inputs.
#[derive(Clone, Copy, Debug, PartialEq, Digital)]
pub struct SignerIn {
    /// The configuration (static while running).
    pub config: SignConfig,
    /// The session runs.
    pub run: bool,
    /// The free-running tick counter.
    pub ticks: b64,
    /// `s_axis_sign`.
    pub request: Axis512,
    /// `m_axis_frame` `tready`.
    pub frame_ready: bool,
    /// `m_axis_cert` `tready`.
    pub cert_ready: bool,
}

/// Signer outputs.
#[derive(Clone, Copy, Debug, PartialEq, Digital)]
pub struct SignerOut {
    /// `s_axis_sign` `tready`.
    pub request_ready: bool,
    /// `m_axis_frame`.
    pub frame: Axis512,
    /// `m_axis_cert`: the announce of each new batch certificate.
    pub cert: Axis512,
    /// Certificates announced.
    pub announced: b32,
    /// Requests accepted.
    pub taken: b32,
    /// Frames sent.
    pub signed: b32,
    /// Batches certified.
    pub certified: b32,
    /// The Ed25519 public key derived from the seed.
    pub public_key: ScalarWords,
    /// A slice fault.
    pub slice_fault: bool,
    /// A certificate unit fault.
    pub cert_fault: bool,
    /// Isolated-request latency.
    pub latency: Latency,
}

/// Dealer, arbiter and counters.
#[derive(Clone, Copy, Debug, PartialEq, Digital)]
#[doc(hidden)]
pub struct SignerState {
    /// Each slice's one-message buffer.
    pending: [Message; SLICES],
    /// Rotating dealer pointer.
    next: b3,
    /// The arbiter is sending `owner`'s frame.
    locked: bool,
    /// Whose frame is on the stream.
    owner: b3,
    /// Rotating arbiter pointer.
    next_owner: b3,
    /// Requests accepted.
    taken: b32,
    /// Frames sent.
    signed: b32,
    /// Requests accepted whose frame has not left.
    in_flight: b32,
    /// Latency statistics.
    latency: Latency,
    /// An announce is waiting to leave.
    ann_valid: bool,
    /// Its second (signature) beat is next.
    ann_second: bool,
    /// The announced commitment.
    ann_commitment: [b8; 64],
    /// The announced signature.
    ann_signature: [b8; 64],
    /// Certificates announced.
    announced: b32,
}

/// Profile 2's signed context in the sign beat (bytes 8..56; 0 in profile 1).
const CONTEXT_BYTES: usize = if TWO_BLOCK_MESSAGE { 48 } else { 0 };

impl Default for SignerState {
    /// Empty buffers, nothing in flight.
    fn default() -> Self {
        Self {
            pending: [Message {
                valid: false,
                bytes: [b8(0); crate::MESSAGE_BYTES],
                index: b64(0),
            }; SLICES],
            next: b3(0),
            locked: false,
            owner: b3(0),
            next_owner: b3(0),
            taken: b32(0),
            signed: b32(0),
            in_flight: b32(0),
            latency: Latency::default(),
            ann_valid: false,
            ann_second: false,
            ann_commitment: [b8(0); 64],
            ann_signature: [b8(0); 64],
            announced: b32(0),
        }
    }
}

/// The signing half.
#[derive(Clone, Debug, Synchronous, SynchronousDQ)]
pub struct UbftSigner<const TABLE_MASK: usize> {
    /// Dealer, arbiter, counters.
    state: DFF<SignerState>,
    /// The shared Merkle-top and Ed25519 certificate unit.
    cert: CertUnit,
    /// The slices.
    slices: ReplicatedSynchronous<Slice<TABLE_MASK>, SLICES>,
    /// Frame beats, slice → arbiter.
    beats: [RelayPipe<FrameBeat>; SLICES],
    /// Messages, dealer → slice.
    messages: [ToggleLink<Message>; SLICES],
    /// Certificates, cert unit → slice.
    certificates: [ToggleLink<Certificate>; SLICES],
    /// Configuration, `run` and root credit, signer → slice.
    to_slice: [Delay<SliceControl>; SLICES],
    /// Root pulses, status and fault, slice → signer.
    from_slice: [Delay<SliceReport>; SLICES],
}

impl<const TABLE_MASK: usize> Default for UbftSigner<TABLE_MASK> {
    /// Power-on: nothing made, nothing buffered.
    fn default() -> Self {
        Self {
            state: DFF::new(SignerState::default()),
            cert: CertUnit::default(),
            slices: ReplicatedSynchronous::new(Slice::default()),
            beats: core::array::from_fn(|_| RelayPipe::default()),
            messages: core::array::from_fn(|_| ToggleLink::default()),
            certificates: core::array::from_fn(|_| ToggleLink::default()),
            to_slice: core::array::from_fn(|_| Delay::default()),
            from_slice: core::array::from_fn(|_| Delay::default()),
        }
    }
}

impl<const TABLE_MASK: usize> SynchronousIO for UbftSigner<TABLE_MASK> {
    type I = SignerIn;
    type O = SignerOut;
    type Kernel = ubft_signer_kernel<TABLE_MASK>;
}

/// The signer's logic.
#[allow(clippy::needless_range_loop, clippy::too_many_lines)]
#[kernel]
pub fn ubft_signer_kernel<const TABLE_MASK: usize>(
    _clock_reset: ClockReset,
    input: SignerIn,
    q: UbftSignerQ<TABLE_MASK>,
) -> (SignerOut, UbftSignerD<TABLE_MASK>) {
    let mut s = q.state;
    let run = input.run;

    // ------------------------------------------------ dealer
    // A buffer whose message the link took is empty again.
    let mut pending = q.state.pending;
    let mut message_taken = [false; SLICES];
    for i in 0..SLICES {
        message_taken[i] = q.state.pending[i].valid && q.messages[i].ready;
        if message_taken[i] {
            pending[i].valid = false;
        }
    }
    // The first empty buffer at or after `next`, else the first empty one.
    let mut pick_found = false;
    let mut pick = b3(0);
    for j in 0..SLICES {
        let i = SLICES - 1 - j;
        if !q.state.pending[i].valid && b3(i as u128) >= q.state.next {
            pick_found = true;
            pick = b3(i as u128);
        }
    }
    if !pick_found {
        for j in 0..SLICES {
            let i = SLICES - 1 - j;
            if !q.state.pending[i].valid {
                pick_found = true;
                pick = b3(i as u128);
            }
        }
    }
    let request_ready = run && pick_found;
    let accept = request_ready && input.request.valid;
    if accept {
        let d = input.request.data;
        // Profile 1: message bytes 0..16, tag 16..24. Profile 2 (sign layout
        // v2, as Ed25519's): tag 0..8, the 48-byte context 8..56, signed
        // zero-extended to 64 bytes.
        let mut bytes = [b8(0); crate::MESSAGE_BYTES];
        let mut index = b64(0);
        if TWO_BLOCK_MESSAGE {
            for k in 0..CONTEXT_BYTES {
                bytes[k] = d[8 + k];
            }
            for k in 0..8 {
                index = index | (d[k].resize::<64>() << ((8 * k) as u128));
            }
        } else {
            for k in 0..16 {
                bytes[k] = d[k];
            }
            for k in 0..8 {
                index = index | (d[16 + k].resize::<64>() << ((8 * k) as u128));
            }
        }
        for i in 0..SLICES {
            if pick == b3(i as u128) {
                pending[i] = Message {
                    valid: true,
                    bytes,
                    index,
                };
            }
        }
        s.next = if pick == b3((SLICES - 1) as u128) { b3(0) } else { pick + b3(1) };
        s.taken = q.state.taken + b32(1);
    }
    s.pending = pending;

    // ------------------------------------------------ arbiter
    let mut frame = Axis512 {
        valid: false,
        data: [b8(0); 64],
        last: false,
    };
    let mut beat_taken = [false; SLICES];
    let mut sent_last = false;
    if q.state.locked {
        for i in 0..SLICES {
            if q.state.owner == b3(i as u128) {
                frame = Axis512 {
                    valid: q.beats[i].valid,
                    data: q.beats[i].data.data,
                    last: q.beats[i].data.last,
                };
                beat_taken[i] = q.beats[i].valid && input.frame_ready;
            }
        }
        if frame.valid && input.frame_ready && frame.last {
            sent_last = true;
            s.locked = false;
            s.signed = q.state.signed + b32(1);
        }
    } else {
        let mut found = false;
        let mut owner = b3(0);
        for j in 0..SLICES {
            let i = SLICES - 1 - j;
            if q.beats[i].valid && b3(i as u128) >= q.state.next_owner {
                found = true;
                owner = b3(i as u128);
            }
        }
        if !found {
            for j in 0..SLICES {
                let i = SLICES - 1 - j;
                if q.beats[i].valid {
                    found = true;
                    owner = b3(i as u128);
                }
            }
        }
        if found {
            s.locked = true;
            s.owner = owner;
            s.next_owner = if owner == b3((SLICES - 1) as u128) { b3(0) } else { owner + b3(1) };
        }
    }

    // ------------------------------------------------ latency
    let begin = accept && q.state.in_flight == b32(0);
    let end = sent_last && q.state.in_flight == b32(1);
    let abandon = accept && q.state.in_flight != b32(0);
    s.latency = latency_kernel(q.state.latency, input.ticks, begin, end, abandon);
    s.in_flight = q.state.in_flight + (if accept { b32(1) } else { b32(0) }) - (if sent_last { b32(1) } else { b32(0) });

    // ------------------------------------------------ certificate announce
    let cert_out = Axis512 {
        valid: q.state.ann_valid,
        data: if q.state.ann_second { q.state.ann_signature } else { q.state.ann_commitment },
        last: q.state.ann_second,
    };
    if q.state.ann_valid && input.cert_ready {
        if q.state.ann_second {
            s.ann_valid = false;
            s.ann_second = false;
            s.announced = q.state.announced + b32(1);
        } else {
            s.ann_second = true;
        }
    }
    // A certificate slice 0 takes this cycle is copied, unless one waits.
    let fresh = q.cert.certificates[0].valid && q.certificates[0].ready;
    if fresh && !q.state.ann_valid {
        s.ann_valid = true;
        s.ann_second = false;
        s.ann_commitment = q.cert.certificates[0].commitment;
        s.ann_signature = q.cert.certificates[0].signature;
    }

    // ------------------------------------------------ slices and links
    let cfg = input.config;
    let mut roots = [q.from_slice[0].root; SLICES];
    let mut cert_taken = [false; SLICES];
    let mut slice_fault = false;
    for i in 0..SLICES {
        roots[i] = q.from_slice[i].root;
        cert_taken[i] = q.cert.certificates[i].valid && q.certificates[i].ready;
        slice_fault = slice_fault || q.from_slice[i].fault;
    }
    let mut to_slice = [SliceControl {
        config: FactoryConfig {
            prefix_cv: cfg.prefix_cv,
            epoch: cfg.epoch,
            first_batch: cfg.first_batch,
            batches: cfg.batches,
            slice: b3(0),
        },
        run,
        roots_popped: q.cert.roots_popped,
    }; SLICES];
    let mut slices = [SliceInput {
        config: q.to_slice[0].config,
        run: q.to_slice[0].run,
        message: q.messages[0].data,
        certificate: q.certificates[0].data,
        beat_ready: q.beats[0].ready,
        roots_popped: q.to_slice[0].roots_popped,
    }; SLICES];
    let mut beats = [PipeIn::<FrameBeat> {
        data: q.slices[0].beat,
        valid: q.slices[0].beat.valid,
        taken: beat_taken[0],
    }; SLICES];
    let mut messages = [PipeIn::<Message> {
        data: q.state.pending[0],
        valid: q.state.pending[0].valid,
        taken: q.slices[0].message_taken,
    }; SLICES];
    let mut certificates = [PipeIn::<Certificate> {
        data: q.cert.certificates[0],
        valid: q.cert.certificates[0].valid,
        taken: q.slices[0].certificate_taken,
    }; SLICES];
    let mut from_slice = [SliceReport {
        root: q.slices[0].root,
        keys_started: q.slices[0].keys_started,
        fault: q.slices[0].fault,
    }; SLICES];
    for i in 0..SLICES {
        to_slice[i].config.slice = b3(i as u128);
        slices[i] = SliceInput {
            config: q.to_slice[i].config,
            run: q.to_slice[i].run,
            message: q.messages[i].data,
            certificate: q.certificates[i].data,
            beat_ready: q.beats[i].ready,
            roots_popped: q.to_slice[i].roots_popped,
        };
        slices[i].message.valid = q.messages[i].valid;
        slices[i].certificate.valid = q.certificates[i].valid;
        beats[i] = PipeIn::<FrameBeat> {
            data: q.slices[i].beat,
            valid: q.slices[i].beat.valid,
            taken: beat_taken[i],
        };
        messages[i] = PipeIn::<Message> {
            data: q.state.pending[i],
            valid: q.state.pending[i].valid,
            taken: q.slices[i].message_taken,
        };
        certificates[i] = PipeIn::<Certificate> {
            data: q.cert.certificates[i],
            valid: q.cert.certificates[i].valid,
            taken: q.slices[i].certificate_taken,
        };
        from_slice[i] = SliceReport {
            root: q.slices[i].root,
            keys_started: q.slices[i].keys_started,
            fault: q.slices[i].fault,
        };
    }
    let d = UbftSignerD::<TABLE_MASK> {
        state: s,
        cert: CertInput {
            config: CertConfig {
                epoch: cfg.epoch,
                first_batch: cfg.first_batch,
                key_seed: ScalarWords { words: cfg.seed },
                run,
            },
            roots,
            taken: cert_taken,
        },
        slices,
        beats,
        messages,
        certificates,
        to_slice,
        from_slice,
    };
    (
        SignerOut {
            request_ready,
            frame,
            cert: cert_out,
            announced: q.state.announced,
            taken: q.state.taken,
            signed: q.state.signed,
            certified: q.cert.certified,
            public_key: q.cert.public_key,
            slice_fault,
            cert_fault: q.cert.fault,
            latency: q.state.latency,
        },
        d,
    )
}