What is Waku?

Waku is a family of robust, censorship-resistant communication protocols designed to enable privacy-focused messaging for web3 apps.

In other words, Waku allows you to build decentralized applications which require any form of message transfer (e.g. chats, push notifications, event broadcasting, weak consensus/coordination, message queues). You can build your own application protocols on top of plug&play Waku protocols, which ensure your node will be well connected with the network and your messages will be broadcasted reliably.

Waku also includes protocols friendly to resource restricted / adaptive devices like smartphones or laptops which may not have a lot of compute power or bandwith.

Who is this deployment for?

The deployment manifests in this folder target users who wish to support the Waku Network as a node operator (i.e. making the network more robust, decentralized and private), but also users who would like to build an application on top of waku.

We provide 2 deployment manifests - they both enable Relay, Lightpush, Filter and Store protocols and connect to The Waku Network, but differ in the archive backend for Store protocol.

The deploy.sqlite.yaml is the simpler of two, leverages SQLite for archive, hence results in simpler and slightly cheaper deployment.

The deploy.yaml deploys Postgresql database instance in addition to the nwaku node.

How to

Waku nodes connecting to The Waku Network require access to an Ethereum (Sepolia Testnet) RPC endpoint. You can obtain one from miriad of node providers like Infura, Chainstack, Quicknode, or run one yourself (even on Akash:)).

The RPC node URL needs to be configured in ETH_CLIENT_ADDRESS environment variable of the deployment manifest.

Another mandatory environment variable is IP_ADDR. This is the IP address leased for this deplyoment. Sadly, it cannot be obtained before the actual deployment happens neither can it be resolved from inside the deployment. This means that after deploying first with empty IP_ADDR, you need to get the address of the IP lease and update the deployment by adding the value to the environment variable. Only after you do that, the node will be able to properly announce itself to the network and other peers will be able to connect to it.

Deploying as Relayer

If you just want to support the network without intent to publish your own messages, you can simple add the RPC node URL and submit the deployment manifest. After the node syncs the RLN membership tree it will start relaying messages. You don’t need to do anything else.

Deploying as Publisher

In case your goal is to use this node to publish messages, you will need to obtain an RLN membership yourself. For that you can use a helper script in nwaku-compose which allows you to register the membership and produces keystore.json file. You will need to encode the content of this file with base64 encoding and pass it into the deployment fail as RLN_RELAY_CRED_BASE64.

Deploying with Postgres

This deployment not only deploys Waku node, but also a Postgres database serving as an archive for the store protocol. The manifest including Postgres instance is availabale in deploy.yaml.

You may want to change the POSTGRES_PASSWORD in services.node.env and services.postgres.env (make sure both values match!).

Deploying with Permanent PeerId

PeerID is part of the node’s identity. It is based on a private key which randomly generated by default. In case you want or need to hardcode your node in your application, you will need a stable/permanent PeerID. This is achieved by providing a value in the NODEKEY environment variable. You can generate a node key by running

openssl rand -hex 32

Deploying with Domain Name

There is an environment variable DOMAIN available in the manifests which allows you to provide a domain name which can be used to address your node. This requires a 2 step deployment as we cannot predict the IP lease before the actual instance is deployed.

Deploy one of the manifests with empty DOMAIN.
Check the IP leased to your deployment.
Create an A record for the desired domain name and the leased IP.
Update your deployment with the DOMAIN value.

After applying the updated deployment, you should see Let’s Encrypt certificates being provisioned in logs and then node starting and relaying messages.

After You Deploy

Two important pieces of information about your node are the node’s multiaddresses and ENR. You can find both early in the logs output after the deployment.

