Skip to main content

Crate ed25519_simd

Crate ed25519_simd 

Source
Expand description

§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" cargo build --release

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:

[profile.release]
lto = true
codegen-units = 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" cargo test --doc

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 the Zip215Verifier alias) is the default. It performs the ZIP-215 cofactored check and accepts non-canonical point encodings according to the verify_zebra / batch verifier behavior.
  • DalekPolicy (or the DalekVerifier alias) performs the strict Dalek-style check: R must be canonical, and neither the public key nor R may 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 ed25519_simd::{VerifyInput, Zip215Verifier};

let mut verifier = Zip215Verifier::new();

let inputs = [VerifyInput {
    public_key,
    signature,
    message,
}];

let mut out = vec![false; inputs.len()];
verifier.verify_batch(&inputs, &mut out);
// 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, use NullKeyCache.
  • Keep the bound tight. with_capacity reserves allocator capacity for the whole bound, but the backing pages generally become resident as entries are written. A full cache costs about n * 2.8 KB: 11 MB at 4096 and 2.8 GB at 1,000,000. Size n from 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. n is 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 ed25519_simd::{HotKeyCache, Zip215Verifier};

let mut verifier = Zip215Verifier::with_cache(HotKeyCache::with_capacity(256));

§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:

Eight batch values transposed into limb-major AVX-512 SIMD registers

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:

cd benches-compare
for bench in zip215_cold_self dalek_cold_self
do
  for filter in \
    'distinct_keys/msg_len_1/ed25519_simd' \
    'distinct_keys/msg_len_1024/ed25519_simd' \
    'distinct_keys/msg_len_mixed/ed25519_simd'
  do
    taskset -c 4 env \
      RUSTFLAGS="-C target-cpu=native -C target-feature=+avx512f,+avx512bw,+avx512dq,+avx512ifma" \
      cargo bench --bench "$bench" -- \
        "$filter" --noplot --discard-baseline
  done
done

Message length 1:

Backend8163264
ed25519-simd Zip215 null-cache3.953.953.953.95
ed25519-simd Dalek null-cache3.883.883.883.88
solana-ed25519 Zip215 batch113.2212.2111.7411.52
solana-ed25519 Dalek loop23.6323.5823.6023.59
ed25519-dalek batch114.3013.2112.6812.44
ed25519-dalek loop20.2420.2120.2020.22
aws-lc-rs parsed loop22.5922.6122.6222.59
ring loop30.6730.6030.5931.58
sodiumoxide loop35.5635.4935.4835.61
openssl loop59.3559.3459.1759.38

Message length 1024:

Backend8163264
ed25519-simd Zip215 null-cache4.214.214.214.21
ed25519-simd Dalek null-cache4.154.164.164.16
solana-ed25519 Zip215 batch114.2813.2312.7312.53
solana-ed25519 Dalek loop24.5724.6324.6424.66
ed25519-dalek batch115.3314.2613.6713.40
ed25519-dalek loop21.2521.2321.2121.22
aws-lc-rs parsed loop23.7323.7223.7323.72
ring loop31.7631.7531.7132.67
sodiumoxide loop36.8036.7836.8136.82
openssl loop60.0260.2160.0060.02

Mixed message lengths:

Backend8163264
ed25519-simd Zip215 null-cache4.084.034.044.01
ed25519-simd Dalek null-cache4.013.973.973.95
solana-ed25519 Zip215 batch113.4212.3811.9311.71
solana-ed25519 Dalek loop23.6923.7623.7723.76
ed25519-dalek batch114.3913.4012.8412.60
ed25519-dalek loop20.3620.3520.3720.38
aws-lc-rs parsed loop22.7922.8022.7722.78
ring loop30.8030.7930.7531.73
sodiumoxide loop35.6835.6635.7135.77
openssl loop59.5259.2859.5659.56

§Hot Key Repeats

To rerun only this crate’s hot-key cases:

cd benches-compare
for bench in zip215_cold_self zip215_hot dalek_cold_self dalek_hot
do
  taskset -c 4 env \
    RUSTFLAGS="-C target-cpu=native -C target-feature=+avx512f,+avx512bw,+avx512dq,+avx512ifma" \
    cargo bench --bench "$bench" -- \
      'hot_keys/distinct_4/ed25519_simd' --noplot --discard-baseline
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:

Backend8163264
ed25519-simd Zip215 null-cache3.943.943.943.94
ed25519-simd Zip215 hot-key cache (warm)3.693.533.533.53
ed25519-simd Dalek null-cache3.903.903.903.90
ed25519-simd Dalek hot-key cache (warm)3.683.493.393.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.


  1. 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. ↩ 1 2 3 4 5 6

Structs§

CachedPublicKey
A decoded public key and its precomputed multiplication table.
DalekPolicy
Dalek-compatible verification policy.
HotKeyCache
A bounded LRU KeyCache for decoded keys.
NullKeyCache
A KeyCache that retains no decoded keys.
Verifier
Batch Ed25519 verifier for a compile-time VerificationPolicy and KeyCache. Reuse one across verify_batch calls.
VerifyInput
One public key, signature, and message to verify.
Zip215Policy
ZIP-215 cofactored verification policy.

Enums§

RuntimeVerifier
Explicit runtime choice between the two monomorphized verifier types.
VerifyPolicy
Which acceptance rules a Verifier applies.

Constants§

PUBLIC_KEY_LEN
Byte length of an encoded Ed25519 public key: a compressed Edwards point.
SIGNATURE_LEN
Byte length of an encoded Ed25519 signature.

Traits§

KeyCache
Storage policy for verifier-decoded public keys.
VerificationPolicy
A compile-time verification policy.

Type Aliases§

DalekVerifier
A verifier fixed to Dalek-compatible rules at compile time.
Zip215Verifier
A verifier fixed to ZIP-215 at compile time.