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

package/versioned_docs/version-v3.x/guides/testing/testing-in-detail.md

@@ -0,0 +1,191 @@
+---
+title: MACI Testing in Detail
+description: How MACI tests work in detail
+sidebar_label: Testing in detail
+sidebar_position: 2
+---
+
+# Testing in detail
+
+This doc expands on our [introduction to testing](/docs/guides/testing/testing-introduction) doc and explains how MACI tests work in greater detail. This information should be used by MACI's maintainers as well as contributors.
+
+## Automated Tests
+
+### Integration Tests
+
+Integration tests follow a similar fashion of the e2e tests, though they also ensure that the tally results are as expected.
+
+Currently, tests are defined using a JSON file, here is one example:
+
+```json
+{
+  "name": "Happy path",
+  "description": "Full tree, 4 batches, no bribers",
+  "numVotesPerUser": 1,
+  "numUsers": 15,
+  "expectedTally": [15, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+  "expectedSpentVoiceCredits": [15, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+  "expectedTotalSpentVoiceCredits": 15
+}
+```
+
+This test will generate 15 signups (as expressed in `numUsers`), and submit one vote (`numVotesPerUser`) for each of the users. As we did not provide any vote detail, it will use the default: `weight = 1`, `option = 0` for all voters. This will result of course in a tally result of 15 for option 0, and 0 for all other options.
+
+Finally, the whole process of merging the state and message trees is performed, proofs are generated and the tally result is verified against the expected result.
+
+#### How to implement a new test case
+
+To add a new test case, it is quite simple. You can amend the `testing/ts/__tests__/data/suites.json` file and add your test declaration in there.
+
+```json
+{
+  "name": "4 voters 1 vote per user",
+  "description": "has correct results",
+  "numUsers": 4,
+  "numVotesPerUser": 1,
+  "votes": {
+    "0": {
+      "0": { "voteOptionIndex": 0, "voteWeight": 1, "valid": true }
+    },
+    "1": {
+      "0": { "voteOptionIndex": 0, "voteWeight": 1, "valid": true }
+    },
+    "2": {
+      "0": { "voteOptionIndex": 0, "voteWeight": 1, "valid": true }
+    },
+    "3": {
+      "0": { "voteOptionIndex": 0, "voteWeight": 1, "valid": true }
+    }
+  },
+  "expectedTally": [4, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+  "expectedSpentVoiceCredits": [4, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+  "expectedTotalSpentVoiceCredits": 4
+}
+```
+
+Let's look at the fields in detail:
+
+- `name`: the name of the test case
+- `description`: a description of the test case
+- `numUsers`: the number of users to generate
+- `numVotesPerUser`: the number of votes to generate for each user
+- `votes`: the votes to generate. This is an object where the key is the user index, and the value is another object where the key is the message index, and the value is the vote details. If you do not provide any vote details, the default will be used: `weight = 1`, `option = 0` for all voters.
+- `expectedTally`: the expected tally result for each vote option (in order)
+- `expectedSpentVoiceCredits`: the expected spent voice credits for each vote option (in order)
+- `expectedTotalSpentVoiceCredits`: the expected total spent voice credits
+
+As an example, let's try to implement a test given the following criteria:
+
+1. We want 10 users to signup
+2. We want each user to publish a different vote
+3. We want to verify that the tally result is as expected
+
+```json
+{
+  "name": "10 Users test",
+  "description": "Should signup 10 users, submit 10 votes and tally the results",
+  "numUsers": 10,
+  "numVotesPerUser": 1,
+  "votes": {
+    "0": {
+      "0": { "voteOptionIndex": 0, "voteWeight": 5 }
+    },
+    "1": {
+      "0": { "voteOptionIndex": 0, "voteWeight": 9 }
+    },
+    "2": {
+      "0": { "voteOptionIndex": 5, "voteWeight": 3 }
+    },
+    "3": {
+      "0": { "voteOptionIndex": 3, "voteWeight": 2 }
+    },
+    "4": {
+      "0": { "voteOptionIndex": 0, "voteWeight": 1 }
+    },
+    "5": {
+      "0": { "voteOptionIndex": 9, "voteWeight": 1 }
+    },
+    "6": {
+      "0": { "voteOptionIndex": 4, "voteWeight": 7 }
+    },
+    "7": {
+      "0": { "voteOptionIndex": 7, "voteWeight": 5 }
+    },
+    "8": {
+      "0": { "voteOptionIndex": 3, "voteWeight": 10 }
+    },
+    "9": {
+      "0": { "voteOptionIndex": 8, "voteWeight": 2 }
+    }
+  },
+  "expectedTally": [15, 0, 0, 12, 7, 3, 0, 5, 2, 1, 0, 0, 0, 0, 0, 0, 0, 0],
+  "expectedSpentVoiceCredits": [107, 0, 0, 104, 49, 9, 0, 25, 4, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+  "expectedTotalSpentVoiceCredits": 299
+}
+```
+
+**Why expectedTally as above**
+
+[(5 + 9 + 1), 0, 0, (2 + 10), 7, 3, 0, 5, 2, 1, 0, 0, 0, 0, 0, 0, 0, 0] -> [15, 0, 0, 12, 7, 3, 0, 5, 2, 1, 0, 0, 0, 0, 0, 0, 0, 0]
+
+**Why 299 voice credits spent**
+
+- 5 ** 2 + 9 ** 2 + 3 ** 2 + 2 ** 2 + 1 ** 2 + 1 ** 1 + 7 ** 2 + 5 ** 2 + 10 ** 2 + 2 ** 2 = 25 + 81 + 9 + 4 + 1 + 1 + 49 + 25 + 100 + 4 = 299
+
+**Why expectedSpentVoiceCredits as above**
+
+[(25 + 81 + 1), 0, 0, (4 + 100), 49, 0, 25, 4, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0] -> [107, 0, 0, 104, 49, 0, 25, 4, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
+
+#### MACI keys integration tests
+
+Another test file which is found inside the integration tests folder is the `maciKeys.test.ts` file. This file contains a number of tests that are used to verify that the MACI keys work as expected. These tests are written in TypeScript and use the `mocha` and `chai` frameworks.
+
+They are testing that between the `contracts`, `domainobjs` and `crypto` packages, the MACI keys are working correctly, and are serialized/deserialized as expected. This is particularly important to test due to different data formats for keys, especially when parsed from the smart contract events.
+
+### Contract tests
+
+Within the contracts folder, there are a number of tests that are used to verify that the contracts work as expected. These tests are written in TypeScript and use the `hardhat` framework.
+
+These tests interact with all other packages, such as crypto, domainobjs and core, where mock data comes from. Their main goal is to ensure that the smart contracts have the correct parameters when deployed, privileged functions cannot be called by non-privileged users, and that the contract state is as expected after a series of operations.
+
+### Circuits tests
+
+Within the circuits folder, there are a number of tests that are used to verify that the circuits work as expected. These tests are written in TypeScript and use the `circom_tester` (which runs on top of `mocha` and `chai`).
+
+These tests often use mock data from the `core` package. For instance, when testing the `processMessages` circuit, we are required to generate the parameters from the `core` packing, using the `Poll:processMessages` function. The same applies to vote tallying, where we need the `Poll:tally` function to be run first with mock users and vote messages.
+
+All of the tests run using test parameters, usually `10, 20, 2`, aside from the tests inside: [`ceremonyParam`](https://github.com/privacy-scaling-explorations/maci/blob/dev/circuits/ts/__tests__/CeremonyParams.test.ts) which use the parameters of the latest MACI ceremony. More details on the trusted setup can be found [here](/docs/security/trusted-setup).
+
+### Core
+
+The core package contains a number of tests that are used to verify that the core functions work as expected. These tests are written in TypeScript and use the `mocha` and `chai` frameworks.
+
+These tests interact with the crypto and dombinobjs packages, where mock data comes from. Their main goal is to ensure that the core functions work as expected, and that the state is as expected after a series of operations.
+
+Currently, there is a blend of e2e and unit tests, where e2e tests are used to verify that the entire MACI local processing works as expected (users signup, publish votes, messages are processed and finally these votes are tallied). Unit tests on the other hand are used to verify that the core functions work as expected, such as `processMessage` and `tallyVotes`. You will find them in separate files, with e2e being [here](https://github.com/privacy-scaling-explorations/maci/blob/dev/core/ts/__tests__/e2e.test.ts) and unit tests in the other files.
+
+### Domainobjs/Crypto tests
+
+These tests are used to verify that MACI's primitives such as private keys work as expected. They are written in TypeScript and use the `mocha` and `chai` frameworks.
+
+## "Manual" Testing
+
+To ensure that the MACI stack works as expected, without having to run the entire test suite (or even just the e2e tests), there is a [bash script](https://github.com/privacy-scaling-explorations/maci/blob/dev/packages/contracts/testScriptLocalhost.sh) inside the contracts folder which can be used.
+
+This script contains a number of actions which touch all of the parts of MACI, and resemble exactly what other e2e tests do.
+
+Looking at this in more details we do the following:
+
+1. Deploy a `VkRegistry` contract
+2. Set the verification keys on this smart contract
+3. Deploy a `MACI` contract (and associated utility contracts)
+4. Deploy a Poll from the MACI contract.
+5. Signup 1 user
+6. Publish 2 messages
+7. Travel in time (local blockchain node) to arrive at the end of the poll
+8. Merge the tree commitments on chain
+9. Generate proofs for the message processing and vote tallying
+10. Update the on chain state
+11. Verify that proofs and tally are correct
+
+The above is the minimum required to ensure that the stack works as expected, as it encompasses actions from both voters and the coordinator.

package/versioned_docs/version-v3.x/guides/testing/testing-introduction.md

@@ -0,0 +1,158 @@
+---
+title: Testing MACI
+description: An introduction on how to test MACI
+sidebar_label: Testing Introduction
+sidebar_position: 1
+---
+
+# Testing introduction
+
+## Unit tests
+
+Unit tests within the project are built using [Mocha](https://mochajs.org/) and [Chai](https://www.chaijs.com/). Mocha is a test framework that provides the environment to write and run JavaScript tests, while Chai is an assertion library that allows us to write assertions in a more expressive and readable way.
+
+The following submodules contain unit tests: `core`, `crypto`, `circuits`,
+`contracts`, and `domainobjs`.
+
+You can run all unit tests from the root directory of the repo by running:
+
+```bash
+pnpm run test
+```
+
+Or you can run unit tests within each submodule. for example to run the `crypto` tests:
+
+```bash
+cd packages/crypto
+pnpm run test
+```
+
+You can also run individual tests within submodules, for example:
+
+```bash
+cd packages/contracts
+pnpm run test:tally
+```
+
+This test command will run `Tally.test.ts`
+
+### Contracts
+
+First, compile the contracts.
+
+From the main `maci/` directory, run:
+
+```bash
+cd packages/contracts && \
+pnpm run compileSol
+```
+
+To run Contracts only tests, run:
+
+```bash
+pnpm run test
+```
+
+### Circuits
+
+To test the circuits, from the main `maci/` directory, run:
+
+```bash
+cd packages/circuits && \
+pnpm run test
+```
+
+Tests are run using [Mocha](https://mochajs.org/) and [`circom_tester`](https://github.com/iden3/circom_tester).
+
+## CLI
+
+You can test the CLI locally. First, you need to either generate `.zkey` files,
+or download them. Please remember to not use these testing `.zkey` files in production.
+
+### Download `.zkey` files or the witness generation binaries
+
+MACI has two main zk-SNARK circuits, `processMessages` and `tallyVotes`.
+
+:::info
+The `processMessages` and `tallyVotes` circuits are also provided in a non-quadratic voting (non-QV) version. Currently these new versions have not undergone a trusted setup ceremony.
+:::
+
+Each circuit is parameterised and there should be one
+`.zkey` file for each circuit and set of parameters.
+
+Unless you wish to generate a fresh set of `.zkey` files, you should obtain
+them from someone who has performed a multi-party trusted setup for said
+circuits.
+
+Note the locations of the `.zkey` files as the smart contract tasks require them as part of the JSON configuration file.
+
+For testing purposes you can download the required artifacts using the [`download-zkeys:test`](https://github.com/privacy-scaling-explorations/maci/blob/dev/package.json#L15). The script will place all required artifacts inside the `cli/zkeys` folder.
+
+You can run the script directly with bash or use pnpm: `pnpm run download:test-zkeys` from the monorepo root.
+
+### Compile the circuits and generate zkeys (if decided to generate from scratch)
+
+From the root folder, run:
+
+**for c++ witness generator**
+
+```bash
+pnpm build:circuits-c -- --outPath ../testing/zkeys
+```
+
+**for wasm witness generator**
+
+```bash
+pnpm build:circuits-wasm -- --outPath ../testing/zkeys
+```
+
+**generate zkeys**
+
+```bash
+pnpm setup:zkeys --outPath ../testing/zkeys
+```
+
+### Check the Rapidsnark binary
+
+Next, ensure that the `prover` binary of `rapidsnark` is in
+`~/rapidsnark/build/prover`.
+
+:::info
+This step is only required if you wish to use rapidsnark, for faster proof generation. You can also use the WASM witnesses provided in the `testing/zkeys` folder.
+:::
+
+### Run CLI tests
+
+You can find the tests in `maci/testing/ts/__tests__`.
+
+To run the tests first start a hardhat node in the background:
+
+```bash
+cd packages/contracts
+pnpm run hardhat &
+cd ../testing/ts
+```
+
+Then run the tests (this will run all tests):
+
+```bash
+pnpm run test
+```
+
+To run e2e tests (quadratic voting):
+
+```bash
+pnpm run test:e2e
+```
+
+To run e2e tests with normal voting (not quadratic voting):
+
+```bash
+pnpm run test:e2e-non-qv
+```
+
+To run integration tests:
+
+```bash
+pnpm run test:integration
+```

package/versioned_docs/version-v3.x/guides/troubleshooting.md

@@ -0,0 +1,161 @@
+---
+title: Troubleshooting
+description: How to troubleshoot MACI's failures
+sidebar_label: Troubleshooting
+sidebar_position: 5
+---
+
+# Troubleshooting
+
+## cli: `genProofs` command failure
+
+### Case: missing `.dat` files
+
+If your logs look like the following, then make sure you have `ProcessMessages_10-2-1-2_test.dat` and `TallyVotes_10-1-2_test.dat` files in the same directory as your zkeys:
+
+```
+node build/ts/index.js genProofs -x 0xf204a4Ef082f5c04bB89F7D5E6568B796096735a \
+>     -sk macisk.49953af3585856f539d194b46c82f4ed54ec508fb9b882940cbe68bbc57e59e \
+>     -o 0 \
+>     -r ~/rapidsnark/build/prover \
+>     -wp ./zkeys/ProcessMessages_10-2-1-2_test \
+>     -wt ./zkeys/TallyVotes_10-1-2_test \
+>     -zp ./zkeys/ProcessMessages_10-2-1-2_test.0.zkey \
+>     -zt ./zkeys/TallyVotes_10-1-2_test.0.zkey \
+>     -t tally.json \
+>     -f proofs
+
+fromBlock = 0
+Generating proofs of message processing...
+terminate called after throwing an instance of 'std::system_error'
+  what():  open: No such file or directory
+Aborted (core dumped)
+
+terminate called after throwing an instance of 'std::system_error'
+  what():  open: No such file or directory
+Aborted (core dumped)
+
+Error: could not generate proof.
+Error: Error executing ./zkeys/ProcessMessages_10-2-1-2_test /tmp/tmp-9904-zG0k8YPTATWB/input.json /tmp/tmp-9904-zG0k8YPTATWB/output.wtns
+    at genProof (/home/ubuntu/maci/circuits/ts/index.ts:44:15)
+    at /home/ubuntu/maci/cli/ts/genProofs.ts:339:25
+    at step (/home/ubuntu/maci/cli/build/genProofs.js:33:23)
+    at Object.next (/home/ubuntu/maci/cli/build/genProofs.js:14:53)
+    at fulfilled (/home/ubuntu/maci/cli/build/genProofs.js:5:58)
+```
+
+You can generate the missing `.dat` files using the following command:
+
+```bash
+pnpm build:circuits-c -- --outPath ../cli/zkeys
+```
+
+## contracts: `prove` command failure
+
+### Case `Commitment mismatch`
+
+If your log looks like the following, that's because you have already run the `prove` command. You can access the `cli` and attempt again by executing the `genProofs` command.
+
+```
+Error: commitment mismatch
+    at Prover.validateCommitment (/home/user/Documents/maci/contracts/tasks/helpers/Prover.ts:458:13)
+    at Prover.proveTally (/home/user/Documents/maci/contracts/tasks/helpers/Prover.ts:390:12)
+    at processTicksAndRejections (node:internal/process/task_queues:95:5)
+    at async SimpleTaskDefinition.action (/home/user/Documents/maci/contracts/tasks/runner/prove.ts:235:7)
+    at async Environment._runTaskDefinition (/home/user/Documents/maci/node_modules/.pnpm/hardhat@2.22.2_ts-node@10.9.2_typescript@5.4.3/node_modules/hardhat/src/internal/core/runtime-environment.ts:359:14)
+    at async Environment.run (/home/user/Documents/maci/node_modules/.pnpm/hardhat@2.22.2_ts-node@10.9.2_typescript@5.4.3/node_modules/hardhat/src/internal/core/runtime-environment.ts:192:14)
+    at async main (/home/user/Documents/maci/node_modules/.pnpm/hardhat@2.22.2_ts-node@10.9.2_typescript@5.4.3/node_modules/hardhat/src/internal/cli/cli.ts:323:7)
+ ELIFECYCLE  Command failed with exit code 1.
+ ELIFECYCLE  Command failed with exit code 1.
+```
+
+This is because commitments are generated using random salts, thus will differ at each `genProofs` run.
+
+In [core/Poll.ts](https://github.com/privacy-scaling-explorations/maci/blob/dev/packages/core/ts/Poll.ts):
+
+```
+let newSbSalt = genRandomSalt();
+while (this.sbSalts[this.currentMessageBatchIndex!] === newSbSalt) {
+  newSbSalt = genRandomSalt();
+}
+```
+
+## General Failure
+
+### Case `AssertionError`
+
+This could happen when you run `prove` in the `contracts` package, or run `genProofs` in the `cli` package. If your log looks like the following, there are two possible reasons:
+
+1. If your MACI keypair for the coordinator was generated based on a previous version, it may have been generated incorrectly due to a breaking change in a third-party package (`zk-kit/eddsa-poseidon`). Please generate a new pair and run the whole process again.
+2. The provided private key is unmatched to the public key which deployed the poll, you will need to input the correct private key.
+
+```
+An unexpected error occurred:
+
+AssertionError [ERR_ASSERTION]: false == true
+    at genMaciStateFromContract (/home/user/Documents/maci/contracts/ts/genMaciState.ts:156:9)
+    at processTicksAndRejections (node:internal/process/task_queues:95:5)
+    at async SimpleTaskDefinition.action (/home/user/Documents/maci/contracts/tasks/runner/prove.ts:127:25)
+    at async Environment._runTaskDefinition (/home/user/Documents/maci/node_modules/.pnpm/hardhat@2.22.2_ts-node@10.9.2_typescript@5.4.3/node_modules/hardhat/src/internal/core/runtime-environment.ts:359:14)
+    at async Environment.run (/home/user/Documents/maci/node_modules/.pnpm/hardhat@2.22.2_ts-node@10.9.2_typescript@5.4.3/node_modules/hardhat/src/internal/core/runtime-environment.ts:192:14)
+    at async main (/home/user/Documents/maci/node_modules/.pnpm/hardhat@2.22.2_ts-node@10.9.2_typescript@5.4.3/node_modules/hardhat/src/internal/cli/cli.ts:323:7) {
+  generatedMessage: true,
+  code: 'ERR_ASSERTION',
+  actual: false,
+  expected: true,
+  operator: '=='
+}
+```
+
+### Cannot filter non-indexed parameters
+
+If you encountered the following error log:
+
+```
+TypeError: cannot filter non-indexed parameters; must be null (argument="contract._messageRoot", value=4658669366154318429589992378027343879410506110087584229116806667655891474709, code=INVALID_ARGUMENT, version=6.11.1)
+    at makeError (/home/user/Documents/maci/node_modules/.pnpm/ethers@6.11.1/node_modules/ethers/src.ts/utils/errors.ts:687:21)
+    at assert (/home/user/Documents/maci/node_modules/.pnpm/ethers@6.11.1/node_modules/ethers/src.ts/utils/errors.ts:715:25)
+    at assertArgument (/home/user/Documents/maci/node_modules/.pnpm/ethers@6.11.1/node_modules/ethers/src.ts/utils/errors.ts:727:5)
+    at /home/user/Documents/maci/node_modules/.pnpm/ethers@6.11.1/node_modules/ethers/src.ts/abi/interface.ts:1047:31
+    at Array.forEach (<anonymous>)
+    at Interface.encodeFilterTopics (/home/user/Documents/maci/node_modules/.pnpm/ethers@6.11.1/node_modules/ethers/src.ts/abi/interface.ts:1042:16)
+    at /home/user/Documents/maci/node_modules/.pnpm/ethers@6.11.1/node_modules/ethers/src.ts/contract/contract.ts:108:39
+    at processTicksAndRejections (node:internal/process/task_queues:95:5)
+    at async getSubInfo (/home/user/Documents/maci/node_modules/.pnpm/ethers@6.11.1/node_modules/ethers/src.ts/contract/contract.ts:502:18)
+    at async Proxy.queryFilter (/home/user/Documents/maci/node_modules/.pnpm/ethers@6.11.1/node_modules/ethers/src.ts/contract/contract.ts:938:38) {
+  code: 'INVALID_ARGUMENT',
+  argument: 'contract._messageRoot',
+  value: 4658669366154318429589992378027343879410506110087584229116806667655891474709n,
+  shortMessage: 'cannot filter non-indexed parameters; must be null'
+}
+```
+
+This could happen during running `genProofs` in `cli` package, or running `prove` in `contracts` package.
+Be aware that we updated several parameters to `indexed`:
+
+```javascript
+event MergeMaciStateAqSubRoots(uint256 indexed _numSrQueueOps);
+event MergeMaciStateAq(uint256 indexed _stateRoot, uint256 indexed _numSignups);
+event MergeMessageAqSubRoots(uint256 indexed _numSrQueueOps);
+event MergeMessageAq(uint256 indexed _messageRoot);
+```
+
+Please remember to pull the latest MACI repo updates(`git fetch origin && git pull origin dev`) and run `pnpm build` in the root of this monorepo.
+
+### Verifier contract found the proof invalid
+
+If your log looks like the following, that's because the zkey and wasm files added to the [`VkRegistry` contract](/docs/technical-references/smart-contracts/VkRegistry) are different from what you use to run the **prove** command. Check if you're using the correct zkey and wasm files.
+
+```
+Error: The verifier contract found the proof invalid.
+    at Prover.proveMessageProcessing (/home/user/Documents/maci/contracts/tasks/helpers/Prover.ts:215:15)
+    at processTicksAndRejections (node:internal/process/task_queues:95:5)
+    at async SimpleTaskDefinition.action (/home/user/Documents/maci/contracts/tasks/runner/prove.ts:185:7)
+    at async Environment._runTaskDefinition (/home/user/Documents/maci/node_modules/.pnpm/hardhat@2.22.2_ts-node@10.9.2_typescript@5.4.4/node_modules/hardhat/src/internal/core/runtime-environment.ts:359:14)
+    at async Environment.run (/home/user/Documents/maci/node_modules/.pnpm/hardhat@2.22.2_ts-node@10.9.2_typescript@5.4.4/node_modules/hardhat/src/internal/core/runtime-environment.ts:192:14)
+    at async main (/home/user/Documents/maci/node_modules/.pnpm/hardhat@2.22.2_ts-node@10.9.2_typescript@5.4.4/node_modules/hardhat/src/internal/cli/cli.ts:323:7)
+```
+
+### The on-chain verification of total spent voice credits failed
+
+If you ran the `verify` command and got this error, please ensure consistency in your use of quadratic voting throughout interactions with MACI, including poll deployment, proof generation, and verification.

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

@@ -0,0 +1,153 @@
+---
+title: What is MACI?
+description: High-level introduction to Minimum Anti-Collusion Infrastructure (MACI)
+sidebar_label: What is MACI?
+sidebar_position: 1
+---
+
+# Welcome to MACI
+
+![MACI card](/img/maci-card.png)
+
+## What is MACI?
+
+**Minimal Anti-Collusion Infrastructure (MACI)** is an open-source public good that serves as infrastructure for private on-chain voting.
+
+MACI is an Ethereum application that provides privacy and collusion resistance for on-chain voting, both in a [quadratic](https://vitalik.eth.limo/general/2019/12/07/quadratic.html) and non-quadratic fashion. A common problem among today’s on-chain voting (or public good funding) processes is how easy it is to bribe voters into voting for a particular option. Since all transactions on the blockchain are public by default, without MACI, voters can easily prove to the briber which option they voted for and therefore receive the bribe rewards.
+
+MACI counters this problem by using encryption and zero-knowledge proofs (zk-SNARKs) to hide how each person voted while still publicly revealing the final result. User’s cannot prove which option they voted for, and therefore bribers cannot reliably trust that a user voted for their preferred option. For example, a voter can tell a briber that they are voting for option A, but in reality they voted for option B. There is no reliable way to prove which option the voter actually voted for, so the briber has less incentive to pay voters to vote their way.
+
+Applications like [clr.fund](https://clr.fund/) or protocols like [Allo](https://github.com/gitcoinco/MACI_QF) build atop MACI to increase
+user privacy and discourage collusion or bribery for public goods funding.
+
+## Why MACI Matters
+
+To understand the promise of on-chain voting and the purpose of MACI, we highly recommend reading [Vitalik's post on blockchain voting](https://vitalik.eth.limo/general/2021/05/25/voting2.html). He provides an overview of the incredible potential of e-voting and why blockchains are an excellent technology to implement e-voting solutions on top of.
+
+Below we attempt to summarize some of the points laid out in that post:
+
+### Security requirements of a voting system
+
+Any voting system requires a few crucial security properties in order to be trusted by users:
+
+- **Correct execution**: the result (tally of votes) must be correct, and the result must be guaranteed by a transparent process (so that everyone is convinced that the result is correct)
+- **Censorship resistance**: anyone eligible to vote should be able to vote, and it should not be possible to interfere with anyone's attempt to vote or to prevent anyone’s vote from being counted
+- **Privacy:** you should not be able to tell which candidate someone specific voted for, or even if they voted at all
+- **Coercion resistance:** you should not be able to prove to someone else how you voted, even if you want to
+
+### Voting systems
+
+Looking at various approaches to implement a voting system, we can see how they compare across these properties.
+
+#### In-person voting systems
+
+In short, it's hard to know for sure how current voting systems operate. Governments and corporations spend lots of resources on their systems and processes in an attempt to ensure their integrity, but ultimately neither the systems nor the processes are fully auditable, so we must trust that these security properties are being enforced.
+
+|                       | In-person |
+| --------------------- | --------- |
+| Correct execution     | 🤷‍♂️        |
+| Censorship resistance | 🤷‍♂️        |
+| Privacy               | 🤷‍♂️        |
+| Collusion resistance  | 🤷‍♂️        |
+
+#### Blockchain voting systems
+
+Blockchains provide two key properties: correct execution and censorship resistance. In terms of execution, the blockchain accepts inputs (transaction) from users, correctly processes them according to some pre-defined rules, and returns the correct output. No one is able to change the rules. Any user that wants to send a transaction and is willing to pay a high enough fee can send the transaction and expect to see it quickly included on-chain.
+
+By default, however, Blockchain voting applications face challenges. Ethereum, like most blockchains, is completely transparent - all transaction data is public, so there is no privacy for voters or their votes. This makes bribery very easy as a result: someone can easily show a transaction receipt that proves how they voted. In some cases, bribery can be completely automated via smart contracts to make collusion entirely trustless.
+
+|                       | In-person | Ethereum |
+| --------------------- | --------- | -------- |
+| Correct execution     | 🤷‍♂️        | ✅       |
+| Censorship resistance | 🤷‍♂️        | ✅       |
+| Privacy               | 🤷‍♂️        | ❌       |
+| Collusion resistance  | 🤷‍♂️        | ❌       |
+
+#### Blockchain voting systems (with ZKPs)
+
+Enter zero-knowledge proofs (ZKPs), which when combined with blockchains like Ethereum, can enable private on-chain voting but maintain public on-chain results that are verifiable by anyone (including smart contracts). Vote tallying takes place off-chain but ZKPs are submitted and verified on-chain, which guarantees votes are counted correctly without revealing the individual votes.
+
+|                       | In-person | Ethereum | Ethereum w/ ZK |
+| --------------------- | --------- | -------- | -------------- |
+| Correct execution     | 🤷‍♂️        | ✅       | ✅             |
+| Censorship resistance | 🤷‍♂️        | ✅       | ✅             |
+| Privacy               | 🤷‍♂️        | ❌       | ✅             |
+| Collusion resistance  | 🤷‍♂️        | ❌       | ✅             |
+
+This, in essence, is why MACI exists. By combining these technologies in novel ways, we believe we can achieve all the core security properties that a voting system must have.
+
+## Features
+
+MACI offers the following guarantees:
+
+| Property                 | Description                                                                                                             |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| **Collusion Resistance** | No one except a trusted coordinator should be certain of the validity of a vote, reducing the effectiveness of bribery. |
+| **Receipt-freeness**     | No one can prove (besides to the coordinator) which way they voted.                                                     |
+| **Privacy**              | No one except a trusted coordinator should be able to decrypt a vote.                                                   |
+| **Uncensorability**      | No one — not even the trusted coordinator, should be able to censor a vote.                                             |
+| **Unforgeability**       | Only the owner of a user's private key may cast a vote tied to its corresponding public key.                            |
+| **Non-repudiation**      | No one may modify or delete a vote after it is cast, although a user may cast another vote to nullify it.               |
+| **Correct execution**    | No one, not even the trusted coordinator, should be able to produce a false tally of votes.                             |
+
+Under the hood, MACI uses Ethereum smart contracts, ECDH encryption, and zero-knowledge proofs.
+It inherits security and uncensorability from the underlying Ethereum
+blockchain, ensures unforgeability via asymmetric encryption, and achieves
+collusion resistance, privacy, and correct execution via zk-SNARK proofs.
+
+The participants of a MACI voting process are: 1) the voters and 2) a trusted coordinator. The coordinator is in charge of setting up the system, deploying polls, and computing the tally of the votes. Through smart contracts and ZK-proofs, MACI ensures that everything is done in a fair manner. Although MACI can provide collusion resistance only if the coordinator is honest, a dishonest coordinator can neither censor nor tamper with its execution.
+
+Note that MACI presumes an identity system where each legitimate member
+controls a unique Ethereum private key.
+
+For information on MACI's latest features, please check out our [MACI v2.0.0 release post](/blog/2024-v2).
+
+## Background
+
+MACI was originally proposed by Vitalik Buterin in [this ethresear.ch
+post](https://ethresear.ch/t/minimal-anti-collusion-infrastructure/5413) and has been maintained and improved since thanks to support from the Ethereum Foundation. For a general overview, the history and the importance of MACI, see [Release Announcement: MACI 1.0](/blog/maci-1-0-release) by Wei Jie, one of the creators. He also created a helpful [overview of MACI video](https://www.youtube.com/watch?v=sKuNj_IQVYI). Kyle Charbonnet wrote a great [Technical Introduction to MACI 1.0](/blog/maci-1-0-technical-introduction) that provides a walkthrough on how MACI operates.
+
+## Credits
+
+MACI is a public good infrastructure that is supported by the [Ethereum Foundation](https://ethereum.foundation/) within [Privacy & Scaling Explorations (PSE)](https://pse.dev/). It's also continuously improved by our open source community! Many people have contributed to MACI, but below are some notable contributors.
+
+**[MACI v1.0](/blog/maci-1-0-release) was originally developed by:**
+
+- [Barry WhiteHat](https://github.com/barryWhiteHat)
+- [Cory Dickson](https://github.com/corydickson)
+- [Chih-Cheng Liang](https://twitter.com/ChihChengLiang)
+- [Han Jian](https://han0110.github.io/)
+- [Kendrick Tan](https://kndrck.co/)
+- [Kirill Goncharov](https://github.com/xuhcc)
+- [Kobi Gurkan](http://kobi.one/)
+- [Koh Wei Jie](https://kohweijie.com)
+- [Samuel Gosling](https://twitter.com/xGozzy)
+
+**[MACI v1.1.1](/blog/maci-v1-1-1-release) was primarily developed by:**
+
+- [ctrlc03](https://github.com/ctrlc03)
+- [chaosma](https://github.com/chaosma)
+- [baumstern](https://github.com/baumstern)
+- [daodesigner](https://github.com/daodesigner)
+- [0xjei](https://github.com/0xjei)
+
+**[MACI v1.2 till v3.0](/blog/2024-v2) was primarily developed by:**
+
+- [ctrlc03](https://github.com/ctrlc03)
+- [samajammin](https://github.com/samajammin)
+- [0xmad](https://github.com/0xmad)
+- [kittybest](https://github.com/kittybest)
+- [crisgarner](https://github.com/crisgarner)
+
+**Currently, MACI (v3.0 and beyond) is maintained and continuously improved by a core development team:**
+
+- [ctrlc03](https://github.com/ctrlc03)
+- [0xmad](https://github.com/0xmad)
+- [nicoserranop](https://github.com/NicoSerranoP)
+- [john](https://github.com/JohnGuilding)
+
+Our core team continues to work on improving the protocol and its documentation with help from our open source community.
+
+:::info
+If you are using one of the previous versions of MACI, see the [MACI v2.0](/docs/v2.x/introduction) documentation.
+:::

package/versioned_docs/version-v3.x/processes/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Processes",
+  "position": 11
+}