github.com/koko1123/flow-go-1@v0.29.6/cmd/execution/README.md (about)

     1  # Execution
     2  
     3  The Execution Node (EN) processes blocks and collections prepared by consensus and collection
     4  nodes. It executes the transaction in a Flow Virtual Machine, runtime environment of Flow protocol.
     5  EN also maintains Execution State, ledger containing user data which is manipulated by transactions.
     6  As a last step of processing block, it prepares and distributes Execution Receipt allowing verification
     7  nodes to verify correctness of computation, and later, consensus nodes to seal blocks.
     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  ##Table of Contents
    12  
    13  - [Terminology](#terminology)
    14  - [Architecture overview](#architecture-overview)
    15    - [Ingestion engine](#ingestion-engine)
    16    - [ComputationManager](#computationmanager)
    17    - [Provider engine](#provider-engine)
    18    - [RPC Engine](#rpc-engine)
    19  - [Ingestion operation](#ingestion-operation)
    20    - [Mempool queues](#mempool-queues)
    21    - [Mempool cache](#mempool-cache)
    22  - [Syncing](#syncing)
    23    - [Execution State syncing](#execution-state-syncing)
    24    - [Missing blocks](#missing-blocks)
    25  - [Operation](#operation)
    26  
    27  <!-- END doctoc generated TOC please keep comment here to allow auto update -->
    28  
    29  ## Terminology
    30  
    31  - Computation - is a process of evaluating block content and yielding list of changes to the ledger.  
    32  - Execution - complete, Flow protocol compliant operation of executing block. It manages environment for computation of block, stores execution states, creates execution receipt among others.
    33  
    34  ## Architecture overview
    35  
    36  ### Ingestion engine
    37  Central component - input of the node - execution state owner, only component allowed to mutate it. 
    38  It receives blocks, assembles them (gather collections) and forms execution queue (fork-aware ordering).
    39  Once a block is assembled and ready to be computed (full content of transactions is known and valid, previous execution state is available) it passes `ExecutableBlock` for computation (to `ComputationManager`)
    40  After receiving computation results ingestion engine generates Flow-compliant entities (`ExecutionReceipt`) and saves them along with other internal execution state data (block's `StateCommitment`).
    41  
    42  ### ComputationManager
    43  Abstraction of computing blocks, creates and manages Cadence runtime, exposes interface for computing blocks.
    44  
    45  ### Provider engine
    46  The output of the Execution Node. It's responsible for broadcasting `ExecutionReceipts` and answering requests for various states of protocol.
    47  
    48  ### RPC Engine
    49  It's gRPC endpoint exposing Observation API. This is a temporary solution and Observation Node is expected to take over this responsibility.
    50  
    51  ## Ingestion operation
    52  
    53  ### Mempool queues
    54  Ingestion engine accepts incoming blocks and classifies them into two mempool map of queues:
    55   - execution queue - which contains subqueues of blocks executable in order. This allow forks to be executed in parallel. 
    56     Head of each queue is either being executed or waiting for collections. It's starting state commitment is present. It will
    57     produce state commitment for it's children. 
    58   - orphan queue - which contains subqueues of orphaned blocks. Those who cannot be executed immediately or are not known to be
    59     executable soon. It's kept separately, as it will be used to determine when the node should switch into synchronisation mode
    60     
    61  ### Mempool cache
    62  Additionally, EN keeps a simple mapping of collection IDs to block, for lookup when the collection is received.
    63  
    64  ## Syncing
    65  
    66  If EN cannot execute number of consecutive blocks (`syncThreshold` parameter) it enter synchronisation mode. The number of blocks
    67  required to trigger this condition is put in place to prevent triggering it in case of blocks arriving out of order, which can
    68  happen on unstable networks.
    69  EN keeps track of the highest block it has executed. This is not a Flow protocol feature, and only serves synchronisation needs.
    70  
    71  ### Execution State syncing
    72  Other execution node is queried for range of missing blocks and hold authority to decide if it's willing (and able) to answer this query.
    73  If so, it sends the `ExecutionStateDelta` which contains all the block data and results of execution.
    74  Currently, this is fully trusted operation, meaning data is applied as-is without any extra checks.
    75  
    76  ### Missing blocks
    77  If no other EN are available, the block-level synchronisation is started. This requests blocks from consensus nodes, and
    78  incoming blocks are processed as if they were received during normal mode of operation
    79  
    80  ## Operation
    81  
    82  In order to execute a block, all collections must be requested and validated. A valid collection must be signed by an authorized collection node (i.e. with positive weight). The protocol state can be altered by executing transactions, hence the parent block must be executed to provide
    83  up-to-date copy of protocol state. This allows to validate collection nodes identities and in turn, validity of collection itself.
    84  Having all collections retrieved and Execution State of a parent known - a block execution can commence.
    85  Blocks are executed in separate Go routine to allow potential forks (sharing parent block) to be computed in parallel.
    86  After execution is finished, it passes newly created execution state to its children, and if they are now ready - they are, repeating the loop.
    87