2020-09-30 04:14:31 +00:00
---
title: Waku Message
2020-10-22 10:29:05 +00:00
version: 2.0.0-beta1
status: Draft
2020-09-30 04:14:31 +00:00
authors: Oskar Thorén < oskar @ status . im >
---
# Table of Contents
- [Abstract ](#abstract )
- [Motivation ](#motivation )
2020-10-22 10:29:05 +00:00
- [WakuMessage ](#wakumessage )
- [Protobuf ](#protobuf )
- [Payload encryption ](#payload-encryption )
- [Version 0 ](#version-0 )
- [Version 1 ](#version-1 )
2020-09-30 04:14:31 +00:00
- [Differences from Whisper / Waku v1 envelopes ](#differences-from-whisper--waku-v1-envelopes )
- [Changelog ](#changelog )
- [Copyright ](#copyright )
# Abstract
This specification provides a way to encapsulate messages sent over Waku with specific information security goals.
# Motivation
When using Waku to send 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.
2020-10-22 10:29:05 +00:00
# WakuMessage
2020-09-30 04:14:31 +00:00
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 [Waku Filter spec ](waku-filter.md ) for details.
The `version` field MAY be filled out to allow for various types of payload encryption. Omitting it means the version is 0.
## Protobuf
```protobuf
message WakuMessage {
optional bytes payload = 1;
2020-10-20 02:22:42 +00:00
optional fixed32 contentTopic = 2;
2020-11-03 12:10:24 +00:00
optional uint32 version = 3;
2020-09-30 04:14:31 +00:00
}
```
## 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.
2020-10-22 10:29:05 +00:00
### Version 1 (not yet implemented in Waku v2)
2020-09-30 04:14:31 +00:00
This indicates that payloads MUST be encrypted using [Waku v1 envelope data
format spec](../v1/envelope-data-format.md).
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.
# 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.
# Changelog
2020-10-22 10:34:07 +00:00
Initial release on [2020-10-22 ](https://github.com/vacp2p/specs/pull/222/commits/dbab6c7084b414b62818150588266abedd09315f ).
2020-09-30 04:14:31 +00:00
# Copyright
Copyright and related rights waived via
[CC0 ](https://creativecommons.org/publicdomain/zero/1.0/ ).
