From 696ca3489adfa91174ea87d0da70bf72eb55e538 Mon Sep 17 00:00:00 2001
From: vyzo <vyzo@hackzen.org>
Date: Mon, 12 Mar 2018 11:14:34 +0200
Subject: [PATCH 01/23] rendezvous protocol

---
 rendezvous/README.md | 86 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 86 insertions(+)
 create mode 100644 rendezvous/README.md

diff --git a/rendezvous/README.md b/rendezvous/README.md
new file mode 100644
index 000000000..ebb95151d
--- /dev/null
+++ b/rendezvous/README.md
@@ -0,0 +1,86 @@
+# Rendezvous Service
+
+Scope:
+- real-time applications that require rendezvous; replace ws-star-rendezvous
+  in conjunction with p2p-circuit relays.
+
+## Rendezvous Protocol
+
+The rendezvous protocol provides facilities for real-time peer discovery within
+application specific namespaces. Peers connect to the rendezvous service and register
+their presence in one or more namespaces; they can subsequently enter rendezvous
+and receive announcements about peer registrations and unregistrations within their
+namespaces of interest. Registrations persist until the peer disconnects or explicitly
+unregisters.
+
+### Interaction
+
+Client peer `A` connects to the rendezvous service `R` and registers for namespace
+`my-app` with a `REGISTER` message. It subsequently enters rendezvous with
+a `RENDEZVOUS` message and waits for `REGISTER`/`UNREGISTER` announcements from
+the service.
+
+```
+A -> R: REGISTER{my-app, {QmA, AddressA}}
+A -> R: RENDEZVOUS{my-app}
+```
+
+Client peer `B` connects, registers and enters rendezvous.
+The rendezvous service immediately notifies `B` about the current namespace registrations
+and emits a register notification to `A`:
+
+```
+B -> R: REGISTER{my-app, {QmB, AddressB}}
+B -> R: RENDEZVOUS{my-app}
+
+R -> B: REGISTER{my-app, {QmA, AddressA}}
+R -> A: REGISTER{my-app, {QmB, AddressB}}
+```
+
+A third client `C` connections and registers:
+```
+C -> R: REGISTER{my-app, {QmC, AddressC}}
+C -> R: RENDEZVOUS{my-app}
+
+R -> C: REGISTER{my-app, {QmA, AddressA}}
+R -> C: REGISTER{my-app, {QmB, AddressB}}
+R -> A: REGISTER{my-app, {QmC, AddressC}}
+R -> B: REGISTER{my-app, {QmC, AddressC}}
+```
+
+### Protobuf
+
+
+```protobuf
+message Message {
+  enum MessageType {
+    REGISTER = 0;
+    UNREGISTER = 1;
+    RENDEZVOUS = 2;
+  }
+
+  message Peer {
+    optional string id = 1;
+    repeated bytes addrs = 2;
+  }
+
+  message Register {
+    optional string ns = 1;
+    optional Peer peer = 2;
+  }
+
+  message Unregister {
+    optional string ns = 1;
+    optional Peer peer = 2;
+  }
+
+  message Rendezvous {
+    optional string ns = 1;
+  }
+
+  optional MessageType type = 1;
+  repeated Register register = 2;
+  repeated Unregister unregister = 3;
+  repeated Rendezvous rendezvous = 4;
+}
+```

From dcbd0b4806f0df791bd145313df7661349f9062a Mon Sep 17 00:00:00 2001
From: vyzo <vyzo@hackzen.org>
Date: Mon, 12 Mar 2018 11:33:46 +0200
Subject: [PATCH 02/23] cosmetics

---
 rendezvous/README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/rendezvous/README.md b/rendezvous/README.md
index ebb95151d..700fe9b04 100644
--- a/rendezvous/README.md
+++ b/rendezvous/README.md
@@ -1,8 +1,8 @@
 # Rendezvous Service
 
 Scope:
-- real-time applications that require rendezvous; replace ws-star-rendezvous
-  in conjunction with p2p-circuit relays.
+- real-time applications that require rendezvous
+- replace ws-star-rendezvous in conjunction with p2p-circuit relays.
 
 ## Rendezvous Protocol
 

From 2ba1ad51113f5e7892417260588f051c101d3739 Mon Sep 17 00:00:00 2001
From: vyzo <vyzo@hackzen.org>
Date: Mon, 12 Mar 2018 12:26:01 +0200
Subject: [PATCH 03/23] peer discovery for bootstrap

---
 rendezvous/README.md | 31 +++++++++++++++++++++++++------
 1 file changed, 25 insertions(+), 6 deletions(-)

diff --git a/rendezvous/README.md b/rendezvous/README.md
index 700fe9b04..844c6da31 100644
--- a/rendezvous/README.md
+++ b/rendezvous/README.md
@@ -2,16 +2,20 @@
 
 Scope:
 - real-time applications that require rendezvous
-- replace ws-star-rendezvous in conjunction with p2p-circuit relays.
+- replace ws-star-rendezvous with a rendezvous service daemon and a fleet
+  of p2p-circuit relays.
 
 ## Rendezvous Protocol
 
 The rendezvous protocol provides facilities for real-time peer discovery within
 application specific namespaces. Peers connect to the rendezvous service and register
