Document the transcript library

crypto/transcript/README.md

@@ -6,6 +6,9 @@ Flexible Transcript is a crate offering:
 provided hash function.
 - `MerlinTranscript`, a wrapper of `merlin` into the trait (available via the
 `merlin` feature).
+- `RecommendedTranscript`, a transcript recommended for usage in applications.
+  Currently, this is `DigestTranscript<Blake2b512>` (available via the
+  `recommended` feature).
 
 The trait was created while working on an IETF draft which defined an incredibly
 simple transcript format. Extensions of the protocol would quickly require a

crypto/transcript/src/lib.rs

@@ -10,9 +10,19 @@ use digest::{typenum::type_operators::IsGreaterOrEqual, consts::U256, Digest, Ou
 pub trait Transcript {
   type Challenge: Clone + Send + Sync + AsRef<[u8]>;
 
+  /// Apply a domain separator to the transcript
   fn domain_separate(&mut self, label: &'static [u8]);
+
+  /// Append a message to the transcript
   fn append_message(&mut self, label: &'static [u8], message: &[u8]);
+
+  /// Produce a challenge. This MUST update the transcript as it does so, preventing the same
+  /// challenge from being generated multiple times
   fn challenge(&mut self, label: &'static [u8]) -> Self::Challenge;
+
+  /// Produce a RNG seed. Helper function for parties needing to generate random data from an
+  /// agreed upon state. Internally calls the challenge function for the needed bytes, converting
+  /// them to the seed format rand_core expects
   fn rng_seed(&mut self, label: &'static [u8]) -> [u8; 32];
 }
 
@@ -36,9 +46,12 @@ impl DigestTranscriptMember {
   }
 }
 
+/// A trait defining Digests with at least a 256-byte output size, assuming at least a 128-bit
+/// level of security accordingly
 pub trait SecureDigest: Clone + Digest {}
 impl<D: Clone + Digest> SecureDigest for D where D::OutputSize: IsGreaterOrEqual<U256> {}
 
+/// A simple transcript format constructed around the specified hash algorithm
 #[derive(Clone, Debug)]
 pub struct DigestTranscript<D: SecureDigest>(D);