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

docs restructure (#140)

This commit is contained in:
LordGhostX 2023-11-23 12:01:32 +01:00 committed by GitHub
parent 3de936c928
commit 590b7d857a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
50 changed files with 431 additions and 859 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.cspell.json
View File

@ -83,7 +83,7 @@
"yarn.lock",
"tsconfig.json",
"node_modules/**",
"docs/guides/reference/node-config-options.md"
"docs/guides/nwaku/config-options.md"
],
"patterns": [
{

12
README.md
View File

@ -13,13 +13,13 @@ The Waku Documentation Portal can be accessed at <https://docs.waku.org/> 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
```

18
diagrams/_history.md
View File

@ -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:"🔥"
```

2
diagrams/_protocol-interaction.md
View File

@ -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.

21
docs/community.md
View File

@ -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.

37
docs/contribute.md
View File

@ -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: <https://github.com/waku-org/bounties>.
## 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: <https://hackenproof.com/status-dot-im/waku>.
## 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 <https://github.com/waku-org/research>.

17
docs/guides/nodes-and-sdks.md → docs/guides/getting-started.md
View File

@ -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 |
| - | - | - |

21
docs/guides/js-waku/configure-discovery.md
View File

@ -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:
<Tabs groupId="package-manager">
<TabItem value="npm" label="NPM">
@ -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";

19
docs/guides/js-waku/debug-waku-dapp.md
View File

@ -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:

19
docs/guides/js-waku/index.md
View File

@ -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";
<script src="https://cdn.jsdelivr.net/npm/protobufjs@latest/dist/protobuf.min.js"></script>
```
## 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).

21
docs/guides/js-waku/light-send-receive.md
View File

@ -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`:

9
docs/guides/js-waku/manage-filter.md
View File

@ -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";
<FilterPingFlow />
```
## 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.
:::

19
docs/guides/js-waku/run-waku-nodejs.md
View File

@ -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: <https://github.com/waku-org/nwaku/issues/1332>.
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: <https://github.com/waku-org/nwaku/issues/1332>.

15
docs/guides/js-waku/store-retrieve-messages.md
View File

@ -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`

3
docs/guides/js-waku/use-waku-create-app.md
View File

@ -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:

15
docs/guides/js-waku/use-waku-react.md
View File

@ -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
</TabItem>
</Tabs>
## 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:

33
docs/guides/nwaku/build-source.md
View File

@ -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';
<Tabs>
<TabItem value="debian" label="Debian and Ubuntu">
```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
</TabItem>
<TabItem value="fedora" label="Fedora">
```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
</TabItem>
<TabItem value="arch" label="Arch Linux">
```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
</TabItem>
<TabItem value="mac" label="MacOS (Homebrew)">
```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
</TabItem>
</Tabs>
## 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.
:::

31
docs/guides/reference/node-config-methods.md → docs/guides/nwaku/config-methods.md
View File

@ -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.
:::

33
docs/guides/reference/node-config-options.md → docs/guides/nwaku/config-options.md
View File

@ -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://<key\>@<fqdn\>' |
| `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.
:::

35
docs/guides/nwaku/configure-discovery.md
View File

@ -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://<key>@<fqdn>` where `<fqdn>` is the fully qualified domain name and `<key>` 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.
:::

83
docs/guides/nwaku/configure-nwaku.md
View File

@ -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 <your.domain.name>
```
:::
## 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]

21
docs/guides/nwaku/run-docker-compose.md
View File

@ -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 <http://localhost:3000/d/yns_4vFVk/nwaku-monitoring> 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.
:::

17
docs/guides/nwaku/run-docker.md
View File

@ -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.
:::

47
docs/guides/run-nwaku-node.md → docs/guides/nwaku/run-node.md
View File

@ -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';
<Tabs>
<TabItem value="request" label="Request">
```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.
:::

7
docs/overview/concepts/content-topics.md → docs/learn/concepts/content-topics.md
View File

@ -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.

1
docs/overview/concepts/discv5.md → docs/learn/concepts/discv5.md
View File

@ -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.

1
docs/overview/concepts/dns-discovery.md → docs/learn/concepts/dns-discovery.md
View File

@ -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/).

34
docs/learn/concepts/network-domains.md Normal file
View File

@ -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";
<ProtocolInteraction />
```

19
docs/learn/concepts/peer-discovery.md Normal file
View File

@ -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)

1
docs/overview/concepts/peer-exchange.md → docs/learn/concepts/peer-exchange.md
View File

@ -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.

13
docs/overview/concepts/protocols.md → docs/learn/concepts/protocols.md
View File

@ -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.

3
docs/overview/concepts/static-peers.md → docs/learn/concepts/static-peers.md
View File

@ -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

5
docs/overview/concepts/transports.md → docs/learn/concepts/transports.md
View File

@ -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

49
docs/overview/reference/glossary.md → docs/learn/glossary.md
View File

@ -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.

7
docs/overview/reference/research-in-progress.md → docs/learn/research.md
View File

@ -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: <https://examples.waku.org/rln-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: <https://github.com/vacp2p/research/issues/148>.

15
docs/overview/reference/security-features.md → docs/learn/security-features.md
View File

@ -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: <https://github.com/vacp2p/research/issues/148>.
Ongoing research is being conducted, including developing [Rate Limit Nullifiers (RLN)](/learn/concepts/protocols#rln-relay), which can be explored further at: <https://github.com/vacp2p/research/issues/148>.
## [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.

7
docs/overview/waku-network.md → docs/learn/waku-network.md
View File

@ -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.

13
docs/overview/reference/waku-vs-libp2p.md → docs/learn/waku-vs-libp2p.md
View File

@ -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.

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

@ -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";
<ProtocolInteraction />
```

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

@ -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)