-their presence in one or more namespaces; they can subsequently enter rendezvous
-and receive announcements about peer registrations and unregistrations within their
-namespaces of interest. Registrations persist until the peer disconnects or explicitly
-unregisters.
+their presence in one or more namespaces. Registrations persist until the peer
+disconnects or explicitly unregisters.
+
+Peers can enter rendezvous and dynamically receive announcements about peer
+registrations and unregistrations within their namespaces of interest.
+For purposes of discovery (eg bootstrap), peers can also ask the service for
+a oneof list of peers within a namespace.
 
 ### Interaction
 
@@ -43,11 +47,20 @@ C -> R: REGISTER{my-app, {QmC, AddressC}}
 C -> R: RENDEZVOUS{my-app}
 
 R -> C: REGISTER{my-app, {QmA, AddressA}}
-R -> C: REGISTER{my-app, {QmB, AddressB}}
+        REGISTER{my-app, {QmB, AddressB}}
 R -> A: REGISTER{my-app, {QmC, AddressC}}
 R -> B: REGISTER{my-app, {QmC, AddressC}}
 ```
 
+A client can discover peers in the namespace by sending a `DISCOVER` message; the
+service responds with the list of current peer reigstrations.
+```
+D -> R: DISCOVER{my-app}
+R -> D: REGISTER{my-app, {QmA, AddressA}}
+        REGISTER{my-app, {QmB, AddressB}}
+        REGISTER{my-app, {QmC, AddressC}}
+```
+
 ### Protobuf
 
 
@@ -57,6 +70,7 @@ message Message {
     REGISTER = 0;
     UNREGISTER = 1;
     RENDEZVOUS = 2;
+    DISCOVER = 3;
   }
 
   message Peer {
@@ -78,9 +92,14 @@ message Message {
     optional string ns = 1;
   }
 
+  message Discover {
+    optional string namespace = 1;
+  }
+
   optional MessageType type = 1;
   repeated Register register = 2;
   repeated Unregister unregister = 3;
   repeated Rendezvous rendezvous = 4;
+  repeated Discover discovery = 5;
 }
 ```

From 3330b69ef55e70998624a06c664a907b761c3e54 Mon Sep 17 00:00:00 2001
From: vyzo <vyzo@hackzen.org>
Date: Mon, 12 Mar 2018 12:28:34 +0200
Subject: [PATCH 04/23] consistent naming for namespace field

---
 rendezvous/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/rendezvous/README.md b/rendezvous/README.md
index 844c6da31..23407f490 100644
--- a/rendezvous/README.md
+++ b/rendezvous/README.md
@@ -93,7 +93,7 @@ message Message {
   }
 
   message Discover {
-    optional string namespace = 1;
+    optional string ns = 1;
   }
 
   optional MessageType type = 1;

From 00fa97ba1354e2cb4ce20585208590b49deaceae Mon Sep 17 00:00:00 2001
From: vyzo <vyzo@hackzen.org>
Date: Tue, 13 Mar 2018 14:20:01 +0200
Subject: [PATCH 05/23] add limit to Discover message, better wording around
 bootstrap

---
 rendezvous/README.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/rendezvous/README.md b/rendezvous/README.md
index 23407f490..c397c77ef 100644
--- a/rendezvous/README.md
+++ b/rendezvous/README.md
@@ -14,8 +14,8 @@ disconnects or explicitly unregisters.
 
 Peers can enter rendezvous and dynamically receive announcements about peer
 registrations and unregistrations within their namespaces of interest.
-For purposes of discovery (eg bootstrap), peers can also ask the service for
-a oneof list of peers within a namespace.
+For purposes of oneof discovery (eg bootstrap), peers can also ask the service
+for a list of peers within a namespace.
 
 ### Interaction
 
