rhdl_dsig_scalable_core/

lib.rs

//! An all-RHDL DSig signer, and a verifier, whose throughput scales with the
//! number of *slices* (signer) or *units* (verifier) they build.
//!
//! # Building for Wolverine's U280
//!
//! The signing-engine flow generates RTL from this crate, then packages and
//! links it on Wolverine. Cargo alone does not produce a card image.
//!
//! Run commands from the workspace root. Before compilation or RTL generation,
//! record ownership in `PROJECT_COORDINATION.md` and
//! `/home/sahasta/Development/FPGA_COORDINATION.md`, and use the applicable
//! nonblocking `local-heavy.lock`; `crates/ed25519/tools/bounded.sh` wraps local
//! Cargo commands with that lock and resource limits. Reserve Wolverine builds
//! in both ledgers too, then use `crates/dsig/tools/with-u280-lock.sh` to hold
//! `u280.lock`. Do not bypass a busy lock.
//!
//! Inside the reserved, locked build session, generate a fresh bundle (Rust 1.96
//! is the toolchain used by the repository's DSig bounded runner):
//!
//! ```sh
//! export CARGO_TARGET_DIR="$PWD/target"
//! cargo build --locked --profile sim -p rhdl_dsig_scalable_core --bin dsig_engine_export
//! RHDL_HDL_ONLY=1 "$CARGO_TARGET_DIR/sim/dsig_engine_export" /absolute/path/new-bundle
//! ```
//!
//! The card build uses Vivado/Vitis 2023.2, the installed U280 `.xpfm`
//! platform and XRT. Replace the absolute example paths below with real paths
//! on Wolverine; the bundle must be copied there with its `BUNDLE.txt` intact,
//! and the output directory must be new. Keep the repository checkout available
//! on Wolverine because the scripts use its Tcl and host sources. Building an
//! image does not program the card or establish measured performance.
//!
//! The build script requires 48 GiB available RAM and 30 GiB free disk.
//! After recording Wolverine ownership in both ledgers, run there:
//!
//! ```sh
//! export HASHSIGS_U280_COORDINATION_ACK=both-ledgers-recorded
//! crates/dsig/tools/with-u280-lock.sh \
//!   "$PWD/crates/dsig/tools/wolverine-engine.sh" build \
//!   /absolute/path/new-bundle /absolute/path/new-build-output \
//!   /absolute/path/U280-platform.xpfm \
//!   /home/Xilinx/Vitis/2023.2/settings64.sh /opt/xilinx/xrt/setup.sh
//! ```
//!
//! Success produces `dsig_engine.xclbin`, a host runner, and
//! `acceptance/route-accepted.txt` after checking routing, setup/hold timing and
//! the kernel LUT cap. See `crates/dsig/fpga/u280/engine/README.md` for the
//! separate prepare/run/verify steps. Use a fresh run directory and key range
//! for every attempt, including after timeout or uncertain launch. Preserve
//! `DSIG_FPGA_W4_HARAKA_BLAKE3_V1`; a verified burst is not continuous throughput.
//!
//! For the verifier and isolated uBFT signature-service probe, use
//! `crates/dsig/tools/wolverine-verify.sh` and `wolverine-ubft.sh`, respectively,
//! with the matching exporters and the README under `fpga/u280/verify` or
//! `fpga/u280/ubft`. The latter is a crypto-service probe, not the full
//! `rhdl_ubft` consensus implementation. Match host and bundle slice counts.
//!
//! DSig signs each message with a fresh one-time hash-based key (W-OTS+,
//! w = 4) and amortizes one Ed25519 signature over every batch of 128 keys.
//! This crate is the hardware that does all of it on an Alveo U280. It
//! *makes* every key, certifies every batch, signs every message and writes
//! every 1,642-byte signature to HBM; and it checks signatures again at the
//! same rate.
//!
//! **In numbers** (October 2026). The 4-slice signer (build v13) signs
//! **12,038,905 signatures per second** on the card: a verified burst of
//! 1,572,864 signatures from one cold start, 17.03 cycles per signature, the
//! 4-slice ceiling of `4 × 205 MHz / 68`. It routes at 205 MHz (WNS
//! +0.016 ns) in **388,542 kernel CLB LUT** of the 420,000 cap. Every frame
//! is re-verified in software before a rate is printed. The 3-unit
//! verifier (build v3) checks those signatures on the card at **at least
//! 16,959,195 per second** (1,572,864 verified valid; a tampered burst got
//! every verdict right), routed at 205 MHz in 368,713 LUT. No continuous
//! (back-to-back) rate is claimed for either side: every number is a finite
//! burst from reset.
//!
//! | | 2 slices | 4 slices | 8 slices |
//! |---|---:|---:|---:|
//! | Ceiling at 205 MHz (one key per 68 clocks per slice) | 6.0M sig/s | 12.1M sig/s | 24.1M sig/s |
//! | Measured on the card | 6,019,465 sig/s (v3) | **12,038,905 sig/s** (v13) | model only |
//! | Kernel CLB LUT, routed at 205 MHz | 296,558 (v2) | 388,542 (v13) | model only |
//!
//! Reproduce: `tools/wolverine-engine.sh build` then `run` (see
//! `fpga/u280/engine/README.md`); the simulation gates are in
//! [Proving it](#chapter-11-proving-it).
//!
//! # The story in five minutes
//!
//! **The problem.** Ed25519 is the signature everyone trusts, and it is
//! expensive: this project's Ed25519 verify core checks about 279,000 per
//! second (native simulation, 735 cycles each at 205 MHz). Some systems
//! want tens of millions.
//!
//! **The bet.** DSig signs each message with a one-time hash-based key and
//! uses one Ed25519 signature to vouch for a whole batch of 128 such keys.
//! Hashing is cheap in hardware, so if the hashes are fast enough the
//! expensive part is paid once per 128 signatures.
//!
//! **The first version** made keys one at a time and was slow. Then, one
//! idea per step: skip the hash work whose inputs are constants (640 → 494
//! S-boxes per step); run a whole three-step chain every clock; give every
//! BLAKE3 compression a fixed slot in a 68-cycle timetable; make keys
//! before messages arrive; tag up to 32 certificate batches in flight; and
//! copy the whole design four times as *slices*.
//!
//! **What broke** was rarely the arithmetic. It was wires: a clock of 205 MHz
//! leaves 4.9 ns per step, and a wire from one silicon die to the next
//! eats a large part of it. Builds v5 to v13 were mostly about pinning blocks
//! to dies and putting registers on every long wire.
//!
//! **Where it stands.** The signer makes 12.04 million verified signatures
//! per second on a real card, the most four slices can do. The verifier
//! checks them on the card at 16.96 million per second, after a Vivado
//! netlist bug in the Ed25519 core was found and designed around.
//!
//! **Where you come in.** Eight slices (24M/s) need each slice at about
//! half its size, the verifier needs a fourth unit, and nobody has measured
//! continuous throughput. Small, checkable
//! starting points are in [Good first contributions](#good-first-contributions).
//!
//! This page tells the story of how the design came to be, one problem at a
//! time: what we were trying to do, what stood in the way, how we reasoned
//! about it, and what we built. Each chapter ends with the module that holds
//! the details. Read it in order once. Afterwards, [Where to go
//! next](#where-to-go-next) sends you straight to the part you want to
//! change.
//!
//! # Contents
//!
//! 1. [The question: what does a DSig signature cost?](#chapter-1-the-question-what-does-a-dsig-signature-cost)
//! 2. [Doing less work](#chapter-2-doing-less-work)
//! 3. [A whole chain every clock](#chapter-3-a-whole-chain-every-clock)
//! 4. [Feeding the chains: the 68-cycle timetable](#chapter-4-feeding-the-chains-the-68-cycle-timetable)
//! 5. [Keys before messages](#chapter-5-keys-before-messages)
//! 6. [One Ed25519 signature per 128 keys](#chapter-6-one-ed25519-signature-per-128-keys)
//! 7. [More of everything: slices](#chapter-7-more-of-everything-slices)
//! 8. [Meeting the clock](#chapter-8-meeting-the-clock)
//! 9. [Choosing the chain hash](#chapter-9-choosing-the-chain-hash)
//! 10. [Living on a shared chip](#chapter-10-living-on-a-shared-chip)
//! 11. [Proving it](#chapter-11-proving-it)
//! 12. [Checking signatures: the verifier](#chapter-12-checking-signatures-the-verifier)
//! 13. [Epilogue: your turn](#epilogue-your-turn)
//!
//! # The map
//!
//! Read the chapters below in order once; then these are the modules, in
//! the order a newcomer should open them:
//!
//! | Module | One line |
//! |---|---|
//! | [`reference`](mod@reference) | the whole scheme in plain software: the answer key for every block |
//! | [`chain_step`], [`chain_lane`] | one chain step (Haraka-512 with 494 live S-boxes, or BLAKE3, SHA-512) |
//! | [`slice_chain`], [`slice_schedule`], [`slice_factory`] | a whole chain per clock; the 68-cycle timetable; the key factory |
//! | [`cache_bank`], [`slice_signer`], [`packer`] | the key cache and the signer that turns a message into a frame |
//! | [`slice_merkle`], [`cert_unit`], [`certificate`], [`ed25519`] | subtrees, batch roots and the Ed25519 certificate |
//! | [`slice`](mod@slice), [`engine`] | one slice; the card kernel with its registers and HBM ports |
//! | [`relay`] | registered links between blocks on different dies |
//! | [`verify`] | the verifier: records in, verdict bytes out |
//! | [`config`], `planner` | cost and rate models for the shared chip planner and TUI |
//!
//! # The cost model
//!
//! Where the signer's 388,542 LUT go (build v13, routed, measured):
//!
//! | Block | CLB LUT | What dominates |
//! |---|---:|---|
//! | 4 slices | 4 × ~82.8k = 331,450 | per slice: key factory 65k (three Haraka lanes ~12k each, BLAKE3 lane 16.7k), signer 16.7k, subtree 1k |
//! | certificate unit | 48,476 | Ed25519 signer 25.9k, BLAKE3 lane 16.3k |
//! | frame-beat relay pipes | 6,263 | one LUT per bit per stage |
//! | control, reader, writers, toggle links | ~2.4k | |
//!
//! The binding constraint is LUTs, not cycles: a slice already makes one
//! key per 68 clocks with its lanes busy every clock, so throughput grows
//! only with more slices, and slices come in powers of two (the Merkle
//! subtree split). Block RAM is second (~270 tiles per slice with T-tables
//! in rounds 3..6); DSP is unused except by Ed25519.
//!
//! # Chapter 1: The question: what does a DSig signature cost?
//!
//! The goal was blunt: 30 million measured signatures per second on one
//! U280, inside a fixed LUT budget. Before designing anything we counted the
//! work, because *throughput = hardware ÷ work per signature*, and we can
//! attack both sides.
//!
//! ```text
//! key generation (per one-time key, ahead of time)
//!   seed, nonces           3 BLAKE3 compressions
//!   68 chain secrets       20 BLAKE3 compressions (XOF)
//!   68 hash chains         68 × 3 chain steps (Haraka-512)   ◀ almost all the work
//!   endpoint commitment    21 BLAKE3 compressions
//!   Merkle leaf + parents  ~1 BLAKE3 compression
//! certificate (per 128 keys)
//!   Merkle top + envelope  a few BLAKE3 compressions, 1 Ed25519 signature
//! signing (per message)
//!   message digest         1 BLAKE3 compression → 68 base-4 digits
//!   reveal                 one stored chain node per chain, 7 Merkle siblings
//! ```
//!
//! A W-OTS+ key has 68 *hash chains*: 64 carry a base-4 digit of the message
//! digest and 4 carry a checksum. Each chain starts at a secret and is hashed
//! three times. A signature reveals, for each chain, the node at the
//! position of its digit. The verifier hashes the rest of the way and checks
//! that it lands on the public endpoint.
//!
#![doc = concat!("<div style=\"overflow-x:auto\">", include_str!("../docs/images/hbss-wots.svg"), "</div>")]
//!
//! So a key costs 204 chain steps and about 47 BLAKE3 compressions. Signing
//! a message is cheap; making the key is the work. **The conclusion that
//! shaped everything:** build a machine that makes keys at line rate and
//! signs from a cache of them.
//!
//! # Chapter 2: Doing less work
//!
//! **Problem.** A Haraka-512 chain step is 40 AES rounds, 640 S-boxes.
//! S-boxes are 256-entry tables. In LUTs they are the bulk of the area.
//!
//! **Reasoning.** A chain block is not arbitrary input. Its layout is fixed:
//! a 16-byte salted nonce, the 18-byte node, then 30 zero bytes. Every byte
//! that is constant at compile time makes some S-box inputs constant, and a
//! constant S-box is no S-box at all.
//!
//! **Decision.** Track which bytes are known through every round and keep
//! only the live S-boxes. 640 become **494**, pinned by a test, so one
//! signature is about 204 × 494 ≈ 100,800 S-box evaluations, and *signatures
//! per second ≈ S-boxes per second ÷ 100,800*.
//!
//! → [`chain_step`], [`haraka`], [`aes_table`]
//!
//! # Chapter 3: A whole chain every clock
//!
//! **Problem.** A chain is three *dependent* steps. Hardware that computes
//! one step and loops back would sit idle while each step travels through
//! its pipeline.
//!
//! **Reasoning.** The 68 chains of a key are independent of each other. If
//! the three steps of a chain are three separate pipelined lanes in series,
//! a new chain can enter every clock while earlier ones are still inside.
//!
//! **Decision.** A *chain engine* is three chain-step lanes in series, each
//! a fully pipelined Haraka-512 step (20 cycles). It finishes one whole chain
//! per clock, all four node positions at once.
//!
//! ```text
//!  secret ──▶ [lane 1] ──▶ [lane 2] ──▶ [lane 3] ──▶ endpoint
//!    │            │            │            │
//!    └────────────┴────────────┴────────────┴──▶ 4 nodes → key cache
//! ```
//!
//! → [`slice_chain`], [`chain_lane`]
//!
//! # Chapter 4: Feeding the chains: the 68-cycle timetable
//!
//! **Problem.** The chain engine wants a new chain secret every clock, so a
//! key's 68 chains take 68 clocks. Around them, the same key needs about 47
//! BLAKE3 compressions: seeds, the XOF that makes the secrets, and the
//! commitment over the 68 endpoints. One BLAKE3 lane finishes a compression
//! per clock but with a 28-cycle latency, and many of these compressions
//! depend on each other.
//!
//! **Reasoning.** If every key's BLAKE3 work happens at the same fixed
//! offsets, the timetable for one key repeats every 68 cycles. Overlapping
//! keys then never collide, as long as no two operations of different keys
//! land on the same cycle *modulo 68*. That is a *modulo schedule*, the
//! classic way compilers pipeline loops.
//!
//! **Decision.** A small solver, run at compile time, places every BLAKE3
//! operation of a key on its own residue mod 68 and respects every data
//! dependency. Up to 16 keys are in flight at once, each in its own
//! *context* (a slot in small RAMs). Result: **one key per 68 cycles per
//! slice**, with the BLAKE3 lane and the chain engine both busy every clock.
//!
//! ```text
//!  cycle mod 68:  0 ......................................... 67
//!  chain engine:  chain 0, chain 1, ...                 chain 67   (key k)
//!  BLAKE3 lane:   XOF of key k+1, commitment of key k−1, seeds of key k+2 ...
//! ```
//!
//! → [`slice_schedule`], [`slice_factory`]
//!
//! # Chapter 5: Keys before messages
//!
//! **Problem.** Messages arrive when they want. Keys come out at a steady
//! rate. Signing must not wait for key generation, and a one-time key must
//! never sign twice.
//!
//! **Reasoning.** Separate the two with a cache. The factory fills it at its
//! own pace; the signer takes one key per message. A key is spent the
//! moment it is admitted to a message, and also on timeout, reset or any
//! uncertain launch. It is never reused.
//!
//! **Decision.** Each slice caches 512 keys (68 chains × 4 nodes each) in
//! dense UltraRAM. The signer turns a message digest into 68 digits, reads
//! one node per chain and streams the 1,642-byte frame.
//!
//! → [`cache_bank`], [`slice_signer`], [`packer`]
//!
//! # Chapter 6: One Ed25519 signature per 128 keys
//!
//! **Problem.** Every 128 keys need a Merkle tree and one Ed25519 signature
//! over its root. The embedded Ed25519 core takes about 22,000 cycles per
//! signature. One at a time, that caps the engine at one batch per 22,000
//! cycles, far below what the slices make.
//!
//! **Reasoning.** *Little's law*: work in flight = throughput × time in
//! system. To finish one certificate every ~895 cycles with a 22,000-cycle
//! latency, about 25 must be in flight.
//!
//! **Decision.** The certificate unit tags each batch and keeps up to 32 in
//! flight, then delivers certificates in order.
//!
//! The batch below is DSig's split in one picture: the hash-based one-time
//! keys are the *foreground* that signs every message; one Ed25519
//! signature per 128 keys is the *background* that vouches for them.
//!
#![doc = concat!("<div style=\"overflow-x:auto\">", include_str!("../docs/images/dsig-batch.svg"), "</div>")]
//!
//! → [`cert_unit`], [`ed25519`], [`certificate`]
//!
//! # Chapter 7: More of everything: slices
//!
//! **Problem.** One slice makes 205 MHz ÷ 68 ≈ 3.0M keys per second. The
//! goal is ten times that.
//!
//! **Reasoning.** Chapters 3–6 made a slice that never idles. The only
//! remaining lever is more of them. Each slice is a complete signer, so
//! slices need nothing from each other except their share of each batch's
//! Merkle tree.
//!
//! **Decision.** The engine builds `SLICES` (2, 4 or 8) copies. RHDL lowers
//! the slice once and instantiates it `SLICES` times. Each slice owns
//! `128 / SLICES` keys of every batch and builds that subtree; the
//! certificate unit joins the subtree roots.
//!
//! ```text
//!                     ┌──────────── slice (× SLICES) ────────────┐
//!  seed, epoch ─────▶ │ factory: BLAKE3 lane + 3 chain lanes      │
//!                     │   68-cycle modulo schedule: 1 key / 68 clk│
//!                     │ key cache: 512 keys in UltraRAM           │
//!                     │ subtree: K leaves → 1 root                │──▶ HBM (frames)
//!  messages (HBM) ──▶ │ signer: digits → nodes → 1,642-byte frame │
//!                     └───────────────▲──────────────┬────────────┘
//!                                     │ certificate  │ subtree root
//!                     ┌───────────────┴──────────────▼────────────┐
//!                     │ cert unit: Merkle top + Ed25519 (≤32 in   │
//!                     │ flight, tagged, in-order delivery)        │
//!                     └────────────────────────────────────────────┘
//! ```
//!
//! → [`slice`](mod@slice), [`slice_merkle`], [`engine`], [`SLICES`]
//!
//! # Chapter 8: Meeting the clock
//!
//! **Problem.** The first routed 2-slice link used 301,037 kernel CLB LUTs
//! but failed timing at 205 MHz by **2.167 ns**.
//!
//! **Reasoning.** The per-hierarchy report pointed at the key caches. Vivado
//! had mapped them to about 136 block RAMs per bank, spread across the die,
//! with unregistered inputs fanning out to all of them.
//!
//! **Decision.** Put the caches in UltraRAM (a `RamStyle` patch in the
//! vendored RHDL lets an RHDL memory ask for it), and register their
//! inputs. That frees block RAM, which the S-box placement can now use
//! (Haraka S-boxes in spare UltraRAM and block RAM instead of LUTs).
//!
//! **Result.** The second link met timing at 205 MHz (setup and hold) with
//! 296,558 kernel CLB LUTs.
//!
//! The climb to four slices at 205 MHz took nine more builds (v4–v13): table
//! rounds, a registered reset, hard per-die floorplans, registered links,
//! kept hierarchy and toggle links. Each is a numbered step with its
//! measurement in [How the speed adds up](#how-the-speed-adds-up).
//!
//! → [`cache_bank`], [`sbox_placement`], [`config`]
//!
//! # Chapter 9: Choosing the chain hash
//!
//! DSig works with any of three chain hashes. Each is a different signature
//! scheme with its own profile name; signatures from one never verify under
//! another. Only chain steps change; everything else stays BLAKE3.
//!
//! | Build variable | Profile | Lane latency |
//! |---|---|---:|
//! | `DSIG_CHAIN=haraka` (default) | `DSIG_FPGA_W4_HARAKA_BLAKE3_V1` | 20 |
//! | `DSIG_CHAIN=blake3` | `DSIG_FPGA_W4_BLAKE3CHAIN_BLAKE3_V1` | 28 |
//! | `DSIG_CHAIN=sha512` | `DSIG_FPGA_W4_SHA512CHAIN_BLAKE3_V1` | 82 |
//!
//! **A lesson from SHA-512.** Its lanes are four times slower, so a key's
//! chain ends leave the engine 248 cycles after they start, more than three
//! 68-cycle periods. Two assumptions broke. Keys stay in flight longer, so
//! the factory needs 32 contexts instead of 16. And the commitment prefix
//! was read from "the current key", which by then is a newer key. The
//! factory now keeps the last few keys' nonces and picks by age. The Haraka
//! hardware is unaffected.
//!
//! → [`chain_lane`], [`slice_factory`]
//!
//! # Chapter 10: Living on a shared chip
//!
//! DSig shares the chip with Ed25519 signing and verification, and both
//! draw on one shared SHA-512 line. A planner models every component's cost
//! and rate; one TUI, shared with the Ed25519 crate, lets you move budgets
//! and see sign/s, verify/s, LUT, DSP and latency change.
//!
//! In the DSig paper's chip, Ed25519 does one signature per 128 DSig
//! signatures, and one verification per DSig verification whose batch root
//! is not already verified: `1 − h` with `h = (b/100) · 127/128`, where `b`
//! is the best-case expectation.
//!
//! → [`config`], `planner` (feature `planner`), `dsig_plan`
//!
//! # Chapter 11: Proving it
//!
//! ## What the card taught us
//!
//! **Problem.** The first card runs of the routed 2-slice kernel never
//! finished. The kernel clock ran (about 205.2M ticks per second), but the
//! counters froze: 6 of 8 batches certified, both key caches full, and the
//! certificate unit's sticky fault set.
//!
//! **Reasoning.** Every block had passed bit-exact simulation, but the
//! engine test signed one batch. With one batch, each slice offers one
//! subtree root. With eight, each slice keeps making keys up to eight
//! batches ahead and offers a root for every batch it finishes, while the
//! certificate unit's root queue holds two. During the Ed25519 key load
//! nothing is popped, so the third root met a full queue and was dropped.
//! The 8-batch simulation reproduces it: the same fault at cycle 16,271.
//!
//! **Decision.** Root credit. The certificate unit reports how many
//! batches' roots it has taken ([`cert_unit::CertOutput::roots_popped`]),
//! and a slice starts a key only while its batch is fewer than
//! [`cert_unit::ROOT_QUEUE`] ahead. The lesson for every test here: run at
//! least as many batches as any queue is deep, and check the fault register
//! every few thousand cycles.
//!
//! ## What is proven
//!
#![doc = include_str!("../docs/validation.md")]
//!
//! ## How the speed adds up
//!
#![doc = include_str!("../docs/how-it-got-fast.md")]
//!
//! The longer design walk-through, with every budget and decision, is
//! [`sustained`].
//!
//! # Chapter 12: Checking signatures: the verifier
//!
//! **Problem.** A signature is only worth what it costs to check, and the
//! comparison paper prices DSig verification next to Ed25519's on the same
//! chip. The planner's verify numbers were a model.
//!
//! **Reasoning.** Checking is the signer's work run backwards and halved:
//! each chain needs only `3 − digit` steps (105 of 204 on average), plus 29
//! BLAKE3 compressions and one Ed25519 check per batch of 128. The same
//! lanes can do it if they never idle on chains that need no step.
//!
//! **Decision.** Verify units of three *recirculating* chain lanes and one
//! BLAKE3 lane shared by 64 records in flight, a certificate cache in front
//! of the Ed25519 project's verify core, and records in, verdict bytes out,
//! in order.
//!
//! **Result.** 35.12 cycles per verification per unit in native
//! simulation, 80,211 LUT per core routed alone at 205 MHz; on the card,
//! three units verify 16,959,195 signatures per second (build v3, finite
//! burst of 1,572,864).
//!
//! → [`verify`] (its page tells the verifier's own story)
//!
//! # Epilogue: your turn
//!
//! ## Using it
//!
//! The whole kernel is one RHDL [`Synchronous`](rhdl::prelude::Synchronous)
//! component, [`engine::Engine`]. Its size and chain hash are chosen at
//! compile time:
//!
//! ```text
//! DSIG_SLICES=2 cargo test --profile sim
//! cargo run --profile sim --bin dsig_engine_export -- NEW_BUNDLE_DIR      # Verilog bundle
//! cargo run --release --bin dsig_plan -- --sweep                          # every build
//! ```
//!
//! The U280 flow (XO packaging, `v++` link at 205 MHz, routed acceptance,
//! card run) is in `fpga/u280/engine/README.md`.
//!
//! ## How to work
//!
//! | Level | Command | Time |
//! |---|---|---|
//! | Leaf blocks, bit-exact vs reference | `DSIG_SLICES=2 DSIG_CHAIN=haraka bash tools/leaf-gate.sh` (inside `tools/dsig-bounded.sh`) | ~25 min |
//! | Sustained throughput | `DSIG_SLICES=2 cargo test --profile sim --test throughput -- --ignored --nocapture` | ~30 min |
//! | Verilog bundle + closure check | `DSIG_SLICES=2 bash tools/engine-bundle-gate.sh NEW_DIR` | ~5 min, 4.6 GB |
//! | Vivado (U280 host) | `tools/wolverine-engine.sh ooc / build / run / report` | hours |
//!
//! RHDL kernels must use literal or const loop bounds and const array
//! indices, keep `Bits` ≤ 128 bits, give a struct at most ~11 synchronous
//! children, and avoid `/` and `%`. These compile under rustc and fail only
//! when lowering. Inside `#[kernel]` bodies, use `//` comments, never `///`.
//! Never run `cargo fmt` over `vendor/` (each snapshot carries a guard).
//!
//! ## Open problems
//!
//! 1. **Continuous throughput.** Every card number is a finite burst from
//!    one cold start; back-to-back runs are not measured.
//! 2. **Past 12M signatures/s.** The next slice count is 8 (24.1M/s), which
//!    needs slices of ~46k LUT instead of ~83k: S-boxes in block RAM and
//!    UltraRAM, BLAKE3 adders in DSPs, a smaller signer.
//! 3. **A fourth verify unit.** Three units (368,713 LUT) verify 16.96M/s
//!    on the card; a fourth needs each unit ~10k LUT smaller (see [`verify`]).
//! 4. **The SHA-512 line above 1 block per clock** (goal 1.75) in 65k LUT
//!    and 20 DSP: see `rhdl_sha512_pipelined`.
//! 5. **More S-boxes per LUT.** BLAKE3 adders in DSPs and T-tables in URAM
//!    are estimates in the planner today.
//!
//! ## Good first contributions
//!
//! Each of these is open today and has a test or a measurement that says
//! when it is done.
//!
//! | Task | Size | What you'll learn | You're done when |
//! |---|---|---|---|
//! | Draw the verify unit (reader, core, writer) as an SVG for `docs/verifier.md` | an hour | how a record flows through the verifier | the diagram matches [`verify::unit`] and renders in `cargo doc` |
//! | Report each verdict class (format, Merkle, chains, certificate) separately in `dsig_verify_host check` | a few hours | the record format and the oracle [`verify::expected_verdict`] | the tampered-record run prints counts per bit that match the oracle |
//! | Price the verifier's shared cluster once per kernel in the planner, not per unit | a few hours | how the planner and TUI turn measurements into plans | `VERIFY_UNIT_IO_LUT` holds only the reader and writer, and the planner tests pass |
//! | Make `verify_core_lowers_to_verilog` fit the bounded runner (≤ 5 GB) | a day | how RHDL lowers a design to Verilog | the test passes under `tools/dsig-bounded.sh` in normal class |
//! | Simulate the verifier with BLAKE3 chains (`DSIG_CHAIN=blake3`) | days | how the chain hash plugs into lanes and rings | `tests/verify_datapath.rs` passes with BLAKE3 records |
//! | Shrink a verify unit by ~10k LUT so four fit under 420k | weeks | where LUTs go in a routed design | a routed 4-unit kernel at or under the cap |
//! | Measure continuous signing: back-to-back bursts without a reset | weeks, needs the card | the card flow and one-time-key safety | a measured rate over consecutive verified bursts, reported apart from the burst rate |
//!
//! ## Where to go next
//!
//! | You want to… | Start here | Then |
//! |---|---|---|
//! | make key generation faster or smaller | [`chain_step`] | [`aes_table`], [`sbox_placement`], [`config`] |
//! | change the chain hash | [`chain_lane`] | [`slice_factory`] (contexts, `PACK_HISTORY`), [`haraka`] |
//! | change the per-key timetable | [`slice_schedule`] | [`slice_factory`] |
//! | change how messages are signed | [`slice_signer`] | [`packer`], [`cache_bank`] |
//! | change batching or certificates | [`cert_unit`] | [`slice_merkle`], [`certificate`], [`ed25519`] |
//! | change the card interface (HBM, registers) | [`engine`] | [`msg_reader`], [`hbm_writer`], [`axi4`] |
//! | run on the card | `fpga/u280/engine/README.md` | [`lease`], `dsig_engine_host` |
//! | check a signature in software | [`reference`](mod@reference) | [`slice_model`] |
//! | check signatures in hardware | [`verify`] | [`verify::datapath`], `dsig_verify_host` |
//! | change the planner or TUI numbers | [`config`] | `planner` (feature `planner`) |
//! | understand a number on this page | [Proving it](#chapter-11-proving-it) | `docs/` |
//!
//! ## Glossary
//!
//! | Term | Meaning |
//! |---|---|
//! | Slice | one complete signer; the engine has `SLICES` of them |
//! | Batch | 128 one-time keys sharing one Merkle root and one Ed25519 certificate |
//! | Chain | one of a key's 68 W-OTS+ hash chains: a secret hashed three times |
//! | Chain step | one compression of a salted chain node by the chain hash |
//! | Context | one in-flight key's slot in the factory's small RAMs |
//! | Modulo schedule | a fixed per-residue timetable repeated every 68 cycles |
//! | Little's law | in flight = throughput × time in system |
//! | Profile | the name of the exact scheme compiled in (chain hash included) |
//! | Frame | one 1,642-byte signature plus its message index, padded to 2 KiB |
//! | Best case `b` | how often a DSig verification finds its batch already verified |
//! | SLR | one of the U280's three dies; crossing between them costs time |
//! | Pblock | a placement region; the platform's per-SLR pblocks pin blocks to a die |
//! | Relay pipe | registers on a valid/ready link so it can cross a die (Carloni) |
//! | Toggle link | a cheaper registered link for rare items: one bit flips per item |
//! | Ceiling | the rate a build reaches if every slice makes one key per 68 clocks |
//! | Verify unit | one HBM reader, one verify core, one verdict writer |
//! | Record | a signature plus its message, the verifier's input (1,664 bytes) |
#![forbid(unsafe_code)]

