From c7a12ee178536e58b29d8ac97d8d0f15013c632a Mon Sep 17 00:00:00 2001
From: Daira Hopwood <daira@jacaranda.org>
Date: Sun, 17 Jan 2021 02:24:09 +0000
Subject: [PATCH] Add documentation of perfect hash parameters.

---
 src/arithmetic/fields.rs | 4 ++++
 src/pasta/fields/fp.rs   | 1 +
 src/pasta/fields/fq.rs   | 1 +
 3 files changed, 6 insertions(+)

diff --git a/src/arithmetic/fields.rs b/src/arithmetic/fields.rs
index 584829a..6a35cc0 100644
--- a/src/arithmetic/fields.rs
+++ b/src/arithmetic/fields.rs
@@ -151,6 +151,10 @@ struct SqrtHasher<F: FieldExt> {
 impl<F: FieldExt> SqrtHasher<F> {
     /// Returns a perfect hash of x for use with SqrtTables::inv.
     fn hash(&self, x: &F) -> usize {
+        // This is just the simplest constant-time perfect hash construction that could
+        // possibly work. The 32 low-order bits are unique within the 2^S order subgroup,
+        // then the xor acts as "salt" to injectively randomize the output when taken modulo
+        // `hash_mod`. Since the table is small, we do not need anything more complicated.
         ((x.get_lower_32() ^ self.hash_xor) as usize) % self.hash_mod
     }
 }
diff --git a/src/pasta/fields/fp.rs b/src/pasta/fields/fp.rs
index 87b3bd3..07a6d3d 100644
--- a/src/pasta/fields/fp.rs
+++ b/src/pasta/fields/fp.rs
@@ -600,6 +600,7 @@ impl ff::PrimeField for Fp {
 }
 
 lazy_static! {
+    // The perfect hash parameters are found by `squareroottab.sage` in zcash/pasta.
     static ref FP_TABLES: SqrtTables<Fp> = SqrtTables::new(0x11BE, 1098);
 }
 
diff --git a/src/pasta/fields/fq.rs b/src/pasta/fields/fq.rs
index 7f9cc0a..3bd0e47 100644
--- a/src/pasta/fields/fq.rs
+++ b/src/pasta/fields/fq.rs
@@ -600,6 +600,7 @@ impl ff::PrimeField for Fq {
 }
 
 lazy_static! {
+    // The perfect hash parameters are found by `squareroottab.sage` in zcash/pasta.
     static ref FQ_TABLES: SqrtTables<Fq> = SqrtTables::new(0x116A9E, 1206);
 }