@maci-protocol/circuits 0.0.0-ci.fd5247e → 0.0.0-ci.ffabe48

package/circom/coordinator/qv/processMessages.circom

@@ -10,7 +10,8 @@ include "../../utils/MessageHasher.circom";
 include "../../utils/MessageToCommand.circom";
 include "../../utils/PrivateToPublicKey.circom";
 include "../../utils/qv/StateLeafAndBallotTransformer.circom";
-include "../../utils/trees/incrementalQuinaryTree.circom";
+include "../../utils/trees/QuinaryTreeInclusionProof.circom";
+include "../../utils/trees/QuinaryGeneratePathIndices.circom";
 include "../../utils/trees/MerkleTreeInclusionProof.circom";
 include "../../utils/trees/LeafExists.circom";
 include "../../utils/trees/CheckRoot.circom";
@@ -205,20 +206,20 @@ template ProcessMessages(
     // Start from batchSize and decrement for process in reverse order.
     for (var i = batchSize - 1; i >= 0; i--) {
         // Process as vote type message.
-        var currentStateLeavesPathElement[stateTreeDepth][STATE_TREE_ARITY - 1];
-        var currentBallotPathElement[stateTreeDepth][STATE_TREE_ARITY - 1];
-        var currentVoteWeightsPathElement[voteOptionTreeDepth][VOTE_OPTION_TREE_ARITY - 1];
+        var computedCurrentStateLeavesPathElements[stateTreeDepth][STATE_TREE_ARITY - 1];
+        var computedCurrentBallotPathElements[stateTreeDepth][STATE_TREE_ARITY - 1];
+        var computedCurrentVoteWeightsPathElements[voteOptionTreeDepth][VOTE_OPTION_TREE_ARITY - 1];
         
         for (var j = 0; j < stateTreeDepth; j++) {
             for (var k = 0; k < STATE_TREE_ARITY - 1; k++) {
-                currentStateLeavesPathElement[j][k] = currentStateLeavesPathElements[i][j][k];
-                currentBallotPathElement[j][k] = currentBallotsPathElements[i][j][k];
+                computedCurrentStateLeavesPathElements[j][k] = currentStateLeavesPathElements[i][j][k];
+                computedCurrentBallotPathElements[j][k] = currentBallotsPathElements[i][j][k];
             }
         }
 
         for (var j = 0; j < voteOptionTreeDepth; j++) {
             for (var k = 0; k < VOTE_OPTION_TREE_ARITY - 1; k++) {
-                currentVoteWeightsPathElement[j][k] = currentVoteWeightsPathElements[i][j][k];
+                computedCurrentVoteWeightsPathElements[j][k] = currentVoteWeightsPathElements[i][j][k];
             }
         }
         
@@ -228,11 +229,11 @@ template ProcessMessages(
             ballotRoots[i + 1],
             actualStateTreeDepth,
             currentStateLeaves[i],
-            currentStateLeavesPathElement,
+            computedCurrentStateLeavesPathElements,
             currentBallots[i],
-            currentBallotPathElement,
+            computedCurrentBallotPathElements,
             currentVoteWeights[i],
-            currentVoteWeightsPathElement,
+            computedCurrentVoteWeightsPathElements,
             computedCommandsStateIndex[i],
             computedCommandsNewPublicKey[i],
             computedCommandsVoteOptionIndex[i],
@@ -388,9 +389,9 @@ template ProcessOne(stateTreeDepth, voteOptionTreeDepth) {
     commandNewVoteWeightSquare <== commandNewVoteWeight * commandNewVoteWeight;
 
     var commandVoteOptionIndexMux = Mux1()([0, commandVoteOptionIndex], computedIsVoteOptionIndexValid);
-    var computedCurrentVoteWeightPathIndices[voteOptionTreeDepth] = QuinGeneratePathIndices(voteOptionTreeDepth)(commandVoteOptionIndexMux);
+    var computedCurrentVoteWeightPathIndices[voteOptionTreeDepth] = QuinaryGeneratePathIndices(voteOptionTreeDepth)(commandVoteOptionIndexMux);
 
-    var computedCurrentVoteWeightQip = QuinTreeInclusionProof(voteOptionTreeDepth)(
+    var computedCurrentVoteWeightQip = QuinaryTreeInclusionProof(voteOptionTreeDepth)(
         currentVoteWeight,
         computedCurrentVoteWeightPathIndices,
         currentVoteWeightsPathElements
@@ -408,7 +409,7 @@ template ProcessOne(stateTreeDepth, voteOptionTreeDepth) {
     );
 
     // 5.1. Update the ballot's vote option root with the new vote weight.
-    var computedNewVoteOptionTreeQip = QuinTreeInclusionProof(voteOptionTreeDepth)(
+    var computedNewVoteOptionTreeQip = QuinaryTreeInclusionProof(voteOptionTreeDepth)(
         voteWeightMux,
         computedCurrentVoteWeightPathIndices,
         currentVoteWeightsPathElements

package/circom/coordinator/qv/tallyVotes.circom

@@ -8,7 +8,7 @@ include "./unpack-element.circom";
 include "../../utils/trees/CheckRoot.circom";
 include "../../utils/trees/MerklePathIndicesGenerator.circom";
 include "../../utils/trees/LeafExists.circom";
-include "../../utils/trees/incrementalQuinaryTree.circom";
+include "../../utils/trees/QuinaryCheckRoot.circom";
 include "../../utils/CalculateTotal.circom";
 include "../../utils/PoseidonHasher.circom";
 
@@ -18,22 +18,22 @@ include "../../utils/PoseidonHasher.circom";
  */
 template TallyVotes(
     stateTreeDepth,
-    intStateTreeDepth,
+    tallyProcessingStateTreeDepth,
     voteOptionTreeDepth
 ) {
     // Ensure there's at least one level in the vote option tree.
     assert(voteOptionTreeDepth > 0);
     // Ensure the intermediate state tree has at least one level.
-    assert(intStateTreeDepth > 0);
+    assert(tallyProcessingStateTreeDepth > 0);
     // The intermediate state tree must be smaller than the full state tree.
-    assert(intStateTreeDepth < stateTreeDepth); 
+    assert(tallyProcessingStateTreeDepth < stateTreeDepth); 
 
     // Number of children per node in the tree, defining the tree's branching factor.
     var TREE_ARITY = 5;
     var BALLOT_TREE_ARITY = 2;
 
     // The number of ballots processed at once, determined by the depth of the intermediate state tree.
-    var batchSize = BALLOT_TREE_ARITY ** intStateTreeDepth;
+    var batchSize = BALLOT_TREE_ARITY ** tallyProcessingStateTreeDepth;
     // Number of voting options available, determined by the depth of the vote option tree.
     var totalVoteOptions = TREE_ARITY ** voteOptionTreeDepth;
 
@@ -44,7 +44,7 @@ template TallyVotes(
     // Index for the voting option root in the ballot array.
     var BALLOT_VOTE_OPTION_ROOT_INDEX = 1;
     // Difference in tree depths, used in path calculations.
-    var STATE_INT_TREE_DEPTH_DIFFERENCE = stateTreeDepth - intStateTreeDepth;
+    var STATE_TREE_DEPTH_DIFFERENCE = stateTreeDepth - tallyProcessingStateTreeDepth;
 
     // Root of the state Merkle tree, representing the overall state before voting.
     signal input stateRoot;
@@ -64,7 +64,7 @@ template TallyVotes(
     signal input totalSignups;
     // Ballots and their corresponding path elements for verification in the tree.
     signal input ballots[batchSize][BALLOT_LENGTH];
-    signal input ballotPathElements[STATE_INT_TREE_DEPTH_DIFFERENCE][BALLOT_TREE_ARITY - 1];
+    signal input ballotPathElements[STATE_TREE_DEPTH_DIFFERENCE][BALLOT_TREE_ARITY - 1];
     signal input votes[batchSize][totalVoteOptions];
     // Current results for each vote option.
     signal input currentResults[totalVoteOptions];
@@ -100,11 +100,11 @@ template TallyVotes(
         computedBallotHashers[i] = PoseidonHasher(2)([ballots[i][BALLOT_NONCE_INDEX], ballots[i][BALLOT_VOTE_OPTION_ROOT_INDEX]]);
     }
 
-    var computedBallotSubroot = CheckRoot(intStateTreeDepth)(computedBallotHashers);
-    var computedBallotPathIndices[STATE_INT_TREE_DEPTH_DIFFERENCE] = MerklePathIndicesGenerator(STATE_INT_TREE_DEPTH_DIFFERENCE)(index / batchSize);
+    var computedBallotSubroot = CheckRoot(tallyProcessingStateTreeDepth)(computedBallotHashers);
+    var computedBallotPathIndices[STATE_TREE_DEPTH_DIFFERENCE] = MerklePathIndicesGenerator(STATE_TREE_DEPTH_DIFFERENCE)(index / batchSize);
 
     // Verifies each ballot's existence within the ballot tree.
-    LeafExists(STATE_INT_TREE_DEPTH_DIFFERENCE)(
+    LeafExists(STATE_TREE_DEPTH_DIFFERENCE)(
         computedBallotSubroot,
         ballotPathElements,
         computedBallotPathIndices,
@@ -114,7 +114,7 @@ template TallyVotes(
     // Processes vote options, verifying each against its declared root.
     var computedVoteTree[batchSize];
     for (var i = 0; i < batchSize; i++) {
-        computedVoteTree[i] = QuinCheckRoot(voteOptionTreeDepth)(votes[i]);
+        computedVoteTree[i] = QuinaryCheckRoot(voteOptionTreeDepth)(votes[i]);
         computedVoteTree[i] === ballots[i][BALLOT_VOTE_OPTION_ROOT_INDEX];
     }
 
@@ -227,7 +227,7 @@ template ResultCommitmentVerifier(voteOptionTreeDepth) {
     signal input newPerVoteOptionSpentVoiceCreditsRootSalt;
 
     // Compute the commitment to the current results.
-    var computedCurrentResultsRoot = QuinCheckRoot(voteOptionTreeDepth)(currentResults);
+    var computedCurrentResultsRoot = QuinaryCheckRoot(voteOptionTreeDepth)(currentResults);
 
     // Verify currentResultsCommitmentHash.
     var computedCurrentResultsCommitment = PoseidonHasher(2)([computedCurrentResultsRoot, currentResultsRootSalt]);
@@ -236,7 +236,7 @@ template ResultCommitmentVerifier(voteOptionTreeDepth) {
     var computedCurrentSpentVoiceCreditsCommitment = PoseidonHasher(2)([currentSpentVoiceCreditSubtotal, currentSpentVoiceCreditSubtotalSalt]);
 
     // Compute the root of the spent voice credits per vote option.
-    var computedCurrentPerVoteOptionSpentVoiceCreditsRoot = QuinCheckRoot(voteOptionTreeDepth)(currentPerVoteOptionSpentVoiceCredits);
+    var computedCurrentPerVoteOptionSpentVoiceCreditsRoot = QuinaryCheckRoot(voteOptionTreeDepth)(currentPerVoteOptionSpentVoiceCredits);
     var computedCurrentPerVoteOptionSpentVoiceCreditsCommitment = PoseidonHasher(2)([computedCurrentPerVoteOptionSpentVoiceCreditsRoot, currentPerVoteOptionSpentVoiceCreditsRootSalt]);
 
     // Commit to the current tally.
@@ -258,14 +258,14 @@ template ResultCommitmentVerifier(voteOptionTreeDepth) {
     isFirstCommitment === currentTallyCommitment;
 
     // Compute the root of the new results.
-    var computedNewResultsRoot = QuinCheckRoot(voteOptionTreeDepth)(newResults);
+    var computedNewResultsRoot = QuinaryCheckRoot(voteOptionTreeDepth)(newResults);
     var computedNewResultsCommitment = PoseidonHasher(2)([computedNewResultsRoot, newResultsRootSalt]);
 
     // Compute the commitment to the new spent voice credits value.
     var computedNewSpentVoiceCreditsCommitment = PoseidonHasher(2)([newSpentVoiceCreditSubtotal, newSpentVoiceCreditSubtotalSalt]);
 
     // Compute the root of the spent voice credits per vote option.
-    var computedNewPerVoteOptionSpentVoiceCreditsRoot = QuinCheckRoot(voteOptionTreeDepth)(newPerVoteOptionSpentVoiceCredits);
+    var computedNewPerVoteOptionSpentVoiceCreditsRoot = QuinaryCheckRoot(voteOptionTreeDepth)(newPerVoteOptionSpentVoiceCredits);
     var computedNewPerVoteOptionSpentVoiceCreditsCommitment = PoseidonHasher(2)([computedNewPerVoteOptionSpentVoiceCreditsRoot, newPerVoteOptionSpentVoiceCreditsRootSalt]);
 
     // Commit to the new tally.

package/circom/utils/CalculateTotal.circom

@@ -1,24 +1,24 @@
 pragma circom 2.0.0;
 
 /**
- * Computes the cumulative sum of an array of n input signals.
+ * Computes the cumulative sum of an array of length input signals.
  * It iterates through each input, aggregating the sum up to that point,
  * and outputs the total sum of all inputs. This template is useful for
  * operations requiring the total sum of multiple signals, ensuring the
  * final output reflects the cumulative total of the inputs provided.
  */
-template CalculateTotal(n) {
+template CalculateTotal(length) {
     // Array of values.
-    signal input nums[n];
+    signal input nums[length];
     // Total sum.
     signal output sum;
 
-    signal sums[n];
+    signal sums[length];
     sums[0] <== nums[0];
 
-    for (var i = 1; i < n; i++) {
+    for (var i = 1; i < length; i++) {
         sums[i] <== sums[i - 1] + nums[i];
     }
 
-    sum <== sums[n - 1];
+    sum <== sums[length - 1];
 }

package/circom/utils/full/MessageValidator.circom

@@ -1,7 +1,5 @@
 pragma circom 2.0.0;
 
-// circomlib import
-include "./mux1.circom";
 // zk-kit imports
 include "./safe-comparators.circom";
 // local imports
@@ -28,7 +26,7 @@ template MessageValidatorFull() {
     // Ballot nonce.
     signal input originalNonce;
     // Command nonce.
-    signal input nonce;
+    signal input commandNonce;
     // Packed command.
     signal input command[PACKED_COMMAND_LENGTH];
     // Public key of the state leaf (user).
@@ -61,7 +59,7 @@ template MessageValidatorFull() {
     var computedIsVoteOptionIndexValid = SafeLessThan(252)([voteOptionIndex, voteOptions]);
 
     // Check (3) - The nonce must be correct.    
-    var computedIsNonceValid = IsEqual()([originalNonce + 1, nonce]);
+    var computedIsNonceValid = IsEqual()([originalNonce + 1, commandNonce]);
 
     // Check (4) - The signature must be correct.    
     var computedIsSignatureValid = VerifySignature()(publicKey, signaturePoint, signatureScalar, command);

package/circom/utils/non-qv/MessageValidator.circom

@@ -26,7 +26,7 @@ template MessageValidatorNonQv() {
     // Ballot nonce.
     signal input originalNonce;
     // Command nonce.
-    signal input nonce;
+    signal input commandNonce;
     // Packed command.
     signal input command[PACKED_COMMAND_LENGTH];
     // Public key of the state leaf (user).
@@ -59,7 +59,7 @@ template MessageValidatorNonQv() {
     var computedIsVoteOptionIndexValid = SafeLessThan(252)([voteOptionIndex, voteOptions]);
 
     // Check (3) - The nonce must be correct.    
-    var computedIsNonceValid = IsEqual()([originalNonce + 1, nonce]);
+    var computedIsNonceValid = IsEqual()([originalNonce + 1, commandNonce]);
 
     // Check (4) - The signature must be correct.    
     var computedIsSignatureValid = VerifySignature()(publicKey, signaturePoint, signatureScalar, command);

package/circom/utils/qv/MessageValidator.circom

@@ -26,7 +26,7 @@ template MessageValidator() {
     // Ballot nonce.
     signal input originalNonce;
     // Command nonce.
-    signal input nonce;
+    signal input commandNonce;
     // Packed command.
     signal input command[PACKED_COMMAND_LENGTH];
     // Public key of the state leaf (user).
@@ -59,7 +59,7 @@ template MessageValidator() {
     var computedIsVoteOptionIndexValid = SafeLessThan(252)([voteOptionIndex, voteOptions]);
 
     // Check (3) - The nonce must be correct.    
-    var computedIsNonceValid = IsEqual()([originalNonce + 1, nonce]);
+    var computedIsNonceValid = IsEqual()([originalNonce + 1, commandNonce]);
 
     // Check (4) - The signature must be correct.    
     var computedIsSignatureValid = VerifySignature()(publicKey, signaturePoint, signatureScalar, command);

package/circom/utils/trees/LeafExists.circom

@@ -13,13 +13,13 @@ template LeafExists(levels) {
   // The elements along the path needed for the inclusion proof.
   signal input path_elements[levels][1];
   // The indices indicating the path taken through the tree for the leaf.
-  signal input path_index[levels];
+  signal input path_indices[levels];
   // The root of the Merkle tree, against which the inclusion is verified.
   signal input root;
 
   var computedMerkleRoot = MerkleTreeInclusionProof(levels)(
     leaf,
-    path_index,
+    path_indices,
     path_elements
   );
 

package/circom/utils/trees/MerkleTreeInclusionProof.circom

@@ -12,7 +12,7 @@ template MerkleTreeInclusionProof(n_levels) {
     // The leaf node from which the Merkle root is calculated.
     signal input leaf;
     // Indices indicating left or right child for each level of the tree.
-    signal input path_index[n_levels];
+    signal input path_indices[n_levels];
     // Sibling node values required to compute the hash at each level.
     signal input path_elements[n_levels][1];
 
@@ -25,8 +25,8 @@ template MerkleTreeInclusionProof(n_levels) {
     levelHashes[0] <== leaf;
 
     for (var i = 0; i < n_levels; i++) {
-        // Validate path_index to be either 0 or 1, ensuring no other values.
-        path_index[i] * (1 - path_index[i]) === 0;
+        // Validate path_indices to be either 0 or 1, ensuring no other values.
+        path_indices[i] * (1 - path_indices[i]) === 0;
 
         // Configure the multiplexer based on the path index for the current level.
         var multiplexer[2][2] = [
@@ -36,7 +36,7 @@ template MerkleTreeInclusionProof(n_levels) {
 
         var multiplexerResult[2] = MultiMux1(2)(
             multiplexer,
-            path_index[i]
+            path_indices[i]
         );
 
         var computedLevelHash = PoseidonHasher(2)([multiplexerResult[0], multiplexerResult[1]]);

package/circom/utils/trees/QuinaryCheckRoot.circom

@@ -0,0 +1,54 @@
+pragma circom 2.0.0;
+
+// local imports
+include "../PoseidonHasher.circom";
+
+/**
+ * Computes the root of a quintary Merkle tree given a list of leaves.
+ * This template constructs a Merkle tree with each node having 5 children (quintary)
+ * and computes the root by hashing with Poseidon the leaves and intermediate nodes in the given order.
+ * The computation is performed by first hashing groups of 5 leaves to form the bottom layer of nodes,
+ * then recursively hashing groups of these nodes to form the next layer, and so on, until the root is computed.
+ */
+template QuinaryCheckRoot(levels) {
+    var LEAVES_PER_NODE = 5;
+    var totalLeaves = LEAVES_PER_NODE ** levels;
+    var numLeafHashers = LEAVES_PER_NODE ** (levels - 1); 
+
+    signal input leaves[totalLeaves];
+    signal output root;
+
+    // Determine the total number of hashers.
+    var numHashers = 0;
+    for (var i = 0; i < levels; i++) {
+        numHashers += LEAVES_PER_NODE ** i;
+    }
+
+    var computedHashers[numHashers]; 
+
+    // Initialize hashers for the leaves.
+    for (var i = 0; i < numLeafHashers; i++) {
+        computedHashers[i] = PoseidonHasher(5)([
+            leaves[i * LEAVES_PER_NODE + 0],
+            leaves[i * LEAVES_PER_NODE + 1],
+            leaves[i * LEAVES_PER_NODE + 2],
+            leaves[i * LEAVES_PER_NODE + 3],
+            leaves[i * LEAVES_PER_NODE + 4]
+        ]);
+    }
+
+    // Initialize hashers for intermediate nodes and compute the root.
+    var k = 0;
+    for (var i = numLeafHashers; i < numHashers; i++) {
+        computedHashers[i] = PoseidonHasher(5)([
+            computedHashers[k * LEAVES_PER_NODE + 0],
+            computedHashers[k * LEAVES_PER_NODE + 1],
+            computedHashers[k * LEAVES_PER_NODE + 2],
+            computedHashers[k * LEAVES_PER_NODE + 3],
+            computedHashers[k * LEAVES_PER_NODE + 4]
+        ]);
+        k++;
+    }
+
+    root <== computedHashers[numHashers - 1]; 
+}

package/circom/utils/trees/QuinaryGeneratePathIndices.circom

@@ -0,0 +1,44 @@
+pragma circom 2.0.0;
+
+// zk-kit import
+include "./safe-comparators.circom";
+// local imports
+include "../CalculateTotal.circom";
+
+/**
+ * Calculates the path indices required for Merkle proof verifications (e.g., QuinaryTreeInclusionProof, QuinaryLeafExists). 
+ * Given a node index within an IQT 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.
+ * e.g., if the index is 30 and the number of levels is 4, the output should be [0, 1, 1, 0].
+ */
+template QuinaryGeneratePathIndices(levels) {
+    // The number of leaves per node (tree arity)
+    var LEAVES_PER_NODE = 5;
+
+    // The index within the tree
+    signal input index;
+    // The generated path indices leading to the node of the provided index
+    signal output out[levels];
+
+    var indexModulus = index;
+    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] <-- indexModulus % LEAVES_PER_NODE;
+        indexModulus = indexModulus \ LEAVES_PER_NODE;
+
+        // Check that each output element is less than the base.
+        var computedIsOutputElementLessThanBase = SafeLessThan(3)([out[i], LEAVES_PER_NODE]);
+        computedIsOutputElementLessThanBase === 1;
+
+        // Re-compute the total sum.
+        computedResults[i] = out[i] * (LEAVES_PER_NODE ** i);
+    }
+    
+    // Check that the total sum matches the index.
+    var computedCalculateTotal = CalculateTotal(levels)(computedResults);
+
+    computedCalculateTotal === index;
+}

package/circom/utils/trees/QuinaryLeafExists.circom

@@ -0,0 +1,30 @@
+pragma circom 2.0.0;
+
+// local imports
+include "./QuinaryTreeInclusionProof.circom";
+
+/**
+ * Verifies if a given leaf exists within an IQT.
+ * Takes a leaf, its path to the root (specified by indices and path elements),
+ * and the root itself, to verify the leaf's inclusion within the tree.
+ */
+template QuinaryLeafExists(levels){
+    // The number of leaves per node (tree arity)
+    var LEAVES_PER_NODE = 5;
+    // Number of leaves per path level (excluding the leaf itself)
+    var LEAVES_PER_PATH_LEVEL = LEAVES_PER_NODE - 1;
+
+    // The leaf to check for inclusion
+    signal input leaf;
+    // The path indices at each level of the tree
+    signal input path_indices[levels];
+    // The sibling nodes at each level of the tree
+    signal input path_elements[levels][LEAVES_PER_PATH_LEVEL];
+    // The computed root of the tree
+    signal input root;
+
+    // Verify the Merkle path.
+    var computedRoot = QuinaryTreeInclusionProof(levels)(leaf, path_indices, path_elements);
+
+    root === computedRoot;
+}

package/circom/utils/trees/QuinarySelector.circom

@@ -0,0 +1,42 @@
+pragma circom 2.0.0;
+
+// zk-kit import
+include "./safe-comparators.circom";
+// local imports
+include "../CalculateTotal.circom";
+
+/**
+ * Selects an item from a list based on the given index.
+ * It verifies the index is within the valid range and then iterates over the inputs to find the match.
+ * For each item, it checks if its position equals the given index and if so, multiplies the item 
+ * by the result of the equality check, effectively selecting it.
+ * The sum of these results yields the selected item, ensuring only the item at the specified index be the output.
+ *
+ * nb. The number of items must be less than 8, and the index must be less than the number of items.
+ */
+template QuinarySelector(choices) {
+    // The input elements to select from.
+    signal input in[choices];
+    // The index of the element to select
+    signal input index;
+    // The selected total sum of the elements.
+    signal output out;
+    
+    // Ensure that index < choices.
+    var computedIndex = SafeLessThan(3)([index, choices]);
+    computedIndex === 1;
+
+    // Initialize an array to hold the results of equality checks.
+    var computedResults[choices];
+
+    // For each item, check whether its index equals the input index.
+    // The result is multiplied by the corresponding input value.
+    for (var i = 0; i < choices; i++) {
+        var computedIsIndexEqual = IsEqual()([i, index]);
+
+        computedResults[i] = computedIsIndexEqual * in[i];
+    }
+
+    // Calculate the total sum of the results array.
+    out <== CalculateTotal(choices)(computedResults);
+}

package/circom/utils/trees/QuinaryTreeInclusionProof.circom

@@ -0,0 +1,55 @@
+pragma circom 2.0.0;
+
+// local imports
+include "../PoseidonHasher.circom";
+include "./Splicer.circom";
+
+/**
+ * Computes the root of an IQT given a leaf, its path, and sibling nodes at each level of the tree. 
+ * It iteratively incorporates the leaf or the hash from the previous level with sibling nodes using 
+ * the Splicer to place the leaf or hash at the correct position based on path_indices. 
+ * Then, it hashes these values together with PoseidonHasher to move up the tree. 
+ * This process repeats for each level (levels) of the tree, culminating in the computation of the tree's root.
+ */
+template QuinaryTreeInclusionProof(levels) {
+    // The number of leaves per node (tree arity)
+    var LEAVES_PER_NODE = 5;
+    // Number of leaves per path level (excluding the leaf itself)
+    var LEAVES_PER_PATH_LEVEL = LEAVES_PER_NODE - 1;
+
+    // The leaf to check for inclusion
+    signal input leaf;
+    // The path indices at each level of the tree
+    signal input path_indices[levels];
+    // The sibling nodes at each level of the tree
+    signal input path_elements[levels][LEAVES_PER_PATH_LEVEL];
+    // The computed root of the tree
+    signal output root;
+
+    var currentLeaf = leaf;
+
+    // Iteratively hash each level of path_elements with the leaf or previous hash
+    for (var i = 0; i < levels; i++) {
+        var elements[LEAVES_PER_PATH_LEVEL];
+
+        for (var j = 0; j < LEAVES_PER_PATH_LEVEL; j++) {
+            elements[j] = path_elements[i][j];
+        }
+
+        var computedSplicedLeaf[LEAVES_PER_NODE] = Splicer(LEAVES_PER_PATH_LEVEL)(
+            elements, 
+            currentLeaf, 
+            path_indices[i]
+        );
+
+        currentLeaf = PoseidonHasher(5)([
+            computedSplicedLeaf[0],
+            computedSplicedLeaf[1],
+            computedSplicedLeaf[2],
+            computedSplicedLeaf[3],
+            computedSplicedLeaf[4]
+        ]);
+    }
+
+    root <== currentLeaf;
+}

package/circom/utils/trees/Splicer.circom

@@ -0,0 +1,76 @@
+pragma circom 2.0.0;
+
+// circomlib imports
+include "./mux1.circom";
+// zk-kit import
+include "./safe-comparators.circom";
+// local imports
+include "./QuinarySelector.circom";
+
+/**
+ * The output array contains the input items, with the leaf inserted at the
+ * specified index. For example, if input = [0, 20, 30, 40], index = 3, and
+ * leaf = 10, the output will be [0, 20, 30, 10, 40].
+ */
+template Splicer(numItems) {
+    // The number of output items (because only one item is inserted).
+    var NUM_OUTPUT_ITEMS = numItems + 1;
+
+    // The input items to splice.
+    signal input in[numItems];
+    // The leaf to insert.
+    signal input leaf;
+    // The index at which to insert the leaf.
+    signal input index;
+    // The output array containing the spliced items.
+    signal output out[NUM_OUTPUT_ITEMS];
+    
+    // There is a loop where the goal is to assign values to the output signal.
+    // 
+    //  | output[0] | output[1] | output[2] | ...
+    // 
+    // We can either assign the leaf, or an item from the `items` signal, to the output, using Mux1().
+    // The Mux1's selector is 0 or 1 depending on whether the index is equal to the loop counter.
+    // 
+    //  i --> [IsEqual] <-- index
+    //             |
+    //             v
+    //  leaf --> [Mux1] <-- <item from in>
+    //             |
+    //             v
+    //          output[m]
+    // 
+    // To obtain the value from <item from in>, we need to compute an item
+    // index (let it be `s`).
+    // 1. if index = 2 and i = 0, then s = 0
+    // 2. if index = 2 and i = 1, then s = 1
+    // 3. if index = 2 and i = 2, then s = 2
+    // 4. if index = 2 and i = 3, then s = 2
+    // 5. if index = 2 and i = 4, then s = 3
+    // We then wire `s`, as well as each item in `in` to a QuinarySelector.
+    // The output signal from the QuinarySelector is <item from in> and gets
+    // wired to Mux1 (as above).
+
+    var inputs[NUM_OUTPUT_ITEMS];
+
+    for (var i = 0; i < numItems; i++) {
+        inputs[i] = in[i];
+    }
+
+    inputs[NUM_OUTPUT_ITEMS - 1] = 0;
+
+    for (var i = 0; i < NUM_OUTPUT_ITEMS; i++) {
+        // Determines if current index is greater than the insertion index.
+        var computedIsIndexAfterInsertPoint = SafeGreaterThan(3)([i, index]);
+
+        // Calculates correct index for original items, adjusting for leaf insertion.
+        var computedAdjustedIndex = i - computedIsIndexAfterInsertPoint;
+
+        // Selects item from the original array or the leaf for insertion.
+        var computedQuinarySelected = QuinarySelector(NUM_OUTPUT_ITEMS)(inputs, computedAdjustedIndex);
+        var computedIsIndexEqual = IsEqual()([index, i]);
+        var mux = Mux1()([computedQuinarySelected, leaf], computedIsIndexEqual);
+
+        out[i] <== mux;
+    }
+}