introduce eager links

1 files changed, 9 insertions, 1 deletions

diff --git a/docs/peers.md b/docs/peers.md
index a56ee62..c0e574d 100644
--- a/docs/peers.md
+++ b/docs/peers.md
@@ -290,7 +290,15 @@ for what's missing). It pulls from one neighbour at a time (15 s timeout); neigh
 that announce heads it lacks meanwhile wait their turn and are pulled from as soon as
 the current pull is answered, if they still have something it lacks. The regular
 STATUS (every third keepalive) triggers the same pull, so gaps close within a few
-keepalive intervals. A node
+keepalive intervals. Links start lazy like this, announced over and pulled from; a
+pull that brought changes this node lacked makes the link eager in that direction
+(Plumtree's GRAFT): its STATUSes ask the neighbour for its changes as soon as the
+neighbour applies them, and the neighbour sends them at once as sync messages, without
+announcing or waiting. Changes this node had already, over an eager link, make it lazy
+again (Plumtree's PRUNE): another path brings them first. Eager links so form where
+changes actually flow, over links that deliver; announcements over the others catch
+what they miss. Every STATUS restates the link's mode, and a link starts lazy again
+whenever its sync does (a new neighbour, dormancy, a new run of the peer). A node
 that just caught up announces its heads once. In a full mesh too: the member list makes
 every member the writer's neighbour, but the writer may reach fewer of them (one behind
 NAT may reach a single one, one on libp2p alone none on Tor alone), and no node can tell