@@ -94,6 +94,7 @@ message Message {
 
   message Discover {
     optional string ns = 1;
+    optional int limit = 2;
   }
 
   optional MessageType type = 1;

From b19d4939fb335b5707b53a809b95ad058da0461b Mon Sep 17 00:00:00 2001
From: vyzo <vyzo@hackzen.org>
Date: Wed, 11 Apr 2018 20:10:02 +0300
Subject: [PATCH 06/23] rev2: drop push discovery, only polling.

---
 rendezvous/README.md | 150 ++++++++++++++++++++++++++-----------------
 1 file changed, 90 insertions(+), 60 deletions(-)

diff --git a/rendezvous/README.md b/rendezvous/README.md
index c397c77ef..294d5c3fa 100644
--- a/rendezvous/README.md
+++ b/rendezvous/README.md
@@ -1,95 +1,122 @@
-# Rendezvous Service
-
-Scope:
-- real-time applications that require rendezvous
-- replace ws-star-rendezvous with a rendezvous service daemon and a fleet
-  of p2p-circuit relays.
-
-## Rendezvous Protocol
-
-The rendezvous protocol provides facilities for real-time peer discovery within
-application specific namespaces. Peers connect to the rendezvous service and register
-their presence in one or more namespaces. Registrations persist until the peer
-disconnects or explicitly unregisters.
-
-Peers can enter rendezvous and dynamically receive announcements about peer
-registrations and unregistrations within their namespaces of interest.
-For purposes of oneof discovery (eg bootstrap), peers can also ask the service
-for a list of peers within a namespace.
+# Rendezvous Protocol
+
+The protocol described in this specification is intended to provide a
+lightweight mechanism for generalized peer discovery. It can be used
+for bootstrap purposes, real time peer discovery, application specific
+routing, and so on.  Any node implementing the rendezvous protocol can
+act as a rendezvous point, allowing the discovery of relevant peers in
+a decentralized fashion.
+
+## Use Cases
+
+Depending on the application, the protocol could be used in the
+following context:
+- During bootstrap, a node can use known rendezvous points to discover
+  peers that provide critical services. For instance, rendezvous can
+  be used to discover circuit relays for connectivity restricted
+  nodes.
+- During initialization, a node can use rendezvous to discover
+  peers to connect with the rest of the application. For instance,
+  rendezvous can be used to discover pubsub peers within a topic.
+- In a real time setting, applications can poll rendezvous points in
+  order to discover new peers in a timely fashion.
+- In an application specific routing setting, rendezvous points can be
+  used to progressively discover peers that can answer specific queries
+  or host shards of content.
+
+### Replacing ws-star-rendezvous
+
+We intend to replace ws-star-rendezvous with a few rendezvous daemons
+and a fleet of p2p-circuit relays.  Real-time applications will
+utilize rendezvous both for bootstrap and in a real-time setting.
+During bootstrap, rendezvous will be used to discover circuit relays
+that provide connectivity for browser nodes.  Subsequently, rendezvous
+will be utilized throughout the lifetime of the application for real
+time peer discovery by registering and polling rendezvous points.
+This allows us to replace a fragile centralized component with a
+horizontally scalable ensemble of daemons.
+
+### Rendezvous and pubsub
+
+Rendezvous can be naturally combined with pubsub for effective
+real-time discovery.  At a basic level, rendezvous can be used to
+bootstrap pubsub: nodes can utilize rendezvous in order to discover
+their peers within a topic.  Contrariwise, pubsub can also be used as
+a mechanism for building rendezvous services. In this scenerio, a
+number of rendezvous points can federate using pubsub for internal
+real-time distribution, while still providing a simple interface to
+clients.
+
+
+## The Protocol
+
+The rendezvous protocol provides facilities for real-time peer
+discovery within application specific namespaces. Peers connect to the
+rendezvous point and register their presence in one or more
+namespaces. Registrations persist until the peer disconnects or
+explicitly unregisters.
+
+Peers registered with the rendezvous point can be discovered by other
+nodes by querying the rendezvous point. The query specifies the
+namespace for limiting application scope and optionally a maximum
+number of peers to return. The namespace can be omitted in the query,
+which asks for all peers registered to the rendezvous point.
 
 ### Interaction
 
-Client peer `A` connects to the rendezvous service `R` and registers for namespace
-`my-app` with a `REGISTER` message. It subsequently enters rendezvous with
-a `RENDEZVOUS` message and waits for `REGISTER`/`UNREGISTER` announcements from
-the service.
+Clients `A` and `B` connect to the rendezvous point `R` and register for namespace
+`my-app` with a `REGISTER` message:
 
 ```
-A -> R: REGISTER{my-app, {QmA, AddressA}}
-A -> R: RENDEZVOUS{my-app}
+A -> R: REGISTER{my-app, {QmA, AddrA}}
+B -> R: REGISTER{my-app, {QmB, AddrB}}
 ```
 
-Client peer `B` connects, registers and enters rendezvous.
-The rendezvous service immediately notifies `B` about the current namespace registrations
-and emits a register notification to `A`:
-
+Client `C` connects and registers for namespace `another-app`:
 ```
-B -> R: REGISTER{my-app, {QmB, AddressB}}
-B -> R: RENDEZVOUS{my-app}
-
-R -> B: REGISTER{my-app, {QmA, AddressA}}
-R -> A: REGISTER{my-app, {QmB, AddressB}}
+C -> R: REGISTER{another-app, {QmC, AddrC}}
 ```
 
-A third client `C` connections and registers:
+Another client `D` can discover peers in `my-app` by sending a `DISCOVER` message; the
+rendezvous point responds with the list of current peer reigstrations.
 ```
-C -> R: REGISTER{my-app, {QmC, AddressC}}
-C -> R: RENDEZVOUS{my-app}
-
-R -> C: REGISTER{my-app, {QmA, AddressA}}
-        REGISTER{my-app, {QmB, AddressB}}
-R -> A: REGISTER{my-app, {QmC, AddressC}}
-R -> B: REGISTER{my-app, {QmC, AddressC}}
+D -> R: DISCOVER{my-app}
+R -> D: [REGISTER{my-app, {QmA, Addr}}
+         REGISTER{my-app, {QmB, Addr}}]
 ```
 
-A client can discover peers in the namespace by sending a `DISCOVER` message; the
-service responds with the list of current peer reigstrations.
+If `D` wants to discover all peers registered with `R`, then it can omit the namespace
+in the query:
 ```
-D -> R: DISCOVER{my-app}
-R -> D: REGISTER{my-app, {QmA, AddressA}}
-        REGISTER{my-app, {QmB, AddressB}}
-        REGISTER{my-app, {QmC, AddressC}}
+D -> R: DISCOVER{}
+R -> D: [REGISTER{my-app, {QmA, Addr}}
+         REGISTER{my-app, {QmB, Addr}}
+         REGISTER{another-app, {QmC, AddrC}}]
 ```
 
 ### Protobuf
 
-
 ```protobuf
 message Message {
   enum MessageType {
     REGISTER = 0;
     UNREGISTER = 1;
-    RENDEZVOUS = 2;
-    DISCOVER = 3;
+    DISCOVER = 2;
+    DISCOVER_RESPONSE = 3;
   }
 
-  message Peer {
+  message PeerInfo {
     optional string id = 1;
     repeated bytes addrs = 2;
   }
 
   message Register {
     optional string ns = 1;
-    optional Peer peer = 2;
+    optional PeerInfo peer = 2;
   }
 
   message Unregister {
     optional string ns = 1;
-    optional Peer peer = 2;
-  }
-
-  message Rendezvous {
-    optional string ns = 1;
   }
 
   message Discover {
@@ -97,10 +124,13 @@ message Message {
     optional int limit = 2;
   }
 
+  message DiscoverResponse {
+    repeated Register registrations = 1;
+  }
+
   optional MessageType type = 1;
   repeated Register register = 2;
   repeated Unregister unregister = 3;
-  repeated Rendezvous rendezvous = 4;
-  repeated Discover discovery = 5;
+  repeated Discover discover = 4;
+  repeated DiscoverResponse discoverResponse = 5;
 }
-```

From 6dbbd4b36b6f7709f4c4a9b160db8ad573f31c43 Mon Sep 17 00:00:00 2001
From: vyzo <vyzo@hackzen.org>
Date: Wed, 11 Apr 2018 20:18:58 +0300
Subject: [PATCH 07/23] protobuf fix: specific messages are optional, not
 repeated

---
 rendezvous/README.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/rendezvous/README.md b/rendezvous/README.md
index 294d5c3fa..0f256636f 100644
--- a/rendezvous/README.md
+++ b/rendezvous/README.md
@@ -129,8 +129,8 @@ message Message {
   }
 
   optional MessageType type = 1;
-  repeated Register register = 2;
-  repeated Unregister unregister = 3;
-  repeated Discover discover = 4;
-  repeated DiscoverResponse discoverResponse = 5;
+  optional Register register = 2;
+  optional Unregister unregister = 3;
+  optional Discover discover = 4;
+  optional DiscoverResponse discoverResponse = 5;
 }

