diff --git a/.cspell.json b/.cspell.json index ecfd0c8..fa91b8a 100644 --- a/.cspell.json +++ b/.cspell.json @@ -83,7 +83,7 @@ "yarn.lock", "tsconfig.json", "node_modules/**", - "docs/guides/reference/node-config-options.md" + "docs/guides/nwaku/config-options.md" ], "patterns": [ { diff --git a/README.md b/README.md index 1029309..6f4993e 100644 --- a/README.md +++ b/README.md @@ -13,13 +13,13 @@ The Waku Documentation Portal can be accessed at and wa Clone this repository: -```bash +```shell git clone https://github.com/waku-org/docs.waku.org ``` Install the dependencies: -```bash +```shell yarn # or @@ -29,19 +29,19 @@ yarn install ## Running Locally -```bash +```shell yarn start ``` Check for spelling errors before deploying: -```bash +```shell yarn check:spell ``` Create a production build locally to check for errors: -```bash +```shell yarn build # test the build @@ -82,6 +82,6 @@ You can find the instructions on adding more documentation sections, localisatio Docusaurus depends heavily on caching to enhance site performance. If you make changes that do not appear in the portal, try clearing the cache by running: -```bash +```shell yarn clear ``` \ No newline at end of file diff --git a/diagrams/_history.md b/diagrams/_history.md deleted file mode 100644 index 8a49593..0000000 --- a/diagrams/_history.md +++ /dev/null @@ -1,18 +0,0 @@ -```mermaid -%%{init: { '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/diagrams/_protocol-interaction.md b/diagrams/_protocol-interaction.md index d62bdda..1725574 100644 --- a/diagrams/_protocol-interaction.md +++ b/diagrams/_protocol-interaction.md @@ -22,7 +22,7 @@ sequenceDiagram 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`. +1. Node A creates a WakuMessage `msg1` with [Content Topic](/learn/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`, stores the message for future retrieval by other nodes and forwards it to Node C. diff --git a/docs/community.md b/docs/community.md deleted file mode 100644 index 81871a6..0000000 --- a/docs/community.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Join Our Community ---- - -Welcome to the Waku Community! Whether you are interested in building with Waku, contributing to the network, expanding your knowledge, or staying abreast of our progress, we have something for everyone. - -## [Discord](https://discord.waku.org/) - -Connect with like-minded individuals in the Waku ecosystem! Introduce yourself, join developer conversations, or seek assistance. Join the [Waku Discord](https://discord.waku.org/) today! - -## [Twitter](https://twitter.com/waku_org) - -Stay informed and updated with the latest news and insights from Waku. [Follow us on Twitter](https://twitter.com/waku_org) now for all the thrilling updates! - -## [Telegram](https://t.me/waku_org) - -Join the [Waku Telegram Group](https://t.me/waku_org) now and become part of the thriving community! Stay informed, share ideas, and connect with fellow enthusiasts. - -## [Vac Forum](https://forum.vac.dev/) - -Are you seeking answers or looking forward to engaging in in-depth discussions about Waku? Join the conversation on the [Vac Forum](https://forum.vac.dev/), where you can participate in research-related and other insightful talks. \ No newline at end of file diff --git a/docs/contribute.md b/docs/contribute.md deleted file mode 100644 index 0aa9c1b..0000000 --- a/docs/contribute.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Contribute to Waku ---- - -Get involved in Waku's open-source initiatives to improve the protocols, SDKs, developer tools and examples, and documentation. You can contribute by: - -- [Running a node](/guides/nodes-and-sdks#run-a-waku-node) within your application. -- [Reporting bugs](#report-a-bug) and [suggesting missing features](#suggest-a-feature) to the development team. -- Completing [Waku Bounties](#complete-waku-bounties) and participating in our [Bug Bounty Programme](#submit-security-bug-reports). -- Inspiring other developers to explore and use Waku for [various use cases](/overview/use-cases). - -Begin your journey by visiting the [Nodes and SDKs](/guides/nodes-and-sdks) guide and start building on Waku today! - -## Report a Bug - -To report a bug, create an issue in the appropriate [GitHub repository](https://github.com/waku-org). Ensure no issue exists about the bug and include detailed steps to reproduce the bug. - -## Suggest a Feature - -To suggest a new feature, create an issue in the appropriate [GitHub repository](https://github.com/waku-org). Ensure no issue exists about the feature and specify the use cases the feature can enable, allowing us to investigate and prioritise accordingly. - -## Make Pull Requests - -Community pull requests (PRs) are highly encouraged, but we recommend [suggesting a feature](#suggest-a-feature) first to gauge interest and gather feedback before proceeding with a PR. - -## Complete Waku Bounties - -To promote community contributions, we encourage members to complete bounties that benefit Waku and earn rewards while positively impacting the network. Join the bounty programme at: . - - -## Submit Security Bug Reports - -To improve Waku's security, we invite researchers to collaborate in identifying and resolving potential vulnerabilities and earn rewards for their efforts. To participate, please review our bug bounty programme's details and submit your reports at: . - -## Contribute to Waku Research - -Waku Research is an innovative R&D project dedicated to developing modular peer-to-peer protocols for communication that prioritise privacy, security, and censorship resistance. Explore Waku's ongoing challenges and experimental code at . \ No newline at end of file diff --git a/docs/guides/nodes-and-sdks.md b/docs/guides/getting-started.md similarity index 84% rename from docs/guides/nodes-and-sdks.md rename to docs/guides/getting-started.md index edc10d2..13980a8 100644 --- a/docs/guides/nodes-and-sdks.md +++ b/docs/guides/getting-started.md @@ -1,23 +1,25 @@ --- -title: Nodes and SDKs +title: Getting Started +hide_table_of_contents: true +slug: / --- :::caution -Waku has risks and limitations as it is still developing and preparing for extensive adoption. However, it is already demonstrating its capabilities by [powering various applications](/powered-by-waku). [Join our community](/community) to stay updated on our progress. +Waku has risks and limitations as it is still developing and preparing for extensive adoption. However, it is already demonstrating its capabilities by powering various applications. [Join our community](https://waku.org/community/) to stay updated on our progress. ::: Ready to integrate Waku into your application for private, secure, censorship-free communication? Explore the available SDKs and contribute by running a node. -## Run a Waku Node +## Run a Waku node The Waku Network is a decentralised, permissionless system where anyone can run nodes, use the network, and contribute to its support. | | Description | Documentation | | - | - | - | -| [nwaku](https://github.com/waku-org/nwaku) | Nim-based Waku implementation to run a standalone node and access the network (recommended) | [Run a Nwaku Node](/guides/run-nwaku-node) | +| [nwaku](https://github.com/waku-org/nwaku) | Nim-based Waku implementation to run a standalone node and access the network (recommended) | [Run a Nwaku Node](/guides/nwaku/run-node) | | [go-waku](https://github.com/waku-org/go-waku) | Golang-based Waku implementation to run a standalone node and access the network | COMING SOON | -## Integrate Using SDKs +## Integrate using SDKs Waku is implemented in multiple SDKs, allowing it to integrate with different languages and address various use cases efficiently. @@ -28,17 +30,16 @@ Waku is implemented in multiple SDKs, allowing it to integrate with different la | [go-waku](https://github.com/waku-org/go-waku) | Golang SDK designed for integration with Golang applications, includes C bindings for usage in C/C++, C#/Unity, Swift, and Kotlin | COMING SOON | | [waku-rust-bindings](https://github.com/waku-org/waku-rust-bindings) | Rust wrapper using `go-waku` bindings designed for integration in Rust applications | COMING SOON | -## Run on Mobile Devices +## Run on mobile devices Waku provides integrations tailored for mobile applications, enabling Waku to run efficiently on mobile devices. | | Description | Documentation | | - | - | - | -| [React Native](https://github.com/waku-org/waku-react-native) | React Native wrapper using `go-waku` bindings designed for native mobile integration | COMING SOON | | Swift (iOS) | `go-waku` bindings for Swift applications to seamlessly integrate Waku | COMING SOON | | Kotlin (Android) | `go-waku` bindings for Kotlin applications to seamlessly integrate Waku | COMING SOON | -## More Integrations +## More integrations | | Description | Documentation | | - | - | - | diff --git a/docs/guides/js-waku/configure-discovery.md b/docs/guides/js-waku/configure-discovery.md index 8d6c7e0..1d8b683 100644 --- a/docs/guides/js-waku/configure-discovery.md +++ b/docs/guides/js-waku/configure-discovery.md @@ -1,16 +1,17 @@ --- title: Bootstrap Nodes and Discover Peers +hide_table_of_contents: true --- -This guide provides detailed steps to bootstrap your your node using [Static Peers](/overview/concepts/static-peers) and discover peers in the Waku Network using [DNS Discovery](/overview/concepts/dns-discovery). +This guide provides detailed steps to bootstrap your your node using [Static Peers](/learn/concepts/static-peers) and discover peers in the Waku Network using [DNS Discovery](/learn/concepts/dns-discovery). :::tip -Until [node incentivisation](/overview/reference/research-in-progress#prevention-of-denial-of-service-dos-and-node-incentivisation) is in place, you should [operate extra nodes](/guides/nodes-and-sdks#run-a-waku-node) alongside the ones provided by the Waku Network. When running a node, we recommend using the [DNS Discovery and Static Peers](#configure-dns-discovery-and-static-peers) configuration to connect to both the Waku Network and your node. +Until [node incentivisation](/learn/research#prevention-of-denial-of-service-dos-and-node-incentivisation) is in place, you should [operate extra nodes](/#run-a-waku-node) alongside the ones provided by the Waku Network. When running a node, we recommend using the [DNS Discovery and Static Peers](#configure-dns-discovery-and-static-peers) configuration to connect to both the Waku Network and your node. ::: -## Default Bootstrap Method +## Default bootstrap method -The `@waku/sdk` package provides a built-in bootstrapping method that uses [DNS Discovery](/overview/concepts/dns-discovery) to locate peers from the `waku v2.prod` `ENR` tree. +The `@waku/sdk` package provides a built-in bootstrapping method that uses [DNS Discovery](/learn/concepts/dns-discovery) to locate peers from the `waku v2.prod` `ENR` tree. ```js import { createLightNode } from "@waku/sdk"; @@ -19,9 +20,9 @@ import { createLightNode } from "@waku/sdk"; const node = await createLightNode({ defaultBootstrap: true }); ``` -## Configure Static Peers +## Configure static peers -To bootstrap a node using [static peers](/overview/concepts/static-peers), first install the `@libp2p/bootstrap` package: +To bootstrap a node using [static peers](/learn/concepts/static-peers), first install the `@libp2p/bootstrap` package: ```mdx-code-block import Tabs from '@theme/Tabs'; @@ -84,9 +85,9 @@ const node = await createLightNode({ For local development using a `nwaku` node, use a `ws` address instead of `wss`. Remember that this setup is functional only when your web server is running locally. ::: -## Configure DNS Discovery +## Configure DNS discovery -To bootstrap a node using [DNS Discovery](/overview/concepts/dns-discovery), first install the `@waku/dns-discovery` package: +To bootstrap a node using [DNS Discovery](/learn/concepts/dns-discovery), first install the `@waku/dns-discovery` package: @@ -152,9 +153,9 @@ const node = await createLightNode({ }); ``` -## Configure DNS Discovery and Static Peers +## Configure DNS discovery and static peers -You can also bootstrap your node using [DNS Discovery](/overview/concepts/dns-discovery) and [Static Peers](/overview/concepts/static-peers) simultaneously: +You can also bootstrap your node using [DNS Discovery](/learn/concepts/dns-discovery) and [Static Peers](/learn/concepts/static-peers) simultaneously: ```js import { createLightNode } from "@waku/sdk"; diff --git a/docs/guides/js-waku/debug-waku-dapp.md b/docs/guides/js-waku/debug-waku-dapp.md index 81ba5de..149ab09 100644 --- a/docs/guides/js-waku/debug-waku-dapp.md +++ b/docs/guides/js-waku/debug-waku-dapp.md @@ -1,14 +1,15 @@ --- title: Debug Your Waku DApp and WebSocket +hide_table_of_contents: true --- -This guide provides detailed steps to enable and use debug logs to troubleshoot your Waku DApp, whether in a NodeJS or browser environment and check your WebSocket connections in [nwaku](/guides/run-nwaku-node). +This guide provides detailed steps to enable and use debug logs to troubleshoot your Waku DApp, whether in a NodeJS or browser environment and check your WebSocket connections in [nwaku](/guides/nwaku/run-node). -## Enabling Debug Logs +## Enabling debug logs When resolving issues in your Waku DApp, debug logs can be helpful. The `@waku/sdk` and `libp2p` packages use the debug tool to handle and show logs that help you debug effectively. -### NodeJS Environments +### NodeJS environments To enable debug logs for `@waku/sdk` on NodeJS, you must set the `DEBUG` environment variable. To only enable debug logs for `@waku/sdk`: @@ -28,7 +29,7 @@ To enable debug logs for all components: export DEBUG=* ``` -### Browser Environments +### Browser environments To view debug logs in your browser's console, modify the local storage and add the `debug` key. Here are guides for various modern browsers: @@ -42,9 +43,9 @@ To view debug logs in your browser's console, modify the local storage and add t | `debug` | `waku*,libp2p*` | Enables `@waku/sdk` and `libp2p` debug logs | | `debug` | `*` | Enables all debug logs | -## Checking WebSocket Setup +## Checking WebSocket setup -[Nwaku](/guides/run-nwaku-node) provides native support for WebSocket (`ws`) and WebSocket Secure (`wss`) protocols. These are the only [transports](/overview/concepts/transports) supported for connecting to the Waku Network via browsers. +[Nwaku](/guides/nwaku/run-node) provides native support for WebSocket (`ws`) and WebSocket Secure (`wss`) protocols. These are the only [transports](/learn/concepts/transports) supported for connecting to the Waku Network via browsers. It's important to note that browsers impose certain limitations on WebSocket usage: @@ -54,7 +55,7 @@ It's important to note that browsers impose certain limitations on WebSocket usa If you encounter difficulties when connecting to a remote node using `wss`, follow these steps: -### Try Websocat for Connection +### Try Websocat for connection Attempt to connect using [websocat](https://github.com/vi/websocat), a tool for WebSocket interactions. Test the WebSocket port using the command: @@ -72,7 +73,7 @@ $ websocat -v wss://nwakunode.com:1234 The connection works if the `[INFO websocat::ws_client_peer] Connected to ws` log entry appears. If not, [check that the certificate is valid](#check-certificate-validity) -### Check Certificate Validity +### Check certificate validity Verify the certificate's validity by passing the `-k` or `--insecure` flag to handle invalid certificates in `websocat`: @@ -82,7 +83,7 @@ websocat -v -k wss://nwakunode.com:1234 If this works, the certificate's invalidity is the problem, and you should investigate the cause of the error if not, [check if the WebSocket port is accessible](#check-websocket-port-accessibility). -### Check WebSocket Port Accessibility +### Check WebSocket port accessibility Use `telnet` or another networking tool to verify if the WebSocket port is open and accessible. For example, if the multiaddr is `/dns4/nwakunode.com/tcp/1234/wss/p2p/16...`, use the command: diff --git a/docs/guides/js-waku/index.md b/docs/guides/js-waku/index.md index 0f316c9..47f71d5 100644 --- a/docs/guides/js-waku/index.md +++ b/docs/guides/js-waku/index.md @@ -1,5 +1,6 @@ --- title: JavaScript Waku SDK +hide_table_of_contents: true --- The [JavaScript Waku SDK](https://github.com/waku-org/js-waku) (`@waku/sdk`) provides a TypeScript implementation of the [Waku protocol](/) designed for web browser environments. Developers can seamlessly integrate Waku functionalities into web applications, enabling efficient communication and collaboration among users using the `@waku/sdk` package. @@ -36,7 +37,7 @@ You can also use the `@waku/sdk` package via a CDN without installing it on your import * as waku from "https://unpkg.com/@waku/sdk@latest/bundle/index.js"; ``` -## Message Structure +## Message structure We recommend creating a message structure for your application using [Protocol Buffers](https://protobuf.dev/) for the following reasons: @@ -76,26 +77,26 @@ import "https://cdn.jsdelivr.net/npm/protobufjs@latest/dist/protobuf.min.js"; ``` -## Getting Started +## Getting started Have a look at the quick start guide and comprehensive tutorials to learn how to build applications using `@waku/sdk`: | Guide | Description | | - | - | -| [Send and Receive Messages Using Light Push and Filter](/guides/js-waku/light-send-receive) | Learn how to send and receive messages on light nodes using the [Light Push](/overview/concepts/protocols#light-push) and [Filter](/overview/concepts/protocols#filter) protocols | -| [Retrieve Messages Using Store Protocol](/guides/js-waku/store-retrieve-messages) | Learn how to retrieve and filter historical messages on light nodes using the [Store protocol](/overview/concepts/protocols#store) | +| [Send and Receive Messages Using Light Push and Filter](/guides/js-waku/light-send-receive) | Learn how to send and receive messages on light nodes using the [Light Push](/learn/concepts/protocols#light-push) and [Filter](/learn/concepts/protocols#filter) protocols | +| [Retrieve Messages Using Store Protocol](/guides/js-waku/store-retrieve-messages) | Learn how to retrieve and filter historical messages on light nodes using the [Store protocol](/learn/concepts/protocols#store) | | [Build React DApps Using @waku/react](/guides/js-waku/use-waku-react) | Learn how to use the [@waku/react](https://www.npmjs.com/package/@waku/react) package seamlessly integrate `@waku/sdk` into a React application | | [Scaffold DApps Using @waku/create-app](/guides/js-waku/use-waku-create-app) | Learn how to use the [@waku/create-app](https://www.npmjs.com/package/@waku/create-app) package to bootstrap your next `@waku/sdk` project from various example templates | -| [Bootstrap Nodes and Discover Peers](/guides/js-waku/configure-discovery) | Learn how to bootstrap your node using [Static Peers](/overview/concepts/static-peers) and discover peers using [DNS Discovery](/overview/concepts/dns-discovery) | +| [Bootstrap Nodes and Discover Peers](/guides/js-waku/configure-discovery) | Learn how to bootstrap your node using [Static Peers](/learn/concepts/static-peers) and discover peers using [DNS Discovery](/learn/concepts/dns-discovery) | | [Run @waku/sdk in a NodeJS Application](/guides/js-waku/run-waku-nodejs) | Learn our suggested approach for using the `@waku/sdk` package within a NodeJS application | -| [Debug Your Waku DApp and WebSocket](/guides/js-waku/debug-waku-dapp) | Learn how to troubleshoot your Waku DApp using debug logs and check [WebSocket](/overview/concepts/transports) connections in [nwaku](/guides/run-nwaku-node) | -| [Manage Your Filter Subscriptions](/guides/js-waku/manage-filter) | Learn how to manage [filter subscriptions](/overview/concepts/protocols#filter) and handle node disconnections in your application | +| [Debug Your Waku DApp and WebSocket](/guides/js-waku/debug-waku-dapp) | Learn how to troubleshoot your Waku DApp using debug logs and check [WebSocket](/learn/concepts/transports) connections in [nwaku](/guides/nwaku/run-node) | +| [Manage Your Filter Subscriptions](/guides/js-waku/manage-filter) | Learn how to manage [filter subscriptions](/learn/concepts/protocols#filter) and handle node disconnections in your application | :::tip -Until [node incentivisation](/overview/reference/research-in-progress#prevention-of-denial-of-service-dos-and-node-incentivisation) is in place, you should [operate extra nodes](/guides/nodes-and-sdks#run-a-waku-node) alongside the ones provided by the Waku Network. When running a node, we recommend using the [DNS Discovery and Static Peers](/guides/js-waku/configure-discovery#configure-dns-discovery-and-static-peers) configuration to connect to both the Waku Network and your node. +Until [node incentivisation](/learn/research#prevention-of-denial-of-service-dos-and-node-incentivisation) is in place, you should [operate extra nodes](/#run-a-waku-node) alongside the ones provided by the Waku Network. When running a node, we recommend using the [DNS Discovery and Static Peers](/guides/js-waku/configure-discovery#configure-dns-discovery-and-static-peers) configuration to connect to both the Waku Network and your node. ::: -## Get Help and Report Issues +## Get help and report issues To engage in general discussions, seek assistance, or stay updated with the latest news, visit the `#support` and `#js-waku-contribute` channels on the [Waku Discord](https://discord.waku.org). diff --git a/docs/guides/js-waku/light-send-receive.md b/docs/guides/js-waku/light-send-receive.md index ec2ed51..7cbb728 100644 --- a/docs/guides/js-waku/light-send-receive.md +++ b/docs/guides/js-waku/light-send-receive.md @@ -1,12 +1,13 @@ --- title: Send and Receive Messages Using Light Push and Filter +hide_table_of_contents: true --- -This guide provides detailed steps to start using the `@waku/sdk` package by setting up a [Light Node](/overview/reference/glossary#light-node) to send messages using the [Light Push protocol](/overview/concepts/protocols#light-push), and receive messages using the [Filter protocol](/overview/concepts/protocols#filter). Have a look at the [installation guide](/guides/js-waku/#installation) for steps on adding `@waku/sdk` to your project. +This guide provides detailed steps to start using the `@waku/sdk` package by setting up a [Light Node](/learn/glossary#light-node) to send messages using the [Light Push protocol](/learn/concepts/protocols#light-push), and receive messages using the [Filter protocol](/learn/concepts/protocols#filter). Have a look at the [installation guide](/guides/js-waku/#installation) for steps on adding `@waku/sdk` to your project. -## Create a Light Node +## Create a light node -Use the `createLightNode()` function to create a [Light Node](/overview/reference/glossary#light-node) and interact with the Waku Network: +Use the `createLightNode()` function to create a [Light Node](/learn/glossary#light-node) and interact with the Waku Network: ```js import { createLightNode } from "@waku/sdk"; @@ -23,7 +24,7 @@ await node.start(); When the `defaultBootstrap` option is set to `true`, your node will be bootstrapped using the [default bootstrap method](/guides/js-waku/configure-discovery#default-bootstrap-method). Have a look at the [Bootstrap Nodes and Discover Peers](/guides/js-waku/configure-discovery) guide to learn more methods to bootstrap nodes. ::: -## Connect to Remote Peers +## Connect to remote peers Use the `waitForRemotePeer()` function to wait for the node to connect with peers on the Waku Network: @@ -34,7 +35,7 @@ import { waitForRemotePeer } from "@waku/sdk"; await waitForRemotePeer(node); ``` -The `protocols` option allows you to specify the [protocols](/overview/concepts/protocols) that the remote peers should have enabled: +The `protocols` option allows you to specify the [protocols](/learn/concepts/protocols) that the remote peers should have enabled: ```js import { waitForRemotePeer, Protocols } from "@waku/sdk"; @@ -46,9 +47,9 @@ await waitForRemotePeer(node, [ ]); ``` -## Choose a Content Topic +## Choose a content topic -[Choose a content topic](/overview/concepts/content-topics) for your application and create a message `encoder` and `decoder`: +[Choose a content topic](/learn/concepts/content-topics) for your application and create a message `encoder` and `decoder`: ```js import { createEncoder, createDecoder } from "@waku/sdk"; @@ -74,7 +75,7 @@ const encoder = createEncoder({ In this example, users send and receive messages on a shared content topic. However, real applications may have users broadcasting messages while others listen or only have 1:1 exchanges. Waku supports all these use cases. ::: -## Create a Message Structure +## Create a message structure Create your application's message structure using [Protobuf's valid message](https://github.com/protobufjs/protobuf.js#usage) fields: @@ -92,7 +93,7 @@ const ChatMessage = new protobuf.Type("ChatMessage") Have a look at the [Protobuf installation](/guides/js-waku/#message-structure) guide for adding the `protobufjs` package to your project. ::: -## Send Messages Using Light Push +## Send messages using light push To send messages over the Waku Network using the `Light Push` protocol, create a new message object and use the `lightPush.send()` function: @@ -113,7 +114,7 @@ await node.lightPush.send(encoder, { }); ``` -## Receive Messages Using Filter +## Receive messages using filter To receive messages using the `Filter` protocol, create a callback function for message processing, then use the `filter.subscribe()` function to subscribe to a `content topic`: diff --git a/docs/guides/js-waku/manage-filter.md b/docs/guides/js-waku/manage-filter.md index b5acc5a..0feafff 100644 --- a/docs/guides/js-waku/manage-filter.md +++ b/docs/guides/js-waku/manage-filter.md @@ -1,8 +1,9 @@ --- title: Manage Your Filter Subscriptions +hide_table_of_contents: true --- -This guide provides detailed steps to manage [Filter](/overview/concepts/protocols#filter) subscriptions and handle node disconnections in your application. Have a look at the [Filter guide](/guides/js-waku/light-send-receive) for receiving messages with the `Light Push` and `Filter` protocol. +This guide provides detailed steps to manage [Filter](/learn/concepts/protocols#filter) subscriptions and handle node disconnections in your application. Have a look at the [Filter guide](/guides/js-waku/light-send-receive) for receiving messages with the `Light Push` and `Filter` protocol. ## Overview @@ -14,7 +15,7 @@ import FilterPingFlow from "@site/diagrams/_filter-ping-flow.md"; ``` -## Pinging Filter Subscriptions +## Pinging filter subscriptions The `@waku/sdk` package provides a `Filter.ping()` function to ping subscriptions and check for an active connection. To begin, create a `Filter` subscription: @@ -51,6 +52,10 @@ const pingAndReinitiateSubscription = async () => { await pingAndReinitiateSubscription(); ``` +:::info +Pings will fail when there are temporary network degradations or reachability issues. This does not mean that the underlying connection has been closed. +::: + :::success Congratulations! You have successfully managed your `Filter` subscriptions to handle node disconnections in your application. ::: \ No newline at end of file diff --git a/docs/guides/js-waku/run-waku-nodejs.md b/docs/guides/js-waku/run-waku-nodejs.md index 95f8993..0346974 100644 --- a/docs/guides/js-waku/run-waku-nodejs.md +++ b/docs/guides/js-waku/run-waku-nodejs.md @@ -1,33 +1,34 @@ --- title: "Run @waku/sdk in a NodeJS Application" +hide_table_of_contents: true --- While the `@waku/sdk` package is primarily designed for browser environments, you can use it in a NodeJS application. However, there are certain limitations and considerations to keep in mind. This guide provides a comprehensive overview of using `@waku/sdk` in NodeJS. ## Limitations -### API Compatibility +### API compatibility `@waku/sdk` prioritises browser compatibility, avoiding NodeJS APIs for simpler bundling. This design choice enhances browser API compatibility but sacrifices NodeJS optimisation. While many browser APIs work in NodeJS, they might need better optimisation. -### Protocol Implementation +### Protocol implementation -`@waku/sdk` focuses on the client side of the [Request/Response protocol](/overview/concepts/network-domains#requestresponse-domain). We'll have to replicate all the functionalities added to [nwaku](/guides/run-nwaku-node) to implement extra features. +`@waku/sdk` focuses on the client side of the [Request/Response protocol](/learn/concepts/network-domains#requestresponse-domain). We'll have to replicate all the functionalities added to [nwaku](/guides/nwaku/run-node) to implement extra features. -### Codebase Complexity +### Codebase complexity `@waku/sdk` aims to provide optimal default for the browser, striking a balance between browser and NodeJS compatibility while ensuring simplicity will add complexity. -### Browser-Specific Protocols +### Browser-specific protocols -Certain features in `@waku/sdk` are tailored for browsers and might not translate seamlessly to NodeJS. For example, only `WebSocket` is supported in the browser, whereas a NodeJS application can benefit from using [transport methods](/overview/concepts/transports) like `TCP`. +Certain features in `@waku/sdk` are tailored for browsers and might not translate seamlessly to NodeJS. For example, only `WebSocket` is supported in the browser, whereas a NodeJS application can benefit from using [transport methods](/learn/concepts/transports) like `TCP`. -`@waku/sdk` default peer management caters to the browser's ephemeral nature, which is different for NodeJS. This is why [DNS Discovery](/overview/concepts/dns-discovery) and [Peer Exchange](/overview/concepts/peer-exchange) are the default discovery mechanisms for the browser but not for NodeJS and desktop applications. +`@waku/sdk` default peer management caters to the browser's ephemeral nature, which is different for NodeJS. This is why [DNS Discovery](/learn/concepts/dns-discovery) and [Peer Exchange](/learn/concepts/peer-exchange) are the default discovery mechanisms for the browser but not for NodeJS and desktop applications. ## Recommendations Before using `@waku/sdk` in a NodeJS environment, take into account these limitations. For a more optimised solution, we recommend [running nwaku in a Docker container](/guides/nwaku/run-docker) and consuming its [REST API](https://waku-org.github.io/waku-rest-api/). -## Future Developments +## Future developments -There are plans to release a NodeJS package based on [nwaku](/guides/run-nwaku-node) to streamline the process of using Waku Network features in NodeJS applications. You can track the progress and updates here: . \ No newline at end of file +There are plans to release a NodeJS package based on [nwaku](/guides/nwaku/run-node) to streamline the process of using Waku Network features in NodeJS applications. You can track the progress and updates here: . \ No newline at end of file diff --git a/docs/guides/js-waku/store-retrieve-messages.md b/docs/guides/js-waku/store-retrieve-messages.md index e483ef9..336f8cb 100644 --- a/docs/guides/js-waku/store-retrieve-messages.md +++ b/docs/guides/js-waku/store-retrieve-messages.md @@ -1,10 +1,11 @@ --- title: Retrieve Messages Using Store Protocol +hide_table_of_contents: true --- -This guide provides detailed steps to create a Light Node for retrieving and filtering historical messages using the [Store protocol](/overview/concepts/protocols#store). +This guide provides detailed steps to create a Light Node for retrieving and filtering historical messages using the [Store protocol](/learn/concepts/protocols#store). -## Create a Light Node +## Create a light node Use the `createLightNode()` function to create a Light Node and interact with the Waku Network: @@ -16,7 +17,7 @@ const node = await createLightNode({ defaultBootstrap: true }); await node.start(); ``` -## Connect to Store Peers +## Connect to store peers Use the `waitForRemotePeer()` function to wait for the node to connect with Store peers: @@ -27,9 +28,9 @@ import { waitForRemotePeer, Protocols } from "@waku/sdk"; await waitForRemotePeer(node, [Protocols.Store]); ``` -## Choose a Content Topic +## Choose a content topic -[Choose a content topic](/overview/concepts/content-topics) for filtering the messages to retrieve and create a message `decoder`: +[Choose a content topic](/learn/concepts/content-topics) for filtering the messages to retrieve and create a message `decoder`: ```js import { createDecoder } from "@waku/sdk"; @@ -41,7 +42,7 @@ const contentTopic = "/store-guide/1/message/proto"; const decoder = createDecoder(contentTopic); ``` -## Retrieve Messages +## Retrieve messages `@waku/sdk` provides the `queryWithOrderedCallback()` and `queryGenerator()` functions for querying `Store` nodes and retrieving historical or missed messages. The responses from `Store` nodes are paginated and require you to process each page sequentially. @@ -99,7 +100,7 @@ for await (const messagesPromises of storeQuery) { The `queryGenerator()` function always returns the oldest messages in a page first. ::: -## Store Query Options +## Store query options ### `pageDirection` diff --git a/docs/guides/js-waku/use-waku-create-app.md b/docs/guides/js-waku/use-waku-create-app.md index 4d46191..9dce2e9 100644 --- a/docs/guides/js-waku/use-waku-create-app.md +++ b/docs/guides/js-waku/use-waku-create-app.md @@ -1,5 +1,6 @@ --- title: "Scaffold DApps Using @waku/create-app" +hide_table_of_contents: true --- This guide provides detailed steps to bootstrap your next `@waku/sdk` project from [various example templates](https://github.com/waku-org/js-waku-examples/tree/master/examples) using the [@waku/create-app](https://www.npmjs.com/package/@waku/create-app) package. @@ -38,7 +39,7 @@ Next, select a template to initialise your app from: If you have previously installed `@waku/create-app` globally, we recommend uninstalling the package to ensure that `npx` always uses the latest version. ::: -## Contributing New Templates +## Contributing new templates We welcome and appreciate the contributions of templates for the `@waku/create-app` package. To contribute a template, please follow these steps: diff --git a/docs/guides/js-waku/use-waku-react.md b/docs/guides/js-waku/use-waku-react.md index 94a48ee..b8f7ff4 100644 --- a/docs/guides/js-waku/use-waku-react.md +++ b/docs/guides/js-waku/use-waku-react.md @@ -1,10 +1,11 @@ --- title: "Build React DApps Using @waku/react" +hide_table_of_contents: true --- The [@waku/react](https://www.npmjs.com/package/@waku/react) package provides components and UI adapters to integrate `@waku/sdk` into React applications effortlessly. This guide provides detailed steps for using `@waku/react` in your project. -## Install the Dependencies +## Install the dependencies First, set up a project using any [production-grade React framework](https://react.dev/learn/start-a-new-react-project) or an existing React application. For this guide, we will create a boilerplate using [ViteJS](https://vitejs.dev/guide/): @@ -49,7 +50,7 @@ yarn add @waku/react @waku/sdk protobufjs -## Initialise the Waku Provider +## Initialise the Waku provider In the `main.jsx` file, which serves as the entry point for a React app, we will set up the `LightNodeProvider` [context provider](https://react.dev/reference/react/createContext#provider) to wrap the entire application within the Waku provider. Import the following on top of your file: @@ -69,7 +70,7 @@ ReactDOM.createRoot(document.getElementById('root')).render( ) ``` -Next, create and start a [Light Node](/overview/reference/glossary#light-node) using the `useWaku()` function within the `App.jsx` file: +Next, create and start a [Light Node](/learn/glossary#light-node) using the `useWaku()` function within the `App.jsx` file: ```js title="src/App.jsx" import { useWaku } from "@waku/react"; @@ -84,7 +85,7 @@ function App() { } ``` -## Build the Application Interface +## Build the application interface Let's build a user interface for sending messages and viewing past messages, modify the `App.jsx` file with the following code block: @@ -201,7 +202,7 @@ Next, modify the `App.css` file with the following code block: } ``` -## Send Messages Using Light Push +## Send messages using light push To send messages in our application, we need to modify the `sendMessage()` function to serialize user input into our Protobuf structure and [push it to the network](/guides/js-waku/light-send-receive#send-messages-using-light-push) using the `useLightPush()` function: @@ -238,7 +239,7 @@ function App() { } ``` -## Receive Messages Using Filter +## Receive messages using filter To display messages in our application, we need to use the `useFilterMessages()` function to create a [Filter subscription](/guides/js-waku/light-send-receive/#receive-messages-using-filter), receive incoming messages, and render them in our interface: @@ -259,7 +260,7 @@ function App() { } ``` -## Retrieve Messages Using Store +## Retrieve messages using store To display messages from the past, we need to retrieve them from the [Store protocol](/guides/js-waku/store-retrieve-messages) using the `useStoreMessages()` function when our application initialises and then render them alongside newly received messages: diff --git a/docs/guides/nwaku/build-source.md b/docs/guides/nwaku/build-source.md index 773814b..940512f 100644 --- a/docs/guides/nwaku/build-source.md +++ b/docs/guides/nwaku/build-source.md @@ -1,5 +1,6 @@ --- title: Build Nwaku from Source +hide_table_of_contents: true --- This guide provides detailed steps to build a `nwaku` node from the source code to access the latest development version or a specific commit or release of `nwaku`. For your convenience, you may want to [download a pre-compiled binary](https://github.com/waku-org/nwaku/tags) instead. @@ -21,7 +22,7 @@ import TabItem from '@theme/TabItem'; -```bash +```shell sudo apt-get install build-essential git libpq5 curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh ``` @@ -29,7 +30,7 @@ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -```bash +```shell sudo dnf install @development-tools git libpq-devel curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh ``` @@ -37,7 +38,7 @@ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -```bash +```shell # Using your favoured AUR helper sudo [AUR HELPER] -S base-devel git postgresql-libs curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh @@ -46,7 +47,7 @@ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -```bash +```shell brew install cmake git postgresql@15 rustup-init # Create a symbolic link to libpq.5.dylib in /usr/local/lib/ sudo mkdir -p /usr/local/lib/ @@ -56,11 +57,11 @@ sudo ln -s /opt/homebrew/opt/postgresql@15/lib/libpq.5.dylib /usr/local/lib/libp -## Clone the Repository +## Clone the repository Get the source code from the GitHub repository. The default branch is `master`, the release candidate for major updates. -```bash +```shell git clone https://github.com/waku-org/nwaku cd nwaku ``` @@ -69,25 +70,25 @@ cd nwaku You can use `git tag -l` to check specific version tags. ::: -## Build the Binary +## Build the binary Build the `nwaku` binary: -```bash +```shell make wakunode2 ``` The first `make` invocation updates to all Git submodules. After each `git pull`, run `make update` to keep the submodules updated in the future. -```bash +```shell make update ``` -## Run the Binary +## Run the binary Nwaku will create the `wakunode2` binary in the `./build/` directory. -```bash +```shell # Run with default configuration ./build/wakunode2 @@ -97,19 +98,19 @@ Nwaku will create the `wakunode2` binary in the `./build/` directory. To learn more about running nwaku, have a look at these guides: -- [Run a Nwaku Node](/guides/run-nwaku-node#run-the-node) +- [Run a Nwaku Node](/guides/nwaku/run-node#run-the-node) - [Run Nwaku in a Docker Container](/guides/nwaku/run-docker) - [Run Nwaku with Docker Compose](/guides/nwaku/run-docker-compose) -- [Node Configuration Methods](/guides/reference/node-config-methods) +- [Node Configuration Methods](/guides/nwaku/config-methods) -## Run Test Suite +## Run test suite Run the tests for Waku: -```bash +```shell make test ``` :::tip Congratulations! -You have successfully built the `nwaku` binary from the source code. Have a look at the [Nwaku Configuration Examples](/guides/nwaku/configure-nwaku) guide to learn how to configure `nwaku` for different use cases. +You have successfully built the `nwaku` binary from the source code. Have a look at the [Node Configuration Examples](/guides/nwaku/configure-nwaku) guide to learn how to configure `nwaku` for different use cases. ::: \ No newline at end of file diff --git a/docs/guides/reference/node-config-methods.md b/docs/guides/nwaku/config-methods.md similarity index 85% rename from docs/guides/reference/node-config-methods.md rename to docs/guides/nwaku/config-methods.md index 74c3698..546cc97 100644 --- a/docs/guides/reference/node-config-methods.md +++ b/docs/guides/nwaku/config-methods.md @@ -1,5 +1,6 @@ --- title: Node Configuration Methods +hide_table_of_contents: true --- Waku nodes can be configured using a combination of the following methods: @@ -13,33 +14,33 @@ Waku nodes can be configured using a combination of the following methods: Take note of the precedence order: Each configuration method overrides the one below it (e.g., command line options override environment variables and configuration files). ::: -## Command Line Options +## Command line options -Node configuration is primarily done using command line options, which override other methods. Specify [configuration options](/guides/reference/node-config-options) by providing them in this format after the binary name: +Node configuration is primarily done using command line options, which override other methods. Specify [configuration options](/guides/nwaku/config-options) by providing them in this format after the binary name: -```bash +```shell ./build/wakunode2 --tcp-port=65000 ``` When running your node with Docker, provide the command line options after the image name in this format: -```bash +```shell docker run statusteam/nim-waku --tcp-port=65000 ``` -## Environment Variables +## Environment variables Nodes can be configured using environment variables by prefixing the variable name with `WAKUNODE2_` and using the configuration option in [SCREAMING_SNAKE_CASE](https://en.wiktionary.org/wiki/screaming_snake_case) format. To set the `tcp-port` configuration, the `wakunode2` binary should be called in this format: -```bash +```shell WAKUNODE2_TCP_PORT=65000 ./build/wakunode2 ``` When running your node with Docker, start the node using the `-e` command option: -```bash +```shell docker run -e "WAKUNODE2_TCP_PORT=65000" statusteam/nim-waku ``` @@ -47,7 +48,7 @@ docker run -e "WAKUNODE2_TCP_PORT=65000" statusteam/nim-waku This is the second configuration method in order of precedence. [Command Line Options](#command-line-options) override environment variables. ::: -## Configuration Files +## Configuration files Nodes can be configured using a configuration file following the [TOML](https://toml.io/en/) format: @@ -58,15 +59,15 @@ topic = ["/waku/2/default-waku/proto"] metrics-logging = false ``` -The `config-file` [configuration option](/guides/reference/node-config-options) lets you specify the configuration file path: +The `config-file` [configuration option](/guides/nwaku/config-options) lets you specify the configuration file path: -```bash +```shell ./build/wakunode2 --config-file=[TOML CONFIGURATION FILE] ``` You can also specify the configuration file via environment variables: -```bash +```shell # Using environment variables WAKUNODE2_CONFIG_FILE=[TOML CONFIGURATION FILE] ./build/wakunode2 @@ -78,7 +79,7 @@ docker run -e "WAKUNODE2_CONFIG_FILE=[TOML CONFIGURATION FILE]" statusteam/nim-w This is the third configuration method in order of precedence. [Command Line Options](#command-line-options) and [Environment Variables](#environment-variables) override configuration files. ::: -## Default Configuration Values +## Default configuration values The default configuration is used when no other options are specified. By default, a `nwaku` node does the following: @@ -89,12 +90,12 @@ The default configuration is used when no other options are specified. By defaul - Enable the `Relay` protocol for relaying messages. - Enable the `Store` protocol as a client, allowing it to query peers for historical messages but not store any message itself. -To see the default values of all [configuration options](/guides/reference/node-config-options), run `wakunode2 --help`: +To see the default values of all [configuration options](/guides/nwaku/config-options), run `wakunode2 --help`: -```bash +```shell ./build/wakunode2 --help ``` :::tip -To explore the available node configuration options, have a look at the [Node Configuration Options](/guides/reference/node-config-options) guide. +To explore the available node configuration options, have a look at the [Node Configuration Options](/guides/nwaku/config-options) guide. ::: \ No newline at end of file diff --git a/docs/guides/reference/node-config-options.md b/docs/guides/nwaku/config-options.md similarity index 95% rename from docs/guides/reference/node-config-options.md rename to docs/guides/nwaku/config-options.md index 5e9c16b..d40dd9b 100644 --- a/docs/guides/reference/node-config-options.md +++ b/docs/guides/nwaku/config-options.md @@ -1,24 +1,25 @@ --- title: Node Configuration Options +hide_table_of_contents: true --- Here are the available node configuration options, along with their default values and descriptions: -## Application-Level Config +## Application-level config | Name | Default Value | Description | | - | - | - | | `config-file` | | Loads configuration from a TOML file (cmd-line parameters take precedence) | | `protected-topic` | `newSeq[ProtectedTopic](0)` | Topics and its public key to be used for message validation, topic:pubkey. Argument may be repeated | -## Log Config +## Log config | Name | Default Value | Description | | - | - | - | | `log-level` | `logging.LogLevel.INFO` | Sets the log level for process. Supported levels: TRACE, DEBUG, INFO, NOTICE, WARN, ERROR or FATAL | | `log-format` | `logging.LogFormat.TEXT` | Specifies what kind of logs should be written to stdout. Supported formats: TEXT, JSON | -## General Node Config +## General node config | Name | Default Value | Description | | - | - | - | @@ -36,7 +37,7 @@ Here are the available node configuration options, along with their default valu | `peer-store-capacity` | | Maximum stored peers in the peerstore | | `peer-persistence` | `false` | Enable peer persistence | -## DNS Addrs Config +## DNS addrs config | Name | Default Value | Description | | - | - | - | @@ -44,7 +45,7 @@ Here are the available node configuration options, along with their default valu | `dns-addrs-name-server` | `["1.1.1.1", "1.0.0.1"]` | DNS name server IPs to query for DNS multiaddrs resolution. Argument may be repeated | | `dns4-domain-name` | | The domain name resolving to the node's public IPv4 address | -## Relay Config +## Relay config | Name | Default Value | Description | | - | - | - | @@ -69,7 +70,7 @@ Here are the available node configuration options, along with their default valu | `pubsub-topic` | | Default pubsub topic to subscribe to. Argument may be repeated | | `content-topic` | | Default content topic to subscribe to. Argument may be repeated | -## Store and Message Store Config +## Store and message store config | Name | Default Value | Description | | - | - | - | @@ -80,7 +81,7 @@ Here are the available node configuration options, along with their default valu | `store-message-db-vacuum` | `false` | Enable database vacuuming at start. Only supported by SQLite database engine | | `store-message-db-migration` | `true` | Enable database migration at start | -## Filter Config +## Filter config | Name | Default Value | Description | | - | - | - | @@ -88,14 +89,14 @@ Here are the available node configuration options, along with their default valu | `filternode` | | Peer multiaddr to request content filtering of messages | | `filter-timeout` | `14400 # 4 hours` | Timeout for filter node in seconds | -## Light Push Config +## Light push config | Name | Default Value | Description | | - | - | - | | `lightpush` | `false` | Enable lightpush protocol: true\|false | | `lightpushnode` | | Peer multiaddr to request lightpush of published messages | -## JSON-RPC Config +## JSON-RPC config | Name | Default Value | Description | | - | - | - | @@ -105,7 +106,7 @@ Here are the available node configuration options, along with their default valu | `rpc-admin` | `false` | Enable access to JSON-RPC Admin API: true\|false | | `rpc-private` | `false` | Enable access to JSON-RPC Private API: true\|false | -## REST HTTP Config +## REST HTTP config | Name | Default Value | Description | | - | - | - | @@ -116,7 +117,7 @@ Here are the available node configuration options, along with their default valu | `rest-admin` | `false` | Enable access to REST HTTP Admin API: true\|false | | `rest-private` | `false` | Enable access to REST HTTP Private API: true\|false | -## Metrics Config +## Metrics config | Name | Default Value | Description | | - | - | - | @@ -125,7 +126,7 @@ Here are the available node configuration options, along with their default valu | `metrics-server-port` | `8008` | Listening HTTP port of the metrics server | | `metrics-logging` | `true` | Enable metrics logging: true\|false | -## DNS Discovery Config +## DNS discovery config | Name | Default Value | Description | | - | - | - | @@ -133,7 +134,7 @@ Here are the available node configuration options, along with their default valu | `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 | -## Discv5 Config +## Discv5 config | Name | Default Value | Description | | - | - | - | @@ -145,14 +146,14 @@ Here are the available node configuration options, along with their default valu | `discv5-bucket-ip-limit` | `2` | Maximum amount of nodes with the same IP in discv5 routing table buckets | | `discv5-bits-per-hop` | `1` | Kademlia's b variable, increase for less hops per lookup | -## Waku Peer Exchange Config +## Waku peer exchange config | Name | Default Value | Description | | - | - | - | | `peer-exchange` | `false` | Enable waku peer exchange protocol (responder side): true\|false | | `peer-exchange-node` | | Peer multiaddr to send peer exchange requests to. (enables peer exchange protocol requester side) | -## WebSocket Config +## WebSocket config | Name | Default Value | Description | | - | - | - | @@ -163,5 +164,5 @@ Here are the available node configuration options, along with their default valu | `websocket-secure-cert-path` | | Secure websocket Certificate path: '/path/to/cert.txt' | :::tip -To configure your node using the provided configuration options, have a look at the [Node Configuration Methods](/guides/reference/node-config-methods) guide. +To configure your node using the provided configuration options, have a look at the [Node Configuration Methods](/guides/nwaku/config-methods) guide. ::: \ No newline at end of file diff --git a/docs/guides/nwaku/configure-discovery.md b/docs/guides/nwaku/configure-discovery.md index 9789cbb..38f2de1 100644 --- a/docs/guides/nwaku/configure-discovery.md +++ b/docs/guides/nwaku/configure-discovery.md @@ -1,5 +1,6 @@ --- title: Configure Peer Discovery +hide_table_of_contents: true --- This guide provides detailed steps to configure a `nwaku` node to discover and connect with peers in the Waku Network. @@ -8,11 +9,11 @@ This guide provides detailed steps to configure a `nwaku` node to discover and c You can configure a `nwaku` node to use multiple peer discovery mechanisms simultaneously. ::: -## Configure Static Peers +## Configure static peers -You can provide [static peers](/overview/concepts/static-peers) to a `nwaku` node during startup using the `staticnode` configuration option. To connect to multiple peers on startup, repeat the `staticnode` option: +You can provide [static peers](/learn/concepts/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 +```shell ./build/wakunode2 \ --staticnode=[PEER MULTIADDR 1] \ --staticnode=[PEER MULTIADDR 2] @@ -20,21 +21,21 @@ You can provide [static peers](/overview/concepts/static-peers) to a `nwaku` nod For example, consider a `nwaku` node that connects to two static peers on the same local host (IP: `0.0.0.0`) using TCP ports `60002` and `60003`: -```bash +```shell ./build/wakunode2 \ --staticnode=/ip4/0.0.0.0/tcp/60002/p2p/16Uiu2HAkzjwwgEAXfeGNMKFPSpc6vGBRqCdTLG5q3Gmk2v4pQw7H \ --staticnode=/ip4/0.0.0.0/tcp/60003/p2p/16Uiu2HAmFBA7LGtwY5WVVikdmXVo3cKLqkmvVtuDu63fe8safeQJ ``` -## Configure DNS Discovery +## Configure DNS discovery -To enable [DNS Discovery](/overview/concepts/dns-discovery) in a `nwaku` node, use the following configuration options: +To enable [DNS Discovery](/learn/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. -```bash +```shell ./build/wakunode2 \ --dns-discovery=true \ --dns-discovery-url=enrtree://[PUBLIC KEY]@[DOMAIN NAME] \ @@ -47,7 +48,7 @@ If you omit the `dns-discovery-name-server` option, `nwaku` will attempt to use For example, consider a `nwaku` node that enables `DNS Discovery`, connects to a DNS node list, and queries the IPs `8.8.8.8` and `8.8.4.4`: -```bash +```shell ./build/wakunode2 \ --dns-discovery=true \ --dns-discovery-url=enrtree://ANEDLO25QVUGJOUTQFRYKWX6P4Z4GKVESBMHML7DZ6YK4LGS5FC5O@prod.wakuv2.nodes.status.im \ @@ -57,12 +58,12 @@ For example, consider a `nwaku` node that enables `DNS Discovery`, connects to a ## Configure Discv5 -To enable [Discv5](/overview/concepts/discv5) in a `nwaku` node, use the following configuration options: +To enable [Discv5](/learn/concepts/discv5) in a `nwaku` node, use the following configuration options: - `discv5-discovery`: Enables `Discv5` on the node (disabled by default). - `discv5-bootstrap-node`: ENR for `Discv5` routing table bootstrap node. You can repeat this option to provide multiple bootstrap entries. -```bash +```shell ./build/wakunode2 \ --discv5-discovery=true \ --discv5-bootstrap-node=[DISCV5 ENR BOOTSTRAP ENTRY 1] \ @@ -71,7 +72,7 @@ To enable [Discv5](/overview/concepts/discv5) in a `nwaku` node, use the followi For example, consider a `nwaku` node that enables `Discv5` and bootstraps its routing table using a static `ENR`: -```bash +```shell ./build/wakunode2 \ --discv5-discovery=true \ --discv5-bootstrap-node=enr:-IO4QDxToTg86pPCK2KvMeVCXC2ADVZWrxXSvNZeaoa0JhShbM5qed69RQz1s1mWEEqJ3aoklo_7EU9iIBcPMVeKlCQBgmlkgnY0iXNlY3AyNTZrMaEDdBHK1Gx6y_zv5DVw5Qb3DtSOMmVHTZO1WSORrF2loL2DdWRwgiMohXdha3UyAw @@ -81,14 +82,14 @@ For example, consider a `nwaku` node that enables `Discv5` and bootstraps its ro 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. ::: -## Configure Peer Exchange +## Configure peer exchange -To enable [Peer Exchange](/overview/concepts/peer-exchange) in a `nwaku` node, use the following configuration options: +To enable [Peer Exchange](/learn/concepts/peer-exchange) in a `nwaku` node, use the following configuration options: - `peer-exchange`: Enables `Peer Exchange` on the node as a responder (disabled by default). - `peer-exchange-node` (optional): Multiaddr for bootstrap node with the peer exchange protocol enabled. -```bash +```shell ./build/wakunode2 \ --peer-exchange=true \ --peer-exchange-node=[PEER MULTIADDR WITH EXCHANGE ENABLED] @@ -96,11 +97,11 @@ To enable [Peer Exchange](/overview/concepts/peer-exchange) in a `nwaku` node, u For example, consider two `nwaku` nodes configured as a `server` (peer exchange responder node) and `client` (node using peer exchange) on the same local host (IP: `0.0.0.0`): -```bash title="Server: Nwaku Node with Peer Exchange Enabled" +```shell title="Server: Nwaku Node with Peer Exchange Enabled" ./build/wakunode2 --peer-exchange=true ``` -```bash title="Client: Nwaku Node Bootstrapping with Peer Exchange" +```shell title="Client: Nwaku Node Bootstrapping with Peer Exchange" ./build/wakunode2 \ --tcp-port=30305 \ --ports-shift=1 \ @@ -108,5 +109,5 @@ For example, consider two `nwaku` nodes configured as a `server` (peer exchange ``` :::info -`nwaku` provides a [`relay-peer-exchange`](/guides/reference/node-config-options#relay-config) option via `libp2p` for peer exchange, allowing network growth through neighbouring nodes. However, this feature can compromise security and network robustness, so we recommend only using it in high-trust environments. +`nwaku` provides a [`relay-peer-exchange`](/guides/nwaku/config-options#relay-config) option via `libp2p` for peer exchange, allowing network growth through neighbouring nodes. However, this feature can compromise security and network robustness, so we recommend only using it in high-trust environments. ::: diff --git a/docs/guides/nwaku/configure-nwaku.md b/docs/guides/nwaku/configure-nwaku.md index 30aae3b..f4fb4cd 100644 --- a/docs/guides/nwaku/configure-nwaku.md +++ b/docs/guides/nwaku/configure-nwaku.md @@ -1,41 +1,42 @@ --- -title: Nwaku Configuration Examples +title: Node Configuration Examples +hide_table_of_contents: true --- This guide provides detailed steps to configure a `nwaku` node for different use cases. -## Connect to Other Peers +## Connect to other peers -To join the Waku Network, nodes must [bootstrap](/overview/reference/glossary#bootstrapping) for an entry point before discovering more peers. Nwaku provides multiple [peer discovery](/overview/concepts/peer-discovery) mechanisms: +To join the Waku Network, nodes must [bootstrap](/learn/glossary#bootstrapping) for an entry point before discovering more peers. Nwaku provides multiple [peer discovery](/learn/concepts/peer-discovery) mechanisms: - [Configure Static Peers](/guides/nwaku/configure-discovery#configure-static-peers) - [Configure DNS Discovery](/guides/nwaku/configure-discovery#configure-dns-discovery) - [Configure Discv5](/guides/nwaku/configure-discovery#configure-discv5) - [Configure Peer Exchange](/guides/nwaku/configure-discovery#configure-peer-exchange) -## Configure a Domain Name +## Configure a domain name You can set up an IPv4 DNS domain name that resolves to the public IPv4 address of a node using the `dns4-domain-name` option. This allows the node's publicly announced multiaddrs to use the `/dns4` scheme. -```bash +```shell ./build/wakunode2 --dns4-domain-name=[DOMAIN NAME] ``` For example, consider the domain name `nwakunode.com`, which resolves to a `nwaku` node: -```bash +```shell ./build/wakunode2 --dns4-domain-name=nwakunode.com ``` Browser nodes can only connect to nodes with a domain name and secure WebSocket (`wss`) configured. These nodes will generate a discoverable ENR with `/wss` as the multiaddr and `/dns4` as the domain name. This configuration is essential for verifying domain certificates when establishing a secure connection. :::info -This example describes configuring a domain name that resolves to your node's IP address and is unrelated to [DNS Discovery](/overview/concepts/dns-discovery). +This example describes configuring a domain name that resolves to your node's IP address and is unrelated to [DNS Discovery](/learn/concepts/dns-discovery). ::: -## Configure Store Protocol and Message Store +## Configure store protocol and message store -To enable message caching and serve them to network peers, enable the [Store protocol](/overview/concepts/protocols#store) using the following configuration options: +To enable message caching and serve them to network peers, enable the [Store protocol](/learn/concepts/protocols#store) using the following configuration options: - `store`: Enables storing messages to serve them to peers (disabled by default). - `store-message-retention-policy`: Retention policy of the store node (how long messages will be persisted). Three different retention policies are supported: @@ -45,7 +46,7 @@ To enable message caching and serve them to network peers, enable the [Store pro - Set this option to `none` to disable the retention policy. If you omit this option, it will default to `time:172800` (48 hours). - `store-message-db-url`: Database connection URL for persisting messages in the [SQLAlchemy database URL format](https://docs.sqlalchemy.org/en/20/core/engines.html#database-urls). Setting this option to an empty string will instruct the node to use the fallback in-memory message store. If you omit this option, it will default to `sqlite://store.sqlite3`. -```bash +```shell ./build/wakunode2 \ --store=true \ --store-message-retention-policy=[MESSAGE RETENTION POLICY] \ @@ -54,7 +55,7 @@ To enable message caching and serve them to network peers, enable the [Store pro For example, consider a `nwaku` node that is configured to be a `Store` protocol and retain messages received in the last `21600` seconds (6 hours): -```bash +```shell ./build/wakunode2 \ --store=true \ --store-message-retention-policy=time:21600 \ @@ -63,27 +64,27 @@ For example, consider a `nwaku` node that is configured to be a `Store` protocol You can configure `nwaku` as a `Store client` using the `storenode` option. This allows the node to query peers for historical messages but not store any message itself. -```bash +```shell ./build/wakunode2 --storenode=[STORE PEER MULTIADDR] ``` For example, consider a `nwaku` node that does not persist messages but can query peers for historical messages: -```bash +```shell ./build/wakunode2 --storenode=/dns4/node-01.ac-cn-hongkong-c.wakuv2.prod.statusim.net/tcp/30303/p2p/16Uiu2HAm4v86W3bmT1BiH6oSPzcsSr24iDQpSN5Qa992BCjjwgrD ``` -## Generate and Configure a Node Key +## Generate and configure a node key -Nodes generate [new random key pairs](/overview/reference/glossary#node-key) at each boot, leading to different `multiaddrs`. To maintain consistency, you can use a pre-generated private key with the `nodekey` option: +Nodes generate [new random key pairs](/learn/glossary#node-key) at each boot, leading to different `multiaddrs`. To maintain consistency, you can use a pre-generated private key with the `nodekey` option: -```bash +```shell ./build/wakunode2 --nodekey=[NODE PRIVATE KEY] ``` This option takes a [Secp256k1](https://en.bitcoin.it/wiki/Secp256k1) private key (64-char hex string). On Linux, you can use the OpenSSL `rand` command for a pseudo-random 32-byte hex string: -```bash +```shell openssl rand -hex 32 # 286cae9f2990bfc49dafdd3a9e737f56ddba3656e5e427108cef456fb67680e8 @@ -91,7 +92,7 @@ openssl rand -hex 32 On Linux, you can create a reusable key file using OpenSSL. To get the 32-byte private key in hex format, use the `ecparam` command and some standard utilities: -```bash +```shell # Generate key file openssl ecparam -genkey -name secp256k1 -out my_private_key.pem @@ -105,13 +106,13 @@ openssl ec -in my_private_key.pem -outform DER | tail -c +8 | head -c 32| xxd -p You can use the output `286cae9f2990bfc49dafdd3a9e737f56ddba3656e5e427108cef456fb67680e8` as a `Node Key` for `nwaku`: -```bash +```shell ./build/wakunode2 --nodekey=286cae9f2990bfc49dafdd3a9e737f56ddba3656e5e427108cef456fb67680e8 ``` -## Configure WebSocket Transport +## Configure WebSocket transport -WebSocket is the only [transport method](/overview/concepts/transports) browser nodes support using [@waku/sdk](/guides/js-waku/). To enable WebSocket in `nwaku` to serve browser peers, use the following configuration options: +WebSocket is the only [transport method](/learn/concepts/transports) browser nodes support using [@waku/sdk](/guides/js-waku/). To enable WebSocket in `nwaku` to serve browser peers, use the following configuration options: - `websocket-support`: Enables WebSocket (`ws`) on the node (disabled by default). - `websocket-port` (optional): WebSocket listening port. If you omit this option, it will default to `8000`. @@ -119,7 +120,7 @@ WebSocket is the only [transport method](/overview/concepts/transports) browser - `websocket-secure-key-path`: Secure WebSocket key path. - `websocket-secure-cert-path`: Secure WebSocket Certificate path. -```bash +```shell ./build/wakunode2 \ --websocket-support=true \ --websocket-port=[WEBSOCKET LISTENING PORT] \ @@ -130,7 +131,7 @@ WebSocket is the only [transport method](/overview/concepts/transports) browser For example, consider a `nwaku` node that enabled WebSocket (unencrypted) for local testing on port `8001`: -```bash +```shell ./build/wakunode2 \ --websocket-support=true \ --websocket-port=8001 @@ -138,7 +139,7 @@ For example, consider a `nwaku` node that enabled WebSocket (unencrypted) for lo Consider a `nwaku` node that enabled Secure WebSocket (encrypted) using its key and certificate (`privkey.pem` and `fullchain.pem`) on port `8002`: -```bash +```shell ./build/wakunode2 \ --websocket-secure-support=true \ --websocket-secure-key-path=privkey.pem \ @@ -149,12 +150,12 @@ Consider a `nwaku` node that enabled Secure WebSocket (encrypted) using its key :::tip You can use [Let's Encrypt](https://letsencrypt.org/) or [Certbot](https://certbot.eff.org/) to generate a valid certificate for your `nwaku` node: -```bash +```shell sudo letsencrypt -d ``` ::: -## Configure REST API Server +## Configure REST API server Nwaku provides a REST API to interact with the node and Waku Network. To enable the REST API, use the following configuration options: @@ -165,7 +166,7 @@ Nwaku provides a REST API to interact with the node and Waku Network. To enable - `rest-admin` (optional): Enables access to REST admin API (disabled by default). - `rest-private` (optional): Enables access to REST private API (disabled by default). -```bash +```shell ./build/wakunode2 \ --rest=true \ --rest-address=[REST SERVER LISTENING ADDRESS] \ @@ -177,7 +178,7 @@ Nwaku provides a REST API to interact with the node and Waku Network. To enable For example, consider a `nwaku` node that enabled the REST API server on port `9000`: -```bash +```shell ./build/wakunode2 \ --rest=true \ --rest-port=9000 \ @@ -186,7 +187,7 @@ For example, consider a `nwaku` node that enabled the REST API server on port `9 Consider a `nwaku` node that enabled the REST `admin` and `private` API with a message cache capacity of `100`: -```bash +```shell ./build/wakunode2 \ --rest=true \ --rest-admin=true \ @@ -194,17 +195,17 @@ Consider a `nwaku` node that enabled the REST `admin` and `private` API with a m --rest-relay-cache-capacity=100 ``` -## Configure Filter Protocol +## Configure filter protocol -To enable `nwaku` to serve light clients, enable the [Filter protocol](/overview/concepts/protocols#filter) using `filter` option: +To enable `nwaku` to serve light clients, enable the [Filter protocol](/learn/concepts/protocols#filter) using `filter` option: -```bash +```shell ./build/wakunode2 --filter=true ``` You can configure `nwaku` as a `Filter client` using the `filternode` and `filter-timeout` options. This allows the node to request content filtering of messages from peers. -```bash +```shell ./build/wakunode2 \ --filternode=[FILTER PEER MULTIADDR] \ --filter-timeout=[FILTER PEER TIMEOUT] @@ -212,7 +213,7 @@ You can configure `nwaku` as a `Filter client` using the `filternode` and `filte For example, consider a `nwaku` node that requests content filtering of messages from peers with a timeout of `21600` seconds (6 hours): -```bash +```shell ./build/wakunode2 \ --filternode=/dns4/node-01.ac-cn-hongkong-c.wakuv2.prod.statusim.net/tcp/30303/p2p/16Uiu2HAm4v86W3bmT1BiH6oSPzcsSr24iDQpSN5Qa992BCjjwgrD \ --filter-timeout=21600 @@ -222,31 +223,31 @@ For example, consider a `nwaku` node that requests content filtering of messages If you omit the `filter-timeout` option, it will default to `14400` seconds (4 hours). ::: -## Configure Light Push Protocol +## Configure light push protocol -To enable `nwaku` to serve light clients, enable the [Light Push protocol](/overview/concepts/protocols#light-push) using the `lightpush` option: +To enable `nwaku` to serve light clients, enable the [Light Push protocol](/learn/concepts/protocols#light-push) using the `lightpush` option: -```bash +```shell ./build/wakunode2 --lightpush=true ``` You can configure `nwaku` as a `Light Push client` using the `lightpushnode` option. This allows the node to request lightpush of published messages from peers. -```bash +```shell ./build/wakunode2 --lightpushnode=[LIGHT PUSH PEER MULTIADDR] ``` For example, consider a `nwaku` node that requests lightpush of published messages from peers: -```bash +```shell ./build/wakunode2 --lightpushnode=/dns4/node-01.ac-cn-hongkong-c.wakuv2.prod.statusim.net/tcp/30303/p2p/16Uiu2HAm4v86W3bmT1BiH6oSPzcsSr24iDQpSN5Qa992BCjjwgrD ``` -## Run Nwaku Behind a Reverse Proxy +## Run nwaku behind a reverse proxy When using a reverse proxy server for SSL/TLS encryption, you only want to announce the proxy server's IP or domain. Nwaku provides the `ext-multiaddr-only` and `ext-multiaddr` options for specifying published multiaddr: -```bash +```shell ./build/wakunode2 \ --ext-multiaddr-only=true \ --ext-multiaddr=[MULTIADDR TO PUBLISH] diff --git a/docs/guides/nwaku/run-docker-compose.md b/docs/guides/nwaku/run-docker-compose.md index e9afc92..4035fd5 100644 --- a/docs/guides/nwaku/run-docker-compose.md +++ b/docs/guides/nwaku/run-docker-compose.md @@ -1,10 +1,11 @@ --- title: Run Nwaku with Docker Compose +hide_table_of_contents: true --- `nwaku-compose` is a ready-to-use Docker Compose setup that runs the following: -- `nwaku` node running [Relay](/overview/concepts/protocols#relay) and [Store](/overview/concepts/protocols#store) protocols with [RLN](/overview/concepts/protocols#rln-relay) enabled. +- `nwaku` node running [Relay](/learn/concepts/protocols#relay) and [Store](/learn/concepts/protocols#store) protocols with [RLN](/learn/concepts/protocols#rln-relay) enabled. - Simple frontend to interact with your node and the network to send and receive messages. - [Grafana](https://grafana.com/) metrics dashboard for advanced users or node operators. @@ -18,16 +19,16 @@ This guide provides detailed steps to configure, run, monitor, and interact with - [Wallet with Sepolia Ethereum](https://github.com/waku-org/nwaku/blob/master/docs/tutorial/pre-requisites-of-running-on-chain-spam-protected-chat2.md#2-obtain-sepolia-eth-from-faucet) (less than 0.1 Sepolia ETH) - A password to protect your RLN membership -## Clone the Repository +## Clone the repository -```bash +```shell git clone https://github.com/waku-org/nwaku-compose cd nwaku-compose ``` -## Configure the Setup +## Configure the setup -Modify the `run_node.sh` file to customise your [node's configuration](/guides/reference/node-config-options) and `docker-compose.yml` to specify particular [Docker image](https://hub.docker.com/r/statusteam/nim-waku/tags) tag. Next, export your Ethereum Sepolia configuration and membership password: +Modify the `run_node.sh` file to customise your [node's configuration](/guides/nwaku/config-options) and `docker-compose.yml` to specify particular [Docker image](https://hub.docker.com/r/statusteam/nim-waku/tags) tag. Next, export your Ethereum Sepolia configuration and membership password: ```shell export ETH_CLIENT_ADDRESS=wss://sepolia.infura.io/ws/v3/[INFURA API KEY] @@ -35,7 +36,7 @@ export ETH_TESTNET_KEY=[INFURA API KEY] export KEYSTORE_PASSWORD=[RLN MEMBERSHIP PASSWORD] ``` -## Register RLN Membership +## Register RLN membership The RLN membership is your access key to The Waku Network. Its registration is done on-chain and allows your `nwaku` node to send messages decentralised and privately, respecting some rate limits. Other peers won't relay messages exceeding the rate limit: @@ -47,15 +48,15 @@ The RLN membership is your access key to The Waku Network. Its registration is d If you only want to relay traffic without sending messages to the network, you don't need to register for RLN membership. ::: -## Run Docker Compose +## Run the node Start all processes: `nwaku` node, database and Grafana for metrics. Your RLN membership is loaded into nwaku under the hood: -```bash +```shell docker-compose up -d ``` -## Interact with the Node +## Interact with the node Visit to view your node metrics in real-time. @@ -96,5 +97,5 @@ curl --location 'http://127.0.0.1:8645/store/v1/messages?contentTopics=%2Fmy-app ``` :::tip Congratulations! -You have successfully started a `nwaku` node with `RLN` enabled using Docker Compose. Have a look at the [Nwaku Configuration Examples](/guides/nwaku/configure-nwaku) and [Advanced Configuration](https://github.com/waku-org/nwaku-compose/blob/master/ADVANCED.md) guides to learn how to configure `nwaku` for different use cases. +You have successfully started a `nwaku` node with `RLN` enabled using Docker Compose. Have a look at the [Node Configuration Examples](/guides/nwaku/configure-nwaku) and [Advanced Configuration](https://github.com/waku-org/nwaku-compose/blob/master/ADVANCED.md) guides to learn how to configure `nwaku` for different use cases. ::: \ No newline at end of file diff --git a/docs/guides/nwaku/run-docker.md b/docs/guides/nwaku/run-docker.md index 1b76c10..c8ecb26 100644 --- a/docs/guides/nwaku/run-docker.md +++ b/docs/guides/nwaku/run-docker.md @@ -1,5 +1,6 @@ --- title: Run Nwaku in a Docker Container +hide_table_of_contents: true --- This guide provides detailed steps to build and run a `nwaku` node in a Docker container. If you prefer a pre-configured setup with a monitoring dashboard, see the [Run Nwaku with Docker Compose](/guides/nwaku/run-docker-compose) guide. @@ -8,13 +9,13 @@ This guide provides detailed steps to build and run a `nwaku` node in a Docker c Ensure [Docker](https://www.docker.com/) is installed on your system using the appropriate instructions provided in the [Docker documentation](https://docs.docker.com/engine/install/). -## Get Docker Image +## Get Docker image The Nwaku Docker images are available on the Docker Hub public registry under the [statusteam/nim-waku](https://hub.docker.com/r/statusteam/nim-waku) repository. Please visit [statusteam/nim-waku/tags](https://hub.docker.com/r/statusteam/nim-waku/tags) for images of specific releases. You can also build the Docker image locally: -```bash +```shell # Clone the repository git clone --recurse-submodules https://github.com/waku-org/nwaku cd nwaku @@ -23,21 +24,21 @@ cd nwaku make docker-image ``` -## Run Docker Container +## Run Docker container Run `nwaku` in a new Docker container: -```bash +```shell docker run [OPTIONS] [IMAGE] [ARG...] ``` - `OPTIONS` are your selected [Docker options](https://docs.docker.com/engine/reference/commandline/run/#options) - `IMAGE` is the image and tag you pulled from the registry or built locally -- `ARG...` is the list of arguments for your [node configuration options](/guides/reference/node-config-options) +- `ARG...` is the list of arguments for your [node configuration options](/guides/nwaku/config-options) Run `nwaku` using the most typical configuration: -```bash +```shell docker run -i -t -p 60000:60000 -p 9000:9000/udp statusteam/nim-waku:v0.20.0 \ --dns-discovery=true \ --dns-discovery-url=enrtree://ANEDLO25QVUGJOUTQFRYKWX6P4Z4GKVESBMHML7DZ6YK4LGS5FC5O@prod.wakuv2.nodes.status.im \ @@ -48,7 +49,7 @@ docker run -i -t -p 60000:60000 -p 9000:9000/udp statusteam/nim-waku:v0.20.0 \ To find your public IP, use: -```bash +```shell dig TXT +short o-o.myaddr.l.google.com @ns1.google.com | awk -F'"' '{ print $2}' ``` @@ -57,5 +58,5 @@ We recommend using explicit port mappings (`-p`) when exposing ports accessible ::: :::tip Congratulations! -You have successfully built and started a `nwaku` node in a Docker container. Have a look at the [Nwaku Configuration Examples](/guides/nwaku/configure-nwaku) guide to learn how to configure `nwaku` for different use cases. +You have successfully built and started a `nwaku` node in a Docker container. Have a look at the [Node Configuration Examples](/guides/nwaku/configure-nwaku) guide to learn how to configure `nwaku` for different use cases. ::: diff --git a/docs/guides/run-nwaku-node.md b/docs/guides/nwaku/run-node.md similarity index 80% rename from docs/guides/run-nwaku-node.md rename to docs/guides/nwaku/run-node.md index 8edee17..cbcf381 100644 --- a/docs/guides/run-nwaku-node.md +++ b/docs/guides/nwaku/run-node.md @@ -1,8 +1,9 @@ --- title: Run a Nwaku Node +hide_table_of_contents: true --- -Nwaku is a lightweight and robust Nim client for running a Waku node, equipped with tools to monitor and maintain a running node. Nwaku is highly configurable, enabling operators to select the [protocols](/overview/concepts/protocols) they want to support based on their needs, motivations, and available resources. +Nwaku is a lightweight and robust Nim client for running a Waku node, equipped with tools to monitor and maintain a running node. Nwaku is highly configurable, enabling operators to select the [protocols](/learn/concepts/protocols) they want to support based on their needs, motivations, and available resources. This guide provides detailed steps to download, build, configure, and connect a `nwaku` node to the Waku Network. It also includes interacting with the node and finding its addresses. @@ -10,22 +11,22 @@ This guide provides detailed steps to download, build, configure, and connect a We recommend running a `nwaku` node with at least 2GB of RAM, especially if you have `WSS` enabled. If running just a `Relay` node, 0.5GB of RAM is sufficient. ::: -## Get the Node Binary +## Get the node binary To run a node, you must have the `nwaku` binary. Nwaku provides multiple options for acquiring the node binary: -#### Download the Binary +#### Download the binary | | Description | Documentation | | - | - | - | | Precompiled Binary | Download a precompiled binary of the `nwaku` node | [Download Nwaku Binary](https://github.com/waku-org/nwaku/tags) | | Nightly Release | Try the latest `nwaku` updates without compiling the binaries | [Download Nightly Release](https://github.com/waku-org/nwaku/releases/tag/nightly) | -#### Build the Binary +#### Build the binary You can build the node binary directly from the [nwaku source code](https://github.com/waku-org/nwaku). Have a look at the [Build Nwaku from Source](/guides/nwaku/build-source) guide to learn more. -#### Run Nwaku in Docker +#### Run nwaku in Docker | | Description | Documentation | | - | - | - | @@ -36,11 +37,11 @@ You can build the node binary directly from the [nwaku source code](https://gith You can run the `nwaku` binaries and Docker images on cloud service providers like [Google Cloud](https://cloud.google.com/), [Microsoft Azure](https://azure.microsoft.com/), [Amazon Web Services](https://aws.amazon.com/), and [DigitalOcean](https://www.digitalocean.com/). ::: -## Run the Node +## Run the node -Once you have gotten the `nwaku` binary, run it using the [default configuration](/guides/reference/node-config-methods#default-configuration-values): +Once you have gotten the `nwaku` binary, run it using the [default configuration](/guides/nwaku/config-methods#default-configuration-values): -```bash +```shell # Run with default configuration ./build/wakunode2 @@ -49,25 +50,25 @@ Once you have gotten the `nwaku` binary, run it using the [default configuration ``` :::tip -To learn how to customise the configuration of a `nwaku` node, have a look at the [Node Configuration Methods](/guides/reference/node-config-methods) and [Node Configuration Options](/guides/reference/node-config-options) guides. +To learn how to customise the configuration of a `nwaku` node, have a look at the [Node Configuration Methods](/guides/nwaku/config-methods) and [Node Configuration Options](/guides/nwaku/config-options) guides. ::: -## Bootstrap the Node +## Bootstrap the node -To join the Waku Network, nodes must [bootstrap](/overview/reference/glossary#bootstrapping) for an entry point before discovering more peers. Nwaku provides multiple [peer discovery](/overview/concepts/peer-discovery) mechanisms: +To join the Waku Network, nodes must [bootstrap](/learn/glossary#bootstrapping) for an entry point before discovering more peers. Nwaku provides multiple [peer discovery](/learn/concepts/peer-discovery) mechanisms: | | Description | Documentation | | - | - | - | | 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 bootstrap nodes using the [DNS Discovery](/overview/concepts/dns-discovery) mechanism | [Configure DNS Discovery](/guides/nwaku/configure-discovery#configure-dns-discovery) | -| Discv5 | Enable `nwaku` to discover peers using the [Discv5](/overview/concepts/discv5) mechanism | [Configure Discv5](/guides/nwaku/configure-discovery#configure-discv5) | -| Peer Exchange | Enable [Peer Exchange](/overview/concepts/peer-exchange) protocol for light nodes to request peers from your `nwaku` node | [Configure Peer Exchange](/guides/nwaku/configure-discovery#configure-peer-exchange) | +| DNS Discovery | Enable `nwaku` to bootstrap nodes using the [DNS Discovery](/learn/concepts/dns-discovery) mechanism | [Configure DNS Discovery](/guides/nwaku/configure-discovery#configure-dns-discovery) | +| Discv5 | Enable `nwaku` to discover peers using the [Discv5](/learn/concepts/discv5) mechanism | [Configure Discv5](/guides/nwaku/configure-discovery#configure-discv5) | +| Peer Exchange | Enable [Peer Exchange](/learn/concepts/peer-exchange) protocol for light nodes to request peers from your `nwaku` node | [Configure Peer Exchange](/guides/nwaku/configure-discovery#configure-peer-exchange) | :::info You can configure a `nwaku` node to use multiple peer discovery mechanisms simultaneously. ::: -## Interact with the Node +## Interact with the node You can interact with a running `nwaku` node through the [REST API](https://waku-org.github.io/waku-rest-api/), such as querying the node information using the [Get node info](https://waku-org.github.io/waku-rest-api/#get-/debug/v1/info) endpoint: @@ -79,7 +80,7 @@ import TabItem from '@theme/TabItem'; -```bash +```shell curl --location 'http://127.0.0.1:8645/debug/v1/info' \ --header 'Accept: application/json' ``` @@ -103,7 +104,7 @@ curl --location 'http://127.0.0.1:8645/debug/v1/info' \ The `listenAddresses` field stores the node's listening addresses, while the `enrUri` field stores the discoverable `ENR` URI for peer discovery. ::: -## Find the Node Addresses +## Find the node addresses You can find the addresses of a running node through its logs or by calling the [Get node info](https://waku-org.github.io/waku-rest-api/#get-/debug/v1/info) endpoint of the [REST API](https://waku-org.github.io/waku-rest-api/). @@ -111,7 +112,7 @@ You can find the addresses of a running node through its logs or by calling the When starting the node, `nwaku` will display all the public listening and discovery addresses at the `INFO` log level. ::: -### Listening Addresses +### Listening addresses Look for the log entry that begins with `Listening on`, for example: @@ -119,7 +120,7 @@ Look for the log entry that begins with `Listening on`, for example: INF 2023-06-15 16:09:54.448+01:00 Listening on topics="waku node" tid=1623445 file=waku_node.nim:922 full=[/ip4/0.0.0.0/tcp/60000/p2p/16Uiu2HAmQCsH9V81xoqTwGuT3qwkZWbwY1TtTQwpr3DjHU2TSwMn][/ip4/0.0.0.0/tcp/8000/ws/p2p/16Uiu2HAmQCsH9V81xoqTwGuT3qwkZWbwY1TtTQwpr3DjHU2TSwMn] ``` -```bash +```shell # Listening TCP transport address /ip4/0.0.0.0/tcp/60000/p2p/16Uiu2HAmQCsH9V81xoqTwGuT3qwkZWbwY1TtTQwpr3DjHU2TSwMn @@ -127,7 +128,7 @@ INF 2023-06-15 16:09:54.448+01:00 Listening on top /ip4/0.0.0.0/tcp/8000/ws/p2p/16Uiu2HAmQCsH9V81xoqTwGuT3qwkZWbwY1TtTQwpr3DjHU2TSwMn ``` -### Discoverable ENR Addresses +### Discoverable ENR addresses A `nwaku` node can encode its addressing information in an [Ethereum Node Record (ENR)](https://eips.ethereum.org/EIPS/eip-778) following the [WAKU2-ENR](https://rfc.vac.dev/spec/31/) specification, primarily for peer discovery. @@ -139,7 +140,7 @@ Look for the log entry that begins with `DNS: discoverable ENR`, for example: INF 2023-06-15 16:09:54.448+01:00 DNS: discoverable ENR topics="waku node" tid=1623445 file=waku_node.nim:923 enr=enr:-Iu4QBKYj8Ovxwz4fIalxZ_1a8dOCU2WC-1LQrcBCCb4Np93f9-UuSZXn3vagJL1S3k3hwRYfOp3JSbW7_VqwtqMIeMBgmlkgnY0gmlwhAAAAACJc2VjcDI1NmsxoQOrmyV59dAzY4ZKrvrj32VOoZbLby8dCKFnXnqhIdQ0NYN0Y3CC6mCFd2FrdTIB ``` -```bash +```shell # ENR the node addresses are encoded in enr:-Iu4QBKYj8Ovxwz4fIalxZ_1a8dOCU2WC-1LQrcBCCb4Np93f9-UuSZXn3vagJL1S3k3hwRYfOp3JSbW7_VqwtqMIeMBgmlkgnY0gmlwhAAAAACJc2VjcDI1NmsxoQOrmyV59dAzY4ZKrvrj32VOoZbLby8dCKFnXnqhIdQ0NYN0Y3CC6mCFd2FrdTIB ``` @@ -152,11 +153,11 @@ Look for the log entry that begins with `Discv5: discoverable ENR`, for example: INF 2023-06-15 16:09:54.448+01:00 Discv5: discoverable ENR topics="waku node" tid=1623445 file=waku_node.nim:924 enr=enr:-IO4QDxToTg86pPCK2KvMeVCXC2ADVZWrxXSvNZeaoa0JhShbM5qed69RQz1s1mWEEqJ3aoklo_7EU9iIBcPMVeKlCQBgmlkgnY0iXNlY3AyNTZrMaEDdBHK1Gx6y_zv5DVw5Qb3DtSOMmVHTZO1WSORrF2loL2DdWRwgiMohXdha3UyAw ``` -```bash +```shell # ENR the node addresses are encoded in enr:-IO4QDxToTg86pPCK2KvMeVCXC2ADVZWrxXSvNZeaoa0JhShbM5qed69RQz1s1mWEEqJ3aoklo_7EU9iIBcPMVeKlCQBgmlkgnY0iXNlY3AyNTZrMaEDdBHK1Gx6y_zv5DVw5Qb3DtSOMmVHTZO1WSORrF2loL2DdWRwgiMohXdha3UyAw ``` :::tip Congratulations! -You have successfully started, configured, and connected a `nwaku` node to the Waku Network. Have a look at the [Nwaku Configuration Examples](/guides/nwaku/configure-nwaku) guide to learn how to configure `nwaku` for different use cases. +You have successfully started, configured, and connected a `nwaku` node to the Waku Network. Have a look at the [Node Configuration Examples](/guides/nwaku/configure-nwaku) guide to learn how to configure `nwaku` for different use cases. ::: \ No newline at end of file diff --git a/docs/overview/concepts/content-topics.md b/docs/learn/concepts/content-topics.md similarity index 84% rename from docs/overview/concepts/content-topics.md rename to docs/learn/concepts/content-topics.md index 3722698..ebb4433 100644 --- a/docs/overview/concepts/content-topics.md +++ b/docs/learn/concepts/content-topics.md @@ -1,10 +1,11 @@ --- title: Content Topics +hide_table_of_contents: true --- -`Content Topics` are metadata strings set by developers on outgoing messages to facilitate protocol-level features like selectively processing incoming messages ([Relay](/overview/concepts/protocols#relay) or [Filter](/overview/concepts/protocols#filter)) and retrieving historical messages ([Store](/overview/concepts/protocols#store)) that meet specific filtering criteria. Have a look at the [WAKU2-TOPICS](https://rfc.vac.dev/spec/23/#content-topics) specification to learn more. +`Content Topics` are metadata strings set by developers on outgoing messages to facilitate protocol-level features like selectively processing incoming messages ([Relay](/learn/concepts/protocols#relay) or [Filter](/learn/concepts/protocols#filter)) and retrieving historical messages ([Store](/learn/concepts/protocols#store)) that meet specific filtering criteria. Have a look at the [WAKU2-TOPICS](https://rfc.vac.dev/spec/23/#content-topics) specification to learn more. -## Naming Format +## Naming format Here is the recommended format for content topics: @@ -24,7 +25,7 @@ For example, if your DApp is called `SuperCrypto` and it allows users to receive While you can choose any encoding format for your `Content Topic`, we highly recommend using Protocol Buffers (`proto`) because of its efficiency. Choosing a lightweight format ensures optimal performance of your DApp. ::: -## Naming Considerations +## Naming considerations When choosing a content topic, it is crucial to consider privacy implications. The `Filter`, `Store`, and `Light Push` protocols disclose content topics to peers, enabling said peer to link IP and content topic interests. `Relay` provides recipient anonymity thanks to `GossipSub`, but this may be lost if the content topic reveals information about the user. diff --git a/docs/overview/concepts/discv5.md b/docs/learn/concepts/discv5.md similarity index 96% rename from docs/overview/concepts/discv5.md rename to docs/learn/concepts/discv5.md index 0e37b4a..758bc1c 100644 --- a/docs/overview/concepts/discv5.md +++ b/docs/learn/concepts/discv5.md @@ -1,5 +1,6 @@ --- title: Discv5 +hide_table_of_contents: true --- `Discv5` is a decentralised 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 randomised sets of nodes for mesh expansion. Have a look at the [Discv5](https://rfc.vac.dev/spec/33/) specification to learn more. diff --git a/docs/overview/concepts/dns-discovery.md b/docs/learn/concepts/dns-discovery.md similarity index 97% rename from docs/overview/concepts/dns-discovery.md rename to docs/learn/concepts/dns-discovery.md index cd17e6e..1dbde46 100644 --- a/docs/overview/concepts/dns-discovery.md +++ b/docs/learn/concepts/dns-discovery.md @@ -1,5 +1,6 @@ --- title: DNS Discovery +hide_table_of_contents: true --- 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 standardised [ENR format](https://rfc.vac.dev/spec/31/). diff --git a/docs/learn/concepts/network-domains.md b/docs/learn/concepts/network-domains.md new file mode 100644 index 0000000..130f9c3 --- /dev/null +++ b/docs/learn/concepts/network-domains.md @@ -0,0 +1,34 @@ +--- +title: Network Domains +hide_table_of_contents: true +--- + +Waku is a unified and cohesive entity that offers a rich ecosystem with three distinct network interaction domains. These domains serve specialised purposes and contribute to the robust functionality of Waku, forming its foundation. + +## 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](/learn/concepts/discv5) and [Peer Exchange](/learn/concepts/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](/learn/concepts/protocols#relay) to distribute messages across the network. Additionally, Waku introduces [RLN Relay](/learn/concepts/protocols#rln-relay), an experimental mechanism that combines privacy preservation and economic spam protection. + +## Request/response domain + +Waku provides a set of protocols to optimise its performance in resource-limited environments like low bandwidth or mostly offline scenarios for multiple purposes. + +- [Store](/learn/concepts/protocols#store) enables the retrieval of historical messages. +- [Filter](/learn/concepts/protocols#filter) efficiently retrieves a subset of messages to conserve bandwidth. +- [Light Push](/learn/concepts/protocols#light-push) facilitates message publication for nodes with limited bandwidth and short connection windows. + +## Overview of protocol interaction + +Here is a diagram illustrating the interaction between different protocols within the Waku Network. + +```mdx-code-block +import ProtocolInteraction from "@site/diagrams/_protocol-interaction.md"; + + +``` \ No newline at end of file diff --git a/docs/learn/concepts/peer-discovery.md b/docs/learn/concepts/peer-discovery.md new file mode 100644 index 0000000..9bd1d2d --- /dev/null +++ b/docs/learn/concepts/peer-discovery.md @@ -0,0 +1,19 @@ +--- +title: Peer Discovery +hide_table_of_contents: true +--- + +When initialising a Waku node, it must connect with other peers to enable message sending, receiving, and retrieval. To achieve this, a discovery mechanism is employed to locate other peers in the network. This process is known as bootstrapping. + +Once a connection is established, the node must actively seek out additional peers to have: + +- Sufficient peers in the [Relay](/learn/concepts/protocols#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 capabilities: The node seeks out peers with specific capabilities, such as [Store](/learn/concepts/protocols#store), [Light Push](/learn/concepts/protocols#light-push), or [Filter](/learn/concepts/protocols#filter). This allows for targeted interactions and enhanced functionality based on the desired capabilities. + +Waku supports multiple peer discovery mechanisms, such as: + +- [Configuring Static Peers](/learn/concepts/static-peers) +- [Peer Discovery via DNS](/learn/concepts/dns-discovery) +- [Discv5 Ambient Peer Discovery](/learn/concepts/discv5) +- [Peer Exchange](/learn/concepts/peer-exchange) \ No newline at end of file diff --git a/docs/overview/concepts/peer-exchange.md b/docs/learn/concepts/peer-exchange.md similarity index 96% rename from docs/overview/concepts/peer-exchange.md rename to docs/learn/concepts/peer-exchange.md index b35f27e..5a90ec6 100644 --- a/docs/overview/concepts/peer-exchange.md +++ b/docs/learn/concepts/peer-exchange.md @@ -1,5 +1,6 @@ --- title: Peer Exchange +hide_table_of_contents: true --- The primary objective of this protocol is to facilitate peer connectivity for resource-limited devices without relying on `Discv5`. The peer exchange protocol enables light nodes to request peers from other nodes within the network. Have a look at the [Peer Exchange](https://rfc.vac.dev/spec/34/) specification to learn more. diff --git a/docs/overview/concepts/protocols.md b/docs/learn/concepts/protocols.md similarity index 77% rename from docs/overview/concepts/protocols.md rename to docs/learn/concepts/protocols.md index 9c8701a..161e52f 100644 --- a/docs/overview/concepts/protocols.md +++ b/docs/learn/concepts/protocols.md @@ -1,5 +1,6 @@ --- title: Protocols +hide_table_of_contents: true --- Waku takes a modular approach, providing a range of protocols that enable applications to control the trade-offs involved in the [Anonymity Trilemma](https://eprint.iacr.org/2017/954.pdf). This flexibility empowers applications to make informed choices regarding the desired balance between anonymity, scalability, and latency. Here are the main protocols provided by Waku: @@ -8,13 +9,13 @@ Waku takes a modular approach, providing a range of protocols that enable applic `Relay` protocol employs a Pub/Sub architecture to facilitate the sending and receiving of messages among peers. It extends the [libp2p GossipSub protocol](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/README.md) to create a privacy-focused peer-to-peer messaging protocol that enables secure communication channels, encryption, and protection against censorship. It also scales the Waku Network to accommodate many nodes efficiently. -## [RLN Relay](https://rfc.vac.dev/spec/17/) +## [RLN relay](https://rfc.vac.dev/spec/17/) `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 enforces a rate limit on messages over time for all peers in the network, economically preventing spam, and imposes financial penalties and network removal for spammers. You can find more details in the [RLN Relay blog post](https://vac.dev/rln-relay). ## [Filter](https://rfc.vac.dev/spec/12/) -`Filter` protocol allows light nodes to selectively subscribe to specific messages relayed by other peers using [content topics](/overview/concepts/content-topics). It is designed to be a lightweight alternative for accessing the `Relay` network, particularly tailored for devices with limited bandwidth. +`Filter` protocol allows light nodes to selectively subscribe to specific messages relayed by other peers using [content topics](/learn/concepts/content-topics). It is designed to be a lightweight alternative for accessing the `Relay` network, particularly tailored for devices with limited bandwidth. :::info `Filter` protocol helps optimise bandwidth usage, but it has fewer privacy guarantees as it must disclose the content topic to its peers to retrieve messages. @@ -28,19 +29,19 @@ Waku takes a modular approach, providing a range of protocols that enable applic Using `Relay` and `Filter` protocols is recommended when a node is online, as `Store` does not guarantee data availability. The `Store` protocol is suitable for retrieving messages when connecting to the network, like when a DApp starts. ::: -## [Light Push](https://rfc.vac.dev/spec/19/) +## [Light push](https://rfc.vac.dev/spec/19/) -`Light Push` is a [Request/Response](/overview/concepts/network-domains#requestresponse-domain) protocol for nodes with limited bandwidth and short connection windows. It allows a client to receive an acknowledgement when sending messages, indicating that at least one peer has received them. Subsequently, the remote peer forwards these messages to the `Relay` network. +`Light Push` is a [Request/Response](/learn/concepts/network-domains#requestresponse-domain) protocol for nodes with limited bandwidth and short connection windows. It allows a client to receive an acknowledgement when sending messages, indicating that at least one peer has received them. Subsequently, the remote peer forwards these messages to the `Relay` network. :::info While the `Light Push` protocol acknowledges the receipt by the remote peer, it does not guarantee network-wide propagation. ::: -## [Waku Message](https://rfc.vac.dev/spec/14) +## [Waku message](https://rfc.vac.dev/spec/14) `Waku Message` specifies the structure and format of messages in the Waku Network. It includes the following attributes: -- `content_topic` attribute for [content-based filtering](/overview/concepts/content-topics). +- `content_topic` attribute for [content-based filtering](/learn/concepts/content-topics). - `payload` attribute containing the message data payload to be sent. - `meta` attribute for conveying additional details to various protocols for application-specific processing. - `timestamp` attribute signifying the time at which the message was generated by its sender. diff --git a/docs/overview/concepts/static-peers.md b/docs/learn/concepts/static-peers.md similarity index 86% rename from docs/overview/concepts/static-peers.md rename to docs/learn/concepts/static-peers.md index ae6bc61..37eca6c 100644 --- a/docs/overview/concepts/static-peers.md +++ b/docs/learn/concepts/static-peers.md @@ -1,8 +1,9 @@ --- title: Static Peers +hide_table_of_contents: true --- -Waku applications have the flexibility to embed bootstrap node addresses directly into their codebase. Developers can either use static peers operated by Status or [run a node](/guides/nodes-and-sdks#run-a-waku-node). +Waku applications have the flexibility to embed bootstrap node addresses directly into their codebase. Developers can either use static peers operated by Status or [run a node](/#run-a-waku-node). #### Pros diff --git a/docs/overview/concepts/transports.md b/docs/learn/concepts/transports.md similarity index 85% rename from docs/overview/concepts/transports.md rename to docs/learn/concepts/transports.md index 4b3ae06..f433150 100644 --- a/docs/overview/concepts/transports.md +++ b/docs/learn/concepts/transports.md @@ -1,13 +1,14 @@ --- title: Transports +hide_table_of_contents: true --- Transports help move data packets across a network by establishing connections between peers. They define the rules and protocols to ensure efficient network transmission, routing, and data delivery. Waku is a transport-agnostic framework that allows developers to choose and support multiple protocols according to their requirements. For Waku nodes, the following transports are recommended: -- **TCP:** By default, Waku nodes use TCP for communication. Service nodes should employ TCP for listening to and connecting with other nodes. -- **Secure WebSocket:** In browser environments, secure WebSocket is used. Service nodes are encouraged to set up SSL certificates to enable incoming connections from browsers and serve them securely. +- **TCP**: By default, Waku nodes use TCP for communication. Service nodes should employ TCP for listening to and connecting with other nodes. +- **Secure WebSocket**: In browser environments, secure WebSocket is used. Service nodes are encouraged to set up SSL certificates to enable incoming connections from browsers and serve them securely. - Other protocols like [WebRTC](https://github.com/waku-org/js-waku/issues/20), [WebTransport](https://github.com/waku-org/js-waku/issues/697), and QUIC have been researched and studied for potential integration. :::info diff --git a/docs/overview/reference/glossary.md b/docs/learn/glossary.md similarity index 87% rename from docs/overview/reference/glossary.md rename to docs/learn/glossary.md index 50abec4..fc8b994 100644 --- a/docs/overview/reference/glossary.md +++ b/docs/learn/glossary.md @@ -1,5 +1,6 @@ --- title: Glossary +hide_table_of_contents: true --- # Waku Docs Glossary @@ -10,7 +11,7 @@ Definitions and usage of the terminology used in the Waku ecosystem. Bootstrapping is the initial entry point of a [node](#node) to the [Waku Network](#waku-network). Once connected, other [peer discovery](#peer-discovery) methods can be employed to locate other [peers](#peer) in the network. -### [Content Topic](/overview/concepts/content-topics) +### [Content topic](/learn/concepts/content-topics) A content topic is a string attached to [messages](#waku-message) to enable [protocol-level](#protocol) features like selective message processing and retrieval based on specific criteria. @@ -18,11 +19,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 decentralised applications and blockchain nodes, including [Waku](#waku). -### [Discv5](/overview/concepts/discv5) +### [Discv5](/learn/concepts/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/dns-discovery) +### [DNS discovery](/learn/concepts/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 decentralisation. @@ -30,11 +31,11 @@ DNS discovery is a [peer discovery](#peer-discovery) mechanism that allows the r Ethereum Node Record (ENR) is a specification used to represent and identify [nodes](#node), facilitating [discovery](#peer-discovery) and communication within the network. Besides connection details, `ENR` also includes node configuration information like enabled protocol and shards. -### [Filter](/overview/concepts/protocols#filter) +### [Filter](/learn/concepts/protocols#filter) Filter is a [protocol](#protocol) that enables [light nodes](#light-node) to selectively subscribe to specific [messages](#waku-message) transmitted by [peers](#peer) using [content topics](#content-topic). It is designed to be a lightweight alternative for accessing the [Relay](#relay) network. -### [GossipSub](/overview/concepts/network-domains#gossip-domain) +### [GossipSub](/learn/concepts/network-domains#gossip-domain) GossipSub is a [protocol](#protocol) for efficient and scalable information dissemination in decentralised networks commonly used in blockchain systems. @@ -42,15 +43,15 @@ GossipSub is a [protocol](#protocol) for efficient and scalable information diss Libp2p is a modular network stack and protocol suite that allows developers to build decentralised, peer-to-peer applications across various network protocols. -### Light Node +### Light node A light node is a [resource-limited](#resource-limited) device or client that leverages service nodes to access the [Relay](#relay) network. -### [Light Push](/overview/concepts/protocols#light-push) +### [Light push](/learn/concepts/protocols#light-push) Light push is a protocol enabling [light nodes](#light-node) to send [messages](#waku-message) to the [Relay](#relay) network and receive acknowledgements confirming that a [peer](#peer) has received them. -### Mostly Offline +### Mostly offline Mostly offline devices are clients who spend most of their time offline or disconnected from the internet and only occasionally to the internet and [Waku Network](#waku-network). Examples include browsers and mobile phones. @@ -58,7 +59,7 @@ Mostly offline devices are clients who spend most of their time offline or disco A node is a device or client that implements Waku [protocols](#protocol) and leverages the [Waku Network](#waku-network) to enable secure and private peer-to-peer web3 communication. -### Node Key +### Node key A node key is a [Secp256k1](https://en.bitcoin.it/wiki/Secp256k1) (64-char hex string) private key for generating the [PeerID](#peer-id), [listening](#transport) addresses, and [discovery](#peer-discovery) addresses of a Waku node. @@ -70,11 +71,11 @@ The payload field in a [Waku Message](#waku-message) contains the application da A peer refers to other [nodes](#node) and participants of the [Waku Network](#waku-network) with whom communication and interaction are possible. -### [Peer Discovery](/overview/concepts/peer-discovery) +### [Peer discovery](/learn/concepts/peer-discovery) Peer discovery is when a [node](#node) locates and gets information about other [peers](#peer) in the [Waku Network](#waku-network). -### [Peer Exchange](/overview/concepts/peer-exchange) +### [Peer exchange](/learn/concepts/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). @@ -82,7 +83,7 @@ Peer exchange is a [peer discovery](#peer-discovery) mechanism that enables [lig `PeerID` is the unique identifier of a [node](#node) in the [Waku Network](#waku-network) generated from the cryptographic hash of the node's public key. -### [Protocol](/overview/concepts/protocols) +### [Protocol](/learn/concepts/protocols) A protocol is a set of rules that enables [nodes](#node) within the [Waku Network](#waku-network) to perform various functionalities such as message sending, relaying, filtering, storing, retrieving, and more. @@ -90,35 +91,35 @@ A protocol is a set of rules that enables [nodes](#node) within the [Waku Networ Publish/Subscribe (Pub/Sub) is an asynchronous messaging pattern where publishers send messages to topics, and subscribers receive messages from topics of interest, allowing efficient one-to-many communication. -### Pub/Sub Topic +### Pub/Sub topic A Pub/Sub topic is a string that serves as an identifier for the topic of interest among [GossipSub](#gossipsub) peers. Peers interested in the same topic are likely to maintain a connection and forward messages received on that topic. -### [Rate Limit Nullifiers](https://rfc.vac.dev/spec/64/#rln-rate-limiting) +### [Rate limit nullifiers](https://rfc.vac.dev/spec/64/#rln-rate-limiting) Rate Limit Nullifiers (RLN) are a construct based on zero-knowledge proofs that enables rate limiting functionality while preserving the users's anonymity. -### [Relay](/overview/concepts/protocols#relay) +### [Relay](/learn/concepts/protocols#relay) Relay is a [protocol](#protocol) that extends the [GossipSub protocol](#gossipsub) to enable secure and censorship resistant [message](#waku-message) sending and receiving among [peers](#peer) while preserving privacy. It also scales the [Waku Network](#waku-network) to accommodate many nodes efficiently. -### Resource-Limited +### Resource-limited Resource-limited refers to environments or devices restricting available resources, including bandwidth, CPU, memory, disk, and battery power. -### [RLN Relay](/overview/concepts/protocols#rln-relay) +### [RLN relay](/learn/concepts/protocols#rln-relay) RLN Relay is an extension of the [Relay protocol](#relay) that uses [Rate Limit Nullifiers (RLN)](#rate-limit-nullifiers) to prevent spam economically by enforcing a rate limit on messages over time, imposing penalties, and facilitating network removal for spammers. -### [SDK](/guides/nodes-and-sdks) +### [SDK](/) SDKs are tools, libraries, and resources to integrate Waku's private, secure, and censorship-free communication features into various applications. -### [Store](/overview/concepts/protocols#store) +### [Store](/learn/concepts/protocols#store) Store is a [protocol](#protocol) that enables the storage of relayed [messages](#waku-message) in the network, allowing offline peers to retrieve missed messages upon reconnecting to the network. -### [Transport](/overview/concepts/transports) +### [Transport](/learn/concepts/transports) A transport is a network mechanism that establishes connections between [peers](#peer) and enables efficient transmission, routing, and delivery of data packets. @@ -126,18 +127,18 @@ A transport is a network mechanism that establishes connections between [peers]( Waku is a family of private, secure, decentralised, and peer-to-peer web3 communication [protocols](#protocol) designed to operate in [resource-limited](#resource-limited) environments and suitable for [node](#node) or desktop application use. Additionally, these protocols collectively form the [Waku Network](#waku-network). -### [Waku Message](/overview/concepts/protocols#waku-message) +### [Waku message](/learn/concepts/protocols#waku-message) Waku Message defines the structure of messages in the [Waku Network](#waku-network), including the [content topic](#content-topic), [payload](#payload), and metadata for application-specific processing. -### [Waku Message Payload Encryption](https://rfc.vac.dev/spec/26/) +### [Waku message payload encryption](https://rfc.vac.dev/spec/26/) Waku Message Payload Encryption provides guidelines for implementing secure and private communication in the [Waku Network](#waku-network). It covers encryption, decryption, and signing methods for message [payloads](#payload), focusing on confidentiality, authenticity, integrity, and unlinkability. -### [Waku Network](/overview/waku-network) +### [Waku network](/learn/waku-network) The Waku Network is an open-access, scalable peer-to-peer messaging network emphasizing privacy protection and accessibility to [resource limited](#resource-limited) devices. -### [Waku Noise](https://rfc.vac.dev/spec/35/) +### [Waku noise](https://rfc.vac.dev/spec/35/) Waku Noise is a specified way to use the [Noise Protocol Framework](http://noiseprotocol.org/) to build protocols that enable secure key-exchange mechanisms for encrypted communication with confidentiality, authenticity, integrity, strong forward secrecy, and identity-hiding properties. \ No newline at end of file diff --git a/docs/overview/reference/research-in-progress.md b/docs/learn/research.md similarity index 91% rename from docs/overview/reference/research-in-progress.md rename to docs/learn/research.md index 8bd088a..f0eae36 100644 --- a/docs/overview/reference/research-in-progress.md +++ b/docs/learn/research.md @@ -1,16 +1,17 @@ --- -title: Research in Progress +title: Research +hide_table_of_contents: true --- The following features are currently experimental and under research and initial implementation: -## Economic Spam Resistance +## Economic spam resistance We aim to enable an incentivised 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 the [RLN Relay blog post](https://vac.dev/rln-relay). We have prepared a PoC implementation of this method in JS: -## Prevention of Denial of Service (DoS) and Node Incentivisation +## Prevention of denial of service (DoS) and node incentivisation Denial of service signifies the case where an adversarial peer exhausts another node's service capacity (e.g., by making a large number of requests) and makes it unavailable to the rest of the system. RnD on DoS attack mitigation can tracked from here: . diff --git a/docs/overview/reference/security-features.md b/docs/learn/security-features.md similarity index 83% rename from docs/overview/reference/security-features.md rename to docs/learn/security-features.md index 26c68e7..8099774 100644 --- a/docs/overview/reference/security-features.md +++ b/docs/learn/security-features.md @@ -1,5 +1,6 @@ --- title: Security Features +hide_table_of_contents: true --- Waku's protocol layers offer different services and security considerations, shaping the overall security of Waku. We document the security models in the [RFCs of the protocols](https://rfc.vac.dev/), aiming to provide transparent and open-source references. This empowers Waku users to understand each protocol's security guarantees and limitations. @@ -10,23 +11,23 @@ Some of the Waku's security features include the following: Waku ensures pseudonymity across its protocol layers, using libp2p `PeerID` as identifiers instead of disclosing true identities. However, it is important to note that pseudonymity does not provide complete anonymity. Actions performed under the same pseudonym (`PeerID`) can be linked, leading to the potential re-identification of the actual actor. -## [Anonymity/Unlinkability](https://rfc.vac.dev/spec/10/#anonymity--unlinkability) +## [Anonymity/unlinkability](https://rfc.vac.dev/spec/10/#anonymity--unlinkability) Anonymity means an adversary cannot connect an actor to their actions or data. To achieve anonymity, avoiding linking activities with actors or their Personally Identifiable Information (PII) is crucial. In Waku, the following anonymity features are provided: -- [Publisher-Message Unlinkability](https://rfc.vac.dev/spec/11/#security-analysis): Ensures that the publisher of messages in the `Relay` protocol cannot be linked to their published messages. -- [Subscriber-Topic Unlinkability](https://rfc.vac.dev/spec/11/#security-analysis): Ensures that the subscriber of topics in the `Relay` protocol cannot be linked to the topics they have subscribed to. +- [Publisher-message unlinkability](https://rfc.vac.dev/spec/11/#security-analysis): Ensures that the publisher of messages in the `Relay` protocol cannot be linked to their published messages. +- [Subscriber-topic unlinkability](https://rfc.vac.dev/spec/11/#security-analysis): Ensures that the subscriber of topics in the `Relay` protocol cannot be linked to the topics they have subscribed to. -## [Spam Protection](https://rfc.vac.dev/spec/10/#spam-protection) +## [Spam protection](https://rfc.vac.dev/spec/10/#spam-protection) 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 behaviour and remove peers with low scores. -Ongoing research is being conducted, including developing [Rate Limit Nullifiers (RLN)](/overview/concepts/protocols#rln-relay), which can be explored further at: . +Ongoing research is being conducted, including developing [Rate Limit Nullifiers (RLN)](/learn/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) +## [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 [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) +## [Security considerations](https://rfc.vac.dev/spec/10/#security-considerations) In protocols like `Store` and `Filter`, where direct connections are required for the designated service, anonymity or unlinkability is not guaranteed. This is because nodes use their `PeerID` to identify each other during direct connections, making the service obtained in these protocols linkable to the beneficiary's `PeerID`, considered Personally Identifiable Information (PII). In `Store`, the queried node can link the querying node's `PeerID` to the topics being queried. Similarly, in `Filter`, a node can link the `PeerID` of a light node to its content filter. \ No newline at end of file diff --git a/docs/overview/waku-network.md b/docs/learn/waku-network.md similarity index 93% rename from docs/overview/waku-network.md rename to docs/learn/waku-network.md index a08e596..bd4320f 100644 --- a/docs/overview/waku-network.md +++ b/docs/learn/waku-network.md @@ -1,5 +1,6 @@ --- title: The Waku Network +hide_table_of_contents: true --- :::info @@ -15,7 +16,7 @@ The Waku Network is a shared p2p messaging network that is open-access, useful f If you want to learn more about the Waku Network, the [WAKU2-NETWORK RFC](https://rfc.vac.dev/spec/64/) provides an in-depth look under the hood. -## Why Join the Waku Network? +## Why join the Waku network? 1. Applications or projects can build decentralized communication components on this network, gaining from the fault-tolerance of shared infrastructure, the out-of-the-box censorship resistance of a p2p network and the privacy-preservation of Waku protocols. 2. Supporters of public goods and decentralized infrastructure can run their nodes to support the network. @@ -23,9 +24,9 @@ If you want to learn more about the Waku Network, the [WAKU2-NETWORK RFC](https: ## Prerequisites -1. **Ethereum Sepolia WebSocket Endpoint**, which can be yours or from a third party. Have a look at the [Access a Sepolia Node Using Infura](https://github.com/waku-org/nwaku/blob/master/docs/tutorial/pre-requisites-of-running-on-chain-spam-protected-chat2.md#3-access-a-node-on-the-sepolia-testnet-using-infura) guide for a free Infura option. This node is used to interact with the [on-chain RLN membership contract](https://rfc.vac.dev/spec/17/). +1. **Ethereum Sepolia WebSocket endpoint**, which can be yours or from a third party. Have a look at the [Access a Sepolia Node Using Infura](https://github.com/waku-org/nwaku/blob/master/docs/tutorial/pre-requisites-of-running-on-chain-spam-protected-chat2.md#3-access-a-node-on-the-sepolia-testnet-using-infura) guide for a free Infura option. This node is used to interact with the [on-chain RLN membership contract](https://rfc.vac.dev/spec/17/). 2. **Wallet with Sepolia Ethereum** (less than 0.1 Sepolia ETH). Have a look at the [Create a Sepolia Ethereum Wallet](https://github.com/waku-org/nwaku/blob/master/docs/tutorial/pre-requisites-of-running-on-chain-spam-protected-chat2.md#1-create-a-sepolia-ethereum-account-and-obtain-its-private-key) and [Obtain Sepolia Ethereum from Faucet](https://github.com/waku-org/nwaku/blob/master/docs/tutorial/pre-requisites-of-running-on-chain-spam-protected-chat2.md#2-obtain-sepolia-eth-from-faucet) guides to get a Sepolia wallet and fund it with some Sepolia Ethereum. This wallet is required to register [RLN membership](https://rfc.vac.dev/spec/17/#setup-and-registration), which is essential for publishing on the network. -## Running a Waku Network Node +## Running a Waku network node Have a look at the [Run Nwaku with Docker Compose](/guides/nwaku/run-docker-compose) guide for instructions on running a [nwaku](https://github.com/waku-org/nwaku) node in the Waku Network. Use the Sepolia node and wallet you obtained above. \ No newline at end of file diff --git a/docs/overview/reference/waku-vs-libp2p.md b/docs/learn/waku-vs-libp2p.md similarity index 61% rename from docs/overview/reference/waku-vs-libp2p.md rename to docs/learn/waku-vs-libp2p.md index f90e100..b558734 100644 --- a/docs/overview/reference/waku-vs-libp2p.md +++ b/docs/learn/waku-vs-libp2p.md @@ -1,19 +1,20 @@ --- title: Comparing Waku and libp2p +hide_table_of_contents: true --- Since Waku is built on top of libp2p, they share a lot of concepts and terminologies between them. However, there are key differences between them that are worth noting. -## Waku as a Service Network +## Waku as a service network -Waku intends to incentivise mechanisms to run nodes, but it is not part of libp2p's scope. Additionally, users or developers do not have to deploy their infrastructure as a prerequisite to use Waku. It is a service network. However, you are encouraged to [run a node](/guides/nodes-and-sdks#run-a-waku-node) to support and decentralise the network. +Waku intends to incentivise mechanisms to run nodes, but it is not part of libp2p's scope. Additionally, users or developers do not have to deploy their infrastructure as a prerequisite to use Waku. It is a service network. However, you are encouraged to [run a node](/#run-a-waku-node) to support and decentralise the network. -## Waku as a Turnkey Solution +## Waku as a turnkey solution Waku includes various protocols covering the following domains: privacy preservation, censorship resistance, and platform agnosticism, allowing it to run on any platform or environment. -Waku provides 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. +Waku provides out-of-the-box protocols to enable mostly offline/resource-limited devices, [Store](/learn/concepts/protocols#store)/[Light Push](/learn/concepts/protocols#light-push)/[Filter](/learn/concepts/protocols#filter) caters to those use cases. -## Economic Spam Protection +## Economic spam protection -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. +libp2p does not have strong spam protection guarantees, [RLN Relay](/learn/concepts/protocols#rln-relay) is a protocol being developed by the Waku team towards this goal. diff --git a/docs/overview/concepts/network-domains.md b/docs/overview/concepts/network-domains.md deleted file mode 100644 index e66b56e..0000000 --- a/docs/overview/concepts/network-domains.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Network Domains ---- - -Waku is a unified and cohesive entity that offers a rich ecosystem with three distinct network interaction domains. These domains serve specialised purposes and contribute to the robust functionality of Waku, forming its foundation. - -## 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/discv5) and [Peer Exchange](/overview/concepts/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. - -## Request/Response Domain - -Waku provides a set of protocols to optimise its performance in resource-limited environments like low bandwidth or mostly offline scenarios for 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. -- [Light Push](/overview/concepts/protocols#light-push) facilitates message publication for nodes with limited bandwidth and short connection windows. - -## Overview of Protocol Interaction - -Here is a diagram illustrating the interaction between different protocols within the Waku Network. - -```mdx-code-block -import ProtocolInteraction from "@site/diagrams/_protocol-interaction.md"; - - -``` \ No newline at end of file diff --git a/docs/overview/concepts/peer-discovery.md b/docs/overview/concepts/peer-discovery.md deleted file mode 100644 index 6272734..0000000 --- a/docs/overview/concepts/peer-discovery.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Peer Discovery ---- - -When initialising a Waku node, it must connect with other peers to enable message sending, receiving, and retrieval. To achieve this, a discovery mechanism is employed to locate other peers in the network. This process is known as bootstrapping. - -Once a connection is established, the node must actively seek out additional peers to have: - -- Sufficient peers in the [Relay](/overview/concepts/protocols#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 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. - -Waku supports multiple peer discovery mechanisms, such as: - -- [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/history.md b/docs/overview/history.md deleted file mode 100644 index 4a7e4ae..0000000 --- a/docs/overview/history.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -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). - -```mdx-code-block -import History from "@site/diagrams/_history.md"; - - -``` - -### 2013 - -The Ethereum White Paper was published, unveiling the holy trinity of web3, comprising: - -- Ethereum for consensus. -- Swarm for decentralised storage. -- Whisper for peer-to-peer messaging. - -### 2015-2018 - -The development of the Whisper protocol lagged behind the advancements made by the Ethereum EVM and Swarm, primarily because there was no dedicated team working on building the protocol. - -### 2018 - -Owing to the lack of progress made on Whisper and growing concerns around scalability, [Vac](https://vac.dev/) was established to focus on researching and developing more scalable peer-to-peer messaging solutions. - -### 2020 - -`Waku v1` replaces Whisper as the messaging protocol in Status, resulting in the following: - -- Enhanced performance. -- Better scalability. -- Capability to work in resource-limited environments. -- And many more. - -### 2021 - -`Waku v2` releases with a fully revamped suite of protocols that not only supersedes but also surpasses the performance of `Waku v1`. - -### Present Day - -Waku has continued to evolve and enhance itself, enabling privacy-focused and uncompromised web3 communication at scale. \ No newline at end of file diff --git a/docs/overview/index.md b/docs/overview/index.md deleted file mode 100644 index d63539d..0000000 --- a/docs/overview/index.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Introduction to Waku -slug: / ---- - -:::caution -Waku has risks and limitations as it is still developing and preparing for extensive adoption. However, it is already demonstrating its capabilities by [powering various applications](/powered-by-waku). [Join our community](/community) to stay updated on our progress. -::: - -Waku is a family of robust and censorship resistant communication protocols enabling privacy-focused messaging for web3 applications. 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 integrating Waku into your DApp, you can add decentralised communication features to your application without compromising security or privacy. - -## Motivation and Goals - -The Waku family of protocols is designed for diverse applications due to their properties, such as: - -### Generalised - -Waku aims to solve the problem of ephemeral messaging between subsystems and nodes through a flexible, secure, and private protocol. It supports human-to-human and machine-to-machine messaging scenarios but is not designed for data storage. - -### Peer-to-Peer - -Waku is suitable for applications that require a peer-to-peer approach, offering the following advantages: - -- Censorship resistance with no single point of failure. -- Adaptive and scalable network. -- Shared infrastructure, leveraging the capabilities of Waku as a service network. - -### Platform Agnostic - -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 mostly offline. - -### Privacy Preserving - -Waku can cater to applications that require privacy guarantees, such as: - -- Pseudonymity and not being tied to any Personally Identifiable Information (PII). -- Metadata protection in transit. -- Various forms of [unlinkability](/overview/reference/security-features#anonymityunlinkability). - -### Modular Design - -Waku nodes are adaptive and can be customised 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. -- Stronger guarantees for spam protection vs. economic registration cost. - -These options are part of the [Anonymity Trilemma](https://eprint.iacr.org/2017/954.pdf), which Waku addresses through its adjustable protocol. - - -### Service Network - -Waku provides developers with a convenient solution for building decentralised communication systems, eliminating the need to build a peer-to-peer network from scratch. Node operators can offer multiple services, such as: - -- Storing messages for offline devices. -- Enabling bandwidth-saving access to the [Relay](/overview/concepts/protocols#relay) network through [Light Push](/overview/concepts/protocols#light-push) and [Filter](/overview/concepts/protocols#filter) protocols. -- Implementing spam-prevention and DoS-mitigation features. -- Providing a resilient and shared [Relay](/overview/concepts/protocols#relay) infrastructure that applications can leverage to enhance reliability and efficiency. - -## How Does Waku Work? - -The [Relay](/overview/concepts/protocols#relay) protocol is the foundation of the Waku Network, which employs a Pub/Sub architecture built on the [libp2p GossipSub protocol](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/README.md). Additionally, various other Waku protocols have been created to facilitate specific functionalities, including but not limited to: - -1. Facilitating the retrieval of historical messages for mostly offline devices. -2. Providing solutions for encrypted communication, such as symmetric encryption, ECIES/asymmetric encryption, and noise handshake-based key turns. -3. Preserving bandwidth usage for resource-limited environments. -4. Implementing economic spam protection (rate limits) while ensuring privacy. -5. Developing methods to protect against mass deanonymisation (currently being researched). -6. Designing strategies to scale `Relay/GossipSub` securely. - -If you want to learn more about how Waku works, the [WAKU2 RFC](https://rfc.vac.dev/spec/10/) provides an in-depth look under the hood. diff --git a/docs/overview/use-cases.md b/docs/overview/use-cases.md deleted file mode 100644 index d33024f..0000000 --- a/docs/overview/use-cases.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: Use Cases ---- - -Waku is a decentralised communication network, facilitating secure and private person-to-person and machine-to-machine communication without a central authority. It supports various use cases, including but not limited to: - -### Chat Messengers - -Waku can be used as the communication layer when building a private, decentralised, and censorship resistant messenger. - -#### Demos - -* [Status Web](https://github.com/status-im/status-web) - -### Polls - -With Waku, you can create, answer, and view censorship resistant polls, promoting a democratic and transparent voting environment immune to manipulation and censorship. - -#### Demos - -* [Waku Connect Poll SDK](https://github.com/status-im/wakuconnect-vote-poll-sdk) - -### NFT Marketplaces - -Waku can be used to take NFT bids and offers off-chain, enabling gas savings. Additionally, it allows for adding a social media layer, enabling NFT owners to like, comment, and perform other social actions. - -#### Demos - -* [SmolPuddle Marketplace](https://github.com/Agusx1211/smolpuddle-web) - -### State Channels - -Waku can enable two parties to establish and sustain a state channel effortlessly, facilitating message exchange and seamless updates to their shared agreement without direct blockchain involvement. - -### Voting and Proposals - -To save on gas fees, votes for proposals submitted on the blockchain can be exchanged over Waku. These votes can then be aggregated and submitted to the blockchain to commit the result. - -#### Demos - -* [Waku Connect Poll SDK](https://github.com/status-im/wakuconnect-vote-poll-sdk) - -### Signature Exchange for Multi-Signature Wallets - -Waku can enable multiple owners of a given multi-signature wallet to exchange signatures in a decentralised, private, and censorship resistant manner, allowing for the approval of transactions. - -### Game Mechanics Communication - -Waku can be used as the communication layer for a peer-to-peer, decentralised game, eliminating the need for a centralised infrastructure for gameplay communications. - -#### Demos - -* [Super Card Game](https://github.com/fjij/ethonline-2021) - -### DApp to Wallet Communication - -DApp operators can use communication between a user's wallet and their DApp to notify users (e.g., governance token holders can be notified to vote on a proposal) or to request transaction signatures from the wallet. - -#### Demos - -* [WalletConnect 2.0](https://walletconnect.com/) -* [HashPack](https://www.hashpack.app/hashconnect) - -### Layer 2 Coordination (Open Market, Spam Protected Mempool) - -Waku can broadcast and aggregate Layer 2 transactions to enhance privacy, anonymity, and resilience. Aggregating transactions reduces network load and improves scalability, ensuring a more robust Layer 2 ecosystem. - -### Generalised Marketplaces - -Waku can enable users to offer, bid, accept, and trade goods and services, making it possible to create ride-sharing or trading apps. - -#### Demos - -* [Waku-Uber](https://github.com/TheBojda/waku-uber) - -### Social Media Platforms - -While chat messengers are a type of social media that can be decentralised and made censorship resistant through Waku, other forms of social media, such as news feeds, blog posts, and audio or video sharing, can also benefit from using Waku. \ No newline at end of file diff --git a/docs/overview/why-waku.md b/docs/overview/why-waku.md deleted file mode 100644 index 21432e6..0000000 --- a/docs/overview/why-waku.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Why Waku? ---- - -Present-day communication is predominantly centralised, enabling significant third-party intervention, with profit motives overshadowing principles and downplaying censorship and privacy concerns. This shift leads to the exploitation and unauthorised use of user data in the surveillance economy, where data ownership is no longer in the hands of individuals. - -Waku transforms how individuals communicate and manage data by offering a scalable, decentralised solution that grants ultimate control. - -- Waku improves upon Whisper's capabilities by overcoming limitations and addressing functional gaps. -- Provides a public infrastructure for the Ethereum and multi-chain ecosystem, serving as a common good. -- Waku is not confined to a particular blockchain. -- Modular, adaptable, configurable, and can cater to various use cases. -- Enables developers to decentralise communication in their DApps or move actions off-chain while maintaining decentralisation. -- Designed to run on various platforms, including mobile devices, cloud environments, web browsers, desktop apps, or even a [Dappnode](https://dappnode.com/)! - -## Why Waku is Necessary - -| | Whisper | Waku | -| - | - | - | -| **Scalability** | Whisper does not 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. | -| **Incentivisation Infrastructure** | There is no incentive to run a Whisper node. | Research in progress to design incentivisation for node operators. | -| **Formal Specification/Documentation** | Lack of formal and unambiguous specification. | The specs and docs are open-source and licenced under CC0, making them freely available for anyone to read, modify and improve without restrictions. | -| **Portability** | Runs over devp2p which limits where Whisper can run and how. | Waku is built using libp2p, making it easy to run Waku anywhere. | diff --git a/docs/powered-by-waku.mdx b/docs/powered-by-waku.mdx deleted file mode 100644 index d87a3a7..0000000 --- a/docs/powered-by-waku.mdx +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Powered by Waku ---- - -import { Grid, AppCard } from "@site/src/components/mdx"; - -Leap into the future with Waku! Revolutionise communication, collaboration, and connectivity. Join us and create something extraordinary! - - - - - - - - - - - - - - - diff --git a/docs/presentations.md b/docs/presentations.md deleted file mode 100644 index febb221..0000000 --- a/docs/presentations.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Watch Our Presentations ---- - -## Waku Workshop: Running Your Own Waku Node - - - -## Waku Workshop: Getting Started with Waku - - - -## Hashing it Out: Decentralised Messaging - - - -## Using ZKP for Better p2p Messaging with Waku - - - -## How to Ethically Build Public Good Infrastructure - - - -## Building Privacy-Protecting Infrastructure - - - -## Secureum TrustX - Waku: Enabling a New Dimension for DApps - - - -## Waku: Enabling a New Dimension for DApps - - - -## The Next Level of Decentralisation Messaging in Web3 - - - -## Build with Waku & DappConnect - - - -## DappConnect: Enabling Decentralised Communications Using Waku - - - -## DappConnect: Decentralised Communication Using Waku - - \ No newline at end of file diff --git a/docs/terms.md b/docs/terms.md index 3bdb8e3..b514b90 100644 --- a/docs/terms.md +++ b/docs/terms.md @@ -1,6 +1,7 @@ --- displayed_sidebar: null sidebar_class_name: hidden +hide_table_of_contents: true --- # Terms of Use @@ -78,5 +79,4 @@ These Website Terms of Use cover the entire agreement between you and us regardi The captions and headings identifying sections and subsections of these Website Terms of Use are for reference only and do not define, modify, expand, limit, or affect the interpretation of any provisions of these Website Terms of Use. -If any part of these Website Terms of Use is held invalid or unenforceable, that part will be severable from these Website Terms of Use, and the remaining portions will remain in full force and effect. If we fail to enforce any of these Website Terms of Use, that does not mean that we have waived our right to enforce them. - +If any part of these Website Terms of Use is held invalid or unenforceable, that part will be severable from these Website Terms of Use, and the remaining portions will remain in full force and effect. If we fail to enforce any of these Website Terms of Use, that does not mean that we have waived our right to enforce them. \ No newline at end of file diff --git a/docusaurus.config.js b/docusaurus.config.js index c1e4716..e7b1650 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -65,60 +65,19 @@ const config = { { type: "docSidebar", position: "left", - sidebarId: "main", - label: "About Waku", - }, - { - to: "/presentations", - label: "Presentations", - position: "left", - }, - { - to: "/powered-by-waku", - label: "Powered by Waku", - position: "left", - }, - { - type: "dropdown", + sidebarId: "guides", label: "Guides", - position: "right", - items: [ - { - label: "Nodes and SDKs", - to: "/guides/nodes-and-sdks", - }, - { - label: "Run a Nwaku Node", - to: "/guides/run-nwaku-node", - }, - { - label: "JavaScript Waku SDK", - to: "/guides/js-waku/", - }, - ], }, { - type: "dropdown", - label: "Community", - position: "right", - items: [ - { - label: "Join Our Community", - to: "/community", - }, - { - label: "Contribute to Waku", - to: "/contribute", - }, - { - label: "Waku Bounties", - to: "https://github.com/waku-org/bounties", - }, - { - label: "Bug Bounty Program", - to: "https://hackenproof.com/status-dot-im/waku", - }, - ], + type: "docSidebar", + position: "left", + sidebarId: "learn", + label: "Learn", + }, + { + href: "https://discord.waku.org", + position: "left", + label: "Discord", }, { href: "https://github.com/waku-org", @@ -134,11 +93,11 @@ const config = { title: "Guides", items: [ { - to: "/guides/nodes-and-sdks", - label: "Nodes and SDKs", + to: "/", + label: "Getting Started", }, { - to: "/guides/run-nwaku-node", + to: "/guides/nwaku/run-node", label: "Run a Nwaku Node", }, { @@ -151,36 +110,40 @@ const config = { title: "Community", items: [ { - href: "https://discord.waku.org", + href: "https://discord.waku.org/", label: "Discord", }, { - href: "https://twitter.com/waku_org", - label: "Twitter", + href: "https://twitter.com/waku_org/", + label: "X", }, { - href: "https://t.me/waku_org", + href: "https://t.me/waku_org/", label: "Telegram", }, { - href: "https://forum.vac.dev", + href: "https://forum.vac.dev/", label: "Vac Forum", }, + { + href: "https://github.com/waku-org/bounties/", + label: "Bounties", + }, ], }, { title: "Resources", items: [ { - href: "https://github.com/waku-org", + href: "https://github.com/waku-org/", label: "GitHub", }, { - href: "https://vac.dev/research", + href: "https://blog.waku.org/", label: "Blog", }, { - href: "https://rfc.vac.dev", + href: "https://rfc.vac.dev/", label: "Vac RFCs", }, ], @@ -190,7 +153,7 @@ const config = { items: [ { href: "/terms", - label: "Terms & Conditions", + label: "Terms of Use", }, ], }, diff --git a/scripts/config-table-generator.py b/scripts/config-table-generator.py index 921e5c2..0e6ddc2 100644 --- a/scripts/config-table-generator.py +++ b/scripts/config-table-generator.py @@ -12,7 +12,7 @@ def parse_table_heading(line: str) -> Tuple[str, bool]: table_heading = re.split('##', line)[1].strip() if 'config' not in table_heading or 'Application-level' in table_heading: return None, False - table_heading = table_heading.title() + table_heading = table_heading.capitalize() word_replace_re = re.compile('|'.join([ r'(Configuration)', r'(And)', r'(Lightpush)', @@ -20,12 +20,12 @@ def parse_table_heading(line: str) -> Tuple[str, bool]: r'(Discovery V5)', r'(Websocket)' ])) word_replace_dict = { - 'Configuration': 'Config', 'And': 'and', 'Lightpush': 'Light Push', + 'Configuration': 'config', 'And': 'and', 'Lightpush': 'Light push', 'Json-Rpc': 'JSON-RPC', 'Rest Http': 'REST HTTP', 'Dns': 'DNS', '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 + return '## ' + table_heading, Trues def fetch_config_file(config_path: str) -> str: config_file = requests.get(config_path) @@ -37,7 +37,7 @@ def fetch_config_file(config_path: str) -> str: def extract_config(config_path: str) -> str: config_data = fetch_config_file(config_path) - config_table = "## Application-Level Config\n\n| Name | Default Value | Description |\n| - | - | - |\n" + config_table = "## Application-level config\n\n| Name | Default Value | Description |\n| - | - | - |\n" row = {"name": None, "default": "", "description": None} for line in config_data: line = line.strip() diff --git a/sidebars.js b/sidebars.js index d966285..addce68 100644 --- a/sidebars.js +++ b/sidebars.js @@ -2,67 +2,23 @@ /** @type {import("@docusaurus/plugin-content-docs").SidebarsConfig} */ const sidebars = { - main: [ - "overview/index", - "overview/waku-network", - "overview/history", - "overview/why-waku", - "overview/use-cases", - { - type: "category", - label: "Concepts", - items: [ - "overview/concepts/protocols", - "overview/concepts/content-topics", - "overview/concepts/network-domains", - "overview/concepts/transports", - { - type: "category", - label: "Peer Discovery", - link: { - type: "doc", - id: "overview/concepts/peer-discovery", - }, - items: [ - "overview/concepts/static-peers", - "overview/concepts/dns-discovery", - "overview/concepts/discv5", - "overview/concepts/peer-exchange", - ] - }, - ] - }, - { - type: "category", - label: "Reference", - collapsed: false, - items: [ - "overview/reference/glossary", - "overview/reference/security-features", - "overview/reference/research-in-progress", - "overview/reference/waku-vs-libp2p", - ] - }, - { - type: 'html', - value: 'Nodes and SDKs', - } - ], guides: [ - "guides/nodes-and-sdks", + "guides/getting-started", { type: "category", label: "Run a Nwaku Node", link: { type: "doc", - id: "guides/run-nwaku-node", + id: "guides/nwaku/run-node", }, items: [ "guides/nwaku/build-source", "guides/nwaku/run-docker", "guides/nwaku/run-docker-compose", "guides/nwaku/configure-discovery", - "guides/nwaku/configure-nwaku" + "guides/nwaku/configure-nwaku", + "guides/nwaku/config-methods", + "guides/nwaku/config-options", ] }, { @@ -91,30 +47,39 @@ const sidebars = { }, ] }, + ], + learn: [ + "learn/waku-network", { type: "category", - label: "Reference", + label: "Concepts", collapsed: false, items: [ - "guides/reference/node-config-methods", - "guides/reference/node-config-options", + "learn/concepts/protocols", + "learn/concepts/content-topics", + "learn/concepts/network-domains", + "learn/concepts/transports", + { + type: "category", + label: "Peer Discovery", + link: { + type: "doc", + id: "learn/concepts/peer-discovery", + }, + items: [ + "learn/concepts/static-peers", + "learn/concepts/dns-discovery", + "learn/concepts/discv5", + "learn/concepts/peer-exchange", + ] + }, ] }, + "learn/security-features", + "learn/research", + "learn/waku-vs-libp2p", + "learn/glossary", ], - community: [ - "community", - "contribute", - "presentations", - "powered-by-waku", - { - type: 'html', - value: 'Waku Bounties', - }, - { - type: 'html', - value: 'Bug Bounty Program', - }, - ] }; module.exports = sidebars; \ No newline at end of file