Logos LIP Index

An IETF-style index of Logos-managed LIPs across Storage, Messaging, Blockchain, AnonComms, and Research sections. Use the filters below to jump straight to a specification.

About

The Logos LIP Index collects specifications maintained by Logos Research across Messaging, Blockchain, Storage, and AnonComms. Each RFC documents a protocol, process, or system in a consistent, reviewable format.

This site is generated with mdBook from the repository: logos-co/logos-lips.

Contributing

1. Open a pull request against the repo.
2. Add or update the RFC in the appropriate component folder.
3. Include clear status and category metadata in the RFC header table.

If you are unsure where a document belongs, open an issue first and we will help route it.

We keep RFCs in Markdown within this repository; updates happen through pull requests.

Links

• Logos Research: https://vac.dev
• IETF RFC Series: https://www.rfc-editor.org/
• Repository: https://github.com/logos-co/logos-lips

Messaging LIPs

Logos Messaging builds a family of privacy-preserving, censorship-resistant communication protocols for web3 applications.

Contributors can visit Messaging LIPs for new Messaging specifications under discussion.

Core

Core messaging delivery specifications.

Core

Core messaging delivery raw specifications.

RELAY-SHARDING

Timeline

• 2026-06-16 — 16e8af1 — Chore/separate messaging specs (#361)
• 2026-06-12 — 124f895 — chore: fix broken links (#357)
• 2026-05-11 — 1ac7689 — chore: split ift ts specs (#334)
• 2026-05-07 — 48600b5 — Migrate logos-messaging/specs into docs/messaging/ (#315)

Abstract

This document describes ways of sharding the Waku relay topic, allowing Waku networks to scale in the number of content topics.

Note: Scaling in the size of a single content topic is out of scope for this document.

Background and Motivation

Unstructured P2P networks are more robust and resilient against DoS attacks compared to structured P2P networks). However, they do not scale to large traffic loads. A single libp2p gossipsub mesh, which carries messages associated with a single pubsub topic, can be seen as a separate unstructured P2P network (control messages go beyond these boundaries, but at its core, it is a separate P2P network). With this, the number of Waku relay content topics that can be carried over a pubsub topic is limited. This prevents app protocols that aim to span many multicast groups (realized by content topics) from scaling.

This document specifies three pubsub topic sharding methods (with varying degrees of automation), which allow application protocols to scale in the number of content topics. This document also covers discovery of topic shards.

Named Sharding

Note: As of 2025-07-24 freely named sharding has been deprecated from all Waku implementations. It is still described here as background for static and automatic sharding.

Named sharding offers apps to freely choose pubsub topic names. It is RECOMMENDED for App protocols to follow the naming structure detailed in 23/WAKU2-TOPICS. With named sharding, managing discovery falls into the responsibility of apps. For this reason it is NOT RECOMMENDED that app protocols and Waku implementations make use of named sharding.

From an app protocol point of view, a subscription to a content topic waku2/xxx on a shard named /mesh/v1.1.1/xxx would look like:

subscribe("/waku2/xxx", "/mesh/v1.1.1/xxx")

Static Sharding

Static sharding is an extension of named sharding that offers a set of shards with fixed names. Assigning content topics to specific shards is up to app protocols, but the discovery of these shards is managed by Waku. This is the RECOMMENDED default format for shards chosen by an app protocol.

Static shards are managed in shard clusters of 1024 shards per cluster. Waku static sharding can manage shard clusters. Each shard cluster is identified by its index (between and ).

It is RECOMMENDED that, for simplification of configuration and various APIs, all app-level protocols only interact with cluster and shard and never the fully-formed pubsub topic, which is a concern internal to the Waku implementation.

A specific shard cluster is either globally available to all apps, specific for an app protocol, or reserved for automatic sharding (see next section).

Note: This leads to shards for which Waku manages discovery.

App protocols can either choose to use global shards, or app specific shards.

Like the IANA ports, shard clusters are divided into ranges:

The informational RFC WAKU2-RELAY-STATIC-SHARD-ALLOC lists the current index allocations.

The global shard with index 0 and the "all app protocols" range are treated in the same way, but choosing shards in the global cluster has a higher probability of sharing the shard with other apps. This offers k-anonymity and better connectivity, but comes at a higher bandwidth cost.

Since the introduction of the Waku Network, it is RECOMMENDED that apps choose a cluster + shard within the defined range for that network.

The name of the pubsub topic corresponding to a given static shard is specified as

/waku/2/rs/<cluster_id>/<shard_number>,

an example for the 2nd shard in the global shard cluster:

/waku/2/rs/0/2.

Note: Because all shards distribute payload defined in 14/WAKU2-MESSAGE via protocol buffers, the pubsub topic name does not explicitly add /proto to indicate protocol buffer encoding. We use rs to indicate these are relay shard clusters; further shard types might follow in the future.

From an app point of view, a subscription to a content topic waku2/xxx on a static shard would look like:

subscribe("/waku2/xxx", 16, 43)

for shard 43 of the Status app (which has allocated index 16).

Discovery

Waku v2 supports the discovery of peers within static shards, so app protocols do not have to implement their own discovery method.

Nodes add information about their shard participation in their WAKU2-ENR. Having a static shard participation indication as part of the ENR allows nodes to discover peers that are part of shards via 33/WAKU2-DISCV5 as well as via DNS.

Note: In the current version of this document, sharding information is directly added to the ENR. (see Ethereum ENR sharding bit vector here Static relay sharding supports 1024 shards per cluster, leading to a flag field of 128 bytes. This already takes half (including index and key) of the ENR space of 300 bytes. For this reason, the current specification only supports a single shard cluster per node. In future versions, we will add further (hierarchical) discovery methods. We will update WAKU2-ENR accordingly, once this RFC moves forward.

This document specifies two ways of indicating shard cluster participation. The index list SHOULD be used for nodes that participante in fewer than 64 shards, the bit vector representation SHOULD be used for nodes participating in 64 or more shards. Nodes MUST NOT use both index list (rs) and bit vector (rsv) in a single ENR. ENRs with both rs and rsv keys SHOULD be ignored. Nodes MAY interpret rs in such ENRs, but MUST ignore rsv.

Index List

The ENR key is rs. The value is comprised of

• a two-byte shard cluster index in network byte order, concatenated with
• a one-byte length field holding the number of shards in the given shard cluster, concatenated with
• two-byte shard indices in network byte order

Example:

This example node is part of shards 13, 14, and 45 in the Status main-net shard cluster (index 16).

Bit Vector

The ENR key is rsv. The value is comprised of a two-byte shard cluster index in network byte order concatenated with a 128-byte wide bit vector. The bit vector indicates which shards of the respective shard cluster the node is part of. The right-most bit in the bit vector represents shard 0, the left-most bit represents shard 1023. The representation in the ENR is inspired by Ethereum shard ENRs), and this).

Example:

The [...] in the example indicates 120 0 bytes. This example node is part of shards 13, 14, and 45 in the Status main-net shard cluster (index 16). (This is just for illustration purposes, a node that is only part of three shards should use the index list method specified above.)

Automatic Sharding

Autosharding is an extension of static sharding, where shards can automatically be selected based on content topic. This is only possible in cases where there exists a clear definition of a "network" combining multiple shards with a predefined cluster ID and number of shards in the network (number_of_shards_in_network). An example is the Waku Network. To use autosharding, the shards corresponding to the network definition MUST be numbered from 0 and monotonously increase to number_of_shards_in_network - 1. The Waku Network SHOULD be considered the default destination for all app-level protocols. In cases where the Waku Network is not used but autosharding is desired, the default number of shards in a network SHOULD be considered 1.

When using autosharding, shards (pubsub topics) MUST be computed from content topics with the procedure below.

Algorithm

Hash using Sha2-256 the concatenation of the content topic application field (UTF-8 string of N bytes) and the version (UTF-8 string of N bytes). The shard to use is the modulo of the hash by the number of shards in the network.

Example

• SHA2-256 of 0x6d7961707031 is 0x8e541178adbd8126068c47be6a221d77d64837221893a8e4e53139fb802d4928
• 0x8e541178adbd8126068c47be6a221d77d64837221893a8e4e53139fb802d4928 MOD 8 equals 0
• The shard to use has index 0

Content Topics Format for Autosharding

Content topics MUST follow the format in 23/WAKU2-TOPICS. In addition, a generation prefix MAY be added to content topics. When omitted default values are used. Generation default value is 0.

• The full length format is /{generation}/{application-name}/{version-of-the-application}/{content-topic-name}/{encoding}
• The short length format is /{application-name}/{version-of-the-application}/{content-topic-name}/{encoding}

Example

• Full length /0/myapp/1/mytopic/cbor
• Short length /myapp/1/mytopic/cbor

Generation and scaling

The generation number monotonously increases and indirectly refers to the total number of shards of a defined network. In order to scale, each subsequent generation of a defined network can define a larger number_of_shards_in_network, with the content topics only sharded to the number of shards defined for the corresponding generation of the network. Generational autosharding MUST be clearly defined for each generation of a network.

For example, consider a specific network defined as the 2 shards 0 and 1 in cluster 32. This will automatically be assumed to be generation 0 of this network. All content topics in the format /myapp/1/mytopic/cbor defined for apps on this network will be autosharded to 1 of these 2 shards. If in future the specifiers of this network want to scale the network to 4 shards (i.e. shards 0 to 3 on cluster 32), they MUST define a generation 1 version of the network with number_of_shards_in_network = 4. New content topics for apps on generation 1 of this network MUST be prefixed in the format /1/myapp/1/mytopic/cbor to be autosharded into all 4 shards. Legacy generation 0 content topics will still only be autosharded into the original 2 shards.

Topic Design

Content topics have 2 purposes: filtering and routing. Filtering is done by changing the {content-topic-name} field. As this part is not hashed, it will not affect routing (shard selection). The {application-name} and {version-of-the-application} fields do affect routing. Using multiple content topics with different {application-name} field has advantages and disadvantages. It increases the traffic a relay node is subjected to when subscribed to all topics. It also allows relay and light nodes to subscribe to a subset of all topics.

Problems

Hot Spots

Hot spots occur (similar to DHTs), when a specific mesh network (shard) becomes responsible for (several) large multicast groups (content topics). The opposite problem occurs when a mesh only carries multicast groups with very few participants: this might cause bad connectivity within the mesh.

The current autosharding method does not solve this problem.

Note: Automatic sharding based on network traffic measurements to avoid hot spots in not part of this specification.

Discovery

For the discovery of automatic shards this document specifies two methods (the second method will be detailed in a future version of this document).

The first method uses the discovery introduced above in the context of static shards.

The second discovery method will be a successor to the first method, but is planned to preserve the index range allocation. Instead of adding the data to the ENR, it will treat each array index as a capability, which can be hierarchical, having each shard in the indexed shard cluster as a sub-capability. When scaling to a very large number of shards, this will avoid blowing up the ENR size, and allows efficient discovery. We currently use 33/WAKU2-DISCV5 for discovery, which is based on Ethereum's discv5. While this allows to sample nodes from a distributed set of nodes efficiently and offers good resilience, it does not allow to efficiently discover nodes with specific capabilities within this node set. Our research log post explains this in more detail. Adding efficient (but still preserving resilience) capability discovery to discv5 is ongoing research. A paper on this has been completed, but the Ethereum discv5 specification has yet to be updated. When the new capability discovery is available, this document will be updated with a specification of the second discovery method. The transition to the second method will be seamless and fully backwards compatible because nodes can still advertise and discover shard memberships in ENRs.

Security/Privacy Considerations

See WAKU2-ADVERSARIAL-MODELS, especially the parts on k-anonymity. We will add more on security considerations in future versions of this document.

Receiver Anonymity

The strength of receiver anonymity, i.e. topic receiver unlinkablity, depends on the number of content topics (k), as a proxy for the number of peers and messages, that get mapped onto a single pubsub topic (shard). For named and static sharding this responsibility is at the app protocol layer.

Copyright

Copyright and related rights waived via CC0.

References

• 11/WAKU2-RELAY
• Unstructured P2P network
• 33/WAKU2-DISCV5
• WAKU2-ENR
• 23/WAKU2-TOPICS
• Ethereum ENR sharding bit vector
• Ethereum discv5 specification
• Research log: Waku Discovery
• WAKU2-RELAY-STATIC-SHARD-ALLOC
• 14/WAKU2-MESSAGE
• 64/WAKU2-NETWORK

WAKU-LIGHTPUSH

Timeline

• 2026-06-16 — 16e8af1 — Chore/separate messaging specs (#361)
• 2026-05-11 — 1ac7689 — chore: split ift ts specs (#334)
• 2026-05-07 — 48600b5 — Migrate logos-messaging/specs into docs/messaging/ (#315)

previous version: /vac/waku/lightpush/2.0.0-beta1 19/WAKU2-LIGHTPUSH

Protocol identifier: /vac/waku/lightpush/3.0.0

Motivation and Goals

Light nodes with short connection windows and limited bandwidth wish to push messages to other nodes in the Waku network to request message services.
A common use case is to request that the service node publish the message to an 11/WAKU2-RELAY pubsub-topic. Additionally, there is sometimes a need for confirmation that a message has been received "by the network" (here, at least one node).

WAKU-LIGHTPUSH is a request/response protocol for this.

Payloads

syntax = "proto3";

message LightPushRequest {
    string request_id = 1;
    // 10 Reserved for future `request_type`. Currently, RELAY is the only available service.
    optional string pubsub_topic = 20;
    WakuMessage message = 21;
}

message LightPushResponse {
    string request_id = 1;
    uint32 status_code = 10; // has value 200 in case of success, see appendix
    optional string status_desc = 11;
    optional uint32 relay_peer_count = 12; // number of peers, the message is successfully relayed to 
}

Message Relaying

Nodes that respond to LightPushRequest SHOULD

• either relay the encapsulated message via 11/WAKU2-RELAY protocol on the specified pubsub_topic
  
• or perform another requested service. Services beyond [11/WAKU2-RELAY](https://github.com/logos-co/logos-lips/blob/master/docs/messaging/core/stable/11/relay.md) are yet to be defined.

Depending on the network configuration, the lightpush client may not need to provide pubsub_topic (WAKU2-RELAY-SHARDING).

If the node is unable to perform the request for some reason, it SHOULD return an error code in LightPushResponse.

Once the relay is successful, the relay_peer_count will indicate the number of peers that the node has managed to relay the message to. It's important to note that this number may vary depending on the node subscriptions and support for the requested pubsub_topic. The client can use this information to either consider the relay as successful or take further action, such as switching to a lightpush service peer with better connectivity.

The field relay_peer_count may not be present or has the value zero in case of error or in other future use cases, where no relay is involved.

Examples of possible error codes

The list of error codes is not complete and can be extended in the future.

Security Considerations

Since this can introduce an amplification factor, it is RECOMMENDED for the node relaying to the rest of the network to take extra precautions. Therefore Waku applies or will apply:

• DOS protection through request rate limitation on the service itself.
• message rate limiting via 17/WAKU2-RLN-RELAY, applied via network membership subscription.

These features are under development.

Future work

• Add support attaching RLN proof for the message requested to be relayed.
• Add support for other request types.
• Incentivization of the service

Copyright

Copyright and related rights waived via CC0.

References

• 11/WAKU2-RELAY
• 17/WAKU2-RLN-RELAY

WAKU-MIX

Timeline

• 2026-06-16 — 16e8af1 — Chore/separate messaging specs (#361)
• 2026-05-11 — 1ac7689 — chore: split ift ts specs (#334)
• 2026-05-07 — 48600b5 — Migrate logos-messaging/specs into docs/messaging/ (#315)

Tags

waku/core-protocol

Abstract

The document describes libp2p mix integration into waku. This integration provides higher anonymity for users publishing or querying for messages to/from the Waku network.

This document covers integration of mix with lightpush and store protocols. Both of these are request-response based protocols that follow a service-user and a service-provider model. A node that initiates the request is a service-user/client whereas a node that replies to the request is the service-provider/service-node.

This document also covers the aspect of relay nodes acting as mix nodes.

Background / Rationale / Motivation

Waku protocols have weak sender/originator anonymity as explained in Waku Privacy and Anonymity Analysis. Without further anonymization, it is easy to analyze the network traffic and determine the originator of messages published into the network. Topic interests of a user can be identified by analyzing Store query messages sent by a user. Same applies for topic subscriptions via Filter protocol.

Mix protocol allows libp2p nodes to send messages without revealing the sender's identity (peer ID, IP address) to intermediary mix nodes or the recipient/destination. Anonymity is achieved by using the Sphinx packet format, which encrypts and routes messages through a series of mix nodes before reaching the recipient.

By integrating the mix protocol into the waku network, we can improve the anonymity for publishers and store query users. Each waku relay node SHOULD be acting as a mix node that forms an overlay mix network. This network of mix nodes SHALL relay mix messages anonymously to the recepient.

Anonymity of Filter users is not addressed by this document.

Terminology

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC2119.

Theory / Semantics

Waku Mix creates an overlay network of all the Waku nodes that support the mix protocol.

Nodes with mix protocol mounted SHOULD advertise that they support mix protocol via their their chosen discovery method. They MAY do so by updating their ENR and using one of the ENR based discovery methods.

Nodes that want higher anonymity while publishing a message via lightpush or performing a store query SHOULD use the mix protocol to route their messages to the destination. Sender Node that would like to use mix protocol SHOULD discover enough mix nodes so that there is always a healthy pool of mix nodes available for selection. The pool size of mix nodes SHOULD be large enough for the mixing to be effective. We RECOMMEND a pool size of at least 100 mix nodes for the mixing to be effective.

The serialized Waku Message MUST be the payload in the sphinx packet.

To allow acknowledgments from the service-node while preserving sender anonymity, Single Use Reply Blocks or anonymous replies as specified in the original sphinx paper SHALL be used.

A node that sends messages using mix MAY use two redundant paths to have better reliability of the message being delivered. It is up to the higher-layer mixed protocol to deduplicate redundant messages received in this way.

Node Roles

Mix protocol defines 3 roles for the nodes in the mix network - sender, exit, intermediary.

• An sender node is the originator node of a message, i.e a node that wishes to publish/query messages to/from the waku network.
• An exit node is responsible for delivering messages to destination peer in the network.
• An intermediary node is responsible for forwarding a mix packet to the next mix node in the path.

A Waku relay node SHOULD by default have mix intermediary and exit node roles in the network. The implementation MAY provide a configuration to disable a node from acting as an intermediary\exit node.

Any waku node that wishes to publish/query messages via mix from the waku network MUST act as a sender node.

Resource-restricted/Edge nodes with short connection windows MUST only act as sender nodes and cannot function as intermediaries or exit nodes.

ENR updates

Each waku node that supports the mix intermediary or exit role SHOULD indicate the same in its discoverable ENR. The following fields MUST be set as part of the discoverable ENR of a mix waku node:

• The bit 5 in the waku2 ENR key is reserved to indicate mix support. This bit MUST be set to true to indicate mix support.
• A new field mix-key SHOULD be set to the ed25519 public key which is used for sphinx encryption.

Adding these fields to the ENR may cause the ENR size to cross the 300 byte limit especially in case a node supports multiple transports. This limitation will have to be addressed in future.

Discovery

Mix protocol provides better anonymity when a sender node has a sufficiently large pool of mix nodes to do path selection. This moves the problem into discovery domain and requires the following from discovery mechanisms:

1. It is important for nodes to be able to discover as many nodes as possible quickly. This becomes especially important for edge nodes that come online just to publish/query messages for a short period of time.
2. The discovery mechanism MUST be unbiased and not biased toward specific subsets (e.g., nodes that are topologically closer).
3. It is important to have the most recent online status of the nodes so that mix paths that are selected are not broken which lead to reliability issues.

Point-3 above can be mitigated partially by choosing redundant mix paths for the same message by the sender node. This may not be an effective solution as it increases the overall bandwidth usage.

Spam Protection

Mix protocol in waku network SHOULD have rate-limiting/spam protection to handle scenarios such as below:

1. Any node can generate a mix packet and publish into the mix network. Hence there needs to be some validation as to who is allowed to publish and whether the user is within allowed rate-limits.
2. Any node can intentionally generate paths which are broken and send messages into the mix network.
3. An attacker can spawn a huge number of mix nodes so that user behaviour is observed in order to determine traffic patterns and deanonymize users.

There is a need to enforce rate-limits and spam protect the mix network. The rate-limiting and spam protection shall be addressed as part of future work.

Tradeoffs

Using mix protocol for publishing and querying messages adds certain overhead which is primarily the delay in delivering message to the destination. The overall additional delay D depends on the following params:

• path length L
• delay added by each intermediary node dm
• connection establishment time dc
• processing delay dp

Delay overhead can be calculated as D = L * (dm + dc +dp)

Future Work

• Integration of waku relay with mix.
• Spam protection of mix overlay network.
• Alternative way to communicate mix-public-key in order to overcome ENR size limitations.

Copyright

Copyright and related rights waived via CC0.

References

• libp2p mix
• waku lightpush
• waku relay
• ENR
• sphinx encryption

WAKU-RENDEZVOUS

Timeline

• 2026-06-16 — 16e8af1 — Chore/separate messaging specs (#361)
• 2026-05-11 — 1ac7689 — chore: split ift ts specs (#334)
• 2026-05-07 — 48600b5 — Migrate logos-messaging/specs into docs/messaging/ (#315)

Abstract

This document describes the goal, strategy, usage, and changes to the libp2p rendezvous protocol by Waku.

Rendezvous is one of the discovery methods that can be used by Waku. It supplements Discovery v5 and Waku peer exchange.

Background and Rationale

Waku needs discovery mechanism(s) that are both rapid and robust against attacks. Fully centralised discovery (such as DNS lookup) may be fast but is not secure. Fully decentralised discovery (such as discv5) may be robust, but too slow for some bootstrapping use cases Rendezvous provides a limited, balanced solution that trades off some robustness for speed. It's meant to complement not replaced fully decentralised discovery mechanisms, like discv5

By combining rendezvous with Discv5 and 34/WAKU2-PEER-EXCHANGE, Waku nodes can more quickly reach a meaningful set of peers than by relying on a single discovery method.

Semantics

Waku rendezvous extends the libp2p rendezvous semantics by using WakuPeerRecord instead of the standard libp2p PeerRecord. This allows nodes to advertise additional Waku-specific metadata beyond what is available in the standard libp2p peer record.

Specifications

Libp2p Protocol identifier: /vac/waku/rendezvous/1.0.0

Wire Protocol

Nodes advertise their information through WakuPeerRecord, a custom peer record structure designed for Waku rendezvous. Since this is a customPeerRecord, we define a private multicodec value of 0x300000 as per multicodec table. The WakuPeerRecord is defined as follows:

WakuPeerRecord fields:

• peer_id: The libp2p PeerId of the node.
• seqNo: The time at which the record was created or last updated (Unix epoch, seconds).
• multiaddrs: A list of multiaddresses for connectivity.
• mix_public_key: The Mix protocol public key (only present for nodes supporting Mix).

Encoding: WakuPeerRecord is encoded as a protobuf message. The exact schema is:

message WakuPeerRecord {
  string peer_id = 1;
  uint64 seqNo = 2;
  repeated string multiaddrs = 3;
  optional bytes mix_public_key = 4;
}

When a node discovers peers through rendezvous, it receives the complete WakuPeerRecord for each peer, allowing it to make informed decisions about which peers to connect to based on their advertised information.

Namespace Format

The rendezvous namespaces used to register and request peer records MUST be in the format rs/<cluster-id>/<capability>. <capability> is a string representing the individual capability for which a discoverable Waku peer record is registered. The Waku peer record is separately registered against each capability for which discovery is desired. The only defined capability for now is mix, representing Waku Mix support. For example, a Waku peer record for a node supporting mix protocol in cluster 1 will be registered against a namespace: rs/1/mix.

This allows for discovering peers with specific capabilities within a given cluster. Currently, this is used for Mix protocol discovery where the capability field specifies mix.

Refer to RELAY-SHARDING for cluster information.

Registration and Discovery

Every Waku Relay node SHOULD be initialized as a rendezvous point.

Each relay node that participates in discovery MUST register with random rendezvous points at regular intervals. The RECOMMENDED registration interval is 10 seconds.

All relay nodes participating in rendezvous discovery SHOULD advertise their information using WakuPeerRecord. For nodes supporting the Mix protocol, the mix_public_key field MUST be included. All advertised records MUST conform to the WakuPeerRecord definition.

It is RECOMMENDED that rendezvous points expire registrations after 1 minute (60 seconds TTL) to keep discovered peer records limited to those recently online.

At startup, every Waku node supporting Mix SHOULD discover peers by sending requests to random rendezvous points for the Mix capability namespace.

It is RECOMMENDED a maximum of 12 peers be requested each time. This number is sufficient for good GossipSub connectivity and minimizes the load on rendezvous points.

Operational Recommendations

It is RECOMMENDED that bootstrap nodes participate in rendezvous discovery and that other discovery methods are used in conjunction and continue discovering peers for the lifetime of the local node.

For resource-constrained devices or light clients, a client-only mode MAY be used where nodes only query for peers without acting as rendezvous points themselves and without advertising their own peer records.

Future Work

The protocol currently supports advertising Mix-specific capabilities (Mix public keys) through WakuPeerRecord. Future enhancements could include:

• Extending WakuPeerRecord to advertise other Waku protocol capabilities (Relay, Store, Filter, Lightpush, etc.)
• Supporting shard-based namespaces (e.g., rs/<cluster-id>/<shard>) for general relay peer discovery without capability filtering
• Batch registration support allowing nodes to register across multiple namespaces in a single request

Copyright

Copyright and related rights waived via CC0.

References

• Discv5
• ENR
• 34/WAKU2-PEER-EXCHANGE
• Libp2p Rendezvous
• Relay

WAKU-STORE-SYNC

Timeline

• 2026-06-16 — 16e8af1 — Chore/separate messaging specs (#361)
• 2026-05-11 — 1ac7689 — chore: split ift ts specs (#334)
• 2026-05-07 — 48600b5 — Migrate logos-messaging/specs into docs/messaging/ (#315)

Abstract

This document describes a strategy to keep 13/WAKU2-STORE nodes synchronised, using a combination of 13/WAKU2-STORE queries and the WAKU-SYNC protocol.

Background / Rationale / Motivation

Message propagation in 10/WAKU2 networks is not perfect. Even with peer-to-peer reliability mechanisms, a certain amount of routing losses are always expected between Waku nodes. For example, nodes could experience brief, undetected disconnections, undergo restarts in order to update software, or suffer losses due to resource constraints.

Whatever the source of the losses, this affects applications and services relying on the message routing layer. One such service is the 13/WAKU2-STORE protocol that allows nodes to cache historical 14/WAKU2-MESSAGEs from the routing layer, and provision these to clients. Using Waku Store Sync, 13/WAKU2-STORE can remain synchronised and reach eventual consistency despite occasional losses on the routing layer.

Scope:

Waku Store Sync aims to provide a way for 13/WAKU2-STORE nodes to compare and retrieve differences with other 13/WAKU2-STORE nodes, in order to remedy messages that might have been missed or lost on the routing layer.

It seeks to cover the following loss scenarios:

1. Short-term offline periods, for example due to a restart or short-term node maintenance
2. Occasional message losses that occur during normal operation, due to short-term instability, churn, etc.

For the purposes of this document, we define short-term offline periods as no more than 1 hour and occasional message losses as no more than 20% of total routed messages.

It does not aim to address recovery after long-term offline periods, or to address massive message losses due to extraordinary circumstances, such as adversarial behaviour. Although Store Sync could perhaps work in such cases, it's not optimised or designed for catastrophic loss recovery. Large scale recovery falls beyond the scope of this document. We provide further recommendations for reasonable parameter defaults below.

Theory / Semantics

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

A 13/WAKU2-STORE node with Store Sync enabled:

1. MAY use Store Resume to recover messages after detectable short-term offline periods
2. MUST use Waku Sync to maintain consistency with other nodes and recover occasional message losses

Store Resume

Store Sync nodes MAY use Store Resume to fill the gap in messages for any short-term offline period. Such a node SHOULD keep track of its last online timestamp. It MAY do so by periodically storing the current timestamp on disk while online. After a detected offline period has been resolved, or at startup, a Store Sync node using Store Resume SHOULD select another 13/WAKU2-STORE node using any available discovery mechanism. We RECOMMEND that this to be a random node. Next, the Store Sync node SHOULD perform a 13/WAKU2-STORE query to the selected node for the time interval since it was last online. Messages returned by the query are then added to the local node storage. It is RECOMMENDED to limit the time interval to a maximum of 6 hours.

Waku Sync

Even while online, Store Sync nodes may occasionally miss messages. To remedy any such losses and to achieve eventual consistency, Store Sync nodes MUST mount WAKU2-SYNC protocol to detect and exchange differences with other Store Sync nodes. As described in that specification, WAKU2-SYNC consists of two sub-protocols. Both sub-protocols MUST be used by Store Sync nodes in the following way:

1. reconciliation MUST be used to detect and exchange differences between 14/WAKU2-MESSAGEs cached by the 13/WAKU2-STORE node
2. transfer MUST be used to transfer the actual content of such differences. Messages received via transfer MUST be cached in the same archive backend where the 13/WAKU2-STORE node caches messages received via normal routing.

Periodic syncing

Store Sync nodes SHOULD periodically trigger WAKU2-SYNC. We RECOMMEND syncing at least once every 5 minutes with 1 other Store Sync peer. The node MAY choose to sync more often with more peers to achieve faster consistency. Any peer selected for Store Sync SHOULD be chosen at random.

Discovery of other Store Sync peers falls outside the scope of this document. For simplicity, a Store Sync node MAY assume that any other 13/WAKU2-STORE peer supports Store Sync and attempt to trigger a sync operation with that node. If the sync operation then fails (due to unsupported protocol), it could continue attempting to sync with other 13/WAKU2-STORE peers on a trial-and-error basis until it finds a suitable Store Sync peer.

Sync window

For every WAKU2-SYNC operation, the Store Sync node SHOULD choose a reasonable window of time into the past over which to sync cached messages. We RECOMMEND a sync window of 1 hour into the past. This means that the syncing peers will compare and exchange differences in cached messages up to 1 hour into the past. A Store Sync node MAY choose to sync over a shorter time window to save resources and sync faster. A Store Sync node MAY choose to sync over a longer time window to remedy losses over a longer period.

Copyright

Copyright and related rights waived via CC0.

References

• 10/WAKU2
• 13/WAKU2-STORE
• 14/WAKU2-MESSAGE
• WAKU-P2P-RELIABILITY
• WAKU2-SYNC

WAKU-SYNC

Timeline

• 2026-06-16 — 16e8af1 — Chore/separate messaging specs (#361)
• 2026-05-11 — 1ac7689 — chore: split ift ts specs (#334)
• 2026-05-07 — 48600b5 — Migrate logos-messaging/specs into docs/messaging/ (#315)

Abstract

This specification explains WAKU-SYNC which enables the synchronization of messages between nodes storing sets of 14/WAKU2-MESSAGEs.

Specification

Waku Sync consists of two libp2p protocols: reconciliation and transfer. The Reconciliation protocol finds differences in sets of messages. The Transfer protocol is used to exchange the differences found with other peers. The end goal being that peers have the same set of messages.

Terminology

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC2119.

Reconciliation

Libp2p Protocol identifier: /vac/waku/reconciliation/1.0.0

The reconciliation protocol finds the differences between two sets of 14/WAKU2-MESSAGE on different nodes. It assumes that each 14/WAKU2-MESSAGE maps to a uniquely identifying SyncID, which is maintained in an ordered set within each node. An ordered set of SyncIDs is termed a Range. This implies that any contiguous subset of a Range is also a Range. In other words, the reconciliation protocol allows two nodes to find differences between Ranges of SyncIDs, which would map to an equivalent difference in cached 14/WAKU2-MESSAGEs. These terms, the wire protocol and message flows are explained below.

Wire protocol

Reconcilation payload

Nodes participating in the reconciliation protocol exchange encoded RangesData messages.

The RangesData structure represents a complete reconciliation payload:

The cluster and shards fields represent the sharding elements as defined in RELAY-SHARDING. The ranges field contain a sequence of ranges for reconciliation.

We identify the following subtypes:

Range

A Range represents a representation of the bounds, type and, optionally, an encoded representation of the content of a range.

RangeBounds

RangeBounds defines a Range by two bounding SyncID values, forming a time-hash interval:

The lower bound MUST be strictly smaller than the upper bound.

SyncID

A SyncID consists of a message timestamp and hash to uniquely identify a 14/WAKU2-MESSAGE.

The timestamp MUST be the time of message creation and the hash MUST follow the deterministic message hashing specification. SyncIDs MUST be totally ordered by timestamp first, then by hash to disambiguate messages with identical timestamps.

RangeType

A RangeType indicates the type of content encoding for the Range:

Fingerprint

A Fingerprint is a compact 32-byte representation of all message hashes within a Range. It MUST be implemented as an XOR of all contained hashes, extracted from the SyncIDs present in the Range. Fingerprints allow for efficient difference detection without transmitting complete message sets.

ItemSet

An ItemSet contains a full representation of all SyncIDs within a Range and a reconciliation status:

Payload encoding

We can now define a heuristic for encoding the RangesData payload. All varints MUST be encoded according to the specified varint encoding procedure.

Concatenate each of the following, in order:

1. Encode the cluster ID as a varint
2. Encode the number of shards as a varint
3. For each shard, encode the shard as a varint and concatenate it to the previous
4. Encode the ranges, according to "Delta encoding for Ranges".

Varint encoding

All variable integers (varints) MUST be encoded as little-endian base 128 variable-length integers (LEB128) and MUST be minimally encoded.

Delta encoding for Ranges

The ranges field contain a sequence of Ranges.

It can be delta encoded as follows:

For each Range element, concatenate the following:

1. From the RangeBounds, select only the SyncID representing the upper bound of that range. Inclusive lower bounds are omitted because they are always the same as the exclusive upper bounds of the previous range. The first range is always assumed to have a lower bound SyncID of 0 (both the timestamp and hash are 0).
2. Delta encode the selected SyncID by comparing it to the previous ranges' SyncIDs. The first range's SyncID will be fully encoded, as described in that section.
3. Encode the RangeType as a single byte and concatenate it to the delta encoded SyncID.
4. If the RangeType is:
   • Skip: encode nothing more
   • Fingerprint: encode the 32-byte fingerprint
   • ItemSet:
     • Encode the number of elements as a varint
     • Delta encode the item set, according to "Delta encoding for ItemSets"

Delta encoding for sequential SyncIDs

Sequential SyncIDs can be delta encoded to minimize payload size.

Given an ordered sequence of SyncIDs:

1. Encode the first timestamp in full
2. Delta encode subsequent timestamps, i.e., encode only the difference from the previous timestamp
3. If the timestamps are identical, encode a SyncID hash delta as follows: 3.1. Compared to the previous hash, truncate the hash up to and including the first differentiating byte 3.2. Encode the number of bytes in the truncated hash (as a single byte) 3.3. Encode the truncated hash

See the table below as an example:

Delta encoding for ItemSets

An ItemSet is delta encoded as follows:

Concatenate each of the following, in order:

1. From the first SyncID, encode the timestamp in full
2. From the first SyncID, encode the hash in full
3. For each subsequent SyncID:
   • Delta encode the timestamp, i.e., encode only the difference from the previous SyncID's timestamp
   • Append the encoded hash in full
4. Encode a single byte for the reconciled boolean (0 or 1)

Reconciliation Message Flow

The reconciliation message flow is triggered by an initiator with an initial RangesData payload. The selection of sync peers and triggers for initiating a reconciliation is out of scope of this document.

The response to a RangesData payload is another RangesData payload, according to the heuristic below. The syncing peers SHOULD continue exchanging RangesData payloads until all ranges have been processed.

The output of a reconciliation flow is a set of differences in SyncIDs. These could either be SyncIDs present in the remote peer and missing locally, or SyncIDs present locally but missing in the remote peer. Each sync peer MAY use the transfer protocol to exchange the full messages corresponding to these computed differences, proactively transferring messages missing in the remote peer.

Initial Message

The initiator

1. Selects a time range to sync
2. Computes a fingerprint for the entire range
3. Constructs an initial RangesData payload with:
   • The initiator's cluster ID
   • The initiator's supported shards
   • A single range of type Fingerprint covering the entire sync period
   • The fingerprint for this range
4. Delta encodes the payload
5. Sends the payload using libp2p length-prefixed encoding

Responding to a RangesData payload

Each syncing peer performs the following in response to a RangesData payload:

The responder:

1. Receives and decodes the payload
2. If shards and cluster match, processes each range:
   • If the received range is of type Skip, ignores it.
   • If the received range is of type Fingerprint, computes the fingerprint over the local matching range
     • If the local fingerprint matches the received fingerprint, includes this range in the response as type Skip
     • If the local fingerprint does not match the received fingerprint:
       • If the corresponding range is small enough, includes this range in the response as type ItemSet with all SyncIDs
       • If the corresponding range is too large, divide it into subranges. For each subrange, if the range is small enough, includes it in the response as type ItemSet with all SyncIDs. If the subrange is too large, includes it in the response as type Fingerprint.
   • If the received range is of type ItemSet, compares it to the local items in the corresponding range
     • If there are any differences between the local and remote items, adds these as part of the output of the reconciliation procedure. At this point, the syncing peers MAY start to exchange the full messages corresponding to differences using the transfer protocol.
     • If the received ItemSet is not marked as reconciled by the remote peer, includes the corresponding local range in the response as type ItemSet.
     • If the received ItemSet is marked as reconciled by the remote peer, includes the corresponding local range in the response as type Skip.
3. If shards or cluster don't match:
   • Responds with an empty payload
4. Delta encodes the response
5. Sends the response using libp2p length-prefixed encoding

This process continues until the syncing peer crafts an empty response, i.e., when all ranges have been processed and reconciled by both syncing peers and there are no differences left.

Transfer Protocol

Libp2p Protocol identifier: /vac/waku/transfer/1.0.0

Once the reconciliation protocol starts finding differences in SyncIDs, the transfer protocol MAY be used to exchange actual message contents between peers. A node using transfer SHOULD proactively send 14/WAKU2-MESSAGEs missing in the remote party. Nodes SHOULD only accept incoming transfers from peers for which they have an active reconciliation session. The SyncIDs corresponding to messages received via transfer, MUST be added to the corresponding Range tracked by the reconciliation protocol. The transferpayload MUST follow the wire specification below.

Wire specification

syntax = "proto3";

package waku.sync.transfer.v1;

import "waku/message/v1/message.proto";

message WakuMessageAndTopic {
  // Full message content and associated pubsub_topic as value
  optional waku.message.v1.WakuMessage message = 1;
  optional string pubsub_topic = 2;
}

Implementation Suggestions

The flexibility of the protocol implies that much is left to the implementers. What will follow is NOT part of the specification. This section was created to inform implementations.

Cluster & Shards

To prevent nodes from synchronizing messages from shard they don't support, cluster and shards information has been added to each payload. On reception, if two peers don't share the same set of shards the sync is aborted.

Parameters

Two useful parameters to add to your implementation are partitioning count and the item set threshold.

The partitioning count is the number of time a range is split. A higher value reduces round trips at the cost of computing more fingerprints.

The item set threshold determines when item sets are sent instead of fingerprints. A higher value sends more items which means higher chance of duplicates but reduces the amount of round trips overall.

Storage

The storage implementation should reflect the context. Most messages that will be added will be recent and removed messages will be older ones. When differences are found some messages will have to be inserted randomly. It is expected to be a less likely case than time based insertion and removal. Last but not least it must be optimized for fingerprinting as it is the most often used operation.

Sync Interval

Ad-hoc syncing can be useful in some cases but continuous periodic sync minimize the differences in messages stored across the network. Syncing early and often is the best strategy. The default used in Nwaku is 5 minutes interval between sync with a range of 1 hour.

Sync Window

By default we offset the sync window by 20 seconds in the past. The actual start of the sync range is T-01:00:20 and the end T-00:00:20 in most cases. This is to handle the inherent jitters of GossipSub. In other words, it is the amount of time needed to confirm if a message is missing or not.

Peer Choice

Wrong peering strategies can lead to inadvertently segregating peers and reduce sampling diversity. Nwaku randomly select peers to sync with for simplicity and robustness.

More sophisticated strategies may be implemented in future.

Security/Privacy Considerations

Nodes using WAKU-SYNC are fully trusted. Message hashes are assumed to be of valid messages received via Waku Relay or Light push.

Further refinements to the protocol are planned to reduce the trust level required to operate. Notably by verifying messages RLN proof at reception.

Copyright

Copyright and related rights waived via CC0.

References

• RBSR
• Negentropy Explainer
• Master Thesis

WAKU2-INCENTIVIZATION

Timeline

• 2026-06-16 — 16e8af1 — Chore/separate messaging specs (#361)
• 2026-06-12 — 124f895 — chore: fix broken links (#357)
• 2026-05-11 — 1ac7689 — chore: split ift ts specs (#334)
• 2026-05-07 — 48600b5 — Migrate logos-messaging/specs into docs/messaging/ (#315)

Abstract

This document describes an approach to incentivization of Waku request-response protocols. Incentivization is necessary for economically sustainable growth of Waku. In an incentivized request-response protocol, only eligible (e.g., paying) clients receive the service. Clients include eligibility proofs in their requests.

Eligibility proofs are designed to be used in multiple Waku protocols, such as Store, Lightpush, and Filter. Lightpush is planned to become the first Waku protocol with an incentivization component. In particular, a Lightpush client will be able to publish messages without their own RLN membership. Instead, the client would pay the server for publishing the client's message using the server's RLN proof. We will discuss a proof-of-concept implementation of this incentivization component in a later section.

Background / Rationale / Motivation

Decentralized protocols require incentivization to be economically sustainable. While some aspects of a P2P network can successfully operate in a tit-for-tat model, we believe that nodes that run the protocol in good faith need to be tangibly rewarded. Motivating servers to expand resources on handling clients' requests allows us to scale the network beyond its initial altruism-based phase.

Incentivization is not necessarily limited to monetary rewards. Reputation may also play a role. For Waku request-response (i.e., client-server) protocols, we envision a combination of monetary and reputation-based incentivization. See a write-up on incentivization for our high-level reasoning on the topic.

Theory / Semantics

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

Consider a request-response protocol with two roles: a client and a server. A server MAY indicate to a client that it expects certain eligibility criteria to be met. In that case, a client MUST provide a valid eligibility proof as part of its request.

Forms of eligibility proofs include:

• Proof of payment: for paid non-authenticated requests. A proof of payment, in turn, may also take different forms, such as a transaction hash or a ZK-proof. In order to interpret a proof of payment, the server needs information about its type.
• Proof of membership: for services for a predefined group of users. An example use case: an application developer pays in bulk for their users' requests. A client then prove that they belong to the user set of that application. Rate limiting in Waku RLN Relay is based on a similar concept.
• Service credential: a proof of membership in a set of clients who have prepaid for the service (which may be considered a special case of proof of membership).

Upon a receiving a request:

• the server SHOULD check if the eligibility proof is included and valid;
• if that proof is absent or invalid, the server SHOULD send back a response with a corresponding error code and an error description;
• if the proof is valid, the server SHOULD send back the response that the client has requested.

Note that the protocol does not ensure atomicity. It is technically possible for a server to fail to respond to an eligible request (in violation of the protocol). Addressing this issue is left for future work.

Wire Format Specification / Syntax

A client includes an EligibilityProof in its request. A server includes an EligibilityStatus in its response.

syntax = "proto3";

message EligibilityProof {
  optional bytes proof_of_payment = 1;  // e.g., a txid
  // may be extended with other eligibility proof types, such as:
  //optional bytes proof_of_membership = 2;  // e.g., an RLN proof
}

message EligibilityStatus {
  optional uint32 status_code = 1;
  optional string status_desc = 2;
}

We include the other_eligibility_proof field in EligibilityProof to reflect other types of eligibility proofs that could be added to the protocol later.

Implementation in Lightpush (PoC version)

This Section describes a proof-of-concept (PoC) implementation of incentivization in the Lightpush protocol. Note: this section may later be moved to Lightpush RFC.

Lightpush is one of Waku's request-response protocols. A Lightpush client sends a request to the server containing the message to be published to the Waku network on the client's behalf. A Lightpush server responds to indicate whether the client's message was successfully published. See 19/WAKU2-LIGHTPUSH for the definitions of PushRequest and PushResponse.

The PoC Lightpush incentivization makes the following simplifying assumptions:

• the client knows the server's on-chain address A (likely on an L2 network);
• the client and the server have agreed on a constant price p per published message.

To publish a message, the client:

1. pays p to the server's address A with an on-chain transaction;
2. waits until the transaction is confirmed with identifier txid;
3. includes txid in the request as a proof of payment.

It is the server's responsibility to keep track of the txids from prior requests and to make sure they are not reused.

Note that txid may not always be practical as proof of payment due to on-chain confirmation latency. To address this issue, future versions of the protocol may involve bulk payments, that is, paying for multiple requests in one transaction. In that scheme, after a bulk payment is made, the client will not have to face on-chain latency for each new prepaid request.

Wire Format Specifications for Lightpush PoC incentivization

Request

We extend PushRequest to include an eligibility proof:

message PushRequest {
  string pubsub_topic = 1;
  WakuMessage message = 2;
  // numbering gap left for non-eligibility-related protocol extensions
  + optional bytes eligibility_proof = 10;
}

An example of usage with txid as a proof of payment:

PushRequest push_request {
  pubsub_topic: "example_pubsub_topic"
  message: "example_message"
  eligibility_proof: {
    proof_of_payment: 0xabc123  // txid for the client's payment
    // eligibility proofs of other types are not included
  };
}

Response

We extend the PushResponse to indicate the eligibility status:

message PushResponse {  
    bool is_success = 1;
    // Error messages, etc
    string info = 2;
  + EligibilityStatus eligibility_status = 3;
}

Example of a response if the client is eligible:

PushResponse response_example {
  is_success: true
  info: "Request successful"
  eligibility_status: {
    status_code: 200
    status_desc: "OK"
    }
  }

Example of a response if the client is not eligible:

PushResponse response_example {
  is_success: false
  info: "Request failed"
  eligibility_status: {
    status_code: 402
    status_desc: "PAYMENT_REQUIRED"
  }
}

Security/Privacy Considerations

Eligibility proofs may reveal private information about the client. In particular, a transaction identifier used as a proof of payment links the client's query to their on-chain activity. Potential countermeasures may include using one-time addresses or ZK-based privacy-preserving protocols.

Limitations and Future Work

This document is intentionally simplified in its initial version. It assumes a shared understanding of prices and the blockchain addresses of servers. Additionally, the feasibility of paying for each query is hindered by on-chain fees and confirmation delays.

We will address these challenges as the specification evolves alongside the corresponding PoC implementation. The following ideas will be explored:

• Batch Payment: instead of paying for an individual query, the client would make a consolidated payment for multiple messages.
• Price Negotiation: rather than receiving prices off-band, the client would engage in negotiation with the server to determine costs.
• Dynamic Pricing: the price per message would be variable, based on the total size (in bytes) of all received messages.
• Subscriptions: the client would pay for a defined time period during which they can query any number of messages, subject to DoS protection.

Copyright

Copyright and related rights waived via CC0.

References

normative

• A high-level incentivization outline
• 19/WAKU2-LIGHTPUSH (for Lightpush-specific sections)

informative

RFCs of request-response protocols:

• 12/WAKU2-FILTER
• 13/WAKU2-STORE
• 19/WAKU2-LIGHTPUSH

RFCs of Relay and RLN-Relay:

• 11/WAKU2-RELAY
• 17/WAKU2-RLN-RELAY

WAKU2-RLN-CONTRACT

Timeline

• 2026-06-16 — 16e8af1 — Chore/separate messaging specs (#361)
• 2026-06-12 — 124f895 — chore: fix broken links (#357)
• 2026-05-11 — 1ac7689 — chore: split ift ts specs (#334)
• 2026-05-07 — 48600b5 — Migrate logos-messaging/specs into docs/messaging/ (#315)

Abstract

This document describes membership management within the Rate-Limiting Nullifer (RLN) smart contract, specifically addressing:

• membership-related contract functionality;
• suggested parameter values for the initial mainnet deployment;
• contract governance and upgradability.

Background

Rate-Limiting Nullifier (RLN) is a Zero-Knowledge (ZK) based gadget used for privacy-preserving rate limiting in Waku. The RLN smart contract (referred to as "the contract" hereinafter) is the central component of the RLN architecture. The contract stores the membership set, which contains all current memberships. Users interact with the contract to manage their memberships and obtain the necessary data for proof generation and verification.

Message transmission is handled by Waku RLN Relay nodes. RLN Relay nodes verify the validity of messages according to RLN requirements and do not relay invalid messages. For the full specification of RLN Relay, see 17/WAKU2-RLN-RELAY.

Currently, this document focuses solely on membership-related functionality. It might later evolve into a comprehensive contract specification. As of August 2024, RLN is deployed only on Sepolia testnet (source code). This document aims to outline the path to its mainnet deployment.

Contract overview

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

The contract MUST provide the following membership-related functionalities (hereinafter, functionalities):

• register a membership;
• extend a membership;
• erase a membership;
• withdraw a deposit.

A membership holder is a role that grants special privileges in the context of membership management. Each membership MUST have exactly one holder. The holder role MUST be assigned at membership registration time to the sender (msg.sender in Solidity semantics) of the registration transaction. The sender of the registration SHOULD have an RLN identity_commitment created. For more information on identity_commitment creation, see 32/RLN-V1.

Membership registration MAY be initiated by a different entity from the one that controls the RLN identity_secret, which is associated with the respective RLN identity_commitment. Therefore, the holder role MAY be assigned to a blockchain address that is not derived from the identity_secret. The contract SHOULD verify that the identity_commitment is valid. If the identity_commitment is not checked or validated, the contract MAY be exploited using malicious or malformed inputs. When authorizing membership-related requests, the contract MUST distinguish between the holder and non-holders, and MAY also implement additional criteria.

The contract MUST support transactions sent directly from externally-owned accounts (EOA). The contract MAY support transactions sent via a chain of contract calls, in which case the last contract in the call chain MAY be designated as the membership holder. The contract MAY also support meta-transactions sent via paymasters or relayers, which MAY require additional authentication-related logic.

Contract parameters and their RECOMMENDED values for the initial mainnet deployment are as follows:

The pricing function SHOULD be linear in the rate limit per epoch.

Note: epoch length means the same as period as defined in 17/WAKU2-RLN-RELAY. This specification uses the term "epoch length" instead of "period" to avoid confusion with "grace period".

Membership lifecycle

Any existing membership MUST always be in exactly one of the following states:

• Active;
• GracePeriod;
• Expired;
• ErasedAwaitsWithdrawal;
• Erased.

The duration of each state MUST include the start timestamp. The duration of each state MUST exclude the end timestamp. For example, if a membership is registered at time 0, and the active state duration A = 5, the membership is considered to be Active at timestamps 0, 1, 2, 3, and 4. At timestamp 5, the membership is considered to be in GracePeriod.

graph TD;
    NonExistent --> |"register"| Active;
    Active -.-> |"time A passed"| GracePeriod;
    GracePeriod ==> |"extend"| Active;
    GracePeriod -.-> |"time G passed"| Expired;
    GracePeriod ==> |"erase"| ErasedAwaitsWithdrawal;
    Expired --> |"erase"| ErasedAwaitsWithdrawal;
    Expired --> |"reused by a new membership"| ErasedAwaitsWithdrawal;
    ErasedAwaitsWithdrawal ==> |"withdraw"| Erased;

Different line types denote the types of state transitions:

Transaction-triggered state transitions MUST be applied immediately.

When handling a membership-specific transaction, the contract MUST:

• check whether the state of the involved membership is up-to-date;
• if necessary, update the membership state;
• process the transaction in accordance with the updated membership state.

Memberships MUST be included in the membership set according to the following table:

The holder role MUST NOT be transferable to a different blockchain address. A user MAY use one blockchain address to manage multiple memberships. A user MAY use one Waku node¹ to manage multiple memberships.

Contract functionalities

Availability of functionalities[^2] MUST be as follows:

[^2] Note: Sending a message is not present in this table because it is part of the RLN Relay protocol and not the contract. For completeness, we note that the membership holder MUST be able to send a message if their membership is Active, in GracePeriod, or Expired. Sending messages with Expired memberships is allowed, because the inclusion (Merkle) proof that the holder provides to RLN Relay only proves that the membership belongs to the membership set, and not that membership's state.

Register a membership

Membership registration is subject to the following requirements:

• The holder MUST specify the requested rate limit r of a new membership at registration time².
• Registration MUST fail if r < r_{min} or r > r_{max}.
• To register a membership, the holder MUST make a tranasction that locks up a deposit in the contract.
• The amount of the deposit MUST depend on the specified rate limit.
• In case of a successful registration:
  • the new membership MUST become Active;
  • the new membership MUST have an active state duration A > 0 and a grace period duration G >= 0;
  • the current total rate limit MUST be incremented by the rate limit of the new membership.

Reusing the rate limit of Expired memberships

The rate limits are defined as follows:

• R_{active} is the total rate limit of all Active memberships;
• R_{grace_period} is the total rate limit of all GracePeriod memberships;
• R_{expired} is the total rate limit of all Expired memberships.

The free rate limit that is available without reusing the rate limit of Expired memberships is defined as follows:

R_{free} = R_{max} - R_{active} - R_{grace_period} - R_{expired}

Membership registration is additionally subject to the following requirements:

• If r <= R_{free}, the new membership MUST be registered (assuming all other necessary conditions hold).
  • The new membership MAY erase one or multiple Expired memberships and reuse their rate limit.
• If r > R_{free}:
  • if r > R_{free} + R_{expired}, registration MUST fail;
  • if r <= R_{free} + R_{expired}, the new membership SHOULD be registered by reusing some Expired memberships.
• The sender of the registration transaction MAY specify a list of Expired memberships to be erased and their rate limit reused.
  • If any of the memberships in the list are not Expired, the registration MUST fail.
  • If the list is not provided, the contract MAY use any criteria to select Expired memberships to reuse (see Implementation Suggestions).
  • If the list is not provided, the registration MAY fail even if the membership set contains Expired membership that, if erased, would free up sufficient rate limit.
• If a new membership A erases an Expired membership B to reuse its rate limit:
  • membership B MUST become ErasedAwaitsWithdrawal;
  • the current total rate limit MUST be decremented by the rate limit of membership B;
  • the contract MUST take all necessary steps to ensure that the holder of membership B can withdraw their deposit later.

Extend a membership

Extending a membership is subject to the following conditions:

• The extension MUST fail if the membership is in any state other than GracePeriod.
• The membership holder MUST be able to extend their membership.
• Any user other than the membership holder MUST NOT be able to extend a membership.
• After an extension, the membership MUST become Active.
• After an extension, the membership MUST stay Active for time g + A, where g is the remaining time of the GracePeriod after the extension, and A is this membership's active state duration.
• The extended membership MUST retain its original parameters, including active state duration A and grace period duration G, even if the global default values of such parameters for new memberships have been changed.

Withdraw the deposit

Deposit withdrawal is subject to the following conditions:

• The membership holder MUST be able to withdraw their deposit.
• Any user other than the membership holder MUST NOT be able to withdraw its deposit.
• A deposit MUST be withdrawn in full.
• A withdrawal MUST fail if the membership is not in ErasedAwaitsWithdrawal.
• A membership MUST become Erased after withdrawal.

Governance and upgradability

At initial mainnet deployment, the contract MUST have an Owner. The Owner MUST be able to change the values of all contract parameters. The updated parameter values MUST apply to all new memberships. The parameters of existing memberships MUST NOT change if the Owner updates global parameters. The contract MAY restrict extensions for memberships created before the latest parameter update.

The Owner MUST be able to pause any of the functionalities (see definition above).

At some point, the Owner SHOULD renounce their privileges, and the contract becomes immutable. If further upgrades are necessary, a new contract SHOULD be deployed, and the membership set SHOULD be migrated.

Implementation Suggestions

Membership Set Implementation

The membership set MAY be implemented as a Merkle tree, such as an Incremental Merkle Tree (IMT).

Choosing Which Expired Memberships to Reuse

When registering a new membership, the contract needs to decide which Expired memberships, if any, to reuse. The criteria for this selection can vary depending on the implementation.

Key considerations include:

• To minimize gas costs, it's better to reuse a single high-rate membership rather than multiple low-rate ones.
• To encourage timely deposit withdrawals, it's better to reuse memberships that have been Expired for a long time.

Considerations for User-facing Applications

User-facing applications SHOULD suggest one or more rate limits (tiers) to simplify user selection among the following RECOMMENDED options:

• 20 messages per epoch as low-tier;
• 200 messages per epoch as mid-tier;
• 600 messages per epoch as high-tier.

User-facing applications SHOULD save membership expiration timestamps in a local keystore during registration, and notify the user when their membership is about to expire.

Q&A

Why can't I withdraw a deposit from an Active membership?

The rationale for this limitation is to prevent a usage pattern where users make deposits and withdrawals in quick succession.
Such a pattern could lead to network instability and should be carefully considered if deemed desirable.

Why can't I extend an Active membership?

Memberships can only be extended during GracePeriod. Extending an Active membership is not allowed. The rationale is to make possible parameter changes that the contract Owner might make (e.g., for security reasons) applicable to most memberships.

What if I don't extend my membership within its GracePeriod?

If the membership is not extended during its GracePeriod, it becomes Expired and can be erased at any time.
Users are expected to either extend their membership on time to avoid this risk, or erase them and withdraw their deposit.

Can I send messages when my membership is Expired?

An Expired membership allows sending messages for a certain period. The RLN proof that message senders provide to RLN Relay nodes does not prove the state of the membership, only its inclusion in the membership set.

Expired memberships are not immediately erased from the membership set. An Expired membership is erased in the following scenarios:

• the holder erases it to withdraw the deposit;
• a new membership erases it to free up rate limit during registration;
• a public function is called that erases Expired memberships from the given list.

Once in Erased or ErasedAwaitsWithdrawal state, the membership can no longer be used to send messages.

Will my deposit be slashed if I exceed the rate limit?

This specification does not include slashing. The deposit's current purpose is purely to protect the network from denial-of-service attacks through bandwidth capping.

Do I need an extra deposit to extend my membership?

Membership extension requires no additional deposit. The opportunity cost of locked-up capital and gas fees for extension transactions make extensions non-free, which is sufficient for the initial mainnet deployment.

Why this particular epoch length?

Epoch length is a global parameter defined in the contract. Rate limits are defined in terms of the maximum allowed messages per epoch.

There is a trade-off between short and long epochs. Longer epochs accommodate short-term usage peaks better, but they increase memory requirements for RLN Relay nodes. An epoch length of 10 minutes was chosen as a reasonable middle ground.

Each message contains a nullifier that proves its validity in terms of RLN. Each RLN Relay node must store a nullifier log for the current epoch in memory. A nullifier plus metadata is 128 bytes per message. With a 10-minute epoch, a high-tier user with a 1 message per second rate limit generates up to 600 * 128 / 1024 = 75 KiB of nullifier log data per epoch. This equates to, approximately:

• 73 MiB for 1000 users;
• 732 MiB for 10 thousand users.

Why is there a cap on the total rate limit?

Total network bandwidth is a limited resource. To avoid overstretching the network's capabilities for the initial mainnet deployment, we define a cap R_{max} on the total rate limit.

Why is there a minimum rate limit?

The minimum rate limit r_{min} prevents an attack where a large number of tiny memberships cause membership set bloat.

Why is there a maximum rate limit?

The maximum rate limit r_{max} prevents any single actor from consuming an excessive portion of the total available rate limit.

However, it is still possible for an attacker to register multiple Ethereum addresses, and occupy a significant portion of the total rate limit through several memberships.

Are there bulk discounts for high-rate memberships?

For the initial mainnet deployment, no bulk discounts are offered. Membership price is linearly proportional to its rate limit. We choose this pricing scheme for simplicity. Future work may explore alternative pricing schemes that balance efficiency with centralization risk.

Why only accept DAI?

When choosing a token to accept, we considered the following criteria:

• a stablecoin, as USD-denominated pricing is familiar for users and requires no oracle;
• popular with high liquidity;
• decentralized;
• reasonably good censorship-resistance.

Based on these criteria, we chose DAI for the initial mainnet deployment. Other tokens may be added in the future.

Security / Privacy Considerations

Issuing membership-specific transactions, such as membership extensions and deposit withdrawals, publicly associates a membership with an Ethereum address. However, this association does not compromise the privacy of the relayed messages, as the protocol does not require the sender to disclose their specific membership to RLN Relay nodes.

To generate an RLN proof, a message sender must obtain a proof that their membership belongs to the membership set. This proof can be requested directly from the contract. Requesting the proof through a third-party RPC provider could compromise the sender's privacy, as the provider might link the requester's Ethereum address, their RLN membership, and the corresponding API key.

Copyright

Copyright and related rights waived via CC0.

References

• Rate-Limiting Nullifier
• 11/WAKU2-RELAY
• 17/WAKU2-RLN-RELAY
• 32/RLN-V1

Core

Core messaging delivery draft specifications.

10/WAKU2

Timeline

• 2026-06-16 — 16e8af1 — Chore/separate messaging specs (#361)
• 2026-06-12 — 124f895 — chore: fix broken links (#357)
• 2026-05-11 — 1ac7689 — chore: split ift ts specs (#334)
• 2026-05-08 — c0ef3b9 — Cleanup: rewrite specs-repo links in pre-existing messaging specs (#316)
• 2026-04-20 — c3d15a9 — COSS overhaul: new statuses, CFR type, raw-spec leniency (#308)
• 2026-02-09 — afd94c8 — chore: add math support (#287)
• 2026-01-16 — f01d5b9 — chore: fix links (#260)
• 2026-01-16 — 89f2ea8 — Chore/mdbook updates (#258)
• 2025-12-22 — 0f1855e — Chore/fix headers (#239)
• 2025-12-22 — b1a5783 — Chore/mdbook updates (#237)
• 2025-12-18 — d03e699 — ci: add mdBook configuration (#233)
• 2025-04-15 — 34aa3f3 — Fix links 10/WAKU2 (#153)
• 2025-04-09 — cafa04f — 10/WAKU2: Update (#125)
• 2024-11-20 — ff87c84 — Update Waku Links (#104)
• 2024-09-13 — 3ab314d — Fix Files for Linting (#94)
• 2024-03-21 — 2eaa794 — Broken Links + Change Editors (#26)
• 2024-02-01 — 8e14d58 — Update waku2.md
• 2024-02-01 — 6cf68fd — Update waku2.md
• 2024-02-01 — 6734b16 — Update waku2.md
• 2024-01-31 — 356649a — Update and rename WAKU2.md to waku2.md
• 2024-01-27 — 550238c — Rename README.md to WAKU2.md
• 2024-01-27 — eef961b — remove rfs folder
• 2024-01-26 — d6651b7 — Update README.md
• 2024-01-25 — 6e98666 — Rename README.md to README.md
• 2024-01-25 — 9b740d8 — Rename waku/10/README.md to waku/specs/standards/core/10-WAKU2/README.md
• 2024-01-24 — 330c35b — Create README.md

Abstract

Waku is a family of modular peer-to-peer protocols for secure communication. The protocols are designed to be secure, privacy-preserving, censorship-resistant and being able to run in resource-restricted environments. At a high level, it implements Pub/Sub over libp2p and adds a set of capabilities to it. These capabilities are things such as: (i) retrieving historical messages for mostly-offline devices (ii) adaptive nodes, allowing for heterogeneous nodes to contribute to the network (iii) preserving bandwidth usage for resource-restriced devices

This makes Waku ideal for running a p2p protocol on mobile devices and other similar restricted environments.

Historically, it has its roots in 6/WAKU1, which stems from Whisper, originally part of the Ethereum stack. However, Waku acts more as a thin wrapper for Pub/Sub 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 (2020) for more historical context.

Motivation and Goals

Waku, as a family of protocols, is designed to have a set of properties that are useful for many applications:

1.Useful for generalized messaging.

Many applications require some form of messaging protocol to communicate between different subsystems or different nodes. This messaging can be human-to-human, machine-to-machine or a mix. Waku is designed to work for all these scenarios.

2.Peer-to-peer.

Applications sometimes have requirements that make them suitable for peer-to-peer solutions:

• Censorship-resistant with no single point of failure
• Adaptive and scalable network
• Shared infrastructure

3.Runs anywhere.

Applications often run in restricted environments, where resources or the environment is restricted in some fashion. For example:

• Limited bandwidth, CPU, memory, disk, battery, etc.
• Not being publicly connectable
• Only being intermittently connected; mostly-offline

4.Privacy-preserving.

Applications often have a desire for some privacy guarantees, such as:

• Pseudonymity and not being tied to any personally identifiable information (PII)
• Metadata protection in transit
• Various forms of unlinkability, etc.

5.Modular design.

Applications often have different trade-offs when it comes to what properties they and their users value. Waku is designed in a modular fashion where an application protocol or node can choose what protocols they run. We call this concept adaptive nodes.

For example:

• Resource usage vs metadata protection
• Providing useful services to the network vs mostly using it
• Stronger guarantees for spam protection vs economic registration cost

For more on the concept of adaptive nodes and what this means in practice, please see the 30/ADAPTIVE-NODES spec.

Specification

The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in 2119.

Network Interaction Domains

While Waku is best thought of as a single cohesive thing, there are three network interaction domains:

(a) gossip domain (b) discovery domain (c) request/response domain

Protocols and Identifiers

Since Waku is built on top of libp2p, many protocols have a libp2p protocol identifier. The current main protocol identifiers are:

1. /vac/waku/relay/2.0.0
2. /vac/waku/store-query/3.0.0
3. /vac/waku/filter/2.0.0-beta1
4. /vac/waku/lightpush/2.0.0-beta1

This is in addition to protocols that specify messages, payloads, and recommended usages. Since these aren't negotiated libp2p protocols, they are referred to by their RFC ID. For example:

• 14/WAKU2-MESSAGE and 26/WAKU-PAYLOAD for message payloads
• 23/WAKU2-TOPICS and 27/WAKU2-PEERS for recommendations around usage

There are also more experimental libp2p protocols such as:

1. /vac/waku/waku-rln-relay/2.0.0-alpha1
2. /vac/waku/peer-exchange/2.0.0-alpha1

The semantics of these protocols are referred to by RFC ID 17/WAKU2-RLN-RELAY and 34/WAKU2-PEER-EXCHANGE.

Use of libp2p and Protobuf

Unless otherwise specified, all protocols are implemented over libp2p and use Protobuf by default. Since messages are exchanged over a bi-directional binary stream, as a convention, libp2p protocols prefix binary message payloads with the length of the message in bytes. This length integer is encoded as a protobuf varint.

Gossip Domain

Waku is using gossiping to disseminate messages throughout the network.

Protocol identifier: /vac/waku/relay/2.0.0

See 11/WAKU2-RELAY specification for more details.

For an experimental privacy-preserving economic spam protection mechanism, see 17/WAKU2-RLN-RELAY.

See 23/WAKU2-TOPICS for more information about the recommended topic usage.

Direct use of libp2p protocols

In addition to /vac/waku/* protocols, Waku MAY directly use the following libp2p protocols:

• libp2p ping protocol with protocol id

/ipfs/ping/1.0.0

for liveness checks between peers, or to keep peer-to-peer connections alive.

• libp2p identity and identity/push with protocol IDs

/ipfs/id/1.0.0

and

/ipfs/id/push/1.0.0

respectively, as basic means for capability discovery. These protocols are anyway used by the libp2p connection establishment layer Waku is built on. We plan to introduce a new AnonComms capability discovery protocol with better anonymity properties and more functionality.

Transports

Waku is built in top of libp2p, and like libp2p it strives to be transport agnostic. We define a set of recommended transports in order to achieve a baseline of interoperability between clients. This section describes these recommended transports.

Waku client implementations SHOULD support the TCP transport. Where TCP is supported it MUST be enabled for both dialing and listening, even if other transports are available.

Waku nodes running in environments that do not allow the use of TCP directly, MAY use other transports.

A Waku node SHOULD support secure websockets for bidirectional communication streams, for example in a web browser context.

A node MAY support unsecure websockets if required by the application or running environment.

Discovery Domain

Discovery Methods

Waku can retrieve a list of nodes to connect to using DNS-based discovery as per EIP-1459. While this is a useful way of bootstrapping connection to a set of peers, it MAY be used in conjunction with an ambient peer discovery procedure to find other nodes to connect to, such as Node Discovery v5. It is possible to bypass the discovery domain by specifying static nodes.

Use of ENR

WAKU2-ENR describes the usage of EIP-778 ENR (Ethereum Node Records) for Waku discovery purposes. It introduces two new ENR fields, multiaddrs and waku2, that a Waku node MAY use for discovery purposes. These fields MUST be used under certain conditions, as set out in the specification. Both EIP-1459 DNS-based discovery and Node Discovery v5 operate on ENR, and it's reasonable to expect even wider utility for ENR in Waku networks in the future.

Request/Response Domain

In addition to the Gossip domain, Waku provides a set of request/response protocols. They are primarily 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-query/3.0.0

This is used to fetch historical messages for mostly offline devices. See 13/WAKU2-STORE spec specification for more details.

There is also an experimental fault-tolerant addition to the store protocol that relaxes the high availability requirement. See 21/WAKU2-FAULT-TOLERANT-STORE

Content Filtering

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

This is used to preserve more bandwidth when fetching a subset of messages. See 12/WAKU2-FILTER specification for more details.

LightPush

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

This is used for nodes with short connection windows and limited bandwidth to publish messages into the Waku network. See 19/WAKU2-LIGHTPUSH specification for more details.

Other Protocols

The above is a non-exhaustive list, and due to the modular design of Waku, there may be other protocols here that provide a useful service to the Waku network.

Overview of Protocol Interaction

See the sequence diagram below for an overview of how different protocols interact.

0. We have six nodes, A-F. The protocols initially mounted are indicated as such. The PubSub topics pubtopic1 and pubtopic2 is used for routing and indicates that it is subscribed to messages on that topic for relay, see 11/WAKU2-RELAY for details. Ditto for 13/WAKU2-STORE where it indicates that these messages are persisted on that node.

1. Node A creates a WakuMessage msg1 with a ContentTopic contentTopic1. See 14/WAKU2-MESSAGE for more details. If WakuMessage version is set to 1, we use the 6/WAKU1 compatible data field with encryption. See 7/WAKU-DATA for more details.

2. Node F requests to get messages filtered by PubSub topic pubtopic1 and ContentTopic contentTopic1. Node D subscribes F to this filter and will in the future forward messages that match that filter. See 12/WAKU2-FILTER for more details.

3. Node A publishes msg1 on pubtopic1 and subscribes to that relay topic. It then gets relayed further from B to D, but not C since it doesn't subscribe to that topic. See 11/WAKU2-RELAY.

4. Node D saves msg1 for possible later retrieval by other nodes. See 13/WAKU2-STORE.

5. Node D also pushes msg1 to F, as it has previously subscribed F to this filter. See 12/WAKU2-FILTER.

6. At a later time, Node E comes online. It then requests messages matching pubtopic1 and contentTopic1 from Node D. Node D responds with messages meeting this (and possibly other) criteria. See 13/WAKU2-STORE.

Appendix A: Upgradability and Compatibility

Compatibility with Waku Legacy

6/WAKU1 and Waku are different protocols all together. They use a different transport protocol underneath; 6/WAKU1 is devp2p RLPx based while Waku 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 15/WAKU-BRIDGE for details on a bidirectional bridge mode.

Appendix B: Security

Each protocol layer of Waku provides a distinct service and is associated with a separate set of security features and concerns. Therefore, the overall security of Waku depends on how the different layers are utilized. In this section, we overview the security properties of Waku protocols against a static adversarial model which is described below. Note that a more detailed security analysis of each Waku protocol is supplied in its respective specification as well.

Primary Adversarial Model

In the primary adversarial model, we consider adversary as a passive entity that attempts to collect information from others to conduct an attack, but it does so without violating protocol definitions and instructions.

The following are not considered as part of the adversarial model:

• An adversary with a global view of all the peers and their connections.
• An adversary that can eavesdrop on communication links between arbitrary pairs of peers (unless the adversary is one end of the communication). Specifically, the communication channels are assumed to be secure.

Security Features

Pseudonymity

Waku by default guarantees pseudonymity for all of the protocol layers since parties do not have to disclose their true identity and instead they utilize libp2p PeerID as their identifiers. While pseudonymity is an appealing security feature, it does not guarantee full anonymity since the actions taken under the same pseudonym i.e., PeerID can be linked together and potentially result in the re-identification of the true actor.

Anonymity / Unlinkability

At a high level, anonymity is the inability of an adversary in linking an actor to its data/performed action (the actor and action are context-dependent). To be precise about linkability, we use the term Personally Identifiable Information (PII) to refer to any piece of data that could potentially be used to uniquely identify a party. For example, the signature verification key, and the hash of one's static IP address are unique for each user and hence count as PII. Notice that users' actions can be traced through their PIIs (e.g., signatures) and hence result in their re-identification risk. As such, we seek anonymity by avoiding linkability between actions and the actors / actors' PII. Concerning anonymity, Waku provides the following features:

Publisher-Message Unlinkability: This feature signifies the unlinkability of a publisher to its published messages in the 11/WAKU2-RELAY protocol. The Publisher-Message Unlinkability is enforced through the StrictNoSign policy due to which the data fields of pubsub messages that count as PII for the publisher must be left unspecified.

Subscriber-Topic Unlinkability: This feature stands for the unlinkability of the subscriber to its subscribed topics in the 11/WAKU2-RELAY protocol. The Subscriber-Topic Unlinkability is achieved through the utilization of a single PubSub topic. As such, subscribers are not re-identifiable from their subscribed topic IDs as the entire network is linked to the same topic ID. This level of unlinkability / anonymity is known as k-anonymity where k is proportional to the system size (number of subscribers). Note that there is no hard limit on the number of the pubsub topics, however, the use of one topic is recommended for the sake of anonymity.

Spam protection

This property indicates that no adversary can flood the system (i.e., publishing a large number of messages in a short amount of time), either accidentally or deliberately, with any kind of message i.e. even if the message content is valid or useful. Spam protection is partly provided in 11/WAKU2-RELAY through the scoring mechanism provided for by GossipSub v1.1. At a high level, peers utilize a scoring function to locally score the behavior of their connections and remove peers with a low score.

Data confidentiality, Integrity, and Authenticity

Confidentiality can be addressed through data encryption whereas integrity and authenticity are achievable through digital signatures. These features are provided for in 14/WAKU2-MESSAGE (version 1)` through payload encryption as well as encrypted signatures.

Security Considerations

Lack of anonymity/unlinkability in the protocols involving direct connections including 13/WAKU2-STORE and 12/WAKU2-FILTER protocols:

The anonymity/unlinkability is not guaranteed in the protocols like 13/WAKU2-STORE and 12/WAKU2-FILTER where peers need to have direct connections to benefit from the designated service. This is because during the direct connections peers utilize PeerID to identify each other, therefore the service obtained in the protocol is linkable to the beneficiary's PeerID (which counts as PII). For 13/WAKU2-STORE, the queried node would be able to link the querying node's PeerID to its queried topics. Likewise, in the 12/WAKU2-FILTER, a full node can link the light node's PeerIDs to its content filter.

Appendix C: Implementation Notes

Implementation Matrix

There are multiple implementations of Waku and its protocols:

• nim-waku (Nim)
• go-waku (Go)
• js-waku (NodeJS and Browser)

Below you can find an overview of the specifications that they implement as they relate to Waku. This includes Waku legacy specifications, as they are used for bridging between the two networks.

*js-waku implements 13/WAKU2-STORE as a querying node only. **js-waku only implements 19/WAKU2-LIGHTPUSH requests.

Recommendations for Clients

To implement a minimal Waku client, we recommend implementing the following subset in the following order:

• 10/WAKU2 - this specification
• 11/WAKU2-RELAY - for basic operation
• 14/WAKU2-MESSAGE - version 0 (unencrypted)
• 13/WAKU2-STORE - for historical messaging (query mode only)

To get compatibility with Waku Legacy:

• 7/WAKU-DATA
• 14/WAKU2-MESSAGE - version 1 (encrypted with 7/WAKU-DATA)

For an interoperable keep-alive mechanism:

• libp2p ping protocol, with periodic pings to connected peers

Appendix D: Future work

The following features are currently experimental, under research and initial implementations:

Economic Spam Resistance:

We aim to enable an incentivized spam protection technique to enhance 11/WAKU2-RELAY by using rate limiting nullifiers. More details on this can be found in 17/WAKU2-RLN-RELAY. In this advanced method, peers are limited to a certain rate of messaging per epoch and an immediate financial penalty is enforced for spammers who break this rate.

Prevention of Denial of Service (DoS) and Node Incentivization: Denial of service signifies the case where an adversarial node exhausts another node's service capacity (e.g., by making a large number of requests) and makes it unavailable to the rest of the system. DoS attack is to be mitigated through the accounting model as described in 18/WAKU2-SWAP. In a nutshell, peers have to pay for the service they obtain from each other. In addition to incentivizing the service provider, accounting also makes DoS attacks costly for malicious peers. The accounting model can be used in 13/WAKU2-STORE and 12/WAKU2-FILTER to protect against DoS attacks.

Additionally, this gives node operators who provide a useful service to the network an incentive to perform that service. See 18/WAKU2-SWAP for more details on this piece of work.

Copyright

Copyright and related rights waived via CC0.

References

1. libp2p specs

2. 6/WAKU1

3. Whisper spec (EIP627)

4. Waku v2 plan

5. 30/ADAPTIVE-NODES

6. Protocol Identifiers

7. 14/WAKU2-MESSAGE

8. 26/WAKU-PAYLOAD

9. 23/WAKU2-TOPICS

10. 27/WAKU2-PEERS

11. bi-directional binary stream

12. Protobuf varint encoding

13. 11/WAKU2-RELAY spec

14. 17/WAKU2-RLN-RELAY

15. EIP-1459

16. Ambient peer discovery

17. Node Discovery v5

18. WAKU2-ENR

19. EIP-778 ENR (Ethereum Node Records)

20. 13/WAKU2-STORE spec

21. 21/WAKU2-FT-STORE

22. 12/WAKU2-FILTER

23. 19/WAKU2-LIGHTPUSH

24. 7/WAKU-DATA

25. 15/WAKU-BRIDGE

26. k-anonymity

27. GossipSub v1.1

28. nim-waku (Nim)

29. go-waku (Go)

30. js-waku (NodeJS and Browser)

31. 8/WAKU-MAIL

32. 9/WAKU-RPC

33. 16/WAKU2-RPC

34. 18/WAKU2-SWAP spec

35. 21/WAKU2-FAULT-TOLERANT-STORE

12/WAKU2-FILTER

Timeline

• 2026-06-16 — 16e8af1 — Chore/separate messaging specs (#361)
• 2026-05-11 — 1ac7689 — chore: split ift ts specs (#334)
• 2026-04-20 — c3d15a9 — COSS overhaul: new statuses, CFR type, raw-spec leniency (#308)
• 2026-02-09 — afd94c8 — chore: add math support (#287)
• 2026-01-16 — f01d5b9 — chore: fix links (#260)
• 2026-01-16 — 89f2ea8 — Chore/mdbook updates (#258)
• 2025-12-22 — 0f1855e — Chore/fix headers (#239)
• 2025-12-22 — b1a5783 — Chore/mdbook updates (#237)
• 2025-12-18 — d03e699 — ci: add mdBook configuration (#233)
• 2025-03-25 — e8a3f8a — 12/WAKU2-FILTER: Update (#119)
• 2024-09-13 — 3ab314d — Fix Files for Linting (#94)
• 2024-02-01 — e4d8f27 — Update and rename FILTER.md to filter.md
• 2024-01-27 — 046a3b7 — Rename WAKU2-FILTER.md to FILTER.md
• 2024-01-27 — 57124a7 — Rename README.md to WAKU2-FILTER.md
• 2024-01-27 — eef961b — remove rfs folder
• 2024-01-25 — 940d795 — Rename waku/12/README.md to waku/rfcs/standards/core/12/README.md
• 2024-01-22 — 420adf1 — Vac RFC index initial structure

Protocol identifiers:

• filter-subscribe: /vac/waku/filter-subscribe/2.0.0-beta1
• filter-push: /vac/waku/filter-push/2.0.0-beta1

Abstract

This specification describes the 12/WAKU2-FILTER protocol, which enables a client to subscribe to a subset of real-time messages from a Waku peer. This is a more lightweight version of 11/WAKU2-RELAY, useful for bandwidth restricted devices. This is often used by nodes with lower resource limits to subscribe to full Relay nodes and only receive the subset of messages they desire, based on content topic interest.

Motivation

Unlike the 13/WAKU2-STORE protocol for historical messages, this protocol allows for native lower latency scenarios, such as instant messaging. It is thus complementary to it.

Strictly speaking, it is not just doing basic request-response, but performs sender push based on receiver intent. While this can be seen as a form of light publish/subscribe, it is only used between two nodes in a direct fashion. Unlike the Gossip domain, this is suitable for light nodes which put a premium on bandwidth. No gossiping takes place.

It is worth noting that a light node could get by with only using the 13/WAKU2-STORE protocol to query for a recent time window, provided it is acceptable to do frequent polling.

Semantics

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in 2119.

Content filtering

Content filtering is a way to do message-based filtering. Currently the only content filter being applied is on contentTopic.

Terminology

The term Personally identifiable information (PII) refers to any piece of data that can be used to uniquely identify a user. For example, the signature verification key, and the hash of one's static IP address are unique for each user and hence count as PII.

Protobuf

syntax = "proto3";

// Protocol identifier: /vac/waku/filter-subscribe/2.0.0-beta1
message FilterSubscribeRequest {
  enum FilterSubscribeType {
    SUBSCRIBER_PING = 0;
    SUBSCRIBE = 1;
    UNSUBSCRIBE = 2;
    UNSUBSCRIBE_ALL = 3;
  }

  string request_id = 1;
  FilterSubscribeType filter_subscribe_type = 2;

  // Filter criteria
  optional string pubsub_topic = 10;
  repeated string content_topics = 11;
}

message FilterSubscribeResponse {
  string request_id = 1;
  uint32 status_code = 10;
  optional string status_desc = 11;
}

// Protocol identifier: /vac/waku/filter-push/2.0.0-beta1
message MessagePush {
  WakuMessage waku_message = 1;
  optional string pubsub_topic = 2;
}

Filter-Subscribe

A filter service node MUST support the filter-subscribe protocol to allow filter clients to subscribe, modify, refresh and unsubscribe a desired set of filter criteria. The combination of different filter criteria for a specific filter client node is termed a "subscription". A filter client is interested in receiving messages matching the filter criteria in its registered subscriptions.

Since a filter service node is consuming resources to provide this service, it MAY account for usage and adapt its service provision to certain clients.

Filter Subscribe Request

A client node MUST send all filter requests in a FilterSubscribeRequest message. This request MUST contain a request_id. The request_id MUST be a uniquely generated string. Each request MUST include a filter_subscribe_type, indicating the type of request.

Filter Subscribe Response

When responding to a FilterSubscribeRequest, a filter service node SHOULD send a FilterSubscribeResponse with a requestId matching that of the request. This response MUST contain a status_code indicating if the request was successful or not. Successful status codes are in the 2xx range. Client nodes SHOULD consider all other status codes as error codes and assume that the requested operation had failed. In addition, the filter service node MAY choose to provide a more detailed status description in the status_desc field.

Filter matching

In the description of each request type below, the term "filter criteria" refers to the combination of pubsub_topic and a set of content_topics. The request MAY include filter criteria, conditional to the selected filter_subscribe_type. If the request contains filter criteria, it MUST contain a pubsub_topic and the content_topics set MUST NOT be empty. A 14/WAKU2-MESSAGE matches filter criteria when its content_topic is in the content_topics set and it was published on a matching pubsub_topic.

Filter Subscribe Types

The filter-subscribe types are defined as follows:

SUBSCRIBER_PING

A filter client that sends a FilterSubscribeRequest with filter_subscribe_type set to SUBSCRIBER_PING, requests that the filter service node SHOULD indicate if it has any active subscriptions for this client. The filter client SHOULD exclude any filter criteria from the request. The filter service node SHOULD respond with a success status_code if it has any active subscriptions for this client or an error status_code if not. The filter service node SHOULD ignore any filter criteria in the request.

SUBSCRIBE

A filter client that sends a FilterSubscribeRequest with filter_subscribe_type set to SUBSCRIBE requests that the filter service node SHOULD push messages matching this filter to the client. The filter client MUST include the desired filter criteria in the request. A client MAY use this request type to modify an existing subscription by providing additional filter criteria in a new request. A client MAY use this request type to refresh an existing subscription by providing the same filter criteria in a new request. The filter service node SHOULD respond with a success status_code if it successfully honored this request or an error status_code if not. The filter service node SHOULD respond with an error status_code and discard the request if the FilterSubscribeRequest does not contain valid filter criteria, i.e. both a pubsub_topic and a non-empty content_topics set.

UNSUBSCRIBE

A filter client that sends a FilterSubscribeRequest with filter_subscribe_type set to UNSUBSCRIBE requests that the service node SHOULD stop pushing messages matching this filter to the client. The filter client MUST include the filter criteria it desires to unsubscribe from in the request. A client MAY use this request type to modify an existing subscription by providing a subset of the original filter criteria to unsubscribe from in a new request. The filter service node SHOULD respond with a success status_code if it successfully honored this request or an error status_code if not. The filter service node SHOULD respond with an error status_code and discard the request if the unsubscribe request does not contain valid filter criteria, i.e. both a pubsub_topic and a non-empty content_topics set.

UNSUBSCRIBE_ALL

A filter client that sends a FilterSubscribeRequest with filter_subscribe_type set to UNSUBSCRIBE_ALL requests that the service node SHOULD stop pushing messages matching any filter to the client. The filter client SHOULD exclude any filter criteria from the request. The filter service node SHOULD remove any existing subscriptions for this client. It SHOULD respond with a success status_code if it successfully honored this request or an error status_code if not.

Filter-Push

A filter client node MUST support the filter-push protocol to allow filter service nodes to push messages matching registered subscriptions to this client.

A filter service node SHOULD push all messages matching the filter criteria in a registered subscription to the subscribed filter client. These WakuMessages are likely to come from 11/WAKU2-RELAY, but there MAY be other sources or protocols where this comes from. This is up to the consumer of the protocol.

If a message push fails, the filter service node MAY consider the client node to be unreachable. If a specific filter client node is not reachable from the service node for a period of time, the filter service node MAY choose to stop pushing messages to the client and remove its subscription. This period is up to the service node implementation. It is RECOMMENDED to set 1 minute as a reasonable default.

Message Push

Each message MUST be pushed in a MessagePush message. Each MessagePush MUST contain one (and only one) waku_message. If this message was received on a specific pubsub_topic, it SHOULD be included in the MessagePush. A filter client SHOULD NOT respond to a MessagePush. Since the filter protocol does not include caching or fault-tolerance, this is a best effort push service with no bundling or guaranteed retransmission of messages. A filter client SHOULD verify that each MessagePush it receives originated from a service node where the client has an active subscription and that it matches filter criteria belonging to that subscription.

Adversarial Model

Any node running the WakuFilter protocol i.e., both the subscriber node and the queried node are considered as an adversary. Furthermore, we consider the adversary as a passive entity that attempts to collect information from other nodes to conduct an attack but it does so without violating protocol definitions and instructions. For example, under the passive adversarial model, no malicious node intentionally hides the messages matching to one's subscribed content filter as it is against the description of the WakuFilter protocol.

The following are not considered as part of the adversarial model:

• An adversary with a global view of all the nodes and their connections.
• An adversary that can eavesdrop on communication links between arbitrary pairs of nodes (unless the adversary is one end of the communication). In specific, the communication channels are assumed to be secure.

Security Considerations

Note that while using WakuFilter allows light nodes to save bandwidth, it comes with a privacy cost in the sense that they need to disclose their liking topics to the full nodes to retrieve the relevant messages. Currently, anonymous subscription is not supported by the WakuFilter, however, potential solutions in this regard are discussed below.

Future Work

Anonymous filter subscription: This feature guarantees that nodes can anonymously subscribe for a message filter (i.e., without revealing their exact content filter). As such, no adversary in the WakuFilter protocol would be able to link nodes to their subscribed content filers. The current version of the WakuFilter protocol does not provide anonymity as the subscribing node has a direct connection to the full node and explicitly submits its content filter to be notified about the matching messages. However, one can consider preserving anonymity through one of the following ways:

• By hiding the source of the subscription i.e., anonymous communication. That is the subscribing node shall hide all its PII in its filter request e.g., its IP address. This can happen by the utilization of a proxy server or by using Tor

Note that the current structure of filter requests i.e., FilterRPC does not embody any piece of PII, otherwise, such data fields must be treated carefully to achieve anonymity.

• By deploying secure 2-party computations in which the subscribing node obtains the messages matching a content filter whereas the full node learns nothing about the content filter as well as the messages pushed to the subscribing node. Examples of such 2PC protocols are Oblivious Transfers and one-way Private Set Intersections (PSI).

Copyright

Copyright and related rights waived via CC0.

Previous versions

• 00

References

• 11/WAKU2-RELAY
• message-based filtering
• 13/WAKU2-STORE
• 14/WAKU2-MESSAGE
• Oblivious Transfers

Informative

1. Message Filtering (Wikipedia)
2. Libp2p PubSub spec - topic validation

12/WAKU2-FILTER

Timeline

• 2026-06-16 — 16e8af1 — Chore/separate messaging specs (#361)
• 2026-05-11 — 1ac7689 — chore: split ift ts specs (#334)
• 2026-04-20 — c3d15a9 — COSS overhaul: new statuses, CFR type, raw-spec leniency (#308)
• 2026-02-09 — afd94c8 — chore: add math support (#287)
• 2026-01-21 — a00f16e — chore: mdbook fixes (#265)
• 2026-01-16 — f01d5b9 — chore: fix links (#260)
• 2026-01-16 — 89f2ea8 — Chore/mdbook updates (#258)
• 2025-12-22 — 0f1855e — Chore/fix headers (#239)
• 2025-12-22 — b1a5783 — Chore/mdbook updates (#237)
• 2025-12-18 — d03e699 — ci: add mdBook configuration (#233)
• 2025-03-25 — e8a3f8a — 12/WAKU2-FILTER: Update (#119)
• 2024-09-13 — 3ab314d — Fix Files for Linting (#94)
• 2024-02-05 — d41f106 — Update filter.md
• 2024-02-05 — 8436a31 — Update and rename README.md to filter.md
• 2024-01-27 — eef961b — remove rfs folder
• 2024-01-25 — 420a51b — Rename waku/rfcs/core/12/previous-versions00/README.md to waku/rfcs/standards/core/12/previous-versions00/README.md
• 2024-01-25 — 755fea9 — Rename waku/12/previous-versions/00/README.md to waku/rfcs/core/12/previous-versions00/README.md
• 2024-01-22 — 420adf1 — Vac RFC index initial structure

WakuFilter is a protocol that enables subscribing to messages that a peer receives. This is a more lightweight version of WakuRelay specifically designed for bandwidth restricted devices. This is due to the fact that light nodes subscribe to full-nodes and only receive the messages they desire.

Content filtering

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

Content filtering is a way to do message-based filtering. Currently the only content filter being applied is on contentTopic. This corresponds to topics in Waku v1.

Rationale

Unlike the store protocol for historical messages, this protocol allows for native lower latency scenarios such as instant messaging. It is thus complementary to it.

Strictly speaking, it is not just doing basic request response, but performs sender push based on receiver intent. While this can be seen as a form of light pub/sub, it is only used between two nodes in a direct fashion. Unlike the Gossip domain, this is meant for light nodes which put a premium on bandwidth. No gossiping takes place.

It is worth noting that a light node could get by with only using the store protocol to query for a recent time window, provided it is acceptable to do frequent polling.

Design Requirements

The effectiveness and reliability of the content filtering service enabled by WakuFilter protocol rely on the high availability of the full nodes as the service providers. To this end, full nodes must feature high uptime (to persistently listen and capture the network messages) as well as high Bandwidth (to provide timely message delivery to the light nodes).

Security Consideration

Note that while using WakuFilter allows light nodes to save bandwidth, it comes with a privacy cost in the sense that they need to disclose their liking topics to the full nodes to retrieve the relevant messages. Currently, anonymous subscription is not supported by the WakuFilter, however, potential solutions in this regard are sketched below in Future Work section.

Terminology

The term Personally identifiable information (PII) refers to any piece of data that can be used to uniquely identify a user. For example, the signature verification key, and the hash of one's static IP address are unique for each user and hence count as PII.

Adversarial Model

Any node running the WakuFilter protocol i.e., both the subscriber node and the queried node are considered as an adversary. Furthermore, we consider the adversary as a passive entity that attempts to collect information from other nodes to conduct an attack but it does so without violating protocol definitions and instructions. For example, under the passive adversarial model, no malicious node intentionally hides the messages matching to one's subscribed content filter as it is against the description of the WakuFilter protocol.

The following are not considered as part of the adversarial model:

• An adversary with a global view of all the nodes and their connections.
• An adversary that can eavesdrop on communication links between arbitrary pairs of nodes (unless the adversary is one end of the communication). In specific, the communication channels are assumed to be secure.

Protobuf

message FilterRequest {
  bool subscribe = 1;
  string topic = 2;
  repeated ContentFilter contentFilters = 3;

  message ContentFilter {
    string contentTopic = 1;
  }
}

message MessagePush {
  repeated WakuMessage messages = 1;
}

message FilterRPC {
  string requestId = 1;
  FilterRequest request = 2;
  MessagePush push = 3;
}

FilterRPC

A node MUST send all Filter messages (FilterRequest, MessagePush) wrapped inside a FilterRPC this allows the node handler to determine how to handle a message as the Waku Filter protocol is not a request response based protocol but instead a push based system.

The requestId MUST be a uniquely generated string. When a MessagePush is sent the requestId MUST match the requestId of the subscribing FilterRequest whose filters matched the message causing it to be pushed.

FilterRequest

A FilterRequest contains an optional topic, zero or more content filters and a boolean signifying whether to subscribe or unsubscribe to the given filters. True signifies 'subscribe' and false signifies 'unsubscribe'.

A node that sends the RPC with a filter request and subscribe set to 'true' requests that the filter node SHOULD notify the light requesting node of messages matching this filter.

A node that sends the RPC with a filter request and subscribe set to 'false' requests that the filter node SHOULD stop notifying the light requesting node of messages matching this filter if it is currently doing so.

The filter matches when content filter and, optionally, a topic is matched. Content filter is matched when a WakuMessage contentTopic field is the same.

A filter node SHOULD honor this request, though it MAY choose not to do so. If it chooses not to do so it MAY tell the light why. The mechanism for doing this is currently not specified. For notifying the light node a filter node sends a MessagePush message.

Since such a filter node is doing extra work for a light node, it MAY also account for usage and be selective in how much service it provides. This mechanism is currently planned but underspecified.

MessagePush

A filter node that has received a filter request SHOULD push all messages that match this filter to a light node. These WakuMessage's are likely to come from the relay protocol and be kept at the Node, but there MAY be other sources or protocols where this comes from. This is up to the consumer of the protocol.

A filter node MUST NOT send a push message for messages that have not been requested via a FilterRequest.

If a specific light node isn't connected to a filter node for some specific period of time (e.g. a TTL), then the filter node MAY choose to not push these messages to the node. This period is up to the consumer of the protocol and node implementation, though a reasonable default is one minute.

Future Work

Anonymous filter subscription: This feature guarantees that nodes can anonymously subscribe for a message filter (i.e., without revealing their exact content filter). As such, no adversary in the WakuFilter protocol would be able to link nodes to their subscribed content filers. The current version of the WakuFilter protocol does not provide anonymity as the subscribing node has a direct connection to the full node and explicitly submits its content filter to be notified about the matching messages. However, one can consider preserving anonymity through one of the following ways:

• By hiding the source of the subscription i.e., anonymous communication. That is the subscribing node shall hide all its PII in its filter request e.g., its IP address. This can happen by the utilization of a proxy server or by using Tor

Note that the current structure of filter requests i.e., FilterRPC does not embody any piece of PII, otherwise, such data fields must be treated carefully to achieve anonymity.

• By deploying secure 2-party computations in which the subscribing node obtains the messages matching a content filter whereas the full node learns nothing about the content filter as well as the messages pushed to the subscribing node. Examples of such 2PC protocols are Oblivious Transfers and one-way Private Set Intersections (PSI).

Copyright

Copyright and related rights waived via CC0.

References

1. Message Filtering (Wikipedia)

2. Libp2p PubSub spec - topic validation

13/WAKU2-STORE

Timeline

• 2026-06-16 — 16e8af1 — Chore/separate messaging specs (#361)
• 2026-05-11 — 1ac7689 — chore: split ift ts specs (#334)
• 2026-04-20 — c3d15a9 — COSS overhaul: new statuses, CFR type, raw-spec leniency (#308)
• 2026-02-09 — afd94c8 — chore: add math support (#287)
• 2026-01-16 — f01d5b9 — chore: fix links (#260)
• 2026-01-16 — 89f2ea8 — Chore/mdbook updates (#258)
• 2025-12-22 — 0f1855e — Chore/fix headers (#239)
• 2025-12-22 — b1a5783 — Chore/mdbook updates (#237)
• 2025-12-18 — d03e699 — ci: add mdBook configuration (#233)
• 2025-04-15 — 1b8b2ac — Add missing status to 13/WAKU-STORE (#149)
• 2025-02-03 — a60a2c4 — 13/WAKU-STORE: Update (#124)
• 2024-09-13 — 3ab314d — Fix Files for Linting (#94)
• 2024-08-05 — eb25cd0 — chore: replace email addresses (#86)
• 2024-03-21 — 2eaa794 — Broken Links + Change Editors (#26)
• 2024-02-01 — 755be94 — Update and rename STORE.md to store.md
• 2024-01-27 — 3baed07 — Rename README.md to STORE.md
• 2024-01-27 — eef961b — remove rfs folder
• 2024-01-25 — 51e2879 — Create README.md

Abstract

This specification explains the WAKU2-STORE protocol, which enables querying of 14/WAKU2-MESSAGEs.

Protocol identifier*: /vac/waku/store-query/3.0.0

Terminology

The term PII, Personally Identifiable Information, refers to any piece of data that can be used to uniquely identify a user. For example, the signature verification key, and the hash of one's static IP address are unique for each user and hence count as PII.

Wire Specification

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC2119.

Design Requirements

The concept of ephemeral messages introduced in 14/WAKU2-MESSAGE affects WAKU2-STORE as well. Nodes running WAKU2-STORE SHOULD support ephemeral messages as specified in 14/WAKU2-MESSAGE. Nodes running WAKU2-STORE SHOULD NOT store messages with the ephemeral flag set to true.

Payloads

syntax = "proto3";

// Protocol identifier: /vac/waku/store-query/3.0.0
package waku.store.v3;

import "waku/message/v1/message.proto";

message WakuMessageKeyValue {
  optional bytes message_hash = 1; // Globally unique key for a Waku Message

  // Full message content and associated pubsub_topic as value
  optional waku.message.v1.WakuMessage message = 2;
  optional string pubsub_topic = 3;
}

message StoreQueryRequest {
  string request_id = 1;
  bool include_data = 2; // Response should include full message content

  // Filter criteria for content-filtered queries
  optional string pubsub_topic = 10;
  repeated string content_topics = 11;
  optional sint64 time_start = 12;
  optional sint64 time_end = 13;

  // List of key criteria for lookup queries
  repeated bytes message_hashes = 20; // Message hashes (keys) to lookup

  // Pagination info. 50 Reserved
  optional bytes pagination_cursor = 51; // Message hash (key) from where to start query (exclusive)
  bool pagination_forward = 52;
  optional uint64 pagination_limit = 53;
}

message StoreQueryResponse {
  string request_id = 1;

  optional uint32 status_code = 10;
  optional string status_desc = 11;

  repeated WakuMessageKeyValue messages = 20;

  optional bytes pagination_cursor = 51;
}

General Store Query Concepts

Waku Message Key-Value Pairs

The store query protocol operates as a query protocol for a key-value store of historical messages, with each entry having a 14/WAKU2-MESSAGE and associated pubsub_topic as the value, and deterministic message hash as the key. The store can be queried to return either a set of keys or a set of key-value pairs.

Within the store query protocol, the 14/WAKU2-MESSAGE keys and values MUST be represented in a WakuMessageKeyValue message. This message MUST contain the deterministic message_hash as the key. It MAY contain the full 14/WAKU2-MESSAGE and associated pubsub topic as the value in the message and pubsub_topic fields, depending on the use case as set out below.

If the message contains a value entry in addition to the key, both the message and pubsub_topic fields MUST be populated. The message MUST NOT have either message or pubsub_topic populated with the other unset. Both fields MUST either be set or unset.

Waku Message Store Eligibility

In order for a message to be eligible for storage:

• it MUST be a valid 14/WAKU2-MESSAGE.
• the timestamp field MUST be populated with the Unix epoch time, at which the message was generated in nanoseconds. If at the time of storage the timestamp deviates by more than 20 seconds either into the past or the future when compared to the store node’s internal clock, the store node MAY reject the message.
• the ephemeral field MUST be set to false.

Waku message sorting

The key-value entries in the store MUST be time-sorted by the 14/WAKU2-MESSAGE timestamp attribute. Where two or more key-value entries have identical timestamp values, the entries MUST be further sorted by the natural order of their message hash keys. Within the context of traversing over key-value entries in the store, "forward" indicates traversing the entries in ascending order, whereas "backward" indicates traversing the entries in descending order.

Pagination

If a large number of entries in the store service node match the query criteria provided in a StoreQueryRequest, the client MAY make use of pagination in a chain of store query request and response transactions to retrieve the full response in smaller batches termed "pages". Pagination can be performed either in a forward or backward direction.

A store query client MAY indicate the maximum number of matching entries it wants in the StoreQueryResponse, by setting the page size limit in the pagination_limit field. Note that a store service node MAY enforce its own limit if the pagination_limit is unset or larger than the service node's internal page size limit.

A StoreQueryResponse with a populated pagination_cursor indicates that more stored entries match the query than included in the response.

A StoreQueryResponse without a populated pagination_cursor indicates that there are no more matching entries in the store.

The client MAY request the next page of entries from the store service node by populating a subsequent StoreQueryRequest with the pagination_cursor received in the StoreQueryResponse. All other fields and query criteria MUST be the same as in the preceding StoreQueryRequest.

A StoreQueryRequest without a populated pagination_cursor indicates that the client wants to retrieve the "first page" of the stored entries matching the query.

Store Query Request

A client node MUST send all historical message queries within a StoreQueryRequest message. This request MUST contain a request_id. The request_id MUST be a uniquely generated string.

If the store query client requires the store service node to include 14/WAKU2-MESSAGE values in the query response, it MUST set include_data to true. If the store query client requires the store service node to return only message hash keys in the query response, it SHOULD set include_data to false. By default, therefore, the store service node assumes include_data to be false.

A store query client MAY include query filter criteria in the StoreQueryRequest. There are two types of filter use cases:

1. Content filtered queries and
2. Message hash lookup queries

Content filtered queries

A store query client MAY request the store service node to filter historical entries by a content filter. Such a client MAY create a filter on content topic, on time range or on both.

To filter on content topic, the client MUST populate both the pubsub_topic and content_topics field. The client MUST NOT populate either pubsub_topic or content_topics and leave the other unset. Both fields MUST either be set or unset. A mixed content topic filter with just one of either pubsub_topic or content_topics set, SHOULD be regarded as an invalid request.

To filter on time range, the client MUST set time_start, time_end or both. Each time_ field should contain a Unix epoch timestamp in nanoseconds. An unset time_start SHOULD be interpreted as "from the oldest stored entry". An unset time_end SHOULD be interpreted as "up to the youngest stored entry".

If any of the content filter fields are set, namely pubsub_topic, content_topic, time_start, or time_end, the client MUST NOT set the message_hashes field.

Message hash lookup queries

A store query client MAY request the store service node to filter historical entries by one or more matching message hash keys. This type of query acts as a "lookup" against a message hash key or set of keys already known to the client.

In order to perform a lookup query, the store query client MUST populate the message_hashes field with the list of message hash keys it wants to lookup in the store service node.

If the message_hashes field is set, the client MUST NOT set any of the content filter fields, namely pubsub_topic, content_topic, time_start, or time_end.

Presence queries

A presence query is a special type of lookup query that allows a client to check for the presence of one or more messages in the store service node, without retrieving the full contents (values) of the messages. This can, for example, be used as part of a reliability mechanism, whereby store query clients verify that previously published messages have been successfully stored.

In order to perform a presence query, the store query client MUST populate the message_hashes field in the StoreQueryRequest with the list of message hashes for which it wants to verify presence in the store service node. The include_data property MUST be set to false. The client SHOULD interpret every message_hash returned in the messages field of the StoreQueryResponse as present in the store. The client SHOULD assume that all other message hashes included in the original StoreQueryRequest but not in the StoreQueryResponse is not present in the store.

Pagination info

The store query client MAY include a message hash as pagination_cursor, to indicate at which key-value entry a store service node SHOULD start the query. The pagination_cursor is treated as exclusive and the corresponding entry will not be included in subsequent store query responses.

For forward queries, only messages following (see sorting) the one indexed at pagination_cursor will be returned. For backward queries, only messages preceding (see sorting) the one indexed at pagination_cursor will be returned.

If the store query client requires the store service node to perform a forward query, it MUST set pagination_forward to true. If the store query client requires the store service node to perform a backward query, it SHOULD set pagination_forward to false. By default, therefore, the store service node assumes pagination to be backward.

A store query client MAY indicate the maximum number of matching entries it wants in the StoreQueryResponse, by setting the page size limit in the pagination_limit field. Note that a store service node MAY enforce its own limit if the pagination_limit is unset or larger than the service node's internal page size limit.

See pagination for more on how the pagination info is used in store transactions.

Store Query Response

In response to any StoreQueryRequest, a store service node SHOULD respond with a StoreQueryResponse with a requestId matching that of the request. This response MUST contain a status_code indicating if the request was successful or not. Successful status codes are in the 2xx range. A client node SHOULD consider all other status codes as error codes and assume that the requested operation had failed. In addition, the store service node MAY choose to provide a more detailed status description in the status_desc field.

Filter matching

For content filtered queries, an entry in the store service node matches the filter criteria in a StoreQueryRequest if each of the following conditions are met:

• its content_topic is in the request content_topics set and it was published on a matching pubsub_topic OR the request content_topics and pubsub_topic fields are unset
• its timestamp is larger or equal than the request start_time OR the request start_time is unset
• its timestamp is smaller than the request end_time OR the request end_time is unset

Note that for content filtered queries, start_time is treated as inclusive and end_time is treated as exclusive.

For message hash lookup queries, an entry in the store service node matches the filter criteria if its message_hash is in the request message_hashes set.

The store service node SHOULD respond with an error code and discard the request if the store query request contains both content filter criteria and message hashes.

Populating response messages

The store service node SHOULD populate the messages field in the response only with entries matching the filter criteria provided in the corresponding request. Regardless of whether the response is to a forward or backward query, the messages field in the response MUST be ordered in a forward direction according to the message sorting rules.

If the corresponding StoreQueryRequest has include_data set to true, the service node SHOULD populate both the message_hash and message for each entry in the response. In all other cases, the store service node SHOULD populate only the message_hash field for each entry in the response.

Paginating the response

The response SHOULD NOT contain more messages than the pagination_limit provided in the corresponding StoreQueryRequest. It is RECOMMENDED that the store node defines its own maximum page size internally. If the pagination_limit in the request is unset, or exceeds this internal maximum page size, the store service node SHOULD ignore the pagination_limit field and apply its own internal maximum page size.

In response to a forward StoreQueryRequest:

• if the pagination_cursor is set, the store service node SHOULD populate the messages field with matching entries following the pagination_cursor (exclusive).
• if the pagination_cursor is unset, the store service node SHOULD populate the messages field with matching entries from the first entry in the store.
• if there are still more matching entries in the store after the maximum page size is reached while populating the response, the store service node SHOULD populate the pagination_cursor in the StoreQueryResponse with the message hash key of the last entry included in the response.

In response to a backward StoreQueryRequest:

• if the pagination_cursor is set, the store service node SHOULD populate the messages field with matching entries preceding the pagination_cursor (exclusive).
• if the pagination_cursor is unset, the store service node SHOULD populate the messages field with matching entries from the last entry in the store.
• if there are still more matching entries in the store after the maximum page size is reached while populating the response, the store service node SHOULD populate the pagination_cursor in the StoreQueryResponse with the message hash key of the first entry included in the response.

Security Consideration

The main security consideration while using this protocol is that a querying node has to reveal its content filters of interest to the queried node, hence potentially compromising their privacy.

Adversarial Model

Any peer running the WAKU2-STORE protocol, i.e. both the querying node and the queried node, are considered as an adversary. Furthermore, we currently consider the adversary as a passive entity that attempts to collect information from other peers to conduct an attack but it does so without violating protocol definitions and instructions. As we evolve the protocol, further adversarial models will be considered. For example, under the passive adversarial model, no malicious node hides or lies about the history of messages as it is against the description of the WAKU2-STORE protocol.

The following are not considered as part of the adversarial model:

• An adversary with a global view of all the peers and their connections.
• An adversary that can eavesdrop on communication links between arbitrary pairs of peers (unless the adversary is one end of the communication). Specifically, the communication channels are assumed to be secure.

Future Work

• Anonymous query: This feature guarantees that nodes can anonymously query historical messages from other nodes i.e., without disclosing the exact topics of 14/WAKU2-MESSAGE they are interested in. As such, no adversary in the WAKU2-STORE protocol would be able to learn which peer is interested in which content filters i.e., content topics of 14/WAKU2-MESSAGE. The current version of the WAKU2-STORE protocol does not provide anonymity for historical queries, as the querying node needs to directly connect to another node in the WAKU2-STORE protocol and explicitly disclose the content filters of its interest to retrieve the corresponding messages. However, one can consider preserving anonymity through one of the following ways:

• By hiding the source of the request i.e., anonymous communication. That is the querying node shall hide all its PII in its history request e.g., its IP address. This can happen by the utilization of a proxy server or by using Tor. Note that the current structure of historical requests does not embody any piece of PII, otherwise, such data fields must be treated carefully to achieve query anonymity.

• By deploying secure 2-party computations in which the querying node obtains the historical messages of a certain topic, the queried node learns nothing about the query. Examples of such 2PC protocols are secure one-way Private Set Intersections (PSI).

• Robust and verifiable timestamps: Messages timestamp is a way to show that the message existed prior to some point in time. However, the lack of timestamp verifiability can create room for a range of attacks, including injecting messages with invalid timestamps pointing to the far future. To better understand the attack, consider a store node whose current clock shows 2021-01-01 00:00:30 (and assume all the other nodes have a synchronized clocks +-20seconds). The store node already has a list of messages, (m1,2021-01-01 00:00:00), (m2,2021-01-01 00:00:01), ..., (m10:2021-01-01 00:00:20), that are sorted based on their timestamp. An attacker sends a message with an arbitrary large timestamp e.g., 10 hours ahead of the correct clock (m',2021-01-01 10:00:30). The store node places m' at the end of the list, (m1,2021-01-01 00:00:00), (m2,2021-01-01 00:00:01), ..., (m10:2021-01-01 00:00:20), (m',2021-01-01 10:00:30). Now another message arrives with a valid timestamp e.g., (m11, 2021-01-01 00:00:45). However, since its timestamp precedes the malicious message m', it gets placed before m' in the list i.e., (m1,2021-01-01 00:00:00), (m2,2021-01-01 00:00:01), ..., (m10:2021-01-01 00:00:20), (m11, 2021-01-01 00:00:45), (m',2021-01-01 10:00:30). In fact, for the next 10 hours, m' will always be considered as the most recent message and served as the last message to the querying nodes irrespective of how many other messages arrive afterward.

A robust and verifiable timestamp allows the receiver of a message to verify that a message has been generated prior to the claimed timestamp. One solution is the use of open timestamps e.g., block height in Blockchain-based timestamps. That is, messages contain the most recent block height perceived by their senders at the time of message generation. This proves accuracy within a range of minutes (e.g., in Bitcoin blockchain) or seconds (e.g., in Ethereum 2.0) from the time of origination.

Copyright

Copyright and related rights waived via CC0.

Previous versions

• 00

References

1. 14/WAKU2-MESSAGE
2. protocol buffers v3
3. Open timestamps

13/WAKU2-STORE

Timeline

• 2026-06-16 — 16e8af1 — Chore/separate messaging specs (#361)
• 2026-05-11 — 1ac7689 — chore: split ift ts specs (#334)
• 2026-04-20 — c3d15a9 — COSS overhaul: new statuses, CFR type, raw-spec leniency (#308)
• 2026-02-09 — afd94c8 — chore: add math support (#287)
• 2026-01-16 — f01d5b9 — chore: fix links (#260)
• 2026-01-16 — 89f2ea8 — Chore/mdbook updates (#258)
• 2025-12-22 — 0f1855e — Chore/fix headers (#239)
• 2025-12-22 — b1a5783 — Chore/mdbook updates (#237)
• 2025-12-18 — d03e699 — ci: add mdBook configuration (#233)
• 2025-02-03 — a60a2c4 — 13/WAKU-STORE: Update (#124)
• 2024-09-13 — 3ab314d — Fix Files for Linting (#94)
• 2024-08-05 — eb25cd0 — chore: replace email addresses (#86)
• 2024-03-21 — 2eaa794 — Broken Links + Change Editors (#26)
• 2024-02-01 — 755be94 — Update and rename STORE.md to store.md
• 2024-01-27 — 3baed07 — Rename README.md to STORE.md
• 2024-01-27 — eef961b — remove rfs folder
• 2024-01-25 — 51e2879 — Create README.md

Abstract

This specification explains the 13/WAKU2-STORE protocol which enables querying of messages received through the relay protocol and stored by other nodes. It also supports pagination for more efficient querying of historical messages.

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

Terminology

The term PII, Personally Identifiable Information, refers to any piece of data that can be used to uniquely identify a user. For example, the signature verification key, and the hash of one's static IP address are unique for each user and hence count as PII.

Design Requirements

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC2119.

Nodes willing to provide the storage service using 13/WAKU2-STORE protocol, SHOULD provide a complete and full view of message history. As such, they are required to be highly available and specifically have a high uptime to consistently receive and store network messages. The high uptime requirement makes sure that no message is missed out hence a complete and intact view of the message history is delivered to the querying nodes. Nevertheless, in case storage provider nodes cannot afford high availability, the querying nodes may retrieve the historical messages from multiple sources to achieve a full and intact view of the past.

The concept of ephemeral messages introduced in 14/WAKU2-MESSAGE affects 13/WAKU2-STORE as well. Nodes running 13/WAKU2-STORE SHOULD support ephemeral messages as specified in 14/WAKU2-MESSAGE. Nodes running 13/WAKU2-STORE SHOULD NOT store messages with the ephemeral flag set to true.

Adversarial Model

Any peer running the 13/WAKU2-STORE protocol, i.e. both the querying node and the queried node, are considered as an adversary. Furthermore, we currently consider the adversary as a passive entity that attempts to collect information from other peers to conduct an attack but it does so without violating protocol definitions and instructions. As we evolve the protocol, further adversarial models will be considered. For example, under the passive adversarial model, no malicious node hides or lies about the history of messages as it is against the description of the 13/WAKU2-STORE protocol.

The following are not considered as part of the adversarial model:

• An adversary with a global view of all the peers and their connections.
• An adversary that can eavesdrop on communication links between arbitrary pairs of peers (unless the adversary is one end of the communication). In specific, the communication channels are assumed to be secure.

Wire Specification

Peers communicate with each other using a request / response API. The messages sent are Protobuf RPC messages which are implemented using protocol buffers v3. The following are the specifications of the Protobuf messages.

Payloads

syntax = "proto3";

message Index {
  bytes digest = 1;
  sint64 receiverTime = 2;
  sint64 senderTime = 3;
  string pubsubTopic = 4;
}

message PagingInfo {
  uint64 pageSize = 1;
  Index cursor = 2;
  enum Direction {
    BACKWARD = 0;
    FORWARD = 1;
  }
  Direction direction = 3;
}

message ContentFilter {
  string contentTopic = 1;
}

message HistoryQuery {
  // the first field is reserved for future use
  string pubsubtopic = 2;
  repeated ContentFilter contentFilters = 3;
  PagingInfo pagingInfo = 4;
}

message HistoryResponse {
  // the first field is reserved for future use
  repeated WakuMessage messages = 2;
  PagingInfo pagingInfo = 3;
  enum Error {
    NONE = 0;
    INVALID_CURSOR = 1;
  }
  Error error = 4;
}

message HistoryRPC {
  string request_id = 1;
  HistoryQuery query = 2;
  HistoryResponse response = 3;
}

Index

To perform pagination, each WakuMessage stored at a node running the 13/WAKU2-STORE protocol is associated with a unique Index that encapsulates the following parts.

• digest: a sequence of bytes representing the SHA256 hash of a WakuMessage. The hash is computed over the concatenation of contentTopic and payload fields of a WakuMessage (see 14/WAKU2-MESSAGE).
• receiverTime: the UNIX time in nanoseconds at which the WakuMessage is received by the receiving node.
• senderTime: the UNIX time in nanoseconds at which the WakuMessage is generated by its sender.
• pubsubTopic: the pubsub topic on which the WakuMessage is received.

PagingInfo

PagingInfo holds the information required for pagination. It consists of the following components.

• pageSize: A positive integer indicating the number of queried WakuMessages in a HistoryQuery (or retrieved WakuMessages in a HistoryResponse).
• cursor: holds the Index of a WakuMessage.
• direction: indicates the direction of paging which can be either FORWARD or BACKWARD.

ContentFilter

ContentFilter carries the information required for filtering historical messages.

• contentTopic represents the content topic of the queried historical WakuMessage. This field maps to the contentTopic field of the 14/WAKU2-MESSAGE.

HistoryQuery

RPC call to query historical messages.

• The pubsubTopic field MUST indicate the pubsub topic of the historical messages to be retrieved. This field denotes the pubsub topic on which WakuMessages are published. This field maps to topicIDs field of Message in 11/WAKU2-RELAY. Leaving this field empty means no filter on the pubsub topic of message history is requested. This field SHOULD be left empty in order to retrieve the historical WakuMessage regardless of the pubsub topics on which they are published.
• The contentFilters field MUST indicate the list of content filters based on which the historical messages are to be retrieved. Leaving this field empty means no filter on the content topic of message history is required. This field SHOULD be left empty in order to retrieve historical WakuMessage regardless of their content topics.
• PagingInfo holds the information required for pagination. Its pageSize field indicates the number of WakuMessages to be included in the corresponding HistoryResponse. It is RECOMMENDED that the queried node defines a maximum page size internally. If the querying node leaves the pageSize unspecified, or if the pageSize exceeds the maximum page size, the queried node SHOULD auto-paginate the HistoryResponse to no more than the configured maximum page size. This allows mitigation of long response time for HistoryQuery. In the forward pagination request, the messages field of the HistoryResponse SHALL contain, at maximum, the pageSize amount of WakuMessage whose Index values are larger than the given cursor (and vise versa for the backward pagination). Note that the cursor of a HistoryQuery MAY be empty (e.g., for the initial query), as such, and depending on whether the direction is BACKWARD or FORWARD the last or the first pageSize WakuMessage SHALL be returned, respectively.

Sorting Messages

The queried node MUST sort the WakuMessage based on their Index, where the senderTime constitutes the most significant part and the digest comes next, and then perform pagination on the sorted result. As such, the retrieved page contains an ordered list of WakuMessage from the oldest messages to the most recent one. Alternatively, the receiverTime (instead of senderTime) MAY be used to sort messages during the paging process. However, it is RECOMMENDED the use of the senderTime for sorting as it is invariant and consistent across all the nodes. This has the benefit of cursor reusability i.e., a cursor obtained from one node can be consistently used to query from another node. However, this cursor reusability does not hold when the receiverTime is utilized as the receiver time is affected by the network delay and nodes' clock asynchrony.

HistoryResponse

RPC call to respond to a HistoryQuery call.

• The messages field MUST contain the messages found, these are 14/WAKU2-MESSAGE types.
• PagingInfo holds the paging information based on which the querying node can resume its further history queries. The pageSize indicates the number of returned Waku messages (i.e., the number of messages included in the messages field of HistoryResponse). The direction is the same direction as in the corresponding HistoryQuery. In the forward pagination, the cursor holds the Index of the last message in the HistoryResponse messages (and the first message in the backward paging). Regardless of the paging direction, the retrieved messages are always sorted in ascending order based on their timestamp as explained in the sorting messagessection, that is, from the oldest to the most recent. The requester SHALL embed the returned cursor inside its next HistoryQuery to retrieve the next page of the 14/WAKU2-MESSAGE. The cursor obtained from one node SHOULD NOT be used in a request to another node because the result may be different.
• The error field contains information about any error that has occurred while processing the corresponding HistoryQuery. NONE stands for no error. This is also the default value. INVALID_CURSOR means that the cursor field of HistoryQuery does not match with the Index of any of the WakuMessage persisted by the queried node.

Security Consideration

The main security consideration to take into account while using this protocol is that a querying node have to reveal their content filters of interest to the queried node, hence potentially compromising their privacy.

Future Work

• Anonymous query: This feature guarantees that nodes can anonymously query historical messages from other nodes i.e., without disclosing the exact topics of 14/WAKU2-MESSAGE they are interested in. As such, no adversary in the 13/WAKU2-STORE protocol would be able to learn which peer is interested in which content filters i.e., content topics of 14/WAKU2-MESSAGE. The current version of the 13/WAKU2-STORE protocol does not provide anonymity for historical queries, as the querying node needs to directly connect to another node in the 13/WAKU2-STORE protocol and explicitly disclose the content filters of its interest to retrieve the corresponding messages. However, one can consider preserving anonymity through one of the following ways:
  • By hiding the source of the request i.e., anonymous communication. That is the querying node shall hide all its PII in its history request e.g., its IP address. This can happen by the utilization of a proxy server or by using Tor. Note that the current structure of historical requests does not embody any piece of PII, otherwise, such data fields must be treated carefully to achieve query anonymity.
  • By deploying secure 2-party computations in which the querying node obtains the historical messages of a certain topic, the queried node learns nothing about the query. Examples of such 2PC protocols are secure one-way Private Set Intersections (PSI).

• Robust and verifiable timestamps: Messages timestamp is a way to show that the message existed prior to some point in time. However, the lack of timestamp verifiability can create room for a range of attacks, including injecting messages with invalid timestamps pointing to the far future. To better understand the attack, consider a store node whose current clock shows 2021-01-01 00:00:30 (and assume all the other nodes have a synchronized clocks +-20seconds). The store node already has a list of messages, (m1,2021-01-01 00:00:00), (m2,2021-01-01 00:00:01), ..., (m10:2021-01-01 00:00:20), that are sorted based on their timestamp. An attacker sends a message with an arbitrary large timestamp e.g., 10 hours ahead of the correct clock (m',2021-01-01 10:00:30). The store node places m' at the end of the list,

(m1,2021-01-01 00:00:00), (m2,2021-01-01 00:00:01), ..., (m10:2021-01-01 00:00:20),(m',2021-01-01 10:00:30).

Now another message arrives with a valid timestamp e.g., (m11, 2021-01-01 00:00:45). However, since its timestamp precedes the malicious message m', it gets placed before m' in the list i.e.,

(m1,2021-01-01 00:00:00), (m2,2021-01-01 00:00:01), ..., (m10:2021-01-01 00:00:20), (m11, 2021-01-01 00:00:45), (m',2021-01-01 10:00:30).

In fact, for the next 10 hours, m' will always be considered as the most recent message and served as the last message to the querying nodes irrespective of how many other messages arrive afterward.

A robust and verifiable timestamp allows the receiver of a message to verify that a message has been generated prior to the claimed timestamp. One solution is the use of open timestamps e.g., block height in Blockchain-based timestamps. That is, messages contain the most recent block height perceived by their senders at the time of message generation. This proves accuracy within a range of minutes (e.g., in Bitcoin blockchain) or seconds (e.g., in Ethereum 2.0) from the time of origination.

Copyright

Copyright and related rights waived via CC0.

References

1. 14/WAKU2-MESSAGE
2. protocol buffers v3
3. 11/WAKU2-RELAY
4. Open timestamps

15/WAKU-BRIDGE

Timeline

• 2026-06-16 — 16e8af1 — Chore/separate messaging specs (#361)
• 2026-05-11 — 1ac7689 — chore: split ift ts specs (#334)
• 2026-04-20 — c3d15a9 — COSS overhaul: new statuses, CFR type, raw-spec leniency (#308)
• 2026-02-09 — afd94c8 — chore: add math support (#287)
• 2026-01-16 — f01d5b9 — chore: fix links (#260)
• 2026-01-16 — 89f2ea8 — Chore/mdbook updates (#258)
• 2025-12-22 — 0f1855e — Chore/fix headers (#239)
• 2025-12-22 — b1a5783 — Chore/mdbook updates (#237)
• 2025-12-18 — d03e699 — ci: add mdBook configuration (#233)
• 2025-01-28 — c3d5fe6 — 15/WAKU2-BRIDGE: Update (#113)
• 2024-09-13 — 3ab314d — Fix Files for Linting (#94)
• 2024-02-01 — d637b10 — Update and rename BRIDGE.md to bridge.md
• 2024-01-27 — 4bf2f6e — Rename README.md to BRIDGE.md
• 2024-01-27 — eef961b — remove rfs folder
• 2024-01-25 — f883f26 — Create README.md

Abstract

This specification describes how 6/WAKU1 traffic can be used with 10/WAKU2 networks.

Wire Format

The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in 2119.

A bridge requires supporting both Waku versions:

• 6/WAKU1 - using devp2p RLPx protocol
• 10/WAKU2 - using libp2p protocols

Publishing Packets

Packets received on 6/WAKU1 networks SHOULD be published just once on 10/WAKU2 networks. More specifically, the bridge SHOULD publish this through 11/WAKU2-RELAY (PubSub domain).

When publishing such packet, the creation of a new Message with a new WakuMessage as data field is REQUIRED. The data and topic field, from the 6/WAKU1 Envelope, MUST be copied to the payload and content_topic fields of the WakuMessage. See 14/WAKU2-MESSAGE for message format details. Other fields such as nonce, expiry and ttl will be dropped as they become obsolete in 10/WAKU2.

Before this is done, the usual envelope verification still applies:

• Expiry & future time verification
• PoW verification
• Size verification

Bridging SHOULD occur through the 11/WAKU2-RELAY, but it MAY also be done on other 10/WAKU2 protocols (e.g. 12/WAKU2-FILTER). The latter is however not advised as it will increase the complexity of the bridge and because of the Security Considerations explained further below.

Packets received on 10/WAKU2 networks, SHOULD be posted just once on 6/WAKU1 networks. The 14/WAKU2-MESSAGE contains only the payload and contentTopic fields. The bridge MUST create a new 6/WAKU1 Envelope and copy over the payload and contentFilter fields to the data and topic fields. Next, before posting on the network, the bridge MUST set a new expiry, ttl and do the PoW nonce calculation.

Security Considerations

As mentioned above, a bridge will be posting new 6/WAKU1 envelopes, which requires doing the PoW nonce calculation.

This could be a DoS attack vector, as the PoW calculation will make it more expensive to post the message compared to the original publishing on 10/WAKU2 networks. Low PoW setting will lower this problem, but it is likely that it is still more expensive.

For this reason, it is RECOMMENDED to run bridges independently of other nodes, so that a bridge that gets overwhelmed does not disrupt regular Waku v2 to v2 traffic.

Bridging functionality SHOULD also be carefully implemented so that messages do not bounce back and forth between the 10/WAKU2 and 6/WAKU1 networks. The bridge SHOULD properly track messages with a seen filter, so that no amplification occurs.

Copyright

Copyright and related rights waived via CC0.

References

• 6/WAKU1
• 10/WAKU2
• 11/WAKU2-RELAY
• 14/WAKU2-MESSAGE
• 12/WAKU2-FILTER

17/WAKU2-RLN-RELAY

Timeline

• 2026-06-16 — 16e8af1 — Chore/separate messaging specs (#361)
• 2026-05-11 — 1ac7689 — chore: split ift ts specs (#334)
• 2026-04-20 — c3d15a9 — COSS overhaul: new statuses, CFR type, raw-spec leniency (#308)
• 2026-02-09 — afd94c8 — chore: add math support (#287)
• 2026-01-16 — f01d5b9 — chore: fix links (#260)
• 2026-01-16 — 89f2ea8 — Chore/mdbook updates (#258)
• 2025-12-22 — 0f1855e — Chore/fix headers (#239)
• 2025-12-22 — b1a5783 — Chore/mdbook updates (#237)
• 2025-12-18 — d03e699 — ci: add mdBook configuration (#233)
• 2024-11-20 — 776c1b7 — rfc-index: Update (#110)
• 2024-09-13 — 3ab314d — Fix Files for Linting (#94)
• 2024-08-05 — eb25cd0 — chore: replace email addresses (#86)
• 2024-06-06 — 5064ded — Update 17/WAKU2-RLN-RELAY: Proof Size (#44)
• 2024-05-28 — 7b443c1 — 17/WAKU2-RLN-RELAY: Update (#32)
• 2024-03-21 — 2eaa794 — Broken Links + Change Editors (#26)
• 2024-02-01 — 244ea55 — Update and rename RLN-RELAY.md to rln-relay.md
• 2024-01-27 — 7bcefac — Rename README.md to RLN-RELAY.md
• 2024-01-27 — eef961b — remove rfs folder
• 2024-01-26 — 1ed5919 — Update README.md
• 2024-01-25 — 4b3b4e3 — Create README.md

Abstract

This specification describes the 17/WAKU2-RLN-RELAY protocol, which is an extension of 11/WAKU2-RELAY to provide spam protection using Rate Limiting Nullifiers (RLN).

The security objective is to contain spam activity in the 64/WAKU-NETWORK by enforcing a global messaging rate to all the peers. Peers that violate the messaging rate are considered spammers and their message is considered spam. Spammers are also financially punished and removed from the system.

Motivation

In open and anonymous p2p messaging networks, one big problem is spam resistance. Existing solutions, such as Whisper’s proof of work, are computationally expensive hence not suitable for resource-limited nodes. Other reputation-based approaches might not be desirable, due to issues around arbitrary exclusion and privacy.

We augment the 11/WAKU2-RELAY protocol with a novel construct of RLN to enable an efficient economic spam prevention mechanism that can be run in resource-constrained environments.

Specification

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in 2119.

Flow

The messaging rate is defined by the period which indicates how many messages can be sent in a given period. We define an epoch as unix_time / period . For example, if unix_time is 1644810116 and we set period to 30, then epoch is (unix_time/period) = 54827003.

NOTE: The epoch refers to the epoch in RLN and not Unix epoch. This means a message can only be sent every period, where the period is up to the application.

See section Recommended System Parameters for the RECOMMENDED method to set a sensible period value depending on the application. Peers subscribed to a spam-protected pubsubTopic are only allowed to send one message per epoch. The higher-level layers adopting 17/WAKU2-RLN-RELAY MAY choose to enforce the messaging rate for WakuMessages with a specific contentTopic published on a pubsubTopic.

Setup and Registration

A pubsubTopic that is spam-protected requires subscribed peers to form a RLN group.

• Peers MUST be registered to the RLN group to be able to publish messages.
• Registration MAY be moderated through a smart contract deployed on the Ethereum blockchain.

Each peer has an RLN key pair denoted by sk and pk.

• The secret key sk is secret data and MUST be persisted securely by the peer.
• The state of the membership contract SHOULD contain a list of all registered members' public identity keys i.e., pks.

For registration, a peer MUST create a transaction to invoke the registration function on the contract, which registers its pk in the RLN group.

• The transaction MUST transfer additional tokens to the contract to be staked. This amount is denoted by staked_fund and is a system parameter. The peer who has the secret key sk associated with a registered pk would be able to withdraw a portion reward_portion of the staked fund by providing valid proof.

reward_portion is also a system parameter.

NOTE: Initially sk is only known to its owning peer however, it may get exposed to other peers in case the owner attempts spamming the system i.e., sending more than one message per epoch.

An overview of registration is illustrated in Figure 1.

Publishing

To publish at a given epoch, the publishing peer proceeds based on the regular 11/WAKU2-RELAY protocol. However, to protect against spamming, each WakuMessage (which is wrapped inside the data field of a PubSub message) MUST carry a RateLimitProof with the following fields. Section Payload covers the details about the type and encoding of these fields.

• The merkle_root contains the root of the Merkle tree.
• The epoch represents the current epoch.
• The nullifier is an internal nullifier acting as a fingerprint that allows specifying whether two messages are published by the same peer during the same epoch.
• The nullifier is a deterministic value derived from sk and epoch therefore any two messages issued by the same peer (i.e., using the same sk) for the same epoch are guaranteed to have identical nullifiers.
• The share_x and share_y can be seen as partial disclosure of peer's sk for the intended epoch. They are derived deterministically from peer's sk and current epoch using Shamir secret sharing scheme.

If a peer discloses more than one such pair (share_x, share_y) for the same epoch, it would allow full disclosure of its sk and hence get access to its staked fund in the membership contract.

• The proof field is a zero-knowledge proof signifying that:

1. The message owner is the current member of the group i.e., the peer's identity commitment key, pk, is part of the membership group Merkle tree with the root merkle_root.
2. share_x and share_y are correctly computed.
3. The nullifier is constructed correctly. For more details about the proof generation check RLN The proof generation relies on the knowledge of two pieces of private information i.e., sk and authPath. The authPath is a subset of Merkle tree nodes by which a peer can prove the inclusion of its pk in the group.

The proof generation also requires a set of public inputs which are: the Merkle tree root merkle_root, the current epoch, and the message for which the proof is going to be generated. In 17/WAKU2-RLN-RELAY, the message is the concatenation of WakuMessage's payload filed and its contentTopic i.e., payload||contentTopic.

Group Synchronization

Proof generation relies on the knowledge of Merkle tree root merkle_root and authPath which both require access to the membership Merkle tree. Getting access to the Merkle tree can be done in various ways:

1. Peers construct the tree locally. This can be done by listening to the registration and deletion events emitted by the membership contract. Peers MUST update the local Merkle tree on a per-block basis. This is discussed further in the Merkle Root Validation section.

2. For synchronizing the state of slashed pks, disseminate such information through a pubsubTopic to which all peers are subscribed. A deletion transaction SHOULD occur on the membership contract. The benefit of an off-chain slashing is that it allows real-time removal of spammers as opposed to on-chain slashing in which peers get informed with a delay, where the delay is due to mining the slashing transaction.

For the group synchronization, one important security consideration is that peers MUST make sure they always use the most recent Merkle tree root in their proof generation. The reason is that using an old root can allow inference about the index of the user's pk in the membership tree hence compromising user privacy and breaking message unlinkability.

Routing

Upon the receipt of a PubSub message via 11/WAKU2-RELAY protocol, the routing peer parses the data field as a WakuMessage and gets access to the RateLimitProof field.
The peer then validates the RateLimitProof as explained next.

Epoch Validation

If the epoch attached to the WakuMessage is more than max_epoch_gap, apart from the routing peer's current epoch, then the WakuMessage MUST be discarded and considered invalid. This is to prevent a newly registered peer from spamming the system by messaging for all the past epochs. max_epoch_gap is a system parameter for which we provide some recommendations in section Recommended System Parameters.

Merkle Root Validation

The routing peers MUST check whether the provided Merkle root in the RateLimitProof is valid. It can do so by maintaining a local set of valid Merkle roots, which consist of acceptable_root_window_size past roots. These roots refer to the final state of the Merkle tree after a whole block consisting of group changes is processed. The Merkle roots are updated on a per-block basis instead of a per-event basis. This is done because if Merkle roots are updated on a per-event basis, some peers could send messages with a root that refers to a Merkle tree state that might get invalidated while the message is still propagating in the network, due to many registrations happening during this time frame. By updating roots on a per-block basis instead, we will have only one root update per-block processed, regardless on how many registrations happened in a block, and peers will be able to successfully propagate messages in a time frame corresponding to roughly the size of the roots window times the block mining time.

Atomic processing of the blocks are necessary so that even if the peer is unable to process one event, the previous roots remain valid, and can be used to generate valid RateLimitProof's.

This also allows peers which are not well connected to the network to be able to send messages, accounting for network delay. This network delay is related to the nature of asynchronous network conditions, which means that peers see membership changes asynchronously, and therefore may have differing local Merkle trees. See Recommended System Parameters on choosing an appropriate acceptable_root_window_size.

Proof Verification

The routing peers MUST check whether the zero-knowledge proof proof is valid. It does so by running the zk verification algorithm as explained in RLN. If proof is invalid then the message MUST be discarded.

Spam detection

To enable local spam detection and slashing, routing peers MUST record the nullifier, share_x, and share_y of incoming messages which are not discarded i.e., not found spam or with invalid proof or epoch. To spot spam messages, the peer checks whether a message with an identical nullifier has already been relayed.

1. If such a message exists and its share_x and share_y components are different from the incoming message, then slashing takes place. That is, the peer uses the share_x and share_y of the new message and the share'_x and share'_y of the old record to reconstruct the sk of the message owner. The sk then MAY be used to delete the spammer from the group and withdraw a portion reward_portion of its staked funds.
2. If the share_x and share_y fields of the previously relayed message are identical to the incoming message, then the message is a duplicate and MUST be discarded.
3. If none is found, then the message gets relayed.

An overview of the routing procedure and slashing is provided in Figure 2.

Payloads

Payloads are protobuf messages implemented using protocol buffers v3. Nodes MAY extend the 14/WAKU2-MESSAGE with a rate_limit_proof field to indicate that their message is not spam.

syntax = "proto3";

message RateLimitProof {
  bytes proof = 1;
  bytes merkle_root = 2;
  bytes epoch = 3;
  bytes share_x = 4;
  bytes share_y = 5;
  bytes nullifier = 6;
}

message WakuMessage {
  bytes payload = 1;
  string content_topic = 2;
  optional uint32 version = 3;
  optional sint64 timestamp = 10;
  optional bool ephemeral = 31;
  RateLimitProof rate_limit_proof = 21;
}

WakuMessage

rate_limit_proof holds the information required to prove that the message owner has not exceeded the message rate limit.

RateLimitProof

Below is the description of the fields of RateLimitProof and their types.

Recommended System Parameters

The system parameters are summarized in the following table, and the RECOMMENDED values for a subset of them are presented next.

Epoch Length

A sensible value for the period depends on the application for which the spam protection is going to be used. For example, while the period of 1 second i.e., messaging rate of 1 per second, might be acceptable for a chat application, might be too low for communication among Ethereum network validators. One should look at the desired throughput of the application to decide on a proper period value.

Maximum Epoch Gap

We discussed in the Routing section that the gap between the epoch observed by the routing peer and the one attached to the incoming message should not exceed a threshold denoted by max_epoch_gap. The value of max_epoch_gap can be measured based on the following factors.

• Network transmission delay Network_Delay: the maximum time that it takes for a message to be fully disseminated in the GossipSub network.
• Clock asynchrony Clock_Asynchrony: The maximum difference between the Unix epoch clocks perceived by network peers which can be due to clock drifts.

With a reasonable approximation of the preceding values, one can set max_epoch_gap as

max_epoch_gap where period is the length of the epoch in seconds. Network_Delay and Clock_Asynchrony MUST have the same resolution as period. By this formulation, max_epoch_gap indeed measures the maximum number of epochs that can elapse since a message gets routed from its origin to all the other peers in the network.

acceptable_root_window_size depends upon the underlying chain's average blocktime, block_time

The lower bound for the acceptable_root_window_size SHOULD be set as

Network_Delay MUST have the same resolution as block_time.

By this formulation, acceptable_root_window_size will provide a lower bound of how many roots can be acceptable by a routing peer.

The acceptable_root_window_size should indicate how many blocks may have been mined during the time it takes for a peer to receive a message. This formula represents a lower bound of the number of acceptable roots.

Copyright

Copyright and related rights waived via CC0.

References

1. 11/WAKU2-RELAY
2. 64/WAKU-NETWORK
3. RLN
4. 14/WAKU2-MESSAGE
5. RLN documentation
6. Public inputs to the RLN circuit
7. Shamir secret sharing scheme used in RLN
8. RLN internal nullifier

19/WAKU2-LIGHTPUSH

Timeline

• 2026-06-16 — 16e8af1 — Chore/separate messaging specs (#361)
• 2026-05-11 — 1ac7689 — chore: split ift ts specs (#334)
• 2026-05-08 — c0ef3b9 — Cleanup: rewrite specs-repo links in pre-existing messaging specs (#316)
• 2026-04-20 — c3d15a9 — COSS overhaul: new statuses, CFR type, raw-spec leniency (#308)
• 2026-02-09 — afd94c8 — chore: add math support (#287)
• 2026-01-16 — 89f2ea8 — Chore/mdbook updates (#258)
• 2025-12-22 — 0f1855e — Chore/fix headers (#239)
• 2025-12-22 — b1a5783 — Chore/mdbook updates (#237)
• 2025-12-18 — d03e699 — ci: add mdBook configuration (#233)
• 2024-11-20 — ff87c84 — Update Waku Links (#104)
• 2024-09-13 — 3ab314d — Fix Files for Linting (#94)
• 2024-03-21 — 2eaa794 — Broken Links + Change Editors (#26)
• 2024-02-01 — c88680a — Update and rename LIGHTPUSH.md to lightpush.md
• 2024-01-27 — f9efd29 — Rename README.md to LIGHTPUSH.md
• 2024-01-27 — eef961b — remove rfs folder
• 2024-01-25 — c90013b — Create README.md

Protocol identifier: /vac/waku/lightpush/2.0.0-beta1

Motivation and Goals

Light nodes with short connection windows and limited bandwidth wish to publish messages into the Waku network. Additionally, there is sometimes a need for confirmation that a message has been received "by the network" (here, at least one node).

19/WAKU2-LIGHTPUSH is a request/response protocol for this.

Payloads

syntax = "proto3";

message PushRequest {
    string pubsub_topic = 1;
    WakuMessage message = 2;
}

message PushResponse {
    bool is_success = 1;
    // Error messages, etc
    string info = 2;
}

message PushRPC {
    string request_id = 1;
    PushRequest request = 2;
    PushResponse response = 3;
}

Message Relaying

Nodes that respond to PushRequests MUST either relay the encapsulated message via 11/WAKU2-RELAY protocol on the specified pubsub_topic, or forward the PushRequest via 19/LIGHTPUSH on a WAKU2-DANDELION stem. If they are unable to do so for some reason, they SHOULD return an error code in PushResponse.

Security Considerations

Since this can introduce an amplification factor, it is RECOMMENDED for the node relaying to the rest of the network to take extra precautions. This can be done by rate limiting via 17/WAKU2-RLN-RELAY.

Note that the above is currently not fully implemented.

Copyright

Copyright and related rights waived via CC0.

References

• 11/WAKU2-RELAY
• WAKU2-DANDELION
• 17/WAKU2-RLN-RELAY

31/WAKU2-ENR

Timeline

• 2026-06-16 — 16e8af1 — Chore/separate messaging specs (#361)
• 2026-06-12 — 124f895 — chore: fix broken links (#357)
• 2026-05-11 — 1ac7689 — chore: split ift ts specs (#334)
• 2026-04-20 — c3d15a9 — COSS overhaul: new statuses, CFR type, raw-spec leniency (#308)
• 2026-04-15 — 5a3e844 — Chore/move repo into logos co (#312)
• 2026-02-09 — afd94c8 — chore: add math support (#287)
• 2026-01-16 — 89f2ea8 — Chore/mdbook updates (#258)
• 2025-12-22 — 0f1855e — Chore/fix headers (#239)
• 2025-12-22 — b1a5783 — Chore/mdbook updates (#237)
• 2025-12-18 — d03e699 — ci: add mdBook configuration (#233)
• 2025-10-16 — e4f5f28 — Update WAKU-ENR: Move to Draft (#180)

Abstract

This specification describes the usage of the ENR (Ethereum Node Records) format for 10/WAKU2 purposes. The ENR format is defined in EIP-778 [3].

This specification is an extension of EIP-778, ENR used in Waku MUST adhere to both EIP-778 and 31/WAKU2-ENR.

Motivation

EIP-1459 with the usage of ENR has been implemented [1] [2] as a discovery protocol for Waku.

EIP-778 specifies a number of pre-defined keys. However, the usage of these keys alone does not allow for certain transport capabilities to be encoded, such as Websocket. Currently, Waku nodes running in a browser only support websocket transport protocol. Hence, new ENR keys need to be defined to allow for the encoding of transport protocol other than raw TCP.

Usage of Multiaddr Format Rationale

One solution would be to define new keys such as ws to encode the websocket port of a node. However, we expect new transport protocols to be added overtime such as quic. Hence, this would only provide a short term solution until another specification would need to be added.

Moreover, secure websocket involves SSL certificates. SSL certificates are only valid for a given domain and ip, so an ENR containing the following information:

• secure websocket port
• ipv4 fqdn
• ipv4 address
• ipv6 address

Would carry some ambiguity: Is the certificate securing the websocket port valid for the ipv4 fqdn? the ipv4 address? the ipv6 address?

The 10/WAKU2 protocol family is built on the libp2p protocol stack. Hence, it uses multiaddr to format network addresses.

Directly storing one or several multiaddresses in the ENR would fix the issues listed above:

• multiaddr is self-describing and support addresses for any network protocol: No new specification would be needed to support encoding other transport protocols in an ENR.
• multiaddr contains both the host and port information, allowing the ambiguity previously described to be resolved.

Wire Format

multiaddrs ENR key

We define a multiaddrs key.

• The value MUST be a list of binary encoded multiaddr prefixed by their size.
• The size of the multiaddr MUST be encoded in a Big Endian unsigned 16-bit integer.
• The size of the multiaddr MUST be encoded in 2 bytes.
• The secp256k1 value MUST be present on the record; secp256k1 is defined in EIP-778 and contains the compressed secp256k1 public key.
• The node's peer id SHOULD be deduced from the secp256k1 value.
• The multiaddresses SHOULD NOT contain a peer id except for circuit relay addresses
• For raw TCP & UDP connections details, EIP-778 pre-defined keys SHOULD be used; The keys tcp, udp, ip (and tcp6, udp6, ip6 for IPv6) are enough to convey all necessary information;
• To save space, multiaddrs key SHOULD only be used for connection details that cannot be represented using the EIP-778 pre-defined keys.
• The 300 bytes size limit as defined by EIP-778 still applies; In practice, it is possible to encode 3 multiaddresses in ENR, more or less could be encoded depending on the size of each multiaddress.

Usage

Many connection types

Alice is a Waku node operator, she runs a node that supports inbound connection for the following protocols:

• TCP 10101 on 1.2.3.4
• UDP 20202 on 1.2.3.4
• TCP 30303 on 1234:5600:101:1::142
• UDP 40404 on 1234:5600:101:1::142
• Secure Websocket on wss://example.com:443/
• QUIC on quic://quic.example.com:443/
• A circuit relay address /ip4/1.2.3.4/tcp/55555/p2p/QmRelay/p2p-circuit/p2p/QmAlice

Alice SHOULD structure the ENR for her node as follows:

Where multiaddrs:

• | is the concatenation operator,
• len1 is the length of /dns4/example.com/tcp/443/wss byte representation,
• len2 is the length of /dns4/quic.examle.com/tcp/443/quic byte representation.
• len3 is the length of /ip4/1.2.3.4/tcp/55555/p2p/QmRelay byte representation. Notice that the /p2p-circuit component is not stored, but, since circuit relay addresses are the only one containing a p2p component, it's safe to assume that any address containing this component is a circuit relay address. Decoding this type of multiaddresses would require appending the /p2p-circuit component.

Raw TCP only

Bob is a node operator that runs a node that supports inbound connection for the following protocols:

• TCP 10101 on 1.2.3.4

Bob SHOULD structure the ENR for his node as follows:

As Bob's node's connection details can be represented with EIP-778's pre-defined keys only, it is not needed to use the multiaddrs key.

Limitations

Supported key type is secp256k1 only.

Support for other elliptic curve cryptography such as ed25519 MAY be used.

waku2 ENR key

We define a waku2 field key:

• The value MUST be an 8-bit flag field, where bits set to 1 indicate true and bits set to 0 indicate false for the relevant flags.
• The flag values already defined are set out below, with bit 7 the most significant bit and bit 0 the least significant bit.

• In the scheme above, the flags sync, lightpush, filter, store and relay correlates with support for protocols with the same name. If a protocol is not supported, the corresponding field MUST be set to false. Indicating positive support for any specific protocol is OPTIONAL, though it MAY be required by the relevant application or discovery process.
• Flags marked as undef is not yet defined. These SHOULD be set to false by default.

Key Usage

• A Waku node MAY choose to populate the waku2 field for enhanced discovery capabilities, such as indicating supported protocols. Such a node MAY indicate support for any specific protocol by setting the corresponding flag to true.
• Waku nodes that want to participate in Node Discovery Protocol v5 [4], however, MUST implement the waku2 key with at least one flag set to true.
• Waku nodes that discovered other participants using Discovery v5, MUST filter out participant records that do not implement this field or do not have at least one flag set to true.
• In addition, such nodes MAY choose to filter participants on specific flags (such as supported protocols), or further interpret the waku2 field as required by the application.

Copyright

Copyright and related rights waived via CC0.

References

• 1
• 2
• 3
• 4
• 5

33/WAKU2-DISCV5

Timeline

• 2026-06-16 — 16e8af1 — Chore/separate messaging specs (#361)
• 2026-05-11 — 1ac7689 — chore: split ift ts specs (#334)
• 2026-05-08 — c0ef3b9 — Cleanup: rewrite specs-repo links in pre-existing messaging specs (#316)
• 2026-04-20 — c3d15a9 — COSS overhaul: new statuses, CFR type, raw-spec leniency (#308)
• 2026-02-09 — afd94c8 — chore: add math support (#287)
• 2026-01-16 — f01d5b9 — chore: fix links (#260)
• 2026-01-16 — 89f2ea8 — Chore/mdbook updates (#258)
• 2025-12-22 — 0f1855e — Chore/fix headers (#239)
• 2025-12-22 — b1a5783 — Chore/mdbook updates (#237)
• 2025-12-18 — d03e699 — ci: add mdBook configuration (#233)
• 2025-04-29 — 5971166 — Update discv5.md (#139)
• 2024-11-20 — 87d4ff7 — Workflow Fix: markdown-lint (#111)
• 2024-11-20 — dcc579c — Update WAKU2-PEER-EXCHANGE: Move to draft (#7)
• 2024-11-20 — ff87c84 — Update Waku Links (#104)
• 2024-09-13 — 3ab314d — Fix Files for Linting (#94)
• 2024-03-21 — 2eaa794 — Broken Links + Change Editors (#26)
• 2024-02-01 — 38d68ce — Update discv5.md
• 2024-02-01 — b8f8d20 — Update and rename DISCV5.md to discv5.md
• 2024-01-27 — c6ef447 — Rename README.md to DISCV5.md
• 2024-01-27 — eef961b — remove rfs folder
• 2024-01-25 — 037474d — Create README.md

Abstract

33/WAKU2-DISCV5 specifies a modified version of Ethereum's Node Discovery Protocol v5 as a means for ambient node discovery. 10/WAKU2 uses the 33/WAKU2-DISCV5 ambient node discovery network for establishing a decentralized network of interconnected Waku2 nodes. In its current version, the 33/WAKU2-DISCV5 discovery network is isolated from the Ethereum Discovery v5 network. Isolation improves discovery efficiency, which is especially significant with a low number of Waku nodes compared to the total number of Ethereum nodes.

Disclaimer

This version of 33/WAKU2-DISCV5 has a focus on timely deployment of an efficient discovery method for 10/WAKU2. Establishing a separate discovery network is in line with this focus. However, we are aware of potential resilience problems (see section on security considerations) and are discussing and researching hybrid approaches.

Background and Rationale

11/WAKU2-RELAY assumes the existence of a network of Waku2 nodes. For establishing and growing this network, new nodes trying to join the Waku2 network need a means of discovering nodes within the network. 10/WAKU2 supports the following discovery methods in order of increasing decentralization

• hard coded bootstrap nodes
• DNS discovery (based on EIP-1459)
• 34/WAKU2-PEER-EXCHANGE
• 33/WAKU2-DISCV5 (specified in this document)

The purpose of ambient node discovery within 10/WAKU2 is discovering Waku2 nodes in a decentralized way. The unique selling point of 33/WAKU2-DISCV5 is its holistic view of the network, which allows avoiding hotspots and allows merging the network after a split. While the other methods provide either a fixed or local set of nodes, 33/WAKU2-DISCV5 can provide a random sample of Waku2 nodes. Future iterations of this document will add the possibility of efficiently discovering Waku2 nodes that have certain capabilities, e.g. holding messages of a certain time frame during which the querying node was offline.

Separate Discovery Network

w.r.t. Waku2 Relay Network

33/WAKU2-DISCV5 spans an overlay network separate from the GossipSub network 11/WAKU2-RELAY builds on. Because it is a P2P network on its own, it also depends on bootstrap nodes. Having a separate discovery network reduces load on the bootstrap nodes, because the actual work is done by randomly discovered nodes. This also increases decentralization.

w.r.t. Ethereum Discovery v5

33/WAKU2-DISCV5 spans a discovery network isolated from the Ethereum Discovery v5 network.

Another simple solution would be taking part in the Ethereum Discovery network, and filtering Waku nodes based on whether they support WAKU2-ENR. This solution is more resilient towards eclipse attacks. However, this discovery method is very inefficient for small percentages of Waku nodes (see estimation). It boils down to random walk discovery and does not offer a O(log(n)) hop bound. The rarer the requested property (in this case Waku), the longer a random walk will take until finding an appropriate node, which leads to a needle-in-the-haystack problem. Using a dedicated Waku2 discovery network, nodes can query this discovery network for a random set of nodes and all (well-behaving) returned nodes can serve as bootstrap nodes for other Waku2 protocols.

A more sophisticated solution would be using Discv5 topic discovery. However, in its current state it also has efficiency problems for small percentages of Waku nodes and is still in the design phase (see here).

Currently, the Ethereum discv5 network is very efficient in finding other discv5 nodes, but it is not so efficient for finding discv5 nodes that have a specific property or offer specific services, e.g. Waku.

As part of our discv5 roadmap, we consider two ideas for future versions of 33/WAKU2-DISCV5

• Discv5 topic discovery with adjustments (ideally upstream)
• a hybrid solution that uses both a separate discv5 network and a Waku-ENR-filtered Ethereum discv5 network

Semantics

33/WAKU2-DISCV5 fully inherits the discv5 semantics.

Before announcing their address via Waku2 discv5, nodes SHOULD check if this address is publicly reachable. Nodes MAY use the libp2p AutoNAT protocol to perform that check. Nodes SHOULD only announce publicly reachable addresses via Waku2 discv5, to avoid cluttering peer lists with nodes that are not reachable.

Wire Format Specification

33/WAKU2-DISCV5 inherits the discv5 wire protocol except for the following differences

WAKU2-Specific protocol-id

Ethereum discv5:

header        = static-header || authdata
static-header = protocol-id || version || flag || nonce || authdata-size
protocol-id   = <b>"discv5"</b>
version       = 0x0001
authdata-size = uint16    -- byte length of authdata
flag          = uint8     -- packet type identifier
nonce         = uint96    -- nonce of message

33/WAKU2-DISCV5:

kcode>
header        = static-header || authdata
static-header = protocol-id || version || flag || nonce || authdata-size
protocol-id   = <b>"d5waku"</b>
version       = 0x0001
authdata-size = uint16    -- byte length of authdata
flag          = uint8     -- packet type identifier
nonce         = uint96    -- nonce of message

Suggestions for Implementations

Existing discv5 implementations

• can be augmented to make the protocol-id selectable using a compile-time flag as in this feature branch of nim-eth/discv5.
• can be forked followed by changing the protocol-id string as in go-waku.

Security Considerations

Sybil attack

Implementations should limit the number of bucket entries that have the same network parameters (IP address / port) to mitigate Sybil attacks.

Eclipse attack

Eclipse attacks aim to eclipse certain regions in a DHT. Malicious nodes provide false routing information for certain target regions. The larger the desired eclipsed region, the more resources (i.e. controlled nodes) the attacker needs. This introduces an efficiency versus resilience tradeoff. Discovery is more efficient if information about target objects (e.g. network parameters of nodes supporting Waku) are closer to a specific DHT address. If nodes providing specific information are closer to each other, they cover a smaller range in the DHT and are easier to eclipse.

Sybil attacks greatly increase the power of eclipse attacks, because they significantly reduce resources necessary to mount a successful eclipse attack.

Security Implications of a Separate Discovery Network

A dedicated Waku discovery network is more likely to be subject to successful eclipse attacks (and to DoS attacks in general). This is because eclipsing in a smaller network requires less resources for the attacker. DoS attacks render the whole network unusable if the percentage of attacker nodes is sufficient.

Using random walk discovery would mitigate eclipse attacks targeted at specific capabilities, e.g. Waku. However, this is because eclipse attacks aim at the DHT overlay structure, which is not used by random walks. So, this mitigation would come at the cost of giving up overlay routing efficiency. The efficiency loss is especially severe with a relatively small number of Waku nodes.

Properly protecting against eclipse attacks is challenging and raises research questions that we will address in future stages of our discv5 roadmap.

References

1. 10/WAKU2
2. 34/WAKU2-PEER-EXCHANGE
3. 11/WAKU2-RELAY
4. WAKU2-ENR
5. Node Discovery Protocol v5 (discv5)
6. discv5 semantics.
7. discv5 wire protocol
8. discv5 topic discovery
9. libp2p AutoNAT protocol
10. EIP-1459
11. GossipSub
12. Waku discv5 roadmap discussion
13. discovery efficiency estimation
14. implementation: Nim
15. implementation: Go

Copyright

Copyright and related rights waived via CC0.

34/WAKU2-PEER-EXCHANGE

Timeline

• 2026-06-16 — 16e8af1 — Chore/separate messaging specs (#361)
• 2026-05-11 — 1ac7689 — chore: split ift ts specs (#334)
• 2026-05-08 — c0ef3b9 — Cleanup: rewrite specs-repo links in pre-existing messaging specs (#316)
• 2026-04-20 — c3d15a9 — COSS overhaul: new statuses, CFR type, raw-spec leniency (#308)
• 2026-01-16 — f01d5b9 — chore: fix links (#260)
• 2026-01-16 — 89f2ea8 — Chore/mdbook updates (#258)
• 2025-12-22 — 0f1855e — Chore/fix headers (#239)
• 2025-12-22 — b1a5783 — Chore/mdbook updates (#237)
• 2025-12-18 — d03e699 — ci: add mdBook configuration (#233)
• 2024-12-07 — 2b297d5 — Update peer-exchange.md to fix a build error (#114)
• 2024-11-20 — 87d4ff7 — Workflow Fix: markdown-lint (#111)
• 2024-11-20 — dcc579c — Update WAKU2-PEER-EXCHANGE: Move to draft (#7)

Abstract

This document specifies a simple request-response peer exchange protocol. Responders send information about a requested number of peers. The main purpose of this protocol is providing resource restricted devices with peers.

Protocol Identifier

/vac/waku/peer-exchange/2.0.0-alpha1

Background and Motivation

It may not be feasible, on resource restricted devices, to take part in distributed random sampling ambient peer discovery protocols, such as 33/WAKU2-DISCV5. The Waku peer discovery protocol, specified in this document, allows resource restricted devices to request a list of peers from a service node. Network parameters necessary to connect to this service node COULD be learned from a static bootstrapping method or using EIP-1459: Node Discovery via DNS. The advantage of using Waku peer exchange to discover new peers, compared to relying on a static peer list or DNS discovery, is a more even load distribution. If a lot of resource restricted nodes would use the same service nodes as relay or store nodes, the load on these would be very high. Heavily used static nodes also add a centralized element. Downtime of such a node might significantly impact the network.

However, the resource efficiency of this protocol comes at an anonymity cost, which is explained in the Security/Privacy Considerations section. This protocol SHOULD only be used if 33/WAKU2-DISCV5 is infeasible.

Theory and Protocol Semantics

The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in 2119.

The peer exchange protocol, specified in this document, is a simple request-response protocol. As Figure 1 illustrates, the requesting node sends a request to a peer, which acts as the responder. The responder replies with a list of ENRs as specified in WAKU2-ENR. The multiaddresses used to connect to the respective peers can be extracted from the ENRs.

In order to protect its anonymity, the responder MUST NOT provide peers from its actively used peer list as this opens pathways to Neighbourhood Surveillance attacks, as described in the Security/Privacy Considerations Section. The responder SHOULD provide a set of peers that has been retrieved using ambient peer discovery methods supporting random sampling, e.g. 33/WAKU2-DISCV5. This both protects the responder's anonymity as well as helps distributing load.

To allow for fast responses, responders SHOULD retrieve peers unsolicited (before receiving a query) and maintain a queue of peers for the purpose of providing them in peer exchange responses. To get the best anonymity properties with respect to response peer sets, responders SHOULD use each of these peers only once.

To save bandwidth, and as a trade off to anonymity, responders MAY maintain a larger cache of exchange peers and randomly sample response sets from this local cache. The size of the cache SHOULD be large enough to allow randomly sampling peer sets that (on average) do not overlap too much. The responder SHOULD periodically replace the oldest peers in the cache. The RECOMMENDED options for the cache size are described in the Implementation Suggestions Section.

Requesters, in the context of the specified peer exchange protocol, SHOULD be resource restricted devices. While any node could technically act as a requester, using the peer exchange protocol comes with two drawbacks:

• reducing anonymity
• causing load on responder nodes

Wire Format Specification

syntax = "proto3";

message PeerInfo {
  bytes enr = 1;
}

message PeerExchangeQuery {
  uint64 num_peers = 1;
}

message PeerExchangeResponse {
  repeated PeerInfo peer_infos = 1;
}

message PeerExchangeRPC {
  PeerExchangeQuery query = 1;
  PeerExchangeResponse response = 2;
}

The enr field contains a Waku ENR as specified in WAKU2-ENR.

Requesters send a PeerExchangeQuery to a peer. Responders SHOULD include a maximum of num_peers PeerInfo instances into a response. Responders send a PeerExchangeResponse to requesters containing a list of PeerInfo instances, which in turn hold an ENR.

Implementation Suggestions

Discovery Interface

Implementations can implement the libp2p discovery interface:

• nim
• javascript.

Exchange Peer Cache Size

The size of the (optional) exchange peer cache discussed in Theory and Protocol Semantics depends on the average number of requested peers, which is expected to be the outbound degree of the underlying libp2p gossipsub mesh network. The RECOMMENDED value for this outbound degree is 6 (see parameter D in 29/WAKU2-CONFIG). It is RECOMMENDED for the cache to hold at least 10 times as many peers (60).

The RECCOMENDED cache size also depends on the number of requesters a responder is expected to serve within a refresh cycle. A refresh cycle is the time interval in which all peers in the cache are expected to be replaced. If the number of requests expected per refresh cycle exceeds 600 (10 times the above recommended 60), it is RECOMMENDED to increase the cache size to at least a tenth of that number.

Security Considerations

Privacy and Anonymity

The peer exchange protocol specified in this document comes with anonymity and security implications. We differentiate these implications into the requester and responder side, respectively.

Requester

With a simple peer exchange protocol, the requester is inherently susceptible to both neighbourhood surveillance and controlled neighbourhood attacks.

To mount a neighbourhood surveillance attack, an attacker has to connect to the peers of the victim node. The peer exchange protocol allows a malicious responder to easily get into this position. The responder connects to a set of peers and simply returns this set of peers to the requester.

The peer exchange protocol also makes it much easier to get into the position required for the controlled neighbourhood attack: A malicious responder provides controlled peers in the response peer list.

More on these attacks may be found in our research log article.

As a weak mitigation the requester MAY ask several peers and select a subset of the returned peers.

Responder

Responders that answer with active mesh peers are more vulnerable to a neighbourhood surveillance attack. Responding with the set of active mesh peers allows a malicious requester to get into the required position more easily. It takes away the first hurdle of the neighbourhood surveillance attack: The attacker knows which peers to try to connect to. This increased vulnerability can be avoided by only responding with randomly sampled sets of peers, e.g. by requesting a random peer set via 33/WAKU2-DISCV5. (As stated in the Theory and Protocol Semantics Section, these peer sets SHOULD be retrieved unsolicitedly before receiving requests to achieve faster response times.)

Responders are also susceptible to amplification DoS attacks. Requesters send a simple message request which causes responders to engage in ambient peer discovery to retrieve a new random peer set. As a mitigation, responders MAY feature a seen cache for requests and only answer once per time interval. The exchange-peer cache discussed in Theory and Protocol Semantics Section also provides mitigation. Still, frequent queries can tigger the refresh cycle more often. The seen cache MAY be used in conjunction to provide additional mitigation.

Further Considerations

The response field contains ENRs as specified in WAKU2-ENR. While ENRs contain signatures, they do not violate the Waku relay no-sign policy, because they are part of the discovery domain and are not propagated in the relay domain. However, there might still be some form of leakage: ENRs could be used to track peers and facilitate linking attacks. We will investigate this further in our Waku anonymity analysis.

Copyright

Copyright and related rights waived via CC0.

References

• 33/WAKU2-DISCV5
• EIP-1459: Node Discovery via DNS
• WAKU2-ENR
• multiaddress
• libp2p discovery interface in nim
• libp2p discovery interface in javascript
• libp2p gossipsub
• 29/WAKU2-CONFIG
• Waku Relay Anonymity
• Waku relay no-sign policy

36/WAKU2-BINDINGS-API

Timeline

• 2026-06-16 — 16e8af1 — Chore/separate messaging specs (#361)
• 2026-05-11 — 1ac7689 — chore: split ift ts specs (#334)
• 2026-04-20 — c3d15a9 — COSS overhaul: new statuses, CFR type, raw-spec leniency (#308)
• 2026-02-09 — afd94c8 — chore: add math support (#287)
• 2026-01-16 — 89f2ea8 — Chore/mdbook updates (#258)
• 2025-12-22 — 0f1855e — Chore/fix headers (#239)
• 2025-12-22 — b1a5783 — Chore/mdbook updates (#237)
• 2025-12-18 — d03e699 — ci: add mdBook configuration (#233)
• 2024-09-13 — 3ab314d — Fix Files for Linting (#94)
• 2024-03-21 — 2eaa794 — Broken Links + Change Editors (#26)
• 2024-02-28 — cb56103 — Update bindings-api.md
• 2024-02-01 — e9469d0 — Update and rename BINDINGS-API.md to bindings-api.md
• 2024-01-27 — 76e514a — Rename README.md to BINDINGS-API.md
• 2024-01-27 — eef961b — remove rfs folder
• 2024-01-25 — 6bd686d — Create README.md

Introduction

Native applications that wish to integrate Waku may not be able to use nwaku and its JSON RPC API due to constraints on packaging, performance or executables.

An alternative is to link existing Waku implementation as a static or dynamic library in their application.

This specification describes the C API that SHOULD be implemented by native Waku library and that SHOULD be used to consume them.

Design requirements

The API should be generic enough, so:

• it can be implemented by both nwaku and go-waku C-Bindings,
• it can be consumed from a variety of languages such as C#, Kotlin, Swift, Rust, C++, etc.

The selected format to pass data to and from the API is JSON.

It has been selected due to its widespread usage and easiness of use. Other alternatives MAY replace it in the future (C structure, protobuf) if it brings limitations that need to be lifted.

The API

General

WakuCallBack type

All the API functions require passing callbacks which will be executed depending on the result of the execution result. These callbacks are defined as

typedef void (*WakuCallBack) (const char* msg, size_t len_0);

With msg containing a \0 terminated string, and len_0 the length of this string. The format of the data sent to these callbacks will depend on the function being executed. The data can be characters, numeric or json.

Status Codes

The API functions return an integer with status codes depending on the execution result. The following status codes are defined:

• 0 - Success
• 1 - Error
• 2 - Missing callback

JsonMessage type

A Waku Message in JSON Format:

{
    payload: string;
    contentTopic: string;
    version: number;
    timestamp: number;
}

Fields:

• payload: base64 encoded payload, waku_utils_base64_encode can be used for this.
• contentTopic: The content topic to be set on the message.
• version: The Waku Message version number.
• timestamp: Unix timestamp in nanoseconds.

DecodedPayload type

A payload once decoded, used when a received Waku Message is encrypted:

interface DecodedPayload {
    pubkey?: string;
    signature?: string;
    data: string;
    padding: string;
  }

Fields:

• pubkey: Public key that signed the message (optional), hex encoded with 0x prefix,
• signature: Message signature (optional), hex encoded with 0x prefix,
• data: Decrypted message payload base64 encoded,
• padding: Padding base64 encoded.

FilterSubscription type

The criteria to create subscription to a light node in JSON Format:

{
    contentFilters: ContentFilter[];
    pubsubTopic: string?;
}

Fields:

• contentFilters: Array of ContentFilter being subscribed to / unsubscribed from.
• topic: Optional pubsub topic.

ContentFilter type

{
    contentTopic: string;
}

Fields:

• contentTopic: The content topic of a Waku message.

StoreQuery type

Criteria used to retrieve historical messages

interface StoreQuery {
    pubsubTopic?: string;
    contentFilters?: ContentFilter[];
    startTime?: number;
    endTime?: number;
    pagingOptions?: PagingOptions
  }

Fields:

• pubsubTopic: The pubsub topic on which messages are published.
• contentFilters: Array of ContentFilter to query for historical messages,
• startTime: The inclusive lower bound on the timestamp of queried messages. This field holds the Unix epoch time in nanoseconds.
• endTime: The inclusive upper bound on the timestamp of queried messages. This field holds the Unix epoch time in nanoseconds.
• pagingOptions: Paging information in PagingOptions format.

StoreResponse type

The response received after doing a query to a store node:

interface StoreResponse {
    messages: JsonMessage[];
    pagingOptions?: PagingOptions;
  }

Fields:

• messages: Array of retrieved historical messages in JsonMessage format.
• pagingOption: Paging information in PagingOptions format from which to resume further historical queries

PagingOptions type

interface PagingOptions {
    pageSize: number;
    cursor?: Index;
    forward: bool;
  }

Fields:

• pageSize: Number of messages to retrieve per page.
• cursor: Message Index from which to perform pagination. If not included and forward is set to true, paging will be performed from the beginning of the list. If not included and forward is set to false, paging will be performed from the end of the list.
• forward: true if paging forward, false if paging backward

Index type

interface Index {
    digest: string;
    receiverTime: number;
    senderTime: number;
    pubsubTopic: string;
  }

Fields:

• digest: Hash of the message at this Index.
• receiverTime: UNIX timestamp in nanoseconds at which the message at this Index was received.
• senderTime: UNIX timestamp in nanoseconds at which the message is generated by its sender.
• pubsubTopic: The pubsub topic of the message at this Index.

Events

Asynchronous events require a callback to be registered. An example of an asynchronous event that might be emitted is receiving a message. When an event is emitted, this callback will be triggered receiving a JSON string of type JsonSignal.

JsonSignal type

{
    type: string;
    event: any;
}

Fields:

• type: Type of signal being emitted. Currently, only message is available.
• event: Format depends on the type of signal.

For example:

{
  "type": "message",
  "event": {
    "pubsubTopic": "/waku/2/default-waku/proto",
    "messageId": "0x6496491e40dbe0b6c3a2198c2426b16301688a2daebc4f57ad7706115eac3ad1",
    "wakuMessage": {
      "payload": "TODO",
      "contentTopic": "/my-app/1/notification/proto",
      "version": 1,
      "timestamp": 1647826358000000000
    }
  }
}

JsonMessageEvent type

Type of event field for a message event:

{
    pubsubTopic: string;
    messageId: string;
    wakuMessage: JsonMessage;
}

• pubsubTopic: The pubsub topic on which the message was received.
• messageId: The message id.
• wakuMessage: The message in JsonMessage format.

waku_set_event_callback

extern void waku_set_event_callback(WakuCallBack cb){}

Register callback to act as event handler and receive application signals, which are used to react to asynchronous events in Waku.

Parameters

1. WakuCallBack cb: callback that will be executed when an async event is emitted.

Node management

JsonConfig type

Type holding a node configuration:

interface JsonConfig {
    host?: string;
    port?: number;
    advertiseAddr?: string;
    nodeKey?: string;
    keepAliveInterval?: number;
    relay?: boolean;
    relayTopics?: Array<string>;
    gossipsubParameters?: GossipSubParameters;
    minPeersToPublish?: number
    legacyFilter?: boolean;
    discV5?: boolean;
    discV5BootstrapNodes?: Array<string>;
    discV5UDPPort?: number;
    store?: boolean;
    databaseURL?: string;
    storeRetentionMaxMessages?: number;
    storeRetentionTimeSeconds?: number;
    websocket?: Websocket;
    dns4DomainName?: string;
}

Fields:

All fields are optional. If a key is undefined, or null, a default value will be set.

• host: Listening IP address. Default 0.0.0.0.
• port: Libp2p TCP listening port. Default 60000. Use 0 for random.
• advertiseAddr: External address to advertise to other nodes. Can be ip4, ip6 or dns4, dns6. If null, the multiaddress(es) generated from the ip and port specified in the config (or default ones) will be used. Default: null.
• nodeKey: Secp256k1 private key in Hex format (0x123...abc). Default random.
• keepAliveInterval: Interval in seconds for pinging peers to keep the connection alive. Default 20.
• relay: Enable relay protocol. Default true.
• relayTopics: Array of pubsub topics that WakuRelay will automatically subscribe to when the node starts Default []
• gossipSubParameters: custom gossipsub parameters. See GossipSubParameters section for defaults
• minPeersToPublish: The minimum number of peers required on a topic to allow broadcasting a message. Default 0.
• legacyFilter: Enable Legacy Filter protocol. Default false.
• discV5: Enable DiscoveryV5. Default false
• discV5BootstrapNodes: Array of bootstrap nodes ENR
• discV5UDPPort: UDP port for DiscoveryV5 Default 9000
• store: Enable store protocol to persist message history Default false
• databaseURL: url connection string. Accepts SQLite and PostgreSQL connection strings Default: sqlite3://store.db
• storeRetentionMaxMessages: max number of messages to store in the database. Default 10000
• storeRetentionTimeSeconds: max number of seconds that a message will be persisted in the database. Default 2592000 (30d)
• websocket: custom websocket support parameters. See Websocket section for defaults
• dns4DomainName: the domain name resolving to the node's public IPv4 address.

For example:

{
  "host": "0.0.0.0",
  "port": 60000,
  "advertiseAddr": "1.2.3.4",
  "nodeKey": "0x123...567",
  "keepAliveInterval": 20,
  "relay": true,
  "minPeersToPublish": 0
}

GossipsubParameters type

Type holding custom gossipsub configuration:

interface GossipSubParameters {
    D?: number;
    D_low?: number;
    D_high?: number;
    D_score?: number;
    D_out?: number;
    HistoryLength?: number;
    HistoryGossip?: number;
    D_lazy?: number;
    GossipFactor?: number;
    GossipRetransmission?: number;
    HeartbeatInitialDelayMs?: number;
    HeartbeatIntervalSeconds?: number;
    SlowHeartbeatWarning?: number;
    FanoutTTLSeconds?: number;
    PrunePeers?: number;
    PruneBackoffSeconds?: number;
    UnsubscribeBackoffSeconds?: number;
    Connectors?: number;
    MaxPendingConnections?: number;
    ConnectionTimeoutSeconds?: number;
    DirectConnectTicks?: number;
    DirectConnectInitialDelaySeconds?: number;
    OpportunisticGraftTicks?: number;
    OpportunisticGraftPeers?: number;
    GraftFloodThresholdSeconds?: number;
    MaxIHaveLength?: number;
    MaxIHaveMessages?: number;
    IWantFollowupTimeSeconds?: number;
}

Fields:

All fields are optional. If a key is undefined, or null, a default value will be set.

• d: optimal degree for a GossipSub topic mesh. Default 6
• dLow: lower bound on the number of peers we keep in a GossipSub topic mesh Default 5
• dHigh: upper bound on the number of peers we keep in a GossipSub topic mesh. Default 12
• dScore: affects how peers are selected when pruning a mesh due to over subscription. Default 4
• dOut: sets the quota for the number of outbound connections to maintain in a topic mesh. Default 2
• historyLength: controls the size of the message cache used for gossip. Default 5
• historyGossip: controls how many cached message ids we will advertise in IHAVE gossip messages. Default 3
• dLazy: affects how many peers we will emit gossip to at each heartbeat. Default 6
• gossipFactor: affects how many peers we will emit gossip to at each heartbeat. Default 0.25
• gossipRetransmission: controls how many times we will allow a peer to request the same message id through IWANT gossip before we start ignoring them. Default 3
• heartbeatInitialDelayMs: short delay in milliseconds before the heartbeat timer begins after the router is initialized. Default 100 milliseconds
• heartbeatIntervalSeconds: controls the time between heartbeats. Default 1 second
• slowHeartbeatWarning: duration threshold for heartbeat processing before emitting a warning. Default 0.1
• fanoutTTLSeconds: controls how long we keep track of the fanout state. Default 60 seconds
• prunePeers: controls the number of peers to include in prune Peer eXchange. Default 16
• pruneBackoffSeconds: controls the backoff time for pruned peers. Default 60 seconds
• unsubscribeBackoffSeconds: controls the backoff time to use when unsuscribing from a topic. Default 10 seconds
• connectors: number of active connection attempts for peers obtained through PX. Default 8
• maxPendingConnections: maximum number of pending connections for peers attempted through px. Default 128
• connectionTimeoutSeconds: timeout in seconds for connection attempts. Default 30 seconds
• directConnectTicks: the number of heartbeat ticks for attempting to reconnect direct peers that are not currently connected. Default 300
• directConnectInitialDelaySeconds: initial delay before opening connections to direct peers. Default 1 second
• opportunisticGraftTicks: number of heartbeat ticks for attempting to improve the mesh with opportunistic grafting. Default 60
• opportunisticGraftPeers: the number of peers to opportunistically graft. Default 2
• graftFloodThresholdSeconds: If a GRAFT comes before GraftFloodThresholdSeconds has elapsed since the last PRUNE, then there is an extra score penalty applied to the peer through P7. Default 10 seconds
• maxIHaveLength: max number of messages to include in an IHAVE message, also controls the max number of IHAVE ids we will accept and request with IWANT from a peer within a heartbeat. Default 5000
• maxIHaveMessages: max number of IHAVE messages to accept from a peer within a heartbeat. Default 10
• iWantFollowupTimeSeconds: Time to wait for a message requested through IWANT following an IHAVE advertisement. Default 3 seconds
• seenMessagesTTLSeconds: configures when a previously seen message ID can be forgotten about. Default 120 seconds

Websocket type

Type holding custom websocket support configuration:

interface Websocket {
    enabled?: bool;
    host?: string;
    port?: number;
    secure?: bool;
    certPath?: string;
    keyPath?: string;
}

Fields:

All fields are optional. If a key is undefined, or null, a default value will be set. If using secure websockets support, certPath and keyPath become mandatory attributes. Unless selfsigned certificates are used, it will probably make sense in the JsonConfiguration to specify the domain name used in the certificate in the dns4DomainName attribute.

• enabled: indicates if websockets support will be enabled Default false
• host: listening address for websocket connections Default 0.0.0.0
• port: TCP listening port for websocket connection (0 for random, binding to 443 requires root access) Default 60001, if secure websockets support is enabled, the default is 6443“
• secure: enable secure websockets support Default false
• certPath: secure websocket certificate path
• keyPath: secure websocket key path

waku_new

extern int waku_new(char* jsonConfig, WakuCallBack onErrCb){}

Instantiates a Waku node.

Parameters

1. char* jsonConfig: JSON string containing the options used to initialize a waku node. Type JsonConfig. It can be NULL to use defaults.
2. WakuCallBack onErrCb: WakuCallBack. Callback to be executed if the function fails

Returns

int with a status code. Possible values:

• 0 - The operation was completed successfuly.
• 1 - The operation failed for any reason. onErrCb will be executed with the reason the function execution failed.
• 2 - The function is missing the onErrCb callback

waku_start

extern int waku_start(WakuCallBack onErrCb){}

Starts a Waku node mounting all the protocols that were enabled during the Waku node instantiation.

Parameters

1. WakuCallBack onErrCb: callback to be executed if the function fails

Returns

int with a status code. Possible values:

• 0 - The operation was completed successfuly.
• 1 - The operation failed for any reason. onErrCb will be executed with the reason the function execution failed.
• 2 - The function is missing the onErrCb callback

waku_stop

extern int waku_stop(WakuCallBack onErrCb){}

Stops a Waku node.

Parameters

1. WakuCallBack onErrCb: callback to be executed if the function fails

Returns

int with a status code. Possible values:

• 0 - The operation was completed successfuly.
• 1 - The operation failed for any reason. onErrCb will be executed with the reason the function execution failed.
• 2 - The function is missing the onErrCb callback

waku_peerid

extern int waku_peerid(WakuCallBack onOkCb, WakuCallBack onErrCb){}

Get the peer ID of the waku node.

Parameters

1. WakuCallBack onOkCb: callback to be executed if the function is succesful
2. WakuCallBack onErrCb: callback to be executed if the function fails

Returns

int with a status code. Possible values:

• 0 - The operation was completed successfuly. onOkCb will receive the base58 encoded peer ID, for example QmWjHKUrXDHPCwoWXpUZ77E8o6UbAoTTZwf1AD1tDC4KNP
• 1 - The operation failed for any reason. onErrCb will be executed with the reason the function execution failed.
• 2 - The function is missing the onOkCb or onErrCb callback

waku_listen_addresses

extern int waku_listen_addresses(WakuCallBack onOkCb, WakuCallBack onErrCb){}

Get the multiaddresses the Waku node is listening to.

Parameters

1. WakuCallBack onOkCb: callback to be executed if the function is succesful
2. WakuCallBack onErrCb: callback to be executed if the function fails

Returns

int with a status code. Possible values:

• 0 - The operation was completed successfuly. onOkCb will receive a json array of multiaddresses. The multiaddresses are strings. For example:

[
    "/ip4/127.0.0.1/tcp/30303",
    "/ip4/1.2.3.4/tcp/30303",
    "/dns4/waku.node.example/tcp/8000/wss"
]

• 1 - The operation failed for any reason. onErrCb will be executed with the reason the function execution failed.
• 2 - The function is missing the onOkCb and onErrCb callback

Connecting to peers

waku_add_peer

extern int waku_add_peer(char* address, char* protocolId, WakuCallBack onOkCb, WakuCallBack onErrCb){}

Add a node multiaddress and protocol to the waku node's peerstore.

Parameters

1. char* address: A multiaddress (with peer id) to reach the peer being added.
2. char* protocolId: A protocol we expect the peer to support.
3. WakuCallBack onOkCb: callback to be executed if the function is succesful
4. WakuCallBack onErrCb: callback to be executed if the function fails

Returns

int with a status code. Possible values:

• 0 - The operation was completed successfuly. onOkCb will receive the base 58 peer ID of the peer that was added.
• 1 - The operation failed for any reason. onErrCb will be executed with the reason the function execution failed.
• 2 - The function is missing the onOkCb or onErrCb callback

waku_connect

extern int waku_connect(char* address, int timeoutMs, WakuCallBack onErrCb){}

Dial peer using a multiaddress.

Parameters

1. char* address: A multiaddress to reach the peer being dialed.
2. int timeoutMs: Timeout value in milliseconds to execute the call. If the function execution takes longer than this value, the execution will be canceled and an error returned. Use 0 for no timeout.
3. WakuCallBack onErrCb: callback to be executed if the function fails

Returns

int with a status code. Possible values:

• 0 - The operation was completed successfuly.
• 1 - The operation failed for any reason. onErrCb will be executed with the reason the function execution failed.
• 2 - The function is missing the onErrCb callback

waku_connect_peerid

extern int waku_connect_peerid(char* peerId, int timeoutMs, WakuCallBack onErrCb){}

Dial peer using its peer ID.

Parameters

1. char* peerID: Peer ID to dial. The peer must be already known. It must have been added before with waku_add_peer or previously dialed with waku_connect.
2. int timeoutMs: Timeout value in milliseconds to execute the call. If the function execution takes longer than this value, the execution will be canceled and an error returned. Use 0 for no timeout.
3. WakuCallBack onErrCb: callback to be executed if the function fails

Returns

int with a status code. Possible values:

• 0 - The operation was completed successfuly.
• 1 - The operation failed for any reason. onErrCb will be executed with the reason the function execution failed.
• 2 - The function is missing the onErrCb callback

waku_disconnect

extern int waku_disconnect(char* peerId, WakuCallBack onErrCb){}

Disconnect a peer using its peerID

Parameters

1. char* peerID: Peer ID to disconnect.
2. WakuCallBack onErrCb: callback to be executed if the function fails

Returns

int with a status code. Possible values:

• 0 - The operation was completed successfuly.
• 1 - The operation failed for any reason. onErrCb will be executed with the reason the function execution failed.
• 2 - The function is missing the onErrCb callback

waku_peer_cnt

extern int waku_peer_cnt(WakuCallBack onOkCb, WakuCallBack onErrCb){}

Get number of connected peers.

Parameters

1. WakuCallBack onOkCb: callback to be executed if the function is succesful
2. WakuCallBack onErrCb: callback to be executed if the function fails

Returns

int with a status code. Possible values:

• 0 - The operation was completed successfuly. onOkCb will receive the number of connected peers.
• 1 - The operation failed for any reason. onErrCb will be executed with the reason the function execution failed.
• 2 - The function is missing the onOkCb or onErrCb callback

waku_peers

extern int waku_peers(WakuCallBack onOkCb, WakuCallBack onErrCb){}

Retrieve the list of peers known by the Waku node.

Parameters

1. WakuCallBack onOkCb: callback to be executed if the function is succesful
2. WakuCallBack onErrCb: callback to be executed if the function fails

Returns

int with a status code. Possible values:

• 0 - The operation was completed successfuly. onOkCb will receive a json array with the list of peers. This list has this format:

[
  {
    "peerID": "16Uiu2HAmJb2e28qLXxT5kZxVUUoJt72EMzNGXB47RedcBafeDCBA",
    "protocols": [
      "/ipfs/id/1.0.0",
      "/vac/waku/relay/2.0.0",
      "/ipfs/ping/1.0.0"
    ],
    "addrs": [
      "/ip4/1.2.3.4/tcp/30303"
    ],
    "connected": true
  }
]

• 1 - The operation failed for any reason. onErrCb will be executed with the reason the function execution failed.
• 2 - The function is missing the onOkCb or onErrCb callback

Waku Relay

waku_content_topic

extern int waku_content_topic(char* applicationName, unsigned int applicationVersion, char* contentTopicName, char* encoding, WakuCallBack onOkCb){}

Create a content topic string according to RFC 23.

Parameters

1. char* applicationName
2. unsigned int applicationVersion
3. char* contentTopicName
4. char* encoding: depending on the payload, use proto, rlp or rfc26
5. WakuCallBack onOkCb: callback to be executed if the function is succesful

Returns

int with a status code. Possible values:

• 0 - The operation was completed successfuly. onOkCb will receive the content topic formatted according to RFC 23: /{application-name}/{version-of-the-application}/{content-topic-name}/{encoding}
• 1 - The operation failed for any reason.
• 2 - The function is missing the onOkCb callback

waku_pubsub_topic

extern int waku_pubsub_topic(char* name, char* encoding, WakuCallBack onOkCb){}

Create a pubsub topic string according to RFC 23.

Parameters

1. char* name
2. char* encoding: depending on the payload, use proto, rlp or rfc26
3. WakuCallBack onOkCb: callback to be executed if the function is succesful

Returns

int with a status code. Possible values:

• 0 - The operation was completed successfuly. onOkCb will get populated with a pubsub topic formatted according to RFC 23: /waku/2/{topic-name}/{encoding}
• 1 - The operation failed for any reason.
• 2 - The function is missing the onOkCb callback

waku_default_pubsub_topic

extern int waku_default_pubsub_topic(WakuCallBack onOkCb){}

Returns the default pubsub topic used for exchanging waku messages defined in RFC 10.

Parameters

1. WakuCallBack onOkCb: callback to be executed if the function is succesful

Returns

int with a status code. Possible values:

• 0 - The operation was completed successfuly. onOkCb will get populated with /waku/2/default-waku/proto
• 1 - The operation failed for any reason.
• 2 - The function is missing the onOkCb callback

waku_relay_publish

extern int waku_relay_publish(char* messageJson, char* pubsubTopic, int timeoutMs, WakuCallBack onOkCb, WakuCallBack onErrCb){}

Publish a message using Waku Relay.

Parameters

1. char* messageJson: JSON string containing the Waku Message as JsonMessage.
2. char* pubsubTopic: pubsub topic on which to publish the message. If NULL, it uses the default pubsub topic.
3. int timeoutMs: Timeout value in milliseconds to execute the call. If the function execution takes longer than this value, the execution will be canceled and an error returned. Use 0 for no timeout.
4. WakuCallBack onOkCb: callback to be executed if the function is succesful
5. WakuCallBack onErrCb: callback to be executed if the function fails

If the execution is successful, the result field contains the message ID.

Returns

int with a status code. Possible values:

• 0 - The operation was completed successfuly. onOkCb will get populated with the message ID
• 1 - The operation failed for any reason. onErrCb will be executed with the reason the function execution failed.
• 2 - The function is missing the onOkCb or onErrCb callback

waku_relay_enough_peers

extern int waku_relay_enough_peers(char* pubsubTopic, WakuCallBack onOkCb, WakuCallBack onErrCb){}

Determine if there are enough peers to publish a message on a given pubsub topic.

Parameters

1. char* pubsubTopic: Pubsub topic to verify. If NULL, it verifies the number of peers in the default pubsub topic.
2. WakuCallBack onOkCb: callback to be executed if the function is succesful
3. WakuCallBack onErrCb: callback to be executed if the function fails

Returns

int with a status code. Possible values:

• 0 - The operation was completed successfuly. onOkCb will receive a string boolean indicating whether there are enough peers, i.e. true or false
• 1 - The operation failed for any reason. onErrCb will be executed with the reason the function execution failed.
• 2 - The function is missing the onOkCb or onErrCb callback

waku_relay_subscribe

extern int waku_relay_subscribe(char* topic, WakuCallBack onErrCb){}

Subscribe to a Waku Relay pubsub topic to receive messages.

Parameters

1. char* topic: Pubsub topic to subscribe to. If NULL, it subscribes to the default pubsub topic.
2. WakuCallBack onErrCb: callback to be executed if the function fails

Returns

int with a status code. Possible values:

• 0 - The operation was completed successfuly.
• 1 - The operation failed for any reason. onErrCb will be executed with the reason the function execution failed.
• 2 - The function is missing the onErrCb callback

Events

When a message is received, a "message" event is emitted containing the message, pubsub topic, and node ID in which the message was received.

The event type is JsonMessageEvent.

For Example:

{
  "type": "message",
  "event": {
    "pubsubTopic": "/waku/2/default-waku/proto",
    "messageId": "0x6496491e40dbe0b6c3a2198c2426b16301688a2daebc4f57ad7706115eac3ad1",
    "wakuMessage": {
      "payload": "TODO",
      "contentTopic": "/my-app/1/notification/proto",
      "version": 1,
      "timestamp": 1647826358000000000
    }
  }
}

waku_relay_unsubscribe

extern int waku_relay_unsubscribe(char* topic, WakuCallBack onErrCb)

Closes the pubsub subscription to a pubsub topic. No more messages will be received from this pubsub topic.

Parameters

1. char* pusubTopic: Pubsub topic to unsubscribe from. If NULL, unsubscribes from the default pubsub topic.
2. WakuCallBack onErrCb: callback to be executed if the function fails

Returns

int with a status code. Possible values:

• 0 - The operation was completed successfuly.
• 1 - The operation failed for any reason.
• 2 - The function is missing the onErrCb callback

waku_relay_topics

extern int waku_relay_topics(WakuCallBack onOkCb, WakuCallBack onErrCb)

Get the list of subscribed pubsub topics in Waku Relay.

Parameters

1. WakuCallBack onOkCb: callback to be executed if the function is succesful
2. WakuCallBack onErrCb: callback to be executed if the function fails

Returns

int with a status code. Possible values:

• 0 - The operation was completed successfuly. onOkCb will receive a json array of pubsub topics i.e ["pubsubTopic1", "pubsubTopic2"]
• 1 - The operation failed for any reason. onErrCb will be executed with the reason the function execution failed.
• 2 - The function is missing the onOkCb or onErrCb callback

Waku Filter

waku_filter_subscribe

extern int waku_filter_subscribe(char* filterJSON, char* peerID, int timeoutMs, WakuCallBack onOkCb, WakuCallBack onErrCb)

Creates a subscription to a filter full node matching a content filter..

Parameters

1. char* filterJSON: JSON string containing the FilterSubscription to subscribe to.
2. char* peerID: Peer ID to subscribe to. The peer must be already known. It must have been added before with waku_add_peer or previously dialed with waku_connect_peer. Use NULL to automatically select a node.
3. int timeoutMs: Timeout value in milliseconds to execute the call. If the function execution takes longer than this value, the execution will be canceled and an error returned. Use 0 for no timeout.
4. WakuCallBack onOkCb: callback to be executed if the function is succesful
5. WakuCallBack onErrCb: callback to be executed if the function fails

Returns

int with a status code. Possible values:

• 0 - The operation was completed successfuly. onOkCb will receive the subscription details, for example:

{
  "peerID": "....",
  "pubsubTopic": "...",
  "contentTopics": [...]
}

• 1 - The operation failed for any reason. onErrCb will be executed with the reason the function execution failed.
• 2 - The function is missing the onOkCb or onErrCb callback

Events

When a message is received, a "message" event is emitted containing the message, pubsub topic, and node ID in which the message was received.

The event type is JsonMessageEvent.

For Example:

{
  "type": "message",
  "event": {
    "pubsubTopic": "/waku/2/default-waku/proto",
    "messageId": "0x6496491e40dbe0b6c3a2198c2426b16301688a2daebc4f57ad7706115eac3ad1",
    "wakuMessage": {
      "payload": "TODO",
      "contentTopic": "/my-app/1/notification/proto",
      "version": 1,
      "timestamp": 1647826358000000000
    }
  }
}

waku_filter_ping

extern int waku_filter_ping(char* peerID, int timeoutMs, WakuCallBack onErrCb){}

Used to know if a service node has an active subscription for this client

Parameters

1. char* peerID: Peer ID to check for an active subscription The peer must be already known. It must have been added before with waku_add_peer or previously dialed with waku_connect_peer.
2. int timeoutMs: Timeout value in milliseconds to execute the call. If the function execution takes longer than this value, the execution will be canceled and an error returned. Use 0 for no timeout.
3. WakuCallBack onErrCb: callback to be executed if the function fails

Returns

int with a status code. Possible values:

• 0 - The operation was completed successfuly.
• 1 - The operation failed for any reason. onErrCb will be executed with the reason the function execution failed.
• 2 - The function is missing the onErrCb callback

waku_filter_unsubscribe

extern int waku_filter_unsubscribe(filterJSON *C.char, char* peerID, int timeoutMs, WakuCallBack onErrCb){}

Sends a requests to a service node to stop pushing messages matching this filter to this client. It might be used to modify an existing subscription by providing a subset of the original filter criteria

Parameters

1. char* filterJSON: JSON string containing the FilterSubscription criteria to unsubscribe from
2. char* peerID: Peer ID to unsubscribe from The peer must be already known. It must have been added before with waku_add_peer or previously dialed with waku_connect_peer.
3. int timeoutMs: Timeout value in milliseconds to execute the call. If the function execution takes longer than this value, the execution will be canceled and an error returned. Use 0 for no timeout.
4. WakuCallBack onErrCb: callback to be executed if the function fails

Returns

int with a status code. Possible values:

• 0 - The operation was completed successfuly.
• 1 - The operation failed for any reason. onErrCb will be executed with the reason the function execution failed.
• 2 - The function is missing the onOkCb or onErrCb callback

waku_filter_unsubscribe_all

extern int waku_filter_unsubscribe_all(char* peerID, int timeoutMs, WakuCallBack onOkCb, WakuCallBack onErrCb){}

Sends a requests to a service node (or all service nodes) to stop pushing messages

Parameters

1. char* peerID: Peer ID to unsubscribe from The peer must be already known. It must have been added before with waku_add_peer or previously dialed with waku_connect_peer. Use NULL to unsubscribe from all peers with active subscriptions
2. int timeoutMs: Timeout value in milliseconds to execute the call. If the function execution takes longer than this value, the execution will be canceled and an error returned. Use 0 for no timeout.
3. WakuCallBack onOkCb: callback to be executed if the function is succesful
4. WakuCallBack onErrCb: callback to be executed if the function fails

Returns

int with a status code. Possible values:

• 0 - The operation was completed successfuly. onOkCb will receive an array with information about the state of each unsubscription attempt (one per peer)

[
  {
    "peerID": ....,
    "error": "" // Empty if succesful
  },
  ...
]

• 1 - The operation failed for any reason. onErrCb will be executed with the reason the function execution failed.
• 2 - The function is missing the onOkCb or onErrCb callback

Waku Legacy Filter

waku_legacy_filter_subscribe

extern int waku_legacy_filter_subscribe(char* filterJSON, char* peerID, int timeoutMs, WakuCallBack onErrCb){}

Creates a subscription in a lightnode for messages that matches a content filter and optionally a PubSub topic.

Parameters

1. char* filterJSON: JSON string containing the LegacyFilterSubscription to subscribe to.
2. char* peerID: Peer ID to subscribe to. The peer must be already known. It must have been added before with waku_add_peer or previously dialed with waku_connect_peer. Use NULL to automatically select a node.
3. int timeoutMs: Timeout value in milliseconds to execute the call. If the function execution takes longer than this value, the execution will be canceled and an error returned. Use 0 for no timeout.
4. WakuCallBack onErrCb: callback to be executed if the function fails

Returns

int with a status code. Possible values:

• 0 - The operation was completed successfuly.
• 1 - The operation failed for any reason. onErrCb will be executed with the reason the function execution failed.
• 2 - The function is missing the onErrCb callback

Events

When a message is received, a "message" event is emitted containing the message, pubsub topic, and node ID in which the message was received.

The event type is JsonMessageEvent.

For Example:

{
  "type": "message",
  "event": {
    "pubsubTopic": "/waku/2/default-waku/proto",
    "messageId": "0x6496491e40dbe0b6c3a2198c2426b16301688a2daebc4f57ad7706115eac3ad1",
    "wakuMessage": {
      "payload": "TODO",
      "contentTopic": "/my-app/1/notification/proto",
      "version": 1,
      "timestamp": 1647826358000000000
    }
  }
}

waku_legacy_filter_unsubscribe

extern int waku_legacy_filter_unsubscribe(char* filterJSON, int timeoutMs, WakuCallBack onErrCb){}

Removes subscriptions in a light node matching a content filter and, optionally, a PubSub topic.

Parameters

1. char* filterJSON: JSON string containing the LegacyFilterSubscription.
2. int timeoutMs: Timeout value in milliseconds to execute the call. If the function execution takes longer than this value, the execution will be canceled and an error returned. Use 0 for no timeout.
3. WakuCallBack onErrCb: callback to be executed if the function fails

Returns

int with a status code. Possible values:

• 0 - The operation was completed successfuly.
• 1 - The operation failed for any reason. onErrCb will be executed with the reason the function execution failed.
• 2 - The function is missing the onErrCb callback

Waku Lightpush

waku_lightpush_publish

extern int waku_lightpush_publish(char* messageJSON, char* topic, char* peerID, int timeoutMs, WakuCallBack onOkCb, WakuCallBack onErrCb){}

Publish a message using Waku Lightpush.

Parameters

1. char* messageJson: JSON string containing the Waku Message as JsonMessage.
2. char* pubsubTopic: pubsub topic on which to publish the message. If NULL, it uses the default pubsub topic.
3. char* peerID: Peer ID supporting the lightpush protocol. The peer must be already known. It must have been added before with waku_add_peer or previously dialed with waku_connect_peer. Use NULL to automatically select a node.
4. int timeoutMs: Timeout value in milliseconds to execute the call. If the function execution takes longer than this value, the execution will be canceled and an error returned. Use 0 for no timeout.
5. WakuCallBack onOkCb: callback to be executed if the function is succesful
6. WakuCallBack onErrCb: callback to be executed if the function fails

Note: messageJson.version is overwritten to 0.

Returns

int with a status code. Possible values:

• 0 - The operation was completed successfuly. onOkCb will receive the message ID
• 1 - The operation failed for any reason. onErrCb will be executed with the reason the function execution failed.
• 2 - The function is missing the onOkCb or onErrCb callback

Waku Store

waku_store_query

extern int waku_store_query(char* queryJSON, char* peerID, int timeoutMs, WakuCallBack onOkCb, WakuCallBack onErrCb){}

Retrieves historical messages on specific content topics. This method may be called with PagingOptions, to retrieve historical messages on a per-page basis. If the request included PagingOptions, the node must return messages on a per-page basis and include PagingOptions in the response. These PagingOptions must contain a cursor pointing to the Index from which a new page can be requested.

Parameters

1. char* queryJSON: JSON string containing the StoreQuery.
2. char* peerID: Peer ID supporting the store protocol. The peer must be already known. It must have been added before with waku_add_peer or previously dialed with waku_connect_peer.
3. int timeoutMs: Timeout value in milliseconds to execute the call. If the function execution takes longer than this value, the execution will be canceled and an error returned. Use 0 for no timeout.
4. WakuCallBack onOkCb: callback to be executed if the function is succesful
5. WakuCallBack onErrCb: callback to be executed if the function fails

Returns

int with a status code. Possible values:

• 0 - The operation was completed successfuly. onOkCb will receive a StoreResponse.
• 1 - The operation failed for any reason. onErrCb will be executed with the reason the function execution failed.
• 2 - The function is missing the onOkCb or onErrCb callback

waku_store_local_query

extern int waku_store_local_query(char* queryJSON, WakuCallBack onOkCb, WakuCallBack onErrCb){}

Retrieves locally stored historical messages on specific content topics. This method may be called with PagingOptions, to retrieve historical messages on a per-page basis. If the request included PagingOptions, the node must return messages on a per-page basis and include PagingOptions in the response. These PagingOptions must contain a cursor pointing to the Index from which a new page can be requested.

Parameters

1. char* queryJSON: JSON string containing the StoreQuery.
2. int timeoutMs: Timeout value in milliseconds to execute the call. If the function execution takes longer than this value, the execution will be canceled and an error returned. Use 0 for no timeout.
3. WakuCallBack onOkCb: callback to be executed if the function is succesful
4. WakuCallBack onErrCb: callback to be executed if the function fails

Returns

int with a status code. Possible values:

• 0 - The operation was completed successfuly. onOkCb will receive a StoreResponse.
• 1 - The operation failed for any reason. onErrCb will be executed with the reason the function execution failed.
• 2 - The function is missing the onOkCb or onErrCb callback

Encrypting messages

waku_encode_symmetric

extern int waku_encode_symmetric(char* messageJson, char* symmetricKey, char* optionalSigningKey, WakuCallBack onOkCb, WakuCallBack onErrCb){}

Encrypt a message using symmetric encryption and optionally sign the message

Parameters

1. char* messageJson: JSON string containing the Waku Message as JsonMessage.
2. char* symmetricKey: hex encoded secret key to be used for encryption.
3. char* optionalSigningKey: hex encoded private key to be used to sign the message.
4. WakuCallBack onOkCb: callback to be executed if the function is succesful
5. WakuCallBack onErrCb: callback to be executed if the function fails

Note: messageJson.version is overwritten to 1.

Returns

int with a status code. Possible values:

• 0 - The operation was completed successfuly. onOkCb will receive the encrypted waku message which can be broadcasted with relay or lightpush protocol publish functions.
• 1 - The operation failed for any reason. onErrCb will be executed with the reason the function execution failed.
• 2 - The function is missing the onOkCb or onErrCb callback

waku_encode_asymmetric

extern int waku_encode_asymmetric(char* messageJson, char* publicKey, char* optionalSigningKey, WakuCallBack onOkCb, WakuCallBack onErrCb){}

Encrypt a message using asymmetric encryption and optionally sign the message

Parameters

1. char* messageJson: JSON string containing the Waku Message as JsonMessage.
2. char* publicKey: hex encoded public key to be used for encryption.
3. char* optionalSigningKey: hex encoded private key to be used to sign the message.
4. WakuCallBack onOkCb: callback to be executed if the function is succesful
5. WakuCallBack onErrCb: callback to be executed if the function fails

Note: messageJson.version is overwritten to 1.

Returns

int with a status code. Possible values:

• 0 - The operation was completed successfuly. onOkCb will receive the encrypted waku message which can be broadcasted with relay or lightpush protocol publish functions.
• 1 - The operation failed for any reason. onErrCb will be executed with the reason the function execution failed.
• 2 - The function is missing the onOkCb or onErrCb callback

Decrypting messages

waku_decode_symmetric

extern int waku_decode_symmetric(char* messageJson, char* symmetricKey, WakuCallBack onOkCb, WakuCallBack onErrCb){}

Decrypt a message using a symmetric key

Parameters

1. char* messageJson: JSON string containing the Waku Message as JsonMessage.
2. char* symmetricKey: 32 byte symmetric key hex encoded.
3. WakuCallBack onOkCb: callback to be executed if the function is succesful
4. WakuCallBack onErrCb: callback to be executed if the function fails

Note: messageJson.version is expected to be 1.

Returns

int with a status code. Possible values:

• 0 - The operation was completed successfuly. onOkCb will receive the decoded payload as a DecodedPayload.

{
  "pubkey": "0x......",
  "signature": "0x....",
  "data": "...",
  "padding": "..."
}

• 1 - The operation failed for any reason. onErrCb will be executed with the reason the function execution failed.
• 2 - The function is missing the onOkCb or onErrCb callback

waku_decode_asymmetric

extern int waku_decode_asymmetric(char* messageJson, char* privateKey, WakuCallBack onOkCb, WakuCallBack onErrCb){}

Decrypt a message using a secp256k1 private key

Parameters

1. char* messageJson: JSON string containing the Waku Message as JsonMessage.
2. char* privateKey: secp256k1 private key hex encoded.
3. WakuCallBack onOkCb: callback to be executed if the function is succesful
4. WakuCallBack onErrCb: callback to be executed if the function fails

Note: messageJson.version is expected to be 1.

Returns

int with a status code. Possible values:

• 0 - The operation was completed successfuly. onOkCb will receive the decoded payload as a DecodedPayload.

{
  "pubkey": "0x......",
  "signature": "0x....",
  "data": "...",
  "padding": "..."
}

• 1 - The operation failed for any reason. onErrCb will be executed with the reason the function execution failed.
• 2 - The function is missing the onOkCb or onErrCb callback

DNS Discovery

waku_dns_discovery

extern int waku_dns_discovery(char* url, char* nameserver, int timeoutMs, WakuCallBack onOkCb, WakuCallBack onErrCb){}

Returns a list of multiaddress and enrs given a url to a DNS discoverable ENR tree

Parameters

1. char* url: URL containing a discoverable ENR tree
2. char* nameserver: The nameserver to resolve the ENR tree url. If NULL or empty, it will automatically use the default system dns.
3. int timeoutMs: Timeout value in milliseconds to execute the call. If the function execution takes longer than this value, the execution will be canceled and an error returned. Use 0 for no timeout.
4. WakuCallBack onOkCb: callback to be executed if the function is succesful
5. WakuCallBack onErrCb: callback to be executed if the function fails

Returns

int with a status code. Possible values:

• 0 - The operation was completed successfuly. onOkCb will receive an array objects describing the multiaddresses, enr and peerID each node found.

[
    {
        "peerID":"16Uiu2HAmPLe7Mzm8TsYUubgCAW1aJoeFScxrLj8ppHFivPo97bUZ",
        "multiaddrs":[
            "/ip4/134.209.139.210/tcp/30303/p2p/16Uiu2HAmPLe7Mzm8TsYUubgCAW1aJoeFScxrLj8ppHFivPo97bUZ",
            "/dns4/node-01.do-ams3.wakuv2.test.statusim.net/tcp/8000/wss/p2p/16Uiu2HAmPLe7Mzm8TsYUubgCAW1aJoeFScxrLj8ppHFivPo97bUZ"
        ],
        "enr":"enr:-M-4QCtJKX2WDloRYDT4yjeMGKUCRRcMlsNiZP3cnPO0HZn6IdJ035RPCqsQ5NvTyjqHzKnTM6pc2LoKliV4CeV0WrgBgmlkgnY0gmlwhIbRi9KKbXVsdGlhZGRyc7EALzYobm9kZS0wMS5kby1hbXMzLndha3V2Mi50ZXN0LnN0YXR1c2ltLm5ldAYfQN4DiXNlY3AyNTZrMaEDnr03Tuo77930a7sYLikftxnuG3BbC3gCFhA4632ooDaDdGNwgnZfg3VkcIIjKIV3YWt1Mg8"
    },
    ...
]

• 1 - The operation failed for any reason. onErrCb will be executed with the reason the function execution failed.
• 2 - The function is missing the onOkCb or onErrCb callback

DiscoveryV5

waku_discv5_update_bootnodes

extern int waku_discv5_update_bootnodes(char* bootnodes, WakuCallBack onErrCb)`

Update the bootnode list used for discovering new peers via DiscoveryV5

Parameters

1. char* bootnodes: JSON array containing the bootnode ENRs i.e. ["enr:...", "enr:..."]
2. WakuCallBack onErrCb: callback to be executed if the function fails

Returns

int with a status code. Possible values:

• 0 - The operation was completed successfuly.
• 1 - The operation failed for any reason. onErrCb will be executed with the reason the function execution failed.
• 2 - The function is missing the onErrCb callback

Copyright

Copyright and related rights waived via CC0.

64/WAKU2-NETWORK

Timeline

• 2026-06-16 — 16e8af1 — Chore/separate messaging specs (#361)
• 2026-06-12 — 124f895 — chore: fix broken links (#357)
• 2026-05-11 — 1ac7689 — chore: split ift ts specs (#334)
• 2026-05-08 — c0ef3b9 — Cleanup: rewrite specs-repo links in pre-existing messaging specs (#316)
• 2026-04-20 — c3d15a9 — COSS overhaul: new statuses, CFR type, raw-spec leniency (#308)
• 2026-04-15 — 5a3e844 — Chore/move repo into logos co (#312)
• 2026-01-16 — f01d5b9 — chore: fix links (#260)
• 2026-01-16 — 89f2ea8 — Chore/mdbook updates (#258)
• 2025-12-22 — 0f1855e — Chore/fix headers (#239)
• 2025-12-22 — b1a5783 — Chore/mdbook updates (#237)
• 2025-12-18 — d03e699 — ci: add mdBook configuration (#233)
• 2025-02-25 — 0277fd0 — docs: update dead links in 64/Network (#133)
• 2024-09-13 — 3ab314d — Fix Files for Linting (#94)
• 2024-07-09 — 77029a2 — Add RLNv2 to TheWakuNetwork (#82)
• 2024-05-10 — e5b859a — Update WAKU2-NETWORK: Move to draft (#5)

Abstract

This specification describes an opinionated deployment of 10/WAKU2 protocols to form a coherent and shared decentralized messaging network that is open-access, useful for generalized messaging, privacy-preserving, scalable and accessible even to resource-restricted devices. We'll refer to this opinionated deployment simply as the public Waku Network, the Waku Network or, if the context is clear, the network in the rest of this document. All The Waku Network configuration parameters are listed here.

Theory / Semantics

Routing protocol

The Waku Network is built on the 17/WAKU2-RLN-RELAY routing protocol, which in turn is an extension of 11/WAKU2-RELAY with spam protection measures.

Network shards

Traffic in the Waku Network is sharded into eight 17/WAKU2-RLN-RELAY pubsub topics. Each pubsub topic is named according to the static shard naming format defined in WAKU2-RELAY-SHARDING with:

• <cluster_id> set to 1
• <shard_number> occupying the range 0 to 7. In other words, the Waku Network is a 17/WAKU2-RLN-RELAY network routed on the combination of the eight pubsub topics:

/waku/2/rs/1/0
/waku/2/rs/1/1
...
/waku/2/rs/1/7

A node MUST use 66/WAKU2-METADATA protocol to identify the <cluster_id> that every inbound/outbound peer that attempts to connect supports. In any of the following cases, the node MUST trigger a disconnection:

• 66/WAKU2-METADATA dial fails.
• 66/WAKU2-METADATA reports an empty <cluster_id>.
• 66/WAKU2-METADATA reports a <cluster_id> different than 1.

Roles

There are two distinct roles evident in the network, those of:

1. nodes, and
2. applications.

Nodes

Nodes are the individual software units using 10/WAKU2 protocols to form a p2p messaging network. Nodes, in turn, can participate in a shard as full relayers, i.e. relay nodes, or by running a combination of protocols suitable for resource-restricted environments, i.e. non-relay nodes. Nodes can also provide various services to the network, such as storing historical messages or protecting the network against spam. See the section on default services for more.

Relay nodes

Relay nodes MUST follow 17/WAKU2-RLN-RELAY to route messages to other nodes in the network for any of the pubsub topics defined as the Waku Network shards. Relay nodes MAY choose to subscribe to any of these shards, but MUST be subscribed to at least one defined shard. Each relay node SHOULD be subscribed to as many shards as it has resources to support. If a relay node supports an encapsulating application, it SHOULD be subscribed to all the shards servicing that application. If resource restrictions prevent a relay node from servicing all shards used by the encapsulating application, it MAY choose to support some shards as a non-relay node.

Bootstrapping and discovery

Nodes MAY use any method to bootstrap connection to the network, but it is RECOMMENDED that each node retrieves a list of bootstrap peers to connect to using EIP-1459 DNS-based discovery. Relay nodes SHOULD use 33/WAKU2-DISCV5 to continually discover other peers in the network. Each relay node MUST encode its supported shards into its discoverable ENR, as described in WAKU2-RELAY-SHARDING. The ENR MUST be updated if the set of supported shards change. A node MAY choose to ignore discovered peers that do not support any of the shards in its own subscribed set.

Transports

Relay nodes MUST follow 10/WAKU2 specifications with regards to supporting different transports. If TCP transport is available, each relay node MUST support it as transport for both dialing and listening. In addition, a relay node SHOULD support secure websockets for bidirectional communication streams, for example to allow connections from and to web browser-based clients. A relay node MAY support unsecure websockets if required by the application or running environment.

Default services

For each supported shard, each relay node SHOULD enable and support the following protocols as a service node:

1. 12/WAKU2-FILTER to allow resource-restricted peers to subscribe to messages matching a specific content filter.
2. 13/WAKU2-STORE to allow other peers to request historical messages from this node.
3. 19/WAKU2-LIGHTPUSH to allow resource-restricted peers to request publishing a message to the network on their behalf.
4. WAKU2-PEER-EXCHANGE to allow resource-restricted peers to discover more peers in a resource efficient way.

Store service nodes

Each relay node SHOULD support 13/WAKU2-STORE as a store service node, for each supported shard. The store SHOULD be configured to retain at least 12 hours of messages per supported shard. Store service nodes SHOULD only store messages with a valid rate_limit_proof attribute.

Non-relay nodes

Nodes MAY opt out of relay functionality on any network shard and instead request services from relay nodes as clients using any of the defined service protocols:

1. 12/WAKU2-FILTER to subscribe to messages matching a specific content filter.
2. 13/WAKU2-STORE to request historical messages matching a specific content filter.
3. 19/WAKU2-LIGHTPUSH to request publishing a message to the network.
4. WAKU2-PEER-EXCHANGE to discover more peers in a resource efficient way.

Store client nodes

Nodes MAY request historical messages from 13/WAKU2-STORE service nodes as store clients. A store client SHOULD discard any messages retrieved from a store service node that do not contain a valid rate_limit_proof attribute. The client MAY consider service nodes returning messages without a valid rate_limit_proof attribute as untrustworthy. The mechanism by which this may happen is currently underdefined.

Applications

Applications are the higher-layer projects or platforms that make use of the generalized messaging capability of the network. In other words, an application defines a payload used in the various 10/WAKU2 protocols. Any participant in an application SHOULD make use of an underlying node in order to communicate on the network. Applications SHOULD make use of an autosharding API to allow the underlying node to automatically select the target shard on the Waku Network. See the section on autosharding for more.

RLN rate-limiting

The 17/WAKU2-RLN-RELAY protocol uses RLN-V2 proofs to ensure that a pre-agreed rate limit of x messages every y seconds is not exceeded by any publisher. While the network is under capacity, individual relayers MAY choose to freely route messages without RLN proofs up to a discretionary bandwidth limit, after which messages without proofs MUST be discarded by relay nodes. This bandwidth limit SHOULD be enforced using a bandwidth validation mechanism separate from a RLN rate-limiting. This implies that quality of service and reliability is significantly lower for messages without proofs and at times of high network utilization these messages may not be relayed at all.

RLN Parameters

The Waku Network uses the following RLN parameters:

• rlnRelayUserMessageLimit=100: Amount of messages that a membership is allowed to publish per epoch. Configurable between 0 and MAX_MESSAGE_LIMIT.
• rlnEpochSizeSec=600: Size of the epoch in seconds.
• rlnRelayChainId=11155111: Network in which the RLN contract is deployed, aka Sepolia.
• rlnRelayEthContractAddress=0xCB33Aa5B38d79E3D9Fa8B10afF38AA201399a7e3: Network address where RLN memberships are stored.
• staked_fund=0: In other words, the Waku Network does not use RLN staking. Registering a membership just requires to pay gas.
• MAX_MESSAGE_LIMIT=100: Maximum amount of messages allowed per epoch for any membership. Enforced in the contract.
• max_epoch_gap=20: Maximum allowed gap in seconds into the past or future compared to the validator's clock.

Nodes MUST reject messages not respecting any of these parameters. Nodes SHOULD use Network Time Protocol (NTP) to synchronize their own clocks, thereby ensuring valid timestamps for proof generation and validation. Publishers to the Waku Network SHOULD register an RLN membership.

RLN Proofs

Each RLN member MUST generate and attach an RLN proof to every published message as described in 17/WAKU2-RLN-RELAY and RLN-V2. Slashing is not implemented for the Waku Network. Instead, validators will penalise peers forwarding messages exceeding the rate limit as specified for the rate-limiting validation mechanism. This incentivizes all relay nodes to validate RLN proofs and reject messages violating rate limits in order to continue participating in the network.

Network traffic

All payload on the Waku Network MUST be encapsulated in a 14/WAKU2-MESSAGE with rate limit proof extensions defined for 17/WAKU2-RLN-RELAY. Each message on the Waku Network SHOULD be validated by each relayer, according to the rules discussed under message validation.

Message Attributes

• The mandatory payload attribute MUST contain the message data payload as crafted by the application.
• The mandatory content_topic attribute MUST specify a string identifier that can be used for content-based filtering. This is also crafted by the application. See Autosharding for more on the content topic format.
• The optional meta attribute MAY be omitted. If present, will form part of the message uniqueness vector described in 14/WAKU2-MESSAGE.
• The optional version attribute SHOULD be set to 0. It MUST be interpreted as 0 if not present.
• The mandatory timestamp attribute MUST contain the Unix epoch time at which the message was generated by the application. The value MUST be in nanoseconds. It MAY contain a fudge factor of up to 1 seconds in either direction to improve resistance to timing attacks.
• The optional ephemeral attribute MUST be set to true, if the message should not be persisted by the Waku Network.
• The optional rate_limit_proof attribute SHOULD be populated with the RLN proof as set out in RLN Proofs. Messages with this field unpopulated MAY be discarded from the network by relayers. This field MUST be populated if the message should be persisted by the Waku Network.

Message Size

Any 14/WAKU2-MESSAGE published to the network MUST NOT exceed an absolute maximum size of 150 kilobytes. This limit applies to the entire message after protobuf serialization, including attributes. It is RECOMMENDED not to exceed an average size of 4 kilobytes for 14/WAKU2-MESSAGE published to the network.

Message Validation

Relay nodes MUST apply gossipsub v1.1 validation to each relayed message and SHOULD apply all of the rules set out in the section below to determine the validity of a message. Validation has one of three outcomes, repeated here from the gossipsub specification for ease of reference:

1. Accept - the message is considered valid and it MUST be delivered and forwarded to the network.
2. Reject - the message is considered invalid, MUST be rejected and SHOULD trigger a gossipsub scoring penalty against the transmitting peer.
3. Ignore - the message SHOULD NOT be delivered and forwarded to the network, but this MUST NOT trigger a gossipsub scoring penalty against the transmitting peer.

The following validation rules are defined:

Decoding failure

If a message fails to decode as a valid 14/WAKU2-MESSAGE, the relay node MUST reject the message. This SHOULD trigger a penalty against the transmitting peer.

Invalid timestamp

If a message has a timestamp deviating by more than 20 seconds either into the past or the future when compared to the relay node's internal clock, the relay node MUST reject the message. This allows for some deviation between internal clocks, network routing latency and an optional fudge factor when timestamping new messages.

Free bandwidth exceeded

If a message contains no RLN proof and the current bandwidth utilization on the shard the message was published to equals or exceeds 1 Mbps, the relay node SHOULD ignore the message.

Invalid RLN epoch

If a message contains an RLN proof and the epoch attached to the proof deviates by more than max_epoch_gap seconds from the relay node's own epoch, the relay node MUST reject the message. max_epoch_gap is set to 20 seconds for the Waku Network.

Invalid RLN proof

If a message contains an RLN proof and the zero-knowledge proof is invalid according to the verification process described in RLN-V2, the relay node MUST ignore the message.

Rate limit exceeded

If a message contains an RLN proof and the relay node detects double signaling according to the verification process described in RLN-V2, the relay node MUST reject the message for violating the agreed rate limit of rlnRelayUserMessageLimit messages every rlnEpochSizeSec second. This SHOULD trigger a penalty against the transmitting peer.

Autosharding

Nodes in the Waku Network SHOULD allow encapsulating applications to use autosharding, as defined in WAKU2-RELAY-SHARDING by automatically determining the appropriate pubsub topic from the list of defined Waku Network shards. This allows the application to omit the target pubsub topic when invoking any Waku protocol function. Applications using autosharding MUST use content topics in the format defined in WAKU2-RELAY-SHARDING and SHOULD use the short length format:

/{application-name}/{version-of-the-application}/{content-topic-name}/{encoding}

When an encapsulating application makes use of autosharding the underlying node MUST determine the target pubsub topic(s) from the content topics provided by the application using the hashing mechanism defined in WAKU2-RELAY-SHARDING.

Copyright

Copyright and related rights waived via CC0.

References

• 10/WAKU2
• 17/WAKU2-RLN-RELAY
• 11/WAKU2-RELAY
• WAKU2-RELAY-SHARDING
• 66/WAKU2-METADATA
• EIP-1459 DNS-based discovery
• 33/WAKU2-DISCV5
• 12/WAKU2-FILTER
• 13/WAKU2-STORE
• 19/WAKU2-LIGHTPUSH
• 34/WAKU2-PEER-EXCHANGE
• 32/RLN-V1
• RLN-V2
• 14/WAKU2-MESSAGE
• gossipsub v1.1 validation
• WAKU2-RELAY-SHARDING
• The Waku Network Config