github.com/badrootd/celestia-core@v0.0.0-20240305091328-aa4207a4b25d/spec/p2p/v0.34/README.md (about)

     1  # Peer-to-Peer Communication
     2  
     3  This document describes the implementation of the peer-to-peer (p2p)
     4  communication layer in CometBFT.
     5  
     6  It is part of an [effort](https://github.com/cometbft/cometbft/issues/19)
     7  to produce a high-level specification of the operation of the p2p layer adopted
     8  in production CometBFT networks.
     9  
    10  This documentation, therefore, considers the releases `0.34.*` of CometBFT, more
    11  specifically, the branch [`v0.34.x`](https://github.com/cometbft/cometbft/tree/v0.34.x)
    12  of this repository.
    13  
    14  ## Overview
    15  
    16  A CometBFT network is composed of multiple CometBFT instances, hereafter
    17  called **nodes**, that interact by exchanging messages.
    18  
    19  CometBFT assumes a partially-connected network model.
    20  This means that a node is not assumed to be directly connected to every other
    21  node in the network.
    22  Instead, each node is directly connected to a subset of other nodes in the
    23  network, hereafter called its **peers**.
    24  
    25  The peer-to-peer (p2p) communication layer is responsible for establishing
    26  connections between nodes in a CometBFT network,
    27  for managing the communication between a node and its peers,
    28  and for intermediating the exchange of messages between peers in CometBFT protocols.
    29  
    30  ## Contents
    31  
    32  The documentation follows the organization of the `p2p` package of CometBFT,
    33  which implements the following abstractions:
    34  
    35  - [Transport](./transport.md): establishes secure and authenticated
    36     connections with peers;
    37  - [Switch](./switch.md): responsible for dialing peers and accepting
    38     connections from peers, for managing established connections, and for
    39     routing messages between the reactors and peers,
    40     that is, between local and remote instances of the CometBFT protocols;
    41  - [PEX Reactor](./pex.md): a reactor is the implementation of a protocol which
    42    exchanges messages through the p2p layer. The PEX reactor manages the [Address Book](./addressbook.md)  and implements both the [PEX protocol](./pex-protocol.md) and the  [Peer Manager](./peer_manager.md) role.
    43      - [Peer Exchange protocol](./pex-protocol.md): enables nodes to exchange peer addresses, thus implementing a peer discovery service;
    44      - [Address Book](./addressbook.md): stores discovered peer addresses and
    45    quality metrics associated to peers with which the node has interacted;
    46      - [Peer Manager](./peer_manager.md): defines when and to which peers a node
    47    should dial, in order to establish outbound connections;
    48  - Finally, [Types](./types.md) and [Configuration](./configuration.md) provide
    49     a list of existing types and configuration parameters used by the p2p layer implementation.
    50  
    51  ## Further References
    52  
    53  Existing documentation referring to the p2p layer:
    54  
    55  - <https://github.com/cometbft/cometbft/tree/v0.34.x/spec/p2p>: p2p-related
    56    configuration flags; overview of connections, peer instances, and reactors;
    57    overview of peer discovery and node types; peer identity, secure connections
    58    and peer authentication handshake.
    59  - <https://github.com/cometbft/cometbft/tree/v0.34.x/spec/p2p/messages>: message
    60    types and channel IDs of Block Sync, Mempool, Evidence, State Sync, PEX, and
    61    Consensus reactors.
    62  - <https://docs.cometbft.com/v0.34/core>: the p2p layer
    63    configuration and operation is documented in several pages.
    64    This content is not necessarily up-to-date, some settings and concepts may
    65    refer to the release `v0.35`, that was [discontinued][v35postmorten].