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",