[node]: INF 2023-08-14 13:59:38.175+00:00 PeerInfo                                   topics="waku node" tid=1 file=waku_node.nim:796 peerId=16U*9q9fq5 addrs=@[]
[node]: INF 2023-08-14 13:59:38.175+00:00 Listening on                               topics="waku node" tid=1 file=waku_node.nim:803 full=[/dns4/waku.myrandomdemos.online/tcp/60000/p2p/16Uiu2HAmDdZ1brt7nq717ugWSK1EcGdaxUMVmHeVFzcPGb9q9fq5][/dns4/waku.myrandomdemos.online/tcp/8000/wss/p2p/16Uiu2HAmDdZ1brt7nq717ugWSK1EcGdaxUMVmHeVFzcPGb9q9fq5]
[node]: INF 2023-08-14 13:59:38.175+00:00 DNS: discoverable ENR                      topics="waku node" tid=1 file=waku_node.nim:804 enr=enr:-OG4QIzHr0Xd9OJVY3cDxqmDvwprccDQcRL0km9LR-q0MnjwFXZsqri_mnFwECqzVOxi78YierreeH9DUyYpdCeWZvIBgmlkgnY0gmlwhLhporWKbXVsdGlhZGRyc7hCAB42GXdha3UubXlyYW5kb21kZW1vcy5vbmxpbmUG6mAAIDYZd2FrdS5teXJhbmRvbWRlbW9zLm9ubGluZQYfQN4DiXNlY3AyNTZrMaEDDn10Z_V6Qh_BJV0BA_Y7wuTaApavCGi0WiIoZkMlGXyDdGNwgupgg3VkcIIjLYV3YWt1Mg8

You can verify that your deployment was successful and your node is reachable by connecting to it using wakucanary tool or, if you used the full deployment, by connecting via WSS using one of the js-waku-examples.

You can monitor your deployment with Prometheus and use a Grafana dashboard available in https://github.com/waku-org/nwaku-compose/tree/master/monitoring.

You should see basic metrics printed in logs as well:

[node]: INF 2023-08-15 10:39:37.807+00:00 Relay peer connections                     topics="waku node peer_manager" tid=1 file=peer_manager.nim:683 inRelayConns=4/160 outRelayConns=17/80 totalConnections=24/300 notConnectedPeers=137 outsideBackoffPeers=5
[node]: INF 2023-08-15 10:39:39.460+00:00 Finished dialing multiple peers            topics="waku node peer_manager" tid=1 file=peer_manager.nim:532 successfulConns=0 attempted=3
[node]: INF 2023-08-15 10:39:40.532+00:00 Total connections initiated                topics="waku node metrics" tid=1 file=waku_metrics.nim:56 count=0.0
[node]: INF 2023-08-15 10:39:40.532+00:00 Total messages                             topics="waku node metrics" tid=1 file=waku_metrics.nim:57 count=231479.0
[node]: INF 2023-08-15 10:39:40.532+00:00 Total store peers                          topics="waku node metrics" tid=1 file=waku_metrics.nim:58 count=0.0
[node]: INF 2023-08-15 10:39:40.532+00:00 Total peer exchange peers                  topics="waku node metrics" tid=1 file=waku_metrics.nim:59 count=0.0
[node]: INF 2023-08-15 10:39:40.532+00:00 Total lightpush peers                      topics="waku node metrics" tid=1 file=waku_metrics.nim:60 count=0.0
[node]: INF 2023-08-15 10:39:40.532+00:00 Total filter peers                         topics="waku node metrics" tid=1 file=waku_metrics.nim:61 count=0.0
[node]: INF 2023-08-15 10:39:40.532+00:00 Total active filter subscriptions          topics="waku node metrics" tid=1 file=waku_metrics.nim:62 count=0.0
[node]: INF 2023-08-15 10:39:40.532+00:00 Total errors                               topics="waku node metrics" tid=1 file=waku_metrics.nim:63 count=1.0
[node]: INF 2023-08-15 10:40:10.532+00:00 Total connections initiated                topics="waku node metrics" tid=1 file=waku_metrics.nim:56 count=0.0

Notice the inRelayConns and outRelayConns - those represent the number of nodes in peer-to-peer relay network you are connected to.

Notice the Total messages metric - this represents how many messages went through your node.