@maci-protocol/website 0.0.0-ci.b4e6be4 → 0.0.0-ci.ec84efe

package/blog/2024-12-01-maci-getting-started.md

@@ -1,5 +1,5 @@
 ---
-slug: Getting Started MACI
+slug: getting-started-with-maci
 title: Getting Started with MACI
 description: Guide to use MACI
 authors:

package/blog/2025-03-21-roadmap-2025.md

@@ -1,5 +1,5 @@
 ---
-slug: 2025 Roadmap
+slug: 2025-Roadmap
 title: 2025 High Level Roadmap and recap
 description: High level roadmap for 2025
 authors:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maci-protocol/website",
-  "version": "0.0.0-ci.b4e6be4",
+  "version": "0.0.0-ci.ec84efe",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -41,8 +41,8 @@
     "@docusaurus/module-type-aliases": "^3.7.0",
     "@docusaurus/tsconfig": "^3.7.0",
     "@docusaurus/types": "^3.7.0",
-    "@types/node": "^22.13.10",
-    "@types/react": "^19.0.12",
+    "@types/node": "^22.14.0",
+    "@types/react": "^19.1.0",
     "ts-node": "^10.9.2",
     "typescript": "^5.8.2"
   },
@@ -61,5 +61,5 @@
   "engines": {
     "node": ">=18.0"
   },
-  "gitHead": "b10c63bffeb79508fd4f9630008131dae96a4473"
+  "gitHead": "b27e334527501011f6e95b16c78d5141c3d3c66d"
 }

package/versioned_docs/version-v3.x/core-concepts/coordinator-service.md

@@ -0,0 +1,16 @@
+---
+title: Coordinator Service
+description: The Coordinator Service is a service that allows to automate MACI coordinator tasks.
+sidebar_label: Coordinator Service
+sidebar_position: 10
+---
+
+# Coordinator Service
+
+MACI’s coordinator service is a backend service that aims to automate MACI-related operations, such as contracts deployment, proof generation and poll finalisation.
+
+Up until now, users of MACI have had to manually deploy the smart contracts using some scripts, which while pretty straightforward, they require the manual step of running them from a command line. The same goes for the finalisation of polls, which requires coordinators to check when a poll ends, and then run a number of scripts to process votes and tally them, as well as sending the results on chain. This prevents (or at a minimum makes it very difficult) non technical users from being coordinators of MACI.
+
+With the coordinator service, a number of REST endpoints are exposed that allow client applications to perform the above tasks. For instance, now we can have frontend applications with intuitive interfaces to deploy and configure smart contracts. For poll finalisation, this can either be automated with a cron job, or triggered by a client application request.
+
+For more details on how to use and integrate the coordinator service into your application, please refer to this [guide](/docs/technical-references/coordinator-service).

package/versioned_docs/version-v3.x/core-concepts/offchain-voting.md

