Waku Source

AuthorsOskar Thorén

Table of Contents


Waku is a privacy-preserving peer-to-peer messaging protocol for resource restricted devices. It implements PubSub over libp2p and adds capabilities on top of it. These capabilities are: (i) retrieving historical messages for mostly-offline devices (ii) adaptive nodes, allowing for heterogeneous nodes to contribute, and (iii) bandwidth preservation for light nodes. This makes it ideal for running a p2p protocol on mobile.

Historically, it has its roots in Waku v1, which stems from Whisper, originally part of the Ethereum stack. However, Waku v2 acts more as a thin wrapper for PubSub and has a different API. It is implemented in an iterative manner where initial focus is on porting essential functionality to libp2p. See rough road map.

Motivation and goals

  1. Generalized messaging. Many applications requires some form of messaging protocol to communicate between different subsystems or different nodes. This messaging can be human-to-human or machine-to-machine or a mix.

  2. Peer-to-peer. These applications sometimes have requirements that make them suitable for peer-to-peer solutions.

  3. Resource restricted.These applications often run in constrained environments, where resources or the environment is restricted in some fashion. E.g.:

  • limited bandwidth, CPU, memory, disk, battery, etc
  • not being publicly connectable
  • only being intermittently connected; mostly-offline
  1. Privacy. These applications have a desire for some privacy guarantees, such as pseudonymity, metadata protection in transit, etc.

Waku provides a solution that satisfies these goals in a reasonable matter.

Network interaction domains

While Waku is best though of as a single cohesive thing, there are three network interaction domains: (a) gossip domain (b) discovery domain (c) req/resp domain.

Protocols and identifiers

The current protocol identifiers are:

  1. /vac/waku/relay/2.0.0-beta1
  2. /vac/waku/store/2.0.0-beta1
  3. /vac/waku/filter/2.0.0-beta1

These protocols and their semantics are elaborated on in their own specs.

For the actual content being passed around, see the Waku Message spec.

Gossip domain

Protocol identifier*: /vac/waku/relay/2.0.0-beta1

See WakuRelay spec for more details.

Discovery domain

Discovery domain is not yet implemented. Currently static nodes should be used.

Request/reply domain

This consists of two main protocols. They are used in order to get Waku to run in resource restricted environments, such as low bandwidth or being mostly offline.

Historical message support

Protocol identifier*: /vac/waku/store/2.0.0-beta1

See WakuStore spec for more details.

Content filtering

Protocol identifier*: /vac/waku/filter/2.0.0-beta1

See WakuFilter spec for more details.

Upgradability and Compatibility

Compatibility with Waku v1

Waku v2 and Waku v1 are different protocols all together. They use a different transport protocol underneath; Waku v1 is devp2p RLPx based while Waku v2 uses libp2p. The protocols themselves also differ as does their data format. Compatibility can be achieved only by using a bridge that not only talks both devp2p RLPx and libp2p, but that also transfers (partially) the content of a packet from one version to the other.

See bridge spec for details on a bridge mode.



Initial draft version. Released 2020-09-17


Copyright and related rights waived via CC0.


  1. Protocol Identifiers

  2. PubSub interface for libp2p (r2, 2019-02-01)

  3. GossipSub v1.0

  4. GossipSub v1.1

  5. Waku v1 spec

  6. Whisper spec (EIP627)

  7. Waku v2 plan

  8. Message Filtering (Wikipedia)

  9. Libp2p PubSub spec - topic validation