diff --git a/.cspell.json b/.cspell.json index 1d07c8c..6fc3342 100644 --- a/.cspell.json +++ b/.cspell.json @@ -72,6 +72,8 @@ "lightpushnode", "filternode", "instanceof", + "sepolia", + "faucet", ], "flagWords": [], "ignorePaths": [ diff --git a/docs/guides/js-waku/manage-filter.md b/docs/guides/js-waku/manage-filter.md index 7beb119..b5acc5a 100644 --- a/docs/guides/js-waku/manage-filter.md +++ b/docs/guides/js-waku/manage-filter.md @@ -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 diff --git a/docs/guides/js-waku/run-waku-nodejs.md b/docs/guides/js-waku/run-waku-nodejs.md index 9336309..95f8993 100644 --- a/docs/guides/js-waku/run-waku-nodejs.md +++ b/docs/guides/js-waku/run-waku-nodejs.md @@ -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 diff --git a/docs/guides/nodes-and-sdks.md b/docs/guides/nodes-and-sdks.md index a99a762..a04e522 100644 --- a/docs/guides/nodes-and-sdks.md +++ b/docs/guides/nodes-and-sdks.md @@ -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) | \ No newline at end of file diff --git a/docs/guides/nwaku/run-docker-compose.md b/docs/guides/nwaku/run-docker-compose.md index 01975c7..e9afc92 100644 --- a/docs/guides/nwaku/run-docker-compose.md +++ b/docs/guides/nwaku/run-docker-compose.md @@ -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 to view your node metrics in real-time. +Visit to view your node metrics in real-time. ![nwaku compose dashboard](/img/nwaku-compose-dashboard.png) @@ -41,6 +65,36 @@ Visit 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. ::: \ No newline at end of file diff --git a/docs/guides/reference/node-config-options.md b/docs/guides/reference/node-config-options.md index c556785..5e9c16b 100644 --- a/docs/guides/reference/node-config-options.md +++ b/docs/guides/reference/node-config-options.md @@ -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 | diff --git a/docs/guides/run-nwaku-node.md b/docs/guides/run-nwaku-node.md index f601dcf..8edee17 100644 --- a/docs/guides/run-nwaku-node.md +++ b/docs/guides/run-nwaku-node.md @@ -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'; ```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' ``` @@ -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. diff --git a/docs/overview/reference/glossary.md b/docs/overview/reference/glossary.md index 4c2595f..50abec4 100644 --- a/docs/overview/reference/glossary.md +++ b/docs/overview/reference/glossary.md @@ -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/) diff --git a/docs/overview/waku-network.md b/docs/overview/waku-network.md new file mode 100644 index 0000000..a08e596 --- /dev/null +++ b/docs/overview/waku-network.md @@ -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. \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index 118fea1..1f390ed 100644 --- a/sidebars.js +++ b/sidebars.js @@ -4,6 +4,7 @@ const sidebars = { main: [ "overview/index", + "overview/waku-network", "overview/history", "overview/why-waku", "overview/use-cases",