logos-messaging/docs.waku.org
1
0
Fork 0
mirror of https://github.com/logos-messaging/docs.waku.org.git synced 2026-01-02 12:53:12 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'develop' into shard-info-js-waku

Browse Source
This commit is contained in:
LordGhostX 2024-06-05 14:14:32 +01:00 committed by GitHub
commit e73cd9d4ab
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
27 changed files with 409 additions and 226 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.cspell.json
View File

@ -80,6 +80,8 @@
"baarerstrasse",
"FDPIC",
"IPFS",
"cheatsheet",
"hacken",
],
"flagWords": [],
"ignorePaths": [

108
docs/guides/getting-started.md
View File

@ -1,53 +1,93 @@
---
title: Getting Started
title: Introduction to Waku
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. [Join our community](https://waku.org/community/) to stay updated on our progress.
Waku is a family of robust, censorship-resistant, peer-to-peer communication protocols that enable privacy-focused messaging for Web3 applications, allowing you to integrate decentralised communication features into your dApp without compromising security or privacy.
```mermaid
graph LR
S1(Message Sender 1) -->|Message 1| W(The Waku Network)
S2(Message Sender 2) -->|Message 2| W
S3(Message Sender 3) -->|Message 3| W
W -->|Message 1| R1(Message Receiver 1)
W -->|Message 2| R1
W -->|Message 3| R2(Message Receiver 2)
```
<div class="video-container">
<iframe class="yt-video" src="https://www.youtube.com/embed/nIWx5Vp_Qxk" title="Waku Tutorial 001: Introduction to Waku" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
</div>
:::tip
Check out our [Learn section](/learn/waku-network), [YouTube channel](https://www.youtube.com/@wakuorg), and [Blog](https://blog.waku.org/) to dive into how Waku works behind the scenes!
:::
Ready to integrate Waku into your application for private, secure, censorship-free communication? Explore the available SDKs and contribute by running a node.
## What isn’t Waku?
## Run a Waku node
- Waku is not a blockchain but a network composed of protocols designed for Web3 communication, operating without the need for gas fees.
- Waku is not just for messaging applications; it supports the development of complex applications that require secure and private data transmission.
- Waku is not a long-term data storage network; it focuses on short, ephemeral, real-time messaging.
The Waku Network is a decentralised, permissionless system where anyone can run nodes, use the network, and contribute to its support.
## What can Waku be used for?
| | Description | Documentation |
| - | - | - |
| [nwaku](https://github.com/waku-org/nwaku) | Nim-based Waku implementation to run a standalone node and access the network | [Run a Nwaku Node](/guides/nwaku/run-node) |
| [nwaku-compose](https://github.com/waku-org/nwaku-compose) | Pre-configured Docker Compose setup for running a RLN-enabled `nwaku` node with Grafana metrics dashboard (recommended) | [Run Nwaku with Docker Compose](/guides/nwaku/run-docker-compose) |
| [go-waku](https://github.com/waku-org/go-waku) | Golang-based Waku implementation to run a standalone node and access the network | COMING SOON |
1. **Chat Messengers**: Waku can be used to build private, decentralised chat apps resistant to censorship.
2. **Voting and Proposals**: Exchange votes on proposals off-chain via Waku to save gas fees, then submit aggregated results to the blockchain.
3. **NFT Marketplaces**: Use Waku to handle off-chain NFT bids and offers for gas savings, and to integrate social interactions like likes and comments.
4. **State Channels**: Establish and maintain state channels with Waku, facilitating seamless message exchanges and updates without blockchain interaction.
5. **Signature Exchange for Multi-Signature Wallets**: Allow multi-signature wallet owners to exchange signatures privately and securely through Waku.
6. **Game Mechanics Communication**: Implement Waku as a communication layer for decentralised, peer-to-peer gaming, avoiding centralised infrastructure.
7. **Layer 2 Coordination (Open Market, Spam Protected Mempool)**: Broadcast and aggregate Layer 2 transactions via Waku to enhance privacy and scalability, reducing network load.
8. **Social Media Platforms**: Beyond chat messengers, use Waku for decentralised, censorship-resistant social media platforms like news feeds and multimedia sharing.
## Integrate using SDKs
:::tip
Looking for what to build with Waku? Discover a collection of sample ideas and use cases for inspiration, curated by our community at: https://ideas.waku.org/ and [Awesome Waku](https://github.com/waku-org/awesome-waku/).
:::
## Case studies
<div class="case-study-container">
<a href="https://blog.waku.org/thegraph-waku-case-study/" target="_blank" rel="noopener noreferrer"><img src="/img/graph-use-case.jpeg" /></a>
<a href="https://blog.waku.org/railgun-waku-case-study/" target="_blank" rel="noopener noreferrer"><img src="/img/railgun-use-case.jpeg" /></a>
</div>
## Getting started
<div class="video-container">
<iframe class="yt-video two-items" src="https://www.youtube.com/embed/PYQaXCxUCwA" title="Waku Tutorial 001: Introduction to Waku" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
<iframe class="yt-video two-items" src="https://www.youtube.com/embed/sfmMcrbiX0c" title="Build a game using Waku Protocol" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
</div>
### Run a Waku node
Waku is a decentralised, permissionless system where anyone can run a node, use the network, and contribute to its support. We recommend following the [Run Nwaku with Docker Compose](/guides/nwaku/run-docker-compose) guide and [Waku Node Operator Cheatsheet](/Waku-NodeOperator.pdf) to easily run a node.
<div class="video-container">
<iframe class="yt-video" src="https://www.youtube.com/embed/fs0ynLk4z0I" title="How to run a Waku node using Nwaku Compose" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
</div>
:::tip
If you encounter issues running your node or require assistance with anything, please visit the [#node-help channel](https://discord.com/channels/1110799176264056863/1216748184592711691) on our Discord.
:::
### Integrate using SDKs
Waku is implemented in multiple SDKs, allowing it to integrate with different languages and address various use cases efficiently.
| | Description | Documentation |
| - | - | - |
| [@waku/sdk](https://github.com/waku-org/js-waku) | JavaScript/TypeScript SDK designed for browser environments | [JavaScript Waku SDK](/guides/js-waku/) |
| | Description | Documentation |
| -------------------------------------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| [@waku/sdk](https://github.com/waku-org/js-waku) | JavaScript/TypeScript SDK designed for browser environments | [JavaScript Waku SDK](/guides/js-waku/) |
| [@waku/react](https://www.npmjs.com/package/@waku/react) | React components and UI adapters designed for seamless integration with `@waku/sdk` | [Build React DApps Using @waku/react](/guides/js-waku/use-waku-react) |
| [nwaku](https://github.com/waku-org/nwaku) | Nim SDK designed for integration with native Nim applications | COMING SOON |
| [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
### Other integrations
Waku provides integrations tailored for mobile applications, enabling Waku to run efficiently on mobile devices.
| | Description | Documentation |
| - | - | - |
| 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
| | Description | Documentation |
| - | - | - |
| [REST API](https://waku-org.github.io/waku-rest-api/) | REST API interface provided by `nwaku` and `go-waku` to interact with the Waku Network | [Waku Node REST API Reference](https://waku-org.github.io/waku-rest-api/) |
| [@waku/create-app](https://www.npmjs.com/package/@waku/create-app) | Starter kit to bootstrap your next `@waku/sdk` project from various example templates | [Scaffold DApps Using @waku/create-app](/guides/js-waku/use-waku-create-app) |
| | Description | Documentation |
| ------------------------------------------------------------------ | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| [REST API](https://waku-org.github.io/waku-rest-api/) | REST API interface provided by `nwaku` and `go-waku` to interact with the Waku Network | [Waku Node REST API Reference](https://waku-org.github.io/waku-rest-api/) |
| [@waku/create-app](https://www.npmjs.com/package/@waku/create-app) | Starter kit to bootstrap your next `@waku/sdk` project from various example templates | [Scaffold DApps Using @waku/create-app](/guides/js-waku/use-waku-create-app) |
:::tip
Check out the [Waku Idea Board](https://ideas.waku.org/) for creative project ideas and explore the limitless possibilities of the Waku protocol.
:::
Explore some example apps built using Waku at https://examples.waku.org/ and view a list of projects and workshops from previous hackathons at [Awesome Waku](https://github.com/waku-org/awesome-waku/).
:::

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

@ -153,7 +153,12 @@ const callback = (wakuMessage) => {
};
// Create a Filter subscription
const subscription = await node.filter.createSubscription();
const { error, subscription } = await node.filter.createSubscription({ contentTopics: [contentTopic] });
if (error) {
// handle errors if happens
throw Error(error);
}
// Subscribe to content topics and process new messages
await subscription.subscribe([decoder], callback);

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

@ -21,7 +21,12 @@ The `@waku/sdk` package provides a `Filter.ping()` function to ping subscription
```js
// Create a Filter subscription
const subscription = await node.filter.createSubscription();
const { error, subscription } = await node.filter.createSubscription({ contentTopics: [contentTopic] });
if (error) {
// handle errors if happens
throw Error(error);
}
// Subscribe to content topics and process new messages
await subscription.subscribe([decoder], callback);

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

@ -50,22 +50,19 @@ const decoder = createDecoder(contentTopic);
The `store.queryWithOrderedCallback()` function provides a straightforward method for querying `Store` nodes and processing messages in chronological order through a callback function. It accepts these parameters:
- `decoders`: List of `decoders` that specify the `content topic` to query for and their [message decryption](https://rfc.vac.dev/spec/26/) methods.
- `decoders`: List of `decoders` that specify the `content topic` to query for and their [message decryption](https://rfc.vac.dev/waku/standards/application/26/payload) methods.
- `callback`: The callback function for processing the retrieved messages.
- `options` (optional): [Query options](/guides/js-waku/store-retrieve-messages#store-query-options) to filter the retrieved messages.
```js
// Create the callback function
const callback = (wakuMessage) => {
// Render the message/payload in your application
console.log(wakuMessage);
// Render the message/payload in your application
console.log(wakuMessage);
};
// Query the Store peer
await node.store.queryWithOrderedCallback(
[decoder],
callback,
);
await node.store.queryWithOrderedCallback([decoder], callback);
```
:::info
@ -76,7 +73,7 @@ The `queryWithOrderedCallback()` function always returns the most recent message
The `store.queryGenerator()` function provides more control and flexibility over processing messages retrieved from `Store` nodes through [Async Generators](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncGenerator). It accepts these parameters:
- `decoders`: List of `decoders` that specify the `content topic` to query for and their [message decryption](https://rfc.vac.dev/spec/26/) methods.
- `decoders`: List of `decoders` that specify the `content topic` to query for and their [message decryption](https://rfc.vac.dev/waku/standards/application/26/payload) methods.
- `options` (optional): [Query options](/guides/js-waku/store-retrieve-messages#store-query-options) to filter the retrieved messages.
```js
@ -85,14 +82,14 @@ const storeQuery = node.store.queryGenerator([decoder]);
// Process the messages
for await (const messagesPromises of storeQuery) {
// Fulfil the messages promises
const messages = await Promise.all(messagesPromises
.map(async (p) => {
const msg = await p;
// Render the message/payload in your application
console.log(msg);
})
);
// Fulfil the messages promises
const messages = await Promise.all(
messagesPromises.map(async (p) => {
const msg = await p;
// Render the message/payload in your application
console.log(msg);
})
);
}
```
@ -114,12 +111,12 @@ import { PageDirection } from "@waku/sdk";
// Retrieve recent messages first
const queryOptions = {
pageDirection: PageDirection.BACKWARD,
pageDirection: PageDirection.BACKWARD,
};
// Retrieve oldest messages first
const queryOptions = {
pageDirection: PageDirection.FORWARD,
pageDirection: PageDirection.FORWARD,
};
// Query the Store peer with options
@ -137,18 +134,15 @@ import { waku } from "@waku/sdk";
// Create the callback function
const messages = [];
const callback = (wakuMessage) => {
messages.push(wakuMessage);
// Return "true" to stop retrieving pages
// Here, it retrieves only the first page
return true;
messages.push(wakuMessage);
// Return "true" to stop retrieving pages
// Here, it retrieves only the first page
return true;
};
// Retrieve the first page of messages
// This retrieves all the messages if "return true" is not present
await node.store.queryWithOrderedCallback(
[decoder],
callback,
);
await node.store.queryWithOrderedCallback([decoder], callback);
// Create the cursor
const lastMessage = messages[messages.length - 1];
@ -156,13 +150,9 @@ const cursor = await waku.createCursor(lastMessage);
// Retrieve the next page of messages
// The message at the cursor index is excluded from the result
await node.store.queryWithOrderedCallback(
[decoder],
callback,
{
cursor: cursor,
},
);
await node.store.queryWithOrderedCallback([decoder], callback, {
cursor: cursor,
});
console.log(messages);
```
@ -182,10 +172,10 @@ startTime.setDate(endTime.getDate() - 7);
// Retrieve a week of messages
const queryOptions = {
timeFilter: {
startTime,
endTime,
},
timeFilter: {
startTime,
endTime,
},
};
// Query the Store peer with options
@ -199,4 +189,4 @@ The `timeFilter` option significantly reduces message retrieval performance. To
:::tip Congratulations!
You have successfully retrieved and filtered historical messages on a Light Node using the `Store` protocol. Have a look at the [store-js](https://github.com/waku-org/js-waku-examples/tree/master/examples/store-js) and [store-reactjs-chat](https://github.com/waku-org/js-waku-examples/tree/master/examples/store-reactjs-chat) examples for working demos.
:::
:::

60
docs/guides/nwaku/find-node-address.md Normal file
View File

@ -0,0 +1,60 @@
---
title: Find Your Node Address
hide_table_of_contents: true
---
:::info
When starting the node, `nwaku` will display all the public listening and discovery addresses at the `INFO` log level.
:::
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/).
## Listening addresses
Look for the log entry that begins with `Listening on`, for example:
```txt title="Nwaku Log Output"
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]
```
```shell
# Listening TCP transport address
/ip4/0.0.0.0/tcp/60000/p2p/16Uiu2HAmQCsH9V81xoqTwGuT3qwkZWbwY1TtTQwpr3DjHU2TSwMn
# Listening WebSocket address
/ip4/0.0.0.0/tcp/8000/ws/p2p/16Uiu2HAmQCsH9V81xoqTwGuT3qwkZWbwY1TtTQwpr3DjHU2TSwMn
```
## Discoverable ENR addresses
A `nwaku` node can encode its addressing information in an [Ethereum Node Record (ENR)](https://eips.ethereum.org/EIPS/eip-778).
### ENR for DNS discovery
Look for the log entry that begins with `DNS: discoverable ENR`, for example:
```txt title="Nwaku Log Output"
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
```
```shell
# ENR the node addresses are encoded in
enr:-Iu4QBKYj8Ovxwz4fIalxZ_1a8dOCU2WC-1LQrcBCCb4Np93f9-UuSZXn3vagJL1S3k3hwRYfOp3JSbW7_VqwtqMIeMBgmlkgnY0gmlwhAAAAACJc2VjcDI1NmsxoQOrmyV59dAzY4ZKrvrj32VOoZbLby8dCKFnXnqhIdQ0NYN0Y3CC6mCFd2FrdTIB
```
### ENR for Discv5
Look for the log entry that begins with `Discv5: discoverable ENR`, for example:
```txt title="Nwaku Log Output"
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
```
```shell
# ENR the node addresses are encoded in
enr:-IO4QDxToTg86pPCK2KvMeVCXC2ADVZWrxXSvNZeaoa0JhShbM5qed69RQz1s1mWEEqJ3aoklo_7EU9iIBcPMVeKlCQBgmlkgnY0iXNlY3AyNTZrMaEDdBHK1Gx6y_zv5DVw5Qb3DtSOMmVHTZO1WSORrF2loL2DdWRwgiMohXdha3UyAw
```
:::tip Congratulations!
You have successfully found the listening and discoverable addresses for your `nwaku` node. Have a look at the Configure Peer Discovery](/guides/nwaku/configure-discovery) guide to learn how to discover and connect with peers in the network.
:::

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

@ -3,13 +3,21 @@ 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-compose](https://github.com/waku-org/nwaku-compose) is a ready-to-use Docker Compose setup that configures the following automatically:
- `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 the node and Waku network to send and receive messages.
- [Grafana](https://grafana.com/) metrics dashboard for advanced users and node operators to monitor the node.
This guide provides detailed steps to configure, run, monitor, and interact with a `nwaku` node with [nwaku-compose](https://github.com/waku-org/nwaku-compose).
## Video tutorial
<div class="video-container">
<iframe class="yt-video" src="https://www.youtube.com/embed/fs0ynLk4z0I" title="How to run a Waku node using Nwaku Compose" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
</div>
:::tip
Check out the [Waku Node Operator Cheatsheet](/Waku-NodeOperator.pdf) to learn how to easily run, monitor, and interact with a node.
:::
## Prerequisites
@ -19,6 +27,10 @@ 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.01 Sepolia ETH)
- A password to protect your RLN membership
:::info
We recommend running a `nwaku` node with at least 2GB of RAM, especially if `WSS` is enabled. If running just a `Relay` node, 0.5GB of RAM is sufficient.
:::
## Clone the repository
```shell
@ -41,7 +53,7 @@ Ensure that you do **NOT** include any secrets in the `.env.example` file, as it
## Register for RLN membership
The RLN membership is your access key to The Waku Network. Its registration is done on-chain, allowing your `nwaku` node to send messages decentralised and privately, respecting some [rate limits](https://rfc.vac.dev/spec/64/#rate-limit-exceeded). Other peers won't relay messages that exceed the rate limit.
The RLN membership is your access key to The Waku Network. Its registration is done on-chain, allowing your `nwaku` node to send messages decentralised and privately, respecting some rate limits. Other peers won't relay messages that exceed the rate limit.
This command registers your membership and saves it in the `keystore/keystore.json` file:
@ -55,7 +67,7 @@ If you only want to relay traffic without sending messages to the network, you d
## Run the node
Start all processes: `nwaku` node, database for storing messages, and Grafana for metrics. Your RLN membership is loaded into nwaku under the hood:
Launch all the processes: `nwaku` node, database for storing messages, and Grafana for metrics with the following command. Your RLN membership is loaded into `nwaku` under the hood:
```shell
docker-compose up -d
@ -67,7 +79,7 @@ View the logs of the node to confirm that it is running correctly:
docker-compose logs -f nwaku
```
## Interact with the node
## Monitor the node
Visit <http://localhost:3000/d/yns_4vFVk/nwaku-monitoring> to view your node metrics in real time.
@ -77,7 +89,7 @@ Visit <http://localhost:3000/d/yns_4vFVk/nwaku-monitoring> to view your node met
To access Grafana from outside your machine, remove `127.0.0.1` and open the port. Consider setting up a password for Grafana to ensure security.
:::
## Use the REST API
## Interact with the node
Your `nwaku` node provides a [REST API](https://waku-org.github.io/waku-rest-api/) on port `8645` for interacting with it:
@ -107,6 +119,10 @@ curl --location 'http://127.0.0.1:8645/store/v1/messages?contentTopics=%2Fmy-app
--header 'Accept: application/json'
```
:::tip
If you encounter issues running your node or require assistance with anything, please visit the [#node-help channel](https://discord.com/channels/1110799176264056863/1216748184592711691) on our Discord.
:::
:::tip Congratulations!
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.
:::

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

@ -9,6 +9,10 @@ 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/).
:::info
We recommend running a `nwaku` node with at least 2GB of RAM, especially if `WSS` is enabled. If running just a `Relay` node, 0.5GB of RAM is sufficient.
:::
## 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.
@ -52,10 +56,14 @@ To find your public IP, use:
dig TXT +short o-o.myaddr.l.google.com @ns1.google.com | awk -F'"' '{ print $2}'
```
:::tip
:::info
We recommend using explicit port mappings (`-p`) when exposing ports accessible from outside the host (listening and discovery ports, API servers).
:::
:::tip
If you encounter issues running your node or require assistance with anything, please visit the [#node-help channel](https://discord.com/channels/1110799176264056863/1216748184592711691) on our Discord.
:::
:::tip Congratulations!
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.
:::

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

@ -5,6 +5,8 @@ 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](/learn/concepts/protocols) they want to support based on their needs, motivations, and available resources.
![waku architecture](/img/architecture.png)
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.
:::info
@ -17,26 +19,24 @@ To run a node, you must have the `nwaku` binary. Nwaku provides multiple options
#### Run nwaku in Docker (recommended)
| | Description | Documentation |
| - | - | - |
| Docker Compose | Run a `nwaku` node with Docker Compose | [Run Nwaku with Docker Compose](/guides/nwaku/run-docker-compose) |
| Docker Container | Run a `nwaku` node in a Docker Container | [Run Nwaku in a Docker Container](/guides/nwaku/run-docker) |
We recommend [using Docker Compose](/guides/nwaku/run-docker-compose) to run a node because it's the simplest and fastest way to configure and run one:
:::tip
We recommend [using Docker Compose](/guides/nwaku/run-docker-compose) to run a node because it's the simplest and fastest way to configure and run one.
:::
| | Description | Documentation |
| ---------------- | ---------------------------------------- | ----------------------------------------------------------------- |
| Docker Compose | Run a `nwaku` node with Docker Compose | [Run Nwaku with Docker Compose](/guides/nwaku/run-docker-compose) |
| Docker Container | Run a `nwaku` node in a Docker Container | [Run Nwaku in a Docker Container](/guides/nwaku/run-docker) |
#### 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) |
| | 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
| | Description | Documentation |
| - | - | - |
| | Description | Documentation |
| ----------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------- |
| Build from Source | Build the node from the [nwaku source code](https://github.com/waku-org/nwaku) | [Build Nwaku from Source](/guides/nwaku/build-source) |
:::tip
@ -48,11 +48,11 @@ You can run the `nwaku` binaries and Docker images on cloud service providers li
Once you have gotten the `nwaku` binary, run it using the [default configuration](/guides/nwaku/config-methods#default-configuration-values):
```shell
# Run with default configuration
./build/wakunode2
# Run the Docker Compose
docker-compose up -d
# See available command line options
./build/wakunode2 --help
# Run the standalone binary
./build/wakunode2
```
:::tip
@ -63,20 +63,20 @@ To learn how to customise the configuration of a `nwaku` node, have a look at th
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](/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) |
| | 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](/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.
:::tip
We suggest [configuring WebSocket transport](/guides/nwaku/configure-nwaku#configure-websocket-transport) for your node to enable support and serving of browser peers using [@waku/sdk](/guides/js-waku/).
:::
## 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:
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:
```mdx-code-block
import Tabs from '@theme/Tabs';
@ -96,10 +96,10 @@ curl --location 'http://127.0.0.1:8645/debug/v1/info' \
```json
{
"listenAddresses": [
"/ip4/0.0.0.0/tcp/60000/p2p/16Uiu2HAmUbPquFQqje3jiqoB5YoiUbBya59NB4qqEzeiTNGHeA6w"
],
"enrUri": "enr:-Iu4QCQZXZDb_JsYmLoYor0F5E_95HbIywgO_wgx2rIdDbmCJZkTzmlCr0wmMzV47lgik_tVwww5mIng90Ris83TisMBgmlkgnY0gmlwhAAAAACJc2VjcDI1NmsxoQPszztG-Ev52ZB7tk0jF8s6Md4KvyY_rhzNZokaaB_ABIN0Y3CC6mCFd2FrdTIB"
"listenAddresses": [
"/ip4/0.0.0.0/tcp/60000/p2p/16Uiu2HAmUbPquFQqje3jiqoB5YoiUbBya59NB4qqEzeiTNGHeA6w"
],
"enrUri": "enr:-Iu4QCQZXZDb_JsYmLoYor0F5E_95HbIywgO_wgx2rIdDbmCJZkTzmlCr0wmMzV47lgik_tVwww5mIng90Ris83TisMBgmlkgnY0gmlwhAAAAACJc2VjcDI1NmsxoQPszztG-Ev52ZB7tk0jF8s6Md4KvyY_rhzNZokaaB_ABIN0Y3CC6mCFd2FrdTIB"
}
```
@ -110,64 +110,32 @@ 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.
:::
## Check the node health status
You can check the health status of the node by calling the [Get node health status](https://waku-org.github.io/waku-rest-api/#get-/health) endpoint of the [REST API](https://waku-org.github.io/waku-rest-api/):
<Tabs>
<TabItem value="request" label="Request">
```shell
curl --location 'http://127.0.0.1:8645/health' \
--header 'Accept: text/plain'
```
</TabItem>
<TabItem value="response" label="Response">
```txt
Node is healthy
```
</TabItem>
</Tabs>
:::tip
We suggest [configuring WebSocket transport](/guides/nwaku/configure-nwaku#configure-websocket-transport) for your node to enable support and serving of browser peers using [@waku/sdk](/guides/js-waku/).
If you encounter issues running your node or require assistance with anything, please visit the [#node-help channel](https://discord.com/channels/1110799176264056863/1216748184592711691) on our Discord.
:::
## 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/).
:::info
When starting the node, `nwaku` will display all the public listening and discovery addresses at the `INFO` log level.
:::
### Listening addresses
Look for the log entry that begins with `Listening on`, for example:
```txt title="Nwaku Log Output"
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]
```
```shell
# Listening TCP transport address
/ip4/0.0.0.0/tcp/60000/p2p/16Uiu2HAmQCsH9V81xoqTwGuT3qwkZWbwY1TtTQwpr3DjHU2TSwMn
# Listening WebSocket address
/ip4/0.0.0.0/tcp/8000/ws/p2p/16Uiu2HAmQCsH9V81xoqTwGuT3qwkZWbwY1TtTQwpr3DjHU2TSwMn
```
### 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.
#### ENR for DNS discovery
Look for the log entry that begins with `DNS: discoverable ENR`, for example:
```txt title="Nwaku Log Output"
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
```
```shell
# ENR the node addresses are encoded in
enr:-Iu4QBKYj8Ovxwz4fIalxZ_1a8dOCU2WC-1LQrcBCCb4Np93f9-UuSZXn3vagJL1S3k3hwRYfOp3JSbW7_VqwtqMIeMBgmlkgnY0gmlwhAAAAACJc2VjcDI1NmsxoQOrmyV59dAzY4ZKrvrj32VOoZbLby8dCKFnXnqhIdQ0NYN0Y3CC6mCFd2FrdTIB
```
#### ENR for Discv5
Look for the log entry that begins with `Discv5: discoverable ENR`, for example:
```txt title="Nwaku Log Output"
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
```
```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 [Node Configuration Examples](/guides/nwaku/configure-nwaku) guide to learn how to configure `nwaku` for different use cases.
:::
:::

6
docs/learn/concepts/content-topics.md
View File

@ -3,7 +3,7 @@ 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](/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.
`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/waku/informational/23/topics#content-topics) specification to learn more.
## Naming format
@ -36,7 +36,7 @@ The `Filter`, `Store`, and `Light Push` protocols share content topics with peer
For example, instead of using Personally Identifiable Information (PII) in the content topic (e.g., a public key), you can create buckets (e.g., based on the first 4 bytes of the public key hash).
:::info
Waku is developing privacy-preserving features like [Anonymous Filter Subscription](https://rfc.vac.dev/spec/12/#future-work) for the `Filter` protocol and [Anonymous Query](https://rfc.vac.dev/spec/13/#future-work) for the `Store` protocol to hide content topics from potential adversaries.
Waku is developing privacy-preserving features like [Anonymous Filter Subscription](https://rfc.vac.dev/waku/standards/core/12/filter/#future-work) for the `Filter` protocol and [Anonymous Query](https://rfc.vac.dev/waku/standards/core/13/store#future-work) for the `Store` protocol to hide content topics from potential adversaries.
:::
### Increasing k-anonymity preserves user anonymity
@ -69,4 +69,4 @@ This approach divides traffic into multiple topics, reducing the messages users
:::info
The **k** value of **k-anonymity** equals the number of IDs for which the first character of the hash is `"a"`. For example, using a single content topic in an application with 10,000 users results in **k = 10,000**. However, using the hash ID's first character, **k** reduces to **10,000 / 16 = 625**.
:::
:::

4
docs/learn/concepts/discv5.md
View File

@ -3,7 +3,7 @@ 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.
`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/waku/standards/core/33/discv5) specification to learn more.
#### Pros
@ -21,4 +21,4 @@ hide_table_of_contents: true
import Discv5 from "@site/diagrams/_discv5.md";
<Discv5 />
```
```

4
docs/learn/concepts/dns-discovery.md
View File

@ -3,7 +3,7 @@ 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/).
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.
This bootstrapping method allows anyone to register and publish a domain name for the network, promoting increased decentralisation.
@ -24,4 +24,4 @@ This bootstrapping method allows anyone to register and publish a domain name fo
import DNSDiscovery from "@site/diagrams/_dns-discovery.md";
<DNSDiscovery />
```
```

4
docs/learn/concepts/peer-exchange.md
View File

@ -3,7 +3,7 @@ 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.
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.
:::info
`Peer Exchange` enables requesting random peers from other network nodes without revealing information about their connectivity or neighbourhood.
@ -25,4 +25,4 @@ The primary objective of this protocol is to facilitate peer connectivity for re
import PeerExchange from "@site/diagrams/_peer-exchange.md";
<PeerExchange />
```
```

14
docs/learn/concepts/protocols.md
View File

@ -5,15 +5,15 @@ 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:
## [Relay](https://rfc.vac.dev/spec/11/)
## [Relay](https://rfc.vac.dev/waku/standards/core/11/relay/)
`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/waku/standards/core/17/rln-relay/)
`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).
`RLN Relay` protocol extends the `Relay` protocol by using [Rate Limit Nullifiers (RLN)](https://rfc.vac.dev/vac/32/rln-v1/) 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](https://rfc.vac.dev/waku/standards/core/12/filter/)
`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.
@ -21,7 +21,7 @@ Waku takes a modular approach, providing a range of protocols that enable applic
`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.
:::
## [Store](https://rfc.vac.dev/spec/13/)
## [Store](https://rfc.vac.dev/waku/standards/core/13/store)
`Store` protocol is responsible for storing messages relayed in the network, making it possible to query and retrieve them later. This functionality benefits offline peers by enabling them to retrieve missed messages upon reconnection.
@ -29,7 +29,7 @@ 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/waku/standards/core/19/lightpush)
`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.
@ -37,7 +37,7 @@ Using `Relay` and `Filter` protocols is recommended when a node is online, as `S
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/waku/standards/core/14/message)
`Waku Message` specifies the structure and format of messages in the Waku Network. It includes the following attributes:

10
docs/learn/glossary.md
View File

@ -27,7 +27,7 @@ Discv5 is a [peer discovery](#peer-discovery) mechanism using a Distributed Hash
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.
### [ENR](https://rfc.vac.dev/spec/31/)
### [ENR](https://eips.ethereum.org/EIPS/eip-778)
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.
@ -99,7 +99,7 @@ Publish/Subscribe (Pub/Sub) is an asynchronous messaging pattern where publisher
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://rate-limiting-nullifier.github.io/rln-docs/)
Rate Limit Nullifiers (RLN) are a construct based on zero-knowledge proofs that enables rate limiting functionality while preserving the users's anonymity.
@ -135,7 +135,7 @@ Waku is a family of private, secure, decentralised, and peer-to-peer web3 commun
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/waku/standards/application/26/payload)
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.
@ -143,6 +143,6 @@ Waku Message Payload Encryption provides guidelines for implementing secure and
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
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.
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.

2
docs/learn/research.md
View File

@ -7,7 +7,7 @@ The following features are currently experimental and under research and initial
## 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 aim to enable an incentivised spam protection technique to enhance `Relay` by using [Rate Limit Nullifiers (RLN)](https://rfc.vac.dev/vac/32/rln-v1/). 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/>

18
docs/learn/security-features.md
View File

@ -7,27 +7,27 @@ Waku's protocol layers offer different services and security considerations, sha
Some of the Waku's security features include the following:
## [Pseudonymity](https://rfc.vac.dev/spec/10/#pseudonymity)
## [Pseudonymity](https://rfc.vac.dev/waku/standards/core/10/waku2/#pseudonymity)
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/waku/standards/core/10/waku2/#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/waku/standards/core/11/relay/#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/waku/standards/core/11/relay/#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/waku/standards/core/10/waku2/#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)](/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/waku/standards/core/10/waku2/#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.
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/waku/standards/core/14/message/#version-1) and Noise protocols, which offer payload encryption and encrypted signatures. Noise 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/waku/standards/core/10/waku2/#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.
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.

24
docs/learn/waku-network.md
View File

@ -5,15 +5,13 @@ hide_table_of_contents: true
The Waku Network is a shared p2p messaging network that is open-access, useful for generalized messaging, privacy-preserving, scalable and accessible even to resource-restricted devices. Some of the most prominent features include:
1. DoS/spam protection with privacy-preserving [Rate-Limiting Nullifiers](https://rfc.vac.dev/spec/64/#rln-rate-limiting).
2. Scalability by [sharding traffic](https://rfc.vac.dev/spec/64/#network-shards) into 8 pubsub topics.
3. [Automatic shard selection](https://rfc.vac.dev/spec/64/#autosharding) based on content topic.
4. [Services](https://rfc.vac.dev/spec/64/#default-services) for resource-restricted nodes, including historical message storage and retrieval, filtering, etc.
1. DoS/spam protection with privacy-preserving Rate-Limiting Nullifiers.
2. Scalability by sharding traffic into 8 pubsub topics.
3. Automatic shard selection based on content topic.
4. Services for resource-restricted nodes, including historical message storage and retrieval, filtering, etc.
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.
:::info
The public Waku Network replaces the previous experimental shared routing layer based on a default pubsub topic (`/waku/2/default-waku/proto`). If your project currently uses this or any other shared pubsub topics, we encourage you to migrate to the public Waku Network with built-in DoS protection, scalability, and reasonable bandwidth usage.
:::tip
If you want to learn more about the Waku Network, the [The Waku Network: Technical Overview](https://blog.waku.org/2024-waku-network-tech-overview) article provides an in-depth look under the hood.
:::
## Why join the Waku network?
@ -24,9 +22,13 @@ The public Waku Network replaces the previous experimental shared routing layer
## 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/).
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.
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/waku/standards/core/17/rln-relay/).
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/waku/standards/core/17/rln-relay/#setup-and-registration), which is essential for publishing on the network.
## 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.
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.
:::info
The public Waku Network replaces the previous experimental shared routing layer based on a default pubsub topic (`/waku/2/default-waku/proto`). If your project currently uses this or any other shared pubsub topics, we encourage you to migrate to the public Waku Network with built-in DoS protection, scalability, and reasonable bandwidth usage.
:::

2
docs/research/index.md
View File

@ -4,6 +4,6 @@ hide_table_of_contents: true
sidebar_position: 1
---
**Research and Studies**: Protocol simulations and theoretical analysis to support the design of Waku protocols. The protocol definitions are on the [Vac RFC](https://rfc.vac.dev/) website.
**Research and Studies**: Protocol simulations and theoretical analysis to support the design of Waku protocols. The protocol definitions are on the [Waku RFCs](https://rfc.vac.dev/waku) website.
**Benchmarks**: Results of implementations and engineering-related benchmarks for Waku clients.

14
docs/security.md Normal file
View File

@ -0,0 +1,14 @@
---
displayed_sidebar: null
sidebar_class_name: hidden
pagination_prev: null
pagination_next: null
---
# Security
We take security seriously at Waku and across the <a href="https://free.technology/" target="_blank">Institute of Free Technology</a> and its affiliates.
Please report any security incidents via <a href="mailto:security@free.technology">security@free.technology</a>.
Please report any discovered vulnerabilities in our bounty programme at <a href="https://hackenproof.com/ift" target="_blank">HackenProof</a> to help ensure our protocols and software remain secure.

19
docusaurus.config.js
View File

@ -98,6 +98,7 @@ const config = {
],
},
footer: {
copyright: "Waku",
links: [
{
title: "Guides",
@ -107,7 +108,7 @@ const config = {
label: "Getting Started",
},
{
to: "/guides/nwaku/run-node",
to: "/guides/nwaku/run-docker-compose",
label: "Run a Nwaku Node",
},
{
@ -153,8 +154,8 @@ const config = {
label: "Blog",
},
{
href: "https://rfc.vac.dev/",
label: "Vac RFCs",
href: "https://rfc.vac.dev/waku",
label: "Waku RFCs",
},
{
href: "https://github.com/waku-org/awesome-waku/",
@ -170,12 +171,16 @@ const config = {
label: "Terms of Use",
},
{
href: '/privacy-policy',
label: 'Privacy Policy',
href: "/privacy-policy",
label: "Privacy Policy",
},
{
href: '/rules-of-engagement',
label: 'Rules of Engagement',
href: "/rules-of-engagement",
label: "Rules of Engagement",
},
{
href: "/security",
label: "Security",
},
],
},

40
sidebars.js
View File

@ -7,7 +7,7 @@ const sidebars = {
{
type: "category",
label: "Run a Nwaku Node",
collapsed: false,
collapsed: true,
link: {
type: "doc",
id: "guides/nwaku/run-node",
@ -17,6 +17,7 @@ const sidebars = {
"guides/nwaku/run-docker",
"guides/nwaku/build-source",
"guides/nwaku/configure-discovery",
"guides/nwaku/find-node-address",
"guides/nwaku/config-methods",
"guides/nwaku/config-options",
"guides/nwaku/configure-nwaku",
@ -31,7 +32,7 @@ const sidebars = {
{
type: "category",
label: "JavaScript Waku SDK",
collapsed: false,
collapsed: true,
link: {
type: "doc",
id: "guides/js-waku/index",
@ -59,6 +60,36 @@ const sidebars = {
},
],
},
{
type: "link",
label: "Learn About Waku",
href: "/learn/waku-network",
},
{
type: "link",
label: "Waku Research",
href: "/research",
},
{
type: "html",
value:
'<a href="https://discord.waku.org" target="_blank" rel="noopener noreferrer" class="menu__link external-link">Discord<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://github.com/waku-org/awesome-waku/" target="_blank" rel="noopener noreferrer" class="menu__link external-link">Awesome Waku<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://ideas.waku.org" target="_blank" rel="noopener noreferrer" class="menu__link external-link">Waku Idea Board<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://github.com/waku-org/bounties/" target="_blank" rel="noopener noreferrer" class="menu__link external-link">Post-Hackathon 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>',
},
],
learn: [
"learn/waku-network",
@ -92,11 +123,6 @@ const sidebars = {
"learn/waku-vs-libp2p",
"learn/glossary",
"learn/faq",
{
type: "html",
value:
'<a href="https://ideas.waku.org" target="_blank" rel="noopener noreferrer" class="menu__link external-link">Waku Idea Board<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>',
},
],
research: [
{

48
src/css/custom.scss
View File

@ -19,10 +19,52 @@ html[data-theme="dark"] .header-github-link:before {
no-repeat;
}
.video-container {
display: flex;
flex-wrap: wrap;
justify-content: space-around;
align-items: flex-start;
}
.yt-video {
flex: 1 1 auto;
max-width: 100%;
width: 640px;
height: 360px;
height: 432px;
}
.two-items {
width: 100%;
}
/* Media query for tablets and desktops */
@media (min-width: 768px) {
.two-items {
width: 48%;
}
}
.case-study-container a {
display: block;
width: 100%;
margin-bottom: 20px;
}
.case-study-container a img {
width: 100%;
height: auto;
}
@media (min-width: 768px) {
.case-study-container a {
display: inline-block;
width: 48%;
margin-bottom: 20px;
margin-right: 2%;
}
.case-study-container a:nth-child(2n) {
margin-right: 0;
}
}
.external-link {
@ -35,4 +77,4 @@ html[data-theme="dark"] .header-github-link:before {
.theme-doc-toc-desktop {
display: none;
}
}

BIN
static/Waku-NodeOperator.pdf Normal file
View File

Binary file not shown.

BIN
static/img/architecture.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 87 KiB

BIN
static/img/graph-use-case.jpeg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 279 KiB

BIN
static/img/railgun-use-case.jpeg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 994 KiB