diff --git a/static/discv5.md b/diagrams/_discv5.md similarity index 99% rename from static/discv5.md rename to diagrams/_discv5.md index ebfeb8e..e4043b0 100644 --- a/static/discv5.md +++ b/diagrams/_discv5.md @@ -1,4 +1,3 @@ - ```mermaid sequenceDiagram Alice->>DNS Server: (1) Execute DNS Discovery diff --git a/static/dns_discovery.md b/diagrams/_dns_discovery.md similarity index 99% rename from static/dns_discovery.md rename to diagrams/_dns_discovery.md index e7a2e85..af6ac6c 100644 --- a/static/dns_discovery.md +++ b/diagrams/_dns_discovery.md @@ -1,5 +1,3 @@ - - ```mermaid sequenceDiagram Waku Node->>DNS Server: (1) Lookup TXT example.com diff --git a/diagrams/_history.md b/diagrams/_history.md new file mode 100644 index 0000000..d4f5011 --- /dev/null +++ b/diagrams/_history.md @@ -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:"🔥" +``` \ No newline at end of file diff --git a/static/peer_exchange.md b/diagrams/_peer_exchange.md similarity index 99% rename from static/peer_exchange.md rename to diagrams/_peer_exchange.md index 6390362..70739fe 100644 --- a/static/peer_exchange.md +++ b/diagrams/_peer_exchange.md @@ -1,4 +1,3 @@ - ```mermaid sequenceDiagram Alice->>DNS Server: (1) Execute DNS Discovery diff --git a/diagrams/_protocol_interaction.md b/diagrams/_protocol_interaction.md new file mode 100644 index 0000000..fbc7543 --- /dev/null +++ b/diagrams/_protocol_interaction.md @@ -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. \ No newline at end of file diff --git a/docs/overview/concepts/network-domains.md b/docs/overview/concepts/network-domains.md index 9098363..ed506ac 100644 --- a/docs/overview/concepts/network-domains.md +++ b/docs/overview/concepts/network-domains.md @@ -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. \ No newline at end of file + +``` \ No newline at end of file diff --git a/docs/overview/concepts/peer-discovery/discv5.md b/docs/overview/concepts/peer-discovery/discv5.md index 88f81af..d1b4a17 100644 --- a/docs/overview/concepts/peer-discovery/discv5.md +++ b/docs/overview/concepts/peer-discovery/discv5.md @@ -4,12 +4,20 @@ 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 +## Pros - Decentralized with random sampling from a global view. - Continuously researched and improved. -#### Cons +## Cons - Requires lots of connections and involves frequent churn. -- Relies on User Datagram Protocol (UDP), which is not supported in web browsers. \ No newline at end of file +- Relies on User Datagram Protocol (UDP), which is not supported in web browsers. + +## Overview + +```mdx-code-block +import Discv5 from "@site/diagrams/_discv5.md"; + + +``` \ No newline at end of file diff --git a/docs/overview/concepts/peer-discovery/dns-discovery.md b/docs/overview/concepts/peer-discovery/dns-discovery.md index 0420121..16cb9d0 100644 --- a/docs/overview/concepts/peer-discovery/dns-discovery.md +++ b/docs/overview/concepts/peer-discovery/dns-discovery.md @@ -6,13 +6,21 @@ Built upon the foundation of [EIP-1459: Node Discovery via DNS](https://eips.eth This bootstrapping method allows anyone to register and publish a domain name for the network, promoting increased decentralization. -#### Pros +## 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 +## 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. \ No newline at end of file +- 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"; + + +``` \ No newline at end of file diff --git a/docs/overview/concepts/peer-discovery/peer-exchange.md b/docs/overview/concepts/peer-discovery/peer-exchange.md index 4d12508..cdd8782 100644 --- a/docs/overview/concepts/peer-discovery/peer-exchange.md +++ b/docs/overview/concepts/peer-discovery/peer-exchange.md @@ -4,12 +4,20 @@ 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 +## Pros - Low resource requirements. - Decentralized with random sampling of nodes from a global view using `Discv5`. -#### Cons +## Cons - Decreased anonymity. -- Imposes additional load on responder nodes. \ No newline at end of file +- Imposes additional load on responder nodes. + +## Overview + +```mdx-code-block +import PeerExchange from "@site/diagrams/_peer_exchange.md"; + + +``` \ No newline at end of file diff --git a/docs/overview/concepts/peer-discovery/predefined-nodes.md b/docs/overview/concepts/peer-discovery/predefined-nodes.md index 076db16..eb4873e 100644 --- a/docs/overview/concepts/peer-discovery/predefined-nodes.md +++ b/docs/overview/concepts/peer-discovery/predefined-nodes.md @@ -4,12 +4,12 @@ title: Predefined Nodes 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 +## Pros - Low latency. - Low resource requirements. -#### Cons +## Cons - Vulnerable to censorship: Node IPs can be blocked or restricted. - Limited scalability: The number of nodes is fixed and cannot easily be expanded. diff --git a/docs/overview/history.md b/docs/overview/history.md index 3920749..f0de64e 100644 --- a/docs/overview/history.md +++ b/docs/overview/history.md @@ -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"; + + ``` ### 2013