Document all items

Author: carloskiki

Cargo.lock

@@ -5,4 +5,4 @@ edition = "2024"
 
 [dependencies]
 digest = "=0.11.0-pre.10"
-signature = "2.3.0-pre.7"
+signature = "3.0.0-rc.1"

vrf/Cargo.toml

@@ -1,9 +1,11 @@
 # [RustCrypto]: Verifiable Random Functions
 
+Traits which provide generic, object-safe APIs for [verifiable random functions].
+
 ## SemVer Policy
 
 - All on-by-default features of this library are covered by SemVer
-- MSRV is considered exempt from SemVer as noted above
+- MSRV is considered exempt from SemVer
 
 ## License
 
@@ -20,3 +22,7 @@ Unless you explicitly state otherwise, any contribution intentionally submitted
 for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
 dual licensed as above, without any additional terms or conditions.
 
+[//]: # (links)
+
+[verifiable random functions]: https://en.wikipedia.org/wiki/Verifiable_random_function
+[RustCrypto]: https://github.com/RustCrypto/

vrf/README.md

@@ -1,19 +1,58 @@
+#![no_std]
+#![doc = include_str!("../README.md")]
+#![doc(
+    html_logo_url = "https://raw.githubusercontent.com/RustCrypto/media/8f1a9894/logo.svg",
+    html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/media/8f1a9894/logo.svg"
+)]
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+#![forbid(unsafe_code)]
+#![warn(
+    clippy::mod_module_files,
+    clippy::unwrap_used,
+    missing_docs,
+    rust_2018_idioms,
+    unused_lifetimes,
+    missing_debug_implementations,
+    unused_qualifications
+)]
+
+//! # Design
+//!
+//! Traits are defined to match the functionality of verifiable random functions in
+//! [RFC9381](https://www.rfc-editor.org/rfc/rfc9381.pdf).
+//!
+//! ## Verifying Proofs
+//!
+//! Trait based proof verification is delegated to the [`signature::Verifier`] trait, defined in
+//! the `signature` crate and re-exported here. The message corresponds to the `alpha` or
+//! `alpha_string` in RFC9381 (see section 1.2), and the signature corresponds to the [`Proof`].
+
 use digest::{Output, OutputSizeUser};
 
 pub use signature::Verifier;
 
+
+/// A VRF Proof, denoted `pi` or `pi_string` in RFC9381. See RFC9381 section 1.2 for details.
 pub trait Proof<H>
 where
     H: OutputSizeUser,
 {
+    /// Get the hash of the VRF proof.
+    ///
+    /// Defined as `VRF_proof_to_hash` in RFC9381 section 2.
     fn to_hash(&self) -> Output<H>;
 }
 
+/// A cryptographic key that has the capability to generate VRF proofs.
 pub trait Prover<H>
 where
     H: OutputSizeUser,
 {
+    /// Proofs generated by this algorithm.
     type Proof: Proof<H>;
 
+    /// Generate a proof from the given alpha value.
+    ///
+    /// defined as `VRF_proof` in RFC9381 section 2.
     fn prove(&self, alpha: &[u8]) -> Self::Proof;
 }