github.com/onflow/flow-go@v0.35.7-crescendo-preview.23-atree-inlining/engine/verification/Readme.md (about)

     1  # Verification Node
     2  The Verification Node in the Flow blockchain network is a critical component responsible for
     3  verifying `ExecutionResult`s and generating `ResultApproval`s. 
     4  Its primary role is to ensure the integrity and validity of block execution by performing verification processes.
     5  In a nutshell, the Verification Node is responsible for the following:
     6  1. Following the chain for new finalized blocks (`Follower` engine).
     7  2. Processing the execution results in the finalized blocks and determining assigned chunks to the node (`Assigner` engine).
     8  3. Requesting chunk data pack from Execution Nodes for the assigned chunks (`Fetcher` and `Requester` engines).
     9  4. Verifying the assigned chunks and emitting `ResultApproval`s for the verified chunks to Consensus Nodes (`Verifier` engine).
    10  ![architecture.png](architecture.png)
    11  
    12     
    13  ## Block Consumer ([consumer.go](verification%2Fassigner%2Fblockconsumer%2Fconsumer.go))
    14  The `blockconsumer` package efficiently manages the processing of finalized blocks in Verification Node of Flow blockchain.
    15  Specifically, it listens for notifications from the `Follower` engine regarding finalized blocks, and systematically 
    16  queues these blocks for processing. The package employs parallel workers, each an instance of the `Assigner` engine, 
    17  to fetch and process blocks from the queue. The `BlockConsumer` diligently coordinates this process by only assigning 
    18  a new block to a worker once it has completed processing its current block and signaled its availability. 
    19  This ensures that the processing is not only methodical but also resilient to any node crashes. 
    20  In case of a crash, the `BlockConsumer` resumes from where it left off by reading the processed block index from storage, reassigning blocks from the queue to workers,
    21  thereby guaranteeing no loss of data.
    22  
    23  ## Assigner Engine 
    24  The `Assigner` [engine](verification%2Fassigner%2Fengine.go) is an integral part of the verification process in Flow, 
    25  focusing on processing the execution results in the finalized blocks, performing chunk assignments on the results, and
    26  queuing the assigned chunks for further processing. The Assigner engine is a worker of the `BlockConsumer` engine,
    27  which assigns finalized blocks to the Assigner engine for processing.
    28  This engine reads execution receipts included in each finalized block, 
    29  determines which chunks are assigned to the node for verification, 
    30  and stores the assigned chunks into the chunks queue for further processing (by the `Fetcher` engine).
    31  
    32  The core behavior of the Assigner engine is implemented in the `ProcessFinalizedBlock` function. 
    33  This function initiates the process of execution receipt indexing, chunk assignment, and processing the assigned chunks. 
    34  For every receipt in the block, the engine determines chunk assignments using the verifiable chunk assignment algorithm of Flow.
    35  Each assigned chunk is then processed by the `processChunk` method. This method is responsible for storing a chunk locator in the chunks queue, 
    36  which is a crucial step for further processing of the chunks by the fetcher engine. 
    37  Deduplication of chunk locators is handled by the chunks queue.
    38  The Assigner engine provides robustness by handling the situation where a node is not authorized at a specific block ID. 
    39  It verifies the role of the result executor, checks if the node has been ejected, and assesses the node's staked weight before granting authorization.
    40  Lastly, once the Assigner engine has completed processing the receipts in a block, it sends a notification to the block consumer. This is inline with 
    41  Assigner engine as a worker of the block consumer informing the consumer that it is ready to process the next block.
    42  This ensures a smooth and efficient flow of data in the system, promoting consistency across different parts of the Flow architecture.
    43  
    44  ### Chunk Locator
    45  A chunk locator in the Flow blockchain is an internal structure of the Verification Nodes that points to a specific chunk 
    46  within a specific execution result of a block. It's an important part of the verification process in the Flow network,
    47  allowing verification nodes to efficiently identify, retrieve, and verify individual chunks of computation.
    48  
    49  ```go
    50  type ChunkLocator struct {
    51      ResultID flow.Identifier // The identifier of the ExecutionResult
    52      Index    uint64         // Index of the chunk
    53  }
    54  ```
    55  - `ResultID`: This is the identifier of the execution result that the chunk is a part of. The execution result contains a list of chunks which each represent a portion of the computation carried out by execution nodes. Each execution result is linked to a specific block in the blockchain.
    56  - `Index`: This is the index of the chunk within the execution result's list of chunks. It's an easy way to refer to a specific chunk within a specific execution result.
    57  
    58  **Note-1**: The `ChunkLocator` doesn't contain the chunk itself but points to where the chunk can be found. In the context of the `Assigner` engine, the `ChunkLocator` is stored in a queue after chunk assignment is done, so the `Fetcher` engine can later retrieve the chunk for verification.
    59  **Note-2**: The `ChunkLocator` is never meant to be sent over the networking layer to another Flow node. It's an internal structure of the verification nodes, and it's only used for internal communication between the `Assigner` and `Fetcher` engines.
    60  
    61  
    62  ## ChunkConsumer 
    63  The `ChunkConsumer` ([consumer](verification%2Ffetcher%2Fchunkconsumer%2Fconsumer.go)) package orchestrates the processing of chunks in the Verification Node of the Flow blockchain. 
    64  Specifically, it keeps tabs on chunks that are assigned for processing by the `Assigner` engine and systematically enqueues these chunks for further handling. 
    65  To expedite the processing, the package deploys parallel workers, with each worker being an instance of the `Fetcher` engine, which retrieves and processes the chunks from the queue. 
    66  The `ChunkConsumer` administers this process by ensuring that a new chunk is assigned to a worker only after it has finalized processing its current chunk and signaled that it is ready for more. 
    67  This systematic approach guarantees not only efficiency but also robustness against any node failures. In an event where a node crashes,
    68  the `ChunkConsumer` picks up right where it left, redistributing chunks from the queue to the workers, ensuring that there is no loss of data or progress.
    69  
    70  ## Fetcher Engine - The Journey of a `ChunkLocator` to a `VerifiableChunkData`
    71  The Fetcher [engine.go](fetcher%2Fengine.go) of the Verification Nodes focuses on the lifecycle of a `ChunkLocator` as it transitions into a `VerifiableChunkData`.
    72  
    73  ### `VerifiableChunkData`
    74  `VerifiableChunkData` refers to a data structure that encapsulates all the necessary components and resources required to
    75  verify a chunk within the Flow blockchain network. It represents a chunk that has undergone processing and is ready for verification.
    76  
    77  The `VerifiableChunkData` object contains the following key elements:
    78  ```go
    79  type VerifiableChunkData struct {
    80  	IsSystemChunk     bool                  // indicates whether this is a system chunk
    81  	Chunk             *flow.Chunk           // the chunk to be verified
    82  	Header            *flow.Header          // BlockHeader that contains this chunk
    83  	Result            *flow.ExecutionResult // execution result of this block
    84  	ChunkDataPack     *flow.ChunkDataPack   // chunk data package needed to verify this chunk
    85  	EndState          flow.StateCommitment  // state commitment at the end of this chunk
    86  	TransactionOffset uint32                // index of the first transaction in a chunk within a block
    87  }
    88  ```
    89  1. `IsSystemChunk`: A boolean value that indicates whether the chunk is a system chunk. System chunk is a specific chunk typically representing the last chunk within an execution result.
    90  2. `Chunk`: The actual chunk that needs to be verified. It contains the relevant data and instructions related to the execution of transactions within the blockchain.
    91  3. `Header`: The `BlockHeader` associated with the chunk. It provides important contextual information about the block that the chunk belongs to.
    92  4. `Result`: The `ExecutionResult` object that corresponds to the execution of the block containing the chunk. It contains information about the execution status, including any errors or exceptions encountered during the execution process.
    93  5. `ChunkDataPack`: The `ChunkDataPack`, which is a package containing additional data and resources specific to the chunk being verified. It provides supplementary information required for the verification process.
    94  6. `EndState`: The state commitment at the end of the chunk. It represents the final state of the blockchain after executing all the transactions within the chunk.
    95  7. `TransactionOffset`: An index indicating the position of the first transaction within the chunk in relation to the entire block. This offset helps in locating and tracking individual transactions within the blockchain.
    96  By combining these elements, the VerifiableChunkData object forms a comprehensive representation of a chunk ready for verification. It serves as an input to the `Verifier` engine, which utilizes this data to perform the necessary checks and validations to ensure the integrity and correctness of the chunk within the Flow blockchain network.
    97  
    98  ### The Journey of a `ChunkLocator` to a `VerifiableChunkData`
    99  Upon receiving the `ChunkLocator`, the `Fetcher` engine’s `validateAuthorizedExecutionNodeAtBlockID` function is responsible 
   100  for validating the authenticity of the sender. It evaluates whether the sender is an authorized execution node for the respective block. 
   101  The function cross-references the sender’s credentials against the state snapshot of the specific block. 
   102  In the case of unauthorized or invalid credentials, an error is logged, and the `ChunkLocator` is rejected. 
   103  For authorized credentials, the processing continues.
   104  
   105  Once authenticated, the `ChunkLocator` is utilized to retrieve the associated Chunk Data Pack. 
   106  The `requestChunkDataPack` function takes the Chunk Locator and generates a `ChunkDataPackRequest`. 
   107  During this stage, the function segregates execution nodes into two categories - those which agree with the execution result (`agrees`) and those which do not (`disagrees`). 
   108  This information is encapsulated within the `ChunkDataPackRequest` and is forwarded to the `Requester` Engine. 
   109  The `Requester` Engine handles the retrieval of the `ChunkDataPack` from the network of execution nodes.
   110  
   111  After the Chunk Data Pack is successfully retrieved by the `Requester` Engine,
   112  the next phase involves structuring this data for verification and constructing a `VerifiableChunkData`. 
   113  It’s imperative that this construction is performed with utmost accuracy to ensure that the data is in a state that can be properly verified.
   114  
   115  The final step in the lifecycle is forwarding the `VerifiableChunkData` to the `Verifier` Engine. The `Verifier` Engine is tasked with the critical function 
   116  of thoroughly analyzing and verifying the data. Depending on the outcome of this verification process, 
   117  the chunk may either pass verification successfully or be rejected due to discrepancies.
   118  
   119  ### Handling Sealed Chunks
   120  In parallel, the `Fetcher` engine remains vigilant regarding the sealed status of chunks. 
   121  The `NotifyChunkDataPackSealed` function monitors the sealing status.
   122  If the Consensus Nodes seal a chunk, this function ensures that the `Fetcher` Engine acknowledges this update and discards the respective 
   123  `ChunkDataPack` from its processing pipeline as it is now sealed (i.e., has been verified by an acceptable quota of Verification Nodes).
   124  
   125  ## Requester Engine - Retrieving the `ChunkDataPack`
   126  The `Requester` [engine](requester%2Frequester.go) is responsible for handling the request and retrieval of chunk data packs in the Flow blockchain network.
   127  It acts as an intermediary between the `Fetcher` engine and the Execution Nodes, facilitating the communication and coordination required 
   128  to obtain the necessary `ChunkDataPack` for verification.
   129  
   130  The `Requester` engine receives `ChunkDataPackRequest`s from the `Fetcher`. 
   131  These requests contain information such as the chunk ID, block height, agree and disagree executors, and other relevant details.
   132  Upon receiving a `ChunkDataPackRequest`, the `Requester` engine adds it to the pending requests cache for tracking and further processing.
   133  The Requester engine periodically checks the pending chunk data pack requests and dispatches them to the Execution Nodes for retrieval. 
   134  It ensures that only qualified requests are dispatched based on certain criteria, such as the chunk ID and request history.
   135  The dispatching process involves creating a `ChunkDataRequest` message and publishing it to the network. 
   136  The request is sent to a selected number of Execution Nodes, determined by the `requestTargets` parameter.
   137  
   138  When an Execution Node receives a `ChunkDataPackRequest`, it processes the request and generates a `ChunkDataResponse` 
   139  message containing the requested chunk data pack. The execution node sends this response back to the`Requester` engine.
   140  The `Requester` engine receives the chunk data pack response, verifies its integrity, and passes it to the registered `ChunkDataPackHandler`, 
   141  i.e., the `Fetcher` engine.
   142  
   143  ### Retry and Backoff Mechanism
   144  In case a `ChunkDataPackRequest` does not receive a response within a certain period, the `Requester` engine retries the request to ensure data retrieval.
   145  It implements an exponential backoff mechanism for retrying failed requests.
   146  The retry interval, backoff multiplier, and backoff intervals can be customized using the respective configuration parameters.
   147  
   148  ### Handling Sealed Blocks
   149  If a `ChunkDataPackRequest` pertains to a block that has already been sealed, the `Requester` engine recognizes this and 
   150  removes the corresponding request from the pending requests cache. 
   151  It notifies the `ChunkDataPackHandler` (i.e., the `Fetcher` engine) about the sealing of the block to ensure proper handling.
   152  
   153  ### Parallel Chunk Data Pack Retrieval
   154  The `Requester` processes a number of chunk data pack requests in parallel, 
   155  dispatching them to execution nodes and handling the received responses. 
   156  However, it is important to note that if a chunk data pack request does not receive a response from the execution nodes, 
   157  the `Requester` engine can become stuck in processing, waiting for the missing chunk data pack. 
   158  To mitigate this, the engine implements a retry and backoff mechanism, ensuring that requests are retried and backed off if necessary. 
   159  This mechanism helps to prevent prolonged waiting and allows the engine to continue processing other requests while waiting for the missing chunk data pack response.
   160  
   161  ## Verifier Engine - Verifying Chunks
   162  The `Verifier` [engine](verifier%2Fengine.go) is responsible for verifying chunks, generating `ResultApproval`s, and maintaining a cache of `ResultApproval`s. 
   163  It receives verifiable chunks along with the necessary data for verification, verifies the chunks by constructing a partial trie,
   164  executing transactions, and checking the final state commitment and other chunk metadata. 
   165  If the verification is successful, it generates a `ResultApproval` and broadcasts it to the consensus nodes.
   166  
   167  The `Verifier` Engine offers the following key features:
   168  1. **Verification of Chunks**: The engine receives verifiable chunks, which include the chunk to be verified, the associated header, execution result, and chunk data pack. It performs the verification process, which involves constructing a partial trie, executing transactions, and checking the final state commitment. The verification process ensures the integrity and validity of the chunk.
   169  2. **Generation of Result Approvals**: If the verification process is successful, the engine generates a result approval for the verified chunk. The result approval includes the block ID, execution result ID, chunk index, attestation, approver ID, attestation signature, and SPoCK (Secure Proof of Confidential Knowledge) signature. The result approval provides a cryptographic proof of the chunk's validity and is used to seal the block.
   170  3. **Cache of Result Approvals**: The engine maintains a cache of result approvals for efficient retrieval and lookup. The result approvals are stored in a storage module, allowing quick access to the approvals associated with specific chunks and execution results.