@maci-protocol/website 0.0.0-ci.a577366 → 0.0.0-ci.a73cfa9

package/versioned_docs/version-v3.x/technical-references/zk-snark-circuits/processMessages.md

@@ -5,11 +5,11 @@ sidebar_label: Process Messages Circuit
 sidebar_position: 3
 ---
 
-[**Repo link**](https://github.com/privacy-scaling-explorations/maci/blob/dev/circuits/circom/core)
+[**Repo link**](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/coordinator)
 
-This circuit allows the coordinator to prove that they have correctly processed each message in reverse order, in a consecutive batch of 5 ^ msgBatchDepth messages to the respective state leaf within the state tree. Coordinators would use this circuit to prove correct execution at the end of each Poll.
+This circuit allows the coordinator to prove that they have correctly processed each message in reverse order, in a consecutive batch of 5 ^ messageBatchDepth messages to the respective state leaf within the state tree. Coordinators would use this circuit to prove correct execution at the end of each Poll.
 
-The [`processMessages`](https://github.com/privacy-scaling-explorations/maci/blob/dev/circuits/circom/core/qv/processMessages.circom) circuit will try to decrypt the messages, and based on the content of the message, update within itself the trees, to generate a proof that the coordinator's off-chain processing was done correctly. In other words, the circuit takes a final state, an initial state, and the leaves (messages and user signups) - it processes these messages via the different state transitions to finally check that the expected state is correct.
+The [`MessageProcessorQv`](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/coordinator/qv/MessageProcessor.circom) circuit will try to decrypt the messages, and based on the content of the message, update within itself the trees, to generate a proof that the coordinator's off-chain processing was done correctly. In other words, the circuit takes a final state, an initial state, and the leaves (messages and user signups) - it processes these messages via the different state transitions to finally check that the expected state is correct.
 The pre-requisites for this circuit are:
 
 - the related Poll has ended
@@ -18,10 +18,74 @@ The pre-requisites for this circuit are:
 
 This circuit requires the coordinator's private key, hence a proof for this circuit can only be generated by the coordinator. The private key is needed in order to generate the ECDH shared key used to decrypt the messages.
 
-![ProcessMessages](/img/circuits/processMessages_2_0.svg)
+```mermaid
+flowchart LR
+        parameters(["MessageProcessorQv - Parameters"])
+        parameters --> stateTreeDepth["stateTreeDepth"]
+        parameters --> batchSize["batchSize"]
+        parameters --> voteOptionTreeDepth["voteOptionTreeDepth"]
+
+        stateTreeDepth & batchSize & voteOptionTreeDepth --> publicInputs["Public inputs"]
+
+        subgraph publicInputs
+            direction LR
+            totalSignups ~~~ index
+            batchEndIndex ~~~ currentSbCommitment
+            newSbCommitment ~~~ outputBatchHash
+            actualStateTreeDepth ~~~ coordinatorPublicKeyHash
+            voteOptions
+        end
+
+        publicInputs --> privateInputs
+
+        subgraph privateInputs
+            direction LR
+            inputBatchHash ~~~ messages
+            coordinatorPrivateKey ~~~ encryptionPublicKeys
+            currentStateRoot ~~~ currentStateLeaves
+            currentStateLeavesPathElements ~~~ currentSbSalt
+            newSbSalt ~~~ currentBallotRoot
+            currentBallots ~~~ currentBallotsPathElements
+            currentVoteWeights ~~~ currentVoteWeightsPathElements
+        end
+
+        privateInputs --> step1["1 - Verify currentSbCommitment"]
+        step1 --> step1B["hash(currentStateRoot, currentBallotRoot, currentSbSalt)"]
+
+        privateInputs --> step2["2 – Check voteOptions upper-bound"]
+        step2 --> step2B["voteOptions <= 5 ** voteOptionTreeDepth"]
+
+        privateInputs --> step3["3 – Ensure totalSignups within capacity"]
+        step3 --> step3B["totalSignups <= 2 ** stateTreeDepth"]
+
+        privateInputs --> step4["4 – Hash each message + pub-key"]
+        step4 --> step4B["MessageHasher template loop"]
+
+        privateInputs --> step5["5 – Build and verify chainHash"]
+        step5 --> step5B["PoseidonHasher template loop + Mux1"]
+
+        privateInputs --> step6["6 – Derive & verify coordinator pubKey"]
+        step6 --> step6B["PrivateToPublicKey -> derivedPublicKeyHash == coordinatorPublicKeyHash"]
+
+        privateInputs --> step7["7 – Decrypt each message to a command using MessageToCommand"]
+        step7 --> step7B["MessageToCommand template loop"]
+
+        privateInputs --> step8["8 – Process messages in reverse order"]
+        step8 --> step8B["SingleMessageProcessorQv template loop"]
+
+        privateInputs --> step9["9 – Compute newSbCommitment"]
+        step9 --> step9B["hash(stateRoot, ballotRoot, newSbSalt)"]
+
+        privateInputs --> step10["10 – Verify provided newSbCommitment"]
+        step10 --> step10B["equality with computed commitment"]
+```
+
+:::info
+A version working with non quadratic voting (non-qv) is also [available](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/coordinator/non-qv/MessageProcessor.circom). This version is called `MessageProcessorNonQV` and is to be used when the Poll is not using the quadratic voting feature. Note that by default MACI works with quadratic voting.
+:::
 
 :::info
-A version working with non quadratic voting (non-qv) is also [available](https://github.com/privacy-scaling-explorations/maci/blob/dev/circuits/circom/core/non-qv/processMessages.circom). This version is called `processMessagesNonQV` and is to be used when the Poll is not using the quadratic voting feature. Note that by default MACI works with quadratic voting.
+A version working with full credits voting (full) is also [available](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/coordinator/full/MessageProcessor.circom). This version is called `MessageProcessorFull` and is to be used when the Poll is not using the quadratic or non quadratic voting features. Note that by default MACI works with quadratic voting.
 :::
 
 #### Parameters
@@ -36,17 +100,17 @@ A version working with non quadratic voting (non-qv) is also [available](https:/
 
 | Input signal                     | Description                                                                             |
 | -------------------------------- | --------------------------------------------------------------------------------------- |
-| `numSignUps`                     | Number of users that have completed the sign up                                         |
+| `totalSignups`                   | Number of users that have completed the sign up                                         |
 | `index`                          | The batch index of current message batch                                                |
 | `pollEndTimestamp`               | The Unix timestamp at which the poll ends                                               |
-| `msgRoot`                        | The root of the message tree                                                            |
-| `msgs`                           | The batch of messages as an array of arrays                                             |
-| `msgSubrootPathElements`         | As described below                                                                      |
+| `messageRoot`                    | The root of the message tree                                                            |
+| `messages`                       | The batch of messages as an array of arrays                                             |
+| `messageSubrootPathElements`     | As described below                                                                      |
 | `coordinatorPublicKeyHash`       | $\mathsf{poseidon_2}([cPk_x, cPk_y])$                                                   |
 | `newSbCommitment`                | As described below                                                                      |
-| `coordPrivKey`                   | The coordinator's private key                                                           |
+| `coordinatorPrivateKey`          | The coordinator's private key                                                           |
 | `batchEndIndex`                  | The last batch index                                                                    |
-| `encPubKeys`                     | The public keys used to generate shared ECDH encryption keys to encrypt the messages    |
+| `encryptionPublicKeys`           | The public keys used to generate shared ECDH encryption keys to encrypt the messages    |
 | `currentStateRoot`               | The state root before the commands are applied                                          |
 | `currentStateLeaves`             | The state leaves upon which messages are applied                                        |
 | `currentStateLeavesPathElements` | The Merkle path to each incremental state root                                          |
@@ -74,9 +138,9 @@ The salt used to produce `currentSbCommitment` (see above).
 
 The salt used to produce `newSbCommitment` (see above).
 
-##### `msgSubrootPathElements`
+##### `messageSubrootPathElements`
 
-The index of each message in `msgs` is consecutive. As such, in order to prove that each message in `msgs` is indeed a leaf of the message tree, we compute the subtree root of `msgs`, and then verify that the subtree root is indeed a subroot of `msgRoot`.
+The index of each message in `messages` is consecutive. As such, in order to prove that each message in `messages` is indeed a leaf of the message tree, we compute the subtree root of `messages`, and then verify that the subtree root is indeed a subroot of `messageRoot`.
 
 A simplified example using a tree of arity 2:
 
@@ -92,7 +156,7 @@ A simplified example using a tree of arity 2:
 
 To prove that `a...d` are leaves of the tree with root `r`, we prove that the leaves have the subroot `s` with depth 2, and _then_ prove that `s` is a member of `r` at depth 1.
 
-The implementation for this is in the `QuinBatchLeavesExists` circuit in `https://github.com/privacy-scaling-explorations/maci/blob/dev/circuits/circom/trees/incrementalQuinTree.circom`.
+The implementation for this is in the `QuinBatchLeavesExists` circuit in `https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/trees/incrementalQuinTree.circom`.
 
 This method requires fewer circuit constraints than if we verified a Merkle proof for each leaf.
 
@@ -100,7 +164,7 @@ This method requires fewer circuit constraints than if we verified a Merkle proo
 
 1. That the prover knows the preimage to `currentSbCommitment` (that is, the state root, ballot root, and `currentSbSalt`)
 2. That `maxVoteOptions <= (5 ^ voteOptionTreeDepth)`
-3. That `numSignUps <= (2 ^ stateTreeDepth)`
-4. That `coordinatorPublicKeyHash` is a hash of public key that is correctly derived from `coordPrivKey`
-5. That each message in `msgs` exists in the message tree
+3. That `totalSignups <= (2 ^ stateTreeDepth)`
+4. That `coordinatorPublicKeyHash` is a hash of public key that is correctly derived from `coordinatorPrivateKey`
+5. That each message in `messages` exists in the message tree
 6. That after decrypting and applying each message, in reverse order, to the corresponding state and ballot leaves, the new state root, new ballot root, and `newSbSalt` are the preimage to `newSbCommitment`

package/versioned_docs/version-v3.x/technical-references/zk-snark-circuits/setup.md

@@ -37,7 +37,7 @@ MACI's circuits are parameterized, and thus can be configured to support differe
 - **STATE_TREE_DEPTH** = how many users the system supports
 - **VOTE_OPTIONS_TREE_DEPTH** = how many vote options the system supports
 - **MESSAGE_BATCH_SIZE** = how many messages in a batch the circuit should process
-- **INT_STATE_TREE_DEPTH** = how many ballots can be processed per batch when tallying the results (`5 ** INT_STATE_TREE_DEPTH` ballots)
+- **TALLY_PROCESSING_STATE_TREE_DEPTH** = how many ballots can be processed per batch when tallying the results (`2 ** TALLY_PROCESSING_STATE_TREE_DEPTH` ballots)
 
 Please refer to the individual circuit documentation for more details on the inner working of each circuit and where parameters fit.
 
@@ -90,7 +90,7 @@ To test the circuits package, please use `pnpm run test`. This will run all of t
 
 To run individual tests, you can use the following commands (for all other circuits please refer to the `package.json` scripts section):
 
-- `pnpm run test:processMessages` to run the tests for the `processMessages` circuit.
-- `pnpm run test:tallyVotes` to run the tests for the `tallyVotes` circuit.
+- `pnpm run test:messageProcessor` to run the tests for the `MessageProcessor` circuit.
+- `pnpm run test:voteTally` to run the tests for the `VoteTally` circuit.
 
 More details on testing are provided in the [testing section](/docs/guides/testing/testing-introduction) of the documentation.

package/versioned_docs/version-v3.x/technical-references/zk-snark-circuits/tallyVotes.md

@@ -5,7 +5,7 @@ sidebar_label: Tally Votes Circuit
 sidebar_position: 4
 ---
 
-[**Repo link**](https://github.com/privacy-scaling-explorations/maci/blob/dev/circuits/circom/core)
+[**Repo link**](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/core)
 
 #### Parameters
 
@@ -15,17 +15,17 @@ sidebar_position: 4
 | 1   | State leaf batch depth | Allows $(5^{n})$ users' votes to be processed per batch. |
 | 2   | Vote option tree depth | Allows $(5^{n})$ vote options.                           |
 
-![TallyVotes](/img/circuits/tallyVotes.svg)
+![VoteTally](/img/circuits/tallyVotes.svg)
 
 :::info
-A version working with non quadratic voting (non-qv) is also [available](https://github.com/privacy-scaling-explorations/maci/blob/dev/circuits/circom/core/non-qv/tallyVotes.circom). This version is called `tallyVotesNonQv` and is to be used when the Poll is not using the quadratic voting feature. Note that by default MACI works with quadratic voting.
+A version working with non quadratic and full credits voting (non-qv, full) is also [available](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/coordinator/non-qv/VoteTally.circom). This version is called `tallyVotes` and is to be used when the Poll is not using the quadratic voting feature. Note that by default MACI works with quadratic voting.
 :::
 
 #### Input signals
 
 | Input signal                            | Description                                                      |
 | --------------------------------------- | ---------------------------------------------------------------- |
-| `numSignUps`                            | The number of users that signup                                  |
+| `totalSignups`                          | The number of users that signup                                  |
 | `index`                                 | Start index of given batch                                       |
 | `sbCommitment`                          | Described below                                                  |
 | `currentTallyCommitment`                | Described below                                                  |
@@ -72,8 +72,8 @@ $poseidon_3([tc_r, tc_t, tc_p])$
 #### Statements that the circuit proves
 
 1. That the coordinator knows the preimage of `sbCommitment`
-2. That `index` is less than or equal to `numSignUps`
-3. That each ballot in `ballots` is in a member of the ballot tree with the Merkle root `ballotRoot` at indices `batchStartIndex` to `batchStartIndex + (5 ** intStateTreeDepth)`
+2. That `index` is less than or equal to `totalSignups`
+3. That each ballot in `ballots` is in a member of the ballot tree with the Merkle root `ballotRoot` at indices `batchStartIndex` to `batchStartIndex + (5 ** tallyProcessingStateTreeDepth)`
 4. That each set of votes (`votes[i]`) has the Merkle root $blt_r$ whose value equals `ballots[i][1]`
 5. That the tally is valid, which is:
    - That the sum of votes per vote option is correct

package/versioned_docs/version-v3.x/technical-references/zk-snark-circuits/utilities.md

@@ -7,7 +7,7 @@ sidebar_position: 5
 
 #### Process Messages Input Hasher
 
-A utility circuit used by the main `processMessages` circuit to hash its inputs.
+A utility circuit used by the main `MessageProcessor` circuit to hash its inputs.
 
 ![ProcessMessagesInputHasher](/img/circuits/processMessagesInputHasher.svg)
 
@@ -15,7 +15,7 @@ It outputs one field element, which is the SHA256 hash of the following inputs:
 
 1. `packedVals`
 2. `pollEndTimestamp`
-3. `msgRoot`
+3. `messageRoot`
 4. `coordinatorPubKeyHash`
 5. `newSbCommitment`
 6. `currentSbCommitment`
@@ -35,15 +35,15 @@ It outputs one field element, which is the SHA256 hash of the following inputs:
 
 #### ResultsCommitmentVerifier
 
-A utility circuit used by the main `tallyVotes` circuit to verify that the results commitment is correct.
+A utility circuit used by the main `VoteTally` circuit to verify that the results commitment is correct.
 
 ![ResultsCommitmentVerifier](/img/circuits/resultsCommitmentVerifier.svg)
 
-#### QuinCheckRoot
+#### QuinaryCheckRoot
 
 Utility circuit that given a quin Merkle root and a list of leaves, check if the root is the correct result of inserting all the leaves into the tree in the given order.
 
-![QuinCheckRoot](/img/circuits/quinCheckRoot.svg)
+![QuinaryCheckRoot](/img/circuits/quinCheckRoot.svg)
 
 #### CalculateTotal
 
@@ -100,11 +100,11 @@ Utility circuit used to unpack an input element.
 
 ![UnpackElement](/img/circuits/unpackElement.svg)
 
-#### QuinSelector
+#### QuinarySelector
 
 Utility circuit used to select one element from an array of n elements at a given index.
 
-![QuinSelector](/img/circuits/quinSelector.svg)
+![QuinarySelector](/img/circuits/quinSelector.svg)
 
 #### Splicer
 
@@ -118,11 +118,11 @@ Utility circuit used to check if a batch of leaves exists in a quinary tree.
 
 ![QuinBatchLeavesExists](/img/circuits/quinBatchLeavesExists.svg)
 
-#### QuinGeneratePathIndices
+#### QuinaryGeneratePathIndices
 
 Utility circuit used to generate the indices needed to traverse the tree until we find the leaf we are looking for.
 
-![QuinGeneratePathIndices](/img/circuits/quinGeneratePathIndices.svg)
+![QuinaryGeneratePathIndices](/img/circuits/quinGeneratePathIndices.svg)
 
 #### ProcessOne
 

package/versioned_docs/version-v3.x/technical-references/zk-snark-circuits/zk-snark-circuits.md

@@ -5,10 +5,10 @@ sidebar_label: zk-SNARK Circuits
 sidebar_position: 1
 ---
 
-MACI has three main zk-SNARK [circuits](https://github.com/privacy-scaling-explorations/maci/tree/dev/circuits):
+MACI has three main zk-SNARK [circuits](https://github.com/privacy-scaling-explorations/maci/tree/main/packages/circuits):
 
-1. ProcessMessages.circom, which takes a batch of encrypted messages, decrypts them, and generates a proof that the coordinator's local processing was performed correctly. [QV](https://github.com/privacy-scaling-explorations/maci/blob/dev/circuits/circom/core/qv/processMessages.circom) and [non-QV](https://github.com/privacy-scaling-explorations/maci/blob/dev/circuits/circom/core/non-qv/processMessages.circom) versions are available.
-2. TallyVotes.circom, which counts votes from users' ballots, batch by batch. [QV](https://github.com/privacy-scaling-explorations/maci/blob/dev/circuits/circom/core/qv/tallyVotes.circom) and [non-QV](https://github.com/privacy-scaling-explorations/maci/blob/dev/circuits/circom/core/non-qv/tallyVotes.circom) versions are available.
+1. ProcessMessages.circom, which takes a batch of encrypted messages, decrypts them, and generates a proof that the coordinator's local processing was performed correctly. [QV](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/coordinator/qv/MessageProcessor.circom), [non-QV](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/coordinator/non-qv/MessageProcessor.circom), [Full](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/coordinator/full/MessageProcessor.circom) versions are available.
+2. TallyVotes.circom, which counts votes from users' ballots, batch by batch. [QV](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/coordinator/qv/VoteTally.circom) and [non-QV](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/coordinator/non-qv/VoteTally.circom) versions are available.
 3. PollJoining.circom, which allows users to prove they know a private key for a public key signed up to the MACI smart contract, and to register to a specific poll.
 
 The rest of the circuits are utilities templates that are required for the main circuits to work correctly. These include utilities such as float math, conversion of private keys, and Poseidon hashing/encryption.