github.com/badrootd/nibiru-cometbft@v0.37.5-0.20240307173500-2a75559eee9b/spec/p2p/implementation/pex.md (about)

     1  # PEX Reactor
     2  
     3  The PEX reactor is one of the reactors running in a CometBFT node.
     4  
     5  Its implementation is located in the `p2p/pex` package, and it is considered
     6  part of the implementation of the p2p layer.
     7  
     8  This document overviews the implementation of the PEX reactor, describing how
     9  the methods from the `Reactor` interface are implemented.
    10  
    11  The actual operation of the PEX reactor is presented in documents describing
    12  the roles played by the PEX reactor in the p2p layer:
    13  
    14  - [Address Book](./addressbook.md): stores known peer addresses and information
    15    about peers to which the node is connected or has attempted to connect
    16  - [Peer Manager](./peer_manager.md): manages connections established with peers,
    17    defining when a node should dial peers and which peers it should dial
    18  - [Peer Exchange protocol](./pex-protocol.md): enables nodes to exchange peer
    19    addresses, thus implementing a peer discovery service
    20  
    21  ## OnStart
    22  
    23  The `OnStart` method implements `BaseService` and starts the PEX reactor.
    24  
    25  The [address book](./addressbook.md), which is a `Service` is started.
    26  This loads the address book content from disk,
    27  and starts a routine that periodically persists the address book content to disk.
    28  
    29  The PEX reactor is configured with the addresses of a number of seed nodes,
    30  the `Seeds` parameter of the `ReactorConfig`.
    31  The addresses of seed nodes are parsed into `NetAddress` instances and resolved
    32  into IP addresses, which is implemented by the `checkSeeds` method.
    33  Valid seed node addresses are stored in the `seedAddrs` field,
    34  and are used by the `dialSeeds` method to contact the configured seed nodes.
    35  
    36  The last action is to start one of the following persistent routines, based on
    37  the `SeedMode` configuration parameter:
    38  
    39  - Regular nodes run the `ensurePeersRoutine` to check whether the node has
    40    enough outbound peers, dialing peers when necessary
    41  - Seed nodes run the `crawlPeersRoutine` to periodically start a new round
    42    of [crawling](./pex-protocol.md#Crawling-peers) to discover as many peer
    43    addresses as possible
    44  
    45  ### Errors
    46  
    47  Errors encountered when loading the address book from disk are returned,
    48  and prevent the reactor from being started.
    49  An exception is made for the `service.ErrAlreadyStarted` error, which is ignored.
    50  
    51  Errors encountered when parsing the configured addresses of seed nodes
    52  are returned and cause the reactor startup to fail.
    53  An exception is made for DNS resolution `ErrNetAddressLookup` errors,
    54  which are not deemed fatal and are only logged as invalid addresses.
    55  
    56  If none of the configured seed node addresses is valid, and the loaded address
    57  book is empty, the reactor is not started and an error is returned.
    58  
    59  ## OnStop
    60  
    61  The `OnStop` method implements `BaseService` and stops the PEX reactor.
    62  
    63  The address book routine that periodically saves its content to disk is stopped.
    64  
    65  ## GetChannels
    66  
    67  The `GetChannels` method, from the `Reactor` interface, returns the descriptor
    68  of the channel used by the PEX protocol.
    69  
    70  The channel ID is `PexChannel` (0), with priority `1`, send queue capacity of
    71  `10`, and maximum message size of `64000` bytes.
    72  
    73  ## AddPeer
    74  
    75  The `AddPeer` method, from the `Reactor` interface,
    76  adds a new peer to the PEX protocol.
    77  
    78  If the new peer is an **inbound peer**, i.e., if the peer has dialed the node,
    79  the peer's address is [added to the address book](./addressbook.md#adding-addresses).
    80  Since the peer was authenticated when establishing a secret connection with it,
    81  the source of the peer address is trusted, and its source is set by the peer itself.
    82  In the case of an outbound peer, the node should already have its address in
    83  the address book, as the switch has dialed the peer.
    84  
    85  If the peer is an **outbound peer**, i.e., if the node has dialed the peer,
    86  and the PEX protocol needs more addresses,
    87  the node [sends a PEX request](./pex-protocol.md#Requesting-Addresses) to the peer.
    88  The same is not done when inbound peers are added because they are deemed least
    89  trustworthy than outbound peers.
    90  
    91  ## RemovePeer
    92  
    93  The `RemovePeer` method, from the `Reactor` interface,
    94  removes a peer from the PEX protocol.
    95  
    96  The peer's ID is removed from the tables tracking PEX requests
    97  [sent](./pex-protocol.md#misbehavior) but not yet replied
    98  and PEX requests [received](./pex-protocol.md#misbehavior-1).
    99  
   100  ## Receive
   101  
   102  The `Receive` method, from the `Reactor` interface,
   103  handles a message received by the PEX protocol.
   104  
   105  A node receives two type of messages as part of the PEX protocol:
   106  
   107  - `PexRequest`: a request for addresses received from a peer, handled as
   108    described [here](./pex-protocol.md#providing-addresses)
   109  - `PexAddrs`: a list of addresses received from a peer, as a reponse to a PEX
   110    request sent by the node, as described [here](./pex-protocol.md#responses)
   111