Add further FROST documentation

coins/monero/src/lib.rs

@@ -1,19 +1,19 @@
 #![cfg_attr(docsrs, feature(doc_auto_cfg))]
 
-///! monero-serai: A modern Monero transaction library intended for usage in wallets. It prides
+//! monero-serai: A modern Monero transaction library intended for usage in wallets. It prides
-///! itself on accuracy, correctness, and removing common pit falls developers may face.
+//! itself on accuracy, correctness, and removing common pit falls developers may face.
-///!
+//!
-///! monero-serai contains safety features, such as first-class acknowledgement of the burning bug,
+//! monero-serai contains safety features, such as first-class acknowledgement of the burning bug,
-///! yet also a high level API around creating transactions. monero-serai also offers a FROST-based
+//! yet also a high level API around creating transactions. monero-serai also offers a FROST-based
-///! multisig, which is orders of magnitude more performant than Monero's.
+//! multisig, which is orders of magnitude more performant than Monero's.
-///!
+//!
-///! monero-serai was written for Serai, a decentralized exchange aiming to support Monero.
+//! monero-serai was written for Serai, a decentralized exchange aiming to support Monero.
-///! Despite this, monero-serai is intended to be a widely usable library, accurate to Monero.
+//! Despite this, monero-serai is intended to be a widely usable library, accurate to Monero.
-///! monero-serai guarantees the functionality needed for Serai, yet will not deprive functionality
+//! monero-serai guarantees the functionality needed for Serai, yet will not deprive functionality
-///! from other users, and may potentially leave Serai's umbrella at some point.
+//! from other users, and may potentially leave Serai's umbrella at some point.
-///!
+//!
-///! Various legacy transaction formats are not currently implemented, yet monero-serai is still
+//! Various legacy transaction formats are not currently implemented, yet monero-serai is still
-///! increasing its support for various transaction types.
+//! increasing its support for various transaction types.
 use lazy_static::lazy_static;
 use rand_core::{RngCore, CryptoRng};
 

crypto/frost/Cargo.toml

@@ -43,7 +43,7 @@ dleq = { path = "../dleq", version = "0.1", features = ["serialize"] }
 
 [dev-dependencies]
 sha2 = "0.10"
-dalek-ff-group = { path = "../dalek-ff-group" }
+dalek-ff-group = { path = "../dalek-ff-group", version = "^0.1.2" }
 
 [features]
 dalek = ["sha2", "dalek-ff-group"]

crypto/frost/README.md

@@ -1,6 +1,13 @@
 # Modular FROST
 
