@maci-protocol/website 0.0.0-ci.2653bc0

package/versioned_docs/version-v1.2/solidity-docs/MACI.md

@@ -0,0 +1,345 @@
+# MACI
+
+A contract which allows users to sign up, and deploy new polls
+
+### stateTreeDepth
+
+```solidity
+uint8 stateTreeDepth
+```
+
+The state tree depth is fixed. As such it should be as large as feasible
+so that there can be as many users as possible. i.e. 5 \*\* 10 = 9765625
+this should also match the parameter of the circom circuits.
+
+### STATE_TREE_SUBDEPTH
+
+```solidity
+uint8 STATE_TREE_SUBDEPTH
+```
+
+IMPORTANT: remember to change the ballot tree depth
+in contracts/ts/genEmptyBallotRootsContract.ts file
+if we change the state tree depth!
+
+### TREE_ARITY
+
+```solidity
+uint8 TREE_ARITY
+```
+
+### BLANK_STATE_LEAF_HASH
+
+```solidity
+uint256 BLANK_STATE_LEAF_HASH
+```
+
+The hash of a blank state leaf
+
+### nextPollId
+
+```solidity
+uint256 nextPollId
+```
+
+Each poll has an incrementing ID
+
+### polls
+
+```solidity
+mapping(uint256 => address) polls
+```
+
+A mapping of poll IDs to Poll contracts.
+
+### subtreesMerged
+
+```solidity
+bool subtreesMerged
+```
+
+Whether the subtrees have been merged (can merge root before new signup)
+
+### numSignUps
+
+```solidity
+uint256 numSignUps
+```
+
+The number of signups
+
+### topupCredit
+
+```solidity
+contract TopupCredit topupCredit
+```
+
+ERC20 contract that hold topup credits
+
+### pollFactory
+
+```solidity
+contract IPollFactory pollFactory
+```
+
+Factory contract that deploy a Poll contract
+
+### messageProcessorFactory
+
+```solidity
+contract IMessageProcessorFactory messageProcessorFactory
+```
+
+Factory contract that deploy a MessageProcessor contract
+
+### tallyFactory
+
+```solidity
+contract ITallySubsidyFactory tallyFactory
+```
+
+Factory contract that deploy a Tally contract
+
+### subsidyFactory
+
+```solidity
+contract ITallySubsidyFactory subsidyFactory
+```
+
+Factory contract that deploy a Subsidy contract
+
+### stateAq
+
+```solidity
+contract AccQueue stateAq
+```
+
+The state AccQueue. Represents a mapping between each user's public key
+and their voice credit balance.
+
+### signUpGatekeeper
+
+```solidity
+contract SignUpGatekeeper signUpGatekeeper
+```
+
+Address of the SignUpGatekeeper, a contract which determines whether a
+user may sign up to vote
+
+### initialVoiceCreditProxy
+
+```solidity
+contract InitialVoiceCreditProxy initialVoiceCreditProxy
+```
+
+The contract which provides the values of the initial voice credit
+balance per user
+
+### PollContracts
+
+```solidity
+struct PollContracts {
+  address poll;
+  address messageProcessor;
+  address tally;
+  address subsidy;
+}
+```
+
+### SignUp
+
+```solidity
+event SignUp(uint256 _stateIndex, uint256 _userPubKeyX, uint256 _userPubKeyY, uint256 _voiceCreditBalance, uint256 _timestamp)
+```
+
+### DeployPoll
+
+```solidity
+event DeployPoll(uint256 _pollId, uint256 _coordinatorPubKeyX, uint256 _coordinatorPubKeyY, struct MACI.PollContracts pollAddr)
+```
+
+### onlyPoll
+
+```solidity
+modifier onlyPoll(uint256 _pollId)
+```
+
+Only allow a Poll contract to call the modified function.
+
+### CallerMustBePoll
+
+```solidity
+error CallerMustBePoll(address _caller)
+```
+
+custom errors
+
+### PoseidonHashLibrariesNotLinked
+
+```solidity
+error PoseidonHashLibrariesNotLinked()
+```
+
+### TooManySignups
+
+```solidity
+error TooManySignups()
+```
+
+### MaciPubKeyLargerThanSnarkFieldSize
+
+```solidity
+error MaciPubKeyLargerThanSnarkFieldSize()
+```
+
+### PreviousPollNotCompleted
+
+```solidity
+error PreviousPollNotCompleted(uint256 pollId)
+```
+
+### PollDoesNotExist
+
+```solidity
+error PollDoesNotExist(uint256 pollId)
+```
+
+### SignupTemporaryBlocked
+
+```solidity
+error SignupTemporaryBlocked()
+```
+
+### constructor
+
+```solidity
+constructor(contract IPollFactory _pollFactory, contract IMessageProcessorFactory _messageProcessorFactory, contract ITallySubsidyFactory _tallyFactory, contract ITallySubsidyFactory _subsidyFactory, contract SignUpGatekeeper _signUpGatekeeper, contract InitialVoiceCreditProxy _initialVoiceCreditProxy, contract TopupCredit _topupCredit, uint8 _stateTreeDepth) public payable
+```
+
+Create a new instance of the MACI contract.
+
+#### Parameters
+
+| Name                      | Type                              | Description                          |
+| ------------------------- | --------------------------------- | ------------------------------------ |
+| \_pollFactory             | contract IPollFactory             | The PollFactory contract             |
+| \_messageProcessorFactory | contract IMessageProcessorFactory | The MessageProcessorFactory contract |
+| \_tallyFactory            | contract ITallySubsidyFactory     | The TallyFactory contract            |
+| \_subsidyFactory          | contract ITallySubsidyFactory     | The SubsidyFactory contract          |
+| \_signUpGatekeeper        | contract SignUpGatekeeper         | The SignUpGatekeeper contract        |
+| \_initialVoiceCreditProxy | contract InitialVoiceCreditProxy  | The InitialVoiceCreditProxy contract |
+| \_topupCredit             | contract TopupCredit              | The TopupCredit contract             |
+| \_stateTreeDepth          | uint8                             | The depth of the state tree          |
+
+### signUp
+
+```solidity
+function signUp(struct DomainObjs.PubKey _pubKey, bytes _signUpGatekeeperData, bytes _initialVoiceCreditProxyData) public virtual
+```
+
+Allows any eligible user sign up. The sign-up gatekeeper should prevent
+double sign-ups or ineligible users from doing so. This function will
+only succeed if the sign-up deadline has not passed. It also enqueues a
+fresh state leaf into the state AccQueue.
+
+#### Parameters
+
+| Name                          | Type                     | Description                                                                                                                                                                 |
+| ----------------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| \_pubKey                      | struct DomainObjs.PubKey | The user's desired public key.                                                                                                                                              |
+| \_signUpGatekeeperData        | bytes                    | Data to pass to the sign-up gatekeeper's register() function. For instance, the POAPGatekeeper or SignUpTokenGatekeeper requires this value to be the ABI-encoded token ID. |
+| \_initialVoiceCreditProxyData | bytes                    | Data to pass to the InitialVoiceCreditProxy, which allows it to determine how many voice credits this user should have.                                                     |
+
+### deployPoll
+
+```solidity
+function deployPoll(uint256 _duration, struct Params.TreeDepths _treeDepths, struct DomainObjs.PubKey _coordinatorPubKey, address _verifier, address _vkRegistry, bool useSubsidy) public virtual returns (struct MACI.PollContracts pollAddr)
+```
+
+Deploy a new Poll contract.
+
+#### Parameters
+
+| Name                | Type                     | Description                                     |
+| ------------------- | ------------------------ | ----------------------------------------------- |
+| \_duration          | uint256                  | How long should the Poll last for               |
+| \_treeDepths        | struct Params.TreeDepths | The depth of the Merkle trees                   |
+| \_coordinatorPubKey | struct DomainObjs.PubKey | The coordinator's public key                    |
+| \_verifier          | address                  | The Verifier Contract                           |
+| \_vkRegistry        | address                  | The VkRegistry Contract                         |
+| useSubsidy          | bool                     | If true, the Poll will use the Subsidy contract |
+
+#### Return Values
+
+| Name     | Type                      | Description                 |
+| -------- | ------------------------- | --------------------------- |
+| pollAddr | struct MACI.PollContracts | a new Poll contract address |
+
+### mergeStateAqSubRoots
+
+```solidity
+function mergeStateAqSubRoots(uint256 _numSrQueueOps, uint256 _pollId) public
+```
+
+Allow Poll contracts to merge the state subroots
+
+#### Parameters
+
+| Name            | Type    | Description               |
+| --------------- | ------- | ------------------------- |
+| \_numSrQueueOps | uint256 | Number of operations      |
+| \_pollId        | uint256 | The ID of the active Poll |
+
+### mergeStateAq
+
+```solidity
+function mergeStateAq(uint256 _pollId) public returns (uint256 root)
+```
+
+Allow Poll contracts to merge the state root
+
+#### Parameters
+
+| Name     | Type    | Description        |
+| -------- | ------- | ------------------ |
+| \_pollId | uint256 | The active Poll ID |
+
+#### Return Values
+
+| Name | Type    | Description                |
+| ---- | ------- | -------------------------- |
+| root | uint256 | The calculated Merkle root |
+
+### getStateAqRoot
+
+```solidity
+function getStateAqRoot() public view returns (uint256 root)
+```
+
+Return the main root of the StateAq contract
+
+#### Return Values
+
+| Name | Type    | Description     |
+| ---- | ------- | --------------- |
+| root | uint256 | The Merkle root |
+
+### getPoll
+
+```solidity
+function getPoll(uint256 _pollId) public view returns (address poll)
+```
+
+Get the Poll details
+
+#### Parameters
+
+| Name     | Type    | Description                            |
+| -------- | ------- | -------------------------------------- |
+| \_pollId | uint256 | The identifier of the Poll to retrieve |
+
+#### Return Values
+
+| Name | Type    | Description              |
+| ---- | ------- | ------------------------ |
+| poll | address | The Poll contract object |

