@maci-protocol/circuits 0.0.0-ci.044d30d

package/circom/utils/trees/incrementalQuinaryTree.circom

@@ -0,0 +1,287 @@
+pragma circom 2.0.0;
+
+// circomlib imports
+include "./bitify.circom";
+include "./mux1.circom";
+// zk-kit import
+include "./safe-comparators.circom";
+// local imports
+include "../calculateTotal.circom";
+include "../hashers.circom";
+
+// Incremental Quintary Merkle Tree (IQT) verification circuits.
+// Since each node contains 5 leaves, we are using PoseidonT6 for hashing them.
+// 
+// nb. circom has some particularities which limit the code patterns we can use:
+//  - You can only assign a value to a signal once.
+//  - A component's input signal must only be wired to another component's output signal.
+//  - Variables can store linear combinations, and can also be used for loops,
+//    declaring sizes of things, and anything that is not related to inputs of a circuit.
+//  - The compiler fails whenever you try to mix invalid elements.
+//  - You can't use a signal as a list index.
+
+/**
+ * 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 QuinSelector(choices) {
+    signal input in[choices];
+    signal input index;
+    signal output out;
+    
+    // Ensure that index < choices.
+    var computedLtIndex = SafeLessThan(3)([index, choices]);
+    computedLtIndex === 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);
+}
+
+/**
+ * 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;
+
+    signal input in[numItems];
+    signal input leaf;
+    signal input index;
+    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 QuinSelector.
+    // The output signal from the QuinSelector 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 computedQuinSelected = QuinSelector(NUM_OUTPUT_ITEMS)(inputs, computedAdjustedIndex);
+        var computedIsIndexEqual = IsEqual()([index, i]);
+        var mux = Mux1()([computedQuinSelected, leaf], computedIsIndexEqual);
+
+        out[i] <== mux;
+    }
+}
+
+/**
+ * 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_index. 
+ * 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 QuinTreeInclusionProof(levels) {
+    var LEAVES_PER_NODE = 5;
+    var LEAVES_PER_PATH_LEVEL = LEAVES_PER_NODE - 1;
+
+    signal input leaf;
+    signal input path_index[levels];
+    signal input path_elements[levels][LEAVES_PER_PATH_LEVEL];
+    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_index[i]
+        );
+
+        currentLeaf = PoseidonHasher(5)([
+            computedSplicedLeaf[0],
+            computedSplicedLeaf[1],
+            computedSplicedLeaf[2],
+            computedSplicedLeaf[3],
+            computedSplicedLeaf[4]
+        ]);
+    }
+
+    root <== currentLeaf;
+}
+
+/**
+ * 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 QuinLeafExists(levels){
+    var LEAVES_PER_NODE = 5;
+    var LEAVES_PER_PATH_LEVEL = LEAVES_PER_NODE - 1;
+
+    signal input leaf;
+    signal input path_index[levels];
+    signal input path_elements[levels][LEAVES_PER_PATH_LEVEL];
+    signal input root;
+
+    // Verify the Merkle path.
+    var computedRoot = QuinTreeInclusionProof(levels)(leaf, path_index, path_elements);
+
+    root === computedRoot;
+}
+
+/**
+ * Checks if a list of leaves exists within an IQT, leveraging the PoseidonT6
+ * circuit for hashing. This can be used to verify the presence of multiple leaves.
+ */
+template QuinBatchLeavesExists(levels, batchLevels) {
+    var LEAVES_PER_NODE = 5;
+    var LEAVES_PER_PATH_LEVEL = LEAVES_PER_NODE - 1;
+    var LEAVES_PER_BATCH = LEAVES_PER_NODE ** batchLevels;
+
+    signal input root;
+    signal input leaves[LEAVES_PER_BATCH];
+    signal input path_index[levels - batchLevels];
+    signal input path_elements[levels - batchLevels][LEAVES_PER_PATH_LEVEL];
+
+    // Compute the subroot (= leaf).
+    var computedQuinSubroot = QuinCheckRoot(batchLevels)(leaves);
+
+    // Check if the Merkle path is valid
+    QuinLeafExists(levels - batchLevels)(computedQuinSubroot, path_index, path_elements, root);
+}
+
+/**
+ * Calculates the path indices required for Merkle proof verifications (e.g., QuinTreeInclusionProof, QuinLeafExists). 
+ * 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 QuinGeneratePathIndices(levels) {
+    var BASE = 5;
+
+    signal input in; 
+    signal output out[levels];
+
+    var m = in;
+    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;
+
+        // Check that each output element is less than the base.
+        var computedIsOutputElementLessThanBase = SafeLessThan(3)([out[i], BASE]);
+        computedIsOutputElementLessThanBase === 1;
+
+        // Re-compute the total sum.
+        computedResults[i] = out[i] * (BASE ** i);
+    }
+    
+    // Check that the total sum matches the index.
+    var computedCalculateTotal = CalculateTotal(levels)(computedResults);
+
+    computedCalculateTotal === in;
+}
+
+/**
+ * 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 QuinCheckRoot(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/verifySignature.circom

@@ -0,0 +1,117 @@
+pragma circom 2.0.0;
+
+// circomlib imports
+include "./compconstant.circom";
+include "./comparators.circom";
+include "./pointbits.circom";
+include "./bitify.circom";
+include "./escalarmulany.circom";
+include "./escalarmulfix.circom";
+// local imports
+include "./hashers.circom";
+
+/**
+ * Variant of the EdDSAPoseidonVerifier template from circomlib
+ * https://github.com/iden3/circomlib/blob/master/circuits/eddsa.circom
+ */
+template EdDSAPoseidonVerifier_patched() {
+    // The x and y coordinates of the public key.
+    signal input Ax;
+    signal input Ay;
+    // Signature scalar.
+    signal input S;
+    // The x and y coordinates of the signature point.
+    signal input R8x;
+    signal input R8y;
+    // Message hash.
+    signal input M;
+
+    signal output valid;
+
+    // Ensure S<Subgroup Order.
+    // convert the signature scalar S into its binary representation.
+    var computedNum2Bits[254] = Num2Bits(254)(S);
+
+    var computedCompConstantIn[254] = computedNum2Bits;
+    computedCompConstantIn[253] = 0;
+
+    // A component that ensures S is within a valid range, 
+    // comparing it against a constant representing the subgroup order.
+    var computedCompConstant = CompConstant(2736030358979909402780800718157159386076813972158567259200215660948447373040)(computedCompConstantIn);
+
+    // Calculate the h = H(R,A, msg).
+    var computedH2Bits[254] = Num2Bits_strict()(PoseidonHasher(5)([R8x, R8y, Ax, Ay, M]));
+
+    // These components perform point doubling operations on the public key
+    // to align it within the correct subgroup as part of the verification process.
+    var (computedDbl1XOut, computedDbl1YOut) = BabyDbl()(Ax, Ay);
+    var (computedDbl2XOut, computedDbl2YOut) = BabyDbl()(computedDbl1XOut, computedDbl1YOut);
+    var (computedDbl3XOut, computedDbl3YOut) = BabyDbl()(computedDbl2XOut, computedDbl2YOut);
+
+    // A component that performs scalar multiplication of the 
+    // adjusted public key by the hash output, essential for the verification calculation.
+    var computedEscalarMulAny[2] = EscalarMulAny(254)(computedH2Bits, [computedDbl3XOut, computedDbl3YOut]);
+
+    // Compute the right side: right =  R8 + right2.
+    var (computedAddRightXOut, computedAddRightYOut) = BabyAdd()(R8x, R8y, computedEscalarMulAny[0], computedEscalarMulAny[1]);
+
+    // Calculate the left side: left = S * B8.
+    var BASE8[2] = [
+        5299619240641551281634865583518297030282874472190772894086521144482721001553,
+        16950150798460657717958625567821834550301663161624707787222815936182638968203
+    ];
+    
+    // Fixed-base scalar multiplication of a base point by S.
+    var computedEscalarMulFix[2] = EscalarMulFix(254, BASE8)(computedNum2Bits);
+
+    // Components to check the equality of x and y coordinates 
+    // between the computed and expected points of the signature.
+    var computedIsRightValid = IsEqual()([computedEscalarMulFix[0], computedAddRightXOut]);
+    var computedIsLeftValid = IsEqual()([computedEscalarMulFix[1], computedAddRightYOut]);
+    var computedIsLeftRightValid = IsEqual()([computedIsRightValid + computedIsLeftValid, 2]);
+
+    // Components to handle edge cases and ensure that all conditions 
+    // for a valid signature are met, including the 
+    // public key not being zero and other integrity checks.
+    var computedIsAxZero = IsZero()(Ax);
+    var computedIsAxEqual = IsEqual()([computedIsAxZero, 0]);
+    var computedIsCcZero = IsZero()(computedCompConstant);
+    var computedIsValid = IsEqual()([computedIsLeftRightValid + computedIsAxEqual + computedIsCcZero, 3]);
+
+    valid <== computedIsValid;
+}
+
+/**
+ * Verifies the EdDSA signature for a given command, which has exactly four elements in the hash preimage.
+ */
+template VerifySignature() {
+    // Public key of the signer, consisting of two coordinates [x, y].
+    signal input pubKey[2];
+    // R8 point from the signature, consisting of two coordinates [x, y]. 
+    signal input R8[2];
+    // Scalar component of the signature.
+    signal input S;
+
+    // Number of elements in the hash preimage.
+    var k = 4;
+    
+    // The preimage data that was hashed, an array of four elements.
+    signal input preimage[k];
+
+    signal output valid;
+
+    // Hash the preimage using the Poseidon hashing function configured for four inputs.
+    var computedM = PoseidonHasher(4)(preimage);
+
+    // Instantiate the patched EdDSA Poseidon verifier with the necessary inputs.
+    var computedVerifier = EdDSAPoseidonVerifier_patched()(
+        pubKey[0],
+        pubKey[1],
+        S,
+        R8[0],
+        R8[1],
+        computedM
+    );
+
+    valid <== computedVerifier;
+}