/// The full design walk-through: budgets, slices, caches and decisions.
#[doc = include_str!("../docs/sustained.md")]
pub mod sustained {}

/// The compiled-in DSig profile (chosen by the `chain-*` feature).
pub use chain_lane::PROFILE;
/// Frozen derivation domain shared by hardware builders and the host oracle.
pub const SEED_DERIVATION_CONTEXT: &str = "DSig FPGA V1 one-time seed allocation";
/// Number of independent message digits, taken from low bits of XOF bytes.
pub const MESSAGE_DIGITS: usize = 64;
/// Number of little-endian base-four complement-checksum digits.
pub const CHECKSUM_DIGITS: usize = 4;
/// Number of independently salted WOTS hash chains.
pub const CHAINS: usize = MESSAGE_DIGITS + CHECKSUM_DIGITS;
/// Number of stored positions, including each secret and its public endpoint.
pub const POSITIONS: usize = 4;
/// Number of bytes per chain node (144 bits).
pub const ELEMENT_BYTES: usize = 18;
/// Number of public keys authenticated by one Ed25519 certificate.
pub const BATCH_KEYS: usize = 128;
/// Host-side byte-oriented chain element.
pub type Element = [u8; ELEMENT_BYTES];
/// Host-side 256-bit digest.
pub type Digest = [u8; 32];
/// Host-side 128-bit salt; message nonces stay signer-private until admission.
pub type Nonce = [u8; 16];
/// Number of siblings in an inclusion proof for a fixed-size batch.
pub const MERKLE_HEIGHT: usize = 7;