From 219dc409c18b85c686b4fdada982449464aa538a Mon Sep 17 00:00:00 2001
From: vyzo <vyzo@hackzen.org>
Date: Thu, 12 Apr 2018 10:06:28 +0300
Subject: [PATCH 08/23] add section on registration lifetime

---
 rendezvous/README.md | 17 +++++++++++++++--
 1 file changed, 15 insertions(+), 2 deletions(-)

diff --git a/rendezvous/README.md b/rendezvous/README.md
index 0f256636f..c6537692f 100644
--- a/rendezvous/README.md
+++ b/rendezvous/README.md
@@ -53,8 +53,7 @@ clients.
 The rendezvous protocol provides facilities for real-time peer
 discovery within application specific namespaces. Peers connect to the
 rendezvous point and register their presence in one or more
-namespaces. Registrations persist until the peer disconnects or
-explicitly unregisters.
+namespaces.
 
 Peers registered with the rendezvous point can be discovered by other
 nodes by querying the rendezvous point. The query specifies the
@@ -62,6 +61,19 @@ namespace for limiting application scope and optionally a maximum
 number of peers to return. The namespace can be omitted in the query,
 which asks for all peers registered to the rendezvous point.
 
+### Registration Lifetime
+
+Registration lifetime is controlled by an optional TTL parameter in
+the `REGISTER` message.  If a TTL is specified, then the registration
+persists until the TTL expires.  If no TTL was specified, then the
+registration persists while the issuing peer is still connected to the
+rendezvous point.
+
+Peers can refresh their registrations at any time with a new
+`REGISTER` message; the TTL of the new message supersedes previous
+registrations. Peers can also cancel existing registrations at any
+time with an explicit `UNREGISTER` message.
+
 ### Interaction
 
 Clients `A` and `B` connect to the rendezvous point `R` and register for namespace
