From 4e1cc330fd6bcb652bf16cd984d1ca008cf4c65a Mon Sep 17 00:00:00 2001 From: LordGhostX Date: Fri, 16 Jun 2023 09:40:22 +0100 Subject: [PATCH] add peer discovery guide --- .cspell.json | 4 +- ...{_predefined-nodes.md => _static-peers.md} | 4 +- docs/guides/nwaku/configure-discovery.md | 48 +++++++++++++++++++ docs/guides/reference/node-config-methods.md | 6 ++- docs/guides/reference/node-config-options.md | 10 ++-- docs/guides/run-nwaku-node.md | 6 +-- docs/overview/concepts/peer-discovery.md | 2 +- .../{predefined-nodes.md => static-peers.md} | 8 ++-- docs/powered-by-waku.mdx | 6 +-- scripts/config-table-generator.py | 4 +- sidebars.js | 3 +- 11 files changed, 80 insertions(+), 21 deletions(-) rename diagrams/{_predefined-nodes.md => _static-peers.md} (58%) create mode 100644 docs/guides/nwaku/configure-discovery.md rename docs/overview/concepts/{predefined-nodes.md => static-peers.md} (54%) diff --git a/.cspell.json b/.cspell.json index 92699f3..7ccdf05 100644 --- a/.cspell.json +++ b/.cspell.json @@ -45,7 +45,9 @@ "devel", "statusteam", "myaddr", - "extip" + "extip", + "staticnode", + "permissioned" ], "flagWords": [], "ignorePaths": [ diff --git a/diagrams/_predefined-nodes.md b/diagrams/_static-peers.md similarity index 58% rename from diagrams/_predefined-nodes.md rename to diagrams/_static-peers.md index 7d1a0ec..9120956 100644 --- a/diagrams/_predefined-nodes.md +++ b/diagrams/_static-peers.md @@ -1,7 +1,7 @@ ```mermaid sequenceDiagram -Alice->>Bob: Connect to Bob (predefined node details) -Alice->>Carol: Connect to Carol (predefined node details) +Alice->>Bob: Connect to Bob (static peer details) +Alice->>Carol: Connect to Carol (static peer details) ``` Alice establishes connections with Bob and Carol using their node details, which are predefined (hard-coded) into Alice's node. \ No newline at end of file diff --git a/docs/guides/nwaku/configure-discovery.md b/docs/guides/nwaku/configure-discovery.md new file mode 100644 index 0000000..3ae68fb --- /dev/null +++ b/docs/guides/nwaku/configure-discovery.md @@ -0,0 +1,48 @@ +--- +title: Configure Peer Discovery +--- + +This guide provides detailed steps to configure a `nwaku` node to locate and connect with peers in the Waku Network. + +:::tip +You can configure a `nwaku` node to use multiple peer discovery mechanisms simultaneously. +::: + +## Configure Static Peers + +You can provide static peers to a `nwaku` node during startup using the `staticnode` configuration option. To connect to multiple peers on startup, repeat the `staticnode` option: + +```bash +wakunode2 \ + --staticnode:[Libp2p MULTIADDR PEER 1] \ + --staticnode:[Libp2p MULTIADDR PEER 2] +``` + +## Configure DNS Discovery + +To enable [DNS Discovery](/overview/concepts/dns-discovery) in a `nwaku` node, use the following configuration options: + +- `dns-discovery`: Enables DNS Discovery on the node (disabled by default). +- `dns-discovery-url`: URL for DNS node list in the format `enrtree://@` where `` is the fully qualified domain name and `` is the base32 encoding of the compressed 32-byte public key that signed the list at that location. +- `dns-discovery-name-server` (optional): DNS name server IPs to query. You can repeat this option to provide multiple DNS name servers. + +``` +wakunode2 \ + --dns-discovery:true \ + --dns-discovery-url:[DNS NODE LIST] +``` + +## Configure Discv5 + +You can enable [Discv5](/overview/concepts/discv5) in a `nwaku` node using the `discv5-discovery` and `discv5-bootstrap-node` configuration options. To configure multiple bootstrap entries for the Discv5 routing table, repeat the `discv5-bootstrap-node` option: + +```bash +wakunode2 \ + --discv5-discovery:true \ + --discv5-bootstrap-node:[DISCV5 ENR BOOTSTRAP ENTRY 1] \ + --discv5-bootstrap-node:[DISCV5 ENR BOOTSTRAP ENTRY 2] +``` + +:::info +When Discv5 is enabled and used with [DNS Discovery](#configure-dns-discovery), the `nwaku` node will attempt to bootstrap the Discv5 routing table by extracting `ENRs` from peers discovered through DNS. +::: \ No newline at end of file diff --git a/docs/guides/reference/node-config-methods.md b/docs/guides/reference/node-config-methods.md index b81178d..c70e68c 100644 --- a/docs/guides/reference/node-config-methods.md +++ b/docs/guides/reference/node-config-methods.md @@ -92,4 +92,8 @@ The following options are available: --tcp-port TCP listening port. [=60000]. <...> -``` \ No newline at end of file +``` + +:::tip +To explore the available node configuration options, please refer to the [Node Configuration Options](/guides/reference/node-config-options) guide. +::: \ No newline at end of file diff --git a/docs/guides/reference/node-config-options.md b/docs/guides/reference/node-config-options.md index cbf9478..9128597 100644 --- a/docs/guides/reference/node-config-options.md +++ b/docs/guides/reference/node-config-options.md @@ -2,7 +2,7 @@ title: Node Configuration Options --- -Here are the node configuration options and their descriptions: +Here are the available node configuration options, along with their default values and descriptions: ## Application-Level Config @@ -131,7 +131,7 @@ Here are the node configuration options and their descriptions: | `dns-discovery-url` | | URL for DNS node list in format 'enrtree://@' | | `dns-discovery-name-server` | `@[1.1.1.1, 1.0.0.1]` | DNS name server IPs to query. Argument may be repeated | -## Discovery v5 Config +## Discv5 Config | Name | Default Value | Description | | - | - | - | @@ -158,4 +158,8 @@ Here are the node configuration options and their descriptions: | `websocket-port` | `8000` | WebSocket listening port | | `websocket-secure-support` | `false` | Enable secure websocket: true\|false | | `websocket-secure-key-path` | | Secure websocket key path: '/path/to/key.txt' | -| `websocket-secure-cert-path` | | Secure websocket Certificate path: '/path/to/cert.txt' | \ No newline at end of file +| `websocket-secure-cert-path` | | Secure websocket Certificate path: '/path/to/cert.txt' | + +:::tip +To configure your node using the provided configuration options, please refer to the [Node Configuration Methods](/guides/reference/node-config-methods) guide. +::: \ No newline at end of file diff --git a/docs/guides/run-nwaku-node.md b/docs/guides/run-nwaku-node.md index bb6561c..3ef482f 100644 --- a/docs/guides/run-nwaku-node.md +++ b/docs/guides/run-nwaku-node.md @@ -57,9 +57,9 @@ To join the Waku Network, nodes must connect with peers. Nwaku provides multiple | | Description | Documentation | | - | - | - | -| Predefined Nodes | Configure the bootstrap nodes that `nwaku` should establish connections upon startup | [Configure Predefined Nodes](https://github.com/waku-org/nwaku/blob/master/docs/operators/how-to/connect.md#option-1-configure-peers-statically) | -| DNS Discovery | Enable `nwaku` to locate peers to connect to using the `DNS Discovery` mechanism | [Configure DNS Discovery](https://github.com/waku-org/nwaku/blob/master/docs/operators/how-to/configure-dns-disc.md) | -| Discv5 | Enable `nwaku` to locate peers to connect to using the `Discv5` mechanism | [Configure Discv5](https://github.com/waku-org/nwaku/blob/master/docs/operators/how-to/connect.md#option-3-discover-peers-using-waku-discovery-v5) | +| Static Peers | Configure the bootstrap nodes that `nwaku` should establish connections upon startup | [Configure Static Peers](/guides/nwaku/configure-discovery#configure-static-peers) | +| DNS Discovery | Enable `nwaku` to locate peers to connect to using the `DNS Discovery` mechanism | [Configure DNS Discovery](/guides/nwaku/configure-discovery#configure-dns-discovery) | +| Discv5 | Enable `nwaku` to locate peers to connect to using the `Discv5` mechanism | [Configure Discv5](/guides/nwaku/configure-discovery#configure-discv5) | :::tip You can configure a `nwaku` node to use multiple peer discovery mechanisms simultaneously. diff --git a/docs/overview/concepts/peer-discovery.md b/docs/overview/concepts/peer-discovery.md index 8ab6de3..0cf1641 100644 --- a/docs/overview/concepts/peer-discovery.md +++ b/docs/overview/concepts/peer-discovery.md @@ -12,7 +12,7 @@ Once a connection is established, the node must actively seek out additional pee Waku supports multiple peer discovery mechanisms, such as: -- [Configuring Predefined Nodes](/overview/concepts/predefined-nodes) +- [Configuring Static Peers](/overview/concepts/static-peers) - [Peer Discovery via DNS](/overview/concepts/dns-discovery) - [Discv5 Ambient Peer Discovery](/overview/concepts/discv5) - [Peer Exchange](/overview/concepts/peer-exchange) \ No newline at end of file diff --git a/docs/overview/concepts/predefined-nodes.md b/docs/overview/concepts/static-peers.md similarity index 54% rename from docs/overview/concepts/predefined-nodes.md rename to docs/overview/concepts/static-peers.md index 0a3a473..7b3b841 100644 --- a/docs/overview/concepts/predefined-nodes.md +++ b/docs/overview/concepts/static-peers.md @@ -1,8 +1,8 @@ --- -title: Predefined Nodes +title: Static Peer --- -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. +Waku applications have the flexibility to embed bootstrap node addresses directly into their codebase. Developers can either use [static peers 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 @@ -18,7 +18,7 @@ Waku applications have the flexibility to embed bootstrap node addresses directl ## Overview ```mdx-code-block -import PredefinedNodes from "@site/diagrams/_predefined-nodes.md"; +import StaticPeers from "@site/diagrams/_static-peers.md"; - + ``` \ No newline at end of file diff --git a/docs/powered-by-waku.mdx b/docs/powered-by-waku.mdx index 57b64d9..8bb8679 100644 --- a/docs/powered-by-waku.mdx +++ b/docs/powered-by-waku.mdx @@ -11,7 +11,7 @@ import { PoweredBy } from "@site/src/components/mdx"; { name: "Status", description: - "Status is a secure messaging app, crypto wallet, and Web3 browser built with state-of-the-art technology.", + "Waku powers many of the Status super app's features, including its private messaging.", logoSrc: "/img/status-mark-black.svg", logoSrcDark: "/img/status-mark-white.svg", link: "https://status.im", @@ -19,7 +19,7 @@ import { PoweredBy } from "@site/src/components/mdx"; { name: "RAILGUN", description: - "RAILGUN uses Waku to offer private gas payments to users, ensuring anonymity and privacy for their transactions.", + "The privacy-focused DeFi protocol Railgun anonymizes Ethereum transactions with Waku.", logoSrc: "/img/railgun-mark-black.svg", logoSrcDark: "/img/railgun-mark-white.svg", link: "https://railgun.org", @@ -35,7 +35,7 @@ import { PoweredBy } from "@site/src/components/mdx"; { name: "XMTP", description: - "XMTP uses the Waku network to enable secure Web3 messaging in their open protocol and network.", + "Inter-blockchain account messaging protocol XMTP uses Waku to facilitate communication between nodes in its currently permissioned network.", logoSrc: "/img/xmtp-mark-black.svg", logoSrcDark: "/img/xmtp-mark-white.svg", link: "https://xmtp.org", diff --git a/scripts/config-table-generator.py b/scripts/config-table-generator.py index 06a5c89..c412938 100644 --- a/scripts/config-table-generator.py +++ b/scripts/config-table-generator.py @@ -17,12 +17,12 @@ def parse_table_heading(line: str) -> Tuple[str, bool]: word_replace_re = re.compile('|'.join([ r'(Configuration)', r'(And)', r'(Lightpush)', r'(Json-Rpc)', r'(Rest Http)', r'(Dns)', - r'(V5)', r'(Websocket)' + r'(Discovery V5)', r'(Websocket)' ])) word_replace_dict = { 'Configuration': 'Config', 'And': 'and', 'Lightpush': 'Light Push', 'Json-Rpc': 'JSON-RPC', 'Rest Http': 'REST HTTP', 'Dns': 'DNS', - 'V5': 'v5', 'Websocket': 'WebSocket' + 'Discovery V5': 'Discv5', 'Websocket': 'WebSocket' } table_heading = word_replace_re.sub(lambda match: word_replace_dict[match.group(0)], table_heading) return '## ' + table_heading, True diff --git a/sidebars.js b/sidebars.js index f436caf..d81ada1 100644 --- a/sidebars.js +++ b/sidebars.js @@ -31,7 +31,7 @@ const sidebars = { id: "overview/concepts/peer-discovery", }, items: [ - "overview/concepts/predefined-nodes", + "overview/concepts/static-peers", "overview/concepts/dns-discovery", "overview/concepts/discv5", "overview/concepts/peer-exchange", @@ -64,6 +64,7 @@ const sidebars = { "guides/nwaku/build-source", "guides/nwaku/run-docker", "guides/nwaku/run-docker-compose", + "guides/nwaku/configure-discovery", ] }, {