diff --git a/doc/src/SUMMARY.md b/doc/src/SUMMARY.md index c3995a575..d67098296 100644 --- a/doc/src/SUMMARY.md +++ b/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) diff --git a/doc/src/architecture/dna.md b/doc/src/architecture/dna.md new file mode 100644 index 000000000..d843edb7e --- /dev/null +++ b/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`. diff --git a/doc/src/architecture/nodes.md b/doc/src/architecture/nodes.md deleted file mode 100644 index 002d7246c..000000000 --- a/doc/src/architecture/nodes.md +++ /dev/null @@ -1,5 +0,0 @@ -DarkFi nodes -============ - -The core daemon used for wallet management, transaction building, and -general operations is called `darkfid`.