gossipsub: work draft 1 into the specs

libp2p · Jun 28, 2018 · f970878 · f970878
1 parent 4721e1a
commit f970878
Show file tree

Hide file tree

Showing 3 changed files with 40 additions and 28 deletions.
diff --git a/4-architecture.md b/4-architecture.md
@@ -117,17 +117,7 @@ Bootstrap-List is a Discovery Protocol that uses local storage to cache the addr
 
 #### 4.5.1 PubSub
 
-See https://github.com/libp2p/specs/tree/master/pubsub.
-
-##### 4.5.1.1 Implementations
-
-[PubSub](https://github.com/libp2p/specs/tree/master/pubsub) is a work in progress, with floodsub as an initial protocol, followed by gossipsub, which is an alpha release as of May 2018.
-
-Implementations of floodsub include:
-
-- [go-libp2p-floodsub](https://github.com/libp2p/go-floodsub/); also see [this issue](https://github.com/libp2p/go-floodsub/issues/77) for context; and [this PR](https://github.com/libp2p/go-floodsub/pull/67) for gossipsub;
-- [rust-libp2p-floodsub](https://github.com/libp2p/rust-libp2p/tree/master/floodsub); research and work is in progress on gossipsub by @jamesray1 with Drops of Diamond; and
-- [js-libp2p-floodsub](http://github.com/libp2p/js-libp2p-floodsub).
+See [`pubsub/`](pubsub/) and [`pubsub/gossipsub/`](pubsub/gossipsub/).
 
 
 ## 4.6 Naming

diff --git a/pubsub/README.md b/pubsub/README.md
@@ -1,4 +1,9 @@
-# libp2p pubsub specification
+# PubSub interface for libp2p
+
+Revision: draft 1, 2017-02-17
+
+Authors:
+- whyrusleeping ([email protected])
 
 This is the specification for generalized pubsub over libp2p. Pubsub in libp2p
 is currently still experimental and this specification is subject to change.
@@ -16,6 +21,13 @@ You can find information about the PubSub research and notes in the following re
 - https://github.com/libp2p/research-pubsub
 - https://github.com/libp2p/pubsub-notes
 
+Implementations:
+- FloodSub, simple flooding pubsub (2017)
+  - [libp2p/go-floodsub](https://github.com/libp2p/go-floodsub/pull/67), [libp2p/js-libp2p-floodsub](http://github.com/libp2p/js-libp2p-floodsub), [libp2p/rust-libp2p/floodsub](https://github.com/libp2p/rust-libp2p/tree/master/floodsub)
+- GossipSub, proximity-aware epidemic pubsub (2018)
+  - [`./gossipsub`](./gossipsub)
+
+
 ## The RPC
 
 All communication between peers happens in the form of exchanging protobuf RPC
@@ -39,7 +51,7 @@ This is a relatively simple message containing zero or more subscription
 messages, and zero or more content messages. The subscription messages contain
 a topicid string that specifies the topic, and a boolean signifying whether to
 subscribe or unsubscribe to the given topic. True signifies 'subscribe' and
-false signifies 'unsubscribe'. 
+false signifies 'unsubscribe'.
 
 ## The Message
 
@@ -57,20 +69,20 @@ message Message {
 
 The `from` field denotes the author of the message, note that this is not
 necessarily the peer who sent the RPC this message is contained in. This is
-done to allow content to be routed through a swarm of pubsubbing peers. 
+done to allow content to be routed through a swarm of pubsubbing peers.
 
 The `data` field is an opaque blob of data, it can contain any data that the
-publisher wants it to. 
+publisher wants it to.
 
 The `seqno` field is a linearly increasing number that is unique among messages
 originating from each given peer. No two messages on a pubsub topic from the
 same peer should have the same `seqno` value, however messages from different
 peers may have the same sequence number, so this number alone cannot be used to
 address messages. (Notably the 'timecache' in use by the floodsub
-implementation uses the concatenation of the `seqno` and the `from` field.) 
-	
+implementation uses the concatenation of the `seqno` and the `from` field.)
+
 The `topicIDs` field specifies a set of topics that this message is being
-published to. 
+published to.
 
 Note that messages are currently *not* signed. This will come in the near
 future.
@@ -79,7 +91,7 @@ future.
 
 The topic descriptor message is used to define various options and parameters
 of a topic. It currently specifies the topic's human readable name, its
-authentication options, and its encryption options. 
+authentication options, and its encryption options.
 
 The `TopicDescriptor` protobuf is as follows:
 
@@ -114,7 +126,7 @@ message TopicDescriptor {
 ```
 
 The `name` field is a string used to identify or mark the topic, It can be
-descriptive or random or anything that the creator chooses. 
+descriptive or random or anything that the creator chooses.
 
 The `auth` field specifies how authentication will work for this topic. Only
 authenticated peers may publish to a given topic. See 'AuthOpts' below for

diff --git a/pubsub/gossipsub/README.md b/pubsub/gossipsub/README.md
@@ -1,6 +1,15 @@
-# RFC: Proximity Aware Epidemic PubSub
+# GossipSub: Proximity Aware Epidemic PubSub for libp2p
 
-author: vyzo
+Revision: draft 1, 2018-06-28
+
+Authors:
+- vyzo ([email protected])
+
+Implementation status:
+- Go: [libp2p/go-floodsub#67](https://github.com/libp2p/go-floodsub/pull/67) (experimental)
+- JS: not yet started
+- Rust: not yet started
+- Gerbil: [vyzo/gerbil-simsub](https://github.com/vyzo/gerbil-simsub) (very first implementation)
 
 <!-- toc -->
 
@@ -24,10 +33,11 @@ author: vyzo
 
 ## Introduction
 
-This RFC proposes a topic pubsub protocol based on the following papers:
-1. [Epidemic Broadcast Trees](http://www.gsd.inesc-id.pt/~ler/docencia/rcs1617/papers/srds07.pdf)
-2. [HyParView: a membership protocol for reliable gossip-based broadcast](http://asc.di.fct.unl.pt/~jleitao/pdf/dsn07-leitao.pdf)
-3. [GoCast: Gossip-enhanced Overlay Multicast for Fast and Dependable Group Communication](http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.75.4811)
+This document proposes a successor to the FloodSub protocol.
+It proposes a topic pubsub protocol based on the following papers:
+1. Epidemic Broadcast Trees, 2007 ([PDF](http://www.gsd.inesc-id.pt/~ler/docencia/rcs1617/papers/srds07.pdf), DOI: [10.1109/SRDS.2007.27](https://doi.org/10.1109/SRDS.2007.27))
+2. HyParView: a membership protocol for reliable gossip-based broadcast, 2007 ([PDF](http://asc.di.fct.unl.pt/~jleitao/pdf/dsn07-leitao.pdf), DOI: [10.1109/DSN.2007.56](http://doi.org/10.1109/DSN.2007.56))
+3. GoCast: Gossip-enhanced Overlay Multicast for Fast and Dependable Group Communication, 2005 ([PDF](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.75.4811&rep=rep1&type=pdf))
 
 The protocol implements the Plumtree algorithm from [1], with
 membership managed using HyParView[2] and proximity-aware overlay
@@ -202,7 +212,7 @@ lists eagerly, at the cost of some bandwidth.
 
 The active list is generally managed reactively: failures are detected
 by TCP, either when a message is sent or when the connection is detected
-as closed. 
+as closed.
 
 In addition to the reactive management strategy, the active list has
 stabilization and optimization components that run periodically with a
@@ -285,7 +295,7 @@ The state of the broadcast loop consists of two sets of peers, the eager
 and lazy lists, with the eager list initialized to the initial neighbors
 and the lazy list empty. The loop also maintains a time-based cache of
 recent messages, together with a queue of lazy message notifications.
-In addition to the cache, it maintains a list of missing messages 
+In addition to the cache, it maintains a list of missing messages
 known by lazy gossip but not yet received through the multicast tree.
 
 ### Message Propagation and Multicast Tree Construction