ref: v0.3.0 tallyard/README.md -rw-r--r-- 4.7 KiB
12de6e81 — David Florness Add note in README on git-send-email.io 4 months ago


tallyard is an authenticated voting system that ensures voter privacy while preventing double-voting.

A voter can be any user on the Matrix network. All ballots are tied to specific Matrix users (preventing double-voting), and said users can only participate in elections where they are members of the room in which the election was created. Thus, election participation can be limited to, for instance, members of a club or citizens of a jurisdiction.

Voter privacy is achieved by using the homomorphic secret sharing system outlined here to count the ballots in such a way that no individual user's ballot is revealed to anyone, but the final, aggregate result of the election can still be computed. In short, every voter helps count the ballots, but no individual voter can know anyone's ballot but their own.

STARKs zero-knowledge proofs, as described here by Vitalik Buterin, are used to ensure (with very high probability) that no individual voter has submitted a fraudulent ballot. (Unfortunately, this zero-knowledge proof part of tallyard has not been finished yet.)

Have a look at the presentation I gave for my former university's cybersecurity club for an overview of the aforementioned cryptography.

Because Matrix is an open, federated messaging protocol, it is quite possible for individuals to participate completely anonymously since often nothing more than a username and password is required to create a Matrix user account. This will only be more true once P2P Matrix becomes more of a reality down the road.


tallyard is very much work-in-progress software as it is being actively designed and implemented, and is thus subject to change (though we will try to follow semantic versioning for releases, at least for protocol changes).

tallyard is also currently only useful for elections where everyone is voting nearly simultaneously, and requires a somewhat cumbersome five-step process to conduct an election to completion:

  1. the election is created
  2. voters explicitly "join" the election
  3. the election creator "starts" the election
  4. voters (only those who partook in step 2) submit ballots
  5. everyone helps to calculate the result


#Arch Linux

#Latest Stable Version

$ yay -S tallyard

#HEAD of master

$ yay -S tallyard-git

#From Source

Ensure you have the Go programming language installed. Then:

$ git clone https://gitlab.com/edwargix/tallyard
$ cd tallyard
$ make
$ ./tallyard


Every voter must have a Matrix account. Once everyone wishing to participate in an election has tallyard installed, everyone should run it with

$ tallyard

Everyone will be prompted to enter their Matrix credentials.

Each voter should then select the room where the election will take place (or is taking place)[^1]. One voter should select "Create Election" and enter the election's candidates. Once the election has been created, all other voters should see the election appear in their room UI where they will be able to select the election, join, and vote (once the election's been started).

[^1]: You cannot join rooms from within tallyard; use a more featureful Matrix client like Element to do so.


Please send any patches / suggestions to david.[at].florness.[dot].com. In the future, I will have a mailing list for patches instead. If you've never sent patches with email before, I highly recommend git-send-email.io.

#Why Go?

#Future Work

  • Matrix bots for periodically voting on topics in Matrix rooms.

#Stuck? Have suggestions or feedback?

Join our Matrix room to join the discussion.

If you're unfamiliar with Matrix, you can learn about it and sign up for an account here.

#Origin of the name

"Tillyard" is the last name of the author of the The Elizabethan World Picture, which I read in my phenomenal Shakespeare class. Also, the voting system works by keeping a "tally" of votes in a secretive manner. These two notions together yield "tallyard".

"tallyard" is written in lowercase letters to follow the convention of UNIX executable names being all lowercase.