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
TallyResult
Tally results
struct TallyResult {
uint256 value;
bool flag;
}
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: 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
sbCommitment
uint256 sbCommitment
verifier
contract IVerifier verifier
vkRegistry
contract IVkRegistry vkRegistry
poll
contract IPoll poll
messageProcessor
contract IMessageProcessor messageProcessor
mode
enum DomainObjs.Mode mode
tallyResults
mapping(uint256 => struct Tally.TallyResult) tallyResults
totalTallyResults
uint256 totalTallyResults
totalSpent
uint256 totalSpent
ProcessingNotComplete
error ProcessingNotComplete()
custom errors
InvalidTallyVotesProof
error InvalidTallyVotesProof()
AllBallotsTallied
error AllBallotsTallied()
NumSignUpsTooLarge
error NumSignUpsTooLarge()
BatchStartIndexTooLarge
error BatchStartIndexTooLarge()
TallyBatchSizeTooLarge
error TallyBatchSizeTooLarge()
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 |
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 _perVOSpentVoiceCreditsHash) 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 |
| _perVOSpentVoiceCreditsHash | 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 _perVOSpentVoiceCreditsHash) 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 |
| _perVOSpentVoiceCreditsHash | 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 |
verifyPerVOSpentVoiceCredits
function verifyPerVOSpentVoiceCredits(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 _perVOSpentVoiceCreditsHash) 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) |
| _perVOSpentVoiceCreditsHash | uint256 | hashLeftRight(merkle root of the no spent voice credits per vote option, perVOSpentVoiceCredits 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 _perVOSpentVoiceCreditsHash, 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) |
| _perVOSpentVoiceCreditsHash | uint256 | hashLeftRight(root of noSpentVoiceCreditsPerVoteOption, perVOSpentVoiceCredits) |
| _voteOptionTreeDepth | uint8 | vote option tree depth |