waku-org
/
nwaku
mirror of https://github.com/waku-org/nwaku.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
nwaku/docs/operators/how-to/run.md

9.1 KiB
Raw Blame History

Running nwaku

Nwaku binaries can be built and run on Linux and macOS. Windows support is experimental.

# Run with default configuration
./build/wakunode2

# See available command line options
./build/wakunode2 --help

Default configuration

By default a nwaku node will:

  • generate a new private key and libp2p identities after every restart. See this tutorial if you want to generate and configure a persistent private key.
  • listen for incoming libp2p connections on the default TCP port (60000)
  • enable relay protocol
  • subscribe to the default pubsub topic, namely /waku/2/default-waku/proto
  • enable store protocol, but only as a client. This implies that the nwaku node will not persist any historical messages itself, but can query store service peers who do so. To configure store as a service node, see this tutorial.

Note: The filter and lightpush protocols are not enabled by default. Consult the configuration guide on how to configure your nwaku node to run these protocols.

Some typical non-default configurations are explained below. For more advanced configuration, see the configuration guide. Different ways to connect to other nodes are expanded upon in our connection guide.

Finding your listening address(es)

Find the log entry beginning with Listening on. It should be printed at INFO level when you start your node and contains a list of all publically announced listening addresses for the nwaku node.

For example

INF 2022-05-11 16:42:30.591+02:00 Listening on                               topics="wakunode" tid=6661 file=wakunode2.nim:941 full=[/ip4/0.0.0.0/tcp/60000/p2p/16Uiu2HAkzjwwgEAXfeGNMKFPSpc6vGBRqCdTLG5q3Gmk2v4pQw7H][/ip4/0.0.0.0/tcp/8000/ws/p2p/16Uiu2HAkzjwwgEAXfeGNMKFPSpc6vGBRqCdTLG5q3Gmk2v4pQw7H]

indicates that your node is listening on the TCP transport address

/ip4/0.0.0.0/tcp/60000/p2p/16Uiu2HAkzjwwgEAXfeGNMKFPSpc6vGBRqCdTLG5q3Gmk2v4pQw7H

and websocket address

/ip4/0.0.0.0/tcp/8000/ws/p2p/16Uiu2HAkzjwwgEAXfeGNMKFPSpc6vGBRqCdTLG5q3Gmk2v4pQw7H

You can also query a running node for its listening addresses using a get_waku_v2_debug_v1_info JSON-RPC API call.

For example

curl -d '{"jsonrpc":"2.0","id":"id","method":"get_waku_v2_debug_v1_info", "params":[]}' --header "Content-Type: application/json" http://localhost:8545

returns a response similar to

{
  "jsonrpc": "2.0",
  "id": "id",
  "result": {
    "listenAddresses": [
      "/ip4/0.0.0.0/tcp/60000/p2p/16Uiu2HAmLU5Nwng9dWFZwM2DgJ5QGcUuDnefJyHJiXUCVaprhgL4"
    ],
    "enrUri": "enr:-IO4QDxToTg86pPCK2KvMeVCXC2ADVZWrxXSvNZeaoa0JhShbM5qed69RQz1s1mWEEqJ3aoklo_7EU9iIBcPMVeKlCQBgmlkgnY0iXNlY3AyNTZrMaEDdBHK1Gx6y_zv5DVw5Qb3DtSOMmVHTZO1WSORrF2loL2DdWRwgiMohXdha3UyAw"
  }
}

Finding your discoverable ENR address(es)

A nwaku node can encode its addressing information in an Ethereum Node Record (ENR) according to 31/WAKU2-ENR. These ENR are most often used for discovery purposes.

ENR for DNS discovery

Find the log entry beginning with DNS: discoverable ENR. It should be printed at INFO level when you start your node with DNS discovery enabled and contains an ENR that can be added to node lists discoverable via DNS.

For example

INF 2022-05-20 11:52:48.772+02:00 DNS: discoverable ENR                      topics="wakunode" tid=5182 file=wakunode2.nim:941 enr=enr:-Iu4QBZs5huNuEAjI9WA0HOAjzpmp39vKJAtYRG3HXH86-i3HGcxMgupIkyDBmBq9qJ2wFfgMiW8AUzUxTFMAzfJM5MBgmlkgnY0gmlwhAAAAACJc2VjcDI1NmsxoQN0EcrUbHrL_O_kNXDlBvcO1I4yZUdNk7VZI5GsXaWgvYN0Y3CC6mCFd2FrdTID

indicates that your node addresses are encoded in the ENR

enr=enr:-Iu4QBZs5huNuEAjI9WA0HOAjzpmp39vKJAtYRG3HXH86-i3HGcxMgupIkyDBmBq9qJ2wFfgMiW8AUzUxTFMAzfJM5MBgmlkgnY0gmlwhAAAAACJc2VjcDI1NmsxoQN0EcrUbHrL_O_kNXDlBvcO1I4yZUdNk7VZI5GsXaWgvYN0Y3CC6mCFd2FrdTID

ENR for Discovery v5

Find the log entry beginning with Discv5: discoverable ENR. It should be printed at INFO level when you start your node with Waku Discovery v5 enabled and contains the ENR that will be discoverable by other peers.

For example

