10/WAKU2: General improvements to main spec (#444)

* Tweak intro and motivation/goals

* update protocol and interactions

* update ref count

* Move security and future work into appendicies

* fmt

* fix indent

* Update content/docs/rfcs/10/README.md

Co-authored-by: Franck Royer <franck@status.im>

* Update content/docs/rfcs/10/README.md

Co-authored-by: Sanaz Taheri Boshrooyeh <35961250+staheri14@users.noreply.github.com>

* Update content/docs/rfcs/10/README.md

Co-authored-by: Sanaz Taheri Boshrooyeh <35961250+staheri14@users.noreply.github.com>

* Update content/docs/rfcs/10/README.md

Co-authored-by: Sanaz Taheri Boshrooyeh <35961250+staheri14@users.noreply.github.com>

* Update content/docs/rfcs/10/README.md

Co-authored-by: Sanaz Taheri Boshrooyeh <35961250+staheri14@users.noreply.github.com>

* Update content/docs/rfcs/10/README.md

Co-authored-by: Sanaz Taheri Boshrooyeh <35961250+staheri14@users.noreply.github.com>

* simplify

Co-authored-by: Franck Royer <franck@status.im>
Co-authored-by: Sanaz Taheri Boshrooyeh <35961250+staheri14@users.noreply.github.com>

content/docs/rfcs/10/README.md

@@ -9,56 +9,97 @@ contributors:
   - Hanno Cornelius <hanno@status.im>
 ---
 
-Waku is a privacy-preserving peer-to-peer messaging protocol for resource restricted devices.
+## Abstract
-It implements PubSub over libp2p and adds capabilities on top of it. These capabilities are:
-(i) retrieving historical messages for mostly-offline devices
-(ii) adaptive nodes, allowing for heterogeneous nodes to contribute, and
-(iii) bandwidth preservation for light nodes.
-This makes it ideal for running a p2p protocol on mobile and in similarly restricted environments.
 
-Historically, it has its roots in [Waku v1](/spec/6), which stems from [Whisper](https://eips.ethereum.org/EIPS/eip-627), originally part of the Ethereum stack.
+Waku v2 is family of modular peer-to-peer protocols for secure communication.
+The protocols are designed to be secure, privacy-preserving, censorship-resistant and being able to run in resource restricted environments.
+At a high level, it implements Pub/Sub over [libp2p](https://github.com/libp2p/specs) and adds a set of capabilities to it.
+These capabilities are things such as:
+(i) retrieving historical messages for mostly-offline devices
+(ii) adaptive nodes, allowing for heterogeneous nodes to contribute to the network
+(iii) preserving bandwidth usage for resource-restriced devices
+
+This makes Waku ideal for running a p2p protocol on mobile and in similarly restricted environments.
+
+Historically, it has its roots in [Waku v1](/spec/6),
+which stems from [Whisper](https://eips.ethereum.org/EIPS/eip-627), originally part of the Ethereum stack.
 However, Waku v2 acts more as a thin wrapper for PubSub and has a different API.
 It is implemented in an iterative manner where initial focus is on porting essential functionality to libp2p.
-See [rough road map](https://vac.dev/waku-v2-plan).
+See [rough road map (2020)](https://vac.dev/waku-v2-plan) for more historical context.
 
-# Motivation and goals
+## Motivation and goals
+
+Waku as a family of protocols is designed to have a set of properties that are useful for many applications:
+
+1. **Useful for generalized messaging.**
 
-1. **Generalized messaging.**
 Many applications require some form of messaging protocol to communicate between different subsystems or different nodes.
 This messaging can be human-to-human or machine-to-machine or a mix.
+Waku is designed to work for all these scenarios.
 
 2. **Peer-to-peer.**
-These applications sometimes have requirements that make them suitable for peer-to-peer solutions.
 
-3. **Resource restricted**.
+Applications sometimes have requirements that make them suitable for peer-to-peer solutions:
-These applications often run in constrained environments, where resources or the environment is restricted in some fashion. E.g.:
+- Censorship-resistant with no single point of failure 
+- Adaptive and scalable network
+- Shared infrastructure
 
-- limited bandwidth, CPU, memory, disk, battery, etc
+3. **Runs anywhere.**
-- not being publicly connectable
-- only being intermittently connected; mostly-offline
 
-4. **Privacy.**
+Applications often run in restricted environments, where resources or the environment is restricted in some fashion.
-These applications have a desire for some privacy guarantees, such as pseudonymity, metadata protection in transit, etc.
+For example:
 
-Waku provides a solution that satisfies these goals in a reasonable matter.
+- Limited bandwidth, CPU, memory, disk, battery, etc
+- Not being publicly connectable
+- Only being intermittently connected; mostly-offline
 
-# Network interaction domains
+4. **Privacy-preserving.**
+
+ Applications often have a desire for some privacy guarantees, such as:
+ - Pseudonymity and not being tied to any personally identifiable information (PII)
+ - Metadata protection in transit
+ - Various forms of unlinkability, etc
+
+5. **Modular design.**
+
+Applications often have different trade-offs when it comes to what properties they and their users value.
+Waku is designed in a modular fashion where an application protocol or node can choose what protocols they run.
+We call this concept *adaptive nodes*.
+
+For example:
+- Resource usage vs metadata protection
+- Providing useful services to the network vs mostly using it
+- Stronger guarantees for spam protection vs economic registration cost
+
+## Network interaction domains
+
+While Waku is best thought of as a single cohesive thing, there are three network interaction domains:
 
-While Waku is best though of as a single cohesive thing, there are three network
-interaction domains:
 (a) gossip domain
 (b) discovery domain
-(c) req/resp domain.
+(c) req/resp domain
 
-## Protocols and identifiers
+### Protocols and identifiers
 
-The current [protocol identifiers](https://docs.libp2p.io/concepts/protocols/) are:
+Since Waku v2 is built on top of libp2p, many protocols have a libp2p protocol identifier.
+The current main [protocol identifiers](https://docs.libp2p.io/concepts/protocols/) are:
 
 1. `/vac/waku/relay/2.0.0`
 2. `/vac/waku/store/2.0.0-beta3`
 3. `/vac/waku/filter/2.0.0-beta1`
-4. `/vac/waku/swap/2.0.0-beta1`
+4. `/vac/waku/lightpush/2.0.0-beta1`
-5. `/vac/waku/lightpush/2.0.0-beta1`
+
+This is in addition to protocols that specify messages, payloads, and recommended usages.
+Since these aren't negotiated libp2p protocols, they are referred to by their RFC ID.
+For example:
+
+- [14/WAKU2-MESSAGE](/spec/14)and [26/WAKU2-PAYLOAD](/spec/26) for message payloads
+- [23/WAKU2-TOPICS](/spec/23) and [27/WAKU2-PEERS](/spec/27) for recommendations around usage
+
+There are also more experimental libp2p protocols such as:
+
+1. `/vac/waku/swap/2.0.0-beta1`
+2. `/vac/waku/waku-rln-relay/2.0.0-alpha1`
 
 These protocols and their semantics are elaborated on in their own specs.
 
@@ -70,38 +111,26 @@ In addition, Waku v2 MAY make use of [libp2p ping protocol](https://docs.libp2p.
 
 for liveness checks between peers, or to keep peer-to-peer connections alive.
 
-For the actual content being passed around, see the [7/WAKU-DATA](/spec/7) spec.
+### Use of libp2p and protobuf
-
-## Use of libp2p and protobuf
 
 Unless otherwise specified, all protocols are implemented over libp2p and use Protobuf by default.
 Since messages are exchanged over a [bi-directional binary stream](https://docs.libp2p.io/concepts/protocols/),
 as a convention, libp2p protocols prefix binary message payloads with the length of the message in bytes.
 This length integer is encoded as a [protobuf varint](https://developers.google.com/protocol-buffers/docs/encoding#varints).
 
-## Gossip domain
+### Gossip domain
+
+Waku is using gossiping to disseminate messages throughout the network.
 
 **Protocol identifier**: `/vac/waku/relay/2.0.0`
 
 See [11/WAKU2-RELAY](/spec/11) spec for more details.
 
-### Default pubsub topic
+For an experimental privacy-preserving economic spam protection mechanism, see [17/WAKU2-RLNRELAY](/spec/17).
 
-The default PubSub topic being used for Waku is currently:
+See [23/WAKU2-TOPICS](/spec/23) for more information about recommended topic usage.
-`/waku/2/default-waku/proto`
 
-This indicates that it relates to Waku, is version 2, is the default topic, and
+### Discovery domain
-that the encoding of data field is protobuf.
-
-The default PubSub topic SHOULD be used for all protocols.
-This ensures a connected network, as well some degree of metadata protection.
-It MAY be different if or when:
-- Different applications have different message volume
-- Topic sharding is introduced
-- Encoding is changed
-- Version is changed
-
-## Discovery domain
 
 Waku v2 can retrieve a list of nodes to connect to using DNS-based discovery as per [EIP-1459](https://eips.ethereum.org/EIPS/eip-1459).
 While this is a useful way of bootstrapping connection to a set of peers,
@@ -111,27 +140,45 @@ It is possible to bypass the discovery domain by specifying static nodes.
 
 <!-- TODO: Document (a) how we map ENR to multiaddr for EIP-1459, once specified, (b) ambient peer discovery. -->
 
-## Request/reply domain
+### Request/Reply domain
 
-This consists of two main protocols.
+In addition to the Gossip domain,
-They are used in order to get Waku to run in resource restricted environments,
+Waku provides a set of Request/Reply protocols.
+They are primarily used in order to get Waku to run in resource restricted environments,
 such as low bandwidth or being mostly offline.
 
-### Historical message support
+#### Historical message support
 
 **Protocol identifier***: `/vac/waku/store/2.0.0-beta3`
 
+This is used to fetch historical messages for mostly offline devices.
 See [13/WAKU2-STORE](/spec/13) spec for more details.
 
-### Content filtering
+There is also an experimental fault-tolerant addition to the store protocol that relaxes the high availability requirement.
+See [21/WAKU2-FT-STORE](/spec/21)
+
+#### Content filtering
 
 **Protocol identifier***: `/vac/waku/filter/2.0.0-beta1`
 
+This is used to make fetching of a subset of messages more bandwidth preserving.
 See [12/WAKU2-FILTER](/spec/12) spec for more details.
 
-## Overview
+#### Light push
 
-See the sequence diagram below for an overview of how the different protocols interact.
+**Protocol identifier***: `/vac/waku/lightpush/2.0.0-beta1`
+
+This is used for nodes with short connection windows and limited bandwidth to publish messages into the Waku network.
+See [19/WAKU2-LIGHTPUSH](/spec/19) spec for more details.
+
+#### Other protocols
+
+The above is a non-exhaustive list,
+and due to the modular design of Waku there may be other protocols here that provide a useful service to the Waku network.
+
+### Overview of protocol interaction
+
+See the sequence diagram below for an overview of how different protocols interact.
 
 ![Overview of how protocols interact in Waku v2.](../../../../rfcs/10/overview.png)
 
@@ -140,26 +187,32 @@ The protocols initially mounted are indicated as such.
 The PubSub topics `pubtopic1` and `pubtopic2` is used for routing and indicates that it is subscribed to messages on that topic for relay, see [11/WAKU2-RELAY](/spec/11) for details.
 Ditto for [13/WAKU2-STORE](/spec/13) where it indicates that these messages are persisted on that node.
 
-1. Node A creates a WakuMessage `msg1` with a ContentTopic `contentTopic1`. See [14/WAKU2-MESSAGE](/spec/14) for more details.
+1. Node A creates a WakuMessage `msg1` with a ContentTopic `contentTopic1`.
-If WakuMessage version is set to 1, we use the [6/WAKU1](/spec/6) compatible `data` field with encryption. See [7/WAKU-DATA](/spec/7) for more details.
+See [14/WAKU2-MESSAGE](/spec/14) for more details.
+If WakuMessage version is set to 1, we use the [6/WAKU1](/spec/6) compatible `data` field with encryption.
+See [7/WAKU-DATA](/spec/7) for more details.
 
 2. Node F requests to get messages filtered by PubSub topic `pubtopic1` and ContentTopic `contentTopic1`.
-Node D subscribes F to this filter and will in the future forward messages that match that filter. See [12/WAKU2-FILTER](/spec/12) for more details.
+Node D subscribes F to this filter and will in the future forward messages that match that filter.
+See [12/WAKU2-FILTER](/spec/12) for more details.
 
 3. Node A publishes `msg1` on `pubtopic1` and subscribes to that relay topic pick it up.
-It then gets relayed further from B to D, but not C since it doesn't subscribe to that topic. See [11/WAKU2-RELAY](/spec/11).
+It then gets relayed further from B to D, but not C since it doesn't subscribe to that topic.
+See [11/WAKU2-RELAY](/spec/11).
 
-4. Node D saves `msg1` for possible later retrieval by other nodes. See [13/WAKU2-STORE](/spec/13).
+4. Node D saves `msg1` for possible later retrieval by other nodes.
+See [13/WAKU2-STORE](/spec/13).
 
-5. Node D also pushes `msg1` to F, as it has previously subscribed F to this filter. See [12/WAKU2-FILTER](/spec/12).
+5. Node D also pushes `msg1` to F, as it has previously subscribed F to this filter.
+See [12/WAKU2-FILTER](/spec/12).
 
 6. At a later time, Node E comes online.
 It then requests messages matching `pubtopic1` and `contentTopic1` from Node D.
 Node D responds with messages meeting this (and possibly other) criteria. See [13/WAKU2-STORE](/spec/13).
 
-# Upgradability and Compatibility
+## Appendix A: Upgradability and Compatibility
 
-## Compatibility with Waku v1
+### Compatibility with Waku v1
 
 Waku v1 and Waku v2 are different protocols all together.
 They use a different transport protocol underneath; Waku v1 is devp2p RLPx based while Waku v2 uses libp2p.
@@ -168,7 +221,7 @@ Compatibility can be achieved only by using a bridge that not only talks both de
 
 See [15/WAKU-BRIDGE](/spec/15) for details on a bidirectional bridge mode.
 
-# Security 
+# Appendix B: Security 
 
 Each protocol layer of Waku v2 provides a distinct service and is associated with a separate set of security features and concerns.
 Therefore, the overall security of Waku v2 depends on how the different layers are utilized.
@@ -238,26 +291,7 @@ Likewise, in the `12/WAKU2-FILTER`, a full node can link the light node's `PeerI
 
 <!--TODO: might be good to add a figure visualizing the Waku protocol stack and the security features of each layer-->
 
-## Future work
+## Appendix C: Implementation Notes
-
-We are actively working on the following features to be added to Waku v2.
-
-**Economic Spam resistance**:
-We aim to enable an incentivized spam protection technique to enhance `11/WAKU2-RELAY` by using rate limiting nullifiers.
-More details on this can be found in [17/WAKU2-RLNRELAY](/spec/17).
-In this advanced method, peers are limited to a certain rate of messaging per epoch and an immediate financial penalty is enforced for spammers who break this rate.
-
-**Prevention of Denial of Service (DoS) and Node Incentivization**:
-Denial of service signifies the case where an adversarial node exhausts another node's service capacity (e.g., by making a large number of requests) and makes it unavailable to the rest of the system.
-DoS attack is to be mitigated through the accounting model as described in [18/WAKU2-SWAP](/spec/18).
-In a nutshell, peers have to pay for the service they obtain from each other.
-In addition to incentivizing the service provider, accounting also makes DoS attacks costly for malicious peers.
-The accounting model can be used in `13/WAKU2-STORE` and `12/WAKU2-FILTER` to protect against DoS attacks.
-
-Additionally, this gives node operators who provide a useful service to the network an incentive to perform that service.
-See [18/WAKU2-SWAP](/spec/18) for more details on this piece of work.
-
-## Appendix A: Implementation Notes
 
 ### Implementation Matrix
 
@@ -267,7 +301,8 @@ There are multiple implementations of Waku v2 and its protocols:
 - [go-waku (Go)](https://github.com/status-im/go-waku/)
 - [js-waku (NodeJS and Browser)](https://github.com/status-im/js-waku/)
 
-Below you can find an overview of the specs that they implement as they relate to Waku. This includes Waku v1 specs, as they are used for bridging between the two networks.
+Below you can find an overview of the specs that they implement as they relate to Waku v2.
+This includes Waku v1 specs, as they are used for bridging between the two networks.
 
 | Spec | nim-waku (Nim) | go-waku (Go) | js-waku (Node JS) | js-waku (Browser JS) |
 | ---- | -------------- | ------------ | ----------------- | -------------------- |
@@ -309,44 +344,66 @@ For an interoperable keep-alive mechanism:
 - [libp2p ping protocol](https://docs.libp2p.io/concepts/protocols/#ping),
 with periodic pings to connected peers
 
-# Copyright
+## Appendix D: Future work
+
+The following features are currently experimental and under research and initial implementation:
+
+**Economic Spam resistance**:
+We aim to enable an incentivized spam protection technique to enhance `11/WAKU2-RELAY` by using rate limiting nullifiers.
+More details on this can be found in [17/WAKU2-RLNRELAY](/spec/17).
+In this advanced method, peers are limited to a certain rate of messaging per epoch and an immediate financial penalty is enforced for spammers who break this rate.
+
+**Prevention of Denial of Service (DoS) and Node Incentivization**:
+Denial of service signifies the case where an adversarial node exhausts another node's service capacity (e.g., by making a large number of requests) and makes it unavailable to the rest of the system.
+DoS attack is to be mitigated through the accounting model as described in [18/WAKU2-SWAP](/spec/18).
+In a nutshell, peers have to pay for the service they obtain from each other.
+In addition to incentivizing the service provider, accounting also makes DoS attacks costly for malicious peers.
+The accounting model can be used in `13/WAKU2-STORE` and `12/WAKU2-FILTER` to protect against DoS attacks.
+
+Additionally, this gives node operators who provide a useful service to the network an incentive to perform that service.
+See [18/WAKU2-SWAP](/spec/18) for more details on this piece of work.
+
+
+## Copyright
 
 Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
 
-# References
+## References
 
-1. [6/WAKU1 spec](/spec/6)
+1. [libp2p specs](https://github.com/libp2p/specs)
 
-2. [Whisper spec (EIP627)](https://eips.ethereum.org/EIPS/eip-627)
+2. [6/WAKU1 spec](/spec/6)
 
-3. [Waku v2 plan](https://vac.dev/waku-v2-plan)
+3. [Whisper spec (EIP627)](https://eips.ethereum.org/EIPS/eip-627)
 
-4. [Protocol Identifiers](https://docs.libp2p.io/concepts/protocols/)
+4. [Waku v2 plan](https://vac.dev/waku-v2-plan)
 
-5. [Protobuf varint encoding](https://developers.google.com/protocol-buffers/docs/encoding#varints)
+5. [Protocol Identifiers](https://docs.libp2p.io/concepts/protocols/)
 
-6. [7/WAKU-DATA spec](/spec/7)
+6. [Protobuf varint encoding](https://developers.google.com/protocol-buffers/docs/encoding#varints)
 
-7. [11/WAKU2-RELAY spec](/spec/11)
+7. [7/WAKU-DATA spec](/spec/7)
 
-8. [13/WAKU2-STORE spec](/spec/13)
+8. [11/WAKU2-RELAY spec](/spec/11)
 
-9. [12/WAKU2-FILTER spec](/spec/12)
+9. [13/WAKU2-STORE spec](/spec/13)
 
-10. [15/WAKU2-BRIDGE spec](/spec/15)
+10. [12/WAKU2-FILTER spec](/spec/12)
 
-11. [k-anonymity](https://www.privitar.com/blog/k-anonymity-an-introduction/)
+11. [15/WAKU2-BRIDGE spec](/spec/15)
 
-12. [GossipSub v1.1](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md)
+12. [k-anonymity](https://www.privitar.com/blog/k-anonymity-an-introduction/)
 
-13. [14/WAKU2-MESSAGE spec](/spec/14)
+13. [GossipSub v1.1](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md)
 
-14. [14/WAKU2-RLNRELAY spec](/spec/17)
+14. [14/WAKU2-MESSAGE spec](/spec/14)
 
-15. [18/WAKU2-SWAP spec](/spec/18)
+15. [14/WAKU2-RLNRELAY spec](/spec/17)
 
-16. [Ping protocol](https://docs.libp2p.io/concepts/protocols/#ping)
+16. [18/WAKU2-SWAP spec](/spec/18)
 
-17. [EIP-1459](https://eips.ethereum.org/EIPS/eip-1459)
+17. [Ping protocol](https://docs.libp2p.io/concepts/protocols/#ping)
 
-18. [Ambient peer discovery](https://docs.libp2p.io/concepts/publish-subscribe/#discovery)
+18. [EIP-1459](https://eips.ethereum.org/EIPS/eip-1459)
+
+19. [Ambient peer discovery](https://docs.libp2p.io/concepts/publish-subscribe/#discovery)