acid-info
/
waku.guide
mirror of https://github.com/acid-info/waku.guide.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #66 from waku-org/add-network-diagrams 

add network diagrams
This commit is contained in:
LordGhostX 2023-06-10 01:38:47 +01:00 committed by GitHub
parent ce42439669 a5e761b3af
commit fbcdd8bb33
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
18 changed files with 190 additions and 116 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
static/discv5.md → diagrams/_discv5.md
View File

@ -1,4 +1,3 @@
```mermaid
sequenceDiagram
Alice->>DNS Server: (1) Execute DNS Discovery

2
static/dns_discovery.md → diagrams/_dns-discovery.md
View File

@ -1,5 +1,3 @@
```mermaid
sequenceDiagram
Waku Node->>DNS Server: (1) Lookup TXT example.com

18
diagrams/_history.md Normal file
View File

@ -0,0 +1,18 @@
```mermaid
%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showBranches': true, 'showCommitLabel':true,'mainBranchName': 'HISTORY'}} }%%
gitGraph
commit id:"2013"
commit id:"2015" tag:"R&D"
commit id:"2018" tag:"R&D" type: HIGHLIGHT
branch v1
checkout v1
commit id:"2020" tag:"release"
checkout HISTORY
merge v1
branch v2
checkout v2
commit id:"2021" tag:"release"
checkout HISTORY
merge v2
commit id:"🔥"
```

1
static/peer_exchange.md → diagrams/_peer-exchange.md
View File