package/circom/voter/poll.circom

@@ -0,0 +1,92 @@
+pragma circom 2.0.0;
+
+// local imports
+include "../utils/hashers.circom";
+include "../utils/privToPubKey.circom";
+include "../utils/trees/BinaryMerkleRoot.circom";
+
+// Poll Joining Circuit
+// Allows a user to prove knowledge of a private key that is signed up to 
+// a MACI contract.
+template PollJoining(stateTreeDepth) {
+    // Constants defining the tree structure
+    var STATE_TREE_ARITY = 2;
+
+    // User's private key
+    signal input privKey;
+    // Poll's public key
+    signal input pollPubKey[2];
+    // Siblings
+    signal input siblings[stateTreeDepth][STATE_TREE_ARITY - 1];
+    // Indices
+    signal input indices[stateTreeDepth];
+    // User's hashed private key
+    signal input nullifier;
+    // MACI State tree root which proves the user is signed up
+    signal input stateRoot;
+    // The actual tree depth (might be <= stateTreeDepth) used in BinaryMerkleRoot
+    signal input actualStateTreeDepth;
+    // The poll id
+    signal input pollId;
+
+    // Compute the nullifier (hash of private key and poll id)
+    var computedNullifier = PoseidonHasher(2)([privKey, pollId]);
+    nullifier === computedNullifier;
+
+    // User private to public key
+    var derivedPubKey[2] = PrivToPubKey()(privKey);
+    // Hash the public key
+    var pubKeyHash = PoseidonHasher(2)([derivedPubKey[0], derivedPubKey[1]]);
+
+    // Ensure the poll public key is the same as the maci one (public input)
+    derivedPubKey[0] === pollPubKey[0];
+    derivedPubKey[1] === pollPubKey[1];
+
+    // Inclusion proof  
+    var calculatedRoot = BinaryMerkleRoot(stateTreeDepth)(
+        pubKeyHash,
+        actualStateTreeDepth,
+        indices,
+        siblings
+    );
+
+    calculatedRoot === stateRoot;
+}
+
+// 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 privKey;
+    // 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 derivedPubKey[2] = PrivToPubKey()(privKey);
+
+    var stateLeaf = PoseidonHasher(3)([derivedPubKey[0], derivedPubKey[1], voiceCreditsBalance]);
+
+    // Inclusion proof  
+    var stateLeafQip = BinaryMerkleRoot(stateTreeDepth)(
+        stateLeaf,
+        actualStateTreeDepth,
+        pathIndices,
+        pathElements
+    );
+
+    stateLeafQip === stateRoot;
+}
+

