@maci-protocol/website 0.0.0-ci.de6bbd5 → 0.0.0-ci.df324d0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/blog/2024-02-28-maci-v1.2.0.md +1 -1
- package/blog/2025-03-21-roadmap-2025.md +1 -1
- package/package.json +2 -2
- package/versioned_docs/version-v1.2/circuits.md +8 -8
- package/versioned_docs/version-v1.2/contributing/contributing.md +4 -4
- package/versioned_docs/version-v1.2/deployment.md +1 -1
- package/versioned_docs/version-v1.2/integrating.md +1 -1
- package/versioned_docs/version-v1.2/key-change.md +1 -1
- package/versioned_docs/version-v1.2/poll-types.md +1 -1
- package/versioned_docs/version-v1.2/testing-in-detail.md +3 -3
- package/versioned_docs/version-v1.2/testing.md +1 -1
- package/versioned_docs/version-v1.2/topup.md +1 -1
- package/versioned_docs/version-v1.2/typedoc/core/index.md +2 -2
- package/versioned_docs/version-v1.2/versioning.md +3 -3
- package/versioned_docs/version-v1.2/workflow.md +1 -1
- package/versioned_docs/version-v2.x/contributing/contributing.md +4 -4
- package/versioned_docs/version-v2.x/core-concepts/key-change.md +1 -1
- package/versioned_docs/version-v2.x/core-concepts/merkle-trees.md +1 -1
- package/versioned_docs/version-v2.x/core-concepts/poll-types.md +1 -1
- package/versioned_docs/version-v2.x/core-concepts/workflow.md +1 -1
- package/versioned_docs/version-v2.x/guides/integrating.md +1 -1
- package/versioned_docs/version-v2.x/guides/testing/testing-in-detail.md +3 -3
- package/versioned_docs/version-v2.x/guides/testing/testing.md +1 -1
- package/versioned_docs/version-v2.x/processes/versioning.md +3 -3
- package/versioned_docs/version-v2.x/supported-networks/deployed-contracts.md +7 -7
- package/versioned_docs/version-v2.x/technical-references/smart-contracts/AccQueue.md +1 -1
- package/versioned_docs/version-v2.x/technical-references/smart-contracts/MACI.md +1 -1
- package/versioned_docs/version-v2.x/technical-references/smart-contracts/MessageProcessor.md +1 -1
- package/versioned_docs/version-v2.x/technical-references/smart-contracts/Params.md +1 -1
- package/versioned_docs/version-v2.x/technical-references/smart-contracts/Poll.md +1 -1
- package/versioned_docs/version-v2.x/technical-references/smart-contracts/PollFactory.md +1 -1
- package/versioned_docs/version-v2.x/technical-references/smart-contracts/Tally.md +1 -1
- package/versioned_docs/version-v2.x/technical-references/smart-contracts/VkRegistry.md +1 -1
- package/versioned_docs/version-v2.x/technical-references/smart-contracts/VoiceCreditProxy.md +1 -1
- package/versioned_docs/version-v2.x/technical-references/zk-snark-circuits/processMessages.md +4 -4
- package/versioned_docs/version-v2.x/technical-references/zk-snark-circuits/tallyVotes.md +2 -2
- package/versioned_docs/version-v2.x/technical-references/zk-snark-circuits/zk-snark-circuits.md +3 -3
- package/versioned_docs/version-v3.x/contributing/contributing.md +4 -4
- package/versioned_docs/version-v3.x/core-concepts/key-change.md +1 -1
- package/versioned_docs/version-v3.x/core-concepts/poll-types.md +1 -1
- package/versioned_docs/version-v3.x/core-concepts/polls.md +1 -1
- package/versioned_docs/version-v3.x/core-concepts/workflow.md +1 -1
- package/versioned_docs/version-v3.x/guides/integrating.md +2 -2
- package/versioned_docs/version-v3.x/guides/sdk.md +1 -1
- package/versioned_docs/version-v3.x/guides/testing/testing-in-detail.md +3 -3
- package/versioned_docs/version-v3.x/guides/testing/testing-introduction.md +1 -1
- package/versioned_docs/version-v3.x/guides/troubleshooting.md +2 -2
- package/versioned_docs/version-v3.x/processes/versioning.md +3 -3
- package/versioned_docs/version-v3.x/security/trusted-setup.md +1 -1
- package/versioned_docs/version-v3.x/supported-networks/deployed-contracts.md +7 -7
- package/versioned_docs/version-v3.x/technical-references/smart-contracts/MACI.md +1 -1
- package/versioned_docs/version-v3.x/technical-references/smart-contracts/MessageProcessor.md +1 -1
- package/versioned_docs/version-v3.x/technical-references/smart-contracts/Params.md +1 -1
- package/versioned_docs/version-v3.x/technical-references/smart-contracts/Policies.md +1 -1
- package/versioned_docs/version-v3.x/technical-references/smart-contracts/Poll.md +1 -1
- package/versioned_docs/version-v3.x/technical-references/smart-contracts/PollFactory.md +1 -1
- package/versioned_docs/version-v3.x/technical-references/smart-contracts/Tally.md +1 -1
- package/versioned_docs/version-v3.x/technical-references/smart-contracts/VkRegistry.md +1 -1
- package/versioned_docs/version-v3.x/technical-references/smart-contracts/VoiceCreditProxy.md +1 -1
- package/versioned_docs/version-v3.x/technical-references/zk-snark-circuits/joinPoll.md +1 -1
- package/versioned_docs/version-v3.x/technical-references/zk-snark-circuits/processMessages.md +5 -5
- package/versioned_docs/version-v3.x/technical-references/zk-snark-circuits/tallyVotes.md +2 -2
- package/versioned_docs/version-v3.x/technical-references/zk-snark-circuits/zk-snark-circuits.md +3 -3
|
@@ -94,7 +94,7 @@ Following the successful completion of our [MACI trusted setup ceremony](https:/
|
|
|
94
94
|
|
|
95
95
|
To accomplish this, we'll leverage the tooling of [P0tion](https://github.com/privacy-scaling-explorations/p0tion), which helps to streamline and automate Groth16 phase2 ceremonies.
|
|
96
96
|
|
|
97
|
-
We'll update this page after the ceremony completes to include the production-ready zkey artifacts. In the meantime, the artifacts for v.1.1.1 can be found on our [website](/docs/security/trusted-setup), and the [`tallyVotes`](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
97
|
+
We'll update this page after the ceremony completes to include the production-ready zkey artifacts. In the meantime, the artifacts for v.1.1.1 can be found on our [website](/docs/security/trusted-setup), and the [`tallyVotes`](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/tallyVotes.circom) artifacts can still be used in production.
|
|
98
98
|
|
|
99
99
|
## Get Involved
|
|
100
100
|
|
|
@@ -26,7 +26,7 @@ We are happy to announce that we completed the work on developing a service to a
|
|
|
26
26
|
|
|
27
27
|
This server exposes a REST API, as well as some Websocket endpoints (for proof generation only). We soon will publish a detailed guide on how to use, and how to integrate it via its SDK -stay tuned for a separate blog post.
|
|
28
28
|
|
|
29
|
-
For anyone interested in the code, you can find it [here](https://github.com/privacy-scaling-explorations/maci/tree/
|
|
29
|
+
For anyone interested in the code, you can find it [here](https://github.com/privacy-scaling-explorations/maci/tree/main/apps/coordinator).
|
|
30
30
|
|
|
31
31
|
### MACI Offchain voting support
|
|
32
32
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@maci-protocol/website",
|
|
3
|
-
"version": "0.0.0-ci.
|
|
3
|
+
"version": "0.0.0-ci.df324d0",
|
|
4
4
|
"private": false,
|
|
5
5
|
"publishConfig": {
|
|
6
6
|
"access": "public"
|
|
@@ -62,5 +62,5 @@
|
|
|
62
62
|
"engines": {
|
|
63
63
|
"node": ">=18.0"
|
|
64
64
|
},
|
|
65
|
-
"gitHead": "
|
|
65
|
+
"gitHead": "ef306008c7607d428a62acf1296d480fd29248e6"
|
|
66
66
|
}
|
|
@@ -11,11 +11,11 @@ MACI uses zk-SNARKs to essentially hide how each person voted while still reveal
|
|
|
11
11
|
|
|
12
12
|
## MACI Circuits
|
|
13
13
|
|
|
14
|
-
MACI has three main zk-SNARK [circuits](https://github.com/privacy-scaling-explorations/maci/tree/
|
|
14
|
+
MACI has three main zk-SNARK [circuits](https://github.com/privacy-scaling-explorations/maci/tree/main/circuits):
|
|
15
15
|
|
|
16
|
-
1. [`ProcessMessages.circom`](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
17
|
-
2. [`TallyVotes.circom`](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
18
|
-
3. [`Subsidy.circom`](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
16
|
+
1. [`ProcessMessages.circom`](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/processMessages.circom), which takes a batch of encrypted messages, decrypts them, and generates a proof that the coordinator's local processing was performed correctly.
|
|
17
|
+
2. [`TallyVotes.circom`](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/tallyVotes.circom), which counts votes from users' ballots, batch by batch.
|
|
18
|
+
3. [`Subsidy.circom`](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/subsidy.circom), which implements [pairwise subsidy](https://hackmd.io/@chaosma/H1_9xmT2K). Please note this is an optional feature.
|
|
19
19
|
|
|
20
20
|
The rest of the circuits are utilities templates that are required for the main circuits to work correctly. These include utilities such as float math, conversion of private keys, and Poseidon hashing/encryption.
|
|
21
21
|
|
|
@@ -45,7 +45,7 @@ The circuits are used by the coordinator (the prover) to prove that they have co
|
|
|
45
45
|
|
|
46
46
|
## How do the circuits work?
|
|
47
47
|
|
|
48
|
-
### Message processing ([`processMessages`](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
48
|
+
### Message processing ([`processMessages`](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/processMessages.circom))
|
|
49
49
|
|
|
50
50
|
This circuit allows the coordinator to prove that they have correctly processed each message in reverse order, in a consecutive batch of 5 ^ msgBatchDepth messages to the respective state leaf within the state tree. Coordinators would use this circuit to prove correct execution at the end of each Poll.
|
|
51
51
|
|
|
@@ -162,7 +162,7 @@ A simplified example using a tree of arity 2:
|
|
|
162
162
|
|
|
163
163
|
To prove that `a...d` are leaves of the tree with root `r`, we prove that the leaves have the subroot `s` with depth 2, and _then_ prove that `s` is a member of `r` at depth 1.
|
|
164
164
|
|
|
165
|
-
The implementation for this is in the `QuinBatchLeavesExists` circuit in `https://github.com/privacy-scaling-explorations/maci/blob/
|
|
165
|
+
The implementation for this is in the `QuinBatchLeavesExists` circuit in `https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/trees/incrementalQuinTree.circom`.
|
|
166
166
|
|
|
167
167
|
This method requires fewer circuit constraints than if we verified a Merkle proof for each leaf.
|
|
168
168
|
|
|
@@ -177,7 +177,7 @@ This method requires fewer circuit constraints than if we verified a Merkle proo
|
|
|
177
177
|
7. That each message in `msgs` exists in the message tree
|
|
178
178
|
8. That after decrypting and applying each message, in reverse order, to the corresponding state and ballot leaves, the new state root, new ballot root, and `newSbSalt` are the preimage to `newSbCommitment`
|
|
179
179
|
|
|
180
|
-
### Tally Votes ([`tallyVotes`](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
180
|
+
### Tally Votes ([`tallyVotes`](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/tallyVotes.circom))
|
|
181
181
|
|
|
182
182
|
#### Parameters
|
|
183
183
|
|
|
@@ -280,7 +280,7 @@ $poseidon_3([tc_r, tc_t, tc_p])$
|
|
|
280
280
|
6. That the tally is valid, which is:
|
|
281
281
|
- That the sum of votes per vote option is correct
|
|
282
282
|
|
|
283
|
-
### Subsisdy ([`subsidy`](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
283
|
+
### Subsisdy ([`subsidy`](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/subsidy.circom))
|
|
284
284
|
|
|
285
285
|
This circuit is an optional feature - it's not required for MACI to function.
|
|
286
286
|
The subsidy circuit is used to implement pairwise subsidy. This is a technique that can be used to detect voters collusion. It currently is not optimized for production and the team will work on a more efficient implementation in the future.
|
|
@@ -37,13 +37,13 @@ Pull requests are great if you want to add a feature or fix a bug. Here's a quic
|
|
|
37
37
|
|
|
38
38
|
7. Make the test pass.
|
|
39
39
|
|
|
40
|
-
8. Commit your changes. Please make sure your forked `
|
|
40
|
+
8. Commit your changes. Please make sure your forked `main` branch is synched as well feature/fix branch and there are no "temp" commits (like wip, fix typo/lint/types and etc). We recommend to squash the feature/fix branch commits before creating PR. You can use this command for it:
|
|
41
41
|
|
|
42
42
|
```bash
|
|
43
|
-
git reset $(git merge-base
|
|
43
|
+
git reset $(git merge-base main $(git rev-parse --abbrev-ref HEAD))
|
|
44
44
|
```
|
|
45
45
|
|
|
46
|
-
9. Push to your fork and submit a pull request on our `
|
|
46
|
+
9. Push to your fork and submit a pull request on our `main` branch. Please provide us with some explanation of why you made the changes you made. For new features make sure to explain a standard use case to us.
|
|
47
47
|
|
|
48
48
|
10. Link any issues that the PR is addressing as described in our processes documentation.
|
|
49
49
|
|
|
@@ -111,7 +111,7 @@ Just as in the subject, use the imperative, present tense: "change" not "changed
|
|
|
111
111
|
|
|
112
112
|
### Branch rules
|
|
113
113
|
|
|
114
|
-
- Branches should generally be created off of the base branch (`
|
|
114
|
+
- Branches should generally be created off of the base branch (`main` )
|
|
115
115
|
- Avoid long descriptive names for long-lived branches
|
|
116
116
|
- Use kebab-case (no CamelCase)
|
|
117
117
|
- Use grouping tokens (words) at the beginning of your branch names (in a similar way to the `type` of commit)
|
|
@@ -112,7 +112,7 @@ For non-quadratic voting polls, you can use the `--use-quadratic-voting false` f
|
|
|
112
112
|
5. 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)
|
|
113
113
|
|
|
114
114
|
:::info
|
|
115
|
-
Should you wish to deploy on a different network, you will need to update the [contracts/tasks/helpers/constants.ts](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
115
|
+
Should you wish to deploy on a different network, you will need to update the [contracts/tasks/helpers/constants.ts](https://github.com/privacy-scaling-explorations/maci/blob/main/contracts/tasks/helpers/constants.ts) file.
|
|
116
116
|
:::
|
|
117
117
|
|
|
118
118
|
6. You will find all of the deployed contracts addresses and configs in the `deployed-contracts.json` file inside the contracts folder.
|
|
@@ -140,7 +140,7 @@ function contribute(
|
|
|
140
140
|
|
|
141
141
|
## InitialVoiceCreditProxy
|
|
142
142
|
|
|
143
|
-
If you'd like to extend the functionality of how votes are distributed among users, you need to extend [InitialVoiceCreditProxy](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
143
|
+
If you'd like to extend the functionality of how votes are distributed among users, you need to extend [InitialVoiceCreditProxy](https://github.com/privacy-scaling-explorations/maci/blob/main/contracts/contracts/initialVoiceCreditProxy/InitialVoiceCreditProxy.sol) contract. You can see our [basic example](https://github.com/privacy-scaling-explorations/maci/blob/main/contracts/contracts/initialVoiceCreditProxy/ConstantInitialVoiceCreditProxy.sol) how it's implemented for constant distribution.
|
|
144
144
|
|
|
145
145
|
```javascript
|
|
146
146
|
// SPDX-License-Identifier: MIT
|
|
@@ -178,5 +178,5 @@ expect(stateLeaf2.pubKey.equals(user2Keypair.pubKey)).to.eq(true);
|
|
|
178
178
|
We see that is important that we set the final message (the one with the new vote) with nonce 1, as this vote would be counted as the first vote.
|
|
179
179
|
|
|
180
180
|
:::info
|
|
181
|
-
Tests related to key changes have been added to the [core package](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
181
|
+
Tests related to key changes have been added to the [core package](https://github.com/privacy-scaling-explorations/maci/blob/main/core/ts/__tests__/) and to the [cli package](https://github.com/privacy-scaling-explorations/maci/blob/main/cli/tests/).
|
|
182
182
|
:::
|
|
@@ -13,7 +13,7 @@ This document will explain how to use each of these options.
|
|
|
13
13
|
|
|
14
14
|
## Quadratic Voting
|
|
15
15
|
|
|
16
|
-
MACI has always worked with quadratic voting. Users signing up to MACI are assigned a number of voice credits based on certain conditions (enforced by the [initial voice credit proxy contract](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
16
|
+
MACI has always worked with quadratic voting. Users signing up to MACI are assigned a number of voice credits based on certain conditions (enforced by the [initial voice credit proxy contract](https://github.com/privacy-scaling-explorations/maci/blob/main/contracts/contracts/initialVoiceCreditProxy/InitialVoiceCreditProxy.sol)), and after each vote, the number of voice credits is reduced by the square of the weight of the vote casted. For instance, if the vote weight is 5, a user must have at least 25 voice credits to cast the vote.
|
|
17
17
|
|
|
18
18
|
To run a poll with quadratic voting, the coordinator must set the `useQuadraticVoting` parameter to `true` when creating the MACI instance. This will make the MACI instance use the `Tally` smart contract, which is the one that has been used since the beginning of MACI.
|
|
19
19
|
|
|
@@ -171,7 +171,7 @@ Within the circuits folder, there are a number of tests that are used to verify
|
|
|
171
171
|
|
|
172
172
|
These tests often use mock data from the `core` package. For instance, when testing the `processMessages` circuit, we are required to generate the parameters from the `core` packing, using the `Poll:processMessages` function. The same applies to vote tallying, where we need the `Poll:tally` function to be run first with mock users and vote messages.
|
|
173
173
|
|
|
174
|
-
All of the tests run using test parameters, usually `10, 2, 1, 2`, aside from the tests inside: [`ceremonyParam`](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
174
|
+
All of the tests run using test parameters, usually `10, 2, 1, 2`, aside from the tests inside: [`ceremonyParam`](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/ts/__tests__/CeremonyParams.test.ts) which use the parameters of the latest MACI ceremony. More details on the trusted setup can be found [here](/docs/v1.2/trusted-setup).
|
|
175
175
|
|
|
176
176
|
### Core
|
|
177
177
|
|
|
@@ -179,7 +179,7 @@ The core package contains a number of tests that are used to verify that the cor
|
|
|
179
179
|
|
|
180
180
|
These tests interact with the crypto and dombinobjs packages, where mock data comes from. Their main goal is to ensure that the core functions work as expected, and that the state is as expected after a series of operations.
|
|
181
181
|
|
|
182
|
-
Currently, there is a blend of e2e and unit tests, where e2e tests are used to verify that the entire MACI local processing works as expected (users signup, publish votes, messages are processed and finally these votes are tallied). Unit tests on the other hand are used to verify that the core functions work as expected, such as `processMessage` and `tallyVotes`. You will find them in separate files, with e2e being [here](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
182
|
+
Currently, there is a blend of e2e and unit tests, where e2e tests are used to verify that the entire MACI local processing works as expected (users signup, publish votes, messages are processed and finally these votes are tallied). Unit tests on the other hand are used to verify that the core functions work as expected, such as `processMessage` and `tallyVotes`. You will find them in separate files, with e2e being [here](https://github.com/privacy-scaling-explorations/maci/blob/main/core/ts/__tests__/e2e.test.ts) and unit tests in the other files.
|
|
183
183
|
|
|
184
184
|
### Domainobjs/Crypto tests
|
|
185
185
|
|
|
@@ -187,7 +187,7 @@ These tests are used to verify that MACI's primitives such as private keys work
|
|
|
187
187
|
|
|
188
188
|
## "Manual" Testing
|
|
189
189
|
|
|
190
|
-
To ensure that the MACI stack works as expected, without having to run the entire test suite (or even just the e2e tests), there is a [bash script](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
190
|
+
To ensure that the MACI stack works as expected, without having to run the entire test suite (or even just the e2e tests), there is a [bash script](https://github.com/privacy-scaling-explorations/maci/blob/main/cli/testScript.sh) inside the cli folder which can be used.
|
|
191
191
|
|
|
192
192
|
This script contains a number of actions which touch all of the parts of MACI, and resemble exactly what other e2e tests do.
|
|
193
193
|
|
|
@@ -87,7 +87,7 @@ circuits.
|
|
|
87
87
|
Note the locations of the `.zkey` files as the CLI requires them as
|
|
88
88
|
command-line flags.
|
|
89
89
|
|
|
90
|
-
For testing purposes you can download the required artifacts using the [`download_zkeys`](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
90
|
+
For testing purposes you can download the required artifacts using the [`download_zkeys`](https://github.com/privacy-scaling-explorations/maci/blob/main/integrationTests/scripts/download_zkeys.sh) script inside the `integrationTests/scripts` folder. The script will place all required artifacts inside the `cli/zkeys` folder.
|
|
91
91
|
You can run the script directly with bash or use pnpm: `pnpm run download:test-zkeys` from the monorepo root.
|
|
92
92
|
|
|
93
93
|
### Compile the circuits and generate zkeys (if decided to generate from scratch)
|
|
@@ -13,7 +13,7 @@ In a nutshell, this feature was added to support some application like quadratic
|
|
|
13
13
|
|
|
14
14
|
## How topup messages are processed
|
|
15
15
|
|
|
16
|
-
Topup messages are submitted on chain using the same smart contract used for voting, [`Poll`](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
16
|
+
Topup messages are submitted on chain using the same smart contract used for voting, [`Poll`](https://github.com/privacy-scaling-explorations/maci/blob/main/contracts/contracts/Poll.sol). With the current design, a TopUpCredit token smart contract is required. In this implementation of MACI, there is an example token, which is an ERC20 contract with 1 decimal, of which the coordinator (or MACI's operator) has ownership of. This privileged figure can mint tokens to users (at their discretion) and users will need to deposit such tokens to the Poll contract in order to topup their voice credits.
|
|
17
17
|
|
|
18
18
|
:::info
|
|
19
19
|
MACI is not concerned with the way of distributing such tokens. The operators of the MACI instance should implement their own way of distributing such tokens, as well as withdrawing them from the Poll contract. For instance, if the operator chooses to use a token with a monetary value, the Poll balance could be withdrawn and sent to fund public goods.
|
|
@@ -18,7 +18,7 @@ contracts in discrete components which are easy to test.
|
|
|
18
18
|
|
|
19
19
|
To this end, this submodule exposes a `MaciState` class and a `Poll` class.
|
|
20
20
|
Developers should instantiate objects from these classes to test MACI. For
|
|
21
|
-
instance, [`MACI.test.ts`](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
21
|
+
instance, [`MACI.test.ts`](https://github.com/privacy-scaling-explorations/maci/blob/main/packages/contracts/tests/MACI.test.ts) creates a
|
|
22
22
|
`MaciState` object and every time it interacts with the MACI smart contract, it
|
|
23
23
|
mirrors said interaction on the `MaciState` and `Poll`. As such, the developer
|
|
24
24
|
can then use their helper functions like `maciState.signUp()`,
|
|
@@ -38,7 +38,7 @@ call `maciState.signUp()` as well, so that the off-chain representation of MACI
|
|
|
38
38
|
is kept up to date.
|
|
39
39
|
|
|
40
40
|
In production, `genMaciStateFromContract()` in
|
|
41
|
-
[`genMaciState.ts`](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
41
|
+
[`genMaciState.ts`](https://github.com/privacy-scaling-explorations/maci/blob/main/contracts/ts/genMaciState.ts) uses this function when it
|
|
42
42
|
scans a MACI contract's event log for signups, so as to bring its `MaciState`
|
|
43
43
|
instance up to date.
|
|
44
44
|
|
|
@@ -19,7 +19,7 @@ MACI follows the [Semantic Versioning Specification (SemVer)](https://semver.org
|
|
|
19
19
|
|
|
20
20
|
All MACI packages are organized in our monorepo and follow a global release approach, meaning that all packages have the same version.
|
|
21
21
|
|
|
22
|
-
Currently, MACI core team manually decides when to release and what the version should be. Packages are released [automatically via CI](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
22
|
+
Currently, MACI core team manually decides when to release and what the version should be. Packages are released [automatically via CI](https://github.com/privacy-scaling-explorations/maci/blob/main/.github/workflows/release.yml) when a new tag is created in GitHub. [You can view our releases and tags in GitHub](https://github.com/privacy-scaling-explorations/maci/releases).
|
|
23
23
|
|
|
24
24
|
## MACI Release Process
|
|
25
25
|
|
|
@@ -37,10 +37,10 @@ Version number '1.2.3' is used here as an example. You should replace the versio
|
|
|
37
37
|
git clone https://github.com/privacy-scaling-explorations/maci
|
|
38
38
|
```
|
|
39
39
|
|
|
40
|
-
3. Switch to the `
|
|
40
|
+
3. Switch to the `main` branch:
|
|
41
41
|
|
|
42
42
|
```
|
|
43
|
-
git checkout
|
|
43
|
+
git checkout main
|
|
44
44
|
```
|
|
45
45
|
|
|
46
46
|
4. Install required dependencies:
|
|
@@ -65,7 +65,7 @@ Therefore, even if a coordinator is corrupt, they are unable to change a user’
|
|
|
65
65
|
|
|
66
66
|
To explain the MACI workflow, let's give a quick overview of the key smart contracts.
|
|
67
67
|
|
|
68
|
-
See our [smart contract docs](/docs/v1.2/contracts) or our [contract source code](https://github.com/privacy-scaling-explorations/maci/tree/
|
|
68
|
+
See our [smart contract docs](/docs/v1.2/contracts) or our [contract source code](https://github.com/privacy-scaling-explorations/maci/tree/main/contracts/contracts) for a more in-depth explanation of all smart contracts.
|
|
69
69
|
|
|
70
70
|
### MACI.sol
|
|
71
71
|
|
|
@@ -57,13 +57,13 @@ Pull requests are great if you want to add a feature or fix a bug. Here's a quic
|
|
|
57
57
|
|
|
58
58
|
7. Make the test pass.
|
|
59
59
|
|
|
60
|
-
8. Commit your changes. Please make sure your forked `
|
|
60
|
+
8. Commit your changes. Please make sure your forked `main` branch is synced as well feature/fix branch and there are no "temp" commits (like wip, fix typo/lint/types and etc). We recommend to squash the feature/fix branch commits before creating PR. You can use this command for it:
|
|
61
61
|
|
|
62
62
|
```bash
|
|
63
|
-
git reset $(git merge-base
|
|
63
|
+
git reset $(git merge-base main $(git rev-parse --abbrev-ref HEAD))
|
|
64
64
|
```
|
|
65
65
|
|
|
66
|
-
9. Push to your fork and submit a pull request on our `
|
|
66
|
+
9. Push to your fork and submit a pull request on our `main` branch. Please provide us with some explanation of why you made the changes you made. For new features make sure to explain a standard use case to us.
|
|
67
67
|
|
|
68
68
|
10. Link any issues that the PR is addressing as described in our processes documentation.
|
|
69
69
|
|
|
@@ -131,7 +131,7 @@ Just as in the subject, use the imperative, present tense: "change" not "changed
|
|
|
131
131
|
|
|
132
132
|
### Branch rules
|
|
133
133
|
|
|
134
|
-
- Branches should generally be created off of the base branch (`
|
|
134
|
+
- Branches should generally be created off of the base branch (`main` )
|
|
135
135
|
- Avoid long descriptive names for long-lived branches
|
|
136
136
|
- Use kebab-case (no CamelCase)
|
|
137
137
|
- Use grouping tokens (words) at the beginning of your branch names (in a similar way to the `type` of commit)
|
|
@@ -175,5 +175,5 @@ expect(stateLeaf2.pubKey.equals(user2Keypair.pubKey)).to.eq(true);
|
|
|
175
175
|
We see that is important that we set the final message (the one with the new vote) with nonce 1, as this vote would be counted as the first vote.
|
|
176
176
|
|
|
177
177
|
:::info
|
|
178
|
-
Tests related to key changes have been added to the [core package](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
178
|
+
Tests related to key changes have been added to the [core package](https://github.com/privacy-scaling-explorations/maci/blob/main/core/ts/__tests__/) and to the [cli package](https://github.com/privacy-scaling-explorations/maci/blob/main/cli/tests/).
|
|
179
179
|
:::
|
|
@@ -5,7 +5,7 @@ sidebar_label: Merkle Trees
|
|
|
5
5
|
sidebar_position: 5
|
|
6
6
|
---
|
|
7
7
|
|
|
8
|
-
MACI uses different types of merkle trees to store and manage data. On chain, a [LazyIMT](https://github.com/privacy-scaling-explorations/zk-kit.solidity/tree/main/packages/lazy-imt) is used to store user's state leaves, and an [AccQueue](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
8
|
+
MACI uses different types of merkle trees to store and manage data. On chain, a [LazyIMT](https://github.com/privacy-scaling-explorations/zk-kit.solidity/tree/main/packages/lazy-imt) is used to store user's state leaves, and an [AccQueue](https://github.com/privacy-scaling-explorations/maci/blob/main/packages/contracts/contracts/trees/AccQueue.sol) to store user's messages.
|
|
9
9
|
|
|
10
10
|
## Accumulator queue
|
|
11
11
|
|
|
@@ -11,7 +11,7 @@ This document will explain how to use each of these options. Hardhat tasks are t
|
|
|
11
11
|
|
|
12
12
|
## Quadratic Voting
|
|
13
13
|
|
|
14
|
-
MACI has always worked with quadratic voting. Users signing up to MACI are assigned a number of voice credits based on certain conditions (enforced by the [initial voice credit proxy contract](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
14
|
+
MACI has always worked with quadratic voting. Users signing up to MACI are assigned a number of voice credits based on certain conditions (enforced by the [initial voice credit proxy contract](https://github.com/privacy-scaling-explorations/maci/blob/main/contracts/contracts/initialVoiceCreditProxy/InitialVoiceCreditProxy.sol)), and after each vote, the number of voice credits is reduced by the square of the weight of the vote casted. For instance, if the vote weight is 5, a user must have at least 25 voice credits to cast the vote.
|
|
15
15
|
|
|
16
16
|
To run a poll with quadratic voting, the coordinator must deploy the Poll with the mode set to quadratic voting.
|
|
17
17
|
|
|
@@ -65,7 +65,7 @@ Therefore, even if a coordinator is corrupt, they are unable to change a user’
|
|
|
65
65
|
|
|
66
66
|
To explain the MACI workflow, let's give a quick overview of the key smart contracts.
|
|
67
67
|
|
|
68
|
-
See our [smart contract docs](/docs/category/smart-contracts) or our [contract source code](https://github.com/privacy-scaling-explorations/maci/tree/
|
|
68
|
+
See our [smart contract docs](/docs/category/smart-contracts) or our [contract source code](https://github.com/privacy-scaling-explorations/maci/tree/main/contracts/contracts) for a more in-depth explanation of all smart contracts.
|
|
69
69
|
|
|
70
70
|
### MACI.sol
|
|
71
71
|
|
|
@@ -41,7 +41,7 @@ function signUp(
|
|
|
41
41
|
|
|
42
42
|
## InitialVoiceCreditProxy
|
|
43
43
|
|
|
44
|
-
If you'd like to extend the functionality of how votes are distributed among users, you need to extend [InitialVoiceCreditProxy](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
44
|
+
If you'd like to extend the functionality of how votes are distributed among users, you need to extend [InitialVoiceCreditProxy](https://github.com/privacy-scaling-explorations/maci/blob/main/contracts/contracts/initialVoiceCreditProxy/InitialVoiceCreditProxy.sol) contract. You can see our [basic example](https://github.com/privacy-scaling-explorations/maci/blob/main/contracts/contracts/initialVoiceCreditProxy/ConstantInitialVoiceCreditProxy.sol) how it's implemented for constant distribution.
|
|
45
45
|
|
|
46
46
|
```ts
|
|
47
47
|
contract ConstantInitialVoiceCreditProxy is InitialVoiceCreditProxy {
|
|
@@ -165,7 +165,7 @@ Within the circuits folder, there are a number of tests that are used to verify
|
|
|
165
165
|
|
|
166
166
|
These tests often use mock data from the `core` package. For instance, when testing the `processMessages` circuit, we are required to generate the parameters from the `core` packing, using the `Poll:processMessages` function. The same applies to vote tallying, where we need the `Poll:tally` function to be run first with mock users and vote messages.
|
|
167
167
|
|
|
168
|
-
All of the tests run using test parameters, usually `10, 2, 1, 2`, aside from the tests inside: [`ceremonyParam`](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
168
|
+
All of the tests run using test parameters, usually `10, 2, 1, 2`, aside from the tests inside: [`ceremonyParam`](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/ts/__tests__/CeremonyParams.test.ts) which use the parameters of the latest MACI ceremony. More details on the trusted setup can be found [here](/docs/security/trusted-setup).
|
|
169
169
|
|
|
170
170
|
### Core
|
|
171
171
|
|
|
@@ -173,7 +173,7 @@ The core package contains a number of tests that are used to verify that the cor
|
|
|
173
173
|
|
|
174
174
|
These tests interact with the crypto and dombinobjs packages, where mock data comes from. Their main goal is to ensure that the core functions work as expected, and that the state is as expected after a series of operations.
|
|
175
175
|
|
|
176
|
-
Currently, there is a blend of e2e and unit tests, where e2e tests are used to verify that the entire MACI local processing works as expected (users signup, publish votes, messages are processed and finally these votes are tallied). Unit tests on the other hand are used to verify that the core functions work as expected, such as `processMessage` and `tallyVotes`. You will find them in separate files, with e2e being [here](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
176
|
+
Currently, there is a blend of e2e and unit tests, where e2e tests are used to verify that the entire MACI local processing works as expected (users signup, publish votes, messages are processed and finally these votes are tallied). Unit tests on the other hand are used to verify that the core functions work as expected, such as `processMessage` and `tallyVotes`. You will find them in separate files, with e2e being [here](https://github.com/privacy-scaling-explorations/maci/blob/main/core/ts/__tests__/e2e.test.ts) and unit tests in the other files.
|
|
177
177
|
|
|
178
178
|
### Domainobjs/Crypto tests
|
|
179
179
|
|
|
@@ -181,7 +181,7 @@ These tests are used to verify that MACI's primitives such as private keys work
|
|
|
181
181
|
|
|
182
182
|
## "Manual" Testing
|
|
183
183
|
|
|
184
|
-
To ensure that the MACI stack works as expected, without having to run the entire test suite (or even just the e2e tests), there is a [bash script](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
184
|
+
To ensure that the MACI stack works as expected, without having to run the entire test suite (or even just the e2e tests), there is a [bash script](https://github.com/privacy-scaling-explorations/maci/blob/main/cli/testScript.sh) inside the cli folder which can be used.
|
|
185
185
|
|
|
186
186
|
This script contains a number of actions which touch all of the parts of MACI, and resemble exactly what other e2e tests do.
|
|
187
187
|
|
|
@@ -87,7 +87,7 @@ circuits.
|
|
|
87
87
|
Note the locations of the `.zkey` files as the CLI requires them as
|
|
88
88
|
command-line flags.
|
|
89
89
|
|
|
90
|
-
For testing purposes you can download the required artifacts using the [`download-zkeys:test`](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
90
|
+
For testing purposes you can download the required artifacts using the [`download-zkeys:test`](https://github.com/privacy-scaling-explorations/maci/blob/main/package.json#L15). The script will place all required artifacts inside the `cli/zkeys` folder.
|
|
91
91
|
|
|
92
92
|
You can run the script directly with bash or use pnpm: `pnpm run download:test-zkeys` from the monorepo root.
|
|
93
93
|
|
|
@@ -19,7 +19,7 @@ MACI follows the [Semantic Versioning Specification (SemVer)](https://semver.org
|
|
|
19
19
|
|
|
20
20
|
All MACI packages are organized in our monorepo and follow a global release approach, meaning that all packages have the same version.
|
|
21
21
|
|
|
22
|
-
Currently, MACI core team manually decides when to release and what the version should be. Packages are released [automatically via CI](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
22
|
+
Currently, MACI core team manually decides when to release and what the version should be. Packages are released [automatically via CI](https://github.com/privacy-scaling-explorations/maci/blob/main/.github/workflows/release.yml) when a new tag is created in GitHub. [You can view our releases and tags in GitHub](https://github.com/privacy-scaling-explorations/maci/releases).
|
|
23
23
|
|
|
24
24
|
## MACI Release Process
|
|
25
25
|
|
|
@@ -37,10 +37,10 @@ Version number '1.2.3' is used here as an example. You should replace the versio
|
|
|
37
37
|
git clone https://github.com/privacy-scaling-explorations/maci
|
|
38
38
|
```
|
|
39
39
|
|
|
40
|
-
3. Switch to the `
|
|
40
|
+
3. Switch to the `main` branch:
|
|
41
41
|
|
|
42
42
|
```
|
|
43
|
-
git checkout
|
|
43
|
+
git checkout main
|
|
44
44
|
```
|
|
45
45
|
|
|
46
46
|
4. Install required dependencies:
|
|
@@ -7,14 +7,14 @@ sidebar_position: 2
|
|
|
7
7
|
|
|
8
8
|
There are a number of MACI's smart contracts which can be re-used by different deployments. These are the following:
|
|
9
9
|
|
|
10
|
-
- [VkRegistry](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
11
|
-
- [PoseidonHashers](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
12
|
-
- [PollFactory](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
13
|
-
- [MessageProcessorFactory](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
14
|
-
- [TallyFactory](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
15
|
-
- [Verifier](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
10
|
+
- [VkRegistry](https://github.com/privacy-scaling-explorations/maci/blob/main/contracts/contracts/VkRegistry.sol)
|
|
11
|
+
- [PoseidonHashers](https://github.com/privacy-scaling-explorations/maci/blob/main/contracts/contracts/crypto/Hasher.sol)
|
|
12
|
+
- [PollFactory](https://github.com/privacy-scaling-explorations/maci/blob/main/contracts/contracts/PollFactory.sol)
|
|
13
|
+
- [MessageProcessorFactory](https://github.com/privacy-scaling-explorations/maci/blob/main/contracts/contracts/MessageProcessorFactory.sol)
|
|
14
|
+
- [TallyFactory](https://github.com/privacy-scaling-explorations/maci/blob/main/contracts/contracts/TallyFactory.sol)
|
|
15
|
+
- [Verifier](https://github.com/privacy-scaling-explorations/maci/blob/main/contracts/contracts/crypto/Verifier.sol)
|
|
16
16
|
- [FreeForAllGatekeeper](https://github.com/privacy-scaling-explorations/maci/blob/v2.5.0/packages/contracts/contracts/gatekeepers/FreeForAllGatekeeper.sol)
|
|
17
|
-
- [ConstantInitialVoiceCreditProxy](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
17
|
+
- [ConstantInitialVoiceCreditProxy](https://github.com/privacy-scaling-explorations/maci/blob/main/contracts/contracts/initialVoiceCreditProxy/ConstantInitialVoiceCreditProxy.sol) - if you are happy to work with a fixed amount of credits
|
|
18
18
|
|
|
19
19
|
VkRegistries can be re-used by different protocols to share the same set of verifying keys. Please be advised that you should be verifying that those verifying keys are the ones that have undergone a trusted setup ceremony.
|
|
20
20
|
|
|
@@ -6,7 +6,7 @@ sidebar_position: 1
|
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
:::info
|
|
9
|
-
Code location: [AccQueue.sol](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
9
|
+
Code location: [AccQueue.sol](https://github.com/privacy-scaling-explorations/maci/blob/main/contracts/contracts/trees/AccQueue.sol)
|
|
10
10
|
:::
|
|
11
11
|
|
|
12
12
|
The AccQueue contract represents a Merkle Tree where each leaf insertion only updates a subtree. To obtain the main tree root, the subtrees must be merged together by the contract owner. This requires at least two operations, a `mergeSubRoots` and a `merge`.
|
|
@@ -6,7 +6,7 @@ sidebar_position: 1
|
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
:::info
|
|
9
|
-
Code location: [MACI.sol](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
9
|
+
Code location: [MACI.sol](https://github.com/privacy-scaling-explorations/maci/blob/main/contracts/contracts/MACI.sol)
|
|
10
10
|
:::
|
|
11
11
|
|
|
12
12
|
`MACI.sol` is the core contract of the project, as it provides the base layer for user signups and Polls to be created.
|
package/versioned_docs/version-v2.x/technical-references/smart-contracts/MessageProcessor.md
CHANGED
|
@@ -6,7 +6,7 @@ sidebar_position: 4
|
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
:::info
|
|
9
|
-
Code location: [MessageProcessor.sol](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
9
|
+
Code location: [MessageProcessor.sol](https://github.com/privacy-scaling-explorations/maci/blob/main/contracts/contracts/MessageProcessor.sol)
|
|
10
10
|
:::
|
|
11
11
|
|
|
12
12
|
This contract is used to prepare parameters for the zk-SNARK circuits as well as for verifying proofs. It should be deployed alongside a `Poll` and ownership assigned to the coordinator.
|
|
@@ -6,7 +6,7 @@ sidebar_position: 9
|
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
:::info
|
|
9
|
-
Code location: [Params.sol](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
9
|
+
Code location: [Params.sol](https://github.com/privacy-scaling-explorations/maci/blob/main/contracts/contracts/utils/Params.sol)
|
|
10
10
|
:::
|
|
11
11
|
|
|
12
12
|
A contract holding three structs:
|
|
@@ -6,7 +6,7 @@ sidebar_position: 2
|
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
:::info
|
|
9
|
-
Code location: [Poll.sol](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
9
|
+
Code location: [Poll.sol](https://github.com/privacy-scaling-explorations/maci/blob/main/contracts/contracts/Poll.sol)
|
|
10
10
|
:::
|
|
11
11
|
|
|
12
12
|
This contract allows users to submit their votes.
|
|
@@ -6,7 +6,7 @@ sidebar_position: 3
|
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
:::info
|
|
9
|
-
Code location: [PollFactory.sol](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
9
|
+
Code location: [PollFactory.sol](https://github.com/privacy-scaling-explorations/maci/blob/main/contracts/contracts/PollFactory.sol)
|
|
10
10
|
:::
|
|
11
11
|
|
|
12
12
|
`PollFactory` is a smart contract that is used to deploy new Polls. This is used by MACI inside the `deployPoll` function.
|
|
@@ -6,7 +6,7 @@ sidebar_position: 5
|
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
:::info
|
|
9
|
-
Code location: [Tally.sol](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
9
|
+
Code location: [Tally.sol](https://github.com/privacy-scaling-explorations/maci/blob/main/contracts/contracts/Tally.sol)
|
|
10
10
|
:::
|
|
11
11
|
|
|
12
12
|
The `Tally` contract is used by the coordinator to submit commitments to the tally results via the `tallyVotes` function. This is done in batches and the final commitment can be used by the users to verify the validity of the results.
|
|
@@ -6,7 +6,7 @@ sidebar_position: 8
|
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
:::info
|
|
9
|
-
Code location: [VkRegistry.sol](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
9
|
+
Code location: [VkRegistry.sol](https://github.com/privacy-scaling-explorations/maci/blob/main/contracts/contracts/VkRegistry.sol)
|
|
10
10
|
:::
|
|
11
11
|
|
|
12
12
|
The VkRegistry is a contract that holds the verifying keys for the zk-SNARK circuits. It holds two different sets of keys:
|
package/versioned_docs/version-v2.x/technical-references/smart-contracts/VoiceCreditProxy.md
CHANGED
|
@@ -6,7 +6,7 @@ sidebar_position: 7
|
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
:::info
|
|
9
|
-
Code location: [InitialVoiceCreditProxy](https://github.com/privacy-scaling-explorations/maci/tree/
|
|
9
|
+
Code location: [InitialVoiceCreditProxy](https://github.com/privacy-scaling-explorations/maci/tree/main/contracts/contracts/initialVoiceCreditProxy)
|
|
10
10
|
:::
|
|
11
11
|
|
|
12
12
|
The VoiceCreditProxy contract is used to assign voice credits to users. Whichever implementation should the MACI deployers use, this must implement a view function that returns the balance for a user, such as the one below:
|
package/versioned_docs/version-v2.x/technical-references/zk-snark-circuits/processMessages.md
CHANGED
|
@@ -5,11 +5,11 @@ sidebar_label: Process Messages Circuit
|
|
|
5
5
|
sidebar_position: 3
|
|
6
6
|
---
|
|
7
7
|
|
|
8
|
-
[**Repo link**](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
8
|
+
[**Repo link**](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/core)
|
|
9
9
|
|
|
10
10
|
This circuit allows the coordinator to prove that they have correctly processed each message in reverse order, in a consecutive batch of 5 ^ msgBatchDepth messages to the respective state leaf within the state tree. Coordinators would use this circuit to prove correct execution at the end of each Poll.
|
|
11
11
|
|
|
12
|
-
The [`processMessages`](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
12
|
+
The [`processMessages`](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/core/qv/processMessages.circom) circuit will try to decrypt the messages, and based on the content of the message, update within itself the trees, to generate a proof that the coordinator's off-chain processing was done correctly. In other words, the circuit takes a final state, an initial state, and the leaves (messages and user signups) - it processes these messages via the different state transitions to finally check that the expected state is correct.
|
|
13
13
|
The pre-requisites for this circuit are:
|
|
14
14
|
|
|
15
15
|
- the related Poll has ended
|
|
@@ -21,7 +21,7 @@ This circuit requires the coordinator's private key, hence a proof for this circ
|
|
|
21
21
|

|
|
22
22
|
|
|
23
23
|
:::info
|
|
24
|
-
A version working with non quadratic voting (non-qv) is also [available](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
24
|
+
A version working with non quadratic voting (non-qv) is also [available](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/core/non-qv/processMessages.circom). This version is called `processMessagesNonQV` and is to be used when the Poll is not using the quadratic voting feature. Note that by default MACI works with quadratic voting.
|
|
25
25
|
:::
|
|
26
26
|
|
|
27
27
|
#### Parameters
|
|
@@ -93,7 +93,7 @@ A simplified example using a tree of arity 2:
|
|
|
93
93
|
|
|
94
94
|
To prove that `a...d` are leaves of the tree with root `r`, we prove that the leaves have the subroot `s` with depth 2, and _then_ prove that `s` is a member of `r` at depth 1.
|
|
95
95
|
|
|
96
|
-
The implementation for this is in the `QuinBatchLeavesExists` circuit in `https://github.com/privacy-scaling-explorations/maci/blob/
|
|
96
|
+
The implementation for this is in the `QuinBatchLeavesExists` circuit in `https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/trees/incrementalQuinTree.circom`.
|
|
97
97
|
|
|
98
98
|
This method requires fewer circuit constraints than if we verified a Merkle proof for each leaf.
|
|
99
99
|
|
|
@@ -5,7 +5,7 @@ sidebar_label: Tally Votes Circuit
|
|
|
5
5
|
sidebar_position: 4
|
|
6
6
|
---
|
|
7
7
|
|
|
8
|
-
[**Repo link**](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
8
|
+
[**Repo link**](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/core)
|
|
9
9
|
|
|
10
10
|
#### Parameters
|
|
11
11
|
|
|
@@ -18,7 +18,7 @@ sidebar_position: 4
|
|
|
18
18
|

|
|
19
19
|
|
|
20
20
|
:::info
|
|
21
|
-
A version working with non quadratic voting (non-qv) is also [available](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
21
|
+
A version working with non quadratic voting (non-qv) is also [available](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/core/non-qv/tallyVotes.circom). This version is called `tallyVotesNonQv` and is to be used when the Poll is not using the quadratic voting feature. Note that by default MACI works with quadratic voting.
|
|
22
22
|
:::
|
|
23
23
|
|
|
24
24
|
#### Input signals
|
package/versioned_docs/version-v2.x/technical-references/zk-snark-circuits/zk-snark-circuits.md
CHANGED
|
@@ -5,10 +5,10 @@ sidebar_label: zk-SNARK Circuits
|
|
|
5
5
|
sidebar_position: 1
|
|
6
6
|
---
|
|
7
7
|
|
|
8
|
-
MACI has two main zk-SNARK [circuits](https://github.com/privacy-scaling-explorations/maci/tree/
|
|
8
|
+
MACI has two main zk-SNARK [circuits](https://github.com/privacy-scaling-explorations/maci/tree/main/circuits):
|
|
9
9
|
|
|
10
|
-
1. ProcessMessages.circom, which takes a batch of encrypted messages, decrypts them, and generates a proof that the coordinator's local processing was performed correctly. [QV](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
11
|
-
2. TallyVotes.circom, which counts votes from users' ballots, batch by batch. [QV](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
10
|
+
1. ProcessMessages.circom, which takes a batch of encrypted messages, decrypts them, and generates a proof that the coordinator's local processing was performed correctly. [QV](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/core/qv/processMessages.circom) and [non-QV](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/core/non-qv/processMessages.circom) versions are available.
|
|
11
|
+
2. TallyVotes.circom, which counts votes from users' ballots, batch by batch. [QV](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/core/qv/tallyVotes.circom) and [non-QV](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/core/non-qv/tallyVotes.circom) versions are available.
|
|
12
12
|
|
|
13
13
|
The rest of the circuits are utilities templates that are required for the main circuits to work correctly. These include utilities such as float math, conversion of private keys, and Poseidon hashing/encryption.
|
|
14
14
|
|
|
@@ -57,13 +57,13 @@ Pull requests are great if you want to add a feature or fix a bug. Here's a quic
|
|
|
57
57
|
|
|
58
58
|
7. Make the test pass.
|
|
59
59
|
|
|
60
|
-
8. Commit your changes. Please make sure your forked `
|
|
60
|
+
8. Commit your changes. Please make sure your forked `main` branch is synced as well feature/fix branch and there are no "temp" commits (like wip, fix typo/lint/types and etc). We recommend to squash the feature/fix branch commits before creating PR. You can use this command for it:
|
|
61
61
|
|
|
62
62
|
```bash
|
|
63
|
-
git reset $(git merge-base
|
|
63
|
+
git reset $(git merge-base main $(git rev-parse --abbrev-ref HEAD))
|
|
64
64
|
```
|
|
65
65
|
|
|
66
|
-
9. Push to your fork and submit a pull request on our `
|
|
66
|
+
9. Push to your fork and submit a pull request on our `main` branch. Please provide us with some explanation of why you made the changes you made. For new features make sure to explain a standard use case to us.
|
|
67
67
|
|
|
68
68
|
10. Link any issues that the PR is addressing as described in our processes documentation.
|
|
69
69
|
|
|
@@ -131,7 +131,7 @@ Just as in the subject, use the imperative, present tense: "change" not "changed
|
|
|
131
131
|
|
|
132
132
|
### Branch rules
|
|
133
133
|
|
|
134
|
-
- Branches should generally be created off of the base branch (`
|
|
134
|
+
- Branches should generally be created off of the base branch (`main` )
|
|
135
135
|
- Avoid long descriptive names for long-lived branches
|
|
136
136
|
- Use kebab-case (no CamelCase)
|
|
137
137
|
- Use grouping tokens (words) at the beginning of your branch names (in a similar way to the `type` of commit)
|
|
@@ -175,5 +175,5 @@ expect(stateLeaf2.publicKey.equals(user2Keypair.publicKey)).to.eq(true);
|
|
|
175
175
|
We see that is important that we set the final message (the one with the new vote) with nonce 1, as this vote would be counted as the first vote.
|
|
176
176
|
|
|
177
177
|
:::info
|
|
178
|
-
Tests related to key changes have been added to the [core package](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
178
|
+
Tests related to key changes have been added to the [core package](https://github.com/privacy-scaling-explorations/maci/blob/main/core/ts/__tests__/) and to the [cli package](https://github.com/privacy-scaling-explorations/maci/blob/main/cli/tests/).
|
|
179
179
|
:::
|
|
@@ -11,7 +11,7 @@ This document will explain how to use each of these options. Hardhat tasks are t
|
|
|
11
11
|
|
|
12
12
|
## Quadratic Voting
|
|
13
13
|
|
|
14
|
-
MACI has always worked with quadratic voting. Users signing up to MACI are assigned a number of voice credits based on certain conditions (enforced by the [initial voice credit proxy contract](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
14
|
+
MACI has always worked with quadratic voting. Users signing up to MACI are assigned a number of voice credits based on certain conditions (enforced by the [initial voice credit proxy contract](https://github.com/privacy-scaling-explorations/maci/blob/main/packages/contracts/contracts/initialVoiceCreditProxy/ConstantInitialVoiceCreditProxy.sol)), and after each vote, the number of voice credits is reduced by the square of the weight of the vote casted. For instance, if the vote weight is 5, a user must have at least 25 voice credits to cast the vote.
|
|
15
15
|
|
|
16
16
|
To run a poll with quadratic voting, the coordinator must deploy the Poll with the mode set to quadratic voting.
|
|
17
17
|
|
|
@@ -34,7 +34,7 @@ The full configuration for a poll looks like this:
|
|
|
34
34
|
|
|
35
35
|
## Quadratic Voting
|
|
36
36
|
|
|
37
|
-
MACI has always worked with quadratic voting. Users joining a Poll are assigned a number of voice credits based on certain conditions (enforced by the [initial voice credit proxy contract](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
37
|
+
MACI has always worked with quadratic voting. Users joining a Poll are assigned a number of voice credits based on certain conditions (enforced by the [initial voice credit proxy contract](https://github.com/privacy-scaling-explorations/maci/blob/main/packages/contracts/contracts/initialVoiceCreditProxy/ConstantInitialVoiceCreditProxy.sol)), and after each vote, the number of voice credits is reduced by the square of the weight of the vote casted. For instance, if the vote weight is 5, a user must have at least 25 voice credits to cast the vote.
|
|
38
38
|
|
|
39
39
|
To run a poll with quadratic voting, the coordinator must deploy the Poll with the mode set to quadratic voting.
|
|
40
40
|
|
|
@@ -66,7 +66,7 @@ Therefore, even if a coordinator is corrupt, they are unable to change a user’
|
|
|
66
66
|
|
|
67
67
|
To explain the MACI workflow, let's give a quick overview of the key smart contracts.
|
|
68
68
|
|
|
69
|
-
See our [smart contract docs](/docs/category/smart-contracts) or our [contract source code](https://github.com/privacy-scaling-explorations/maci/tree/
|
|
69
|
+
See our [smart contract docs](/docs/category/smart-contracts) or our [contract source code](https://github.com/privacy-scaling-explorations/maci/tree/main/contracts/contracts) for a more in-depth explanation of all smart contracts.
|
|
70
70
|
|
|
71
71
|
### MACI.sol
|
|
72
72
|
|
|
@@ -43,7 +43,7 @@ function signUp(PublicKey memory _publicKey, bytes memory _signUpPolicyData) pub
|
|
|
43
43
|
|
|
44
44
|
## InitialVoiceCreditProxy
|
|
45
45
|
|
|
46
|
-
If you'd like to extend the functionality of how votes are distributed among users, you'll need to build you own initial voice credit proxy contract by following the [IInitialVoiceCreditProxy interface](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
46
|
+
If you'd like to extend the functionality of how votes are distributed among users, you'll need to build you own initial voice credit proxy contract by following the [IInitialVoiceCreditProxy interface](https://github.com/privacy-scaling-explorations/maci/blob/main/packages/contracts/contracts/interfaces/IInitialVoiceCreditProxy.sol). You can see our [basic example](https://github.com/privacy-scaling-explorations/maci/blob/main/packages/contracts/contracts/initialVoiceCreditProxy/ConstantInitialVoiceCreditProxy.sol) how it's implemented for constant distribution.
|
|
47
47
|
|
|
48
48
|
```ts
|
|
49
49
|
contract ConstantInitialVoiceCreditProxy is InitialVoiceCreditProxy {
|
|
@@ -118,7 +118,7 @@ Given the verification functions being exposed by the Tally contract, quadratic
|
|
|
118
118
|
|
|
119
119
|
## SDK
|
|
120
120
|
|
|
121
|
-
Another important component of MACI is the [SDK](https://github.com/privacy-scaling-explorations/maci/tree/
|
|
121
|
+
Another important component of MACI is the [SDK](https://github.com/privacy-scaling-explorations/maci/tree/main/packages/sdk). This is a TypeScript library that allows you to interact with MACI.
|
|
122
122
|
|
|
123
123
|
You can find the following subdirectories, where functions are organised as follows:
|
|
124
124
|
|
|
@@ -43,7 +43,7 @@ This step is required to register a user to a specific poll for which they want
|
|
|
43
43
|
|
|
44
44
|
Option 1: Use the `joinPoll` function from the `@maci-protocol/sdk/browser` package.
|
|
45
45
|
|
|
46
|
-
1. Download the `pollJoining` zk artifacts using [downloadPollJoiningArtifactsBrowser](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
46
|
+
1. Download the `pollJoining` zk artifacts using [downloadPollJoiningArtifactsBrowser](https://github.com/privacy-scaling-explorations/maci/blob/main/packages/sdk/ts/proof/download.ts#L46)
|
|
47
47
|
|
|
48
48
|
```typescript
|
|
49
49
|
import { downloadPollJoiningArtifactsBrowser } from "@maci-protocol/sdk/browser";
|
|
@@ -154,7 +154,7 @@ Within the circuits folder, there are a number of tests that are used to verify
|
|
|
154
154
|
|
|
155
155
|
These tests often use mock data from the `core` package. For instance, when testing the `processMessages` circuit, we are required to generate the parameters from the `core` packing, using the `Poll:processMessages` function. The same applies to vote tallying, where we need the `Poll:tally` function to be run first with mock users and vote messages.
|
|
156
156
|
|
|
157
|
-
All of the tests run using test parameters, usually `10, 20, 2`, aside from the tests inside: [`ceremonyParam`](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
157
|
+
All of the tests run using test parameters, usually `10, 20, 2`, aside from the tests inside: [`ceremonyParam`](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/ts/__tests__/CeremonyParams.test.ts) which use the parameters of the latest MACI ceremony. More details on the trusted setup can be found [here](/docs/security/trusted-setup).
|
|
158
158
|
|
|
159
159
|
### Core
|
|
160
160
|
|
|
@@ -162,7 +162,7 @@ The core package contains a number of tests that are used to verify that the cor
|
|
|
162
162
|
|
|
163
163
|
These tests interact with the crypto and dombinobjs packages, where mock data comes from. Their main goal is to ensure that the core functions work as expected, and that the state is as expected after a series of operations.
|
|
164
164
|
|
|
165
|
-
Currently, there is a blend of e2e and unit tests, where e2e tests are used to verify that the entire MACI local processing works as expected (users signup, publish votes, messages are processed and finally these votes are tallied). Unit tests on the other hand are used to verify that the core functions work as expected, such as `MessageProcessor` and `VoteTally`. You will find them in separate files, with e2e being [here](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
165
|
+
Currently, there is a blend of e2e and unit tests, where e2e tests are used to verify that the entire MACI local processing works as expected (users signup, publish votes, messages are processed and finally these votes are tallied). Unit tests on the other hand are used to verify that the core functions work as expected, such as `MessageProcessor` and `VoteTally`. You will find them in separate files, with e2e being [here](https://github.com/privacy-scaling-explorations/maci/blob/main/core/ts/__tests__/e2e.test.ts) and unit tests in the other files.
|
|
166
166
|
|
|
167
167
|
### Domainobjs/Crypto tests
|
|
168
168
|
|
|
@@ -170,7 +170,7 @@ These tests are used to verify that MACI's primitives such as private keys work
|
|
|
170
170
|
|
|
171
171
|
## "Manual" Testing
|
|
172
172
|
|
|
173
|
-
To ensure that the MACI stack works as expected, without having to run the entire test suite (or even just the e2e tests), there is a [bash script](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
173
|
+
To ensure that the MACI stack works as expected, without having to run the entire test suite (or even just the e2e tests), there is a [bash script](https://github.com/privacy-scaling-explorations/maci/blob/main/packages/contracts/testScriptLocalhost.sh) inside the contracts folder which can be used.
|
|
174
174
|
|
|
175
175
|
This script contains a number of actions which touch all of the parts of MACI, and resemble exactly what other e2e tests do.
|
|
176
176
|
|
|
@@ -112,7 +112,7 @@ circuits.
|
|
|
112
112
|
|
|
113
113
|
Note the locations of the `.zkey` files as the smart contract tasks require them as part of the JSON configuration file.
|
|
114
114
|
|
|
115
|
-
For testing purposes you can download the required artifacts using the [`download-zkeys:test`](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
115
|
+
For testing purposes you can download the required artifacts using the [`download-zkeys:test`](https://github.com/privacy-scaling-explorations/maci/blob/main/package.json#L15). The script will place all required artifacts inside the `cli/zkeys` folder.
|
|
116
116
|
|
|
117
117
|
You can run the script directly with bash or use pnpm: `pnpm run download:test-zkeys` from the monorepo root.
|
|
118
118
|
|
|
@@ -71,7 +71,7 @@ Error: commitment mismatch
|
|
|
71
71
|
|
|
72
72
|
This is because commitments are generated using random salts, thus will differ at each `generateProofs` run.
|
|
73
73
|
|
|
74
|
-
In [core/Poll.ts](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
74
|
+
In [core/Poll.ts](https://github.com/privacy-scaling-explorations/maci/blob/main/packages/core/ts/Poll.ts):
|
|
75
75
|
|
|
76
76
|
```
|
|
77
77
|
let newSbSalt = genRandomSalt();
|
|
@@ -140,7 +140,7 @@ event MergeMessageAqSubRoots(uint256 indexed _numSrQueueOps);
|
|
|
140
140
|
event MergeMessageAq(uint256 indexed _messageRoot);
|
|
141
141
|
```
|
|
142
142
|
|
|
143
|
-
Please remember to pull the latest MACI repo updates(`git fetch origin && git pull origin
|
|
143
|
+
Please remember to pull the latest MACI repo updates(`git fetch origin && git pull origin main`) and run `pnpm build` in the root of this monorepo.
|
|
144
144
|
|
|
145
145
|
### Verifier contract found the proof invalid
|
|
146
146
|
|
|
@@ -19,7 +19,7 @@ MACI follows the [Semantic Versioning Specification (SemVer)](https://semver.org
|
|
|
19
19
|
|
|
20
20
|
All MACI packages are organized in our monorepo and follow a global release approach, meaning that all packages have the same version.
|
|
21
21
|
|
|
22
|
-
Currently, MACI core team manually decides when to release and what the version should be. Packages are released [automatically via CI](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
22
|
+
Currently, MACI core team manually decides when to release and what the version should be. Packages are released [automatically via CI](https://github.com/privacy-scaling-explorations/maci/blob/main/.github/workflows/release.yml) when a new tag is created in GitHub. [You can view our releases and tags in GitHub](https://github.com/privacy-scaling-explorations/maci/releases).
|
|
23
23
|
|
|
24
24
|
## MACI Release Process
|
|
25
25
|
|
|
@@ -37,10 +37,10 @@ Version number '1.2.3' is used here as an example. You should replace the versio
|
|
|
37
37
|
git clone https://github.com/privacy-scaling-explorations/maci
|
|
38
38
|
```
|
|
39
39
|
|
|
40
|
-
3. Switch to the `
|
|
40
|
+
3. Switch to the `main` branch:
|
|
41
41
|
|
|
42
42
|
```
|
|
43
|
-
git checkout
|
|
43
|
+
git checkout main
|
|
44
44
|
```
|
|
45
45
|
|
|
46
46
|
4. Install required dependencies:
|
|
@@ -17,7 +17,7 @@ to manage a large amount of value, and if their users accept that the risk of
|
|
|
17
17
|
coordinator misbehaviour is insufficient to justify doing the work of a
|
|
18
18
|
trusted setup. After all, MACI's security model presumes a trusted coordinator.
|
|
19
19
|
|
|
20
|
-
The [PSE team](https://pse.
|
|
20
|
+
The [PSE team](https://pse.main/) is making available a trusted set of zKeys for MACI's circuits,
|
|
21
21
|
which are available and accessible on
|
|
22
22
|
[p0tion's website](https://ceremony.pse.dev/).
|
|
23
23
|
For more info on trusted setup ceremonies please refer to p0tion's [docs](https://p0tion.super.site/).
|
|
@@ -7,14 +7,14 @@ sidebar_position: 2
|
|
|
7
7
|
|
|
8
8
|
There are a number of MACI's smart contracts which can be re-used by different deployments. These are the following:
|
|
9
9
|
|
|
10
|
-
- [VerifyingKeysRegistry](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
11
|
-
- [PoseidonHashers](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
12
|
-
- [PollFactory](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
13
|
-
- [MessageProcessorFactory](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
14
|
-
- [TallyFactory](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
15
|
-
- [Verifier](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
10
|
+
- [VerifyingKeysRegistry](https://github.com/privacy-scaling-explorations/maci/blob/main/packages/contracts/contracts/VerifyingKeysRegistry.sol)
|
|
11
|
+
- [PoseidonHashers](https://github.com/privacy-scaling-explorations/maci/blob/main/packages/contracts/contracts/crypto/Hasher.sol)
|
|
12
|
+
- [PollFactory](https://github.com/privacy-scaling-explorations/maci/blob/main/packages/contracts/contracts/PollFactory.sol)
|
|
13
|
+
- [MessageProcessorFactory](https://github.com/privacy-scaling-explorations/maci/blob/main/packages/contracts/contracts/MessageProcessorFactory.sol)
|
|
14
|
+
- [TallyFactory](https://github.com/privacy-scaling-explorations/maci/blob/main/packages/contracts/contracts/TallyFactory.sol)
|
|
15
|
+
- [Verifier](https://github.com/privacy-scaling-explorations/maci/blob/main/packages/contracts/contracts/crypto/Verifier.sol)
|
|
16
16
|
- [FreeForAllPolicy](https://github.com/privacy-scaling-explorations/excubiae/tree/main/packages/contracts/contracts/extensions/freeForAll)
|
|
17
|
-
- [ConstantInitialVoiceCreditProxy](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
17
|
+
- [ConstantInitialVoiceCreditProxy](https://github.com/privacy-scaling-explorations/maci/blob/main/packages/contracts/contracts/initialVoiceCreditProxy/ConstantInitialVoiceCreditProxy.sol) - if you are happy to work with a fixed amount of credits
|
|
18
18
|
|
|
19
19
|
VkRegistries can be re-used by different protocols to share the same set of verifying keys. Please be advised that you should be verifying that those verifying keys are the ones that have undergone a trusted setup ceremony.
|
|
20
20
|
|
|
@@ -6,7 +6,7 @@ sidebar_position: 1
|
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
:::info
|
|
9
|
-
Code location: [MACI.sol](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
9
|
+
Code location: [MACI.sol](https://github.com/privacy-scaling-explorations/maci/blob/main/packages/contracts/contracts/MACI.sol)
|
|
10
10
|
:::
|
|
11
11
|
|
|
12
12
|
`MACI.sol` is the core contract of the project, as it provides the base layer for user signups and Polls to be created.
|
package/versioned_docs/version-v3.x/technical-references/smart-contracts/MessageProcessor.md
CHANGED
|
@@ -6,7 +6,7 @@ sidebar_position: 4
|
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
:::info
|
|
9
|
-
Code location: [MessageProcessor.sol](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
9
|
+
Code location: [MessageProcessor.sol](https://github.com/privacy-scaling-explorations/maci/blob/main/packages/contracts/contracts/MessageProcessor.sol)
|
|
10
10
|
:::
|
|
11
11
|
|
|
12
12
|
This contract is used to prepare parameters for the zk-SNARK circuits as well as for verifying proofs. It should be deployed alongside a `Poll`.
|
|
@@ -6,7 +6,7 @@ sidebar_position: 9
|
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
:::info
|
|
9
|
-
Code location: [Params.sol](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
9
|
+
Code location: [Params.sol](https://github.com/privacy-scaling-explorations/maci/blob/main/packages/contracts/contracts/utilities/Params.sol)
|
|
10
10
|
:::
|
|
11
11
|
|
|
12
12
|
A contract holding three structs:
|
|
@@ -21,7 +21,7 @@ The MACI repository comes with several out-of-the-box options:
|
|
|
21
21
|
- `HatsPolicy` - This allows gatekeeping signups to only users who have a specific [Hat](https://www.hatsprotocol.xyz/).
|
|
22
22
|
- `GitcoinPassportPolicy` - This allows gatekeeping signups to only users who have a specific [Gitcoin Passport](https://passport.gitcoin.co/) score.
|
|
23
23
|
- `ZupassPolicy` - This allows gatekeeping signups only to users who have a valid [Zupass PCD ticket](https://github.com/proofcarryingdata/zupass).
|
|
24
|
-
- `SemaphorePolicy` - This allows gatekeeping signups only to users who can prove they are part of a [Semaphore](https://semaphore.pse.
|
|
24
|
+
- `SemaphorePolicy` - This allows gatekeeping signups only to users who can prove they are part of a [Semaphore](https://semaphore.pse.main/) group.
|
|
25
25
|
|
|
26
26
|
You can find all of the latest policy contracts here:
|
|
27
27
|
https://github.com/privacy-scaling-explorations/excubiae/tree/main/packages/contracts/contracts/extensions
|
|
@@ -6,7 +6,7 @@ sidebar_position: 2
|
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
:::info
|
|
9
|
-
Code location: [Poll.sol](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
9
|
+
Code location: [Poll.sol](https://github.com/privacy-scaling-explorations/maci/blob/main/packages/contracts/contracts/Poll.sol)
|
|
10
10
|
:::
|
|
11
11
|
|
|
12
12
|
This contract allows users to submit their votes.
|
|
@@ -6,7 +6,7 @@ sidebar_position: 3
|
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
:::info
|
|
9
|
-
Code location: [PollFactory.sol](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
9
|
+
Code location: [PollFactory.sol](https://github.com/privacy-scaling-explorations/maci/blob/main/packages/contracts/contracts/PollFactory.sol)
|
|
10
10
|
:::
|
|
11
11
|
|
|
12
12
|
`PollFactory` is a smart contract that is used to deploy new Polls. This is used by MACI inside the `deployPoll` function.
|
|
@@ -6,7 +6,7 @@ sidebar_position: 5
|
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
:::info
|
|
9
|
-
Code location: [Tally.sol](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
9
|
+
Code location: [Tally.sol](https://github.com/privacy-scaling-explorations/maci/blob/main/packages/contracts/contracts/Tally.sol)
|
|
10
10
|
:::
|
|
11
11
|
|
|
12
12
|
The `Tally` contract is used by the coordinator to submit commitments to the tally results via the `tallyVotes` function. This is done in batches and the final commitment can be used by the users to verify the validity of the results.
|
|
@@ -6,7 +6,7 @@ sidebar_position: 8
|
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
:::info
|
|
9
|
-
Code location: [VerifyingKeysRegistry.sol](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
9
|
+
Code location: [VerifyingKeysRegistry.sol](https://github.com/privacy-scaling-explorations/maci/blob/main/packages/contracts/contracts/VerifyingKeysRegistry.sol)
|
|
10
10
|
:::
|
|
11
11
|
|
|
12
12
|
The VerifyingKeysRegistry is a contract that holds the verifying keys for the zk-SNARK circuits. It holds four different sets of keys:
|
package/versioned_docs/version-v3.x/technical-references/smart-contracts/VoiceCreditProxy.md
CHANGED
|
@@ -6,7 +6,7 @@ sidebar_position: 7
|
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
:::info
|
|
9
|
-
Code location: [InitialVoiceCreditProxy](https://github.com/privacy-scaling-explorations/maci/tree/
|
|
9
|
+
Code location: [InitialVoiceCreditProxy](https://github.com/privacy-scaling-explorations/maci/tree/main/contracts/contracts/initialVoiceCreditProxy)
|
|
10
10
|
:::
|
|
11
11
|
|
|
12
12
|
The VoiceCreditProxy contract is used to assign voice credits to users. Whichever implementation should the MACI deployers use, this must implement a view function that returns the balance for a user, such as the one below:
|
|
@@ -5,7 +5,7 @@ sidebar_label: Join Poll Circuit
|
|
|
5
5
|
sidebar_position: 6
|
|
6
6
|
---
|
|
7
7
|
|
|
8
|
-
[**Repo link**](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
8
|
+
[**Repo link**](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/voter)
|
|
9
9
|
|
|
10
10
|
## PollJoining
|
|
11
11
|
|
package/versioned_docs/version-v3.x/technical-references/zk-snark-circuits/processMessages.md
CHANGED
|
@@ -5,11 +5,11 @@ sidebar_label: Process Messages Circuit
|
|
|
5
5
|
sidebar_position: 3
|
|
6
6
|
---
|
|
7
7
|
|
|
8
|
-
[**Repo link**](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
8
|
+
[**Repo link**](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/coordinator)
|
|
9
9
|
|
|
10
10
|
This circuit allows the coordinator to prove that they have correctly processed each message in reverse order, in a consecutive batch of 5 ^ messageBatchDepth messages to the respective state leaf within the state tree. Coordinators would use this circuit to prove correct execution at the end of each Poll.
|
|
11
11
|
|
|
12
|
-
The [`MessageProcessorQv`](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
12
|
+
The [`MessageProcessorQv`](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/coordinator/qv/MessageProcessor.circom) circuit will try to decrypt the messages, and based on the content of the message, update within itself the trees, to generate a proof that the coordinator's off-chain processing was done correctly. In other words, the circuit takes a final state, an initial state, and the leaves (messages and user signups) - it processes these messages via the different state transitions to finally check that the expected state is correct.
|
|
13
13
|
The pre-requisites for this circuit are:
|
|
14
14
|
|
|
15
15
|
- the related Poll has ended
|
|
@@ -81,11 +81,11 @@ flowchart LR
|
|
|
81
81
|
```
|
|
82
82
|
|
|
83
83
|
:::info
|
|
84
|
-
A version working with non quadratic voting (non-qv) is also [available](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
84
|
+
A version working with non quadratic voting (non-qv) is also [available](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/coordinator/non-qv/MessageProcessor.circom). This version is called `MessageProcessorNonQV` and is to be used when the Poll is not using the quadratic voting feature. Note that by default MACI works with quadratic voting.
|
|
85
85
|
:::
|
|
86
86
|
|
|
87
87
|
:::info
|
|
88
|
-
A version working with full credits voting (full) is also [available](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
88
|
+
A version working with full credits voting (full) is also [available](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/coordinator/full/MessageProcessor.circom). This version is called `MessageProcessorFull` and is to be used when the Poll is not using the quadratic or non quadratic voting features. Note that by default MACI works with quadratic voting.
|
|
89
89
|
:::
|
|
90
90
|
|
|
91
91
|
#### Parameters
|
|
@@ -156,7 +156,7 @@ A simplified example using a tree of arity 2:
|
|
|
156
156
|
|
|
157
157
|
To prove that `a...d` are leaves of the tree with root `r`, we prove that the leaves have the subroot `s` with depth 2, and _then_ prove that `s` is a member of `r` at depth 1.
|
|
158
158
|
|
|
159
|
-
The implementation for this is in the `QuinBatchLeavesExists` circuit in `https://github.com/privacy-scaling-explorations/maci/blob/
|
|
159
|
+
The implementation for this is in the `QuinBatchLeavesExists` circuit in `https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/trees/incrementalQuinTree.circom`.
|
|
160
160
|
|
|
161
161
|
This method requires fewer circuit constraints than if we verified a Merkle proof for each leaf.
|
|
162
162
|
|
|
@@ -5,7 +5,7 @@ sidebar_label: Tally Votes Circuit
|
|
|
5
5
|
sidebar_position: 4
|
|
6
6
|
---
|
|
7
7
|
|
|
8
|
-
[**Repo link**](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
8
|
+
[**Repo link**](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/core)
|
|
9
9
|
|
|
10
10
|
#### Parameters
|
|
11
11
|
|
|
@@ -18,7 +18,7 @@ sidebar_position: 4
|
|
|
18
18
|

|
|
19
19
|
|
|
20
20
|
:::info
|
|
21
|
-
A version working with non quadratic and full credits voting (non-qv, full) is also [available](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
21
|
+
A version working with non quadratic and full credits voting (non-qv, full) is also [available](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/coordinator/non-qv/VoteTally.circom). This version is called `tallyVotes` and is to be used when the Poll is not using the quadratic voting feature. Note that by default MACI works with quadratic voting.
|
|
22
22
|
:::
|
|
23
23
|
|
|
24
24
|
#### Input signals
|
package/versioned_docs/version-v3.x/technical-references/zk-snark-circuits/zk-snark-circuits.md
CHANGED
|
@@ -5,10 +5,10 @@ sidebar_label: zk-SNARK Circuits
|
|
|
5
5
|
sidebar_position: 1
|
|
6
6
|
---
|
|
7
7
|
|
|
8
|
-
MACI has three main zk-SNARK [circuits](https://github.com/privacy-scaling-explorations/maci/tree/
|
|
8
|
+
MACI has three main zk-SNARK [circuits](https://github.com/privacy-scaling-explorations/maci/tree/main/packages/circuits):
|
|
9
9
|
|
|
10
|
-
1. ProcessMessages.circom, which takes a batch of encrypted messages, decrypts them, and generates a proof that the coordinator's local processing was performed correctly. [QV](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
11
|
-
2. TallyVotes.circom, which counts votes from users' ballots, batch by batch. [QV](https://github.com/privacy-scaling-explorations/maci/blob/
|
|
10
|
+
1. ProcessMessages.circom, which takes a batch of encrypted messages, decrypts them, and generates a proof that the coordinator's local processing was performed correctly. [QV](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/coordinator/qv/MessageProcessor.circom), [non-QV](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/coordinator/non-qv/MessageProcessor.circom), [Full](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/coordinator/full/MessageProcessor.circom) versions are available.
|
|
11
|
+
2. TallyVotes.circom, which counts votes from users' ballots, batch by batch. [QV](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/coordinator/qv/VoteTally.circom) and [non-QV](https://github.com/privacy-scaling-explorations/maci/blob/main/circuits/circom/coordinator/non-qv/VoteTally.circom) versions are available.
|
|
12
12
|
3. PollJoining.circom, which allows users to prove they know a private key for a public key signed up to the MACI smart contract, and to register to a specific poll.
|
|
13
13
|
|
|
14
14
|
The rest of the circuits are utilities templates that are required for the main circuits to work correctly. These include utilities such as float math, conversion of private keys, and Poseidon hashing/encryption.
|