@ -1,4 +1,3 @@
```mermaid
sequenceDiagram
Alice->>DNS Server: (1) Execute DNS Discovery

7
diagrams/_predefined-nodes.md Normal file
View File

@ -0,0 +1,7 @@
```mermaid
sequenceDiagram
Alice->>Bob: Connect to Bob (predefined node details)
Alice->>Carol: Connect to Carol (predefined node details)
```
Alice establishes connections with Bob and Carol using their node details, which are predefined (hard-coded) into Alice's node.

30
diagrams/_protocol-interaction.md Normal file
View File

@ -0,0 +1,30 @@
```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 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 ->> C: relay msg1 on pubtopic1 (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. Node D serves as a `Store` and is responsible for persisting messages.
1. Node A creates a WakuMessage `msg1` with [Content Topic](/overview/concepts/content-topics) `contentTopic1`.
2. Node F requests to get messages filtered by Pub/Sub topic `pubtopic1` and Content Topic `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` 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.

2
docs/guides/nodes-and-sdks.md
View File

@ -44,4 +44,4 @@ Waku provides integrations tailored for mobile applications, enabling Waku to ru
| - | - | - |
| [@waku/react](https://www.npmjs.com/package/@waku/react) | React components and UI adapters designed for seamless integration with `js-waku` | |
| [@waku/create-app](https://www.npmjs.com/package/@waku/create-app) | Starter kit to bootstrap your next `js-waku` project from various example templates | |
| JSON-RPC API | `JSON-RPC` API interface provided by `nwaku` and `go-waku` to access the Waku Network | |
| JSON-RPC API | `JSON-RPC` API interface provided by `nwaku` and `go-waku` to interact with the Waku Network | |

7
docs/guides/run-nwaku-node.md
View File

@ -39,6 +39,7 @@ By default, a `nwaku` node is configured to do the following:
- Generate a new private key and libp2p identity.
- Listen for incoming libp2p connections on the default TCP port (`60000`).
- Subscribe to the default Pub/Sub topic (`/waku/2/default-waku/proto`).
- Start the `JSON-RPC` HTTP server on the default port (`8545`).
- Enable the `Relay` protocol for relaying messages.
- Enable the `Store` protocol as a client, allowing it to query peers for historical messages but not persist any message itself.
@ -81,4 +82,8 @@ You will get a response similar to:
"enrUri":"enr:-IO4QDxToTg86pPCK2KvMeVCXC2ADVZWrxXSvNZeaoa0JhShbM5qed69RQz1s1mWEEqJ3aoklo_7EU9iIBcPMVeKlCQBgmlkgnY0iXNlY3AyNTZrMaEDdBHK1Gx6y_zv5DVw5Qb3DtSOMmVHTZO1WSORrF2loL2DdWRwgiMohXdha3UyAw"
}
}
```
```
:::info
The `listenAddresses` field stores the transport addresses for accepting connections, while the `enrUri` field stores the `ENR` URI for peer discovery.
:::

35
docs/overview/concepts/network-domains.md
View File

@ -6,7 +6,7 @@ Waku is a unified and cohesive entity that offers a rich ecosystem with three di
## Discovery Domain
Peer discovery in Waku facilitates locating other nodes 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 nodes 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
@ -26,33 +26,8 @@ Waku provides a set of protocols to optimize its performance in resource-limited
Here is 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 filter
```mdx-code-block
import ProtocolInteraction from "@site/diagrams/_protocol-interaction.md";
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 ->> C: relay msg1 on pubtopic1 (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. Node D serves as a `Store` and is responsible for persisting messages.
1. Node A creates a WakuMessage `msg1` with [Content Topic](/overview/concepts/content-topics) `contentTopic1`.
2. Node F requests to get messages filtered by Pub/Sub topic `pubtopic1` and Content Topic `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` 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.
<ProtocolInteraction />
```

63
docs/overview/concepts/peer-discovery.md
View File

@ -10,62 +10,9 @@ Once a connection is established, the node must actively seek out additional pee
- 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 capabilities: The node seeks out peers with specific capabilities, such as [Store](/overview/concepts/protocols#store), [Light Push](/overview/concepts/protocols#light-push), or [Filter](/overview/concepts/protocols#filter). This allows for targeted interactions and enhanced functionality based on the desired capabilities.
## Predefined Nodes
Waku supports multiple peer discovery mechanisms, such as:
Waku applications have the flexibility to embed bootstrap node addresses directly into their codebase. Developers can opt to use either the [predefined nodes by Status](https://github.com/waku-org/js-waku/blob/master/packages/core/src/lib/predefined_bootstrap_nodes.ts#L45) or [run a node](/guides/nodes-and-sdks#run-a-waku-node) 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 involves releasing and deploying.
## [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 the retrieval of an `ENR` tree from the `TXT` field of a domain name. This innovative approach enables the storage of essential node connection details, including IP, port, and multiaddr, using 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, promoting 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 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/)
`Discv5` is a decentralized and efficient peer discovery method for the Waku Network. It uses 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
- 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-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
- Low resource requirements.
- Decentralized with random sampling of nodes from a global view using `Discv5`.
#### Cons
- Decreased anonymity.
- Imposes additional load on responder nodes.
- [Configuring Predefined Nodes](/overview/concepts/peer-discovery/predefined-nodes)
- [Peer Discovery via DNS](/overview/concepts/peer-discovery/dns-discovery)
- [Discv5 Ambient Peer Discovery](/overview/concepts/peer-discovery/discv5)
- [Peer Exchange](/overview/concepts/peer-discovery/peer-exchange)

23
docs/overview/concepts/peer-discovery/discv5.md Normal file
View File

@ -0,0 +1,23 @@
---
title: Discv5
---
`Discv5` is a decentralized and efficient peer discovery mechanism for the Waku Network. It uses 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. Please refer to the [Discv5](https://rfc.vac.dev/spec/33/) specification to learn more.
## Pros
- Decentralized with random sampling from a global view.
- Continuously researched and improved.
## Cons
- Requires lots of connections and involves frequent churn.
- Relies on User Datagram Protocol (UDP), which is not supported in web browsers.
## Overview
```mdx-code-block
import Discv5 from "@site/diagrams/_discv5.md";
<Discv5 />
```

26
docs/overview/concepts/peer-discovery/dns-discovery.md Normal file
View File

@ -0,0 +1,26 @@
---
title: DNS Discovery
---
Built upon the foundation of [EIP-1459: Node Discovery via DNS](https://eips.ethereum.org/EIPS/eip-1459), DNS Discovery allows the retrieval of an `ENR` tree from the `TXT` field of a domain name. This innovative approach enables the storage of essential node connection details, including IP, port, and multiaddr, using 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, promoting 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 listed nodes are at risk of being overwhelmed by receiving all queries. Also, operators must provide their `ENR` to the domain owner for listing.
## Overview
```mdx-code-block
import DNSDiscovery from "@site/diagrams/_dns-discovery.md";
<DNSDiscovery />
```

23
docs/overview/concepts/peer-discovery/peer-exchange.md Normal file
View File

@ -0,0 +1,23 @@
---
title: Peer Exchange
---
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`. Please refer to the [Peer Exchange](https://rfc.vac.dev/spec/34/) specification to learn more.
## 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.
## Overview
```mdx-code-block
import PeerExchange from "@site/diagrams/_peer-exchange.md";
<PeerExchange />
```

24
docs/overview/concepts/peer-discovery/predefined-nodes.md Normal file
View File

@ -0,0 +1,24 @@
---
title: Predefined Nodes
---
Waku applications have the flexibility to embed bootstrap node addresses directly into their codebase. Developers can use either the [predefined nodes by Status](https://github.com/waku-org/js-waku/blob/master/packages/core/src/lib/predefined_bootstrap_nodes.ts#L45) or [run a node](/guides/nodes-and-sdks#run-a-waku-node) 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 involves releasing and deploying.
## Overview
```mdx-code-block
import PredefinedNodes from "@site/diagrams/_predefined-nodes.md";
<PredefinedNodes />
```

21
docs/overview/history.md
View File

@ -4,23 +4,10 @@ title: History of Waku
`Waku v1` was a fork of Whisper with some added tweaks for efficiency. `Waku v2` introduces a fully revamped suite of protocols designed to address the goals set out [previously](/#motivation-and-goals).
```mermaid
%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showBranches': true, 'showCommitLabel':true,'mainBranchName': 'HISTORY'}} }%%
gitGraph
commit id:"2013"
commit id:"2015" tag:"R&D"
commit id:"2018" tag:"R&D" type: HIGHLIGHT
branch v1
checkout v1
commit id:"2020" tag:"release"
checkout HISTORY
merge v1
branch v2
checkout v2
commit id:"2021" tag:"release"
checkout HISTORY
merge v2
commit id:"🔥"
```mdx-code-block
import History from "@site/diagrams/_history.md";
<History />
```
### 2013

2
docs/overview/index.md
View File

@ -41,7 +41,7 @@ Waku can cater to applications that require privacy guarantees, such as:
### Modular Design
Waku nodes are adaptive and can be customized based on the application's requirements and environment. Users can adjust multiple parameters, including:
Waku nodes are adaptive and can be customized based on the application's requirements and environment. Users can adjust multiple parameters, such as:
- Low privacy/low resource usage vs. high privacy/increased latency + bandwidth usage.
- Providing resources to the network vs. consuming resources.

6
docs/overview/reference/glossary.md
View File

@ -18,11 +18,11 @@ A content topic is a string attached to [messages](#waku-message) to enable [pro
Dappnode is an open-source platform that simplifies the hosting and management of decentralized applications and blockchain nodes, including [Waku](#waku).
### [Discv5](/overview/concepts/peer-discovery#discv5)
### [Discv5](/overview/concepts/peer-discovery/discv5)
Discv5 is a [peer discovery](#peer-discovery) mechanism using a Distributed Hash Table (DHT) to store [ENR](#enr) records, providing censorship resistance, load distribution, and enhanced network resilience.
### [DNS Discovery](/overview/concepts/peer-discovery#dns-discovery)
### [DNS Discovery](/overview/concepts/peer-discovery/dns-discovery)
DNS discovery is a [peer discovery](#peer-discovery) mechanism that allows the retrieval of an [ENR](#enr) tree from the TXT field of a domain name, enabling the storage of [node](#node) connection details and promoting decentralization.
@ -66,7 +66,7 @@ A peer refers to other [nodes](#node) and participants of the [Waku Network](#wa
Peer discovery is when a [node](#node) locates and gets information about other [peers](#peer) in the [Waku Network](#waku).
### [Peer Exchange](/overview/concepts/peer-discovery#peer-exchange)
### [Peer Exchange](/overview/concepts/peer-discovery/peer-exchange)
Peer exchange is a [peer discovery](#peer-discovery) mechanism that enables [light nodes](#light-node) to request and receive peers from other nodes in the network, allowing them to bootstrap and expand their connections without depending on [Discv5](#discv5).

15
sidebars.js
View File

@ -28,7 +28,20 @@ const sidebars = {
"overview/concepts/protocols",
"overview/concepts/content-topics",
"overview/concepts/network-domains",
"overview/concepts/peer-discovery",
{
type: "category",
label: "Peer Discovery",
link: {
type: "doc",
id: "overview/concepts/peer-discovery"
},
items: [
"overview/concepts/peer-discovery/predefined-nodes",
"overview/concepts/peer-discovery/dns-discovery",
"overview/concepts/peer-discovery/discv5",
"overview/concepts/peer-discovery/peer-exchange"
]
},
"overview/concepts/transports"
]
},