@@ 1,25 1,56 @@
# tallyard
tallyard is an authenticated voting system that ensures voter privacy while
-preventing double-voting. Voter privacy is achieved via the homomorphic secret
-sharing system outlined
+preventing double-voting.
+
+A voter can be any user on the [Matrix](https://matrix.org) 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](https://en.wikipedia.org/wiki/Homomorphic_secret_sharing#Example:_decentralized_voting_protocol)
-and double-voting is prevented by a STARKs zero-knowledge proof as described
-[here](https://vitalik.ca/general/2017/11/09/starks_part_1.html). Voters'
-computers communicate with each other directly over a peer-to-peer network.
-While there is a "master" node that decides what the candidates of the election
-are, it does not have any privileges once voting begins.
+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](https://vitalik.ca/general/2017/11/09/starks_part_1.html) 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](https://gitlab.com/edwargix/tallyard/-/raw/master/doc/oresec-talk/tallyard.pdf)
-I gave for my university's cybersecurity club for an overview of the
-mathematics.
+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](https://matrix.org/blog/2020/06/02/introducing-p-2-p-matrix) becomes
+more of a reality down the road.
-The zero-knowledge implementation is not entirely finished.
+# Work-in-progress
-tallyard is very much a work-in-progress and is only useful for elections where
-everyone is voting simultaneously, such as a club election, which it was
-actually used for.
+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](https://semver.org) 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
# Installation
@@ 39,47 70,47 @@ $ yay -S tallyard-git
## From Source
-Ensure you have the [Go](https://golang.org) programming language
-installed. Then:
+Ensure you have the [Go](https://golang.org) programming language installed.
+Then:
```sh
$ git clone https://gitlab.com/edwargix/tallyard
$ cd tallyard
$ make
-$ # the tallyard binary is now at ./tallyard
+$ ./tallyard
```
# Usage
-Once every voter wishing to participate in the election has tallyard installed,
-everyone should run it:
+Every voter must have a Matrix account. Once everyone wishing to participate in
+an election has tallyard installed, everyone should run it with
```sh
$ tallyard
```
-One voter, henceforth called "the master", will then choose "Create Election",
-enter the candidates of the election, and share the printed "election key" with
-everyone else[^1]. Every voter who is not the master will instead select "Join
-Election" and paste the "election key" provided by the master. Voting will
-begin once the master hits the enter key. However, the master should only do so
-once he has received confirmation of a connection from all of the other voters.
+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]: preferably over a secure medium
+[^1]: You cannot join rooms from within tallyard; use a more featureful Matrix
+ client like [Element](https://element.io) to do so.
# Why Go?
- concurrency
-- [libp2p](https://libp2p.io)
+- simplicity
+- elegance
+- [mautrix-go](https://github.com/tulir/mautrix-go)
# Future Work
-- Support authentication systems. First on the list is
- [Matrix](https://matrix.org/) accounts. Those who used the old client written
- in Racket will know that authentication used to be possible; the transition
- just hasn't been made yet.
-- [Matrix](https://matrix.org) bots for voting on topics in matrix chat rooms.
-- Finish the zero-knowledge proof implementation.
+- [Matrix](https://matrix.org) bots for periodically voting on topics in Matrix
+ rooms.
# Stuck? Have suggestions or feedback?