From f2d19162d2a0704a5834f10c71b33ef22c8af832 Mon Sep 17 00:00:00 2001 From: Ethan Buchman Date: Fri, 19 Jan 2018 17:10:08 -0500 Subject: [PATCH] fixes from caffix review --- docs/specification/new-spec/p2p/connection.md | 2 +- docs/specification/new-spec/p2p/peer.md | 5 +++-- docs/specification/new-spec/p2p/pex.md | 18 +++++++++++------- docs/specification/new-spec/p2p/trustmetric.md | 16 ---------------- 4 files changed, 15 insertions(+), 26 deletions(-) delete mode 100644 docs/specification/new-spec/p2p/trustmetric.md diff --git a/docs/specification/new-spec/p2p/connection.md b/docs/specification/new-spec/p2p/connection.md index dfe0d090f..400111f4a 100644 --- a/docs/specification/new-spec/p2p/connection.md +++ b/docs/specification/new-spec/p2p/connection.md @@ -46,7 +46,7 @@ is returned for processing by the corresponding channels `onReceive` function. Messages are sent from a single `sendRoutine`, which loops over a select statement that results in the sending of a ping, a pong, or a batch of data messages. The batch of data messages may include messages from multiple channels. Message bytes are queued for sending in their respective channel, with each channel holding one unsent message at a time. -Messages are chosen for a batch one a time from the channel with the lowest ratio of recently sent bytes to channel priority. +Messages are chosen for a batch one at a time from the channel with the lowest ratio of recently sent bytes to channel priority. ## Sending Messages diff --git a/docs/specification/new-spec/p2p/peer.md b/docs/specification/new-spec/p2p/peer.md index a172764c1..39be966b1 100644 --- a/docs/specification/new-spec/p2p/peer.md +++ b/docs/specification/new-spec/p2p/peer.md @@ -1,7 +1,8 @@ # Tendermint Peers -This document explains how Tendermint Peers are identified, how they connect to one another, -and how other peers are found. +This document explains how Tendermint Peers are identified and how they connect to one another. + +For details on peer discovery, see the [peer exchange (PEX) reactor doc](pex.md). ## Peer Identity diff --git a/docs/specification/new-spec/p2p/pex.md b/docs/specification/new-spec/p2p/pex.md index a71b97174..43d6f80d7 100644 --- a/docs/specification/new-spec/p2p/pex.md +++ b/docs/specification/new-spec/p2p/pex.md @@ -8,10 +8,10 @@ to good peers and to gossip peers to others. Certain peers are special in that they are specified by the user as `persistent`, which means we auto-redial them if the connection fails. -Some such peers can additional be marked as `private`, which means -we will not gossip them to others. +Some peers can be marked as `private`, which means +we will not put them in the address book or gossip them to others. -All others peers are tracked using an address book. +All peers except private peers are tracked using the address book. ## Discovery @@ -31,7 +31,7 @@ Peers are added to the address book from the PEX when they first connect to us o when we hear about them from other peers. The address book is arranged in sets of buckets, and distinguishes between -vetted and unvetted peers. It keeps different sets of buckets for vetted and +vetted (old) and unvetted (new) peers. It keeps different sets of buckets for vetted and unvetted peers. Buckets provide randomization over peer selection. A vetted peer can only be in one bucket. An unvetted peer can be in multiple buckets. @@ -52,7 +52,7 @@ If a peer becomes unvetted (either a new peer, or one that was previously vetted a randomly selected one of the unvetted peers is removed from the address book. More fine-grained tracking of peer behaviour can be done using -a Trust Metric, but it's best to start with something simple. +a trust metric (see below), but it's best to start with something simple. ## Select Peers to Dial @@ -75,7 +75,7 @@ Send the selected peers. Note we select peers for sending without bias for vette There are various cases where we decide a peer has misbehaved and we disconnect from them. When this happens, the peer is removed from the address book and black listed for some amount of time. We call this "Disconnect and Mark". -Note that the bad behaviour may be detected outside the PEX reactor itseld +Note that the bad behaviour may be detected outside the PEX reactor itself (for instance, in the mconnection, or another reactor), but it must be communicated to the PEX reactor so it can remove and mark the peer. @@ -86,9 +86,13 @@ we Disconnect and Mark. ## Trust Metric The quality of peers can be tracked in more fine-grained detail using a -Proportional-Integral-Derrivative (PID) controller that incorporates +Proportional-Integral-Derivative (PID) controller that incorporates current, past, and rate-of-change data to inform peer quality. While a PID trust metric has been implemented, it remains for future work to use it in the PEX. +See the [trustmetric](../../../architecture/adr-006-trust-metric.md ) +and [trustmetric useage](../../../architecture/adr-007-trust-metric-usage.md ) +architecture docs for more details. + diff --git a/docs/specification/new-spec/p2p/trustmetric.md b/docs/specification/new-spec/p2p/trustmetric.md deleted file mode 100644 index b0eaf96e5..000000000 --- a/docs/specification/new-spec/p2p/trustmetric.md +++ /dev/null @@ -1,16 +0,0 @@ - -The trust metric tracks the quality of the peers. -When a peer exceeds a certain quality for a certain amount of time, -it is marked as vetted in the addrbook. -If a vetted peer's quality degrades sufficiently, it is booted, and must prove itself from scratch. -If we need to make room for a new vetted peer, we move the lowest scoring vetted peer back to unvetted. -If we need to make room for a new unvetted peer, we remove the lowest scoring unvetted peer - -possibly only if its below some absolute minimum ? - -Peer quality is tracked in the connection and across the reactors. -Behaviours are defined as one of: - - fatal - something outright malicious. we should disconnect and remember them. - - bad - any kind of timeout, msgs that dont unmarshal, or fail other validity checks, or msgs we didn't ask for or arent expecting - - neutral - normal correct behaviour. unknown channels/msg types (version upgrades). - - good - some random majority of peers per reactor sending us useful messages -