Fully document crypto/

crypto/dalek-ff-group/README.md

@@ -4,6 +4,7 @@ ff/group bindings around curve25519-dalek with a from_hash/random function based
 around modern dependencies.
 
 This library was
-[audited by Cypher Stack in March 2023](https://github.com/serai-dex/serai/raw/74924095e1a0f266b58181b539d9e74fa35dc37a/audits/Cypher%20Stack%20crypto%20March%202023/Audit.pdf),
-culminating in commit 669d2dbffc1dafb82a09d9419ea182667115df06. Any subsequent
-changes have not undergone auditing.
+[audited by Cypher Stack in March 2023](https://github.com/serai-dex/serai/raw/e1bb2c191b7123fd260d008e31656d090d559d21/audits/Cypher%20Stack%20crypto%20March%202023/Audit.pdf),
+culminating in commit
+[669d2dbffc1dafb82a09d9419ea182667115df06](https://github.com/serai-dex/serai/tree/669d2dbffc1dafb82a09d9419ea182667115df06).
+Any subsequent changes have not undergone auditing.

crypto/dalek-ff-group/src/field.rs

@@ -19,6 +19,7 @@ use crate::{u8_from_bool, constant_time, math, from_uint};
 const MODULUS: U256 = U256::from_u8(1).shl_vartime(255).saturating_sub(&U256::from_u8(19));
 const WIDE_MODULUS: U512 = U256::ZERO.concat(&MODULUS);
 
+/// A constant-time implementation of the Ed25519 field.
 #[derive(Clone, Copy, PartialEq, Eq, Default, Debug)]
 pub struct FieldElement(U256);
 
@@ -184,11 +185,13 @@ impl PrimeFieldBits for FieldElement {
 }
 
 impl FieldElement {
+  /// Interpret the value as a little-endian integer, square it, and reduce it into a FieldElement.
   pub fn from_square(value: [u8; 32]) -> FieldElement {
     let value = U256::from_le_bytes(value);
     FieldElement(value) * FieldElement(value)
   }
 
+  /// Perform an exponentation.
   pub fn pow(&self, other: FieldElement) -> FieldElement {
     let mut table = [FieldElement::one(); 16];
     table[1] = *self;

crypto/dalek-ff-group/src/lib.rs

@@ -1,5 +1,6 @@
 #![cfg_attr(docsrs, feature(doc_auto_cfg))]
 #![no_std]
+#![doc = include_str!("../README.md")]
 
 use core::{
   borrow::Borrow,
@@ -23,15 +24,10 @@ use dalek::{
   constants,
   traits::Identity,
   scalar::Scalar as DScalar,
-  edwards::{
-    EdwardsPoint as DEdwardsPoint, EdwardsBasepointTable as DEdwardsBasepointTable,
-    CompressedEdwardsY as DCompressedEdwards,
-  },
-  ristretto::{
-    RistrettoPoint as DRistrettoPoint, RistrettoBasepointTable as DRistrettoBasepointTable,
-    CompressedRistretto as DCompressedRistretto,
-  },
+  edwards::{EdwardsPoint as DEdwardsPoint, EdwardsBasepointTable, CompressedEdwardsY},
+  ristretto::{RistrettoPoint as DRistrettoPoint, RistrettoBasepointTable, CompressedRistretto},
 };
+pub use constants::{ED25519_BASEPOINT_TABLE, RISTRETTO_BASEPOINT_TABLE};
 
 use group::{
   ff::{Field, PrimeField, FieldBits, PrimeFieldBits},
@@ -39,7 +35,8 @@ use group::{
   prime::PrimeGroup,
 };
 
-pub mod field;
+mod field;
+pub use field::FieldElement;
 
 // Feature gated due to MSRV requirements
 #[cfg(feature = "black_box")]
@@ -362,7 +359,6 @@ macro_rules! dalek_group {
     $torsion_free: expr,
 
     $Table: ident,
-    $DTable: ident,
 
     $DCompressed: ident,
 
@@ -376,6 +372,7 @@ macro_rules! dalek_group {
     constant_time!($Point, $DPoint);
     math_neg!($Point, Scalar, $DPoint::add, $DPoint::sub, $DPoint::mul);
 
+    /// The basepoint for this curve.
     pub const $BASEPOINT_POINT: $Point = $Point(constants::$BASEPOINT_POINT);
 
     impl Sum<$Point> for $Point {
@@ -437,16 +434,10 @@ macro_rules! dalek_group {
 
     impl PrimeGroup for $Point {}
 
-    /// Wrapper around the dalek Table type, offering efficient multiplication against the
-    /// basepoint.
-    pub struct $Table(pub $DTable);
-    deref_borrow!($Table, $DTable);
-    pub const $BASEPOINT_TABLE: $Table = $Table(constants::$BASEPOINT_TABLE);
-
     impl Mul<Scalar> for &$Table {
       type Output = $Point;
       fn mul(self, b: Scalar) -> $Point {
-        $Point(&b.0 * &self.0)
+        $Point(&b.0 * self)
       }
     }
 
@@ -468,8 +459,7 @@ dalek_group!(
   DEdwardsPoint,
   |point: DEdwardsPoint| point.is_torsion_free(),
   EdwardsBasepointTable,
-  DEdwardsBasepointTable,
-  DCompressedEdwards,
+  CompressedEdwardsY,
   ED25519_BASEPOINT_POINT,
   ED25519_BASEPOINT_TABLE
 );
@@ -485,8 +475,7 @@ dalek_group!(
   DRistrettoPoint,
   |_| true,
   RistrettoBasepointTable,
-  DRistrettoBasepointTable,
-  DCompressedRistretto,
+  CompressedRistretto,
   RISTRETTO_BASEPOINT_POINT,
   RISTRETTO_BASEPOINT_TABLE
 );