INF 2022-05-20 11:52:48.775+02:00 Discv5: discoverable ENR                   topics="wakunode" tid=5182 file=wakunode2.nim:905 enr=enr:-IO4QDxToTg86pPCK2KvMeVCXC2ADVZWrxXSvNZeaoa0JhShbM5qed69RQz1s1mWEEqJ3aoklo_7EU9iIBcPMVeKlCQBgmlkgnY0iXNlY3AyNTZrMaEDdBHK1Gx6y_zv5DVw5Qb3DtSOMmVHTZO1WSORrF2loL2DdWRwgiMohXdha3UyAw

indicates that your node addresses are encoded in the ENR

enr=enr:-IO4QDxToTg86pPCK2KvMeVCXC2ADVZWrxXSvNZeaoa0JhShbM5qed69RQz1s1mWEEqJ3aoklo_7EU9iIBcPMVeKlCQBgmlkgnY0iXNlY3AyNTZrMaEDdBHK1Gx6y_zv5DVw5Qb3DtSOMmVHTZO1WSORrF2loL2DdWRwgiMohXdha3UyAw

Typical configuration (relay node)

The typical configuration for a nwaku node is to run the relay protocol, subscribed to the default pubsub topic /waku/2/default-waku/proto, and connecting to one or more existing peers. We assume below that running nodes also participate in Discovery v5 to continually discover and connect to random peers for a more robust mesh.

Connecting to known peer(s)

A typical run configuration for a nwaku node is to connect to existing peers with known listening addresses using the --staticnode option. The --staticnode option can be repeated for each peer you want to connect to on startup. This is also useful if you want to run several nwaku instances locally and therefore know the listening addresses of all peers.

As an example, consider a nwaku node that connects to two known peers on the same local host (with IP 0.0.0.0) with TCP ports 60002 and 60003, and peer IDs 16Uiu2HAkzjwwgEAXfeGNMKFPSpc6vGBRqCdTLG5q3Gmk2v4pQw7H and 16Uiu2HAmFBA7LGtwY5WVVikdmXVo3cKLqkmvVtuDu63fe8safeQJ respectively. The Discovery v5 routing table can similarly be bootstrapped using a static ENR. We include an example below.

./build/wakunode2 \
  --ports-shift:1 \
  --staticnode:/ip4/0.0.0.0/tcp/60002/p2p/16Uiu2HAkzjwwgEAXfeGNMKFPSpc6vGBRqCdTLG5q3Gmk2v4pQw7H \
  --staticnode:/ip4/0.0.0.0/tcp/60003/p2p/16Uiu2HAmFBA7LGtwY5WVVikdmXVo3cKLqkmvVtuDu63fe8safeQJ \
  --discv5-discovery:true \
  --discv5-bootstrap-node:enr:-JK4QM2ylZVUhVPqXrqhWWi38V46bF2XZXPSHh_D7f2PmUHbIw-4DidCBnBnm-IbxtjXOFbdMMgpHUv4dYVH6TgnkucBgmlkgnY0gmowhCJ6_HaJc2VjcDI1NmsxoQM06FsT6EJ57mzR_wiLu2Bz1dER2nUFSCpaFzCccQtnhYN0Y3CCdl-DdWRwgiMohXdha3UyDw

Tip: --ports-shift shifts all configured ports forward by the configured amount. This is another useful option when running several nwaku instances on a single machine and would like to avoid port clashes without manually configuring each port.

Connecting to the wakuv2.prod network

See this explainer on the different networks and Waku v2 fleets.

You can use DNS discovery to bootstrap connection to the existing production network. Discovery v5 will attempt to extract the ENRs of the discovered nodes as bootstrap entries to the routing table.

./build/wakunode2 \
  --ports-shift:1 \
  --dns-discovery:true \
  --dns-discovery-url:enrtree://AOGECG2SPND25EEFMAJ5WF3KSGJNSGV356DSTL2YVLLZWIV6SAYBM@prod.waku.nodes.status.im \
  --discv5-discovery:true

Connecting to the wakuv2.test network

See this explainer on the different networks and Waku v2 fleets.

You can use DNS discovery to bootstrap connection to the existing test network. Discovery v5 will attempt to extract the ENRs of the discovered nodes as bootstrap entries to the routing table.

./build/wakunode2 \
  --ports-shift:1 \
  --dns-discovery:true \
  --dns-discovery-url:enrtree://AOGECG2SPND25EEFMAJ5WF3KSGJNSGV356DSTL2YVLLZWIV6SAYBM@test.waku.nodes.status.im \
  --discv5-discovery:true

Typical configuration (relay and store service node)

Often nwaku nodes choose to also store historical messages from where it can be queried by other peers who may have been temporarily offline. For example, a typical configuration for such a store service node, connecting to the wakuv2.test fleet on startup, appears below.

./build/wakunode2 \
  --ports-shift:1 \
  --store:true \
  --persist-messages:true \
  --db-path:/mnt/nwaku/data/db1/ \
  --store-capacity:150000 \
  --dns-discovery:true \
  --dns-discovery-url:enrtree://AOGECG2SPND25EEFMAJ5WF3KSGJNSGV356DSTL2YVLLZWIV6SAYBM@test.waku.nodes.status.im \
  --discv5-discovery:true

See our store configuration tutorial for more.

Interact with a running nwaku node

A running nwaku node can be interacted with using the Waku v2 JSON RPC API.

Note: Private and Admin API functionality are disabled by default. To configure a nwaku node with these enabled, use the --rpc-admin:true and --rpc-private:true CLI options.