@maci-protocol/website 0.0.0-ci.2653bc0

package/versioned_docs/version-v2.x/guides/frontend.md

@@ -0,0 +1,99 @@
+---
+title: Frontend Deployment
+description: How to troubleshoot MACI's failures
+sidebar_label: Frontend Deployment
+sidebar_position: 2
+---
+
+# Deploy a Frontend
+
+[MACI Platform](https://github.com/privacy-scaling-explorations/maci-platform) is a complete frontend solution for running voting or funding rounds using MACI. This guide explains how to deploy MACI Platform.
+
+## Setup
+
+Start by cloning the MACI Platform repo:
+
+```bash
+git clone https://github.com/privacy-scaling-explorations/maci-platform
+```
+
+Head to the folder, checkout to the v1 release and install the dependencies:
+
+```bash
+cd maci-platform && \
+git checkout v1 && \
+pnpm install
+```
+
+:::note
+This guide uses the v1 version of MACI Platform, for documentation related to each version head to the repository docs [here](https://github.com/privacy-scaling-explorations/maci-platform/blob/main/docs/01_setup.md).
+:::
+
+## Configuration
+
+Copy the example variables and update them accord to your needs:
+
+```bash
+cp packages/interface/.env.example packages/interface/.env
+```
+
+At the very minimum make sure to configure:
+
+- **BLOB_READ_WRITE_TOKEN.** Storage for applications metadata.
+- **NEXT_PUBLIC_ALCHEMY_ID.** Optional but highly recommended for RPC calls.
+- **NEXT_PUBLIC_REGISTRATION_END_DATE.** Determine when users can register application.
+- **NEXT_PUBLIC_ADMIN_ADDRESS.** Address that will approve applications and voters
+- **NEXT_PUBLIC_APPROVAL_SCHEMA.** Schema for applications and voters.
+- **NEXT_PUBLIC_METADATA_SCHEMA.** Schema for storing metadata refs.
+- **NEXT_PUBLIC_MACI_ADDRESS.** The MACI contract address deployed on the [Getting Started Guide](/docs/getting-started).
+- **NEXT_PUBLIC_MACI_START_BLOCK.** Block when was deployed the MACI contract.
+- **NEXT_PUBLIC_MACI_SUBGRAPH_URL.** URL of the Subgraph deployed on the [Subgraph Deployment Guide](/docs/guides/subgraph).
+
+:::important
+Make sure that the EAS schemas exist in the network that you are using.
+:::
+
+Build the repo with the following command.
+
+```bash
+pnpm build
+```
+
+In order to run the interface locally can run:
+
+```bash
+pnpm dev:interface
+```
+
+## Deploy Poll
+
+Once you have configured the repo with the subgraph and MACI contract you only need to [deploy a poll](/docs/getting-started#deploy-poll) on MACI.
+
+```bash
+pnpm deploy-poll:NETWORK
+```
+
+## Deploy Frontend
+
+The easiest way to deploy MACI Platform is using [vercel](https://vercel.com/new).
+
+1. Import the repo you created/forked
+2. Open the Environment Variables panel
+3. Select the first field and paste your variables from your text editor.
+4. Deploy!
+
+## Results
+
+Once the voting time has ended, as a coordinator, you need to [merge the signups and generate the proofs](/docs/getting-started#poll-finalization). This is done on the MACI repo.
+
+This is going to generate a `tally.json` file, then you need to rename it as `tally-{pollId}.json` or `tally-{roundId}.json`, upload it and add it as an environment variable `NEXT_PUBLIC_TALLY_URL`. The frontend will read this variable and will display the results.
+
+:::important
+We recommend you use vercel storage to upload the `tally-{pollid}.json` file.
+:::
+
+## Credits
+
+The interface originally started as a fork of [easy-rpgf](https://github.com/gitcoinco/easy-retro-pgf), but has since taken a completely different direction. As a result, we decided to detach the fork to clarify the project's new focus, which now extends beyond RPGF to include other types of voting and funding.
+
+We are very thankful to the developers and all contributors of the [easy-rpgf](https://github.com/gitcoinco/easy-retro-pgf) project, and we hope to continue collaborating and wish to see their project succeed and help more communities/projects get funded.

package/versioned_docs/version-v2.x/guides/integrating.md

@@ -0,0 +1,73 @@
+---
+title: Integrating MACI
+description: How to integrate MACI into your application
+sidebar_label: Integrating
+sidebar_position: 5
+---
+
+MACI can be used in any protocol that requires collusion resistance, for instance it has been proven to be quite efficient when integrated in quadratic funding applications such as [clr.fund](https://github.com/clrfund/monorepo) and [qfi](https://github.com/quadratic-funding/qfi/tree/feat/code-freeze).
+
+Here we will be looking at how the smart contracts can be integrated. Please note that this will be expanded as QFI is updated to use the newest version of MACI. Should you decide to integrate MACI in the meantime, feel free to open an issue on the GitHub repo.
+
+## MACI Contract
+
+The MACI contract is the core of the protocol. Contracts can inherit from MACI and thus expose the `signUp` and `deployPoll` functions. As with standalone MACI, one would need to deploy a [sign up gatekeeper](/docs/technical-references/smart-contracts/Gatekeepers) as well as the [voice credit proxy](/docs/technical-references/smart-contracts/VoiceCreditProxy).
+
+As an example, a [contract](https://github.com/ctrlc03/minimalQF/blob/main/contracts/MinimalQf.sol#L113) could inherit from MACI and allows sign up via a custom signup function.
+
+```javascript
+function signUp(
+    PubKey memory _pubKey,
+    bytes memory _signUpGatekeeperData,
+    bytes memory _initialVoiceCreditProxyData
+) public override {
+  // the amount must be set in the initial voice credit proxy data
+  uint256 amount = abi.decode(_initialVoiceCreditProxyData, (uint256));
+
+  // transfer tokens to this contract
+  nativeToken.safeTransferFrom(msg.sender, address(this), amount);
+
+  // the voice credits will be the amount divided by the factor
+  // the factor should be decimals of the token
+  // normal signup
+  super.signUp(_pubKey, _signUpGatekeeperData, _initialVoiceCreditProxyData);
+
+  // store the address of the user signing up and amount so they can be refunded just in case
+  // the round is cancelled
+  // they will be able to vote from different addresses though
+  contributors[msg.sender] = amount;
+}
+```
+
+## InitialVoiceCreditProxy
+
+If you'd like to extend the functionality of how votes are distributed among users, you need to extend [InitialVoiceCreditProxy](https://github.com/privacy-scaling-explorations/maci/blob/dev/contracts/contracts/initialVoiceCreditProxy/InitialVoiceCreditProxy.sol) contract. You can see our [basic example](https://github.com/privacy-scaling-explorations/maci/blob/dev/contracts/contracts/initialVoiceCreditProxy/ConstantInitialVoiceCreditProxy.sol) how it's implemented for constant distribution.
+
+```ts
+contract ConstantInitialVoiceCreditProxy is InitialVoiceCreditProxy {
+  /// @notice the balance to be returned by getVoiceCredits
+  uint256 internal balance;
+
+  /// @notice creates a new ConstantInitialVoiceCreditProxy
+  /// @param _balance the balance to be returned by getVoiceCredits
+  constructor(uint256 _balance) payable {
+    balance = _balance;
+  }
+
+  /// @notice Returns the constant balance for any new MACI's voter
+  /// @return balance
+  function getVoiceCredits(address, bytes memory) public view override returns (uint256) {
+    return balance;
+  }
+}
+```
+
+## Poll Contract
+
+On the other hand, the Poll contract can be inherited to expose functionality such as publishing of messages/commands.
+
+For instance, should it be required to gatekeep who can send a message, overriding the `publishMessage` function could be the best way to go.
+
+## Tally Contract
+
+Given the verification functions being exposed by the Tally contract, quadratic funding protocols might require to extend the Tally contract to add distribution logic. Looking at this [example](https://github.com/ctrlc03/minimalQF/blob/main/contracts/MinimalQFTally.sol#L114) the `claimFunds` function is added to a contract inheriting from `Tally`, and uses functions such as `verifyPerVOSpentVoiceCredits` to distribute funds to projects part of a quadratic funding round.

package/versioned_docs/version-v2.x/guides/maciWrapper.md

@@ -0,0 +1,173 @@
+---
+title: MACI Wrapper Guide Scaffold ETH 2 & MACI Voting Template
+description: Introduction to the MACI Wrapper and Setup
+sidebar_label: MACI Wrapper Guide
+sidebar_position: 3
+---
+
+# MACI Wrapper Guide: [Scaffold ETH 2 & MACI Voting Template](https://github.com/yashgo0018/maci-wrapper) by [Yash](https://github.com/yashgo0018)
+
+Welcome to the hacker guide for the Scaffold ETH 2 + MACI Voting Template! This guide will help you get started with the template, providing step-by-step instructions to set up and customize your decentralized voting application, understand MACI, and explore project ideas.
+
+## Understanding MACI
+
+### What is MACI?
+
+Minimal Anti-Collusion Infrastructure (MACI) is a cryptographic protocol designed to enhance the privacy and security of voting systems on blockchain platforms. MACI ensures that votes are cast anonymously, preventing voters from being coerced or bribed. It combines several cryptographic techniques, including zk-SNARKs (Zero-Knowledge Succinct Non-Interactive Argument of Knowledge) and Merkle trees, to achieve its anti-collusion goals.
+
+### Key Features of MACI
+
+- **Anonymity:** Ensures that the identity of the voter is concealed, making it impossible to link votes to individuals.
+- **Collusion Resistance:** Prevents voters from proving how they voted, thereby deterring bribery and coercion.
+- **Privacy:** Maintains the confidentiality of individual votes while allowing the aggregate result to be verified.
+
+### How MACI Works
+
+1. **Voter Registration:** Voters register their identities using a public-private key pair.
+2. **Vote Casting:** Votes are encrypted and submitted to the MACI contract. When votes are processed, only votes of eligible users are counted.
+3. **Tallying Votes:** After the voting period, the votes are decrypted and tallied in a way that ensures the privacy and integrity of the results.
+
+## Quickstart Guide
+
+### 1. Clone and Set Up the Project
+
+Clone the project repository and install the dependencies:
+
+```bash
+git clone https://github.com/yashgo0018/maci-wrapper.git
+cd maci-wrapper
+yarn install
+```
+
+### 2. Download the zkeys for the MACI Circuits
+
+In your first terminal window, run:
+
+```bash
+yarn download-zkeys
+```
+
+### 3. Update Environment Variables
+
+Copy the example environment files to the required `.env` files:
+
+```bash
+cp packages/hardhat/.env.example packages/hardhat/.env
+cp packages/nextjs/.env.example packages/nextjs/.env.local
+```
+
+Update the values of the environment variables in these new `.env` files.
+
+### 4. Start a Local Ethereum Network
+
+In your first terminal window, run:
+
+```bash
+yarn chain
+```
+
+This will start a local Ethereum network using Hardhat.
+
+### 5. Deploy Contracts
+
+In a second terminal window, deploy your contracts:
+
+```bash
+yarn deploy
+```
+
+### 6. Launch the NextJS Application
+
+In a third terminal window, start the NextJS frontend:
+
+```bash
+yarn start
+```
+
+### 7. Compute Results
+
+In a fourth terminal window, clone the MACI repository:
+
+```bash
+git clone git@github.com:privacy-scaling-explorations/maci.git
+```
+
+Copy the zkeys generated from the maci-wrapper repo to the CLI directory of the MACI repo:
+
+```bash
+cp -r ../maci-wrapper/packages/hardhat/zkeys ./cli
+```
+
+Install dependencies and build the MACI project:
+
+```bash
+pnpm i
+pnpm run build
+```
+
+Copy the new contract addresses:
+
+```bash
+cp -r ../maci-wrapper/packages/contractAddresses.json ./cli/build/contractAddresses.json
+```
+
+Follow the MACI documentation to merge signups, merge messages, generate proof, and then you can upload the `tally.json` file to the admin panel after the poll is over.
+
+### 8. Interact with Your DApp
+
+Navigate to `http://localhost:3000` to interact with your decentralized application (dApp).
+
+### 9. Modifications
+
+You can modify the app configuration in `packages/nextjs/scaffold.config.ts` to change the target network and `packages/hardhat/constants.ts` is you want to update the zkeys or use your own custom contracts for `voice credit proxy`, `gate keeper`, `verifier` or `topup credits`.
+
+#### Example Configuration Changes
+
+To host your dApp on a separate network (e.g., Sepolia testnet), you need to update the following file:
+
+1. **`packages/nextjs/scaffold.config.ts`**
+
+```
+...
+const scaffoldConfig = {
+  ...
+  targetNetworks: [chains.sepolia],
+...
+```
+
+2. **Deploying Contracts to Sepolia**
+
+Ensure your `packages/hardhat/.env` file contains your private key and Alchemy project ID:
+
+```env
+DEPLOYER_PRIVATE_KEY=your_private_key
+ALCHEMY_API_KEY=your_alchemy_project_id
+```
+
+Then, deploy your contracts to Sepolia:
+
+```bash
+yarn deploy --network sepolia
+```
+
+## Usage
+
+### Register
+
+Use the app's interface to register with the MACI contract and gain voting rights.
+
+### Create Polls
+
+As an admin, you can create polls with custom questions and options.
+
+### Vote
+
+Registered voters can participate in polls, utilizing MACI's secure voting mechanism.
+
+### View Results
+
+Access poll outcomes after the voting phase ends.
+
+### Admin Dashboard
+
+Monitor and manage ongoing polls, including viewing detailed poll status.

package/versioned_docs/version-v2.x/guides/subgraph.md

@@ -0,0 +1,79 @@
+---
+title: Subgraph Deployment
+description: How to deploy a MACI Subgraph
+sidebar_label: Subgraph Deployment
+sidebar_position: 1
+---
+
+# Subgraph Deployment
+
+In some instances like a frontend you might need to deploy a subgraph, in the MACI repository you can find the configuration to deploy a subgraph on The Graph Network or Alchemy Subgraphs.
+
+:::important
+While the free plan of The Graph and Alchemy can work well, it's recommended to use a paid plan for production.
+:::
+
+## Configuration
+
+Head to the subgraph folder in the app folder.
+
+```bash
+cd apps/subgraph
+```
+
+Edit the `network.json` file in the `config` folder. Adding the network it was deployed, the MACI contract and the block where it was deployed.
+
+```json
+{
+  "network": "optimism-sepolia",
+  "maciContractAddress": "0xD18Ca45b6cC1f409380731C40551BD66932046c3",
+  "maciContractStartBlock": 11052407
+}
+```
+
+:::note
+See the supported networks of The Graph **[here](https://thegraph.com/docs/en/developing/supported-networks/)**.
+:::
+
+Create a subgraph in [the graph studio](https://thegraph.com/studio/) and name it `maci-subgraph`.
+
+## The Graph Deployment
+
+The first thing you need to do is to copy the `key` in subgraph studio dashboard and run the following command to authenticate:
+
+```bash
+graph auth --studio {key}
+```
+
+Then run the following commands to build and deploy the subgraph:
+
+```bash
+pnpm run build && \
+pnpm run deploy
+```
+
+:::important
+The `pnpm run deploy` command uses `maci-subgraph` as the subgraph name by default, but if you named your subgraph differently (e.g. maci-graph, my-graph, etc.), please change the command to `graph deploy --node https://api.studio.thegraph.com/deploy/ your_subgraph_name`
+:::
+
+## Alchemy Deployment
+
+Deploying to the Alchemy subgraph service requires some changes to the `subgraph.template.yaml` file located in the `templates` folder. You need to remove the following keys:
+
+```yaml
+indexerHints:
+  prune: auto
+```
+
+Now you can run the deploy command with some minor changes:
+
+```bash
+graph deploy SUBGRAPH_NAME \
+  --version-label VERSION \
+  --node https://subgraphs.alchemy.com/api/subgraphs/deploy \
+  --deploy-key API_KEY
+```
+
+:::note
+In order to get a subgraph deploy key for alchemy, head to the subgraph dashboard section and select `add subgraph` and pick `Deploy a New Subgraph` here you will see the deploy key.
+:::

package/versioned_docs/version-v2.x/guides/testing/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Testing",
+  "position": 7
+}

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

@@ -0,0 +1,203 @@
+---
+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/testing) 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
+
+### CLI Tests
+
+MACI's CLI provides a series of commands that can be used by both the coordinator and voters, to interact with MACI, from deploying smart contracts to submitting a vote.
+
+Currently, there are a number of test cases that are available inside the cli tests folder. The tests are split into two categories:
+
+- e2e tests that include the entire MACI stack, from deploying the contracts to submitting a vote and tallying all results.
+- unit tests for cli commands
+
+The goal of these tests is to ensure that the MACI stack works as expected, and that the coordinator and voters can interact with the system as expected. They currently do not attempt to verify whether the tally results are expected, or that all votes were accounted for. On the other hand, they test different scenarios, mixing different numbers of voters and messages.
+
+### Integration Tests
+
+Integration tests follow a similar fashion of the CLI 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 `integrationTests/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, 2, 1, 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/cli/testScript.sh) inside the cli 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 signups tree
+9. Merge the messages tree
+10. Generate proofs for the message processing and vote tallying
+11. Update the on chain state
+12. 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.