From 4ce0a6549ccb112d6415f6a46d3e3e4f688bf402 Mon Sep 17 00:00:00 2001 From: LordGhostX Date: Sat, 13 May 2023 21:58:19 +0100 Subject: [PATCH 01/13] overhaul concept protocols --- docs/overview/concepts/different-protocols.md | 27 --------- .../concepts/network-interaction-domains.md | 55 +++++++++++++++++++ .../concepts/protocols-overview-by-example.md | 49 ----------------- .../{protocols-explained.md => protocols.md} | 4 +- docs/overview/use-cases.md | 10 ++-- docs/overview/what-is-waku.md | 4 +- docusaurus.config.js | 2 +- sidebars.js | 7 +-- 8 files changed, 68 insertions(+), 90 deletions(-) delete mode 100644 docs/overview/concepts/different-protocols.md create mode 100644 docs/overview/concepts/network-interaction-domains.md delete mode 100644 docs/overview/concepts/protocols-overview-by-example.md rename docs/overview/concepts/{protocols-explained.md => protocols.md} (92%) diff --git a/docs/overview/concepts/different-protocols.md b/docs/overview/concepts/different-protocols.md deleted file mode 100644 index c230e67..0000000 --- a/docs/overview/concepts/different-protocols.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Different Types of Protocols in Waku ---- - -Waku is modular: several protocols are available and applications can decide on how they want to turn the dials on the [Anonymity Trilemma](https://freedom.cs.purdue.edu/projects/trilemma.html). Here are the different types of protocols Waku offers: - -## 1. Discovery Domain - -Node discovery is the mechanism that enables a Waku node to find other nodes. Waku is a modular protocol, several discovery mechanisms are and will be included in Waku (eg: [`Discv5`](https://rfc.vac.dev/spec/33/) and [`Peer Exchange`](https://rfc.vac.dev/spec/34/) ) so that developers can select the best mechanism(s) based for their use case and the user’s environment (e.g. mobile phone, desktop browser, server, etc). - -## 2. Gossip Domain - -Gossipsub is named after the fact that in a pub-sub network, the peers gossip to each other about which messages they have seen and use this information to maintain a message delivery network. - -Waku is using gossiping to disseminate messages throughout the network using [`WAKU-RELAY`](https://rfc.vac.dev/spec/11/). -An extension of this is [`WAKU-RLN-RELAY`](https://rfc.vac.dev/spec/17/): an experimental privacy-preserving economic spam protection mechanism. - -## 3. Request/Response 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, such as low bandwidth or being mostly offline. - -- [`WAKU-STORE`](https://rfc.vac.dev/spec/13/) is used to fetch historical messages for mostly offline devices. - -:::info There is also an experimental fault-tolerant addition to the store protocol (WAKU-FT-STORE) that relaxes the high availability requirement. - -- [`WAKU-FILTER`](https://rfc.vac.dev/spec/12/) is used to make fetching of a subset of messages more bandwidth preserving. -- [`WAKU-LIGHTPUSH`](https://rfc.vac.dev/spec/19/) is used for nodes with short connection windows and limited bandwidth to publish messages into the Waku network. diff --git a/docs/overview/concepts/network-interaction-domains.md b/docs/overview/concepts/network-interaction-domains.md new file mode 100644 index 0000000..57894ed --- /dev/null +++ b/docs/overview/concepts/network-interaction-domains.md @@ -0,0 +1,55 @@ +--- +title: Network Interaction Domains +--- + +Waku is a unified and cohesive entity that offers a rich ecosystem with three distinct network interaction domains. These domains serve specialized purposes and contribute to the robust functionality of Waku, forming its foundation. + +## Discovery Domain + +Node discovery in Waku facilitates locating other nodes within the network. As a modular protocol, Waku incorporates various discovery mechanisms, such as [`Discv5`](https://rfc.vac.dev/spec/33/) and [`Peer Exchange`](https://rfc.vac.dev/spec/34/). These mechanisms allow developers to choose the most suitable option(s) for their specific use cases and user environments, including mobile phones, desktop browsers, servers, and more. + +## Gossip Domain + +Gossipsub derives its name from the practice within pub-sub networks where peers gossip about the messages they have encountered, thus establishing a message delivery network. + +Waku employs gossiping through [`WAKU-RELAY`](https://rfc.vac.dev/spec/11/) to distribute messages across the network. Additionally, Waku introduces [`WAKU-RLN-RELAY`](https://rfc.vac.dev/spec/17/), an experimental mechanism that combines privacy preservation and economic spam protection. + +## Request/Reply Domain + +Waku provides a set of Request/Reply protocols to optimize its performance in resource-restricted environments like low bandwidth or offline scenarios. + +These protocols serve multiple purposes. [`WAKU-STORE`](https://rfc.vac.dev/spec/13/) enables the retrieval of historical messages, [`WAKU-FILTER`](https://rfc.vac.dev/spec/12/) efficiently retrieves a subset of messages to conserve bandwidth, and [`WAKU-LIGHTPUSH`](https://rfc.vac.dev/spec/19/) facilitates message publication for nodes with limited bandwidth and short connection windows. + +## Overview of Protocol Interaction + +Here's a diagram illustrating the interaction between different protocols within the Waku network. + +```mermaid +sequenceDiagram +participant A as A relay +participant B as B relay(pubtopic1) +participant C as C relay(pubtopic1) +participant D as D relay(pubtopic1), store(pubtopic1), filter +participant E as E relay, store +participant F as F relay, filter + +A ->> A: msg1=WakuMessage(contentTopic1, data) (1) +F ->> D: FilterRequest(pubtopic1, contentTopic1) (2) +D ->> D: Subscribe F to filter (2) +A ->> B: Publish msg1 on pubtopic1 (3) +B ->> D: relay msg1 on pubtopic1 (3) +D ->> D: store: saves msg1 (4) +D ->> F: MessagePush(msg1) (5) +E ->> E: E comes online (6) +E ->> D: HistoryQuery(pubtopic1, contentTopic1) (6) +D ->> E: HistoryResponse(msg1, ...) (6) +``` + +The Pub/Sub topic `pubtopic1` serves as a means of routing messages (the network employs a default pub-sub topic) and indicates that it is subscribed to messages on that topic for a relay. In the context of Waku Store, Node D is responsible for persisting these messages. + +1. Node A creates a WakuMessage `msg1` with a ContentTopic `contentTopic1`. +2. Node F requests to get messages filtered by Pub/Sub topic `pubtopic1` and ContentTopic `contentTopic1`. Node D subscribes F to this filter and will forward messages that match that filter in the future. +3. Node A publishes `msg1` on `pubtopic1`. The message is sent from Node A to Node B and then forwarded to Node D. +4. Node D, upon receiving `msg1`, stores the message in its store for possible later retrieval by other nodes. +5. Node D also pushes `msg1` to Node F, informing it about the arrival of a new message. +6. At a later time, Node E comes online and requests messages matching `pubtopic1` and `contentTopic1` from Node D. Node D responds with `msg1` and potentially other messages that match the query. \ No newline at end of file diff --git a/docs/overview/concepts/protocols-overview-by-example.md b/docs/overview/concepts/protocols-overview-by-example.md deleted file mode 100644 index 09b48fa..0000000 --- a/docs/overview/concepts/protocols-overview-by-example.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Protocols Overview by Example ---- - -We have six nodes, A-F. - -The protocols initially mounted are indicated as such. - -```mermaid -sequenceDiagram - participant A as A relay(0) - participant B as B relay(pubtopic1)(0) - participant C as C relay(pubtopic1)(0) - participant D as D relay(pubtopic1), store(pubtopic1), filter(0) - participant E as E relay, store(0) - participant F as F relay, filter(0) - - A ->> A: msg1=WakuMessage(contentTopic1, data) [14/WAKU2-MESSAGE] (1) - Note right of A: If version=1, encrypt data per [7/WAKU-DATA] (1) - - F ->> D: FilterRequest(pubtopic1, contentTopic1) [12/WAKU2-FILTER] (2) - D ->> D: Subscribe F to filter [12/WAKU2-FILTER] (2) - - A ->> B: Publish msg1 on pubtopic1 [11/WAKU2-RELAY] (3) - B ->> D: relay msg1 on pubtopic1 [11/WAKU2-RELAY] (3) - - D ->> D: store: saves msg1 [13/WAKU2-STORE] (4) - - D ->> F: MessagePush(msg1)[12/WAKU2-FILTER] (5) - - E ->> E: E comes online (6) - E ->> D: HistoryQuery(pubtopic1, contentTopic1) [13/WAKU2-STORE] (6) - D ->> E: HistoryResponse(msg1, ...) [13/WAKU2-STORE] (6) - -``` - -The PubSub topic `pubtopic1` is used for routing (the network uses a default pubsub topic) and indicates that it is subscribed to messages on that topic for relay.Ditto for Waku Store where it indicates that these messages are persisted on that node. - -1. Node A creates a WakuMessage `msg1` with a ContentTopic `/my-dapp/0/notifications/proto`. - -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. - -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. - -4. Node D saves `msg1` for possible later retrieval by other nodes. - -5. Node D also pushes `msg1` to F, as it has previously subscribed F to this filter. - -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. diff --git a/docs/overview/concepts/protocols-explained.md b/docs/overview/concepts/protocols.md similarity index 92% rename from docs/overview/concepts/protocols-explained.md rename to docs/overview/concepts/protocols.md index 8f6db3b..b3cf68f 100644 --- a/docs/overview/concepts/protocols-explained.md +++ b/docs/overview/concepts/protocols.md @@ -1,7 +1,9 @@ --- -title: Protocols Explained +title: Waku Protocols --- +Waku is modular: several protocols are available and applications can decide on how they want to turn the dials on the [Anonymity Trilemma](https://freedom.cs.purdue.edu/projects/trilemma.html). Here are the different types of protocols Waku offers: + Currently, the main Waku protocols are: ### [Waku Relay](https://rfc.vac.dev/spec/11/) diff --git a/docs/overview/use-cases.md b/docs/overview/use-cases.md index 580fc38..7c62a61 100644 --- a/docs/overview/use-cases.md +++ b/docs/overview/use-cases.md @@ -2,9 +2,7 @@ title: Waku Use Cases --- -Waku is a decentralized communication network that supports person-to-person and machine-to-machine communication, enabling secure and private operation without a central authority. - -The following is a list of some of the use cases that have been considered and their current status. +Waku is a decentralized communication network, facilitating secure and private person-to-person and machine-to-machine communication without a central authority. It supports various use cases, including but not limited to: ### Chat Messenger @@ -16,7 +14,7 @@ Waku can be used as the communication layer when building a private, decentraliz ### Polls -With Waku, you can create, answer, and view censorship-resistant polls. +With Waku, you can create, answer, and view censorship-resistant polls, fostering a democratic and transparent voting environment immune to manipulation and censorship. #### Demos @@ -32,7 +30,7 @@ Waku can be used to take NFT bids and offers off-chain, enabling gas savings. Ad ### State Channels -Waku can enable two parties to set up and maintain a state channel. +Waku can enable two parties to establish and sustain a state channel effortlessly, facilitating message exchange and seamless updates to their shared agreement without direct blockchain involvement. ### Voting and Proposals @@ -65,7 +63,7 @@ dApp operators can use communication between a user's wallet and their dApp to n ### Layer 2 Coordination (Open Market, Spam Protected Mempool) -Waku can broadcast and aggregate layer 2 transactions, potentially enhancing privacy, anonymity, and resilience. +Waku can broadcast and aggregate Layer 2 transactions to enhance privacy, anonymity, and resilience. Aggregating transactions reduces network load and improves scalability, ensuring a more robust Layer 2 ecosystem. ### Generalized Marketplace diff --git a/docs/overview/what-is-waku.md b/docs/overview/what-is-waku.md index 9031abc..cf43af8 100644 --- a/docs/overview/what-is-waku.md +++ b/docs/overview/what-is-waku.md @@ -17,11 +17,11 @@ Waku aims to solve the problem of ephemeral messaging between subsystems and nod ### Peer-to-Peer -Waku is suitable for applications that require a peer-to-peer approach, as it offers the following advantages: +Waku is suitable for applications that require a peer-to-peer approach, offering the following advantages: - Censorship resistance with no single point of failure. - Adaptive and scalable network. -- Shared infrastructure/service network. +- Shared infrastructure, leveraging the capabilities of Waku as a service network. ### Platform Agnostic diff --git a/docusaurus.config.js b/docusaurus.config.js index d319f01..2466590 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -65,7 +65,7 @@ const config = { }, announcementBar: { content: - "While Waku still has progress to make, apps like XMTP and Railgun have already implemented it in production. Join our Discord Community to stay updated on our progress.", + "While Waku is still in development and needs to prepare for extensive adoption, it is already being used by XMTP and Railgun. Join our Discord Community to stay updated on our progress.", backgroundColor: "#EBEDF0", textColor: "#1B1B1D", isCloseable: true, diff --git a/sidebars.js b/sidebars.js index 30b00d8..8bba87f 100644 --- a/sidebars.js +++ b/sidebars.js @@ -12,13 +12,12 @@ const sidebars = { "overview/implementations", { type: "category", - label: "Concepts", + label: "Waku Concepts", collapsed: false, collapsible: true, items: [ - "overview/concepts/different-protocols", - "overview/concepts/protocols-explained", - "overview/concepts/protocols-overview-by-example", + "overview/concepts/network-interaction-domains", + "overview/concepts/protocols", "overview/concepts/discovery-and-bootstrap", "overview/concepts/transports-in-waku", "overview/concepts/content-topics", From 1f3ee4e6beb2515d0746f2cbf2cf39a1b51f7630 Mon Sep 17 00:00:00 2001 From: LordGhostX Date: Sun, 14 May 2023 04:01:19 +0100 Subject: [PATCH 02/13] overhaul protocols docs --- .../concepts/network-interaction-domains.md | 6 +- docs/overview/concepts/protocols.md | 68 ++++++------------- docs/overview/what-is-waku.md | 2 +- docusaurus.config.js | 2 +- 4 files changed, 25 insertions(+), 53 deletions(-) diff --git a/docs/overview/concepts/network-interaction-domains.md b/docs/overview/concepts/network-interaction-domains.md index 57894ed..022177c 100644 --- a/docs/overview/concepts/network-interaction-domains.md +++ b/docs/overview/concepts/network-interaction-domains.md @@ -12,13 +12,13 @@ Node discovery in Waku facilitates locating other nodes within the network. As a Gossipsub derives its name from the practice within pub-sub networks where peers gossip about the messages they have encountered, thus establishing a message delivery network. -Waku employs gossiping through [`WAKU-RELAY`](https://rfc.vac.dev/spec/11/) to distribute messages across the network. Additionally, Waku introduces [`WAKU-RLN-RELAY`](https://rfc.vac.dev/spec/17/), an experimental mechanism that combines privacy preservation and economic spam protection. +Waku employs gossiping through [`WAKU-RELAY`](/overview/concepts/protocols#waku-relay) to distribute messages across the network. Additionally, Waku introduces [`WAKU-RLN-RELAY`](/overview/concepts/protocols#waku-rln-relay), an experimental mechanism that combines privacy preservation and economic spam protection. ## Request/Reply Domain Waku provides a set of Request/Reply protocols to optimize its performance in resource-restricted environments like low bandwidth or offline scenarios. -These protocols serve multiple purposes. [`WAKU-STORE`](https://rfc.vac.dev/spec/13/) enables the retrieval of historical messages, [`WAKU-FILTER`](https://rfc.vac.dev/spec/12/) efficiently retrieves a subset of messages to conserve bandwidth, and [`WAKU-LIGHTPUSH`](https://rfc.vac.dev/spec/19/) facilitates message publication for nodes with limited bandwidth and short connection windows. +These protocols serve multiple purposes. [`WAKU-STORE`](/overview/concepts/protocols#waku-store) enables the retrieval of historical messages, [`WAKU-FILTER`](/overview/concepts/protocols#waku-filter) efficiently retrieves a subset of messages to conserve bandwidth, and [`WAKU-LIGHTPUSH`](/overview/concepts/protocols#waku-light-push) facilitates message publication for nodes with limited bandwidth and short connection windows. ## Overview of Protocol Interaction @@ -45,7 +45,7 @@ E ->> D: HistoryQuery(pubtopic1, contentTopic1) (6) D ->> E: HistoryResponse(msg1, ...) (6) ``` -The Pub/Sub topic `pubtopic1` serves as a means of routing messages (the network employs a default pub-sub topic) and indicates that it is subscribed to messages on that topic for a relay. In the context of Waku Store, Node D is responsible for persisting these messages. +The Publish/Subscribe topic `pubtopic1` serves as a means of routing messages (the network employs a default pub-sub topic) and indicates that it is subscribed to messages on that topic for a relay. In the context of Waku Store, Node D is responsible for persisting these messages. 1. Node A creates a WakuMessage `msg1` with a ContentTopic `contentTopic1`. 2. Node F requests to get messages filtered by Pub/Sub topic `pubtopic1` and ContentTopic `contentTopic1`. Node D subscribes F to this filter and will forward messages that match that filter in the future. diff --git a/docs/overview/concepts/protocols.md b/docs/overview/concepts/protocols.md index b3cf68f..393e0d0 100644 --- a/docs/overview/concepts/protocols.md +++ b/docs/overview/concepts/protocols.md @@ -1,71 +1,43 @@ --- -title: Waku Protocols +title: Protocols in Waku --- -Waku is modular: several protocols are available and applications can decide on how they want to turn the dials on the [Anonymity Trilemma](https://freedom.cs.purdue.edu/projects/trilemma.html). Here are the different types of protocols Waku offers: - -Currently, the main Waku protocols are: +Waku takes a modular approach, providing a range of protocols that enable applications to control the trade-offs involved in the [Anonymity Trilemma](https://eprint.iacr.org/2017/954.pdf). This flexibility empowers applications to make informed choices regarding the desired balance between anonymity, scalability, and reliability. Here are the main protocols provided by Waku: ### [Waku Relay](https://rfc.vac.dev/spec/11/) -`WAKU2-RELAY` specifies a Publish/Subscribe approach to peer-to-peer messaging with a strong focus on privacy, censorship-resistance, security and scalability. -Its current implementation is a minor extension of the libp2p GossipSub protocol and prescribes gossip-based dissemination. - -An extension of this is `WAKU-RLN-RELAY`, a privacy-preserving economic spam protection mechanism. +`WAKU2-RELAY` is a privacy-focused peer-to-peer messaging protocol that extends the `libp2p GossipSub` protocol. It utilizes a Publish/Subscribe approach to enable secure communication channels, encryption, and protection against censorship. With a strong emphasis on privacy, `Waku Relay` ensures scalability, allowing many peers and messages to coexist within the network. ### [Waku Filter](https://rfc.vac.dev/spec/12/) -`WAKU2-FILTER` is a protocol that enables subscribing to messages that a peer receives. -It enables a node to access the relay network without the connectivity and bandwidth requirements of relay nodes, but it comes with privacy drawbacks. -Light nodes subscribe to service nodes and only receive the messages they desire. - -It makes receiving messages more bandwidth preserving. +`WAKU2-FILTER` is a protocol enabling peers to subscribe to specific messages from other peers. It is designed for devices with limited bandwidth, serving as a lighter alternative to [Waku Relay](#waku-relay). Unlike relay nodes, `Waku Filter` allows light nodes to subscribe to service nodes and receive only the messages they are interested in. This optimizes bandwidth consumption but may involve privacy compromises. Nonetheless, `Waku Filter` efficiently delivers desired messages within bandwidth constraints. ### [Waku Store](https://rfc.vac.dev/spec/13/) -DApps running on a phone or in a browser are often offline: -The browser could be closed or mobile app in the background. +`WAKU2-STORE` is a protocol that allows the querying of messages received through the relay protocol and stored by nodes. It supports retrieving historical messages with pagination. Unlike [Waku Relay](#waku-relay), which doesn't save messages for offline users, `Waku Store` peers retain relayed messages for later retrieval. -[Waku Relay](https://rfc.vac.dev/spec/11/) is a gossip protocol. -As a user, it means that your peers forward you messages they just received. -If you cannot be reached by your peers, then messages are not relayed; -relay peers do **not** save messages for later. - -However, [Waku Store](https://rfc.vac.dev/spec/13/) peers do save messages they relay, -allowing you to retrieve them at a later time. -The Waku Store protocol is best-effort and does not guarantee data availability. -Waku Relay or Waku Filter should still be preferred when online; -Waku Store can be used after resuming connectivity: -For example, when the dApp starts. +:::info +Data availability is not guaranteed with `Waku Store`. [Waku Relay](#waku-relay) or [Waku Filter](#waku-filter) are preferred for online usage, while `Waku Store` is suitable for retrieving messages after reconnecting to the network, like when a dApp starts. +::: ### [Waku Light Push](https://rfc.vac.dev/spec/19/) -Waku Light Push enables a client to receive a confirmation when sending a message. +`WAKU2-LIGHTPUSH` is a [Request/Reply](/overview/concepts/network-interaction-domains#requestreply-domain) protocol for Waku's light nodes with limited bandwidth and short connection windows. It enables clients to receive a confirmation when sending messages, indicating that at least one node has received them. However, using `Waku Light Push` compromises privacy as the remote peer becomes aware of the message originator. -The Waku Relay protocol sends messages to connected peers but does not provide any information on whether said peers have received messages. -This can be an issue when facing potential connectivity issues. -For example, when the connection drops easily, or it is connected to a small number of relay peers. - -Waku Light Push allows a client to get a response from a remote peer when sending a message. -Note this only guarantees that the remote peer has received the message, -it cannot guarantee propagation to the network. - -It also means weaker privacy properties as the remote peer knows the client is the originator of the message. -Whereas with Waku Relay, a remote peer would not know whether the client created or forwarded the message. - -You can find Waku Light Push's specifications on [Vac RFC](https://rfc.vac.dev/spec/19/). - -`WAKU2-LIGHTPUSH` is a request/response protocol for this. +:::info +Please note that `Waku Light Push` confirms receipt by the remote peer but doesn't guarantee network-wide propagation. +::: ## Additional Protocols -This is in addition to protocols that specify messages, payloads, and recommended usages. -For example: +### [Waku Message](https://rfc.vac.dev/spec/14) -- [14/WAKU2-MESSAGE](https://rfc.vac.dev/spec/14) and [26/WAKU2-PAYLOAD](https://rfc.vac.dev/spec/26) for message payloads -- [23/WAKU2-TOPICS](https://rfc.vac.dev/spec/23) and [27/WAKU2-PEERS](https://rfc.vac.dev/spec/27) for recommendations around usage +`WAKU2-MESSAGE` is a communication protocol that facilitates the exchange of messages between peers in the network. It includes the data payload (actual message content being transmitted) and attributes (metadata associated with the message). -There are also more experimental libp2p protocols such as -[`WAKU-RLN-RELAY`](https://rfc.vac.dev/spec/17/) +### [Waku Payload](https://rfc.vac.dev/spec/26) -You can find more information on this [here](./research-in-progress.md). +`WAKU2-PAYLOAD` provides guidelines for implementing secure and private communication in the Waku network. It covers encryption, decryption, and signing methods for message payloads, focusing on confidentiality, authenticity, integrity, and unlinkability. + +### [Waku RLN Relay](https://rfc.vac.dev/spec/17/) + +The `WAKU2-RLN-RELAY` protocol extends the [Waku Relay](#waku-relay) protocol by adding spam protection using [Rate Limiting Nullifiers (RLN)](https://rfc.vac.dev/spec/32/). It enforces a global messaging rate for all peers to prevent spam in the Waku network. Spammers face financial penalties and removal from the system. This protocol provides efficient and economic spam prevention suitable for resource-constrained environments. \ No newline at end of file diff --git a/docs/overview/what-is-waku.md b/docs/overview/what-is-waku.md index cf43af8..8455220 100644 --- a/docs/overview/what-is-waku.md +++ b/docs/overview/what-is-waku.md @@ -43,7 +43,7 @@ Waku nodes are adaptive and can be customized based on the application's require - Providing resources to the network vs. consuming resources. - Stronger guarantees for spam protection vs. economic registration cost. -These options are part of the [anonymity trilemma](https://eprint.iacr.org/2017/954.pdf), which Waku addresses through its adjustable protocol. +These options are part of the [Anonymity Trilemma](https://eprint.iacr.org/2017/954.pdf), which Waku addresses through its adjustable protocol. ## How Does Waku Work? diff --git a/docusaurus.config.js b/docusaurus.config.js index 2466590..fc288b9 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -65,7 +65,7 @@ const config = { }, announcementBar: { content: - "While Waku is still in development and needs to prepare for extensive adoption, it is already being used by XMTP and Railgun. Join our Discord Community to stay updated on our progress.", + "While Waku is still in development and needs to prepare for extensive adoption, it is already being used by Status, XMTP and Railgun. Join our Discord Community to stay updated on our progress.", backgroundColor: "#EBEDF0", textColor: "#1B1B1D", isCloseable: true, From 7f100470f2781bfeda5a2c0523ba374a8db54b91 Mon Sep 17 00:00:00 2001 From: LordGhostX Date: Sun, 14 May 2023 06:08:18 +0100 Subject: [PATCH 03/13] overhaul node discovery --- README.md | 6 ++ .../concepts/discovery-and-bootstrap.md | 96 ------------------- ...eraction-domains.md => network-domains.md} | 2 +- docs/overview/concepts/node-discovery.md | 75 +++++++++++++++ docs/overview/what-is-waku.md | 12 +-- docs/overview/why-waku.md | 2 +- sidebars.js | 4 +- 7 files changed, 91 insertions(+), 106 deletions(-) delete mode 100644 docs/overview/concepts/discovery-and-bootstrap.md rename docs/overview/concepts/{network-interaction-domains.md => network-domains.md} (90%) create mode 100644 docs/overview/concepts/node-discovery.md diff --git a/README.md b/README.md index 7a46caf..8443f08 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,12 @@ yarn install yarn start ``` +Check for spelling errors before deploying: + +```bash +npm run check:spell +``` + ## Configuration Edit the `docusaurus.config.js` file located in the repository's root directory, and update the `businessUnit` field within the presets section. Here is a list of valid values for this field: diff --git a/docs/overview/concepts/discovery-and-bootstrap.md b/docs/overview/concepts/discovery-and-bootstrap.md deleted file mode 100644 index 8f898cd..0000000 --- a/docs/overview/concepts/discovery-and-bootstrap.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: Discovery & Bootstrap Nodes ---- - -Node discovery is the mechanism that enables a Waku node to find other nodes. - -When starting a Waku node, it needs to connect to other nodes to be able to send, receive and retrieve messages. -This means there needs to be a discovery mechanism that enables finding other nodes when its initially not connected to any nodes. -This process is called _bootstrapping_. - -Once connected, the node needs to find additional peers to have: - -- Enough peers in the Waku Relay mesh (target is 6), -- Enough peers in reserve, in case current peers are overloaded or go offline, -- Peers with specific Waku capabilities (e.g. Store, Light Push, Filter). - -## Predefined Bootstrap Nodes - -An application using Waku can hardcode the addresses of bootstrap nodes directly in their codebase. - -You can choose to use Status' deployed nodes, or run your own. - -:::info Developers have the choice to run their own [nwaku](https://github.com/status-im/nim-waku/) nodes. Read [Nwaku Service Node](https://github.com/status-im/nwaku/tree/master/docs/operators) to learn how to run your own node. -:::: - -**Pros:** - -- Low latency -- Low resource requirements - -**Cons:** - -- Prone to censorship: node IPs can be blocked -- Limited: Static number of nodes -- Poor maintainability: Code needs to be changed to update the list - -## DNS Discovery - -[EIP-1459: Node Discovery via DNS](https://eips.ethereum.org/EIPS/eip-1459) has been implemented in js-waku, nwaku and go-waku with some modification on the [ENR format](https://rfc.vac.dev/spec/31/). - -DNS Discovery enables anyone to register an ENR tree in the `TXT` field of a domain name. - -_ENR_ is the format used to store node connection details (IP, port, multiaddr, etc). - -This enables a separation of software development and operations as dApp developers can include one or several domain names to use for DNS discovery, while operators can handle the update of the dns record. - -It also enables more decentralized bootstrapping as anyone can register a domain name and publish it for others to use. - -**Pros:** - -- Low latency, low resource requirements, -- Bootstrap list can be updated by editing a domain name: no code change is needed, -- Can reference to a greater list of nodes by pointing to other domain names in the code or in the ENR tree. - -**Cons:** - -- Prone to censorship: domain names can be blocked, -- Limited: Static number of nodes, operators must provide their ENR to the domain owner to get their node listed. - -## Discv5 - -Discovery v5 is an ambient peer discovery method for Waku v2: it is decentralized, efficient, actively researched, and has web3 as its main application area. -As Discv5 uses [DHT](https://en.wikipedia.org/wiki/Distributed_hash_table) to store ENR records, it is more resilient to censorship than DNS discovery. -And one of the main benefits of DHTs is offering a global view over participating nodes. This, in turn, allows sampling random sets of nodes which is important for equally distributing load. - -Without discv5 and similar methods, the bootstrap nodes are used as part of the gossipsub mesh. This might put heavy load on these nodes and further, might open pathways to inference attacks. Discv5, on the other hand, uses the bootstrap nodes merely as an entry to the discovery network and can provide random sets of nodes (sampled from a global view) for bootstrapping or expanding the mesh. - -**_Pros:_** - -- Decentralized; random sampling of nodes from a global view -- Actively researched - -**_Cons:_** - -- High resource requirements -- Nodes behind restrictive NAT setups cannot run this protocol - -## Peer Exchange - -While discv5 based ambient peer discovery has many desirable properties, resource restricted nodes and nodes behind restrictive NAT setups cannot run discv5 satisfactory. -With these nodes in mind, [Peer Exchange](https://rfc.vac.dev/spec/34/) was introduced. - -The main purpose of this protocol is providing resource restricted devices with peers. -The peer exchange protocol allows resource restricted nodes (light nodes) to ask for peers from other nodes in the network. This allows light nodes to bootstrap and expand their mesh without relying on discv5 or bootstrap nodes. - -This protocol should only be used if discv5 is infeasible. - -**_Pros:_** - -- Low resource requirements -- Decentralized; random sampling of nodes from a global view (via discv5) - -**_Cons:_** - -- Reduced anonymity -- Cause load on responder nodes diff --git a/docs/overview/concepts/network-interaction-domains.md b/docs/overview/concepts/network-domains.md similarity index 90% rename from docs/overview/concepts/network-interaction-domains.md rename to docs/overview/concepts/network-domains.md index 022177c..7bf418c 100644 --- a/docs/overview/concepts/network-interaction-domains.md +++ b/docs/overview/concepts/network-domains.md @@ -6,7 +6,7 @@ Waku is a unified and cohesive entity that offers a rich ecosystem with three di ## Discovery Domain -Node discovery in Waku facilitates locating other nodes within the network. As a modular protocol, Waku incorporates various discovery mechanisms, such as [`Discv5`](https://rfc.vac.dev/spec/33/) and [`Peer Exchange`](https://rfc.vac.dev/spec/34/). These mechanisms allow developers to choose the most suitable option(s) for their specific use cases and user environments, including mobile phones, desktop browsers, servers, and more. +Node discovery in Waku facilitates locating other nodes within the network. As a modular protocol, Waku incorporates various discovery mechanisms, such as [`Discv5`](/overview/concepts/node-discovery#discv5) and [`Peer Exchange`](/overview/concepts/node-discovery#peer-exchange). These mechanisms allow developers to choose the most suitable option(s) for their specific use cases and user environments, including mobile phones, desktop browsers, servers, and more. ## Gossip Domain diff --git a/docs/overview/concepts/node-discovery.md b/docs/overview/concepts/node-discovery.md new file mode 100644 index 0000000..9f020a2 --- /dev/null +++ b/docs/overview/concepts/node-discovery.md @@ -0,0 +1,75 @@ +--- +title: Node Discovery Mechanisms +--- + +When initializing a Waku node, it must connect with other nodes to enable message sending, receiving, and retrieval. To achieve this, a discovery mechanism is employed to locate other nodes where no connections are present. This process is known as bootstrapping. + +After establishing a connection, the node must actively seek out additional peers to have: + +- Sufficient peers in the `Waku Relay` mesh: The goal is to have at least 6 peers in the mesh. This ensures a robust network where messages can be efficiently relayed. +- Reserve peers for backup: It is essential to have a surplus of peers available as reserves. These reserves are backups when the current peers become overloaded or experience unexpected disconnections. +- Peers with specific Waku capabilities: The node seeks out peers with specific Waku capabilities, such as `Store`, `Light Push`, or `Filter`. This allows for targeted interactions and enhanced functionality based on the desired capabilities. + +## Predefined Bootstrap Nodes + +Waku applications have the flexibility to embed bootstrap node addresses directly into their codebase. Developers can opt to utilize either the [pre-deployed nodes by Status](https://github.com/waku-org/js-waku/blob/master/packages/core/src/lib/predefined_bootstrap_nodes.ts#L45) or [set up their nodes](https://github.com/waku-org/nwaku/tree/master/docs/operators) per their preference. + +#### Pros + +- Low latency. +- Low resource requirements. + +#### Cons + +- Vulnerable to censorship: Node IPs can be blocked or restricted. +- Limited scalability: The number of nodes is fixed and cannot easily be expanded. +- Maintenance challenges: Updating the node list requires modifying the code, which can be cumbersome and less maintainable. + +## [DNS Discovery](https://rfc.vac.dev/spec/31/) + +Built upon the foundation of [EIP-1459: Node Discovery via DNS](https://eips.ethereum.org/EIPS/eip-1459), DNS Discovery allows for registering an `ENR` tree in the `TXT` field of a domain name. This innovative approach enables the storage of essential node connection details, including IP, port, and multiaddr, utilizing the standardized [ENR format](https://rfc.vac.dev/spec/31/). + +This bootstrapping method allows anyone to register and publish a domain name for the network, fostering increased decentralization. + +#### Pros + +- Low latency, low resource requirements. +- Easy bootstrap list updates by modifying the domain name, eliminating the need for code changes. +- Ability to reference a larger list of nodes by including other domain names in the code or ENR tree. + +#### Cons + +- Vulnerable to censorship: Domain names can be blocked or restricted. +- Limited scalability: The number of nodes is fixed, and operators need to provide their `ENR` to the domain owner for listing. + +## [Discv5](https://rfc.vac.dev/spec/33/) + +`Discv5` is a decentralized and efficient peer discovery method for the Waku network. It utilizes a [Distributed Hash Table (DHT)](https://en.wikipedia.org/wiki/Distributed_hash_table) for storing `ENR` records, providing resistance to censorship. `Discv5` offers a global view of participating nodes, enabling random sampling for load distribution. It uses bootstrap nodes as an entry point to the network, providing randomized sets of nodes for mesh expansion. This enhances resilience, load balancing, and security in the Waku network. + +#### Pros + +- Decentralized with random sampling from a global view. +- Continuously researched and improved. + +#### Cons + +- Demands high resource allocation. +- Nodes hindered by restrictive NAT setups are unable to run this protocol. + +## [Peer Exchange](https://rfc.vac.dev/spec/34/) + +The primary objective of this protocol is to facilitate peer connectivity for resource-restricted devices. The peer exchange protocol enables lightweight nodes to request peers from other nodes within the network. Light nodes can bootstrap and expand their mesh independently without relying on `Discv5` or bootstrap nodes. + +:::info +This protocol is intended for situations where the use of `Discv5` is not feasible. +::: + +#### Pros + +- Low resource requirements. +- Decentralized with random sampling of nodes from a global view using `Discv5`. + +#### Cons + +- Decreased anonymity. +- Imposes additional load on responder nodes. diff --git a/docs/overview/what-is-waku.md b/docs/overview/what-is-waku.md index 8455220..0d2aa48 100644 --- a/docs/overview/what-is-waku.md +++ b/docs/overview/what-is-waku.md @@ -3,9 +3,9 @@ title: What is Waku? slug: / --- -Waku is a family of peer-to-peer protocols that offer **secure and private communication** in a decentralized environment, making it suitable for various decentralized applications (dApps). It is designed to operate in **resource-limited environments** but can also be used as a node or desktop application. +Waku is a family of peer-to-peer protocols that offer secure and private communication in a decentralized environment, making it suitable for various decentralized applications (dApps). It is designed to operate in resource-limited environments but can also be used as a node or desktop application. -Waku protocols ensure that users communication remains **censorship-resistant and privacy-preserving**, giving them complete control over their data. By incorporating Waku into your dApp, you can add decentralized communication features to your application **without compromising security or privacy**. +Waku protocols ensure that users communication remains censorship-resistant and privacy-preserving, giving them complete control over their data. By incorporating Waku into your dApp, you can add decentralized communication features to your application without compromising security or privacy. ## Motivation and Goals @@ -49,10 +49,10 @@ These options are part of the [Anonymity Trilemma](https://eprint.iacr.org/2017/ The Waku Relay protocol is the foundation of the Waku Network, which employs a `pubsub` architecture built on the `libp2p gossipsub` protocol. In addition to this, various other Waku protocols have been created to facilitate specific functionalities, including but not limited to: -1. Facilitating the retrieval of **historical messages** for primarily offline devices. -2. Providing solutions for **encrypted communication**, such as symmetric encryption, ECIES/asymmetric encryption, and noise handshake-based key turns. -3. Preserve bandwidth usage for **resource-limited environments**. -4. Implementing economic **spam protection** (rate limits) while ensuring privacy. +1. Facilitating the retrieval of historical messages for primarily offline devices. +2. Providing solutions for encrypted communication, such as symmetric encryption, ECIES/asymmetric encryption, and noise handshake-based key turns. +3. Preserve bandwidth usage for resource-limited environments. +4. Implementing economic spam protection (rate limits) while ensuring privacy. 5. Developing methods to protect against mass deanonymization (currently being researched). If you want to learn more about how Waku operates, the [10/WAKU2](https://rfc.vac.dev/spec/10/) RFC provides an in-depth look under the hood. diff --git a/docs/overview/why-waku.md b/docs/overview/why-waku.md index 0aaede5..e876564 100644 --- a/docs/overview/why-waku.md +++ b/docs/overview/why-waku.md @@ -4,7 +4,7 @@ title: Why Waku? Communication in the present day is heavily influenced by third-party intervention, ranging from censorship and deplatforming to intermediaries that seek to profit from rent and the misuse of data in the surveillance economy. -Waku is intended to empower individuals by returning control of communication to them. It is the go-to standard for Web3 communication, offering a **scalable decentralized communication** solution. +Waku is intended to empower individuals by returning control of communication to them. It is the go-to standard for Web3 communication, offering a scalable decentralized communication solution. - Waku improves upon Whisper's capabilities by overcoming limitations and addressing functional gaps. - It provides a public infrastructure for the Ethereum and multi-chain ecosystem, serving as a common good. diff --git a/sidebars.js b/sidebars.js index 8bba87f..09dd9ed 100644 --- a/sidebars.js +++ b/sidebars.js @@ -16,9 +16,9 @@ const sidebars = { collapsed: false, collapsible: true, items: [ - "overview/concepts/network-interaction-domains", "overview/concepts/protocols", - "overview/concepts/discovery-and-bootstrap", + "overview/concepts/network-domains", + "overview/concepts/node-discovery", "overview/concepts/transports-in-waku", "overview/concepts/content-topics", "overview/concepts/security-features", From d117ca5375550b37330403a548faef0e7a972eb1 Mon Sep 17 00:00:00 2001 From: LordGhostX Date: Sun, 14 May 2023 06:18:41 +0100 Subject: [PATCH 04/13] overhaul transports --- docs/overview/concepts/transports-in-waku.md | 11 ----------- docs/overview/concepts/transports.md | 13 +++++++++++++ .../research-in-progress.md | 0 .../{concepts => reference}/security-features.md | 0 .../{concepts => reference}/waku-vs-libp2p.md | 0 sidebars.js | 16 ++++++++++++---- 6 files changed, 25 insertions(+), 15 deletions(-) delete mode 100644 docs/overview/concepts/transports-in-waku.md create mode 100644 docs/overview/concepts/transports.md rename docs/overview/{concepts => reference}/research-in-progress.md (100%) rename docs/overview/{concepts => reference}/security-features.md (100%) rename docs/overview/{concepts => reference}/waku-vs-libp2p.md (100%) diff --git a/docs/overview/concepts/transports-in-waku.md b/docs/overview/concepts/transports-in-waku.md deleted file mode 100644 index 3487b69..0000000 --- a/docs/overview/concepts/transports-in-waku.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Transports in Waku ---- - -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. - -This section describes these recommended transports: - -- Waku nodes uses TCP to communicate by default. A service node should be using TCP to listen to, and connect to other nodes. -- For browser environments, secure websocket is used. Service nodes are encouraged to setup a SSL certificate to enable incoming connections from browser and serve them. -- Other protocols such as [WebRTC](https://github.com/waku-org/js-waku/issues/20), [WebTransport](https://github.com/waku-org/js-waku/issues/697) and QUIC have been studied. diff --git a/docs/overview/concepts/transports.md b/docs/overview/concepts/transports.md new file mode 100644 index 0000000..7bc2ae1 --- /dev/null +++ b/docs/overview/concepts/transports.md @@ -0,0 +1,13 @@ +--- +title: Transports in Waku +--- + +Waku aims to be transport agnostic, providing flexibility in selecting suitable transports. However, a set of recommended transports is defined to establish a baseline of client interoperability. + +The recommended transports for Waku nodes are as follows: + +- TCP: By default, Waku nodes utilize TCP for communication. Service nodes should employ TCP for listening to and connecting with other nodes. +- Secure WebSocket: In browser environments, secure WebSocket is used. Service nodes are encouraged to set up SSL certificates to enable incoming connections from browsers and serve them securely. +- Other protocols like [WebRTC](https://github.com/waku-org/js-waku/issues/20), [WebTransport](https://github.com/waku-org/js-waku/issues/697), and QUIC have been investigated and studied for potential integration. + +Waku ensures compatibility and enhanced communication capabilities among nodes by adhering to these recommended transports. \ No newline at end of file diff --git a/docs/overview/concepts/research-in-progress.md b/docs/overview/reference/research-in-progress.md similarity index 100% rename from docs/overview/concepts/research-in-progress.md rename to docs/overview/reference/research-in-progress.md diff --git a/docs/overview/concepts/security-features.md b/docs/overview/reference/security-features.md similarity index 100% rename from docs/overview/concepts/security-features.md rename to docs/overview/reference/security-features.md diff --git a/docs/overview/concepts/waku-vs-libp2p.md b/docs/overview/reference/waku-vs-libp2p.md similarity index 100% rename from docs/overview/concepts/waku-vs-libp2p.md rename to docs/overview/reference/waku-vs-libp2p.md diff --git a/sidebars.js b/sidebars.js index 09dd9ed..2f9575f 100644 --- a/sidebars.js +++ b/sidebars.js @@ -19,13 +19,21 @@ const sidebars = { "overview/concepts/protocols", "overview/concepts/network-domains", "overview/concepts/node-discovery", - "overview/concepts/transports-in-waku", + "overview/concepts/transports", "overview/concepts/content-topics", - "overview/concepts/security-features", - "overview/concepts/research-in-progress", - "overview/concepts/waku-vs-libp2p", ], }, + { + type: "category", + label: "Reference", + collapsed: true, + collapsible: true, + items: [ + "overview/reference/security-features", + "overview/reference/research-in-progress", + "overview/reference/waku-vs-libp2p", + ], + }, ], browser: [ "browser/introduction", From 66c8a05e7bd22ea5e925f4a2c61aa2399b6ccce4 Mon Sep 17 00:00:00 2001 From: LordGhostX Date: Sun, 14 May 2023 14:23:15 +0100 Subject: [PATCH 05/13] overhaul content topics --- docs/overview/concepts/content-topics.md | 25 ++++++++++------------- docs/overview/concepts/network-domains.md | 2 +- docs/overview/concepts/transports.md | 4 +++- 3 files changed, 15 insertions(+), 16 deletions(-) diff --git a/docs/overview/concepts/content-topics.md b/docs/overview/concepts/content-topics.md index 3842139..a5d0b72 100644 --- a/docs/overview/concepts/content-topics.md +++ b/docs/overview/concepts/content-topics.md @@ -1,24 +1,21 @@ --- -title: Content Topic and How to Choose One +title: Content Topics --- -A content topic is used for content based filtering and allows you to filter out the messages that your dApp processes, -both when receiving live messages (Relay or Filter) or retrieving historical messages (Store). +Content topics optimize node bandwidth usage by filtering messages based on specific topics of interest. They enable dApps to selectively process incoming live messages (`Relay` or `Filter`) and retrieve historical messages (`Store`) that match their filtering criteria. For more information, please refer to the [23/WAKU2-TOPICS](https://rfc.vac.dev/spec/23/#content-topics) specification. -The recommended format for content topics is as follows: +## Content Topic Format -`/{dapp-name}/{version}/{content-topic-name}/{encoding}` +Here is the recommended format for content topics: -- `dapp-name`: The name of your dApp, it must be unique to avoid conflict with other dApps. -- `version`: We usually start at `1`, useful when introducing breaking changes in your messages. -- `content-topic-name`: The actual content topic name to use for filtering. - If your dApp uses Waku for several features, - you should use a content topic per feature. -- `encoding`: The encoding format of the message, [Protobuf](https://developers.google.com/protocol-buffers) is most often used: `proto`. +`/{application-name}/{version}/{content-topic-name}/{encoding}` -For example: Your dApp's name is SuperCrypto, -it enables users to receive notifications and send private messages. -You may want to use the following content topics: +- `application-name`: This is the unique name of your decentralized application (dApp) to prevent conflicts with other dApps. +- `version`: Typically starting at 1, this field helps track breaking changes in your messages. +- `content-topic-name`: The specific name of the content topic used for filtering. If your dApp utilizes Waku for multiple features, it is advisable to have a separate content topic for each feature. +- `encoding`: The message encoding format, with [Protobuf](https://developers.google.com/protocol-buffers) (`proto`) being the commonly used choice. + +For instance, if your dApp is called `SuperCrypto` and it allows users to receive notifications and send private messages, you can consider utilizing the following content topics: - `/supercrypto/1/notification/proto` - `/supercrypto/1/private-message/proto` diff --git a/docs/overview/concepts/network-domains.md b/docs/overview/concepts/network-domains.md index 7bf418c..e7dd0f9 100644 --- a/docs/overview/concepts/network-domains.md +++ b/docs/overview/concepts/network-domains.md @@ -47,7 +47,7 @@ D ->> E: HistoryResponse(msg1, ...) (6) The Publish/Subscribe topic `pubtopic1` serves as a means of routing messages (the network employs a default pub-sub topic) and indicates that it is subscribed to messages on that topic for a relay. In the context of Waku Store, Node D is responsible for persisting these messages. -1. Node A creates a WakuMessage `msg1` with a ContentTopic `contentTopic1`. +1. Node A creates a WakuMessage `msg1` with a [ContentTopic](/overview/concepts/content-topics) `contentTopic1`. 2. Node F requests to get messages filtered by Pub/Sub topic `pubtopic1` and ContentTopic `contentTopic1`. Node D subscribes F to this filter and will forward messages that match that filter in the future. 3. Node A publishes `msg1` on `pubtopic1`. The message is sent from Node A to Node B and then forwarded to Node D. 4. Node D, upon receiving `msg1`, stores the message in its store for possible later retrieval by other nodes. diff --git a/docs/overview/concepts/transports.md b/docs/overview/concepts/transports.md index 7bc2ae1..92cbdad 100644 --- a/docs/overview/concepts/transports.md +++ b/docs/overview/concepts/transports.md @@ -10,4 +10,6 @@ The recommended transports for Waku nodes are as follows: - Secure WebSocket: In browser environments, secure WebSocket is used. Service nodes are encouraged to set up SSL certificates to enable incoming connections from browsers and serve them securely. - Other protocols like [WebRTC](https://github.com/waku-org/js-waku/issues/20), [WebTransport](https://github.com/waku-org/js-waku/issues/697), and QUIC have been investigated and studied for potential integration. -Waku ensures compatibility and enhanced communication capabilities among nodes by adhering to these recommended transports. \ No newline at end of file +:::note +Waku ensures compatibility and enhanced communication capabilities among nodes by adhering to these recommended transports. +::: \ No newline at end of file From 5a22c37ca962e921bd92f92197b068fe0b854da5 Mon Sep 17 00:00:00 2001 From: LordGhostX Date: Sun, 14 May 2023 21:34:45 +0100 Subject: [PATCH 06/13] overhaul reference docs --- docs/overview/concepts/content-topics.md | 4 +- docs/overview/concepts/network-domains.md | 4 +- docs/overview/concepts/node-discovery.md | 6 +- docs/overview/concepts/protocols.md | 2 +- docs/overview/concepts/transports.md | 12 ++-- .../reference/research-in-progress.md | 24 ++++---- docs/overview/reference/security-features.md | 60 +++++++------------ docs/overview/reference/waku-vs-libp2p.md | 13 ++-- docs/overview/what-is-waku.md | 2 +- sidebars.js | 2 +- 10 files changed, 54 insertions(+), 75 deletions(-) diff --git a/docs/overview/concepts/content-topics.md b/docs/overview/concepts/content-topics.md index a5d0b72..706cab7 100644 --- a/docs/overview/concepts/content-topics.md +++ b/docs/overview/concepts/content-topics.md @@ -2,7 +2,7 @@ title: Content Topics --- -Content topics optimize node bandwidth usage by filtering messages based on specific topics of interest. They enable dApps to selectively process incoming live messages (`Relay` or `Filter`) and retrieve historical messages (`Store`) that match their filtering criteria. For more information, please refer to the [23/WAKU2-TOPICS](https://rfc.vac.dev/spec/23/#content-topics) specification. +Content topics optimize node bandwidth usage by filtering messages based on specific topics of interest. They enable dApps to selectively process incoming live messages ([Relay](/overview/concepts/protocols#waku-relay) or [Filter](/overview/concepts/protocols#waku-filter)) and retrieve historical messages ([Store](/overview/concepts/protocols#waku-store)) that match their filtering criteria. For more information, please refer to the [WAKU2-TOPICS](https://rfc.vac.dev/spec/23/#content-topics) specification. ## Content Topic Format @@ -13,7 +13,7 @@ Here is the recommended format for content topics: - `application-name`: This is the unique name of your decentralized application (dApp) to prevent conflicts with other dApps. - `version`: Typically starting at 1, this field helps track breaking changes in your messages. - `content-topic-name`: The specific name of the content topic used for filtering. If your dApp utilizes Waku for multiple features, it is advisable to have a separate content topic for each feature. -- `encoding`: The message encoding format, with [Protobuf](https://developers.google.com/protocol-buffers) (`proto`) being the commonly used choice. +- `encoding`: The message serialization/encoding format, with [Protobuf](https://protobuf.dev/) (`proto`) being the commonly used choice. For instance, if your dApp is called `SuperCrypto` and it allows users to receive notifications and send private messages, you can consider utilizing the following content topics: diff --git a/docs/overview/concepts/network-domains.md b/docs/overview/concepts/network-domains.md index e7dd0f9..8420ec1 100644 --- a/docs/overview/concepts/network-domains.md +++ b/docs/overview/concepts/network-domains.md @@ -10,7 +10,7 @@ Node discovery in Waku facilitates locating other nodes within the network. As a ## Gossip Domain -Gossipsub derives its name from the practice within pub-sub networks where peers gossip about the messages they have encountered, thus establishing a message delivery network. +Gossipsub derives its name from the practice within Pub/Sub networks where peers gossip about the messages they have encountered, thus establishing a message delivery network. Waku employs gossiping through [`WAKU-RELAY`](/overview/concepts/protocols#waku-relay) to distribute messages across the network. Additionally, Waku introduces [`WAKU-RLN-RELAY`](/overview/concepts/protocols#waku-rln-relay), an experimental mechanism that combines privacy preservation and economic spam protection. @@ -45,7 +45,7 @@ E ->> D: HistoryQuery(pubtopic1, contentTopic1) (6) D ->> E: HistoryResponse(msg1, ...) (6) ``` -The Publish/Subscribe topic `pubtopic1` serves as a means of routing messages (the network employs a default pub-sub topic) and indicates that it is subscribed to messages on that topic for a relay. In the context of Waku Store, Node D is responsible for persisting these messages. +The Pub/Sub topic `pubtopic1` serves as a means of routing messages (the network employs a default pubsub topic) and indicates that it is subscribed to messages on that topic for a relay. In the context of Waku Store, Node D is responsible for persisting these messages. 1. Node A creates a WakuMessage `msg1` with a [ContentTopic](/overview/concepts/content-topics) `contentTopic1`. 2. Node F requests to get messages filtered by Pub/Sub topic `pubtopic1` and ContentTopic `contentTopic1`. Node D subscribes F to this filter and will forward messages that match that filter in the future. diff --git a/docs/overview/concepts/node-discovery.md b/docs/overview/concepts/node-discovery.md index 9f020a2..44e4b6d 100644 --- a/docs/overview/concepts/node-discovery.md +++ b/docs/overview/concepts/node-discovery.md @@ -6,9 +6,9 @@ When initializing a Waku node, it must connect with other nodes to enable messag After establishing a connection, the node must actively seek out additional peers to have: -- Sufficient peers in the `Waku Relay` mesh: The goal is to have at least 6 peers in the mesh. This ensures a robust network where messages can be efficiently relayed. +- Sufficient peers in the [Waku Relay](/overview/concepts/protocols#waku-relay) mesh: The goal is to have at least 6 peers in the mesh. This ensures a robust network where messages can be efficiently relayed. - Reserve peers for backup: It is essential to have a surplus of peers available as reserves. These reserves are backups when the current peers become overloaded or experience unexpected disconnections. -- Peers with specific Waku capabilities: The node seeks out peers with specific Waku capabilities, such as `Store`, `Light Push`, or `Filter`. This allows for targeted interactions and enhanced functionality based on the desired capabilities. +- Peers with specific Waku capabilities: The node seeks out peers with specific Waku capabilities, such as [Store](/overview/concepts/protocols#waku-store), [Light Push](/overview/concepts/protocols#waku-light-push), or [Filter](/overview/concepts/protocols#waku-filter). This allows for targeted interactions and enhanced functionality based on the desired capabilities. ## Predefined Bootstrap Nodes @@ -58,7 +58,7 @@ This bootstrapping method allows anyone to register and publish a domain name fo ## [Peer Exchange](https://rfc.vac.dev/spec/34/) -The primary objective of this protocol is to facilitate peer connectivity for resource-restricted devices. The peer exchange protocol enables lightweight nodes to request peers from other nodes within the network. Light nodes can bootstrap and expand their mesh independently without relying on `Discv5` or bootstrap nodes. +The primary objective of this protocol is to facilitate peer connectivity for resource-restricted devices. The peer exchange protocol enables lightweight nodes to request peers from other nodes within the network. Light nodes can bootstrap and expand their mesh independently without relying on [Discv5](#discv5) or bootstrap nodes. :::info This protocol is intended for situations where the use of `Discv5` is not feasible. diff --git a/docs/overview/concepts/protocols.md b/docs/overview/concepts/protocols.md index 393e0d0..1a3cff1 100644 --- a/docs/overview/concepts/protocols.md +++ b/docs/overview/concepts/protocols.md @@ -6,7 +6,7 @@ Waku takes a modular approach, providing a range of protocols that enable applic ### [Waku Relay](https://rfc.vac.dev/spec/11/) -`WAKU2-RELAY` is a privacy-focused peer-to-peer messaging protocol that extends the `libp2p GossipSub` protocol. It utilizes a Publish/Subscribe approach to enable secure communication channels, encryption, and protection against censorship. With a strong emphasis on privacy, `Waku Relay` ensures scalability, allowing many peers and messages to coexist within the network. +`WAKU2-RELAY` is a privacy-focused peer-to-peer messaging protocol that extends the `libp2p GossipSub` protocol. It utilizes a Pub/Sub approach to enable secure communication channels, encryption, and protection against censorship. With a strong emphasis on privacy, `Waku Relay` ensures scalability, allowing many peers and messages to coexist within the network. ### [Waku Filter](https://rfc.vac.dev/spec/12/) diff --git a/docs/overview/concepts/transports.md b/docs/overview/concepts/transports.md index 92cbdad..4e6782b 100644 --- a/docs/overview/concepts/transports.md +++ b/docs/overview/concepts/transports.md @@ -2,14 +2,14 @@ title: Transports in Waku --- -Waku aims to be transport agnostic, providing flexibility in selecting suitable transports. However, a set of recommended transports is defined to establish a baseline of client interoperability. +Transports facilitate data packet movement across networks with TCP and UDP being standard protocols. However, alternatives are at lower (Ethernet, Bluetooth) and higher (QUIC) levels. Waku, aiming to be transport agnostic, enables developers to choose and support multiple protocols based on their needs. The recommended transports for Waku nodes are as follows: -- TCP: By default, Waku nodes utilize TCP for communication. Service nodes should employ TCP for listening to and connecting with other nodes. -- Secure WebSocket: In browser environments, secure WebSocket is used. Service nodes are encouraged to set up SSL certificates to enable incoming connections from browsers and serve them securely. -- Other protocols like [WebRTC](https://github.com/waku-org/js-waku/issues/20), [WebTransport](https://github.com/waku-org/js-waku/issues/697), and QUIC have been investigated and studied for potential integration. +- **TCP:** By default, Waku nodes utilize TCP for communication. Service nodes should employ TCP for listening to and connecting with other nodes. +- **Secure WebSocket:** In browser environments, secure WebSocket is used. Service nodes are encouraged to set up SSL certificates to enable incoming connections from browsers and serve them securely. +- Other protocols like [WebRTC](https://github.com/waku-org/js-waku/issues/20), [WebTransport](https://github.com/waku-org/js-waku/issues/697), and QUIC have been researched and studied for potential integration. -:::note -Waku ensures compatibility and enhanced communication capabilities among nodes by adhering to these recommended transports. +:::info +Waku ensures compatibility and improved communication capabilities by following these recommended transports. ::: \ No newline at end of file diff --git a/docs/overview/reference/research-in-progress.md b/docs/overview/reference/research-in-progress.md index 570a758..b32c26b 100644 --- a/docs/overview/reference/research-in-progress.md +++ b/docs/overview/reference/research-in-progress.md @@ -4,20 +4,18 @@ title: Research in Progress 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 `WAKU-RELAY` by using rate limiting nullifiers. -More details on this can be found in [17/WAKU2-RLN-RELAY](https://rfc.vac.dev/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. +## Economic Spam Resistance -We have prepared a PoC implementation of this method in JS: https://examples.waku.org/rln-js/ +We aim to enable an incentivized spam protection technique to enhance `WAKU-RELAY` by using rate limiting nullifiers. More details on this can be found in [WAKU2-RLN-RELAY](https://rfc.vac.dev/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. -RnD on DoS attack mitigation can tracked from here: https://github.com/vacp2p/research/issues/148 -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. +We have prepared a PoC implementation of this method in JS: -Additionally, along with RLN, this gives node operators who provide a useful service to the network an incentive to perform that service. Read more here: https://vac.dev/building-privacy-protecting-infrastructure +## Prevention of Denial of Service (DoS) and Node Incentivization -You can also read more about the current open problems the Vac/Waku team is working on here: https://vac.dev/open-problems +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. RnD on DoS attack mitigation can tracked from here: . + +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 `WAKU2-STORE` and `WAKU2-FILTER` to protect against DoS attacks. + +Additionally, along with RLN, this gives node operators who provide a useful service to the network an incentive to perform that service. Read more here: + +You can also read more about the current open problems the Vac/Waku team is working on here: diff --git a/docs/overview/reference/security-features.md b/docs/overview/reference/security-features.md index 3b2c7cc..fee252e 100644 --- a/docs/overview/reference/security-features.md +++ b/docs/overview/reference/security-features.md @@ -2,62 +2,44 @@ title: Security Features --- -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. +Each protocol layer of Waku provides a distinct service and is associated with a separate set of security features and concerns. Therefore, the overall security of Waku depends on how the different layers are utilized. -The security models are detailed in the RFC of the protocols. -We strive to provide well documented and open source RFCs so that Waku users know what security guarantees are and aren't provided by each protocol. +The security models are detailed in the RFC of the protocols. We strive to provide well documented and [open source RFCs](https://rfc.vac.dev/) so that Waku users know what security guarantees are and aren't provided by each protocol. -Some of the security features of Waku v2 are: +Some of the security features of Waku are: -### Pseudonymity +## Pseudonymity -Waku v2 by default guarantees pseudonymity for all of the protocol layers since parties do not have to disclose their true identity -and instead they utilize libp2p `PeerID` as their identifiers. -While pseudonymity is an appealing security feature, it does not guarantee full anonymity since the actions taken under the same pseudonym -i.e., `PeerID`, can be linked together and potentially result in the re-identification of the true actor. +Waku by default guarantees pseudonymity for all of the protocol layers since parties do not have to disclose their true identity +and instead they utilize libp2p `PeerID` as their identifiers. While pseudonymity is an appealing security feature, it does not guarantee full anonymity since the actions taken under the same pseudonym i.e., `PeerID`, can be linked together and potentially result in the re-identification of the true actor. -### Anonymity / Unlinkability +## Anonymity/Unlinkability -At a high level, anonymity is the inability of an adversary in linking an actor to its data/performed action (the actor and action are context-dependent). -To be precise about linkability, we use the term Personally Identifiable Information (PII) to refer to any piece of data that could potentially be used to uniquely identify a party. -For example, the signature verification key, and the hash of one's static IP address are unique for each user and hence count as PII. -Notice that users' actions can be traced through their PIIs (e.g., signatures) and hence result in their re-identification risk. -As such, we seek anonymity by avoiding linkability between actions and the actors / actors' PII. Concerning anonymity, Waku v2 provides the following features: +At a high level, anonymity is the inability of an adversary in linking an actor to its data/performed action (the actor and action are context-dependent). To be precise about linkability, we use the term Personally Identifiable Information (PII) to refer to any piece of data that could potentially be used to uniquely identify a party. + +For example, the signature verification key, and the hash of one's static IP address are unique for each user and hence count as PII. Notice that users' actions can be traced through their PIIs (e.g., signatures) and hence result in their re-identification risk. As such, we seek anonymity by avoiding linkability between actions and the actors / actors' PII. Concerning anonymity, Waku provides the following features: + +### Publisher-Message Unlinkability -**Publisher-Message Unlinkability**: This feature signifies the unlinkability of a publisher to its published messages in the `WAKU-RELAY` protocol. -**Subscriber-Topic Unlinkability**: -This feature stands for the unlinkability of the subscriber to its subscribed topics in the `WAKU-RELAY` protocol. -The [Subscriber-Topic Unlinkability](https://rfc.vac.dev/spec/11/#security-analysis) is achieved through the utilization of a single PubSub topic. -As such, subscribers are not re-identifiable from their subscribed topic IDs as the entire network is linked to the same topic ID. -This level of unlinkability / anonymity is known as [k-anonymity](https://www.privitar.com/blog/k-anonymity-an-introduction/) where k is proportional to the system size (number of subscribers). -Note that there is no hard limit on the number of the pubsub topics, however, the use of one topic is recommended for the sake of anonymity. +### Subscriber-Topic Unlinkability -### Spam protection +This feature stands for the unlinkability of the subscriber to its subscribed topics in the `WAKU-RELAY` protocol. The [Subscriber-Topic Unlinkability](https://rfc.vac.dev/spec/11/#security-analysis) is achieved through the utilization of a single PubSub topic. As such, subscribers are not re-identifiable from their subscribed topic IDs as the entire network is linked to the same topic ID. This level of unlinkability / anonymity is known as [k-anonymity](https://www.privitar.com/blog/k-anonymity-an-introduction/) where k is proportional to the system size (number of subscribers). Note that there is no hard limit on the number of the pubsub topics, however, the use of one topic is recommended for the sake of anonymity. + +## Spam Protection This property indicates that no adversary can flood the system (i.e., publishing a large number of messages in a short amount of time), either accidentally or deliberately, with any kind of message i.e. even if the message content is valid or useful. -Spam protection is partly provided in `WAKU2-RELAY` through the [scoring mechanism](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md#spam-protection-measures) provided for by GossipSub v1.1. -At a high level, peers utilize a scoring function to locally score the behavior of their connections and remove peers with a low score. -There's also further research being done in this domain, including the designing of [RLN (Rate Limiting Nullifiers)](./research-in-progress.md) +Spam protection is partly provided in `WAKU2-RELAY` through the [scoring mechanism](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md#spam-protection-measures) provided for by GossipSub v1.1. At a high level, peers utilize a scoring function to locally score the behavior of their connections and remove peers with a low score. -https://github.com/vacp2p/research/issues/148 +There's also further research being done in this domain, including the designing of [RLN (Rate Limiting Nullifiers)](https://rfc.vac.dev/spec/32/): . -### Data confidentiality, Integrity, and Authenticity +## Data Confidentiality, Integrity, and Authenticity Confidentiality can be addressed through data encryption whereas integrity and authenticity are achievable through digital signatures. -These features are provided for in [WAKU-MESSAGE (version 1)](https://rfc.vac.dev/spec/14#version-1) and [WAKU-NOISE](https://rfc.vac.dev/spec/35/) through payload encryption as well as encrypted signatures. - -:::info `WAKU-NOISE` enables secure channel negotiation over Waku. -::: +These features are provided for in [WAKU-MESSAGE (version 1)](https://rfc.vac.dev/spec/14#version-1) and [WAKU-NOISE](https://rfc.vac.dev/spec/35/) through payload encryption as well as encrypted signatures. `WAKU-NOISE` enables secure channel negotiation over Waku. ## Security Considerations -**Lack of anonymity/unlinkability in the protocols involving direct connections including [`13/WAKU2-STORE`](https://rfc.vac.dev/spec/13/) and [`12/WAKU2-FILTER`](https://rfc.vac.dev/spec/12/) protocols**: -The anonymity/unlinkability is not guaranteed in the protocols like `13/WAKU2-STORE` and `12/WAKU2-FILTER` where peers need to have direct connections to benefit from the designated service. -This is because during the direct connections peers utilize `PeerID` to identify each other, -therefore the service obtained in the protocol is linkable to the beneficiary's `PeerID` (which counts as PII). -For `13/WAKU2-STORE`, the queried node would be able to link the querying node's `PeerID` to its queried topics. -Likewise, in the `12/WAKU2-FILTER`, a full node can link the light node's `PeerID`s to its content filter. +The anonymity/unlinkability is not guaranteed in the protocols like `WAKU2-STORE` and `WAKU2-FILTER` where peers need to have direct connections to benefit from the designated service. This is because during the direct connections peers utilize `PeerID` to identify each other, therefore the service obtained in the protocol is linkable to the beneficiary's `PeerID` (which counts as PII). For `WAKU2-STORE`, the queried node would be able to link the querying node's `PeerID` to its queried topics. Likewise, in the `WAKU2-FILTER`, a full node can link the light node's `PeerID` to its content filter. \ No newline at end of file diff --git a/docs/overview/reference/waku-vs-libp2p.md b/docs/overview/reference/waku-vs-libp2p.md index 3c4c92a..f0cf36d 100644 --- a/docs/overview/reference/waku-vs-libp2p.md +++ b/docs/overview/reference/waku-vs-libp2p.md @@ -1,22 +1,21 @@ --- -title: Waku vs libp2p - what's the difference? +title: Waku vs libp2p - What's the difference? --- -Since Waku v2 is built on top of libp2p, they share a lot of concepts and terminologies between them. However, there are key differences between them that are worth noting. +Since Waku is built on top of libp2p, they share a lot of concepts and terminologies between them. However, there are key differences between them that are worth noting. -### Waku as a service network +## Waku as a Service Network -Waku offers incentivization mechanisms to run nodes, whereas libp2p does not. +Waku offers incentivization mechanisms to run nodes, whereas libp2p does not. Additionally, a user or a developer does not have to deploy own infra as a prerequisite to use Waku, it is a service network. -Additionally, a user or a developer does not have to deploy own infra as a prerequisite to use Waku, it is a service network. However, it is encouraged to [run your own node](https://github.com/status-im/nwaku/tree/master/docs/operators) to support and decentralize the network. -### Waku as a keyturn solution +## Waku as a Keyturn Solution Waku includes a number of protocol covering the following domains like privacy preservation, censorship resistance, portability/runs anywhere. libp2p does not provide out of the box protocols to enable mostly offline/resource restricted devices, [WAKU-STORE](https://rfc.vac.dev/spec/13/)/[WAKU-LIGHTPUSH](https://rfc.vac.dev/spec/19/)/[WAKU-FILTER](https://rfc.vac.dev/spec/12/) caters to those use cases. -### Economic spam protection +## Economic Spam Protection libp2p does not have strong spam protection guarantees, [RLN (Rate Limit Nullifier)](https://rfc.vac.dev/spec/32/) is a protocol being developed by the Waku team towards this goal. diff --git a/docs/overview/what-is-waku.md b/docs/overview/what-is-waku.md index 0d2aa48..bb7b7d9 100644 --- a/docs/overview/what-is-waku.md +++ b/docs/overview/what-is-waku.md @@ -47,7 +47,7 @@ These options are part of the [Anonymity Trilemma](https://eprint.iacr.org/2017/ ## How Does Waku Work? -The Waku Relay protocol is the foundation of the Waku Network, which employs a `pubsub` architecture built on the `libp2p gossipsub` protocol. In addition to this, various other Waku protocols have been created to facilitate specific functionalities, including but not limited to: +The Waku Relay protocol is the foundation of the Waku Network, which employs a Pub/Sub architecture built on the `libp2p gossipsub` protocol. In addition to this, various other Waku protocols have been created to facilitate specific functionalities, including but not limited to: 1. Facilitating the retrieval of historical messages for primarily offline devices. 2. Providing solutions for encrypted communication, such as symmetric encryption, ECIES/asymmetric encryption, and noise handshake-based key turns. diff --git a/sidebars.js b/sidebars.js index 2f9575f..f5376f0 100644 --- a/sidebars.js +++ b/sidebars.js @@ -19,8 +19,8 @@ const sidebars = { "overview/concepts/protocols", "overview/concepts/network-domains", "overview/concepts/node-discovery", - "overview/concepts/transports", "overview/concepts/content-topics", + "overview/concepts/transports", ], }, { From e24a0bdd5a331124dd092e34ed0104f27f3f1520 Mon Sep 17 00:00:00 2001 From: LordGhostX Date: Mon, 15 May 2023 12:31:30 +0100 Subject: [PATCH 07/13] update transports guide --- docs/overview/concepts/protocols.md | 2 +- docs/overview/concepts/transports.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/overview/concepts/protocols.md b/docs/overview/concepts/protocols.md index 1a3cff1..421ec22 100644 --- a/docs/overview/concepts/protocols.md +++ b/docs/overview/concepts/protocols.md @@ -22,7 +22,7 @@ Data availability is not guaranteed with `Waku Store`. [Waku Relay](#waku-relay) ### [Waku Light Push](https://rfc.vac.dev/spec/19/) -`WAKU2-LIGHTPUSH` is a [Request/Reply](/overview/concepts/network-interaction-domains#requestreply-domain) protocol for Waku's light nodes with limited bandwidth and short connection windows. It enables clients to receive a confirmation when sending messages, indicating that at least one node has received them. However, using `Waku Light Push` compromises privacy as the remote peer becomes aware of the message originator. +`WAKU2-LIGHTPUSH` is a [Request/Reply](/overview/concepts/network-domains#requestreply-domain) protocol for Waku's light nodes with limited bandwidth and short connection windows. It enables clients to receive a confirmation when sending messages, indicating that at least one node has received them. However, using `Waku Light Push` compromises privacy as the remote peer becomes aware of the message originator. :::info Please note that `Waku Light Push` confirms receipt by the remote peer but doesn't guarantee network-wide propagation. diff --git a/docs/overview/concepts/transports.md b/docs/overview/concepts/transports.md index 4e6782b..571d2b0 100644 --- a/docs/overview/concepts/transports.md +++ b/docs/overview/concepts/transports.md @@ -2,9 +2,9 @@ title: Transports in Waku --- -Transports facilitate data packet movement across networks with TCP and UDP being standard protocols. However, alternatives are at lower (Ethernet, Bluetooth) and higher (QUIC) levels. Waku, aiming to be transport agnostic, enables developers to choose and support multiple protocols based on their needs. +Transports facilitate the movement of data packets over a network as they define the rules and protocols for establishing connections between members. They provide the necessary mechanisms and protocols to ensure the efficient transmission, routing, and delivery of these packets across the network. -The recommended transports for Waku nodes are as follows: +Waku is a transport-agnostic framework that allows developers to choose and support multiple protocols according to their specific requirements. For Waku nodes, the following transports are recommended: - **TCP:** By default, Waku nodes utilize TCP for communication. Service nodes should employ TCP for listening to and connecting with other nodes. - **Secure WebSocket:** In browser environments, secure WebSocket is used. Service nodes are encouraged to set up SSL certificates to enable incoming connections from browsers and serve them securely. From 7ee00ba3454653041b902f6da7b4c83e424645d1 Mon Sep 17 00:00:00 2001 From: LordGhostX Date: Tue, 16 May 2023 16:08:52 +0100 Subject: [PATCH 08/13] update content topics intro --- docs/overview/concepts/content-topics.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/overview/concepts/content-topics.md b/docs/overview/concepts/content-topics.md index 706cab7..1c29619 100644 --- a/docs/overview/concepts/content-topics.md +++ b/docs/overview/concepts/content-topics.md @@ -2,7 +2,9 @@ title: Content Topics --- -Content topics optimize node bandwidth usage by filtering messages based on specific topics of interest. They enable dApps to selectively process incoming live messages ([Relay](/overview/concepts/protocols#waku-relay) or [Filter](/overview/concepts/protocols#waku-filter)) and retrieve historical messages ([Store](/overview/concepts/protocols#waku-store)) that match their filtering criteria. For more information, please refer to the [WAKU2-TOPICS](https://rfc.vac.dev/spec/23/#content-topics) specification. +`Content Topics` in Waku are the foundation for content addressing, similar to [Content-Addressable Storage](https://en.wikipedia.org/wiki/Content-addressable_storage). They facilitate protocol-level features like processing incoming live messages selectively ([Relay](/overview/concepts/protocols#waku-relay) or [Filter](/overview/concepts/protocols#waku-filter)) and retrieving historical messages ([Store](/overview/concepts/protocols#waku-store)) that meet specific filtering criteria. + +Unlike encrypted data, `Content Topics` are metadata strings set by developers on outgoing messages. Please refer to the [WAKU2-TOPICS](https://rfc.vac.dev/spec/23/#content-topics) specification to learn more. ## Content Topic Format From 5689db243e14bd4d4ee1df43ec97d32932489ec0 Mon Sep 17 00:00:00 2001 From: LordGhostX Date: Tue, 16 May 2023 17:04:42 +0100 Subject: [PATCH 09/13] update network-domains & node-discovery --- .cspell.json | 3 ++- docs/overview/concepts/network-domains.md | 5 +++-- docs/overview/concepts/node-discovery.md | 16 ++++++---------- 3 files changed, 11 insertions(+), 13 deletions(-) diff --git a/.cspell.json b/.cspell.json index b6f63a2..4690b49 100644 --- a/.cspell.json +++ b/.cspell.json @@ -30,7 +30,8 @@ "QUIC", "Dappnode", "gameplay", - "Smol" + "Smol", + "Datagram" ], "flagWords": [], "ignorePaths": [ diff --git a/docs/overview/concepts/network-domains.md b/docs/overview/concepts/network-domains.md index 8420ec1..6610305 100644 --- a/docs/overview/concepts/network-domains.md +++ b/docs/overview/concepts/network-domains.md @@ -31,7 +31,7 @@ participant B as B relay(pubtopic1) participant C as C relay(pubtopic1) participant D as D relay(pubtopic1), store(pubtopic1), filter participant E as E relay, store -participant F as F relay, filter +participant F as F filter A ->> A: msg1=WakuMessage(contentTopic1, data) (1) F ->> D: FilterRequest(pubtopic1, contentTopic1) (2) @@ -39,6 +39,7 @@ D ->> D: Subscribe F to filter (2) A ->> B: Publish msg1 on pubtopic1 (3) B ->> D: relay msg1 on pubtopic1 (3) D ->> D: store: saves msg1 (4) +D ->> C: relay msg1 on pubtopic1 (4) D ->> F: MessagePush(msg1) (5) E ->> E: E comes online (6) E ->> D: HistoryQuery(pubtopic1, contentTopic1) (6) @@ -50,6 +51,6 @@ The Pub/Sub topic `pubtopic1` serves as a means of routing messages (the network 1. Node A creates a WakuMessage `msg1` with a [ContentTopic](/overview/concepts/content-topics) `contentTopic1`. 2. Node F requests to get messages filtered by Pub/Sub topic `pubtopic1` and ContentTopic `contentTopic1`. Node D subscribes F to this filter and will forward messages that match that filter in the future. 3. Node A publishes `msg1` on `pubtopic1`. The message is sent from Node A to Node B and then forwarded to Node D. -4. Node D, upon receiving `msg1`, stores the message in its store for possible later retrieval by other nodes. +4. Node D, upon receiving `msg1` both stores the message for future retrieval by other nodes and forwards it to Node C. 5. Node D also pushes `msg1` to Node F, informing it about the arrival of a new message. 6. At a later time, Node E comes online and requests messages matching `pubtopic1` and `contentTopic1` from Node D. Node D responds with `msg1` and potentially other messages that match the query. \ No newline at end of file diff --git a/docs/overview/concepts/node-discovery.md b/docs/overview/concepts/node-discovery.md index 44e4b6d..d5a1e15 100644 --- a/docs/overview/concepts/node-discovery.md +++ b/docs/overview/concepts/node-discovery.md @@ -2,7 +2,7 @@ title: Node Discovery Mechanisms --- -When initializing a Waku node, it must connect with other nodes to enable message sending, receiving, and retrieval. To achieve this, a discovery mechanism is employed to locate other nodes where no connections are present. This process is known as bootstrapping. +When initializing a Waku node, it must connect with other nodes to enable message sending, receiving, and retrieval. To achieve this, a discovery mechanism is employed to locate and connect with other nodes. This process is known as bootstrapping. After establishing a connection, the node must actively seek out additional peers to have: @@ -23,7 +23,7 @@ Waku applications have the flexibility to embed bootstrap node addresses directl - Vulnerable to censorship: Node IPs can be blocked or restricted. - Limited scalability: The number of nodes is fixed and cannot easily be expanded. -- Maintenance challenges: Updating the node list requires modifying the code, which can be cumbersome and less maintainable. +- Maintenance challenges: Updating the node list requires modifying the code, which can be cumbersome and involves releasing and deploying. ## [DNS Discovery](https://rfc.vac.dev/spec/31/) @@ -40,7 +40,7 @@ This bootstrapping method allows anyone to register and publish a domain name fo #### Cons - Vulnerable to censorship: Domain names can be blocked or restricted. -- Limited scalability: The number of nodes is fixed, and operators need to provide their `ENR` to the domain owner for listing. +- Limited scalability: The listed nodes are at risk of being overwhelmed by receiving all queries. Also, operators must provide their `ENR` to the domain owner for listing. ## [Discv5](https://rfc.vac.dev/spec/33/) @@ -53,16 +53,12 @@ This bootstrapping method allows anyone to register and publish a domain name fo #### Cons -- Demands high resource allocation. -- Nodes hindered by restrictive NAT setups are unable to run this protocol. +- Requires lots of connections and involves frequent churn. +- Relies on User Datagram Protocol (UDP), which is not supported in web browsers. ## [Peer Exchange](https://rfc.vac.dev/spec/34/) -The primary objective of this protocol is to facilitate peer connectivity for resource-restricted devices. The peer exchange protocol enables lightweight nodes to request peers from other nodes within the network. Light nodes can bootstrap and expand their mesh independently without relying on [Discv5](#discv5) or bootstrap nodes. - -:::info -This protocol is intended for situations where the use of `Discv5` is not feasible. -::: +The primary objective of this protocol is to facilitate peer connectivity for resource-restricted devices. The peer exchange protocol enables lightweight nodes to request peers from other nodes within the network. Light nodes can bootstrap and expand their mesh independently without relying on [Discv5](#discv5). #### Pros From c89f424142b17f9f96c3164d2a0d2c989b5c1686 Mon Sep 17 00:00:00 2001 From: LordGhostX Date: Tue, 16 May 2023 17:52:01 +0100 Subject: [PATCH 10/13] update protocols & transports --- docs/overview/concepts/protocols.md | 4 ++-- docs/overview/concepts/transports.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/overview/concepts/protocols.md b/docs/overview/concepts/protocols.md index 421ec22..13d497b 100644 --- a/docs/overview/concepts/protocols.md +++ b/docs/overview/concepts/protocols.md @@ -2,7 +2,7 @@ title: Protocols in Waku --- -Waku takes a modular approach, providing a range of protocols that enable applications to control the trade-offs involved in the [Anonymity Trilemma](https://eprint.iacr.org/2017/954.pdf). This flexibility empowers applications to make informed choices regarding the desired balance between anonymity, scalability, and reliability. Here are the main protocols provided by Waku: +Waku takes a modular approach, providing a range of protocols that enable applications to control the trade-offs involved in the [Anonymity Trilemma](https://eprint.iacr.org/2017/954.pdf). This flexibility empowers applications to make informed choices regarding the desired balance between anonymity, scalability, and latency. Here are the main protocols provided by Waku: ### [Waku Relay](https://rfc.vac.dev/spec/11/) @@ -32,7 +32,7 @@ Please note that `Waku Light Push` confirms receipt by the remote peer but doesn ### [Waku Message](https://rfc.vac.dev/spec/14) -`WAKU2-MESSAGE` is a communication protocol that facilitates the exchange of messages between peers in the network. It includes the data payload (actual message content being transmitted) and attributes (metadata associated with the message). +`WAKU2-MESSAGE` specifies the message structure used in the Waku network. It defines metadata fields, such as content topics and timestamps, that other Waku protocols can use. ### [Waku Payload](https://rfc.vac.dev/spec/26) diff --git a/docs/overview/concepts/transports.md b/docs/overview/concepts/transports.md index 571d2b0..836e09c 100644 --- a/docs/overview/concepts/transports.md +++ b/docs/overview/concepts/transports.md @@ -2,9 +2,9 @@ title: Transports in Waku --- -Transports facilitate the movement of data packets over a network as they define the rules and protocols for establishing connections between members. They provide the necessary mechanisms and protocols to ensure the efficient transmission, routing, and delivery of these packets across the network. +Transports help move data packets across a network by establishing connections between members. They define the rules and protocols to ensure efficient network transmission, routing, and data delivery. -Waku is a transport-agnostic framework that allows developers to choose and support multiple protocols according to their specific requirements. For Waku nodes, the following transports are recommended: +Waku is a transport-agnostic framework that allows developers to choose and support multiple protocols according to their requirements. For Waku nodes, the following transports are recommended: - **TCP:** By default, Waku nodes utilize TCP for communication. Service nodes should employ TCP for listening to and connecting with other nodes. - **Secure WebSocket:** In browser environments, secure WebSocket is used. Service nodes are encouraged to set up SSL certificates to enable incoming connections from browsers and serve them securely. From 510fa3f83c61ddc812d3f6fdb2973ebab64d7039 Mon Sep 17 00:00:00 2001 From: LordGhostX Date: Tue, 16 May 2023 19:39:55 +0100 Subject: [PATCH 11/13] update libp2p comparison --- docs/overview/concepts/protocols.md | 2 +- docs/overview/reference/waku-vs-libp2p.md | 10 +++++----- docs/overview/what-is-waku.md | 1 + 3 files changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/overview/concepts/protocols.md b/docs/overview/concepts/protocols.md index 13d497b..4b77e12 100644 --- a/docs/overview/concepts/protocols.md +++ b/docs/overview/concepts/protocols.md @@ -6,7 +6,7 @@ Waku takes a modular approach, providing a range of protocols that enable applic ### [Waku Relay](https://rfc.vac.dev/spec/11/) -`WAKU2-RELAY` is a privacy-focused peer-to-peer messaging protocol that extends the `libp2p GossipSub` protocol. It utilizes a Pub/Sub approach to enable secure communication channels, encryption, and protection against censorship. With a strong emphasis on privacy, `Waku Relay` ensures scalability, allowing many peers and messages to coexist within the network. +`WAKU2-RELAY` is a privacy-focused peer-to-peer messaging protocol that extends the [libp2p GossipSub protocol](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/README.md). It utilizes a Pub/Sub approach to enable secure communication channels, encryption, and protection against censorship. With a strong emphasis on privacy, `Waku Relay` ensures scalability, allowing many peers and messages to coexist within the network. ### [Waku Filter](https://rfc.vac.dev/spec/12/) diff --git a/docs/overview/reference/waku-vs-libp2p.md b/docs/overview/reference/waku-vs-libp2p.md index f0cf36d..44082b7 100644 --- a/docs/overview/reference/waku-vs-libp2p.md +++ b/docs/overview/reference/waku-vs-libp2p.md @@ -6,16 +6,16 @@ Since Waku is built on top of libp2p, they share a lot of concepts and terminolo ## Waku as a Service Network -Waku offers incentivization mechanisms to run nodes, whereas libp2p does not. Additionally, a user or a developer does not have to deploy own infra as a prerequisite to use Waku, it is a service network. +Waku intends to incentivize mechanisms to run nodes, but it's not part of libp2p's scope. Additionally, users or developers do not have to deploy their infra as a prerequisite to use Waku. It is a service network. -However, it is encouraged to [run your own node](https://github.com/status-im/nwaku/tree/master/docs/operators) to support and decentralize the network. +However, you are encouraged to [run your node](https://github.com/waku-org/nwaku/tree/master/docs/operators) to support and decentralize the network. ## Waku as a Keyturn Solution -Waku includes a number of protocol covering the following domains like privacy preservation, censorship resistance, portability/runs anywhere. +Waku includes various protocols covering the following domains: privacy preservation, censorship resistance, and platform agnosticism, allowing it to run on any platform or environment. -libp2p does not provide out of the box protocols to enable mostly offline/resource restricted devices, [WAKU-STORE](https://rfc.vac.dev/spec/13/)/[WAKU-LIGHTPUSH](https://rfc.vac.dev/spec/19/)/[WAKU-FILTER](https://rfc.vac.dev/spec/12/) caters to those use cases. +libp2p does not provide out-of-the-box protocols to enable mostly offline/resource-restricted devices, [WAKU-STORE](/overview/concepts/protocols#waku-store)/[WAKU-LIGHTPUSH](/overview/concepts/protocols#waku-light-push)/[WAKU-FILTER](/overview/concepts/protocols#waku-filter) caters to those use cases. ## Economic Spam Protection -libp2p does not have strong spam protection guarantees, [RLN (Rate Limit Nullifier)](https://rfc.vac.dev/spec/32/) is a protocol being developed by the Waku team towards this goal. +libp2p does not have strong spam protection guarantees, [RLN (Rate Limit Nullifier)](/overview/concepts/protocols#waku-rln-relay) is a protocol being developed by the Waku team towards this goal. diff --git a/docs/overview/what-is-waku.md b/docs/overview/what-is-waku.md index bb7b7d9..2109f09 100644 --- a/docs/overview/what-is-waku.md +++ b/docs/overview/what-is-waku.md @@ -54,5 +54,6 @@ The Waku Relay protocol is the foundation of the Waku Network, which employs a P 3. Preserve bandwidth usage for resource-limited environments. 4. Implementing economic spam protection (rate limits) while ensuring privacy. 5. Developing methods to protect against mass deanonymization (currently being researched). +6. Designing strategies to scale [Waku Relay/GossipSub](/overview/concepts/protocols#waku-relay) securely. If you want to learn more about how Waku operates, the [10/WAKU2](https://rfc.vac.dev/spec/10/) RFC provides an in-depth look under the hood. From 5b9779dfbe1dab14c27d4c12c8c64e6f1be6035c Mon Sep 17 00:00:00 2001 From: LordGhostX Date: Tue, 16 May 2023 22:45:00 +0100 Subject: [PATCH 12/13] update security features --- docs/overview/reference/security-features.md | 43 +++++++------------- 1 file changed, 15 insertions(+), 28 deletions(-) diff --git a/docs/overview/reference/security-features.md b/docs/overview/reference/security-features.md index fee252e..c03ac5b 100644 --- a/docs/overview/reference/security-features.md +++ b/docs/overview/reference/security-features.md @@ -2,44 +2,31 @@ title: Security Features --- -Each protocol layer of Waku provides a distinct service and is associated with a separate set of security features and concerns. Therefore, the overall security of Waku depends on how the different layers are utilized. +Waku's protocol layers offer different services and security considerations, shaping the overall security of Waku. We document the security models in the [RFCs of the protocols](https://rfc.vac.dev/), aiming to provide transparent and open-source references. This empowers Waku users to understand each protocol's security guarantees and limitations. -The security models are detailed in the RFC of the protocols. We strive to provide well documented and [open source RFCs](https://rfc.vac.dev/) so that Waku users know what security guarantees are and aren't provided by each protocol. +Some of the Waku's security features include the following: -Some of the security features of Waku are: +## [Pseudonymity](https://rfc.vac.dev/spec/10/#pseudonymity) -## Pseudonymity +Waku ensures pseudonymity across its protocol layers, using libp2p `PeerID` as identifiers instead of disclosing true identities. However, it's important to note that pseudonymity doesn't provide complete anonymity. Actions performed under the same pseudonym (`PeerID`) can be linked, leading to the potential re-identification of the actual actor. -Waku by default guarantees pseudonymity for all of the protocol layers since parties do not have to disclose their true identity -and instead they utilize libp2p `PeerID` as their identifiers. While pseudonymity is an appealing security feature, it does not guarantee full anonymity since the actions taken under the same pseudonym i.e., `PeerID`, can be linked together and potentially result in the re-identification of the true actor. +## [Anonymity/Unlinkability](https://rfc.vac.dev/spec/10/#anonymity--unlinkability) -## Anonymity/Unlinkability +Anonymity means an adversary cannot connect an actor to their actions or data. To achieve anonymity, avoiding linking activities with actors or their Personally Identifiable Information (PII) is crucial. In Waku, the following anonymity features are provided: -At a high level, anonymity is the inability of an adversary in linking an actor to its data/performed action (the actor and action are context-dependent). To be precise about linkability, we use the term Personally Identifiable Information (PII) to refer to any piece of data that could potentially be used to uniquely identify a party. +- [Publisher-Message Unlinkability](https://rfc.vac.dev/spec/11/#security-analysis): Ensures that the publisher of messages in the `Waku Relay` protocol cannot be linked to their published messages. +- [Subscriber-Topic Unlinkability](https://rfc.vac.dev/spec/11/#security-analysis): Ensures that the subscriber of topics in the `Waku Relay` protocol cannot be linked to the topics they have subscribed to. -For example, the signature verification key, and the hash of one's static IP address are unique for each user and hence count as PII. Notice that users' actions can be traced through their PIIs (e.g., signatures) and hence result in their re-identification risk. As such, we seek anonymity by avoiding linkability between actions and the actors / actors' PII. Concerning anonymity, Waku provides the following features: +## [Spam Protection](https://rfc.vac.dev/spec/10/#spam-protection) -### Publisher-Message Unlinkability +The spam protection feature in `WAKU RELAY` ensures that no adversary can flood the system with many messages, intentionally or not, regardless of the content's validity or usefulness. This protection is achieved through the [scoring mechanism](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md#spam-protection-measures) of `GossipSub v1.1`. Peers assign scores to their connections based on their behavior and remove peers with low scores. -This feature signifies the unlinkability of a publisher to its published messages in the `WAKU-RELAY` protocol. +Ongoing research is being conducted, including developing [Rate Limiting Nullifiers (RLN)](overview/concepts/protocols#waku-rln-relay), which can be explored further at: . -### Subscriber-Topic Unlinkability +## [Data Confidentiality, Integrity, and Authenticity](https://rfc.vac.dev/spec/10/#data-confidentiality-integrity-and-authenticity) -This feature stands for the unlinkability of the subscriber to its subscribed topics in the `WAKU-RELAY` protocol. The [Subscriber-Topic Unlinkability](https://rfc.vac.dev/spec/11/#security-analysis) is achieved through the utilization of a single PubSub topic. As such, subscribers are not re-identifiable from their subscribed topic IDs as the entire network is linked to the same topic ID. This level of unlinkability / anonymity is known as [k-anonymity](https://www.privitar.com/blog/k-anonymity-an-introduction/) where k is proportional to the system size (number of subscribers). Note that there is no hard limit on the number of the pubsub topics, however, the use of one topic is recommended for the sake of anonymity. +Confidentiality in Waku is ensured through data encryption, while integrity and authenticity are achieved through digital signatures. These security measures are available in [Waku Message (version 1)](https://rfc.vac.dev/spec/14#version-1)) and [Waku Noise](https://rfc.vac.dev/spec/35/) protocols, which offer payload encryption and encrypted signatures. [Waku Noise](https://rfc.vac.dev/spec/35/) also facilitates secure channel negotiation within the Waku network. -## Spam Protection +## [Security Considerations](https://rfc.vac.dev/spec/10/#security-considerations) -This property indicates that no adversary can flood the system (i.e., publishing a large number of messages in a short amount of time), either accidentally or deliberately, with any kind of message i.e. even if the message content is valid or useful. - -Spam protection is partly provided in `WAKU2-RELAY` through the [scoring mechanism](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md#spam-protection-measures) provided for by GossipSub v1.1. At a high level, peers utilize a scoring function to locally score the behavior of their connections and remove peers with a low score. - -There's also further research being done in this domain, including the designing of [RLN (Rate Limiting Nullifiers)](https://rfc.vac.dev/spec/32/): . - -## Data Confidentiality, Integrity, and Authenticity - -Confidentiality can be addressed through data encryption whereas integrity and authenticity are achievable through digital signatures. -These features are provided for in [WAKU-MESSAGE (version 1)](https://rfc.vac.dev/spec/14#version-1) and [WAKU-NOISE](https://rfc.vac.dev/spec/35/) through payload encryption as well as encrypted signatures. `WAKU-NOISE` enables secure channel negotiation over Waku. - -## Security Considerations - -The anonymity/unlinkability is not guaranteed in the protocols like `WAKU2-STORE` and `WAKU2-FILTER` where peers need to have direct connections to benefit from the designated service. This is because during the direct connections peers utilize `PeerID` to identify each other, therefore the service obtained in the protocol is linkable to the beneficiary's `PeerID` (which counts as PII). For `WAKU2-STORE`, the queried node would be able to link the querying node's `PeerID` to its queried topics. Likewise, in the `WAKU2-FILTER`, a full node can link the light node's `PeerID` to its content filter. \ No newline at end of file +In protocols like `Waku Store` and `Waku Filter`, where direct connections are required for the designated service, anonymity or unlinkability is not guaranteed. This is because peers use their `PeerID` to identify each other during direct connections, making the service obtained in these protocols linkable to the beneficiary's `PeerID`, considered Personally Identifiable Information (PII). In `Waku Store`, the queried node can link the querying node's `PeerID` to the topics being queried. Similarly, in `Waku Filter`, a full node can link the `PeerID` of a light node to its content filter. \ No newline at end of file From 1221d2dffea2ce33cc48b950068713ca757ff4fb Mon Sep 17 00:00:00 2001 From: LordGhostX Date: Wed, 17 May 2023 12:37:21 +0100 Subject: [PATCH 13/13] update content topics intro --- docs/overview/concepts/content-topics.md | 4 +--- docs/overview/concepts/network-domains.md | 4 ++-- docs/overview/concepts/protocols.md | 14 +++++++------- docs/overview/reference/research-in-progress.md | 4 ++-- docs/overview/reference/security-features.md | 2 +- docs/overview/reference/waku-vs-libp2p.md | 4 ++-- docs/overview/what-is-waku.md | 2 +- 7 files changed, 16 insertions(+), 18 deletions(-) diff --git a/docs/overview/concepts/content-topics.md b/docs/overview/concepts/content-topics.md index 1c29619..a7a69a1 100644 --- a/docs/overview/concepts/content-topics.md +++ b/docs/overview/concepts/content-topics.md @@ -2,9 +2,7 @@ title: Content Topics --- -`Content Topics` in Waku are the foundation for content addressing, similar to [Content-Addressable Storage](https://en.wikipedia.org/wiki/Content-addressable_storage). They facilitate protocol-level features like processing incoming live messages selectively ([Relay](/overview/concepts/protocols#waku-relay) or [Filter](/overview/concepts/protocols#waku-filter)) and retrieving historical messages ([Store](/overview/concepts/protocols#waku-store)) that meet specific filtering criteria. - -Unlike encrypted data, `Content Topics` are metadata strings set by developers on outgoing messages. Please refer to the [WAKU2-TOPICS](https://rfc.vac.dev/spec/23/#content-topics) specification to learn more. +`Content Topics` are metadata strings set by developers on outgoing messages to facilitate protocol-level features like selectively processing incoming messages ([Relay](/overview/concepts/protocols#waku-relay) or [Filter](/overview/concepts/protocols#waku-filter)) and retrieving historical messages ([Store](/overview/concepts/protocols#waku-store)) that meet specific filtering criteria. Please refer to the [WAKU2-TOPICS](https://rfc.vac.dev/spec/23/#content-topics) specification to learn more. ## Content Topic Format diff --git a/docs/overview/concepts/network-domains.md b/docs/overview/concepts/network-domains.md index 6610305..eef3c86 100644 --- a/docs/overview/concepts/network-domains.md +++ b/docs/overview/concepts/network-domains.md @@ -12,13 +12,13 @@ Node discovery in Waku facilitates locating other nodes within the network. As a Gossipsub derives its name from the practice within Pub/Sub networks where peers gossip about the messages they have encountered, thus establishing a message delivery network. -Waku employs gossiping through [`WAKU-RELAY`](/overview/concepts/protocols#waku-relay) to distribute messages across the network. Additionally, Waku introduces [`WAKU-RLN-RELAY`](/overview/concepts/protocols#waku-rln-relay), an experimental mechanism that combines privacy preservation and economic spam protection. +Waku employs gossiping through [`Waku Relay`](/overview/concepts/protocols#waku-relay) to distribute messages across the network. Additionally, Waku introduces [`Waku RLN Relay`](/overview/concepts/protocols#waku-rln-relay), an experimental mechanism that combines privacy preservation and economic spam protection. ## Request/Reply Domain Waku provides a set of Request/Reply protocols to optimize its performance in resource-restricted environments like low bandwidth or offline scenarios. -These protocols serve multiple purposes. [`WAKU-STORE`](/overview/concepts/protocols#waku-store) enables the retrieval of historical messages, [`WAKU-FILTER`](/overview/concepts/protocols#waku-filter) efficiently retrieves a subset of messages to conserve bandwidth, and [`WAKU-LIGHTPUSH`](/overview/concepts/protocols#waku-light-push) facilitates message publication for nodes with limited bandwidth and short connection windows. +These protocols serve multiple purposes. [`Waku Store`](/overview/concepts/protocols#waku-store) enables the retrieval of historical messages, [`Waku Filter`](/overview/concepts/protocols#waku-filter) efficiently retrieves a subset of messages to conserve bandwidth, and [`Waku Light Push`](/overview/concepts/protocols#waku-light-push) facilitates message publication for nodes with limited bandwidth and short connection windows. ## Overview of Protocol Interaction diff --git a/docs/overview/concepts/protocols.md b/docs/overview/concepts/protocols.md index 4b77e12..8d35147 100644 --- a/docs/overview/concepts/protocols.md +++ b/docs/overview/concepts/protocols.md @@ -6,15 +6,15 @@ Waku takes a modular approach, providing a range of protocols that enable applic ### [Waku Relay](https://rfc.vac.dev/spec/11/) -`WAKU2-RELAY` is a privacy-focused peer-to-peer messaging protocol that extends the [libp2p GossipSub protocol](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/README.md). It utilizes a Pub/Sub approach to enable secure communication channels, encryption, and protection against censorship. With a strong emphasis on privacy, `Waku Relay` ensures scalability, allowing many peers and messages to coexist within the network. +`Waku Relay` is a privacy-focused peer-to-peer messaging protocol that extends the [libp2p GossipSub protocol](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/README.md). It utilizes a Pub/Sub approach to enable secure communication channels, encryption, and protection against censorship. With a strong emphasis on privacy, `Waku Relay` ensures scalability, allowing many peers and messages to coexist within the network. ### [Waku Filter](https://rfc.vac.dev/spec/12/) -`WAKU2-FILTER` is a protocol enabling peers to subscribe to specific messages from other peers. It is designed for devices with limited bandwidth, serving as a lighter alternative to [Waku Relay](#waku-relay). Unlike relay nodes, `Waku Filter` allows light nodes to subscribe to service nodes and receive only the messages they are interested in. This optimizes bandwidth consumption but may involve privacy compromises. Nonetheless, `Waku Filter` efficiently delivers desired messages within bandwidth constraints. +`Waku Filter` is a protocol enabling peers to subscribe to specific messages from other peers. It is designed for devices with limited bandwidth, serving as a lighter alternative to [Waku Relay](#waku-relay). Unlike relay nodes, `Waku Filter` allows light nodes to subscribe to service nodes and receive only the messages they are interested in. This optimizes bandwidth consumption but may involve privacy compromises. Nonetheless, `Waku Filter` efficiently delivers desired messages within bandwidth constraints. ### [Waku Store](https://rfc.vac.dev/spec/13/) -`WAKU2-STORE` is a protocol that allows the querying of messages received through the relay protocol and stored by nodes. It supports retrieving historical messages with pagination. Unlike [Waku Relay](#waku-relay), which doesn't save messages for offline users, `Waku Store` peers retain relayed messages for later retrieval. +`Waku Store` is a protocol that allows the querying of messages received through the relay protocol and stored by nodes. It supports retrieving historical messages with pagination. Unlike [Waku Relay](#waku-relay), which doesn't save messages for offline users, `Waku Store` peers retain relayed messages for later retrieval. :::info Data availability is not guaranteed with `Waku Store`. [Waku Relay](#waku-relay) or [Waku Filter](#waku-filter) are preferred for online usage, while `Waku Store` is suitable for retrieving messages after reconnecting to the network, like when a dApp starts. @@ -22,7 +22,7 @@ Data availability is not guaranteed with `Waku Store`. [Waku Relay](#waku-relay) ### [Waku Light Push](https://rfc.vac.dev/spec/19/) -`WAKU2-LIGHTPUSH` is a [Request/Reply](/overview/concepts/network-domains#requestreply-domain) protocol for Waku's light nodes with limited bandwidth and short connection windows. It enables clients to receive a confirmation when sending messages, indicating that at least one node has received them. However, using `Waku Light Push` compromises privacy as the remote peer becomes aware of the message originator. +`Waku Light Push` is a [Request/Reply](/overview/concepts/network-domains#requestreply-domain) protocol for Waku's light nodes with limited bandwidth and short connection windows. It enables clients to receive a confirmation when sending messages, indicating that at least one node has received them. However, using `Waku Light Push` compromises privacy as the remote peer becomes aware of the message originator. :::info Please note that `Waku Light Push` confirms receipt by the remote peer but doesn't guarantee network-wide propagation. @@ -32,12 +32,12 @@ Please note that `Waku Light Push` confirms receipt by the remote peer but doesn ### [Waku Message](https://rfc.vac.dev/spec/14) -`WAKU2-MESSAGE` specifies the message structure used in the Waku network. It defines metadata fields, such as content topics and timestamps, that other Waku protocols can use. +`Waku Message` specifies the message structure used in the Waku network. It defines metadata fields, such as content topics and timestamps, that other Waku protocols can use. ### [Waku Payload](https://rfc.vac.dev/spec/26) -`WAKU2-PAYLOAD` provides guidelines for implementing secure and private communication in the Waku network. It covers encryption, decryption, and signing methods for message payloads, focusing on confidentiality, authenticity, integrity, and unlinkability. +`Waku Payload` provides guidelines for implementing secure and private communication in the Waku network. It covers encryption, decryption, and signing methods for message payloads, focusing on confidentiality, authenticity, integrity, and unlinkability. ### [Waku RLN Relay](https://rfc.vac.dev/spec/17/) -The `WAKU2-RLN-RELAY` protocol extends the [Waku Relay](#waku-relay) protocol by adding spam protection using [Rate Limiting Nullifiers (RLN)](https://rfc.vac.dev/spec/32/). It enforces a global messaging rate for all peers to prevent spam in the Waku network. Spammers face financial penalties and removal from the system. This protocol provides efficient and economic spam prevention suitable for resource-constrained environments. \ No newline at end of file +The `Waku RLN Relay` protocol extends the [Waku Relay](#waku-relay) protocol by adding spam protection using [Rate Limiting Nullifiers (RLN)](https://rfc.vac.dev/spec/32/). It enforces a global messaging rate for all peers to prevent spam in the Waku network. Spammers face financial penalties and removal from the system. This protocol provides efficient and economic spam prevention suitable for resource-constrained environments. \ No newline at end of file diff --git a/docs/overview/reference/research-in-progress.md b/docs/overview/reference/research-in-progress.md index b32c26b..46a26fb 100644 --- a/docs/overview/reference/research-in-progress.md +++ b/docs/overview/reference/research-in-progress.md @@ -6,7 +6,7 @@ The following features are currently experimental and under research and initial ## Economic Spam Resistance -We aim to enable an incentivized spam protection technique to enhance `WAKU-RELAY` by using rate limiting nullifiers. More details on this can be found in [WAKU2-RLN-RELAY](https://rfc.vac.dev/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. +We aim to enable an incentivized spam protection technique to enhance `Waku Relay` by using rate limiting nullifiers. More details on this can be found in [WAKU2-RLN-RELAY](https://rfc.vac.dev/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. We have prepared a PoC implementation of this method in JS: @@ -14,7 +14,7 @@ We have prepared a PoC implementation of this method in JS: . -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 `WAKU2-STORE` and `WAKU2-FILTER` to protect against DoS attacks. +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 `Waku Store` and `Waku Filter` to protect against DoS attacks. Additionally, along with RLN, this gives node operators who provide a useful service to the network an incentive to perform that service. Read more here: diff --git a/docs/overview/reference/security-features.md b/docs/overview/reference/security-features.md index c03ac5b..f58737e 100644 --- a/docs/overview/reference/security-features.md +++ b/docs/overview/reference/security-features.md @@ -19,7 +19,7 @@ Anonymity means an adversary cannot connect an actor to their actions or data. T ## [Spam Protection](https://rfc.vac.dev/spec/10/#spam-protection) -The spam protection feature in `WAKU RELAY` ensures that no adversary can flood the system with many messages, intentionally or not, regardless of the content's validity or usefulness. This protection is achieved through the [scoring mechanism](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md#spam-protection-measures) of `GossipSub v1.1`. Peers assign scores to their connections based on their behavior and remove peers with low scores. +The spam protection feature in `Waku Relay` ensures that no adversary can flood the system with many messages, intentionally or not, regardless of the content's validity or usefulness. This protection is achieved through the [scoring mechanism](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md#spam-protection-measures) of `GossipSub v1.1`. Peers assign scores to their connections based on their behavior and remove peers with low scores. Ongoing research is being conducted, including developing [Rate Limiting Nullifiers (RLN)](overview/concepts/protocols#waku-rln-relay), which can be explored further at: . diff --git a/docs/overview/reference/waku-vs-libp2p.md b/docs/overview/reference/waku-vs-libp2p.md index 44082b7..e993f5f 100644 --- a/docs/overview/reference/waku-vs-libp2p.md +++ b/docs/overview/reference/waku-vs-libp2p.md @@ -1,5 +1,5 @@ --- -title: Waku vs libp2p - What's the difference? +title: Waku vs. libp2p - What's the Difference? --- Since Waku is built on top of libp2p, they share a lot of concepts and terminologies between them. However, there are key differences between them that are worth noting. @@ -14,7 +14,7 @@ However, you are encouraged to [run your node](https://github.com/waku-org/nwaku Waku includes various protocols covering the following domains: privacy preservation, censorship resistance, and platform agnosticism, allowing it to run on any platform or environment. -libp2p does not provide out-of-the-box protocols to enable mostly offline/resource-restricted devices, [WAKU-STORE](/overview/concepts/protocols#waku-store)/[WAKU-LIGHTPUSH](/overview/concepts/protocols#waku-light-push)/[WAKU-FILTER](/overview/concepts/protocols#waku-filter) caters to those use cases. +libp2p does not provide out-of-the-box protocols to enable mostly offline/resource-restricted devices, [Waku Store](/overview/concepts/protocols#waku-store)/[Waku Light Push](/overview/concepts/protocols#waku-light-push)/[Waku Filter](/overview/concepts/protocols#waku-filter) caters to those use cases. ## Economic Spam Protection diff --git a/docs/overview/what-is-waku.md b/docs/overview/what-is-waku.md index 2109f09..39f07a3 100644 --- a/docs/overview/what-is-waku.md +++ b/docs/overview/what-is-waku.md @@ -56,4 +56,4 @@ The Waku Relay protocol is the foundation of the Waku Network, which employs a P 5. Developing methods to protect against mass deanonymization (currently being researched). 6. Designing strategies to scale [Waku Relay/GossipSub](/overview/concepts/protocols#waku-relay) securely. -If you want to learn more about how Waku operates, the [10/WAKU2](https://rfc.vac.dev/spec/10/) RFC provides an in-depth look under the hood. +If you want to learn more about how Waku operates, the [WAKU2 RFC](https://rfc.vac.dev/spec/10/) provides an in-depth look under the hood.