# tallyard

tallyard is an authenticated voting system that ensures voter privacy while
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)
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.

Jens Groth's zk-SNARK, as described [here](https://z.cash/technology/zksnarks/),
is used to ensure (with very high probability) that a given voter's ballot is
not fraudulent, while revealing zero information about the ballot itself.

Have a look at the
[presentation](https://gitlab.com/edwargix/tallyard/-/raw/master/doc/oresec-talk/tallyard.pdf)
I gave for my former university's cybersecurity club for an overview of the
aforementioned cryptography.  **Note:** some of the info in the slides is very
out-of-date.

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.

# Work-in-progress

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

## Arch Linux

### Latest Stable Version

```sh
$ yay -S tallyard
```

### HEAD of master

```sh
$ yay -S tallyard-git
```

## From Source

Ensure you have the [Go](https://golang.org) programming language installed.
Then:

```sh
$ wget -O tallyard-v0.3.0.tar.gz https://git.hnitbjorg.xyz/~edwargix/tallyard/archive/v0.3.0.tar.gz
$ tar xzf tallyard-v0.3.0.tar.gz
$ cd tallyard-v0.3.0
$ make
$ ./tallyard
```

# Usage

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
```

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](https://element.io) to do so.

# Contributing

Contributions are welcome; thank you!  Please send any patches you come up with
to
[~edwargix/tallyard-dev@lists.hnitbjorg.xyz](mailto:~edwargix/tallyard-dev@lists.hnitbjorg.xyz).

Please send any feature requests / issues to
[~edwargix/tallyard@todo.hnitbjorg.xyz](mailto:~edwargix/tallyard@todo.hnitbjorg.xyz)
or to our [Matrix room](https://matrix.to/#/#tallyard:hnitbjorg.xyz).

Both of these lists are behind a greylisting SMTP server, so it'll take a few
minutes for your first couple of messages to get through.

You should consider everything you submit to these lists public; if you want to
contribute privately, please reach out to me directly with email and PGP or via
a private 1-on-1 Matrix room with me.

If you've never sent patches with email before, I highly recommend
[git-send-email.io](https://git-send-email.io/).

# Why Go?

- concurrency
- simplicity
- elegance
- [mautrix-go](https://github.com/tulir/mautrix-go)

# Future Work

See
[todo.hnitbjorg.xyz/~edwargix/tallyard](https://todo.hnitbjorg.xyz/~edwargix/tallyard).

# Stuck? Have suggestions or feedback?

Join our [Matrix room](https://matrix.to/#/#tallyard:hnitbjorg.xyz) to
participate in the discussion.

If you're unfamiliar with Matrix, you can learn about it and sign up for an
account [here](https://matrix.org).

# 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.