@maci-protocol/website 0.0.0-ci.2df0337 → 0.0.0-ci.2ea88a0

package/versioned_docs/version-v3.x/contributing/contributing.md

@@ -57,15 +57,21 @@ Pull requests are great if you want to add a feature or fix a bug. Here's a quic
 
 7. Make the test pass.
 
-8. Commit your changes. Please make sure your forked `dev` branch is synced as well feature/fix branch and there are no "temp" commits (like wip, fix typo/lint/types and etc). We recommend to squash the feature/fix branch commits before creating PR. You can use this command for it:
+8. Commit your changes. Please make sure your forked `main` branch is synced as well feature/fix branch and there are no "temp" commits (like wip, fix typo/lint/types and etc). We recommend to squash the feature/fix branch commits before creating PR. You can use this command for it:
 
 ```bash
-git reset $(git merge-base dev $(git rev-parse --abbrev-ref HEAD))
+git checkout main
+git pull
+git checkout your-branch
+git rebase main
+git reset $(git merge-base main $(git rev-parse --abbrev-ref HEAD))
 ```
 
-9. Push to your fork and submit a pull request on our `dev` branch. Please provide us with some explanation of why you made the changes you made. For new features make sure to explain a standard use case to us.
+9. Before creating a pull request make sure your work is ready. Do not create WIP pull requests and do not skip pre-commit hooks.
 
-10. Link any issues that the PR is addressing as described in our processes documentation.
+10. Push to your fork and submit a pull request on our `main` branch. Please provide us with some explanation of why you made the changes you made. For new features make sure to explain a standard use case to us. Do not remove our PR template and follow all the steps defined in it.
+
+11. Link any issues that the PR is addressing as described in our processes documentation.
 
 ## CI (Github Actions) Tests
 
@@ -131,7 +137,7 @@ Just as in the subject, use the imperative, present tense: "change" not "changed
 
 ### Branch rules
 
-- Branches should generally be created off of the base branch (`dev` )
+- Branches should generally be created off of the base branch (`main` )
 - Avoid long descriptive names for long-lived branches
 - Use kebab-case (no CamelCase)
 - Use grouping tokens (words) at the beginning of your branch names (in a similar way to the `type` of commit)

package/versioned_docs/version-v3.x/core-concepts/key-change.md

@@ -23,14 +23,14 @@ Reverse processing was introduced to prevent a type of attack where a briber wou
 
 Let's take as an example the following:
 
-1. Alice signs up with pub key $pub1$
-2. Bob (Briber) bribes Alice and asks her to submit a key change message to $pub2$ (owned by Bob)
-3. Bob submits a vote with $pub2$
-4. Alice submits a vote with $pub1$
+1. Alice signs up with public key $public1$
+2. Bob (Briber) bribes Alice and asks her to submit a key change message to $public2$ (owned by Bob)
+3. Bob submits a vote with $public2$
+4. Alice submits a vote with $public1$
 
 If messages were processed in the same order as they were submitted, Alice's vote would not be valid, due to it being signed with a private key $priv1$ - which now would not be valid.
 
-On the other hand, due to messages being processed in reverse order, Alice's last message would be counted as valid as the key change would have not been processed yet. Then, Bob's vote would not be counted as valid as the current key for Alice would be $pub1$.
+On the other hand, due to messages being processed in reverse order, Alice's last message would be counted as valid as the key change would have not been processed yet. Then, Bob's vote would not be counted as valid as the current key for Alice would be $public1$.
 
 > Note that a key change message should have the nonce set to 1 in order for it to be valid. We'll see a code example in the next sections.
 
@@ -47,7 +47,7 @@ Let's take a look into a code example:
 ```ts
 const user1Keypair = new Keypair();
 const user2Keypair = new Keypair();
-const secondKeyPair = new Keypair();
+const secondKeypair = new Keypair();
 ```
 
 - Votes will be
@@ -77,7 +77,7 @@ As seen above, we expect the first vote weight 9 to not be counted, but instead
 - Deploy a MaciState locally and sign up
 
 ```ts
-const maciState: MaciState = new MaciState(STATE_TREE_DEPTH);
+const maciState = new MaciState(STATE_TREE_DEPTH);
 // Sign up
 user1StateIndex = maciState.signUp(user1Keypair.publicKey, voiceCreditBalance, BigInt(Math.floor(Date.now() / 1000)));
 user2StateIndex = maciState.signUp(user2Keypair.publicKey, voiceCreditBalance, BigInt(Math.floor(Date.now() / 1000)));
@@ -95,7 +95,7 @@ pollId = maciState.deployPoll(
 
 ```ts
 const poll = maciState.polls[pollId];
