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

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

@@ -0,0 +1,79 @@
+---
+title: MACI Tally Votes Circuit
+description: Introduction to the core zk-SNARK circuits of MACI
+sidebar_label: Tally Votes Circuit
+sidebar_position: 4
+---
+
+[**Repo link**](https://github.com/privacy-scaling-explorations/maci/blob/dev/circuits/circom/core)
+
+#### Parameters
+
+| #   | Parameter              | Description                                              |
+| --- | ---------------------- | -------------------------------------------------------- |
+| 0   | State tree depth       | Allows $(5^{n})$ signups.                                |
+| 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)
+
+:::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.
+:::
+
+#### Input signals
+
+| Input signal                            | Description                                                      |
+| --------------------------------------- | ---------------------------------------------------------------- |
+| `numSignUps`                            | The number of users that signup                                  |
+| `index`                                 | Start index of given batch                                       |
+| `sbCommitment`                          | Described below                                                  |
+| `currentTallyCommitment`                | Described below                                                  |
+| `newTallyCommitment`                    | Described below                                                  |
+| `stateRoot`                             | The root of the state tree after all messages have been applied  |
+| `ballotRoot`                            | The root of the ballot tree after all messages have been applied |
+| `sbSalt`                                | The salt used to produce `sbCommitment`                          |
+| `ballots`                               | The ballots in the batch being tallied                           |
+| `ballotPathElements`                    | The Merkle path to each ballot leaf                              |
+| `votes`                                 | The votes in each ballot cast per result                         |
+| `currentResults`                        | The current tally of votes per vote option                       |
+| `currentResultsRootSalt`                | A random value                                                   |
+| `currentSpentVoiceCreditSubtotal`       | The subtotal of voice credits spent across all vote options      |
+| `currentSpentVoiceCreditSubtotalSalt`   | A random value                                                   |
+| `currentPerVOSpentVoiceCredits`         | The voice credits spent on each vote option so far               |
+| `currentPerVOSpentVoiceCreditsRootSalt` | A random value                                                   |
+| `newResultsRootSalt`                    | A random value                                                   |
+| `newPerVOSpentVoiceCreditsRootSalt`     | A random value                                                   |
+| `newSpentVoiceCreditSubtotalSalt`       | A random value                                                   |
+
+##### `sbCommitment`
+
+The commitment to `stateRoot`, `ballotRoot`, and `sbSalt`:
+
+$poseidon_3([stateRoot, ballotRoot, sbSalt])$
+
+Proving preimage of `sbCommitment` is one out of the several steps required to prove that the votes were tallied correctly. By establishing that the coordinator knows `ballotRoot`, the coordinator can (using other parts of the circuit) prove that they know the preimage of the ballot leaves in the batch being tallied.
+
+##### `currentTallyCommitment` and `newTallyCommitment`
+
+A tally is represented by a _tally commitment_, which is the $poseidon_3$ hash of:
+
+1. $tc_r$: a commitment to the votes per option
+   - This is the hash of the Merkle root $r_r$ of the votes and a salt $r_s$, computed as $poseidon_2([r_r, r_s])$
+2. $tc_t$: a commitment to the total spent voice credits
+   - This is the hash of the total spent voice credits $t_c$ and a salt $t_s$, computed as $poseidon_2([t_c, t_s])$
+3. $tc_p$: a commitment to the spent voice credits per vote option
+   - This is the hash of the Merkle root of the spent voice credits per vote option $p_v$ and a salt $p_s$, computed as $poseidon_2([p_v, p_s])$
+
+The tally commitment is computed as such:
+
+$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)`
+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

@@ -0,0 +1,131 @@
+---
+title: MACI Utility Circuits
+description: Introduction to the core zk-SNARK circuits of MACI
+sidebar_label: Utility Circuits
+sidebar_position: 5
+---
+
+#### Process Messages Input Hasher
+
+A utility circuit used by the main `processMessages` circuit to hash its inputs.
+
+![ProcessMessagesInputHasher](/img/circuits/processMessagesInputHasher.svg)
+
+It outputs one field element, which is the SHA256 hash of the following inputs:
+
+1. `packedVals`
+2. `pollEndTimestamp`
+3. `msgRoot`
+4. `coordinatorPubKeyHash`
+5. `newSbCommitment`
+6. `currentSbCommitment`
+
+#### Tally Votes Input Hasher
+
+A utility template that generates a sha256 hash of the provided tally inputs.
+
+![TallyVotesInputHasher](/img/circuits/tallyInputHasher.svg)
+
+It outputs one field element, which is the SHA256 hash of the following inputs:
+
+1. `packedVals`
+2. `sbCommitment`
+3. `currentTallyCommitment`
+4. `newTallyCommitment`
+
+#### ResultsCommitmentVerifier
+
+A utility circuit used by the main `tallyVotes` circuit to verify that the results commitment is correct.
+
+![ResultsCommitmentVerifier](/img/circuits/resultsCommitmentVerifier.svg)
+
+#### QuinCheckRoot
+
+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)
+
+#### CalculateTotal
+
+Utility circuit used to calculate the sum of an array of elements.
+
+![CalculateTotal](/img/circuits/calculateTotal.svg)
+
+#### ECDH
+
+Utility circuit used to generate a shared key from a private key and a public key.
+
+![ECDH](/img/circuits/ecdh.svg)
+
+#### Poseidon
+
+Utility circuit used to generate a Poseidon hash. In this case, it supports up to 13 inputs.
+
+![Poseidon13](/img/circuits/poseidonHasher13.svg)
+
+#### MessageToCommand
+
+Utility circuit used to convert a message into a command, this involves decrypting the message.
+
+![MessageToCommand](/img/circuits/messageToCommand.svg)
+
+#### MessageValidator
+
+Utility circuit used to validate a message. This performs several checks:
+
+- `stateTreeIndex` is valid
+- `voteOptionIndex` is valid
+- `nonce` is valid
+- the signature is valid
+- the user signed up before poll end timestamp
+- the user had enough voice credits
+
+![MessageValidator](/img/circuits/messageValidator.svg)
+
+#### PrivToPubKey
+
+Utility circuit used to generate a public key from a private key.
+
+![PrivToPubKey](/img/circuits/privToPubkey.svg)
+
+#### VerifySignature
+
+Utility circuit used to verify a EdDSA signature
+
+![VerifySignature](/img/circuits/verifySignature.svg)
+
+#### UnpackElement
+
+Utility circuit used to unpack an input element.
+
+![UnpackElement](/img/circuits/unpackElement.svg)
+
+#### QuinSelector
+
+Utility circuit used to select one element from an array of n elements at a given index.
+
+![QuinSelector](/img/circuits/quinSelector.svg)
+
+#### Splicer
+
+Utility circuit used to insert one element in an array at position `index`.
+
+![Splicer](/img/circuits/splicer.svg)
+
+#### QuinBatchLeavesExists
+
+Utility circuit used to check if a batch of leaves exists in a quinary tree.
+
+![QuinBatchLeavesExists](/img/circuits/quinBatchLeavesExists.svg)
+
+#### QuinGeneratePathIndices
+
+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)
+
+#### ProcessOne
+
+Utility circuit used to process one message.
+
+![ProcessOne](/img/circuits/processOne.svg)

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

@@ -0,0 +1,42 @@
+---
+title: MACI Circuits Introduction
+description: Introduction to the core zk-SNARK circuits of MACI
+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):
+
+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.
+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.
+
+Each circuit is parameterised and it is important to set the right parameters that 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$).
+
+## Background
+
+### zk-SNARKs
+
+zk-SNARKs are a type of zero-knowledge proof which allows a "prover" to prove to a "verifier" that they know a secret without revealing the secret itself. In MACI, the prover is the coordinator. MACI uses zk-SNARKs to prove that the coordinator has correctly processed the batches of messages and that all votes have been tallied correctly. A smart contract acts as the verifier to check the proof from the coordinator. Users can also verify that the process was done correctly at any point after the proof generation.
+
+### Circom
+
+MACI's circuits are written using [Circom](https://docs.circom.io/), a domain-specific language (DSL) used to write zk-SNARK circuits. Circom syntax resembles JavaScript, and it currently is one of the most popular DSL in use by zk developers. Please refer to their documentation to learn more about the language.
+
+### Proving system
+
+MACI uses [Groth16](https://eprint.iacr.org/2016/260.pdf) as its proving system. Groth16 is a zk-SNARK proving system that allows for the generation of proofs that are small and fast to verify.
+
+## How are the circuits used?
+
+The process messages and tally circuits are used by the coordinator (the prover) to prove that they have correctly processed a batch of messages and tallied the votes correctly. This happens after a Poll has completed, and the coordinator has merged the state and message trees. The coordinator then generates a proof for each batch of messages, and submits them to the contract. The contract then verifies the proofs and updates the commitments on chain.
+
+The poll joining circuit are used by users to prove that they know a private key for a public key signed up to the MACI smart contract, and to register to a specific poll. This happens when a user wants to register to a poll.
+
+Furthermore, an optional circuit is available to prove that a user has been registered to a specific poll. This is to be used when offchain voting is enabled, so that the coordinator relayer can use it as a way to prevent spam.
+
+## How do the Circuits fit in a voting round?
+
+![flow](/img/circuits/processingAfterPollEnds.svg)

package/versioned_docs/version-v3.x/use-cases/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Use Cases",
+  "position": 3
+}

package/versioned_docs/version-v3.x/use-cases/governance.md

@@ -0,0 +1,18 @@
+---
+title: Governance Applications
+description: Overview of MACI governance applications.
+sidebar_label: Governance
+sidebar_position: 1
+---
+
+MACI is designed to be used in a variety of applications where stakes are high, and we believe that governance is one of them.
+
+## DAOs Governance
+
+MACI, as a privacy-preserving on-chain voting protocol, enables the execution of on-chain proposals where results directly trigger smart contracts. Public voting in DAOs currently faces challenges such as vote coercion and bandwagon effects, which MACI aims to mitigate.
+
+In 2023 Nouns DAO, Aztec and Aragon ZK Research joined to do a Private Voting Research Sprint. You can read the technical report [here](https://research.aragon.org/nouns-tech.html) and the general report [here](https://research.aragon.org/nouns.html).
+
+## Elections
+
+We believe MACI could eventually be used in elections, where privacy is paramount. While we are still far from implementing government elections using MACI, work is being done to start testing the waters with college student councils. We are excited to continue working on making local elections a reality, together with our community and their contribution. Stay tuned.

package/versioned_docs/version-v3.x/use-cases/polling.md

@@ -0,0 +1,10 @@
+---
+title: Polling
+description: Overview of MACI polling applications.
+sidebar_label: Polling
+sidebar_position: 3
+---
+
+Polling typically involves surveying public opinion, and MACI can be effectively applied to this use case.
+
+Decentralized social networks, such as Farcaster or Lens, which are native to Web3, enable seamless integration for conducting private polls.

package/versioned_docs/version-v3.x/use-cases/public-goods.md

@@ -0,0 +1,65 @@
+---
+title: Public Goods Funding
+description: Overview of public goods funding.
+sidebar_label: Public Goods Funding
+sidebar_position: 2
+---
+
+# What is Public Goods Funding?
+
+Think crowdfunding and grant-giving where the community weighs the contribution of each project and decides how much of financial funding said project should receive.
+
+There are different flavors of funding mechanisms, you can find more information about each of them below:
+
+- [Simple Percentage](#simple-voting)
+- [Quadratic Funding](#quadratic-funding)
+- [Retroactive Public Goods Funding](#retroactive-public-goods-funding)
+
+## Simple Voting
+
+Public goods funding through a Simple Voting mechanism involves a pool of funds that is allocated based on the outcomes of a straightforward voting process. The percentage of votes received determines the corresponding percentage of the pool distributed.
+
+While Simple voting makes sense for some cases, we suggest using Quadratic Funding for more fair model. You can read more [here](#quadratic-funding-a-better-balance).
+
+## Quadratic Funding
+
+Quadratic funding (QF) is a crowdfunding mechanism that aims to distribute funds in a way that is more fair and inclusive than traditional crowdfunding. It works by matching small individual contributions with matching funds from a larger pool, using a quadratic formula.
+
+In a QF round, donors are incentivized to contribute money to a project or cause that they support. The matching funds are then distributed to the projects that receive the most support from the largest number of people. This helps to ensure that smaller, grassroots projects can receive funding and support, even if they don't have access to large donors or corporate sponsors.
+
+The quadratic formula used in this type of funding means that the matching funds increase exponentially with the number of individual contributors, which helps to amplify the impact of smaller donations and create a more equitable distribution of funds. This makes it possible for projects with a large number of small supporters to receive more funding than projects with just a few large supporters, which helps to level the playing field for smaller and less well-funded initiatives.
+
+Quadratic funding is made up of:
+
+1. a pool of funds to be distributed
+2. a voting system for distributing those funds
+
+Two common voting systems you may have used are 1-person-1-vote and 1-dollar-1-vote. Quadratic funding is a best-of-both-worlds solution where users vote with the **square root** of the money they spend — read on to learn more.
+
+### Quadratic Funding: a better balance?
+
+Quadratic funding is a compromise between 1-dollar-1-vote and 1-person-1-vote. Participants vote on how to distribute pooled funds by making individual donations, but each person's influence, rather than being the amount of money they spend, is the square root of that amount.
+
+Compared to 1-dollar-1-vote in the market, quadratic funding makes it exponentially easier for the influence of many poorer people to outweigh that of a single rich person:
+
+- 1-dollar-1-vote: 1 person paying \$10,000 has the same influence as 100 people paying \$100
+- Quadratic funding: 1 person paying \$10,000 has the same influence as 100 people paying \$1 or 10 people paying \$100
+
+Compared to 1-person-1-vote, quadratic funding lets the person who lives in Florida full-time, and cares twice as much about the vote's outcome than the person who lives in Florida half-time, have more influence:
+
+- 1-person-1-vote: the two Florida voters have equal influence
+- Quadratic funding: the full-time Florida resident, who cares twice as much, pays twice as much, and as a result gets 2^(1/2) times the influence of the half-time resident
+
+(It's important to note that while these example are a good demonstration of the argument for quadratic funding, they do over-simplify these situations, which are as sociological as they are mathematical.)
+
+### Quadratic Funding Resources
+
+- [Quadratic Payments: A Primer](https://vitalik.eth.limo/general/2019/12/07/quadratic.html)
+- [Liberal Radicalism: A Flexible Design For Philanthropic Matching Funds](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=3243656)
+- [Quadratic Voting](https://www.radicalxchange.org/concepts/plural-voting/)
+
+## Retroactive Public Goods Funding
+
+Retroactive Public Goods Funding (Retro Funding) is based on the idea that it’s easier to agree on what was useful in the past than what might be useful in the future. Originally was designed by Vitalik and a simple early version implemented by Optimism Foundation. You can read the original post [here](https://medium.com/ethereum-optimism/retroactive-public-goods-funding-33c9b7d00f0c).
+
+An implementation of Retro Funding with MACI is similar as using Quadratic Funding or Simple Majority, with the difference that the selected projects need to present what they have done and voters assign funds based on results.

package/versioned_sidebars/version-v0.x-sidebars.json

@@ -0,0 +1,8 @@
+{
+  "version-0.x/mySidebar": [
+    {
+      "type": "autogenerated",
+      "dirName": "."
+    }
+  ]
+}

package/versioned_sidebars/version-v1.2-sidebars.json

@@ -0,0 +1,8 @@
+{
+  "version-1.2/mySidebar": [
+    {
+      "type": "autogenerated",
+      "dirName": "."
+    }
+  ]
+}

package/versioned_sidebars/version-v2.x-sidebars.json

@@ -0,0 +1,8 @@
+{
+  "mySidebar": [
+    {
+      "type": "autogenerated",
+      "dirName": "."
+    }
+  ]
+}

package/versioned_sidebars/version-v3.x-sidebars.json

@@ -0,0 +1,8 @@
+{
+  "mySidebar": [
+    {
+      "type": "autogenerated",
+      "dirName": "."
+    }
+  ]
+}

package/versions.json

@@ -0,0 +1 @@
+["v3.x", "v2.x", "v1.2", "v0.x"]