github.com/aakash4dev/cometbft@v0.38.2/spec/p2p/implementation/types.md (about)

     1  # Types adopted in the p2p implementation
     2  
     3  This document lists the packages and source files, excluding test units, that
     4  implement the p2p layer, and summarizes the main types they implement.
     5  Types play the role of classes in Go.
     6  
     7  The reference version for this documentation is the branch
     8  [`v0.34.x`](https://github.com/aakash4dev/cometbft/tree/v0.34.x/p2p).
     9  
    10  State of August 2022.
    11  
    12  ## Package `p2p`
    13  
    14  Implementation of the p2p layer of CometBFT.
    15  
    16  ### `base_reactor.go`
    17  
    18  `Reactor` interface.
    19  
    20  `BaseReactor` implements `Reactor`.
    21  
    22  **Not documented yet**.
    23  
    24  ### `conn_set.go`
    25  
    26  `ConnSet` interface, a "lookup table for connections and their ips".
    27  
    28  Internal type `connSet` implements the `ConnSet` interface.
    29  
    30  Used by the [transport](#transportgo) to store connected peers.
    31  
    32  ### `errors.go`
    33  
    34  Defines several error types.
    35  
    36  `ErrRejected` enumerates a number of reason for which a peer was rejected.
    37  Mainly produced by the [transport](#transportgo),
    38  but also by the [switch](#switchgo).
    39  
    40  `ErrSwitchDuplicatePeerID` is produced by the `PeerSet` used by the [switch](#switchgo).
    41  
    42  `ErrSwitchConnectToSelf` is handled by the [switch](#switchgo),
    43  but currently is not produced outside tests.
    44  
    45  `ErrSwitchAuthenticationFailure` is handled by the [PEX reactor](#pex_reactorgo),
    46  but currently is not produced outside tests.
    47  
    48  `ErrTransportClosed` is produced by the [transport](#transportgo)
    49  and handled by the [switch](#switchgo).
    50  
    51  `ErrNetAddressNoID`, `ErrNetAddressInvalid`, and `ErrNetAddressLookup`
    52  are parsing a string to create an instance of `NetAddress`.
    53  It can be returned in the setup of the [switch](#switchgo)
    54  and of the [PEX reactor](#pex_reactorgo),
    55  as well when the [transport](#transportgo) validates a `NodeInfo`, as part of
    56  the connection handshake.
    57  
    58  `ErrCurrentlyDialingOrExistingAddress` is produced by the [switch](#switchgo),
    59  and handled by the switch and the [PEX reactor](#pex_reactorgo).
    60  
    61  ### `fuzz.go`
    62  
    63  For testing purposes.
    64  
    65  `FuzzedConnection` wraps a `net.Conn` and injects random delays.
    66  
    67  ### `key.go`
    68  
    69  `NodeKey` is the persistent key of a node, namely its private key.
    70  
    71  The `ID` of a node is a string representing the node's public key.
    72  
    73  ### `metrics.go`
    74  
    75  Prometheus `Metrics` exposed by the p2p layer.
    76  
    77  ### `netaddress.go`
    78  
    79  Type `NetAddress` contains the `ID` and the network address (IP and port) of a node.
    80  
    81  The API of the [address book](#addrbookgo) receives and returns `NetAddress` instances.
    82  
    83  This source file was adapted from [`btcd`](https://github.com/btcsuite/btcd),
    84  a Go implementation of Bitcoin.
    85  
    86  ### `node_info.go`
    87  
    88  Interface `NodeInfo` stores the basic information about a node exchanged with a
    89  peer during the handshake.
    90  
    91  It is implemented by `DefaultNodeInfo` type.
    92  
    93  The [switch](#switchgo) stores the local `NodeInfo`.
    94  
    95  The `NodeInfo` of connected peers is produced by the
    96  [transport](#transportgo) during the handshake, and stored in [`Peer`](#peergo) instances.
    97  
    98  ### `peer.go`
    99  
   100  Interface `Peer` represents a connected peer.
   101  
   102  It is implemented by the internal `peer` type.
   103  
   104  The [transport](#transportgo) API methods return `Peer` instances,
   105  wrapping established secure connection with peers.
   106  
   107  The [switch](#switchgo) API methods receive `Peer` instances.
   108  The switch stores connected peers in a `PeerSet`.
   109  
   110  The [`Reactor`](#base_reactorgo) methods, invoked by the switch, receive `Peer` instances.
   111  
   112  ### `peer_set.go`
   113  
   114  Interface `IPeerSet` offers methods to access a table of [`Peer`](#peergo) instances.
   115  
   116  Type `PeerSet` implements a thread-safe table of [`Peer`](#peergo) instances,
   117  used by the [switch](#switchgo).
   118  
   119  The switch provides limited access to this table by returing a `IPeerSet`
   120  instance, used by the [PEX reactor](#pex_reactorgo).
   121  
   122  ### `switch.go`
   123  
   124  Documented in [switch](./switch.md).
   125  
   126  The `Switch` implements the [peer manager](./peer_manager.md) role for inbound peers.
   127  
   128  [`Reactor`](#base_reactorgo)s have access to the `Switch` and may invoke its methods.
   129  This includes the [PEX reactor](#pex_reactorgo).
   130  
   131  ### `transport.go`
   132  
   133  Documented in [transport](./transport.md).
   134  
   135  The `Transport` interface is implemented by `MultiplexTransport`.
   136  
   137  The [switch](#switchgo) contains a `Transport` and uses it to establish
   138  connections with peers.
   139  
   140  ### `types.go`
   141  
   142  Aliases for p2p's `conn` package types.
   143  
   144  ## Package `p2p.conn`
   145  
   146  Implements the connection between CometBFT nodes,
   147  which is encrypted, authenticated, and multiplexed.
   148  
   149  ### `connection.go`
   150  
   151  Implements the `MConnection` type and the `Channel` abstraction.
   152  
   153  A `MConnection` multiplexes a generic network connection (`net.Conn`) into
   154  multiple independent `Channel`s, used by different [`Reactor`](#base_reactorgo)s.
   155  
   156  A [`Peer`](#peergo) stores the `MConnection` instance used to interact with a
   157  peer, which multiplex a [`SecretConnection`](#secret_connectiongo).
   158  
   159  ### `conn_go110.go`
   160  
   161  Support for go 1.10.
   162  
   163  ### `secret_connection.go`
   164  
   165  Implements the `SecretConnection` type, which is an encrypted authenticated
   166  connection built atop a raw network (TCP) connection.
   167  
   168  A [`Peer`](#peergo) stores the `SecretConnection` established by the transport,
   169  which is the underlying connection multiplexed by [`MConnection`](#connectiongo).
   170  
   171  As briefly documented in the [transport](./transport.md#Connection-Upgrade),
   172  a `SecretConnection` implements the Station-To-Station (STS) protocol.
   173  
   174  The `SecretConnection` type implements the `net.Conn` interface,
   175  which is a generic network connection.
   176  
   177  ## Package `p2p.mock`
   178  
   179  Mock implementations of [`Peer`](#peergo) and [`Reactor`](#base_reactorgo) interfaces.
   180  
   181  ## Package `p2p.mocks`
   182  
   183  Code generated by `mockery`.
   184  
   185  ## Package `p2p.pex`
   186  
   187  Implementation of the [PEX reactor](./pex.md).
   188  
   189  ### `addrbook.go`
   190  
   191  Documented in [address book](./addressbook.md).
   192  
   193  This source file was adapted from [`btcd`](https://github.com/btcsuite/btcd),
   194  a Go implementation of Bitcoin.
   195  
   196  ### `errors.go`
   197  
   198  A number of errors produced and handled by the [address book](#addrbookgo).
   199  
   200  `ErrAddrBookNilAddr` is produced by the address book, but handled (logged) by
   201  the [PEX reactor](#pex_reactorgo).
   202  
   203  `ErrUnsolicitedList` is produced and handled by the [PEX protocol](#pex_reactorgo).
   204  
   205  ### `file.go`
   206  
   207  Implements the [address book](#addrbookgo) persistence.
   208  
   209  ### `known_address.go`
   210  
   211  Type `knownAddress` represents an address stored in the [address book](#addrbookgo).
   212  
   213  ### `params.go`
   214  
   215  Constants used by the [address book](#addrbookgo).
   216  
   217  ### `pex_reactor.go`
   218  
   219  Implementation of the [PEX reactor](./pex.md), which is a [`Reactor`](#base_reactorgo).
   220  
   221  This includes the implementation of the [PEX protocol](./pex-protocol.md)
   222  and of the [peer manager](./peer_manager.md) role for outbound peers.
   223  
   224  The PEX reactor also manages an [address book](#addrbookgo) instance.
   225  
   226  ## Package `p2p.trust`
   227  
   228  Go documentation of `Metric` type:
   229  
   230  > // Metric - keeps track of peer reliability
   231  > // See cometbft/docs/architecture/adr-006-trust-metric.md for details
   232  
   233  Not imported by any other CometBFT source file.