From 8693a311f0338ad75bb671a9a092a34f4600700d Mon Sep 17 00:00:00 2001 From: Jimmy Debe <91767824+jimstir@users.noreply.github.com> Date: Thu, 26 Dec 2024 14:44:17 -0500 Subject: [PATCH 1/6] Update message.md --- waku/standards/core/14/message.md | 80 +++++++++++++++++-------------- 1 file changed, 45 insertions(+), 35 deletions(-) diff --git a/waku/standards/core/14/message.md b/waku/standards/core/14/message.md index af30ee57..a64ba4fe 100644 --- a/waku/standards/core/14/message.md +++ b/waku/standards/core/14/message.md @@ -16,14 +16,16 @@ contributors: ## Abstract -Waku v2 is a family of modular peer-to-peer protocols for secure communication. +[10/WAKU2](/waku/standards/core/10/waku2.md) is a family of modular peer-to-peer protocols +for secure communication. These protocols are designed to be secure, privacy-preserving, and censorship-resistant and can run in resource-restricted environments. -At a high level, Waku v2 implements a Pub/Sub messaging pattern over libp2p and +At a high level, +[10/WAKU2](/waku/standards/core/10/waku2.md) implements a publish/subscribe messaging pattern over libp2p and adds capabilities. -The present document specifies the Waku v2 message format, -a way to encapsulate the messages sent with specific information security goals, +The present document specifies the [10/WAKU2](/waku/standards/core/10/waku2.md) message format. +A way to encapsulate the messages sent with specific information security goals, and Whisper/Waku v1 backward compatibility. ## Motivation @@ -32,7 +34,7 @@ When sending messages over Waku, there are multiple requirements: - One may have a separate encryption layer as part of the application. - One may want to provide efficient routing for resource-restricted devices. -- One may want to provide compatibility with [Waku v1 envelopes](../../legacy/6/waku1.md). +- One may want to provide compatibility with [6/WAKU1](/waku/standards/legacy/6/waku1.md) envelopes. - One may want encrypted payloads by default. - One may want to provide unlinkability to get metadata protection. @@ -40,16 +42,20 @@ This specification attempts to provide for these various requirements. ## 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](https://www.ietf.org/rfc/rfc2119.txt). + ### Waku Message -A Waku message is constituted by the combination of data payload and +A `WakuMessage` is constituted by the combination of data payload and attributes that, for example, a *publisher* sends to a *topic* and is eventually delivered to *subscribers*. -Waku message attributes are key-value pairs of metadata associated with a message. -And the message data payload is the part of the transmitted Waku message +The `WakuMessage` attributes are key-value pairs of metadata associated with a message. +The message data payload is the part of the transmitted `WakuMessage` that is the actual message information. -The data payload is also treated as a Waku message attribute for convenience. +The data payload is also treated as a `WakuMessage` attribute for convenience. ### Message Attributes @@ -57,13 +63,13 @@ The data payload is also treated as a Waku message attribute for convenience. - The `content_topic` attribute MUST specify a string identifier that can be used for content-based filtering, -as described in [23/WAKU2-TOPICS](../../../informational/23/topics.md). +as described in [23/WAKU2-TOPICS](/waku/informational/23/topics.md). - The `meta` attribute, if present, contains an arbitrary application-specific variable-length byte array with a maximum length limit of 64 bytes. This attribute can be utilized to convey supplementary details -to various Waku protocols, +to various [10/WAKU2](/waku/standards/core/10/waku2.md) protocols, thereby enabling customized processing based on its contents. - The `version` attribute, if present, @@ -76,14 +82,14 @@ This attribute MAY contain the Unix epoch time in nanoseconds. If the attribute is omitted, it SHOULD be interpreted as timestamp 0. - The `ephemeral` attribute, if present, signifies the transient nature of the message. -For example, an ephemeral message SHOULD not be persisted by the Waku network. +For example, an ephemeral message SHOULD not be persisted by the [64/WAKU2-NETWORK](/waku/standards/core/64/network.md). If this attribute is set to `true`, the message SHOULD be interpreted as ephemeral. If, instead, the attribute is omitted or set to `false`, the message SHOULD be interpreted as non-ephemeral. ## Wire Format -The Waku message wire format is specified using [protocol buffers v3](https://developers.google.com/protocol-buffers/). +The `WakuMessage` wire format is specified using [protocol buffers v3](https://developers.google.com/protocol-buffers/). ```protobuf syntax = "proto3"; @@ -102,7 +108,7 @@ An example proto file following this specification can be found [here (vacp2p/wa ## Payload encryption -The Waku message payload MAY be encrypted. +The `WakuMessage` payload MAY be encrypted. The message `version` attribute indicates the schema used to encrypt the payload data. @@ -112,14 +118,14 @@ the schema used to encrypt the payload data. at the application layer. - **Version 1:** -The payload SHOULD be encrypted using Waku v1 payload encryption specified in [26/WAKU-PAYLOAD](../../application/26/payload.md). +The payload SHOULD be encrypted using [6/WAKU1](/waku/standards/legacy/6/waku1.md) payload encryption specified in [26/WAKU-PAYLOAD](/waku/standards/application/26/payload.md). This provides asymmetric and symmetric encryption. The key agreement is performed out of band. And provides an encrypted signature and padding for some form of unlinkability. - **Version 2:** The payload SHOULD be encoded according to [WAKU2-NOISE](https://github.com/waku-org/specs/blob/master/standards/application/noise.md). -Waku Noise protocol provides symmetric encryption and asymmetric key exchange. +The Waku Noise protocol provides symmetric encryption and asymmetric key exchange. Any `version` value not included in this list is reserved for future specification. And, in this case, the payload SHOULD be interpreted as unencrypted by the Waku layer. @@ -132,8 +138,8 @@ Whisper/Waku v1 envelopes are compatible with Waku v2 messages format. SHOULD be mapped to Waku v2 message's `content_topic` attribute. - Whisper/Waku v1 `data` field SHOULD be mapped to Waku v2 message's `payload` attribute. -Waku v2 implements a pub/sub messaging pattern over libp2p. -This makes redundant some Whisper/Waku v1 envelope fields +[10/WAKU2](/waku/standards/core/10/waku2.md) implements a publish/subscribe messaging pattern over libp2p. +This makes some Whisper/Waku v1 envelope fields redundant (e.g., `expiry`, `ttl`, `topic`, etc.), so they can be ignored. ## Deterministic message hashing @@ -144,7 +150,7 @@ and languages. It is also unstable across different builds with schema changes due to unknown fields. To overcome this interoperability limitation, -a Waku v2 message's hash MUST be computed following this schema: +a [10/WAKU2](/waku/standards/core/10/waku2.md) message's hash MUST be computed following this schema: ```js message_hash = sha256(concat(pubsub_topic, message.payload, message.content_topic, message.meta, message.timestamp)) @@ -164,7 +170,7 @@ coupled with using a SHA-2 (256-bit) hashing algorithm. ### Test vectors -Waku message hash computation (`meta` size of 12 bytes): +The `WakuMessage` hash computation (`meta` size of 12 bytes): ```js pubsub_topic = "/waku/2/default-waku/proto" (0x2f77616b752f322f64656661756c742d77616b752f70726f746f) @@ -176,7 +182,7 @@ message.timestamp = 0x175789bfa23f8400 message_hash = 0x64cce733fed134e83da02b02c6f689814872b1a0ac97ea56b76095c3c72bfe05 ``` -Waku message hash computation (`meta` size of 64 bytes): +The `WakuMessage` hash computation (`meta` size of 64 bytes): ```js pubsub_topic = "/waku/2/default-waku/proto" (0x2f77616b752f322f64656661756c742d77616b752f70726f746f) @@ -188,7 +194,7 @@ message.timestamp = 0x175789bfa23f8400 message_hash = 0x7158b6498753313368b9af8f6e0a0a05104f68f972981da42a43bc53fb0c1b27 ``` -Waku message hash computation (`meta` attribute not present): +The `WakuMessage` hash computation (`meta` attribute not present): ```js pubsub_topic = "/waku/2/default-waku/proto" (0x2f77616b752f322f64656661756c742d77616b752f70726f746f) @@ -200,7 +206,7 @@ message.timestamp = 0x175789bfa23f8400 message_hash = 0xa2554498b31f5bcdfcbf7fa58ad1c2d45f0254f3f8110a85588ec3cf10720fd8 ``` -Waku message hash computation (`payload` length 0): +The `WakuMessage` hash computation (`payload` length 0): ```js pubsub_topic = "/waku/2/default-waku/proto" (0x2f77616b752f322f64656661756c742d77616b752f70726f746f) @@ -217,28 +223,29 @@ message_hash = 0x483ea950cb63f9b9d6926b262bb36194d3f40a0463ce8446228350bd44e96de ### Confidentiality, integrity, and authenticity The level of confidentiality, integrity, and -authenticity of the Waku message payload is discretionary. +authenticity of the `WakuMessage` payload is discretionary. Accordingly, the application layer shall utilize the encryption and -signature schemes supported by Waku v2 to meet the application-specific privacy needs. +signature schemes supported by [10/WAKU2](/waku/standards/core/10/waku2.md), +to meet the application-specific privacy needs. ### Reliability of the `timestamp` attribute -The Waku message `timestamp` attribute is set by the sender. +The message `timestamp` attribute is set by the sender. Therefore, because message timestamps aren’t independently verified, this attribute is prone to exploitation and misuse. It should not solely be relied upon for operations such as message ordering. -For example, a malicious actor can arbitrarily set the `timestamp` of a Waku message +For example, a malicious actor 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 Waku messages’ `timestamp` attribute -are recommended to use additional methods for more robust message ordering. +Applications using [10/WAKU2](/waku/standards/core/10/waku2.md) messages’ `timestamp` attribute +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 [62/STATUS-PAYLOADS](../../../../status/62/payloads.md/#clock-vs-timestamp-and-message-ordering). +see [62/STATUS-PAYLOADS](/status/62/payloads.md/#clock-vs-timestamp-and-message-ordering). ### Reliability of the `ephemeral` attribute -The Waku message `ephemeral` attribute is set by the sender. +The message `ephemeral` attribute is set by the sender. Since there is currently no incentive mechanism for network participants to behave correctly, this attribute is inherently insecure. @@ -251,8 +258,11 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public ## References -- [6/WAKU1](../../legacy/6/waku1.md) -- [Google Protocol buffers v3](https://developers.google.com/protocol-buffers/) -- [26/WAKU-PAYLOAD](../../application/26/payload.md) +- [10/WAKU2](/waku/standards/core/10/waku2.md) +- [6/WAKU1](/waku/standards/legacy/6/waku1.md) +- [23/WAKU2-TOPICS](/waku/informational/23/topics.md) +- [64/WAKU2-NETWORK](/waku/standards/core/64/network.md) +- [protocol buffers v3](https://developers.google.com/protocol-buffers/) +- [26/WAKU-PAYLOAD](/waku/standards/application/26/payload.md) - [WAKU2-NOISE](https://github.com/waku-org/specs/blob/master/standards/application/noise.md) -- [62/STATUS-PAYLOADS](../../../../status/62/payloads.md/#clock-vs-timestamp-and-message-ordering) +- [62/STATUS-PAYLOADS](/status/62/payloads.md/#clock-vs-timestamp-and-message-ordering) From 167ef503cbb35ef9cf9dcae541bd3baf72046400 Mon Sep 17 00:00:00 2001 From: Jimmy Debe <91767824+jimstir@users.noreply.github.com> Date: Thu, 2 Jan 2025 10:44:23 -0500 Subject: [PATCH 2/6] Update message.md --- waku/standards/core/14/message.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/waku/standards/core/14/message.md b/waku/standards/core/14/message.md index a64ba4fe..f8186d42 100644 --- a/waku/standards/core/14/message.md +++ b/waku/standards/core/14/message.md @@ -2,7 +2,7 @@ slug: 14 title: 14/WAKU2-MESSAGE name: Waku v2 Message -status: draft +status: stable category: Standards Track tags: waku/core-protocol editor: Hanno Cornelius From 15773b94093cd96fd2b9c6be62e8e724dbe1390c Mon Sep 17 00:00:00 2001 From: Jimmy Debe <91767824+jimstir@users.noreply.github.com> Date: Thu, 2 Jan 2025 10:56:28 -0500 Subject: [PATCH 3/6] Update message.md --- waku/standards/core/14/message.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/waku/standards/core/14/message.md b/waku/standards/core/14/message.md index f8186d42..2630a3d6 100644 --- a/waku/standards/core/14/message.md +++ b/waku/standards/core/14/message.md @@ -20,7 +20,7 @@ contributors: for secure communication. These protocols are designed to be secure, privacy-preserving, and censorship-resistant and can run in resource-restricted environments. -At a high level, +At a high level, [10/WAKU2](/waku/standards/core/10/waku2.md) implements a publish/subscribe messaging pattern over libp2p and adds capabilities. From 96eba2bb7ebf8c8dce0f5e4df9fd0eceb4c0b3fb Mon Sep 17 00:00:00 2001 From: Jimmy Debe <91767824+jimstir@users.noreply.github.com> Date: Wed, 29 Jan 2025 20:02:52 -0500 Subject: [PATCH 4/6] Update waku/standards/core/14/message.md Co-authored-by: Hanno Cornelius <68783915+jm-clius@users.noreply.github.com> --- waku/standards/core/14/message.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/waku/standards/core/14/message.md b/waku/standards/core/14/message.md index 2630a3d6..06cf1611 100644 --- a/waku/standards/core/14/message.md +++ b/waku/standards/core/14/message.md @@ -82,7 +82,7 @@ This attribute MAY contain the Unix epoch time in nanoseconds. If the attribute is omitted, it SHOULD be interpreted as timestamp 0. - The `ephemeral` attribute, if present, signifies the transient nature of the message. -For example, an ephemeral message SHOULD not be persisted by the [64/WAKU2-NETWORK](/waku/standards/core/64/network.md). +For example, an ephemeral message SHOULD not be persisted by other nodes on the same network. If this attribute is set to `true`, the message SHOULD be interpreted as ephemeral. If, instead, the attribute is omitted or set to `false`, the message SHOULD be interpreted as non-ephemeral. From f39d5d6ecd54f202f8ee6b15d7bd7637e8342d59 Mon Sep 17 00:00:00 2001 From: Jimmy Debe <91767824+jimstir@users.noreply.github.com> Date: Wed, 29 Jan 2025 22:59:32 -0500 Subject: [PATCH 5/6] Update message.md --- waku/standards/core/14/message.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/waku/standards/core/14/message.md b/waku/standards/core/14/message.md index 06cf1611..142de1fb 100644 --- a/waku/standards/core/14/message.md +++ b/waku/standards/core/14/message.md @@ -81,6 +81,9 @@ signifies the time at which the message was generated by its sender. This attribute MAY contain the Unix epoch time in nanoseconds. If the attribute is omitted, it SHOULD be interpreted as timestamp 0. +- The `rate_limit_proof` attribute, if present, +contains a rate limit proof encoded as per [17/WAKU2-RLN-RELAY](/waku/standards/core/17/rln-relay.md). + - The `ephemeral` attribute, if present, signifies the transient nature of the message. For example, an ephemeral message SHOULD not be persisted by other nodes on the same network. If this attribute is set to `true`, the message SHOULD be interpreted as ephemeral. @@ -100,6 +103,7 @@ message WakuMessage { optional uint32 version = 3; optional sint64 timestamp = 10; optional bytes meta = 11; + optional bytes rate_limit_proof = 21; optional bool ephemeral = 31; } ``` @@ -261,6 +265,7 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public - [10/WAKU2](/waku/standards/core/10/waku2.md) - [6/WAKU1](/waku/standards/legacy/6/waku1.md) - [23/WAKU2-TOPICS](/waku/informational/23/topics.md) +- [17/WAKU2-RLN-RELAY](/waku/standards/core/17/rln-relay.md) - [64/WAKU2-NETWORK](/waku/standards/core/64/network.md) - [protocol buffers v3](https://developers.google.com/protocol-buffers/) - [26/WAKU-PAYLOAD](/waku/standards/application/26/payload.md) From 010d42260026953142b7bd9ef17e0a304a93f54c Mon Sep 17 00:00:00 2001 From: Jimmy Debe <91767824+jimstir@users.noreply.github.com> Date: Thu, 27 Feb 2025 18:32:59 -0500 Subject: [PATCH 6/6] Update message.md --- waku/standards/core/14/message.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/waku/standards/core/14/message.md b/waku/standards/core/14/message.md index 142de1fb..9be05121 100644 --- a/waku/standards/core/14/message.md +++ b/waku/standards/core/14/message.md @@ -26,7 +26,7 @@ adds capabilities. The present document specifies the [10/WAKU2](/waku/standards/core/10/waku2.md) message format. A way to encapsulate the messages sent with specific information security goals, -and Whisper/Waku v1 backward compatibility. +and Whisper/[6/WAKU1](/waku/standards/legacy/6/waku1.md) backward compatibility. ## Motivation @@ -134,16 +134,16 @@ The Waku Noise protocol provides symmetric encryption and asymmetric key exchang Any `version` value not included in this list is reserved for future specification. And, in this case, the payload SHOULD be interpreted as unencrypted by the Waku layer. -## Whisper/Waku v1 envelope compatibility +## Whisper/[6/WAKU1](/waku/standards/legacy/6/waku1.md) envelope compatibility -Whisper/Waku v1 envelopes are compatible with Waku v2 messages format. +Whisper/[6/WAKU1](/waku/standards/legacy/6/waku1.md) envelopes are compatible with Waku messages format. -- Whisper/Waku v1 `topic` field -SHOULD be mapped to Waku v2 message's `content_topic` attribute. -- Whisper/Waku v1 `data` field SHOULD be mapped to Waku v2 message's `payload` attribute. +- Whisper/[6/WAKU1](/waku/standards/legacy/6/waku1.md) `topic` field +SHOULD be mapped to Waku message's `content_topic` attribute. +- Whisper/[6/WAKU1](/waku/standards/legacy/6/waku1.md) `data` field SHOULD be mapped to Waku message's `payload` attribute. [10/WAKU2](/waku/standards/core/10/waku2.md) implements a publish/subscribe messaging pattern over libp2p. -This makes some Whisper/Waku v1 envelope fields redundant +This makes some Whisper/[6/WAKU1](/waku/standards/legacy/6/waku1.md) envelope fields redundant (e.g., `expiry`, `ttl`, `topic`, etc.), so they can be ignored. ## Deterministic message hashing