package/versioned_docs/version-v1.2/solidity-docs/MessageProcessor.md

@@ -0,0 +1,266 @@
+# MessageProcessor
+
+_MessageProcessor is used to process messages published by signup users.
+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._
+
+### NoMoreMessages
+
+```solidity
+error NoMoreMessages()
+```
+
+custom errors
+
+### StateAqNotMerged
+
+```solidity
+error StateAqNotMerged()
+```
+
+### MessageAqNotMerged
+
+```solidity
+error MessageAqNotMerged()
+```
+
+### InvalidProcessMessageProof
+
+```solidity
+error InvalidProcessMessageProof()
+```
+
+### VkNotSet
+
+```solidity
+error VkNotSet()
+```
+
+### MaxVoteOptionsTooLarge
+
+```solidity
+error MaxVoteOptionsTooLarge()
+```
+
+### NumSignUpsTooLarge
+
+```solidity
+error NumSignUpsTooLarge()
+```
+
+### CurrentMessageBatchIndexTooLarge
+
+```solidity
+error CurrentMessageBatchIndexTooLarge()
+```
+
+### BatchEndIndexTooLarge
+
+```solidity
+error BatchEndIndexTooLarge()
+```
+
+### TREE_ARITY
+
+```solidity
+uint256 TREE_ARITY
+```
+
+### processingComplete
+
+```solidity
+bool processingComplete
+```
+
+Get the result of whether there are unprocessed messages left
+
+#### Return Values
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+
+### numBatchesProcessed
+
+```solidity
+uint256 numBatchesProcessed
+```
+
+The number of batches processed
+
+### currentMessageBatchIndex
+
+```solidity
+uint256 currentMessageBatchIndex
+```
+
+The current message batch index. When the coordinator runs
+processMessages(), this action relates to messages
+currentMessageBatchIndex to currentMessageBatchIndex + messageBatchSize.
+
+### sbCommitment
+
+```solidity
+uint256 sbCommitment
+```
+
+Get the commitment to the state and ballot roots
+
+#### Return Values
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+
+### poll
+
+```solidity
+contract IPoll poll
+```
+
+### verifier
+
+```solidity
+contract IVerifier verifier
+```
+
+### vkRegistry
+
+```solidity
+contract IVkRegistry vkRegistry
+```
+
+### constructor
+
+```solidity
+constructor(address _verifier, address _vkRegistry, address _poll) public payable
+```
+
+Create a new instance
+
+#### Parameters
+
+| Name         | Type    | Description                     |
+| ------------ | ------- | ------------------------------- |
+| \_verifier   | address | The Verifier contract address   |
+| \_vkRegistry | address | The VkRegistry contract address |
+| \_poll       | address | The Poll contract address       |
+
+### processMessages
+
+```solidity
+function processMessages(uint256 _newSbCommitment, uint256[8] _proof) external
+```
+
+Update the Poll's currentSbCommitment if the proof is valid.
+
+#### Parameters
+
+| Name              | Type       | Description                                                                    |
+| ----------------- | ---------- | ------------------------------------------------------------------------------ |
+| \_newSbCommitment | uint256    | The new state root and ballot root commitment after all messages are processed |
+| \_proof           | uint256[8] | The zk-SNARK proof                                                             |
+
+### verifyProcessProof
+
+```solidity
+function verifyProcessProof(uint256 _currentMessageBatchIndex, uint256 _messageRoot, uint256 _currentSbCommitment, uint256 _newSbCommitment, uint8 _messageTreeSubDepth, uint8 _messageTreeDepth, uint8 _voteOptionTreeDepth, uint256[8] _proof) internal view returns (bool isValid)
+```
+
+Verify the proof for processMessage
+
+_used to update the sbCommitment_
+
+#### Parameters
+
+| Name                       | Type       | Description                                             |
+| -------------------------- | ---------- | ------------------------------------------------------- |
+| \_currentMessageBatchIndex | uint256    | The batch index of current message batch                |
+| \_messageRoot              | uint256    | The message tree root                                   |
+| \_currentSbCommitment      | uint256    | The current sbCommitment (state and ballot)             |
+| \_newSbCommitment          | uint256    | The new sbCommitment after we update this message batch |
+| \_messageTreeSubDepth      | uint8      | The message tree subdepth                               |
+| \_messageTreeDepth         | uint8      | The message tree depth                                  |
+| \_voteOptionTreeDepth      | uint8      | The vote option tree depth                              |
+| \_proof                    | uint256[8] | The zk-SNARK proof                                      |
+
+#### Return Values
+
+| Name    | Type | Description                |
+| ------- | ---- | -------------------------- |
+| isValid | bool | Whether the proof is valid |
+
+### genProcessMessagesPublicInputHash
+
+```solidity
+function genProcessMessagesPublicInputHash(uint256 _currentMessageBatchIndex, uint256 _messageRoot, uint256 _numSignUps, uint256 _numMessages, uint256 _currentSbCommitment, uint256 _newSbCommitment, uint8 _messageTreeSubDepth, uint8 _voteOptionTreeDepth) public view returns (uint256 inputHash)
+```
+
+Returns the SHA256 hash of the packed values (see
+genProcessMessagesPackedVals), the hash of the coordinator's public key,
+the message root, and the commitment to the current state root and
+ballot root. By passing the SHA256 hash of these values to the circuit
+as a single public input and the preimage as private inputs, we reduce
+its verification gas cost though the number of constraints will be
+higher and proving time will be longer.
+
+#### Parameters
+
+| Name                       | Type    | Description                                             |
+| -------------------------- | ------- | ------------------------------------------------------- |
+| \_currentMessageBatchIndex | uint256 | The batch index of current message batch                |
+| \_messageRoot              | uint256 |                                                         |
+| \_numSignUps               | uint256 | The number of users that signup                         |
+| \_numMessages              | uint256 | The number of messages                                  |
+| \_currentSbCommitment      | uint256 | The current sbCommitment (state and ballot root)        |
+| \_newSbCommitment          | uint256 | The new sbCommitment after we update this message batch |
+| \_messageTreeSubDepth      | uint8   | The message tree subdepth                               |
+| \_voteOptionTreeDepth      | uint8   |                                                         |
+
+#### Return Values
+
+| Name      | Type    | Description                                  |
+| --------- | ------- | -------------------------------------------- |
+| inputHash | uint256 | Returns the SHA256 hash of the packed values |
+
+### genProcessMessagesPackedVals
+
+```solidity
+function genProcessMessagesPackedVals(uint256 _currentMessageBatchIndex, uint256 _numSignUps, uint256 _numMessages, uint8 _messageTreeSubDepth, uint8 _voteOptionTreeDepth) public pure returns (uint256 result)
+```
+
+One of the inputs to the ProcessMessages circuit is a 250-bit
+representation of four 50-bit values. This function generates this
+250-bit value, which consists of the maximum number of vote options, the
+number of signups, the current message batch index, and the end index of
+the current batch.
+
+#### Parameters
+
+| Name                       | Type    | Description                          |
+| -------------------------- | ------- | ------------------------------------ |
+| \_currentMessageBatchIndex | uint256 | batch index of current message batch |
+| \_numSignUps               | uint256 | number of users that signup          |
+| \_numMessages              | uint256 | number of messages                   |
+| \_messageTreeSubDepth      | uint8   | message tree subdepth                |
+| \_voteOptionTreeDepth      | uint8   | vote option tree depth               |
+
+#### Return Values
+
+| Name   | Type    | Description      |
+| ------ | ------- | ---------------- |
+| result | uint256 | The packed value |
+
+### updateMessageProcessingData
+
+```solidity
+function updateMessageProcessingData(uint256 _newSbCommitment, uint256 _currentMessageBatchIndex, bool _processingComplete) internal
+```
+
+update message processing state variables
+
+#### Parameters
+
+| Name                       | Type    | Description                                             |
+| -------------------------- | ------- | ------------------------------------------------------- |
+| \_newSbCommitment          | uint256 | sbCommitment to be updated                              |
+| \_currentMessageBatchIndex | uint256 | currentMessageBatchIndex to be updated                  |
+| \_processingComplete       | bool    | update flag that indicate processing is finished or not |

package/versioned_docs/version-v1.2/solidity-docs/MessageProcessorFactory.md

@@ -0,0 +1,26 @@
+# MessageProcessorFactory
+
+A factory contract which deploys MessageProcessor contracts.
+
+### deploy
+
+```solidity
+function deploy(address _verifier, address _vkRegistry, address _poll, address _owner) public returns (address messageProcessorAddr)
+```
+
+Deploy a new MessageProcessor contract and return the address.
+
+#### Parameters
+
+| Name         | Type    | Description                            |
+| ------------ | ------- | -------------------------------------- |
+| \_verifier   | address | Verifier contract                      |
+| \_vkRegistry | address | VkRegistry contract                    |
+| \_poll       | address | Poll contract                          |
+| \_owner      | address | Owner of the MessageProcessor contract |
+
+#### Return Values
+
+| Name                 | Type    | Description                            |
+| -------------------- | ------- | -------------------------------------- |
+| messageProcessorAddr | address | The deployed MessageProcessor contract |