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

package/versioned_docs/version-v3.x/security/trusted-setup.md

@@ -0,0 +1,172 @@
+---
+title: MACI Trusted Setup
+description: Introduction to the MACI multi-party trusted setup
+sidebar_label: Trusted Setup
+sidebar_position: 2
+---
+
+# Trusted setup
+
+MACI currently uses Groth16 zk-SNARKs written in `circom`. Teams who wish to
+build on MACI may choose to perform a multi-party trusted setup. This allows
+observers to have a higher degree of confidence that the coordinator cannot
+generate fake proofs. Some teams, however, may forgo the trusted setup.
+
+There are two possible reasons for doing so: if a team does not intend
+to manage a large amount of value, and if their users accept that the risk of
+coordinator misbehaviour is insufficient to justify doing the work of a
+trusted setup. After all, MACI's security model presumes a trusted coordinator.
+
+The [PSE team](https://pse.dev/) is making available a trusted set of zKeys for MACI's circuits,
+which are available and accessible on
+[p0tion's website](https://ceremony.pse.dev/).
+For more info on trusted setup ceremonies please refer to p0tion's [docs](https://p0tion.super.site/).
+
+## Maci v3.0 Trusted Setup Ceremony
+
+:::danger
+Maci v3.0 Trusted Setup Ceremony has not started yet. Thus for production use cases, please use [MACI v2.0](https://github.com/privacy-scaling-explorations/maci/releases/tag/v2.5.0).
+:::
+
+## Maci v2.0 Trusted Setup Ceremony (most recent)
+
+:::info
+Maci v2.0 Trusted Setup Ceremony is now completed and the circuits can be used in production.
+:::
+
+For this release, we plan to run two ceremonies, one with smaller size circuits (more accessible to contributors) due to smaller batch sizes for proving on chain, and one with larger circuits and large batch sizes for proving. Smaller size artifacts can be used for smaller rounds or for operators that want to run everything on a local computer vs using a beefy server. On the other hand, we plan to use the artifacts with larger batch sizes for large rounds and solely on a server.
+
+### Small Batch Size Ceremony
+
+:::info
+To download the artifacts, please run the following command from within MACI monorepo's root directory:
+
+```bash
+pnpm download-zkeys:ceremony
+```
+
+:::
+
+Here are the **maximum** values supported by these artifacts:
+
+**_ProcessMessages_**
+
+- users: $2^14 = 16384$
+- votes: $5^9 = 1953125$
+- batch size for proving: $5^2 = 25$
+- vote options: $5^3 = 125$
+
+**_TallyVotes_**
+
+- users (ballots): $2^14 = 16384$
+- batch size for proving: $2^5 = 32$
+- vote options: $5^3 = 125$
+
+### Large Batch Size Ceremony
+
+:::info
+Please note that this ceremony has not started yet. We will inform when it will start and when the artifacts are available for use.
+:::
+
+Here are the **maximum** values supported by these artifacts:
+
+**_ProcessMessages_**
+
+- users: $2^14 = 16384$
+- votes: $5^9 = 1953125$
+- batch size for proving: $5^3 = 125$
+- vote options: $5^3 = 125$
+
+**_TallyVotes_**
+
+- users (ballots): $2^14 = 16384$
+- batch size for proving: $2^7 = 128$
+- vote options: $5^3 = 125$
+
+## Maci v1.2 Trusted Setup Ceremony
+
+:::danger
+Please be advised that you will not be able to use these artifacts with MACI v2.
+:::
+
+:::info
+MACI v1.2 artifacts are stored on [Amazon S3](https://maci-develop-fra.s3.eu-central-1.amazonaws.com/v1.2.0/maci_artifacts_6-9-2-3_prod.tar.gz). Please either download directly, or checkout any of the maci v1.2 tags to access the artifacts using the following commands:
+
+```bash
+git checkout v1.2.5
+download:ceremony-zkeys
+```
+
+:::
+
+Here are the **maximum** values supported by these artifacts:
+
+**_ProcessMessages_**
+
+- users: $5^6 = 15625$
+- votes: $5^9 = 1953125$
+- batch size for proving: $5^2 = 25$
+- vote options: $5^3 = 125$
+
+**_TallyVotes_**
+
+- users (ballots): $5^6 = 15625$
+- batch size for proving: $5^2 = 25$
+- vote options: $5^3 = 125$
+
+For your convenience, here is a list of the artifacts that can be used in production:
+
+| Artifact                               | Description                                                                                              | Parameters | Link                                                                                                                                                                                                                                            |
+| -------------------------------------- | -------------------------------------------------------------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| processMessages zKey                   | The production-ready zKey for the processMessages circuit.                                               | 6-9-2-3    | [processMessages_6-9-2-3_final.zkey](https://maci-v1-2-0-trusted-setup-ceremony-pse-p0tion-production.s3.eu-central-1.amazonaws.com/circuits/maci-processmessages_6-9-2-3/contributions/maci-processmessages_6-9-2-3_final.zkey)                |
+| processMessagesNonQv zKey              | The production-ready zKey for the processMessagesNonQv circuit.                                          | 6-9-2-3    | [processMessagesNonQv_6-9-2-3_final.zkey](https://maci-v1-2-0-trusted-setup-ceremony-pse-p0tion-production.s3.eu-central-1.amazonaws.com/circuits/maci-processmessagesnonqv_6-9-2-3/contributions/maci-processmessagesnonqv_6-9-2-3_final.zkey) |
+| tallyVotes zKey                        | The production-ready zKey for the tallyVotes circuit.                                                    | 6-2-3      | [tallyVotes_6-2-3_final.zkey](https://maci-v1-trusted-setup-ceremony-pse-p0tion-production.s3.eu-central-1.amazonaws.com/circuits/tallyvotes_6-2-3/contributions/tallyvotes_6-2-3_final.zkey)                                                   |
+| tallyVotesNonQv zKey                   | The production-ready zKey for the tallyVotesNonQv circuit.                                               | 6-2-3      | [tallyVotesNonQv_6-2-3_final.zkey](https://maci-v1-2-0-trusted-setup-ceremony-pse-p0tion-production.s3.eu-central-1.amazonaws.com/circuits/maci-tallyvotesnonqv_6-2-3/contributions/maci-tallyvotesnonqv_6-2-3_final.zkey)                      |
+| processMessages r1cs                   | The Rank-1 Constraint System file that was used to generate the zKey                                     | 6-9-2-3    | [MACI-ProcessMessages_6-9-2-3.r1cs ](https://maci-v1-2-0-trusted-setup-ceremony-pse-p0tion-production.s3.eu-central-1.amazonaws.com/circuits/maci-processmessages_6-9-2-3/MACI-ProcessMessages_6-9-2-3.r1cs)                                    |
+| processMessagesNonQv r1cs              | The Rank-1 Constraint System file that was used to generate the zKey                                     | 6-9-2-3    | [MACI-ProcessMessagesNonQv_6-9-2-3.r1cs](https://maci-v1-2-0-trusted-setup-ceremony-pse-p0tion-production.s3.eu-central-1.amazonaws.com/circuits/maci-processmessagesnonqv_6-9-2-3/MACI-ProcessMessagesNonQv_6-9-2-3.r1cs)                      |
+| tallyVotes r1cs                        | The Rank-1 Constraint System file that was used to generate the zKey                                     | 6-2-3      | [tallyvotes_6-2-3.r1cs](https://maci-v1-trusted-setup-ceremony-pse-p0tion-production.s3.eu-central-1.amazonaws.com/circuits/tallyvotes_6-2-3/tallyvotes_6-2-3.r1cs)                                                                             |
+| tallyVotesNonQv r1cs                   | The Rank-1 Constraint System file that was used to generate the zKey                                     | 6-2-3      | [tallyvotesnonqv_6-2-3.r1cs](https://maci-v1-2-0-trusted-setup-ceremony-pse-p0tion-production.s3.eu-central-1.amazonaws.com/circuits/maci-tallyvotesnonqv_6-2-3/MACI-TallyVotesNonQv_6-2-3.r1cs)                                                |
+| processMessages wasm                   | The WASM file that can be used to generate proofs                                                        | 6-9-2-3    | [MACI-ProcessMessages_6-9-2-3.wasm](https://maci-v1-2-0-trusted-setup-ceremony-pse-p0tion-production.s3.eu-central-1.amazonaws.com/circuits/maci-processmessages_6-9-2-3/MACI-ProcessMessages_6-9-2-3.wasm)                                     |
+| processMessagesNonQv wasm              | The WASM file that can be used to generate proofs                                                        | 6-9-2-3    | [MACI-ProcessMessagesNonQv_6-9-2-3.wasm](https://maci-v1-2-0-trusted-setup-ceremony-pse-p0tion-production.s3.eu-central-1.amazonaws.com/circuits/maci-processmessagesnonqv_6-9-2-3/MACI-ProcessMessagesNonQv_6-9-2-3.wasm)                      |
+| tallyVotes wasm                        | The WASM file that can be used to generate proofs                                                        | 6-2-3      | [tallyvotes_6-2-3.wasm](https://maci-v1-trusted-setup-ceremony-pse-p0tion-production.s3.eu-central-1.amazonaws.com/circuits/tallyvotes_6-2-3/tallyvotes_6-2-3.wasm)                                                                             |
+| tallyVotesNonQv wasm                   | The WASM file that can be used to generate proofs                                                        | 6-2-3      | [tallyvotesnonqv_6-2-3.wasm](https://maci-v1-2-0-trusted-setup-ceremony-pse-p0tion-production.s3.eu-central-1.amazonaws.com/circuits/maci-tallyvotesnonqv_6-2-3/MACI-TallyVotesNonQv_6-2-3.wasm)                                                |
+| processMessages vKey                   | The verification key that can be used to verify the processMessages circuit's proofs                     | 6-9-2-3    | [maci-processmessages_6-9-2-3_vkey.json](https://maci-v1-2-0-trusted-setup-ceremony-pse-p0tion-production.s3.eu-central-1.amazonaws.com/circuits/maci-processmessages_6-9-2-3/maci-processmessages_6-9-2-3_vkey.json)                           |
+| processMessagesNonQv vKey              | The verification key that can be used to verify the processMessagesNonQv circuit's proofs                | 6-9-2-3    | [maci-processmessagesnonqv_6-9-2-3_vkey.json](https://maci-v1-2-0-trusted-setup-ceremony-pse-p0tion-production.s3.eu-central-1.amazonaws.com/circuits/maci-processmessagesnonqv_6-9-2-3/maci-processmessagesnonqv_6-9-2-3_vkey.json)            |
+| tallyVotes vKey                        | The verification key that can be used to verify the tallyVotes circuit's proofs                          | 6-2-3      | [tallyvotes_6-2-3_vkey.json](https://maci-v1-trusted-setup-ceremony-pse-p0tion-production.s3.eu-central-1.amazonaws.com/circuits/tallyvotes_6-2-3/tallyvotes_6-2-3_vkey.json)                                                                   |
+| tallyVotesNonQv vKey                   | The verification key that can be used to verify the tallyVotesNonQv circuit's proofs                     | 6-2-3      | [tallyvotesnonqv_6-2-3_vkey.json](https://maci-v1-2-0-trusted-setup-ceremony-pse-p0tion-production.s3.eu-central-1.amazonaws.com/circuits/maci-tallyvotesnonqv_6-2-3/maci-tallyvotesnonqv_6-2-3_vkey.json)                                      |
+| processMessages Solidity verifier      | The Solidity smart contract which can be used to verify the processMessages circuit proofs on-chain      | 6-9-2-3    | [maci-processmessages_6-9-2-3_verifier.sol](https://maci-v1-2-0-trusted-setup-ceremony-pse-p0tion-production.s3.eu-central-1.amazonaws.com/circuits/maci-processmessages_6-9-2-3/maci-processmessages_6-9-2-3_verifier.sol)                     |
+| processMessagesNonQv Solidity verifier | The Solidity smart contract which can be used to verify the processMessagesNonQv circuit proofs on-chain | 6-9-2-3    | [maci-processmessagesnonqv_6-9-2-3_verifier.sol](https://maci-v1-2-0-trusted-setup-ceremony-pse-p0tion-production.s3.eu-central-1.amazonaws.com/circuits/maci-processmessagesnonqv_6-9-2-3/maci-processmessagesnonqv_6-9-2-3_verifier.sol)      |
+| tallyVotes Solidity verifier           | The Solidity smart contract which can be used to verify the tallyVotes circuit proofs on-chain           | 6-2-3      | [tallyvotes_6-2-3_verifier.sol](https://maci-v1-trusted-setup-ceremony-pse-p0tion-production.s3.eu-central-1.amazonaws.com/circuits/tallyvotes_6-2-3/tallyvotes_6-2-3_verifier.sol)                                                             |
+| tallyVotesNonQv Solidity verifier      | The Solidity smart contract which can be used to verify the tallyVotesNonQv circuit proofs on-chain      | 6-2-3      | [tallyvotesnonqv_6-2-3_verifier.sol](https://maci-v1-2-0-trusted-setup-ceremony-pse-p0tion-production.s3.eu-central-1.amazonaws.com/circuits/maci-tallyvotesnonqv_6-2-3/maci-tallyvotesnonqv_6-2-3_verifier.sol)                                |
+
+## Maci v1.1 Trusted Setup Ceremony
+
+Here are the **maximum** values supported by these artifacts:
+
+**_ProcessMessages_**
+
+- users: $5^6 = 15625$
+- votes: $5^8 = 390625$
+- messages per batch: $5^2 = 25$
+- vote options: $5^3 = 125$
+
+**_TallyVotes_**
+
+- users (ballots): $5^6 = 15625$
+- batch size: $5^2 = 25$
+- vote options: $5^3 = 125$
+
+For your convenience, here is a list of the artifacts that can be used in production:
+
+| Artifact                          | Description                                                                                         | Parameters | Link                                                                                                                                                                                                               |
+| --------------------------------- | --------------------------------------------------------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| processMessages zKey              | The production-ready zKey for the processMessages circuit.                                          | 6-8-2-3    | [processmessages_6-8-2-3_final.zkey](https://maci-v1-trusted-setup-ceremony-pse-p0tion-production.s3.eu-central-1.amazonaws.com/circuits/processmessages_6-8-2-3/contributions/processmessages_6-8-2-3_final.zkey) |
+| tallyVotes zKey                   | The production-ready zKey for the tallyVotes circuit.                                               | 6-2-3      | [tallyvotes_6-2-3_final.zkey](https://maci-v1-trusted-setup-ceremony-pse-p0tion-production.s3.eu-central-1.amazonaws.com/circuits/tallyvotes_6-2-3/contributions/tallyvotes_6-2-3_final.zkey)                      |
+| processMessages r1cs              | The Rank-1 Constraint System file that was used to generate the zKey                                | 6-8-2-3    | [processmessages_6-8-2-3.r1cs](https://maci-v1-trusted-setup-ceremony-pse-p0tion-production.s3.eu-central-1.amazonaws.com/circuits/processmessages_6-8-2-3/processmessages_6-8-2-3.r1cs)                           |
+| tallyVotes r1cs                   | The Rank-1 Constraint System file that was used to generate the zKey                                | 6-2-3      | [tallyvotes_6-2-3.r1cs](https://maci-v1-trusted-setup-ceremony-pse-p0tion-production.s3.eu-central-1.amazonaws.com/circuits/tallyvotes_6-2-3/tallyvotes_6-2-3.r1cs)                                                |
+| processMessage wasm               | The WASM file that can be used to generate proofs                                                   | 6-8-2-3    | [processmessages_6-8-2-3.wasm](https://maci-v1-trusted-setup-ceremony-pse-p0tion-production.s3.eu-central-1.amazonaws.com/circuits/processmessages_6-8-2-3/processmessages_6-8-2-3.wasm)                           |
+| tallyVotes wasm                   | The WASM file that can be used to generate proofs                                                   | 6-2-3      | [tallyvotes_6-2-3.wasm](https://maci-v1-trusted-setup-ceremony-pse-p0tion-production.s3.eu-central-1.amazonaws.com/circuits/tallyvotes_6-2-3/tallyvotes_6-2-3.wasm)                                                |
+| processMessages vKey              | The verification key that can be used to verify the processMessages circuit's proofs                | 6-8-2-3    | [processmessages_6-8-2-3_vkey.json](https://maci-v1-trusted-setup-ceremony-pse-p0tion-production.s3.eu-central-1.amazonaws.com/circuits/processmessages_6-8-2-3/processmessages_6-8-2-3_vkey.json)                 |
+| tallyVotes vKey                   | The verification key that can be used to verify the tallyVotes circuit's proofs                     | 6-2-3      | [tallyvotes_6-2-3_vkey.json](https://maci-v1-trusted-setup-ceremony-pse-p0tion-production.s3.eu-central-1.amazonaws.com/circuits/tallyvotes_6-2-3/tallyvotes_6-2-3_vkey.json)                                      |
+| processMessages Solidity verifier | The Solidity smart contract which can be used to verify the processMessages circuit proofs on-chain | 6-8-2-3    | [processmessages_6-8-2-3_verifier.sol](https://maci-v1-trusted-setup-ceremony-pse-p0tion-production.s3.eu-central-1.amazonaws.com/circuits/processmessages_6-8-2-3/processmessages_6-8-2-3_verifier.sol)           |
+| tallyVotes Solidity verifier      | The Solidity smart contract which can be used to verify the tallyVotes circuit proofs on-chain      | 6-2-3      | [tallyvotes_6-2-3_verifier.sol](https://maci-v1-trusted-setup-ceremony-pse-p0tion-production.s3.eu-central-1.amazonaws.com/circuits/tallyvotes_6-2-3/tallyvotes_6-2-3_verifier.sol)                                |

package/versioned_docs/version-v3.x/supported-networks/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Supported Networks",
+  "position": 6
+}

package/versioned_docs/version-v3.x/supported-networks/deployed-contracts.md

@@ -0,0 +1,112 @@
+---
+title: Deployed MACI Smart Contracts
+description: Deployed MACI Smart Contracts
+sidebar_label: Deployed MACI Smart Contracts
+sidebar_position: 2
+---
+
+There are a number of MACI's smart contracts which can be re-used by different deployments. These are the following:
+
+- [VkRegistry](https://github.com/privacy-scaling-explorations/maci/blob/dev/contracts/contracts/VkRegistry.sol)
+- [PoseidonHashers](https://github.com/privacy-scaling-explorations/maci/blob/dev/contracts/contracts/crypto/Hasher.sol)
+- [PollFactory](https://github.com/privacy-scaling-explorations/maci/blob/dev/contracts/contracts/PollFactory.sol)
+- [MessageProcessorFactory](https://github.com/privacy-scaling-explorations/maci/blob/dev/contracts/contracts/MessageProcessorFactory.sol)
+- [TallyFactory](https://github.com/privacy-scaling-explorations/maci/blob/dev/contracts/contracts/TallyFactory.sol)
+- [Verifier](https://github.com/privacy-scaling-explorations/maci/blob/dev/contracts/contracts/crypto/Verifier.sol)
+- [FreeForAllPolicy](https://github.com/privacy-scaling-explorations/excubiae/tree/main/packages/contracts/contracts/extensions/freeForAll)
+- [ConstantInitialVoiceCreditProxy](https://github.com/privacy-scaling-explorations/maci/blob/dev/contracts/contracts/initialVoiceCreditProxy/ConstantInitialVoiceCreditProxy.sol) - if you are happy to work with a fixed amount of credits
+
+VkRegistries can be re-used by different protocols to share the same set of verifying keys. Please be advised that you should be verifying that those verifying keys are the ones that have undergone a trusted setup ceremony.
+
+In order to verify you will need the following:
+
+- configure the cli (`cd cli && cp .env.example .env` and set the correct env vars)
+- download the keys (`pnpm download-zkeys:ceremony` from the monorepo root)
+- run checkVerifyingKeys with the cli (see below)
+
+```bash
+cd cli && node build/ts/index.js checkVerifyingKeys -q false -vk 0x74569d524a193daC0D3Df17B9E207C916174745b -s 6 -i 2 -m 9 -v 3 -b 2 -p ./zkeys/ProcessMessages_6-9-2-3/processMessages_6-9-2-3.zkey -t ./zkeys/TallyVotes_6-2-3/tallyVotes_6-2-3.zkey
+```
+
+:::info
+You should change the -vk parameter to the VkRegistry address for the chain you are deploying to. Also you might need to modify the parameters based on the circuit configuration. Please refer to the [circuits page](/docs/technical-references/zk-snark-circuits/setup) for more information. Also you can add `-uq false` if you want to check non quadratic voting keys.
+:::
+
+## Contract Addresses
+
+### Arbitrum Sepolia
+
+| Contract                                     | Address                                                                                                                      |
+| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| ConstantInitialVoiceCreditProxy (99 Credits) | [0x41a29A58A63A998c9Edde6883Bcec2d89835a8e9](https://sepolia.arbiscan.io/address/0x41a29A58A63A998c9Edde6883Bcec2d89835a8e9) |
+| Verifier                                     | [0xB400794f463d90ce5f462A43d8E6f9155656d02d](https://sepolia.arbiscan.io/address/0xB400794f463d90ce5f462A43d8E6f9155656d02d) |
+| PoseidonT3                                   | [0xa0e0aC07c211D329ebA2D6ec552F4dC1B230A89A](https://sepolia.arbiscan.io/address/0xa0e0aC07c211D329ebA2D6ec552F4dC1B230A89A) |
+| PoseidonT4                                   | [0x4f02c99df5731C8C69f6baa62Aa4C9f99C529CE2](https://sepolia.arbiscan.io/address/0x0CC8B7Aed7d79a8B948636242706265548D0B10a) |
+| PoseidonT5                                   | [0xB8Bc2c7cF71441fF7E6F111D3457e3d61c564968](https://sepolia.arbiscan.io/address/0xB8Bc2c7cF71441fF7E6F111D3457e3d61c564968) |
+| PoseidonT6                                   | [0x37282fEde56aa1d7266Ecb12DC3b342D12044e2E](https://sepolia.arbiscan.io/address/0x37282fEde56aa1d7266Ecb12DC3b342D12044e2E) |
+
+### Arbitrum Mainnet
+
+| Contract                                      | Address                                                                                                              |
+| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| ConstantInitialVoiceCreditProxy (200 Credits) | [0x16FC13edD59D4b9F788Fb11A70eA022E1Bb1B856](https://arbiscan.io/address/0x16FC13edD59D4b9F788Fb11A70eA022E1Bb1B856) |
+| Verifier                                      | [0x2427Ab201488Ac81Bec421F179B1Be23c55ebC27](https://arbiscan.io/address/0x2427Ab201488Ac81Bec421F179B1Be23c55ebC27) |
+| PoseidonT3                                    | [0x2F1398ab5E322d357dF8CdD2e7ba73122c5FDDA4](https://arbiscan.io/address/0x2F1398ab5E322d357dF8CdD2e7ba73122c5FDDA4) |
+| PoseidonT4                                    | [0x8778dA47eF619f56341fE95514e95fa0FF3B77C6](https://arbiscan.io/address/0x8778dA47eF619f56341fE95514e95fa0FF3B77C6) |
+| PoseidonT5                                    | [0x43B519FF023757508311518AC41B5fA1CfD57181](https://arbiscan.io/address/0x43B519FF023757508311518AC41B5fA1CfD57181) |
+| PoseidonT6                                    | [0xb123798B1b21082100D289BeA24bFF0F8dfcbEe1](https://arbiscan.io/address/0xb123798B1b21082100D289BeA24bFF0F8dfcbEe1) |
+
+### Optimism
+
+| Contract                                      | Address                                                                                                                          |
+| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| ConstantInitialVoiceCreditProxy (200 Credits) | [0x83dD551541C580e338206f1f677835D427C92dE2](https://optimistic.etherscan.io/address/0x83dD551541C580e338206f1f677835D427C92dE2) |
+| Verifier                                      | [0x88C2c6A7535463962A34757FE63cc4F296381aba](https://optimistic.etherscan.io/address/0x88C2c6A7535463962A34757FE63cc4F296381aba) |
+| PoseidonT3                                    | [0xF8E637e5c9EC3A8d8fa8843A6dF833348E1F1E66](https://optimistic.etherscan.io/address/0xF8E637e5c9EC3A8d8fa8843A6dF833348E1F1E66) |
+| PoseidonT4                                    | [0x0a0D66baFDa8c8838281084d9C3d68Dd9a6Fc274](https://optimistic.etherscan.io/address/0x0a0D66baFDa8c8838281084d9C3d68Dd9a6Fc274) |
+| PoseidonT5                                    | [0xD2F6c828606Ad8e985008Cd825012f269B50CD58](https://optimistic.etherscan.io/address/0xD2F6c828606Ad8e985008Cd825012f269B50CD58) |
+| PoseidonT6                                    | [0x982530673Ce9e5Efa02438c694d48327Aa4fB592](https://optimistic.etherscan.io/address/0x982530673Ce9e5Efa02438c694d48327Aa4fB592) |
+
+### Optimism Sepolia
+
+| Contract                                     | Address                                                                                                                                |
+| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| ConstantInitialVoiceCreditProxy (99 Credits) | [0x4473aC3e68ad78D67757336ABaAa2Dced08cfcdF](https://sepolia-optimism.etherscan.io/address/0x4473aC3e68ad78D67757336ABaAa2Dced08cfcdF) |
+| Verifier                                     | [0xB1abb44291ff487f96636758b07Ccd9881f64c9A](https://sepolia-optimism.etherscan.io/address/0xB1abb44291ff487f96636758b07Ccd9881f64c9A) |
+| PoseidonT3                                   | [0x07490eba00dc4ACA6721D052Fa4C5002Aa077233](https://sepolia-optimism.etherscan.io/address/0x07490eba00dc4ACA6721D052Fa4C5002Aa077233) |
+| PoseidonT4                                   | [0xbb0e724CE02e5E7eDd31e632dc6e59F229a1126d](https://sepolia-optimism.etherscan.io/address/0xbb0e724CE02e5E7eDd31e632dc6e59F229a1126d) |
+| PoseidonT5                                   | [0xE0398F7DFAC494c530F6404AfEaC8669ABeD2679](https://sepolia-optimism.etherscan.io/address/0xE0398F7DFAC494c530F6404AfEaC8669ABeD2679) |
+| PoseidonT6                                   | [0xfD77833F10a29c76A6a0ede235Eb651D744d0E2F](https://sepolia-optimism.etherscan.io/address/0xfD77833F10a29c76A6a0ede235Eb651D744d0E2F) |
+
+### Scroll Sepolia
+
+| Contract                                     | Address                                                                                                                         |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| ConstantInitialVoiceCreditProxy (99 Credits) | [0xB486cce9B4507A67Db147B0802D5673774C8D278](https://sepolia.scrollscan.com/address/0xB486cce9B4507A67Db147B0802D5673774C8D278) |
+| Verifier                                     | [0xD5C41106db85EDd0298279AcFCE5A722060cc5f9](https://sepolia.scrollscan.com/address/0xD5C41106db85EDd0298279AcFCE5A722060cc5f9) |
+| PoseidonT3                                   | [0x88C2c6A7535463962A34757FE63cc4F296381aba](https://sepolia.scrollscan.com/address/0x88C2c6A7535463962A34757FE63cc4F296381aba) |
+| PoseidonT4                                   | [0x0a0D66baFDa8c8838281084d9C3d68Dd9a6Fc274](https://sepolia.scrollscan.com/address/0x0a0D66baFDa8c8838281084d9C3d68Dd9a6Fc274) |
+| PoseidonT5                                   | [0xE0398F7DFAC494c530F6404AfEaC8669ABeD2679](https://sepolia.scrollscan.com/address/0xE0398F7DFAC494c530F6404AfEaC8669ABeD2679) |
+| PoseidonT6                                   | [0xD2F6c828606Ad8e985008Cd825012f269B50CD58](https://sepolia.scrollscan.com/address/0xD2F6c828606Ad8e985008Cd825012f269B50CD58) |
+
+### Base
+
+| Contract                                      | Address                                                                                                               |
+| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| ConstantInitialVoiceCreditProxy (200 Credits) | [0x16FC13edD59D4b9F788Fb11A70eA022E1Bb1B856](https://basescan.org/address/0x16FC13edD59D4b9F788Fb11A70eA022E1Bb1B856) |
+| Verifier                                      | [0x2427Ab201488Ac81Bec421F179B1Be23c55ebC27](https://basescan.org/address/0x2427Ab201488Ac81Bec421F179B1Be23c55ebC27) |
+| PoseidonT3                                    | [0x2F1398ab5E322d357dF8CdD2e7ba73122c5FDDA4](https://basescan.org/address/0x2F1398ab5E322d357dF8CdD2e7ba73122c5FDDA4) |
+| PoseidonT4                                    | [0x8778dA47eF619f56341fE95514e95fa0FF3B77C6](https://basescan.org/address/0x8778dA47eF619f56341fE95514e95fa0FF3B77C6) |
+| PoseidonT5                                    | [0xB8Bc2c7cF71441fF7E6F111D3457e3d61c564968](https://basescan.org/address/0xB8Bc2c7cF71441fF7E6F111D3457e3d61c564968) |
+| PoseidonT6                                    | [0x37282fEde56aa1d7266Ecb12DC3b342D12044e2E](https://basescan.org/address/0x37282fEde56aa1d7266Ecb12DC3b342D12044e2E) |
+
+### Base Sepolia
+
+| Contract                                     | Address                                                                                                                       |
+| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| ConstantInitialVoiceCreditProxy (99 Credits) | [0x16FC13edD59D4b9F788Fb11A70eA022E1Bb1B856](https://sepolia.basescan.org/address/0x16FC13edD59D4b9F788Fb11A70eA022E1Bb1B856) |
+| Verifier                                     | [0x2427Ab201488Ac81Bec421F179B1Be23c55ebC27](https://sepolia.basescan.org/address/0x2427Ab201488Ac81Bec421F179B1Be23c55ebC27) |
+| PoseidonT3                                   | [0x2F1398ab5E322d357dF8CdD2e7ba73122c5FDDA4](https://sepolia.basescan.org/address/0x2F1398ab5E322d357dF8CdD2e7ba73122c5FDDA4) |
+| PoseidonT4                                   | [0x8778dA47eF619f56341fE95514e95fa0FF3B77C6](https://sepolia.basescan.org/address/0x8778dA47eF619f56341fE95514e95fa0FF3B77C6) |
+| PoseidonT5                                   | [0xB8Bc2c7cF71441fF7E6F111D3457e3d61c564968](https://sepolia.basescan.org/address/0xB8Bc2c7cF71441fF7E6F111D3457e3d61c564968) |
+| PoseidonT6                                   | [0x37282fEde56aa1d7266Ecb12DC3b342D12044e2E](https://sepolia.basescan.org/address/0x37282fEde56aa1d7266Ecb12DC3b342D12044e2E) |

package/versioned_docs/version-v3.x/supported-networks/supported-networks.md

@@ -0,0 +1,53 @@
+---
+title: Supported Networks
+description: Supported Networks
+sidebar_label: Supported Networks
+sidebar_position: 1
+---
+
+:::info
+
+Testing was done using MACI v2, we expect similar results with v3.
+
+:::
+
+MACI has been tested on the following EVM networks:
+
+- Optimism
+- Optimism Sepolia
+- Arbitrum
+- Arbitrum Sepolia
+- Base
+- Base Sepolia
+- Gnosis
+- Gnosis Chiado
+- Polygon
+- Polygon Amoy
+
+We recommend using either Optimism, Arbitrum or Base. Please open an issue/PR if you intend to use other EVM networks and would like to contribute to this record of deployed and verified contracts as well as benchmarks, that would be greatly appreciated.
+
+## Limitations
+
+For better UX, MACI clients should be sending votes (messages) in batches. Depending on the number of vote options available, larger batch might be sent. Below you can find the largest batch you can send for each network and how much gas it consumes:
+
+| Network          | Max Batch Size | Gas used | Price (based on Ether price at the time ~$2595) |
+| ---------------- | -------------- | -------- | ----------------------------------------------- |
+| Optimism         | 89             | 28167603 | 0.000036061732019822 ETH ($0.09)                |
+| Optimism Sepolia | 89             | 28163331 | 0.005651520470449442 ETH ($10.46)               |
+| Arbitrum         | 98             | 31017545 | 0.00031017545 ETH ($0.80)                       |
+| Arbitrum Sepolia | 98             | 31115404 | 0.0031115404 ETH ($8.06)                        |
+| Base             | 89             | 28165467 | 0.000591851649982612 ETH ($1.54)                |
+| Base Sepolia     | 89             | 28190232 | 0.002072926785842714 ETH ($5.18)                |
+| Gnosis           | 50             | 15921153 | 0.0000124615 ETH ($0.03)                        |
+| Gnosis Chiado    | 50             | 15921753 | 0.0000188313 ETH ($0.05)                        |
+| Polygon          | 85             | 26915773 | 0.0002193417259598 ETH ($0.54)                  |
+| Polygon Amoy     | 89             | 28192368 | 0.00017069180975304 ETH ($0.43)                 |
+
+## Test yourself
+
+To test MACI on a network, whether it's one of the ones listed above, or a new one, you can use the `benchmark` hardhat task:
+
+1. Ensure you have copied `.env.example` to `.env` and set the correct values for the network you want to test on.
+2. Configure your `deploy-config.json` - ensure `messageTreeDepth` is set to at least 3 (supporting 5 \*\* 3 votes)
+3. Ensure you have copied the `default-deployed-contracts.json` to `deployed-contracts.json` to avoid deploying unnecessary contracts again.
+4. Run the `benchmark` task: `pnpm benchmark:$NETWORK`

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

@@ -0,0 +1,4 @@
+{
+  "label": "Technical References",
+  "position": 5
+}

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

@@ -0,0 +1,160 @@
+---
+title: MACI Smart Contract
+description: MACI main smart contract
+sidebar_label: MACI
+sidebar_position: 1
+---
+
+:::info
+Code location: [MACI.sol](https://github.com/privacy-scaling-explorations/maci/blob/dev/contracts/contracts/MACI.sol)
+:::
+
+`MACI.sol` is the core contract of the project, as it provides the base layer for user signups and Polls to be created.
+
+The constructor shown below accepts several arguments:
+
+- `PollFactory` address
+- `MessageProcessorFactory` address
+- `TallyFactory` address
+- `IBasePolicy` address
+- `InitialVoiceCreditProxy` address
+- The depth of the state tree
+
+```solidity
+constructor(
+  IPollFactory _pollFactory,
+  IMessageProcessorFactory _messageProcessorFactory,
+  ITallyFactory _tallyFactory,
+  IBasePolicy _signUpPolicy,
+  uint8 _stateTreeDepth,
+  uint256[5] memory _emptyBallotRoots
+) payable {
+  // initialize and insert the blank leaf
+  InternalLeanIMT._insert(leanIMTData, PAD_KEY_HASH);
+  stateRootsOnSignUp.push(PAD_KEY_HASH);
+
+  pollFactory = _pollFactory;
+  messageProcessorFactory = _messageProcessorFactory;
+  tallyFactory = _tallyFactory;
+  signUpPolicy = _signUpPolicy;
+  stateTreeDepth = _stateTreeDepth;
+  maxSignups = uint256(STATE_TREE_ARITY) ** uint256(_stateTreeDepth);
+  emptyBallotRoots = _emptyBallotRoots;
+
+  // Verify linked poseidon libraries
+  if (hash2([uint256(1), uint256(1)]) == 0) revert PoseidonHashLibrariesNotLinked();
+}
+```
+
+Upon deployment, the contract will initialize the state tree, and insert the blank leaf hash.
+
+After this, all of the parameters will be stored to state, and then the contract will perform a simple sanity check to ensure that the Poseidon hash libraries were linked successfully.
+
+## SignUp
+
+Next, we have the `signUp` function, which allows users to `signUp`, as long as they pass the conditions set in the `signUpPolicy` contract. This contract can use any mean necessary to gatekeep access to MACI's polls. For instance, only wallets with a specific ERC721 token can be allowed to sign up.
+
+This function does the following:
+
+- checks that the maximum number of signups has not been reached. Given a tree depth of 10, this will be $2 ** 10 - 1$.
+- checks that the provided public key is a valid baby-jubjub point
+- registers the user using the sign up policy contract. It is important that whichever policy is used, this reverts if a user tries to sign up twice or the conditions are not met (i.e returning false is not enough)
+- hashes the public key and inserts it into the state tree.
+
+```ts
+function signUp(PubKey memory _pubKey, bytes memory _signUpPolicyData) public virtual {
+  // ensure we do not have more signups than what the circuits support
+  if (leanIMTData.size >= maxSignups) revert TooManySignups();
+
+  // ensure that the public key is on the baby jubjub curve
+  if (!CurveBabyJubJub.isOnCurve(_pubKey.x, _pubKey.y)) {
+    revert InvalidPubKey();
+  }
+
+  // Register the user via the sign-up policy. This function should
+  // throw if the user has already registered or if ineligible to do so.
+  signUpPolicy.register(msg.sender, _signUpPolicyData);
+
+  // Hash the public key and insert it into the tree.
+  uint256 pubKeyHash = hashLeftRight(_pubKey.x, _pubKey.y);
+  uint256 stateRoot = InternalLeanIMT._insert(leanIMTData, pubKeyHash);
+
+  // Store the current state tree root in the array
+  stateRootsOnSignUp.push(stateRoot);
+
+  emit SignUp(leanIMTData.size - 1, block.timestamp, _pubKey.x, _pubKey.y);
+}
+```
+
+## DeployPoll
+
+Once everything has been setup, polls can be deployed using the `deployPoll` function. Polls can be deployed concurrently, as each deployment has its own separate set of contracts and state.
+
+```ts
+function deployPoll(DeployPollArgs calldata args) public virtual returns (PollContracts memory) {
+  // cache the poll to a local variable so we can increment it
+  uint256 pollId = nextPollId;
+
+  // Increment the poll ID for the next poll
+  // 2 ** 256 polls available
+  unchecked {
+    nextPollId++;
+  }
+
+  // check coordinator key is a valid point on the curve
+  if (!CurveBabyJubJub.isOnCurve(args.coordinatorPubKey.x, args.coordinatorPubKey.y)) {
+    revert InvalidPubKey();
+  }
+
+  ExtContracts memory extContracts = ExtContracts({
+    maci: IMACI(address(this)),
+    verifier: IVerifier(args.verifier),
+    vkRegistry: IVkRegistry(args.vkRegistry),
+    policy: IsignUpPolicy(args.policy),
+    initialVoiceCreditProxy: IInitialVoiceCreditProxy(args.initialVoiceCreditProxy)
+  });
+
+  IPollFactory.DeployPollArgs memory deployPollArgs = IPollFactory.DeployPollArgs({
+    startDate: args.startDate,
+    endDate: args.endDate,
+    treeDepths: args.treeDepths,
+    messageBatchSize: args.messageBatchSize,
+    coordinatorPubKey: args.coordinatorPubKey,
+    extContracts: extContracts,
+    emptyBallotRoot: emptyBallotRoots[args.treeDepths.voteOptionTreeDepth - 1],
+    pollId: pollId,
+    relayers: args.relayers,
+    voteOptions: args.voteOptions
+  });
+
+  address p = pollFactory.deploy(deployPollArgs);
+  address mp = messageProcessorFactory.deploy(args.verifier, args.vkRegistry, p, msg.sender, args.mode);
+  address tally = tallyFactory.deploy(args.verifier, args.vkRegistry, p, mp, msg.sender, args.mode);
+
+  // store the addresses in a struct so they can be returned
+  PollContracts memory pollAddr = PollContracts({ poll: p, messageProcessor: mp, tally: tally });
+
+  polls[pollId] = pollAddr;
+
+  emit DeployPoll(pollId, args.coordinatorPubKey.x, args.coordinatorPubKey.y, args.mode);
+
+  return pollAddr;
+}
+```
+
+Polls require the following information:
+
+- `duration`: the duration of the poll
+- `treeDepths`: the depth of the state tree, message tree, and vote option tree
+- `coordinatorPubKey`: the public key of the poll's coordinator
+- `verifier`: the address of the zk-SNARK verifier contract
+- `vkRegistry`: the address of the vk registry contract
+- `mode`: the mode of the poll, to set whether it supports quadratic voting or non quadratic voting
+- `signUpPolicy`: the address of the sign up policy contract
+- `initialVoiceCreditProxy`: the address of the initial voice credit proxy contract
+- `relayers`: the addresses of the relayers for the poll (if offchain voting is enabled)
+- `voteOptions`: the number of vote options for the poll
+
+:::info
+Please be advised that the number of signups in the MACI contract (number of leaves in the merkle tree holding MACI's state) considers the initial zero leaf as one signup. For this reason, when accounting for the real users signed up to MACI, you should subtract one from the value returned from the `numSignUps` function.
+:::

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

@@ -0,0 +1,13 @@
+---
+title: MessageProcessor Smart Contract
+description: MessageProcessor smart contract
+sidebar_label: MessageProcessor
+sidebar_position: 4
+---
+
+:::info
+Code location: [MessageProcessor.sol](https://github.com/privacy-scaling-explorations/maci/blob/dev/contracts/contracts/MessageProcessor.sol)
+:::
+
+This contract is used to prepare parameters for the zk-SNARK circuits as well as for verifying proofs. It should be deployed alongside a `Poll`.
+It will process messages in batches, and after all batches have been processed, the `sbCommitment` can then be used for the `Tally` contract verification steps.

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

@@ -0,0 +1,33 @@
+---
+title: Params Smart Contract
+description: Params smart contract
+sidebar_label: Params
+sidebar_position: 9
+---
+
+:::info
+Code location: [Params.sol](https://github.com/privacy-scaling-explorations/maci/blob/dev/contracts/contracts/utils/Params.sol)
+:::
+
+A contract holding three structs:
+
+```ts
+/// @notice A struct holding the depths of the merkle trees
+struct TreeDepths {
+  uint8 intStateTreeDepth;
+  uint8 voteOptionTreeDepth;
+}
+
+/// @notice A struct holding the external contracts
+/// that are to be passed to a Poll contract on
+/// deployment
+struct ExtContracts {
+  IMACI maci;
+  IVerifier verifier;
+  IVkRegistry vkRegistry;
+  IBasePolicy policy;
+  IInitialVoiceCreditProxy initialVoiceCreditProxy;
+}
+```
+
+Struct parameters are used to avoid stack too deep errors in the other contracts.

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

@@ -0,0 +1,39 @@
+---
+title: Policies Smart Contract
+description: Policies smart contract
+sidebar_label: Policies
+sidebar_position: 6
+---
+
+:::info
+Code location: [Policies](https://github.com/privacy-scaling-explorations/excubiae/tree/main/packages/contracts/contracts/extensions)
+:::
+
+MACI is composed of multiple smart contracts, which together with the zk-SNARK circuits, can be used to carry out on-chain voting. Start with an [overview of our smart contracts here](/docs/technical-references/smart-contracts/MACI).
+
+MACI uses a "policy" contract from Excubiae, which is used to configure and enforce the eligibility criteria of voters who can participate in MACI polls. In other words, it is a way to whitelist signups to the system. Operators of MACI can use the policy contract to configure signup eligibility and to protect against sybil attacks in their polls.
+
+The MACI repository comes with several out-of-the-box options:
+
+- `FreeForAllPolicy` - This allows anyone to signup on MACI.
+- `SignUpTokenPolicy` - This restricts signups only to holders of a specific ERC721 token.
+- `EASPolicy` - This restricts signups only to users who have received an attestation of a specific schema from a trusted attester.
+- `HatsPolicy` - This allows gatekeeping signups to only users who have a specific [Hat](https://www.hatsprotocol.xyz/).
+- `GitcoinPassportPolicy` - This allows gatekeeping signups to only users who have a specific [Gitcoin Passport](https://passport.gitcoin.co/) score.
+- `ZupassPolicy` - This allows gatekeeping signups only to users who have a valid [Zupass PCD ticket](https://github.com/proofcarryingdata/zupass).
+- `SemaphorePolicy` - This allows gatekeeping signups only to users who can prove they are part of a [Semaphore](https://semaphore.pse.dev/) group.
+
+You can find all of the latest policy contracts here:
+https://github.com/privacy-scaling-explorations/excubiae/tree/main/packages/contracts/contracts/extensions
+
+Developers are also welcome to implement a custom policy contract as long as it conforms to the `BasePolicy` - an abstract contract to inherit from with function signature:
+
+```ts
+abstract contract BasePolicy {
+    function enforce(address subject, bytes calldata evidence) external override onlyTarget {}
+}
+```
+
+Whenever a user signs up (via the `MACI.signUp` function), this triggers the MACI contract to call the `BasePolicy.enforce` function. Please note that this function should throw if the user is not eligible to sign up, rather than returning true or false.
+
+If you'd like to create a policy contract for your project, or if there's specific policy functionality you'd like to see MACI support, we'd be happy to help! Please [create a GitHub issue](https://github.com/privacy-scaling-explorations/maci/issues/new/choose).