measure 2-hop neighbourhood

1 files changed, 9 insertions, 0 deletions

diff --git a/docs/peers.md b/docs/peers.md
index c0e574d..763f6aa 100644
--- a/docs/peers.md
+++ b/docs/peers.md
@@ -304,6 +304,15 @@ every member the writer's neighbour, but the writer may reach fewer of them (one
 NAT may reach a single one, one on libp2p alone none on Tor alone), and no node can tell
 which from where it is. A neighbour that has the changes already only answers.
 
+Every node tells its neighbours whom it reaches ([`swarm/reach.rs`](../src/swarm/reach.rs)): the members it
+has an active session with (handshake done, neither dormant nor unreachable), each by
+an 8-byte key (the hash its pair scores come from), in its keepalive STATUSes and
+their replies, and within 5 s when it changed; not in announcements of heads, which go
+often. So every node knows its 2-hop neighbourhood as measured, not as the member list
+says, for as long as it is fresh (two STATUS refreshes and a keepalive: 7 minutes with
+the default keepalive), and nothing goes into the document. `GET /peers` shows it
+(`localReaches`, and `reaches` per peer).
+
 ## Keepalive and self-healing
 
 ```mermaid