From be15ee09509d3a40bf557f3ec3fcbaa1583fd27a Mon Sep 17 00:00:00 2001 From: LordGhostX Date: Thu, 25 May 2023 17:48:57 +0100 Subject: [PATCH] add glosary outline --- README.md | 6 +++--- docs/overview/concepts/content-topics.md | 4 ++-- docs/overview/concepts/network-domains.md | 10 ++++++---- docs/overview/concepts/peer-discovery.md | 2 +- docs/overview/concepts/protocols.md | 2 +- docs/overview/index.md | 2 +- docs/overview/reference/glossary.md | 7 +++++++ docs/overview/reference/research-in-progress.md | 2 +- docs/overview/reference/security-features.md | 4 ++-- docs/overview/reference/waku-vs-libp2p.md | 4 ++-- docs/overview/why-waku.md | 2 +- docs/powered-by-waku.mdx | 8 ++++---- docusaurus.config.js | 2 +- sidebars.js | 1 + src/components/PoweredByCard.js | 6 +++--- 15 files changed, 36 insertions(+), 26 deletions(-) create mode 100644 docs/overview/reference/glossary.md diff --git a/README.md b/README.md index a420d2c..9fce9d7 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ -# Waku Documentation Portal +# Waku Docs Portal -[![Waku Documentation Portal](https://img.shields.io/badge/waku.guide-black)](https://waku.guide/) +[![Waku Docs Portal](https://img.shields.io/badge/waku.guide-black)](https://waku.guide/) -The Waku Documentation Portal can be accessed at [waku.guide](https://waku.guide) and was built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator. +The Waku Docs Portal can be accessed at [waku.guide](https://waku.guide) and was built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator. ## Prerequisites diff --git a/docs/overview/concepts/content-topics.md b/docs/overview/concepts/content-topics.md index f44856a..2bb1c01 100644 --- a/docs/overview/concepts/content-topics.md +++ b/docs/overview/concepts/content-topics.md @@ -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 serialization/encoding format, with [Protobuf](https://protobuf.dev/) (`proto`) being the commonly used choice. +- `encoding`: The message serialization/encoding format, with [Protocol Buffers](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: @@ -21,5 +21,5 @@ For instance, if your dApp is called `SuperCrypto` and it allows users to receiv - `/supercrypto/1/private-message/proto` :::info -While you can choose any encoding format for your `Content Topic`, we highly recommend using [Protobuf](https://protobuf.dev/) (`proto`) because of its efficiency. Choosing a lightweight format ensures optimal performance of your dApp. +While you can choose any encoding format for your `Content Topic`, we highly recommend using [Protocol Buffers](https://protobuf.dev/) (`proto`) because of its efficiency. Choosing a lightweight format ensures optimal performance of your dApp. ::: \ No newline at end of file diff --git a/docs/overview/concepts/network-domains.md b/docs/overview/concepts/network-domains.md index c375c1a..c7ff59e 100644 --- a/docs/overview/concepts/network-domains.md +++ b/docs/overview/concepts/network-domains.md @@ -6,19 +6,21 @@ Waku is a unified and cohesive entity that offers a rich ecosystem with three di ## Discovery Domain -Peer discovery in Waku facilitates locating other peers within the network. As a modular protocol, Waku incorporates various discovery mechanisms, such as [`Discv5`](/overview/concepts/peer-discovery#discv5) and [`Peer Exchange`](/overview/concepts/peer-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. +Peer discovery in Waku facilitates locating other peers within the network. As a modular protocol, Waku incorporates various discovery mechanisms, such as [Discv5](/overview/concepts/peer-discovery#discv5) and [Peer Exchange](/overview/concepts/peer-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 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 [`Relay`](/overview/concepts/protocols#relay) to distribute messages across the network. Additionally, Waku introduces [`RLN Relay`](/overview/concepts/protocols#rln-relay), an experimental mechanism that combines privacy preservation and economic spam protection. +Waku employs gossiping through [Relay](/overview/concepts/protocols#relay) to distribute messages across the network. Additionally, Waku introduces [RLN Relay](/overview/concepts/protocols#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. +Waku provides a set of protocols to optimize its performance in resource-limited environments like low bandwidth or offline scenarios for multiple purposes. -These protocols serve multiple purposes. [`Store`](/overview/concepts/protocols#store) enables the retrieval of historical messages, [`Filter`](/overview/concepts/protocols#filter) efficiently retrieves a subset of messages to conserve bandwidth, and [`Light Push`](/overview/concepts/protocols#light-push) facilitates message publication for nodes with limited bandwidth and short connection windows. +- [Store](/overview/concepts/protocols#store) enables the retrieval of historical messages. +- [Filter](/overview/concepts/protocols#filter) efficiently retrieves a subset of messages to conserve bandwidth. +- [Light Push](/overview/concepts/protocols#light-push) facilitates message publication for nodes with limited bandwidth and short connection windows. ## Overview of Protocol Interaction diff --git a/docs/overview/concepts/peer-discovery.md b/docs/overview/concepts/peer-discovery.md index b110065..83f4321 100644 --- a/docs/overview/concepts/peer-discovery.md +++ b/docs/overview/concepts/peer-discovery.md @@ -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`. +The primary objective of this protocol is to facilitate peer connectivity for resource-limited 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`. #### Pros diff --git a/docs/overview/concepts/protocols.md b/docs/overview/concepts/protocols.md index 616fd28..a887b1f 100644 --- a/docs/overview/concepts/protocols.md +++ b/docs/overview/concepts/protocols.md @@ -10,7 +10,7 @@ Waku takes a modular approach, providing a range of protocols that enable applic ## [RLN Relay](https://rfc.vac.dev/spec/17/) -`RLN Relay` protocol extends the `Relay` protocol by using [Rate Limiting Nullifiers (RLN)](https://rfc.vac.dev/spec/32/) to provide efficient and economic spam prevention. It caps the bandwidth usage for all peers on the network, effectively preventing spam, and imposes financial penalties and network removal for spammers. You can find more details [in this blog post](https://vac.dev/rln-relay). +`RLN Relay` protocol extends the `Relay` protocol by using [Rate Limit Nullifiers (RLN)](https://rfc.vac.dev/spec/32/) to provide efficient and economic spam prevention. It caps the bandwidth usage for all peers on the network, effectively preventing spam, and imposes financial penalties and network removal for spammers. You can find more details [in this blog post](https://vac.dev/rln-relay). ## [Filter](https://rfc.vac.dev/spec/12/) diff --git a/docs/overview/index.md b/docs/overview/index.md index cfe34a3..216a243 100644 --- a/docs/overview/index.md +++ b/docs/overview/index.md @@ -29,7 +29,7 @@ Waku is suitable for applications that require a peer-to-peer approach, offering ### Platform Agnostic -Waku can run on any platform or environment, even in restricted settings with limited resources like bandwidth, CPU, memory, disk, battery, etc. It can also function when the nodes are not publicly connected or are primarily offline. +Waku can run on any platform or environment, even settings with limited resources like bandwidth, CPU, memory, disk, battery, etc. It can also function when the nodes are not publicly connected or are primarily offline. ### Privacy-Preserving diff --git a/docs/overview/reference/glossary.md b/docs/overview/reference/glossary.md new file mode 100644 index 0000000..3bd3fac --- /dev/null +++ b/docs/overview/reference/glossary.md @@ -0,0 +1,7 @@ +--- +title: Glossary +--- + +# Waku Docs Glossary + +Definitions and usage of the terminology used in the Waku ecosystem. \ 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 af988a3..712a21d 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 `Relay` by using [Rate Limiting Nullifiers (RLN)](https://rfc.vac.dev/spec/32/). In this advanced method, peers are limited to a certain messaging rate per epoch, and an immediate financial penalty is enforced for spammers who break this rate. You can find more details [in this blog post](https://vac.dev/rln-relay). +We aim to enable an incentivized spam protection technique to enhance `Relay` by using [Rate Limit Nullifiers (RLN)](https://rfc.vac.dev/spec/32/). In this advanced method, peers are limited to a certain messaging rate per epoch, and an immediate financial penalty is enforced for spammers who break this rate. You can find more details [in this blog post](https://vac.dev/rln-relay). We have prepared a PoC implementation of this method in JS: diff --git a/docs/overview/reference/security-features.md b/docs/overview/reference/security-features.md index bd36628..d899144 100644 --- a/docs/overview/reference/security-features.md +++ b/docs/overview/reference/security-features.md @@ -21,11 +21,11 @@ Anonymity means an adversary cannot connect an actor to their actions or data. T The spam protection feature in `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#rln-relay), which can be explored further at: . +Ongoing research is being conducted, including developing [Rate Limit Nullifiers (RLN)](/overview/concepts/protocols#rln-relay), which can be explored further at: . ## [Data Confidentiality, Integrity, and Authenticity](https://rfc.vac.dev/spec/10/#data-confidentiality-integrity-and-authenticity) -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. +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 [Noise](https://rfc.vac.dev/spec/35/) protocols, which offer payload encryption and encrypted signatures. [Noise](https://rfc.vac.dev/spec/35/) protocols also facilitate secure channel negotiation within the Waku network. ## [Security Considerations](https://rfc.vac.dev/spec/10/#security-considerations) diff --git a/docs/overview/reference/waku-vs-libp2p.md b/docs/overview/reference/waku-vs-libp2p.md index 628c9c0..1aec1e7 100644 --- a/docs/overview/reference/waku-vs-libp2p.md +++ b/docs/overview/reference/waku-vs-libp2p.md @@ -12,8 +12,8 @@ Waku intends to incentivize mechanisms to run nodes, but it's not part of libp2p 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, [Store](/overview/concepts/protocols#store)/[Light Push](/overview/concepts/protocols#light-push)/[Filter](/overview/concepts/protocols#filter) caters to those use cases. +libp2p does not provide out-of-the-box protocols to enable mostly offline/resource-limited devices, [Store](/overview/concepts/protocols#store)/[Light Push](/overview/concepts/protocols#light-push)/[Filter](/overview/concepts/protocols#filter) caters to those use cases. ## Economic Spam Protection -libp2p does not have strong spam protection guarantees, [RLN (Rate Limit Nullifier)](/overview/concepts/protocols#rln-relay) is a protocol being developed by the Waku team towards this goal. +libp2p does not have strong spam protection guarantees, [RLN Relay](/overview/concepts/protocols#rln-relay) is a protocol being developed by the Waku team towards this goal. diff --git a/docs/overview/why-waku.md b/docs/overview/why-waku.md index d5f3974..84b3c6c 100644 --- a/docs/overview/why-waku.md +++ b/docs/overview/why-waku.md @@ -17,7 +17,7 @@ Waku is intended to empower individuals by returning control of communication to | | Whisper | Waku | | - | - | - | -| **Scalability** | Whisper doesn't scale very well, specifically when it comes to bandwidth usage on mobile devices. | Uses gossipsub and content topics. | +| **Scalability** | Whisper doesn't scale very well, specifically when it comes to bandwidth usage on mobile devices. | Uses GossipSub and Content Topics. | | **Spam Resistance** | Proof of work requires too much battery and compute power making it a poor mechanism for heterogeneous nodes. | Uses innovative p2p economic spam protection mechanism RLN Relay. | | **Incentivization Infrastructure** | There is no incentive to run a Whisper node. | Research in progress to design incentivization for node operators. | | **Formal Specification/Documentation** | Lack of formal and unambiguous specification. | The specs and docs are open-source and licensed under CC0, making them freely available for anyone to read, modify and improve without restrictions. | diff --git a/docs/powered-by-waku.mdx b/docs/powered-by-waku.mdx index cf7917c..16aa885 100644 --- a/docs/powered-by-waku.mdx +++ b/docs/powered-by-waku.mdx @@ -11,28 +11,28 @@ import PoweredByCard from "@site/src/components/PoweredByCard"; Status is a secure messaging app, crypto wallet, and Web3 browser built with state-of-the-art technology. XMTP uses the Waku network to enable secure Web3 messaging in their open protocol and network. RAILGUN uses Waku to offer private gas payments to users, ensuring anonymity and privacy for their transactions. Waku powers the Graphcast SDK, enabling the development of gossip-powered applications within The Graph ecosystem. diff --git a/docusaurus.config.js b/docusaurus.config.js index 41963d1..e2335b2 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -4,7 +4,7 @@ require("dotenv").config(); /** @type {import("@docusaurus/types").Config} */ const config = { - title: "Waku Documentation Portal", + title: "Waku Docs Portal", url: "https://waku.guide/", baseUrl: "/", onBrokenLinks: "throw", diff --git a/sidebars.js b/sidebars.js index 0a9e320..b1e69a4 100644 --- a/sidebars.js +++ b/sidebars.js @@ -36,6 +36,7 @@ const sidebars = { collapsed: false, collapsible: true, items: [ + "overview/reference/glossary", "overview/reference/security-features", "overview/reference/research-in-progress", "overview/reference/waku-vs-libp2p" diff --git a/src/components/PoweredByCard.js b/src/components/PoweredByCard.js index 14dbc3f..e9ce012 100644 --- a/src/components/PoweredByCard.js +++ b/src/components/PoweredByCard.js @@ -1,6 +1,6 @@ import React from "react"; -const PoweredByCard = ({ appLink, logoSrc, logoAlt, children }) => ( +const PoweredByCard = ({ appLink, logoSrc, appName, children }) => (
( }}> {logoAlt} ( color: "#3578e5" }} > - Visit Application  + Visit { appName }