Initial documentation for the Monero libraries (#122)

* Document all features

* Largely document the Monero libraries

Relevant to https://github.com/serai-dex/serai/issues/103 and likely 
sufficient to get this removed from 
https://github.com/serai-dex/serai/issues/102.

coins/monero/src/ringct/bulletproofs/mod.rs

@@ -23,6 +23,7 @@ pub(crate) use self::plus::PlusStruct;
 
 pub(crate) const MAX_OUTPUTS: usize = self::core::MAX_M;
 
+/// Bulletproofs enum, supporting the original and plus formulations.
 #[allow(clippy::large_enum_variant)]
 #[derive(Clone, PartialEq, Eq, Debug)]
 pub enum Bulletproofs {
@@ -50,6 +51,7 @@ impl Bulletproofs {
       }
   }
 
+  /// Prove the list of commitments are within [0 .. 2^64).
   pub fn prove<R: RngCore + CryptoRng>(
     rng: &mut R,
     outputs: &[Commitment],
@@ -65,6 +67,7 @@ impl Bulletproofs {
     })
   }
 
+  /// Verify the given Bulletproofs.
   #[must_use]
   pub fn verify<R: RngCore + CryptoRng>(&self, rng: &mut R, commitments: &[EdwardsPoint]) -> bool {
     match self {
@@ -73,6 +76,9 @@ impl Bulletproofs {
     }
   }
 
+  /// Accumulate the verification for the given Bulletproofs into the specified BatchVerifier.
+  /// Returns false if the Bulletproofs aren't sane, without mutating the BatchVerifier.
+  /// Returns true if the Bulletproofs are sane, regardless of their validity.
   #[must_use]
   pub fn batch_verify<ID: Copy + Zeroize, R: RngCore + CryptoRng>(
     &self,
@@ -128,6 +134,7 @@ impl Bulletproofs {
     self.serialize_core(w, |points, w| write_vec(write_point, points, w))
   }
 
+  /// Deserialize non-plus Bulletproofs.
   pub fn deserialize<R: std::io::Read>(r: &mut R) -> std::io::Result<Bulletproofs> {
     Ok(Bulletproofs::Original(OriginalStruct {
       A: read_point(r)?,
@@ -144,6 +151,7 @@ impl Bulletproofs {
     }))
   }
 
+  /// Deserialize Bulletproofs+.
   pub fn deserialize_plus<R: std::io::Read>(r: &mut R) -> std::io::Result<Bulletproofs> {
     Ok(Bulletproofs::Plus(PlusStruct {
       A: read_point(r)?,

coins/monero/src/ringct/clsag/mod.rs

@@ -28,6 +28,7 @@ lazy_static! {
   static ref INV_EIGHT: Scalar = Scalar::from(8u8).invert();
 }
 
+/// Errors returned when CLSAG signing fails.
 #[derive(Clone, Error, Debug)]
 pub enum ClsagError {
   #[error("internal error ({0})")]
@@ -48,6 +49,7 @@ pub enum ClsagError {
   InvalidC1,
 }
 
+/// Input being signed for.
 #[derive(Clone, PartialEq, Eq, Debug, Zeroize, ZeroizeOnDrop)]
 pub struct ClsagInput {
   // The actual commitment for the true spend
@@ -189,6 +191,7 @@ fn core(
   ((D, c * mu_P, c * mu_C), c1.unwrap_or(c))
 }
 
+/// CLSAG signature, as used in Monero.
 #[derive(Clone, PartialEq, Eq, Debug)]
 pub struct Clsag {
   pub D: EdwardsPoint,
@@ -225,7 +228,9 @@ impl Clsag {
     (Clsag { D, s, c1 }, pseudo_out, p, c * z)
   }
 
-  // Single signer CLSAG
+  /// Generate CLSAG signatures for the given inputs.
+  /// inputs is of the form (private key, key image, input).
+  /// sum_outputs is for the sum of the outputs' commitment masks.
   pub fn sign<R: RngCore + CryptoRng>(
     rng: &mut R,
     mut inputs: Vec<(Scalar, EdwardsPoint, ClsagInput)>,
@@ -262,6 +267,7 @@ impl Clsag {
     res
   }
 
+  /// Verify the CLSAG signature against the given Transaction data.
   pub fn verify(
     &self,
     ring: &[[EdwardsPoint; 2]],

coins/monero/src/ringct/clsag/multisig.rs

@@ -23,7 +23,7 @@ use frost::{curve::Ed25519, FrostError, FrostView, algorithm::Algorithm};
 use dalek_ff_group as dfg;
 
 use crate::{
-  frost::{MultisigError, write_dleq, read_dleq},
+  frost::{write_dleq, read_dleq},
   ringct::{
     hash_to_point,
     clsag::{ClsagInput, Clsag},
@@ -54,6 +54,7 @@ impl ClsagInput {
   }
 }
 
+/// CLSAG Input and the mask to use for it.
 #[derive(Clone, Debug, Zeroize, ZeroizeOnDrop)]
 pub struct ClsagDetails {
   input: ClsagInput,
@@ -76,6 +77,7 @@ struct Interim {
   pseudo_out: EdwardsPoint,
 }
 
+/// FROST algorithm for producing a CLSAG signature.
 #[allow(non_snake_case)]
 #[derive(Clone, Debug)]
 pub struct ClsagMultisig {
@@ -97,8 +99,8 @@ impl ClsagMultisig {
     transcript: RecommendedTranscript,
     output_key: EdwardsPoint,
     details: Arc<RwLock<Option<ClsagDetails>>>,
-  ) -> Result<ClsagMultisig, MultisigError> {
-    Ok(ClsagMultisig {
+  ) -> ClsagMultisig {
+    ClsagMultisig {
       transcript,
 
       H: hash_to_point(output_key),
@@ -108,7 +110,7 @@ impl ClsagMultisig {
 
       msg: None,
       interim: None,
-    })
+    }
   }
 
   pub(crate) const fn serialized_len() -> usize {

coins/monero/src/ringct/hash_to_point.rs

@@ -2,6 +2,7 @@ use curve25519_dalek::edwards::EdwardsPoint;
 
 pub use monero_generators::{hash_to_point as raw_hash_to_point};
 
+/// Monero's hash to point function, as named `ge_fromfe_frombytes_vartime`.
 pub fn hash_to_point(key: EdwardsPoint) -> EdwardsPoint {
   raw_hash_to_point(key.compress().to_bytes())
 }

coins/monero/src/ringct/mod.rs

@@ -14,6 +14,7 @@ use crate::{
   ringct::{clsag::Clsag, bulletproofs::Bulletproofs},
 };
 
+/// Generate a key image for a given key. Defined as `x * hash_to_point(xG)`.
 pub fn generate_key_image(mut secret: Scalar) -> EdwardsPoint {
   let res = secret * hash_to_point(&secret * &ED25519_BASEPOINT_TABLE);
   secret.zeroize();
@@ -74,6 +75,7 @@ pub enum RctPrunable {
 }
 
 impl RctPrunable {
+  /// RCT Type byte for a given RctPrunable struct.
   pub fn rct_type(&self) -> u8 {
     match self {
       RctPrunable::Null => 0,