Run a Nwaku Node
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 they want to support based on their needs, motivations, and available resources.
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.
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 the node binary
To run a node, you must have the nwaku binary. Nwaku provides multiple options for running a node:
Run nwaku in Docker (recommended)
| Description | Documentation | |
|---|---|---|
| Docker Compose | Run a nwaku node with Docker Compose | Run Nwaku with Docker Compose |
| Docker Container | Run a nwaku node in a Docker Container | Run Nwaku in a Docker Container |
We recommend using Docker Compose to run a node because it's the simplest and fastest way to configure and run one.
Download the binary
| Description | Documentation | |
|---|---|---|
| Precompiled Binary | Download a precompiled binary of the nwaku node | Download Nwaku Binary |
| Nightly Release | Try the latest nwaku updates without compiling the binaries | Download Nightly Release |
Build the binary
| Description | Documentation | |
|---|---|---|
| Build from Source | Build the node from the nwaku source code | Build Nwaku from Source |
You can run the nwaku binaries and Docker images on cloud service providers like Google Cloud, Microsoft Azure, Amazon Web Services, and DigitalOcean.
Run the node
Once you have gotten the nwaku binary, run it using the default configuration:
# Run with default configuration
./build/wakunode2
# See available command line options
./build/wakunode2 --help
To learn how to customise the configuration of a nwaku node, have a look at the Node Configuration Methods and Node Configuration Examples guides.
Bootstrap the node
To join the Waku Network, nodes must bootstrap for an entry point before discovering more peers. Nwaku provides multiple peer discovery mechanisms:
| Description | Documentation | |
|---|---|---|
| Static Peers | Configure the bootstrap nodes that nwaku should establish connections upon startup | Configure Static Peers |
| DNS Discovery | Enable nwaku to bootstrap nodes using the DNS Discovery mechanism | Configure DNS Discovery |
| Discv5 | Enable nwaku to discover peers using the Discv5 mechanism | Configure Discv5 |
| Peer Exchange | Enable Peer Exchange protocol for light nodes to request peers from your nwaku node | Configure Peer Exchange |
You can configure a nwaku node to use multiple peer discovery mechanisms simultaneously.
Interact with the node
You can interact with a running nwaku node through the REST API, such as querying the node information using the Get node info endpoint:
- Request
- Response
curl --location 'http://127.0.0.1:8645/debug/v1/info' \
--header 'Accept: application/json'
{
"listenAddresses": [
"/ip4/0.0.0.0/tcp/60000/p2p/16Uiu2HAmUbPquFQqje3jiqoB5YoiUbBya59NB4qqEzeiTNGHeA6w"
],
"enrUri": "enr:-Iu4QCQZXZDb_JsYmLoYor0F5E_95HbIywgO_wgx2rIdDbmCJZkTzmlCr0wmMzV47lgik_tVwww5mIng90Ris83TisMBgmlkgnY0gmlwhAAAAACJc2VjcDI1NmsxoQPszztG-Ev52ZB7tk0jF8s6Md4KvyY_rhzNZokaaB_ABIN0Y3CC6mCFd2FrdTIB"
}
The listenAddresses field stores the node's listening addresses, while the enrUri field stores the discoverable ENR URI for peer discovery.
We suggest configuring WebSocket transport for your node to enable support and serving of browser peers using @waku/sdk.
Find the node addresses
You can find the addresses of a running node through its logs or by calling the Get node info endpoint of the REST API.
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:
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]
# 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) following the WAKU2-ENR specification, primarily for peer discovery.
ENR for DNS discovery
Look for the log entry that begins with DNS: discoverable ENR, for example:
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
# 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:
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
# ENR the node addresses are encoded in
enr:-IO4QDxToTg86pPCK2KvMeVCXC2ADVZWrxXSvNZeaoa0JhShbM5qed69RQz1s1mWEEqJ3aoklo_7EU9iIBcPMVeKlCQBgmlkgnY0iXNlY3AyNTZrMaEDdBHK1Gx6y_zv5DVw5Qb3DtSOMmVHTZO1WSORrF2loL2DdWRwgiMohXdha3UyAw
You have successfully started, configured, and connected a nwaku node to the Waku Network. Have a look at the Node Configuration Examples guide to learn how to configure nwaku for different use cases.