Poll
A Poll contract allows voters to submit encrypted messages which can be either votes or key change messages.
Do not deploy this directly. Use PollFactory.deploy() which performs some checks on the Poll constructor arguments.
coordinatorPubKey
struct DomainObjs.PubKey coordinatorPubKey
The coordinator's public key
coordinatorPubKeyHash
uint256 coordinatorPubKeyHash
Hash of the coordinator's public key
mergedStateRoot
uint256 mergedStateRoot
the state root of the state merkle tree
startDate
uint256 startDate
The start date of the poll
endDate
uint256 endDate
The end date of the poll
emptyBallotRoot
uint256 emptyBallotRoot
The root of the empty ballot tree at a given voteOptionTree depth
stateMerged
bool stateMerged
Whether the MACI contract's stateAq has been merged by this contract
currentSbCommitment
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
uint256 numMessages
The number of messages that have been published
numSignups
uint256 numSignups
The number of signups that have been processed before the Poll ended (stateAq merged)
actualStateTreeDepth
uint8 actualStateTreeDepth
The actual depth of the state tree to be used as public input for the circuit
voteOptions
uint256 voteOptions
The number of valid vote options for the poll
treeDepths
struct Params.TreeDepths treeDepths
Depths of the merkle trees
messageBatchSize
uint8 messageBatchSize
Message batch size for the poll
extContracts
struct Params.ExtContracts extContracts
The contracts used by the Poll
batchHashes
uint256[] batchHashes
The array for chain hash checkpoints
chainHash
uint256 chainHash
Current chain hash
isBatchHashesPadded
bool isBatchHashesPadded
@notice flag for batch padding
pollStateTree
struct LazyIMTData pollStateTree
Poll state tree for anonymous joining
ipfsHashes
bytes32[] ipfsHashes
IPFS hashes of messages batches
relayers
mapping(address => bool) relayers
Relayer address
BLANK_STATE_LEAF_HASH
uint256 BLANK_STATE_LEAF_HASH
The hash of a blank state leaf
VOTE_TREE_ARITY
uint8 VOTE_TREE_ARITY
pollNullifiers
mapping(uint256 => bool) pollNullifiers
Poll joining nullifiers
pollId
uint256 pollId
The Id of this poll
pollStateRootsOnJoin
uint256[] pollStateRootsOnJoin
The array of the poll state tree roots for each poll join For the N'th poll join, the poll state tree root will be stored at the index N
VotingPeriodOver
error VotingPeriodOver()
VotingPeriodNotOver
error VotingPeriodNotOver()
VotingPeriodNotStarted
error VotingPeriodNotStarted()
PollAlreadyInit
error PollAlreadyInit()
TooManyMessages
error TooManyMessages()
InvalidPubKey
error InvalidPubKey()
StateAlreadyMerged
error StateAlreadyMerged()
InvalidBatchLength
error InvalidBatchLength()
BatchHashesAlreadyPadded
error BatchHashesAlreadyPadded()
UserAlreadyJoined
error UserAlreadyJoined()
InvalidPollProof
error InvalidPollProof()
NotRelayer
error NotRelayer()
StateLeafNotFound
error StateLeafNotFound()
TooManyVoteOptions
error TooManyVoteOptions()
PublishMessage
event PublishMessage(struct DomainObjs.Message _message, struct DomainObjs.PubKey _encPubKey)
MergeState
event MergeState(uint256 _stateRoot, uint256 _numSignups)
PollJoined
event PollJoined(uint256 _pollPubKeyX, uint256 _pollPubKeyY, uint256 _voiceCreditBalance, uint256 _timestamp, uint256 _nullifier, uint256 _pollStateIndex)
ChainHashUpdated
event ChainHashUpdated(uint256 _chainHash)
IpfsHashAdded
event IpfsHashAdded(bytes32 _ipfsHash)
constructor
constructor(uint256 _startDate, uint256 _endDate, struct Params.TreeDepths _treeDepths, uint8 _messageBatchSize, struct DomainObjs.PubKey _coordinatorPubKey, struct Params.ExtContracts _extContracts, uint256 _emptyBallotRoot, uint256 _pollId, address[] _relayers, uint256 _voteOptions) public payable
Each MACI instance can have multiple Polls. When a Poll is deployed, its voting period starts immediately.
Parameters
| Name | Type | Description |
|---|---|---|
| _startDate | uint256 | The start date of the poll |
| _endDate | uint256 | The end date of the poll |
| _treeDepths | struct Params.TreeDepths | The depths of the merkle trees |
| _messageBatchSize | uint8 | The message batch size |
| _coordinatorPubKey | struct DomainObjs.PubKey | The coordinator's public key |
| _extContracts | struct Params.ExtContracts | The external contracts |
| _emptyBallotRoot | uint256 | The root of the empty ballot tree |
| _pollId | uint256 | The poll id |
| _relayers | address[] | |
| _voteOptions | uint256 | The number of valid vote options for the poll |
isAfterVotingDeadline
modifier isAfterVotingDeadline()
A modifier that causes the function to revert if the voting period is not over.
onlyRelayer
modifier onlyRelayer()
A modifier that causes the function to revert if the caller is not a relayer
isOpenForVoting
modifier isOpenForVoting()
A modifier that causes the function to revert if the voting period is over
This is used to prevent users from publishing messages after the voting period has ended or before the voting period has started
isWithinVotingDeadline
modifier isWithinVotingDeadline()
A modifier that causes the function to revert if the voting period is over
This is used to prevent users from joining the poll after the voting period has ended This allows to join before the poll is open for voting
getBatchHashes
function getBatchHashes() external view returns (uint256[])
Get all message batch hashes
Return Values
| Name | Type | Description |
|---|---|---|
| [0] | uint256[] | betchHashes array containing all batch hashes |
publishMessage
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. |
relayMessagesBatch
function relayMessagesBatch(uint256[] _messageHashes, bytes32 _ipfsHash) public virtual
Allows relayer to publish messages using IPFS.
Parameters
| Name | Type | Description |
|---|---|---|
| _messageHashes | uint256[] | The message hashes |
| _ipfsHash | bytes32 | The IPFS hash of the messages batch |
updateChainHash
function updateChainHash(uint256 messageHash) internal
compute and update current message chain hash
Parameters
| Name | Type | Description |
|---|---|---|
| messageHash | uint256 | hash of the current message |
padLastBatch
function padLastBatch() external
pad last unclosed batch
Anyone can call this function, it will only pad once
publishMessageBatch
function publishMessageBatch(struct DomainObjs.Message[] _messages, struct DomainObjs.PubKey[] _encPubKeys) public virtual
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 |
joinPoll
function joinPoll(uint256 _nullifier, struct DomainObjs.PubKey _pubKey, uint256 _stateRootIndex, uint256[8] _proof, bytes _signUpPolicyData, bytes _initialVoiceCreditProxyData) external virtual
Join the poll for voting
Parameters
| Name | Type | Description |
|---|---|---|
| _nullifier | uint256 | Hashed user's private key to check whether user has already voted |
| _pubKey | struct DomainObjs.PubKey | Poll user's public key |
| _stateRootIndex | uint256 | Index of the MACI's stateRootOnSignUp for which the inclusion proof is generated |
| _proof | uint256[8] | The zk-SNARK proof |
| _signUpPolicyData | bytes | Data to pass to the signup policy |
| _initialVoiceCreditProxyData | bytes | Data to pass to the InitialVoiceCreditProxy |
verifyJoiningPollProof
function verifyJoiningPollProof(uint256 _nullifier, uint256 _index, struct DomainObjs.PubKey _pubKey, uint256[8] _proof) public view returns (bool isValid)
Verify the proof for Poll joining
Parameters
| Name | Type | Description |
|---|---|---|
| _nullifier | uint256 | Hashed user's private key to check whether user has already voted |
| _index | uint256 | Index of the MACI's stateRootOnSignUp when the user signed up |
| _pubKey | struct DomainObjs.PubKey | Poll user's public key |
| _proof | uint256[8] | The zk-SNARK proof |
Return Values
| Name | Type | Description |
|---|---|---|
| isValid | bool | Whether the proof is valid |
verifyJoinedPollProof
function verifyJoinedPollProof(uint256 _index, uint256[8] _proof) public view returns (bool isValid)
Verify the proof for joined Poll
Parameters
| Name | Type | Description |
|---|---|---|
| _index | uint256 | Index of the MACI's stateRootOnSignUp when the user signed up |
| _proof | uint256[8] | The zk-SNARK proof |
Return Values
| Name | Type | Description |
|---|---|---|
| isValid | bool | Whether the proof is valid |
getPublicJoiningCircuitInputs
function getPublicJoiningCircuitInputs(uint256 _nullifier, uint256 _index, struct DomainObjs.PubKey _pubKey) public view returns (uint256[] publicInputs)
Get public circuit inputs for poll joining circuit
Parameters
| Name | Type | Description |
|---|---|---|
| _nullifier | uint256 | Hashed user's private key to check whether user has already voted |
| _index | uint256 | Index of the MACI's stateRootOnSignUp when the user signed up |
| _pubKey | struct DomainObjs.PubKey | Poll user's public key |
Return Values
| Name | Type | Description |
|---|---|---|
| publicInputs | uint256[] | Public circuit inputs |
getPublicJoinedCircuitInputs
function getPublicJoinedCircuitInputs(uint256 _index) public view returns (uint256[] publicInputs)
Get public circuit inputs for poll joined circuit
Parameters
| Name | Type | Description |
|---|---|---|
| _index | uint256 | Index of the MACI's stateRootOnSignUp when the user signed up |
Return Values
| Name | Type | Description |
|---|---|---|
| publicInputs | uint256[] | Public circuit inputs |
mergeState
function mergeState() public
The second step of merging the poll state. This allows the ProcessMessages circuit to access the latest state tree and ballots via currentSbCommitment.
getStartAndEndDate
function getStartAndEndDate() public view virtual returns (uint256 pollStartDate, uint256 pollEndDate)
Returns the Poll's start and end dates
Return Values
| Name | Type | Description |
|---|---|---|
| pollStartDate | uint256 | |
| pollEndDate | uint256 |
numSignUpsAndMessages
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 |
getMaciContract
function getMaciContract() public view returns (contract IMACI maci)
Get the external contracts
Return Values
| Name | Type | Description |
|---|---|---|
| maci | contract IMACI | The IMACI contract |
getStateIndex
function getStateIndex(uint256 element) public view returns (uint40)
Get the index of a state leaf in the state tree
Parameters
| Name | Type | Description |
|---|---|---|
| element | uint256 | The hash of thestate leaf |
Return Values
| Name | Type | Description |
|---|---|---|
| [0] | uint40 | index The index of the state leaf in the state tree |