@maci-protocol/website 0.0.0-ci.00107eb

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:
+
+- [VerifyingKeysRegistry](https://github.com/privacy-scaling-explorations/maci/blob/main/packages/contracts/contracts/VerifyingKeysRegistry.sol)
+- [PoseidonHashers](https://github.com/privacy-scaling-explorations/maci/blob/main/packages/contracts/contracts/crypto/Hasher.sol)
+- [PollFactory](https://github.com/privacy-scaling-explorations/maci/blob/main/packages/contracts/contracts/PollFactory.sol)
+- [MessageProcessorFactory](https://github.com/privacy-scaling-explorations/maci/blob/main/packages/contracts/contracts/MessageProcessorFactory.sol)
+- [TallyFactory](https://github.com/privacy-scaling-explorations/maci/blob/main/packages/contracts/contracts/TallyFactory.sol)
+- [Verifier](https://github.com/privacy-scaling-explorations/maci/blob/main/packages/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/main/packages/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/MessageProcessorQv_6-9-2-3/MessageProcessorQv_6-9-2-3.zkey -t ./zkeys/VoteTallyQv_6-2-3/tallyVotes_6-2-3.zkey
+```
+
+:::info
+You should change the -vk parameter to the VerifyingKeysRegistry 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,69 @@
+---
+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
+- Scroll
+- Scroll Sepolia
+- Linea
+- Linea Sepolia
+- Zksync Era
+- Zksync Sepolia
+- Polygon Zkevm
+- Polygon Cardona Zkevm
+
+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)                 |
+| Scroll           | 62             | 19447318 | 0.000233368 ETH ($0.61)                         |
+| Scroll Sepolia   | 62             | 19447318 | 0.000233368 ETH ($0.61)                         |
+| Linea            | 14             | 4438205  | 0.00005325846 ETH ($0.1382)                     |
+| Linea Sepolia    | 14             | 4438205  | 0.00005325846 ETH ($0.1382)                     |
+| Zksync Era       | 2              | 24000690 | 0.00028801 ETH ($0.75)                          |
+| Zksync Sepolia   | 2              | 24000690 | 0.00028801 ETH ($0.75)                          |
+| Polygon Zkevm    | 6              | 1917872  | 0.00006904 ETH ($0.18)                          |
+| Polygon Cardona  | 6              | 1917872  | 0.00006904 ETH ($0.18)                          |
+
+## 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/coordinator-service/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Coordinator Service",
+  "position": 1,
+  "link": {
+    "type": "generated-index",
+    "description": "The Coordinator Service is a backend service that aims to automate MACI-related operations, such as contracts deployment, proof generation and poll finalisation."
+  }
+}

package/versioned_docs/version-v3.x/technical-references/coordinator-service/index.md

@@ -0,0 +1,24 @@
+---
+title: Introduction
+description: The Coordinator Service is a service that allows to automate MACI coordinator tasks.
+sidebar_label: Introduction
+sidebar_position: 1
+---
+
+# Coordinator Service
+
+Welcome to the Coordinator Service technical reference. This guide describes how the Coordinator Service works, its workflow, and how to interact with it. For more technical code documentation regarding API endpoints and data transfer objects, please refer to the [API documentation](https://coordinator.maci.vote/api).
+
+## Responsibilities
+
+A MACI coordinator is responsible for running voting processes. In quadratic funding rounds or authority election rounds, the coordinator is the entity that defines who can vote, which projects or candidates are eligible for funding, and the duration of the voting round.
+
+First of all, the coordinator needs to deploy the MACI smart contracts with the desired configuration: gatekeeper policy, which defines who can sign up as a voter; the state Merkle tree depth which defines the maximum number of voters; and the voting mode which defines how votes will be counted (more info in [Poll types](https://maci.pse.dev/docs/core-concepts/poll-types#quadratic-voting)).
+
+After deploying the MACI contracts, the coordinator can deploy a poll (which represents a voting process). To deploy the poll, the coordinator needs to specify: the gatekeeper policy, which defines who can join the poll as a voter; the start and end dates of the poll; the number of options to vote for; the maximum number of votes per voter; and the voting mode.
+
+The coordinator will then wait until the poll ends, after which they will need to finalize the poll. This involves processing all published messages, extracting the votes, tallying them, and submitting the results on-chain.
+
+## Conclusion
+
+In the following documents, we will go through the details of setting up the Coordinator Service and how to interact with it to perform the tasks described above.

package/versioned_docs/version-v3.x/technical-references/coordinator-service/installation.md

@@ -0,0 +1,15 @@
+---
+title: Installation and setup
+description: Learn how to install and setup the Coordinator Service.
+sidebar_label: Installation
+sidebar_position: 2
+---
+
+There are two ways to run the coordinator service: building it from source or using Docker. Both methods require you to clone the MACI repository and move to the project root directory.
+
+```bash
+git clone https://github.com/privacy-scaling-explorations/maci
+cd maci
+```
+
+You need to check the latest [README.md](https://github.com/privacy-ethereum/maci/tree/main/apps/coordinator) instructions in the coordinator service app for detailed information about requirements and steps to install, build, and run the service.

package/versioned_docs/version-v3.x/technical-references/coordinator-service/usage.md

@@ -0,0 +1,64 @@
+---
+title: Usage
+description: Learn how to interact with a running MACI coordinator service instance.
+sidebar_label: Usage
+sidebar_position: 3
+---
+
+After setting up and running the MACI coordinator service, you can interact with it through its RESTful API. The service provides various endpoints for deployment and finalization of polls. Please refer to the API documentation at [https://coordinator.maci.vote/api](https://coordinator.maci.vote/api) for the exact request format and required parameters for all endpoint calls described below.
+
+# Authentication
+
+The coordinator service uses a custom signature authentication mechanism to guard the deploy endpoints. To interact with these endpoints, you need to:
+
+1. Make sure you have run the command to set up and generate the RSA keypair, as described in the instructions section.
+
+2. Ensure that your Ethereum public key is set in the `.env` file under the `COORDINATOR_ADDRESSES` variable.
+
+3. Get the RSA public key from the coordinator service with [https://coordinator.maci.vote/v1/proof/publicKey](https://coordinator.maci.vote/v1/proof/publicKey).
+
+4. Sign a message such as "authenticate-me" using the coordinator's Ethereum private key.
+
+5. Encrypt both the message (also called digest) and its signature using the RSA public key. For example, you can use RSA public-key encryption in the format:
+
+```javascript
+const payload: string = "signature:digest";
+```
+
+Then encrypt this payload using the coordinator’s RSA public key.
+
+# Deploy MACI
+
+To deploy the set of MACI smart contracts, you need to call the endpoint [https://coordinator.maci.vote/v1/deploy/maci](https://coordinator.maci.vote/v1/deploy/maci) with a POST request. The request body should include the necessary parameters for the deployment, such as the gatekeeper policy, state tree depth, and voting mode.
+
+# Deploy Poll
+
+To deploy a new poll to an existing MACI instance, you need to call the endpoint [https://coordinator.maci.vote/v1/deploy/poll](https://coordinator.maci.vote/v1/deploy/poll) with a POST request. The request body should include the necessary parameters for the poll deployment, such as the gatekeeper policy, start and end dates, number of options, and voting mode.
+
+# Deploy Subgraph
+
+To deploy a subgraph for a MACI instance and its corresponding polls, you need to call the endpoint [https://coordinator.maci.vote/v1/subgraph/deploy](https://coordinator.maci.vote/v1/subgraph/deploy) with a POST request. The request body should include the necessary parameters for the subgraph deployment, such as the MACI contract address and the subgraph name.
+
+# Finalize Poll
+
+To finalize a poll, you need to follow a series of steps that involve processing messages, merging state trees, generating proofs, and submitting the final tally on-chain. The Coordinator Service provides endpoints for each of these steps.
+
+## Merge
+
+To merge the published messages and create the required state tree, you need to call the endpoint [https://coordinator.maci.vote/v1/proof/merge](https://coordinator.maci.vote/v1/proof/merge) with a POST request. The request body should include the necessary parameters for the merge operation, such as the MACI contract address and the poll ID.
+
+## Generate
+
+Once the Merkle trees are ready, you can generate the zk-SNARK proof for the final tally by calling the endpoint [https://coordinator.maci.vote/v1/proof/generate](https://coordinator.maci.vote/v1/proof/generate) with a POST request. The request body should include the necessary parameters for the proof generation, such as the MACI contract address and the poll ID.
+
+## Submit
+
+After generating the proof, you can submit the final tally on-chain by calling the endpoint [https://coordinator.maci.vote/v1/proof/submit](https://coordinator.maci.vote/v1/proof/submit) with a POST request. The request body should include the necessary parameters for the submission, such as the MACI contract address, poll ID, and the generated proof.
+
+# Schedule Poll
+
+After deploying a poll, you can schedule it to be finalized automatically after it ends. Make sure to set the MACI coordinator private key in the `.env` file. To do so, you need to call the endpoint [https://coordinator.maci.vote/v1/schedule/poll](https://coordinator.maci.vote/v1/schedule/poll) with a POST request. The request body should include the necessary parameters for scheduling the poll, such as the MACI contract address and the poll ID.
+
+# Health
+
+To check that the env variables are set correctly and the service is running, you can call the health endpoint [https://coordinator.maci.vote/v1/health](https://coordinator.maci.vote/v1/health) with a GET request. This endpoint will return a status message indicating the rapidsnark access, redis database connection, zkeys access, and the MACI coordinator address with its funds in each MACI-compatible network.

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

@@ -0,0 +1,8 @@
+{
+  "label": "Offchain Relayer",
+  "position": 1,
+  "link": {
+    "type": "generated-index",
+    "description": "The Offchain Relayer is a service that allows users to vote on MACI polls free of charge."
+  }
+}

package/versioned_docs/version-v3.x/technical-references/offchain-relayer/index.md

@@ -0,0 +1,51 @@
+---
+title: Introduction
+description: The Offchain Relayer is a service that allows users to vote on MACI polls free of charge.
+sidebar_label: Introduction
+sidebar_position: 1
+---
+
+# Coordinator Service
+
+Welcome to the Offchain Relayer technical reference. Here you will find the technical details of the Offchain Relayer: how to set it up and and how to use it.
+
+## Flow Diagram
+
+Below is a high-level diagram illustrating the flow of the Relayer Service:
+
+![MACI Relayer Flow](/img/relayer-diagram.png)
+
+## High-Level Overview of the Relayer:
+
+### Functionality
+
+The Relayer serves as an intermediary between users and the MACI system. It performs the following tasks:
+
+- Allows users to send messages without having to pay gas fees by processing these messages off-chain.
+- Receives user messages.
+- Prepare messages batches and upload it to IPFS
+- Submits the message hashes to the Poll contract with IPFS hash of the batch.
+
+This process ensures that user actions are recorded on-chain without compromising their privacy.
+
+### Privacy Preservation
+
+By verifying the zero-knowledge proofs, the Relayer ensures that only authorized users can send messages.
+Users must know the pre-image to a state leaf in the poll state tree.
+
+### Decentralization and Trust
+
+It's recommended that the coordinator only runs this service for now. That is because if the service malfunctions and batch hashes are pushed on chain without the messages actually being stored on ipfs, then polls can't be finalized.
+
+### Integration with MACI Components
+
+The Relayer interacts with other components of the MACI system, such as the **Coordinator** and the on-chain smart contracts:
+
+- The **Coordinator** fetches all the messages stored in IPFS and uses them as regular on-chain messages.
+- This ensures that user messages are properly processed and recorded, contributing to the overall functionality and security of the voting protocol.
+
+### Additional Information
+
+For more details, you can read the following post on EthResearch:
+
+[MACI with Mostly Off-Chain Happy Path](https://ethresear.ch/t/maci-with-mostly-off-chain-happy-path/19527)

package/versioned_docs/version-v3.x/technical-references/offchain-relayer/installation.md

@@ -0,0 +1,109 @@
+---
+title: Installation and setup
+description: Learn how to install and setup the Offchain Relayer service.
+sidebar_label: Setup
+sidebar_position: 2
+---
+
+## Prerequisites
+
+Make sure you have the following tools installed on your system:
+
+- **Docker**: [Install Docker](https://www.docker.com/products/docker-desktop)
+- **Docker Compose**: [Install Docker Compose](https://docs.docker.com/compose/install/)
+
+## Getting Started
+
+Follow these steps to run the MACI Relayer service using Docker.
+
+### 1. Clone the Repository
+
+First, clone the repository to your local machine.
+
+```bash
+git clone https://github.com/privacy-scaling-explorations/maci
+cd maci
+```
+
+## 2. Configure Environment Variables
+
+The `.env` file contains sensitive configuration values that will be injected into the Docker containers at runtime. To set them up:
+
+1. Copy the `.env.example` file to `.env`.
+
+```bash
+cp .env.example .env
+```
+
+2. Edit the `.env` file and configure the variables.
+
+## 3. Build and Run the Docker Containers
+
+Now that your environment is set up, it's time to build and run the Docker containers.
+
+Run the following command from the root directory of your project:
+
+```bash
+docker-compose up --build
+```
+
+This command does the following:
+
+- Builds the Docker images based on the Dockerfile and `docker-compose.yml` files.
+- Starts the service container (the MACI relayer application) and the mongodb container.
+
+The MACI Relayer service will be available on port 3000 by default (you can modify this in the `.env` file).
+
+## 4. Access the Service
+
+Once the containers are up and running, you can access the relayer service at:
+
+```
+http://localhost:3000
+```
+
+Additionally, the Swagger UI documentation for the Relayer service API can be accessed at:
+
+```
+http://localhost:3000/api
+```
+
+You can interact with the API through the Swagger interface, which provides a convenient way to test endpoints and view the API methods.
+
+## 5. Check Logs
+
+To view the logs from the containers and troubleshoot any issues, run:
+
+```bash
+docker-compose logs
+```
+
+This will display logs from both the service (relayer) and mongodb containers.
+
+## 6. Stop the Services
+
+To stop the containers and remove the containers (but keep the volumes), use the following command:
+
+```bash
+docker-compose down
+```
+
+This will stop and remove the containers but retain the volumes (like MongoDB data). To also remove the volumes, run:
+
+```bash
+docker-compose down --volumes
+```
+
+## 7. MongoDB Persistence
+
+MongoDB data is persisted using Docker volumes (`mongodb-data`). Even if you remove and recreate the MongoDB container, the data will persist.
+
+This ensures that any data stored in the MongoDB database is not lost even if the container is restarted or removed.
+
+If you'd like to remove the persisted data as well, you can remove the volume by running:
+
+```bash
+docker volume rm your-repo_mongodb-data
+```
+
+This will delete the volume, along with all the data stored in MongoDB.

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/main/packages/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(PublicKey memory _publicKey, 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(_publicKey.x, _publicKey.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(_publicKey.x, _publicKey.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, _publicKey.x, _publicKey.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, non quadratic voting, full credits 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 `totalSignups` 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/main/packages/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.