Further documentation, start shoring up API boundaries of existing crates

coins/monero/generators/src/hash_to_point.rs

@@ -9,7 +9,7 @@ use monero_io::decompress_point;
 
 use crate::keccak256;
 
-/// Monero's hash to point function, as named `hash_to_ec`.
+/// Monero's `hash_to_ec` function.
 pub fn hash_to_point(bytes: [u8; 32]) -> EdwardsPoint {
   #[allow(non_snake_case)]
   let A = FieldElement::from(486662u64);

coins/monero/generators/src/lib.rs

@@ -24,7 +24,10 @@ fn keccak256(data: &[u8]) -> [u8; 32] {
 }
 
 static H_CELL: OnceLock<DalekPoint> = OnceLock::new();
-/// Monero's alternate generator `H`, used for amounts in Pedersen commitments.
+/// Monero's `H` generator.
+///
+/// Contrary to convention (`G` for values, `H` for randomness), `H` is used by Monero for amounts
+/// within Pedersen commitments.
 #[allow(non_snake_case)]
 pub fn H() -> DalekPoint {
   *H_CELL.get_or_init(|| {
@@ -33,7 +36,9 @@ pub fn H() -> DalekPoint {
 }
 
 static H_POW_2_CELL: OnceLock<[DalekPoint; 64]> = OnceLock::new();
-/// Monero's alternate generator `H`, multiplied by 2**i for i in 1 ..= 64.
+/// Monero's `H` generator, multiplied by 2**i for i in 1 ..= 64.
+///
+/// This table is useful when working with amounts, which are u64s.
 #[allow(non_snake_case)]
 pub fn H_pow_2() -> &'static [DalekPoint; 64] {
   H_POW_2_CELL.get_or_init(|| {
@@ -45,8 +50,11 @@ pub fn H_pow_2() -> &'static [DalekPoint; 64] {
   })
 }
 
+// The maximum amount of commitments proven for within a single range proof.
 const MAX_M: usize = 16;
+// The amount of bits the value within a commitment may use.
 const N: usize = 64;
+// The maximum amount of bits used within a single range proof.
 const MAX_MN: usize = MAX_M * N;
 
 /// Container struct for Bulletproofs(+) generators.
@@ -57,18 +65,24 @@ pub struct Generators {
 }
 
 /// Generate generators as needed for Bulletproofs(+), as Monero does.
+///
+/// Consumers should not call this function ad-hoc, yet call it within a build script or use a
+/// once-initialized static.
 pub fn bulletproofs_generators(dst: &'static [u8]) -> Generators {
+  let mut preimage = H().compress().to_bytes().to_vec();
+  preimage.extend(dst);
+
   let mut res = Generators { G: Vec::with_capacity(MAX_MN), H: Vec::with_capacity(MAX_MN) };
   for i in 0 .. MAX_MN {
+    // We generate a pair of generators per iteration
     let i = 2 * i;
 
-    let mut even = H().compress().to_bytes().to_vec();
-    even.extend(dst);
-    let mut odd = even.clone();
-
-    write_varint::<Vec<u8>, u64>(&i.try_into().unwrap(), &mut even).unwrap();
-    write_varint::<Vec<u8>, u64>(&(i + 1).try_into().unwrap(), &mut odd).unwrap();
+    let mut even = preimage.clone();
+    write_varint(&i, &mut even).unwrap();
     res.H.push(EdwardsPoint(hash_to_point(keccak256(&even))));
+
+    let mut odd = preimage.clone();
+    write_varint(&(i + 1), &mut odd).unwrap();
     res.G.push(EdwardsPoint(hash_to_point(keccak256(&odd))));
   }
   res

coins/monero/generators/src/tests/hash_to_point.rs

@@ -1,38 +0,0 @@
-use crate::{decompress_point, hash_to_point};
-
-#[test]
-fn crypto_tests() {
-  // tests.txt file copied from monero repo
-  // https://github.com/monero-project/monero/
-  //   blob/ac02af92867590ca80b2779a7bbeafa99ff94dcb/tests/crypto/tests.txt
-  let reader = include_str!("./tests.txt");
-
-  for line in reader.lines() {
-    let mut words = line.split_whitespace();
-    let command = words.next().unwrap();
-
-    match command {
-      "check_key" => {
-        let key = words.next().unwrap();
-        let expected = match words.next().unwrap() {
-          "true" => true,
-          "false" => false,
-          _ => unreachable!("invalid result"),
-        };
-
-        let actual = decompress_point(hex::decode(key).unwrap().try_into().unwrap());
-
-        assert_eq!(actual.is_some(), expected);
-      }
-      "hash_to_ec" => {
-        let bytes = words.next().unwrap();
-        let expected = words.next().unwrap();
-
-        let actual = hash_to_point(hex::decode(bytes).unwrap().try_into().unwrap());
-
-        assert_eq!(hex::encode(actual.compress().to_bytes()), expected);
-      }
-      _ => unreachable!("unknown command"),
-    }
-  }
-}

coins/monero/generators/src/tests/mod.rs

@@ -1 +1,36 @@
-mod hash_to_point;
+use crate::{decompress_point, hash_to_point};
+
+#[test]
+fn test_vectors() {
+  // tests.txt file copied from monero repo
+  // https://github.com/monero-project/monero/
+  //   blob/ac02af92867590ca80b2779a7bbeafa99ff94dcb/tests/crypto/tests.txt
+  let reader = include_str!("./tests.txt");
+
+  for line in reader.lines() {
+    let mut words = line.split_whitespace();
+    let command = words.next().unwrap();
+
+    match command {
+      "check_key" => {
+        let key = words.next().unwrap();
+        let expected = match words.next().unwrap() {
+          "true" => true,
+          "false" => false,
+          _ => unreachable!("invalid result"),
+        };
+
+        let actual = decompress_point(hex::decode(key).unwrap().try_into().unwrap());
+        assert_eq!(actual.is_some(), expected);
+      }
+      "hash_to_ec" => {
+        let bytes = words.next().unwrap();
+        let expected = words.next().unwrap();
+
+        let actual = hash_to_point(hex::decode(bytes).unwrap().try_into().unwrap());
+        assert_eq!(hex::encode(actual.compress().to_bytes()), expected);
+      }
+      _ => unreachable!("unknown command"),
+    }
+  }
+}