@maci-protocol/website 0.0.0-ci.1e276ed

package/versioned_docs/version-v0.x/quadratic-vote-tallying-circuit.md

@@ -0,0 +1,138 @@
+---
+title: MACI v0.x quadratic vote tallying circuit
+sidebar_label: "Circuit: quadratic vote tallying"
+sidebar_position: 5
+---
+
+# The quadratic vote tallying circuit
+
+Quadratic voting is one of many types of vote tallying mechanisms. We chose it for the first version of MACI due to the high amount of interest that the community has shown for it.
+
+Quadratic voting allows users to express the strength of their preferences when they vote for options. Since users are allocated a limited number of _voice credits_, and the number of tallied votes per option is the square root of the number of voice credits spent on said option, quadratic voting [over-privileges neither concentrated nor diffuse interests](https://vitalik.eth.limo/general/2019/12/07/quadratic.html).
+
+For instance, if a user has 99 voice credits, they may spend them this way (each row represents a command):
+
+| Option | Voice credits spent |
+| ------ | ------------------- |
+| A      | 1                   |
+| A      | 9                   |
+| B      | 25                  |
+| C      | 64                  |
+
+The outcome is as such:
+
+| Option | Tallied votes |
+| ------ | ------------- |
+| A      | 3.16          |
+| B      | 5             |
+| C      | 8             |
+
+Even though the user has a disproportionate preference for option C (64 voice credits), their impact on the tallied vote (8 votes) is merely the square root of the voice credits they have spent. This prevents them from having an outsized influence on the results simply by virtue of their willingness to spend as many voice credits on that option as they had.
+
+Additionally, we consider that votes are cumulative. This means that the user spent 10 voice credits on option A.
+
+The MACI contract's `quadraticVoteTally()` function should verify a proof created using this circuit to compute the results of tallying a set of state leaves. This also proves that these state leaves have an intermediate root `A`, as well that `A` is part of the tree with final state root `R`. This allows the coordinator to prove the final tally in batches. The function keeps track of the index of each intermediate root to ensure that they are processed consecutively.
+
+## Inputs
+
+| Pseudocode name               | zk-SNARK input type | Description                                                                                                | Set by      |
+| ----------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------- | ----------- |
+| `fullStateRoot`               | Public              | The final Merkle root of the state tree                                                                    | Contract    |
+| `fullStateTreeDepth`          | Hardcoded           | The depth of the state tree                                                                                | Contract    |
+| `intermediateStateTreeDepth`  | Hardcoded           | The depth of the intermediate state tree                                                                   | Contract    |
+| `intermediateStateRoot`       | Public              | The intermediate Merkle root generated by the given state leaves                                           | Contract    |
+| `intermediatePathElements[k]` | Private             | The Merkle path elements from `intermediateStateRoot` to `stateRoot`.                                      | Coordinator |
+| `intermediatePathIndex`       | Public              | The Merkle path index from `intermediateStateRoot` to `stateRoot`.                                         | Contract    |
+| `currentResults[n]`           | Private             | The vote tally of all prior batches of state leaves                                                        | Coordinator |
+| `currentResultsSalt`          | Private             | A random value to hash with the vote tally for state leaves up to the current batch                        | Coordinator |
+| `currentResultsCommitment`    | Public              | The salted commitment of the values in `currentResults`                                                    | Contract    |
+| `newResultsCommitment`        | Public              | The salted commitment of the vote tally for this batch of leaves plus the vote tally from `currentResults` | Contract    |
+| `salt`                        | Private             | A random value to hash with the culmulate vote tally for this batch of state leaves                        | Coordinator |
+| `stateLeaves[m][p]`           | Private             | The batch of leaves of the state tree to tally.                                                            | Coordinator |
+| `voteLeaves[m][n]`            | Private             | The vote leaves for each user in this batch of state leaves.                                               | Coordinator |
+
+`n` is the number of options in `voteOptionTree`.
+`m` is the number of state leaves in this batch.
+`k` is `fullStateTreeDepth - intermediateStateTreeDepth`
+`p` is the message length
+
+A result commitment is the hash of a Merkle root of all the vote leaves, and a salt. For instance:
+
+```javascript
+root = genTree(results);
+hash(root, salt);
+```
+
+## Circuit pseudocode
+
+```javascript
+// Alice votes for party A with 16 credits
+// Bob votes for party A with 9 credits
+
+// Party A gets 7 tallied votes. NOT 5 votes.
+
+// Ensure via a constraint that the intermediate root is the
+// correct Merkle root of the stateLeaves passed into this
+// snark
+assert(intermediateStateRoot == genTree(stateLeaves))
+
+// Ensure via a constraint that the intermediate root is part of the full state tree
+var x = generateMerkleRoot(
+    intermediatePathElements,
+    intermediatePathIndex,
+    intermediateRoot
+)
+
+assert(x == stateRoot)
+
+// This variable stores the sum of the square roots of each
+// user's voice credits per option.
+var computedResults = currentResults
+
+var start = 1
+if intermediatePathIndex > 0:
+    start = 0
+
+// For each user
+for i as start to m: // we ignore leaf 0 on purpose
+
+    // Ensure via a constraint that the voteLeaves for this
+    // user is correct (such that when each vote leaf is
+    // inserted into an MT, the Merkle root matches
+    // the `voteOptionTreeRoot` field of the state leaf)
+
+    var computedVoteOptionTreeRoot = genTree(voteLeaves[i])
+    assert(computedVoteOptionTreeRoot == stateLeaves[i].voteOptionTreeRoot)
+
+    // Calculate the sum of votes for each option
+    for j as 0 to n.
+        // This adds to the subtotal from previous batches
+        // of state leaves
+        computedResults[j] += voteLeaves[i][j]
+
+
+// Ensure via a constraint that the commitment to the current results is
+// correct
+
+assert(
+    hash(genTree(currentResults), currentResultsSalt) ==
+    currentResultsCommitment
+)
+
+// Ensure via a constraint that the final result
+// is correct
+assert(
+    hash(genTree(computedResults), salt) ==
+    newResultsCommitment
+)
+```
+
+where `genTree` is pseudocode for a circuit which computes a Merkle root from a list of leaves.
+
+## Circuit failure modes
+
+| Condition                                                                                          | Outcome                        |
+| -------------------------------------------------------------------------------------------------- | ------------------------------ |
+| Invalid state leaves and/or intermediate state root                                                | No such proof can be generated |
+| Invalid vote option leaves                                                                         | No such proof can be generated |
+| Invalid Merkle path to the full state root from the intermediate state root for the batch of votes | No such proof can be generated |

package/versioned_docs/version-v0.x/state-root-transition-circuit.md

@@ -0,0 +1,230 @@
+---
+title: MACI v0.x state root transition proof circuit
+sidebar_label: "Circuit: state root transition proof"
+sidebar_position: 4
+---
+
+# The state root transition proof circuit
+
+This circuit proves the correctness of each state root transition.
+
+## Public Inputs
+
+All public inputs are set by the contract.
+
+| Pseudocode name            | Description                                                                             |
+| -------------------------- | --------------------------------------------------------------------------------------- |
+| `coordinatorPubKey`        | The coordinator's public key                                                            |
+| `currentStateRoot`         | The current state root                                                                  |
+| `msgTreeRoot`              | The Merkle root of the message tree                                                     |
+| `msgTreePathIndex`         | The Merkle path index of the message in the message tree                                |
+| `maxStateLeafIndex`        | The maximum leaf index of the state tree                                                |
+| `userCurrentLeafPathIndex` | The Merkle path index from the user's latest valid state leaf to the current state root |
+| `newStateRoot`             | The new state root                                                                      |
+
+## Private Inputs
+
+All private inputs are set by the coordinator.
+
+| Pseudocode name                    | Description                                                                                                                                    |
+| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `userCurrentLeafPathElements`      | The Merkle path elements from the user's latest valid state leaf to the current state root                                                     |
+| `currentVoteOptionPathElements[n]` | The Merkle path needed to prove the existence of the current vote option leaf. Size is `253` \* `vote_option_tree_depth` bits                  |
+| `newVoteOptionPathElements[n]`     | The Merkle path needed to update the vote option tree root in the state leaf. Size is `253` \* `vote_option_tree_depth` bits                   |
+| `currentVoteWeight`                | In the quadratic voting use case, this is the square root of the number of voice credits a user wishes to spend on this vote. Size is 32 bits. |
+| `message`                          | The message                                                                                                                                    |
+| `msgTreePathElements`              | The Merkle path elements to the message tree root from the message leaf                                                                        |
+| `randomLeaf`                       | Random data                                                                                                                                    |
+| `newStateTreePathIndex`            | The Merkle path index to the new state root from the new state leaf                                                                            |
+| `newStateTreePathElements`         | The Merkle path elements to the new state root from the new state leaf                                                                         |
+| `newStateTreePathElementsToZero`   | The Merkle path elements to the new state root from leaf 0, **after** the new state leaf has been updated                                      |
+| `userCurrentLeaf`                  | The user's latest valid state leaf                                                                                                             |
+| `command`                          | The command to process. Includes all the details in the leaf.                                                                                  |
+| `noOp`                             | The no-op flag                                                                                                                                 |
+| `userPubKey`                       | The public key associated with the private key used to sign the command                                                                        |
+| `encPubKey`                        | The ephemeral public key used to generate the ECDH shared key which was used to encrypt the command.                                           |
+| `coordinatorPrivKey`               | The coordinator's private key.                                                                                                                 |
+
+For the sake of simplicity, in this specification, we assume that there is no batching of commands and we handle each command one at a time.
+
+## Check 1: That the message has been encrypted with the correct key
+
+```javascript
+// Derive the coordinator's public key from
+// their private key
+var derivedCoordinatorPubKey = eddsaDerivePubKey(coordinatorPrivKey);
+
+// Ensure via a constraint that it matches the
+// coordinator's public key given as an input
+assert(derivedCoordinatorPubKey == coordinatorPubKey);
+
+// Generate the ECDH key
+var ecdhSharedKey = genEcdhKey(coordinatorPrivKey, encPubKey);
+
+// Use the ECDH shared key to decrypt the message
+var decryptedCommand = decrypt(ecdhSharedKey, message);
+
+// Ensure via a constraint that the message has been correctly decrypted
+assert(decryptedCommand == command);
+```
+
+## Check 2: that the message is part of the message tree
+
+```javascript
+var generatedMsgTreeRoot = generateMerkleRoot(msgTreePathElements, msgTreePathIndex, message);
+
+assert(generatedMsgTreeRoot, msgTreeRoot);
+```
+
+## Check 3: that the new state root transition is the correct result of executing the given command — _or_ — that the command is invalid and the no-op flag is set to true.
+
+## Circuit logic
+
+The message should already have been decrypted to `decryptedCommand` (see above).
+
+```javascript
+/***********************************
+This function generates a state leaf
+***********************************/
+function generateStateLeaf(
+    command,
+    computedNewVoteOptionRoot,
+    newVoiceCreditBalance
+) => {
+
+    return [
+        command.newPublicKeyX,
+        command.newPublicKeyY,
+        computedNewVoteOptionRoot,
+        newVoiceCreditBalance,
+        command.nonce + 1
+    ]
+}
+
+/*************************
+// The main circuit logic:
+**************************/
+
+// Record in a variable that the new state leaf index is
+// valid (i.e. it is leq to the maximum allowed value)
+var validStateLeafIndex = newStateTreePathIndex <= maxStateLeafIndex && newStateTreePathIndex > 0
+
+// Record in a variable if the signature is valid
+var validSignature = verifyEddsa(signature, decryptedCommand, userPubKey)
+
+// Record in a variable if the nonce is correct
+var correctNonce = decryptedCommand.nonce == userCurrentLeaf.nonce + 1
+
+// Prove that the user's current leaf is part of the
+// Merkle tree. Note that this check is independent of
+// the noOp flag. As such, the coordinator cannot
+// create an invalid proof by tampering with the
+// Merkle proof and setting noOp to true; the Merkle proof
+// *must* be valid.
+var x = generateMerkleRoot(
+    userCurrentLeafPathElements,
+    userCurrentLeafPathIndex,
+    userCurrentLeaf
+)
+
+assert(x == currentStateRoot)
+
+// Prove that the current vote option weight (leaf)
+// input is correct by checking that it exists in the
+// tree at the given index
+var y = generateMerkleRoot(
+    decryptedCommand.currentVoteOptionPathElements,
+    decryptedCommand.voteOptionIndex,
+    decryptedCommand.currentVoteWeight
+)
+
+assert(y == userCurrentLeaf.voteOptionTreeRoot)
+
+// Record in a variable if the user has enough
+// voice credits
+
+var newVoiceCreditBalance =
+    userCurrentLeaf.voiceCreditBalance +
+    (decryptedCommand.currentVoteWeight ^ 2) -
+    (decryptedCommand.newVoteWeight ^ 2)
+
+var enoughVoiceCredits = newVoiceCreditBalance >= 0
+
+// Record in a variable if the new leaf's vote option
+// tree root is the correct result of updating the
+// vote option leaf.
+var computedNewVoteOptionRoot =
+    updateMerkleTree(
+        command.voteOptionIndex,
+        command.voteOptionPath,
+        command.voteWeight,
+        decryptedCommand.newVoteWeight
+    )
+
+assert(newStateLeaf.voteOptionRoot == computedNewVoteOptionRoot)
+    newStateLeaf.voteOptionRoot == computedNewVoteOptionRoot
+
+// Record in a variable if the vote option index is
+// within a permissible range (0 to 2 ** vote option tree
+// depth, inclusive) where VOTE_OPTION_TREE_DEPTH is
+// not an input, but rather hardcoded during the trusted
+// setup.
+var validVoteOptionTreeIndex = command.voteOptionIndex < VOTE_OPTION_TREE_DEPTH
+
+var newStateLeaf = generateStateLeaf(
+    command,
+    computedNewVoteOptionRoot,
+    newVoiceCreditBalance
+)
+
+if (enoughVoiceCredits &&
+    correctNonce &&
+    validSignature &&
+    validStateLeafIndex &&
+    validVoteOptionTreeIndex
+):
+    // Use a constraint to ensure that the no-op flag
+    // is set to false
+    assert(noOp == false)
+
+
+    // Generate the new state root.
+    var s = merkleTreeUpdate(
+        newStateTreePathIndex
+        newStateLeaf,
+        currentStateRoot,
+        newStateTreePathElements
+    )
+
+    // Update the leaf at index `0` to generate a new state
+    // root, and ensure via a constraint that it is equal
+    // to the new state root passed to the snark as an
+    // input.
+
+    var updatedStateRoot = merkleTreeUpdate(
+        0,
+        randomLeaf,
+        s,
+        newStateTreePathElementsToZero
+    )
+
+    assert(updatedStateRoot == newStateRoot)
+
+else:
+    // Use a constraint to ensure that the no-op flag
+    // is set to true
+    assert(noOp == true)
+```
+
+## Circuit failure modes
+
+| Condition                                           | noOp flag | Outcome                                 |
+| --------------------------------------------------- | --------- | --------------------------------------- |
+| Insufficient voice credits                          | `true`    | Valid proof, but only leaf 0 is updated |
+| Invalid nonce                                       | `true`    | Valid proof, but only leaf 0 is updated |
+| Invalid signature                                   | `true`    | Valid proof, but only leaf 0 is updated |
+| Invalid new vote option root                        | `true`    | Valid proof, but only leaf 0 is updated |
+| Invalid state leaf index                            | `true`    | Valid proof, but only leaf 0 is updated |
+| Invalid vote option tree index                      | `true`    | Valid proof, but only leaf 0 is updated |
+| Invalid Merkle path to the current state root       | N/A       | No such proof can be generated          |
+| Invalid Merkle path to the current vote option root | N/A       | No such proof can be generated          |

package/versioned_docs/version-v1.2/audit.md

@@ -0,0 +1,160 @@
+---
+title: MACI Security Audits
+description: Overview of MACI audit history with references to audit reports.
+sidebar_label: Security audits
+sidebar_position: 14
+---
+
+# MACI Security Audits
+
+## Full reports
+
+- Audit by PSE Audit 2024/02 [report](/audit_reports/20240223_PSE_Audit_audit_report.pdf)
+- Audit by HashCloak 2022/09 [report](/audit_reports/202220930_Hashcloak_audit_report.pdf)
+- Audit by HashCloak 2021/09 [report](/audit_reports/20210922_Hashcloak_audit_report.pdf)
+
+## PSE audit 2024
+
+In February 2024 the PSE Audit team audited the MACI codebase with a focus on the smart contracts, TypeScript core, and Circom circuits Three critical bugs were found: two within the Circom circuits and one in the smart contracts. All three of these have been fixed.
+
+Please see the [PSE Audit report](/audit_reports/20240223_PSE_Audit_audit_report.pdf) for details.
+
+## Veridise disclosure 2023
+
+In March 2023, Veridise responsibly disclosed a number of issues to the MACI team, which were identified using their new [tool](https://twitter.com/VeridiseInc/status/1630806464695791616?s=20) for catching ZK circuit bugs.
+
+Out of five issues disclosed, only three were relevant and have been since fixed by the MACI team. The other two issues were disregarded as they were present in older version of code which is not in use anymore.
+
+We would like to thank the Veridise team for their effort in keeping open source projects safe.
+
+### Issue 1
+
+**Description**
+
+In the template `QuinSelector`, if you want to confirm the input signal index is a valid integer less than 2\*\*3, you should add Num2bits(3) to check it.
+
+**Code Location**
+
+[`incrementalQuinTree.circom`](https://github.com/privacy-scaling-explorations/maci/blob/78609349aecd94186216ac8743d61b1cb81a097f/circuits/circom/trees/incrementalQuinTree.circom#L30)
+
+**Fix**
+
+[Code location](https://github.com/chaosma/maci/blob/60727d4d10406edda32ad28e53d399d41d45ed88/circuits/circom/trees/incrementalQuinTree.circom#L37)
+
+```javascript
+// Ensure that index < choices
+component lessThan = SafeLessThan(3);
+```
+
+This was fixed by adding a new Template, `SafeLesThan` which uses `Num2Bits` as further check on the signals:
+
+```javascript
+// the implicit assumption of LessThan is both inputs are at most n bits
+// so we need to add range check for both inputs
+template SafeLessThan(n) {
+    assert(n <= 252);
+    signal input in[2];
+    signal output out;
+
+    component n2b1 = Num2Bits(n);
+    n2b1.in  <== in[0];
+    component n2b2 = Num2Bits(n);
+    n2b2.in  <== in[1];
+
+    component n2b = Num2Bits(n+1);
+
+    n2b.in <== in[0]+ (1<<n) - in[1];
+
+    out <== 1-n2b.out[n];
+}
+```
+
+### Issue 2
+
+**Description**
+
+This issue is the same issue number 1, this time for the input signal index.
+
+**Code Location**
+
+[`incrementalQuinTree.circom`](https://github.com/privacy-scaling-explorations/maci/blob/78609349aecd94186216ac8743d61b1cb81a097f/circuits/circom/trees/incrementalQuinTree.circom#L64)
+
+**Fix**
+
+[PR with fix](https://github.com/privacy-scaling-explorations/maci/pull/646/files#diff-f3ad1f61e9b95b88929664b67c873325fdf70cb8569c2a96da4b0e9f02710391)
+
+As with issue number 1, a new template `SafeGreaterThan` was added:
+
+```javascript
+// N is the number of bits the input have.
+// The MSF is the sign bit.
+template SafeGreaterThan(n) {
+    signal input in[2];
+    signal output out;
+
+    component lt = SafeLessThan(n);
+
+    lt.in[0] <== in[1];
+    lt.in[1] <== in[0];
+    lt.out ==> out;
+}
+```
+
+And then used it to constrain the [`index` input signal](https://github.com/chaosma/maci/blob/2d7a3a0efd33dfc3a5f4d3f95bec3adda7abb963/circuits/circom/trees/incrementalQuinTree.circom#L115-L117):
+
+```javascript
+greaterThan[i] = SafeGreaterThan(3);
+greaterThan[i].in[0] <== i;
+greaterThan[i].in[1] <== index;
+```
+
+### Issue 3
+
+**Description**
+
+In the template `QuinGeneratePathIndices`, the constraints of the `signal n[levels + 1]` don't perform well for division and modulo counting.
+
+**Code Location**
+
+[`incrementalQuinTree.circom`](https://github.com/privacy-scaling-explorations/maci/blob/7c1b3743ea753786011289a356eaa45ba72f9ca1/circuits/circom/trees/incrementalQuinTree.circom#L228-L242)
+
+**Fix**
+
+The [updated code](https://github.com/chaosma/maci/blob/2d7a3a0efd33dfc3a5f4d3f95bec3adda7abb963/circuits/circom/trees/incrementalQuinTree.circom#L285-L290) uses the `SafeLessThen` template, as shown below:
+
+```javascript
+for (var i = 0; i < levels; i++) {
+    // Check that each output element is less than the base
+    leq[i] = SafeLessThan(3);
+    leq[i].in[0] <== out[i];
+    leq[i].in[1] <== BASE;
+    leq[i].out === 1;
+
+    // Re-compute the total sum
+    sum.nums[i] <== out[i] * (BASE ** i);
+}
+```
+
+## HashCloak audit 2022
+
+In the summer of 2022, MACI v1 was audited by HashCloak. The audit covered both the zk-SNARK circuits and the Solidity smart contracts.
+
+This audit revealed a number of high severity issues which have been remediated by the MACI development team. All issues were successfully fixed and reflected in MACI v1.1.1.
+
+Please see the [HashCloak report](/audit_reports/202220930_Hashcloak_audit_report.pdf) for details.
+
+## HashCloak audit 2021
+
+From July 5th, 2021 to August 2nd, 2021, the Ethereum Foundation’s Applied ZKPs team engaged HashCloak for an audit of the MACI protocol. The audit was conducted with 3 auditors over 15 person weeks.
+
+The following packages were in scope:
+
+- Circuits
+- Contracts
+- Core
+- Crypto
+- Domainobjs
+
+From August 18, 2021 to September 22, 2021, Hashcloak assisted the MACI team in resolving the issues.
+
+Please see the [HashCloak report](/audit_reports/20210922_Hashcloak_audit_report.pdf) for details.

package/versioned_docs/version-v1.2/ci-pipeline.md

@@ -0,0 +1,38 @@
+---
+title: CI Pipeline
+description: Introduction to how MACI's CI works
+sidebar_label: CI
+sidebar_position: 15
+---
+
+# Continuous Integration (CI) Pipeline
+
+CI (Continuous Integration) pipeline is an automated workflow to ensure that software is always in a working state. An event like opening a pull request causes a pipeline to run. The pipeline consists of an automated build process and a suite of automated tests (See [Testing](https://pse.dev/docs/testing) for more details).
+
+![cicd-maci drawio-7](https://user-images.githubusercontent.com/1610146/185962260-091cd952-5444-44f3-89e3-be64e81d4c21.png)
+
+## Pipeline Triggers
+
+### Commit to Main Branch
+
+Each commit (i.e. a merged PR) to the main branch triggers the pipeline. The pipeline creates packages that can be deployed to any environment. Packages are uploaded to an artifact repository (e.g. npm).
+
+![cicd-maci drawio-12](https://user-images.githubusercontent.com/1610146/183404579-8bcb76fe-34b6-4748-a5ae-e2e4b010bd86.png)
+
+### Pull Request (PR)
+
+When a pull request has been created (or updated), it triggers the PR pipeline. It gives the reviewer confidence that the software works as expected with the introduced code changes.
+
+![cicd-maci drawio-9](https://user-images.githubusercontent.com/1610146/183391880-d3a20f29-2708-4d72-988d-4781c0396e48.png)
+
+### Nightly
+
+Nightly build runs every midnight. It is to ensure that all required dependencies are present and to show no bugs have been introduced.
+
+![cicd-maci drawio-11](https://user-images.githubusercontent.com/1610146/183404455-cc2aaace-fe52-40f4-b5e4-3c852c5ff516.png)
+
+### Tag Push
+
+When a tag has been pushed, it triggers a release pipeline. It will draft a release note with an auto-generated changelog and publish npm package(s).
+
+![cicd-maci drawio-5](https://user-images.githubusercontent.com/1610146/185958513-51dadaf1-7f72-404b-b482-149b91edcaab.png)