diff --git a/README.md b/README.md index f47234d6..df81db6a 100644 --- 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 index df1ad3f2..9df6b08a 100644 --- 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 index 9a826406..daad7708 100644 --- 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 deleted file mode 100644 index d5f25de9..00000000 --- a/docs/03_creating_badgeholders.md +++ /dev/null @@ -1,10 +0,0 @@ -# Creating badgeholders - -- Navigate to https://easy-retro-pgf.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 - -[](https://www.loom.com/embed/5ee5b309c2334370925a95615ed8bac5) diff --git a/docs/03_register.md b/docs/03_register.md new file mode 100644 index 00000000..ed21a95b --- /dev/null +++ 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 + +[](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 index 8afdd022..ac80dc88 100644 --- 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 index 81bab2c9..594400ce 100644 --- 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 index de45c89a..5f8b749b 100644 --- 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