Code comments and documentation for crypto benchmarks (#588)

* Documented functions and structures
* Added images
* Added comments on fields.
* Added efficiency notes.
* Added figures to read-me
* `cargo update`

Author: bwbush

crypto-benchmarks.rs/Cargo.lock

@@ -16,6 +16,7 @@ bitvec = "1.0.1"
 blst = "0.3.13"
 clap = { version = "4.5.28", features = ["derive"] }
 criterion = "0.5.1"
+embed-doc-image = "0.1.4"
 hex = "0.4.3"
 num-bigint = { version = "0.4.6", features = ["serde"] }
 num-rational = "0.4.2"
@@ -29,6 +30,12 @@ serde = { version = "1.0.217", features = ["derive"] }
 serde_cbor = "0.11.2"
 statrs = "0.18.0"
 
+[features]
+doc-images = []
+
+[package.metadata.docs.rs]
+features = ["doc-images"]
+
 [[bench]]
 name = "serialization_bench"
 harness = false

crypto-benchmarks.rs/Cargo.toml

@@ -7,6 +7,23 @@ See [Specification.md](Specification.md) for a description of the algorithms imp
 - Benchmarks: [benches/](benches/)
 
 
+## Background material
+
+![BLS scheme from original Leios preprint](figure-7-bls.png)
+
+![Voting scheme from original Leios preprint](figure-8-voting.png)
+
+
+## Efficiency notes
+
+The benchmark code uses an efficient BLS implementation, but it has not been optimized.
+
+- Some of the hash data structures in the certificate could be replaced by bit sets.
+- The optional group checks are turned on for calls to the `blst` library even though in some cases these may not strictly be necessary.
+- The rational arthmetic for computing logarithms and performing sortition uses the maximum precision obtainable in `Ratio<BigInt>` even though that precision is not necessarily needed.
+- The code has not been profiled.
+
+
 ## Command-line interface
 
 A command-line interface is provided for testing and exploration. Note that all input and output files are CBOR.

crypto-benchmarks.rs/ReadMe.md

@@ -1,3 +1,5 @@
+//! Criterion benchmarks for Fait Accompli.
+
 use criterion::{criterion_group, criterion_main, Criterion};
 use quickcheck::{Arbitrary, Gen};
 use std::collections::BTreeMap;

crypto-benchmarks.rs/benches/fait_accompli_bench.rs

@@ -1,3 +1,5 @@
+//! Criterion benchmarks for serialization and deserialization.
+
 use criterion::{criterion_group, criterion_main, Criterion};
 use quickcheck::{Arbitrary, Gen};
 

crypto-benchmarks.rs/benches/serialization_bench.rs

@@ -1,3 +1,5 @@
+//! Criterion benchmarks for sortition.
+
 use criterion::{criterion_group, criterion_main, Criterion};
 use num_bigint::BigInt;
 use num_rational::Ratio;

crypto-benchmarks.rs/benches/sortition_bench.rs

@@ -1,3 +1,5 @@
+//! Criterion benchmarks for voting.
+
 use criterion::{criterion_group, criterion_main, Criterion};
 use leios_crypto_benchmarks::cert::*;
 use leios_crypto_benchmarks::registry::{arbitrary_pools, PersistentId, Registry};

crypto-benchmarks.rs/benches/vote_bench.rs

@@ -1,3 +1,5 @@
+//! Criterion benchmarks for VRF.
+
 use criterion::{criterion_group, criterion_main, Criterion};
 
 use leios_crypto_benchmarks::vrf::{sk_random, sk_to_pk_point, vrf_prove, vrf_verify};