wots_rhdl/verify/

mod.rs

//! SHA-256 WOTS verification framing, exact work accounting, and RHDL tops.
//!
//! Verification consumes only public data. Its chain workload is therefore
//! message dependent, while the final comparison always examines all 256 bits.
//!
//! # Implemented scope and profile boundary
//!
//! This module implements hardware verification only for
//! `HASHSIGS_SHA256_GENERIC_V1`. [`top::Sha256VerifierTop`] is the inline-lane
//! source-simulation top, and [`top::ModularSha256VerifierTop`] is the typed
//! unresolved-lane skeleton for a separately generated RHDL SHA-256 lane. There
//! is no legacy Keccak verifier top in this crate. `LEGACY_KECCAK` signatures
//! can be checked by the `hashsigs-reference` software oracle, but they must not
//! be presented to this hardware interface.
//!
//! Serialized frames have no profile tag. A host protocol must authenticate
//! the selected profile/build target separately. Verification does not repair
//! the one-time-key requirement: accepting one signature says nothing about
//! whether its private key was safely used only once.
//!
//! # Input and result contract
//!
//! [`framing::VerifyStreamBeat`] carries the canonical byte sequence
//! `signature`, then `public_seed`, then `public_key_hash`, then the
//! already-hashed 32-byte message. All 2,240 bytes occupy exactly 35 transfers:
//!
//! | Beats | Contents | Sideband |
//! |---:|---|---|
//! | 0 through 32 | Signature segments 0 through 65 | Every byte valid; not last |
//! | 33 | Signature segment 66 followed by the public seed | Every byte valid; not last |
//! | 34 | Public-key endpoint hash followed by the message digest | Every byte valid; last |
//!
//! [`framing::pack_verify_input`] and [`framing::unpack_verify_input`] are the
//! independent host framing oracles. The hardware locks one physical context
//! from accepted beat zero through exactly 35 accepted beats. Fixed beat count,
//! not untrusted `last`, releases frame ownership. A stalled ready/valid offer
//! does not advance either the top or child frame counter.
//!
//! [`top::VerifierTopOutput`] returns one registered
//! [`cluster::VerifyResult`]. Its job ID is the opaque identity captured from
//! beat zero. `verified` is meaningful only with [`sha::VERIFY_ERROR_NONE`]; a
//! framing, transport, or audit error forces it false. The result remains stable
//! while `result_valid` is true and the consumer withholds `result_ready`, except
//! that the first fatal transport edge may convert a retained clean completion
//! into an identified transport error before suppressing its transfer.
//!
//! # Work graph and production topology
//!
//! Let `S` be the sum of `15 - digit` over the 64 message digits and let `h(S)`
//! be the sum of the three hexadecimal checksum digits. The verifier performs
//! exactly `S + 45 - h(S)` real chain hashes, ranging from 45 to 990. Including
//! 16 mask PRFs and 34 serialized endpoint-hash blocks, a SHA job emits between
//! [`tasks::VERIFY_MIN_SHA_TASKS`] and [`tasks::VERIFY_MAX_SHA_TASKS`] (95 and
//! 1,040) compression tasks. A bypassed chain position emits no compression
//! request.
//!
//! One [`sha::VerifySingleContextSha`] owns the frame, dependency state,
//! parity-banked chain storage, exact issued/retired counts, and retained result.
//! Four contexts share one lane through [`transport::VerifyTransport`] inside
//! [`cluster::VerifierCluster`]. The transport delays each launched tag for the
//! lane's exact 64-cycle latency and compares it before routing. The production
//! [`top::VerifierTop`] replicates three complete clusters, giving twelve
//! physical contexts and three lanes:
//!
//! ```text
//! top::Sha256VerifierTop
//!   +-- cluster 0: 4 verifier contexts + expected-tag transport + 1 lane
//!   +-- cluster 1: 4 verifier contexts + expected-tag transport + 1 lane
//!   +-- cluster 2: 4 verifier contexts + expected-tag transport + 1 lane
//!   +-- registered input-frame ownership and fair result merge
//! ```
//!
//! # Fail-closed transport and reset
//!
//! Outbound rejection and every missing, extra, mistimed, swapped, malformed,
//! stale, duplicate, or unowned return are fatal transport events. The failing
//! cluster registers reset-only poison. The top records the first cause,
//! broadcasts a registered abort to peers, blocks new frame admission and lane
//! launch, and drains already-accepted identities as nonzero errors. One input
//! beat may complete on the original containment edge because already-advertised
//! ready cannot depend combinationally on the newly observed response fault;
//! registered poison removes credit on the next cycle.
//!
//! Shared reset flushes every lane, expected-tag slot, valid bit, frame owner,
//! generation, result, and poison state and suppresses transfers on the reset
//! edge. Resetless data is ignored while resettable ownership is clear. Systems
//! that cannot reset the contexts, transport, and lanes together do not satisfy
//! this verifier's stale-token contract.
//!
//! # Reading order
//!
//! 1. [`framing`] defines the exact untrusted byte stream and host oracle.
//! 2. [`tasks`] derives message-dependent work and the canonical verifier tag
//!    subset without hardware state.
//! 3. [`sha`] implements one frame-owning context and its local audit/fault
//!    rules.
//! 4. [`transport`] arbitrates four contexts and enforces the exact lane-return
//!    schedule before routing.
//! 5. [`cluster`] composes four contexts, one transport, one injectable lane,
//!    result buffering, and local poison.
//! 6. [`top`] composes three clusters, locks the global frame, merges results,
//!    and contains a fault across peers.
//!
//! # Evidence boundary
//!
//! The complete inline-lane three-cluster top has Rust/RHDL source-simulation
//! evidence for twelve simultaneous worst-case jobs. The trace accepts and
//! routes exactly `12 * 1,040 = 12,480` SHA tasks, checks all decisions and job
//! identities under deterministic result stalls, and reaches quiescence. The
//! modular top also passes a bounded source-descriptor structure check with the
//! expected unresolved lane leaf.
//!
//! Those are source-tier results. This verifier has no linked generated-Verilog
//! arithmetic/equivalence simulation, U280 synthesis, mapped-resource, timing,
//! placement, route, or card-execution evidence. Signer throughput evidence
//! elsewhere in the crate cannot be attributed to the verifier.

