@maci-protocol/website 0.0.0-ci.1e276ed

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

@@ -0,0 +1,381 @@
+# Poll
+
+A Poll contract allows voters to submit encrypted messages
+which can be either votes, key change messages or topup messages.
+
+_Do not deploy this directly. Use PollFactory.deploy() which performs some
+checks on the Poll constructor arguments._
+
+### isInit
+
+```solidity
+bool isInit
+```
+
+Whether the Poll has been initialized
+
+### coordinatorPubKey
+
+```solidity
+struct DomainObjs.PubKey coordinatorPubKey
+```
+
+The coordinator's public key
+
+### coordinatorPubKeyHash
+
+```solidity
+uint256 coordinatorPubKeyHash
+```
+
+Hash of the coordinator's public key
+
+### mergedStateRoot
+
+```solidity
+uint256 mergedStateRoot
+```
+
+the state root of the state merkle tree
+
+### deployTime
+
+```solidity
+uint256 deployTime
+```
+
+### duration
+
+```solidity
+uint256 duration
+```
+
+### stateAqMerged
+
+```solidity
+bool stateAqMerged
+```
+
+Whether the MACI contract's stateAq has been merged by this contract
+
+### currentSbCommitment
+
+```solidity
+uint256 currentSbCommitment
+```
+
+Get the commitment to the state leaves and the ballots. This is
+hash3(stateRoot, ballotRoot, salt).
+Its initial value should be
+hash(maciStateRootSnapshot, emptyBallotRoot, 0)
+Each successful invocation of processMessages() should use a different
+salt to update this value, so that an external observer cannot tell in
+the case that none of the messages are valid.
+
+### numMessages
+
+```solidity
+uint256 numMessages
+```
+
+The number of messages that have been published
+
+### numSignups
+
+```solidity
+uint256 numSignups
+```
+
+The number of signups that have been processed
+before the Poll ended (stateAq merged)
+
+### maxValues
+
+```solidity
+struct Params.MaxValues maxValues
+```
+
+Max values for the poll
+
+### treeDepths
+
+```solidity
+struct Params.TreeDepths treeDepths
+```
+
+Depths of the merkle trees
+
+### extContracts
+
+```solidity
+struct Params.ExtContracts extContracts
+```
+
+The contracts used by the Poll
+
+### VotingPeriodOver
+
+```solidity
+error VotingPeriodOver()
+```
+
+### VotingPeriodNotOver
+
+```solidity
+error VotingPeriodNotOver()
+```
+
+### PollAlreadyInit
+
+```solidity
+error PollAlreadyInit()
+```
+
+### TooManyMessages
+
+```solidity
+error TooManyMessages()
+```
+
+### MaciPubKeyLargerThanSnarkFieldSize
+
+```solidity
+error MaciPubKeyLargerThanSnarkFieldSize()
+```
+
+### StateAqAlreadyMerged
+
+```solidity
+error StateAqAlreadyMerged()
+```
+
+### StateAqSubtreesNeedMerge
+
+```solidity
+error StateAqSubtreesNeedMerge()
+```
+
+### InvalidBatchLength
+
+```solidity
+error InvalidBatchLength()
+```
+
+### PublishMessage
+
+```solidity
+event PublishMessage(struct DomainObjs.Message _message, struct DomainObjs.PubKey _encPubKey)
+```
+
+### TopupMessage
+
+```solidity
+event TopupMessage(struct DomainObjs.Message _message)
+```
+
+### MergeMaciStateAqSubRoots
+
+```solidity
+event MergeMaciStateAqSubRoots(uint256 _numSrQueueOps)
+```
+
+### MergeMaciStateAq
+
+```solidity
+event MergeMaciStateAq(uint256 _stateRoot, uint256 _numSignups)
+```
+
+### MergeMessageAqSubRoots
+
+```solidity
+event MergeMessageAqSubRoots(uint256 _numSrQueueOps)
+```
+
+### MergeMessageAq
+
+```solidity
+event MergeMessageAq(uint256 _messageRoot)
+```
+
+### constructor
+
+```solidity
+constructor(uint256 _duration, struct Params.MaxValues _maxValues, struct Params.TreeDepths _treeDepths, struct DomainObjs.PubKey _coordinatorPubKey, struct Params.ExtContracts _extContracts) public payable
+```
+
+Each MACI instance can have multiple Polls.
+When a Poll is deployed, its voting period starts immediately.
+
+#### Parameters
+
+| Name                | Type                       | Description                                     |
+| ------------------- | -------------------------- | ----------------------------------------------- |
+| \_duration          | uint256                    | The duration of the voting period, in seconds   |
+| \_maxValues         | struct Params.MaxValues    | The maximum number of messages and vote options |
+| \_treeDepths        | struct Params.TreeDepths   | The depths of the merkle trees                  |
+| \_coordinatorPubKey | struct DomainObjs.PubKey   | The coordinator's public key                    |
+| \_extContracts      | struct Params.ExtContracts | The external contracts                          |
+
+### isAfterVotingDeadline
+
+```solidity
+modifier isAfterVotingDeadline()
+```
+
+A modifier that causes the function to revert if the voting period is
+not over.
+
+### isWithinVotingDeadline
+
+```solidity
+modifier isWithinVotingDeadline()
+```
+
+A modifier that causes the function to revert if the voting period is
+over
+
+### init
+
+```solidity
+function init() public
+```
+
+The initialization function.
+
+_Should be called immediately after Poll creation
+and messageAq ownership transferred_
+
+### topup
+
+```solidity
+function topup(uint256 stateIndex, uint256 amount) public virtual
+```
+
+Allows to publish a Topup message
+
+#### Parameters
+
+| Name       | Type    | Description                          |
+| ---------- | ------- | ------------------------------------ |
+| stateIndex | uint256 | The index of user in the state queue |
+| amount     | uint256 | The amount of credits to topup       |
+
+### publishMessage
+
+```solidity
+function publishMessage(struct DomainObjs.Message _message, struct DomainObjs.PubKey _encPubKey) public virtual
+```
+
+Allows anyone to publish a message (an encrypted command and signature).
+This function also enqueues the message.
+
+#### Parameters
+
+| Name        | Type                      | Description                                                                                                                                        |
+| ----------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| \_message   | struct DomainObjs.Message | The message to publish                                                                                                                             |
+| \_encPubKey | struct DomainObjs.PubKey  | An ephemeral public key which can be combined with the coordinator's private key to generate an ECDH shared key with which to encrypt the message. |
+
+### publishMessageBatch
+
+```solidity
+function publishMessageBatch(struct DomainObjs.Message[] _messages, struct DomainObjs.PubKey[] _encPubKeys) external
+```
+
+submit a message batch
+
+_Can only be submitted before the voting deadline_
+
+#### Parameters
+
+| Name         | Type                        | Description               |
+| ------------ | --------------------------- | ------------------------- |
+| \_messages   | struct DomainObjs.Message[] | the messages              |
+| \_encPubKeys | struct DomainObjs.PubKey[]  | the encrypted public keys |
+
+### mergeMaciStateAqSubRoots
+
+```solidity
+function mergeMaciStateAqSubRoots(uint256 _numSrQueueOps, uint256 _pollId) public
+```
+
+The first step of merging the MACI state AccQueue. This allows the
+ProcessMessages circuit to access the latest state tree and ballots via
+currentSbCommitment.
+
+#### Parameters
+
+| Name            | Type    | Description               |
+| --------------- | ------- | ------------------------- |
+| \_numSrQueueOps | uint256 | Number of operations      |
+| \_pollId        | uint256 | The ID of the active Poll |
+
+### mergeMaciStateAq
+
+```solidity
+function mergeMaciStateAq(uint256 _pollId) public
+```
+
+The second step of merging the MACI state AccQueue. This allows the
+ProcessMessages circuit to access the latest state tree and ballots via
+currentSbCommitment.
+
+#### Parameters
+
+| Name     | Type    | Description               |
+| -------- | ------- | ------------------------- |
+| \_pollId | uint256 | The ID of the active Poll |
+
+### mergeMessageAqSubRoots
+
+```solidity
+function mergeMessageAqSubRoots(uint256 _numSrQueueOps) public
+```
+
+The first step in merging the message AccQueue so that the
+ProcessMessages circuit can access the message root.
+
+#### Parameters
+
+| Name            | Type    | Description                                       |
+| --------------- | ------- | ------------------------------------------------- |
+| \_numSrQueueOps | uint256 | The number of subroot queue operations to perform |
+
+### mergeMessageAq
+
+```solidity
+function mergeMessageAq() public
+```
+
+The second step in merging the message AccQueue so that the
+ProcessMessages circuit can access the message root.
+
+### getDeployTimeAndDuration
+
+```solidity
+function getDeployTimeAndDuration() public view returns (uint256 pollDeployTime, uint256 pollDuration)
+```
+
+Returns the Poll's deploy time and duration
+
+#### Return Values
+
+| Name           | Type    | Description |
+| -------------- | ------- | ----------- |
+| pollDeployTime | uint256 |             |
+| pollDuration   | uint256 |             |
+
+### numSignUpsAndMessages
+
+```solidity
+function numSignUpsAndMessages() public view returns (uint256 numSUps, uint256 numMsgs)
+```
+
+The number of messages which have been processed and the number of signups
+
+#### Return Values
+
+| Name    | Type    | Description                           |
+| ------- | ------- | ------------------------------------- |
+| numSUps | uint256 |                                       |
+| numMsgs | uint256 | The number of messages sent by voters |

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

