nim-waku

Waku v1

Introduction

The nim-waku repository holds a Nim implementation of the Waku v1 protocol and a cli application wakunode that allows you to run a Waku enabled node from command line.

The Waku v1 specification is still in draft and thus this implementation will change accordingly. For supported specification details see here.

Additionally the original Whisper (EIP-627) protocol can also be enabled as can an experimental Whisper - Waku bridging option.

The underlying transport protocol is rlpx + devp2p and the nim-eth implementation is used.

This repository is also a place for experimenting with possible future versions of Waku such as replacing the transport protocol with libp2p, see also Waku v2 protocol

How to Build & Run

Prerequisites

• GNU Make, Bash and the usual POSIX utilities. Git 2.9.4 or newer.
• PCRE

More information on the installation of these can be found here.

Wakunode

# The first `make` invocation will update all Git submodules.
# You'll run `make update` after each `git pull`, in the future, to keep those submodules up to date.
make wakunode1

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

# Connect the client directly with the Status test fleet
./build/wakunode --log-level:debug --discovery:off --fleet:test --log-metrics

Waku v1 Protocol Test Suite

# Run all the Waku v1 tests
make test1

You can also run a specific test (and alter compile options as you want):

# Get a shell with the right environment variables set
./env.sh bash
# Run a specific test
nim c -r ./tests/v1/test_waku_connect.nim

Waku v1 Protocol Example

There is a more basic example, more limited in features and configuration than the wakunode, located in examples/v1/example.nim.

More information on how to run this example can be found it its readme.

Waku Quick Simulation

One can set up several nodes, get them connected and then instruct them via the JSON-RPC interface. This can be done via e.g. web3.js, nim-web3 (needs to be updated) or simply curl your way out.

The JSON-RPC interface is currently the same as the one of Whisper. The only difference is the addition of broadcasting the topics interest when a filter with a certain set of topics is subcribed.

The quick simulation uses this approach, start_network launches a set of wakunodes, and quicksim instructs the nodes through RPC calls.

Example of how to build and run:

# Build wakunode + quicksim with metrics enabled
make NIMFLAGS="-d:insecure" sim1

# Start the simulation nodes, this currently requires multitail to be installed
./build/start_network --topology:FullMesh --amount:6 --test-node-peers:2
# In another shell run
./build/quicksim

The start_network tool will also provide a prometheus.yml with targets set to all simulation nodes that are started. This way you can easily start prometheus with this config, e.g.:

cd ./metrics/prometheus
prometheus

A Grafana dashboard containing the example dashboard for each simulation node is also generated and can be imported in case you have Grafana running. This dashboard can be found at ./metrics/waku-sim-all-nodes-grafana-dashboard.json

To read more details about metrics, see next section.

Using Metrics

Metrics are available for valid envelopes and dropped envelopes.

To compile in an HTTP endpoint for accessing the metrics we need to provide the insecure flag:

make NIMFLAGS="-d:insecure" wakunode1
./build/wakunode --metrics-server

Ensure your Prometheus config prometheus.yml contains the targets you care about, e.g.:

scrape_configs:
  - job_name: "waku"
    static_configs:
      - targets: ['localhost:8008', 'localhost:8009', 'localhost:8010']

For visualisation, similar steps can be used as is written down for Nimbus here.

There is a similar example dashboard that includes visualisation of the envelopes available at metrics/waku-grafana-dashboard.json.

Spec support

This section last updated April 21, 2020

This client of Waku is spec compliant with Waku spec v1.0.0.

It doesn't yet implement the following recommended features:

• No support for rate limiting
• No support for DNS discovery to find Waku nodes
• It doesn't disconnect a peer if it receives a message before a Status message
• No support for negotiation with peer supporting multiple versions via Devp2p capabilities in Hello packet

Additionally it makes the following choices:

• It doesn't send message confirmations
• It has partial support for accounting:
  • Accounting of total resource usage and total circulated envelopes is done through metrics But no accounting is done for individual peers.

Waku v2

Waku v2 is under active development but is currently in an early alpha state. See waku/node/v2/ and waku/protocol/v2/ directory for more details on the current state.

Here's a post outlining the current plan for Waku v2, and here's the current roadmap and progress https://github.com/vacp2p/research/issues/40

Docker Image

You can create a Docker image using:

make docker-image
docker run --rm -it statusteam/nim-waku:latest --help

Default, the target will be a docker image with wakunode, which is the Waku v1 node. You can change this to wakunode2, the Waku v2 node like this:

make docker-image MAKE_TARGET=wakunode2
docker run --rm -it statusteam/nim-waku:latest --help