---
slug: 14
title: 14/WAKU2-MESSAGE
name: Waku v2 Message
status: draft
editor: Oskar Thorén <oskar@status.im>
contributors:
  - Sanaz Taheri <sanaz@status.im>
  - Aaryamann Challani <aaryamann@status.im>
---

This specification provides a way to encapsulate messages sent over Waku with specific information security goals.

# Motivation

When sending messages over Waku there are multiple concerns:
- We may have a separate encryption layer as part of our application
- We may want to provide efficient routing for resource restricted devices
- We may want to provide compatibility with Waku v1 envelopes
- We may want payloads to be encrypted by default
- We may want to provide unlinkability for metadata protection

This specification attempts to provide for these various requirements.

# WakuMessage

A `WakuMessage` is what is being passed around by the other protocols, such as WakuRelay, WakuStore, and WakuFilter.

The `payload` field SHOULD contain whatever payload is being sent. See section below on payload encryption.

The `contentTopic` field SHOULD be filled out to allow for content-based filtering.
See [12/WAKU2-FILTER](/spec/12) and [13/WAKU2-STORE](/spec/13) for more details.
To enable a bidirectional bridge with Waku v1 see [15/WAKU2-BRIDGE](/spec/15) for further requirements on this field.

The `version` field MAY be filled out to allow for various types of payload encryption.
Omitting it means the version is 0.

The `timestamp` field MAY be filled out to signify the time at which the message is generated by its sender. 
This field holds the Unix epoch time in nanoseconds. 
Omitting it means the timestamp is unspecified.

The `ephemeral` field MAY be set to signify the transient nature of the message.
If the message should be stored by the [store protocol](/spec/13), then this field MUST be set to `false`, which is equivalent to omitting the field.
If the message should not be stored by the [store protocol](/spec/13), then this field MUST be set to `true`.

See [13/WAKU2-STORE](/spec/13) for more details.

## Payloads

Payloads are implemented using [protocol buffers v3](https://developers.google.com/protocol-buffers/).

```protobuf
syntax = "proto3";

message WakuMessage {
  bytes payload = 1;
  string contentTopic = 2;
  uint32 version = 3;
  sint64 timestamp = 10;
  bool ephemeral = 31;
}
```

## Payload encryption

Payload encryption depends on the `version` field.

### Version 0

This indicates that the payload SHOULD be either unencrypted or that encryption is done at a separate layer outside of Waku.

### Version 1

This indicates that payloads MUST be encrypted using [WAKU2-PAYLOAD](/spec/26).

This provides for asymmetric and symmetric encryption.
Key agreement is out of band.
It also provides an encrypted signature and padding for some form of unlinkability.

### Version 2

This indicates that payloads MUST be encoded using [35/WAKU-NOISE](/spec/35).

This provides for symmetric encryption and
asymmetric key-exchange protocols.

# Differences from Whisper / Waku v1 envelopes

In Whisper and Waku v1, an envelope contains the following fields: `expiry, ttl, topic, data, nonce`.

Since Waku v2 is using libp2p PubSub, some of these fields can be dropped.
The previous `topic` field corresponds to `contentTopic`.
The previous `data` field corresponds to the `payload` field.

# Security Consideration

## Confidentiality, integrity, and authenticity 
It is up to the application layer as to what level confidentiality, integrity and authenticity of the `payload` of `WakuMessage` matters. 
Accordingly, the application layer shall utilize the encryption and signature schemes supported in WAKU2 to meet the application-specific privacy needs.
The set of supported schemes in WAKU2 is presented in [WAKU2-PAYLOAD](/spec/26).

## Reliability of the WakuMessage timestamp

The `timestamp` field in `WakuMessage` is set by the sender.
Because `timestamp` isn't independently verified, this field is prone to exploit and misuse.
It should not solely be relied upon for operations such as message ordering.

For example, a malicious node can arbitrarily set the  `timestamp` of a `WakuMessage` to a high value so that it always shows up as the most recent message in a chat application.
Applications using the `WakuMessage`'s `timestamp` field are recommended to use additional methods for more robust message ordering.
An example of how to deal with message ordering against adversarial message timestamps can be found in the Status protocol, see [6/PAYLOADS](https://specs.status.im/spec/6#clock-vs-timestamp-and-message-ordering).

## Reliability of the ephemeral flag

The `ephemeral` field in `WakuMessage` is set by the sender.
Since there is currently no incentive mechanism for nodes that implement [13/WAKU2-STORE](/spec/13) and [11/WAKU2-RELAY](/spec/11) to behave correctly, this field is inherently unsecure.
Malicious nodes that implement [11/WAKU2-RELAY](/spec/11) can flip the value of the ephemeral flag, and nodes that receive such messages would have no mechanism to verify the integrity of the message.

# Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).