// ---------------------------------------------------------------- area knob
//
// How many slices the engine builds is the main area/throughput knob. It is
// chosen at compile time with the DSIG_SLICES build variable:
//
//   DSIG_SLICES=2 cargo build   # 127,502 LUT per slice (routed)
//   DSIG_SLICES=4 cargo build
//   cargo build                 # 8 slices (default)
//
// Every slice still signs its share of each 128-key batch: with fewer slices
// each one owns more keys per batch, its subtree grows by one level per
// halving, and the certificate unit's Merkle top shrinks by the same level.
// The inclusion proof is always MERKLE_HEIGHT = 7 siblings.
//
//   SLICES  KEYS_PER_SLICE  SUBTREE_LEVELS  TOP_LEVELS  ceiling @205 MHz
//      2          64              6              1          6.0M sig/s
//      4          32              5              2         12.1M sig/s
//      8          16              4              3         24.1M sig/s

// `SLICES` comes from the `DSIG_SLICES` build variable (2, 4 or 8; default
// 8), checked by `build.rs`. It is not a Cargo feature because exactly one
// count must hold, and Cargo features must be safe to enable together.
include!(concat!(env!("OUT_DIR"), "/engine_shape.rs"));

/// Keys of each batch made, cached and signed by one slice.
pub const KEYS_PER_SLICE: usize = BATCH_KEYS / SLICES;
/// Merkle levels inside a slice's subtree (`log2 KEYS_PER_SLICE`).
pub const SUBTREE_LEVELS: usize = KEYS_PER_SLICE.trailing_zeros() as usize;
/// Merkle levels joined by the certificate unit (`log2 SLICES`).
pub const TOP_LEVELS: usize = SLICES.trailing_zeros() as usize;

