From 99d1e9174d38192f8b525fd0aeae1f87a72de560 Mon Sep 17 00:00:00 2001 From: yu-zhen Date: Fri, 29 Dec 2023 21:33:12 +0800 Subject: [PATCH 1/2] chore: fix typos and remove redundant introductions --- .../versioned_docs/version-v1.x/circuits.md | 8 +- website/versioned_docs/version-v1.x/cli.md | 16 ++-- .../versioned_docs/version-v1.x/contracts.md | 88 ++++--------------- .../version-v1.x/integrating.md | 2 +- .../versioned_docs/version-v1.x/key-change.md | 2 +- .../versioned_docs/version-v1.x/testing.md | 4 +- 6 files changed, 31 insertions(+), 89 deletions(-) diff --git a/website/versioned_docs/version-v1.x/circuits.md b/website/versioned_docs/version-v1.x/circuits.md index d5e9b00658..0d75d868b6 100644 --- a/website/versioned_docs/version-v1.x/circuits.md +++ b/website/versioned_docs/version-v1.x/circuits.md @@ -229,7 +229,7 @@ The hash is computed using the `sha256` Solidity function and is then subject to | 4th 50 bits | `numSignUps` | | 5th 50 bits | `batchStartIndex` | -`numSignUps`, a value provided by the contract, is the number of users who have signed up. This is one less than the number of leaves inserted in the state tree (since the 0th state leaf is a blank state leaf [2.8.1]). `batchStartIndex` is the ballot tree index at which the batch begins. +`numSignUps`, a value provided by the contract, is the number of users who have signed up. This is one less than the number of leaves inserted in the state tree (since the 0th state leaf is a [blank state leaf](./primitives#state-leaf)). `batchStartIndex` is the ballot tree index at which the batch begins. For instance, if `numSignUps` is 25 and the batch index is `5`, and all other values are 0, the following is the `packedVals` representation in hexadecimal: @@ -241,11 +241,11 @@ The commitment to `stateRoot`, `ballotRoot`, and `sbSalt`: $poseidon_3([stateRoot, ballotRoot, sbSalt])$ -Proving preimage of `sbCommitment` is one out of the several steps required to prove that the votes were tallied correctly. By establishing that the coordinator knows `ballotRoot`, the coordinator can (using other parts of the circuit) prove that that they know the preimage of the ballot leaves in the batch being tallied. +Proving preimage of `sbCommitment` is one out of the several steps required to prove that the votes were tallied correctly. By establishing that the coordinator knows `ballotRoot`, the coordinator can (using other parts of the circuit) prove that they know the preimage of the ballot leaves in the batch being tallied. ##### `currentTallyCommitment` and `newTallyCommitment` -A tally is represented by a _tally commitment_, which is the poseidon_3$ hash of: +A tally is represented by a _tally commitment_, which is the $poseidon_3$ hash of: 1. $tc_r$: a commitment to the votes per option - This is the hash of the Merkle root $r_r$ of the votes and a salt $r_s$, computed as $poseidon_2([r_r, r_s])$ @@ -354,7 +354,7 @@ Utility circuit used to validate a message. This performs several checks: - `stateTreeIndex` is valid - `voteOptionIndex` is valid - `nonce` is valid -- the signatuer is valid +- the signature is valid - the user signed up before poll end timestamp - the user had enough voice credits diff --git a/website/versioned_docs/version-v1.x/cli.md b/website/versioned_docs/version-v1.x/cli.md index 6c6755ae26..e43c11c5ab 100644 --- a/website/versioned_docs/version-v1.x/cli.md +++ b/website/versioned_docs/version-v1.x/cli.md @@ -39,14 +39,14 @@ pnpm run hardhat | `deployPoll` | Deploy a new poll | `-t, --duration `: The poll duration
`-g, --max-messages `: The max messages
`-mv, --max-vote-options `: The max vote options
`-i, --int-state-tree-depth `: The int state tree depth
`-b, --msg-batch-depth `: The message tree sub depth
`-m, --msg-tree-depth `: The message tree depth
`-v, --vote-option-tree-depth `: The vote option tree depth
`-pk, --pubkey `: The coordinator public key
`-x, --maci-address `: The MACI contract address
`-q, --quiet`: Whether to print values to the console | | `setVerifyingKeys` | Set the verifying keys | `-s, --state-tree-depth `: The state tree depth
`-i, --int-state-tree-depth `: The intermediate state tree depth
`-m, --msg-tree-depth `: The message tree depth
`-v, --vote-option-tree-depth `: The vote option tree depth
`-b, --msg-batch-depth `: The message batch depth
`-p, --process-messages-zkey `: The process messages zkey path
`-t, --tally-votes-zkey `: The tally votes zkey path
`-k, --vk-registry `: The vk registry contract address
`-q, --quiet`: Whether to print values to the console
`-ss, --subsidy-zkey `: The subsidy zkey path | | `publish` | Publish a new message to a MACI Poll contract | `-p, --pubkey `: The MACI public key which should replace the user's public key in the state tree
`-x, --contract `: The MACI contract address
`-sk, --privkey `: Your serialized MACI private key
`-i, --state-index `: The user's state index
`-v, --vote-option-index `: The vote option index
`-n, --nonce `: The message nonce
`-s, --salt `: The message salt
`-o, --poll-id `: The poll id
`-w, --new-vote-weight `: The new vote weight
`-q, --quiet`: Whether to print values to the console | -| mergeMessages | Merge the message accumulator queue | `-q, --quiet`: Whether to print values to the console
`-x, --maci-contract-address `: The MACI contract address
`-o, --poll-id `: The poll id
`-n, --num-queue-ops `: The number of queue operations | -| mergeSignups | Merge the signups accumulator queue | `-q, --quiet`: Whether to print values to the console
`-x, --maci-contract-address `: The MACI contract address
`-o, --poll-id `: The poll id
`-n, --num-queue-ops `: The number of queue operations | -| timeTravel | Fast-forward the time (only works for local hardhat testing) | `-s, --seconds `: The number of seconds to fast-forward
`-q, --quiet`: Whether to print values to the console | -| signup | Sign up to a MACI contract | `-p, --pubkey `: The MACI public key
`-x, --maci-address `: The MACI contract address
`-s, --sg-data `: The signup gateway data
`-i, --ivcp-data `: The initial voice credit proxy data
`-q, --quiet`: Whether to print values to the console | -| topup | Top up an account with voice credits | `-a, --amount `: The amount of topup
`-x, --maci-address `: The MACI contract address
`-i, --state-index `: State leaf index
`-o, --poll-id `: Poll id
`-q, --quiet`: Whether to print values to the console | -| fundWallet | Fund a wallet with Ether | `-a, --amount `: The amount of Ether
`-w, --address
`: The address to fund
`-q, --quiet`: Whether to print values to the console | -| verify | Verify the results of a poll and optionally the subsidy results | `-o, --poll-id `: The poll id
`-t, --tally-file `: The tally file
`-s, --subsidy-file `: The subsidy file
`-x, --contract `: The MACI contract address
`-tc, --tally-contract `: The tally contract address
`-sc, --subsidy-contract `: The subsidy contract address
`-q, --quiet`: Whether to print values to the console | -| genProofs | Generate the proofs for a poll | `-sk, --privkey `: Your serialized MACI private key
`-x, --contract `: The MACI contract address
`-o, --poll-id `: The poll id
`-t, --tally-file `: The tally file
`-s, --subsidy-file `: The subsidy file
`-r, --rapidsnark `: The path to the rapidsnark binary
`-wp, --process-witnessgen `: The path to the process witness generation binary
`-wt, --tally-witnessgen `: The path to the tally witness generation binary
`-ws, --subsidy-witnessgen `: The path to the subsidy witness generation binary
`-zp, --process-zkey `-zt, --tally-zkey `: The path to the tally zkey
`-zs, --subsidy-zkey `: The path to the subsidy zkey
`-q, --quiet`: Whether to print values to the console
`-f, --output `: The output directory for proofs
`-tx, --transaction-hash :` Transaction hash of MACI contract creation
`-w, --wasm`: Whether to use the wasm binaries
`-pw, --process-wasm `: The path to the process witness generation wasm binary
`-tw, --tally-wasm `: The path to the tally witness generation wasm binary
`-sw, --subsidy-wasm `: The path to the subsidy witness generation wasm binary | +| `mergeMessages` | Merge the message accumulator queue | `-q, --quiet`: Whether to print values to the console
`-x, --maci-contract-address `: The MACI contract address
`-o, --poll-id `: The poll id
`-n, --num-queue-ops `: The number of queue operations | +| `mergeSignups` | Merge the signups accumulator queue | `-q, --quiet`: Whether to print values to the console
`-x, --maci-contract-address `: The MACI contract address
`-o, --poll-id `: The poll id
`-n, --num-queue-ops `: The number of queue operations | +| `timeTravel` | Fast-forward the time (only works for local hardhat testing) | `-s, --seconds `: The number of seconds to fast-forward
`-q, --quiet`: Whether to print values to the console | +| `signup` | Sign up to a MACI contract | `-p, --pubkey `: The MACI public key
`-x, --maci-address `: The MACI contract address
`-s, --sg-data `: The signup gateway data
`-i, --ivcp-data `: The initial voice credit proxy data
`-q, --quiet`: Whether to print values to the console | +| `topup` | Top up an account with voice credits | `-a, --amount `: The amount of topup
`-x, --maci-address `: The MACI contract address
`-i, --state-index `: State leaf index
`-o, --poll-id `: Poll id
`-q, --quiet`: Whether to print values to the console | +| `fundWallet` | Fund a wallet with Ether | `-a, --amount `: The amount of Ether
`-w, --address
`: The address to fund
`-q, --quiet`: Whether to print values to the console | +| `verify` | Verify the results of a poll and optionally the subsidy results | `-o, --poll-id `: The poll id
`-t, --tally-file `: The tally file
`-s, --subsidy-file `: The subsidy file
`-x, --contract `: The MACI contract address
`-tc, --tally-contract `: The tally contract address
`-sc, --subsidy-contract `: The subsidy contract address
`-q, --quiet`: Whether to print values to the console | +| `genProofs` | Generate the proofs for a poll | `-sk, --privkey `: Your serialized MACI private key
`-x, --contract `: The MACI contract address
`-o, --poll-id `: The poll id
`-t, --tally-file `: The tally file
`-s, --subsidy-file `: The subsidy file
`-r, --rapidsnark `: The path to the rapidsnark binary
`-wp, --process-witnessgen `: The path to the process witness generation binary
`-wt, --tally-witnessgen `: The path to the tally witness generation binary
`-ws, --subsidy-witnessgen `: The path to the subsidy witness generation binary
`-zp, --process-zkey `-zt, --tally-zkey `: The path to the tally zkey
`-zs, --subsidy-zkey `: The path to the subsidy zkey
`-q, --quiet`: Whether to print values to the console
`-f, --output `: The output directory for proofs
`-tx, --transaction-hash :` Transaction hash of MACI contract creation
`-w, --wasm`: Whether to use the wasm binaries
`-pw, --process-wasm `: The path to the process witness generation wasm binary
`-tw, --tally-wasm `: The path to the tally witness generation wasm binary
`-sw, --subsidy-wasm `: The path to the subsidy witness generation wasm binary | | proveOnChain | Prove the results of a poll on chain | `-o, --poll-id `: The poll id
`-q, --quiet`: Whether to print values to the console
`-x, --contract `: The MACI contract address
`-p, --message-processor-address `: The message processor contract address
`-t, --tally-contract `: The tally contract address
`-s, --subsidy-contract `: The subsidy contract address
`-f, --proof-dir `: The proof output directory from the genProofs subcommand | ## Public and private key format diff --git a/website/versioned_docs/version-v1.x/contracts.md b/website/versioned_docs/version-v1.x/contracts.md index cc2d48a411..1a16ef897e 100644 --- a/website/versioned_docs/version-v1.x/contracts.md +++ b/website/versioned_docs/version-v1.x/contracts.md @@ -21,15 +21,19 @@ The constructor shown below accepts three arguments, a `PollFactory` contract, a constructor( PollFactory _pollFactory, SignUpGatekeeper _signUpGatekeeper, - InitialVoiceCreditProxy _initialVoiceCreditProxy + InitialVoiceCreditProxy _initialVoiceCreditProxy, + TopupCredit _topupCredit, + uint8 _stateTreeDepth ) { // Deploy the state AccQueue stateAq = new AccQueueQuinaryBlankSl(STATE_TREE_SUBDEPTH); stateAq.enqueue(BLANK_STATE_LEAF_HASH); pollFactory = _pollFactory; + topupCredit = _topupCredit; signUpGatekeeper = _signUpGatekeeper; initialVoiceCreditProxy = _initialVoiceCreditProxy; + stateTreeDepth = _stateTreeDepth; // Verify linked poseidon libraries require( @@ -45,63 +49,6 @@ Should this be changed, it will be necessary to amend the `contracts/ts/genEmpty After this, the contracts will be stored to state, the current time taken and then the contract will perform a simple sanity check to ensure that the Poseidon hash libraries were linked successfully. -Once the contract is deployed, the owner (set as the deployer address of MACI), is required to call the `init` function, which is shown below: - -```javascript -function init( - VkRegistry _vkRegistry, - MessageAqFactory _messageAqFactory, - TopupCredit _topupCredit - ) public onlyOwner { - require(!isInitialised, "MACI: already initialised"); - - isInitialised = true; - - vkRegistry = _vkRegistry; - messageAqFactory = _messageAqFactory; - topupCredit = _topupCredit; - - // Check that the factory contracts have correct access controls before - // allowing any functions in MACI to run (via the afterInit modifier) - require( - pollFactory.owner() == address(this), - "MACI: PollFactory owner incorrectly set" - ); - - // The PollFactory needs to store the MessageAqFactory address - pollFactory.setMessageAqFactory(messageAqFactory); - - // The MessageAQFactory owner must be the PollFactory contract - require( - messageAqFactory.owner() == address(pollFactory), - "MACI: MessageAqFactory owner incorrectly set" - ); - - // The VkRegistry owner must be the owner of this contract - require( - vkRegistry.owner() == owner(), - "MACI: VkRegistry owner incorrectly set" - ); - - emit Init(_vkRegistry, _messageAqFactory); -} -``` - -This function accepts three arguments: - -- `VkRegistry` - the contract holding the verifying keys -- `MessageAqFactory` - the factory contract for deploying new MessageAq contracts -- `TopupCredit` - the contract responsible for topping up voting credits - -In more details, the `init` function will check/do the following: - -1. That the `PollFactory` contract's owner has been set to be the `MACI` contract -2. Set the `messageAqFactory` contract on the `pollFactory` contract -3. Check that the owner of the `messageAqFactory` is the `pollFactory` contract -4. Confirm that the `vkRegistry` owner is the same as the `MACI` owner - -Finally, it will emit an event. - Next, we have the `signUp` function, which allows users to `signUp` using a `SignUpGatekeeper` contract. This contract can use any mean necessary to gatekeep access to MACI's polls. For instance, only wallets with access to a specific ERC721 token can be allowed to sign up. Please note that this function can only be called after the contract is initialized (thanks to the `afterInit` modifier). This function does the following: @@ -163,7 +110,7 @@ function deployPoll( MaxValues memory _maxValues, TreeDepths memory _treeDepths, PubKey memory _coordinatorPubKey -) public afterInit { +) public onlyOwner returns (address pollAddr) { uint256 pollId = nextPollId; // Increment the poll ID for the next poll @@ -291,8 +238,7 @@ In order for the `processMessages` circuit to access the message root, the follo `PollFactory` is a smart contract that is used to deploy new Polls. This is used by MACI inside the `deployPoll` function. It only contains two functions: -- `setMessageAqFactory` - owner only function which allows to set the address of the `MessageAqFactory` (a contract used to deploy new AccQueue contracts) -- `deploy` - owner only function which allows to deploy a new Poll +- `deploy` - owner only function which allows to deploy a new Poll, also deploys a messageAq The arguments required to deploy a new Poll are the following: @@ -310,23 +256,19 @@ address _pollOwner Upon deployment, the ownership of the messageAq contract will be transferred to the deployed poll, as well as the ownership of the new Poll contract be transferred to the poll owner, which in MACI is set as the owner of MACI. -## PollProcessorAndTallyer +## MessageProcessor This contract is used to prepare parameters for the zk-SNARK circuits as well as for verifying proofs. It should be deployed alongside MACI and ownership assigned to the coordinator. +It will process message by batch due to large size of messages. +After it finishes processing, the sbCommitment will be used for Tally and Subsidy contracts. -## MessageAqFactory +## Tally -This is a simple factory contract which allows to deploy new `AccQueueQuinaryMaci` contracts. It exposes one function, `deploy`, which can only be called by the contract owner. After deployment of the contract, it will transfer its ownership to the same owner as the factory contract. +The Tally contract is used during votes tallying and by users to verify the tally results. -```javascript -contract MessageAqFactory is Ownable { - function deploy(uint256 _subDepth) public onlyOwner returns (AccQueue) { - AccQueue aq = new AccQueueQuinaryMaci(_subDepth); - aq.transferOwnership(owner()); - return aq; - } -} -``` +## Subsidy + +This contract is used to verify that the subsidy calculations are correct. It is also used to update the subsidy commitment if the proof is valid. ## SignUpToken diff --git a/website/versioned_docs/version-v1.x/integrating.md b/website/versioned_docs/version-v1.x/integrating.md index eb67fbe989..4f6d4f05d7 100644 --- a/website/versioned_docs/version-v1.x/integrating.md +++ b/website/versioned_docs/version-v1.x/integrating.md @@ -13,7 +13,7 @@ Here we will be looking at QFI and how it was used. Please note that this will b ## MACI Contract -The MACI contract is the core of the protocol. Contracts can inherit from MACI and thus expose the signup and topup functions. As with standalone MACI, one would need to deploy a sign up gatekeeper as well as the voice credit proxy. +The MACI contract is the core of the protocol. Contracts can inherit from MACI and thus expose the signup and topup functions. As with standalone MACI, one would need to deploy a [sign up gatekeeper](./contracts#signupgatekeeper) as well as the [voice credit proxy](./contracts#voicecreditproxy). As an example, within the quadratic funding infrastructure project, the QFI contract inherits from MACI and allows sign up via the contribute function. diff --git a/website/versioned_docs/version-v1.x/key-change.md b/website/versioned_docs/version-v1.x/key-change.md index 4583baf98c..b5aec91393 100644 --- a/website/versioned_docs/version-v1.x/key-change.md +++ b/website/versioned_docs/version-v1.x/key-change.md @@ -32,7 +32,7 @@ Let's take as an example the following: If messages were processed in the same order as they were submitted, Alice's vote would not be valid, due to it being signed with a private key $priv1$ - which now would not be valid. -On the other hand, due to messages being processed in reverse order, Alice's last message would be counted as valid as the key change would have not been processed yet. Then, Bob's vote would not be counted as valid as the current key for Alice would be $pub2$. +On the other hand, due to messages being processed in reverse order, Alice's last message would be counted as valid as the key change would have not been processed yet. Then, Bob's vote would not be counted as valid as the current key for Alice would be $pub1$. > Note that a key change message should have the nonce set to 1 in order for it to be valid. We'll see it a code example in the next sections. diff --git a/website/versioned_docs/version-v1.x/testing.md b/website/versioned_docs/version-v1.x/testing.md index e39e06830b..c555ce95b4 100644 --- a/website/versioned_docs/version-v1.x/testing.md +++ b/website/versioned_docs/version-v1.x/testing.md @@ -180,9 +180,9 @@ You can run them with: pnpm run test ``` -## Pre-Compiled Artifacts for testing +### Pre-Compiled Artifacts for testing -The followingcompiled circuits and zkeys are available to download: +The following compiled circuits and zkeys are available to download: - [Prod](#prod-size) (`7-9-3-4`) - [Micro](#micro-size) (`10-2-1-2`) From d33e7e6bc833907bec1d5575ec4f46656011028c Mon Sep 17 00:00:00 2001 From: yu-zhen Date: Sun, 31 Dec 2023 00:23:46 +0800 Subject: [PATCH 2/2] chore: update docs --- contracts/contracts/MACI.sol | 1 + website/versioned_docs/version-v1.x/contracts.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/contracts/contracts/MACI.sol b/contracts/contracts/MACI.sol index f49593a759..73e7f8393a 100644 --- a/contracts/contracts/MACI.sol +++ b/contracts/contracts/MACI.sol @@ -104,6 +104,7 @@ contract MACI is IMACI, Params, Utilities, Ownable { /// @param _subsidyFactory The SubsidyFactory contract /// @param _signUpGatekeeper The SignUpGatekeeper contract /// @param _initialVoiceCreditProxy The InitialVoiceCreditProxy contract + /// @param _topupCredit The TopupCredit contract /// @param _stateTreeDepth The depth of the state tree constructor( IPollFactory _pollFactory, diff --git a/website/versioned_docs/version-v1.x/contracts.md b/website/versioned_docs/version-v1.x/contracts.md index 1a16ef897e..365475abd0 100644 --- a/website/versioned_docs/version-v1.x/contracts.md +++ b/website/versioned_docs/version-v1.x/contracts.md @@ -259,7 +259,7 @@ Upon deployment, the ownership of the messageAq contract will be transferred to ## MessageProcessor This contract is used to prepare parameters for the zk-SNARK circuits as well as for verifying proofs. It should be deployed alongside MACI and ownership assigned to the coordinator. -It will process message by batch due to large size of messages. +It will process messages in batches, to increase performance and stay within the block gas limit. After it finishes processing, the sbCommitment will be used for Tally and Subsidy contracts. ## Tally