add waku network guide (#139)

This commit is contained in:
LordGhostX 2023-11-22 12:54:04 +01:00 committed by GitHub
parent be3086de62
commit 8f8b31be32
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
10 changed files with 127 additions and 43 deletions

View File

@ -72,6 +72,8 @@
"lightpushnode",
"filternode",
"instanceof",
"sepolia",
"faucet",
],
"flagWords": [],
"ignorePaths": [

View File

@ -2,7 +2,7 @@
title: Manage Your Filter Subscriptions
---
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](/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.
## Overview

View File

@ -26,7 +26,7 @@ Certain features in `@waku/sdk` are tailored for browsers and might not translat
## 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 [JSON RPC API](https://rfc.vac.dev/spec/16/).
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

View File

@ -42,7 +42,7 @@ Waku provides integrations tailored for mobile applications, enabling Waku to ru
| | Description | Documentation |
| - | - | - |
| JSON-RPC API | `JSON-RPC` API interface provided by `nwaku` and `go-waku` to interact with the Waku Network | COMING SOON |
| [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 Spec](https://waku-org.github.io/waku-rest-api/) |
| [@waku/react](https://www.npmjs.com/package/@waku/react) | React components and UI adapters designed for seamless integration with `@waku/sdk` | COMING SOON |
| [@waku/create-app](https://www.npmjs.com/package/@waku/create-app) | Starter kit to bootstrap your next `@waku/sdk` project from various example templates | [Bootstrap DApps Using @waku/create-app](/guides/js-waku/use-waku-create-app) |
| [nwaku-compose](https://github.com/waku-org/nwaku-compose) | Pre-configured Docker Compose setup for running and monitoring a `nwaku` node using Prometheus and Grafana | [Run Nwaku with Docker Compose](/guides/nwaku/run-docker-compose) |

View File

@ -2,15 +2,21 @@
title: Run Nwaku with Docker Compose
---
`nwaku-compose` is a ready-to-use Docker Compose setup that runs a nwaku node and monitors it with already configured [Prometheus](https://prometheus.io/) and [Grafana](https://grafana.com/) instances.
`nwaku-compose` is a ready-to-use Docker Compose setup that runs the following:
This guide provides detailed steps to build, configure, run, and monitor a `nwaku` node with [nwaku-compose](https://github.com/waku-org/nwaku-compose).
- `nwaku` node running [Relay](/overview/concepts/protocols#relay) and [Store](/overview/concepts/protocols#store) protocols with [RLN](/overview/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.
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).
## Prerequisites
- [Git](https://git-scm.com/) or [GitHub Desktop](https://desktop.github.com/)
- [Docker](https://docs.docker.com/engine/install/)
- [Docker Compose](https://docs.docker.com/compose/install/)
- [Docker](https://docs.docker.com/engine/install/) and [Docker Compose](https://docs.docker.com/compose/install/)
- [Ethereum Sepolia WebSocket Endpoint](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)
- [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
@ -21,19 +27,37 @@ cd nwaku-compose
## 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.
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:
```shell
export ETH_CLIENT_ADDRESS=wss://sepolia.infura.io/ws/v3/[INFURA API KEY]
export ETH_TESTNET_KEY=[INFURA API KEY]
export KEYSTORE_PASSWORD=[RLN MEMBERSHIP PASSWORD]
```
## 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:
```shell
./register_rln.sh
```
:::info
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
Spin up the containers using `docker-compose`:
Start all processes: `nwaku` node, database and Grafana for metrics. Your RLN membership is loaded into nwaku under the hood:
```bash
docker-compose up -d
```
## Monitor the Node
## Interact with the Node
Visit <http://localhost:3000/d/yns_4vFVk/nwaku-monitoring?orgId=1> to view your node metrics in real-time.
Visit <http://localhost:3000/d/yns_4vFVk/nwaku-monitoring> to view your node metrics in real-time.
![nwaku compose dashboard](/img/nwaku-compose-dashboard.png)
@ -41,6 +65,36 @@ Visit <http://localhost:3000/d/yns_4vFVk/nwaku-monitoring?orgId=1> to view your
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
Your `nwaku` node provides a [REST API](https://waku-org.github.io/waku-rest-api/) on port `8645` for interacting with it:
```shell
# Get nwaku version
curl --location 'http://127.0.0.1:8645/debug/v1/version'
# Get nwaku info
curl --location 'http://127.0.0.1:8645/debug/v1/info'
```
Send a message to a `contentTopic`, which all subscribers will receive. Please note that the payload is encoded in `base64`.
```shell
curl --location 'http://127.0.0.1:8645/relay/v1/auto/messages' \
--header 'Content-Type: application/json' \
--data '{
"payload": "'$(echo -n "Hello Waku Network - from Anonymous User" | base64)'",
"contentTopic": "/my-app/2/chatroom-1/proto"
}'
```
Retrieve messages sent to a `contentTopic`. Please note that this query can be made to any `Store` node within the network:
```shell
curl --location 'http://127.0.0.1:8645/store/v1/messages?contentTopics=%2Fmy-app%2F2%2Fchatroom-1%2Fproto&pageSize=50&ascending=true' \
--header 'Accept: application/json'
```
:::tip Congratulations!
You have successfully started a `nwaku` node using Docker Compose. 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 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.
:::

View File

@ -56,8 +56,10 @@ Here are the available node configuration options, along with their default valu
| `rln-relay-dynamic` | `false` | Enable waku-rln-relay with on-chain dynamic group management: true\|false |
| `rln-relay-id-key` | | Rln relay identity secret key as a Hex string |
| `rln-relay-id-commitment-key` | | Rln relay identity commitment key as a Hex string |
| `rln-relay-eth-client-address` | `ws://localhost:8540/` | WebSocket address of an Ethereum testnet client e.g., ws://localhost:8540/ |
| `rln-relay-eth-client-address` | `ws://localhost:8540/` | WebSocket address of an Ethereum testnet client e.g., `ws://localhost:8540/` |
| `rln-relay-eth-contract-address` | | Address of membership contract on an Ethereum testnet |
| `rln-relay-eth-private-key` | | Private key for broadcasting transactions |
| `execute` | `false` | Runs the registration function on-chain. By default, a dry-run will occur |
| `rln-relay-cred-password` | | Password for encrypting RLN credentials |
| `rln-relay-tree-path` | | Path to the RLN merkle tree sled db (https://github.com/spacejam/sled) |
| `rln-relay-bandwidth-threshold` | `0 # to maintain backwards compatibility` | Message rate in bytes/sec after which verification of proofs should happen |

View File

@ -69,7 +69,7 @@ You can configure a `nwaku` node to use multiple peer discovery mechanisms simul
## Interact with the Node
You can interact with a running `nwaku` node through the [JSON RPC API](https://rfc.vac.dev/spec/16/), such as querying the node information using the `get_waku_v2_debug_v1_info` method:
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';
@ -80,14 +80,8 @@ import TabItem from '@theme/TabItem';
<TabItem value="request" label="Request">
```bash
curl --location --request GET 'http://localhost:8545' \
--header 'Content-Type: application/json' \
--data '{
"jsonrpc": "2.0",
"id": "id",
"method": "get_waku_v2_debug_v1_info",
"params": []
}'
curl --location 'http://127.0.0.1:8645/debug/v1/info' \
--header 'Accept: application/json'
```
</TabItem>
@ -95,14 +89,10 @@ curl --location --request GET 'http://localhost:8545' \
```json
{
"jsonrpc": "2.0",
"id": "id",
"result": {
"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"
}
```
@ -115,7 +105,7 @@ The `listenAddresses` field stores the node's listening addresses, while the `en
## Find the Node Addresses
You can find the addresses of a running node through its logs or by calling the `get_waku_v2_debug_v1_info` method of the [JSON RPC API](https://rfc.vac.dev/spec/16/).
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.

View File

@ -8,7 +8,7 @@ Definitions and usage of the terminology used in the Waku ecosystem.
### Bootstrapping
Bootstrapping is the initial entry point of a [node](#node) to the [Waku Network](#waku). Once connected, other [peer discovery](#peer-discovery) methods can be employed to locate other [peers](#peer) in the network.
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)
@ -52,11 +52,11 @@ Light push is a protocol enabling [light nodes](#light-node) to send [messages](
### 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). Examples include browsers and mobile phones.
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.
### Node
A node is a device or client that implements Waku [protocols](#protocol) and leverages the [Waku Network](#waku) to enable secure and private peer-to-peer web3 communication.
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
@ -68,11 +68,11 @@ The payload field in a [Waku Message](#waku-message) contains the application da
### Peer
A peer refers to other [nodes](#node) and participants of the [Waku Network](#waku) with whom communication and interaction are possible.
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 is when a [node](#node) locates and gets information about other [peers](#peer) in the [Waku Network](#waku).
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)
@ -80,11 +80,11 @@ Peer exchange is a [peer discovery](#peer-discovery) mechanism that enables [lig
### Peer ID
`PeerID` is the unique identifier of a [node](#node) in the [Waku Network](#waku) generated from the cryptographic hash of the node's public key.
`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)
A protocol is a set of rules that enables [nodes](#node) within the [Waku Network](#waku) to perform various functionalities such as message sending, relaying, filtering, storing, retrieving, and more.
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.
### Pub/Sub
@ -94,13 +94,13 @@ 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/32/)
### [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 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) to accommodate many nodes efficiently.
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
@ -124,15 +124,19 @@ A transport is a network mechanism that establishes connections between [peers](
### Waku
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 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 defines the structure of messages in the [Waku Network](#waku), including the [content topic](#content-topic), [payload](#payload), and metadata for application-specific processing.
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 provides guidelines for implementing secure and private communication in the [Waku Network](#waku). It covers encryption, decryption, and signing methods for message [payloads](#payload), focusing on confidentiality, authenticity, integrity, and unlinkability.
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)
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/)

View File

@ -0,0 +1,31 @@
---
title: The Waku Network
---
:::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, better scalability, etc.
:::
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.
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?
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.
3. We are also working on incentivisation vectors to encourage more node operators to provide services to the network.
## 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.
## 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.

View File

@ -4,6 +4,7 @@
const sidebars = {
main: [
"overview/index",
"overview/waku-network",
"overview/history",
"overview/why-waku",
"overview/use-cases",