Crate rhdl_ed25519_fast_core

Expand description

§RHDL Ed25519 Fast Core

rhdl_ed25519_fast_core is one Rust crate containing a complete RHDL implementation of cached-key Ed25519 signing and strict verification for exactly 64-byte messages. Rust/RHDL is the only authored hardware source. Verilog is generated output and is never hand maintained.

§Building for Wolverine’s U280

This earlier core is a reusable hardware component. Build its Rust library with cargo build --locked -p rhdl_ed25519_fast_core from the workspace root. That command does not generate a standalone XRT .xclbin.

For the maintained Ed25519 card exporter and Wolverine link script, follow the scalable crate’s build instructions in rustdoc (crates/ed25519/src/lib.rs in the repository). That flow builds the scalable card kernel, not an image of Fast64Core. Deploying this core itself requires integrating its RHDL interface into a card kernel, exporting the RTL, then packaging and linking for the U280 with Vitis 2023.2.

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.

§Start Here

New to signatures or FPGAs? Open the visual guide. It follows one message through signing and verification, maps each step to Rust code, overlays the pipeline stages, and explains the resource budget. Read it before the API reference; no cryptography or FPGA background is needed. The Markdown source is docs/visual-guide.md; its diagrams are embedded in Rustdoc, work offline, and need no JavaScript or external image service.

The public hardware boundary is Fast64Core, with typed input and output bundles Fast64CoreIn and Fast64CoreOut. Start with those three types; the remaining public modules document the arithmetic stages for developers who need to tune or verify the implementation.

§What The Core Does

Expands and caches one 32-byte Ed25519 seed entirely in hardware.
Derives and exposes the matching public key.
Signs fixed 64-byte messages with RFC 8032 Ed25519.
Strictly verifies fixed 64-byte Ed25519 signatures.
Hashes with SHA-512 in hardware; the host never prehashes.
Keeps messages, scalar state, point state, and tables on chip.
Preserves an opaque 16-bit tag from every accepted request to its result.
Runs signing and verification concurrently behind one result interface.
Explicitly clears cached secret state when clear_key is asserted.

The fixed message size is intentional. One message fits in one 512-bit AXI beat, so neither signing nor verification needs external message replay, DRAM/HBM scratch space, or a host-side cryptographic operation.

§Request Protocol

All words are little endian. A request transfers on a rising edge when its valid input and matching ready output are both high.

Assert load_key_valid with key_seed while load_key_ready is high.
Wait for key_loaded; cached_public_key is then valid.
Submit signs with sign_valid && sign_ready and verifies with verify_valid && verify_ready. The two channels are independent.
Observe each one-cycle result.valid pulse. result.is_verify selects the result interpretation, and result.tag identifies the request.
Stop submitting signs and wait for all accepted signs and key expansion to finish before asserting clear_key. Keep request-valid inputs low during clear. This invalidates and clears the cached signing key; it is not a claim that every intermediate datapath register is erased.

Inputs must remain stable for the transfer edge. There is no output backpressure: the internal arbiter absorbs coincident signing and verification completions and retires one tagged result per cycle. internal_error is sticky and indicates an overflow or violated internal scheduling invariant.

Strict-verification error codes are exported by verify:

Code	Meaning
0	Signature accepted
1	Noncanonical or invalid public-key encoding
2	Noncanonical or invalid signature `R` encoding
3	Small-order public key
4	Small-order signature `R`
5	Noncanonical signature scalar `S`
6	Verification equation failure

§Datapath

See the annotated flowchart, pipeline overlay, and conceptual FPGA map.

The main parallelism is structural rather than cosmetic:

sha512_parallel provides four-lane banks; parallel combines two for signing.
field_parallel maps radix-2^51 multiplication to registered 26 x 17 partial products intended for DSP inference.
multicomb overlaps 24 fixed-base scalar-multiplication contexts.
point_decode and variable_base each overlap 20 contexts.
scalar_parallel uses spatial radix-2^16 reduction and multiply-add pipelines.
sign owns 128 request contexts; verify owns 64, with messages in inferred BRAM.