-const command1 = new PCommand(
+const command1 = new VoteCommand(
   BigInt(user1StateIndex),
   user1Keypair.publicKey,
   user1VoteOptionIndex,
@@ -112,7 +112,7 @@ const sharedKey1 = Keypair.genEcdhSharedKey(ecdhKeypair1.privateKey, coordinator
 const message1 = command1.encrypt(signature1, sharedKey1);
 poll.publishMessage(message1, ecdhKeypair1.publicKey);
 
-const command2 = new PCommand(
+const command2 = new VoteCommand(
   BigInt(user2StateIndex),
   user2Keypair.publicKey,
   user2VoteOptionIndex,
@@ -134,9 +134,9 @@ poll.publishMessage(message2, ecdhKeypair2.publicKey);
 
 ```ts
 const poll = maciState.polls[pollId];
-const command = new PCommand(
+const command = new VoteCommand(
   BigInt(user1StateIndex),
-  secondKeyPair.publicKey,
+  secondKeypair.publicKey,
   user1VoteOptionIndex,
   user1NewVoteWeight,
   BigInt(1),
@@ -158,8 +158,8 @@ poll.publishMessage(message, ecdhKeypair.publicKey);
 const poll = maciState.polls[pollId];
 poll.processMessages(pollId);
 poll.tallyVotes();
-expect(poll.perVOSpentVoiceCredits[0].toString()).to.eq((user1NewVoteWeight * user1NewVoteWeight).toString());
-expect(poll.perVOSpentVoiceCredits[1].toString()).to.eq((user2VoteWeight * user2VoteWeight).toString());
+expect(poll.perVoteOptionSpentVoiceCredits[0].toString()).to.eq((user1NewVoteWeight * user1NewVoteWeight).toString());
+expect(poll.perVoteOptionSpentVoiceCredits[1].toString()).to.eq((user2VoteWeight * user2VoteWeight).toString());
 ```
 
 - Finally confirm that the keypair was changed for the user1
@@ -175,5 +175,5 @@ expect(stateLeaf2.publicKey.equals(user2Keypair.publicKey)).to.eq(true);
 We see that is important that we set the final message (the one with the new vote) with nonce 1, as this vote would be counted as the first vote.
 
 :::info
-Tests related to key changes have been added to the [core package](https://github.com/privacy-scaling-explorations/maci/blob/dev/core/ts/__tests__/) and to the [cli package](https://github.com/privacy-scaling-explorations/maci/blob/dev/cli/tests/).
+Tests related to key changes have been added to the [core package](https://github.com/privacy-scaling-explorations/maci/blob/main/core/ts/__tests__/) and to the [cli package](https://github.com/privacy-scaling-explorations/maci/blob/main/cli/tests/).
 :::

package/versioned_docs/version-v3.x/core-concepts/maci-keys.md

@@ -78,7 +78,7 @@ Serialized, these will look like **macipk.0e5194a54562ea4d440ac6a0049a41d4b600e3
 After successfully [installing](/docs/quick-start#installation) MACI, you can easily generate your MACI key pair by running:
 
 ```bash
-pnpm run genMaciKeyPair
+pnpm run generate-maci-keypair
 ```
 
 This command will create the necessary public and private keys required for running various MACI operations.

package/versioned_docs/version-v3.x/core-concepts/poll-types.md

@@ -5,25 +5,25 @@ sidebar_label: Poll types
 sidebar_position: 9
 ---
 
-MACI allows to conduct polls in both a quadratic voting and non quadratic voting fashion. One should be aware that the only distinction between the two happens when messages are processed and votes tallied. On top of that, the Tally smart contract has been split into two different ones, with the non quadratic voting version one being slightly smaller, due to the need of one less function.
+MACI allows to conduct polls in both a quadratic voting and non quadratic voting fashion. One should be aware that the only distinction between the two happens when messages are processed and votes tallied. On top of that, the Tally smart contract has been split into two different ones, with the non quadratic voting version one being slightly smaller, due to the need of one less function. Additionally, there is a variation of non quadratic voting that allows participants to cast their entire voice credit balance for a single option only.
 
 This document will explain how to use each of these options. Hardhat tasks are the currently recommended way to deploy contracts and run polls but you can also use the MACI cli.
 
 ## Quadratic Voting
 
-MACI has always worked with quadratic voting. Users signing up to MACI are assigned a number of voice credits based on certain conditions (enforced by the [initial voice credit proxy contract](https://github.com/privacy-scaling-explorations/maci/blob/dev/contracts/contracts/initialVoiceCreditProxy/InitialVoiceCreditProxy.sol)), and after each vote, the number of voice credits is reduced by the square of the weight of the vote casted. For instance, if the vote weight is 5, a user must have at least 25 voice credits to cast the vote.
+MACI has always worked with quadratic voting. Users signing up to MACI are assigned a number of voice credits based on certain conditions (enforced by the [initial voice credit proxy contract](https://github.com/privacy-scaling-explorations/maci/blob/main/packages/contracts/contracts/initialVoiceCreditProxy/ConstantInitialVoiceCreditProxy.sol)), and after each vote, the number of voice credits is reduced by the square of the weight of the vote casted. For instance, if the vote weight is 5, a user must have at least 25 voice credits to cast the vote.
 
 To run a poll with quadratic voting, the coordinator must deploy the Poll with the mode set to quadratic voting.
 
 ### Using Hardhat tasks
 
-In the deploy-config.json file set the `useQuadraticVoting` value to **true**.
+In the deploy-config.json file set the `mode` value to **qv**.
 
 ```json
 "Poll": {
     "pollDuration": 604800,
-    "coordinatorPubkey": "macipk",
-    "useQuadraticVoting": true
+    "coordinatorPublicKey": "macipk",
+    "mode": "qv"
 }
 ```
 
@@ -37,17 +37,41 @@ pnpm deploy-poll:NETWORK
 
 The non quadratic voting option is a new feature that has been added to MACI with the v1.2 release. It allows to conduct polls without the quadratic voting mechanism. This means that the number of voice credits is not reduced by the square of the weight of the vote casted. This option is useful for polls where the quadratic voting mechanism is not necessary, and it is also slightly cheaper for coordinators to tally votes, as there are less checks required in the Tally smart contract.
 
-To run a poll with non quadratic voting, the coordinator must set the `useQuadraticVoting` parameter to `false` when creating the MACI instance. This will make the MACI instance use the `TallyNonQv` smart contract, which is a smaller version of the `Tally` smart contract, as it does not require the checks for the quadratic voting mechanism.
+To run a poll with non quadratic voting, the coordinator must set the `mode` parameter to `non-qv` when creating the MACI instance. This will make the MACI instance use the `TallyNonQv` smart contract, which is a smaller version of the `Tally` smart contract, as it does not require the checks for the quadratic voting mechanism.
 
 ### Using Hardhat tasks
 
-In the deploy-config.json file set the `useQuadraticVoting` value to **false**.
+In the deploy-config.json file set the `mode` value to **non-qv**.
 
 ```json
 "Poll": {
     "pollDuration": 604800,
-    "coordinatorPubkey": "macipk",
-    "useQuadraticVoting": false
+    "coordinatorPublicKey": "macipk",
+    "mode": "non-qv"
+}
+```
+
+Then run the task to create a poll:
+
+```bash
+pnpm deploy-poll:NETWORK
+```
+
+## Full Credits Voting
+
+Full Credits Voting is a new feature introduced in MACI v3. This voting mode disables the quadratic voting mechanism and requires participants to allocate their entire voice credit balance to a single option. Unlike quadratic voting, where the cost of votes increases quadratically with the number of votes cast, Full Credits Voting uses a linear model: participants spend all their available voice credits on one chosen option. No splitting across multiple options is allowed. This option is useful for polls where the quadratic voting mechanism is not necessary and where it's important to ensure voters fully commit to a single choice—eliminating fragmented or spread-out voting behavior. It also offers a slight cost advantage for coordinators, as tallying is more efficient with fewer checks required in the Tally smart contract.
+
+To run a poll full credits voting, the coordinator must set the `mode` parameter to `full` when creating the MACI instance. This will make the MACI instance use the `TallyNonQv` smart contract, which is a smaller version of the `Tally` smart contract, as it does not require the checks for the quadratic voting mechanism.
+
+### Using Hardhat tasks
+
+In the deploy-config.json file set the `mode` value to **full**.
+
+```json
+"Poll": {
+    "pollDuration": 604800,
+    "coordinatorPublicKey": "macipk",
+    "mode": "full"
 }
 ```
 

package/versioned_docs/version-v3.x/core-concepts/polls.md

@@ -11,7 +11,7 @@ Currently, you can configure the following parameters for a poll:
 
 - Poll duration, in the form of a unix timestamp for start and end times. This allows polls to be scheduled to start at a certain time, and run for a certain amount of time.
 - Vote option - how many vote options are allowed for a poll.
-- Vote mode - quadratic or non quadratic voting. One should be aware that the only distinction between the two happens when messages are processed and votes tallied.
+- Vote mode - quadratic, non quadratic, full credits voting. One should be aware that the only distinction between them happens when messages are processed and votes tallied.
 - Policy - the Excubiae policy that will be used to gate access to the poll.
 - Initial voice credit proxy - the initial voice credit proxy that will be used to assign voice credits to voters.
 - Relayer - the list of addresses that will be able to relay messages on behalf of other users (for now this is recommended to be the coordinator only)
@@ -23,7 +23,7 @@ The full configuration for a poll looks like this:
 "Poll": {
     "pollStartDate": 3600,
     "pollEndDate": 3600,
-    "coordinatorPubkey": "macipk.9a59264310d95cfd8eb7083aebeba221b5c26e77427f12b7c0f50bc1cc35e621",
+    "coordinatorPublicKey": "macipk.9a59264310d95cfd8eb7083aebeba221b5c26e77427f12b7c0f50bc1cc35e621",
     "useQuadraticVoting": false,
     "policy": "FreeForAllPolicy",
     "relayers": "0x0000000000000000000000000000000000000000",
@@ -34,19 +34,19 @@ The full configuration for a poll looks like this:
 
 ## Quadratic Voting
 
-MACI has always worked with quadratic voting. Users joining a Poll are assigned a number of voice credits based on certain conditions (enforced by the [initial voice credit proxy contract](https://github.com/privacy-scaling-explorations/maci/blob/dev/contracts/contracts/initialVoiceCreditProxy/InitialVoiceCreditProxy.sol)), and after each vote, the number of voice credits is reduced by the square of the weight of the vote casted. For instance, if the vote weight is 5, a user must have at least 25 voice credits to cast the vote.
+MACI has always worked with quadratic voting. Users joining a Poll are assigned a number of voice credits based on certain conditions (enforced by the [initial voice credit proxy contract](https://github.com/privacy-scaling-explorations/maci/blob/main/packages/contracts/contracts/initialVoiceCreditProxy/ConstantInitialVoiceCreditProxy.sol)), and after each vote, the number of voice credits is reduced by the square of the weight of the vote casted. For instance, if the vote weight is 5, a user must have at least 25 voice credits to cast the vote.
 
 To run a poll with quadratic voting, the coordinator must deploy the Poll with the mode set to quadratic voting.
 
 ### Using Hardhat tasks
 
-In the deploy-config.json file set the `useQuadraticVoting` value to **true**.
+In the deploy-config.json file set the `mode` value to **qv**.
 
 ```json
 "Poll": {
     [...]
-    "coordinatorPubkey": "macipk",
-    "useQuadraticVoting": true
+    "coordinatorPublicKey": "macipk",
+    "mode": "qv"
 }
 ```
 
@@ -60,17 +60,41 @@ pnpm deploy-poll:NETWORK
 
 The non quadratic voting option is a new feature that has been added to MACI with the v1.2 release. It allows to conduct polls without the quadratic voting mechanism. This means that the number of voice credits is not reduced by the square of the weight of the vote casted. This option is useful for polls where the quadratic voting mechanism is not necessary, and it is also slightly cheaper for coordinators to tally votes, as there are less checks required in the Tally smart contract.
 
-To run a poll with non quadratic voting, the coordinator must set the `useQuadraticVoting` parameter to `false` when creating the MACI instance.
+To run a poll with non quadratic voting, the coordinator must set the `mode` parameter to `non-qv` when creating the MACI instance.
 
 ### Using Hardhat tasks
 
-In the deploy-config.json file set the `useQuadraticVoting` value to **false**.
+In the deploy-config.json file set the `mode` value to **non-qv**.
 
 ```json
 "Poll": {
     [...]
-    "coordinatorPubkey": "macipk",
-    "useQuadraticVoting": false
+    "coordinatorPublicKey": "macipk",
+    "mode": "non-qv"
+}
+```
+
+Then run the task to create a poll:
+
+```bash
+pnpm deploy-poll:NETWORK
+```
+
+## Full Credits Voting
+
+Full Credits Voting is a new feature introduced in MACI v3. This voting mode disables the quadratic voting mechanism and requires participants to allocate their entire voice credit balance to a single option. Unlike quadratic voting, where the cost of votes increases quadratically with the number of votes cast, Full Credits Voting uses a linear model: participants spend all their available voice credits on one chosen option. No splitting across multiple options is allowed. This option is useful for polls where the quadratic voting mechanism is not necessary and where it's important to ensure voters fully commit to a single choice—eliminating fragmented or spread-out voting behavior. It also offers a slight cost advantage for coordinators, as tallying is more efficient with fewer checks required in the Tally smart contract.
+
+To run a poll with full credits voting, the coordinator must set the `mode` parameter to `full` when creating the MACI instance.
+
+### Using Hardhat tasks
+
+In the deploy-config.json file set the `mode` value to **full**.
+
+```json
+"Poll": {
+    [...]
+    "coordinatorPublicKey": "macipk",
+    "mode": "full"
 }
 ```
 

package/versioned_docs/version-v3.x/core-concepts/spec.md

@@ -550,88 +550,22 @@ To make these processes easy to use, we provide command-line interface tools.
 
 The integration tests and shell scripts in the `cli` directory provide examples of the order in which to execute them.
 
-| Command            | Description                                              | Notes                                                                                                                                        |
-| ------------------ | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| `genMaciPubkey`    | Generate a MACI public key from a private key            | Only the coordinator needs to run this, as users should generate their keys in the browser and should be automated by the client application |
-| `genMaciKeypair`   | Generates a MACI private key and public key              | Only the coordinator needs to run this, as users should generate their keys in the browser and should be automated by the client application |
-| `deployVkRegistry` | Deploy the `VkRegistry` contract                         | Executed only the coordinator                                                                                                                |
-| `setVerifyingKeys` | Set verifying keys to the `VkRegistry`                   | Executed only the coordinator                                                                                                                |
-| `create`           | Deploy a new instance of MACI                            | Executed only the coordinator                                                                                                                |
-| `deployPoll`       | Deploy a new poll on a MACI instance                     | Executed only the coordinator                                                                                                                |
-| `signup`           | Sign up a user                                           | Mainly for testing; as users are more likely to use the client application instead of the CLI                                                |
-| `publish`          | Submit a message to a poll                               | Mainly for testing; as users are more likely to use the client application instead of the CLI                                                |
-| `mergeMessages`    | Must be executed before generating proofs                | Executed only the coordinator                                                                                                                |
-| `mergeSignups`     | Must be executed before generating proofs                | Executed only the coordinator                                                                                                                |
-| `genProofs`        | Generate all message processing and vote tallying proofs | Executed only the coordinator                                                                                                                |
-| `proveOnChain`     | Submit proofs to the `PollProcessorAndTallyer` contract  | Executed only the coordinator                                                                                                                |
-
-## 5. Ethereum contracts
-
-### 5.1. MACI
-
-| Function                                                                                                   | Permissions                                                         | Notes                                                                        |
-| ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
-| `init(VkRegistry _vkRegistry, MessageAqFactory _messageAqFactory)`                                         | Coordinator only                                                    | Initialise factory, helper and registry contracts that share equal ownership |
-| `signUp(PubKey memory _pubKey, bytes memory _signUpPolicyData, bytes memory _initialVoiceCreditProxyData)` | Executable only during the sign-up period and after initialisation  | Participant registration and voice credit assignment                         |
-| `mergeStateAqSubRoots(uint256 _numSrQueueOps, uint256 _pollId)`                                            | Executable only by poll contract `_pollId` and after initialisation | Merge queued state leaves to form the state tree subroots                    |
-| `mergeStateAq(uint256 _pollId)`                                                                            | Executable only by poll contract `_pollId` and after initialisation | Merge the state subroots to form the state root                              |
-| `getStateTreeRoot()`                                                                                       | Non-applicable                                                      | Query the state root                                                         |
-| `deployPoll(uint256 _duration, TreeDepths memory _treeDepths, PubKey memory _coordinatorPubKey)`           | Executable only after initialisation                                | Create a new poll                                                            |
-| `getPoll(uint256 _pollId)`                                                                                 | Non-applicable                                                      | Query a poll address                                                         |
-
-### 5.2. Poll
-
-| Function                                                                     | Permissions                                                                            | Notes                                                                                           |
-| ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
-| `getDeployTimeAndDuration()`                                                 | Non-applicable                                                                         | Query the deployment timestamp and duration                                                     |
-| `numSignUpsAndMessages()`                                                    | Non-applicable                                                                         | Query the number of participants and messages cast                                              |
-| `currentSbAndTallyCommitments()`                                             | Non-applicable                                                                         | Query the current state-ballot and tally commitments hashes                                     |
-| `publishMessage(Message memory _message, PubKey memory _encPubKey)`          | Executable only during the voting period and if the message limit has not been not met | Submit a message (whether valid or not) to the message queue                                    |
-| `hashMessageAndEncPubKey(Message memory _message, PubKey memory _encPubKey)` | Non-applicable                                                                         | Query a hash of a message and public key coordinates                                            |
-| `mergeMaciStateAqSubRoots( uint256 _numSrQueueOps, uint256 _pollId)`         | Executable only by the coordinator and after the voting period                         | Merge queued state leaves to form the state subroots                                            |
-| `mergeMaciStateAq(uint256 _pollId)`                                          | Executable only by the coordinator and after the voting period                         | Merge the state subroots to form the state root and initialise the state-ballot commitment hash |
-| `mergeMessageAqSubRoots(uint256 _numSrQueueOps)`                             | Executable only by the coordinator and after the voting period                         | Merge the queued message leaves to form the message tree subroots                               |
-| `mergeMessageAq()`                                                           | Executable only by the coordinator and after the voting period                         | Merge the message tree subroots to form the message tree root                                   |
-| `batchEnqueueMessage(uint256 _messageSubRoot)`                               | Executable only by the coordinator and after the voting period                         | Submit a batch of messages to the queue                                                         |
-
-### 5.3. PollFactory
-
-| Function                                                                                                                                                                             | Permissions      | Notes                                   |
-| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------- | --------------------------------------- |
-| `setMessageAqFactory(MessageAqFactory _messageAqFactory)`                                                                                                                            | Coordinator only | Initialise the message factory contract |
-| `deploy(uint256 _duration, TreeDepths memory _treeDepths, BatchSizes memory _batchSizes, PubKey memory _coordinatorPubKey, VkRegistry _vkRegistry, IMACI _maci, address _pollOwner)` | Coordinator only | Create a new poll                       |
-
-### 5.4. VkRegistry
-
-| Function                                                                                                                                                                                                                   | Permissions      | Notes                                                                                                                                |
-| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| `isProcessVkSet(uint256 _sig)`                                                                                                                                                                                             | Non-applicable   | Query whether a signature is valid for message processing                                                                            |
-| `isTallyVkSet(uint256 _sig)`                                                                                                                                                                                               | Non-applicable   | Query whether a signature valid for tallying votes                                                                                   |
-| `genProcessVkSig(uint256 _stateTreeDepth, uint256 _messageTreeDepth, uint256 _voteOptionTreeDepth, uint256 _messageBatchSize)`                                                                                             | Non-applicable   | Generate a signature (used for verifying key mapping lookups) for message processing by compressing parameters into a singular value |
-| `genTallyVkSig(uint256 _stateTreeDepth, uint256 _intStateTreeDepth, uint256 _voteOptionTreeDepth)`                                                                                                                         | Non-applicable   | Generate a signature (used for verifying key mapping lookups) for vote tallying by compressing parameters into a singular value      |
-| `setVerifyingKeys( uint256 _stateTreeDepth, uint256 _intStateTreeDepth, uint256 _messageTreeDepth, uint256 _voteOptionTreeDepth, uint256 _messageBatchSize, VerifyingKey memory _processVk, VerifyingKey memory _tallyVk)` | Coordinator only | Initialise verifying keys for processing and tallying to the contract alongside specifying each tree depth                           |
-| `hasProcessVk(uint256 _stateTreeDepth, uint256 _messageTreeDepth, uint256 _voteOptionTreeDepth, uint256 _messageBatchSize)`                                                                                                | Non-applicable   | Query whether the signature of the parameters is valid for message processing                                                        |
-| `getProcessVkBySig(uint256 _sig)`                                                                                                                                                                                          | Non-applicable   | Query a processing verifying key by providing a valid signature                                                                      |
-| `getProcessVk(uint256 _stateTreeDepth, uint256 _messageTreeDepth, uint256 _voteOptionTreeDepth, uint256 _messageBatchSize)`                                                                                                | Non-applicable   | Query a processing verifying key by providing parameters to generate a valid signature                                               |
-| `hasTallyVk(uint256 _stateTreeDepth, uint256 _intStateTreeDepth, uint256 _voteOptionTreeDepth)`                                                                                                                            | Non-applicable   | Query whether the signature of the parameters is valid for vote tallying                                                             |
-| `getTallyVkBySig(uint256 _sig)`                                                                                                                                                                                            | Non-applicable   | Query a tallying verifying key by providing a valid signature                                                                        |
-| `getTallyVk(uint256 _stateTreeDepth, uint256 _intStateTreeDepth, uint256 _voteOptionTreeDepth)`                                                                                                                            | Non-applicable   | Query a tallying verifying key by providing parameters to generate a valid signature                                                 |
-
-### 5.5. PollProcessorAndTallyer
-
-| Function                                                                                                                                                                              | Permissions                                                    | Notes                                                                                                        |
-| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| `sha256Hash(uint256[] memory array)`                                                                                                                                                  | Non-applicable                                                 | Hash an array of values (using SHA256) moduluo the snark field size                                          |
-| `processMessages(Poll _poll, uint256 _newSbCommitment, uint256[8] memory _proof)`                                                                                                     | Executable only by the coordinator and after the voting period | Process state messages relative to a new state-ballot commitment given that the proof is valid               |
-| `verifyProcessProof(Poll _poll, uint256 _currentMessageBatchIndex, uint256 _messageRoot, uint256 _currentSbCommitment, uint256 _newSbCommitment, uint256[8] memory _proof)`           | Non-applicable                                                 | Query whether a message processing proof is valid                                                            |
-| `genProcessMessagesPublicInputHash(Poll _poll, uint256 _currentMessageBatchIndex, uint256 _messageRoot, uint256 _numSignUps, uint256 _currentSbCommitment, uint256 _newSbCommitment)` | Non-applicable                                                 | Hash of the coordinators public key, `packedVals`, current state-ballot commitment and message root          |
-| `genProcessMessagesPackedVals( Poll _poll, uint256 _currentMessageBatchIndex, uint256 _numSignUps)`                                                                                   | Non-applicable                                                 | Generate a packed 250-bit value `packedVals` for message processing                                          |
-| `genTallyVotesPackedVals( uint256 _numSignUps, uint256 _batchStartIndex, uint256 _tallyBatchSize)`                                                                                    | Non-applicable                                                 | Generate a packed 100-bit value `packedVals` for vote tallying                                               |
-| `genTallyVotesPublicInputHash( uint256 _numSignUps, uint256 _batchStartIndex, uint256 _tallyBatchSize, uint256 _newTallyCommitment )`                                                 | Non-applicable                                                 | Hash of the current tally commitment, the new tally commitment, `packedVals` and the state-ballot commitment |
-| `tallyVotes(Poll _poll, uint256 _newTallyCommitment, uint256[8] memory _proof)`                                                                                                       | Executable only by the coordinator and after the voting period | Tally votes relative to a new tally commitment given that the proof is valid                                 |
-| `verifyTallyProof(Poll _poll, uint256[8] memory _proof, uint256 _numSignUps, uint256 _batchStartIndex, uint256 _tallyBatchSize, uint256 _newTallyCommitment)`                         | Non-applicable                                                 | Query whether a vote tallying proof is valid                                                                 |
-
-## 6. zk-SNARKs
+| Command                       | Description                                                   | Notes                                                                                                                                        |
+| ----------------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `generateMaciPublicKey`       | Generate a MACI public key from a private key                 | Only the coordinator needs to run this, as users should generate their keys in the browser and should be automated by the client application |
+| `generateMaciKeypair`         | Generates a MACI private key and public key                   | Only the coordinator needs to run this, as users should generate their keys in the browser and should be automated by the client application |
+| `deployVerifyingKeysRegistry` | Deploy the `deployVerifyingKeysRegistry` contract             | Executed only the coordinator                                                                                                                |
+| `setVerifyingKeys`            | Set verifying keys to the `deployVerifyingKeysRegistry`       | Executed only the coordinator                                                                                                                |
+| `create`                      | Deploy a new instance of MACI                                 | Executed only the coordinator                                                                                                                |
+| `deployPoll`                  | Deploy a new poll on a MACI instance                          | Executed only the coordinator                                                                                                                |
+| `signup`                      | Sign up a user                                                | Mainly for testing; as users are more likely to use the client application instead of the CLI                                                |
+| `publish`                     | Submit a message to a poll                                    | Mainly for testing; as users are more likely to use the client application instead of the CLI                                                |
+| `mergeMessages`               | Must be executed before generating proofs                     | Executed only the coordinator                                                                                                                |
+| `mergeSignups`                | Must be executed before generating proofs                     | Executed only the coordinator                                                                                                                |
+| `generateProofs`              | Generate all message processing and vote tallying proofs      | Executed only the coordinator                                                                                                                |
+| `proveOnChain`                | Submit proofs to the `MessageProcessor` and `Tally` contracts | Executed only the coordinator                                                                                                                |
+
+## 5. zk-SNARKs
 
 The zk-SNARK circuits in MACI are written in the [circom](https://github.com/iden3/circom) language. Proofs are [Groth16](https://eprint.iacr.org/2016/260.pdf) and are generated using the [`rapidsnark`](https://github.com/iden3/rapidsnark) prover.
 
@@ -646,15 +580,15 @@ Please note that MACI requires the coordinator to generate proofs on an x86 mach
 
 ### 6.1. Message processing circuit
 
-The message processing circuit, defined in `circuits/circom/processMessages.circom`, allows the coordinator to prove that they have correctly applied each message in reverse order, in a consecutive batch of `5 ^ msgBatchDepth` messages to the respective state leaf within the state tree.
+The message processing circuit, defined in `circuits/circom/coordinator/qv/MessageProcessor.circom`, allows the coordinator to prove that they have correctly applied each message in reverse order, in a consecutive batch of `5 ^ messageBatchDepth` messages to the respective state leaf within the state tree.
 
 #### Parameters
 
 | Parameter             | Description                                                                                                                                                   |
 | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `stateTreeDepth`      | Depth of the state tree, this value must be equal to `10`                                                                                                     |
-| `msgTreeDepth`        | Depth of the message tree, this must be the same value passed to the `deployPoll()` contract function of `MACI.sol`                                           |
-| `msgBatchDepth`       | Depth of a tree that exactly fits the number of messages in a batch, this must be the same value passed to the `deployPoll()` contract function of `MACI.sol` |
+| `messageTreeDepth`    | Depth of the message tree, this must be the same value passed to the `deployPoll()` contract function of `MACI.sol`                                           |
+| `messageBatchDepth`   | Depth of a tree that exactly fits the number of messages in a batch, this must be the same value passed to the `deployPoll()` contract function of `MACI.sol` |
 | `voteOptionTreeDepth` | Depth of the vote option tree, this must be the same value passed to the `deployPoll()` contract function of `MACI.sol`                                       |
 
 The state tree, message tree, and vote option trees all have an arity of 5. As such, it is possible to calculate the maximum number of signups, messages per poll, and vote options per poll.
@@ -663,17 +597,17 @@ The state tree, message tree, and vote option trees all have an arity of 5. As s
 
 | 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                                          |
@@ -701,9 +635,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:
 
@@ -727,9 +661,9 @@ 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 <== (5 ^ 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 <== (5 ^ 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`
 
 #### How messages are decrypted and applied
@@ -813,21 +747,21 @@ The final tally should be:
 2. Total voice credits per vote option: `[3, 9, 19, 33, 26]`
 3. Total spent voice credits: `66`
 
-The coordinator uses the ballot tallying circuit (`tallyVotes.circom`) to generate proofs that they have correctly computed the tally. As there are many ballots to tally, each proof only computes the tally for a batch of ballots. Each proof is chained to the previous one such that each proof is also a proof of knowledge of the preimage of the previous tally commitment.
+The coordinator uses the ballot tallying circuit (`VoteTally.circom`) to generate proofs that they have correctly computed the tally. As there are many ballots to tally, each proof only computes the tally for a batch of ballots. Each proof is chained to the previous one such that each proof is also a proof of knowledge of the preimage of the previous tally commitment.
 
 #### Parameters
 
-| Parameter             | Description                                                                                                             |
-| --------------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| `stateTreeDepth`      | Depth of the state tree, this value must be equal to `10`                                                               |
-| `intStateTreeDepth`   | Depth of the intermediate state tree, `5 ** intStateTreeDepth` is the batch size                                        |
-| `voteOptionTreeDepth` | Depth of the vote option tree, this must be the same value passed to the `deployPoll()` contract function of `MACI.sol` |
+| Parameter                       | Description                                                                                                             |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `stateTreeDepth`                | Depth of the state tree, this value must be equal to `10`                                                               |
+| `tallyProcessingStateTreeDepth` | Depth of the intermediate state tree, `5 ** tallyProcessingStateTreeDepth` is the batch size                            |
+| `voteOptionTreeDepth`           | Depth of the vote option tree, this must be the same value passed to the `deployPoll()` contract function of `MACI.sol` |
 
 #### 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`                          | As described below                                               |
 | `currentTallyCommitment`                | As described below                                               |
@@ -874,8 +808,8 @@ $\mathsf{poseidon_3}([tc_r, tc_t, tc_p])$
 #### Statements that the circuit proves
 
 1. That the coordinator knows the preimage of `sbCommitment` (see above)
-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/core-concepts/workflow.md

@@ -66,7 +66,7 @@ Therefore, even if a coordinator is corrupt, they are unable to change a user’
 
 To explain the MACI workflow, let's give a quick overview of the key smart contracts.
 
-See our [smart contract docs](/docs/category/smart-contracts) or our [contract source code](https://github.com/privacy-scaling-explorations/maci/tree/dev/contracts/contracts) for a more in-depth explanation of all smart contracts.
+See our [smart contract docs](/docs/category/smart-contracts) or our [contract source code](https://github.com/privacy-scaling-explorations/maci/tree/main/contracts/contracts) for a more in-depth explanation of all smart contracts.
 
 ### MACI.sol
 
@@ -133,7 +133,7 @@ The `MessageProcessor` contract will send the proof to a separate verifier contr
 
 #### Tally Results
 
-Finally, once all messages have been processed, the coordinator tallies the votes of the valid messages (off-chain). The coordinator creates a zk-SNARK proving that the valid messages in the state tree (proved in Process Messages step) contain votes that sum to the given tally result. Then, they call [`Tally.tallyVotes()`](/docs/technical-references/smart-contracts/solidity-docs/Tally#tallyvotes) with a hash of the correct tally results and the zk-SNARK proof. Similarly to the processMessages function, the `tallyVotes` function will send the proof to a verifier contract to ensure that it is valid.
+Finally, once all messages have been processed, the coordinator tallies the votes of the valid messages (off-chain). The coordinator creates a zk-SNARK proving that the valid messages in the state tree (proved in Process Messages step) contain votes that sum to the given tally result. Then, they call [`Tally.tallyVotes()`](/docs/technical-references/smart-contracts/solidity-docs/Tally#tallyvotes) with a hash of the correct tally results and the zk-SNARK proof. Similarly to the `processMessages` function, the `tallyVotes` function will send the proof to a verifier contract to ensure that it is valid.
 
 <!-- "hash of the correct tally results" - so are the final results actually put on chain? or just a hash?? -->