github.com/onflow/flow-go@v0.35.7-crescendo-preview.23-atree-inlining/cmd/consensus/README.md (about)

     1  # Consensus
     2  
     3  The consensus node is responsible for deciding on the subjective ordering of the transactions that will be executed by the execution nodes. They do so by running a consensus algorithm for the blockchain, whereas each block payload contains an ordered list of collection guarantees received from collection node clusters.
     4  
     5  Consensus nodes are also responsible for maintaining the protocol state, which encompasses epochs with their respective set of node identities, as well as the adjudication of all slashing challenges which maintain the economic incentives that serve as the foundation of the bigger Flow system.
     6  
     7  This document provides a high-level overview of the consensus node architecture. Each section includes links to the appropriate packages, which may contain more detailed documentation.
     8  
     9  <!-- START doctoc generated TOC please keep comment here to allow auto update -->
    10  <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
    11  
    12  
    13  - [Terminology](#terminology)
    14  - [Processes](#processes)
    15    - [Collection Guarantee Lifecycle](#collection-guarantee-lifecycle)
    16    - [Block Seal Lifecycle](#block-seal-lifecycle)
    17    - [Block Formation](#block-formation)
    18  - [Engines](#engines)
    19    - [Ingestion](#ingestion)
    20    - [Propagation](#propagation)
    21    - [Compliance](#compliance)
    22    - [Synchronization](#synchronization)
    23    - [Provider](#provider)
    24    - [Sealing](#sealing)
    25  - [Modules](#modules)
    26    - [Protocol State](#protocol-state)
    27    - [Block Builder](#block-builder)
    28    - [Block Finalizer](#block-finalizer)
    29    - [Core Consensus](#core-consensus)
    30  
    31  <!-- END doctoc generated TOC please keep comment here to allow auto update -->
    32  
    33  
    34  ## Terminology
    35  
    36  - **Collection** - a set of transactions proposed by a cluster of collection nodes.
    37  - **Guarantee**, also _Collection Guarantee_ - an attestation for a collection guaranteed by a collection cluster, containing a hash over the collection contents and signed by a qualified majority of the participants of the cluster.
    38  - **Result**, also _Execution Result_ - a summary representing the delta of the execution state resulting from the execution of a specific block, containing a reference to the previous state and a state commitment for the resulting state.
    39  - **Receipt**, also _Execution Receipt_ - a proof of execution linked to a specific execution node, containing an execution result, data on execution chunks and a signature of the execution node.
    40  - **Approval**, also _Result Approval_ - an approval of the execution of a chunk of an execution result, as verified by a specific verification node.
    41  - **Seal**, also _Block Seal_ - an attestation of correct execution of a block in the blockchain, built by the consensus node after receiving the necessary execution receipts and result approvals.
    42  - **Header**, also _Block Header_ - a data structure containing the meta-data for a block, including the merkle root hash for the payload as well as the relevant consensus node signatures.
    43  - **Payload**, also _Block Payload_ - a list of entities included in a block, currently consisting of collection guarantees and block seals.
    44  - **Index**, also _Payload Index_ - a list of entitie IDs included in a block, currently consising of a list of collection guarantee IDs and block seal IDs.
    45  - **Block** - the combination of a block header with a block contents, representing all of the data necessary to construct and validate the entirety of the block.
    46  
    47  
    48  ## Processes
    49  
    50  The consensus nodes accomplish a single high-level process: the formation of and the consensus-finding on blocks with their payloads. Each payload can include collection guarantees and block seals, which are each handled by their own high-level processes.
    51  
    52  On an implementation level, each process is implemented by a number of node engines, modules and storage components.
    53  
    54  ### Collection Guarantee Lifecycle
    55  
    56  1. Collection guarantees are received from collection node clusters.
    57  2. Collection guarantees are propagated to other consensus nodes.
    58  3. Collection guarantees are introduced into the memory pool.
    59  4. Collection guarantees are included in a block proposal.
    60  5. Collection guarantees are removed from the memory pool when the block is finalized.
    61  
    62  ### Block Seal Lifecycle
    63  
    64  1. Execution receipts are received from execution nodes.
    65  2. Result approvals are received from verification nodes.
    66  3. Execution receipts and result approvals are introduced into the memory pool.
    67  4. Execution receipts are matched with result approvals for block seal generation.
    68  5. Generated blocks seals are introduced into the memory pool.
    69  6. Execution receipts and result approvals are removed from the memory pool when a seal is generated.
    70  7. Blocks seals are included in a block proposal.
    71  8. Block seals are removed from the memory pool when the block is finalized.
    72  
    73  ### Block Formation
    74  
    75  1. Core consensus algorithm requests a block proposal for a specific parent.
    76  2. Block builder includes collection guarantees available in the memory pool.
    77  3. Block builder includes block seals available in the memory pool.
    78  4. Core consensus algorithm orders finalization of a block.
    79  
    80  
    81  ## Engines
    82  
    83  Engines are units of application logic which are generally responsible for a well-isolated process that is part of the bigger system. They receive messages from the network on selected channels and submit messages to the network on the same channels.
    84  
    85  ### [Ingestion](../../engine/consensus/ingestion)
    86  
    87  The `ingestion` engine is responsible for receiving collection guarantees from clusters of collection nodes.
    88  
    89  It will perform some basic validation, such as checking the origin of the collection guarantee and the collection expiry. When a collection guarantee appears valid, it forwards it to the propagation engine.
    90  
    91  ### [Propagation](../../engine/consensus/propagation)
    92  
    93  The `propagation` engine is responsible for proactively synchronizing the memory pools for collection guarantee between consensus nodes.
    94  
    95  It can receive new collection guarantees from the ingestion engine or directly from other consensus nodes. Once received, it will add it to the memory pool for block construction and share it with other consensus nodes as needed.
    96  
    97  ### [Compliance](../../engine/consensus/compliance)
    98  
    99  The `compliance` engine is responsible for ensuring blocks comply with the validity rules of the protocol state and for enabling communication between the replicas of the core consensus algorithm.
   100  
   101  The compliance functions as the communication layer between the replicas of the core consensus algorithm. It receives block proposals and votes from the network and forwards them to the core consensus algorithm, as well as providing the core consensus algorithm with facilities to broadcast block proposals and send votes to the other replicas on the network.
   102  
   103  When a block proposal is received, consensus node will first try to assemble all data required for its validation. Once it is available, the compliance engine validates the block proposal against the protocol state, which enforces formation rules outside of the purview of the core consensus algorithm, such as those relating to block payloads. If a block is considered compliant, the header is forwarded to the core consensus algorithm for decision-making.
   104  
   105  ### [Synchronization](../../engine/common/synchronization)
   106  
   107  The `synchronization` engine is responsible for reactive synchronization of consensus nodes about the protocol state.
   108  
   109  At regular interval, it will send synchronization requests (pings) to a random subset of consensus nodes, and receive synchonization responses (pongs) in return. If it detects a difference in finalized block height above a certain threshold, it will request the missing block heights.
   110  
   111  Additionally, the synchronization engine provides the possibility to request blocks by specific identifier. This is used by the compliance engine to actively request missing blocks that are needed for the validation of another block.
   112  
   113  ### [Provider](../../engine/consensus/provider)
   114  
   115  The `provider` engine is responsible for providing blocks to the non-consensus participants of the Flow system.
   116  
   117  At the moment, it simply receives each block proposal from the compliance engine and broadcasts it to all interested nodes on its communication channel.
   118  
   119  ### [Sealing](../../engine/consensus/sealing)
   120  
   121  The `sealing` engine is responsible for receiving execution receipts and result approvals, as well as generating the block seals for them.
   122  
   123  Whenever an execution receipt or a result approval are received by the sealing engine, it will perform all possible validity checks on it before adding it to the respective memory pool.
   124  
   125  If the related result or chunk is new, the sealing engine checks if there are any results in its memory pool that can be fully verified with the received result approvals. Once this is the case, it creates the related block seal and adds it to the memory pool for block construction.
   126  
   127  
   128  ## Modules
   129  
   130  Modules encapsulate big parts of the application logic, which they provide as a service to other components, such as engines. They usually don't run anything unless another component calls into them.
   131  
   132  ### [Protocol State](../../state/protocol)
   133  
   134  The `protocol state` is the most important stateful component of the consensus nodes. It provides the ability to retrieve a snapshot at a given point of the blockchain history, as well as allowing the mutation of the protocol state by extending it with a block or finalizing a block.
   135  
   136  When receiving a block proposal, it is validated against the protocol state by trying to extend the protocol state mutator; this will perform a check for all chain compliance rules, such as some basic header constraints and the full check for payload duplicates or invalid content.
   137  
   138  For a lot of messages, we check whether the origin is a valid sender for the given message type. This is done by getting the node identities from the protocol state snapshot and validating the origin against them.
   139  
   140  ### [Block Builder](../../module/builder/consensus)
   141  
   142  The `block builder` is complementary to the protocol state and is responsible for building block proposals that are complying with the validity rules of the protocol state. This means there is a lot of overlap in their logic.
   143  
   144  It will retrieve all pending collection guarantees and block seals from the memory pools and check which ones it can validly include into the block payload without breaking compliance on the respective fork of the block chain it is building on.
   145  
   146  ### [Block Finalizer](../../module/finalizer/consensus)
   147  
   148  The `block finalizer` is also complementary to the protocol state and is responsible for providing an idempotent interface for finalizing a block or mapping blocks to their parents.
   149  
   150  When provided with a block, it will attempt to finalize each block between the last finalized block and the candidate block in order. If no blocks have to be finalized, it will be an empty operation.
   151  
   152  ### [Core Consensus](../../consensus/hotstuff)
   153  
   154  The `core consensus` in Flow is provided by the HotStuff algorithm. While there are some interdependencies between the components, it exists mostly in isolation from the compliance engine and interacts only through some well-defined interfaces.
   155  
   156  Please take a look at the [Hotstuff Documentation](../../consensus/hotstuff/README.md) for a more detailed overview of its internal workings.