From 7fe0c6ea9b184ed2e538577f7297cbfac35af651 Mon Sep 17 00:00:00 2001
From: David Florness <david@florness.com>
Date: Mon, 18 May 2020 20:30:04 -0600
Subject: [PATCH] README

---
 README.md | 106 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 106 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..620a4d2
--- /dev/null
+++ b/README.md
@@ -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.
-- 
2.38.4