Documentation of p2p layer in Tendermint v0.34

[cason]

Documentation of the implementation of the p2p layer (p2p package in v0.34.x branch).

The documentation is based in the analysis of the source code, and follows its organization and the abstractions there defined. The target public of this document are developers, as I hope this documentation will help them to understand the code.

Having said that, there is an initial effort to map implementation abstractions to more high-level concepts. For instance, the documentation of the PEX reactor was split into three parts, representing the roles it implements. The intent here is to support a refactoring of the code that would allow a more clear separation of these roles.

What is not covered by this documentation:

• The general concept of reactors, and their interaction with the p2p layer, specially the the Switch
• The actual implementation of the communication between nodes, which is part of the p2p/conn package
• The routines that allows exchanging messages with peers, part of Peer abstraction and p2p/conn package

Addresses #9089.

[sergio-mena]

What is the rationale to consider them more trustworthy?
Is this distinction (inbound vs outbound) also used for point 2)? If not, then there is a contradiction, IMO, on what is considered trustworthy.

[jmalicevic]

Good point, at the moment the ensurePeersRoutine does not take into consideration whether the peer in the address book is outbound or inbound but does check the rating of the peers (chooses which bucket to take peer from). The PEX request in case 1) is sent immediately to this outbound peer assuming that the node already trusted this peer as the outbound peers are usually preconfigured by the node operators.

[sergio-mena]

Still, I'd add some footnote or something, as the "trustworthy" concept looks more of a heuristic than something well defined.

[sergio-mena]

"banned" is not defined at this point. Please add a forward reference to the "bad peers" section

[sergio-mena]

Can't this cause a periodic churn between buckets if all "good" peers don't fit their corresponding "old" buckets? This churn would be anything but useful, BTW.

[sergio-mena]

Is there a mechanism for a really bad address (simple example: an address that didn't ever work for, say, months) to be deleted from the address book altogether?
I'm thinking of a malicious actor (e.g. a malicious seed node) providing plenty of fake addresses that will then be kept around forever

[sergio-mena]

Ok, I see there is such mechanism in the Buckets section. I guess I agree with @adizere in that (some form of) the Buckets section should appear early on in this file.