const _: () = assert!(SLICES * KEYS_PER_SLICE == BATCH_KEYS);
const _: () = assert!(SUBTREE_LEVELS + TOP_LEVELS == MERKLE_HEIGHT);
/// Width of a key's number within its slice's batch share (`j`) and of a
/// Merkle node's index within its level: 6 bits in every batch-engine
/// build (up to 64 keys per slice), more only when a slice makes larger
/// batch shares. Kept at 6 rather than shrunk so the measured builds'
/// hardware does not change.
pub const KEY_BITS: usize = if SUBTREE_LEVELS > 6 { SUBTREE_LEVELS } else { 6 };
/// A key's number within its slice's batch share ([`KEY_BITS`] wide).
pub type KeyIndex = rhdl::prelude::Bits<KEY_BITS>;
/// `0` as a [`KeyIndex`].
pub const KEY_ZERO: KeyIndex = rhdl::prelude::bits(0);
/// `1` as a [`KeyIndex`].
pub const KEY_ONE: KeyIndex = rhdl::prelude::bits(1);
/// Merkle levels that have a node base (`0..=KEY_BITS`).
pub const NODE_LEVELS: usize = KEY_BITS + 1;
/// Width of a node slot within one ring entry (`2·KEYS_PER_SLICE` slots).
pub const NODE_SLOT_BITS: usize = KEY_BITS + 1;

const _: () = assert!(KEYS_PER_SLICE <= 1 << KEY_BITS, "key-in-slice numbers fit KEY_BITS");


pub mod aes_table;
pub mod axi4;
pub mod blake3_core;
pub mod cache_bank;
pub mod cert_unit;
pub mod certificate;
pub mod chain_lane;
pub mod chain_step;
pub mod config;
pub mod ed25519;
pub mod engine;
pub mod haraka;
pub mod hbm_writer;
pub mod lease;
pub mod msg_reader;
pub mod packer;
#[cfg(feature = "planner")]
pub mod planner;
pub mod reference;
pub mod relay;
pub mod slice;
pub mod slice_chain;
pub mod slice_factory;
pub mod slice_merkle;
pub mod slice_model;
pub mod slice_schedule;
pub mod sbox_placement;
pub mod slice_signer;
pub mod verify;
#[cfg(feature = "ubft")]
#[doc = include_str!("../docs/ubft.md")]
pub mod ubft;