updated README (about, design, etc)

diff --git a/README b/README
index 7117329..b4c986e 100644 (file)
--- a/README
+++ b/README
@@ -1,14 +1,98 @@
 This is the source code repository of the epoint transaction service.
 
-Latest version should be available at
+Source
+------
+
 web:
        http://repo.or.cz/w/epoint-server.git
 git:
        git clone git://repo.or.cz/epoint-server.git
 
-This project is about redesigning the ePoint Transfer Protocol.
-Description and source code of the old design can be found at the
-epointsystem.org website:
+
+Build
+-----
+
+epoint-server depends on a patched version of the latest go source
+to get it (see http://golang.org/doc/install.html for details) run
+       hg clone https://go.googlecode.com/hg/ go
+       cd go/src
+       hg patch path/to/epoint-server/patches/*.diff
+       ./all.bash
+
+to build and install (into $GOROOT/bin) run
+       make
+
+
+Contact
+-------
+
+discuss@epointsystem.org
+TODO: mailing list
+
+
+About
+-----
+
+The goal of the epoint service is to provide secure and efficient
+bookkeeping of transferrable debt denominated in currencies that
+are issued by the anonymous clients of the system themselvs.
+
+The central bookkeeping is designed to be auditable by any client
+and proofs can be constructed in case of errors.
+
+To convert between the various currencies a currency market can
+be used that is outside of the scope of the epoint service.
+
+The agreements and authentication methods between the issuers and
+holders of debt is outside the epoint system as well.
+
+This project originates from the ePoint Transfer Protocol.
+Description about that design is at the epointsystem.org website:
        https://www.epointsystem.org/trac/epoint_issuer
        https://www.epointsystem.org/trac/website
 
+
+Design
+------
+
+An epoint server is a large billboard, where clients can publish
+draft documents (acknowledging debt, "i owe you")
+
+Draft documents are digitally signed by the clients and the
+clients are identified by their public key.
+
+Any client can issue debt (issuer), and a client holding the
+debt (holder) can transfer parts of it to any other client using
+draft documents. A draft specifies the drawer (the client who
+transfers the debt), the beneficiary (the new holder of the
+debt), the issuer (the client who owes) and an integer amount
+that is transferred. The draft is signed by the drawer.
+
+Drafts with different issuers are independent, the debt of
+different issuers are denominated in different currencies and
+cannot be mixed.
+
+The balance of a client with respect to an issuer is the
+agregate value of all the drafts that transfer debt of the given
+issuer to or from the given client.
+
+The main constraint is that a holder cannot transfer more debt
+than its balance. Such drafts are invalid and must be rejected.
+If the issuer is the drawer of a draft then there is no such
+constraint. The balance of the issuer is <=0 and the balance of
+a holder of the issuer's debt is >=0 at any given time. All the
+balances together give 0.
+
+The main purpose of the server is to make it easy to check the
+current balance of a client with respect to an issuer at any
+given time.
+
+To achieve this the server needs to store all the drafts and the
+public keys of the clients so the drafts are verifiable. The
+ordering of the drafts matters when the constraints are checked
+so the server must keep track of the balances in such a way that
+there is no ambiguity. It must be easy to audit the server and
+prove if it does not calculate the balances properly. This is
+done using server signed certificates declaring the balance of
+a client after each change and referencing related documents
+(draft, previous certificates) with cryptographic hash.