package/circomkit.json

@@ -0,0 +1,18 @@
+{
+  "protocol": "groth16",
+  "prime": "bn128",
+  "version": "2.1.6",
+  "circuits": "./circom/circuits.json",
+  "dirPtau": "./ptau",
+  "dirCircuits": "./circom",
+  "dirInputs": "./inputs",
+  "dirBuild": "./build",
+  "optimization": 2,
+  "inspect": false,
+  "include": ["./node_modules/circomlib/circuits", "./node_modules/@zk-kit/circuits/circom"],
+  "groth16numContributions": 0,
+  "groth16askForEntropy": false,
+  "logLevel": "INFO",
+  "verbose": true,
+  "cWitness": true
+}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@maci-protocol/circuits",
+  "version": "0.0.0-ci.044d30d",
+  "private": false,
+  "description": "zk-SNARK circuits for MACI",
+  "main": "build/ts/index.js",
+  "files": [
+    "build",
+    "circom",
+    "circomkit.json",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build-test-circuits-c": "ts-node ./ts/compile.ts --cWitness",
+    "build-test-circuits-wasm": "ts-node ./ts/compile.ts",
+    "gen-zkeys": "ts-node ./ts/genZkeys.ts",
+    "info": "NODE_OPTIONS=--max-old-space-size=4096 ts-node ./ts/info.ts",
+    "watch": "tsc --watch",
+    "build": "tsc -p tsconfig.build.json",
+    "circom:build": "NODE_OPTIONS=--max-old-space-size=4096 circomkit compile",
+    "circom:setup": "NODE_OPTIONS=--max-old-space-size=4096 circomkit setup",
+    "types": "tsc -p tsconfig.json --noEmit",
+    "mocha-test": "NODE_OPTIONS=--max-old-space-size=4096 ts-mocha --exit -g '^(?!.*\\[fuzz\\]).*$'",
+    "test": "pnpm run mocha-test ts/__tests__/*.test.ts",
+    "test:fuzz": "NODE_OPTIONS=--max-old-space-size=4096 ts-mocha --exit -g '\\[fuzz\\]' ./ts/__tests__/*.test.ts",
+    "test:hasher": "pnpm run mocha-test ts/__tests__/Hasher.test.ts",
+    "test:slAndBallotTransformer": "pnpm run mocha-test ts/__tests__/StateLeafAndBallotTransformer.test.ts",
+    "test:messageToCommand": "pnpm run mocha-test ts/__tests__/MessageToCommand.test.ts",
+    "test:messageValidator": "pnpm run mocha-test ts/__tests__/MessageValidator.test.ts",
+    "test:verifySignature": "pnpm run mocha-test ts/__tests__/VerifySignature.test.ts",
+    "test:privToPubKey": "pnpm run mocha-test ts/__tests__/PrivToPubKey.test.ts",
+    "test:calculateTotal": "pnpm run mocha-test ts/__tests__/CalculateTotal.test.ts",
+    "test:processMessages": "pnpm run mocha-test ts/__tests__/ProcessMessages.test.ts",
+    "test:tallyVotes": "pnpm run mocha-test ts/__tests__/TallyVotes.test.ts",
+    "test:ceremonyParams": "pnpm run mocha-test ts/__tests__/CeremonyParams.test.ts",
+    "test:incrementalQuinaryTree": "pnpm run mocha-test ts/__tests__/IncrementalQuinaryTree.test.ts",
+    "test:pollJoining": "pnpm run mocha-test ts/__tests__/PollJoining.test.ts",
+    "test:pollJoined": "pnpm run mocha-test ts/__tests__/PollJoined.test.ts"
+  },
+  "dependencies": {
+    "@maci-protocol/core": "0.0.0-ci.044d30d",
+    "@maci-protocol/crypto": "0.0.0-ci.044d30d",
+    "@maci-protocol/domainobjs": "0.0.0-ci.044d30d",
+    "@maci-protocol/sdk": "0.0.0-ci.044d30d",
+    "@zk-kit/circuits": "^0.4.0",
+    "circomkit": "^0.3.2",
+    "circomlib": "^2.0.5"
+  },
+  "devDependencies": {
+    "@types/chai": "^4.3.11",
+    "@types/chai-as-promised": "^7.1.8",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^22.14.0",
+    "@types/snarkjs": "^0.7.9",
+    "@zk-kit/baby-jubjub": "^1.0.3",
+    "chai": "^4.3.10",
+    "chai-as-promised": "^7.1.2",
+    "fast-check": "^4.1.0",
+    "glob": "^11.0.1",
+    "mocha": "^11.1.0",
+    "ts-mocha": "^11.1.0",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.8.3"
+  },
+  "gitHead": "5a5bf7a30836932641c6da5e3236d0f2e89aea16"
+}