Documented functions and structures

Author: bwbush

crypto-benchmarks.rs/benches/fait_accompli_bench.rs

@@ -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/serialization_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/sortition_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/vote_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/vrf_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};

crypto-benchmarks.rs/src/bls_util.rs

@@ -1,9 +1,12 @@
+//! Low-level utility functions for BLS operations not supported by the `blst` library.
+
 use blst::min_sig::*;
 use blst::*;
 use num_bigint::{BigInt, Sign};
 use num_rational::Ratio;
 use num_traits::FromPrimitive;
 
+/// Apply a function to a public key (i.e., to a point in G2).
 pub fn pk_transform(f: &dyn Fn(blst_p2) -> blst_p2, pk: &PublicKey) -> PublicKey {
     let mut point: blst_p2 = blst_p2::default();
     unsafe {
@@ -24,6 +27,7 @@ pub fn pk_transform(f: &dyn Fn(blst_p2) -> blst_p2, pk: &PublicKey) -> PublicKey
     }
 }
 
+/// Apply a function to a signature (i.e., to a point in G1).
 pub fn sig_transform(f: &dyn Fn(blst_p1) -> blst_p1, sig: &Signature) -> Signature {
     let mut point: blst_p1 = blst_p1::default();
     unsafe {
@@ -44,6 +48,7 @@ pub fn sig_transform(f: &dyn Fn(blst_p1) -> blst_p1, sig: &Signature) -> Signatu
     }
 }
 
