book: Add DarkFi Node Architecture (DNA)

doc/src/SUMMARY.md

@@ -6,7 +6,7 @@
 - [Tutorial](tutorial.md)
 - [Architecture](architecture/architecture.md)
   - [Blockchain](architecture/blockchain.md)
-  - [Node design](architecture/nodes.md)
+  - [DNA](architecture/dna.md)
 - [Client](clients/clients.md)
   - [darkfid JSON-RPC API](clients/darkfid_jsonrpc.md)
   - [cashierd JSON-RPC API](clients/cashierd_jsonrpc.md)

doc/src/architecture/dna.md

@@ -0,0 +1,112 @@
+DarkFi Node Architecture (DNA)
+==============================
+
+The DarkFi ecosystem runs as a network of P2P nodes, where these
+nodes interact with each other over specific protocols. Below in
+this document, we'll explain how each of the programs fit together
+and when combined create a functioning network that becomes DarkFi.
+
+The layers are organized as a bottom-up pyramid, much like the
+DarkFi logo:
+
+$$ \setminus validatord / $$
+$$  \setminus darkfid  / $$
+$$   \setminus drk   / $$
+
+We will start with the top-level daemon - `validatord` - which
+serves as the consensus and data storage layer, then we will explain
+`darkfid` and its communication with the layer above (`validatord`),
+and the layer below (`drk`).
+
+An abstract view of the network looks like the following:
+
+```
+[drk] <--> [darkfid] <--> [validatord] <-+
+                                         |
+[drk] <--> [darkfid] <--> [validatord] <-+
+```
+
+
+## validatord
+
+`validatord` is the DarkFi consensus and data storage layer. Everyone
+that runs a validator participates in the network as a data archive,
+and is able to store incoming transactions, and relay them to
+other validators over the P2P network and protocol. Additionally,
+storing this data allows others to replicate it and participate in
+the same way.
+
+Provided there is a locked stake on a running validator, the node
+can also participate in the Proof-of-Stake consensus, enabling the
+ability to vote on incoming transactions rather than just relaying
+(and validating) them.
+
+In case the node is not participating in the consensus, it should still
+relay incoming transactions to other (ideally consensus-participating)
+validators in the network.
+
+### Inner workings
+
+In its database, `validatord` stores transactions and blocks that
+have reached consensus. This is commonly known as a _"blockchain"_.
+The blockchain is a shared state that is replicated between all
+validators in the network.
+
+Additionally, validators keep a pool of incoming transactions
+and proposed blocks, which get validated and voted on by the
+consensus-participating validators.
+
+The lifetime of an incoming transaction (and block) is as follows:
+
+1. Wait for a transaction
+2. Validate incoming transaction (and go back to 1. if invalid)
+3. Broadcast transaction to other validators in the network
+4. Other validators validate transaction (and go back to 1. if invalid)
+5. Leader validates the state transition and proposes a block
+6. Consensus-participating nodes validate the state transition and
+   vote on the proposed block if the state transition is valid.
+7. If the block is confirmed, it is appended to the _blockchain_ and
+   is replicated between all validators in the network.
+
+
+## darkfid
+
+`TODO: Initial sync and retrieving wallet state?`
+
+`darkfid` is the client layer of DarkFi used for wallet management
+and transaction broadcasting. The wallet keeps a history of balances,
+_coins_, _nullifiers_, and _merkle roots_ that are necessary in order
+to create new transactions.
+
+By design, `darkfid` is a light client, since `validatord` stores all
+the blockchain data, and `darkfid` can simply query for anything it
+is interested in. This allows us to avoid data duplication and simply
+utilize our modular architecture. This also means that `darkfid` can
+easily be replaced with more specific tooling, if need be.
+
+### Inner workings
+
+Using the P2P network and protocol, `darkfid` can subscribe to
+`validatord` in order to receive new _nullifiers_ and _merkle roots_
+whenever a new block is confirmed. This allows `darkfid` to update
+its local state and enables it to create new valid transactions.
+
+`darkfid` exposes a JSON-RPC endpoint for clients to interact with it.
+This allows a number of things, such as: listing balances, creating
+and submitting transactions, key management, and more.
+
+When creating a new transactions, `darkfid` uses the local synced state
+in order to create new _coins_ and combine them in a transaction. This
+transaction is then submitted to the above validator layer where the
+transaction will get validated and voted on in order to be included
+into a block.
+
+
+## drk
+
+`drk` is a client tool that interacts with `darkfid` in a user-friendly
+way and provides a command-line interface to the DarkFi network and
+its functionality.
+
+The interaction with `darkfid` is done over the JSON-RPC protocol
+and communicates with the endpoint exposed by `darkfid`.

doc/src/architecture/nodes.md

@@ -1,5 +0,0 @@
-DarkFi nodes
-============
-
-The core daemon used for wallet management, transaction building, and
-general operations is called `darkfid`.