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

     1  # Access Node
     2  
     3  The access node provides a single point of contact to interact with the Flow network. It implements the [Access API](https://docs.onflow.org/access-api/)
     4  
     5  It is a GRPC server which also connects to a collection node and an execution node via GRPC.
     6  
     7  At a high level it does the following:
     8  
     9  1. Forwards transaction received from the client via the `SendTransaction` call to the collection node.
    10  2. Forwards all Script related calls (`ExecuteScriptAtLatestBlock`, `ExecuteScriptAtBlockID` and `ExecuteScriptAtBlockHeight`) to one of the execution node
    11  3. Follows updates to the blockchain and locally caches transactions, collections, and sealed blocks.
    12  4. Replies to client API calls for information such as `GetBlockByID`, `GetCollectionByID`, `GetTransaction` etc.
    13  
    14  
    15  ***NOTE**: The Access node does not participate in the Flow protocol*
    16  
    17  <!-- START doctoc generated TOC please keep comment here to allow auto update -->
    18  <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
    19  **Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
    20  
    21  - [Terminology](#terminology)
    22  - [Processes](#processes)
    23    - [Transaction Lifecycle](#transaction-lifecycle)
    24  - [Engines](#engines)
    25    - [Follower Engine](#follower-engine)
    26    - [Ingestion](#ingestion)
    27    - [Requester](#requester)
    28    - [RPC](#rpc)
    29    - [Ping](#ping)
    30  
    31  <!-- END doctoc generated TOC please keep comment here to allow auto update -->
    32  
    33  ## Terminology
    34  
    35  - **Transaction** - a transaction represents a unit of computation that is submitted to the Flow network.
    36  - **Collection** - a set of transactions proposed by a cluster of collection nodes.
    37  - **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.
    38  - **Block** - the combination of a block header with block contents, representing all the data necessary to construct and validate the entirety of the block.
    39  
    40  ## Processes
    41  
    42  ### Transaction Lifecycle
    43  1. Transactions are received by the access node via the [SendTransaction API call](https://docs.onflow.org/access-api/#sendtransaction).
    44  2. The access node forwards the transaction to one of the Collection node in the Collection node cluster to which this transaction belongs to and stores it locally as well.
    45  3. If a [GetTransaction](https://docs.onflow.org/access-api/#gettransaction) request is received, the transaction is read from local storage and returned if found.
    46  4. If a [GetTransactionResult](https://docs.onflow.org/access-api/#gettransactionresult) request is received,
    47  an execution node is requested for events for the transaction and the transaction status is derived as follows:
    48      1. If the collection containing the transaction and the block containing that collection is found locally, but the transaction has expired then its status is returned as `expired`.
    49      2. If either the collection or the block is not found locally, but the transaction has not expired, then its status is returned as `pending`
    50      3. If the transaction has neither expired nor is it pending, but the execution node has not yet executed the transaction,
    51         then the status of the transaction is returned as `finalized`.
    52      4. If the execution node has executed the transaction, then if the height of the block containing the transaction is greater than the highest sealed block,
    53      then the status of the transaction is returned as `executed` else it is returned as `sealed`.
    54      5. If the collection, block, or chain state lookup failed then the status is returned as `unknown`.
    55  
    56  
    57  ## Engines
    58  
    59  Engines are units of application logic that 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.
    60  
    61  ### [Follower Engine](../../engine/common/follower)
    62  
    63  The Follower engine follows the consensus progress and notifies the `ingestion` engine of any new finalized block.
    64  
    65  ### [Ingestion](../../engine/access/ingestion)
    66  
    67  The `ingestion` engine receives finalized blocks from the `follower` engine and request all the collections for the block via the `requester` engine.
    68  As the collections arrive, it persists the collections and the transactions within the collection in the local storage.
    69  
    70  ### [Requester](../../engine/common/requester)
    71  
    72  The `requester` engine requests collections from the collection nodes on behalf of the `ingestion` engine.
    73  
    74  ### [RPC](../../engine/access/rpc)
    75  
    76  The `rpc` engine is the GRPC server which responds to the [Access API](https://docs.onflow.org/access-api/) requests from clients.
    77  It also supports GRPCWebproxy requests.
    78  
    79  ### [REST](../../engine/access/rest)
    80  
    81  The `rest` engine is the HTTP server that implements the [OpenAPI schema](https://github.com/onflow/flow/tree/master/openapi) and handles requests from clients. The API docuemntation is [available here](https://docs.onflow.org/http-api/).
    82  
    83  ### [Ping](../../engine/access/ping)
    84  
    85  The `ping` engine pings all the other nodes specified in the identity list via a [libp2p](https://github.com/libp2p/go-libp2p) ping and reports via metrics if the node is reachable or not.
    86  This helps identify nodes in the system which are unreachable.
    87  
    88  
    89  ### Access node sequence diagram
    90  
    91  ![Access node sequence diagram](/docs/AccessNodeSequenceDiagram.png)