docs: update docs

privacy-scaling-explorations · Sep 2, 2024 · 67f7017 · 67f7017
1 parent 599421d
commit 67f7017
Show file tree

Hide file tree

Showing 8 changed files with 89 additions and 49 deletions.
diff --git a/README.md b/README.md
@@ -27,10 +27,12 @@ To run locally follow these instructions:
 ```sh
 git clone https://github.com/privacy-scaling-explorations/maci-platform
 
-pnpm install && pnpm build
+pnpm install
 
 cp packages/interface/.env.example packages/interface/.env # and update .env variables
 
+pnpm build
+
 ```
 
 At the very minimum you need to configure the subgraph url, admin address, maci address and the voting periods. For more details head to [Setup & Deployment](./docs/01_setup.md). Once you have set everything run:

diff --git a/docs/01_setup.md b/docs/01_setup.md
@@ -12,7 +12,7 @@ A complete installation tutorial can be seen here:
 
 [Fork MACI-PLATFORM](https://github.com/privacy-scaling-explorations/maci-platform/tree/main)
 
-1. Click to view the `.env.example` file in your newly created repo
+1. Click to view the `packages/interface/.env.example` file in your newly created repo
 2. Copy its contents and paste into a text editor
 
 ## 2. Deploy MACI
@@ -21,24 +21,21 @@ As a coordinator you need to deploy a MACI instance and poll.
 
 ### Install MACI
 
-You can read about the [MACI requirements here](https://maci.pse.dev/docs/v1.2/installation). To install MACI run the following commands:
+You can read about the [MACI requirements here](https://maci.pse.dev/docs/quick-start/installation). To install MACI run the following commands:
 
 ```bash
 git clone https://github.com/privacy-scaling-explorations/maci.git && \
 cd maci && \
-git checkout v1.2.4 && \
+git checkout v2.1.0 && \
 pnpm i && \
 pnpm run build
 ```
 
 > [!IMPORTANT]
-> It's important to use version 1.2.4 of MACI, as this version's circuit are audited and have zKeys which have undergone a trusted setup.
+> The circuits of MACI version ^2.0.0 are audited, the zKeys have already gone a trusted setup ceremony.
 
 ### Download .zkey files
 
-> [!IMPORTANT]
-> When using the Ceremony Keys make sure to compile the project using the correct state tree depth argument using the following command `export STATE_TREE_DEPTH=6 && pnpm build`. Refer to the [circuits documentation](https://maci.pse.dev/docs/developers-references/zk-snark-circuits/) page for more information.
-
 Download ceremony artifacts for production:
 
 ```bash
@@ -51,11 +48,11 @@ or the test keys for testnet only:
 pnpm download:test-zkeys
 ```
 
-Note the locations of the .zkey files as the CLI requires them as command-line flags.
+Note the locations of the zkey files as the CLI requires them as command-line flags.
 
 ### Set .env Files
 
-Head to the `contracts` folder and copy the `.env.example` file. Make sure to include a mnemonic and RPC url.
+Head to the `packages/contracts` folder and copy the `.env.example` file. Make sure to include a mnemonic and RPC url.
 
 ```
 MNEMONIC="your_ethereum_secret_key"
@@ -68,7 +65,7 @@ ETHERSCAN_API_KEY="etherscan api key"
 Generate a new key pair and save it in a secure place.
 
 ```bash
-cd cli && \
+cd packages/cli && \
 node build/ts/index.js genMaciKeyPair
 ```
 
@@ -77,7 +74,7 @@ node build/ts/index.js genMaciKeyPair
 Head back to the contracts folder.
 
 ```bash
-cd contracts
+cd ../contracts
 ```
 
 Copy the config example and update the fields as necessary:
@@ -86,37 +83,52 @@ Copy the config example and update the fields as necessary:
 cp deploy-config-example.json deploy-config.json
 ```
 
+There are already some deployed contracts that could be reused, copy the `default-deployed-contracts.json` file if you need them to avoid deploying redundant contracts and save your gas fee.
+
+```bash
+cp default-deployed-contracts.json deployed-contracts.json
+```
+
 > [!IMPORTANT]
-> Make sure that you use the production zkeys, set `useQuadraticVoting` to false, and set the pollDuration with the correct time on seconds.
+> Make sure that you use the production zkeys, and set the `pollDuration` with the correct time on **seconds**.
+> If you set `useQuadraticVoting` to `false`, remember to also set `NEXT_PUBLIC_POLL_MODE` in the `maci-platform/packages/interface/.env` file to `non-qv`, otherwise, if you set `useQuadraticVoting` to `true`, set the `NEXT_PUBLIC_POLL_MODE` to `qv`.
 
 ### Deploy MACI Contracts
 
 Run `pnpm deploy` to deploy the contracts (you can specify the network by appending `:network` to the command, e.g. pnpm deploy:sepolia - please refer to the available networks on the package.json scripts section)
+We highly recommend that if you already copy the `default-deployed-contracts.json` file to `deployed-contracts.json` file, run the following command to save your gas:
+
+```bash
+pnpm deploy:NETWORK --incremental
+```
+
+Of course you could run without the `incremental` flag to deploy everything by yourself:
 
 ```bash
 pnpm deploy:NETWORK
 ```
 
-Run pnpm deploy-poll to deploy your first Poll (you can specify the network by appending :network to the command, e.g. pnpm deploy-poll:sepolia - please refer to the available networks on the package.json scripts section).
+Run pnpm deploy-poll to deploy your first Poll (you can specify the network by appending :network to the command, e.g. pnpm deploy-poll:sepolia - please refer to the available networks on the `package.json` scripts section).
 
 ```sh
 pnpm deploy-poll:NETWORK
 ```
 
-See [MACI docs](https://maci.pse.dev/docs/v1.2/integrating#deployment) for more information.
+See [MACI docs](https://maci.pse.dev/docs/quick-start/deployment#deployment-using-maci-contracts-hardhat-tasks) for more information.
 
 ## 3. Configuration
 
-The `.env.example` file contains instructions for most of these steps.
+The `.env.example` file in the `packages/interface/` folder contains instructions for most of these steps.
 
-At the very minimum you need to configure a subgraph, admin address, MACI address, the EAS Schema and the voting periods under App Configuration.
+At the very minimum you need to configure a **subgraph**, **admin address**, **MACI address**, the **EAS Schema** and the **application registration periods** under App Configuration.
 
 ### Subgraph
 
-In the MACI repo and head to the subgraph folder.
+In the **MACI** repo and head to the subgraph folder.
 
-> [!IMPORTANT]
-> If you are using the v1.2.4 branch, you will need to checkout to dev and build in order to deploy a subgraph, once deployed remember to switch back to v1.2.4 in order to finalize the round. The following steps focus on The Graph, but you can deploy a subgraph using Alchemy.
+```bash
+cd apps/subgraph
+```
 
 1. Make sure you have `{network}.json` file in `config` folder, where network is a CLI name supported for subgraph network [https://thegraph.com/docs/en/developing/supported-networks/](https://thegraph.com/docs/en/developing/supported-networks/).
 
@@ -137,6 +149,9 @@ In the MACI repo and head to the subgraph folder.
 5. Run `graph auth --studio {key}`. You can find the key in subgraph studio dashboard.
 6. Run `pnpm run deploy` to deploy subgraph
 
+> [!IMPORTANT]
+> The `pnpm run deploy` command call `maci-subgraph` as the subgraph name as default, but if you named your subgraph a different name (e.g. maci-graph, my-graph, etc.), please change the command to `graph deploy --node https://api.studio.thegraph.com/deploy/ :your_subgraph_name`
+
 #### Network
 
 The default configuration is Optimism Sepolia for development and Optimism for production.
@@ -145,7 +160,7 @@ You can find supported networks on the EAS documentation website: https://docs.a
 
 #### App
 
-Configure the round timelines such as starts and end dates, as well as the registration and review period.
+Configure the round timelines such as starts and end dates for the application registration period.
 
 Here, you can also configure the admin address who will approve applications and voters.
 
@@ -154,13 +169,15 @@ To create your own round you need to do the following:
 - Update `NEXT_PUBLIC_ADMIN_ADDRESS` a wallet address that approves the applications and voters (badgeholders)
 - Set `NEXT_PUBLIC_ROUND_ID` to a unique identifier that will group the applications you want to list
 - Set `NEXT_PUBLIC_MACI_ADDRESS` - your deployed maci contract
+- Set `NEXT_PUBLIC_MACI_SUBGRAPH_URL` - maci subgraph url. You can setup it using [maci-subgraph](https://github.com/privacy-scaling-explorations/maci/tree/dev/subgraph).
 - Set `NEXT_PUBLIC_MACI_START_BLOCK` - block where your maci contract is deployed - optional but very much recommended (as it's a fallback to subgraph not setup/working)
-- Set `NEXT_PUBLIC_MACI_SUBGRAPH_URL` - maci subgraph url (optional). This is recommended to have and you can setup it using [maci-subgraph](https://github.com/privacy-scaling-explorations/maci/tree/dev/subgraph).
 - Set `NEXT_PUBLIC_TALLY_URL` - your endpoint for vote results, where you host `tally-{pollId}.json` files.
 
 #### EAS
 
-If you are running on a different network than Optimism you need to update the contract addresses for EAS. These addresses are used whenever an attestation is created.
+If you are running on a different network than Optimism, just change the `NEXT_PUBLIC_CHAIN_NAME` to your network. Please head to `src/config.ts` to see what network already having its configs. The EAS addresses are used whenever an attestation is created.
+
+By using EAS as checking approvals and application data, it's required to create schemas on the certain network, and add the schema id to `NEXT_PUBLIC_APPROVAL_SCHEMA` and `NEXT_PUBLIC_METADATA_SCHEMA`.
 
 You can also configure your own schemas here if you wish to, or deploy the EAS contracts to a network that doesn't have them.
 
@@ -180,10 +197,10 @@ https://vercel.com/new
 
 ## Poll finalization
 
-Once the voting time has ended, as a coordinator, first you need to merge signups and messages (votes). Head to MACI contracts repository and run the merge command with the deployed poll:
+Once the voting time has ended, as a coordinator, first you need to merge signups and messages (votes). Head to **MACI** repository and run the merge command with the deployed poll:
 
 ```bash
-cd contracts  && \
+cd packages/contracts  && \
 pnpm merge:[network] --poll [poll-id]
 ```
 
@@ -203,7 +220,7 @@ pnpm run prove:[network] --poll [poll-id] \
 > [!IMPORTANT]
 > We suggest including the --start-block flag, proving requires fetching all events from the smart contracts and by default starts from block zero, this would take a lot of time and is error-prone due to RPC provider limitations.
 
-Once you have the tally.json file you can rename it (tally-{pollId}.json), upload it and add it as an environment variable `NEXT_PUBLIC_TALLY_URL` to show the results.
+Once you have the `tally.json` file you can rename it (`tally-{pollId}.json`), upload it and add it as an environment variable `NEXT_PUBLIC_TALLY_URL` to show the results.
 
 ## Additional configuration
 

diff --git a/docs/02_adding_projects.md b/docs/02_adding_projects.md
@@ -1,6 +1,6 @@
 # Adding projects
 
-- Navigate to https://easy-retro-pgf.vercel.app/applications/new (replace the domain with your deployment)
+- Navigate to https://maci-platform.vercel.app/applications/new (replace the domain with your deployment)
 - Fill out profile fields with name, profile image and banner image
 - Fill out application fields
   - **name** - the name to be displayed
@@ -18,10 +18,10 @@ This will create an Attestation with the Metadata schema and populate the fields
 
 ## Reviewing and approving applications
 
-- Navigate to https://easy-retro-pgf.vercel.app/applications (replace the domain with your deployment)
+- Navigate to https://maci-platform.vercel.app/applications (replace the domain with your deployment)
 - Make sure you have configured `NEXT_PUBLIC_ADMIN_ADDRESS` with the address you connect your wallet with
 - You will see a list of submitted applications
-- Press the Review button to open the application
+- Press each of them to open the application
 - Select the applications you want to approve
 - Press Approve button to create attestations for these projects (send transaction to confirm)
 

diff --git a/docs/03_creating_badgeholders.md b/docs/03_creating_badgeholders.md
diff --git a/docs/03_register.md b/docs/03_register.md
@@ -0,0 +1,32 @@
+# Different gating strategy
+
+You can specify the desired gating strategy in the **deploy-config.json** file, see **01_setup.md** and **maci** repository for more information. Using different gating strategies will result in different authentication methods.
+
+# Free for all
+
+Everyone can register to the MACI contract without any authentication.
+
+# EAS
+
+Everyone with specific attestation given by the admin on certain schema is able to register.
+
+## Giving attestation
+
+- Navigate to https://maci-platform.vercel.app/voters (replace the domain with your deployment)
+- Make sure you have configured `NEXT_PUBLIC_ADMIN_ADDRESS` with the address you connect your wallet with
+- Enter a list of addresses you want to allow to vote (comma-separated)
+- Press Approve button to create attestations for these voters (send transaction to confirm)
+
+> It can take 10 minutes for the voters to be seen in the UI
+
+[<img width="100%" src="https://cdn.loom.com/sessions/thumbnails/5ee5b309c2334370925a95615ed8bac5-with-play.gif" width="50%">](https://www.loom.com/embed/5ee5b309c2334370925a95615ed8bac5)
+
+You could also give attestation on the [easscan](https://easscan.org/) page.
+
+## Semaphore
+
+As long as you belong to a specific semaphore group can register.
+
+## Hats
+
+Those who are wearing hat with certain id could register.
diff --git a/docs/04_voting.md b/docs/04_voting.md
@@ -2,13 +2,12 @@
 
 Once applications have been approved and the voters' addresses have been added, your voters can now signup and then vote for projects.
 
-- Navigate to https://easy-retro-pgf.vercel.app/projects
-- Click Signup button and wait for transaction confirmation
-- After signup, click the plus icon on the project card or Add to ballot button in the project details page
-- Click View ballot to navigate to the ballot page (https://easy-retro-pgf.vercel.app/ballot)
+- Navigate to https://maci-platform.vercel.app/signup
+- Click `Join` button to signup and wait for transaction confirmation
+- After signing up, you could navigate to https://maci-platform.vercel.app/projects and click the `Add` button on the project card or add your vote amount in the project details page (https://maci-platform.vercel.app/projects/:projectId)
+- Click `Ballot` on the navbar to navigate to the ballot page (https://maci-platform.vercel.app/ballot)
 - Adjust the allocation
-- Click Submit ballot and send the transaction
-
-You can also export your ballot as a CSV to import into Excel where you can make changes and later export as a CSV. This CSV file can then be imported and replace your ballot.
+- Click `Submit` and send the transaction
+- If you wanna change your mind on the allocation, just modify them and re-send the transaction
 
 As a coordinator, you need to tally the poll results and publish them using CDN (see `NEXT_PUBLIC_TALLY_URL` env variable). See [maci docs](https://maci.pse.dev/docs/integrating#poll-finalization) for more information.
diff --git a/docs/05_results.md b/docs/05_results.md
@@ -2,12 +2,12 @@
 
 Once the voting has ended you can view the results. There's an env variable `NEXT_PUBLIC_TALLY_URL`. As a coordinator you need to upload `tally-{pollId}.json` file. Make sure the poll id in the file name is the same as current one.
 
-- https://easy-retro-pgf.vercel.app/projects/results
+- https://maci-platform.vercel.app/projects/results
 
 ![](./images/voting_ended_sidebar.png)
 
 You can also see statistics of the round:
 
-- https://easy-retro-pgf.vercel.app/stats
+- https://maci-platform.vercel.app/stats
 
 ![](./images/stats.png)
diff --git a/docs/06_maci_troubleshooting.md b/docs/06_maci_troubleshooting.md
@@ -23,7 +23,7 @@ There's no description in detail for signing up reverted by the contract. The fo
 
 If you found it displays "Voting is over", but you actually just started a poll:
 
-- Make sure that you are deploying using **MACI v1.2.4**.
+- Make sure that you are deploying using **MACI v2**.
 
 ## Fail to process message and tally result