Secret values never select a table address or shorten a formula sequence. Variable-base multiplication always performs one doubling and one addition for every scalar bit. The signed multi-comb table is scanned at constant addresses.

§Source Map

Module	Change it when…
`core`	changing the black-box composition or top-level routing
`protocol`	changing the stable external ABI
`sign`	changing key expansion or the signing scheduler
`verify`	changing strict checks or the verification scheduler
`sha512_parallel`	changing SHA-512 compression parallelism
`field_parallel`	changing field representation or DSP mapping
`scalar_parallel`	changing scalar reduction or multiply-add
`multicomb`	changing fixed-base scalar multiplication
`multicomb_table`	changing constant-pattern basepoint lookup
`point_decode`	changing compressed Edwards-Y decoding
`point_compress`	changing projective-point compression
`variable_base`	changing variable-base scalar multiplication
`equation`	changing the final projective verification equation
`result_arbiter`	changing concurrent completion retirement
`parallel`	changing replicated signing stages and completion credits
`simulation`	running long native simulations without waveform allocation
`optimization`	learning the optimization and measurement workflow
`papers`	finding primary papers and suggested experiments
`export`	changing generated-netlist packaging only

assets/ contains checked fixed-base table initialization. vendor/ contains the pinned RHDL and Dalek source snapshots and is not part of this package’s authored implementation. Cargo metadata reports exactly one workspace package.

§Developer Workflow

Run the bounded local gate from the repository root:

bash tools/bounded.sh bash tools/test_all.sh

For a quick edit loop:

cargo fmt --package rhdl_ed25519_fast_core
bash tools/bounded.sh cargo check --all-targets --locked -j1
bash tools/bounded.sh cargo test --profile sim --lib --locked -j1 -- --test-threads=1

Generate the single implementation netlist:

bash tools/bounded.sh cargo run --locked -j1 --bin export_fast_core_rhdl

This creates reports/generated/fast64_core_rhdl.v. Do not edit that file. Every hardware change starts in src/, then regenerates and revalidates the netlist. The test profile intentionally uses one build and test job to avoid large concurrent Rust compiler memory spikes.

Rustdoc is the primary developer reference:

bash tools/bounded.sh env RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --locked --all-features -j1

Open target/doc/rhdl_ed25519_fast_core/visual_guide/index.html for the illustrated walkthrough, or target/doc/rhdl_ed25519_fast_core/index.html for the crate index. The bounded command uses one Cargo job, at most 6 GiB RAM, no swap, and a 20-minute ceiling. It refuses to overlap another cooperating FPGA build.

Read architecture before changing pipeline depth or context counts. Validation evidence and the exact distinction between simulation, synthesis, routed timing, and on-card measurement live in validation.

§Performance Contract

The current optimization target on an AMD Alveo U280 is 2,000,000 cached signatures/s and at least 200,000 strict verifications/s, while staying below 260,000 LUTs, 520,000 registers, and 9,000 DSPs. The historical handwritten design measured 1.014M signatures/s and 214.6k verifications/s; those figures are a comparison baseline, not evidence for this generated RHDL netlist.

The 2026-10-03 native run matched all 384 Dalek signatures and measured a backlogged 90.984375 cycles/sign sample. That projects to 2.253M/s at an assumed 205 MHz; the minimum clock for 2M/s is about 181.97 MHz. This is not an on-card result. See reports/bench/README.md for raw edges and the conservative warmup/drain calculation. Register packing and full-core fit are still open; the local Yosys leaf flow does not establish the FF cap.

Native differential simulation proves the cryptographic behavior of the new RHDL implementation. A generated-netlist U280 synthesis, route, and on-card run are required before claiming that the RHDL implementation meets the physical performance contract. See the current status in validation.

