@@ 0,0 1,106 @@
+# 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
+[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).
+
+The zero-knowledge implementation is not entirely finished. All of this is
+planned to be done over a peer-to-peer network; however, at the moment there is a
+centralized "bulletin" that relays traffic between peers.
+
+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](https://mailman.mines.edu/pipermail/lug/2020-April/000573.html).
+
+# Usage
+
+Ensure you have the [Racket](https://racket-lang.org) programming language
+installed. Then, install tallyard's dependencies:
+
+```sh
+$ cd /path/to/tallyard/repo
+$ raco pkg install
+```
+
+## Bulletin
+
+The bulletin is a simple Racket-powered RESTful HTTP server to which voters
+(i.e. peers) connect to participate in an election. As the bulletin is running,
+it can be given commands to alter the election.
+
+If you with to run the bulletin, you need to setup a host with an HTTP endpoint
+that accepts a JSON body containing "username" and "password" keys and returns
+the JSON string "success" if the corresponding "username" and "password" values
+correspond to a valid login.
+
+In the following code in bulletin.rkt, replace "AUTH-HOST-HERE" with the
+aforementioned host and "/auth/route/here" with the endpoint. I realize this is
+cumbersome, and I plan to provide an easier way to configure this.
+
+```racket
+(define (auth username password)
+ (equal? (hash-ref
+ (json-response-body
+ (post (update-ssl (update-host json-requester
+ "AUTH-HOST-HERE")
+ #t)
+ "/auth/route/here"
+ #:data
+ (jsexpr->string (hasheq 'username username
+ 'password password))))
+ 'result)
+ "success"))
+```
+
+The bulletin can then be started with
+
+```sh
+$ racket bulletin.rkt
+```
+
+## Voter client
+
+If you're a voter who wants to participate, do
+
+```sh
+$ racket client.rkt
+```
+
+and enter the correct bulletin host and login information when prompted.
+
+# Why Racket?
+
+I've always had a soft spot for LISPs[^1] and needed an excuse to try [Typed
+Racket](https://docs.racket-lang.org/ts-guide/). tallyard began as a quick
+hackathon project, but turned into the project I worked on in my free time once
+I became obsessed.
+
+[^1]: I still don't know why
+
+However, Racket is not the ideal language for networking and fast cryptography.
+Defining functional tree-like structures (like Merkle trees) in Racket is quite
+ugly without something like [recursion
+schemes](https://blog.sumtypeofway.com/posts/introduction-to-recursion-schemes.html),
+which are not implemented in Racket yet.
+
+# Future Work
+
+- utilize [libp2p](https://libp2p.io/) for peer-to-peer networking. This will
+ require either rewriting tallyard it Golang or using FFIs.
+- support multiple authentication systems. First on the list is [Matrix](https://matrix.org/)
+- [Matrix](https://matrix.org/) bots for voting on topics in matrix chat rooms
+- finish the zero-knowledge proof implementation
+
+# 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.