clearmatics · AntoineRondelet · Sep 11, 2020 · Sep 10, 2020
diff --git a/libzeth/circuits/merkle_tree/merkle_path_authenticator.hpp b/libzeth/circuits/merkle_tree/merkle_path_authenticator.hpp
@@ -11,7 +11,7 @@
 namespace libzeth
 {
 
-// Merkle path authenticator, verifies computed root matches expected result
+/// Merkle path authenticator, verifies computed root matches expected result
 template<typename FieldT, typename HashTreeT>
 class merkle_path_authenticator : public merkle_path_compute<FieldT, HashTreeT>
 {

diff --git a/libzeth/circuits/mimc/mimc.hpp b/libzeth/circuits/mimc/mimc.hpp
@@ -7,13 +7,12 @@
 
 #include "libzeth/circuits/mimc/mimc_round.hpp"
 
-// MiMCe7_permutation_gadget enforces correct computation of a MiMC permutation
-// with exponent 7 and rounds 91. It makes use of MiMCe7_round_gadget to enforce
-// correct computation in each round.
-
 namespace libzeth
 {
 
+/// MiMCe7_permutation_gadget enforces correct computation of a MiMC permutation
+/// with exponent 7 and rounds 91. It makes use of MiMCe7_round_gadget to
+/// enforce correct computation in each round.
 template<typename FieldT>
 class MiMCe7_permutation_gadget : public libsnark::gadget<FieldT>
 {

diff --git a/libzeth/circuits/mimc/mimc_mp.hpp b/libzeth/circuits/mimc/mimc_mp.hpp
@@ -7,15 +7,14 @@
 
 #include "libzeth/circuits/mimc/mimc.hpp"
 
-// This gadget implements the interface of the HashTreeT template
-//
-// MiMC_mp_gadget enforces correct computation of MiMC compression function
-// based on a the Miyaguchi-Preneel compression construct and MiMC block cipher
-// on Z_p with exponent 7 (and 91 rounds) p is given by the size(FieldT)
-
 namespace libzeth
 {
 
+/// This gadget implements the interface of the HashTreeT template
+///
+/// MiMC_mp_gadget enforces correct computation of MiMC compression function
+/// based on a the Miyaguchi-Preneel compression construct and MiMC block cipher
+/// on Z_p with exponent 7 (and 91 rounds) p is given by the size(FieldT)
 template<typename FieldT> class MiMC_mp_gadget : public libsnark::gadget<FieldT>
 {
 private:

diff --git a/libzeth/circuits/mimc/mimc_round.hpp b/libzeth/circuits/mimc/mimc_round.hpp
@@ -9,14 +9,13 @@
 
 #include <libsnark/gadgetlib1/gadget.hpp>
 
-// MiMCe7_round_gadget enforces correct computation of a MiMC permutation round
-// with exponent 7. In MiMC permutation last round differs from the others since
-// the key is added again. We use a boolean variable `add_k_to_result` to manage
-// this case.
-
 namespace libzeth
 {
 
+/// MiMCe7_round_gadget enforces correct computation of a MiMC permutation round
+/// with exponent 7. In MiMC permutation last round differs from the others
+/// since the key is added again. We use a boolean variable `add_k_to_result` to
+/// manage this case.
 template<typename FieldT>
 class MiMCe7_round_gadget : public libsnark::gadget<FieldT>
 {

diff --git a/libzeth/circuits/notes/note.hpp b/libzeth/circuits/notes/note.hpp
@@ -15,9 +15,9 @@
 namespace libzeth
 {
 
-// Gadget that makes sure that the note:
-// - Has a value < 2^64
-// - Has a valid r trapdoor which is a 256-bit string
+/// Gadget that makes sure that the note:
+/// - Has a value < 2^64
+/// - 
DD41
Has a valid r trapdoor which is a 256-bit string
 template<typename FieldT> class note_gadget : public libsnark::gadget<FieldT>
 {
 public:
@@ -33,10 +33,10 @@ template<typename FieldT> class note_gadget : public libsnark::gadget<FieldT>
     void generate_r1cs_witness(const zeth_note &note);
 };
 
-// Gadget that makes sure that all conditions are met in order to spend a note:
-// - The nullifier is correctly computed from a_sk and rho
-// - The commitment cm is correctly computed from the coin's data
-// - commitment cm is in the tree of merkle root rt
+/// Gadget that makes sure that all conditions are met in order to spend a note:
+/// - The nullifier is correctly computed from a_sk and rho
+/// - The commitment cm is correctly computed from the coin's data
+/// - commitment cm is in the tree of merkle root rt
 template<typename FieldT, typename HashT, typename HashTreeT, size_t TreeDepth>
 class input_note_gadget : public note_gadget<FieldT>
 {
@@ -93,7 +93,7 @@ class input_note_gadget : public note_gadget<FieldT>
         const zeth_note &note);
 };
 
-// Commit to the output notes of the JS
+/// Commit to the output notes of the Joinsplit
 template<typename FieldT, typename HashT>
 class output_note_gadget : public note_gadget<FieldT>
 {

diff --git a/libzeth/circuits/prfs/prf.hpp b/libzeth/circuits/prfs/prf.hpp
@@ -67,9 +67,9 @@ libsnark::pb_variable_array<FieldT> get_tag_rho(
     const libsnark::pb_variable_array<FieldT> &phi,
     size_t index);
 
-// PRF to generate the public addresses
-// a_pk = blake2sCompress("1100" || [a_sk]_252 || 0^256): See ZCash protocol
-// specification paper, page 57
+/// PRF to generate the public addresses
+/// a_pk = blake2sCompress("1100" || [a_sk]_252 || 0^256): See ZCash protocol
+/// specification paper, page 57
 template<typename FieldT, typename HashT>
 class PRF_addr_a_pk_gadget : public PRF_gadget<FieldT, HashT>
 {
@@ -82,9 +82,9 @@ class PRF_addr_a_pk_gadget : public PRF_gadget<FieldT, HashT>
         const std::string &annotation_prefix = " add_PRF_gadget");
 };
 
-// PRF to generate the nullifier
-// nf = blake2sCompress("1110" || [a_sk]_252 || rho): See ZCash protocol
-// specification paper, page 57
+/// PRF to generate the nullifier
+/// nf = blake2sCompress("1110" || [a_sk]_252 || rho): See ZCash protocol
+/// specification paper, page 57
 template<typename FieldT, typename HashT>
 class PRF_nf_gadget : public PRF_gadget<FieldT, HashT>
 {
@@ -99,9 +99,9 @@ class PRF_nf_gadget : public PRF_gadget<FieldT, HashT>
         const std::string &annotation_prefix = "PRF_nf_gadget");
 };
 
-// PRF to generate the h_i
-// h_i = blake2sCompress("0" || index || "00" || [a_sk]_252 || h_sig): See ZCash
-// protocol specification paper, page 57
+/// PRF to generate the h_i
+/// h_i = blake2sCompress("0" || index || "00" || [a_sk]_252 || h_sig)
+/// See ZCash protocol specification paper, page 57
 template<typename FieldT, typename HashT>
 class PRF_pk_gadget : public PRF_gadget<FieldT, HashT>
 {
@@ -116,9 +116,9 @@ class PRF_pk_gadget : public PRF_gadget<FieldT, HashT>
         const std::string &annotation_prefix = " pk_PRF_gadget");
 };
 
-// PRF to generate rho
-// rho_i = blake2sCompress( "0" || index || "10" || [phi]_252 || h_sig): See
-// ZCash protocol specification paper, page 57
+/// PRF to generate rho
+/// rho_i = blake2sCompress( "0" || index || "10" || [phi]_252 || h_sig)
+/// See ZCash protocol specification paper, page 57
 template<typename FieldT, typename HashT>
 class PRF_rho_gadget : public PRF_gadget<FieldT, HashT>
 {

diff --git a/libzeth/circuits/safe_arithmetic.hpp b/libzeth/circuits/safe_arithmetic.hpp
@@ -10,8 +10,8 @@
 namespace libzeth
 {
 
-/// Subtract `b` from `a`, clamping the result to [0, a] (i.e. returns `0` if `b
-/// > a` instead of wrapping around to the top of the range of values).
+/// Subtract `b` from `a`, clamping the result to [0, a] (i.e. returns `0` if
+/// `b > a` instead of wrapping around to the top of the range of values).
 size_t subtract_with_clamp(size_t a, size_t b);
 
 } // namespace libzeth

diff --git a/libzeth/core/bits.hpp b/libzeth/core/bits.hpp
@@ -12,8 +12,6 @@
 #include <stddef.h>
 #include <vector>
 
-/// Bit-arrays of specific sizes, and related methods.
-
 namespace libzeth
 {
 
@@ -84,10 +82,10 @@ template<size_t TreeDepth> using bits_addr = bits<TreeDepth>;
 /// exception if called with an invalid hexadecimal string.
 std::vector<bool> bit_vector_from_hex(const std::string &str);
 
-// Returns the little endian binary encoding of the integer x.
+/// Returns the little endian binary encoding of the integer x.
 std::vector<bool> bit_vector_from_size_t_le(size_t x);
 
-// Returns the big endian binary encoding of the integer x.
+/// Returns the big endian binary encoding of the integer x.
 std::vector<bool> bit_vector_from_size_t_be(size_t x);
 
 } // namespace libzeth

diff --git a/libzeth/core/extended_proof.hpp b/libzeth/core/extended_proof.hpp
@@ -11,9 +11,9 @@
 namespace libzeth
 {
 
-// An extended_proof is a data structure containing a proof and the
-// corresponding primary inputs It corresponds to the data needed for the
-// verifier to be able to run the verifying algorithm.
+/// An extended_proof is a data structure containing a proof and the
+/// corresponding primary inputs It corresponds to the data needed for the
+/// verifier to be able to run the verifying algorithm.
 template<typename ppT, typename snarkT> class extended_proof
 {
 private:

diff --git a/libzeth/core/hash_stream.hpp b/libzeth/core/hash_stream.hpp
@@ -31,7 +31,7 @@ template<typename HashT> class hash_ostream;
 template<typename HashT> class hash_ostream_wrapper;
 template<typename HashT> class hash_istream_wrapper;
 
-// Internal streambuf for hash_ostream. Hash and discard all written data.
+/// Internal streambuf for hash_ostream. Hash and discard all written data.
 template<typename HashT> class hash_streambuf : std::streambuf
 {
 protected:
@@ -43,7 +43,7 @@ template<typename HashT> class hash_streambuf : std::streambuf
     friend class hash_ostream<HashT>;
 };
 
-// Internal streambuf for wrapped streams. Hash data and forward.
+/// Internal streambuf for wrapped streams. Hash data and forward.
 template<typename HashT> class hash_streambuf_wrapper : std::streambuf
 {
 protected:

diff --git a/libzeth/core/joinsplit_input.hpp b/libzeth/core/joinsplit_input.hpp
@@ -14,10 +14,10 @@
 namespace libzeth
 {
 
-// We simplify the interface of the joinsplit_input object compared to what
-// Zcash did. In fact, all our fields are going to be computed from another
-// component written in python or js, that will use the ethereum primitives to
-// hash.
+/// We simplify the interface of the joinsplit_input object compared to what
+/// Zcash did. In fact, all our fields are going to be computed from another
+/// component written in Python or JS, that will use the Ethereum primitives
+/// to hash.
 template<typename FieldT, size_t TreeDepth> class joinsplit_input
 {
 public:

diff --git a/libzeth/core/merkle_tree_field.hpp b/libzeth/core/merkle_tree_field.hpp
@@ -14,19 +14,18 @@
 namespace libzeth
 {
 
-// Merkle Tree whose nodes are field elements
-//
-// A Merkle tree is maintained as two maps:
-// - `values` = Map from addresses to values, and
-// - `hashes` = Map from addresses to hashes.
-//
-// The second map maintains the intermediate hashes of a Merkle tree
-// built atop the values currently stored in the tree (the
-// implementation admits a very efficient support for sparse
-// trees). Besides offering methods to load and store values, the
-// class offers methods to retrieve the root of the Merkle tree and to
-// obtain the authentication paths for (the value at) a given address.
-
+/// Merkle Tree whose nodes are field elements
+///
+/// A Merkle tree is maintained as two maps:
+/// - `values` = Map from addresses to values, and
+/// - `hashes` = Map from addresses to hashes.
+///
+/// The second map maintains the intermediate hashes of a Merkle tree
+/// built atop the values currently stored in the tree (the
+/// implementation admits a very efficient support for sparse
+/// trees). Besides offering methods to load and store values, the
+/// class offers methods to retrieve the root of the Merkle tree and to
+/// obtain the authentication paths for (the value at) a given address.
 template<typename FieldT, typename HashTreeT> class merkle_tree_field
 {
 

diff --git a/libzeth/mpc/groth16/phase2.hpp b/libzeth/mpc/groth16/phase2.hpp
@@ -8,24 +8,25 @@
 #include "libzeth/mpc/groth16/mpc_hash.hpp"
 #include "libzeth/snarks/groth16/groth16_snark.hpp"
 
-/// Structures and operations related to the "Phase 2" MPC described in
-/// [BoweGM17].  Parts of the implementation use techniques from the
-/// "Phase2" library from "zk-SNARK MPCs, made easy".
-///
-/// References:
-///
-/// \[BoweGM17]
-///  "Scalable Multi-party Computation for zk-SNARK Parameters in the Random
-///  Beacon Model"
-///  Sean Bowe and Ariel Gabizon and Ian Miers,
-///  IACR Cryptology ePrint Archive 2017,
-///  <http://eprint.iacr.org/2017/1050>
-///
-/// "Phase2" (From "zk-SNARK MPCs, made easy" library
-///  https://github.com/ebfull/phase2)
-///
-/// "Sapling MPC" ("Multi-party computation for Zcash's Sapling zk-SNARK public
-///  parameters" https://github.com/zcash-hackworks/sapling-mpc)
+// Structures and operations related to the "Phase 2" MPC described in
+// [BoweGM17].  Parts of the implementation use techniques from the
+//
+// References:
+//
+// \[BoweGM17]
+//  "Scalable Multi-party Computation for zk-SNARK Parameters in the Random
+//  Beacon Model"
+//  Sean Bowe and Ariel Gabizon and Ian Miers,
+//  IACR Cryptology ePrint Archive 2017,
+//  <http://eprint.iacr.org/2017/1050>
+//
+// "Phase2" (From "zk-SNARK MPCs, made easy" library
+//  https://github.com/ebfull/phase2)
+//
+// "Sapling MPC" ("Multi-party computation for Zcash's Sapling zk-SNARK public
+//  parameters" https://github.com/zcash-hackworks/sapling-mpc)
+
 namespace libzeth
 {
 

diff --git a/libzeth/serialization/proto_utils.hpp b/libzeth/serialization/proto_utils.hpp
@@ -17,9 +17,9 @@
 #include <zeth/api/snark_messages.pb.h>
 #include <zeth/api/zeth_messages.pb.h>
 
-/// Functions to convert between in-memory and protobuf types. Consistent with
-/// encoding functions for other types, we use the `<type>_to_proto` and
-/// `<type>_from_proto` naming everywhere.a
+// Functions to convert between in-memory and protobuf types. Consistent with
+// encoding functions for other types, we use the `<type>_to_proto` and
+// `<type>_from_proto` naming everywhere.a
 
 namespace libzeth
 {

diff --git a/libzeth/tests/circuits/simple_test.hpp b/libzeth/tests/circuits/simple_test.hpp
@@ -12,16 +12,16 @@ namespace libzeth
 namespace test
 {
 
-// Generate a simple test circuit with 1 public input 'y' and auxiliary
-//
-// input 'x', for the expression:
-//
-//   x^3 + 4x^2 + 2x + 5 = y
-//
-// Internal auxiliary inputs are:
-//
-//   g1 = x * x
-//   g2 = g1 * x
+/// Generate a simple test circuit with 1 public input 'y' and auxiliary
+///
+/// input 'x', for the expression:
+///
+///   x^3 + 4x^2 + 2x + 5 = y
+///
+/// Internal auxiliary inputs are:
+///
+///   g1 = x * x
+///   g2 = g1 * x
 template<typename FieldT> void simple_circuit(libsnark::protoboard<FieldT> &pb);
 
 } // namespace test