@@ -0,0 +1,50 @@
+# PollFactory
+
+A factory contract which deploys Poll contracts. It allows the MACI contract
+size to stay within the limit set by EIP-170.
+
+### TREE_ARITY
+
+```solidity
+uint256 TREE_ARITY
+```
+
+### InvalidMaxValues
+
+```solidity
+error InvalidMaxValues()
+```
+
+### constructor
+
+```solidity
+constructor() public payable
+```
+
+The PollFactory constructor
+
+### deploy
+
+```solidity
+function deploy(uint256 _duration, struct Params.MaxValues _maxValues, struct Params.TreeDepths _treeDepths, struct DomainObjs.PubKey _coordinatorPubKey, address _maci, contract TopupCredit _topupCredit, address _pollOwner) public virtual returns (address pollAddr)
+```
+
+Deploy a new Poll contract and AccQueue contract for messages.
+
+#### Parameters
+
+| Name                | Type                     | Description                           |
+| ------------------- | ------------------------ | ------------------------------------- |
+| \_duration          | uint256                  | The duration of the poll              |
+| \_maxValues         | struct Params.MaxValues  | The max values for the poll           |
+| \_treeDepths        | struct Params.TreeDepths | The depths of the merkle trees        |
+| \_coordinatorPubKey | struct DomainObjs.PubKey | The coordinator's public key          |
+| \_maci              | address                  | The MACI contract interface reference |
+| \_topupCredit       | contract TopupCredit     | The TopupCredit contract              |
+| \_pollOwner         | address                  | The owner of the poll                 |
+
+#### Return Values
+
+| Name     | Type    | Description                |
+| -------- | ------- | -------------------------- |
+| pollAddr | address | The deployed Poll contract |

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