-A modular implementation of FROST for any curve with a ff/group API. Notably,
+A modular implementation of FROST for any curve with a ff/group API.
-beyond curve modularity, custom algorithms may be specified, providing support
+Additionally, custom algorithms may be specified so any signature reducible to
-for privacy coins. The provided Schnorr algorithm also has a modular HRAM due
+Schnorr-like may be used with FROST.
-to the variety in existence, enabling integration with existing systems.
+
+A Schnorr algorithm is provided, of the form (R, s) where `s = r + cx`, which
+allows specifying the challenge format. This is intended to easily allow
+integrating with existing systems.
+
+This library offers ciphersuites compatible with the
+[IETF draft](https://github.com/cfrg/draft-irtf-cfrg-frost). Currently, version
+8 is supported.

crypto/frost/src/curve/dalek.rs

@@ -9,6 +9,8 @@ use crate::{curve::Curve, algorithm::Hram};
 
 macro_rules! dalek_curve {
   (
+    $feature: literal,
+
     $Curve:      ident,
     $Hram:       ident,
     $Point:      ident,
@@ -19,6 +21,7 @@ macro_rules! dalek_curve {
   ) => {
     use dalek_ff_group::$Point;
 
+    #[cfg_attr(docsrs, doc(cfg(feature = $feature)))]
     #[derive(Clone, Copy, PartialEq, Eq, Debug, Zeroize)]
     pub struct $Curve;
     impl $Curve {
@@ -46,6 +49,7 @@ macro_rules! dalek_curve {
       }
     }
 
+    #[cfg_attr(docsrs, doc(cfg(feature = $feature)))]
     #[derive(Copy, Clone)]
     pub struct $Hram;
     impl Hram<$Curve> for $Hram {
@@ -65,6 +69,7 @@ macro_rules! dalek_curve {
 
 #[cfg(any(test, feature = "ristretto"))]
 dalek_curve!(
+  "ristretto",
   Ristretto,
   IetfRistrettoHram,
   RistrettoPoint,
@@ -75,6 +80,7 @@ dalek_curve!(
 
 #[cfg(feature = "ed25519")]
 dalek_curve!(
+  "ed25519",
   Ed25519,
   IetfEd25519Hram,
   EdwardsPoint,

crypto/frost/src/curve/kp256.rs

@@ -17,6 +17,8 @@ use crate::{curve::Curve, algorithm::Hram};
 
 macro_rules! kp_curve {
   (
+    $feature: literal,
+
     $lib:   ident,
     $Curve: ident,
     $Hram:  ident,
@@ -24,6 +26,7 @@ macro_rules! kp_curve {
     $ID:      literal,
     $CONTEXT: literal
   ) => {
+    #[cfg_attr(docsrs, doc(cfg(feature = $feature)))]
     #[derive(Clone, Copy, PartialEq, Eq, Debug, Zeroize)]
     pub struct $Curve;
     impl $Curve {
@@ -76,6 +79,7 @@ macro_rules! kp_curve {
       }
     }
 
+    #[cfg_attr(docsrs, doc(cfg(feature = $feature)))]
     #[derive(Clone)]
     pub struct $Hram;
     impl Hram<$Curve> for $Hram {
@@ -88,7 +92,14 @@ macro_rules! kp_curve {
 }
 
 #[cfg(feature = "p256")]
-kp_curve!(p256, P256, IetfP256Hram, b"P-256", b"FROST-P256-SHA256-v8");
+kp_curve!("p256", p256, P256, IetfP256Hram, b"P-256", b"FROST-P256-SHA256-v8");
 
 #[cfg(feature = "secp256k1")]
-kp_curve!(k256, Secp256k1, IetfSecp256k1Hram, b"secp256k1", b"FROST-secp256k1-SHA256-v8");
+kp_curve!(
+  "secp256k1",
+  k256,
+  Secp256k1,
+  IetfSecp256k1Hram,
+  b"secp256k1",
+  b"FROST-secp256k1-SHA256-v8"
+);

crypto/frost/src/lib.rs

@@ -1,5 +1,18 @@
+#![cfg_attr(docsrs, feature(doc_cfg))]
 #![cfg_attr(docsrs, feature(doc_auto_cfg))]
 
+//! A modular implementation of FROST for any curve with a ff/group API.
+//! Additionally, custom algorithms may be specified so any signature reducible to
+//! Schnorr-like may be used with FROST.
+//!
+//! A Schnorr algorithm is provided, of the form (R, s) where `s = r + cx`, which
+//! allows specifying the challenge format. This is intended to easily allow
+//! integrating with existing systems.
+//!
+//! This library offers ciphersuites compatible with the
+//! [IETF draft](https://github.com/cfrg/draft-irtf-cfrg-frost). Currently, version
+//! 8 is supported.
+
 use core::fmt::{self, Debug};
 use std::{io::Read, sync::Arc, collections::HashMap};
 
@@ -14,15 +27,21 @@ use group::{
 
 mod schnorr;
 
+/// Curve trait and provided curves/HRAMs, forming various ciphersuites.
 pub mod curve;
 use curve::Curve;
 
+/// Distributed key generation protocol.
 pub mod key_gen;
+/// Promote keys between curves.
 pub mod promote;
 
+/// Algorithm for the signing process.
 pub mod algorithm;
+/// Threshold signing protocol.
 pub mod sign;
 
+/// Tests for application-provided curves and algorithms.
 pub mod tests;
 
 // Validate a map of serialized values to have the expected included participants
@@ -292,7 +311,7 @@ impl<C: Curve> Drop for FrostKeys<C> {
 }
 impl<C: Curve> ZeroizeOnDrop for FrostKeys<C> {}
 
-// View of keys passable to algorithm implementations
+/// View of keys passed to algorithm implementations.
 #[derive(Clone, Zeroize)]
 pub struct FrostView<C: Curve> {
   group_key: C::G,

crypto/frost/src/tests/mod.rs

@@ -11,10 +11,13 @@ use crate::{
   sign::{PreprocessMachine, SignMachine, SignatureMachine, AlgorithmMachine},
 };
 
-// Test suites for public usage
+/// Curve tests.
 pub mod curve;
+/// Schnorr signature tests.
 pub mod schnorr;
+/// Promotion tests.
 pub mod promote;
+/// Vectorized test suite to ensure consistency.
 pub mod vectors;
 
 // Literal test definitions to run during `cargo test`