Crate rhdl_ed25519_docs 

Dalek Ed25519 on RHDL

This is the contributor guide for a synthesizable Ed25519 implementation that matches the pinned Dalek semantics while keeping hashing, scalar arithmetic, point arithmetic, signing, and strict verification in hardware.

The workspace serves two related designs:

1. The compatibility core implements public-key derivation, cold and cached-key signing, strict verification, multipart byte streams, and key clearing. It is the semantic reference for the hardware implementation.
2. The fixed-64 fast path is an optimization track for saturated signing of 64-byte messages on an AMD Alveo U280. It uses a DSP-heavy field pipeline and a fixed-base table. It is not yet a replacement for the compatibility core.

The most important rule for reading this documentation is that measured, modeled, and target results are different things. The compatibility core has end-to-end simulation evidence. The fast path currently has primitive-level RTL and out-of-context synthesis evidence. The 200,000 signatures/second objective remains an integration and hardware acceptance target until a routed U280 image retires and validates that workload.

Start here

• Read architecture for the complete system and signing/verification flows.
• Read code_map before choosing a crate to edit.
• Read interfaces before changing ready/valid behavior or message framing.
• Read arithmetic before changing limb widths, bounds, reduction, or point formulas.
• Read control_and_dataflow before changing the top-level state machine.
• Read memory_and_security before changing a table address, cache, or secret-dependent control signal.
• Read fast_path for the throughput architecture and multi-comb tradeoffs.
• Read verification before claiming compatibility or performance.
• Read fpga_and_benchmarks for U280 synthesis and benchmark acceptance.
• Read contributing for a safe first change and the required commands.

What “hardware Ed25519” means here

The host supplies a command, a 32-byte seed where required, and message bytes. It does not supply a prehash, an expanded secret, a reduced nonce, or an intermediate point. SHA-512 padding, digest processing, clamping, reduction, scalar multiplication, point encoding, and verification all happen inside the RTL data path.

For long or multipart messages, the transport may replay requested bytes. A 4 KiB on-chip cache avoids replaying the common prefix; replay is a transport operation, not host-side cryptographic preprocessing.

Pinned semantic sources

The workspace vendors these source snapshots:

Project	Commit	Role
curve25519-dalek / ed25519-dalek	4cf8db2369786037b6812704a177029c04049d87	semantic oracle and public Rust traits
RHDL	c99d5cc53269a247bbc675d0fbd766991d409f56	synchronous Rust-to-RTL framework

Dalek is built with default-features = false; the compatibility design does not silently acquire Dalek’s large precomputed-tables feature.

A tiny software-oracle example

The model crate is the quickest way to understand the intended byte-level semantics before working on RTL:

use rhdl_ed25519_model::{public_from_secret, sign, verify_strict};

let seed = [7_u8; 32];
let message = b"a hardware-visible message";
let public_key = public_from_secret(seed);
let signature = sign(seed, message);
verify_strict(public_key, message, signature).unwrap();

The model is an oracle, not part of the synthesized core. See [rhdl_ed25519_model] for vector helpers and strict-verification wrappers.

Non-goals

This workspace is scoped to Ed25519 and the Curve25519 arithmetic Ed25519 requires. It is not an X25519 or Ristretto accelerator. It also does not treat cycle-accurate simulation, out-of-context synthesis, place-and-route, and a hardware benchmark as interchangeable evidence.

Modules

architecture

Architecture

arithmetic

Arithmetic backends

code_map

Code map

contributing

Contributing

control_and_dataflow

Control and dataflow

fast_path

Fixed-64 high-throughput path

fpga_and_benchmarks

FPGA build and benchmarking

interfaces

Interfaces and protocol

memory_and_security

Memory, traffic, and security

verification

Verification and evidence