This section of the book describes how nodes participating in the DarkFi blockchain achieve consensus.


ConsensusAlgorithm for reaching blockchain consensus between participating nodes
Node/ValidatorDarkFi daemon participating in the network
MinerBlock producer
Unproposed TransactionTransaction that exists in the memory pool but has not yet been included in a proposal
Block proposalBlock that has not yet been appended onto the canonical blockchain
P2P networkPeer-to-peer network on which nodes communicate with each other
FinalizationState achieved when a block and its contents are appended to the canonical blockchain
ForkChain of block proposals that begins with the last block of the canonical blockchain
MAX_INTThe maximum 32 bytes (256 bits) integer 2^256 − 1

Miner main loop

DarkFi uses RandomX Proof of Work algorithm with enforced finality. Therefore, block production involves the following steps:

  • First, a miner grabs its current best ranking fork and extends it with a block composed of unproposed transactions from the miner's mempool.

  • Then the miner tries to find a nonce such that when the block header is hashed its bytes produce a number that is less than the current difficulty target of the network, using the RandomX mining algorithm.

  • Once the miner finds such a nonce, it broadcasts its block proposal to the P2P network. Finally the miner triggers a finalization check to see if its newly extended fork can be finalized.


loop {
    fork = find_best_fork()

    block = generate_next_block(fork)





Listening for block proposals

Each node listens for new block proposals on the P2P network. Upon receiving block proposals, nodes try to extend the proposals onto a fork held in memory (this process is described in the next section). Then nodes trigger a finalization check to see if their newly extended fork can be finalized.

Upon receiving a new block proposal, miners also check if the extended fork rank is better than the one they are currently trying to extend. If the fork rank is better, the miner will stop mining its proposal and start mining the new best fork.


Each block proposal is ranked based on how hard it is to produce. To measure that, we compute the squared distance of its height target from MAX_INT. For two honest nodes that mine the next block height of the highest ranking fork, their block will have the same rank. To mitigate this tie scenario, we also compute the squared distance of the blocks RandomX hash from MAX_INT, allowing us to always chose the actual higher ranking block for that height, in case of ties. The complete block rank is a tuple containing both squared distances.

Proof of Work algorithm lowers the difficulty target as hashpower grows. This means that blocks will have to be mined for a lower target, therefore rank higher, as they go further away from MAX_INT.

Similar to blocks, blockchain/forks rank is a tuple, with the first part being the sum of its block's squared target distances, and the second being the sum of their squared hash distances. Squared distances are used to disproportionately favors smaller targets, with the idea being that it will be harder to trigger a longer reorg between forks. When we compare forks, we first check the first sum, and if its tied, we use the second as the tie breaker, since we know it will be statistically unique for each sequence.

The ranking of a fork is always increasing as new blocks are appended. To see this, let be a fork with a finite sequence of blocks of length . The rank of a fork is calculated as Let of length be the fork created by appending the block to . Then we see that since for all .

Fork extension

Since there can be more than one block producer, each node holds a set of known forks in memory. Nodes extend the best ranking fork in memory when producing a block.

Upon receiving a block, one of the following cases may occur:

Block extends a known fork at its endAppend block to fork
Block extends a known fork not at its endCreate a new fork up to the extended block and append the new block
Block extends canonical blockchain at its endCreate a new fork containing the new block
Block doesn't extend any known chainIgnore block

Visual Examples

[C]Canonical (finalized) blockchain block
[C]--...--[C]Sequence of canonical blocks
[Mn]Proposal produced by Miner n
FnFork name to identify them in examples
+--Appending a block to fork
/--Dropped fork

Starting state:

               |--[M0] <-- F0
               |--[M1] <-- F1

Blocks on same Y axis have the same height.

Case 1

Extending F0 fork with a new block proposal:

               |--[M0]+--[M2] <-- F0
               |--[M1]        <-- F1

Case 2

Extending F0 fork at [M0] block with a new block proposal, creating a new fork chain:

               |--[M0]--[M2]   <-- F0
               |--[M1]         <-- F1
               |+--[M0]+--[M3] <-- F2
Case 3

Extending the canonical blockchain with a new block proposal:

               |--[M0]--[M2] <-- F0
               |--[M1]       <-- F1
               |--[M0]--[M3] <-- F2
               |+--[M4]      <-- F3


Based on the rank properties, each node will diverge to the highest ranking fork, and new fork wil emerge extending that at its tips. A security threshold is set, which refers to the height where the probability to produce a fork, able to reorg the current best ranking fork reaches zero, similar to the # of block confirmation used by other PoW based protocols.

When the finalization check kicks in, each node will grab its best fork. If the fork's length exceeds the security threshold, the node will push (finalize) its first proposal to the canonical blockchain. The fork acts as a queue (buffer) for the to-be-finalized proposals.

Once a finalization occurs, all the fork chains not starting with the finalized block(s) are removed from the node's memory pool.

We continue Case 3 from the previous section to visualize this logic.

The finalization threshold used in this example is 3 blocks. A node observes 2 proposals. One extends the F0 fork and the other extends the F2 fork:

               |--[M0]--[M2]+--[M5] <-- F0
               |--[M1]              <-- F1
               |--[M0]--[M3]+--[M6] <-- F2
               |--[M4]              <-- F3

Later, the node only observes 1 proposal, extending the F2 fork:

               |--[M0]--[M2]--[M5]        <-- F0
               |--[M1]                    <-- F1
               |--[M0]--[M3]--[M6]+--[M7] <-- F2
               |--[M4]                    <-- F3

When the finalization sync period starts, the node finalizes block M0 and keeps the forks that extend that:

               |--[M0]--[M2]--[M5]       <-- F0
               |/--[M1]                  <-- F1
               |--[M0]--[M3]--[M6]--[M7] <-- F2
               |/--[M4]                  <-- F3

The canonical blockchain now contains blocks M0 and the current state is:

               |--[M2]--[M5]       <-- F0
               |--[M3]--[M6]--[M7] <-- F2

Appendix: Data Structures

This section gives further details about the high level structures that will be used by the protocol.

Note that for hashes, we define custom types like TransactionHash, but here we will just use the raw byte representation [u8; 32].

block_indexu32Block height
tx_indexu16Index of a tx within a block
call_indexu8Index of contract call within a single tx

u32 can store 4.29 billion blocks, which with a 90 second blocktime corresponds to 12.2k years.

u16 max value 65535 which is far above the expected limits. By comparison the tx in Bitcoin with the most outputs has 2501.

versionu8Block version
previous[u8; 32]Previous block hash
heightu32Block height
timestampu64Block creation timestamp
nonceu64The block's nonce value
tree_root[u8; 32]Merkle tree root of the block's transactions hashes


header[u8; 32]Block header hash
txsVec<[u8; 32]Transaction hashes
signatureSignatureBlock producer signature


blocksVec<Block>Series of blocks consisting the Blockchain
modulePoWModuleBlocks difficulties state used by RandomX


chainBlockchainForks current blockchain state
proposalsVec<[u8; 32]Fork proposal hashes sequence
mempoolVec<[u8; 32]Valid pending transaction hashes


canonicalBlockchainCanonical (finalized) blockchain
forksVec<Blockchain>Fork chains containing block proposals

Appendix: Ranking Blocks


Denote blocks by the symbols , then a sequence of blocks (alternatively a fork) is an ordered series .

Use for all sets of sequences for blocks in .

Properties for Rank

Each block is associated with a target where .

  1. Blocks with lower targets are harder to create and ranked higher in a sequence of blocks.
  2. Given two competing forks and , we wish to select a winner. Assume is the winner, then .
  3. There should only ever be a single winner. When , then we have logic to break the tie.

Property (2) can also be statistically true for .

This is used to define a fork-ranking function . This function must always have unique values for distinct sequences.


We also would like the property is additive on subsequences which allows comparing forks from any point within the blockchain. For example let be the blockchain together with forks extending into and . Then we have that which means it's sufficient to compare and directly.

Proposed Rank

With a PoW mining system, we are guaranteed to always have that the block hash . Since the block hashes for a sequence have the property that , as well as being sufficiently random, we can use them to define our work function.

Because is required to be additive, we define a block work function , and .

The block work function should have a statistically higher score for blocks with a smaller target, and always be distinct for unique blocks. We define as since this function is well defined on the codomain.

Hash Function

Let be a fixed subset of representing the output of a hash function .

Definition: a hash function is a function having the following properties:

  1. Uniformity, for any and any , there exists an such that .
  2. One-way, for any , we are unable to construct an such that .

Note: the above notions rely on purely algebraic properties of without requiring the machinery of probability. The second property of being one-way is a stronger notion than being statistically random. Indeed if the probability is non-zero then we could find such an which breaks the one-way property.

Theorem: given a hash function as defined above, it's impossible to construct two distinct sequences and such that .

By property (2), we cannot find a . Again by (2), we cannot construct an such that for any . Recursive application of (2) leads us to the stated theorem.