The primary goal of the P2P layer is to establish connection with peers in order to exchange messages with them. This issue should individuate and document every possible execution flow that results in an established connection.

Most of the steps associated to connection establishment are documented as part of tendermint/tendermint#9089. The produced documentation, however, fails to provide an easy-to-follow overview of how these steps are combined, i.e. the execution flows that result in a new connection being established with a peer, or in an error to be logged by the node. A factor that complicates this description is the dispersion of individual steps across multiple components: Switch, Transport, PEX reactor, Node, etc.

This documentation could thus enable:

• Improvements in the P2P logging
• Some low-risk P2P refactoring efforts

Definition of Done

The following execution flows should be covered:

• Accepting a connection and adding an inbound peer
• Dialing a peer address and adding an outbound peer (regular and expedite mode)
• Dialing the configured seed nodes and retrieving peer addresses via PEX protocol
• Establishing connections to configured persistent peers, plus reconnecting procedure
• (Optional) Manually dialing and configuring peer addresses via unsafe RPC calls
• (Optional) Connection establishment and management in nodes operating in seed mode