§Where this crate sits in rhdl_signatures

This was the project’s first Ed25519 core. Its successor, the LUT/DSP-scalable signer and known-key verifier, is rhdl_ed25519_scalable_core in crates/ed25519, with the chip planner (cargo tuner) at the workspace root. This crate stays for what only it has: the strict verifier for any public key (verify::StrictVerifyCore, no key slots), the parallel-datapath signer, and its evidence (reports/).

It is a workspace member but not a default one, so a plain cargo build skips it. Build it with cargo build -p rhdl_ed25519_fast_core.

Its old copy of the scalable signer (src/scalable, with ed25519_plan, scalable_tuner, export_scalable and docs/scalable.md) was removed when the crate moved here (2026-10-20). The live crate replaces all of it, and DSig’s certificate signer is now Ed25519SignCoreSmall there, an RHDL child component rather than a black box.
ScalableFast64Core (the Fast64Core ports with the scalable signer) moved to scalable_fast64 behind the scalable feature. It now builds on the live crate.
The ten generated files over 1 MB in reports/generated and reports/mapping (Verilog exports, Yosys JSON and logs) were not copied. They are regenerable, and their hashes are in each directory’s SHA256SUMS.

§Resource Explorer And Learning Path

Run cargo build --features tuner --bin resource_tuner -j1 under tools/bounded.sh, then launch target/debug/resource_tuner for LUT/DSP sliders and source-bound measurement feedback. It saves synthesis plans; it does not launch expensive jobs automatically. LUT/FF estimates remain unknown until measured. Read optimization first, then papers.

The default wide-sign topology is the throughput experiment. Use --no-default-features to compare the compact topology. Both are entirely RHDL, in this one crate, and retain the same external interface.

Re-exports§

pub use core::Fast64Core;
pub use protocol::CoreResult;
pub use protocol::Fast64CoreIn;
pub use protocol::Fast64CoreOut;
pub use protocol::SignRequest;
pub use protocol::VerifyRequest;
pub use protocol::Words512;
pub use scalar::ScalarWords;

Modules§

architecture: Detailed hardware boundaries, scheduling, representation, and integration.
core: Public sign-and-verify black box.
equation: Projective Ed25519 verification equation.
export: Deterministic generated-HDL export.
field_parallel: Fully pipelined arithmetic modulo 2^255 - 19.
multicomb: Twenty-four-context, signed multi-comb Ed25519 fixed-base multiplication.
multicomb_table: Constant-pattern multi-comb lookup backed entirely by inferred BRAM.
optimization: Beginner-oriented optimization workflow, resource budgeting, and experiments.
papers: Curated primary-source reading library with implementation-oriented notes.
parallel: Credit-bounded replication of the signing bottlenecks.
point_compress: Parallel pair compression for extended Edwards points.
point_decode: Constant-pattern compressed Edwards-point decoding.
protocol: Stable typed protocol for the fixed-64 signing and verification core.
result_arbiter: Lossless retirement arbitration for signing and verification results.
scalar: Minimal scalar representation and primitives used by the fast backend.
scalar_parallel: Initiation-interval-one scalar arithmetic for Ed25519.
sha512_parallel: Four-lane, three-phase SHA-512 compression fabric.
sign: Cached-key, fixed-64-byte Ed25519 signing pipeline.
simulation: Host-only, constant-memory cycle simulation without waveform recording.
validation: Evidence ledger separating simulation, mapping, timing, and hardware claims.
variable_base: Constant-pattern variable-base scalar multiplication.
verify: High-throughput strict Ed25519 verification for 64-byte messages.
visual_guide: Illustrated introduction to Ed25519, the parallel datapath, and FPGA resources.

Constants§

MESSAGE_BITS: Fixed number of bits in the specialized message path.
MESSAGE_BYTES: Fixed number of bytes in the specialized message path.
TAG_BITS: Default public tag width retained by the black-box protocol.