darkfi/doc/src/architecture/dna.md

DarkFi Node Architecture (DNA)

The DarkFi ecosystem runs as a network of P2P nodes, where these nodes interact with each other over specific programs (or layers). In this section, we'll explain how each of the layers 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.