Waku Relay Source

AuthorsOskar Thorén

Table of Contents


WakuRelay is part of the gossip domain for Waku. It is a thin layer on top of GossipSub.

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

Wire Specification

We are using protobuf RPC messages between peers. Here’s what the protobuf messages looks like, as defined in the PubSub interface. Please see PubSub interface spec for more details.

In this section we specify two things how WakuSub is using these messages.


message RPC {
  repeated SubOpts subscriptions = 1;
  repeated Message publish = 2;

  message SubOpts {
    optional bool subscribe = 1;
    optional string topicid = 2;

message Message {
  optional string from = 1;
  optional bytes data = 2;
  optional bytes seqno = 3;
  repeated string topicIDs = 4;
  optional bytes signature = 5;
  optional bytes key = 6;

WakuSub does not currently use the ControlMessage defined in GossipSub. However, later versions will add likely add this capability.

TopicDescriptor as defined in the PubSub interface spec is not currently used.


These are messages sent to directly connected peers. They SHOULD NOT be gossiped. See section below on how the fields work.


The from field MAY indicate which peer is publishing the message.

The data field MUST be filled out with a WakuMessage. See the Waku Message spec for more details.

The seqno field MAY be used to provide a linearly increasing number. See PubSub spec for more details.

The topicIDs field MUST contain the topics that a message is being published on.

The signature field MAY contain the signature of the message, thus providing authentication of the message. See PubSub spec for more details.

The key field MAY be present and relates to signing. See PubSub spec for more details.


To do topic subscription management, we MAY send updates to our peers. If we do so, then:

The subscribe field MUST contain a boolean, where 1 means subscribe and 0 means unsubscribe to a topic.

The topicid field MUST contain the topic.



Next version. Changes:

  • Moved WakuMessage to separate spec and made it mandatory


Initial draft version. Released 2020-09-17


Copyright and related rights waived via CC0.


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

  2. GossipSub v1.0

  3. GossipSub v1.1

  4. Waku v1 spec

  5. Whisper spec (EIP627)

Re topicid: NOTE: This doesn’t appear to be documented in PubSub spec, upstream? –>