From 8df865337916fbb2caa1c77634d81bc7f084089e Mon Sep 17 00:00:00 2001 From: lunar-mining Date: Wed, 23 Nov 2022 11:48:46 +0100 Subject: [PATCH] book: grammar edit, consensus.md --- doc/src/architecture/consensus.md | 65 +++++++++++++++---------------- 1 file changed, 32 insertions(+), 33 deletions(-) diff --git a/doc/src/architecture/consensus.md b/doc/src/architecture/consensus.md index 14405b877..dc8123d08 100644 --- a/doc/src/architecture/consensus.md +++ b/doc/src/architecture/consensus.md @@ -6,24 +6,25 @@ This section of the book describes how nodes participating in the DarkFi blockch | Name | Description | |------------------------|-------------------------------------------------------------------------------------------| -| Consensus | Algorithm for reaching Blockchain consensus between participating nodes | +| Consensus | Algorithm for reaching blockchain consensus between participating nodes | | Node | darkfid daemon participating in the network | | Slot | Specified timeframe for block production, measured in seconds(default=20) | | Epoch | Specified timeframe for blockchain events, measured in slots(default=10) | | Leader | Block producer | -| Unproposed Transaction | A transaction that exists in nodes memory pool, but have not yet been included in a block | -| P2P network | Peer-To-Peer network all nodes communicate with each other | -| Finalization | Append a Block and its content to canonical blockchain | -| Fork | Chain of unfinalized blocks, starting by the last canonical block of blockchain | +| Unproposed Transaction | Transaction that exists in the memory pool but has not yet been included in a block | +| Block proposal | Block that has not yet been appended onto the canonical blockchain | +| P2P network | Peer-to-peer network on which nodes communicate with eachother | +| Finalization | State achieved when a block and its contents are appended to the canonical blockchain | +| Fork | Chain of unfinalized blocks that begins with the last block of the canonical blockchain | ## Node main loop -As described in previous chapter, DarkFi is based on Ouroboros Crypsinous, therefore, to be able to produce a block, -at slot start each node checks if they are the slots' leader, based on the leader selection algorithm. -If they succeed, they can produce a block containing unproposed transactions, by extending the largest known fork, -and share it with rest nodes, by broadcasting it in the P2P network. -Right before slot end, each node triggers the finalization check, to verify which blocks can be finalized, -also known as finalization sync period. +As described in previous chapter, DarkFi is based on Ouroboros Crypsinous. Therefore, block production involves the following steps: + +At the start of every slot, each node runs a leader selection algorithm to determine if they are the slot's leader. If successful, they can produce a block containing unproposed transactions. This block is then appended to the largest known fork +and shared with rest of the nodes on the P2P network. +Right before the end of every slot each node triggers a _finalization check_, to verify which blocks can be finalized. +This is also known as the finalization sync period. Pseudocode: ``` @@ -47,21 +48,21 @@ loop { ## Listening for blocks -Concurently with the main loop, each node listens to new block proposals, and upon receiving them, -they try to extend a known fork, as described in next section. +Each node listens to new block proposals concurrently with the main loop. Upon receiving block proposals, +nodes try to extend the proposals onto a fork that they hold in memory. This process is described in the next section. ## Fork extension -Since there can be more than one slot leaders, each node holds a set of known forks in memory. -When a node becomes leader, they extend the longest fork they hold. -Upon receiving a block, one of the following cases occur: +Since there can be more than one slot leader, each node holds a set of known forks in memory. +When a node becomes a leader, they extend the longest fork they hold. +Upon receiving a block, one of the following cases may occur: | Description | Handling | |-------------------------------------------|---------------------------------------------------------------------| | Block extends a known fork at its end | Append block to fork | | Block extends a known fork not at its end | Create a new fork up to the extended block and append the new block | | Block extends canonical blockchain | Create a new fork containing the new block | -| Block doesn't extends any known chains | Ignore block | +| Block doesn't extend any known chain | Ignore block | ### Visual Examples @@ -81,7 +82,7 @@ Starting state: #### Case 1 -New proposal received extending L0 fork: +Extending L0 fork with a new block proposal: |--[L0]+--[L2] <-- L0L2 fork [C]--...--[C]--| @@ -89,7 +90,7 @@ New proposal received extending L0 fork: #### Case 2 -New proposal received extending L0L2 fork at [L0] slot: +Extending L0L2 fork at [L0] slot with a new block proposal: |--[L0]--[L2] <-- L0L2 fork [C]--...--[C]--| @@ -99,7 +100,7 @@ New proposal received extending L0L2 fork at [L0] slot: ##### Case 3 -New proposal received extending canonical: +Extending the canonical blockchain with a new block proposal: |--[L0]--[L2] <-- L0L2 fork [C]--...--[C]--| @@ -112,15 +113,13 @@ New proposal received extending canonical: ## Finalization -When finalization sync period kicks in, each node finds the longest fork chain it holds, that is at least 3 blocks long, -without any other fock chain with same length. -If such a fork chain exists, nodes finalizes(appends to canonical blockchain) all proposed blocks up to the last one. -When a fork chain gets finalized, rest fork chains are removed from nodes memory pool. -This practically means, that while we have competting(same length) fork chains, -no finalization occurs until a slot with a single leader happens. +When the finalization sync period kicks in, each node looks up the longest fork chain it holds. This must be at least 3 blocks long and there must be no other fork chain with same length. +If such a fork chain exists, nodes finalize all proposed blocks up to the last one by appending them to the canonical blockchain. +Once finalized, all other fork chains are removed from the memory pool. +Practically this means that no finalization can occur while we have competing fork chains of the same length. In such a case, finalization can only occur when we have a a slot with a single leader. -We continue Case 3 from previous sector to visualize this logic. -On slot 5, node observes 2 proposals, one extending L0L2 fork and one extending L0L3 fork: +We continue Case 3 from the previous section to visualize this logic. +On slot 5, a node observes 2 proposals. One extends the L0L2 fork, and the other extends the L0L3 fork: |--[L0]--[L2]+--[L5a] <-- L0L2L5a fork [C]--...--[C]--| @@ -130,8 +129,8 @@ On slot 5, node observes 2 proposals, one extending L0L2 fork and one extending | |--[L4] <-- L4 fork -Finalization cannot occur, since we have two competting fork chains. -On next slot, node only observers 1 proposal, extending L0L3L5b fork: +Since we have two competing fork chains finalization cannot occur. +On next slot, a node only observes 1 proposal. So it extends the L0L3L5b fork: |--[L0]--[L2]--[L5a] <-- L0L2L5a fork [C]--...--[C]--| @@ -141,7 +140,7 @@ On next slot, node only observers 1 proposal, extending L0L3L5b fork: | |--[L4] <-- L4 fork -When finalization sync period starts, node sees that it can finalize fork L0L3L5bL6 and drop rest forks: +When the finalization sync period starts, the node finalizes the fork L0L3L5bL6 and all other forks get dropped: |/--[L0]--[L2]--[L5a] <-- L0L2L5a fork [C]--...--[C]--| @@ -152,9 +151,9 @@ When finalization sync period starts, node sees that it can finalize fork L0L3L5 |/--[L4] <-- L4 fork -resulting in the following state: +This results in the following state: [C]--...--[C]--|--[L6] -where canonical contains blocks L0, L3 and L5b from L0L3L56L6 fork. +The canonical blockchain contains blocks L0, L3 and L5b from the L0L3L56L6 fork.