The high-level specification of the P2P layer adopted by CometBFT should be available under spec/p2p.

This directory, however, is not empty, and includes content produced at different times and with distinct approaches.

The goal of this issue is to:

1. Identify, evaluate and classify the existing content
2. Identify important components and execution flows to be documented
3. Propose a new structure for the P2P specification, combining the existing content and contend to be produced

Current content

The P2P specification directory currently contains:

• messages/: documents the message types adopted by the six standard reactors (block sync, consensus, evidence, mempool, PEX, and state sync). Includes also the channel IDs each of the reactors is responsible for.
  • This content needs to be reviewed, in some cases updated (e.g., PEX-reactor messages refer to retracted v0.35 release)
• v0.34/: Documentation of p2p layer in Tendermint v0.34 tendermint/tendermint#9348. First attempt to fully document the implementation of the P2P layer in Tendermint Core. Despite referring to the v0.34.* releases, still applies to the current version.
  • Content to be reorganized for better readability. Currently is overly implementation-specific.
• config.md, connection.md, node.md, peer.md: short summary of main components of the P2P layer, produced in late 2019 (Add Section for P2P tendermint/spec#53).
  • Relevant source of information, although partially outdated. Complementary to the content of v0.34/directory.

Definition of Done

• Overview of the p2p package types and interfaces (implementation-specific)
• Overview of main components of the P2P layer (abstract level)
• Table of contents for the P2P specification