44
docs/overview/history.md
View File

@ -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";
<History />
```
### 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.

73
docs/overview/index.md
View File

@ -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.

78
docs/overview/use-cases.md
View File

@ -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.

24
docs/overview/why-waku.md
View File

@ -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. |

46
docs/powered-by-waku.mdx
View File

@ -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!
<Grid xs={{ cols: 1, wrap: true, gap: "0 1rem" }} lg={{ cols: 2 }}>
<Grid.Item xs={1}>
<AppCard
name="Status"
description="Waku powers many of the Status super app's features, including its private messaging."
logoSrc="/img/status-mark-black.svg"
logoSrcDark="/img/status-mark-white.svg"
link="https://status.im"
/>
</Grid.Item>
<Grid.Item xs={1}>
<AppCard
name="RAILGUN"
description="The privacy-focused DeFi protocol Railgun anonymises Ethereum transactions with Waku."
logoSrc="/img/railgun-mark-black.svg"
logoSrcDark="/img/railgun-mark-white.svg"
link="https://railgun.org"
/>
</Grid.Item>
<Grid.Item xs={1}>
<AppCard
name="The Graph"
description="Waku powers the Graphcast SDK, enabling the development of gossip-powered applications within The Graph ecosystem."
logoSrc="/img/the-graph-mark-black.svg"
logoSrcDark="/img/the-graph-mark-white.svg"
link="https://thegraph.com/"
/>
</Grid.Item>
<Grid.Item xs={1}>
<AppCard
name="XMTP"
description="Inter-blockchain account messaging protocol XMTP uses Waku to facilitate communication between nodes in its currently permissioned network."
logoSrc="/img/xmtp-mark-black.svg"
logoSrcDark="/img/xmtp-mark-white.svg"
link="https://xmtp.org"
/>
</Grid.Item>
</Grid>

51
docs/presentations.md
View File

@ -1,51 +0,0 @@
---
title: Watch Our Presentations
---
## Waku Workshop: Running Your Own Waku Node
<iframe class="yt-video" src="https://www.youtube.com/embed/_qjKiy_epSE" title="Waku Workshop: Running Your Own Waku Node by Václav Pavlín" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
## Waku Workshop: Getting Started with Waku
<iframe class="yt-video" src="https://www.youtube.com/embed/dMxs5GcbgG4" title="Waku Workshop: Getting Started with Waku by Alvaro Revuelta" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
## Hashing it Out: Decentralised Messaging
<iframe class="yt-video" src="https://www.youtube.com/embed/vmx_oOb2On0" title="Hashing it Out: Decentralised Messaging by Franck Royer" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
## Using ZKP for Better p2p Messaging with Waku
<iframe class="yt-video" src="https://www.youtube.com/embed/eJwX1JpcKQk" title="Using ZKP for better p2p messaging with Waku by Oskar Thorén" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
## How to Ethically Build Public Good Infrastructure
<iframe class="yt-video" src="https://www.youtube.com/embed/yi7nS0g0Yno" title="How to Ethically Build Public Good Infrastructure by Corey Petty" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
## Building Privacy-Protecting Infrastructure
<iframe class="yt-video" src="https://www.youtube.com/embed/CW1DYJifdhs" title="Building Privacy-Protecting Infrastructure by Oskar Thorén" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
## Secureum TrustX - Waku: Enabling a New Dimension for DApps
<iframe class="yt-video" src="https://www.youtube.com/embed/GXU5Fd6gMVw?start=21700" title="Secureum TrustX - Waku: Enabling a New Dimension for DApps by Corey Petty" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
## Waku: Enabling a New Dimension for DApps
<iframe class="yt-video" src="https://www.youtube.com/embed/OdXtMD-hgdg" title="Waku: enabling a new dimension for DApps by Corey Petty" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
## The Next Level of Decentralisation Messaging in Web3
<iframe class="yt-video" src="https://www.youtube.com/embed/1QjxqrLO8WA" title="The Next Level of Decentralisation Messaging in Web3 by Franck Royer" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
## Build with Waku &amp; DappConnect
<iframe class="yt-video" src="https://www.youtube.com/embed/ooRyn4aXsrM" title="EthOnline Status Bounty - Build with Waku &amp; DappConnect by Franck Royer" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
## DappConnect: Enabling Decentralised Communications Using Waku
<iframe class="yt-video" src="https://www.youtube.com/embed/rQOp3qoDF0g" title="DappConnect: Enabling decentralised communications using Waku by Franck Royer" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
## DappConnect: Decentralised Communication Using Waku
<iframe class="yt-video" src="https://www.youtube.com/embed/CBknF-6Z-Ds" title="DappConnect: Decentralised communication using Waku" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>

4
docs/terms.md
View File

@ -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.

89
docusaurus.config.js
View File

@ -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",
},
],
},

8
scripts/config-table-generator.py
View File

@ -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()

97
sidebars.js
View File

@ -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: '<a href="/guides/nodes-and-sdks" target="_blank" rel="noopener noreferrer" class="menu__link external-link">Nodes and SDKs<svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path fill-rule="evenodd" clip-rule="evenodd" d="M11.1918 4H3.42848V2.85715H13.1428V12.5714H11.9999V4.80813L3.83254 12.9755L3.02441 12.1674L11.1918 4Z" fill="white"/></svg>',
}
],
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: '<a href="https://github.com/waku-org/bounties" target="_blank" rel="noopener noreferrer" class="menu__link external-link">Waku Bounties<svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path fill-rule="evenodd" clip-rule="evenodd" d="M11.1918 4H3.42848V2.85715H13.1428V12.5714H11.9999V4.80813L3.83254 12.9755L3.02441 12.1674L11.1918 4Z" fill="white"/></svg>',
},
{
type: 'html',
value: '<a href="https://hackenproof.com/status-dot-im/waku" target="_blank" rel="noopener noreferrer" class="menu__link external-link">Bug Bounty Program<svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path fill-rule="evenodd" clip-rule="evenodd" d="M11.1918 4H3.42848V2.85715H13.1428V12.5714H11.9999V4.80813L3.83254 12.9755L3.02441 12.1674L11.1918 4Z" fill="white"/></svg>',
},
]
};
module.exports = sidebars;