Add doc comments

README.md

@@ -1 +1,5 @@
-# pollard-kangaroo
+# pollard-kangaroo
+
+See reference documentation:
+- original algorithm explanation: [cuberoot-20120919.pdf](reference/cuberoot-20120919.pdf)
+- our research paper of the algorithm: [kangaroo_plus_testing.pdf](reference/kangaroo_plus_testing.pdf)

src/kangaroo.rs

@@ -23,21 +23,46 @@ pub struct Kangaroo {
     pub table: Table,
 }
 
+/// Defines generated table values.
 #[cfg_attr(feature = "serde", serde_as)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 pub struct Table {
+    /// A vector of generated Ristretto256 points which are used to get the next point and perform
+    /// further distinguished point checks based on [`slog`] scalars.
+    ///
+    /// [`Table::s_values_init`] is used to fill this value with values.
+    ///
+    /// [`slog`]:Table::slog
     pub s: Vec<RistrettoPoint>,
+
+    /// A vector of generated scalars which are used to get the next point and perform further
+    /// distinguished point checks.
+    ///
+    /// [`Table::s_values_init`] is used to fill this value with values.
     pub slog: Vec<Scalar>,
+
+    /// Generated table map where key - distinguished (see [`is_distinguished`] function)
+    /// Ristretto256 point and its discrete log - it's discrete log. Use [`Table::generate`] method
+    /// to fill the table with values.
     #[cfg_attr(feature = "serde", serde_as(as = "Vec<(_, _)>"))]
     pub table: HashMap<CompressedRistretto, Scalar>,
 }
 
+/// Defines constants based on which the algorithm runs.
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 pub struct Parameters {
+    /// Coefficient to increase [`W`] constant.
+    ///
+    /// [`W`]:Parameters::W
     pub i: u64,
+    /// Number of iterations after which we need to regenerate a new starting point
+    /// (see algorithm definition).
     pub W: u64,
+    /// Size of the generated table.
     pub N: u64,
+    /// Number of elements to be generated for `s` and `slog` vectors of the [`Table`] structure.
     pub R: u64,
+    /// Size of a secret to look for.
     pub secret_size: u8,
 }
 
@@ -72,6 +97,11 @@ fn is_distinguished(compressed_point: &CompressedRistretto, parameters: &Paramet
     (point_bytes & (parameters.W - 1)) == 0
 }
 
+/// Gets a new index from the provided compressed Ristretto point. The index is meant to be used
+/// for retrieving elements from [`Table`] `s` and `slog` vectors.
+///
+/// Note: it does not perform hashing. However, in the original reference implementation authors
+/// (Daniel J. Bernstein and Tanja Lange) use exactly the same name.
 fn hash(compressed_point: &CompressedRistretto, parameters: &Parameters) -> u64 {
     let point_bytes = get_last_point_bytes(compressed_point);
 

src/kangaroo/solver.rs

@@ -2,12 +2,17 @@ use crate::kangaroo::{self, Kangaroo};
 use crate::utils;
 
 use anyhow::{Context, Result};
+use curve25519_dalek_ng::traits::Identity;
 use curve25519_dalek_ng::{constants::RISTRETTO_BASEPOINT_POINT, ristretto::RistrettoPoint};
 use std::ops::{Add, AddAssign, Mul, Sub};
 use web_time::{Duration, Instant};
 
 impl Kangaroo {
     pub fn solve_dlp(&self, pk: &RistrettoPoint, max_time: Option<u64>) -> Result<Option<u64>> {
+        if pk.eq(&RistrettoPoint::identity()) {
+            return Ok(Some(0));
+        }
+
         let start_time = max_time.map(|_| Instant::now());
 
         loop {