Adds architecture and steps documentation

Author: nkcr

README.md

@@ -62,9 +62,9 @@
 
 **D-Voting** is an e-voting platform based on the
 [Dela](https://github.com/dedis/dela) blockchain. It uses state-of-the-art
-protocols that guarantee a fully decentralized process. This project was born in
-early 2021 and has been iteratively implemented by EPFL student under the
-supervision of DEDIS members.
+protocols that guarantee privacy of votes and a fully decentralized process.
+This project was born in early 2021 and has been iteratively implemented by EPFL
+students under the supervision of DEDIS members.
 
 ⚠️ This project is still under developpment and should not be used for real
 elections.
@@ -77,11 +77,11 @@ Main properties of the system are the following:
 </div>
 
 **No single point of failure** The system is supported by a decentralized
-network of blockchain nodes, making no single party able to take over the
-network without compromising a Byzantine threshold of nodes. Additionally,
+network of blockchain nodes, making no single party able to break the system
+without compromising a Byzantine threshold of nodes. Additionally,
 side-protocols always distribute trust among nodes: The distributed key
 generation protocol (DKG) ensures that a threshold of honest node is needed to
-decrypt a vote, and the shuffling protocol needs at least one honest node to
+decrypt ballots, and the shuffling protocol needs at least one honest node to
 ensure privacy of voters. Only the identification and authorization mechanism
 make use of a central authority, but can accommodate to other solutions. 
 
@@ -92,9 +92,9 @@ make use of a central authority, but can accommodate to other solutions.
 
 **Privacy** Ballots are cast on the client side using a safely-held distributed
 key-pair. The private key cannot not be revealed without coercing a threshold of
-nodes, and the public key can be retrieved on any node the voter trusts. Ballots
-are decrypted only once a cryptographic process ensured that cast ballots cannot
-be linked to the original voter.
+nodes, and voters can retrieve the public key on any node. Ballots are decrypted
+only once a cryptographic process ensured that cast ballots cannot be linked to
+the original voter.
 
 <div align="center">
     <img height="50px" src="docs/assets/audit-black.png#gh-light-mode-only">
@@ -109,40 +109,190 @@ and auditors can witness the election process.
 
 ## 🧩 Global architecture
 
-Find more about the architecture on the [documentation
-website](https://dedis.github.io/d-voting/#/).
+The project has 4 main high-level components:
+
+**Blockchain node** A blockchain node is the wide definition of the program that
+runs on a host and participate in the election logic. The blockchain node is
+built on top of Dela with an additional d-voting smart contract, proxy, and two
+services: DKG and verifiable Shuffling. The blockchain node is more accurately a
+subsystem, as it wraps many other components. Blockchain nodes communicate
+through gRPC with the [minogrpc][minogrpc] network overlay. We sometimes refer
+to the blockchain node simply as a "node".
+
+**Proxy** A proxy enables external interactions on a blockchain node. It is a
+component of the blockchain node that exposes HTTP endpoints for external
+entities to send commands to the node. The proxy is notably used by the web
+clients to use the election system.
+
+**Web frontend** The web frontend is a web app built with React. It offers a
+view for end-users to use the D-Voting system. The app is meant to be used by
+voters and admins. Admins can perform administrative tasks such as creating an
+election, closing it, or revealing the results. Depending on the task, the web
+frontend will directly send HTTP requests to the proxy of a blockchain node, or
+to the web-backend.
+
+**Web backend** The web backend handles authentication and authorization. Some
+requests that need specific authorization are relayed from the web-frontend to
+the web-backend. The web backend checks the requests and signs messages before
+relaying them to the blockchain node, which trusts the web-backend. The
+web-backend has a local database to store configuration data such as
+authorizations. Admins use the web-frontend to perform update.
+
+The following component diagrams summarizes the interaction between those
+high-level components.
+
+[minogrpc]: https://github.com/dedis/dela/tree/master/mino/minogrpc
 
 ![Global component diagram](http://www.plantuml.com/plantuml/proxy?src=https://raw.githubusercontent.com/dedis/d-voting/main/docs/assets/component-global.puml)
 
+You can find more information about the architecture on the [documentation
+website](https://dedis.github.io/d-voting/#/).
+
+## Workflow
+
+An election follows a specific workflow to ensure privacy of votes. You can
+find more about it in the
+[documentation](https://dedis.github.io/d-voting/#/api?id=signed-requests), but
+here is a high-level recap.
+
+Once an election is created and open, there are 4 main steps from the cast of a
+ballot to getting the result of the election:
+
+<div align="center">
+    <img height="55px" src="docs/assets/encrypt-black.png#gh-light-mode-only">
+    <img height="55px" src="docs/assets/encrypt-white.png#gh-dark-mode-only">
+</div>
+
+**1) Create ballot** The voter get the shared public key and encrypts locally
+its ballot. The shared public key can be retrieved on any node and is associated
+to a private key that is distributed among the nodes. This process is done on
+the client's browser using the web-frontend.
+
+<div align="center">
+    <img height="80px" src="docs/assets/cast-black.png#gh-light-mode-only">
+    <img height="80px" src="docs/assets/cast-white.png#gh-dark-mode-only">
+</div>
+
+**2) Cast ballot** The voter submits its encrypted ballot as a transaction to one
+of the blockchain node. This operation is relayed by the web-backend which
+verifies that the voters has the right to vote. If successful, the encrypted
+ballot is stored on the blockchain. At this stage each encrypted ballot is
+recorded with its user on the blockchain.
+
+<div align="center">
+    <img height="70px" src="docs/assets/shuffle-black.png#gh-light-mode-only">
+    <img height="70px" src="docs/assets/shuffle-white.png#gh-dark-mode-only">
+</div>
+
+**3) Shuffle ballots** Once the election is closed by an admin, ballots are
+shuffled to ensure privacy of voters. This operation is done by a threshold of
+node that each perform their own shuffling. Each shuffling guaranty the
+integrity of votes while re-encrypting and changing the order of votes. At this
+stage encrypted ballots cannot ne linked back to their voters.
+
+<div align="center">
+    <img height="90px" src="docs/assets/reveal-black.png#gh-light-mode-only">
+    <img height="90px" src="docs/assets/reveal-white.png#gh-dark-mode-only">
+</div>
+
+**4) Reveal ballots** Once ballots have been shuffled, they are decrypted and
+revealed. This operation is done only if the previous step is correctly
+executed. The decryption is done by a threshold of nodes that must each provide
+a contribution to achieve the decryption. Once done, the result of the election
+is stored on the blockchain.
+
+## Smart contract
+
+A smart contract is a piece of code that runs on a blockchain. It defines a set
+of operations that act on a global state (think of it as database) and can be
+triggered with transactions. What makes a smart contract special is that its
+executions depends on a consensus among blockchain nodes and operations are
+successful only if a consensus is reached. Additionally, transactions and their
+results are permanently recorded and signed on an append-only ledger, making any
+operations on the blockchain transparent and permanent.
+
+In the D-Voting system a single D-Voting smart contract handles the elections.
+The smart contract ensures that elections follow a correct workflow to
+guarantees its desirable properties such as privacy. For example, the smart
+contract won't allow ballots to be decrypted if they haven't been shuffled by a
+threshold of nodes before.
+
+## Services
+
+Apart from executing smart contracts, blockchain nodes need additional side
+services to support an election. Side services can read from the global state
+and send transactions. They are used to perform specific protocol executions not
+directly related to blockchain protocols such as the distributed key generation
+(DKG) and verifiable shuffling protocols.
+
+### DKG
+
+DKG stands for Distributed Key Generation. This service allows the creation of a
+key-pair that is distributed among multiple participants. Data encrypted with
+the key-pair can only be decrypted with the contribution of a threshold of
+participants. This makes it convenient to distribute trust on encrypted data.
+In the D-Voting project we use the Pedersen [[1]] version of DKG.
+
+The DKG service needs to be setup at the beginning of each new election - we
+want each election to have its own key-pair. Doing the setup requires two steps:
+1\) Initialization and 2\) Setup. The initialization creates a new RPC for nodes
+to communicate and must be done on each node. The second step, setup, must be
+executed on one of the node. The setup step starts the DKG protocol and
+generates the key-pair. Once done, the D-Voting smart contract can be called to
+open the election, which will retrieve the DKG public key and save it on the
+smart contract.
+
+[1]: https://dl.acm.org/doi/10.5555/1754868.1754929
+
+### Verifiable shuffling
+
+The shuffling service ensures that encrypted votes can not be linked to their
+voters. Once the service is setup, each node can perform what we call a
+"shuffling step". A shuffling step re-orders an array of elements such that
+integrity of the elements is guarantee (i.e no elements have been modified,
+added, or removed), but one can't trace how elements have been re-ordered. 
+
+In D-Voting we use the Neff [[2]] implementation of verifiable shuffling. Once
+an election is closed, an admin can trigger the shuffling steps from the nodes.
+During this phase, every node perform a shuffling on the current list of
+encrypted ballots and try to submit it to the D-Voting smart contract. The smart
+contract will accept only one shuffling step per block, and nodes repeat their
+shuffling step with the latest shuffled list until their shuffling step has not
+been accepted and a threshold of nodes has not been reached.
+
+[2]: https://dl.acm.org/doi/10.1145/501983.502000
+
 ## 📁 Folders structure
 
