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

package/blog/2025-09-05-maci-coordinator-service.md

@@ -0,0 +1,167 @@
+---
+slug: maci-coordinator-service
+title: MACI Coordinator Service
+description: Announcing our coordinator service for MACI
+authors:
+  - name: ctrlc03
+    title: MACI former team lead
+    url: https://x.com/ctrlc03
+    image_url: https://avatars.githubusercontent.com/u/93448202?v=4c
+  - name: NicoSerranoP
+    title: MACI team member
+    url: https://x.com/NicoSerranoP
+    image_url: https://avatars.githubusercontent.com/u/38594836?v=4
+tags: [voting, security, anonymity, MACI, coordinator]
+excerpt: "A MACI plugin for Aragon OSx to enable private voting in DAOs"
+---
+
+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](https://github.com/privacy-scaling-explorations/maci/tree/dev/apps/coordinator/ts/subgraph) to query on-chain data easily
+- [Deploy](https://github.com/privacy-scaling-explorations/maci/tree/dev/apps/coordinator/ts/deployer) the MACI smart contracts, including polls
+- [Finalise](https://github.com/privacy-scaling-explorations/maci/tree/dev/apps/coordinator/ts/proof) polls by processing votes and tallying the results
+- [Schedule](https://github.com/privacy-scaling-explorations/maci/tree/main/apps/coordinator/ts/scheduler) polls for automatic finalization when the voting period ends
+- [Health](https://github.com/privacy-scaling-explorations/maci/tree/main/apps/coordinator/ts/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](https://thegraph.com/studio/) 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](https://coordinator.maci.vote/api) and the [MACI guides](https://maci.pse.dev/docs/core-concepts/workflow) 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](https://github.com/privacy-scaling-explorations/maci)
+2. Install dependencies and build the project
+
+```bash
+pnpm install
+pnpm run build
+```
+
+3. Download the zkeys for the coordinator
+
+```bash
+pnpm run download-zkeys:ceremony:coordinator
+```
+
+4. Generate a coordinator MACI keypair. Remember to store those values for later.
+
+```bash
+pnpm run generate-maci-keypair
+```
+
+5. Move to the coordinator service directory
+
+```bash
+cd apps/coordinator
+```
+
+6. 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
+
+```bash
+cp .env.example .env
+```
+
+7. Start the service
+
+```bash
+pnpm run start
+# or
+pnpm run start:prod
+```
+
+### Run it with Docker
+
+1. Clone the MACI repository: [https://github.com/privacy-scaling-explorations/maci](https://github.com/privacy-scaling-explorations/maci)
+2. Go inside the project directory
+
+```bash
+cd maci
+```
+
+3. Build the docker image and run the container
+
+```bash
+# 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](http://localhost:3001/api)
+
+2. We have a [e2e.deploy.test.ts](https://github.com/privacy-scaling-explorations/maci/blob/main/apps/coordinator/tests/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
+
+- [MACI repo](https://github.com/privacy-scaling-explorations/maci)
+- [Sample frontend](https://github.com/privacy-scaling-explorations/maci-aragon-osx-gov-app) using the coordinator service
+- [Code examples](https://github.com/privacy-scaling-explorations/maci-aragon-osx-gov-app/blob/main/plugins/maciVoting/contexts/CoordinatorContext.tsx)
+- [Documentation](https://maci.pse.dev/docs/category/coordinator-service)

package/blog/authors.yml

@@ -0,0 +1,5 @@
+PSE:
+  name: Privacy and Scaling Explorations (PSE)
+  title: Zero-Knowledge research team
+  url: https://pse.dev
+  image_url: /img/pse-logo-round.png

package/docusaurus.config.ts

@@ -0,0 +1,219 @@
+import rehypeKatex from "rehype-katex";
+import remarkMath from "remark-math";
+
+import type * as Preset from "@docusaurus/preset-classic";
+import type { Config } from "@docusaurus/types";
+
+import { loadContent } from "./src/plugins/blog-plugin/index";
+
+const GITHUB_URL = "https://github.com/privacy-scaling-explorations/maci";
+
+async function getConfig(): Promise<Config> {
+  const blogPosts = await loadContent();
+
+  const config: Config = {
+    title: "MACI",
+    tagline: "Minimal Anti-Collusion Infrastructure",
+    favicon: "img/favicon.ico",
+
+    // Set the production url of your site here
+    url: "https://maci.pse.dev",
+    // Set the /<baseUrl>/ pathname under which your site is served
+    // For GitHub pages deployment, it is often '/<projectName>/'
+    baseUrl: "/",
+
+    // GitHub pages deployment config.
+    // If you aren't using GitHub pages, you don't need these.
+    organizationName: "privacy-scaling-explorations", // Usually your GitHub org/user name.
+    projectName: "maci", // Usually your repo name.
+
+    onBrokenLinks: "warn",
+    onBrokenMarkdownLinks: "warn",
+
+    // Even if you don't use internationalization, you can use this field to set
+    // useful metadata like html lang. For example, if your site is Chinese, you
+    // may want to replace "en" with "zh-Hans".
+    i18n: {
+      defaultLocale: "en",
+      locales: ["en"],
+    },
+
+    presets: [
+      [
+        "classic",
+        {
+          docs: {
+            routeBasePath: "docs/",
+            sidebarPath: "./sidebars.ts",
+            editUrl: ({ versionDocsDirPath, docPath }) =>
+              `${GITHUB_URL}/edit/dev/apps/website/${versionDocsDirPath}/${docPath}`,
+            remarkPlugins: [remarkMath],
+            rehypePlugins: [rehypeKatex],
+            includeCurrentVersion: false,
+            versions: {
+              "v1.2": {
+                banner: "none",
+              },
+            },
+          },
+          blog: {
+            showReadingTime: true,
+
+            editUrl: ({ blogDirPath, blogPath }) => `${GITHUB_URL}/edit/dev/apps/website/${blogDirPath}/${blogPath}`,
+            remarkPlugins: [remarkMath],
+            rehypePlugins: [rehypeKatex],
+            onUntruncatedBlogPosts: "ignore",
+          },
+          theme: {
+            customCss: "./src/css/custom.css",
+          },
+        } satisfies Preset.Options,
+      ],
+    ],
+
+    plugins: [
+      [
+        "@easyops-cn/docusaurus-search-local",
+        {
+          hashed: true,
+          language: ["en"],
+          // If the `indexDocs` is set to `true`, Docusaurus will index docs.
+          // If the `indexBlog` is set to `true`, Docusaurus will index blogs.
+          indexDocs: true,
+          indexBlog: true,
+          // If the `indexPages` is set to `true`, Docusaurus will index pages.
+          indexPages: true,
+          // // Docs route base path, default to '/docs'.
+          // docsRouteBasePath: '/docs',
+          // Blog route base path, default to '/blog'.
+          blogRouteBasePath: "/blog",
+        },
+      ],
+      "docusaurus-plugin-image-zoom",
+      "docusaurus-plugin-matomo",
+    ],
+    stylesheets: [
+      {
+        href: "https://cdn.jsdelivr.net/npm/katex@0.13.24/dist/katex.min.css",
+        type: "text/css",
+        integrity: "sha384-odtC+0UGzzFL/6PNoE8rX/SPcQDXBJ+uRepguP4QkPCm2LBxH3FA3y+fKSiJ+AmM",
+        crossorigin: "anonymous",
+      },
+    ],
+    customFields: {
+      blogPosts: Array.isArray(blogPosts) ? blogPosts : [],
+    },
+    themeConfig: {
+      prism: {
+        additionalLanguages: ["bash"],
+      },
+      image: "img/maci-card.png",
+      navbar: {
+        title: "MACI",
+        items: [
+          {
+            label: "Documentation",
+            href: "/docs/introduction",
+            position: "left",
+          },
+          {
+            to: "/blogs",
+            label: "Blog",
+          },
+          {
+            to: "/roadmap",
+            label: "Roadmap",
+            position: "left",
+          },
+          {
+            to: "/projects",
+            label: "Projects",
+            position: "left",
+          },
+          {
+            type: "docsVersionDropdown",
+            position: "right",
+            dropdownActiveClassDisabled: true,
+            // TODO: add /versions page to explain major versions & link to blog posts
+            // dropdownItemsAfter: [
+            //   {
+            //     type: 'html',
+            //     value: '<hr class="dropdown-separator">',
+            //   },
+            //   {
+            //     to: '/versions',
+            //     label: 'All versions',
+            //   },
+            // ],
+          },
+          {
+            type: "search",
+            position: "right",
+          },
+          {
+            href: GITHUB_URL,
+            label: "GitHub",
+            position: "right",
+          },
+        ],
+      },
+      footer: {
+        links: [
+          {
+            title: "Docs",
+            items: [
+              {
+                label: "Documentation",
+                to: "/docs/introduction",
+              },
+              {
+                label: "GitHub",
+                href: GITHUB_URL,
+              },
+            ],
+          },
+          {
+            title: "Community",
+            items: [
+              {
+                label: "Discord",
+                href: "https://discord.com/invite/sF5CT5rzrR",
+              },
+              {
+                label: "Twitter",
+                href: "https://twitter.com/zkMACI",
+              },
+            ],
+          },
+          {
+            title: "More",
+            items: [
+              {
+                label: "Blog",
+                to: "/blog",
+              },
+            ],
+          },
+        ],
+        copyright: `Copyright © ${new Date().getFullYear().toString()} Privacy and Scaling Explorations`,
+      },
+      zoom: {},
+      matomo: {
+        matomoUrl: "https://psedev.matomo.cloud/",
+        siteId: "18",
+        phpLoader: "matomo.php",
+        jsLoader: "matomo.js",
+      },
+      mermaid: {
+        theme: { light: "neutral", dark: "forest" },
+      },
+    } satisfies Preset.ThemeConfig,
+    markdown: {
+      mermaid: true,
+    },
+    themes: ["@docusaurus/theme-mermaid"],
+  };
+  return config;
+}
+
+export default getConfig();

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@maci-protocol/website",
+  "version": "0.0.0-ci.00107eb",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "setup-typedoc": "ts-node ./src/scripts/setupTypedoc.ts",
+    "setup-soliditydocs": "ts-node ./src/scripts/setupSolidityDocs.ts",
+    "docusaurus": "docusaurus",
+    "start": "docusaurus start",
+    "prebuild": "pnpm run setup-typedoc && pnpm run setup-soliditydocs",
+    "build": "docusaurus build",
+    "swizzle": "docusaurus swizzle",
+    "deploy": "docusaurus deploy",
+    "clear": "docusaurus clear",
+    "serve": "docusaurus serve",
+    "write-translations": "docusaurus write-translations",
+    "write-heading-ids": "docusaurus write-heading-ids",
+    "types": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@docusaurus/core": "^3.8.1",
+    "@docusaurus/preset-classic": "^3.8.1",
+    "@docusaurus/theme-classic": "^3.8.1",
+    "@docusaurus/theme-common": "^3.8.1",
+    "@docusaurus/theme-mermaid": "^3.8.1",
+    "@easyops-cn/docusaurus-search-local": "^0.52.1",
+    "@mdx-js/react": "^3.1.0",
+    "clsx": "^2.1.1",
+    "docusaurus-plugin-image-zoom": "^3.0.1",
+    "docusaurus-plugin-matomo": "^0.0.8",
+    "gray-matter": "^4.0.3",
+    "prism-react-renderer": "^2.4.1",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
+    "rehype-katex": "^7.0.1",
+    "remark-math": "^6.0.0"
+  },
+  "devDependencies": {
+    "@docusaurus/module-type-aliases": "^3.8.1",
+    "@docusaurus/tsconfig": "^3.8.1",
+    "@docusaurus/types": "^3.8.1",
+    "@types/node": "^24.2.0",
+    "@types/react": "^19.1.9",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.2"
+  },
+  "browserslist": {
+    "production": [
+      ">0.5%",
+      "not dead",
+      "not op_mini all"
+    ],
+    "development": [
+      "last 3 chrome version",
+      "last 3 firefox version",
+      "last 5 safari version"
+    ]
+  },
+  "engines": {
+    "node": ">=18.0"
+  },
+  "gitHead": "a35d35aea039b6cd1abbe8d842ac2aa754661135"
+}

package/src/components/ActionCard/index.tsx

@@ -0,0 +1,30 @@
+import styles from "./styles.module.css";
+
+interface ActionCardProps {
+  title: string;
+  description: string;
+  buttonText: string;
+  buttonUrl: string;
+}
+
+const ActionCard: React.FC<ActionCardProps> = ({ buttonText, buttonUrl, description, title }: ActionCardProps) => (
+  <div className={styles.actionCard}>
+    <div className={styles.actionCardBody}>
+      <div className={styles.actionCardContent}>
+        <div className={styles.actionCardText}>
+          <h2 className={styles.actionCardTitle}>{title}</h2>
+
+          <p className={styles.actionCardDescription}>{description}</p>
+        </div>
+
+        <div className={styles.actionCardButtonContainer}>
+          <a className={styles.actionCardButton} href={buttonUrl} rel="noopener noreferrer" target="_blank">
+            {buttonText}
+          </a>
+        </div>
+      </div>
+    </div>
+  </div>
+);
+
+export default ActionCard;

package/src/components/ActionCard/styles.module.css

@@ -0,0 +1,96 @@
+.actionCard {
+  background-color: #1a202c; /* darkBlue */
+  color: white;
+  border-radius: 24px;
+  width: 100%;
+  padding: 64px 32px;
+}
+
+.actionCardBody {
+  padding: 0;
+}
+
+.actionCardContent {
+  display: flex;
+  flex-direction: column;
+  justify-content: space-between;
+  align-items: center;
+  gap: 2rem;
+}
+
+.actionCardText {
+  width: 100%;
+}
+
+.actionCardTitle {
+  font-size: 30px;
+  line-height: 44px;
+  font-weight: normal;
+  color: white;
+}
+
+.actionCardDescription {
+  margin-top: 1rem;
+  font-size: 16px;
+  line-height: 25px;
+  font-weight: normal;
+  color: #a0aec0; /* text.400 */
+}
+
+.actionCardButtonContainer {
+  width: 100%;
+}
+
+.actionCardButton {
+  display: inline-block;
+  padding: 0.5rem 1rem;
+  background-color: #3182ce; /* primary */
+  color: white;
+  text-decoration: none;
+  border-radius: 0.25rem;
+  font-size: 1rem;
+  line-height: 1.5;
+  text-align: center;
+}
+
+@media (min-width: 768px) {
+  .actionCardContent {
+    flex-direction: row;
+    gap: 0;
+  }
+
+  .actionCardText {
+    width: 522px;
+  }
+
+  .actionCardTitle {
+    font-size: 40px;
+  }
+
+  .actionCardDescription {
+    font-size: 20px;
+    line-height: 32px;
+  }
+
+  .actionCardButtonContainer {
+    width: auto;
+  }
+
+  .actionCardButton {
+    padding: 0.75rem 1.5rem;
+    font-size: 1.125rem;
+    border-radius: 30px;
+  }
+}
+
+@media (min-width: 992px) {
+  .actionCard {
+    padding: 41px 80px;
+  }
+}
+
+@media (min-width: 1280px) {
+  .actionCard {
+    width: 1110px;
+  }
+}