ed25519-simd
ed25519-simd is a verification-only Ed25519 crate focused on high-throughput
batch verification. It verifies signatures and reports the result for each input
element; it does not provide signing APIs or handle private key material.
The implementation is designed to be acceptance-compatible with
solana-ed25519. The tests include differential checks against
solana-ed25519 for both supported verification policies and for edge cases
such as small-order points, non-canonical encodings, and scalar-boundary
signatures.
Requirements
This crate requires x86_64 with AVX-512 (F, BW, DQ, IFMA) and has no scalar
fallback. All verification — including single-signature checks and partial
batches — runs through the AVX-512 IFMA SIMD path. The crate fails at compile
time unless the required target features are enabled.
Build with the target CPU enabled, e.g.:
RUSTFLAGS="-C target-cpu=native"
For the throughput reported below, enable whole-program LTO and one codegen unit in the consuming workspace. Cargo does not apply release-profile settings from dependency manifests:
[]
= true
= 1
Without those settings, verification remains correct but leaves more large SIMD helpers across call boundaries and is typically a few percent slower.
Doc tests compile through rustdoc, so pass the same CPU target there too:
RUSTFLAGS="-C target-cpu=native" RUSTDOCFLAGS="-C target-cpu=native"
AVX-512 IFMA is available on Intel Ice Lake and later, and on AMD Zen 4 and later.
Because the SIMD path is selected at compile time, AVX-512 F, BW, DQ, and IFMA
support, including OS support for AVX-512 register state, is a deployment
prerequisite. A binary built with -C target-cpu=native must run on the same
CPU it was built for, or one that is at least as capable. Alternatively, use
explicit -C target-feature=+avx512f,+avx512bw,+avx512dq,+avx512ifma flags that match
every deployment host.
The crate performs no runtime CPU-feature detection and has no fallback path.
The target-feature flags apply to the entire binary, not just this crate, so
the compiler may emit AVX-512 instructions in application, dependency, or
standard-library code before any ed25519-simd API is called. Running the
binary on a host without the required CPU and OS support may therefore
terminate with an illegal-instruction fault (SIGILL) at any point.
Scope
This crate only verifies signatures. Signing is intentionally out of scope: private key material raises a much stricter implementation bar, especially around side channels that can leak secret scalar bits through timing, memory access, or microarchitectural behavior. Verification only handles public inputs, which makes the crate a narrower and more auditable component.
Verification Policies
The verifier supports two compile-time policy types:
Zip215Policy(or theZip215Verifieralias) is the default. It performs the ZIP-215 cofactored check and accepts non-canonical point encodings according to theverify_zebra/ batch verifier behavior.DalekPolicy(or theDalekVerifieralias) performs the strict Dalek-style check:Rmust be canonical, and neither the public key norRmay be a small-order point.
Both policies reject non-canonical S scalars (S >= L).
The Dalek policy name means "match solana-ed25519's verify_dalek entry
point", not "match the Dalek row in ed25519-speccheck". Speccheck's Dalek row
describes the acceptance set of the Dalek implementation it tested, which
accepts some small-order and non-canonical edge cases. solana-ed25519's
verify_dalek behavior is stricter for this crate's compatibility target: it
requires canonical R and rejects small-order public keys and R points. The
speccheck fixtures in this repository therefore use speccheck's fixed
expectations for ZIP-215, but use solana-ed25519 itself as the oracle for the
Dalek policy.
Selecting the policy in the verifier's type lets a normal application contain
only the chosen decoding, scoring, and deferral path. If an application truly
needs to select the policy at runtime, RuntimeVerifier is an explicit wrapper
that includes both monomorphized implementations.
Batch Verification
All verification goes through a Verifier, which is constructed once and reused.
It holds the precomputed base-point table and a pluggable, statically-selected
key cache, so construction is not free — build it once and call verify_batch
repeatedly:
use ;
# let public_key = ;
# let signature = ;
# let message: & = b"hello";
let mut verifier = new;
let inputs = ;
let mut out = vec!;
verifier.verify_batch;
// out[0] is true iff `signature` is valid for (public_key, message).
Each output entry corresponds to the input at the same index, so callers can see
which signatures passed or failed. out must be the same length as inputs;
verify_batch panics otherwise. Zip215Verifier::new() uses no retained-key
cache; DalekVerifier::new() selects the other policy at compile time. See
Verification Policies and Key
Caching for the cache-selecting constructor.
Key Caching
Verification repeatedly needs a decoded public key and a precomputed
variable-base multiplication table. Zip215Verifier::new() and
DalekVerifier::new() use NullKeyCache, so decoded keys are not retained
across batches. NullKeyCache is the recommended default for most
workloads: it keeps cold or mostly-distinct-key workloads from paying for
cache bookkeeping they do not use, and it needs no assumptions about the
shape of the workload to be safe.
Only reach for HotKeyCache if you have actual knowledge of your key
distribution — specifically, that a small set of keys repeats often enough
across batches to be worth retaining. Caching a hot set you don't actually
have wastes memory and bookkeeping for no benefit. The Hot Key
Repeats benchmark below quantifies the win on a workload
that does repeat a small key set; measure your own workload before relying on
it, since the win shrinks or disappears as the hot set gets larger or less
repetitive:
HotKeyCache::with_capacity(n)is the only constructor: the bound is mandatory. Public keys are attacker-supplied and each retained one costs about 2.8 KB, nearly all of it the 17-entry multiplication table that makes a hit worthwhile, so an unbounded cache would be a memory-exhaustion vector. Requiring a bound also forces the question that decides whether this cache helps at all — how many keys actually repeat. If you can't answer it, useNullKeyCache.- Keep the bound tight.
with_capacityreserves allocator capacity for the whole bound, but the backing pages generally become resident as entries are written. A full cache costs aboutn * 2.8 KB: 11 MB at 4096 and 2.8 GB at 1,000,000. Sizenfrom measured key reuse. - Eviction is exact least-recently-used, and both lookup and eviction are O(1), so a caller feeding the verifier nothing but distinct keys cannot amplify eviction cost.
HotKeyCache::set_capacity(n)re-bounds an existing cache, evicting immediately down to the new bound and requesting smaller backing allocations. The allocator may retain freed memory, so process RSS is not guaranteed to fall.nis clamped to at least one.- Successful key decodes are retained after verification, so reuse the same verifier across batches when the key distribution is hot.
The verifier keeps any per-chunk decoded tables in local scratch while a chunk
is being verified, even with NullKeyCache:
use ;
let mut verifier = with_cache;
SIMD Path
The crate batches eight signatures per AVX-512 IFMA chunk. There is no scalar fallback: single verifications and ragged batch tails are processed as padded SIMD chunks, and required target features are enforced by the root compile-time gate (see Requirements).
Internally, batch data is transposed from eight independent values into limb-major vectors. Logical register 0 contains limb 0 from batch items 0–7 in its eight SIMD lanes, register 1 contains limb 1 from the same items, and so on:
This structure-of-arrays layout lets one AVX-512 instruction operate on the
same limb of all eight batch items. The diagram uses an eight-limb value; types
with fewer limbs use the same layout with fewer vectors. The register numbers
are logical array positions—the compiler chooses the physical zmm registers.
Benchmark Snapshot
The following numbers are Criterion estimates in microseconds per signature for
distinct-key batches. The ed25519-simd rows use NullKeyCache, so decoded keys
are not retained across batches.
The ed25519-simd and solana-ed25519 0.2.4 rows were refreshed independently
on an AMD EPYC 9555P with rustc 1.95.0, pinned to CPU 4. The other comparison
rows are retained from the previous full comparison run and are therefore not
from the same execution. Criterion used its default 3-second warm-up, 5-second
measurement, and 100 samples.
The comparison benches live in the benches-compare workspace member. Each
policy/cache combination used below has its own self-only executable
(zip215_cold_self, dalek_cold_self, zip215_hot, and dalek_hot) so each
executable registers and instantiates only one benchmark configuration. The
zip215_cold and dalek_cold executables retain the full comparison matrix.
These commands refresh only this crate's null-cache rows used below:
for
do
for
do
done
done
Message length 1:
| Backend | 8 | 16 | 32 | 64 |
|---|---|---|---|---|
| ed25519-simd Zip215 null-cache | 3.95 | 3.95 | 3.95 | 3.95 |
| ed25519-simd Dalek null-cache | 3.88 | 3.88 | 3.88 | 3.88 |
| solana-ed25519 Zip215 batch[^batch-api] | 13.22 | 12.21 | 11.74 | 11.52 |
| solana-ed25519 Dalek loop | 23.63 | 23.58 | 23.60 | 23.59 |
| ed25519-dalek batch[^batch-api] | 14.30 | 13.21 | 12.68 | 12.44 |
| ed25519-dalek loop | 20.24 | 20.21 | 20.20 | 20.22 |
| aws-lc-rs parsed loop | 22.59 | 22.61 | 22.62 | 22.59 |
| ring loop | 30.67 | 30.60 | 30.59 | 31.58 |
| sodiumoxide loop | 35.56 | 35.49 | 35.48 | 35.61 |
| openssl loop | 59.35 | 59.34 | 59.17 | 59.38 |
Message length 1024:
| Backend | 8 | 16 | 32 | 64 |
|---|---|---|---|---|
| ed25519-simd Zip215 null-cache | 4.21 | 4.21 | 4.21 | 4.21 |
| ed25519-simd Dalek null-cache | 4.15 | 4.16 | 4.16 | 4.16 |
| solana-ed25519 Zip215 batch[^batch-api] | 14.28 | 13.23 | 12.73 | 12.53 |
| solana-ed25519 Dalek loop | 24.57 | 24.63 | 24.64 | 24.66 |
| ed25519-dalek batch[^batch-api] | 15.33 | 14.26 | 13.67 | 13.40 |
| ed25519-dalek loop | 21.25 | 21.23 | 21.21 | 21.22 |
| aws-lc-rs parsed loop | 23.73 | 23.72 | 23.73 | 23.72 |
| ring loop | 31.76 | 31.75 | 31.71 | 32.67 |
| sodiumoxide loop | 36.80 | 36.78 | 36.81 | 36.82 |
| openssl loop | 60.02 | 60.21 | 60.00 | 60.02 |
Mixed message lengths:
| Backend | 8 | 16 | 32 | 64 |
|---|---|---|---|---|
| ed25519-simd Zip215 null-cache | 4.08 | 4.03 | 4.04 | 4.01 |
| ed25519-simd Dalek null-cache | 4.01 | 3.97 | 3.97 | 3.95 |
| solana-ed25519 Zip215 batch[^batch-api] | 13.42 | 12.38 | 11.93 | 11.71 |
| solana-ed25519 Dalek loop | 23.69 | 23.76 | 23.77 | 23.76 |
| ed25519-dalek batch[^batch-api] | 14.39 | 13.40 | 12.84 | 12.60 |
| ed25519-dalek loop | 20.36 | 20.35 | 20.37 | 20.38 |
| aws-lc-rs parsed loop | 22.79 | 22.80 | 22.77 | 22.78 |
| ring loop | 30.80 | 30.79 | 30.75 | 31.73 |
| sodiumoxide loop | 35.68 | 35.66 | 35.71 | 35.77 |
| openssl loop | 59.52 | 59.28 | 59.56 | 59.56 |
[^batch-api]: The batch APIs for solana-ed25519 and ed25519-dalek return a
single pass/fail result for the whole batch. They do not identify exactly
which signatures in the batch were invalid.
Hot Key Repeats
To rerun only this crate's hot-key cases:
for
do
done
This scenario cycles through 4 distinct keys to fill each batch and reuses
the same Verifier across benchmark iterations. The cold binary supplies the
NullKeyCache row; in the hot binary, HotKeyCache is warm (all hits) after
the first iteration. Together they quantify the HotKeyCache win referenced
in Key Caching for a workload that actually repeats a small key
set:
| Backend | 8 | 16 | 32 | 64 |
|---|---|---|---|---|
| ed25519-simd Zip215 null-cache | 3.94 | 3.94 | 3.94 | 3.94 |
| ed25519-simd Zip215 hot-key cache (warm) | 3.69 | 3.53 | 3.53 | 3.53 |
| ed25519-simd Dalek null-cache | 3.90 | 3.90 | 3.90 | 3.90 |
| ed25519-simd Dalek hot-key cache (warm) | 3.68 | 3.49 | 3.39 | 3.34 |
Compatibility Target
Compatibility with solana-ed25519 is a design constraint, not just a
benchmark target. The benchmark compares throughput against solana-ed25519,
while the tests compare accept/reject decisions against the matching verifier
entry points.