@@ -113,6 +125,7 @@ message Message {
   message Register {
     optional string ns = 1;
     optional PeerInfo peer = 2;
+    optional uint ttl = 3;
   }
 
   message Unregister {

From ed7c06822670cdc8681f115626773a16e4774f46 Mon Sep 17 00:00:00 2001
From: vyzo <vyzo@hackzen.org>
Date: Thu, 12 Apr 2018 20:54:27 +0300
Subject: [PATCH 09/23] add timestamp to discover queries and responses

---
 rendezvous/README.md | 36 ++++++++++++++++++++++++++++++------
 1 file changed, 30 insertions(+), 6 deletions(-)

diff --git a/rendezvous/README.md b/rendezvous/README.md
index c6537692f..dd1a1cd99 100644
--- a/rendezvous/README.md
+++ b/rendezvous/README.md
@@ -61,6 +61,12 @@ namespace for limiting application scope and optionally a maximum
 number of peers to return. The namespace can be omitted in the query,
 which asks for all peers registered to the rendezvous point.
 
+The query can also specify a timestamp, obtained from the response to
+a previous query, such that only peers registered since the timestamp
+will be returned. This allows peers to progressively refresh their
+network view without overhead, which greatly simplifies real time
+discovery.
+
 ### Registration Lifetime
 
 Registration lifetime is controlled by an optional TTL parameter in
@@ -92,18 +98,34 @@ C -> R: REGISTER{another-app, {QmC, AddrC}}
 Another client `D` can discover peers in `my-app` by sending a `DISCOVER` message; the
 rendezvous point responds with the list of current peer reigstrations.
 ```
-D -> R: DISCOVER{my-app}
-R -> D: [REGISTER{my-app, {QmA, Addr}}
-         REGISTER{my-app, {QmB, Addr}}]
+D -> R: DISCOVER{ns: my-app}
+R -> D: {[REGISTER{my-app, {QmA, Addr}}
+          REGISTER{my-app, {QmB, Addr}}],
+         t1}
 ```
 
 If `D` wants to discover all peers registered with `R`, then it can omit the namespace
 in the query:
 ```
 D -> R: DISCOVER{}
-R -> D: [REGISTER{my-app, {QmA, Addr}}
-         REGISTER{my-app, {QmB, Addr}}
-         REGISTER{another-app, {QmC, AddrC}}]
+R -> D: {[REGISTER{my-app, {QmA, Addr}}
+          REGISTER{my-app, {QmB, Addr}}
+          REGISTER{another-app, {QmC, AddrC}}],
+         t2}
+```
+
+If `D` wants to progressively poll for real time discovery, it can use
+the timestamp obtained from a previous response in order to only ask
+for new registrations.
+
+So here we consider a new client `E` registering after `t1`, and a subsequent
+query that discovers just that peer by including the timestamp:
+
+```
+E -> R: REGISTER{my-app, {QmE, AddrE}}
+D -> R: DISCOVER{ns: my-app, since: t1}
+R -> D: {[REGISTER{my-app, {QmE, AddrE}}],
+         t3}
 ```
 
 ### Protobuf
@@ -135,10 +157,12 @@ message Message {
   message Discover {
     optional string ns = 1;
     optional int limit = 2;
+    optional uint64 since = 3;
   }
 
   message DiscoverResponse {
     repeated Register registrations = 1;
+    optional uint64 timestamp = 2;
   }
 
   optional MessageType type = 1;

From af5ba414c285e73b33843214be8c3a4c61ae69c1 Mon Sep 17 00:00:00 2001
From: vyzo <vyzo@hackzen.org>
Date: Sun, 15 Apr 2018 13:35:37 +0300
Subject: [PATCH 10/23] add RegisterResponse to convey registration success or
 errors.

also, peer ids in unregistrations.
---
 rendezvous/README.md | 38 ++++++++++++++++++++++++++++----------
 1 file changed, 28 insertions(+), 10 deletions(-)

diff --git a/rendezvous/README.md b/rendezvous/README.md
index dd1a1cd99..0bfed5ede 100644
--- a/rendezvous/README.md
+++ b/rendezvous/README.md
@@ -87,12 +87,15 @@ Clients `A` and `B` connect to the rendezvous point `R` and register for namespa
 
 ```
 A -> R: REGISTER{my-app, {QmA, AddrA}}
+R -> A: {OK}
 B -> R: REGISTER{my-app, {QmB, AddrB}}
+R -> B: {OK}
 ```
 
 Client `C` connects and registers for namespace `another-app`:
 ```
 C -> R: REGISTER{another-app, {QmC, AddrC}}
+R -> C: {OK}
 ```
 
 Another client `D` can discover peers in `my-app` by sending a `DISCOVER` message; the
@@ -123,6 +126,7 @@ query that discovers just that peer by including the timestamp:
 
 ```
 E -> R: REGISTER{my-app, {QmE, AddrE}}
+R -> E: {OK}
 D -> R: DISCOVER{ns: my-app, since: t1}
 R -> D: {[REGISTER{my-app, {QmE, AddrE}}],
          t3}
@@ -134,40 +138,54 @@ R -> D: {[REGISTER{my-app, {QmE, AddrE}}],
 message Message {
   enum MessageType {
     REGISTER = 0;
-    UNREGISTER = 1;
-    DISCOVER = 2;
-    DISCOVER_RESPONSE = 3;
+    REGISTER_RESPONSE = 1;
+    UNREGISTER = 2;
+    DISCOVER = 3;
+    DISCOVER_RESPONSE = 4;
   }
 
   message PeerInfo {
-    optional string id = 1;
+    optional bytes id = 1;
     repeated bytes addrs = 2;
   }
 
   message Register {
     optional string ns = 1;
     optional PeerInfo peer = 2;
-    optional uint ttl = 3;
+    optional int64 ttl = 3; // in seconds
+  }
+
+  enum RegisterStatus {
+    OK = 0;
+    E_INVALID_NAMESPACE = 100;
+    E_INVALID_PEER_INFO = 101;
+    E_NOT_AUTHORIZED    = 200;
+  }
+
+  message RegisterReponse {
+    optional RegisterStatus code = 1;
   }
 
   message Unregister {
     optional string ns = 1;
+    optional bytes id = 2;
   }
 
   message Discover {
     optional string ns = 1;
     optional int limit = 2;
-    optional uint64 since = 3;
+    optional int64 since = 3;
   }
 
   message DiscoverResponse {
     repeated Register registrations = 1;
-    optional uint64 timestamp = 2;
+    optional int64 timestamp = 2;
   }
 
   optional MessageType type = 1;
   optional Register register = 2;
-  optional Unregister unregister = 3;
-  optional Discover discover = 4;
-  optional DiscoverResponse discoverResponse = 5;
+  optional RegisterResponse registerResponse = 3;
+  optional Unregister unregister = 4;
+  optional Discover discover = 5;
+  optional DiscoverResponse discoverResponse = 6;
 }

From 3423e159d8023699ff68a7f60e62d879bb57d57e Mon Sep 17 00:00:00 2001
From: vyzo <vyzo@hackzen.org>
Date: Sun, 15 Apr 2018 13:55:08 +0300
Subject: [PATCH 11/23] fix typo, limit should be int64

---
 rendezvous/README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/rendezvous/README.md b/rendezvous/README.md
index 0bfed5ede..d70945549 100644
--- a/rendezvous/README.md
+++ b/rendezvous/README.md
@@ -162,7 +162,7 @@ message Message {
     E_NOT_AUTHORIZED    = 200;
   }
 
-  message RegisterReponse {
+  message RegisterResponse {
     optional RegisterStatus code = 1;
   }
 
@@ -173,7 +173,7 @@ message Message {
 
   message Discover {
     optional string ns = 1;
-    optional int limit = 2;
+    optional int64 limit = 2;
     optional int64 since = 3;
   }
 

From 70367202419dddada3910eb95a635ece06797ba8 Mon Sep 17 00:00:00 2001
From: vyzo <vyzo@hackzen.org>
Date: Sun, 15 Apr 2018 17:29:17 +0300
Subject: [PATCH 12/23] use a cookie for progressive discovery and pagination,
 not a timestamp.

---
 rendezvous/README.md | 35 ++++++++++++++++++-----------------
 1 file changed, 18 insertions(+), 17 deletions(-)

diff --git a/rendezvous/README.md b/rendezvous/README.md
index d70945549..392948abd 100644
--- a/rendezvous/README.md
+++ b/rendezvous/README.md
@@ -61,11 +61,13 @@ namespace for limiting application scope and optionally a maximum
 number of peers to return. The namespace can be omitted in the query,
 which asks for all peers registered to the rendezvous point.
 
-The query can also specify a timestamp, obtained from the response to
-a previous query, such that only peers registered since the timestamp
-will be returned. This allows peers to progressively refresh their
-network view without overhead, which greatly simplifies real time
-discovery.
+The query can also include a cookie, obtained from the response to a
+previous query, such that only registrations that weren't included in
+the previous response will be returned. This allows peers to
+progressively refresh their network view without overhead, which
+greatly simplifies real time discovery. It also allows for pagination
+of query responses, so that large numbers of peer registrations can be
+managed.
 
 ### Registration Lifetime
 
@@ -99,12 +101,12 @@ R -> C: {OK}
 ```
 
 Another client `D` can discover peers in `my-app` by sending a `DISCOVER` message; the
-rendezvous point responds with the list of current peer reigstrations.
+rendezvous point responds with the list of current peer reigstrations and a cookie.
 ```
 D -> R: DISCOVER{ns: my-app}
 R -> D: {[REGISTER{my-app, {QmA, Addr}}
           REGISTER{my-app, {QmB, Addr}}],
-         t1}
+         c1}
 ```
 
 If `D` wants to discover all peers registered with `R`, then it can omit the namespace
@@ -114,22 +116,21 @@ D -> R: DISCOVER{}
 R -> D: {[REGISTER{my-app, {QmA, Addr}}
           REGISTER{my-app, {QmB, Addr}}
           REGISTER{another-app, {QmC, AddrC}}],
-         t2}
+         c2}
 ```
 
 If `D` wants to progressively poll for real time discovery, it can use
-the timestamp obtained from a previous response in order to only ask
-for new registrations.
-
-So here we consider a new client `E` registering after `t1`, and a subsequent
-query that discovers just that peer by including the timestamp:
+the cookie obtained from a previous response in order to only ask for
+new registrations.
 
+So here we consider a new client `E` registering after the first query,
+and a subsequent query that discovers just that peer by including the cookie:
 ```
 E -> R: REGISTER{my-app, {QmE, AddrE}}
 R -> E: {OK}
-D -> R: DISCOVER{ns: my-app, since: t1}
+D -> R: DISCOVER{ns: my-app, cookie: c1}
 R -> D: {[REGISTER{my-app, {QmE, AddrE}}],
-         t3}
+         c3}
 ```
 
 ### Protobuf
@@ -174,12 +175,12 @@ message Message {
   message Discover {
     optional string ns = 1;
     optional int64 limit = 2;
-    optional int64 since = 3;
+    optional bytes cookie = 3;
   }
 
   message DiscoverResponse {
     repeated Register registrations = 1;
-    optional int64 timestamp = 2;
+    optional bytes cookie = 2;
   }
 
   optional MessageType type = 1;

From ec7a5797fa91d501eab29fa78ce9f4e75347bcf3 Mon Sep 17 00:00:00 2001
From: vyzo <vyzo@hackzen.org>
Date: Wed, 18 Apr 2018 18:22:26 +0300
Subject: [PATCH 13/23] add closing backticks

---
 rendezvous/README.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/rendezvous/README.md b/rendezvous/README.md
index 392948abd..648cf7e77 100644
--- a/rendezvous/README.md
+++ b/rendezvous/README.md
@@ -190,3 +190,4 @@ message Message {
   optional Discover discover = 5;
   optional DiscoverResponse discoverResponse = 6;
 }
+```

From 9d061e18d5c5b67057d79169d7059e6b22000b1a Mon Sep 17 00:00:00 2001
From: vyzo <vyzo@hackzen.org>
Date: Wed, 18 Apr 2018 18:26:01 +0300
Subject: [PATCH 14/23] RegisterStatus field should be called status

---
 rendezvous/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/rendezvous/README.md b/rendezvous/README.md
index 648cf7e77..2f4426822 100644
--- a/rendezvous/README.md
+++ b/rendezvous/README.md
@@ -164,7 +164,7 @@ message Message {
   }
 
   message RegisterResponse {
-    optional RegisterStatus code = 1;
+    optional RegisterStatus status = 1;
   }
 
   message Unregister {

From 81e5078580ad5d6bc9d4aebbb7943ef1e292135c Mon Sep 17 00:00:00 2001
From: vyzo <vyzo@hackzen.org>
Date: Fri, 20 Apr 2018 10:31:00 +0300
Subject: [PATCH 15/23] default TTL of 2hrs instead of persist until
 disconneciton semantics

Also specify a minimum upper bound of 72hrs and an E_INVALID_TTL status
code.
---
 rendezvous/README.md | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/rendezvous/README.md b/rendezvous/README.md
index 2f4426822..c2a06be18 100644
--- a/rendezvous/README.md
+++ b/rendezvous/README.md
@@ -73,9 +73,11 @@ managed.
 
 Registration lifetime is controlled by an optional TTL parameter in
 the `REGISTER` message.  If a TTL is specified, then the registration
-persists until the TTL expires.  If no TTL was specified, then the
-registration persists while the issuing peer is still connected to the
-rendezvous point.
+persists until the TTL expires.  If no TTL was specified, then a default
+of 2hrs is implied. There may be a rendezvous point-specific upper bound
+on TTL, with a minimum such value of 72hrs. If the TTL of a registration
+is inadmissible, the rendezvous point may reject the registration with
+an `E_INVALID_TTL` status.
 
 Peers can refresh their registrations at any time with a new
 `REGISTER` message; the TTL of the new message supersedes previous
@@ -160,6 +162,7 @@ message Message {
     OK = 0;
     E_INVALID_NAMESPACE = 100;
     E_INVALID_PEER_INFO = 101;
+    E_INVALID_TTL       = 102;
     E_NOT_AUTHORIZED    = 200;
   }
 

From 9bdee4fffb4cd064fb3e544e5143f86651d523b7 Mon Sep 17 00:00:00 2001
From: vyzo <vyzo@hackzen.org>
Date: Sat, 21 Apr 2018 11:43:04 +0300
Subject: [PATCH 16/23] add error reporting to DiscoverResponse; status text
 for errors.

and some more error codes.
---
 rendezvous/README.md | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/rendezvous/README.md b/rendezvous/README.md
index c2a06be18..e267d36a2 100644
--- a/rendezvous/README.md
+++ b/rendezvous/README.md
@@ -158,16 +158,19 @@ message Message {
     optional int64 ttl = 3; // in seconds
   }
 
-  enum RegisterStatus {
-    OK = 0;
+  enum ResponseStatus {
+    OK                  = 0;
     E_INVALID_NAMESPACE = 100;
     E_INVALID_PEER_INFO = 101;
     E_INVALID_TTL       = 102;
+    E_INVALID_COOKIE    = 103;
     E_NOT_AUTHORIZED    = 200;
+    E_INTERNAL_ERROR    = 300;
   }
 
   message RegisterResponse {
-    optional RegisterStatus status = 1;
+    optional ResponseStatus status = 1;
+    optional string statusText = 2;
   }
 
   message Unregister {
@@ -184,6 +187,8 @@ message Message {
   message DiscoverResponse {
     repeated Register registrations = 1;
     optional bytes cookie = 2;
+    optional ResponseStatus status = 3;
+    optional string statusText = 4;
   }
 
   optional MessageType type = 1;

From 4059338ff0f90835ed953e1eb4c2beb703cc04d9 Mon Sep 17 00:00:00 2001
From: vyzo <vyzo@hackzen.org>
Date: Sat, 21 Apr 2018 11:57:10 +0300
Subject: [PATCH 17/23] protobuf cosmetics -- move response status enum up

---
 rendezvous/README.md | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/rendezvous/README.md b/rendezvous/README.md
index e267d36a2..15053c0bd 100644
--- a/rendezvous/README.md
+++ b/rendezvous/README.md
@@ -147,6 +147,16 @@ message Message {
     DISCOVER_RESPONSE = 4;
   }
 
+  enum ResponseStatus {
+    OK                  = 0;
+    E_INVALID_NAMESPACE = 100;
+    E_INVALID_PEER_INFO = 101;
+    E_INVALID_TTL       = 102;
+    E_INVALID_COOKIE    = 103;
+    E_NOT_AUTHORIZED    = 200;
+    E_INTERNAL_ERROR    = 300;
+  }
+
   message PeerInfo {
     optional bytes id = 1;
     repeated bytes addrs = 2;
@@ -158,16 +168,6 @@ message Message {
     optional int64 ttl = 3; // in seconds
   }
 
-  enum ResponseStatus {
-    OK                  = 0;
-    E_INVALID_NAMESPACE = 100;
-    E_INVALID_PEER_INFO = 101;
-    E_INVALID_TTL       = 102;
-    E_INVALID_COOKIE    = 103;
-    E_NOT_AUTHORIZED    = 200;
-    E_INTERNAL_ERROR    = 300;
-  }
-
   message RegisterResponse {
     optional ResponseStatus status = 1;
     optional string statusText = 2;

From 709356938fea33768beab97fedd7bb780668d75c Mon Sep 17 00:00:00 2001
From: vyzo <vyzo@hackzen.org>
Date: Fri, 18 Jan 2019 13:03:03 +0200
Subject: [PATCH 18/23] add wording regarding arbitrary registrations

---
 rendezvous/README.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/rendezvous/README.md b/rendezvous/README.md
index 15053c0bd..aac7f1882 100644
--- a/rendezvous/README.md
+++ b/rendezvous/README.md
@@ -53,7 +53,9 @@ clients.
 The rendezvous protocol provides facilities for real-time peer
 discovery within application specific namespaces. Peers connect to the
 rendezvous point and register their presence in one or more
-namespaces.
+namespaces. It is not allowed to register arbitrary peers in a
+namespace; only the peer initiating the registration can register
+itself.
 
 Peers registered with the rendezvous point can be discovered by other
 nodes by querying the rendezvous point. The query specifies the

From 9f355780aa896d28bf1e9ae89ff55519f14cea20 Mon Sep 17 00:00:00 2001
From: vyzo <vyzo@hackzen.org>
Date: Fri, 18 Jan 2019 13:05:42 +0200
Subject: [PATCH 19/23] add E_UNAVAILABLE error

---
 rendezvous/README.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/rendezvous/README.md b/rendezvous/README.md
index aac7f1882..ce4970cbc 100644
--- a/rendezvous/README.md
+++ b/rendezvous/README.md
@@ -157,6 +157,7 @@ message Message {
     E_INVALID_COOKIE    = 103;
     E_NOT_AUTHORIZED    = 200;
     E_INTERNAL_ERROR    = 300;
+    E_UNAVAILABLE       = 400;
   }
 
   message PeerInfo {

From 4fa61c2d63ca48523683378bba29099059290165 Mon Sep 17 00:00:00 2001
From: vyzo <vyzo@hackzen.org>
Date: Fri, 18 Jan 2019 13:09:10 +0200
Subject: [PATCH 20/23] add ttl in registration response

---
 rendezvous/README.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/rendezvous/README.md b/rendezvous/README.md
index ce4970cbc..45edd59c5 100644
--- a/rendezvous/README.md
+++ b/rendezvous/README.md
@@ -86,6 +86,9 @@ Peers can refresh their registrations at any time with a new
 registrations. Peers can also cancel existing registrations at any
 time with an explicit `UNREGISTER` message.
 
+The registration response includes the actual TTL of the registration,
+so that peers know when to refresh.
+
 ### Interaction
 
 Clients `A` and `B` connect to the rendezvous point `R` and register for namespace
@@ -174,6 +177,7 @@ message Message {
   message RegisterResponse {
     optional ResponseStatus status = 1;
     optional string statusText = 2;
+    optional int64 ttl = 3; // in seconds
   }
 
   message Unregister {

From 84cf2fd31700d18b7433fbd31608d8e6e65573a8 Mon Sep 17 00:00:00 2001
From: vyzo <vyzo@hackzen.org>
Date: Fri, 18 Jan 2019 13:11:41 +0200
Subject: [PATCH 21/23] wording

---
 rendezvous/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/rendezvous/README.md b/rendezvous/README.md
index 45edd59c5..f87ad9c64 100644
--- a/rendezvous/README.md
+++ b/rendezvous/README.md
@@ -41,7 +41,7 @@ horizontally scalable ensemble of daemons.
 Rendezvous can be naturally combined with pubsub for effective
 real-time discovery.  At a basic level, rendezvous can be used to
 bootstrap pubsub: nodes can utilize rendezvous in order to discover
-their peers within a topic.  Contrariwise, pubsub can also be used as
+their peers within a topic.  Alternatively, pubsub can also be used as
 a mechanism for building rendezvous services. In this scenerio, a
 number of rendezvous points can federate using pubsub for internal
 real-time distribution, while still providing a simple interface to

From aba06e7f95eb9afaad98e723391a210c0346b844 Mon Sep 17 00:00:00 2001
From: vyzo <vyzo@hackzen.org>
Date: Fri, 18 Jan 2019 13:13:35 +0200
Subject: [PATCH 22/23] add author and revision

---
 rendezvous/README.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/rendezvous/README.md b/rendezvous/README.md
index f87ad9c64..e7caa7403 100644
--- a/rendezvous/README.md
+++ b/rendezvous/README.md
@@ -1,5 +1,9 @@
 # Rendezvous Protocol
 
+Author: vyzo
+
+Revision: DRAFT; 2019-01-18
+
 The protocol described in this specification is intended to provide a
 lightweight mechanism for generalized peer discovery. It can be used
 for bootstrap purposes, real time peer discovery, application specific

From e1083c1f9d8f7afc0d65a43a12b05492f3873385 Mon Sep 17 00:00:00 2001
From: vyzo <vyzo@hackzen.org>
Date: Fri, 18 Jan 2019 13:17:23 +0200
Subject: [PATCH 23/23] add section on proof of work

---
 rendezvous/README.md | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/rendezvous/README.md b/rendezvous/README.md
index e7caa7403..668434b92 100644
--- a/rendezvous/README.md
+++ b/rendezvous/README.md
@@ -144,6 +144,16 @@ R -> D: {[REGISTER{my-app, {QmE, AddrE}}],
          c3}
 ```
 
+### Proof of Work
+
+The protocol as described so far is susceptible to spam attacks from
+adversarial actors who generate a large number of peer identities and
+register under a namespace of interest (eg: the relay namespace). This
+can be mitigated by requiring a Proof of Work scheme for client
+registrations.
+
+This is TBD before finalizing the spec.
+
 ### Protobuf
 
 ```protobuf