-```
+<pre>
+<code>
 .
 ├── cli    
-│   ├── cosipbftcontroller
-│   ├── dvoting    
-│   ├── memcoin      
-│   └── postinstall     
-├── contracts           
-│   └── evoting      
-├── deb-package            
-├── docs       
-├── integration
-├── internal            
+│   ├── cosipbftcontroller  Custom initialization of the blockchain node
+│   ├── <b>memcoin</b>             Build the node CLI
+│   └── postinstall         Custom node CLI setup
+├── <b>contracts</b>           
+│   └── <b>evoting</b>             D-Voting smart contract
+│       └── controller      CLI commands for the smart contract
+├── deb-package             Debian package for deployment
+├── docs                    Documentation 
+├── integration             Integration tests
+├── internal                Internal packages: testing, tooling, tracing
 ├── metrics             
-│   └── controller   
-├── proxy      
-├── services    
+│   └── controller          CLI commands for Prometheus
+├── proxy                   Defines and implements HTTP handlers for the REST API
+├── <b>services</b>
 │   ├── dkg  
-│   │   └── pedersen  
+│   │   └── <b>pedersen</b>        Implementation of the DKG service
 │   └── shuffle   
-│       └── neff   
-└── web 
-    ├── backend  
-    │   └── src   
-    └── frontend   
-        └── src   
-```
+│       └── <b>neff</b>            Implementation of the shuffle service
+└── <b>web</b>
+    ├── <b>backend</b>
+    │   └── src             Source of the web backend
+    └── <b>frontend</b>
+        └── src             Sources of the web frontend
+</pre>
+</code>
 
 ## 👩‍💻👨‍💻 Contributors