diff --git a/.cspell.json b/.cspell.json index 3fdfffc..71729c1 100644 --- a/.cspell.json +++ b/.cspell.json @@ -60,6 +60,17 @@ "nwakunode", "tlsv", "rustup", + "storenode", + "nodekey", + "ecparam", + "genkey", + "outform", + "privkey", + "fullchain", + "certbot", + "letsencrypt", + "lightpushnode", + "filternode", ], "flagWords": [], "ignorePaths": [ diff --git a/docs/guides/js-waku/light-send-receive.md b/docs/guides/js-waku/light-send-receive.md index bceef66..2831ada 100644 --- a/docs/guides/js-waku/light-send-receive.md +++ b/docs/guides/js-waku/light-send-receive.md @@ -66,7 +66,7 @@ The `ephemeral` option allows you to specify whether your messages should be per ```js const encoder = createEncoder({ contentTopic: contentTopic, // message content topic - ephemeral: true, // allows messages to be stored or not + ephemeral: true, // allows messages to be persisted or not }); ``` diff --git a/docs/guides/nwaku/build-source.md b/docs/guides/nwaku/build-source.md index ef5a81f..773814b 100644 --- a/docs/guides/nwaku/build-source.md +++ b/docs/guides/nwaku/build-source.md @@ -11,7 +11,7 @@ This guide provides detailed steps to build a `nwaku` node from the source code ## Prerequisites -To build `nwaku`, you need the standard developer tools, including a C compiler, GNU Make, Bash, Git, Rustup and PostgreSQL client library. +To build `nwaku`, you need the standard developer tools, including a C compiler, GNU Make, Bash, Git, Rustup, and PostgreSQL client library. ```mdx-code-block import Tabs from '@theme/Tabs'; @@ -109,3 +109,7 @@ Run the tests for Waku: ```bash make test ``` + +:::tip Congratulations! +You have successfully built the `nwaku` binary from the source code. Have a look at the [Nwaku Configuration Examples](/guides/nwaku/configure-nwaku) guide to learn how to configure `nwaku` for different use cases. +::: \ No newline at end of file diff --git a/docs/guides/nwaku/configure-nwaku.md b/docs/guides/nwaku/configure-nwaku.md new file mode 100644 index 0000000..9f117a0 --- /dev/null +++ b/docs/guides/nwaku/configure-nwaku.md @@ -0,0 +1,242 @@ +--- +title: Nwaku Configuration Examples +--- + +This guide provides detailed steps to configure a `nwaku` node for different use cases. + +## Connect to Other Peers + +To join the Waku Network, nodes must [bootstrap](/overview/reference/glossary#bootstrapping) for an entry point before discovering more peers. Nwaku provides multiple [peer discovery](/overview/concepts/peer-discovery) mechanisms: + +- [Configure Static Peers](/guides/nwaku/configure-discovery#configure-static-peers) +- [Configure DNS Discovery](/guides/nwaku/configure-discovery#configure-dns-discovery) +- [Configure Discv5](/guides/nwaku/configure-discovery#configure-discv5) +- [Configure Peer Exchange](/guides/nwaku/configure-discovery#configure-peer-exchange) + +## Configure a Domain Name + +You can set up an IPv4 DNS domain name that resolves to the public IPv4 address of a node using the `dns4-domain-name` option. This allows the node's publicly announced multiaddrs to use the `/dns4` scheme. + +```bash +./build/wakunode2 --dns4-domain-name=[DOMAIN NAME] +``` + +For example, consider the domain name `nwakunode.com`, which resolves to a `nwaku` node: + +```bash +./build/wakunode2 --dns4-domain-name=nwakunode.com +``` + +Browser nodes can only connect to nodes with a domain name and secure WebSocket (`wss`) configured. These nodes will generate a discoverable ENR with `/wss` as the multiaddr and `/dns4` as the domain name. This configuration is essential for verifying domain certificates when establishing a secure connection. + +:::info +This example describes configuring a domain name that resolves to your node's IP address and is unrelated to [DNS Discovery](/overview/concepts/dns-discovery). +::: + +## Configure Store Protocol and Message Store + +To enable message caching and serve them to network peers, enable the [Store protocol](/overview/concepts/protocols#store) using the following configuration options: + +- `store`: Enables storing messages to serve them to peers (disabled by default). +- `store-message-retention-policy`: Retention policy of the store node (how long messages will be persisted). Two different retention policies are supported: + - Time retention policy: `time:` (e.g., `time:14400`) + - Capacity retention policy: `capacity:` (e.g, `capacity:25000`) + - Set this option to an empty string to disable the retention policy. If you omit this option, it will default to `time:172800` (48 hours). +- `store-message-db-url`: Database connection URL for persisting messages in the [SQLAlchemy database URL format](https://docs.sqlalchemy.org/en/20/core/engines.html#database-urls). Setting this option to an empty string will instruct the node to use the fallback in-memory message store. If you omit this option, it will default to `sqlite://store.sqlite3`. + +```bash +./build/wakunode2 \ + --store=true \ + --store-message-retention-policy=[MESSAGE RETENTION POLICY] \ + --store-message-db-url=[DATABASE CONNECTION URL] +``` + +For example, consider a `nwaku` node that is configured to be a `Store` protocol and retain messages received in the last `21600` seconds (6 hours): + +```bash +./build/wakunode2 \ + --store=true \ + --store-message-retention-policy=time:21600 \ + --store-message-db-url=sqlite://store.sqlite3 +``` + +You can configure `nwaku` as a `Store client` using the `storenode` option. This allows the node to query peers for historical messages but not store any message itself. + +```bash +./build/wakunode2 --storenode=[STORE PEER MULTIADDR] +``` + +For example, consider a `nwaku` node that does not persist messages but can query peers for historical messages: + +```bash +./build/wakunode2 --storenode=/dns4/node-01.ac-cn-hongkong-c.wakuv2.prod.statusim.net/tcp/30303/p2p/16Uiu2HAm4v86W3bmT1BiH6oSPzcsSr24iDQpSN5Qa992BCjjwgrD +``` + +## Generate and Configure a Node Key + +Nodes generate [new random key pairs](/overview/reference/glossary#node-key) at each boot, leading to different `multiaddrs`. To maintain consistency, you can use a pre-generated private key with the `nodekey` option: + +```bash +./build/wakunode2 --nodekey=[NODE PRIVATE KEY] +``` + +This option takes a [Secp256k1](https://en.bitcoin.it/wiki/Secp256k1) private key (64-char hex string). On Linux, you can use the OpenSSL `rand` command for a pseudo-random 32-byte hex string: + +```bash +openssl rand -hex 32 + +# 286cae9f2990bfc49dafdd3a9e737f56ddba3656e5e427108cef456fb67680e8 +``` + +On Linux, you can create a reusable key file using OpenSSL. To get the 32-byte private key in hex format, use the `ecparam` command and some standard utilities: + +```bash +# Generate key file +openssl ecparam -genkey -name secp256k1 -out my_private_key.pem + +# Extract 32-byte private key +openssl ec -in my_private_key.pem -outform DER | tail -c +8 | head -c 32| xxd -p -c 32 + +# read EC key +# writing EC key +# 286cae9f2990bfc49dafdd3a9e737f56ddba3656e5e427108cef456fb67680e8 +``` + +You can use the output `286cae9f2990bfc49dafdd3a9e737f56ddba3656e5e427108cef456fb67680e8` as a `Node Key` for `nwaku`: + +```bash +./build/wakunode2 --nodekey=286cae9f2990bfc49dafdd3a9e737f56ddba3656e5e427108cef456fb67680e8 +``` + +## Configure WebSocket Transport + +WebSocket is the only [transport method](/overview/concepts/transports) browser nodes support using [@waku/sdk](/guides/js-waku/). To enable WebSocket in `nwaku` to serve browser peers, use the following configuration options: + +- `websocket-support`: Enables WebSocket (`ws`) on the node (disabled by default). +- `websocket-port` (optional): WebSocket listening port. If you omit this option, it will default to `8000`. +- `websocket-secure-support`: Enables Secure WebSocket (`wss`) on the node (disabled by default). +- `websocket-secure-key-path`: Secure WebSocket key path. +- `websocket-secure-cert-path`: Secure WebSocket Certificate path. + +```bash +./build/wakunode2 \ + --websocket-support=true \ + --websocket-port=[WEBSOCKET LISTENING PORT] \ + --websocket-secure-support=true \ + --websocket-secure-key-path=[SECURE WEBSOCKET KEY PATH] \ + --websocket-secure-cert-path=[SECURE WEBSOCKET CERTIFICATE PATH] +``` + +For example, consider a `nwaku` node that enabled WebSocket (unencrypted) for local testing on port `8001`: + +```bash +./build/wakunode2 \ + --websocket-support=true \ + --websocket-port=8001 +``` + +Consider a `nwaku` node that enabled Secure WebSocket (encrypted) using its key and certificate (`privkey.pem` and `fullchain.pem`) on port `8002`: + +```bash +./build/wakunode2 \ + --websocket-secure-support=true \ + --websocket-secure-key-path=privkey.pem \ + --websocket-secure-cert-path=fullchain.pem \ + --websocket-port=8002 +``` + +:::tip +You can use [Let's Encrypt](https://letsencrypt.org/) or [Certbot](https://certbot.eff.org/) to generate a valid certificate for your `nwaku` node: + +```bash +sudo letsencrypt -d +``` +::: + +## Configure REST API Server + +Nwaku provides a REST API to interact with the node and Waku Network. To enable the REST API, use the following configuration options: + +- `rest`: Enables the REST API server on the node (disabled by default). +- `rest-address` (optional): Listening address of the REST API server. If you omit this option, it will default to `127.0.0.1`. +- `rest-port` (optional): Listening port of the REST API server. If you omit this option, it will default to `8645`. +- `rest-relay-cache-capacity` (optional): Capacity of the Relay REST API message cache. If you omit this option, it will default to `30`. +- `rest-admin` (optional): Enables access to REST admin API (disabled by default). +- `rest-private` (optional): Enables access to REST private API (disabled by default). + +```bash +./build/wakunode2 \ + --rest=true \ + --rest-address=[REST SERVER LISTENING ADDRESS] \ + --rest-port=[REST SERVER LISTENING PORT] \ + --rest-relay-cache-capacity=[MESSAGE CACHE CAPACITY] \ + --rest-admin=[true|false] \ + --rest-private=[true|false] +``` + +For example, consider a `nwaku` node that enabled the REST API server on port `9000`: + +```bash +./build/wakunode2 \ + --rest=true \ + --rest-port=9000 \ + --rest-address=127.0.0.1 +``` + +Consider a `nwaku` node that enabled the REST `admin` and `private` API with a message cache capacity of `100`: + +```bash +./build/wakunode2 \ + --rest=true \ + --rest-admin=true \ + --rest-private=true \ + --rest-relay-cache-capacity=100 +``` + +## Configure Filter Protocol + +To enable `nwaku` to serve light clients, enable the [Filter protocol](/overview/concepts/protocols#filter) using the following configuration options: + +```bash +./build/wakunode2 --filter=true +``` + +You can configure `nwaku` as a `Filter client` using the `filternode` and `filter-timeout` options. This allows the node to request content filtering of messages from peers. + +```bash +./build/wakunode2 \ + --filternode=[FILTER PEER MULTIADDR] \ + --filter-timeout=[FILTER PEER TIMEOUT] +``` + +For example, consider a `nwaku` node that requests content filtering of messages from peers with a timeout of `21600` seconds (6 hours): + +```bash +./build/wakunode2 \ + --filternode=/dns4/node-01.ac-cn-hongkong-c.wakuv2.prod.statusim.net/tcp/30303/p2p/16Uiu2HAm4v86W3bmT1BiH6oSPzcsSr24iDQpSN5Qa992BCjjwgrD \ + --filter-timeout=21600 +``` + +:::info +If you omit the `filter-timeout` option, it will default to `14400` seconds (4 hours). +::: + +## Configure Light Push Protocol + +To enable `nwaku` to serve light clients, enable the [Light Push protocol](/overview/concepts/protocols#light-push) using the following configuration options: + +```bash +./build/wakunode2 --lightpush=true +``` + +You can configure `nwaku` as a `Light Push client` using the `lightpushnode` option. This allows the node to request lightpush of published messages from peers. + +```bash +./build/wakunode2 --lightpushnode=[LIGHT PUSH PEER MULTIADDR] +``` + +For example, consider a `nwaku` node that requests lightpush of published messages from peers: + +```bash +./build/wakunode2 --lightpushnode=/dns4/node-01.ac-cn-hongkong-c.wakuv2.prod.statusim.net/tcp/30303/p2p/16Uiu2HAm4v86W3bmT1BiH6oSPzcsSr24iDQpSN5Qa992BCjjwgrD +``` \ 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 8cf7bb4..01975c7 100644 --- a/docs/guides/nwaku/run-docker-compose.md +++ b/docs/guides/nwaku/run-docker-compose.md @@ -39,4 +39,8 @@ Visit to view your :::tip 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. +::: + +:::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. ::: \ No newline at end of file diff --git a/docs/guides/nwaku/run-docker.md b/docs/guides/nwaku/run-docker.md index 3034dc0..b5980e1 100644 --- a/docs/guides/nwaku/run-docker.md +++ b/docs/guides/nwaku/run-docker.md @@ -38,7 +38,7 @@ docker run [OPTIONS] [IMAGE] [ARG...] Run `nwaku` using the most typical configuration: ```bash -docker run -i -t -p 60000:60000 -p 9000:9000/udp statusteam/nim-waku:v0.19.0 \ +docker run -i -t -p 60000:60000 -p 9000:9000/udp statusteam/nim-waku:v0.20.0 \ --dns-discovery=true \ --dns-discovery-url=enrtree://AOGECG2SPND25EEFMAJ5WF3KSGJNSGV356DSTL2YVLLZWIV6SAYBM@prod.waku.nodes.status.im \ --discv5-discovery=true \ @@ -53,4 +53,8 @@ dig TXT +short o-o.myaddr.l.google.com @ns1.google.com | awk -F'"' '{ print $2}' :::tip We recommend using explicit port mappings (`-p`) when exposing ports accessible from outside the host (listening and discovery ports, API servers). +::: + +:::tip Congratulations! +You have successfully built and started a `nwaku` node in a Docker container. Have a look at the [Nwaku Configuration Examples](/guides/nwaku/configure-nwaku) guide to learn how to configure `nwaku` for different use cases. ::: \ 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 663d1bd..791843c 100644 --- a/docs/guides/reference/node-config-options.md +++ b/docs/guides/reference/node-config-options.md @@ -23,7 +23,7 @@ Here are the available node configuration options, along with their default valu | Name | Default Value | Description | | - | - | - | | `agent-string` | `nwaku` | Node agent string which is used as identifier in network | -| `nodekey` | | P2P node private key as 64 char hex string | +| `nodekey` | | P2P node private key as 64-char hex string | | `listen-address` | `defaultListenAddress()` | Listening address for LibP2P (and Discovery v5, if enabled) traffic | | `tcp-port` | `60000` | TCP listening port | | `ports-shift` | `0` | Add a shift to all port numbers | @@ -50,15 +50,10 @@ Here are the available node configuration options, along with their default valu | `relay-peer-exchange` | `false` | Enable gossipsub peer exchange in relay protocol: true\|false | | `rln-relay` | `false` | Enable spam protection through rln-relay: true\|false | | `rln-relay-cred-path` | | The path for persisting rln-relay credential | -| `rln-relay-membership-index` | `0` | The index of credentials to use | -| `rln-relay-membership-group-index` | `0` | The index of credentials to use, within a specific rln membership set | -| `rln-relay-pubsub-topic` | `/waku/2/default-waku/proto` | The pubsub topic for which rln-relay gets enabled | -| `rln-relay-content-topic` | `/toy-chat/3/mingde/proto` | The content topic for which rln-relay gets enabled | +| `rln-relay-membership-index` | | The index of the onchain commitment to use | | `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-account-address` | | Account address for the Ethereum testnet Sepolia | -| `rln-relay-eth-account-private-key` | | Account private key for the Ethereum testnet Sepolia | | `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-cred-password` | | Password for encrypting RLN credentials | @@ -80,7 +75,6 @@ Here are the available node configuration options, along with their default valu | `store-message-db-url` | `sqlite://store.sqlite3` | The database connection URL for persistent storage | | `store-message-db-vacuum` | `false` | Enable database vacuuming at start. Only supported by SQLite database engine | | `store-message-db-migration` | `true` | Enable database migration at start | -| `store-resume-peer` | | Peer multiaddress to resume the message store at boot | ## Filter Config diff --git a/docs/guides/run-nwaku-node.md b/docs/guides/run-nwaku-node.md index fde4a68..b0c7252 100644 --- a/docs/guides/run-nwaku-node.md +++ b/docs/guides/run-nwaku-node.md @@ -45,7 +45,7 @@ Once you have gotten the `nwaku` binary, run it using the [default configuration ``` :::tip -For more advanced configurations like enabling other protocols or maintaining a consistent `PeerID`, have a look at the [Node Configuration Methods](/guides/reference/node-config-methods) guide. +To learn how to customise the configuration of a `nwaku` node, have a look at the [Node Configuration Methods](/guides/reference/node-config-methods) and [Node Configuration Options](/guides/reference/node-config-options) guides. ::: ## Bootstrap the Node @@ -161,4 +161,8 @@ INF 2023-06-15 16:09:54.448+01:00 Discv5: discoverable ENR top ```bash # ENR the node addresses are encoded in enr:-IO4QDxToTg86pPCK2KvMeVCXC2ADVZWrxXSvNZeaoa0JhShbM5qed69RQz1s1mWEEqJ3aoklo_7EU9iIBcPMVeKlCQBgmlkgnY0iXNlY3AyNTZrMaEDdBHK1Gx6y_zv5DVw5Qb3DtSOMmVHTZO1WSORrF2loL2DdWRwgiMohXdha3UyAw -``` \ No newline at end of file +``` + +:::tip Congratulations! +You have successfully started, configured, and connected a `nwaku` node to the Waku Network. Have a look at the [Nwaku Configuration Examples](/guides/nwaku/configure-nwaku) guide to learn how to configure `nwaku` for different use cases. +::: \ No newline at end of file diff --git a/docs/overview/reference/glossary.md b/docs/overview/reference/glossary.md index 5a2d00d..4c2595f 100644 --- a/docs/overview/reference/glossary.md +++ b/docs/overview/reference/glossary.md @@ -60,7 +60,7 @@ A node is a device or client that implements Waku [protocols](#protocol) and lev ### Node Key -A node key is a [Secp256k1](https://en.bitcoin.it/wiki/Secp256k1) (64 char hex string) private key for generating the [PeerID](#peer-id), [listening](#transport) addresses, and [discovery](#peer-discovery) addresses of a Waku node. +A node key is a [Secp256k1](https://en.bitcoin.it/wiki/Secp256k1) (64-char hex string) private key for generating the [PeerID](#peer-id), [listening](#transport) addresses, and [discovery](#peer-discovery) addresses of a Waku node. ### Payload diff --git a/sidebars.js b/sidebars.js index e8f9007..c806cbe 100644 --- a/sidebars.js +++ b/sidebars.js @@ -61,6 +61,7 @@ const sidebars = { "guides/nwaku/run-docker", "guides/nwaku/run-docker-compose", "guides/nwaku/configure-discovery", + "guides/nwaku/configure-nwaku" ] }, {