diff --git a/docs/rfc/rfc-101-p2p-bad-peers-checktx.md b/docs/rfc/rfc-101-p2p-bad-peers-checktx.md
index 11150e76402..f263cc29fe8 100644
--- a/docs/rfc/rfc-101-p2p-bad-peers-checktx.md
+++ b/docs/rfc/rfc-101-p2p-bad-peers-checktx.md
@@ -78,7 +78,7 @@ from the node.
The p2p layer implements banning peers by marking them
as bad and removing them from the list of peers to connect to for *at least* a predefined amount of time. This is done by calling the
-[`MarkBad`](https://github.com/cometbft/cometbft/blob/main/spec/p2p/v0.34/addressbook.md#bad-peers) routine implemented by the `Switch`.
+[`MarkBad`](https://github.com/cometbft/cometbft/blob/main/spec/p2p/implementation/addressbook.md#bad-peers) routine implemented by the `Switch`.
If the node does not set the amount of time to be banned, a default value is used.
Note that the timing parameter sets the lower bound for when a peer will be unbanned.
But the p2p layer will only try to connect to banned peers if the node is not sufficiently connected. Thus the node has no
@@ -510,4 +510,4 @@ Otehr than avoiding relying solely on the response code values, there are no imm
- Github discussions on this RFC:
- [CometBFT repo - PR \#78](https://github.com/cometbft/cometbft/pull/78)
- - [Tendermint repo - PR \#9675](https://github.com/tendermint/tendermint/pull/9675)
\ No newline at end of file
+ - [Tendermint repo - PR \#9675](https://github.com/tendermint/tendermint/pull/9675)
diff --git a/p2p/README.md b/p2p/README.md
index 85bb404aa55..aeaa3271dcb 100644
--- a/p2p/README.md
+++ b/p2p/README.md
@@ -4,7 +4,7 @@ The p2p package provides an abstraction around peer-to-peer communication.
Docs:
-- [Connection](https://github.com/cometbft/cometbft/blob/main/spec/p2p/connection.md) for details on how connections and multiplexing work
-- [Peer](https://github.com/cometbft/cometbft/blob/main/spec/p2p/node.md) for details on peer ID, handshakes, and peer exchange
-- [Node](https://github.com/cometbft/cometbft/blob/main/spec/p2p/node.md) for details about different types of nodes and how they should work
-- [Config](https://github.com/cometbft/cometbft/blob/main/spec/p2p/config.md) for details on some config option
+- [Connection](https://github.com/cometbft/cometbft/blob/main/spec/p2p/legacy-docs/connection.md) for details on how connections and multiplexing work
+- [Peer](https://github.com/cometbft/cometbft/blob/main/spec/p2p/legacy-docs/node.md) for details on peer ID, handshakes, and peer exchange
+- [Node](https://github.com/cometbft/cometbft/blob/main/spec/p2p/legacy-docs/node.md) for details about different types of nodes and how they should work
+- [Config](https://github.com/cometbft/cometbft/blob/main/spec/p2p/legacy-docs/config.md) for details on some config option
diff --git a/spec/README.md b/spec/README.md
index 921c68b7cb0..61c4d3fc927 100644
--- a/spec/README.md
+++ b/spec/README.md
@@ -35,12 +35,12 @@ please submit them to our [bug bounty](https://cometbft.com/security)!
### P2P and Network Protocols
-- [The Base P2P Layer](./p2p/node.md): multiplex the protocols ("reactors") on authenticated and encrypted TCP connections
-- [Peer Exchange (PEX)](./p2p/messages/pex.md): gossip known peer addresses so peers can find each other
-- [Block Sync](./p2p/messages/block-sync.md): gossip blocks so peers can catch up quickly
-- [Consensus](./p2p/messages/consensus.md): gossip votes and block parts so new blocks can be committed
-- [Mempool](./p2p/messages/mempool.md): gossip transactions so they get included in blocks
-- [Evidence](./p2p/messages/evidence.md): sending invalid evidence will stop the peer
+- [The Base P2P Layer](./p2p/legacy-docs/node.md): multiplex the protocols ("reactors") on authenticated and encrypted TCP connections
+- [Peer Exchange (PEX)](./p2p/legacy-docs/messages/pex.md): gossip known peer addresses so peers can find each other
+- [Block Sync](./p2p/legacy-docs/messages/block-sync.md): gossip blocks so peers can catch up quickly
+- [Consensus](./p2p/legacy-docs/messages/consensus.md): gossip votes and block parts so new blocks can be committed
+- [Mempool](./p2p/legacy-docs/messages/mempool.md): gossip transactions so they get included in blocks
+- [Evidence](./p2p/legacy-docs/messages/evidence.md): sending invalid evidence will stop the peer
### RPC
diff --git a/spec/abci/abci++_basic_concepts.md b/spec/abci/abci++_basic_concepts.md
index 08675aeffa0..d021b9fd55e 100644
--- a/spec/abci/abci++_basic_concepts.md
+++ b/spec/abci/abci++_basic_concepts.md
@@ -152,7 +152,7 @@ call sequences of these methods.
State sync allows new nodes to rapidly bootstrap by discovering, fetching, and applying
state machine (application) snapshots instead of replaying historical blocks. For more details, see the
-[state sync documentation](../p2p/messages/state-sync.md).
+[state sync documentation](../p2p/legacy-docs/messages/state-sync.md).
New nodes discover and request snapshots from other nodes in the P2P network.
A CometBFT node that receives a request for snapshots from a peer will call
diff --git a/spec/abci/abci++_methods.md b/spec/abci/abci++_methods.md
index a50f04653c0..acbc32c8928 100644
--- a/spec/abci/abci++_methods.md
+++ b/spec/abci/abci++_methods.md
@@ -255,7 +255,7 @@ title: Methods
can be spoofed by adversaries, so applications should employ additional verification schemes
to avoid denial-of-service attacks. The verified `AppHash` is automatically checked against
the restored application at the end of snapshot restoration.
- * For more information, see the `Snapshot` data type or the [state sync section](../p2p/messages/state-sync.md).
+ * For more information, see the `Snapshot` data type or the [state sync section](../p2p/legacy-docs/messages/state-sync.md).
### ApplySnapshotChunk
@@ -775,7 +775,7 @@ Most of the data structures used in ABCI are shared [common data structures](../
| metadata | bytes | Arbitrary application metadata, for example chunk hashes or other verification data. | 5 |
* **Usage**:
- * Used for state sync snapshots, see the [state sync section](../p2p/messages/state-sync.md) for details.
+ * Used for state sync snapshots, see the [state sync section](../p2p/legacy-docs/messages/state-sync.md) for details.
* A snapshot is considered identical across nodes only if _all_ fields are equal (including
`Metadata`). Chunks may be retrieved from all nodes that have the same snapshot.
* When sent across the network, a snapshot message can be at most 4 MB.
diff --git a/spec/p2p/README.md b/spec/p2p/README.md
new file mode 100644
index 00000000000..29efd8ecadf
--- /dev/null
+++ b/spec/p2p/README.md
@@ -0,0 +1,46 @@
+---
+order: 1
+parent:
+ title: P2P
+ order: 6
+---
+
+# Peer-to-Peer Communication
+
+A CometBFT network is composed of multiple CometBFT instances, hereafter called
+`nodes`, that interact by exchanging messages.
+
+The CometBFT protocols are designed under the assumption of a partially-connected network model.
+This means that a node is not assumed to be directly connected to every other
+node in the network.
+Instead, each node is directly connected to only a subset of other nodes,
+hereafter called its `peers`.
+
+The peer-to-peer (p2p) communication layer is then the component of CometBFT that:
+
+1. establishes connections between nodes in a CometBFT network
+2. manages the communication between a node and the connected peers
+3. intermediates the exchange of messages between peers in CometBFT protocols
+
+The specification the p2p layer is a work in progress,
+tracked by [issue #19](https://github.com/cometbft/cometbft/issues/19).
+The current content is organized as follows:
+
+- [`implementation`](./implementation/README.md): documents the current state
+ of the implementation of the p2p layer, covering the main components of the
+ `p2p` package. The documentation covers, in a fairly comprehensive way,
+ the items 1. and 2. from the list above.
+- [`reactor-api`](./reactor-api/README.md): specifies the API offered by the
+ p2p layer to the protocol layer, through the `Reactor` abstraction.
+ This is a high-level specification (i.e., it should not be implementation-specific)
+ of the p2p layer API, covering item 3. from the list above.
+- [`legacy-docs`](./legacy-docs/): We keep older documentation in
+ the `legacy-docs` directory, as overall, it contains useful information.
+ However, part of this content is redundant,
+ being more comprehensively covered in more recent documents,
+ and some implementation details might be outdated
+ (see [issue #981](https://github.com/cometbft/cometbft/issues/981)).
+
+In addition to this content, some unfinished, work in progress, and auxiliary
+material can be found in the
+[knowledge-base](https://github.com/cometbft/knowledge-base/tree/main/p2p) repository.
diff --git a/spec/p2p/reactor/p2p-reactors.png b/spec/p2p/images/p2p-reactors.png
similarity index 100%
rename from spec/p2p/reactor/p2p-reactors.png
rename to spec/p2p/images/p2p-reactors.png
diff --git a/spec/p2p/v0.34/img/p2p_state.png b/spec/p2p/images/p2p_state.png
similarity index 100%
rename from spec/p2p/v0.34/img/p2p_state.png
rename to spec/p2p/images/p2p_state.png
diff --git a/spec/p2p/implementation/README.md b/spec/p2p/implementation/README.md
new file mode 100644
index 00000000000..b32c95658e0
--- /dev/null
+++ b/spec/p2p/implementation/README.md
@@ -0,0 +1,38 @@
+# Implementation of the p2p layer
+
+This section documents the implementation of the peer-to-peer (p2p)
+communication layer in CometBFT.
+
+The documentation was [produced](https://github.com/tendermint/tendermint/pull/9348)
+using the `v0.34.*` releases
+and the branch [`v0.34.x`](https://github.com/cometbft/cometbft/tree/v0.34.x)
+of this repository as reference.
+As there were no substancial changes in the p2p implementation, the
+documentation also applies to the releases `v0.37.*` and `v0.38.*` [^v35].
+
+[^v35]: The releases `v0.35.*` and `v0.36.*`, which included a major
+ refactoring of the p2p layer implementation, were [discontinued][v35postmorten].
+
+[v35postmorten]: https://interchain-io.medium.com/discontinuing-tendermint-v0-35-a-postmortem-on-the-new-networking-layer-3696c811dabc
+
+## Contents
+
+The documentation follows the organization of the
+[`p2p` package](https://github.com/cometbft/cometbft/tree/v0.34.x/p2p),
+which implements the following abstractions:
+
+- [Transport](./transport.md): establishes secure and authenticated
+ connections with peers;
+- [Switch](./switch.md): responsible for dialing peers and accepting
+ connections from peers, for managing established connections, and for
+ routing messages between the reactors and peers,
+ that is, between local and remote instances of the CometBFT protocols;
+- [PEX Reactor](./pex.md): due to the several roles of this component, the
+ documentation is split in several parts:
+ - [Peer Exchange protocol](./pex-protocol.md): enables nodes to exchange peer addresses, thus implementing a peer discovery service;
+ - [Address Book](./addressbook.md): stores discovered peer addresses and
+ quality metrics associated to peers with which the node has interacted;
+ - [Peer Manager](./peer_manager.md): defines when and to which peers a node
+ should dial, in order to establish outbound connections;
+- [Types](./types.md) and [Configuration](./configuration.md) provide a list of
+ existing types and configuration parameters used by the p2p package.
diff --git a/spec/p2p/v0.34/addressbook.md b/spec/p2p/implementation/addressbook.md
similarity index 99%
rename from spec/p2p/v0.34/addressbook.md
rename to spec/p2p/implementation/addressbook.md
index 8fd2cc3a2c8..26b9504214b 100644
--- a/spec/p2p/v0.34/addressbook.md
+++ b/spec/p2p/implementation/addressbook.md
@@ -303,7 +303,7 @@ The `MarkBad` method marks a peer as bad and bans it for a period of time.
This method is only invoked within the PEX reactor, with a banning time of 24
hours, for the following reasons:
-- A peer misbehaves in the [PEX protocol](pex-protocol.md#misbehavior)
+- A peer misbehaves in the [PEX protocol](./pex-protocol.md#misbehavior)
- When the `maxAttemptsToDial` limit (`16`) is reached for a peer
- If an `ErrSwitchAuthenticationFailure` error is returned when dialing a peer
diff --git a/spec/p2p/v0.34/configuration.md b/spec/p2p/implementation/configuration.md
similarity index 71%
rename from spec/p2p/v0.34/configuration.md
rename to spec/p2p/implementation/configuration.md
index 53ac3183db5..977c8c3e049 100644
--- a/spec/p2p/v0.34/configuration.md
+++ b/spec/p2p/implementation/configuration.md
@@ -6,25 +6,25 @@ This document contains configurable parameters a node operator can use to tune t
| --- | --- | ---|
| ListenAddress | "tcp://0.0.0.0:26656" | Address to listen for incoming connections (0.0.0.0:0 means any interface, any port) |
| ExternalAddress | "" | Address to advertise to peers for them to dial |
-| [Seeds](pex-protocol.md#seed-nodes) | empty | Comma separated list of seed nodes to connect to (ID@host:port )|
-| [Persistent peers](peer_manager.md#persistent-peers) | empty | Comma separated list of nodes to keep persistent connections to (ID@host:port ) |
+| [Seeds](./pex-protocol.md#seed-nodes) | empty | Comma separated list of seed nodes to connect to (ID@host:port )|
+| [Persistent peers](./peer_manager.md#persistent-peers) | empty | Comma separated list of nodes to keep persistent connections to (ID@host:port ) |
| UPNP | false | UPNP port forwarding enabled |
-| [AddrBook](addressbook.md) | defaultAddrBookPath | Path do address book |
+| [AddrBook](./addressbook.md) | defaultAddrBookPath | Path do address book |
| AddrBookStrict | true | Set true for strict address routability rules and false for private or local networks |
-| [MaxNumInboundPeers](switch.md#accepting-peers) | 40 | Maximum number of inbound peers |
-| [MaxNumOutboundPeers](peer_manager.md#ensure-peers) | 10 | Maximum number of outbound peers to connect to, excluding persistent peers |
-| [UnconditionalPeers](switch.md#accepting-peers) | empty | These are IDs of the peers which are allowed to be (re)connected as both inbound or outbound regardless of whether the node reached `max_num_inbound_peers` or `max_num_outbound_peers` or not. |
+| [MaxNumInboundPeers](./switch.md#accepting-peers) | 40 | Maximum number of inbound peers |
+| [MaxNumOutboundPeers](./peer_manager.md#ensure-peers) | 10 | Maximum number of outbound peers to connect to, excluding persistent peers |
+| [UnconditionalPeers](./switch.md#accepting-peers) | empty | These are IDs of the peers which are allowed to be (re)connected as both inbound or outbound regardless of whether the node reached `max_num_inbound_peers` or `max_num_outbound_peers` or not. |
| PersistentPeersMaxDialPeriod| 0 * time.Second | Maximum pause when redialing a persistent peer (if zero, exponential backoff is used) |
| FlushThrottleTimeout |100 * time.Millisecond| Time to wait before flushing messages out on the connection |
| MaxPacketMsgPayloadSize | 1024 | Maximum size of a message packet payload, in bytes |
| SendRate | 5120000 (5 mB/s) | Rate at which packets can be sent, in bytes/second |
| RecvRate | 5120000 (5 mB/s) | Rate at which packets can be received, in bytes/second|
-| [PexReactor](pex.md) | true | Set true to enable the peer-exchange reactor |
+| [PexReactor](./pex.md) | true | Set true to enable the peer-exchange reactor |
| SeedMode | false | Seed mode, in which node constantly crawls the network and looks for. Does not work if the peer-exchange reactor is disabled. |
| PrivatePeerIDs | empty | Comma separated list of peer IDsthat we do not add to the address book or gossip to other peers. They stay private to us. |
| AllowDuplicateIP | false | Toggle to disable guard against peers connecting from the same ip.|
-| [HandshakeTimeout](transport.md#connection-upgrade) | 20 * time.Second | Timeout for handshake completion between peers |
-| [DialTimeout](switch.md#dialing-peers) | 3 * time.Second | Timeout for dialing a peer |
+| [HandshakeTimeout](./transport.md#connection-upgrade) | 20 * time.Second | Timeout for handshake completion between peers |
+| [DialTimeout](./switch.md#dialing-peers) | 3 * time.Second | Timeout for dialing a peer |
These parameters can be set using the `$CMTHOME/config/config.toml` file. A subset of them can also be changed via command line using the following command line flags:
diff --git a/spec/p2p/v0.34/peer_manager.md b/spec/p2p/implementation/peer_manager.md
similarity index 94%
rename from spec/p2p/v0.34/peer_manager.md
rename to spec/p2p/implementation/peer_manager.md
index ba2e75ef323..4f83cc6dfdf 100644
--- a/spec/p2p/v0.34/peer_manager.md
+++ b/spec/p2p/implementation/peer_manager.md
@@ -124,19 +124,19 @@ This is not done in the p2p package, but it is part of the procedure to set up a
The picture below is a first attempt of illustrating the life cycle of an outbound peer:
-
+
A peer can be in the following states:
- Candidate peers: peer addresses stored in the address boook, that can be
retrieved via the [`PickAddress`](./addressbook.md#pick-address) method
-- [Dialing](switch.md#dialing-peers): peer addresses that are currently being
+- [Dialing](./switch.md#dialing-peers): peer addresses that are currently being
dialed. This state exists to ensure that a single dialing routine exist per peer.
-- [Reconnecting](switch.md#reconnect-to-peer): persistent peers to which a node
+- [Reconnecting](./switch.md#reconnect-to-peer): persistent peers to which a node
is currently reconnecting, as a previous connection attempt has failed.
- Connected peers: peers that a node has successfully dialed, added as outbound peers.
-- [Bad peers](addressbook.md#bad-peers): peers marked as bad in the address
- book due to exhibited [misbehavior](pex-protocol.md#misbehavior).
+- [Bad peers](./addressbook.md#bad-peers): peers marked as bad in the address
+ book due to exhibited [misbehavior](./pex-protocol.md#misbehavior).
Peers can be reinstated after being marked as bad.
## Pending of documentation
diff --git a/spec/p2p/v0.34/pex-protocol.md b/spec/p2p/implementation/pex-protocol.md
similarity index 98%
rename from spec/p2p/v0.34/pex-protocol.md
rename to spec/p2p/implementation/pex-protocol.md
index ed88993026c..760a56bd9dc 100644
--- a/spec/p2p/v0.34/pex-protocol.md
+++ b/spec/p2p/implementation/pex-protocol.md
@@ -78,7 +78,7 @@ Sending a PEX response to a peer that has not requested peer addresses
is also considered a misbehavior.
So, if a PEX response is received from a peer that is not registered in
the `requestsSent` set, a `ErrUnsolicitedList` error is produced.
-This leads the peer to be disconnected and [marked as a bad peer](addressbook.md#bad-peers).
+This leads the peer to be disconnected and [marked as a bad peer](./addressbook.md#bad-peers).
## Providing Addresses
@@ -102,7 +102,7 @@ The `receiveRequest` method is responsible for verifying this condition.
The node keeps a `lastReceivedRequests` map with the time of the last PEX
request received from every peer.
If the interval between successive requests is less than the minimum accepted
-one, the peer is disconnected and [marked as a bad peer](addressbook.md#bad-peers).
+one, the peer is disconnected and [marked as a bad peer](./addressbook.md#bad-peers).
An exception is made for the first two PEX requests received from a peer.
> The probably reason is that, when a new peer is added, the two conditions for
@@ -150,7 +150,7 @@ peers, the seed node sends a PEX request.
Dialing a selected peer address can fail for multiple reasons.
The seed node might have attempted to dial the peer too many times.
-In this case, the peer address is marked as [bad in the address book](addressbook.md#bad-peers).
+In this case, the peer address is marked as [bad in the address book](./addressbook.md#bad-peers).
The seed node might have attempted to dial the peer recently, without success,
and the exponential `backoffDuration` has not yet passed.
Or the current connection attempt might fail, which is registered in the address book.
diff --git a/spec/p2p/v0.34/pex.md b/spec/p2p/implementation/pex.md
similarity index 100%
rename from spec/p2p/v0.34/pex.md
rename to spec/p2p/implementation/pex.md
diff --git a/spec/p2p/v0.34/switch.md b/spec/p2p/implementation/switch.md
similarity index 95%
rename from spec/p2p/v0.34/switch.md
rename to spec/p2p/implementation/switch.md
index 1d50108f2b9..4497fef96e2 100644
--- a/spec/p2p/v0.34/switch.md
+++ b/spec/p2p/implementation/switch.md
@@ -50,11 +50,11 @@ The `DialPeersAsync` method receives a list of peer addresses (strings)
and dials all of them in parallel.
It is invoked in two situations:
-- In the [setup](https://github.com/cometbft/cometbft/blob/29c5a062d23aaef653f11195db55c45cd9e02715/node/node.go#L985) of a node, to establish connections with every configured
- persistent peer
+- In the [setup](https://github.com/cometbft/cometbft/blob/v0.34.x/node/node.go#L987)
+of a node, to establish connections with every configured persistent peer
- In the RPC package, to implement two unsafe RPC commands, not used in production:
- [`DialSeeds`](https://github.com/cometbft/cometbft/blob/29c5a062d23aaef653f11195db55c45cd9e02715/rpc/core/net.go#L47) and
- [`DialPeers`](https://github.com/cometbft/cometbft/blob/29c5a062d23aaef653f11195db55c45cd9e02715/rpc/core/net.go#L87)
+ [`DialSeeds`](https://github.com/cometbft/cometbft/blob/v0.34.x/rpc/core/net.go#L47) and
+ [`DialPeers`](https://github.com/cometbft/cometbft/blob/v0.34.x/rpc/core/net.go#L87)
The received list of peer addresses to dial is parsed into `NetAddress` instances.
In case of parsing errors, the method returns. An exception is made for
diff --git a/spec/p2p/v0.34/transport.md b/spec/p2p/implementation/transport.md
similarity index 95%
rename from spec/p2p/v0.34/transport.md
rename to spec/p2p/implementation/transport.md
index 457fa1e1cbb..20d4db87a43 100644
--- a/spec/p2p/v0.34/transport.md
+++ b/spec/p2p/implementation/transport.md
@@ -43,9 +43,9 @@ The `NetAddress` method exports the listen address configured for the transport.
The maximum number of simultaneous incoming connections accepted by the listener
is bound to `MaxNumInboundPeer` plus the configured number of unconditional peers,
using the `MultiplexTransportMaxIncomingConnections` option,
-in the node [initialization](https://github.com/cometbft/cometbft/blob/29c5a062d23aaef653f11195db55c45cd9e02715/node/node.go#L563).
+in the node [initialization](https://github.com/cometbft/cometbft/blob/v0.34.x/node/node.go#L563).
-This method is called when a node is [started](https://github.com/cometbft/cometbft/blob/29c5a062d23aaef653f11195db55c45cd9e02715/node/node.go#L972).
+This method is called when a node is [started](https://github.com/cometbft/cometbft/blob/v0.34.x/node/node.go#L974).
In case of errors, the `acceptPeers` routine is not started and the error is returned.
## Accept
@@ -191,7 +191,7 @@ an `ErrRejected` error with reason `isIncompatible` is returned.
The `Close` method closes the TCP listener created by the `Listen` method,
and sends a signal for interrupting the `acceptPeers` routine.
-This method is called when a node is [stopped](https://github.com/cometbft/cometbft/blob/46badfabd9d5491c78283a0ecdeb695e21785508/node/node.go#L1019).
+This method is called when a node is [stopped](https://github.com/cometbft/cometbft/blob/v0.34.x/node/node.go#L1023).
## Cleanup
@@ -216,7 +216,7 @@ For this reason, this method is not invoked with a started transport.
> Note that the default list of supported channel IDs, including the default reactors,
> is provided to the transport as its original `NodeInfo` record.
-[peer-sts]: https://github.com/cometbft/cometbft/blob/main/spec/p2p/peer.md#authenticated-encryption-handshake
-[peer-handshake]:https://github.com/cometbft/cometbft/blob/main/spec/p2p/peer.md#cometbft-version-handshake
+[peer-sts]: ../legacy-docs/peer.md#authenticated-encryption-handshake
+[peer-handshake]: ../legacy-docs/peer.md#cometbft-version-handshake
[sts-paper]: https://link.springer.com/article/10.1007/BF00124891
[sts-paper-pdf]: https://github.com/tendermint/tendermint/blob/0.1/docs/sts-final.pdf
diff --git a/spec/p2p/v0.34/types.md b/spec/p2p/implementation/types.md
similarity index 100%
rename from spec/p2p/v0.34/types.md
rename to spec/p2p/implementation/types.md
diff --git a/spec/p2p/config.md b/spec/p2p/legacy-docs/config.md
similarity index 100%
rename from spec/p2p/config.md
rename to spec/p2p/legacy-docs/config.md
diff --git a/spec/p2p/connection.md b/spec/p2p/legacy-docs/connection.md
similarity index 100%
rename from spec/p2p/connection.md
rename to spec/p2p/legacy-docs/connection.md
diff --git a/spec/p2p/messages/README.md b/spec/p2p/legacy-docs/messages/README.md
similarity index 100%
rename from spec/p2p/messages/README.md
rename to spec/p2p/legacy-docs/messages/README.md
diff --git a/spec/p2p/messages/block-sync.md b/spec/p2p/legacy-docs/messages/block-sync.md
similarity index 92%
rename from spec/p2p/messages/block-sync.md
rename to spec/p2p/legacy-docs/messages/block-sync.md
index b00c3062c57..49afcc417ed 100644
--- a/spec/p2p/messages/block-sync.md
+++ b/spec/p2p/legacy-docs/messages/block-sync.md
@@ -39,8 +39,8 @@ It also contains an extended commit _iff_ vote extensions are enabled at the blo
| Name | Type | Description | Field Number |
|-----------|----------------------------------------------------------------|---------------------------------|--------------|
-| Block | [Block](../../core/data_structures.md#block) | Requested Block | 1 |
-| ExtCommit | [ExtendedCommit](../../core/data_structures.md#extendedcommit) | Sender's LastCommit information | 2 |
+| Block | [Block](../../../core/data_structures.md#block) | Requested Block | 1 |
+| ExtCommit | [ExtendedCommit](../../../core/data_structures.md#extendedcommit) | Sender's LastCommit information | 2 |
### StatusRequest
diff --git a/spec/p2p/messages/consensus.md b/spec/p2p/legacy-docs/messages/consensus.md
similarity index 89%
rename from spec/p2p/messages/consensus.md
rename to spec/p2p/legacy-docs/messages/consensus.md
index ebb7fab7fca..aae0cdbe132 100644
--- a/spec/p2p/messages/consensus.md
+++ b/spec/p2p/legacy-docs/messages/consensus.md
@@ -24,7 +24,7 @@ next block in the blockchain should be.
| Name | Type | Description | Field Number |
|----------|----------------------------------------------------|----------------------------------------|--------------|
-| proposal | [Proposal](../../core/data_structures.md#proposal) | Proposed Block to come to consensus on | 1 |
+| proposal | [Proposal](../../../core/data_structures.md#proposal) | Proposed Block to come to consensus on | 1 |
### Vote
@@ -38,7 +38,7 @@ message is signed by the validator private key.
| Name | Type | Description | Field Number |
|------|--------------------------------------------|---------------------------|--------------|
-| vote | [Vote](../../core/data_structures.md#vote) | Vote for a proposed Block | 1 |
+| vote | [Vote](../../../core/data_structures.md#vote) | Vote for a proposed Block | 1 |
### BlockPart
@@ -49,7 +49,7 @@ and the block part.
|--------|--------------------------------------------|----------------------------------------|--------------|
| height | int64 | Height of corresponding block. | 1 |
| round | int32 | Round of voting to finalize the block. | 2 |
-| part | [Part](../../core/data_structures.md#part) | A part of the block. | 3 |
+| part | [Part](../../../core/data_structures.md#part) | A part of the block. | 3 |
### NewRoundStep
@@ -79,7 +79,7 @@ In case the block is also committed, then IsCommit flag is set to true.
|-----------------------|--------------------------------------------------------------|----------------------------------------|--------------|
| height | int64 | Height of corresponding block | 1 |
| round | int32 | Round of voting to finalize the block. | 2 |
-| block_part_set_header | [PartSetHeader](../../core/data_structures.md#partsetheader) | | 3 |
+| block_part_set_header | [PartSetHeader](../../../core/data_structures.md#partsetheader) | | 3 |
| block_parts | int32 | | 4 |
| is_commit | bool | | 5 |
@@ -104,7 +104,7 @@ round, vote type and the index of the validator that is the originator of the co
|--------|------------------------------------------------------------------|----------------------------------------|--------------|
| height | int64 | Height of corresponding block | 1 |
| round | int32 | Round of voting to finalize the block. | 2 |
-| type | [SignedMessageType](../../core/data_structures.md#signedmsgtype) | | 3 |
+| type | [SignedMessageType](../../../core/data_structures.md#signedmsgtype) | | 3 |
| index | int32 | | 4 |
### VoteSetMaj23
@@ -116,7 +116,7 @@ It contains height, round, vote type and the BlockID.
|--------|------------------------------------------------------------------|----------------------------------------|--------------|
| height | int64 | Height of corresponding block | 1 |
| round | int32 | Round of voting to finalize the block. | 2 |
-| type | [SignedMessageType](../../core/data_structures.md#signedmsgtype) | | 3 |
+| type | [SignedMessageType](../../../core/data_structures.md#signedmsgtype) | | 3 |
### VoteSetBits
@@ -128,8 +128,8 @@ the votes a process has.
|----------|------------------------------------------------------------------|----------------------------------------|--------------|
| height | int64 | Height of corresponding block | 1 |
| round | int32 | Round of voting to finalize the block. | 2 |
-| type | [SignedMessageType](../../core/data_structures.md#signedmsgtype) | | 3 |
-| block_id | [BlockID](../../core/data_structures.md#blockid) | | 4 |
+| type | [SignedMessageType](../../../core/data_structures.md#signedmsgtype) | | 3 |
+| block_id | [BlockID](../../../core/data_structures.md#blockid) | | 4 |
| votes | BitArray | Round of voting to finalize the block. | 5 |
### Message
diff --git a/spec/p2p/messages/evidence.md b/spec/p2p/legacy-docs/messages/evidence.md
similarity index 78%
rename from spec/p2p/messages/evidence.md
rename to spec/p2p/legacy-docs/messages/evidence.md
index 34fc40a9155..7db104b3477 100644
--- a/spec/p2p/messages/evidence.md
+++ b/spec/p2p/legacy-docs/messages/evidence.md
@@ -16,8 +16,8 @@ Evidence has one channel. The channel identifier is listed below.
### EvidenceList
-EvidenceList consists of a list of verified evidence. This evidence will already have been propagated throughout the network. EvidenceList is used in two places, as a p2p message and within the block [block](../../core/data_structures.md#block) as well.
+EvidenceList consists of a list of verified evidence. This evidence will already have been propagated throughout the network. EvidenceList is used in two places, as a p2p message and within the block [block](../../../core/data_structures.md#block) as well.
| Name | Type | Description | Field Number |
|----------|-------------------------------------------------------------|------------------------|--------------|
-| evidence | repeated [Evidence](../../core/data_structures.md#evidence) | List of valid evidence | 1 |
+| evidence | repeated [Evidence](../../../core/data_structures.md#evidence) | List of valid evidence | 1 |
diff --git a/spec/p2p/messages/mempool.md b/spec/p2p/legacy-docs/messages/mempool.md
similarity index 100%
rename from spec/p2p/messages/mempool.md
rename to spec/p2p/legacy-docs/messages/mempool.md
diff --git a/spec/p2p/messages/pex.md b/spec/p2p/legacy-docs/messages/pex.md
similarity index 100%
rename from spec/p2p/messages/pex.md
rename to spec/p2p/legacy-docs/messages/pex.md
diff --git a/spec/p2p/messages/state-sync.md b/spec/p2p/legacy-docs/messages/state-sync.md
similarity index 94%
rename from spec/p2p/messages/state-sync.md
rename to spec/p2p/legacy-docs/messages/state-sync.md
index cfc958e08da..e7be056c442 100644
--- a/spec/p2p/messages/state-sync.md
+++ b/spec/p2p/legacy-docs/messages/state-sync.md
@@ -89,9 +89,9 @@ if necessary. The light block at the height of the snapshot will be used to veri
| Name | Type | Description | Field Number |
|---------------|---------------------------------------------------------|--------------------------------------|--------------|
-| light_block | [LightBlock](../../core/data_structures.md#lightblock) | Light block at the height requested | 1 |
+| light_block | [LightBlock](../../../core/data_structures.md#lightblock) | Light block at the height requested | 1 |
-State sync will use [light client verification](../../../spec/light-client/verification/README.md) to verify
+State sync will use [light client verification](../../../light-client/verification/README.md) to verify
the light blocks.
If no state sync is in progress (i.e. during normal operation), any unsolicited response messages
@@ -113,7 +113,7 @@ A reciever to the request will use the state store to fetch the consensus params
| Name | Type | Description | Field Number |
|----------|--------|---------------------------------|--------------|
| height | uint64 | Height of the consensus params | 1 |
-| consensus_params | [ConsensusParams](../../core/data_structures.md#ConsensusParams) | Consensus params at the height requested | 2 |
+| consensus_params | [ConsensusParams](../../../core/data_structures.md#ConsensusParams) | Consensus params at the height requested | 2 |
### Message
diff --git a/spec/p2p/node.md b/spec/p2p/legacy-docs/node.md
similarity index 100%
rename from spec/p2p/node.md
rename to spec/p2p/legacy-docs/node.md
diff --git a/spec/p2p/peer.md b/spec/p2p/legacy-docs/peer.md
similarity index 100%
rename from spec/p2p/peer.md
rename to spec/p2p/legacy-docs/peer.md
diff --git a/spec/p2p/reactor/README.md b/spec/p2p/reactor-api/README.md
similarity index 92%
rename from spec/p2p/reactor/README.md
rename to spec/p2p/reactor-api/README.md
index e961209019b..401805c4b90 100644
--- a/spec/p2p/reactor/README.md
+++ b/spec/p2p/reactor-api/README.md
@@ -7,7 +7,7 @@ reactors.
The diagram below summarizes this interaction, namely the **northbound interface**
of the p2p communication layer, representing some relevant event flows:
-
+
Each of the protocols running a CometBFT node implements a reactor and registers
the implementation with the p2p layer.
@@ -40,6 +40,4 @@ The remaining of the documentation is organized as follows:
layer to the reactors, through the `Switch` and `Peer` abstractions.
In other words, the interaction of the protocol layer with the p2p layer (top-down).
-> This is a work in progress, tracked by [issue #599](https://github.com/cometbft/cometbft/issues/599).
-
[reactor-interface]: ../../../p2p/base_reactor.go
diff --git a/spec/p2p/reactor/p2p-api.md b/spec/p2p/reactor-api/p2p-api.md
similarity index 100%
rename from spec/p2p/reactor/p2p-api.md
rename to spec/p2p/reactor-api/p2p-api.md
diff --git a/spec/p2p/reactor/reactor.md b/spec/p2p/reactor-api/reactor.md
similarity index 100%
rename from spec/p2p/reactor/reactor.md
rename to spec/p2p/reactor-api/reactor.md
diff --git a/spec/p2p/reactor/reactor.qnt b/spec/p2p/reactor-api/reactor.qnt
similarity index 100%
rename from spec/p2p/reactor/reactor.qnt
rename to spec/p2p/reactor-api/reactor.qnt
diff --git a/spec/p2p/readme.md b/spec/p2p/readme.md
deleted file mode 100644
index e7f57c30263..00000000000
--- a/spec/p2p/readme.md
+++ /dev/null
@@ -1,13 +0,0 @@
----
-order: 1
-parent:
- title: P2P
- order: 6
----
-
-# Peer-to-Peer Communication
-
-The operation of the p2p adopted in production CometBFT networks is [HERE](./v0.34/).
-
-> This is part of an ongoing [effort](https://github.com/cometbft/cometbft/issues/19)
-> to produce a high-level specification of the operation of the p2p layer.
diff --git a/spec/p2p/v0.34/README.md b/spec/p2p/v0.34/README.md
deleted file mode 100644
index 017e1001f66..00000000000
--- a/spec/p2p/v0.34/README.md
+++ /dev/null
@@ -1,70 +0,0 @@
-# Peer-to-Peer Communication
-
-This document describes the implementation of the peer-to-peer (p2p)
-communication layer in CometBFT.
-
-It is part of an [effort](https://github.com/cometbft/cometbft/issues/19)
-to produce a high-level specification of the operation of the p2p layer adopted
-in production CometBFT networks.
-
-This documentation, therefore, considers the releases `0.34.*` of CometBFT, more
-specifically, the branch [`v0.34.x`](https://github.com/cometbft/cometbft/tree/v0.34.x)
-of this repository.
-
-## Overview
-
-A CometBFT network is composed of multiple CometBFT instances, hereafter
-called **nodes**, that interact by exchanging messages.
-
-CometBFT assumes a partially-connected network model.
-This means that a node is not assumed to be directly connected to every other
-node in the network.
-Instead, each node is directly connected to a subset of other nodes in the
-network, hereafter called its **peers**.
-
-The peer-to-peer (p2p) communication layer is responsible for establishing
-connections between nodes in a CometBFT network,
-for managing the communication between a node and its peers,
-and for intermediating the exchange of messages between peers in CometBFT protocols.
-
-## Contents
-
-The documentation follows the organization of the `p2p` package of CometBFT,
-which implements the following abstractions:
-
-- [Transport](./transport.md): establishes secure and authenticated
- connections with peers;
-- [Switch](./switch.md): responsible for dialing peers and accepting
- connections from peers, for managing established connections, and for
- routing messages between the reactors and peers,
- that is, between local and remote instances of the CometBFT protocols;
-- [PEX Reactor](./pex.md): a reactor is the implementation of a protocol which
- exchanges messages through the p2p layer. The PEX reactor manages the [Address Book](./addressbook.md) and implements both the [PEX protocol](./pex-protocol.md) and the [Peer Manager](./peer_manager.md) role.
- - [Peer Exchange protocol](./pex-protocol.md): enables nodes to exchange peer addresses, thus implementing a peer discovery service;
- - [Address Book](./addressbook.md): stores discovered peer addresses and
- quality metrics associated to peers with which the node has interacted;
- - [Peer Manager](./peer_manager.md): defines when and to which peers a node
- should dial, in order to establish outbound connections;
-- Finally, [Types](./types.md) and [Configuration](./configuration.md) provide
- a list of existing types and configuration parameters used by the p2p layer implementation.
-
-## Further References
-
-Existing documentation referring to the p2p layer:
-
-- : p2p-related
- configuration flags; overview of connections, peer instances, and reactors;
- overview of peer discovery and node types; peer identity, secure connections
- and peer authentication handshake.
-- : message
- types and channel IDs of Block Sync, Mempool, Evidence, State Sync, PEX, and
- Consensus reactors.
-- : the p2p layer
- configuration and operation is documented in several pages.
- This content is not necessarily up-to-date, some settings and concepts may
- refer to the release `v0.35`, that was [discontinued][v35postmorten].
-- :
- peer types, peer discovery, peer management overview, address book and peer
- ranking. This documentation refers to the release `v0.35`, that was [discontinued][v35postmorten].
-
-[v35postmorten]: https://interchain-io.medium.com/discontinuing-tendermint-v0-35-a-postmortem-on-the-new-networking-layer-3696c811dabc