@maci-protocol/circuits 0.0.0-ci.a577366 → 0.0.0-ci.a584b1a

package/circom/utils/non-qv/{messageValidator.circom → MessageValidator.circom}

@@ -3,7 +3,7 @@ pragma circom 2.0.0;
 // zk-kit imports
 include "./safe-comparators.circom";
 // local imports
-include "../verifySignature.circom";
+include "../VerifySignature.circom";
 
 /**
  * Checks if a MACI message is valid or not.
@@ -11,12 +11,14 @@ include "../verifySignature.circom";
  */
 template MessageValidatorNonQv() {
     // Length of the packed command.
-    var PACKED_CMD_LENGTH = 4;
+    var PACKED_COMMAND_LENGTH = 4;
+    // Number of checks to be performed.
+    var TOTAL_CHECKS = 5;
 
     // State index of the user.
     signal input stateTreeIndex;
     // Number of user sign-ups in the state tree.
-    signal input numSignUps;
+    signal input totalSignups;
     // Vote option index.
     signal input voteOptionIndex;
     // Number of valid vote options for the poll.
@@ -26,13 +28,13 @@ template MessageValidatorNonQv() {
     // Command nonce.
     signal input nonce;
     // Packed command.
-    signal input cmd[PACKED_CMD_LENGTH];
+    signal input command[PACKED_COMMAND_LENGTH];
     // Public key of the state leaf (user).
-    signal input pubKey[2];
-    // ECDSA signature of the command (R part).
-    signal input sigR8[2];
-    // ECDSA signature of the command (S part).
-    signal input sigS;
+    signal input publicKey[2];
+    // EdDSA signature of the command (R part).
+    signal input signaturePoint[2];
+    // EdDSA signature of the command (S part).
+    signal input signatureScalar;
     // State leaf current voice credit balance.
     signal input currentVoiceCreditBalance;
     // Current number of votes for specific option. 
@@ -48,10 +50,10 @@ template MessageValidatorNonQv() {
     signal output isVoteOptionIndexValid;
 
     // Check (1) - The state leaf index must be valid.
-    // The check ensure that the stateTreeIndex < numSignUps as first validation.
+    // The check ensure that the stateTreeIndex < totalSignups as first validation.
     // Must be < because the stateTreeIndex is 0-based. Zero is for blank state leaf
     // while 1 is for the first actual user.
-    var computedIsStateLeafIndexValid = SafeLessThan(252)([stateTreeIndex, numSignUps]);
+    var computedIsStateLeafIndexValid = SafeLessThan(252)([stateTreeIndex, totalSignups]);
 
     // Check (2) - The vote option index must be less than the number of valid vote options (0 indexed).
     var computedIsVoteOptionIndexValid = SafeLessThan(252)([voteOptionIndex, voteOptions]);
@@ -60,7 +62,7 @@ template MessageValidatorNonQv() {
     var computedIsNonceValid = IsEqual()([originalNonce + 1, nonce]);
 
     // Check (4) - The signature must be correct.    
-    var computedIsSignatureValid = VerifySignature()(pubKey, sigR8, sigS, cmd);
+    var computedIsSignatureValid = VerifySignature()(publicKey, signaturePoint, signatureScalar, command);
  
     // Check (5) - There must be sufficient voice credits.
     // The check ensure that currentVoiceCreditBalance + (currentVotesForOption) >= (voteWeight).
@@ -74,7 +76,7 @@ template MessageValidatorNonQv() {
     // When all five checks are correct, then isValid = 1.
     var computedIsUpdateValid = IsEqual()(
         [
-            5,
+            TOTAL_CHECKS,
             computedIsSignatureValid + 
             computedAreVoiceCreditsSufficient +
             computedIsNonceValid +

package/circom/utils/non-qv/{stateLeafAndBallotTransformer.circom → StateLeafAndBallotTransformer.circom}

@@ -3,7 +3,7 @@ pragma circom 2.0.0;
 // circomlib import
 include "./mux1.circom";
 // local import
-include "./messageValidator.circom";
+include "./MessageValidator.circom";
 
 /**
  * Processes a command by verifying its validity and updates the state leaf and ballot accordingly. 
@@ -13,18 +13,18 @@ include "./messageValidator.circom";
  */
 template StateLeafAndBallotTransformerNonQv() {
     // Length of the packed command.
-    var PACKED_CMD_LENGTH = 4;
+    var PACKED_COMMAND_LENGTH = 4;
 
     // Number of user sign-ups in the state tree.
-    signal input numSignUps;
+    signal input totalSignups;
     // Number of valid vote options for the poll.
     signal input voteOptions;
 
     // The following signals represents a state leaf (signed up user).
     // Public key.
-    signal input slPubKey[2];
+    signal input stateLeafPublicKey[2];
     // Current voice credit balance.
-    signal input slVoiceCreditBalance;
+    signal input stateLeafVoiceCreditBalance;
 
     // The following signals represents a ballot.
     // Nonce.
@@ -34,29 +34,29 @@ template StateLeafAndBallotTransformerNonQv() {
 
     // The following signals represents a command.
     // State index of the user.
-    signal input cmdStateIndex;
+    signal input commandStateIndex;
     // Public key of the user.
-    signal input cmdNewPubKey[2];
+    signal input commandPublicKey[2];
     // Vote option index.
-    signal input cmdVoteOptionIndex;
+    signal input commandVoteOptionIndex;
     // Vote weight.
-    signal input cmdNewVoteWeight;
+    signal input commandNewVoteWeight;
     // Nonce.
-    signal input cmdNonce;
+    signal input commandNonce;
     // Poll identifier.
-    signal input cmdPollId;
+    signal input commandPollId;
     // Salt.
-    signal input cmdSalt;
-    // ECDSA signature of the command (R part).
-    signal input cmdSigR8[2];
-    // ECDSA signature of the command (S part).
-    signal input cmdSigS;
+    signal input commandSalt;
+    // EdDSA signature of the command (R part).
+    signal input commandSignaturePoint[2];
+    // EdDSA signature of the command (S part).
+    signal input commandSignatureScalar;
     // Packed command. 
     // nb. we are assuming that the packedCommand is always valid.
-    signal input packedCommand[PACKED_CMD_LENGTH];
+    signal input packedCommand[PACKED_COMMAND_LENGTH];
 
     // New state leaf (if the command is valid).
-    signal output newSlPubKey[2];
+    signal output newStateLeafPublicKey[2];
     // New ballot (if the command is valid).
     signal output newBallotNonce;
     
@@ -68,38 +68,38 @@ template StateLeafAndBallotTransformerNonQv() {
     signal output isVoteOptionIndexValid;
 
     // Check if the command / message is valid.
-    var (computedMessageValidator, computedIsStateLeafIndexValid, computedIsVoteOptionIndexValid) = MessageValidatorNonQv()(
-        cmdStateIndex,
-        numSignUps,
-        cmdVoteOptionIndex,
+    var (computedIsValid, computedIsStateLeafIndexValid, computedIsVoteOptionIndexValid) = MessageValidatorNonQv()(
+        commandStateIndex,
+        totalSignups,
+        commandVoteOptionIndex,
         voteOptions,
         ballotNonce,
-        cmdNonce,
+        commandNonce,
         packedCommand,
-        slPubKey,
-        cmdSigR8,
-        cmdSigS,
-        slVoiceCreditBalance,
+        stateLeafPublicKey,
+        commandSignaturePoint,
+        commandSignatureScalar,
+        stateLeafVoiceCreditBalance,
         ballotCurrentVotesForOption,
-        cmdNewVoteWeight
+        commandNewVoteWeight
     );
 
     // If the message is valid then we swap out the public key.
-    // This means using a Mux1() for pubKey[0] and another one
-    // for pubKey[1].
-    var computedNewSlPubKey0Mux = Mux1()([slPubKey[0], cmdNewPubKey[0]], computedMessageValidator);
-    var computedNewSlPubKey1Mux = Mux1()([slPubKey[1], cmdNewPubKey[1]], computedMessageValidator);
+    // This means using a Mux1() for publicKey[0] and another one
+    // for publicKey[1].
+    var computedNewstateLeafPublicKey0Mux = Mux1()([stateLeafPublicKey[0], commandPublicKey[0]], computedIsValid);
+    var computedNewstateLeafPublicKey1Mux = Mux1()([stateLeafPublicKey[1], commandPublicKey[1]], computedIsValid);
 
-    newSlPubKey[0] <== computedNewSlPubKey0Mux;
-    newSlPubKey[1] <== computedNewSlPubKey1Mux;
+    newStateLeafPublicKey[0] <== computedNewstateLeafPublicKey0Mux;
+    newStateLeafPublicKey[1] <== computedNewstateLeafPublicKey1Mux;
 
     // If the message is valid, then we swap out the ballot nonce
     // using a Mux1().
-    var computedNewBallotNonceMux = Mux1()([ballotNonce, cmdNonce], computedMessageValidator);
+    var computedNewBallotNonceMux = Mux1()([ballotNonce, commandNonce], computedIsValid);
 
     newBallotNonce <== computedNewBallotNonceMux;
 
-    isValid <== computedMessageValidator;
+    isValid <== computedIsValid;
     isStateLeafIndexValid <== computedIsStateLeafIndexValid;
     isVoteOptionIndexValid <== computedIsVoteOptionIndexValid;
 }

package/circom/utils/qv/{messageValidator.circom → MessageValidator.circom}

@@ -3,7 +3,7 @@ pragma circom 2.0.0;
 // zk-kit imports
 include "./safe-comparators.circom";
 // local imports
-include "../verifySignature.circom";
+include "../VerifySignature.circom";
 
 /**
  * Checks if a MACI message is valid or not.
@@ -11,12 +11,14 @@ include "../verifySignature.circom";
  */
 template MessageValidator() {
     // Length of the packed command.
-    var PACKED_CMD_LENGTH = 4;
+    var PACKED_COMMAND_LENGTH = 4;
+    // Number of checks to be performed.
+    var TOTAL_CHECKS = 6;
 
     // State index of the user.
     signal input stateTreeIndex;
     // Number of user sign-ups in the state tree.
-    signal input numSignUps;
+    signal input totalSignups;
     // Vote option index.
     signal input voteOptionIndex;
     // Number of valid vote options for the poll.
@@ -26,13 +28,13 @@ template MessageValidator() {
     // Command nonce.
     signal input nonce;
     // Packed command.
-    signal input cmd[PACKED_CMD_LENGTH];
+    signal input command[PACKED_COMMAND_LENGTH];
     // Public key of the state leaf (user).
-    signal input pubKey[2];
-    // ECDSA signature of the command (R part).
-    signal input sigR8[2];
-    // ECDSA signature of the command (S part).
-    signal input sigS;
+    signal input publicKey[2];
+    // EdDSA signature of the command (R part).
+    signal input signaturePoint[2];
+    // EdDSA signature of the command (S part).
+    signal input signatureScalar;
     // State leaf current voice credit balance.
     signal input currentVoiceCreditBalance;
     // Current number of votes for specific option. 
@@ -48,10 +50,10 @@ template MessageValidator() {
     signal output isVoteOptionIndexValid;
 
     // Check (1) - The state leaf index must be valid.
-    // The check ensure that the stateTreeIndex < numSignUps as first validation.
+    // The check ensure that the stateTreeIndex < totalSignups as first validation.
     // Must be < because the stateTreeIndex is 0-based. Zero is for blank state leaf
     // while 1 is for the first actual user.
-    var computedIsStateLeafIndexValid = SafeLessThan(252)([stateTreeIndex, numSignUps]);
+    var computedIsStateLeafIndexValid = SafeLessThan(252)([stateTreeIndex, totalSignups]);
 
     // Check (2) - The vote option index must be less than the number of valid vote options (0 indexed).
     var computedIsVoteOptionIndexValid = SafeLessThan(252)([voteOptionIndex, voteOptions]);
@@ -60,7 +62,7 @@ template MessageValidator() {
     var computedIsNonceValid = IsEqual()([originalNonce + 1, nonce]);
 
     // Check (4) - The signature must be correct.    
-    var computedIsSignatureValid = VerifySignature()(pubKey, sigR8, sigS, cmd);
+    var computedIsSignatureValid = VerifySignature()(publicKey, signaturePoint, signatureScalar, command);
 
     // Check (5) - There must be sufficient voice credits.
     // The check ensure that the voteWeight is < sqrt(field size)
@@ -79,7 +81,7 @@ template MessageValidator() {
     // When all six checks are correct, then isValid = 1.
     var computedIsUpdateValid = IsEqual()(
         [
-            6,
+            TOTAL_CHECKS,
             computedIsSignatureValid + 
             computedAreVoiceCreditsSufficient +
             computedIsVoteWeightValid +

package/circom/utils/qv/{stateLeafAndBallotTransformer.circom → StateLeafAndBallotTransformer.circom}

@@ -3,7 +3,7 @@ pragma circom 2.0.0;
 // circomlib import
 include "./mux1.circom";
 // local import
-include "./messageValidator.circom";
+include "./MessageValidator.circom";
 
 /**
  * Processes a command by verifying its validity and updates the state leaf and ballot accordingly. 
@@ -13,18 +13,18 @@ include "./messageValidator.circom";
  */
 template StateLeafAndBallotTransformer() {
     // Length of the packed command.
-    var PACKED_CMD_LENGTH = 4;
+    var PACKED_COMMAND_LENGTH = 4;
 
     // Number of user sign-ups in the state tree.
-    signal input numSignUps;
+    signal input totalSignups;
     // Number of valid vote options for the poll.
     signal input voteOptions;
 
     // The following signals represents a state leaf (signed up user).
     // Public key.
-    signal input slPubKey[2];
+    signal input stateLeafPublicKey[2];
     // Current voice credit balance.
-    signal input slVoiceCreditBalance;
+    signal input stateLeafVoiceCreditBalance;
 
     // The following signals represents a ballot.
     // Nonce.
@@ -34,29 +34,29 @@ template StateLeafAndBallotTransformer() {
 
     // The following signals represents a command.
     // State index of the user.
-    signal input cmdStateIndex;
+    signal input commandStateIndex;
     // Public key of the user.
-    signal input cmdNewPubKey[2];
+    signal input commandPublicKey[2];
     // Vote option index.
-    signal input cmdVoteOptionIndex;
+    signal input commandVoteOptionIndex;
     // Vote weight.
-    signal input cmdNewVoteWeight;
+    signal input commandNewVoteWeight;
     // Nonce.
-    signal input cmdNonce;
+    signal input commandNonce;
     // Poll identifier.
-    signal input cmdPollId;
+    signal input commandPollId;
     // Salt.
-    signal input cmdSalt;
-    // ECDSA signature of the command (R part).
-    signal input cmdSigR8[2];
-    // ECDSA signature of the command (S part).
-    signal input cmdSigS;
+    signal input commandSalt;
+    // EdDSA signature of the command (R part).
+    signal input commandSignaturePoint[2];
+    // EdDSA signature of the command (S part).
+    signal input commandSignatureScalar;
     // Packed command. 
     // nb. we are assuming that the packedCommand is always valid.
-    signal input packedCommand[PACKED_CMD_LENGTH];
+    signal input packedCommand[PACKED_COMMAND_LENGTH];
 
     // New state leaf (if the command is valid).
-    signal output newSlPubKey[2];
+    signal output newStateLeafPublicKey[2];
     // New ballot (if the command is valid).
     signal output newBallotNonce;
     
@@ -68,38 +68,38 @@ template StateLeafAndBallotTransformer() {
     signal output isVoteOptionIndexValid;
 
     // Check if the command / message is valid.
-    var (computedMessageValidator, computedIsStateLeafIndexValid, computedIsVoteOptionIndexValid) = MessageValidator()(
-        cmdStateIndex,
-        numSignUps,
-        cmdVoteOptionIndex,
+    var (computedIsValid, computedIsStateLeafIndexValid, computedIsVoteOptionIndexValid) = MessageValidator()(
+        commandStateIndex,
+        totalSignups,
+        commandVoteOptionIndex,
         voteOptions,
         ballotNonce,
-        cmdNonce,
+        commandNonce,
         packedCommand,
-        slPubKey,
-        cmdSigR8,
-        cmdSigS,
-        slVoiceCreditBalance,
+        stateLeafPublicKey,
+        commandSignaturePoint,
+        commandSignatureScalar,
+        stateLeafVoiceCreditBalance,
         ballotCurrentVotesForOption,
-        cmdNewVoteWeight
+        commandNewVoteWeight
     );
 
     // If the message is valid then we swap out the public key.
-    // This means using a Mux1() for pubKey[0] and another one
-    // for pubKey[1].
-    var computedNewSlPubKey0Mux = Mux1()([slPubKey[0], cmdNewPubKey[0]], computedMessageValidator);
-    var computedNewSlPubKey1Mux = Mux1()([slPubKey[1], cmdNewPubKey[1]], computedMessageValidator);
+    // This means using a Mux1() for publicKey[0] and another one
+    // for publicKey[1].
+    var computedNewstateLeafPublicKey0Mux = Mux1()([stateLeafPublicKey[0], commandPublicKey[0]], computedIsValid);
+    var computedNewstateLeafPublicKey1Mux = Mux1()([stateLeafPublicKey[1], commandPublicKey[1]], computedIsValid);
 
-    newSlPubKey[0] <== computedNewSlPubKey0Mux;
-    newSlPubKey[1] <== computedNewSlPubKey1Mux;
+    newStateLeafPublicKey[0] <== computedNewstateLeafPublicKey0Mux;
+    newStateLeafPublicKey[1] <== computedNewstateLeafPublicKey1Mux;
 
     // If the message is valid, then we swap out the ballot nonce
     // using a Mux1().
-    var computedNewBallotNonceMux = Mux1()([ballotNonce, cmdNonce], computedMessageValidator);
+    var computedNewBallotNonceMux = Mux1()([ballotNonce, commandNonce], computedIsValid);
 
     newBallotNonce <== computedNewBallotNonceMux;
 
-    isValid <== computedMessageValidator;
+    isValid <== computedIsValid;
     isStateLeafIndexValid <== computedIsStateLeafIndexValid;
     isVoteOptionIndexValid <== computedIsVoteOptionIndexValid;
 }

package/circom/utils/trees/BinaryMerkleRoot.circom

@@ -4,7 +4,7 @@ pragma circom 2.0.0;
 include "./mux1.circom";
 include "./comparators.circom";
 // local import
-include "../hashers.circom";
+include "../PoseidonHasher.circom";
 
 // @note taken from @zk-kit/circuits
 // if used directly in processMessages circom complains about duplicated
@@ -21,8 +21,16 @@ include "../hashers.circom";
 // NOTE: This circuit will successfully verify `out = 0` for `depth > MAX_DEPTH`.
 // Make sure to enforce `depth <= MAX_DEPTH` outside the circuit.
 template BinaryMerkleRoot(MAX_DEPTH) {
-    signal input leaf, depth, indices[MAX_DEPTH], siblings[MAX_DEPTH][1];
-
+    // The leaf node of the Merkle tree.
+    signal input leaf;
+    // The depth of the Merkle tree.
+    signal input depth;
+    // The indices of the leaf node in the Merkle tree.
+    signal input indices[MAX_DEPTH];
+    // The sibling nodes of the leaf node in the Merkle tree.
+    signal input siblings[MAX_DEPTH][1];
+
+    // The output of the Merkle tree root.
     signal output out;
 
     signal nodes[MAX_DEPTH + 1];

package/circom/utils/trees/CheckRoot.circom

@@ -1,7 +1,7 @@
 pragma circom 2.0.0;
 
 // local import
-include "../hashers.circom";
+include "../PoseidonHasher.circom";
 
 /**
  * Verifies the correct construction of a Merkle tree from a set of leaves.
@@ -10,36 +10,40 @@ include "../hashers.circom";
  */
 template CheckRoot(levels) {
     // The total number of leaves in the Merkle tree, calculated as 2 to the power of `levels`.
-    var totalLeaves = 2 ** levels;
+    var TOTAL_LEVELS = 2 ** levels;
     // The number of first-level hashers needed, equal to half the total leaves, as each hasher combines two leaves.
-    var numLeafHashers = totalLeaves / 2;
+    var LEAF_HASHERS = TOTAL_LEVELS / 2;
     // The number of intermediate hashers, one less than the number of leaf hashers, 
     // as each level of hashing reduces the number of hash elements by about half.
-    var numIntermediateHashers = numLeafHashers - 1;
+    var INTERMEDIATE_HASHERS = LEAF_HASHERS - 1;
     
     // Array of leaf values input to the circuit.
-    signal input leaves[totalLeaves];
+    signal input leaves[TOTAL_LEVELS];
 
     // Output signal for the Merkle root that results from hashing all the input leaves.
     signal output root;
 
     // Total number of hashers used in constructing the tree, one less than the total number of leaves,
     // since each level of the tree combines two elements into one.
-    var numHashers = totalLeaves - 1;
-    var computedLevelHashers[numHashers];
+    var hashersLength = TOTAL_LEVELS - 1;
+    var computedLevelHashers[hashersLength];
 
     // Initialize hashers for the leaves, each taking two adjacent leaves as inputs.
-    for (var i = 0; i < numLeafHashers; i++){
-        computedLevelHashers[i] = PoseidonHasher(2)([leaves[i*2], leaves[i*2+1]]);
+    for (var i = 0; i < LEAF_HASHERS; i++){
+        computedLevelHashers[i] = PoseidonHasher(2)([leaves[i * 2], leaves[i * 2 + 1]]);
     }
 
     // Initialize hashers for intermediate levels, each taking the outputs of two hashers from the previous level.
-    var k = 0;
-    for (var i = numLeafHashers; i < numLeafHashers + numIntermediateHashers; i++) {
-        computedLevelHashers[i] = PoseidonHasher(2)([computedLevelHashers[k*2], computedLevelHashers[k*2+1]]);
-        k++;
+    var index = 0;
+
+    for (var i = LEAF_HASHERS; i < LEAF_HASHERS + INTERMEDIATE_HASHERS; i++) {
+        computedLevelHashers[i] = PoseidonHasher(2)([
+            computedLevelHashers[index * 2],
+            computedLevelHashers[index * 2 + 1]
+        ]);
+        index++;
     }
 
     // Connect the output of the final hasher in the array to the root output signal.
-    root <== computedLevelHashers[numHashers-1];
+    root <== computedLevelHashers[hashersLength - 1];
 } 

package/circom/utils/trees/LeafExists.circom

@@ -6,7 +6,7 @@ include "./MerkleTreeInclusionProof.circom";
 /**
  * Ensures that a leaf exists within a Merkle tree with a given root.
  */
-template LeafExists(levels){
+template LeafExists(levels) {
   // The leaf whose existence within the tree is being verified.
   signal input leaf;
 

package/circom/utils/trees/{MerkleGeneratePathIndices.circom → MerklePathIndicesGenerator.circom}

@@ -3,27 +3,31 @@ pragma circom 2.0.0;
 // zk-kit imports
 include "./safe-comparators.circom";
 // local import
-include "../calculateTotal.circom";
+include "../CalculateTotal.circom";
 
 /**
  * Calculates the path indices required for Merkle proof verifications. 
  * Given a node index within an IMT and the total tree levels, it outputs the path indices leading to that node.
  * The template handles the modulo and division operations to break down the tree index into its constituent path indices.
  */
-template MerkleGeneratePathIndices(levels) {
+template MerklePathIndicesGenerator(levels) {
+    // The base used for the modulo and division operations, set to 2 for binary trees.
     var BASE = 2;
 
-    signal input in; 
+    // The total sum of the path indices.
+    signal input indices;
+
+    // The generated path indices.
     signal output out[levels];
 
-    var m = in;
+    var computedIndices = indices;
     var computedResults[levels];
 
     for (var i = 0; i < levels; i++) {
         // circom's best practices suggests to avoid using <-- unless you
         // are aware of what's going on. This is the only way to do modulo operation.
-        out[i] <-- m % BASE;
-        m = m \ BASE;
+        out[i] <-- computedIndices % BASE;
+        computedIndices = computedIndices \ BASE;
 
         // Check that each output element is less than the base.
         var computedIsOutputElementLessThanBase = SafeLessThan(3)([out[i], BASE]);
@@ -36,5 +40,5 @@ template MerkleGeneratePathIndices(levels) {
     // Check that the total sum matches the index.
     var computedCalculateTotal = CalculateTotal(levels)(computedResults);
 
-    computedCalculateTotal === in;
+    computedCalculateTotal === indices;
 } 

package/circom/utils/trees/MerkleTreeInclusionProof.circom

@@ -3,7 +3,7 @@ pragma circom 2.0.0;
 // circomlib import
 include "./mux1.circom";
 // local import
-include "../hashers.circom";
+include "../PoseidonHasher.circom";
 
 /**
  * Recomputes a Merkle root from a given leaf and its path in a Merkle tree.
@@ -16,6 +16,7 @@ template MerkleTreeInclusionProof(n_levels) {
     // Sibling node values required to compute the hash at each level.
     signal input path_elements[n_levels][1];
 
+    // The merkle root.
     signal output root;
 
      // Stores the hash at each level starting from the leaf to the root.
@@ -28,17 +29,17 @@ template MerkleTreeInclusionProof(n_levels) {
         path_index[i] * (1 - path_index[i]) === 0;
 
         // Configure the multiplexer based on the path index for the current level.
-        var c[2][2] = [
+        var multiplexer[2][2] = [
             [levelHashes[i], path_elements[i][0]],
             [path_elements[i][0], levelHashes[i]]
         ];
 
-        var mux[2] = MultiMux1(2)(
-            c,
+        var multiplexerResult[2] = MultiMux1(2)(
+            multiplexer,
             path_index[i]
         );
 
-        var computedLevelHash = PoseidonHasher(2)([mux[0], mux[1]]);
+        var computedLevelHash = PoseidonHasher(2)([multiplexerResult[0], multiplexerResult[1]]);
 
         // Store the resulting hash as the next level's hash.
         levelHashes[i + 1] <== computedLevelHash;

package/circom/utils/trees/incrementalQuinaryTree.circom

@@ -6,8 +6,8 @@ include "./mux1.circom";
 // zk-kit import
 include "./safe-comparators.circom";
 // local imports
-include "../calculateTotal.circom";
-include "../hashers.circom";
+include "../CalculateTotal.circom";
+include "../PoseidonHasher.circom";
 
 // Incremental Quintary Merkle Tree (IQT) verification circuits.
 // Since each node contains 5 leaves, we are using PoseidonT6 for hashing them.

package/circom/voter/PollJoined.circom

@@ -0,0 +1,43 @@
+pragma circom 2.0.0;
+
+// local imports
+include "../utils/PoseidonHasher.circom";
+include "../utils/PrivateToPublicKey.circom";
+include "../utils/trees/BinaryMerkleRoot.circom";
+
+// Poll Joined Circuit
+// Allows a user to prove that they have joined a MACI poll.
+// This is to be used with the MACI offchain implementation to allow 
+// users to authenticate to the relayer service (to reduce spamming).
+template PollJoined(stateTreeDepth) {
+    // Constants defining the tree structure
+    var STATE_TREE_ARITY = 2;
+
+    // User's private key
+    signal input privateKey;
+    // User's voice credits balance
+    signal input voiceCreditsBalance;
+    // Path elements
+    signal input pathElements[stateTreeDepth][STATE_TREE_ARITY - 1];
+    // Path indices
+    signal input pathIndices[stateTreeDepth];
+    // Poll State tree root which proves the user is joined
+    signal input stateRoot;
+    // The actual tree depth (might be <= stateTreeDepth) Used in BinaryMerkleRoot
+    signal input actualStateTreeDepth;
+
+     // User private to public key
+    var derivedPublicKey[2] = PrivateToPublicKey()(privateKey);
+
+    var stateLeaf = PoseidonHasher(3)([derivedPublicKey[0], derivedPublicKey[1], voiceCreditsBalance]);
+
+    // Inclusion proof  
+    var calculatedRoot = BinaryMerkleRoot(stateTreeDepth)(
+        stateLeaf,
+        actualStateTreeDepth,
+        pathIndices,
+        pathElements
+    );
+
+    calculatedRoot === stateRoot;
+}