pub mod cluster;
pub mod framing;
pub mod sha;
pub mod tasks;
pub mod top;
pub mod transport;

pub use cluster::{
    ModularSha256VerifierCluster, Sha256VerifierCluster, VERIFY_DIAGNOSTIC_CHILD_FAULT,
    VERIFY_DIAGNOSTIC_CHILD_RESPONSE_REJECT, VERIFY_DIAGNOSTIC_EXTERNAL_ABORT,
    VERIFY_DIAGNOSTIC_OWNERSHIP, VerifierCluster, VerifyClusterControl, VerifyClusterCore,
    VerifyClusterCoreInput, VerifyClusterInput, VerifyClusterOutput, VerifyClusterSelection,
    VerifyClusterTransportGateInput, VerifyClusterTransportGateOutput, VerifyResult,
    select_verify_cluster_context_kernel, sha256_verifier_cluster_kernel,
    verifier_cluster_with_lane_kernel, verify_cluster_core_kernel,
    verify_cluster_transport_gate_kernel,
};

pub use framing::{
    VERIFY_BEAT_BYTES, VERIFY_FULL_KEEP, VERIFY_INPUT_BEATS, VERIFY_INPUT_BYTES, VerifyBeatHalves,
    VerifyFrame, VerifyFrameBeat, VerifyFrameError, VerifyStreamBeat, pack_verify_input,
    unpack_verify_input, verify_beat_halves_kernel, verify_hash_equal_kernel,
};
pub use sha::{
    VERIFY_CONTEXT_LOGICAL_RAM_BITS, VERIFY_ERROR_AUDIT, VERIFY_ERROR_FRAME, VERIFY_ERROR_NONE,
    VERIFY_ERROR_TRANSPORT, VERIFY_LANE_LATENCY, VerifyContextControl, VerifyContextInput,
    VerifyContextOutput, VerifyPrepareRequestInput, VerifySingleContextSha,
    prepare_verify_request_kernel, verify_single_context_sha_kernel,
};
pub use tasks::{
    VERIFY_MASK_TASKS, VERIFY_MAX_CHAIN_TASKS, VERIFY_MAX_SHA_TASKS, VERIFY_MIN_CHAIN_TASKS,
    VERIFY_MIN_SHA_TASKS, VERIFY_PUBLIC_KEY_TASKS, canonical_verification_tasks,
    verification_chain_count, verification_chain_count_kernel, verification_chain_fields_kernel,
    verification_fields_are_canonical_kernel, verification_message_task_count_kernel,
    verification_sha_task_count, verification_sha_task_count_kernel,
    verification_tag_is_well_formed_kernel,
};
pub use transport::{
    VERIFY_CLUSTER_CONTEXTS, VERIFY_DIAGNOSTIC_ISSUE_REJECT, VERIFY_DIAGNOSTIC_RETURN_FORMAT,
    VERIFY_DIAGNOSTIC_RETURN_OWNER, VERIFY_DIAGNOSTIC_RETURN_TAG, VERIFY_DIAGNOSTIC_RETURN_TIMING,
    VERIFY_EXPECTED_TAG_ADDRESS_BITS, VerifyTransport, VerifyTransportControl,
    VerifyTransportInput, VerifyTransportOutput, VerifyTransportSelection,
    compression_input_equal_kernel, select_verify_transport_request_kernel,
    verify_transport_kernel, verify_transport_request_is_canonical_kernel,
};

pub use top::{
    ModularSha256VerifierTop, Sha256VerifierTop, VERIFY_TOP_CLUSTERS, VERIFY_TOP_CONTEXTS,
    VERIFY_TOP_DIAGNOSTIC_ADMISSION_CURSOR, VERIFY_TOP_DIAGNOSTIC_CLUSTER_0,
    VERIFY_TOP_DIAGNOSTIC_CLUSTER_1, VERIFY_TOP_DIAGNOSTIC_CLUSTER_2,
    VERIFY_TOP_DIAGNOSTIC_OWNERSHIP, VERIFY_TOP_DIAGNOSTIC_RESULT_CURSOR, VerifierTop,
    VerifierTopControl, VerifierTopInput, VerifierTopOutput, VerifierTopSelection,
    select_verifier_top_cluster_kernel, sha256_verifier_top_kernel, verifier_top_with_lane_kernel,
};