Skip to main content

One post tagged with "coordinator"

View All Tags

MACI Coordinator Service

· 6 min read
ctrlc03
ctrlc03
MACI former team lead
NicoSerranoP
NicoSerranoP
MACI team member

Hey Anon,

Welcome back to our MACI blog.

Today, we are excited to officially announce something we have referenced frequently: the Coordinator Service.

If you ever used MACI, for instance to run a Retroactive Public Goods Funding (RPGF) or Quadratic Funding (QF) round, you might be aware of how tedious it was to operate. The manual process of running scripts to finalise a round and calculate the tally as well as all of the zk-SNARK proofs could require some time and technical expertise. All these steps had to be done in the terminal and you needed to be familiar with MACI's inner workings to understand the process.

Fear no more - the coordinator service is here to make your life easier.

The vision: MACI for everyone​

Our goal is ambitious, yet simple: completely eliminate the need for any technical knowledge to use MACI. No more terminal commands, no more manual proof generation, no more complex scripts. Just configure once, run inside a Docker container on your server, and enjoy the full power of MACI's privacy-preserving voting infrastructure.

Technical implementation​

The service was built with the following technologies for reliability and scalability:

  • TypeScript for type-safe, maintainable code
  • Nest.js framework for enterprise-grade architecture
  • REST API for standard CRUD operations
  • WebSocket endpoints for real-time updates during intensive computations
  • MACI SDK package to have all the logic and functions ready to use
  • Docker-ready for simple deployment anywhere

The core functionalities of the service are as follows:

  • Deploy a MACI subgraph to query on-chain data easily
  • Deploy the MACI smart contracts, including polls
  • Finalise polls by processing votes and tallying the results
  • Schedule polls for automatic finalization when the voting period ends
  • Health endpoint to check everything is setup and working

Let's dive into more details in the following sections.

Subraph deployment​

The endpoint to deploy a subgraph requires some configuration in the .env file, as well as an HTTP request to the endpoint responsible for this https://coordinator.maci.vote/v1/subgraph/deploy. Make sure you have an account in The Graph to setup your .env file before starting the coordinator service.

Contracts deployment​

There are two endpoints in this module: deploy maci (https://coordinator.maci.vote/v1/deploy/maci) and deploy poll (https://coordinator.maci.vote/v1/deploy/poll). This will take care of all contracts deployment and configuration. It is worth pointing out that you should read the coordinator service API documentation and the MACI guides to understand the roles of each contract (MACI, poll, policy, initialVoiceCredit).

You can deploy one MACI contract (and its internal smart contracts) that will have one gatekeeper policy (e.g. FreeForAll) for all voters to sign up. After that you can deploy multiple polls with different settings (start date, end date, gatekeeper policy, etc). Each voter will have to join each poll to be eligible to participate in. The poll's gatekeeper will check the voter eligibility to join the poll.

Finalisation​

This step includes three separate actions:

  1. Merge - calculate the state merkle tree root and store a commitment to its root (https://coordinator.maci.vote/v1/proof/merge)
  2. Process - fetch all smart contracts events to reconstruct the state locally and process all votes. This includes decrypting votes, checking validity, and finally tallying them. zk-SNARK proofs are generated for each batch of votes processed (https://coordinator.maci.vote/v1/proof/generate)
  3. Submit - submitting all of the zk-SNARK proofs on chain to prove that the poll was processed correctly. Finally, submit the tally results on chain so that they can be seen by everyone (https://coordinator.maci.vote/v1/proof/submit)

We chose to separate each action into its own endpoint to avoid long-running computations that could lead to network errors or timeouts.

Schedule​

After finishing up the finalisation module, we realized that it would be a lot easier for users to create polls and schedule the finalization process. This removes the need for users to manually call the finalization endpoints described above.

  1. To schedule a deployed poll you can use https://coordinator.maci.vote/v1/scheduler/register.
  2. To check if a poll is scheduled you can use https://coordinator.maci.vote/v1/scheduler/status
  3. To delete a scheduled poll you can use https://coordinator.maci.vote/v1/scheduler/delete

How to use​

Run it from source​

  1. Clone the MACI repository: https://github.com/privacy-scaling-explorations/maci
  2. Install dependencies and build the project
pnpm install
pnpm run build
  1. Download the zkeys for the coordinator
pnpm run download-zkeys:ceremony:coordinator
  1. Generate a coordinator MACI keypair. Remember to store those values for later.
pnpm run generate-maci-keypair
  1. Move to the coordinator service directory
cd apps/coordinator
  1. Configure your .env file. Make sure to configure it with your own secure values. The coordinator MACI private key from the previous step should be set here
cp .env.example .env
  1. Start the service
pnpm run start
# or
pnpm run start:prod

Run it with Docker​

  1. Clone the MACI repository: https://github.com/privacy-scaling-explorations/maci
  2. Go inside the project directory
cd maci
  1. Build the docker image and run the container
# Build docker
docker compose -f apps/coordinator/docker-compose.yml build

# Run container detached
docker compose -f apps/coordinator/docker-compose.yml up -d

Usage notes​

  1. You can check out the documentation while the service is running in http://localhost:3001/api

  2. We have a e2e.deploy.test.ts file that performs a complete process: deployment, voting and finalization. You can use it to guide yourself.

Future work​

We are researching about different cryptographic methods to decentralize the coordinator. The idea is to eliminate reliance on a single centralized service for finalizing polls. A group of people would be able to spin up their own coordinator services and finalize the poll in a multi-party computation. For more info check out our MACI v4 research.

Conclusion​

The MACI Coordinator Service represents a significant leap forward in making MACI accessible to everyone. Whether you're running a small community poll or a large-scale funding round, the coordinator service handles the complexity so you can focus on what matters - empowering your community with private, secure voting.

Ready to get started? Head over to our documentation and deploy your first MACI round today!

Please reach out if you would like to integrate the service into your frontend.

References​