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:
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 (
and the layer below (
An abstract view of the network looks like the following:
[drk] <--> [darkfid] <--> [validatord] <-+ | [drk] <--> [darkfid] <--> [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.
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:
- Wait for a transaction
- Validate incoming transaction (and go back to 1. if invalid)
- Broadcast transaction to other validators in the network
- Other validators validate transaction (and go back to 1. if invalid)
- Leader validates the state transition and proposes a block
- Consensus-participating nodes validate the state transition and vote on the proposed block if the state transition is valid.
- If the block is confirmed, it is appended to the blockchain and is replicated between all validators in the network.
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.
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
easily be replaced with more specific tooling, if need be.
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 is a client tool that interacts with
darkfid in a user-friendly
way and provides a command-line interface to the DarkFi network and
The interaction with
darkfid is done over the JSON-RPC protocol
and communicates with the endpoint exposed by