@@ -0,0 +1,27 @@
+# SignUpToken
+
+This contract is an ERC721 token contract which
+can be used to allow users to sign up for a poll.
+
+### constructor
+
+```solidity
+constructor() public payable
+```
+
+The constructor which calls the ERC721 constructor
+
+### giveToken
+
+```solidity
+function giveToken(address to, uint256 curTokenId) public
+```
+
+Gives an ERC721 token to an address
+
+#### Parameters
+
+| Name       | Type    | Description                      |
+| ---------- | ------- | -------------------------------- |
+| to         | address | The address to give the token to |
+| curTokenId | uint256 | The token id to give             |

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

@@ -0,0 +1,218 @@
+# 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.
+
+### rbi
+
+```solidity
+uint256 rbi
+```
+
+### cbi
+
+```solidity
+uint256 cbi
+```
+
+### sbCommitment
+
+```solidity
+uint256 sbCommitment
+```
+
+### subsidyCommitment
+
+```solidity
+uint256 subsidyCommitment
+```
+
+### verifier
+
+```solidity
+contract IVerifier verifier
+```
+
+### vkRegistry
+
+```solidity
+contract IVkRegistry vkRegistry
+```
+
+### poll
+
+```solidity
+contract IPoll poll
+```
+
+### mp
+
+```solidity
+contract IMessageProcessor mp
+```
+
+### ProcessingNotComplete
+
+```solidity
+error ProcessingNotComplete()
+```
+
+### InvalidSubsidyProof
+
+```solidity
+error InvalidSubsidyProof()
+```
+
+### AllSubsidyCalculated
+
+```solidity
+error AllSubsidyCalculated()
+```
+
+### VkNotSet
+
+```solidity
+error VkNotSet()
+```
+
+### NumSignUpsTooLarge
+
+```solidity
+error NumSignUpsTooLarge()
+```
+
+### RbiTooLarge
+
+```solidity
+error RbiTooLarge()
+```
+
+### CbiTooLarge
+
+```solidity
+error CbiTooLarge()
+```
+
+### constructor
+
+```solidity
+constructor(address _verifier, address _vkRegistry, address _poll, address _mp) public payable
+```
+
+Create a new Subsidy contract
+
+#### Parameters
+
+| Name         | Type    | Description                   |
+| ------------ | ------- | ----------------------------- |
+| \_verifier   | address | The Verifier contract         |
+| \_vkRegistry | address | The VkRegistry contract       |
+| \_poll       | address | The Poll contract             |
+| \_mp         | address | The MessageProcessor contract |
+
+### updateSbCommitment
+
+```solidity
+function updateSbCommitment() public
+```
+
+Update the currentSbCommitment if the proof is valid.
+
+_currentSbCommitment is the commitment to the state and ballot roots_
+
+### genSubsidyPackedVals
+
+```solidity
+function genSubsidyPackedVals(uint256 _numSignUps) public view returns (uint256 result)
+```
+
+Generate the packed values for the subsidy proof
+
+#### Parameters
+
+| Name         | Type    | Description           |
+| ------------ | ------- | --------------------- |
+| \_numSignUps | uint256 | The number of signups |
+
+#### Return Values
+
+| Name   | Type    | Description       |
+| ------ | ------- | ----------------- |
+| result | uint256 | The packed values |
+
+### genSubsidyPublicInputHash
+
+```solidity
+function genSubsidyPublicInputHash(uint256 _numSignUps, uint256 _newSubsidyCommitment) public view returns (uint256 inputHash)
+```
+
+Generate the public input hash for the subsidy proof
+
+#### Parameters
+
+| Name                   | Type    | Description                |
+| ---------------------- | ------- | -------------------------- |
+| \_numSignUps           | uint256 | The number of signups      |
+| \_newSubsidyCommitment | uint256 | The new subsidy commitment |
+
+#### Return Values
+
+| Name      | Type    | Description           |
+| --------- | ------- | --------------------- |
+| inputHash | uint256 | The public input hash |
+
+### updateSubsidy
+
+```solidity
+function updateSubsidy(uint256 _newSubsidyCommitment, uint256[8] _proof) external
+```
+
+Update the subsidy commitment if the proof is valid
+
+#### Parameters
+
+| Name                   | Type       | Description                |
+| ---------------------- | ---------- | -------------------------- |
+| \_newSubsidyCommitment | uint256    | The new subsidy commitment |
+| \_proof                | uint256[8] | The proof                  |
+
+### increaseSubsidyIndex
+
+```solidity
+function increaseSubsidyIndex(uint256 batchSize, uint256 numLeaves) internal
+```
+
+Increase the subsidy batch index (rbi, cbi) to next,
+it will try to cbi++ if the whole batch can fit into numLeaves
+otherwise it will increase row index: rbi++.
+Each batch for subsidy calculation is 2 dimensional: batchSize\*batchSize
+
+#### Parameters
+
+| Name      | Type    | Description                                                      |
+| --------- | ------- | ---------------------------------------------------------------- |
+| batchSize | uint256 | the size of 1 dimensional batch over the signup users            |
+| numLeaves | uint256 | total number of leaves in stateTree, i.e. number of signup users |
+
+### verifySubsidyProof
+
+```solidity
+function verifySubsidyProof(uint256[8] _proof, uint256 _numSignUps, uint256 _newSubsidyCommitment) public view returns (bool isValid)
+```
+
+Verify the subsidy proof using the Groth16 on chain verifier
+
+#### Parameters
+
+| Name                   | Type       | Description                |
+| ---------------------- | ---------- | -------------------------- |
+| \_proof                | uint256[8] | The proof                  |
+| \_numSignUps           | uint256    | The number of signups      |
+| \_newSubsidyCommitment | uint256    | The new subsidy commitment |
+
+#### Return Values
+
+| Name    | Type | Description                |
+| ------- | ---- | -------------------------- |
+| isValid | bool | True if the proof is valid |

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

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