vacp2p/rfc
1
0
Fork 0
mirror of https://github.com/vacp2p/rfc.git synced 2025-02-22 11:48:25 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update README.md

Browse Source
This commit is contained in:
Jimmy Debe 2024-01-24 21:49:21 -05:00 committed by GitHub
parent 1e13ef731d
commit 9580382b4b
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 50 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

91
content/docs/rfcs/10/README.md
View File

@ -80,6 +80,7 @@ For more on the concept of adaptive nodes and what this means in practice,
please see the [30/ADAPTIVE-NODES](/spec/30) spec.
## Network interaction domains
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).
While Waku is best thought of as a single cohesive thing, there are three network interaction domains:
@ -97,7 +98,7 @@ The current main [protocol identifiers](https://docs.libp2p.io/concepts/protocol
3. `/vac/waku/filter/2.0.0-beta1`
4. `/vac/waku/lightpush/2.0.0-beta1`
This is in addition to protocols that specify messages, payloads, and recommended usages.
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:
@ -123,13 +124,13 @@ This length integer is encoded as a [protobuf varint](https://developers.google.
Waku is using gossiping to disseminate messages throughout the network.
**Protocol identifier**: `/vac/waku/relay/2.0.0`
**Protocol identifier***: `/vac/waku/relay/2.0.0`
See [11/WAKU2-RELAY](/spec/11) spec for more details.
For an experimental privacy-preserving economic spam protection mechanism, see [17/WAKU2-RLN-RELAY](/spec/17).
See [23/WAKU2-TOPICS](/spec/23) for more information about recommended topic usage.
See [23/WAKU2-TOPICS](/spec/23) for more information about the RECOMMENDED topic usage.
### Direct use of libp2p protocols
@ -141,7 +142,7 @@ In addition to `/vac/waku/*` protocols, Waku v2 MAY directly use the following l
/ipfs/ping/1.0.0
```
for liveness checks between peers, or to keep peer-to-peer connections alive.
For liveness checks between peers, or to keep peer-to-peer connections alive.
* [libp2p identity and identity/push](https://docs.libp2p.io/concepts/protocols/#identify) with protocol IDs
@ -156,28 +157,29 @@ and
/ipfs/id/push/1.0.0
```
respectively, as basic means for capability discovery.
Respectively, as basic means for capability discovery.
These protocols are anyway used by the libp2p connection establishment layer Waku v2 is built on.
We plan to introduce a new Vac capability discovery protocol with better anonymity properties and more functionality.
We plan to introduce a new Vac capability discovery protocol with better anonymity properties and
more functionality.
# Transports
Waku v2 is built in top of libp2p, and like libp2p it strives to be transport agnostic.
We define a set of recommended transports in order to achieve a baseline of interoperability between clients.
Waku v2 is built on top of libp2p, and like libp2p, it strives to be transport agnostic.
We define a set of RECOMMENDED transports in order to achieve a baseline of interoperability between clients.
This section describes these recommended transports.
Waku v2 node implementations SHOULD support the TCP transport.
Waku client implementations SHOULD support the TCP transport.
Where TCP is supported, it MUST be enabled for both dialing and listening,
even if other transports are available.
Where TCP is supported it MUST be enabled for both dialing and listening, even if other transports are available.
Waku v2 nodes, whose environment do not allow use of TCP directly,
MAY use other transports.
Waku v2 nodes where the environment do not allow to use TCP directly, MAY use other transports.
A Waku v2 node SHOULD support secure websockets for bidirectional communication streams, for example in a web browser context.
A Waku v2 node SHOULD support secure websockets for bidirectional communication streams,
for example in a web browser context.
A node MAY support unsecure websockets if required by the application or running environment.
### Discovery domain
#### Discovery methods
@ -188,22 +190,23 @@ it MAY be used in conjunction with an [ambient peer discovery](https://docs.libp
such as [Node Discovery v5](https://github.com/ethereum/devp2p/blob/8fd5f7e1c1ec496a9d8dc1640a8548b8a8b5986b/discv5/discv5.md).
More ambient peer discovery methods are being tested for Waku v2,
and will be specified for wider adoption.
It is possible to bypass the discovery domain by specifying static nodes.
A ambient peer discovery method used by Waku v2 is described in [33/WAKU2-DISCV5](/spec/33).
A Waku v2 node MAY bypass the discovery domain by specifying static nodes.
#### Use of ENR
[31/WAKU2-ENR](/spec/31) describes the usage of [EIP-778 ENR (Ethereum Node Records)](https://eips.ethereum.org/EIPS/eip-778) for Waku v2 discovery purposes.
It introduces two new ENR fields, `multiaddrs` and `waku2`, that a Waku v2 node MAY use for discovery purposes.
These fields MUST be used under certain conditions, as set out in the spec.
It introduces two new ENR fields, `multiaddrs` and `waku2`,
that a Waku v2 node MAY use for discovery purposes.
These fields MUST be used under certain conditions, as set out in the specification.
Both EIP-1459 DNS-based discovery and Node Discovery v5 operates on ENR,
and it's reasonable to expect even wider utility for ENR in Waku v2 networks in future.
### Request/Reply domain
### Request/Reponse domain
In addition to the Gossip domain,
Waku provides a set of Request/Reply protocols.
They are primarily used in order to get Waku to run in resource restricted environments,
Waku v2 provides a set of Request/Reponse protocols.
They are primarily used in order to get Waku v2 to run in resource restricted environments,
such as low bandwidth or being mostly offline.
#### Historical message support
@ -211,61 +214,65 @@ such as low bandwidth or being mostly offline.
**Protocol identifier***: `/vac/waku/store/2.0.0-beta4`
This is used to fetch historical messages for mostly offline devices.
See [13/WAKU2-STORE](/spec/13) spec for more details.
See [13/WAKU2-STORE](/spec/13) specifiction for more details.
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)
An experimental fault-tolerant addition to the store protocol, as described in [21/WAKU2-FT-STORE](/spec/21),
relaxes the high availability requirement.
#### 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.
See [12/WAKU2-FILTER](/spec/12) specification for more details.
#### Light push
**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.
This is used for nodes with short connection windows and
limited bandwidth to publish messages to the Waku network.
See [19/WAKU2-LIGHTPUSH](/spec/19) specification 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.
and due to the modular design of Waku v2 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)
![Overview of how protocols interact in Waku v2.](../../../../static/rfcs/10/overview.png)
0. We have six nodes, A-F.
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.
The PubSub topics `pubsubTopic1` and `pubsubTopic2` 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`.
2. Node A creates a `WakuMessage` with a ContentTopic `contentTopic1`.
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.
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`.
3. 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.
3. Node A publishes `msg1` on `pubtopic1` and subscribes to that relay topic pick it up.
4. 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).
4. Node D saves `msg1` for possible later retrieval by other nodes.
5. 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.
6. 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.
7. 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).
@ -470,6 +477,8 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public
20. [Node Discovery v5](https://github.com/ethereum/devp2p/blob/8fd5f7e1c1ec496a9d8dc1640a8548b8a8b5986b/discv5/discv5.md)
31. [31/WAKU2-ENR spec](/spec/31)
21. [33/WAKU2-DISCV5](/spec/33)
32. [EIP-778](https://eips.ethereum.org/EIPS/eip-778)
22. [31/WAKU2-ENR spec](/spec/31)
23. [EIP-778](https://eips.ethereum.org/EIPS/eip-778)