From 6d08c1af562057066c4f3078dcbceb6c5bf709f6 Mon Sep 17 00:00:00 2001 From: Crisgarner Date: Tue, 1 Oct 2024 01:20:17 -0600 Subject: [PATCH] docs(docs): improved docs, added resources (#1843) Co-authored-by: Crisgarner <@crisgarner> --- apps/website/src/content/projects.json | 10 ++++ .../version-v2.x/core-concepts/poll-types.md | 46 +++++++++++++++++-- .../version-v2.x/introduction.md | 4 +- .../version-v2.x/overview/resources.md | 6 ++- .../version-v2.x/overview/workflow.md | 2 +- 5 files changed, 61 insertions(+), 7 deletions(-) diff --git a/apps/website/src/content/projects.json b/apps/website/src/content/projects.json index 5e57d17e66..fa15ccaaa1 100644 --- a/apps/website/src/content/projects.json +++ b/apps/website/src/content/projects.json @@ -19,6 +19,16 @@ "github": "https://github.com/gitcoinco/MACI_QF" } }, + { + "name": "DoraHacks Light-Weight MACI", + "description": "DoraHacks MACI is a light-weight implementation of MACI.", + "hackathon": null, + "status": "Production", + "links": { + "github": "https://github.com/dorahacksglobal/qf-maci", + "website": "https://dorahacks.io/blog/guides/maci-qv-guide/" + } + }, { "name": "MACI Platform", "description": "a platform that allows to run different types of vote and funding rounds using MACI.", diff --git a/apps/website/versioned_docs/version-v2.x/core-concepts/poll-types.md b/apps/website/versioned_docs/version-v2.x/core-concepts/poll-types.md index 17215bd839..f683bd285a 100644 --- a/apps/website/versioned_docs/version-v2.x/core-concepts/poll-types.md +++ b/apps/website/versioned_docs/version-v2.x/core-concepts/poll-types.md @@ -7,7 +7,7 @@ sidebar_position: 9 MACI allows to conduct polls in both a quadratic voting and non quadratic voting fashion. One should be aware that the only distinction between the two happens when messages are processed and votes tallied. On top of that, the Tally smart contract has been split into two different ones, with the non quadratic voting version one being slightly smaller, due to the need of one less function. -This document will explain how to use each of these options. +This document will explain how to use each of these options. Hardhat tasks are the currently recommended way to deploy contracts and run polls but you can also use the MACI cli. ## Quadratic Voting @@ -15,7 +15,27 @@ MACI has always worked with quadratic voting. Users signing up to MACI are assig To run a poll with quadratic voting, the coordinator must deploy the Poll with the mode set to quadratic voting. -Using MACI's cli, one can create a MACI instance with quadratic voting by running the following command: +### Using Hardhat tasks + +In the deploy-config.json file set the `useQuadraticVoting` value to **true**. + +```json +"Poll": { + "pollDuration": 604800, + "coordinatorPubkey": "macipk", + "useQuadraticVoting": true +} +``` + +Then run the task to create a poll: + +```bash +pnpm deploy-poll:NETWORK +``` + +### Using MACI's cli + +One can create a MACI instance with quadratic voting by running the following command: ```bash maci-cli create -uq true $OTHER_PARAMETERS @@ -43,7 +63,27 @@ The non quadratic voting option is a new feature that has been added to MACI wit To run a poll with non quadratic voting, the coordinator must set the `useQuadraticVoting` parameter to `false` when creating the MACI instance. This will make the MACI instance use the `TallyNonQv` smart contract, which is a smaller version of the `Tally` smart contract, as it does not require the checks for the quadratic voting mechanism. -Using MACI's cli, one can create a MACI instance with non quadratic voting by running the following command: +### Using Hardhat tasks + +In the deploy-config.json file set the `useQuadraticVoting` value to **false**. + +```json +"Poll": { + "pollDuration": 604800, + "coordinatorPubkey": "macipk", + "useQuadraticVoting": false +} +``` + +Then run the task to create a poll: + +```bash +pnpm deploy-poll:NETWORK +``` + +### Using MACI's cli + +One can create a MACI instance with non quadratic voting by running the following command: ```bash maci-cli create -uq false $OTHER_PARAMETERS diff --git a/apps/website/versioned_docs/version-v2.x/introduction.md b/apps/website/versioned_docs/version-v2.x/introduction.md index 2555ea8d8b..4dc7ba2795 100644 --- a/apps/website/versioned_docs/version-v2.x/introduction.md +++ b/apps/website/versioned_docs/version-v2.x/introduction.md @@ -17,7 +17,7 @@ MACI is an Ethereum application that provides privacy and collusion resistance f MACI counters this problem by using encryption and zero-knowledge proofs (zk-SNARKs) to hide how each person voted while still publicly revealing the final result. User’s cannot prove which option they voted for, and therefore bribers cannot reliably trust that a user voted for their preferred option. For example, a voter can tell a briber that they are voting for option A, but in reality they voted for option B. There is no reliable way to prove which option the voter actually voted for, so the briber has less incentive to pay voters to vote their way. -Applications like [clr.fund](https://clr.fund/) build atop MACI to increase +Applications like [clr.fund](https://clr.fund/) or protocols like [Allo](https://github.com/gitcoinco/MACI_QF) build atop MACI to increase user privacy and discourage collusion or bribery for public goods funding. ## Features @@ -44,7 +44,7 @@ The participants of a MACI voting process are: 1) the voters and 2) a trusted co Note that MACI presumes an identity system where each legitimate member controls a unique Ethereum private key. -For information on MACI's latest features, please check out our [MACI v1.2.0 release post](/blog/maci-v1-2-0-release). +For information on MACI's latest features, please check out our [MACI v2.0.0 release post](/blog/2024-v2). ## Background diff --git a/apps/website/versioned_docs/version-v2.x/overview/resources.md b/apps/website/versioned_docs/version-v2.x/overview/resources.md index 0bbbad8254..58feabdb33 100644 --- a/apps/website/versioned_docs/version-v2.x/overview/resources.md +++ b/apps/website/versioned_docs/version-v2.x/overview/resources.md @@ -13,6 +13,7 @@ sidebar_position: 3 - [Technical Introduction to MACI 1.0](/blog/maci-1-0-technical-introduction) - Kyle Charbonnet 01/2022 - [MACI v1.1.1 Release](/blog/maci-v1-1-1-release) - ctrlc03 && chaosma 01/2023 - [MACI v1.2.0 release post](/blog/maci-v1-2-0-release) - ctrlc03 02/2024 +- [MACI v2.0.0 release post](/blog/2024-v2) - ctrlc03 08/2024 ## Videos @@ -22,7 +23,10 @@ sidebar_position: 3 - [Anonymity in MACI](https://www.youtube.com/watch?v=X54LaXfJTn4) - Marija Mikić 07/2023 - [Seeing like a Voting](https://youtu.be/euhugXsTUgY?si=jNhqmvFYD9F0r-tB) - Daehyun 11/2023 - [MACI - Private Voting](https://www.youtube.com/watch?v=85bZwcQIgEo&t=1382s) - ctrlc03 03/2024 -- [Construyendo votaciones privadas onchain con MACI](https://www.youtube.com/watch?v=3u5VJJsKLfg) - Cris Garner 03/2024 +- [Construyendo votaciones privadas onchain con MACI](https://www.youtube.com/watch?v=3u5VJJsKLfg) - Crisgarner 03/2024 - [MACI - Starting From Scratch](https://www.youtube.com/watch?v=qVuhWlHnQF0) - Doris Chan 03/2024 - [MACI Workshop](https://www.youtube.com/watch?v=AimgqnMjG0o) - ctrlc03 04/2024 - [MACI Starter Kit Demo](https://www.youtube.com/watch?v=pYoBLLtVEoI&t=1s) - Yash 05/2024 +- [MACI Tutorial Deploying Contracts and Subgraph](https://www.youtube.com/watch?v=-QA0VB9EUMk) - Crisgarner 09/2024 +- [MACI Tutorial Frontend Deployment 🚀](https://www.youtube.com/watch?v=q0yS8RfwDcw) - Crisgarner 09/2024 +- [Finalizing a MACI Round](https://www.youtube.com/watch?v=nlS3hOC0ljw) - Crisgarner 09/2024 diff --git a/apps/website/versioned_docs/version-v2.x/overview/workflow.md b/apps/website/versioned_docs/version-v2.x/overview/workflow.md index dcbf5c1f77..8114b69402 100644 --- a/apps/website/versioned_docs/version-v2.x/overview/workflow.md +++ b/apps/website/versioned_docs/version-v2.x/overview/workflow.md @@ -106,7 +106,7 @@ controls a unique private key - MACI does not specifically solve for this, but a Once a user has signed up with MACI, they are eligible to vote on open polls. -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 public 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. +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. Before sending their vote on-chain, users encrypt their vote using a shared key that only the user and coordinator can know. This key scheme is designed so that every individual user shares a distinct key with the coordinator. This prevents any bribers from simply reading the transaction data to see which option a user voted for. It also allows the coordinator to decrypt user votes (so that they can tally the results).