Skip to main content
Version: v3.x

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.

maxSignups​

uint256 maxSignups

The max number of poll signups

STATE_TREE_ARITY​

uint8 STATE_TREE_ARITY

The state tree arity

coordinatorPublicKey​

struct DomainObjs.PublicKey coordinatorPublicKey

The coordinator's public key

coordinatorPublicKeyHash​

uint256 coordinatorPublicKeyHash

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

totalSignups​

uint256 totalSignups

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()

InvalidPublicKey​

error InvalidPublicKey()

StateAlreadyMerged​

error StateAlreadyMerged()

InvalidBatchLength​

error InvalidBatchLength()

BatchHashesAlreadyPadded​

error BatchHashesAlreadyPadded()

UserAlreadyJoined​

error UserAlreadyJoined()

InvalidPollProof​

error InvalidPollProof()

NotRelayer​

error NotRelayer()

StateLeafNotFound​

error StateLeafNotFound()

TooManyVoteOptions​

error TooManyVoteOptions()

TooManySignups​

error TooManySignups()

PublishMessage​

event PublishMessage(struct DomainObjs.Message _message, struct DomainObjs.PublicKey _encryptionPublicKey)

MergeState​

event MergeState(uint256 _stateRoot, uint256 _totalSignups)

PollJoined​

event PollJoined(uint256 _pollPublicKeyX, uint256 _pollPublicKeyY, uint256 _voiceCreditBalance, uint256 _nullifier, uint256 _pollStateIndex)

ChainHashUpdated​

event ChainHashUpdated(uint256 _chainHash)

IpfsHashAdded​

event IpfsHashAdded(bytes32 _ipfsHash)

_initialize​

function _initialize() internal

Initializes the contract.

Each MACI instance can have multiple Polls. When a Poll is deployed, its voting period starts immediately.

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​

NameTypeDescription
[0]uint256[]betchHashes array containing all batch hashes

publishMessage​

function publishMessage(struct DomainObjs.Message _message, struct DomainObjs.PublicKey _encryptionPublicKey) public virtual

Allows anyone to publish a message (an encrypted command and signature). This function also enqueues the message.

Parameters​

NameTypeDescription
_messagestruct DomainObjs.MessageThe message to publish
_encryptionPublicKeystruct DomainObjs.PublicKeyAn 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​

NameTypeDescription
_messageHashesuint256[]The message hashes
_ipfsHashbytes32The IPFS hash of the messages batch

updateChainHash​

function updateChainHash(uint256 messageHash) internal

compute and update current message chain hash

Parameters​

NameTypeDescription
messageHashuint256hash 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.PublicKey[] _encryptionPublicKeys) public virtual

Submit a message batch

Can only be submitted before the voting deadline

Parameters​

NameTypeDescription
_messagesstruct DomainObjs.Message[]the messages
_encryptionPublicKeysstruct DomainObjs.PublicKey[]the encryption public keys

joinPoll​

function joinPoll(uint256 _nullifier, struct DomainObjs.PublicKey _publicKey, uint256 _stateRootIndex, uint256[8] _proof, bytes _signUpPolicyData, bytes _initialVoiceCreditProxyData) external virtual

Join the poll for voting

Parameters​

NameTypeDescription
_nullifieruint256Hashed user's private key to check whether user has already voted
_publicKeystruct DomainObjs.PublicKeyPoll user's public key
_stateRootIndexuint256Index of the MACI's stateRootOnSignUp for which the inclusion proof is generated
_proofuint256[8]The zk-SNARK proof
_signUpPolicyDatabytesData to pass to the signup policy
_initialVoiceCreditProxyDatabytesData to pass to the InitialVoiceCreditProxy

verifyJoiningPollProof​

function verifyJoiningPollProof(uint256 _nullifier, uint256 _index, struct DomainObjs.PublicKey _publicKey, uint256[8] _proof) public view returns (bool isValid)

Verify the proof for Poll joining

Parameters​

NameTypeDescription
_nullifieruint256Hashed user's private key to check whether user has already voted
_indexuint256Index of the MACI's stateRootOnSignUp when the user signed up
_publicKeystruct DomainObjs.PublicKeyPoll user's public key
_proofuint256[8]The zk-SNARK proof

Return Values​

NameTypeDescription
isValidboolWhether the proof is valid

verifyJoinedPollProof​

function verifyJoinedPollProof(uint256 _index, uint256[8] _proof) public view returns (bool isValid)

Verify the proof for joined Poll

Parameters​

NameTypeDescription
_indexuint256Index of the MACI's stateRootOnSignUp when the user signed up
_proofuint256[8]The zk-SNARK proof

Return Values​

NameTypeDescription
isValidboolWhether the proof is valid

getPublicJoiningCircuitInputs​

function getPublicJoiningCircuitInputs(uint256 _nullifier, uint256 _index, struct DomainObjs.PublicKey _publicKey) public view returns (uint256[] publicInputs)

Get public circuit inputs for poll joining circuit

Parameters​

NameTypeDescription
_nullifieruint256Hashed user's private key to check whether user has already voted
_indexuint256Index of the MACI's stateRootOnSignUp when the user signed up
_publicKeystruct DomainObjs.PublicKeyPoll user's public key

Return Values​

NameTypeDescription
publicInputsuint256[]Public circuit inputs

getPublicJoinedCircuitInputs​

function getPublicJoinedCircuitInputs(uint256 _index) public view returns (uint256[] publicInputs)

Get public circuit inputs for poll joined circuit

Parameters​

NameTypeDescription
_indexuint256Index of the MACI's stateRootOnSignUp when the user signed up

Return Values​

NameTypeDescription
publicInputsuint256[]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​

NameTypeDescription
pollStartDateuint256
pollEndDateuint256

totalSignupsAndMessages​

function totalSignupsAndMessages() public view returns (uint256 numSUps, uint256 numMsgs)

The number of messages which have been processed and the number of signups

Return Values​

NameTypeDescription
numSUpsuint256
numMsgsuint256The number of messages sent by voters

getMaciContract​

function getMaciContract() public view returns (contract IMACI maci)

Get the external contracts

Return Values​

NameTypeDescription
macicontract IMACIThe IMACI contract

getStateIndex​

function getStateIndex(uint256 element) public view returns (uint40)

Get the index of a state leaf in the state tree

Parameters​

NameTypeDescription
elementuint256The hash of thestate leaf

Return Values​

NameTypeDescription
[0]uint40index The index of the state leaf in the state tree