@maci-protocol/website 0.0.0-ci.26f28d6

package/versioned_docs/version-v3.x/technical-references/smart-contracts/Poll.md

@@ -0,0 +1,170 @@
+---
+title: Poll Smart Contract
+description: MACI Poll Contract
+sidebar_label: Poll
+sidebar_position: 2
+---
+
+:::info
+Code location: [Poll.sol](https://github.com/privacy-scaling-explorations/maci/blob/dev/contracts/contracts/Poll.sol)
+:::
+
+This contract allows users to submit their votes.
+
+The main functions of the contract are as follows:
+
+- `publishMessage` - This function allows anyone to publish a message, and it accepts the message object as well as an ephemeral public key. This key together with the coordinator public key will be used to generate a shared ECDH key that will encrypt the message.
+  Before saving the message, the function will check that the voting deadline has not passed, as well as the max number of messages was not reached.
+- `publisMessageBatch` - This function allows to submit a batch of messages, and it accepts an array of messages with their corresponding public keys used in the encryption step. It will call the `publishMessage` function for each message in the array.
+- `joinPoll` - This function allows a user to join a poll. It will check if the voter is allowed to join the poll based on the sign up policy, as well as allocate voice credits based on the voice credit proxy.
+
+## JoinPoll
+
+The `joinPoll` function looks as follows:
+
+```ts
+  /// @inheritdoc IPoll
+  function joinPoll(
+    uint256 _nullifier,
+    PubKey calldata _pubKey,
+    uint256 _stateRootIndex,
+    uint256[8] calldata _proof,
+    bytes memory _signUpPolicyData,
+    bytes memory _initialVoiceCreditProxyData
+  ) external virtual isWithinVotingDeadline {
+    // Whether the user has already joined
+    if (pollNullifiers[_nullifier]) {
+      revert UserAlreadyJoined();
+    }
+
+    // Set nullifier for user's private key
+    pollNullifiers[_nullifier] = true;
+
+    // Verify user's proof
+    if (!verifyJoiningPollProof(_nullifier, _stateRootIndex, _pubKey, _proof)) {
+      revert InvalidPollProof();
+    }
+
+    // Check if the user is eligible to join the poll
+    extContracts.policy.enforce(msg.sender, _signUpPolicyData);
+
+    // Get the user's voice credit balance.
+    uint256 voiceCreditBalance = extContracts.initialVoiceCreditProxy.getVoiceCredits(
+      msg.sender,
+      _initialVoiceCreditProxyData
+    );
+
+    // Store user in the pollStateTree
+    uint256 stateLeaf = hashStateLeaf(StateLeaf(_pubKey, voiceCreditBalance, block.timestamp));
+
+    uint256 stateRoot = InternalLazyIMT._insert(pollStateTree, stateLeaf);
+
+    // Store the current state tree root in the array
+    pollStateRootsOnJoin.push(stateRoot);
+
+    uint256 pollStateIndex = pollStateTree.numberOfLeaves - 1;
+    emit PollJoined(_pubKey.x, _pubKey.y, voiceCreditBalance, block.timestamp, _nullifier, pollStateIndex);
+  }
+```
+
+## PublishMessage
+
+The `publishMessage` function looks as follows:
+
+```ts
+function publishMessage(Message calldata _message, PubKey calldata _encPubKey) public virtual isOpenForVoting {
+  // check if the public key is on the curve
+  if (!CurveBabyJubJub.isOnCurve(_encPubKey.x, _encPubKey.y)) {
+    revert InvalidPubKey();
+  }
+
+  // cannot realistically overflow
+  unchecked {
+    numMessages++;
+  }
+
+  // compute current message hash
+  uint256 messageHash = hashMessageAndEncPubKey(_message, _encPubKey);
+
+  // update current message chain hash
+  updateChainHash(messageHash);
+
+  emit PublishMessage(_message, _encPubKey);
+}
+```
+
+The `publishMessageBatch` function looks as follows:
+
+```ts
+function publishMessageBatch(Message[] calldata _messages, PubKey[] calldata _encPubKeys) public virtual {
+  if (_messages.length != _encPubKeys.length) {
+    revert InvalidBatchLength();
+  }
+
+  uint256 len = _messages.length;
+  for (uint256 i = 0; i < len; ) {
+    // an event will be published by this function already
+    publishMessage(_messages[i], _encPubKeys[i]);
+
+    unchecked {
+      i++;
+    }
+  }
+}
+```
+
+## MergeState
+
+After a Poll's voting period ends, the coordinator's job is to store the main state root, as well as some more information on the Poll contract using `mergeState`:
+
+```ts
+function mergeState() public isAfterVotingDeadline {
+  // This function can only be called once per Poll after the voting
+  // deadline
+  if (stateMerged) revert StateAlreadyMerged();
+
+  // set merged to true so it cannot be called again
+  stateMerged = true;
+
+  uint256 _mergedStateRoot = InternalLazyIMT._root(pollStateTree);
+  mergedStateRoot = _mergedStateRoot;
+
+  // Set currentSbCommitment
+  uint256[3] memory sb;
+  sb[0] = _mergedStateRoot;
+  sb[1] = emptyBallotRoot;
+  sb[2] = uint256(0);
+
+  currentSbCommitment = hash3(sb);
+
+  // get number of joined users and cache in a var for later use
+  uint256 _numSignups = pollStateTree.numberOfLeaves;
+  numSignups = _numSignups;
+
+  // dynamically determine the actual depth of the state tree
+  uint8 depth = 1;
+  while (uint40(1 << depth) < _numSignups) {
+    depth++;
+  }
+
+  actualStateTreeDepth = depth;
+
+  emit MergeState(mergedStateRoot, numSignups);
+}
+```
+
+The function will store the state root from the MACI contract, create a commitment by hashing this merkle root, an empty ballot root stored in the `emptyBallotRoot` variable, and a zero as salt. The commitment will be stored in the `currentSbCommitment` variable. Finally, it will store the total number of signups, and calculate the actual depth of the state tree. This information will be used when processing messages and tally to ensure proof validity.
+
+The `emptyBallotRoot` value is used to store the empty ballot root for the configured vote option tree depth. For instance, if the vote option tree depth is 5, a build script will generate the following values (this assumes that the state tree depth is 10):
+
+```javascript
+emptyBallotRoots[0] = uint256(16015576667038038422103932363190100635991292382181099511410843174865570503661);
+emptyBallotRoots[1] = uint256(166510078825589460025300915201657086611944528317298994959376081297530246971);
+emptyBallotRoots[2] = uint256(10057734083972610459557695472359628128485394923403014377687504571662791937025);
+emptyBallotRoots[3] = uint256(4904828619307091008204672239231377290495002626534171783829482835985709082773);
+emptyBallotRoots[4] = uint256(18694062287284245784028624966421731916526814537891066525886866373016385890569);
+```
+
+:::info
+Please be advised that the number of signups in this case includes the zero leaf. For this reason, when accounting for the real users signed up to the Poll, you should subtract one from the value stored in the Poll contract.
+:::

package/versioned_docs/version-v3.x/technical-references/smart-contracts/PollFactory.md

@@ -0,0 +1,33 @@
+---
+title: Poll Factory Smart Contract
+description: Poll Factory smart contract
+sidebar_label: PollFactory
+sidebar_position: 3
+---
+
+:::info
+Code location: [PollFactory.sol](https://github.com/privacy-scaling-explorations/maci/blob/dev/contracts/contracts/PollFactory.sol)
+:::
+
+`PollFactory` is a smart contract that is used to deploy new Polls. This is used by MACI inside the `deployPoll` function.
+
+```ts
+/// @inheritdoc IPollFactory
+function deploy(DeployPollArgs calldata _args) public virtual returns (address pollAddr) {
+  // deploy the poll
+  Poll poll = new Poll(
+    _args.startDate,
+    _args.endDate,
+    _args.treeDepths,
+    _args.messageBatchSize,
+    _args.coordinatorPubKey,
+    _args.extContracts,
+    _args.emptyBallotRoot,
+    _args.pollId,
+    _args.relayers,
+    _args.voteOptions
+  );
+
+  pollAddr = address(poll);
+}
+```

package/versioned_docs/version-v3.x/technical-references/smart-contracts/Tally.md

@@ -0,0 +1,43 @@
+---
+title: Tally Smart Contract
+description: Tally smart contract
+sidebar_label: Tally
+sidebar_position: 5
+---
+
+:::info
+Code location: [Tally.sol](https://github.com/privacy-scaling-explorations/maci/blob/dev/contracts/contracts/Tally.sol)
+:::
+
+The `Tally` contract is used by the coordinator to submit commitments to the tally results via the `tallyVotes` function. This is done in batches and the final commitment can be used by the users to verify the validity of the results.
+
+This contract should be deployed alongside a `Poll`, with the the constructor accepting the following parameters:
+
+```ts
+  constructor(
+    address _verifier,
+    address _vkRegistry,
+    address _poll,
+    address _mp,
+    address _tallyOwner,
+    Mode _mode
+  ) payable {
+    verifier = IVerifier(_verifier);
+    vkRegistry = IVkRegistry(_vkRegistry);
+    poll = IPoll(_poll);
+    messageProcessor = IMessageProcessor(_mp);
+    mode = _mode;
+  }
+```
+
+- `verifier` - The address of the verifier contract
+- `vkRegistry` - The address of the vkRegistry contract
+- `poll` - The address of the poll contract
+- `messageProcessor` - The address of the messageProcessor contract
+- `mode` - The mode of the tally contract - depending on this, the commitments will be processed differently, and it must equal the Poll mode (quadratic vs non quadratic voting)
+
+Users can use the verification functions to verify the Tally results. These are as follows:
+
+- `verifySpentVoiceCredits` - Verifies the spent voice credits
+- `verifyPerVOSpentVoiceCredits` - Verifies the spent voice credits per vote option
+- `verifyTallyResult` - Verifies the tally result

package/versioned_docs/version-v3.x/technical-references/smart-contracts/VkRegistry.md

@@ -0,0 +1,62 @@
+---
+title: VkRegistry Smart Contract
+description: VkRegistry smart contract
+sidebar_label: VkRegistry
+sidebar_position: 8
+---
+
+:::info
+Code location: [VkRegistry.sol](https://github.com/privacy-scaling-explorations/maci/blob/dev/contracts/contracts/VkRegistry.sol)
+:::
+
+The VkRegistry is a contract that holds the verifying keys for the zk-SNARK circuits. It holds four different sets of keys:
+
+- `processVks` - The keys for the processMessages circuit
+- `tallyVks` - The keys for the tallyVotes circuit
+- `pollJoiningVk` - The key for the poll joining circuit
+- `pollJoinedVk` - The key for the poll joined circuit
+
+Each circuit will have a signature which is its compile-time constants represented as a uint256.
+
+Please note that each Verifying Key should be set with the corresponding mode. Available modes are quadratic voting and non quadratic voting.
+
+The contract owner can set them using the `setVerifyingKeysBatch` function:
+
+```ts
+function setVerifyingKeysBatch(
+  uint256 _stateTreeDepth,
+  uint256 _intStateTreeDepth,
+  uint256 _voteOptionTreeDepth,
+  uint8 _messageBatchSize,
+  Mode[] calldata _modes,
+  VerifyingKey calldata _pollJoiningVk,
+  VerifyingKey calldata _pollJoinedVk,
+  VerifyingKey[] calldata _processVks,
+  VerifyingKey[] calldata _tallyVks
+) public onlyOwner {
+  if (_modes.length != _processVks.length || _modes.length != _tallyVks.length) {
+    revert InvalidKeysParams();
+  }
+
+  uint256 length = _modes.length;
+
+  setPollJoiningVkKey(_stateTreeDepth, _pollJoiningVk);
+  setPollJoinedVkKey(_stateTreeDepth, _pollJoinedVk);
+
+  for (uint256 index = 0; index < length; ) {
+    setVerifyingKeys(
+      _stateTreeDepth,
+      _intStateTreeDepth,
+      _voteOptionTreeDepth,
+      _messageBatchSize,
+      _modes[index],
+      _processVks[index],
+      _tallyVks[index]
+    );
+
+    unchecked {
+      index++;
+    }
+  }
+}
+```

package/versioned_docs/version-v3.x/technical-references/smart-contracts/VoiceCreditProxy.md

@@ -0,0 +1,18 @@
+---
+title: Voice Credits Proxy Smart Contract
+description: Voice Credits Proxy smart contract
+sidebar_label: VoiceCreditsProxy
+sidebar_position: 7
+---
+
+:::info
+Code location: [InitialVoiceCreditProxy](https://github.com/privacy-scaling-explorations/maci/tree/dev/contracts/contracts/initialVoiceCreditProxy)
+:::
+
+The VoiceCreditProxy contract is used to assign voice credits to users. Whichever implementation should the MACI deployers use, this must implement a view function that returns the balance for a user, such as the one below:
+
+```javascript
+function getVoiceCredits(address _user, bytes memory _data) public virtual view returns (uint256) {}
+```
+
+The repository comes with a simple implementation called `ConstantInitialVoiceCreditProxy` which assigns a fixed amount of voice credits to each user.

package/versioned_docs/version-v3.x/technical-references/smart-contracts/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Smart Contracts",
+  "position": 1,
+  "link": {
+    "type": "generated-index",
+    "description": "MACI is composed of multiple smart contracts, which together with the zk-SNARK circuits, can be used to carry out on-chain voting. The main contracts are presented and explained below. Please also find autogenerated solidity documentation with solidity-docs."
+  }
+}

package/versioned_docs/version-v3.x/technical-references/technical-references.md

@@ -0,0 +1,48 @@
+---
+title: MACI Codebase
+description: High-level overview of the MACI codebase
+sidebar_label: Technical References
+sidebar_position: 1
+---
+
+# MACI Overview
+
+The MACI codebase consists of three subsystems in different programming languages:
+
+1. Solidity smart contracts
+2. TypeScript libraries
+3. Circom circuits
+
+## Smart contracts
+
+The MACI smart contracts handle the on-chain aspects - both the functionality and the storage - of the voting system. They provide the functionality to deploy polls, register voters, and accept votes. They also store and manage the on-chain data from transactions, such as the encrypted votes of a poll. Finally, they verify proofs of the zk-SNARK circuits, so that everyone can validate the voting results.
+
+The MACI smart contracts are written in [Solidity](https://soliditylang.org/).
+
+Contracts are released through the [`@maci-contracts`](https://www.npmjs.com/package/maci-contracts) NPM package.
+
+[Learn more about MACI contracts](/docs/technical-references/smart-contracts/)
+
+## TypeScript libraries
+
+The TypeScript libraries manage the business logic between the smart contracts and the circuit code. They provide a variety of functionality, such as encryption tools, utilities, and a CLI for interacting with MACI (for actions like signing up, voting, tallying votes & generating proofs).
+
+The MACI [TypeScript](https://www.typescriptlang.org/) libraries are released through the following NPM packages:
+
+- [`@maci-cli`](https://www.npmjs.com/package/maci-cli)
+- [`@maci-core`](https://www.npmjs.com/package/maci-core)
+- [`@maci-crypto`](https://www.npmjs.com/package/maci-crypto)
+- [`@maci-domainobjs`](https://www.npmjs.com/package/maci-domainobjs)
+- [`@maci-integrationtests`](https://www.npmjs.com/package/maci-integrationtests)
+- [`@maci-sdk`](https://www.npmjs.com/package/maci-sdk)
+
+## Circuits
+
+MACI has multiple circuits that ensure all off-chain computation is completed correctly. The circuits are used to generate zero-knowledge proofs (zk-SNARKs) that the votes were counted correctly. Specifically, they enforce that message processing and vote tallying were correctly executed by the coordinator. The proofs can then be verified through a verifier smart contract on-chain.
+
+The circuits for these zero-knowledge proofs are written
+in [Circom](https://iden3.io/circom).
+
+The MACI circuits are released through the [`@maci-circuits`](https://www.npmjs.com/package/maci-circuits) NPM package.
+
+[Learn more about MACI circuits](/docs/technical-references/zk-snark-circuits/)

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

@@ -0,0 +1,4 @@
+{
+  "label": "zk-SNARK Circuits",
+  "position": 3
+}

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

@@ -0,0 +1,53 @@
+---
+title: MACI Poll Circuits
+description: Introduction to the core zk-SNARK circuits of MACI
+sidebar_label: Join Poll Circuit
+sidebar_position: 6
+---
+
+[**Repo link**](https://github.com/privacy-scaling-explorations/maci/blob/dev/circuits/circom/voter)
+
+## PollJoining
+
+Users need to provide a valid proof to the Poll smart contract to join a poll, allowing to vote on it. The circuit ensures that they signup to all polls with the same MACI public key, as well as that they can prove being included in MACI's state tree.
+
+#### Parameters
+
+| #   | Parameter        | Description               |
+| --- | ---------------- | ------------------------- |
+| 0   | State tree depth | Allows $(2^{n})$ signups. |
+
+#### Inputs
+
+| Input signal           | Description                                                                                                                                                                        |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `privKey`              | The user's private key                                                                                                                                                             |
+| `pollPubKey`           | The poll's public key                                                                                                                                                              |
+| `siblings`             | The siblings for the merkle tree inclusion proof                                                                                                                                   |
+| `indices`              | The indices for the merkle tree inclusion proof                                                                                                                                    |
+| `nullifier`            | The nullifier                                                                                                                                                                      |
+| `stateRoot`            | The MACI state tree root                                                                                                                                                           |
+| `actualStateTreeDepth` | The actual tree depth (might be less or equal to stateTreeDepth), used by the [LeanIMT structure](https://github.com/privacy-scaling-explorations/zk-kit/tree/main/papers/leanimt) |
+| `pollId`               | The poll id                                                                                                                                                                        |
+
+## PollJoined
+
+Users will use this circuit to anonymously prove that they joined a poll. This can be used to authenticate to the relayer service, to reduce spam.
+
+#### Parameters
+
+| #   | Parameter        | Description               |
+| --- | ---------------- | ------------------------- |
+| 0   | State tree depth | Allows $(2^{n})$ signups. |
+
+#### Inputs
+
+| Input signal           | Description                                                                                                                                                                        |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `privKey`              | The user's private key                                                                                                                                                             |
+| `voiceCreditsBalance`  | The user's initial voice credits balance                                                                                                                                           |
+| `joinTimestamp`        | The timestamp of when the user joined the poll                                                                                                                                     |
+| `pathElements`         | The path elements for the merkle tree inclusion proof                                                                                                                              |
+| `pathIndices`          | The path indices for the merkle tree inclusion proof                                                                                                                               |
+| `stateRoot`            | The MACI state tree root                                                                                                                                                           |
+| `actualStateTreeDepth` | The actual tree depth (might be less or equal to stateTreeDepth), used by the [LeanIMT structure](https://github.com/privacy-scaling-explorations/zk-kit/tree/main/papers/leanimt) |

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

@@ -0,0 +1,106 @@
+---
+title: MACI Process Messages Circuit
+description: Introduction to the core zk-SNARK circuits of MACI
+sidebar_label: Process Messages Circuit
+sidebar_position: 3
+---
+
+[**Repo link**](https://github.com/privacy-scaling-explorations/maci/blob/dev/circuits/circom/core)
+
+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.
+
+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 pre-requisites for this circuit are:
+
+- the related Poll has ended
+- the state tree has been merged
+- the message tree has been merged
+
+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)
+
+:::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.
+:::
+
+#### Parameters
+
+| #   | Parameter              | Description                    |
+| --- | ---------------------- | ------------------------------ |
+| 0   | State tree depth       | Allows $(2^{n})$ signups.      |
+| 1   | Message batch size     | The message batch size         |
+| 2   | Vote option tree depth | Allows $(5^{n})$ vote options. |
+
+#### Inputs
+
+| Input signal                     | Description                                                                             |
+| -------------------------------- | --------------------------------------------------------------------------------------- |
+| `numSignUps`                     | 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                                                                      |
+| `coordinatorPublicKeyHash`       | $\mathsf{poseidon_2}([cPk_x, cPk_y])$                                                   |
+| `newSbCommitment`                | As described below                                                                      |
+| `coordPrivKey`                   | 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    |
+| `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                                          |
+| `currentSbCommitment`            | As described below                                                                      |
+| `currentSbSalt`                  | As described below                                                                      |
+| `newSbCommitment`                | As described below                                                                      |
+| `newSbSalt`                      | As described below                                                                      |
+| `currentBallotRoot`              | The root of the ballot tree before messages are applied                                 |
+| `currentBallots`                 | The ballots upon which ballots are applied                                              |
+| `currentBallotsPathElements`     | The Merkle path to each incremental ballot root                                         |
+| `currentVoteWeights`             | The existing vote weight for the vote option in the ballot which each command refers to |
+| `currentVoteWeightsPathElements` | The Merkle path from each vote weight to the vote option root in its ballot             |
+
+##### `currentSbCommitment` and `newSbCommitment`
+
+The `currentSbCommitment` is the $poseidon_3$ hash of the state tree root, the ballot tree root, and a random salt. The purpose of the random salt, which should be unique to each batch, is to ensure that the value of `currentSbCommitment` always changes even if all the commands in a batch are invalid and therefore do not change the state tree or ballot tree root.
+
+The result of applying a batch of messages to `currentSbCommitment` is `newSbCommitment`.
+
+##### `currentSbSalt`
+
+The salt used to produce `currentSbCommitment` (see above).
+
+##### `newSbSalt`
+
+The salt used to produce `newSbCommitment` (see above).
+
+##### `msgSubrootPathElements`
+
+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`.
+
+A simplified example using a tree of arity 2:
+
+```
+             r
+           /  \
+          s    ...
+       /    \
+      o     o
+     / \   / \
+   a   b  c  d
+```
+
+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`.
+
+This method requires fewer circuit constraints than if we verified a Merkle proof for each leaf.
+
+#### Statements that the circuit proves
+
+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
+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

@@ -0,0 +1,96 @@
+---
+title: MACI Circuits setup
+description: Introduction to the core zk-SNARK circuits of MACI
+sidebar_label: Building and testing
+sidebar_position: 2
+---
+
+## Compile circuits
+
+### Prerequisites
+
+Before building the project, make sure you have the installed the dependencies as explained in the [installation](/docs/quick-start#installation) page.
+
+### Building MACI circuits
+
+To build the main circuits of MACI, run the following command (`-c` postfix for c++ witness gen, and `-wasm` postfix for WASM witness gen only):
+
+```
+pnpm build-test-circuits-c -- --out-path $OUT_PATH
+pnpm build-test-circuits-wasm -- --out-path $OUT_PATH
+```
+
+Please note that the circuits are configured with testing purpose parameters, which means it can only handle a limited amount of messages (up to 25 messages). For more information on the parameters and how to configure them, please refer to the individual circuit documentation within this page. Also, within the [configure-circomkit](/docs/guides/compile-circuits#configure-circomkit) section of the `compile circuits` page, you'll see how you can update the config file with new params.
+
+To compile a single circuit, you can run:
+
+```
+pnpm circom:build $CIRCUIT_NAME
+```
+
+> Please note that the name should match one of the circuit names inside the `circom.json` file.
+
+### Parameters
+
+MACI's circuits are parameterized, and thus can be configured to support different number of users, messages (votes), and vote options. Please ensure you understand what each of these parameter means and correctly configure them when building circuits from scratch, and when deploying the smart contracts.
+
+- **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)
+
+Please refer to the individual circuit documentation for more details on the inner working of each circuit and where parameters fit.
+
+### Generating zKeys
+
+Run from the root directory to save to the `cli/zkeys` folder:
+
+```bash
+pnpm setup:zkeys -- --outPath ../cli/zkeys
+```
+
+Run from the circuits folder with `--outPath` to save to a custom folder:
+
+```bash
+cd packages/circuits && pnpm gen-zkeys --outPath ./CUSTOM_FOLDER_NAME
+```
+
+The larger the trees, the more time this process may take. You may also need a
+machine with a very large amount of memory.
+
+> Note that you will have to modify the parameters inside the `./circuits/circom/circuits.json` file to match your use case. For example, if you want to support up to 3125 messages, the message tree depth parameter should be set to `5` (as $5^5 = 3125$).
+
+#### Measure the circuit sizes
+
+The size of a circuit is denoted by its number of constraints. The larger this
+number, the more time it takes to compile it, generate its `.zkey` file, and
+perform phase 2 contributions.
+
+Run this command to measure a circuit:
+
+```bash
+pnpm exec snarkjs r1cs info CIRCUIT_NAME.circom
+```
+
+#### Download the `.ptau` file
+
+This file should be the result of the Perpetual Powers of Tau trusted setup
+contribution which [Hermez Network
+selected](https://blog.hermez.io/hermez-cryptographic-setup/).
+
+When running the `setup:zkeys` command, the `.ptau` file will be downloaded automatically.
+
+### Generating and Validating ZK Proofs
+
+To generate and validate ZK proofs from the artifacts produced by `circom`, you will need [`snarkjs`](https://github.com/iden3/snarkjs#groth16-1).
+
+## Testing
+
+To test the circuits package, please use `pnpm run test`. This will run all of the tests inside the tests folder.
+
+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.
+
+More details on testing are provided in the [testing section](/docs/guides/testing/testing-introduction) of the documentation.