Tally
The Tally contract is used during votes tallying and by users to verify the tally results.
TREE_ARITY
uint256 TREE_ARITY
VOTE_OPTION_TREE_ARITY
uint256 VOTE_OPTION_TREE_ARITY
tallyCommitment
uint256 tallyCommitment
The commitment to the tally results. Its initial value is 0, but after the tally of each batch is proven on-chain via a zk-SNARK, it should be updated to:
QV: hash3( hashLeftRight(merkle root of current results, salt0) hashLeftRight(number of spent voice credits, salt1), hashLeftRight(merkle root of the no. of spent voice credits per vote option, salt2) )
Non-QV or Full: hash2( hashLeftRight(merkle root of current results, salt0) hashLeftRight(number of spent voice credits, salt1), )
Where each salt is unique and the merkle roots are of arrays of leaves TREE_ARITY ** voteOptionTreeDepth long.
tallyBatchNum
uint256 tallyBatchNum
Get the tally batch number
Return Values
| Name | Type | Description |
|---|
sbCommitment
uint256 sbCommitment
Get the final state and ballot commitment
Return Values
| Name | Type | Description |
|---|
verifier
contract IVerifier verifier
verifyingKeysRegistry
contract IVerifyingKeysRegistry verifyingKeysRegistry
poll
contract IPoll poll
messageProcessor
contract IMessageProcessor messageProcessor
mode
enum DomainObjs.Mode mode
tallyResults
mapping(uint256 => struct ITally.TallyResult) tallyResults
totalTallyResults
uint256 totalTallyResults
Get the total number of tally results
Return Values
| Name | Type | Description |
|---|
totalSpent
uint256 totalSpent
Get the total spent voice credits
Return Values
| Name | Type | Description |
|---|
ResultAdded
event ResultAdded(uint256 voteOptionIndex, uint256 tallyResult)
events
ProcessingNotComplete
error ProcessingNotComplete()
custom errors
InvalidTallyVotesProof
error InvalidTallyVotesProof()
AllBallotsTallied
error AllBallotsTallied()
NotSupported
error NotSupported()
VotesNotTallied
error VotesNotTallied()
IncorrectSpentVoiceCredits
error IncorrectSpentVoiceCredits()
_initialize
function _initialize() internal
Initializes the contract.
isTallied
function isTallied() public view returns (bool tallied)
Check if all ballots are tallied
Return Values
| Name | Type | Description |
|---|---|---|
| tallied | bool | whether all ballots are tallied |
getTallyResults
function getTallyResults(uint256 index) public view returns (struct ITally.TallyResult)
Get tally results for a specific index
Parameters
| Name | Type | Description |
|---|---|---|
| index | uint256 | The index to query |
Return Values
| Name | Type | Description |
|---|---|---|
| [0] | struct ITally.TallyResult | The tally result |
updateSbCommitment
function updateSbCommitment() public
Update the state and ballot root commitment
tallyVotes
function tallyVotes(uint256 _newTallyCommitment, uint256[8] _proof) public
Verify the result of a tally batch
Parameters
| Name | Type | Description |
|---|---|---|
| _newTallyCommitment | uint256 | the new tally commitment to be verified |
| _proof | uint256[8] | the proof generated after tallying this batch |
getPublicCircuitInputs
function getPublicCircuitInputs(uint256 _batchStartIndex, uint256 _newTallyCommitment) public view returns (uint256[] publicInputs)
Get public circuit inputs.
Parameters
| Name | Type | Description |
|---|---|---|
| _batchStartIndex | uint256 | the batch start index |
| _newTallyCommitment | uint256 | the new tally commitment to be verified |
Return Values
| Name | Type | Description |
|---|---|---|
| publicInputs | uint256[] | public circuit inputs |
verifyTallyProof
function verifyTallyProof(uint256 _batchStartIndex, uint256 _newTallyCommitment, uint256[8] _proof) public view returns (bool isValid)
Verify the tally proof using the verifying key
Parameters
| Name | Type | Description |
|---|---|---|
| _batchStartIndex | uint256 | the batch start index |
| _newTallyCommitment | uint256 | the new tally commitment to be verified |
| _proof | uint256[8] | the proof generated after processing all messages |
Return Values
| Name | Type | Description |
|---|---|---|
| isValid | bool | whether the proof is valid |
computeMerkleRootFromPath
function computeMerkleRootFromPath(uint8 _depth, uint256 _index, uint256 _leaf, uint256[][] _pathElements) internal pure returns (uint256 current)
Compute the merkle root from the path elements and a leaf
Parameters
| Name | Type | Description |
|---|---|---|
| _depth | uint8 | the depth of the merkle tree |
| _index | uint256 | the index of the leaf |
| _leaf | uint256 | the leaf |
| _pathElements | uint256[][] | the path elements to reconstruct the merkle root |
Return Values
| Name | Type | Description |
|---|---|---|
| current | uint256 | The merkle root |
verifySpentVoiceCredits
function verifySpentVoiceCredits(uint256 _totalSpent, uint256 _totalSpentSalt, uint256 _resultCommitment, uint256 _perVoteOptionSpentVoiceCreditsHash) public view returns (bool isValid)
Verify the number of spent voice credits from the tally.json
Parameters
| Name | Type | Description |
|---|---|---|
| _totalSpent | uint256 | spent field retrieved in the totalSpentVoiceCredits object |
| _totalSpentSalt | uint256 | the corresponding salt in the totalSpentVoiceCredit object |
| _resultCommitment | uint256 | hashLeftRight(merkle root of the results.tally, results.salt) in tally.json file |
| _perVoteOptionSpentVoiceCreditsHash | uint256 | only for QV - hashLeftRight(merkle root of the no spent voice credits, salt) |
Return Values
| Name | Type | Description |
|---|---|---|
| isValid | bool | Whether the provided values are valid |
verifyQvSpentVoiceCredits
function verifyQvSpentVoiceCredits(uint256 _totalSpent, uint256 _totalSpentSalt, uint256 _resultCommitment, uint256 _perVoteOptionSpentVoiceCreditsHash) internal view returns (bool isValid)
Verify the number of spent voice credits for QV from the tally.json
Parameters
| Name | Type | Description |
|---|---|---|
| _totalSpent | uint256 | spent field retrieved in the totalSpentVoiceCredits object |
| _totalSpentSalt | uint256 | the corresponding salt in the totalSpentVoiceCredit object |
| _resultCommitment | uint256 | hashLeftRight(merkle root of the results.tally, results.salt) in tally.json file |
| _perVoteOptionSpentVoiceCreditsHash | uint256 | hashLeftRight(merkle root of the no spent voice credits per vote option, salt) |
Return Values
| Name | Type | Description |
|---|---|---|
| isValid | bool | Whether the provided values are valid |
verifyNonQvSpentVoiceCredits
function verifyNonQvSpentVoiceCredits(uint256 _totalSpent, uint256 _totalSpentSalt, uint256 _resultCommitment) internal view returns (bool isValid)
Verify the number of spent voice credits for Non-QV from the tally.json
Parameters
| Name | Type | Description |
|---|---|---|
| _totalSpent | uint256 | spent field retrieved in the totalSpentVoiceCredits object |
| _totalSpentSalt | uint256 | the corresponding salt in the totalSpentVoiceCredit object |
| _resultCommitment | uint256 | hashLeftRight(merkle root of the results.tally, results.salt) in tally.json file |
Return Values
| Name | Type | Description |
|---|---|---|
| isValid | bool | Whether the provided values are valid |
verifyPerVoteOptionSpentVoiceCredits
function verifyPerVoteOptionSpentVoiceCredits(uint256 _voteOptionIndex, uint256 _spent, uint256[][] _spentProof, uint256 _spentSalt, uint8 _voteOptionTreeDepth, uint256 _spentVoiceCreditsHash, uint256 _resultCommitment) public view returns (bool isValid)
Return Values
| Name | Type | Description |
|---|---|---|
| isValid | bool | Whether the provided proof is valid |
verifyTallyResult
function verifyTallyResult(uint256 _voteOptionIndex, uint256 _tallyResult, uint256[][] _tallyResultProof, uint256 _tallyResultSalt, uint8 _voteOptionTreeDepth, uint256 _spentVoiceCreditsHash, uint256 _perVoteOptionSpentVoiceCreditsHash) public view returns (bool isValid)
Verify the result generated from the tally.json
Parameters
| Name | Type | Description |
|---|---|---|
| _voteOptionIndex | uint256 | the index of the vote option to verify the correctness of the tally |
| _tallyResult | uint256 | Flattened array of the tally |
| _tallyResultProof | uint256[][] | Corresponding proof of the tally result |
| _tallyResultSalt | uint256 | the respective salt in the results object in the tally.json |
| _voteOptionTreeDepth | uint8 | depth of the vote option tree |
| _spentVoiceCreditsHash | uint256 | hashLeftRight(number of spent voice credits, spent salt) |
| _perVoteOptionSpentVoiceCreditsHash | uint256 | hashLeftRight(merkle root of the no spent voice credits per vote option, perVoteOptionSpentVoiceCredits salt) |
Return Values
| Name | Type | Description |
|---|---|---|
| isValid | bool | Whether the provided proof is valid |
addTallyResults
function addTallyResults(struct ITally.AddTallyResultsArgs args) public virtual
Add and verify tally results by batch.
Parameters
| Name | Type | Description |
|---|---|---|
| args | struct ITally.AddTallyResultsArgs | add tally result args |
addTallyResult
function addTallyResult(uint256 _voteOptionIndex, uint256 _tallyResult, uint256[][] _tallyResultProof, uint256 _tallyResultSalt, uint256 _spentVoiceCreditsHash, uint256 _perVoteOptionSpentVoiceCreditsHash, uint8 _voteOptionTreeDepth) internal virtual
Add and verify tally votes and calculate sum of tally squares for alpha calculation.
Parameters
| Name | Type | Description |
|---|---|---|
| _voteOptionIndex | uint256 | Vote option index. |
| _tallyResult | uint256 | The results of vote tally for the recipients. |
| _tallyResultProof | uint256[][] | Proofs of correctness of the vote tally results. |
| _tallyResultSalt | uint256 | the respective salt in the results object in the tally.json |
| _spentVoiceCreditsHash | uint256 | hashLeftRight(number of spent voice credits, spent salt) |
| _perVoteOptionSpentVoiceCreditsHash | uint256 | hashLeftRight(root of noSpentVoiceCreditsPerVoteOption, perVoteOptionSpentVoiceCredits) |
| _voteOptionTreeDepth | uint8 | vote option tree depth |