@@ -0,0 +1,14 @@
+---
+title: Offchain Voting
+description: The Offchain Voting is a service that allows users to vote on MACI polls free of charge.
+sidebar_label: Offchain Voting
+sidebar_position: 11
+---
+
+# Coordinator Service
+
+MACI’s offchain voting service is a backend service that allows users to vote on MACI polls free of charge. This originated from [Vitalik's post](https://ethresear.ch/t/maci-with-mostly-off-chain-happy-path/19527).
+
+In order to improve inclusivity of MACI polls, a coordinator can spin up the offchain relayer service to allow voters to submit their choices off-chain, saving on gas costs. Voters can check whether their vote has been submitted successfully by using relayer SDK, and if they believe they have been censored, can directly submit their vote on chain, using MACI in its normal form.
+
+For more details on how to use and integrate the offchain relayer service into your application, please refer to this [guide](/docs/technical-references/offchain-relayer).

package/versioned_docs/version-v3.x/core-concepts/spec.md

@@ -2,7 +2,7 @@
 title: MACI v1.0 Specification
 description: A detailed specification meant to assist auditors in reviewing MACI version 1.0
 sidebar_label: Specification
-sidebar_position: 10
+sidebar_position: 11
 ---
 
 # MACI v1.0 Specification

package/versioned_docs/version-v3.x/core-concepts/workflow.md

@@ -103,9 +103,15 @@ Before a user can cast a vote, they must sign up by generating a MACI keypair an
 This registration process is necessary to fortify MACI against Sybil attacks. The particular criteria used to allow user signups is customizable, and can be configured using any [SignUpPolicy contract](https://github.com/privacy-scaling-explorations/excubiae/tree/main/packages/contracts/contracts/extensions). This contracts dictate the criteria a user must pass in order to participate in a poll. For example, a user might need to prove ownership of a certain NFT, or that they've received some attestation on EAS, or prove that they have passed some sort of proof-of-personhood verification. Note that MACI presumes an identity system where each legitimate member
 controls a unique private key - MACI does not specifically solve for this, but allows for customization on how this is configured.
 
+#### Poll Joining
+
+Once a user has signed up with MACI, they can join open polls by passing any poll specific gatekeeping requirements, as well as providing a zero knowledge proof that they know the private key to their previously signed up MACI public key.
+
+This step must be repeated for each poll that the user wishes to vote on, and will allow them to receive voting power specific to that poll.
+
 #### Vote
 
-Once a user has signed up with MACI, they are eligible to vote on open polls.
+After joining a poll, a user can cast a vote by sending a message to the Poll contract.
 
 To cast a vote, a user will bundle a few variables — including a public key, their vote option, their vote amount, and a few others — into what is called a "command". Then, the user signs the command with the private key they originally used to sign up. After that, the user encrypts the signature and command together so that it is now considered a "message". If the command is properly signed by the user’s MACI public key, then the message is considered valid will be counted in the final tally. Therefore, the MACI public key can be thought of as the user’s voting username, and the signature is the voting password. If they provide the correct signature, they can submit a vote.
 

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,10 @@
+---
+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. Here you will find the technical details of the Coordinator Service, including the API endpoints and code examples.

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

@@ -0,0 +1,43 @@
+---
+title: Installation and setup
+description: Learn how to install and setup the Coordinator Service.
+sidebar_label: Installation
+sidebar_position: 2
+---
+
+1. Add `.env` file (see `.env.example`).
+2. Generate RSA key pair with `pnpm run generate-keypair`.
+3. Download zkey files using `pnpm run download-zkeys:{type}` (only test type is available for now).
+4. Make sure you copied RSA public key to your application. This will be needed for encrypting `Authorization` header and coordinator private key for proof generation. Also it can be accessed through API method `GET v1/proof/publicKey`.
+5. Run `pnpm run start` to run the service.
+6. All API calls must be called with `Authorization` header, where the value is encrypted with RSA public key you generated before. Header value contains message signature and message digest created by `COORDINATOR_ADDRESSES`. The format is `publicEncrypt({signature}:{digest})`.
+   Make sure you set `COORDINATOR_ADDRESSES` env variable and sign any message with the addresses from your application (see [AccountSignatureGuard](./ts/auth/AccountSignatureGuard.service.ts)).
+7. Proofs can be generated with `POST v1/proof/generate` API method or with Websockets (see [dto spec](./ts/proof/dto.ts), [controller](./ts/app.controller.ts) and [wsgateway](./ts/events/events.gateway.ts)).
+
+## Subgraph deployment
+
+It is possible to deploy subgraph using coordinator service.
+
+First, you need to setup subgraph and create a project. [Subgraph dashboard](https://thegraph.com/studio/).
+
+Then, set env variables:
+
+```
+# Subgraph name
+SUBGRAPH_NAME="maci-subgraph"
+
+# Subgraph provider url
+SUBGRAPH_PROVIDER_URL=https://api.studio.thegraph.com/deploy/
+
+# Subgraph deploy key
+SUBGRAPH_DEPLOY_KEY=*******
+
+# Subgraph project folder
+SUBGRAPH_FOLDER=../subgraph
+```
+
+After deployment, subgraph url will be available in studio dashboard and you can use this type of url to get latest deployed version in your application:
+
+```
+https://api.studio.thegraph.com/.../{SUBGRAPH_NAME}/version/latest
+```

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.