+/// Convert a signature to a rational number between zero and one.
 pub fn sig_to_rational(sig: &Signature) -> Ratio<BigInt> {
     let bytes: [u8; 48] = sig.to_bytes();
     let mut hashed: [u8; 32] = [0; 32];

crypto-benchmarks.rs/src/bls_vote.rs

@@ -1,13 +1,22 @@
+//! Low-level operations on BLS votes.
+//! 
+//! ![Figure 7 (BLS)](../../../../figure-7-bls.png)
+//! 
+//! ![Figure 8 (voting)](../../../../figure-8-voting.png)
+
 use blst::min_sig::*;
 use blst::*;
 use rand::RngCore;
 
 use crate::bls_util::*;
 
+/// An empty bytestring.
 const EMPTY: [u8; 0] = [];
 
+/// The domain separator for Leios.
 const DST: &[u8; 5] = b"Leios";
 
+/// Generate a secret BLS scalar.
 pub fn gen_key() -> SecretKey {
     let mut rng: rand::prelude::ThreadRng = rand::thread_rng();
     let mut ikm: [u8; 32] = [0u8; 32];
@@ -16,12 +25,14 @@ pub fn gen_key() -> SecretKey {
     SecretKey::key_gen(&ikm, info).unwrap()
 }
 
+/// Create a proof of possession from a secret key `sk`, namely $\mu_1$ and $\mu_2$ of [Figure 8 (voting)](index.html).
 pub fn make_pop(sk: &SecretKey) -> (Signature, Signature) {
     let m1: [u8; 192] = sk.sk_to_pk().serialize();
     let m2 = EMPTY;
     (sk.sign(&m1, DST, b"PoP"), sk.sign(&m2, DST, &EMPTY))
 }
 
+/// Verify the the proof of possession, namely $\mu_1$ and $\mu_2$ of [Figure 8 (voting)](index.html), for a public key `pk`.
 pub fn check_pop(pk: &PublicKey, mu1: &Signature, mu2: &Signature) -> bool {
     let m1: [u8; 192] = pk.serialize();
     let m2 = EMPTY;
@@ -30,29 +41,35 @@ pub fn check_pop(pk: &PublicKey, mu1: &Signature, mu2: &Signature) -> bool {
     result1 == BLST_ERROR::BLST_SUCCESS && result2 == BLST_ERROR::BLST_SUCCESS
 }
 
+/// Sign the message `m` in the election `eid` using the secret key `sk`.
 pub fn gen_sig(sk: &SecretKey, eid: &[u8], m: &[u8]) -> Signature {
     sk.sign(m, DST, eid)
 }
 
+/// Verify a signature `vs` on the message `m` in the election `eid` for the public key `pk`.
 pub fn verify_sig(pk: &PublicKey, eid: &[u8], m: &[u8], vs: &Signature) -> bool {
     let result_m = vs.verify(true, m, DST, eid, pk, false);
     result_m == BLST_ERROR::BLST_SUCCESS
 }
 
+/// Sign the election `eid` with the secret key `sk`.
 pub fn gen_sigma_eid(sk: &SecretKey, eid: &[u8]) -> Signature {
     sk.sign(&EMPTY, DST, eid)
 }
 
+/// Create a vote for the message `m` in the election `eid` using the secret key `sk`.
 pub fn gen_vote(sk: &SecretKey, eid: &[u8], m: &[u8]) -> (Signature, Signature) {
     (sk.sign(&EMPTY, DST, eid), sk.sign(m, DST, eid))
 }
 
+/// Verify the vote `vs` for the message `m` in the election `eid` for the public key `pk`.
 pub fn verify_vote(pk: &PublicKey, eid: &[u8], m: &[u8], vs: &(Signature, Signature)) -> bool {
     let result_eid = vs.0.verify(true, &EMPTY, DST, eid, pk, true);
     let result_m = vs.1.verify(true, m, DST, eid, pk, false);
     result_eid == BLST_ERROR::BLST_SUCCESS && result_m == BLST_ERROR::BLST_SUCCESS
 }
 
+/// Hash an array of signatures `sigma_eids` and `sigma_ms`.
 fn hash_sigs(sigma_eids: &[&Signature], sigma_ms: &[&Signature]) -> [u8; 32] {
     let mut sigmas: Vec<&Signature> = Vec::new();
     sigmas.extend(sigma_eids);
@@ -65,6 +82,7 @@ fn hash_sigs(sigma_eids: &[&Signature], sigma_ms: &[&Signature]) -> [u8; 32] {
     }
 }
 
+/// Hash an integer `i` with a previous hash `h`.
 fn hash_index(i: i32, h: &[u8; 32]) -> [u8; 32] {
     let mut msg: [u8; 36] = [0; 36];
     let ii: [u8; 4] = i.to_ne_bytes();
@@ -80,12 +98,14 @@ fn hash_index(i: i32, h: &[u8; 32]) -> [u8; 32] {
     }
 }
 
+/// Create the signatures for a certificate from the individual vote signatures `vss`.
 pub fn gen_cert(vss: &[&(Signature, Signature)]) -> Result<(Signature, Signature), BLST_ERROR> {
     let sigma_eids: Vec<&Signature> = vss.iter().map(|vs| &vs.1).collect();
     let sigma_ms: Vec<&Signature> = vss.iter().map(|vs| &vs.1).collect();
     gen_cert_fa(&sigma_eids, &sigma_ms)
 }
 
+/// Verify the contents of certificate signatures `cs` for the message `m` in election `eid`, given the vote signatures `vss`.
 pub fn verify_cert(
     pks: &[&PublicKey],
     eid: &[u8],
@@ -129,6 +149,7 @@ pub fn verify_cert(
     }
 }
 
+/// Create certificate signatures including both sortition and message signing signatures.
 pub fn gen_cert_fa(
     sigma_eids: &[&Signature],
     sigma_ms: &[&Signature],
@@ -161,6 +182,7 @@ pub fn gen_cert_fa(
     }
 }
 
+/// Create cerificate signatures including only message signing signatures.
 pub fn gen_cert_fa_pure(sigma_ms: &[&Signature]) -> Result<Signature, BLST_ERROR> {
     let result_m = AggregateSignature::aggregate(sigma_ms, true);
     match result_m {
@@ -169,6 +191,7 @@ pub fn gen_cert_fa_pure(sigma_ms: &[&Signature]) -> Result<Signature, BLST_ERROR
     }
 }
 
+/// Verify cerificate sigantures according to [Figure 8 (voting)](index.html).
 pub fn verify_cert_fa(
     pks: &[&PublicKey],
     pks_nonpersistent: &[&PublicKey],
@@ -212,6 +235,7 @@ pub fn verify_cert_fa(
     }
 }
 
+/// Verify signatures for a message, without verifying sortition.
 pub fn verify_cert_fa_pure(
     pks: &[&PublicKey],
     eid: &[u8],

crypto-benchmarks.rs/src/cert.rs

@@ -1,3 +1,5 @@
+//! High-level operations on certificates.
+
 use blst::min_sig::*;
 use quickcheck::{Arbitrary, Gen};
 use serde::{Deserialize, Serialize};
@@ -10,6 +12,7 @@ use crate::registry::{PersistentId, Registry};
 use crate::sortition::voter_check;
 use crate::vote::{do_voting, Vote};
 
+/// A certificate records the election and EB information along with the persistent voters who voted and the proofs for the non-persistent voters. It contains two aggregate signatures, one for sortition and other for the votes themselves.
 #[derive(PartialEq, Eq, Debug, Clone, Serialize, Deserialize)]
 pub struct Cert {
     pub eid: Eid,
@@ -20,6 +23,7 @@ pub struct Cert {
     pub sigma_tilde_m: Sig,
 }
 
+/// Generate an arbitrary certificate.
 pub fn arbitrary_cert(g: &mut Gen, reg: &Registry) -> Cert {
     let eid = Eid::arbitrary(g);
     let eb = EbHash::arbitrary(g);
@@ -33,6 +37,7 @@ impl Arbitrary for Cert {
     }
 }
 
+/// It's convenient to have a data structure for holding certificate information as it is being built.
 #[derive(Default)]
 struct TraverseVote<'a> {
     pub eids: HashSet<&'a Eid>,
@@ -43,6 +48,7 @@ struct TraverseVote<'a> {
     pub sigma_ms: Vec<&'a Signature>,
 }
 
+/// Add one vote to a certification that is being constructed.
 fn traverse_vote<'a>(reg: &'a Registry, t: &mut TraverseVote<'a>, vote: &'a Vote) -> Option<()> {
     match vote {
         Vote::Persistent {
@@ -74,6 +80,7 @@ fn traverse_vote<'a>(reg: &'a Registry, t: &mut TraverseVote<'a>, vote: &'a Vote
     }
 }
 
+/// Test that a hash set is a singleton.
 fn unique<X>(xs: &HashSet<X>) -> Option<&X> {
     if xs.len() == 1 {
         xs.iter().next()
@@ -82,6 +89,7 @@ fn unique<X>(xs: &HashSet<X>) -> Option<&X> {
     }
 }
 
+/// Generate a certificate for the specified votes.
 pub fn gen_cert(reg: &Registry, votes: &[Vote]) -> Option<Cert> {
     let mut t: TraverseVote = TraverseVote::default();
     let _ = votes
@@ -113,6 +121,7 @@ pub fn gen_cert(reg: &Registry, votes: &[Vote]) -> Option<Cert> {
     }
 }
 
+/// Verify a certificate using the information in the voter registry.
 pub fn verify_cert(reg: &Registry, cert: &Cert) -> bool {
     let pks_persistent: Vec<&PublicKey> = cert
         .persistent_voters
@@ -154,6 +163,7 @@ pub fn verify_cert(reg: &Registry, cert: &Cert) -> bool {
     }
 }
 
+/// Compute the total weight (i.e., stake fraction) of the persistent votes in a certificate.
 fn weigh_persistent(reg: &Registry, cert: &Cert) -> Option<CoinFraction> {
     let weight: Option<Coin> = cert.persistent_voters.iter().try_fold(0, |acc, pid| {
         reg.persistent_pool
@@ -163,6 +173,7 @@ fn weigh_persistent(reg: &Registry, cert: &Cert) -> Option<CoinFraction> {
     weight.map(|total| CoinFraction::from_coins(total, 1))
 }
 
+/// Compute the total weight (i.e., stake fraction) of the non-persistent votes in a certificate.
 fn weigh_nonpersistent(reg: &Registry, cert: &Cert) -> Option<CoinFraction> {
     let nonpersistent_voters = reg.voters - cert.persistent_voters.len();
     let weight: Option<usize> =
@@ -184,6 +195,7 @@ fn weigh_nonpersistent(reg: &Registry, cert: &Cert) -> Option<CoinFraction> {
     })
 }
 
+/// Compute the total weight (i.e., stake fraction) of the votes in a certificate.
 pub fn weigh_cert(reg: &Registry, cert: &Cert) -> Option<CoinFraction> {
     let persistent_weight = weigh_persistent(reg, cert)?.to_ratio();
     let nonpersistent_weight = weigh_nonpersistent(reg, cert)?.to_ratio();

crypto-benchmarks.rs/src/fait_accompli.rs

@@ -1,3 +1,5 @@
+//! Fait Accompli operations.
+
 use num_bigint::BigInt;
 use num_rational::Ratio;
 use num_traits::{One, Zero};
@@ -7,6 +9,7 @@ use std::collections::BTreeMap;
 
 use crate::primitive::{Coin, CoinFraction, PoolKeyhash};
 
+/// Fait Accompli sortition results in a committee of persistent and non-persistent voters.
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct FaSortition {
     pub n_persistent: usize,
@@ -17,6 +20,7 @@ pub struct FaSortition {
 }
 
 impl FaSortition {
+    /// Perform Fait Accompli sortiion on the stake distribution `pools` and target committee size `n`.
     pub fn fait_accompli(pools: &BTreeMap<PoolKeyhash, Coin>, n: usize) -> Self {
         let zero: Ratio<BigInt> = Ratio::from_integer(BigInt::zero());
         let (s, p): (Vec<Ratio<BigInt>>, Vec<PoolKeyhash>) = sort_stake(pools);
@@ -57,6 +61,7 @@ impl FaSortition {
     }
 }
 
+/// Sort stake pools in order of decreasing stake.
 fn sort_stake(pools: &BTreeMap<PoolKeyhash, Coin>) -> (Vec<Ratio<BigInt>>, Vec<PoolKeyhash>) {
     let mut sp: Vec<(Ratio<BigInt>, &PoolKeyhash)> = pools
         .iter()
@@ -67,6 +72,7 @@ fn sort_stake(pools: &BTreeMap<PoolKeyhash, Coin>) -> (Vec<Ratio<BigInt>>, Vec<P
     sp.into_iter().unzip()
 }
 
+/// Sum stake fractions.
 fn sum_stake(s: &[Ratio<BigInt>]) -> Vec<Ratio<BigInt>> {
     let zero: Ratio<BigInt> = Ratio::from_integer(BigInt::zero());
     let (mut rho, _): (Vec<Ratio<BigInt>>, Ratio<BigInt>) =
@@ -81,6 +87,7 @@ fn sum_stake(s: &[Ratio<BigInt>]) -> Vec<Ratio<BigInt>> {
     rho
 }
 
+/// Perform the Fait Accompli test that check whether there are any more persistent pools to be selected.
 fn fa_test(s: &[Ratio<BigInt>], rho: &[Ratio<BigInt>], n: usize, i: usize) -> bool {
     let zero: Ratio<BigInt> = Ratio::from_integer(BigInt::zero());
     let one: Ratio<BigInt> = Ratio::from_integer(BigInt::one());

crypto-benchmarks.rs/src/key.rs

@@ -1,3 +1,5 @@
+//! High-level operations on Leios keys.
+
 use blst::min_sig::*;
 use blst::BLST_ERROR;
 use num_bigint::BigInt;
@@ -11,6 +13,7 @@ use crate::bls_vote;
 use crate::primitive::{arbitrary_poolkeyhash, KesSig, PoolKeyhash};
 use crate::util::{arbitrary_fixed_bytes, deserialize_fixed_bytes, serialize_fixed_bytes};
 
+/// A secret key is a BLS scalar.
 #[derive(Clone, Debug)]
 pub struct SecKey(pub(crate) SecretKey);
 
@@ -58,6 +61,7 @@ impl Arbitrary for SecKey {
     }
 }
 
+/// A public key is a point in G2.
 #[derive(PartialEq, Eq, Clone, Debug)]
 pub struct PubKey(pub(crate) PublicKey);
 
@@ -96,6 +100,7 @@ impl Arbitrary for PubKey {
     }
 }
 
+/// A signature is a point in G1.
 #[derive(PartialEq, Eq, Clone, Debug)]
 pub struct Sig(pub(crate) Signature);
 
@@ -136,6 +141,7 @@ impl Arbitrary for Sig {
     }
 }
 
+/// A proof of possession is a pair of points in G1.
 #[derive(PartialEq, Eq, Debug, Clone, Serialize, Deserialize)]
 pub struct PoP {
     pub mu1: Sig, // 48 bytes
@@ -153,6 +159,7 @@ impl Arbitrary for PoP {
     }
 }
 
+/// Key registration includes the pool hash, the public key, the proof of possession, and a KES signature.
 #[derive(PartialEq, Eq, Debug, Clone, Serialize, Deserialize)]
 pub struct Reg {
     pub pool: PoolKeyhash, //  28 bytes
@@ -161,6 +168,7 @@ pub struct Reg {
     pub kes_sig: KesSig,   // 448 bytes
 } // 668 bytes
 
+/// Generate an arbitrary pool registration.
 pub fn arbitrary_reg(g: &mut Gen, pool: &PoolKeyhash, sk: &SecKey) -> Reg {
     let (mu1, mu2) = bls_vote::make_pop(&sk.0);
     Reg {
@@ -182,6 +190,7 @@ impl Arbitrary for Reg {
     }
 }
 
+/// Generate an arbitrary secret key along with its public key and proof of possession.
 pub fn key_gen() -> (SecKey, PubKey, PoP) {
     let sk: SecretKey = bls_vote::gen_key();
     let mvk: PublicKey = sk.sk_to_pk();
@@ -196,14 +205,17 @@ pub fn key_gen() -> (SecKey, PubKey, PoP) {
     )
 }
 
+/// Verify a proof of possession `mu` for a public key `mvk`.
 pub fn check_pop(mvk: &PubKey, mu: &PoP) -> bool {
     bls_vote::check_pop(&mvk.0, &mu.mu1.0, &mu.mu2.0)
 }
 
+/// Sign a message `msg` in the domain `dst` with the secret key `sk`.
 pub fn sign_message(sk: &SecKey, dst: &[u8], msg: &[u8]) -> Sig {
     Sig(sk.0.sign(msg, dst, &[]))
 }
 
+/// Verify signature `sig` on a message `msg` in the domain `dst` using a public key `pk`.
 pub fn verify_message(pk: &PubKey, dst: &[u8], msg: &[u8], sig: &Sig) -> bool {
     let result = sig.0.verify(true, msg, dst, &[], &pk.0, true);
     result == BLST_ERROR::BLST_SUCCESS