From 43d54b815473614596c80b2de50e1d809e649ce9 Mon Sep 17 00:00:00 2001
From: Ramana Kumar <ramana@member.fsf.org>
Date: Mon, 19 Sep 2022 09:43:18 +0100
Subject: [PATCH] Add some comments to Python file, rename to tests

---
 bindings/python/{example.py => tests.py} | 30 ++++++++++++++++++++++--
 1 file changed, 28 insertions(+), 2 deletions(-)
 rename bindings/python/{example.py => tests.py} (66%)

diff --git a/bindings/python/example.py b/bindings/python/tests.py
similarity index 66%
rename from bindings/python/example.py
rename to bindings/python/tests.py
index d76c3f3..7edac9a 100644
--- a/bindings/python/example.py
+++ b/bindings/python/tests.py
@@ -1,43 +1,58 @@
 import atexit
 import ckzg
 
-def int_from_uint64s(tup):
+def int_from_uint64s(digits):
+    """Convert a 4-tuple of base64 digits to the int it denotes"""
     res, mult = 0, 1
-    for x in tup:
+    for x in digits:
         res += mult * x
         mult *= 2 ** 64
     return res
 
 def eval_poly(coeffs, x):
+    """Evaluate a polynomial represented by a sequence of coefficients"""
     res, mult = 0, 1
     for c in coeffs:
         res += mult * c
         mult *= x
     return res
 
+# Make some elements to be used as coefficients
+
 c1 = ckzg.fr_from_uint64s((12,13,0,0))
 c2 = ckzg.fr_from_uint64(2)
 c3 = ckzg.fr_from_uint64s((1,0,0,0))
 c4 = ckzg.fr_sub(c2, c3)
 
+# A few sanity checks
+
 assert ckzg.fr_is_one(c4)
 
 assert ckzg.fr_equal(c3, c4)
 
+# Create an array of the coefficients
+
 coeffs = [c1, c2, c3, c4]
 cfa = ckzg.frArray(len(coeffs))
 for i, c in enumerate(coeffs):
     cfa[i] = c
 
+# Build the polynomial
+
 ret, pptr = ckzg.new_poly_with_coeffs(cfa.cast(), len(coeffs))
 assert ret == 0
 
+# Check one of its coefficients is as expected
+
 p = ckzg.polyp_frompointer(pptr).value()
 assert p.length == 4
 
 pcoeffs = ckzg.frArray_frompointer(p.coeffs)
 assert ckzg.fr_to_uint64s(pcoeffs[1]) == (2, 0, 0, 0)
 
+# Build a trusted setup with an arbitrary secret s
+# and max scale 4 (so 16 secret values)
+
 max_scale = 4
 
 ret, fs = ckzg.new_fft_settings(max_scale)
@@ -55,20 +70,31 @@ ckzg.generate_trusted_setup(g1s.cast(), g2s.cast(), secret_s, num_secrets)
 ret, ks = ckzg.new_kzg_settings(g1s.cast(), g2s.cast(), num_secrets, fs)
 assert ret == 0
 
+# Compute the Lagrange form of our polynomial in this setup
+
 ret, p_l = ckzg.new_poly_l_from_poly(p, ks)
 assert ret == 0
 
+# Check some evaluations at the point 2
+# First, that Lagrange and coefficient form evaluations agree
+
 ret, y_l = ckzg.eval_poly_l(p_l, c2, fs)
 assert ret == 0
 
 y = ckzg.eval_poly(p, c2)
 assert ckzg.fr_equal(y, y_l)
 
+# And that this agrees with a naive Python evaluation
+
 py_coeffs = [int_from_uint64s(ckzg.fr_to_uint64s(c)) for c in coeffs]
 
 y_p = eval_poly(py_coeffs, int_from_uint64s(ckzg.fr_to_uint64s(c2)))
 assert int_from_uint64s(ckzg.fr_to_uint64s(y)) == y_p
 
+print("All tests passed.")
+
+# We need to manually free the C allocated arrays
+# Use atexit so this file can be loaded interactively before freeing
 def cleanup():
     ckzg.free_poly(pptr)
     ckzg.free_poly_l(p_l)