AtHeartEngineer/rfc.vac.dev
1
0
Fork 0
mirror of https://github.com/vacp2p/rfc.vac.dev.git synced 2026-01-07 23:23:51 -05:00
Code Issues Packages Projects Releases Wiki Activity

chore: MD content updates

Browse Source
This commit is contained in:
Filip Pajic
2024-04-25 09:32:56 +02:00
parent 32f0947064
commit 276328e60b
57 changed files with 845 additions and 897 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
nomos/claro.md → nomos/38/claro.md
View File

@@ -10,7 +10,6 @@ uri: \<https://rdf.logos.co/protocol/Claro/1/0/0#\<2022-08-26%20Fri$2013:11Z\>
contributors:
- Álvaro Castro-Castilla
- Mark Evenson
sidebar_position: 38
---
- Status: raw
- Category: Standards Track

1
status/curation.md → status/24/curation.md
View File

@@ -4,7 +4,6 @@ name: Status Community Directory Curation Voting using Waku v2
status: draft
description: A voting protocol for SNT holders to submit votes to a smart contract. Voting is immutable, which helps avoid sabotage from malicious peers.
editor: Szymon Szlachtowicz \<szymon.s@ethworks.io\>
sidebar_position: 24
---
- Status: draft
- Editor: Szymon Szlachtowicz \<szymon.s@ethworks.io\>

1
status/featuring.md → status/28/featuring.md
View File

@@ -4,7 +4,6 @@ name: Status community featuring using waku v2
status: draft
description: To gain new members, current SNT holders can vote to feature an active Status community to the larger Status audience.
editor: Szymon Szlachtowicz \<szymon.s@ethworks.io\>
sidebar_position: 28
---
- Status: draft
- Editor: Szymon Szlachtowicz \<szymon.s@ethworks.io\>

27
status/1to1-chat.md → status/55/1to1-chat.md
View File

@@ -11,7 +11,6 @@ contributors:
- Corey Petty \<corey@status.im\>
- Oskar Thorén \<oskarth@titanproxy.com\>
- Dean Eigenmann \<dean@status.im\>
sidebar_position: 55
---
- Status: draft
- Category: Standards Track
@@ -43,8 +42,8 @@ This document describes how 2 peers communicate with each other to send messages
This protocol MAY use any key-exchange mechanism previously discussed -
1. [53/WAKU2-X3DH](../../waku/standards/application/53/x3dh.md)
2. [WAKU2-NOISE](https://github.com/waku-org/specs/blob/master/standards/application/noise.md)
1. [53/WAKU2-X3DH](../../waku/standards/application/53/x3dh)
2. [WAKU2-NOISE](https://github.com/waku-org/specs/blob/master/standards/application/noise)
This protocol can provide end-to-end encryption to give peers a strong degree of privacy and security.
Public chat messages are publicly readable by anyone since there's no permission model for who is participating in a public chat.
@@ -58,7 +57,7 @@ There are two phases in the initial negotiation of a 1:1 chat:
A QR code serves two purposes simultaneously - identity verification and initial key material retrieval;
1. **Asynchronous initial key exchange**
For more information on account generation and trust establishment, see [65/ACCOUNT-ADDRESS](../65/account-address.md)
For more information on account generation and trust establishment, see [65/ACCOUNT-ADDRESS](../65/account-address)
### Post Negotiation
@@ -69,9 +68,9 @@ After the peers have shared their public key material, a 1:1 chat can be establi
The 1:1 chat is made robust by having sessions between peers.
It is handled by the key-exchange protocol used. For example,
1. [53/WAKU2-X3DH](../../waku/standards/application/53/x3dh.md), the session management is described in [54/WAKU2-X3DH-SESSIONS](../../waku/standards/application/54/x3dh-sessions.md)
1. [53/WAKU2-X3DH](../../waku/standards/application/53/x3dh), the session management is described in [54/WAKU2-X3DH-SESSIONS](../../waku/standards/application/54/x3dh-sessions)
2. [WAKU2-NOISE](https://github.com/waku-org/specs/blob/master/standards/application/noise.md), the session management is described in [WAKU2-NOISE-SESSIONS](https://github.com/waku-org/specs/blob/master/standards/application/noise-sessions.md)
2. [WAKU2-NOISE](https://github.com/waku-org/specs/blob/master/standards/application/noise), the session management is described in [WAKU2-NOISE-SESSIONS](https://github.com/waku-org/specs/blob/master/standards/application/noise-sessions)
## Negotiation of a 1:1 chat amongst multiple participants (group chat)
@@ -83,7 +82,7 @@ However, this method does not scale as the number of participants increases, for
1. The number of messages sent over the network increases with the number of participants.
2. Handling the X3DH key exchange for each participant is computationally expensive.
The above issues are addressed in [56/STATUS-COMMUNITIES](../56/communities.md), with other trade-offs.
The above issues are addressed in [56/STATUS-COMMUNITIES](../56/communities), with other trade-offs.
### Flow
@@ -209,7 +208,7 @@ To change the display image of the group chat, group admins MUST use an `IMAGE_C
## Security Considerations
1. Inherits the security considerations of the key-exchange mechanism used, e.g., [53/WAKU2-X3DH](../../waku/standards/application/53/x3dh.md) or [WAKU2-NOISE](https://github.com/waku-org/specs/blob/master/standards/application/noise.md)
1. Inherits the security considerations of the key-exchange mechanism used, e.g., [53/WAKU2-X3DH](../../waku/standards/application/53/x3dh) or [WAKU2-NOISE](https://github.com/waku-org/specs/blob/master/standards/application/noise)
## Copyright
@@ -217,11 +216,11 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public
## References
1. [53/WAKU2-X3DH](../../waku/standards/application/53/x3dh.md)
2. [WAKU2-NOISE](https://github.com/waku-org/specs/blob/master/standards/application/noise.md)
3. [65/STATUS-ACCOUNT](../65/account-address.md)
4. [54/WAKU2-X3DH-SESSIONS](../../waku/standards/application/54/x3dh-sessions.md)
5. [WAKU2-NOISE-SESSIONS](https://github.com/waku-org/specs/blob/master/standards/application/noise-sessions.md)
6. [56/STATUS-COMMUNITIES](../56/communities.md)
1. [53/WAKU2-X3DH](../../waku/standards/application/53/x3dh)
2. [WAKU2-NOISE](https://github.com/waku-org/specs/blob/master/standards/application/noise)
3. [65/STATUS-ACCOUNT](../65/account-address)
4. [54/WAKU2-X3DH-SESSIONS](../../waku/standards/application/54/x3dh-sessions)
5. [WAKU2-NOISE-SESSIONS](https://github.com/waku-org/specs/blob/master/standards/application/noise-sessions)
6. [56/STATUS-COMMUNITIES](../56/communities)
7. [chat_message.proto](https://github.com/status-im/status-go/blob/5fd9e93e9c298ed087e6716d857a3951dbfb3c1e/protocol/protobuf/chat_message.proto#L1)
8. [emoji_reaction.proto](https://github.com/status-im/status-go/blob/5fd9e93e9c298ed087e6716d857a3951dbfb3c1e/protocol/protobuf/emoji_reaction.proto)

51
status/communities.md → status/56/communities.md
View File

@@ -7,7 +7,6 @@ description: Status Communities allow multiple users to communicate in a discuss
editor: Aaryamann Challani \<aaryamann@status.im\>
contributors:
- Andrea Piana \<andreap@status.im\>
sidebar_position: 56
---
- Status: draft
- Category: Standards Track
@@ -25,10 +24,10 @@ This is a key feature for the Status messaging app.
The purpose of Status communities, as specified in this document, is allowing for large group chats.
Communities can have further substructure, e.g. specific channels.
Smaller group chats, on the other hand, are out of scope for this document and can be built over [55/STATUS-1TO1-CHAT](../55/1to1-chat.md).
Smaller group chats, on the other hand, are out of scope for this document and can be built over [55/STATUS-1TO1-CHAT](../55/1to1-chat).
We refer to these smaller group chats simply as "group chats", to differentiate them from Communities.
For group chats based on [55/STATUS-1TO1-CHAT](../55/1to1-chat.md), the key exchange mechanism MUST be X3DH, as described in [53/WAKU2-X3DH](../../waku/standards/application/53/x3dh.md).
For group chats based on [55/STATUS-1TO1-CHAT](../55/1to1-chat), the key exchange mechanism MUST be X3DH, as described in [53/WAKU2-X3DH](../../waku/standards/application/53/x3dh).
However, this method does not scale as the number of participants increases, for the following reasons -
1. The number of messages sent over the network increases with the number of participants.
@@ -59,7 +58,7 @@ This extends to banning and kicking members.
8. The public key of the Community is shared out of band.
9. The metadata of the Community can be found by listening on a content topic derived from the public key of the Community.
10. Community members run their own Waku nodes, with the configuration described in [Waku-Protocols](#waku-protocols).
Light nodes solely implementing [19/WAKU2-LIGHTPUSH](../../waku/standards/core/19/lightpush.md) may not be able to run their own Waku node with the configuration described.
Light nodes solely implementing [19/WAKU2-LIGHTPUSH](../../waku/standards/core/19/lightpush) may not be able to run their own Waku node with the configuration described.
## Design
@@ -293,7 +292,7 @@ Note: The usage of the clock is described in the [Clock](#clock) section.
### Content topic usage
"Content topic" refers to the field in [14/WAKU2-MESSAGE](../../waku/standards/core/14/message.md/#message-attributes), further elaborated in [10/WAKU2](../../waku/standards/core/10/waku2.md/#overview-of-protocol-interaction).
"Content topic" refers to the field in [14/WAKU2-MESSAGE](../../waku/standards/core/14/message#message-attributes), further elaborated in [10/WAKU2](../../waku/standards/core/10/waku2#overview-of-protocol-interaction).
#### Advertising a Community
@@ -378,7 +377,7 @@ The Community metadata SHOULD be sent every time the Community metadata is updat
#### Community Join Flow (peer requests to join a Community)
1. A peer and the Community owner establish a 1:1 chat as described in [55/STATUS-1TO1-CHAT](../55/1to1-chat.md).
1. A peer and the Community owner establish a 1:1 chat as described in [55/STATUS-1TO1-CHAT](../55/1to1-chat).
2. The peer requests to join a Community by sending a "CommunityRequestToJoin" message to the Community.
At this point, the peer MAY send a "CommunityCancelRequestToJoin" message to cancel the request.
3. The Community owner MAY accept or reject the request.
@@ -387,7 +386,7 @@ At this point, the peer MAY send a "CommunityCancelRequestToJoin" message to can
#### Community Join Flow (peer is invited to join a Community)
1. The Community owner and peer establish a 1:1 chat as described in [55/STATUS-1TO1-CHAT](../55/1to1-chat.md).
1. The Community owner and peer establish a 1:1 chat as described in [55/STATUS-1TO1-CHAT](../55/1to1-chat).
2. The peer is invited to join a Community by the Community owner, by sending a "CommunityInvitation" message.
3. The peer decrypts the "CommunityInvitation" message, and verifies the signature.
4. The peer requests to join a Community by sending a "CommunityRequestToJoin" message to the Community.
@@ -410,23 +409,23 @@ At this point, the peer MAY send a "CommunityCancelRequestToJoin" message to can
The following Waku protocols SHOULD be used to implement Status Communities -
1. [11/WAKU2-RELAY](../../waku/standards/core/11/relay.md) - To send and receive messages
2. [53/WAKU2-X3DH](../../waku/standards/application/53/x3dh.md) - To encrypt and decrypt messages
3. [54/WAKU2-X3DH-SESSIONS](../../waku/standards/application/54/x3dh-sessions.md) - To handle session keys
4. [14/WAKU2-MESSAGE](../../waku/standards/core/14/message.md) - To wrap community messages in a Waku message
5. [13/WAKU2-STORE](../../waku/standards/core/13/store.md) - To store and retrieve messages for offline devices
1. [11/WAKU2-RELAY](../../waku/standards/core/11/relay) - To send and receive messages
2. [53/WAKU2-X3DH](../../waku/standards/application/53/x3dh) - To encrypt and decrypt messages
3. [54/WAKU2-X3DH-SESSIONS](../../waku/standards/application/54/x3dh-sessions) - To handle session keys
4. [14/WAKU2-MESSAGE](../../waku/standards/core/14/message) - To wrap community messages in a Waku message
5. [13/WAKU2-STORE](../../waku/standards/core/13/store) - To store and retrieve messages for offline devices
The following Waku protocols MAY be used to implement Status Communities -
1. [12/WAKU2-FILTER](../../waku/standards/core/12/filter.md) - Content filtering for resource restricted devices
2. [19/WAKU2-LIGHTPUSH](../../waku/standards/core/19/lightpush.md) - Allows Light clients to participate in the network
1. [12/WAKU2-FILTER](../../waku/standards/core/12/filter) - Content filtering for resource restricted devices
2. [19/WAKU2-LIGHTPUSH](../../waku/standards/core/19/lightpush) - Allows Light clients to participate in the network
### Backups
The member MAY back up their local settings, by encrypting it with their public key, and sending it to a given content topic.
The member MAY then rely on this backup to restore their local settings, in case of a data loss.
This feature relies on [13/WAKU2-STORE](../../waku/standards/core/13/store.md) for storing and retrieving messages.
This feature relies on [13/WAKU2-STORE](../../waku/standards/core/13/store) for storing and retrieving messages.
### Clock
@@ -438,7 +437,7 @@ This allows ordering of messages in an asynchronous network where messages may b
1. The Community owner is a single point of failure. If the Community owner is compromised, the Community is compromised.
2. Follows the same security considerations as the [53/WAKU2-X3DH](../../waku/standards/application/53/x3dh.md) protocol.
2. Follows the same security considerations as the [53/WAKU2-X3DH](../../waku/standards/application/53/x3dh) protocol.
## Future work
@@ -454,16 +453,16 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public
## References
- [55/STATUS-1TO1-CHAT](../55/1to1-chat.md)
- [53/WAKU2-X3DH](../../waku/standards/application/53/x3dh.md)
- [19/WAKU2-LIGHTPUSH](../../waku/standards/core/19/lightpush.md)
- [14/WAKU2-MESSAGE](../../waku/standards/core/14/message.md)
- [10/WAKU2](../../waku/standards/core/10/waku2.md)
- [11/WAKU2-RELAY](../../waku/standards/core/11/relay.md)
- [54/WAKU2-X3DH-SESSIONS](../../waku/standards/application/54/x3dh-sessions.md)
- [13/WAKU2-STORE](../../waku/standards/core/13/store.md)
- [12/WAKU2-FILTER](../../waku/standards/core/12/filter.md)
- [55/STATUS-1TO1-CHAT](../55/1to1-chat)
- [53/WAKU2-X3DH](../../waku/standards/application/53/x3dh)
- [19/WAKU2-LIGHTPUSH](../../waku/standards/core/19/lightpush)
- [14/WAKU2-MESSAGE](../../waku/standards/core/14/message)
- [10/WAKU2](../../waku/standards/core/10/waku2)
- [11/WAKU2-RELAY](../../waku/standards/core/11/relay)
- [54/WAKU2-X3DH-SESSIONS](../../waku/standards/application/54/x3dh-sessions)
- [13/WAKU2-STORE](../../waku/standards/core/13/store)
- [12/WAKU2-FILTER](../../waku/standards/core/12/filter)
### informative
- [community.go](https://github.com/status-im/status-go/blob/6072bd17ab1e5d9fc42cf844fcb8ad18aa07760c/protocol/communities/community.go)
- [organisation-channels.md](https://github.com/status-im/specs/blob/403b5ce316a270565023fc6a1f8dec138819f4b0/docs/raw/organisation-channels.md)
- [organisation-channels.md](https://github.com/status-im/specs/blob/403b5ce316a270565023fc6a1f8dec138819f4b0/docs/raw/organisation-channels)

37
status/community-history-service.md → status/61/community-history-service.md
View File

@@ -8,7 +8,6 @@ editor: r4bbit \<r4bbit@status.im\>
contributors:
- Sanaz Taheri \<sanaz@status.im\>
- John Lea \<john@status.im\>
sidebar_position: 61
---
- Status: draft
- Category: Standards Track
@@ -19,7 +18,7 @@ sidebar_position: 61
## Abstract
Messages are stored permanently by store nodes ([13/WAKU2-STORE](../../waku/standards/core/13/store.md)) for up to a certain configurable period of time, limited by the overall storage provided by a store node.
Messages are stored permanently by store nodes ([13/WAKU2-STORE](../../waku/standards/core/13/store)) for up to a certain configurable period of time, limited by the overall storage provided by a store node.
Messages older than that period are no longer provided by store nodes, making it impossible for other nodes to request historical messages that go beyond that time range.
This raises issues in the case of Status communities, where recently joined members of a community are not able to request complete message histories of the community channels.
@@ -32,9 +31,9 @@ The following terminology is used throughout this specification. Notice that som
| Name | References |
| -------------------- | --- |
| Waku node | An Waku node ([10/WAKU2](../../waku/standards/core/10/waku2.md)) that implements [11/WAKU2-RELAY](../../waku/standards/core/11/relay.md)|
| Store node | A Waku node that implements [13/WAKU2-STORE](../../waku/standards/core/13/store.md) |
| Waku network | A group of Waku nodes forming a graph, connected via [11/WAKU2-RELAY](../../waku/standards/core/11/relay.md) |
| Waku node | An Waku node ([10/WAKU2](../../waku/standards/core/10/waku2)) that implements [11/WAKU2-RELAY](../../waku/standards/core/11/relay)|
| Store node | A Waku node that implements [13/WAKU2-STORE](../../waku/standards/core/13/store) |
| Waku network | A group of Waku nodes forming a graph, connected via [11/WAKU2-RELAY](../../waku/standards/core/11/relay) |
| Status user | An Status account that is used in a Status consumer product, such as Status Mobile or Status Desktop |
| Status node | A Status client run by a Status application |
| Control node | A Status node that owns the private key for a Status community |
@@ -49,7 +48,7 @@ The following terminology is used throughout this specification. Notice that som
This specification has the following assumptions:
- Store nodes([13/WAKU2-STORE](../../waku/standards/core/13/store.md)) are available 24/7, ensuring constant live message availability.
- Store nodes([13/WAKU2-STORE](../../waku/standards/core/13/store)) are available 24/7, ensuring constant live message availability.
- The storage time range limit is 30 days.
- Store nodes have enough storage to persist historical messages for up to 30 days.
- No store nodes have storage to persist historical messages older than 30 days.
@@ -96,10 +95,10 @@ If the control node goes offline (where "offline" means, the control node's main
Community member nodes go through the following (high level) process to fetch and restore community message histories:
1. User joins community and becomes community member (see [org channels spec](../56/communities.md))
1. User joins community and becomes community member (see [org channels spec](../56/communities))
2. By joining a community, member nodes automatically subscribe to special channel for message archive metadata exchange provided by the community
3. Member node requests live message history (last 30 days) of all the community channels including the special channel from store nodes
4. Member node receives Waku message ([14/WAKU2-MESSAGE](../../waku/standards/core/14/message.md)) that contains the metadata magnet link from the special channel
4. Member node receives Waku message ([14/WAKU2-MESSAGE](../../waku/standards/core/14/message)) that contains the metadata magnet link from the special channel
5. Member node extracts the magnet link from the Waku message and passes it to torrent client
6. Member node downloads [message archive index](#message-history-archive-index) file and determines which message archives are not downloaded yet (all or some)
7. Member node fetches missing message archive data via torrent
@@ -107,7 +106,7 @@ Community member nodes go through the following (high level) process to fetch an
## Storing live messages
For archival data serving, the control node MUST store live messages as [14/WAKU2-MESSAGE](../../waku/standards/core/14/message.md).
For archival data serving, the control node MUST store live messages as [14/WAKU2-MESSAGE](../../waku/standards/core/14/message).
This is in addition to their database of application messages.
This is required to provide confidentiality, authenticity, and integrity of message data distributed via the BitTorrent layer, and later validated by community members when they unpack message history archives.
@@ -125,7 +124,7 @@ The `timestamp` is determined by the context in which the control node attempts
1. The control node attempts to create an archive periodically for the past seven days (including the current day). In this case, the `timestamp` has to lie within those 7 days.
2. The control node has been offline (control node's main process has stopped and needs restart) and attempts to create archives for all the live messages it has missed since it went offline. In this case, the `timestamp` has to lie within the day the latest message was received and the current day.
Exported messages MUST be restored as [14/WAKU2-MESSAGE](../../waku/standards/core/14/message.md) for bundling. Waku messages that are older than 30 days and have been exported for bundling can be removed from the control node's database (control nodes still maintain a database of application messages).
Exported messages MUST be restored as [14/WAKU2-MESSAGE](../../waku/standards/core/14/message) for bundling. Waku messages that are older than 30 days and have been exported for bundling can be removed from the control node's database (control nodes still maintain a database of application messages).
## Message history archives
@@ -135,7 +134,7 @@ Message history archives are implemented using the following protocol buffer.
### WakuMessageHistoryArchive
The `from` field SHOULD contain a timestamp of the time range's lower bound.
The type parallels the `timestamp` of [WakuMessage](../../waku/standards/core/14/message.md/#payloads).
The type parallels the `timestamp` of [WakuMessage](../../waku/standards/core/14/message#payloads).
The `to` field SHOULD contain a timestamp of the time range's the higher bound.
@@ -295,7 +294,7 @@ The topic of that special channel follows the following format:
/{application-name}/{version-of-the-application}/{content-topic-name}/{encoding}
```
All messages sent with this topic MUST be instances of `ApplicationMetadataMessage` ([62/STATUS-PAYLOAD](../62/payload.md)) with a `payload` of `CommunityMessageArchiveIndex`.
All messages sent with this topic MUST be instances of `ApplicationMetadataMessage` ([62/STATUS-PAYLOAD](../62/payload)) with a `payload` of `CommunityMessageArchiveIndex`.
Only the control node MAY post to the special channel. Other messages on this specified channel MUST be ignored by clients.
Community members MUST NOT have permission to send messages to the special channel.
@@ -327,7 +326,7 @@ There are two scenarios in which member nodes can receive such a magnet link mes
2. The member node requests messages for a time range of up to 30 days from store nodes (this is the case when a new community member joins a community)
### Downloading message archives
When member nodes receive a message with a `CommunityMessageHistoryArchive` ([62/STATUS-PAYLOADS](../62/payloads.md)) from the aforementioned channnel, they MUST extract the `magnet_uri` and pass it to their underlying BitTorrent client so they can fetch the latest message history archive index, which is the `index` file of the torrent (see [Creating message archive torrents](#creating-message-archive-torrents)).
When member nodes receive a message with a `CommunityMessageHistoryArchive` ([62/STATUS-PAYLOADS](../62/payloads)) from the aforementioned channnel, they MUST extract the `magnet_uri` and pass it to their underlying BitTorrent client so they can fetch the latest message history archive index, which is the `index` file of the torrent (see [Creating message archive torrents](#creating-message-archive-torrents)).
Due to the nature of distributed systems, there's no guarantee that a received message is the "last" message. This is especially true when member nodes request historical messages from store nodes.
@@ -384,15 +383,15 @@ Even if just a single message is missing in one of the histories, the hashes pre
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
## References
* [13/WAKU2-STORE](../../waku/standards/core/13/store.md)
* [13/WAKU2-STORE](../../waku/standards/core/13/store)
* [BitTorrent](https://bittorrent.org)
* [10/WAKU2](../../waku/standards/core/10/waku2.md)
* [11/WAKU2-RELAY](../../waku/standards/core/11/relay.md)
* [10/WAKU2](../../waku/standards/core/10/waku2)
* [11/WAKU2-RELAY](../../waku/standards/core/11/relay)
* [Magnet URI scheme](https://en.wikipedia.org/wiki/Magnet_URI_scheme)
* [forum discussion](https://forum.vac.dev/t/status-communities-protocol-and-product-point-of-view/114)
* [org channels](https://github.com/status-im/specs/pull/151)
* [UI feature spec](https://github.com/status-im/feature-specs/pull/36)
* [Extensions for Peers to Send Metadata Files](https://www.bittorrent.org/beps/bep_0009.html)
* [org channels spec](../56/communities.md)
* [14/WAKU2-MESSAGE](../../waku/standards/core/14/message.md)
* [62/STATUS-PAYLOADS](../62/payloads.md)
* [org channels spec](../56/communities)
* [14/WAKU2-MESSAGE](../../waku/standards/core/14/message)
* [62/STATUS-PAYLOADS](../62/payloads)

7
status/payloads.md → status/62/payloads.md
View File

@@ -8,7 +8,6 @@ contributors:
- Andrea Maria Piana \<andreap@status.im\>
- Oskar Thoren \<oskarth@titanproxy.com\>
- Samuel Hawksby-Robinson \<samuel@status.im\>
sidebar_position: 62
---
- Status: draft
- Editor: r4bbit \<r4bbit@status.im\>
@@ -284,7 +283,7 @@ message DiscordMessageAttachment {
#### Message types
A node requires message types to decide how to encrypt a particular message and what metadata needs to be attached when passing a message to the transport layer.
For more on this, see [10/WAKU2](../../waku/standards/core/10/waku2.md).
For more on this, see [10/WAKU2](../../waku/standards/core/10/waku2).
<!-- TODO: This reference is a bit odd, considering the layer payloads should interact with is Secure Transport, and not Whisper/Waku. This requires more detail -->
@@ -442,7 +441,7 @@ This specification RECOMMENDS that the UI/UX implementation of retracting an `Em
### MembershipUpdateMessage and MembershipUpdateEvent
`MembershipUpdateEvent` is a message used to propagate information about group membership changes in a group chat.
The details are in the [Group chats specs](../56/communities.md).
The details are in the [Group chats specs](../56/communities).
```protobuf
@@ -828,7 +827,7 @@ message DeleteMessage {
### CommunityMessageArchiveLink
A `CommunityMessageArchiveLink` contains a magnet uri for a community's message archive, created using [61/STATUS-Community-History-Archives](../61/community-history-service.md).
A `CommunityMessageArchiveLink` contains a magnet uri for a community's message archive, created using [61/STATUS-Community-History-Archives](../61/community-history-service).
```protobuf
message CommunityMessageArchiveMagnetlink {

1
status/keycard-usage.md → status/63/keycard-usage.md
View File

@@ -7,7 +7,6 @@ description: Describes how an application can use the Status Keycard to create,
editor: Aaryamann Challani \<aaryamann@status.im\>
contributors:
- Jimmy Debe \<jimmy@status.im\>
sidebar_position: 63
---
- Status: draft
- Category: Standards Track

17
status/account-address.md → status/65/account-address.md
View File

@@ -9,7 +9,6 @@ contributors:
- Corey Petty \<corey@status.im\>
- Oskar Thorén \<oskarth@titanproxy.com\>
- Samuel Hawksby-Robinson \<samuel@status.im\>
sidebar_position: 65
---
- Status: draft
- Category: Standards Track
@@ -37,7 +36,7 @@ The Status node verifies or derives everything else associated with the contact
- An ECDSA (secp256k1 curve) public/private keypair MUST be generated via a [BIP43](https://github.com/bitcoin/bips/blob/master/bip-0043.mediawiki) derived path from a [BIP39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) mnemonic seed phrase.
- The default paths are defined as such:
- Waku Chat Key (`IK`): `m/43'/60'/1581'/0'/0` (post Multiaccount integration)
- following [EIP1581](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1581.md)
- following [EIP1581](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1581)
- Status Wallet paths: `m/44'/60'/0'/0/i` starting at `i=0`
- following [BIP44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki)
- NOTE: this (`i=0`) is also the current (and only) path for Waku key before Multiaccount integration
@@ -46,7 +45,7 @@ The Status node verifies or derives everything else associated with the contact
- A user is responsible for broadcasting certain information publicly so that others may contact them.
### X3DH Prekey bundles
- Refer to [53/WAKU2-X3DH](../../waku/standards/application/53/x3dh.md) for details on the X3DH prekey bundle broadcasting, as well as regeneration.
- Refer to [53/WAKU2-X3DH](../../waku/standards/application/53/x3dh) for details on the X3DH prekey bundle broadcasting, as well as regeneration.
## Optional Account additions
@@ -99,7 +98,7 @@ The above payload is broadcasted when 2 devices that belong to a user need to be
## Security Considerations
- This specification inherits security considerations of [53/WAKU2-X3DH](../../waku/standards/application/53/x3dh.md) and [54/WAKU2-X3DH-SESSIONS](../../waku/standards/application/54/x3dh-sessions.md).
- This specification inherits security considerations of [53/WAKU2-X3DH](../../waku/standards/application/53/x3dh) and [54/WAKU2-X3DH-SESSIONS](../../waku/standards/application/54/x3dh-sessions).
## Copyright
@@ -109,15 +108,15 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public
### normative
- [53/WAKU2-X3DH](../../waku/standards/application/53/x3dh.md)
- [54/WAKU2-X3DH-SESSIONS](../../waku/standards/application/54/x3dh-sessions.md)
- [55/STATUS-1TO1-CHAT](../55/1to1-chat.md)
- [53/WAKU2-X3DH](../../waku/standards/application/53/x3dh)
- [54/WAKU2-X3DH-SESSIONS](../../waku/standards/application/54/x3dh-sessions)
- [55/STATUS-1TO1-CHAT](../55/1to1-chat)
## informative
- [BIP43](https://github.com/bitcoin/bips/blob/master/bip-0043.mediawiki)
- [BIP39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki)
- [EIP1581](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1581.md)
- [EIP1581](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1581)
- [BIP44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki)
- [Ethereum Name System](https://ens.domains/)
- [Status Multiaccount](../63/account-address.md)
- [Status Multiaccount](../63/account-address)

57
status/push-notification-server.md → status/71/push-notification-server.md
View File

@@ -7,7 +7,6 @@ description: A set of methods to allow Status clients to use push notification s
editor: Jimmy Debe \<jimmy@status.im\>
contributors:
- Andrea Maria Piana \<andreap@status.im\>
sidebar_position: 71
---
- Status: draft
- Category: Standards Track
@@ -45,7 +44,7 @@ The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL
| client | A node that implements the Status specifications. |
| user | The owner of a device that runs a client. |
| server | A service that performs push notifications. |
| Waku-Store | A Waku node that decides to provide functionality to store messages permanently and deliver the messages to requesting clients. As described in [13/WAKU-STORE](../../waku/standards/core/13/store.md) specification.|
| Waku-Store | A Waku node that decides to provide functionality to store messages permanently and deliver the messages to requesting clients. As described in [13/WAKU-STORE](../../waku/standards/core/13/store) specification.|
### Server Components
@@ -67,11 +66,11 @@ The party releasing the app MUST run its own [gorush](https://github.com/applebo
### Push Notification Server Flow
#### Registration Process:
![registration](./71/images/registration.png)
![registration](./images/registration.png)
#### Sending and Receiving Notification Process:
![notification](./71/images/notification.png)
![notification](./images/notification.png)
### Registering Client
@@ -82,9 +81,9 @@ Registering a client with a push notification service.
- A client SHOULD make sure that all the notification services they registered with have the same information about their tokens.
- A `PNR message` (Push Notification Registration) MUST be sent to the
[partitioned topic](../../waku/standards/application/54/x3dh-sessions.md) for the public key of the node, encrypted with this key.
[partitioned topic](../../waku/standards/application/54/x3dh-sessions) for the public key of the node, encrypted with this key.
- The message MUST be wrapped in a [`ApplicationMetadataMessage`](../62/payloads.md) with type set to `PUSH_NOTIFICATION_REGISTRATION`.
- The message MUST be wrapped in a [`ApplicationMetadataMessage`](../62/payloads) with type set to `PUSH_NOTIFICATION_REGISTRATION`.
- The marshaled protobuf payload MUST also be encrypted with AES-GCM using the Diffie–Hellman key generated from the client and server identity.
This is done in order to ensure that the extracted key from the signature will be considered invalid if it can’t decrypt the payload.
@@ -132,7 +131,7 @@ A push notification server will handle the message according to the following ru
- it MUST verify that `apn_topic` is set if token_type is APN_TOKEN.
- The message MUST be wrapped in a [`ApplicationMetadataMessage`](../62/payloads.md) with type set to `PUSH_NOTIFICATION_REGISTRATION_RESPONSE`.
- The message MUST be wrapped in a [`ApplicationMetadataMessage`](../62/payloads) with type set to `PUSH_NOTIFICATION_REGISTRATION_RESPONSE`.
The payload of the response is:
@@ -153,7 +152,7 @@ message PushNotificationRegistrationResponse {
```
A client SHOULD listen for a response sent on the [partitioned topic](../../waku/standards/application/54/x3dh-sessions.md) that the key used to register.
A client SHOULD listen for a response sent on the [partitioned topic](../../waku/standards/application/54/x3dh-sessions) that the key used to register.
If success is true the client has registered successfully.
If `success` is `false`:
@@ -175,7 +174,7 @@ If `success` is `false`:
- `request_id` SHOULD be set to the [`SHAKE-256`](https://nvlpubs.nist.gov/nistpubs/fips/nist.fips.202.pdf) of the encrypted payload.
- The response MUST be sent on the [partitioned topic](../../waku/standards/application/54/x3dh-sessions.md) of the sender and
- The response MUST be sent on the [partitioned topic](../../waku/standards/application/54/x3dh-sessions) of the sender and
MUST not be encrypted using the secure transport to facilitate the usage of ephemeral keys.
- If no response is returned, the request SHOULD be considered failed and
@@ -235,17 +234,17 @@ message ContactCodeAdvertisement {
```
#### Handle Advertisement Message:
- The message MUST be wrapped in a [`ApplicationMetadataMessage`](../62/payloads.md) with type set to `PUSH_NOTIFICATION_QUERY_INFO`.
- The message MUST be wrapped in a [`ApplicationMetadataMessage`](../62/payloads) with type set to `PUSH_NOTIFICATION_QUERY_INFO`.
- If no filtering is done based on public keys, the access token SHOULD be included in the advertisement.
Otherwise it SHOULD be left empty.
- This SHOULD be advertised on the [contact code topic](../../waku/standards/application/53/x3dh.md) and
- This SHOULD be advertised on the [contact code topic](../../waku/standards/application/53/x3dh) and
SHOULD be coupled with normal contact-code advertisement.
- When a user register or re-register with a push notification service, their contact-code SHOULD be re-advertised.
- Multiple servers MAY be advertised for the same installation_id for redundancy reasons.
#### Discovering a Server:
To discover a push notification service for a given user, their 
[contact code topic](../../waku/standards/application/53/x3dh.md) SHOULD be listened to.
[contact code topic](../../waku/standards/application/53/x3dh) SHOULD be listened to.
A Waku-Store node can be queried for the specific topic to retrieve the most up-to-date contact code.
#### Querying a Server:
@@ -261,10 +260,10 @@ message PushNotificationQuery {
```
#### Handle Query Message:
- The message MUST be wrapped in a [`ApplicationMetadataMessage`](../62/payloads.md) with type set to `PUSH_NOTIFICATION_QUERY`.
- The message MUST be wrapped in a [`ApplicationMetadataMessage`](../62/payloads) with type set to `PUSH_NOTIFICATION_QUERY`.
- it MUST be sent to the server on the topic derived from the hashed public key of the key we are querying,
[as described above](#query-topic).
- An ephemeral key SHOULD be used and SHOULD NOT be encrypted using the [secure transport](../../waku/standards/application/53/x3dh.md).
- An ephemeral key SHOULD be used and SHOULD NOT be encrypted using the [secure transport](../../waku/standards/application/53/x3dh).
If the server has information about the client a response MUST be sent:
@@ -289,7 +288,7 @@ message PushNotificationQueryResponse {
#### Handle Query Response:
- A `PushNotificationQueryResponse` message MUST be wrapped in a
[`ApplicationMetadataMessage`](../62/payloads.md) with type set to `PUSH_NOTIFICATION_QUERY_RESPONSE`.
[`ApplicationMetadataMessage`](../62/payloads) with type set to `PUSH_NOTIFICATION_QUERY_RESPONSE`.
Otherwise a response MUST NOT be sent.
- If `allowed_key_list` is not set `access_token` MUST be set and `allowed_key_list` MUST NOT be set.
@@ -302,8 +301,8 @@ Otherwise a response MUST NOT be sent.
If AES decryption succeeds it will return a valid `uuid` which is what is used for access_token.
The token SHOULD be used to send push notifications.
- The response MUST be sent on the [partitioned topic](../../waku/standards/application/54/x3dh-sessions.md) of the sender and
MUST NOT be encrypted using the [secure transport](../../waku/standards/application/53/x3dh.md) to facilitate the usage of ephemeral keys.
- The response MUST be sent on the [partitioned topic](../../waku/standards/application/54/x3dh-sessions) of the sender and
MUST NOT be encrypted using the [secure transport](../../waku/standards/application/53/x3dh) to facilitate the usage of ephemeral keys.
- On receiving a response a client MUST verify `grant` to ensure that the server has been authorized to send push notification to a given client.
@@ -346,7 +345,7 @@ message PushNotificationRequest {
```
#### Handle Notification Request:
- A `PushNotificationRequest` message MUST be wrapped in a
[`ApplicationMetadataMessage`](../62/payloads.md) with type set to `PUSH_NOTIFICATION_REQUEST`.
[`ApplicationMetadataMessage`](../62/payloads) with type set to `PUSH_NOTIFICATION_REQUEST`.
- Where `message` is the encrypted payload of the message and `chat_id` is the `SHAKE-256` of the `chat_id`.
`message_id` is the id of the message `author` is the `SHAKE-256` of the public key of the sender.
@@ -411,10 +410,10 @@ message PushNotificationResponse {
Where `message_id` is the `message_id` sent by the client.
#### Handle Notification Response:
- A `PushNotificationResponse` message MUST be wrapped in a [`ApplicationMetadataMessage`](../62/payloads.md) with type set to `PUSH_NOTIFICATION_RESPONSE`.
- A `PushNotificationResponse` message MUST be wrapped in a [`ApplicationMetadataMessage`](../62/payloads) with type set to `PUSH_NOTIFICATION_RESPONSE`.
- The response MUST be sent on the [partitioned topic](../../waku/standards/application/54/x3dh-sessions.md) of the sender and
MUST not be encrypted using the [secure transport](../../waku/standards/application/53/x3dh.md) to facilitate the usage of ephemeral keys.
- The response MUST be sent on the [partitioned topic](../../waku/standards/application/54/x3dh-sessions) of the sender and
MUST not be encrypted using the [secure transport](../../waku/standards/application/53/x3dh) to facilitate the usage of ephemeral keys.
- If the request is accepted `success` MUST be set to `true`. Otherwise `success` MUST be set to `false`.
@@ -505,7 +504,7 @@ Data disclosed
#### PushNotificationRequest:
`requests`: a list of PushNotification\<br /\>
`message_id`: the [Status message id](../62/payloads.md)
`message_id`: the [Status message id](../62/payloads)
Data disclosed
- The status `message_id` for which the notification is for
@@ -526,7 +525,7 @@ A client in anonymous mode can register with the server using a key that is diff
This will hide their real chat key. This public key is effectively a secret and
SHOULD only be disclosed to clients approved to notify a user.
- A client MAY advertise the access token on the [contact-code topic](../../waku/standards/application/53/x3dh.md) of the key generated.
- A client MAY advertise the access token on the [contact-code topic](../../waku/standards/application/53/x3dh) of the key generated.
- A client MAY share their public key contact updates in the [protobuf record](https://developers.google.com/protocol-buffers/).
@@ -534,7 +533,7 @@ SHOULD only be disclosed to clients approved to notify a user.
The method described above effectively does not share the identity of the sender nor the receiver to the server, but
MAY result in missing push notifications as the propagation of the secret is left to the client.
This can be mitigated by [device syncing](../62/payloads.md), but not completely addressed.
This can be mitigated by [device syncing](../62/payloads), but not completely addressed.
## Security/Privacy Considerations
If anonymous mode is not used, when registering with a push notification service a client will disclose:
@@ -559,13 +558,13 @@ When sending a push notification a client will disclose:
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
## References
1. [PUSH-NOTIFICATION-SERVER, Initial Specification](https://github.com/status-im/specs/blob/master/docs/raw/push-notification-server.md)
1. [PUSH-NOTIFICATION-SERVER, Initial Specification](https://github.com/status-im/specs/blob/master/docs/raw/push-notification-server)
2. [Push Notification, Apple Developer](https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/APNSOverview.html#//apple_ref/doc/uid/TP40008194-CH8-SW1)
3. [Firebase](https://firebase.google.com)
4. [13/WAKU2-STORE](../../waku/standards/core/13/store.md)
4. [13/WAKU2-STORE](../../waku/standards/core/13/store)
5. [gorush](https://github.com/appleboy/gorush)
6. [54/WAKU2-X3DH-SESSIONS](../../waku/standards/application/54/x3dh-sessions.md)
7. [62/PAYLOAD](../62/payloads.md)
6. [54/WAKU2-X3DH-SESSIONS](../../waku/standards/application/54/x3dh-sessions)
7. [62/PAYLOAD](../62/payloads)
8. [SHAKE-256](https://nvlpubs.nist.gov/nistpubs/fips/nist.fips.202.pdf)
9. [Protocol Buffers](https://developers.google.com/protocol-buffers)
10. [53/WAKU2-X3DH](../../waku/standards/application/53/x3dh.md)
10. [53/WAKU2-X3DH](../../waku/standards/application/53/x3dh)

108
status/simple-scaling.md → status/raw/simple-scaling.md
View File

@@ -1,4 +1,5 @@
---
title: 57/STATUS-Simple-Scaling
name: Status Simple Scaling
status: raw
@@ -7,7 +8,6 @@ description: Describes how to scale Status Communities and Status 1-to-1 chats u
editor: Daniel Kaiser \<danielkaiser@status.im\>
contributors:
- Alvaro Revuelta \<alrevuelta@status.im\>
sidebar_position: 57
---
- Status: raw
- Category: Informational
@@ -17,7 +17,7 @@ sidebar_position: 57
## Abstract
This document describes how to scale [56/STATUS-COMMUNITIES](../56/communities.md) as well as [55/STATUS-1TO1-CHAT](../55/1to1-chat.md)
This document describes how to scale [56/STATUS-COMMUNITIES](../56/communities) as well as [55/STATUS-1TO1-CHAT](../55/1to1-chat)
using Waku v2 protocol and components.
It also adds a few new aspects, where more sophisticated components are not yet researched and evaluated.
@@ -29,8 +29,8 @@ We believe in incremental improvement, i.e. having a working decentralized scali
## Background and Motivation
[56/STATUS-COMMUNITIES](../56/communities.md) as well as [55/STATUS-1TO1-CHAT](../55/1to1-chat.md) use Waku v2 protocols.
Both use Waku content topics (see [23/WAKU2-TOPICS](../../waku/informational/23/topics.md)) for content based filtering.
[56/STATUS-COMMUNITIES](../56/communities) as well as [55/STATUS-1TO1-CHAT](../55/1to1-chat) use Waku v2 protocols.
Both use Waku content topics (see [23/WAKU2-TOPICS](../../waku/informational/23/topics)) for content based filtering.
Waku v2 currently has scaling limitations in two dimensions:
@@ -50,14 +50,14 @@ Splitting content topics in a more sophisticated and efficient way will be part
## Relay Shards
Sharding the [11/WAKU2-RELAY](../../waku/standards/core/11/relay.md) network is an integral part of scaling the Status app.
Sharding the [11/WAKU2-RELAY](../../waku/standards/core/11/relay) network is an integral part of scaling the Status app.
[51/WAKU2-RELAY-SHARDING](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/relay-sharding.md) specifies shards clusters, which are sets of `1024` shards (separate pubsub mesh networks).
[51/WAKU2-RELAY-SHARDING](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/relay-sharding) specifies shards clusters, which are sets of `1024` shards (separate pubsub mesh networks).
Content topics specified by application protocols can be distributed over these shards.
The Status app protocols are assigned to shard cluster `16`,
as defined in [WAKU2-RELAY-STATIC-SHARD-ALLOC](https://github.com/waku-org/specs/blob/waku-RFC/informational/relay-static-shard-alloc.md).
as defined in [WAKU2-RELAY-STATIC-SHARD-ALLOC](https://github.com/waku-org/specs/blob/waku-RFC/informational/relay-static-shard-alloc).
[WAKU2-RELAY-SHARDING](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/relay-sharding.md) specifies three sharding methods.
[WAKU2-RELAY-SHARDING](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/relay-sharding) specifies three sharding methods.
This document uses *static sharding*, which leaves the distribution of content topics to application protocols,
but takes care of shard discovery.
@@ -73,7 +73,7 @@ The 1024 shards within the main Status shard cluster are allocated as follows.
| 768 - 895 | 1:1 chat |
| 896 - 1023 | media and control msgs |
Shard indices are mapped to pubsub topic names as follows (specified in [WAKU2-RELAY-SHARDING](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/relay-sharding.md)).
Shard indices are mapped to pubsub topic names as follows (specified in [WAKU2-RELAY-SHARDING](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/relay-sharding)).
`/waku/2/rs/\<cluster_id\>/\<shard_number\>`
@@ -136,19 +136,19 @@ message CommunityDescription {
}
```
\> *Note*: Currently, Status app has allocated shared cluster `16` in [52/WAKU2-RELAY-STATIC-SHARD-ALLOC](https://github.com/waku-org/specs/blob/waku-RFC/informational/relay-static-shard-alloc.md).
\> *Note*: Currently, Status app has allocated shared cluster `16` in [52/WAKU2-RELAY-STATIC-SHARD-ALLOC](https://github.com/waku-org/specs/blob/waku-RFC/informational/relay-static-shard-alloc).
Status app could allocate more shard clusters, for instance to establish a test net.
We could add the shard cluster index to the community description as well.
The recommendation for now is to keep it as a configuration option of the Status app.
\> *Note*: Once this RFC moves forward, the new community description protobuf fields should be mentioned in [56/STATUS-COMMUNITIES](../56/communities.md).
\> *Note*: Once this RFC moves forward, the new community description protobuf fields should be mentioned in [56/STATUS-COMMUNITIES](../56/communities).
Status communities can be mapped to shards in two ways: static, and owner-based.
#### Static Mapping
With static mapping, communities are assigned a specific shard index within the Status shard cluster.
This mapping is similar in nature to the shard cluster allocation in [WAKU2-RELAY-STATIC-SHARD-ALLOC](https://github.com/waku-org/specs/blob/waku-RFC/informational/relay-static-shard-alloc.md).
This mapping is similar in nature to the shard cluster allocation in [WAKU2-RELAY-STATIC-SHARD-ALLOC](https://github.com/waku-org/specs/blob/waku-RFC/informational/relay-static-shard-alloc).
Shard indices allocated in that way are in the range `16 - 127`.
The Status CC community uses index `16` (not to confuse with shard cluster index `16`, which is the Status shard cluster).
@@ -160,7 +160,7 @@ Community owners can choose to map their communities to any shard within the ind
### 1:1 Chat
[55/STATUS-1TO1-CHAT](../55/1to1-chat.md) uses partitioned topics to map 1:1 chats to a set of 5000 content topics.
[55/STATUS-1TO1-CHAT](../55/1to1-chat) uses partitioned topics to map 1:1 chats to a set of 5000 content topics.
This document extends this mapping to 8192 content topics that are, in turn, mapped to 128 shards in the index range of `768 - 895`.
```
@@ -177,7 +177,7 @@ shardIndex = 768 + mod(publicKey, shardNum)
## Infrastructure Nodes
As described in [30/ADAPTIVE-NODES](../../waku/informational/30/adaptive-nodes.md),
As described in [30/ADAPTIVE-NODES](../../waku/informational/30/adaptive-nodes),
Waku supports a continuum of node types with respect to available resources.
Infrastructure nodes are powerful nodes that have a high bandwidth connection and a high up-time.
@@ -215,7 +215,7 @@ We could improve on this in the future, and research the applicability of PIR (p
## Infrastructure Shards
Waku messages are typically relayed in larger mesh networks comprised of nodes with varying resource profiles (see [30/ADAPTIVE-NODES](../../waku/informational/30/adaptive-nodes.md).
Waku messages are typically relayed in larger mesh networks comprised of nodes with varying resource profiles (see [30/ADAPTIVE-NODES](../../waku/informational/30/adaptive-nodes).
To maximise scaling, relaying of specific message types can be dedicated to shards where only infrastructure nodes with very strong resource profiles relay messages.
This comes as a trade-off to decentralization.
@@ -262,15 +262,15 @@ and devices that (temporarily) have a low bandwidth connection or a connection w
Light protocols comprise
* [19/WAKU2-LIGHTPUSH](../../waku/standards/core/19/lightpush.md) for sending messages
* [12/WAKU2-FILTER](../../waku/standards/core/12/filter.md) for requesting messages with specific attributes
* [WAKU2-PEER-EXCHANGE](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/peer-exchange/peer-exchange.md) for discovering peers
* [19/WAKU2-LIGHTPUSH](../../waku/standards/core/19/lightpush) for sending messages
* [12/WAKU2-FILTER](../../waku/standards/core/12/filter) for requesting messages with specific attributes
* [WAKU2-PEER-EXCHANGE](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/peer-exchange/peer-exchange) for discovering peers
## Waku Archive
Archive nodes are Waku nodes that offer the Waku archive service via the Waku store protocol ([13/WAKU2-STORE](../../waku/standards/core/13/store.md)).
Archive nodes are Waku nodes that offer the Waku archive service via the Waku store protocol ([13/WAKU2-STORE](../../waku/standards/core/13/store)).
They are part of a set of shards and store all messages disseminated in these shards.
Nodes can request history messages via the [13/WAKU2-STORE](../../waku/standards/core/13/store.md).
Nodes can request history messages via the [13/WAKU2-STORE](../../waku/standards/core/13/store).
The store service is not limited to a Status fleet.
Anybody can run a Waku Archive node in the Status shards.
@@ -284,17 +284,17 @@ In fact, the archive service can be offered by infrastructure nodes.
## Discovery
Shard discovery is covered by [WAKU2-RELAY-SHARDING](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/relay-sharding.md).
Shard discovery is covered by [WAKU2-RELAY-SHARDING](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/relay-sharding).
This allows the Status app to abstract from the discovery process and simply address shards by their index.
### Libp2p Rendezvous and Circuit-Relay
To make nodes behind restrictive NATs discoverable,
this document suggests using [libp2p rendezvous](https://github.com/libp2p/specs/blob/master/rendezvous/README.md).
Nodes can check whether they are behind a restrictive NAT using the [libp2p AutoNAT protocol](https://github.com/libp2p/specs/blob/master/autonat/README.md).
this document suggests using [libp2p rendezvous](https://github.com/libp2p/specs/blob/master/rendezvous/README).
Nodes can check whether they are behind a restrictive NAT using the [libp2p AutoNAT protocol](https://github.com/libp2p/specs/blob/master/autonat/README).
\> *Note:* The following will move into [WAKU2-RELAY-SHARDING](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/relay-sharding.md), or [33/WAKU2-DISCV5](../../waku/standards/core/33/discv5.md):
Nodes behind restrictive NATs SHOULD not announce their publicly unreachable address via [33/WAKU2-DISCV5](../../waku/standards/core/33/discv5.md) discovery.
\> *Note:* The following will move into [WAKU2-RELAY-SHARDING](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/relay-sharding), or [33/WAKU2-DISCV5](../../waku/standards/core/33/discv5):
Nodes behind restrictive NATs SHOULD not announce their publicly unreachable address via [33/WAKU2-DISCV5](../../waku/standards/core/33/discv5) discovery.
It is RECOMMENDED that nodes that are part of the relay network also act as rendezvous points.
This includes accepting register queries from peers, as well as answering rendezvous discover queries.
@@ -302,17 +302,17 @@ Nodes MAY opt-out of the rendezvous functionality.
To allow nodes to initiate connections to peers behind restrictive NATs (after discovery via rendezvous),
it is RECOMMENDED that nodes that are part of the Waku relay network also offer
[libp2p circuit relay](https://github.com/libp2p/specs/blob/6634ca7abb2f955645243d48d1cd2fd02a8e8880/relay/circuit-v2.md) functionality.
[libp2p circuit relay](https://github.com/libp2p/specs/blob/6634ca7abb2f955645243d48d1cd2fd02a8e8880/relay/circuit-v2) functionality.
To minimize the load on circuit-relay nodes, nodes SHOULD
1) make use of the [limiting](https://github.com/libp2p/specs/blob/6634ca7abb2f955645243d48d1cd2fd02a8e8880/relay/circuit-v2.md#reservation)
1) make use of the [limiting](https://github.com/libp2p/specs/blob/6634ca7abb2f955645243d48d1cd2fd02a8e8880/relay/circuit-v2##reservation)
functionality offered by the libp2p circuit relay protocols, and
2) use [DCUtR](https://github.com/libp2p/specs/blob/master/relay/DCUtR.md) to upgrade to a direct connection.
2) use [DCUtR](https://github.com/libp2p/specs/blob/master/relay/DCUtR) to upgrade to a direct connection.
Nodes that do not announce themselves at all and only plan to use light protocols,
MAY use rendezvous discovery instead of or along-side [WAKU2-PEER-EXCHANGE](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/peer-exchange/peer-exchange.md).
For these nodes, rendezvous and [WAKU2-PEER-EXCHANGE](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/peer-exchange/peer-exchange.md) offer the same functionality,
MAY use rendezvous discovery instead of or along-side [WAKU2-PEER-EXCHANGE](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/peer-exchange/peer-exchange).
For these nodes, rendezvous and [WAKU2-PEER-EXCHANGE](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/peer-exchange/peer-exchange) offer the same functionality,
but return node sets sampled in different ways.
Using both can help increasing connectivity.
@@ -322,7 +322,7 @@ Such nodes SHOULD, however, not register at circuit relays.
### Announcing Shard Participation
Registering a namespace via [lib-p2p rendezvous](https://github.com/libp2p/specs/blob/master/rendezvous/README.md#interaction)
Registering a namespace via [lib-p2p rendezvous](https://github.com/libp2p/specs/blob/master/rendezvous/README##interaction)
is done via a register query:
```
@@ -336,10 +336,10 @@ The app name, `my-app` contains the encoding of a single shard in string form:
```
The string conversion SHOULD remove leading zeros.
\> *Note:* Since the [ns](https://github.com/libp2p/specs/blob/master/rendezvous/README.md#protobuf) field is of type string,
\> *Note:* Since the [ns](https://github.com/libp2p/specs/blob/master/rendezvous/README##protobuf) field is of type string,
a more efficient byte encoding is not utilized.
Registering shard 2 in the Status shard cluster (with shard cluster index 16, see [WAKU2-RELAY-STATIC-SHARD-ALLOC](https://github.com/waku-org/specs/blob/waku-RFC/informational/relay-static-shard-alloc.md),
Registering shard 2 in the Status shard cluster (with shard cluster index 16, see [WAKU2-RELAY-STATIC-SHARD-ALLOC](https://github.com/waku-org/specs/blob/waku-RFC/informational/relay-static-shard-alloc),
the register query would look like
```
@@ -412,7 +412,7 @@ Requirements on the gossipsub validator:
Other requirements:
* The node shall keep metrics on the messages validation output, `Accept` or `Reject`.
* (Optional). To further strengthen DoS protection, gossipsub [scoring](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md#extended-validators) can be used to trigger disconnections from peers sending multiple invalid messages. See `P4` penalty.
* (Optional). To further strengthen DoS protection, gossipsub [scoring](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1##extended-validators) can be used to trigger disconnections from peers sending multiple invalid messages. See `P4` penalty.
This protects each peer from DoS, since this score is used to trigger disconnections from nodes attempting to DoS them.
@@ -470,7 +470,7 @@ It could be rate-limited with RLN.
This document makes several trade-offs to privacy and anonymity.
Todo: elaborate.
See [WAKU2-ADVERSARIAL-MODELS](https://github.com/waku-org/specs/blob/waku-RFC/informational/adversarial-models.md) for information on Waku Anonymity.
See [WAKU2-ADVERSARIAL-MODELS](https://github.com/waku-org/specs/blob/waku-RFC/informational/adversarial-models) for information on Waku Anonymity.
## Copyright
@@ -478,27 +478,27 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public
## References
* [56/STATUS-COMMUNITIES](../56/communities.md)
* [55/STATUS-1TO1-CHAT](.../55/1to1-chat.md)
* [56/STATUS-COMMUNITIES](../56/communities)
* [55/STATUS-1TO1-CHAT](.../55/1to1-chat)
* [23/WAKU2-TOPICS](../../waku/informational/23/)
* [11/WAKU2-RELAY](../../waku/standards/core/11/relay.md)
* [WAKU2-RELAY-SHARDING](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/relay-sharding.md)
* [WAKU2-RELAY-STATIC-SHARD-ALLOC](https://github.com/waku-org/specs/blob/waku-RFC/informational/relay-static-shard-alloc.md)
* [30/ADAPTIVE-NODES](../../waku/informational/30/adaptive-nodes.md)
* [19/WAKU2-LIGHTPUSH](../../waku/standards/core/19/lightpush.md)
* [12/WAKU2-FILTER](../../waku/standards/core/12/filter.md)
* [WAKU2-PEER-EXCHANGE](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/peer-exchange/peer-exchange.md)
* [13/WAKU2-STORE](../../waku/standards/core/13/store.md)
* [libp2p rendezvous](https://github.com/libp2p/specs/blob/master/rendezvous/README.md)
* [libp2p AutoNAT protocol](https://github.com/libp2p/specs/blob/master/autonat/README.md)
* [33/WAKU2-DISCV5](../../waku/standards/core/33/discv5.md)
* [libp2p circuit relay](https://github.com/libp2p/specs/blob/6634ca7abb2f955645243d48d1cd2fd02a8e8880/relay/circuit-v2.md)
* [limiting](https://github.com/libp2p/specs/blob/6634ca7abb2f955645243d48d1cd2fd02a8e8880/relay/circuit-v2.md#reservation)
* [DCUtR](https://github.com/libp2p/specs/blob/master/relay/DCUtR.md)
* [scoring](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md#extended-validators)
* [11/WAKU2-RELAY](../../waku/standards/core/11/relay)
* [WAKU2-RELAY-SHARDING](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/relay-sharding)
* [WAKU2-RELAY-STATIC-SHARD-ALLOC](https://github.com/waku-org/specs/blob/waku-RFC/informational/relay-static-shard-alloc)
* [30/ADAPTIVE-NODES](../../waku/informational/30/adaptive-nodes)
* [19/WAKU2-LIGHTPUSH](../../waku/standards/core/19/lightpush)
* [12/WAKU2-FILTER](../../waku/standards/core/12/filter)
* [WAKU2-PEER-EXCHANGE](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/peer-exchange/peer-exchange)
* [13/WAKU2-STORE](../../waku/standards/core/13/store)
* [libp2p rendezvous](https://github.com/libp2p/specs/blob/master/rendezvous/README)
* [libp2p AutoNAT protocol](https://github.com/libp2p/specs/blob/master/autonat/README)
* [33/WAKU2-DISCV5](../../waku/standards/core/33/discv5)
* [libp2p circuit relay](https://github.com/libp2p/specs/blob/6634ca7abb2f955645243d48d1cd2fd02a8e8880/relay/circuit-v2)
* [limiting](https://github.com/libp2p/specs/blob/6634ca7abb2f955645243d48d1cd2fd02a8e8880/relay/circuit-v2##reservation)
* [DCUtR](https://github.com/libp2p/specs/blob/master/relay/DCUtR)
* [scoring](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1##extended-validators)
* [Circuit Relay](https://docs.libp2p.io/concepts/nat/circuit-relay/)
* [WAKU2-ADVERSARIAL-MODELS](https://github.com/waku-org/specs/blob/waku-RFC/informational/adversarial-models.md)
* [WAKU2-ADVERSARIAL-MODELS](https://github.com/waku-org/specs/blob/waku-RFC/informational/adversarial-models)
## Informative
* [Circuit Relay](https://docs.libp2p.io/concepts/nat/circuit-relay/)
* [WAKU2-ENR](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/enr.md)
* [WAKU2-ENR](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/enr)

1
status/status-waku-usage.md → status/raw/status-waku-usage.md
View File

@@ -8,7 +8,6 @@ editor: Aaryamann Challani \<aaryamann@status.im\>
contributors:
- Jimmy Debe \<jimmy@status.im\>
sidebar_position: 1
---
- Status: raw
- Category: Best Current Practice

11
vac/coss.md → vac/1/coss.md
View File

@@ -11,7 +11,6 @@ contributors:
- Chris Puttick \<chris.puttick@thehumanjourney.net\>
- Yurii Rashkovskii \<yrashk@gmail.com\>
- Daniel Kaiser \<danielkaiser@status.im\>
sidebar_position: 1
---
- Status: draft
- Category: Best Current Practice
@@ -27,7 +26,7 @@ sidebar_position: 1
This document describes a consensus-oriented specification system (COSS) for building interoperable technical specifications.
COSS is based on a lightweight editorial process that seeks to engage the widest possible range of interested parties and move rapidly to consensus through working code.
This specification is based on [Unprotocols 2/COSS](https://github.com/unprotocols/rfc/blob/master/2/README.md), used by the [ZeromMQ](https://rfc.zeromq.org/) project.
This specification is based on [Unprotocols 2/COSS](https://github.com/unprotocols/rfc/blob/master/2/README), used by the [ZeromMQ](https://rfc.zeromq.org/) project.
It is equivalent except for some areas:
- recommending the use of a permissive licenses, such as CC0 (with the exception of this document);
@@ -55,7 +54,7 @@ if not, see http://www.gnu.org/licenses.
## Change Process
This document is governed by the [1/COSS](./coss.md) (COSS).
This document is governed by the [1/COSS](./coss) (COSS).
## Language
@@ -114,7 +113,7 @@ Every specification has an independent lifecycle that documents clearly its curr
A specification has six possible states that reflect its maturity and contractual weight:
![Lifecycle diagram](./1/images/lifecycle.png)
![Lifecycle diagram](./images/lifecycle.png)
### Raw Specifications
@@ -160,7 +159,7 @@ A specification MUST have a single responsible editor,
the only person who SHALL change the status of the specification through the lifecycle stages.
A specification MAY also have additional contributors who contribute changes to it.
It is RECOMMENDED to use a process similar to [C4 process](https://github.com/unprotocols/rfc/blob/master/1/README.md)
It is RECOMMENDED to use a process similar to [C4 process](https://github.com/unprotocols/rfc/blob/master/1/README)
to maximize the scale and diversity of contributions.
Unlike the original C4 process however, it is RECOMMENDED to use CC0 as a more permissive license alternative.
@@ -215,7 +214,7 @@ This will enable programmatic access to specification metadata.
### Specification Template
Standards Track specifications SHOULD be based on the [Vac RFC template](./images/template.md).
Standards Track specifications SHOULD be based on the [Vac RFC template](./images/template).
## Conventions

3
vac/mvds.md → vac/2/mvds.md
View File

@@ -6,7 +6,6 @@ editor: Sanaz Taheri \<sanaz@status.im\>
contributors:
- Dean Eigenmann \<dean@status.im\>
- Oskar Thorén \<oskarth@titanproxy.com\>
sidebar_position: 2
---
- Status: stable
- Editor: Sanaz Taheri \<sanaz@status.im\>
@@ -155,5 +154,5 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public
## Footnotes
[^1]: akwizgran et al. [BSP](https://code.briarproject.org/briar/briar-spec/blob/master/protocols/BSP.md). Briar.
[^1]: akwizgran et al. [BSP](https://code.briarproject.org/briar/briar-spec/blob/master/protocols/BSP). Briar.
[^2]: \<https://github.com/vacp2p/mvds\>

5
vac/libp2p-dns-discovery.md → vac/25/libp2p-dns-discovery.md
View File

@@ -4,14 +4,13 @@ name: Libp2p Peer Discovery via DNS
status: deleted
editor: Hanno Cornelius \<hanno@status.im\>
contributors:
sidebar_position: 25
---
- Status: deleted
- Editor: Hanno Cornelius \<hanno@status.im\>
`25/LIBP2P-DNS-DISCOVERY` specifies a scheme to implement [`libp2p`](https://libp2p.io/) peer discovery via DNS for Waku v2.
The generalised purpose is to retrieve an arbitrarily long, authenticated, updateable list of [`libp2p` peers](https://docs.libp2p.io/concepts/peer-id/) to bootstrap connection to a `libp2p` network.
Since [`10/WAKU2`](../../waku/standards/core/10/waku2.md) currently specifies use of [`libp2p` peer identities](https://docs.libp2p.io/concepts/peer-id/),
Since [`10/WAKU2`](../../waku/standards/core/10/waku2) currently specifies use of [`libp2p` peer identities](https://docs.libp2p.io/concepts/peer-id/),
this method is suitable for a new Waku v2 node to discover other Waku v2 nodes to connect to.
This specification is largely based on [EIP-1459](https://eips.ethereum.org/EIPS/eip-1459),
@@ -128,7 +127,7 @@ Copyright and related rights waived via
# References
1. [`10/WAKU2`](../../waku/standards/core/10/waku2.md)
1. [`10/WAKU2`](../../waku/standards/core/10/waku2)
1. [EIP-1459: Client Protocol](https://eips.ethereum.org/EIPS/eip-1459#client-protocol)
1. [EIP-1459: Node Discovery via DNS ](https://eips.ethereum.org/EIPS/eip-1459)
1. [`libp2p`](https://libp2p.io/)

3
vac/remote-log.md → vac/3/remote-log.md
View File

@@ -5,7 +5,6 @@ status: draft
editor: Oskar Thorén \<oskarth@titanproxy.com\>
contributors:
- Dean Eigenmann \<dean@status.im\>
sidebar_position: 3
---
- Status: draft
- Editor: Oskar Thorén \<oskarth@titanproxy.com\>
@@ -232,7 +231,7 @@ in time.
### Interaction with MVDS
[vac.mvds.Message](../2/mvds.md/#payloads) payloads are the only payloads that MUST be uploaded. Other messages types MAY be uploaded, depending on the implementation.
[vac.mvds.Message](../2/mvds#payloads) payloads are the only payloads that MUST be uploaded. Other messages types MAY be uploaded, depending on the implementation.
## Acknowledgments

3
vac/rln-v1.md → vac/32/rln-v1.md
View File

@@ -9,7 +9,6 @@ contributors:
- Oskar Thorén \<oskarth@titanproxy.com\>
- Onur Kilic \<onurkilic1004@gmail.com\>
- Blagoj Dimovski \<blagoj.dimovski@yandex.com\>
sidebar_position: 32
---
- Status: raw
- Editor: Rasul Ibragimov \<curryrasul@gmail.com\>
@@ -28,7 +27,7 @@ RLN guarantees a messaging rate is enforced cryptographically while preserving t
A wide range of applications can benefit from RLN and provide desirable security features.
For example, an e-voting system can integrate RLN to contain the voting rate while protecting the voters-vote unlinkability.
Another use case is to protect an anonymous messaging system against DDoS and spam attacks by containing messaging rate of users.
This latter use case is explained in [17/WAKU2-RLN-RELAY RFC](../../waku/standards/core/17/rln-relay.md).
This latter use case is explained in [17/WAKU2-RLN-RELAY RFC](../../waku/standards/core/17/rln-relay).
## Flow

11
vac/mvds-meta.md → vac/4/mvds-meta.md
View File

@@ -7,7 +7,6 @@ contributors:
- Dean Eigenmann \<dean@status.im\>
- Andrea Maria Piana \<andreap@status.im\>
- Oskar Thorén \<oskarth@titanproxy.com\>
sidebar_position: 4
---
- Status: draft
- Editor: Sanaz Taheri \<sanaz@status.im\>
@@ -16,7 +15,7 @@ sidebar_position: 4
- Andrea Maria Piana \<andreap@status.im\>
- Oskar Thorén \<oskarth@titanproxy.com\>
In this specification, we describe a method to construct message history that will aid the consistency guarantees of [2/MVDS](../2/mvds.md). Additionally, we explain how data sync can be used for more lightweight messages that do not require full synchronization.
In this specification, we describe a method to construct message history that will aid the consistency guarantees of [2/MVDS](../2/mvds). Additionally, we explain how data sync can be used for more lightweight messages that do not require full synchronization.
## Motivation
@@ -35,7 +34,7 @@ message Metadata {
}
```
Nodes MAY transmit a `Metadata` message by extending the MVDS [message](../2/mvds.md/#payloads) with a `metadata` field.
Nodes MAY transmit a `Metadata` message by extending the MVDS [message](../2/mvds#payloads) with a `metadata` field.
```diff
message Message {
@@ -50,14 +49,14 @@ message Message {
| Name | Description |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `parents` | list of parent [`message identifier`s](../2/mvds.md/#payloads) for the specific message. |
| `parents` | list of parent [`message identifier`s](../2/mvds#payloads) for the specific message. |
| `ephemeral` | indicates whether a message is ephemeral or not. |
## Usage
### `parents`
This field contains a list of parent [`message identifier`s](../2/mvds.md/#payloads) for the specific message. It MUST NOT contain any messages as parent whose `ack` flag was set to `false`. This establishes a directed acyclic graph (DAG)[^2] of persistent messages.
This field contains a list of parent [`message identifier`s](../2/mvds#payloads) for the specific message. It MUST NOT contain any messages as parent whose `ack` flag was set to `false`. This establishes a directed acyclic graph (DAG)[^2] of persistent messages.
Nodes MAY buffer messages until dependencies are satisfied for causal consistency[^3], they MAY also pass the messages straight away for eventual consistency[^4].
@@ -80,7 +79,7 @@ Nodes SHOULD send ephemeral messages in batch mode. As their delivery is not nee
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
## Footnotes
[^1]: [2/MVDS](../2/mvds.md)
[^1]: [2/MVDS](../2/mvds)
[^2]: \<https://en.wikipedia.org/wiki/Directed_acyclic_graph\>
[^3]: Jepsen. [Causal Consistency](https://jepsen.io/consistency/models/causal). Jepsen, LLC.
[^4]: \<https://en.wikipedia.org/wiki/Eventual_consistency\>

17
vac/gossipsub-tor-push.md → vac/46/gossipsub-tor-push.md
View File

@@ -5,7 +5,6 @@ status: raw
category: Standards Track
editor: Daniel Kaiser \<danielkaiser@status.im\>
contributors:
sidebar_position: 46
---
- Status: raw
- Category: Standards Track
@@ -13,7 +12,7 @@ sidebar_position: 46
## Abstract
This document extends the [libp2p gossipsub specification](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/README.md)
This document extends the [libp2p gossipsub specification](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/README)
specifying gossipsub Tor Push,
a gossipsub-internal way of pushing messages into a gossipsub network via Tor.
Tor Push adds sender identity protection to gossipsub.
@@ -26,7 +25,7 @@ This allows nodes that are oblivious to Tor Push to process messages received vi
## Background
Without extensions, [libp2p gossipsub](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/README.md)
Without extensions, [libp2p gossipsub](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/README)
does not protect sender identities.
A possible design of an anonymity extension to gossipsub is pushing messages through an anonymization network before they enter the gossipsub network.
@@ -84,11 +83,11 @@ The Tp-context MUST NOT share any data, e.g. peer lists, with the default contex
Tp-peers are peers a Tp-node plans to send Tp-messages to.
Tp-peers MUST support `/meshsub/1.1.0`.
For retrieving Tp-peers, Tp-nodes SHOULD use an ambient peer discovery method that retrieves a random peer sample (from the set of all peers), e.g. [33/WAKU2-DISCV5](../../waku/standards/core/33/discv5.md).
For retrieving Tp-peers, Tp-nodes SHOULD use an ambient peer discovery method that retrieves a random peer sample (from the set of all peers), e.g. [33/WAKU2-DISCV5](../../waku/standards/core/33/discv5).
Tp-nodes MUST establish a connection as described in sub-section [Tor Push Connection Establishment](#connection-establishment) to at least one Tp-peer.
To significantly increase resilience, Tp-nodes SHOULD establish Tp-connections to `D` peers,
where `D` is the [desired gossipsub out-degree](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.0.md#parameters),
where `D` is the [desired gossipsub out-degree](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.0##parameters),
with a default value of `8`.
Each Tp-message MUST be sent via the Tp-context over at least one Tp-connection.
@@ -143,7 +142,7 @@ Still, messages might be delayed during this window which might be critical to c
#### Targeting the Gossipsub Network
Without sophisticated rate limiting (for example using [17/WAKU2-RLN-RELAY](../../waku/standards/core/17/rln-relay.md)),
Without sophisticated rate limiting (for example using [17/WAKU2-RLN-RELAY](../../waku/standards/core/17/rln-relay)),
attackers can spam the gossipsub network.
It is not enough to just block peers that send too many messages,
because these messages might actually come from a Tor exit node that many honest Tp-nodes use.
@@ -176,12 +175,12 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public
## References
* [libp2p gossipsub](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/README.md)
* [libp2p gossipsub](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/README)
* [libp2p pubsub](https://github.com/libp2p/specs/tree/master/pubsub)
* [libp2p pubsub message](https://github.com/libp2p/specs/tree/master/pubsub#the-message)
* [libp2p switch](https://docs.libp2p.io/concepts/multiplex/switch)
* [SOCKS5](https://www.rfc-editor.org/rfc/rfc1928)
* [Tor](https://www.torproject.org/)
* [33/WAKU2-DISCV5](../../waku/standards/core/33/discv5.md)
* [33/WAKU2-DISCV5](../../waku/standards/core/33/discv5)
* [Bitcoin over Tor isn't a Good Idea](https://ieeexplore.ieee.org/abstract/document/7163022)
* [17/WAKU2-RLN-RELAY](../../waku/standards/core/17/rln-relay.md)
* [17/WAKU2-RLN-RELAY](../../waku/standards/core/17/rln-relay)

11
vac/rln-interep-spec.md → vac/48/rln-interep-spec.md
View File

@@ -5,7 +5,6 @@ status: raw
category:
editor: Aaryamann Challani \<aaryamann@status.im\>
contributors:
sidebar_position: 48
---
- Status: raw
- Category:
@@ -13,7 +12,7 @@ sidebar_position: 48
## Abstract
This spec integrates [Interep](https://interep.link) into the [RLN](../32/rln-v1.md) spec.
This spec integrates [Interep](https://interep.link) into the [RLN](../32/rln-v1) spec.
Interep is a group management protocol that allows for the creation of groups of users and the management of their membership.
It is used to manage the membership of the RLN group.
@@ -81,11 +80,11 @@ Following is the modified signature of the register function in the RLN contract
## Verification of messages
Messages are verified the same way as in the [RLN spec](../32/rln-v1.md/#verification).
Messages are verified the same way as in the [RLN spec](../32/rln-v1#verification).
## Slashing
The slashing mechanism is the same as in the [RLN spec](../32/rln-v1.md/#slashing).
The slashing mechanism is the same as in the [RLN spec](../32/rln-v1#slashing).
It is important to note that the slashing may not have the intended effect on the user, since the only consequence is that they cannot send messages.
This is due to the fact that the user can send a identity commitment in the registration to the RLN contract, which is different than the one used in the Interep group.
@@ -96,13 +95,13 @@ A proof of concept is available at [vacp2p/rln-interp-contract](https://github.c
## Security Considerations
1. As mentioned in [Slashing](#slashing), the slashing mechanism may not have the intended effect on the user.
2. This spec inherits the security considerations of the [RLN spec](../32/rln-v1.md/#security-considerations).
2. This spec inherits the security considerations of the [RLN spec](../32/rln-v1#security-considerations).
3. This spec inherits the security considerations of [Interep](https://docs.interep.link/).
4. A user may make multiple registrations using the same Interep proofs but different identity commitments. The way to mitigate this is to check if the nullifier hash has been detected previously in proof verification.
## References
1. [RLN spec](../32/rln-v1.md)
1. [RLN spec](../32/rln-v1)
2. [Interep](https://interep.link)
3. [Semaphore](https://semaphore.appliedzkp.org/)
4. [Decentralized cloudflare using Interep](https://ethresear.ch/t/decentralised-cloudflare-using-rln-and-rich-user-identities/10774)

23
vac/rln-v2.md → vac/58/rln-v2.md
View File

@@ -5,7 +5,6 @@ status: raw
editor: Rasul Ibragimov \<curryrasul@gmail.com\>
contributors:
- Lev Soukhanov \<0xdeadfae@gmail.com\>
sidebar_position: 58
---
- Status: raw
- Editor: Rasul Ibragimov \<curryrasul@gmail.com\>
@@ -14,12 +13,12 @@ sidebar_position: 58
## Abstract
The protocol specified in this document is an improvement of [32/RLN-V1](../32/rln-v1.md), being more general construct, that allows to set various limits for an epoch (it's 1 message per epoch in [32/RLN-V1](../32/rln-v1.md)) while remaining almost as simple as it predecessor.
The protocol specified in this document is an improvement of [32/RLN-V1](../32/rln-v1), being more general construct, that allows to set various limits for an epoch (it's 1 message per epoch in [32/RLN-V1](../32/rln-v1)) while remaining almost as simple as it predecessor.
Moreover, it allows to set different rate-limits for different RLN app users based on some public data, e.g. stake or reputation.
## Motivation
The main goal of this RFC is to generalize [32/RLN-V1](../32/rln-v1.md) and expand its applications.
The main goal of this RFC is to generalize [32/RLN-V1](../32/rln-v1) and expand its applications.
There are two different subprotocols based on this protocol:
* RLN-Same - RLN with the same rate-limit for all users;
* RLN-Diff - RLN that allows to set different rate-limits for different users.
@@ -28,7 +27,7 @@ It is important to note that by using a large epoch limit value, users will be a
## Flow
As in [32/RLN-V1](../32/rln-v1.md), the general flow can be described by three steps:
As in [32/RLN-V1](../32/rln-v1), the general flow can be described by three steps:
1. Registration
2. Signaling
@@ -38,13 +37,13 @@ The two sub-protocols have different flows, and hence are defined separately.
### Important note
All terms and parameters used remain the same as in [32/RLN-V1](../32/rln-v1.md), more details [here](../32/rln-v1.md/#technical-overview)
All terms and parameters used remain the same as in [32/RLN-V1](../32/rln-v1), more details [here](../32/rln-v1#technical-overview)
## RLN-Same flow
### Registration
The registration process in the RLN-Same subprotocol does not differ from [32/RLN-V1](../32/rln-v1.md).
The registration process in the RLN-Same subprotocol does not differ from [32/RLN-V1](../32/rln-v1).
### Signalling
@@ -92,13 +91,13 @@ internal_nullifier = poseidonHash([a_1])
### Registration
**id_commitment** in [32/RLN-V1](../32/rln-v1.md) is equal to `poseidonHash(identity_secret)`.
**id_commitment** in [32/RLN-V1](../32/rln-v1) is equal to `poseidonHash(identity_secret)`.
The goal of RLN-Diff is to set different rate-limits for different users.
It follows that **id_commitment** must somehow depend on the `user_message_limit` parameter, where 0 \<= `user_message_limit` \<= `message_limit`.
There are few ways to do that:
1. Sending `identity_secret_hash` = `poseidonHash(identity_secret, userMessageLimit)` and zk proof that `user_message_limit` is valid (is in the right range).
This approach requires zkSNARK verification, which is an expensive operation on the blockchain.
2. Sending the same `identity_secret_hash` as in [32/RLN-V1](../32/rln-v1.md) (`poseidonHash(identity_secret)`) and a user_message_limit publicly to a server or smart-contract where `rate_commitment` = `poseidonHash(identity_secret_hash, userMessageLimit)` is calculated.
2. Sending the same `identity_secret_hash` as in [32/RLN-V1](../32/rln-v1) (`poseidonHash(identity_secret)`) and a user_message_limit publicly to a server or smart-contract where `rate_commitment` = `poseidonHash(identity_secret_hash, userMessageLimit)` is calculated.
The leaves in the membership Merkle tree would be the rate_commitments of the users.
This approach requires additional hashing in the Circuit, but it eliminates the need for zk proof verification for the registration.
@@ -130,12 +129,12 @@ The Output is calculated in the same way as the RLN-Same sub-protocol.
### Verification and slashing
Verification and slashing in both subprotocols remain the same as in [32/RLN-V1](../32/rln-v1.md).
Verification and slashing in both subprotocols remain the same as in [32/RLN-V1](../32/rln-v1).
The only difference that may arise is the `message_limit` check in RLN-Same, since it is now a public input of the Circuit.
### ZK Circuits specification
The design of the [32/RLN-V1](../32/rln-v1.md) circuits is different from the circuits of this protocol.
The design of the [32/RLN-V1](../32/rln-v1) circuits is different from the circuits of this protocol.
RLN-v2 requires additional algebraic constraints.
The membership proof and Shamir's Secret Sharing constraints remain unchanged.
@@ -193,7 +192,7 @@ In the RLN-Diff scheme, instead of the public parameter `message_limit`, a param
## Appendix A: Security considerations
Although there are changes in the circuits, this spec inherits all the security considerations of [32/RLN-V1](../32/rln-v1.md).
Although there are changes in the circuits, this spec inherits all the security considerations of [32/RLN-V1](../32/rln-v1).
## Copyright
@@ -203,4 +202,4 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public
- [1](https://zkresear.ch/t/rate-limit-nullifier-v2-circuits/102)
- [2](https://github.com/Rate-Limiting-Nullifier/rln-circuits-v2)
- [3](../32/rln-v1.md/#technical-overview)
- [3](../32/rln-v1#technical-overview)

3
vac/eth-secpm.md → vac/70/eth-secpm.md
View File

@@ -5,7 +5,6 @@ status: raw
category: Standards Track
editor: Ramses Fernandez \<ramses@status.im\>
contributors:
sidebar_position: 70
---
- Status: raw
- Category: Standards Track
@@ -19,7 +18,7 @@ Therefore a decentralized approach to secure communication becomes increasingly
offering a robust solution to address these challenges.
This specification outlines a private messaging service using the Ethereum blockchain as authentication service.
Rooted in the existing [model](../../waku/standards/application/20/toy-eth-pm.md),
Rooted in the existing [model](../../waku/standards/application/20/toy-eth-pm),
this proposal addresses the deficiencies related to forward privacy and authentication inherent in the current framework.
The specification is divided into 3 sections:

2
vac/raw/README.md
View File

@@ -2,4 +2,4 @@
# Vac Raw Specifications
All Vac specifications that have not reached **draft** status will live in this repository.
To learn more about **raw** specifications, take a look at [1/COSS](../1/coss.md).
To learn more about **raw** specifications, take a look at [1/COSS](../1/coss).

21
vac/rln-stealth-commitments.md → vac/raw/rln-stealth-commitments.md
View File

@@ -5,7 +5,6 @@ category: Standards Track
editor: Aaryamann Challani \<aaryamann@status.im\>
contributors:
- Jimmy Debe \<jimmy@status.im\>
sidebar_position: 1
---
- Category: Standards Track
- Editor: Aaryamann Challani \<aaryamann@status.im\>
@@ -14,11 +13,11 @@ sidebar_position: 1
## Abstract
This specification describes the usage of stealth commitments to add prospective users to a network-governed [32/RLN-V1](./32/rln-v1.md) membership set.
This specification describes the usage of stealth commitments to add prospective users to a network-governed [32/RLN-V1](./32/rln-v1) membership set.
## Motivation
When [32/RLN-V1](./32/rln-v1.md) is enforced in [10/Waku2](../waku/standards/core/10/waku2.md),
When [32/RLN-V1](./32/rln-v1) is enforced in [10/Waku2](../waku/standards/core/10/waku2),
all users are required to register to a membership set.
The membership set will store user identities allowing the secure interaction within an application.
Forcing a user to do an on-chain transaction to join a membership set is an onboarding friction,
@@ -28,24 +27,24 @@ stealth commitments can be used by a counterparty to register identities on the
while maintaining the user's anonymity.
This document specifies a privacy-preserving mechanism,
allowing a counterparty to utilize [32/RLN-V1](./32/rln-v1.md) to register an `identityCommitment` on-chain.
allowing a counterparty to utilize [32/RLN-V1](./32/rln-v1) to register an `identityCommitment` on-chain.
Counterparties will be able to register members to a RLN membership set without exposing the user's private keys.
## Background
The [32/RLN-V1](./32/rln-v1.md) protocol,
The [32/RLN-V1](./32/rln-v1) protocol,
consists of a smart contract that stores a `idenitityCommitment` in a membership set.
In order for a user to join the membership set,
the user is required to make a transaction on the blockchain.
A set of public keys is used to compute a stealth commitment for a user,
as described in [ERC-5564](https://eips.ethereum.org/EIPS/eip-5564).
This specification is an implementation of the [ERC-5564](https://eips.ethereum.org/EIPS/eip-5564) scheme,
tailored to the curve that is used in the [32/RLN-V1](./32/rln-v1.md) protocol.
tailored to the curve that is used in the [32/RLN-V1](./32/rln-v1) protocol.
This can be used in a couple of ways in applications:
1. Applications can add users to the [32/RLN-V1](./32/rln-v1.md) membership set in a batch.
2. Users of the application can register other users to the [32/RLN-V1](./32/rln-v1.md) membership set.
1. Applications can add users to the [32/RLN-V1](./32/rln-v1) membership set in a batch.
2. Users of the application can register other users to the [32/RLN-V1](./32/rln-v1) membership set.
This is useful when the prospective user does not have access to funds on the network that [32/RLN-V1](./32/rln-v1.md) is deployed on.
This is useful when the prospective user does not have access to funds on the network that [32/RLN-V1](./32/rln-v1) is deployed on.
## Wire Format Specification
@@ -105,6 +104,6 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public
## References
- [10/Waku2](../waku/standards/core/10/waku2.md)
- [32/RLN-V1](./32/rln-v1.md)
- [10/Waku2](../waku/standards/core/10/waku2)
- [32/RLN-V1](./32/rln-v1)
- [ERC-5564](https://eips.ethereum.org/EIPS/eip-5564)

1
vac/template.md
View File

@@ -5,7 +5,6 @@ status: (raw|draft|stable)
category: (Standards Track|Informational|Best Current Practice)
editor: Daniel Kaiser \<danielkaiser@status.im\>
contributors:
sidebar_position: 1
---
- Status: (raw|draft|stable)
- Category: (Standards Track|Informational|Best Current Practice)

2
waku/README.md
View File

@@ -1,5 +1,5 @@
## Waku RFCs
# Waku RFCs
Waku builds a family of privacy-preserving, censorship-resistant communication protocols for web3 applications.

57
waku/deprecated/rpc.md → waku/deprecated/16/rpc.md
View File

@@ -3,14 +3,13 @@ title: 16/WAKU2-RPC
name: Waku v2 RPC API
status: deprecated
editor: Hanno Cornelius \<hanno@status.im\>
sidebar_position: 16
---
- Status: deprecated
- Editor: Hanno Cornelius \<hanno@status.im\>
## Introduction
This specification describes the JSON-RPC API that Waku v2 nodes MAY adhere to. Refer to the [Waku v2 specification](../10/waku2.md) for more information on Waku v2.
This specification describes the JSON-RPC API that Waku v2 nodes MAY adhere to. Refer to the [Waku v2 specification](../10/waku2) for more information on Waku v2.
## Wire Protocol
@@ -44,7 +43,7 @@ The following structured types are defined for use throughout the document:
### WakuMessage
Refer to [`Waku Message` specification](../14/message.md) for more information.
Refer to [`Waku Message` specification](../14/message) for more information.
`WakuMessage` is an `Object` containing the following fields:
@@ -54,7 +53,7 @@ Refer to [`Waku Message` specification](../14/message.md) for more information.
| `contentTopic` | `String` | optional | Message content topic for optional content-based filtering |
| `version` | `Number` | optional | Message version. Used to indicate type of payload encryption. Default version is 0 (no payload encryption). |
| `timestamp` | `Number` | optional | The time at which the message is generated by its sender. This field holds the Unix epoch time in nanoseconds as a 64-bits integer value. |
| `ephemeral` | `Boolean` | optional | This flag indicates the transient nature of the message. Indicates if the message is eligible to be stored by the `store` protocol, [13/WAKU2-STORE](../13/store.md). |
| `ephemeral` | `Boolean` | optional | This flag indicates the transient nature of the message. Indicates if the message is eligible to be stored by the `store` protocol, [13/WAKU2-STORE](../13/store). |
## Method naming
@@ -116,17 +115,17 @@ none
## Relay API
Refer to the [Waku Relay specification](../11/relay.md) for more information on the relaying of messages.
Refer to the [Waku Relay specification](../11/relay) for more information on the relaying of messages.
### `post_waku_v2_relay_v1_message`
The `post_waku_v2_relay_v1_message` method publishes a message to be relayed on a [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README.md#the-topic-descriptor)
The `post_waku_v2_relay_v1_message` method publishes a message to be relayed on a [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README##the-topic-descriptor)
#### Parameters
| Field | Type | Inclusion | Description |
| ----: | :---: | :---: |----------- |
| `topic` | `String` | mandatory | The [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README.md#the-topic-descriptor) being published on |
| `topic` | `String` | mandatory | The [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README##the-topic-descriptor) being published on |
| `message` | [`WakuMessage`](#wakumessage) | mandatory | The `message` being relayed |
#### Response
@@ -135,13 +134,13 @@ The `post_waku_v2_relay_v1_message` method publishes a message to be relayed on
### `post_waku_v2_relay_v1_subscriptions`
The `post_waku_v2_relay_v1_subscriptions` method subscribes a node to an array of [PubSub `topics`](https://github.com/libp2p/specs/blob/master/pubsub/README.md#the-topic-descriptor).
The `post_waku_v2_relay_v1_subscriptions` method subscribes a node to an array of [PubSub `topics`](https://github.com/libp2p/specs/blob/master/pubsub/README##the-topic-descriptor).
#### Parameters
| Field | Type | Inclusion | Description |
| ----: | :---: | :---: |----------- |
| `topics` | `Array`[`String`] | mandatory | The [PubSub `topics`](https://github.com/libp2p/specs/blob/master/pubsub/README.md#the-topic-descriptor) being subscribed to |
| `topics` | `Array`[`String`] | mandatory | The [PubSub `topics`](https://github.com/libp2p/specs/blob/master/pubsub/README##the-topic-descriptor) being subscribed to |
#### Response
@@ -149,13 +148,13 @@ The `post_waku_v2_relay_v1_subscriptions` method subscribes a node to an array o
### `delete_waku_v2_relay_v1_subscriptions`
The `delete_waku_v2_relay_v1_subscriptions` method unsubscribes a node from an array of [PubSub `topics`](https://github.com/libp2p/specs/blob/master/pubsub/README.md#the-topic-descriptor).
The `delete_waku_v2_relay_v1_subscriptions` method unsubscribes a node from an array of [PubSub `topics`](https://github.com/libp2p/specs/blob/master/pubsub/README##the-topic-descriptor).
#### Parameters
| Field | Type | Inclusion | Description |
| ----: | :---: | :---: |----------- |
| `topics` | `Array`[`String`] | mandatory | The [PubSub `topics`](https://github.com/libp2p/specs/blob/master/pubsub/README.md#the-topic-descriptor) being unsubscribed from |
| `topics` | `Array`[`String`] | mandatory | The [PubSub `topics`](https://github.com/libp2p/specs/blob/master/pubsub/README##the-topic-descriptor) being unsubscribed from |
#### Response
@@ -163,13 +162,13 @@ The `delete_waku_v2_relay_v1_subscriptions` method unsubscribes a node from an a
### `get_waku_v2_relay_v1_messages`
The `get_waku_v2_relay_v1_messages` method returns a list of messages that were received on a subscribed [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README.md#the-topic-descriptor) after the last time this method was called. The server MUST respond with an [error](https://www.jsonrpc.org/specification#error_object) if no subscription exists for the polled `topic`. If no message has yet been received on the polled `topic`, the server SHOULD return an empty list. This method can be used to poll a `topic` for new messages.
The `get_waku_v2_relay_v1_messages` method returns a list of messages that were received on a subscribed [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README##the-topic-descriptor) after the last time this method was called. The server MUST respond with an [error](https://www.jsonrpc.org/specification#error_object) if no subscription exists for the polled `topic`. If no message has yet been received on the polled `topic`, the server SHOULD return an empty list. This method can be used to poll a `topic` for new messages.
#### Parameters
| Field | Type | Inclusion | Description |
| ----: | :---: | :---: |----------- |
| `topic` | `String` | mandatory | The [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README.md#the-topic-descriptor) to poll for the latest messages |
| `topic` | `String` | mandatory | The [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README##the-topic-descriptor) to poll for the latest messages |
#### Response
@@ -177,7 +176,7 @@ The `get_waku_v2_relay_v1_messages` method returns a list of messages that were
## Relay Private API
The Private API provides functionality to encrypt/decrypt `WakuMessage` payloads using either symmetric or asymmetric cryptography. This allows backwards compatibility with [Waku v1 nodes](../../legacy/6/waku1.md).
The Private API provides functionality to encrypt/decrypt `WakuMessage` payloads using either symmetric or asymmetric cryptography. This allows backwards compatibility with [Waku v1 nodes](../../legacy/6/waku1).
It is the API client's responsibility to keep track of the keys used for encrypted communication. Since keys must be cached by the client and provided to the node to encrypt/decrypt payloads, a Private API SHOULD NOT be exposed on non-local or untrusted nodes.
### Types
@@ -217,7 +216,7 @@ none
### `post_waku_v2_private_v1_symmetric_message`
The `post_waku_v2_private_v1_symmetric_message` method publishes a message to be relayed on a [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README.md#the-topic-descriptor).
The `post_waku_v2_private_v1_symmetric_message` method publishes a message to be relayed on a [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README##the-topic-descriptor).
Before being relayed, the message payload is encrypted using the supplied symmetric key. The client MUST provide a symmetric key.
@@ -225,7 +224,7 @@ Before being relayed, the message payload is encrypted using the supplied symmet
| Field | Type | Inclusion | Description |
| ----: | :---: | :---: |----------- |
| `topic` | `String` | mandatory | The [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README.md#the-topic-descriptor) being published on |
| `topic` | `String` | mandatory | The [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README##the-topic-descriptor) being published on |
| `message` | [`WakuMessage`](#wakumessage) | mandatory | The (unencrypted) `message` being relayed |
| `symkey` | `String` | mandatory | The hex encoded symmetric key to use for payload encryption. This field MUST be included if symmetric key cryptography is selected |
@@ -235,7 +234,7 @@ Before being relayed, the message payload is encrypted using the supplied symmet
### `post_waku_v2_private_v1_asymmetric_message`
The `post_waku_v2_private_v1_asymmetric_message` method publishes a message to be relayed on a [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README.md#the-topic-descriptor).
The `post_waku_v2_private_v1_asymmetric_message` method publishes a message to be relayed on a [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README##the-topic-descriptor).
Before being relayed, the message payload is encrypted using the supplied public key. The client MUST provide a public key.
@@ -243,7 +242,7 @@ Before being relayed, the message payload is encrypted using the supplied public
| Field | Type | Inclusion | Description |
| ----: | :---: | :---: |----------- |
| `topic` | `String` | mandatory | The [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README.md#the-topic-descriptor) being published on |
| `topic` | `String` | mandatory | The [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README##the-topic-descriptor) being published on |
| `message` | [`WakuMessage`](#wakumessage) | mandatory | The (unencrypted) `message` being relayed |
| `publicKey` | `String` | mandatory | The hex encoded public key to use for payload encryption. This field MUST be included if asymmetric key cryptography is selected |
@@ -253,7 +252,7 @@ Before being relayed, the message payload is encrypted using the supplied public
### `get_waku_v2_private_v1_symmetric_messages`
The `get_waku_v2_private_v1_symmetric_messages` method decrypts and returns a list of messages that were received on a subscribed [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README.md#the-topic-descriptor) after the last time this method was called. The server MUST respond with an [error](https://www.jsonrpc.org/specification#error_object) if no subscription exists for the polled `topic`. If no message has yet been received on the polled `topic`, the server SHOULD return an empty list. This method can be used to poll a `topic` for new messages.
The `get_waku_v2_private_v1_symmetric_messages` method decrypts and returns a list of messages that were received on a subscribed [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README##the-topic-descriptor) after the last time this method was called. The server MUST respond with an [error](https://www.jsonrpc.org/specification#error_object) if no subscription exists for the polled `topic`. If no message has yet been received on the polled `topic`, the server SHOULD return an empty list. This method can be used to poll a `topic` for new messages.
Before returning the messages, the server decrypts the message payloads using the supplied symmetric key. The client MUST provide a symmetric key.
@@ -261,7 +260,7 @@ Before returning the messages, the server decrypts the message payloads using th
| Field | Type | Inclusion | Description |
| ----: | :---: | :---: |----------- |
| `topic` | `String` | mandatory | The [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README.md#the-topic-descriptor) to poll for the latest messages |
| `topic` | `String` | mandatory | The [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README##the-topic-descriptor) to poll for the latest messages |
| `symkey` | `String` | mandatory | The hex encoded symmetric key to use for payload decryption. This field MUST be included if symmetric key cryptography is selected |
#### Response
@@ -270,7 +269,7 @@ Before returning the messages, the server decrypts the message payloads using th
### `get_waku_v2_private_v1_asymmetric_messages`
The `get_waku_v2_private_v1_asymmetric_messages` method decrypts and returns a list of messages that were received on a subscribed [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README.md#the-topic-descriptor) after the last time this method was called. The server MUST respond with an [error](https://www.jsonrpc.org/specification#error_object) if no subscription exists for the polled `topic`. If no message has yet been received on the polled `topic`, the server SHOULD return an empty list. This method can be used to poll a `topic` for new messages.
The `get_waku_v2_private_v1_asymmetric_messages` method decrypts and returns a list of messages that were received on a subscribed [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README##the-topic-descriptor) after the last time this method was called. The server MUST respond with an [error](https://www.jsonrpc.org/specification#error_object) if no subscription exists for the polled `topic`. If no message has yet been received on the polled `topic`, the server SHOULD return an empty list. This method can be used to poll a `topic` for new messages.
Before returning the messages, the server decrypts the message payloads using the supplied private key. The client MUST provide a private key.
@@ -278,7 +277,7 @@ Before returning the messages, the server decrypts the message payloads using th
| Field | Type | Inclusion | Description |
| ----: | :---: | :---: |----------- |
| `topic` | `String` | mandatory | The [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README.md#the-topic-descriptor) to poll for the latest messages |
| `topic` | `String` | mandatory | The [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README##the-topic-descriptor) to poll for the latest messages |
| `privateKey` | `String` | mandatory | The hex encoded private key to use for payload decryption. This field MUST be included if asymmetric key cryptography is selected |
#### Response
@@ -288,7 +287,7 @@ Before returning the messages, the server decrypts the message payloads using th
## Store API
Refer to the [Waku Store specification](../13/store.md) for more information on message history retrieval.
Refer to the [Waku Store specification](../13/store) for more information on message history retrieval.
### Types
@@ -341,8 +340,8 @@ The `get_waku_v2_store_v1_messages` method retrieves historical messages on spec
| ----: | :---: | :---: |----------- |
| `pubsubTopic` | `String` | optional | The pubsub topic on which a [`WakuMessage`](#wakumessage) is published |
| `contentFilters` | `Array`[[`ContentFilter`](#contentfilter)] | optional | Array of content filters to query for historical messages |
| `startTime` | `Number`| optional | The inclusive lower bound on the [`timestamp`](../14/message.md/#message-attributes) of queried [`WakuMessage`s](#wakumessage). This field holds the Unix epoch time in nanoseconds as a 64-bits integer value. |
| `endTime` | `Number` | optional | The inclusive upper bound on the [`timestamp`](../14/message.md/#message-attributes) of queried [`WakuMessage`s](#wakumessage). This field holds the Unix epoch time in nanoseconds as a 64-bits integer value. |
| `startTime` | `Number`| optional | The inclusive lower bound on the [`timestamp`](../14/message#message-attributes) of queried [`WakuMessage`s](#wakumessage). This field holds the Unix epoch time in nanoseconds as a 64-bits integer value. |
| `endTime` | `Number` | optional | The inclusive upper bound on the [`timestamp`](../14/message#message-attributes) of queried [`WakuMessage`s](#wakumessage). This field holds the Unix epoch time in nanoseconds as a 64-bits integer value. |
| `pagingOptions` | [`PagingOptions`](#pagingoptions) | optional | Pagination information |
#### Response
@@ -351,7 +350,7 @@ The `get_waku_v2_store_v1_messages` method retrieves historical messages on spec
## Filter API
Refer to the [Waku Filter specification](../12/filter.md) for more information on content filtering.
Refer to the [Waku Filter specification](../12/filter) for more information on content filtering.
### Types
@@ -367,7 +366,7 @@ The following structured types are defined for use on the Filter API:
### `post_waku_v2_filter_v1_subscription`
The `post_waku_v2_filter_v1_subscription` method creates a subscription in a [light node](../12/filter.md/#rationale) for messages that matches a content filter and, optionally, a [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README.md#the-topic-descriptor).
The `post_waku_v2_filter_v1_subscription` method creates a subscription in a [light node](../12/filter#rationale) for messages that matches a content filter and, optionally, a [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README##the-topic-descriptor).
#### Parameters
@@ -382,7 +381,7 @@ The `post_waku_v2_filter_v1_subscription` method creates a subscription in a [li
### `delete_waku_v2_filter_v1_subscription`
The `delete_waku_v2_filter_v1_subscription` method removes subscriptions in a [light node](../12/filter.md/#rationale) matching a content filter and, optionally, a [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README.md#the-topic-descriptor).
The `delete_waku_v2_filter_v1_subscription` method removes subscriptions in a [light node](../12/filter#rationale) matching a content filter and, optionally, a [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README##the-topic-descriptor).
#### Parameters
@@ -636,5 +635,5 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public
1. [JSON-RPC specification](https://www.jsonrpc.org/specification)
1. [LibP2P Addressing](https://docs.libp2p.io/concepts/addressing/)
1. [LibP2P PubSub specification - topic descriptor](https://github.com/libp2p/specs/tree/master/pubsub#the-topic-descriptor)
1. [Waku v2 specification](../10/waku2.md)
1. [Waku v2 specification](../10/waku2)
1. [IETF RFC 4648 - The Base16, Base32, and Base64 Data Encodings](https://datatracker.ietf.org/doc/html/rfc4648)

5
waku/deprecated/swap.md → waku/deprecated/18/swap.md
View File

@@ -4,7 +4,6 @@ name: Waku SWAP Accounting
status: deprecated
editor: Oskar Thorén \<oskarth@titanproxy.com\>
contributor: Ebube Ud \<ebube@status.im\>
sidebar_position: 18
---
- Status: deprecated
- Editor: Oskar Thorén \<oskarth@titanproxy.com\>
@@ -143,7 +142,7 @@ In the soft phase only accounting is performed, without consequence for the
peers. No disconnect or sending of cheques is performed at this tage.
SWAP protocol is performed in conjunction with another request-reply protocol to account for its usage.
It SHOULD be done for [13/WAKU2-STORE](../../core/13/store.md)
It SHOULD be done for [13/WAKU2-STORE](../../core/13/store)
and it MAY be done for other request/reply protocols.
A client SHOULD log accounting state per peer
@@ -175,7 +174,7 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public
1. [Prisoner's Dilemma](https://en.wikipedia.org/wiki/Prisoner%27s_dilemma)
2. [Axelrod - Evolution of Cooperation (book)](https://en.wikipedia.org/wiki/The_Evolution_of_Cooperation)
3. [Book of Swarm](https://web.archive.org/web/20210126130038/https://gateway.ethswarm.org/bzz/latest.bookofswarm.eth)
4. [13/WAKU2-STORE](../../core/13/store.md)
4. [13/WAKU2-STORE](../../core/13/store)
<!--

17
waku/deprecated/waku0.md → waku/deprecated/5/waku0.md
View File

@@ -8,7 +8,6 @@ contributors:
- Andrea Maria Piana \<andreap@status.im\>
- Dean Eigenmann \<dean@status.im\>
- Kim De Mey \<kimdemey@status.im\>
sidebar_position: 5
---
- Status: deprecated
- Editor: Oskar Thorén \<oskarth@titanproxy.com\>
@@ -40,7 +39,7 @@ For nodes to communicate, they MUST implement devp2p and run RLPx. They MUST hav
### Gossip based routing
In Whisper, messages are gossiped between peers. Whisper is a form of rumor-mongering protocol that works by flooding to its connected peers based on some factors. Messages are eligible for retransmission until their TTL expires. A node SHOULD relay messages to all connected nodes if an envelope matches their PoW and bloom filter settings. If a node works in light mode, it MAY choose not to forward envelopes. A node MUST NOT send expired envelopes, unless the envelopes are sent as a [mailserver](./mailserver.md) response. A node SHOULD NOT send a message to a peer that it has already sent before.
In Whisper, messages are gossiped between peers. Whisper is a form of rumor-mongering protocol that works by flooding to its connected peers based on some factors. Messages are eligible for retransmission until their TTL expires. A node SHOULD relay messages to all connected nodes if an envelope matches their PoW and bloom filter settings. If a node works in light mode, it MAY choose not to forward envelopes. A node MUST NOT send expired envelopes, unless the envelopes are sent as a [mailserver](./mailserver) response. A node SHOULD NOT send a message to a peer that it has already sent before.
## Wire Specification
@@ -308,7 +307,7 @@ The drawback of sending message confirmations is that it increases the noise in
#### P2P Request
This packet is used for sending Dapp-level peer-to-peer requests, e.g. Waku Mail Client requesting old messages from the [Waku Mail Server](./mailserver.md).
This packet is used for sending Dapp-level peer-to-peer requests, e.g. Waku Mail Client requesting old messages from the [Waku Mail Server](./mailserver).
#### P2P Message
@@ -333,7 +332,7 @@ Packet codes `0x7E` and `0x7F` may be used to implement Waku Mail Server and Cli
Waku supports multiple capabilities. These include light node, rate limiting and bridging of traffic. Here we list these capabilities, how they are identified, what properties they have and what invariants they must maintain.
Additionally there is the capability of a mailserver which is documented in its on [specification](mailserver.md).
Additionally there is the capability of a mailserver which is documented in its on [specification](mailserver).
### Light node
@@ -409,7 +408,7 @@ It is desirable to have a strategy for maintaining forward compatibility between
## Appendix A: Security considerations
There are several security considerations to take into account when running Waku. Chief among them are: scalability, DDoS-resistance and privacy. These also vary depending on what capabilities are used. The security considerations for extra capabilities such as [mailservers](./mailserver.md#security-considerations) can be found in their respective specifications.
There are several security considerations to take into account when running Waku. Chief among them are: scalability, DDoS-resistance and privacy. These also vary depending on what capabilities are used. The security considerations for extra capabilities such as [mailservers](./mailserver##security-considerations) can be found in their respective specifications.
### Scalability and UX
@@ -461,7 +460,7 @@ By default Devp2p runs on port `30303`, which is not commonly used for any other
| Client | Spec supported | Details |
|--------|----------------|---------|
| **Status-go** | 0.5 | [details](https://github.com/status-im/status-go/blob/develop/WAKU.md) |
| **Status-go** | 0.5 | [details](https://github.com/status-im/status-go/blob/develop/WAKU) |
| **Nimbus** | 0.4 | [details](https://github.com/status-im/nimbus/tree/8747fe1ecd36fe778bb92b97634db84d364fede8/waku) |
### Recommendations for clients
@@ -520,7 +519,7 @@ Released [February 13, 2020](https://github.com/vacp2p/specs/commit/73138d6ba954
### Version 0.2
Released [December 10, 2019](https://github.com/vacp2p/specs/blob/waku-0.2.0/waku.md).
Released [December 10, 2019](https://github.com/vacp2p/specs/blob/waku-0.2.0/waku).
- General style improvements.
- Fix ABNF grammar.
@@ -538,7 +537,7 @@ Released [December 10, 2019](https://github.com/vacp2p/specs/blob/waku-0.2.0/wak
### Version 0.1
Initial version. Released [November 21, 2019](https://github.com/vacp2p/specs/blob/b59b9247f2ac1bf45c75bd3227a2e5dd87b6d7b0/waku.md).
Initial version. Released [November 21, 2019](https://github.com/vacp2p/specs/blob/b59b9247f2ac1bf45c75bd3227a2e5dd87b6d7b0/waku).
### Differences between shh/6 and waku/0
@@ -559,4 +558,4 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public
## Footnotes
[^1]: Felix Lange et al. [The RLPx Transport Protocol](https://github.com/ethereum/devp2p/blob/master/rlpx.md). Ethereum.
[^1]: Felix Lange et al. [The RLPx Transport Protocol](https://github.com/ethereum/devp2p/blob/master/rlpx). Ethereum.

2
waku/deprecated/README.md
View File

@@ -1,5 +1,5 @@
## Deprecated RFCs
# Deprecated RFCs
Deprecated specifications are no longer used in Waku products.
This subdirectory is for achrive purpose and

1
waku/informational/toy-chat.md → waku/informational/22/toy-chat.md
View File

@@ -5,7 +5,6 @@ status: draft
editor: Franck Royer \<franck@status.im\>
contributors:
- Hanno Cornelius \<hanno@status.im\>
sidebar_position: 22
---
- Status: draft
- Editor: Franck Royer \<franck@status.im\>

51
waku/informational/topics.md → waku/informational/23/topics.md
View File

@@ -7,7 +7,6 @@ editor: Oskar Thoren \<oskarth@titanproxy.com\>
contributors:
- Hanno Cornelius \<hanno@status.im\>
- Daniel Kaiser \<danielkaiser@status.im\>
sidebar_position: 23
---
- Status: draft
- Category: Informational
@@ -17,7 +16,7 @@ sidebar_position: 23
- Daniel Kaiser \<danielkaiser@status.im\>
This document outlines recommended usage of topic names in Waku v2.
In [10/WAKU2 spec](../../standards/core/10/waku2.md) there are two types of topics:
In [10/WAKU2 spec](../../standards/core/10/waku2) there are two types of topics:
- pubsub topics, used for routing
- Content topics, used for content-based filtering
@@ -25,9 +24,9 @@ In [10/WAKU2 spec](../../standards/core/10/waku2.md) there are two types of topi
## Pubsub Topics
Pubsub topics are used for routing of messages (see [11/WAKU2-RELAY](../../standards/core/11/relay.md)),
and can be named implicitly by Waku sharding (see [RELAY-SHARDING](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/relay-sharding.md)).
This document comprises recommendations for explicitly naming pubsub topics (e.g. when choosing *named sharding* as specified in [RELAY-SHARDING](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/relay-sharding.md)).
Pubsub topics are used for routing of messages (see [11/WAKU2-RELAY](../../standards/core/11/relay)),
and can be named implicitly by Waku sharding (see [RELAY-SHARDING](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/relay-sharding)).
This document comprises recommendations for explicitly naming pubsub topics (e.g. when choosing *named sharding* as specified in [RELAY-SHARDING](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/relay-sharding)).
### Pubsub Topic Format
@@ -46,10 +45,10 @@ If applicable, it is RECOMMENDED to structure `{topic-name}` in a hierarchical w
\> *Note*: In previous versions of this document, the structure was `/waku/2/{topic-name}/{encoding}`.
The now deprecated `/{encoding}` was always set to `/proto`,
which indicated that the [data field](../../standards/core/11/RELAY.md/#protobuf-definition) in pubsub is serialized/encoded as protobuf.
which indicated that the [data field](../../standards/core/11/RELAY#protobuf-definition) in pubsub is serialized/encoded as protobuf.
The inspiration for this format was taken from
[Ethereum 2 P2P spec](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/phase0/p2p-interface.md#topics-and-messages).
However, because the payload of messages transmitted over [11/WAKU2-RELAY](../../standards/core/11/relay.md) must be a [14/WAKU2-MESSAGE](../../standards/core/14/message.md),
[Ethereum 2 P2P spec](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/phase0/p2p-interface##topics-and-messages).
However, because the payload of messages transmitted over [11/WAKU2-RELAY](../../standards/core/11/relay) must be a [14/WAKU2-MESSAGE](../../standards/core/14/message),
which specifies the wire format as protobuf,`/proto` is the only valid encoding.
This makes the `/proto` indication obsolete.
The encoding of the `payload` field of a Waku Message is indicated by the `/{encoding}` part of the content topic name.
@@ -78,7 +77,7 @@ This indicates that these networks carry WakuMessages, but for different domains
### Named Topic Sharding Example
The following is an example of named sharding, as specified in [RELAY-SHARDING](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/relay-sharding.md).
The following is an example of named sharding, as specified in [RELAY-SHARDING](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/relay-sharding).
```
waku/2/waku-9_shard-0/
@@ -92,10 +91,10 @@ This indicates explicitly that the network traffic has been partitioned into 10
The other type of topic that exists in Waku v2 is a content topic.
This is used for content based filtering.
See [14/WAKU2-MESSAGE spec](../../standards/core/14/message.md) for where this is specified.
See [14/WAKU2-MESSAGE spec](../../standards/core/14/message) for where this is specified.
Note that this doesn't impact routing of messages between relaying nodes,
but it does impact how request/reply protocols such as
[12/WAKU2-FILTER](../../standards/core/12/filter.md) and [13/WAKU2-STORE](../../standards/core/13/store.md) are used.
[12/WAKU2-FILTER](../../standards/core/12/filter) and [13/WAKU2-STORE](../../standards/core/13/store) are used.
This is especially useful for nodes that have limited bandwidth,
and only want to pull down messages that match this given content topic.
@@ -121,11 +120,11 @@ Applications should specify their version (if applicable) in the version field.
The `{content-topic-name}` portion of the content topic is up to the application,
and depends on the problem domain.
It can be hierarchical, for instance to separate content, or to indicate different bandwidth and privacy guarantees.
The encoding field indicates the serialization/encoding scheme for the [WakuMessage payload](../../standards/core/14/message.md/#payloads) field.
The encoding field indicates the serialization/encoding scheme for the [WakuMessage payload](../../standards/core/14/message#payloads) field.
## Differences with Waku v1
In [5/WAKU1](../../deprecated/5/waku0.md) there is no actual routing.
In [5/WAKU1](../../deprecated/5/waku0) there is no actual routing.
All messages are sent to all other nodes.
This means that we are implicitly using the same pubsub topic that would be something like:
@@ -137,7 +136,7 @@ Topics in Waku v1 correspond to Content Topics in Waku v2.
### Bridging Waku v1 and Waku v2
To bridge Waku v1 and Waku v2 we have a [15/WAKU-BRIDGE](../../standards/core/15/bridge.md).
To bridge Waku v1 and Waku v2 we have a [15/WAKU-BRIDGE](../../standards/core/15/bridge).
For mapping Waku v1 topics to Waku v2 content topics,
the following structure for the content topic SHOULD be used:
@@ -147,8 +146,8 @@ the following structure for the content topic SHOULD be used:
The `\<4bytes-waku-v1-topic\>` SHOULD be the lowercase hex representation of the 4-byte Waku v1 topic.
A `0x` prefix SHOULD be used.
`/rfc26` indicates that the bridged content is encoded according to RFC [26/WAKU2-PAYLOAD](../../standards/application/26/payload.md).
See [15/WAKU-BRIDGE](../../standards/core/15/bridge.md) for a description of the bridged fields.
`/rfc26` indicates that the bridged content is encoded according to RFC [26/WAKU2-PAYLOAD](../../standards/application/26/payload).
See [15/WAKU-BRIDGE](../../standards/core/15/bridge) for a description of the bridged fields.
This creates a direct mapping between the two protocols.
For example:
@@ -164,13 +163,13 @@ Copyright and related rights waived via
## References
* [10/WAKU2 spec](../../standards/core/10/waku2.md)
* [11/WAKU2-RELAY](../../standards/core/11/relay.md)
* [RELAY-SHARDING](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/relay-sharding.md)
* [Ethereum 2 P2P spec](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/phase0/p2p-interface.md#topics-and-messages)
* [14/WAKU2-MESSAGE](../../standards/core/14/message.md)
* [12/WAKU2-FILTER](../../standards/core/12/filter.md)
* [13/WAKU2-STORE](../../standards/core/13/store.md)
* [6/WAKU1](../../deprecated/5/waku0.md)
* [15/WAKU-BRIDGE](../../standards/core/15/bridge.md)
* [26/WAKU-PAYLOAD](../../standards/application/26/payload.md)
* [10/WAKU2 spec](../../standards/core/10/waku2)
* [11/WAKU2-RELAY](../../standards/core/11/relay)
* [RELAY-SHARDING](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/relay-sharding)
* [Ethereum 2 P2P spec](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/phase0/p2p-interface##topics-and-messages)
* [14/WAKU2-MESSAGE](../../standards/core/14/message)
* [12/WAKU2-FILTER](../../standards/core/12/filter)
* [13/WAKU2-STORE](../../standards/core/13/store)
* [6/WAKU1](../../deprecated/5/waku0)
* [15/WAKU-BRIDGE](../../standards/core/15/bridge)
* [26/WAKU-PAYLOAD](../../standards/application/26/payload)

19
waku/informational/peers.md → waku/informational/27/peers.md
View File

@@ -4,7 +4,6 @@ name: Waku v2 Client Peer Management Recommendations
status: draft
editor: Hanno Cornelius \<hanno@status.im\>
contributors:
sidebar_position: 27
---
- Status: draft
- Editor: Hanno Cornelius \<hanno@status.im\>
@@ -32,7 +31,7 @@ It is RECOMMENDED that a Waku v2 client tracks at least the following informatio
| --- | --- |
| _Public key_ | The public key for this peer. This is related to the libp2p [`Peer ID`](https://docs.libp2p.io/concepts/peer-id/). |
| _Addresses_ | Known transport layer [`multiaddrs`](https://docs.libp2p.io/concepts/addressing/) for this peer. |
| _Protocols_ | The libp2p [`protocol IDs`](https://docs.libp2p.io/concepts/protocols/#protocol-ids) supported by this peer. This can be used to track the client's connectivity to peers supporting different Waku v2 protocols, e.g. [`11/WAKU2-RELAY`](../../standards/core/11/relay.md) or [`13/WAKU2-STORE`](../../standards/core/13/store.md). |
| _Protocols_ | The libp2p [`protocol IDs`](https://docs.libp2p.io/concepts/protocols/#protocol-ids) supported by this peer. This can be used to track the client's connectivity to peers supporting different Waku v2 protocols, e.g. [`11/WAKU2-RELAY`](../../standards/core/11/relay) or [`13/WAKU2-STORE`](../../standards/core/13/store). |
| _Connectivity_ | Tracks the peer's current connectedness state. See [**Peer connectivity**](#peer-connectivity) below. |
| _Disconnect time_ | The timestamp at which this peer last disconnected. This becomes important when managing [peer reconnections](#reconnecting-peers) |
@@ -47,7 +46,7 @@ A Waku v2 client SHOULD track _at least_ the following connectivity states for e
- **`Connected`**: The client is actively connected to this peer.
This list does not preclude clients from tracking more advanced connectivity metadata,
such as a peer's blacklist status (see [`18/WAKU2-SWAP`](../../standards/application/18/swap.md)).
such as a peer's blacklist status (see [`18/WAKU2-SWAP`](../../standards/application/18/swap)).
### Persistence
@@ -69,14 +68,14 @@ Such conditions include, but are not limited to:
- Reconnecting to all `relay`-capable peers after a client restart. This will require [persistent peer storage](#persistence).
If a client chooses to automatically reconnect to previous peers,
it MUST respect the [backing off period](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md#prune-backoff-and-peer-exchange) specified for GossipSub v1.1 before attempting to reconnect.
it MUST respect the [backing off period](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1##prune-backoff-and-peer-exchange) specified for GossipSub v1.1 before attempting to reconnect.
This requires keeping track of the [last time each peer was disconnected](#tracked-peer-metadata).
### Connection keep-alive
A Waku v2 client MAY choose to implement a keep-alive mechanism to certain peers.
If a client chooses to implement keep-alive on a connection,
it SHOULD do so by sending periodic [libp2p pings](https://docs.libp2p.io/concepts/protocols/#ping) as per `10/WAKU2` [client recommendations](../../standards/core/10/waku2.md/#recommendations-for-clients).
it SHOULD do so by sending periodic [libp2p pings](https://docs.libp2p.io/concepts/protocols/#ping) as per `10/WAKU2` [client recommendations](../../standards/core/10/waku2#recommendations-for-clients).
The recommended period between pings SHOULD be _at most_ 50% of the shortest idle connection timeout for the specific client and transport.
For example, idle TCP connections often times out after 10 to 15 minutes.
@@ -93,9 +92,9 @@ Copyright and related rights waived via
- [`Peer ID`](https://docs.libp2p.io/concepts/peer-id/)
- [`multiaddrs`](https://docs.libp2p.io/concepts/addressing/)
- [`protocol IDs`](https://docs.libp2p.io/concepts/protocols/#protocol-ids)
- [`11/WAKU2-RELAY`](../../standards/core/11/relay.md)
- [`13/WAKU2-STORE`](../../standards/core/13/store.md)
- [`18/WAKU2-SWAP`](../../standards/application/18/swap.md)
- [backing off period](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md#prune-backoff-and-peer-exchange)
- [`11/WAKU2-RELAY`](../../standards/core/11/relay)
- [`13/WAKU2-STORE`](../../standards/core/13/store)
- [`18/WAKU2-SWAP`](../../standards/application/18/swap)
- [backing off period](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1##prune-backoff-and-peer-exchange)
- [libp2p pings](https://docs.libp2p.io/concepts/protocols/#ping)
- [`10/WAKU2` client recommendations](../../standards/core/10/waku2.md/#recommendations-for-clients)
- [`10/WAKU2` client recommendations](../../standards/core/10/waku2#recommendations-for-clients)

19
waku/informational/config.md → waku/informational/29/config.md
View File

@@ -4,7 +4,6 @@ name: Waku v2 Client Parameter Configuration Recommendations
status: draft
editor: Hanno Cornelius \<hanno@status.im\>
contributors:
sidebar_position: 29
---
- Status: draft
- Editor: Hanno Cornelius \<hanno@status.im\>
@@ -13,14 +12,14 @@ sidebar_position: 29
Since Waku v2 is built on [libp2p](https://github.com/libp2p/specs),
most of the parameters and reasonable defaults are derived from there.
Waku v2 relay messaging is specified in [`11/WAKU2-RELAY`](../../standards/core/11/relay.md),
a minor extension of the [libp2p GossipSub protocol](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/README.md).
Waku v2 relay messaging is specified in [`11/WAKU2-RELAY`](../../standards/core/11/relay),
a minor extension of the [libp2p GossipSub protocol](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/README).
GossipSub behaviour is controlled by a series of adjustable parameters.
Waku v2 clients SHOULD configure these parameters to the recommended values below.
## GossipSub v1.0 parameters
GossipSub v1.0 parameters are defined in the [corresponding libp2p specification](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.0.md#parameters).
GossipSub v1.0 parameters are defined in the [corresponding libp2p specification](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.0##parameters).
We repeat them here with RECOMMMENDED values for `11/WAKU2-RELAY` implementations.
| Parameter | Purpose | RECOMMENDED value |
@@ -37,7 +36,7 @@ We repeat them here with RECOMMMENDED values for `11/WAKU2-RELAY` implementation
## GossipSub v1.1 parameters
GossipSub v1.1 extended GossipSub v1.0 and introduced [several new parameters](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md#overview-of-new-parameters).
GossipSub v1.1 extended GossipSub v1.0 and introduced [several new parameters](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1##overview-of-new-parameters).
We repeat the global parameters here with RECOMMMENDED values for `11/WAKU2-RELAY` implementations.
| Parameter | Description | RECOMMENDED value |
@@ -48,7 +47,7 @@ We repeat the global parameters here with RECOMMMENDED values for `11/WAKU2-RELA
| `D_score` | Number of peers to retain by score when pruning from oversubscription | `D_low` |
| `D_out` | Number of outbound connections to keep in the mesh. | `D_low` - 1 |
`11/WAKU2-RELAY` clients SHOULD implement a peer scoring mechanism with the parameter constraints as [specified by libp2p](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md#overview-of-new-parameters).
`11/WAKU2-RELAY` clients SHOULD implement a peer scoring mechanism with the parameter constraints as [specified by libp2p](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1##overview-of-new-parameters).
## Other configuration
@@ -70,7 +69,7 @@ Copyright and related rights waived via
## References
- [libp2p](https://github.com/libp2p/specs)
- [11/WAKU2-RELAY](../../standards/core/11/relay.md)
- [libp2p GossipSub protocol](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/README.md)
- [corresponding libp2p specification](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.0.md#parameters)
- [several new parameters](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md#overview-of-new-parameters)
- [11/WAKU2-RELAY](../../standards/core/11/relay)
- [libp2p GossipSub protocol](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/README)
- [corresponding libp2p specification](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.0##parameters)
- [several new parameters](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1##overview-of-new-parameters)

15
waku/informational/adaptive-nodes.md → waku/informational/30/adaptive-nodes.md
View File

@@ -4,7 +4,6 @@ name: Adaptive nodes
status: draft
editor: Oskar Thorén \<oskarth@titanproxy.com\>
contributors:
sidebar_position: 30
---
- Status: draft
- Editor: Oskar Thorén \<oskarth@titanproxy.com\>
@@ -15,7 +14,7 @@ This is an informational spec that show cases the concept of adaptive nodes.
We can look at node types as a continuum, from more restricted to less restricted, fewer resources to more resources.
![Node types - a continuum](./30/images/adaptive_node_continuum2.png)
![Node types - a continuum](./images/adaptive_node_continuum2.png)
### Possible limitations
@@ -55,9 +54,9 @@ Incentives to run a node is currently planned around:
Each node can choose which protocols to support, depending on its resources and goals.
![Protocol selection](./30/images/adaptive_node_protocol_selection2.png)
![Protocol selection](./images/adaptive_node_protocol_selection2.png)
In the case of protocols like [11/WAKU2-RELAY](../../standards/core/11/relay.md) etc (12, 13, 19, 21) these correspond to Libp2p protocols.
In the case of protocols like [11/WAKU2-RELAY](../../standards/core/11/relay) etc (12, 13, 19, 21) these correspond to Libp2p protocols.
However, other protocols like 16/WAKU2-RPC (local HTTP JSON-RPC), 25/LIBP2P-DNS-DISCOVERY, Discovery v5 (DevP2P) or interfacing with distributed storage, are running on different network stacks.
@@ -71,11 +70,11 @@ We can better visualize the network with some illustrative examples.
The first one shows an example topology with different PubSub topics for the relay protocol.
![Waku Network visualization](./30/images/adaptive_node_network_topology_protocols2.png)
![Waku Network visualization](./images/adaptive_node_network_topology_protocols2.png)
### Legend
![Waku Network visualization legend](./30/images/adaptive_node_network_topology_protocols_legend.png)
![Waku Network visualization legend](./images/adaptive_node_network_topology_protocols_legend.png)
The dotted box shows what content topics (application-specific) a node is interested in.
@@ -93,7 +92,7 @@ Behavior and interaction with other protocols specified in Vac RFCs, e.g. 25/LIB
This one shows a cross-section of nodes in different dimensions and shows how the connections look different for different protocols.
![Node Cross Section](./30/images/adaptive_node_cross_section2.png)
![Node Cross Section](./images/adaptive_node_cross_section2.png)
## Copyright
@@ -101,4 +100,4 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public
## References
- [11/WAKU2-RELAY](../../standards/core/11/relay.md)
- [11/WAKU2-RELAY](../../standards/core/11/relay)

17
waku/standards/application/toy-eth-pm.md → waku/standards/application/20/toy-eth-pm.md
View File

@@ -4,7 +4,6 @@ name: Toy Ethereum Private Message
status: draft
editor: Franck Royer \<franck@status.im\>
contributors:
sidebar_position: 20
---
- Status: draft
- Editor: Franck Royer \<franck@status.im\>
@@ -47,10 +46,10 @@ The proposed protocol MUST adhere to the following design requirements:
2. Bob is willing to participate to Eth-PM, and publishes `B'`,
3. Bob's ownership of `B'` MUST be verifiable,
4. Alice wants to send message `M` to Bob,
5. Bob SHOULD be able to get `M` using [10/WAKU2 spec](../../core/10/waku2.md),
5. Bob SHOULD be able to get `M` using [10/WAKU2 spec](../../core/10/waku2),
6. Participants only have access to their Ethereum Wallet via the Web3 API,
7. Carole MUST NOT be able to read `M`'s content even if she is storing it or relaying it,
8. [Waku Message Version 1](../26/payload.md) Asymmetric Encryption is used for encryption purposes.
8. [Waku Message Version 1](../26/payload) Asymmetric Encryption is used for encryption purposes.
## Limitations
@@ -156,7 +155,7 @@ it is not enough in itself to deduce Bob's Public Key.
This is why the protocol dictates that Bob MUST send his Public Key first,
and Alice MUST receive it before she can send him a message.
Moreover, nim-waku, the reference implementation of [13/WAKU2-STORE](../../core/13/store.md),
Moreover, nim-waku, the reference implementation of [13/WAKU2-STORE](../../core/13/store),
stores messages for a maximum period of 30 days.
This means that Bob would need to broadcast his public key at least every 30 days to be reachable.
@@ -203,10 +202,10 @@ Alice MAY monitor the Waku v2 to collect Ethereum Address and Encryption Public
Alice SHOULD verify that the `signature`s of `PublicKeyMessage`s she receives are valid as per EIP-712.
She SHOULD drop any message without a signature or with an invalid signature.
Using Bob's Encryption Public Key, retrieved via [10/WAKU2 spec](../../core/10/waku2.md), Alice MAY now send an encrypted message to Bob.
Using Bob's Encryption Public Key, retrieved via [10/WAKU2 spec](../../core/10/waku2), Alice MAY now send an encrypted message to Bob.
If she wishes to do so, Alice MUST encrypt her message `M` using Bob's Encryption Public Key `B'`,
as per [26/WAKU-PAYLOAD Asymmetric Encryption specs](../26/payload.md/#asymmetric).
as per [26/WAKU-PAYLOAD Asymmetric Encryption specs](../26/payload#asymmetric).
Alice SHOULD now publish this message on the Private Message content topic.
@@ -215,12 +214,12 @@ Alice SHOULD now publish this message on the Private Message content topic.
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
## References
- [10/WAKU2 spec](../../core/10/waku2.md)
- [Waku Message Version 1](../26/payload.md)
- [10/WAKU2 spec](../../core/10/waku2)
- [Waku Message Version 1](../26/payload)
- [X3DH](https://www.signal.org/docs/specifications/x3dh/)
- [Double Ratchet](https://signal.org/docs/specifications/doubleratchet/)
- [Status secure transport spec](https://specs.status.im/spec/5)
- [EIP-712](https://eips.ethereum.org/EIPS/eip-712)
- [13/WAKU2-STORE](../../core/13/store.md)
- [13/WAKU2-STORE](../../core/13/store)
- [The Graph](https://thegraph.com/)

17
waku/standards/application/fault-tolerant-store.md → waku/standards/application/21/fault-tolerant-store.md
View File

@@ -4,19 +4,18 @@ name: Waku v2 Fault-Tolerant Store
status: draft
editor: Sanaz Taheri \<sanaz@status.im\>
contributors:
sidebar_position: 21
---
- Status: draft
- Editor: Sanaz Taheri \<sanaz@status.im\>
The reliability of [13/WAKU2-STORE](../../core/13/store.md) protocol heavily relies on the fact that full nodes i.e., those who persist messages have high availability and uptime and do not miss any messages.
The reliability of [13/WAKU2-STORE](../../core/13/store) protocol heavily relies on the fact that full nodes i.e., those who persist messages have high availability and uptime and do not miss any messages.
If a node goes offline, then it will risk missing all the messages transmitted in the network during that time.
In this specification, we provide a method that makes the store protocol resilient in presence of faulty nodes.
Relying on this method, nodes that have been offline for a time window will be able to fix the gap in their message history when getting back online.
Moreover, nodes with lower availability and uptime can leverage this method to reliably provide the store protocol services as a full node.
## Method description
As the first step towards making the [13/WAKU2-STORE](../../core/13/store.md) protocol fault-tolerant, we introduce a new type of time-based query through which nodes fetch message history from each other based on their desired time window.
As the first step towards making the [13/WAKU2-STORE](../../core/13/store) protocol fault-tolerant, we introduce a new type of time-based query through which nodes fetch message history from each other based on their desired time window.
This method operates based on the assumption that the querying node knows some other nodes in the store protocol which have been online for that targeted time window.
## Security Consideration
@@ -25,7 +24,7 @@ The main security consideration to take into account while using this method is
This will gradually result in the extraction of the node's activity pattern which can lead to inference attacks.
## Wire Specification
We extend the [HistoryQuery](../../core/13/store.md/#payloads) protobuf message with two fields of `start_time` and `end_time` to signify the time range to be queried.
We extend the [HistoryQuery](../../core/13/store#payloads) protobuf message with two fields of `start_time` and `end_time` to signify the time range to be queried.
### Payloads
@@ -48,10 +47,10 @@ message HistoryQuery {
RPC call to query historical messages.
- `start_time`: this field MAY be filled out to signify the starting point of the queried time window.
This field holds the Unix epoch time in nanoseconds.
The `messages` field of the corresponding [`HistoryResponse`](../../core/13/store.md/#HistoryResponse) MUST contain historical waku messages whose [`timestamp`](../../core/14/message.md/#Payloads) is larger than or equal to the `start_time`.
The `messages` field of the corresponding [`HistoryResponse`](../../core/13/store#HistoryResponse) MUST contain historical waku messages whose [`timestamp`](../../core/14/message#Payloads) is larger than or equal to the `start_time`.
- `end_time` this field MAY be filled out to signify the ending point of the queried time window.
This field holds the Unix epoch time in nanoseconds.
The `messages` field of the corresponding [`HistoryResponse`](../../core/13/store.md/#HistoryResponse) MUST contain historical waku messages whose [`timestamp`](../../core/14/message.md/#Payloads) is less than or equal to the `end_time`.
The `messages` field of the corresponding [`HistoryResponse`](../../core/13/store#HistoryResponse) MUST contain historical waku messages whose [`timestamp`](../../core/14/message#Payloads) is less than or equal to the `end_time`.
A time-based query is considered valid if its `end_time` is larger than or equal to the `start_time`.
Queries that do not adhere to this condition will not get through e.g. an open-end time query in which the `start_time` is given but no `end_time` is supplied is not valid.
@@ -63,7 +62,7 @@ In order to account for nodes asynchrony, and assuming that nodes may be out of
That is if the original window is [`l`,`r`] then the history query SHOULD be made for `[start_time: l - 20s, end_time: r + 20s]`.
Note that `HistoryQuery` preserves `AND` operation among the queried attributes.
As such, The `messages` field of the corresponding [`HistoryResponse`](../../core/13/store.md/#HistoryResponse) MUST contain historical waku messages that satisfy the indicated `pubsubtopic` AND `contentFilters` AND the time range [`start_time`, `end_time`].
As such, The `messages` field of the corresponding [`HistoryResponse`](../../core/13/store#HistoryResponse) MUST contain historical waku messages that satisfy the indicated `pubsubtopic` AND `contentFilters` AND the time range [`start_time`, `end_time`].
## Copyright
@@ -72,5 +71,5 @@ Copyright and related rights waived via
## References
- [13/WAKU2-STORE](../../core/13/store.md)
- [`timestamp`](../../standards/core/14/message.md/#Payloads)
- [13/WAKU2-STORE](../../core/13/store)
- [`timestamp`](../../standards/core/14/message#Payloads)

23
waku/standards/application/payload.md → waku/standards/application/26/payload.md
View File

@@ -4,17 +4,16 @@ name: Waku Message Payload Encryption
status: draft
editor: Oskar Thoren \<oskarth@titanproxy.com\>
contributors:
sidebar_position: 26
---
- Status: draft
- Editor: Oskar Thoren \<oskarth@titanproxy.com\>
This specification describes how Waku provides confidentiality, authenticity, and integrity, as well as some form of unlinkability.
Specifically, it describes how encryption, decryption and signing works in [6/WAKU1](../../legacy/6/waku1.md) and in [10/WAKU2 spec](../../core/10/waku2.md) with [14/WAKU-MESSAGE version 1](../../core/14/message.md/#version1).
Specifically, it describes how encryption, decryption and signing works in [6/WAKU1](../../legacy/6/waku1) and in [10/WAKU2 spec](../../core/10/waku2) with [14/WAKU-MESSAGE version 1](../../core/14/message#version1).
This specification effectively replaces [7/WAKU-DATA](../../legacy/7/data.md) as well as [6/WAKU1 Payload encryption](../../legacy/6/waku1.md/#payload-encryption) but written in a way that is agnostic and self-contained for Waku v1 and Waku v2.
This specification effectively replaces [7/WAKU-DATA](../../legacy/7/data) as well as [6/WAKU1 Payload encryption](../../legacy/6/waku1#payload-encryption) but written in a way that is agnostic and self-contained for Waku v1 and Waku v2.
Large sections of the specification originate from [EIP-627: Whisper spec](https://eips.ethereum.org/EIPS/eip-627) as well from [RLPx Transport Protocol spec (ECIES encryption)](https://github.com/ethereum/devp2p/blob/master/rlpx.md#ecies-encryption) with some modifications.
Large sections of the specification originate from [EIP-627: Whisper spec](https://eips.ethereum.org/EIPS/eip-627) as well from [RLPx Transport Protocol spec (ECIES encryption)](https://github.com/ethereum/devp2p/blob/master/rlpx##ecies-encryption) with some modifications.
## Design requirements
@@ -44,9 +43,9 @@ ECIES is using the following cryptosystem:
## Specification
For [6/WAKU1](../../legacy/6/waku1.md), the `data` field is used in the `waku envelope`, and the field MAY contain the encrypted payload.
For [6/WAKU1](../../legacy/6/waku1), the `data` field is used in the `waku envelope`, and the field MAY contain the encrypted payload.
For [10/WAKU2 spec](../../core/10/waku2.md), the `payload` field is used in `WakuMessage` and MAY contain the encrypted payload.
For [10/WAKU2 spec](../../core/10/waku2), the `payload` field is used in `WakuMessage` and MAY contain the encrypted payload.
The fields that are concatenated and encrypted as part of the `data` (Waku v1) / `payload` (Waku v2) field are:
- flags
@@ -107,7 +106,7 @@ Asymmetric encryption uses the standard Elliptic Curve Integrated Encryption Sch
#### ECIES
This section originates from the [RLPx Transport Protocol spec](https://github.com/ethereum/devp2p/blob/master/rlpx.md#ecies-encryption) spec with minor modifications.
This section originates from the [RLPx Transport Protocol spec](https://github.com/ethereum/devp2p/blob/master/rlpx##ecies-encryption) spec with minor modifications.
The cryptosystem used is:
@@ -144,12 +143,12 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public
## References
1. [6/WAKU1](../../legacy/6/waku1.md)
2. [10/WAKU2 spec](../../core/10/waku2.md)
3. [14/WAKU-MESSAGE version 1](../../core/14/message.md/#version1)
4. [7/WAKU-DATA](../../legacy/7/data.md)
1. [6/WAKU1](../../legacy/6/waku1)
2. [10/WAKU2 spec](../../core/10/waku2)
3. [14/WAKU-MESSAGE version 1](../../core/14/message#version1)
4. [7/WAKU-DATA](../../legacy/7/data)
5. [EIP-627: Whisper spec](https://eips.ethereum.org/EIPS/eip-627)
6. [RLPx Transport Protocol spec (ECIES encryption)](https://github.com/ethereum/devp2p/blob/master/rlpx.md#ecies-encryption)
6. [RLPx Transport Protocol spec (ECIES encryption)](https://github.com/ethereum/devp2p/blob/master/rlpx##ecies-encryption)
7. [Status 5/SECURE-TRANSPORT](https://specs.status.im/spec/5)
8. [Augmented Backus-Naur form (ABNF)](https://tools.ietf.org/html/rfc5234)
9. [Ethereum "Yellow paper": Appendix F Signing transactions](https://ethereum.github.io/yellowpaper/paper.pdf)

7
waku/standards/application/x3dh.md → waku/standards/application/53/x3dh.md
View File

@@ -10,7 +10,6 @@ contributors:
- Corey Petty \<corey@status.im\>
- Oskar Thorén \<oskarth@titanproxy.com\>
- Dean Eigenmann \<dean@status.im\>
sidebar_position: 53
---
- Status: draft
- Category: Standards Track
@@ -58,7 +57,7 @@ Types used in this specification are defined using the [Protobuf](https://develo
End-to-end encryption (E2EE) takes place between two clients.
The main cryptographic protocol is a Double Ratchet protocol, which is derived from the [Off-the-Record protocol](https://otr.cypherpunks.ca/Protocol-v3-4.1.1.html), using a different ratchet.
[The Waku v2 protocol](../../core/10/waku2.md) subsequently encrypts the message payload, using symmetric key encryption.
[The Waku v2 protocol](../../core/10/waku2) subsequently encrypts the message payload, using symmetric key encryption.
Furthermore, the concept of prekeys (through the use of [X3DH](https://signal.org/docs/specifications/x3dh/)) is used to allow the protocol to operate in an asynchronous environment.
It is not necessary for two parties to be online at the same time to initiate an encrypted conversation.
@@ -234,7 +233,7 @@ The message key MUST be used to encrypt the next message to be sent.
1. Inherits the security considerations of [X3DH](https://signal.org/docs/specifications/x3dh/#security-considerations) and [Double Ratchet](https://signal.org/docs/specifications/doubleratchet/#security-considerations).
2. Inherits the security considerations of the [Waku v2 protocol](../../core/10/waku2.md).
2. Inherits the security considerations of the [Waku v2 protocol](../../core/10/waku2).
3. The protocol is designed to be used in a decentralized manner, however, it is possible to use a centralized server to serve prekey bundles. In this case, the server is trusted.
@@ -253,7 +252,7 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public
- [Signal's Double Ratchet](https://signal.org/docs/specifications/doubleratchet/)
- [Protobuf](https://developers.google.com/protocol-buffers/)
- [Off-the-Record protocol](https://otr.cypherpunks.ca/Protocol-v3-4.1.1.html)
- [The Waku v2 protocol](../../core/10/waku2.md)
- [The Waku v2 protocol](../../core/10/waku2)
- [HKDF](https://www.rfc-editor.org/rfc/rfc5869)
- [2/ACCOUNT](https://specs.status.im/spec/2#x3dh-prekey-bundles)
- [reference wire format](https://github.com/status-im/status-go/blob/a904d9325e76f18f54d59efc099b63293d3dcad3/services/shhext/chat/encryption.proto#L12)

7
waku/standards/application/x3dh-sessions.md → waku/standards/application/54/x3dh-sessions.md
View File

@@ -10,7 +10,6 @@ contributors:
- Corey Petty \<corey@status.im\>
- Oskar Thorén \<oskarth@titanproxy.com\>
- Dean Eigenmann \<dean@status.im\>
sidebar_position: 54
---
- Status: draft
- Category: Standards Track
@@ -23,7 +22,7 @@ sidebar_position: 54
This document specifies how to manage sessions based on an X3DH key exchange.
This includes how to establish new sessions, how to re-establish them, how to maintain them, and how to close them.
[53/WAKU2-X3DH](../53/x3dh.md) specifies the Waku `X3DH` protocol for end-to-end encryption.
[53/WAKU2-X3DH](../53/x3dh) specifies the Waku `X3DH` protocol for end-to-end encryption.
Once two peers complete an X3DH handshake, they SHOULD establish an X3DH session.
## Session Establishment
@@ -150,7 +149,7 @@ In this case an empty message containing bundle information MUST be sent back, w
## Security Considerations
1. Inherits all security considerations from [53/WAKU2-X3DH](../53/x3dh.md).
1. Inherits all security considerations from [53/WAKU2-X3DH](../53/x3dh).
### Recommendations
@@ -163,6 +162,6 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public
## References
1. [53/WAKU2-X3DH](../53/x3dh.md)
1. [53/WAKU2-X3DH](../53/x3dh)
2. [Signal's Sesame Algorithm](https://signal.org/docs/specifications/sesame/)

155
waku/standards/core/waku2.md → waku/standards/core/10/waku2.md
View File

@@ -9,7 +9,6 @@ contributors:
- Reeshav Khan \<reeshav@status.im\>
- Daniel Kaiser \<danielkaiser@status.im\>
- Oskar Thorén \<oskarth@titanproxy.com\>
sidebar_position: 10
---
- Status: draft
- Editor: Hanno Cornelius \<hanno@status.im\>
@@ -32,7 +31,7 @@ These capabilities are things such as:
This makes Waku ideal for running a p2p protocol on mobile and in similarly restricted environments.
Historically, it has its roots in [6/WAKU1](../../legacy/6/waku1.md),
Historically, it has its roots in [6/WAKU1](../../legacy/6/waku1),
which stems from [Whisper](https://eips.ethereum.org/EIPS/eip-627), originally part of the Ethereum stack.
However, Waku v2 acts more as a thin wrapper for PubSub and has a different API.
It is implemented in an iterative manner where initial focus is on porting essential functionality to libp2p.
@@ -83,7 +82,7 @@ For example:
- 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](../../../informational/30/adaptive-nodes.md) spec.
please see the [30/ADAPTIVE-NODES](../../../informational/30/adaptive-nodes) spec.
## Network interaction domains
@@ -107,8 +106,8 @@ This is in addition to protocols that specify messages, payloads, and recommende
Since these aren't negotiated libp2p protocols, they are referred to by their RFC ID.
For example:
- [14/WAKU2-MESSAGE](../14/message.md) and [26/WAKU-PAYLOAD](../../application/26/payload.md) for message payloads
- [23/WAKU2-TOPICS](../../../informational/23/topics.md) and [27/WAKU2-PEERS](../../../informational/27/peers.md) for recommendations around usage
- [14/WAKU2-MESSAGE](../14/message) and [26/WAKU-PAYLOAD](../../application/26/payload) for message payloads
- [23/WAKU2-TOPICS](../../../informational/23/topics) and [27/WAKU2-PEERS](../../../informational/27/peers) for recommendations around usage
There are also more experimental libp2p protocols such as:
@@ -131,11 +130,11 @@ Waku is using gossiping to disseminate messages throughout the network.
**Protocol identifier**: `/vac/waku/relay/2.0.0`
See [11/WAKU2-RELAY](../11/relay.md) spec for more details.
See [11/WAKU2-RELAY](../11/relay) spec for more details.
For an experimental privacy-preserving economic spam protection mechanism, see [17/WAKU2-RLN-RELAY](../17/rln-relay.md).
For an experimental privacy-preserving economic spam protection mechanism, see [17/WAKU2-RLN-RELAY](../17/rln-relay).
See [23/WAKU2-TOPICS](../../../informational/23/topics.md) for more information about recommended topic usage.
See [23/WAKU2-TOPICS](../../../informational/23/topics) for more information about recommended topic usage.
### Direct use of libp2p protocols
@@ -191,14 +190,14 @@ A node MAY support unsecure websockets if required by the application or running
Waku v2 can retrieve a list of nodes to connect to using DNS-based discovery as per [EIP-1459](https://eips.ethereum.org/EIPS/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](https://docs.libp2p.io/concepts/publish-subscribe/#discovery) procedure to find still other nodes to connect to,
such as [Node Discovery v5](https://github.com/ethereum/devp2p/blob/8fd5f7e1c1ec496a9d8dc1640a8548b8a8b5986b/discv5/discv5.md).
such as [Node Discovery v5](https://github.com/ethereum/devp2p/blob/8fd5f7e1c1ec496a9d8dc1640a8548b8a8b5986b/discv5/discv5).
More ambient peer discovery methods are being tested for Waku v2,
and will be specified for wider adoption.
It is possible to bypass the discovery domain by specifying static nodes.
#### Use of ENR
[31/WAKU2-ENR](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/enr.md) describes the usage of [EIP-778 ENR (Ethereum Node Records)](https://eips.ethereum.org/EIPS/eip-778) for Waku v2 discovery purposes.
[31/WAKU2-ENR](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/enr) describes the usage of [EIP-778 ENR (Ethereum Node Records)](https://eips.ethereum.org/EIPS/eip-778) for Waku v2 discovery purposes.
It introduces two new ENR fields, `multiaddrs` and `waku2`, that a Waku v2 node MAY use for discovery purposes.
These fields MUST be used under certain conditions, as set out in the spec.
Both EIP-1459 DNS-based discovery and Node Discovery v5 operates on ENR,
@@ -217,24 +216,24 @@ such as low bandwidth or being mostly offline.
**Protocol identifier***: `/vac/waku/store/2.0.0-beta4`
This is used to fetch historical messages for mostly offline devices.
See [13/WAKU2-STORE spec](../13/store.md) spec for more details.
See [13/WAKU2-STORE spec](../13/store) spec for more details.
There is also an experimental fault-tolerant addition to the store protocol that relaxes the high availability requirement.
See [21/WAKU2-FT-STORE](../../application/21/fault-tolerant-store.md)
See [21/WAKU2-FT-STORE](../../application/21/fault-tolerant-store)
#### Content filtering
**Protocol identifier***: `/vac/waku/filter/2.0.0-beta1`
This is used to make fetching of a subset of messages more bandwidth preserving.
See [12/WAKU2-FILTER](../12/filter.md) spec for more details.
See [12/WAKU2-FILTER](../12/filter) spec for more details.
#### Light push
**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](../19/lightpush.md) spec for more details.
See [19/WAKU2-LIGHTPUSH](../19/lightpush) spec for more details.
#### Other protocols
@@ -245,35 +244,35 @@ and due to the modular design of Waku there may be other protocols here that pro
See the sequence diagram below for an overview of how different protocols interact.
![Overview of how protocols interact in Waku v2.](./10/images/overview.png)
![Overview of how protocols interact in Waku v2.](./images/overview.png)
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](../11/relay.md) for details.
Ditto for [13/WAKU2-STORE](../13/store.md) where it indicates that these messages are persisted on that node.
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](../11/relay) for details.
Ditto for [13/WAKU2-STORE](../13/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](../14/message.md) for more details.
If WakuMessage version is set to 1, we use the [6/WAKU1](../../legacy/6/waku1.md) compatible `data` field with encryption.
See [7/WAKU-DATA](../../legacy/7/data.md) for more details.
See [14/WAKU2-MESSAGE](../14/message) for more details.
If WakuMessage version is set to 1, we use the [6/WAKU1](../../legacy/6/waku1) compatible `data` field with encryption.
See [7/WAKU-DATA](../../legacy/7/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](../12/filter.md) for more details.
See [12/WAKU2-FILTER](../12/filter) for more details.
3. Node A publishes `msg1` on `pubtopic1` and subscribes to that relay topic pick it up.
It then gets relayed further from B to D, but not C since it doesn't subscribe to that topic.
See [11/WAKU2-RELAY](../11/relay.md).
See [11/WAKU2-RELAY](../11/relay).
4. Node D saves `msg1` for possible later retrieval by other nodes.
See [13/WAKU2-STORE](../13/store.md).
See [13/WAKU2-STORE](../13/store).
5. Node D also pushes `msg1` to F, as it has previously subscribed F to this filter.
See [12/WAKU2-FILTER](../12/filter.md).
See [12/WAKU2-FILTER](../12/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](../13/store.md).
Node D responds with messages meeting this (and possibly other) criteria. See [13/WAKU2-STORE](../13/store).
## Appendix A: Upgradability and Compatibility
@@ -284,7 +283,7 @@ They use a different transport protocol underneath; Waku v1 is devp2p RLPx based
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](../15/bridge.md) for details on a bidirectional bridge mode.
See [15/WAKU-BRIDGE](../15/bridge) for details on a bidirectional bridge mode.
# Appendix B: Security
@@ -323,11 +322,11 @@ As such, we seek anonymity by avoiding linkability between actions and the actor
**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](../11/relay.md/#security-analysis) 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.
The [Publisher-Message Unlinkability](../11/relay#security-analysis) 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](../11/relay.md/#security-analysis) is achieved through the utilization of a single PubSub topic.
The [Subscriber-Topic Unlinkability](../11/relay#security-analysis) 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](https://www.privitar.com/blog/k-anonymity-an-introduction/) 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.
@@ -335,13 +334,13 @@ Note that there is no hard limit on the number of the pubsub topics, however, th
### 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](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md#spam-protection-measures) provided for by GossipSub v1.1.
Spam protection is partly provided in `11/WAKU2-RELAY` through the [scoring mechanism](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1##spam-protection-measures) 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)](../14/message.md/#version-1)` through payload encryption as well as encrypted signatures.
These features are provided for in [14/WAKU2-MESSAGE (version 1)](../14/message#version-1)` through payload encryption as well as encrypted signatures.
## Security Considerations
@@ -375,39 +374,39 @@ This includes Waku v1 specs, as they are used for bridging between the two netwo
| Spec | nim-waku (Nim) | go-waku (Go) | js-waku (Node JS) | js-waku (Browser JS) |
| ---- | -------------- | ------------ | ----------------- | -------------------- |
|[6/WAKU1](../../legacy/6/waku1.md)|✔|||
|[7/WAKU-DATA](../../legacy/7/data.md)|✔|✔||
|[8/WAKU-MAIL](../../legacy/8/mail.md)|✔|||
|[9/WAKU-RPC](../../legacy/9/rpc.md)|✔|||
|[10/WAKU2](../10/waku2.md)|✔|🚧|🚧|🚧|
|[11/WAKU2-RELAY](../11/relay.md)|✔|✔|✔|✔|
|[12/WAKU2-FILTER](../12/filter.md)|✔|✔||
|[13/WAKU2-STORE](../13/store.md)|✔|✔|✔\*|✔\*|
|[14/WAKU2-MESSAGE](../14/message.md))|✔|✔|✔|✔|
|[15/WAKU2-BRIDGE](../15/bridge.md)|✔|||
|[16/WAKU2-RPC](../16/rpc.md)|✔|||
|[17/WAKU2-RLN-RELAY](../17/rln-relay.md)|🚧|||
|[18/WAKU2-SWAP](../../application/18/swap.md)|🚧|||
|[19/WAKU2-LIGHTPUSH](../19/lightpush.md)|✔|✔|✔\**|✔\**|
|[21/WAKU2-FAULT-TOLERANT-STORE](../../application/21/fault-tolerant-store.md)|✔|✔||
|[6/WAKU1](../../legacy/6/waku1)|✔|||
|[7/WAKU-DATA](../../legacy/7/data)|✔|✔||
|[8/WAKU-MAIL](../../legacy/8/mail)|✔|||
|[9/WAKU-RPC](../../legacy/9/rpc)|✔|||
|[10/WAKU2](../10/waku2)|✔|🚧|🚧|🚧|
|[11/WAKU2-RELAY](../11/relay)|✔|✔|✔|✔|
|[12/WAKU2-FILTER](../12/filter)|✔|✔||
|[13/WAKU2-STORE](../13/store)|✔|✔|✔\*|✔\*|
|[14/WAKU2-MESSAGE](../14/message))|✔|✔|✔|✔|
|[15/WAKU2-BRIDGE](../15/bridge)|✔|||
|[16/WAKU2-RPC](../16/rpc)|✔|||
|[17/WAKU2-RLN-RELAY](../17/rln-relay)|🚧|||
|[18/WAKU2-SWAP](../../application/18/swap)|🚧|||
|[19/WAKU2-LIGHTPUSH](../19/lightpush)|✔|✔|✔\**|✔\**|
|[21/WAKU2-FAULT-TOLERANT-STORE](../../application/21/fault-tolerant-store)|✔|✔||
*js-waku implements [13/WAKU2-STORE](../13/store.md) as a querying node only.
**js-waku only implements [19/WAKU2-LIGHTPUSH](../19/lightpush.md) requests.
*js-waku implements [13/WAKU2-STORE](../13/store) as a querying node only.
**js-waku only implements [19/WAKU2-LIGHTPUSH](../19/lightpush) requests.
### Recommendations for clients
To implement a minimal Waku v2 client, we recommend implementing the following subset in the following order:
- [10/WAKU2](../10/waku2.md) - this spec
- [11/WAKU2-RELAY](../11/relay.md) - for basic operation
- [14/WAKU2-MESSAGE](../14/message.md) - version 0 (unencrypted)
- [13/WAKU2-STORE](../13/store.md) - for historical messaging (query mode only)
- [10/WAKU2](../10/waku2) - this spec
- [11/WAKU2-RELAY](../11/relay) - for basic operation
- [14/WAKU2-MESSAGE](../14/message) - version 0 (unencrypted)
- [13/WAKU2-STORE](../13/store) - for historical messaging (query mode only)
To get compatibility with Waku v1:
- [7/WAKU-DATA](../../legacy/7/data.md)
- [14/WAKU2-MESSAGE](../14/message.md) - version 1 (encrypted with `7/WAKU-DATA`)
- [7/WAKU-DATA](../../legacy/7/data)
- [14/WAKU2-MESSAGE](../14/message) - version 1 (encrypted with `7/WAKU-DATA`)
For an interoperable keep-alive mechanism:
@@ -420,18 +419,18 @@ The following features are currently experimental and under research and initial
**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](../17/rln-relay.md).
More details on this can be found in [17/WAKU2-RLN-RELAY](../17/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](../../application/18/swap.md).
DoS attack is to be mitigated through the accounting model as described in [18/WAKU2-SWAP](../../application/18/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](../../application/18/swap.md) for more details on this piece of work.
See [18/WAKU2-SWAP](../../application/18/swap) for more details on this piece of work.
## Copyright
@@ -442,57 +441,57 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public
1. [libp2p specs](https://github.com/libp2p/specs)
2. [6/WAKU1](../../legacy/6/waku1.md)
2. [6/WAKU1](../../legacy/6/waku1)
3. [Whisper spec (EIP627)](https://eips.ethereum.org/EIPS/eip-627)
4. [Waku v2 plan](https://vac.dev/waku-v2-plan)
5. [30/ADAPTIVE-NODES](../../../informational/30/adaptive-nodes.md)
5. [30/ADAPTIVE-NODES](../../../informational/30/adaptive-nodes)
6. [Protocol Identifiers](https://docs.libp2p.io/concepts/protocols/)
7. [14/WAKU2-MESSAGE](../14/message.md)
7. [14/WAKU2-MESSAGE](../14/message)
8. [26/WAKU-PAYLOAD](../../application/26/payload.md)
8. [26/WAKU-PAYLOAD](../../application/26/payload)
9. [23/WAKU2-TOPICS](../../../informational/23/topics.md)
9. [23/WAKU2-TOPICS](../../../informational/23/topics)
10. [27/WAKU2-PEERS](../../../informational/27/peers.md)
10. [27/WAKU2-PEERS](../../../informational/27/peers)
11. [bi-directional binary stream](https://docs.libp2p.io/concepts/protocols/)
12. [Protobuf varint encoding](https://developers.google.com/protocol-buffers/docs/encoding#varints)
13. [11/WAKU2-RELAY spec](../11/relay.md)
13. [11/WAKU2-RELAY spec](../11/relay)
14. [17/WAKU2-RLN-RELAY](../17/rln-relay.md)
14. [17/WAKU2-RLN-RELAY](../17/rln-relay)
15. [EIP-1459](https://eips.ethereum.org/EIPS/eip-1459)
16. [Ambient peer discovery](https://docs.libp2p.io/concepts/publish-subscribe/#discovery)
17. [Node Discovery v5](https://github.com/ethereum/devp2p/blob/8fd5f7e1c1ec496a9d8dc1640a8548b8a8b5986b/discv5/discv5.md)
17. [Node Discovery v5](https://github.com/ethereum/devp2p/blob/8fd5f7e1c1ec496a9d8dc1640a8548b8a8b5986b/discv5/discv5)
18. [31/WAKU2-ENR](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/enr.md)
18. [31/WAKU2-ENR](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/enr)
19. [EIP-778 ENR (Ethereum Node Records)](https://eips.ethereum.org/EIPS/eip-778)
20. [13/WAKU2-STORE spec](../13/store.md)
20. [13/WAKU2-STORE spec](../13/store)
21. [21/WAKU2-FT-STORE](../../application/21/ft-store.md)
21. [21/WAKU2-FT-STORE](../../application/21/ft-store)
22. [12/WAKU2-FILTER](../12/filter.md)
22. [12/WAKU2-FILTER](../12/filter)
23. [19/WAKU2-LIGHTPUSH](../19/lightpush.md)
23. [19/WAKU2-LIGHTPUSH](../19/lightpush)
24. [7/WAKU-DATA](../../legacy/7/data.md)
24. [7/WAKU-DATA](../../legacy/7/data)
25. [15/WAKU-BRIDGE](../15/bridge.md)
25. [15/WAKU-BRIDGE](../15/bridge)
26. [k-anonymity](https://www.privitar.com/blog/k-anonymity-an-introduction/)
27. [GossipSub v1.1](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md)
27. [GossipSub v1.1](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1)
28. [nim-waku (Nim)](https://github.com/status-im/nim-waku/)
@@ -500,13 +499,13 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public
30. [js-waku (NodeJS and Browser)](https://github.com/status-im/js-waku/)
31. [8/WAKU-MAIL](../../legacy/8/mail.md)
31. [8/WAKU-MAIL](../../legacy/8/mail)
32. [9/WAKU-RPC](../../legacy/9/rpc.md)
32. [9/WAKU-RPC](../../legacy/9/rpc)
33. [16/WAKU2-RPC](../16/rpc.md)
33. [16/WAKU2-RPC](../16/rpc)
34. [18/WAKU2-SWAP spec](../../application/18/swap.md)
34. [18/WAKU2-SWAP spec](../../application/18/swap)
35. [21/WAKU2-FAULT-TOLERANT-STORE](../../application/21/fault-tolerant-store.md)
35. [21/WAKU2-FAULT-TOLERANT-STORE](../../application/21/fault-tolerant-store)

41
waku/standards/core/relay.md → waku/standards/core/11/relay.md
View File

@@ -6,7 +6,6 @@ editor: Hanno Cornelius \<hanno@status.im\>
contributors:
- Oskar Thorén \<oskarth@titanproxy.com\>
- Sanaz Taheri \<sanaz@status.im\>
sidebar_position: 11
---
- Status: stable
- Editor: Hanno Cornelius \<hanno@status.im\>
@@ -15,8 +14,8 @@ sidebar_position: 11
- Sanaz Taheri \<sanaz@status.im\>
`11/WAKU2-RELAY` specifies a [Publish/Subscribe approach](https://docs.libp2p.io/concepts/publish-subscribe/) to peer-to-peer messaging with a strong focus on privacy, censorship-resistance, security and scalability.
Its current implementation is a minor extension of the [libp2p GossipSub protocol](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/README.md) and prescribes gossip-based dissemination.
As such the scope is limited to defining a separate [`protocol id`](https://github.com/libp2p/specs/blob/master/connections/README.md#protocol-negotiation) for `11/WAKU2-RELAY`, establishing privacy and security requirements, and defining how the underlying GossipSub is to be interpreted and implemented within the Waku and cryptoeconomic domain.
Its current implementation is a minor extension of the [libp2p GossipSub protocol](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/README) and prescribes gossip-based dissemination.
As such the scope is limited to defining a separate [`protocol id`](https://github.com/libp2p/specs/blob/master/connections/README##protocol-negotiation) for `11/WAKU2-RELAY`, establishing privacy and security requirements, and defining how the underlying GossipSub is to be interpreted and implemented within the Waku and cryptoeconomic domain.
`11/WAKU2-RELAY` should not be confused with [libp2p circuit relay](https://github.com/libp2p/specs/tree/master/relay).
**Protocol identifier**: `/vac/waku/relay/2.0.0`
@@ -24,7 +23,7 @@ As such the scope is limited to defining a separate [`protocol id`](https://gith
## Security Requirements
The `11/WAKU2-RELAY` protocol is designed to provide the following security properties under a static [Adversarial Model](#adversarial-model).
Note that data confidentiality, integrity, and authenticity are currently considered out of scope for `11/WAKU2-RELAY` and must be handled by higher layer protocols such as [`14/WAKU2-MESSAGE`](../14/message.md).
Note that data confidentiality, integrity, and authenticity are currently considered out of scope for `11/WAKU2-RELAY` and must be handled by higher layer protocols such as [`14/WAKU2-MESSAGE`](../14/message).
<!-- May add the definition of the unsupported feature:
@@ -63,7 +62,7 @@ However, a malicious subscriber may learn which topics are subscribed to by whic
## Wire Specification
The [PubSub interface specification](https://github.com/libp2p/specs/blob/master/pubsub/README.md) defines the protobuf RPC messages exchanged between peers participating in a GossipSub network.
The [PubSub interface specification](https://github.com/libp2p/specs/blob/master/pubsub/README) defines the protobuf RPC messages exchanged between peers participating in a GossipSub network.
We republish these messages here for ease of reference and define how `11/WAKU2-RELAY` uses and interprets each field.
### Protobuf definitions
@@ -94,10 +93,10 @@ message RPC {
```
\> **_NOTE:_**
The various [control messages](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.0.md#control-messages) defined for GossipSub are used as specified there.
The various [control messages](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.0##control-messages) defined for GossipSub are used as specified there.
\> **_NOTE:_**
The [`TopicDescriptor`](https://github.com/libp2p/specs/blob/master/pubsub/README.md#the-topic-descriptor) is not currently used by `11/WAKU2-RELAY`.
The [`TopicDescriptor`](https://github.com/libp2p/specs/blob/master/pubsub/README##the-topic-descriptor) is not currently used by `11/WAKU2-RELAY`.
### Message fields
@@ -107,7 +106,7 @@ The `Message` protobuf defines the format in which content is relayed between pe
- The `from` field MUST NOT be used, following the [`StrictNoSign` signature policy](#signature-policy).
- The `data` field MUST be filled out with a `WakuMessage`.
See [`14/WAKU2-MESSAGE`](../14/message.md) for more details.
See [`14/WAKU2-MESSAGE`](../14/message) for more details.
- The `seqno` field MUST NOT be used, following the [`StrictNoSign` signature policy](#signature-policy).
@@ -128,11 +127,11 @@ The following usage requirements apply:
- The `topicid` field MUST contain the pubsub topic.
\> Note: The `topicid` refering to pubsub topic and
`topicId` refering to content-topic are detailed in [23/WAKU2-TOPICS](../../../informational/23/topics.md).
`topicId` refering to content-topic are detailed in [23/WAKU2-TOPICS](../../../informational/23/topics).
### Signature Policy
The [`StrictNoSign` option](https://github.com/libp2p/specs/blob/master/pubsub/README.md#signature-policy-options) MUST be used, to ensure that messages are built without the `signature`, `key`, `from` and `seqno` fields.
The [`StrictNoSign` option](https://github.com/libp2p/specs/blob/master/pubsub/README##signature-policy-options) MUST be used, to ensure that messages are built without the `signature`, `key`, `from` and `seqno` fields.
Note that this does not merely imply that these fields be empty, but that they MUST be _absent_ from the marshalled message.
## Security Analysis
@@ -152,7 +151,7 @@ The possibility of such inference may get higher when the `data` field is also n
- **Subscriber-Topic Unlinkability:**
To preserve subscriber-topic unlinkability, it is recommended by [`10/WAKU2`](../10/waku2.md) to use a single PubSub topic in the `11/WAKU2-RELAY` protocol.
To preserve subscriber-topic unlinkability, it is recommended by [`10/WAKU2`](../10/waku2) to use a single PubSub topic in the `11/WAKU2-RELAY` protocol.
This allows an immediate subscriber-topic unlinkability where 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](https://www.privitar.com/blog/k-anonymity-an-introduction/) where k is proportional to the system size (number of participants of Waku relay protocol).
However, note that `11/WAKU2-RELAY` supports the use of more than one topic.
@@ -162,11 +161,11 @@ In case that more than one topic id is utilized, preserving unlinkability is the
- **Economic spam resistance**:
In the spam-protected `11/WAKU2-RELAY` protocol, no adversary can flood the system with spam messages (i.e., publishing a large number of messages in a short amount of time).
Spam protection is partly provided by GossipSub v1.1 through [scoring mechanism](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md#spam-protection-measures).
Spam protection is partly provided by GossipSub v1.1 through [scoring mechanism](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1##spam-protection-measures).
At a high level, peers utilize a scoring function to locally score the behavior of their connections and remove peers with a low score.
`11/WAKU2-RELAY` aims at enabling an advanced spam protection mechanism with economic disincentives by utilizing Rate Limiting Nullifiers.
In a nutshell, peers must conform to a certain message publishing rate per a system-defined epoch, otherwise, they get financially penalized for exceeding the rate.
More details on this new technique can be found in [`17/WAKU2-RLN-RELAY`](../17/rln-relay.md).
More details on this new technique can be found in [`17/WAKU2-RLN-RELAY`](../17/rln-relay).
<!-- TODO havn't checked if all the measures in libp2p GossipSub v1.1 are taken in the nim-libp2p as well, may need to audit the code -->
@@ -186,28 +185,28 @@ Copyright and related rights waived via
## References
1. [`10/WAKU2`](../10/waku2.md)
1. [`10/WAKU2`](../10/waku2)
1. [`14/WAKU2-MESSAGE`](../14/message.md)
1. [`14/WAKU2-MESSAGE`](../14/message)
1. [`17/WAKU-RLN`](../17/rln-relay.md)
1. [`17/WAKU-RLN`](../17/rln-relay)
1. [GossipSub v1.0](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.0.md)
1. [GossipSub v1.0](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.0)
1. [GossipSub v1.1](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md)
1. [GossipSub v1.1](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1)
1. [K-anonimity](https://www.privitar.com/blog/k-anonymity-an-introduction/)
1. [`libp2p` concepts: Publish/Subscribe](https://docs.libp2p.io/concepts/publish-subscribe/)
1. [`libp2p` protocol negotiation](https://github.com/libp2p/specs/blob/master/connections/README.md#protocol-negotiation)
1. [`libp2p` protocol negotiation](https://github.com/libp2p/specs/blob/master/connections/README##protocol-negotiation)
1. [Partitioned topics](https://specs.status.im/spec/10#partitioned-topic)
1. [Protocol Buffers](https://developers.google.com/protocol-buffers/)
1. [PubSub interface for libp2p (r2, 2019-02-01)](https://github.com/libp2p/specs/blob/master/pubsub/README.md)
1. [PubSub interface for libp2p (r2, 2019-02-01)](https://github.com/libp2p/specs/blob/master/pubsub/README)
1. [Waku v1 spec](../6/waku1.md)
1. [Waku v1 spec](../6/waku1)
1. [Whisper spec (EIP627)](https://eips.ethereum.org/EIPS/eip-627)

207
waku/standards/core/12/filter.md
View File

@@ -2,31 +2,35 @@
title: 12/WAKU2-FILTER
name: Waku v2 Filter
status: draft
version: 01
editor: Hanno Cornelius \<hanno@status.im\>
contributors:
- Dean Eigenmann \<dean@status.im\>
- Oskar Thorén \<oskarth@titanproxy.com\>
- Oskar Thorén \<oskar@status.im\>
- Sanaz Taheri \<sanaz@status.im\>
- Ebube Ud \<ebube@status.im\>
sidebar_position: 12
---
- Status: draft
- Editor: Hanno Cornelius \<hanno@status.im\>
- Contributors::
- Dean Eigenmann \<dean@status.im\>
- Oskar Thorén \<oskarth@titanproxy.com\>
- Oskar Thorén \<oskar@status.im\>
- Sanaz Taheri \<sanaz@status.im\>
- Ebube Ud \<ebube@status.im\>
- Contributors::
version: 00
previous versions: [00](./previous-versions00)
---
`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`
**Protocol identifiers**:
- _filter-subscribe_: `/vac/waku/filter-subscribe/2.0.0-beta1`
- _filter-push_: `/vac/waku/filter-push/2.0.0-beta1`
Content filtering is a way to do [message-based
filtering](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern#Message_filtering).
@@ -71,80 +75,164 @@ The following are not considered as part of the adversarial model:
### Protobuf
```protobuf
message FilterRequest {
bool subscribe = 1;
string topic = 2;
repeated ContentFilter contentFilters = 3;
syntax = "proto3";
message ContentFilter {
string contentTopic = 1;
// 12/WAKU2-FILTER rfc: https://rfc.vac.dev/spec/12/
package waku.filter.v2;
// 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 {
repeated WakuMessage messages = 1;
}
message FilterRPC {
string requestId = 1;
FilterRequest request = 2;
MessagePush push = 3;
WakuMessage waku_message = 1;
optional string pubsub_topic = 2;
}
```
#### FilterRPC
### Filter-Subscribe
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.
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.
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.
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.
An incentive mechanism is currently planned but underspecified.
#### FilterRequest
#### Filter Subscribe Request
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 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.
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.
#### Filter Subscribe Response
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.
In return to any `FilterSubscribeRequest`,
a filter service node SHOULD respond with 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.
The filter matches when content filter and, optionally, a topic is matched.
Content filter is matched when a `WakuMessage` `contentTopic` field is the same.
#### Filter matching
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.
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 `WakuMessage` matches filter criteria when its `content_topic` is in the `content_topics` set
and it was published on a matching `pubsub_topic`.
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.
#### Filter Subscribe Types
#### MessagePush
The following filter subscribe types are defined:
A filter node that has received a filter request SHOULD push all messages that
match this filter to a light node. These [`WakuMessage`'s](../14/message.md) 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.
##### SUBSCRIBER_PING
A filter node MUST NOT send a push message for messages that have not been
requested via a FilterRequest.
A filter client that sends a `FilterSubscribeRequest` with `filter_subscribe_type` set to `SUBSCRIBER_PING`
requests that the 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 code if it has any active subscriptions for this client
or an error code if not.
The filter service node SHOULD ignore any filter criteria in the request.
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.
##### SUBSCRIBE
A filter client that sends a `FilterSubscribeRequest` with `filter_subscribe_type` set to `SUBSCRIBE`
requests that the 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 code if it successfully honored this request
or an error code if not.
The filter service node SHOULD respond with an error code and discard the request
if the subscribe request 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 code if it successfully honored this request
or an error code if not.
The filter service node SHOULD respond with an error 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 code if it successfully honored this request
or an error 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 [`WakuMessage`s](../14/message) are likely to come from [`11/WAKU2-RELAY`](../11/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.
We consider `1 minute` to be 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.
---
# Future Work
## Future Work
<!-- Alternative title: Filter-subscriber unlinkability -->
@@ -178,6 +266,13 @@ Copyright and related rights waived via
## References
- [message-based
filtering](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern#Message_filtering)
- [`WakuMessage`s](../14/message)
- [`11/WAKU2-RELAY`](../11/relay)
- [Oblivious Transfers](https://link.springer.com/referenceworkentry/10.1007%2F978-1-4419-5906-5_9#:~:text=Oblivious%20transfer%20(OT)%20is%20a,information%20the%20receiver%20actually%20obtains)
- previous versions: [00](./previous-versions00)
1. [Message Filtering (Wikipedia)](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern#Message_filtering)
2. [Libp2p PubSub spec - topic validation](https://github.com/libp2p/specs/tree/master/pubsub#topic-validation)

182
waku/standards/core/12/previous-versions00/filter.md Normal file
View File

@@ -0,0 +1,182 @@
---
title: 12/WAKU2-FILTER
name: Waku v2 Filter
status: draft
editor: Hanno Cornelius \<hanno@status.im\>
contributors:
- Dean Eigenmann \<dean@status.im\>
- Oskar Thorén \<oskarth@titanproxy.com\>
- Sanaz Taheri \<sanaz@status.im\>
- Ebube Ud \<ebube@status.im\>
---
- Status: draft
- Editor: Hanno Cornelius \<hanno@status.im\>
- Contributors::
- Dean Eigenmann \<dean@status.im\>
- Oskar Thorén \<oskarth@titanproxy.com\>
- Sanaz Taheri \<sanaz@status.im\>
- Ebube Ud \<ebube@status.im\>
- Contributors::
version: 00
---
`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](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern#Message_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](#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
```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](../14/message) 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
<!-- Alternative title: Filter-subscriber unlinkability -->
**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
<!-- TODO: if nodes have to disclose their PeerIDs (e.g., for authentication purposes) when connecting to other nodes in the WakuFilter protocol, then Tor does not preserve anonymity since it only helps in hiding the IP. So, the PeerId usage in switches must be investigated further. Depending on how PeerId is used, one may be able to link between a subscriber and its content filter despite hiding the IP address-->
.
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](https://link.springer.com/referenceworkentry/10.1007%2F978-1-4419-5906-5_9#:~:text=Oblivious%20transfer%20(OT)%20is%20a,information%20the%20receiver%20actually%20obtains.) and one-way Private Set Intersections (PSI).
## Changelog
### Next
- Added initial threat model and security analysis.
### 2.0.0-beta2
Initial draft version. Released [2020-10-28](https://github.com/vacp2p/specs/commit/5ceeb88cee7b918bb58f38e7c4de5d581ff31e68)
- Fix: Ensure contentFilter is a repeated field, on implementation
- Change: Add ability to unsubscribe from filters. Make `subscribe` an explicit boolean indication. Edit protobuf field order to be consistent with libp2p.
### 2.0.0-beta1
Initial draft version. Released [2020-10-05](https://github.com/vacp2p/specs/commit/31857c7434fa17efc00e3cd648d90448797d107b)
## Copyright
Copyright and related rights waived via
[CC0](https://creativecommons.org/publicdomain/zero/1.0/).
## References
1. [Message Filtering (Wikipedia)](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern#Message_filtering)
2. [Libp2p PubSub spec - topic validation](https://github.com/libp2p/specs/tree/master/pubsub#topic-validation)

23
waku/standards/core/store.md → waku/standards/core/13/store.md
View File

@@ -9,7 +9,6 @@ contributors:
- Aaryamann Challani \<aaryamann@status.im\>
- Sanaz Taheri \<sanaz@status.im\>
- Hanno Cornelius \<hanno@status.im\>
sidebar_position: 13
---
- Status: draft
- Editor: Simon-Pierre Vivier \<simvivier@status.im\>
@@ -46,8 +45,8 @@ 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`](../14/message.md) affects `13/WAKU2-STORE` as well.
Nodes running `13/WAKU2-STORE` SHOULD support `ephemeral` messages as specified in [14/WAKU2-MESSAGE](../14/message.md).
The concept of `ephemeral` messages introduced in [`14/WAKU2-MESSAGE`](../14/message) affects `13/WAKU2-STORE` as well.
Nodes running `13/WAKU2-STORE` SHOULD support `ephemeral` messages as specified in [14/WAKU2-MESSAGE](../14/message).
Nodes running `13/WAKU2-STORE` SHOULD NOT store messages with the `ephemeral` flag set to `true`.
## Adversarial Model
@@ -128,7 +127,7 @@ message HistoryRPC {
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](../14/message.md)).
The hash is computed over the concatenation of `contentTopic` and `payload` fields of a `WakuMessage` (see [14/WAKU2-MESSAGE](../14/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.
@@ -144,7 +143,7 @@ each `WakuMessage` stored at a node running the `13/WAKU2-STORE` protocol is ass
#### 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](../14/message.md).
This field maps to the `contentTopic` field of the [14/WAKU2-MESSAGE](../14/message).
#### HistoryQuery
@@ -152,7 +151,7 @@ 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 `WakuMessage`s are published.
This field maps to `topicIDs` field of `Message` in [`11/WAKU2-RELAY`](../11/relay.md).
This field maps to `topicIDs` field of `Message` in [`11/WAKU2-RELAY`](../11/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.
@@ -189,13 +188,13 @@ nodes' clock asynchrony.
RPC call to respond to a HistoryQuery call.
- The `messages` field MUST contain the messages found,
these are [14/WAKU2-MESSAGE](../14/message.md) types.
these are [14/WAKU2-MESSAGE](../14/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 messages](#sorting-messages) section, 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](../14/message.md).
The requester SHALL embed the returned `cursor` inside its next `HistoryQuery` to retrieve the next page of the [14/WAKU2-MESSAGE](../14/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.
@@ -209,9 +208,9 @@ The main security consideration to take into account while using this protocol i
## 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](../14/message.md) they are interested in.
without disclosing the exact topics of [14/WAKU2-MESSAGE](../14/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](../14/message.md).
content topics of [14/WAKU2-MESSAGE](../14/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.
@@ -270,7 +269,7 @@ Copyright and related rights waived via
[CC0](https://creativecommons.org/publicdomain/zero/1.0/).
## References
1. [14/WAKU2-MESSAGE](../14/message.md)
1. [14/WAKU2-MESSAGE](../14/message)
2. [protocol buffers v3](https://developers.google.com/protocol-buffers/)
3. [11/WAKU2-RELAY](../11/relay.md)
3. [11/WAKU2-RELAY](../11/relay)
4. [Open timestamps](https://opentimestamps.org/)

19
waku/standards/core/message.md → waku/standards/core/14/message.md
View File

@@ -10,7 +10,6 @@ contributors:
- Lorenzo Delgado \<lorenzo@status.im\>
- Abhimanyu Rawat \<abhi@status.im\>
- Oskar Thorén \<oskarth@titanproxy.com\>
sidebar_position: 14
---
- Status: draft
- Category: Standards Track
@@ -37,7 +36,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 [Waku v1 envelopes](../../legacy/6/waku1).
- One may want encrypted payloads by default.
- One may want to provide unlinkability to get metadata protection.
@@ -59,7 +58,7 @@ The data payload is also treated as a Waku message attribute for convenience.
* The `payload` attribute MUST contain the message data payload to be sent.
* 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](../../../informational/23/topics).
* 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, thereby enabling customized processing based on its contents.
@@ -105,13 +104,13 @@ The message `version` attribute indicates the schema used to encrypt the payload
The payload SHOULD be interpreted as unencrypted; additionally, it CAN indicate that the message payload has been encrypted 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 Waku v1 payload encryption specified in [26/WAKU-PAYLOAD](../../application/26/payload).
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 [35/WAKU2-NOISE]([/spec/35](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/noise.md)).
The payload SHOULD be encoded according to [35/WAKU2-NOISE]([/spec/35](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/noise)).
Waku Noise protocol provides symmetric encryption and asymmetric key exchange.
Any `version` value not included in this list is reserved for future specification.
@@ -204,7 +203,7 @@ Therefore, because message timestamps aren’t independently verified, this attr
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 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.
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).
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#clock-vs-timestamp-and-message-ordering).
### Reliability of the `ephemeral` attribute
@@ -219,8 +218,8 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public
## References
- [6/WAKU1](../../legacy/6/waku1.md)
- [6/WAKU1](../../legacy/6/waku1)
- [Google Protocol buffers v3](https://developers.google.com/protocol-buffers/)
- [26/WAKU-PAYLOAD](../../application/26/payload.md)
- [35/WAKU2-NOISE]([/spec/35](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/noise.md))
- [62/STATUS-PAYLOADS](../../../../status/62/payloads.md/#clock-vs-timestamp-and-message-ordering)
- [26/WAKU-PAYLOAD](../../application/26/payload)
- [35/WAKU2-NOISE]([/spec/35](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/noise))
- [62/STATUS-PAYLOADS](../../../../status/62/payloads#clock-vs-timestamp-and-message-ordering)

1
waku/standards/core/bridge.md → waku/standards/core/15/bridge.md
View File

@@ -3,7 +3,6 @@ title: 15/WAKU-BRIDGE
name: Waku Bridge
status: draft
editor: Hanno Cornelius \<hanno@status.im\>
sidebar_position: 15
---
- Status: draft
- Editor: Hanno Cornelius \<hanno@status.im\>

31
waku/standards/core/rln-relay.md → waku/standards/core/17/rln-relay.md
View File

@@ -8,7 +8,6 @@ contributors:
- Aaryamann Challani \<aaryamann@status.im\>
- Sanaz Taheri \<sanaz@status.im\>
- Hanno Cornelius \<hanno@status.im\>
sidebar_position: 17
---
- Status: draft
- Editor: Alvaro Revuelta \<alvaro@status.im\>
@@ -18,7 +17,7 @@ sidebar_position: 17
- Sanaz Taheri \<sanaz@status.im\>
- Hanno Cornelius \<hanno@status.im\>
The `17/WAKU2-RLN-RELAY` protocol is an extension of `11/WAKU2-RELAY` which additionally provides spam protection using [Rate Limiting Nullifiers (RLN)](../../../../vac/32/rln-v1.md).
The `17/WAKU2-RLN-RELAY` protocol is an extension of `11/WAKU2-RELAY` which additionally provides spam protection using [Rate Limiting Nullifiers (RLN)](../../../../vac/32/rln-v1).
The security objective is to contain spam activity in a GossipSub 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.
@@ -35,7 +34,7 @@ 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`](../11/relay.md) protocol with a novel construct of [RLN](../../../../vac/32/rln-v1.md) to enable an efficient economic spam prevention mechanism that can be run in resource-constrained environments.
We augment the [`11/WAKU2-RELAY`](../11/relay) protocol with a novel construct of [RLN](../../../../vac/32/rln-v1) to enable an efficient economic spam prevention mechanism that can be run in resource-constrained environments.
## Flow
@@ -51,13 +50,13 @@ The higher-level layers adopting `17/WAKU2-RLN-RELAY` MAY choose to enforce the
### Setup and Registration
Peers subscribed to a specific `pubsubTopic` form a [RLN group](../../../../vac/32/rln-v1.md).
Peers subscribed to a specific `pubsubTopic` form a [RLN group](../../../../vac/32/rln-v1).
<!-- link to the RLN group definition in the RLN RFC -->
Peers MUST be registered to the RLN group to be able to publish messages.
Registration is moderated through a smart contract deployed on the Ethereum blockchain.
Each peer has an [RLN key pair](../../../../vac/32/rln-v1.md) denoted by `sk` and `pk`.
Each peer has an [RLN key pair](../../../../vac/32/rln-v1) 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 contains the list of registered members' public identity keys i.e., `pk`s.
For the registration, a peer creates a transaction that invokes the registration function of the contract via which registers its `pk` in the group.
@@ -71,12 +70,12 @@ The peer who has the secret key `sk` associated with a registered `pk` would be
Note that `sk` is initially 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.
![Figure 1: Registration.](./17/images/rln-relay.png)
![Figure 1: Registration.](./images/rln-relay.png)
### Publishing
To publish at a given `epoch`, the publishing peer proceeds based on the regular [`11/WAKU2-RELAY`](../11/relay.md) protocol.
To publish at a given `epoch`, the publishing peer proceeds based on the regular [`11/WAKU2-RELAY`](../11/relay) protocol.
However, to protect against spamming, each `WakuMessage` (which is wrapped inside the `data` field of a PubSub message) MUST carry a [`RateLimitProof`](##RateLimitProof) with the following fields.
Section [Payload](#payloads) covers the details about the type and encoding of these fields.
@@ -88,7 +87,7 @@ The `nullifier` is an internal nullifier acting as a fingerprint that allows spe
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 `nullifier`s.
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](../../../../vac/32/rln-v1.md).
They are derived deterministically from peer's `sk` and current `epoch` using [Shamir secret sharing scheme](../../../../vac/32/rln-v1).
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.
@@ -96,7 +95,7 @@ The `proof` field is a zero-knowledge proof signifying that:
1. The message owner is the current member of the group i.e., her/his 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](../../../../vac/32/rln-v1.md)
For more details about the proof generation check [RLN](../../../../vac/32/rln-v1)
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.
<!-- TODO refer to RLN RFC for authPath def -->
@@ -122,7 +121,7 @@ The reason is that using an old root can allow inference about the index of the
### Routing
Upon the receipt of a PubSub message via [`11/WAKU2-RELAY`](../11/relay.md) protocol, the routing peer parses the `data` field as a `WakuMessage` and gets access to the `RateLimitProof` field.
Upon the receipt of a PubSub message via [`11/WAKU2-RELAY`](../11/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
@@ -146,7 +145,7 @@ See [Recommended System Parameters](#recommended-system-parameters) on choosing
#### 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](../../../../vac/32/rln-v1.md).
It does so by running the zk verification algorithm as explained in [RLN](../../../../vac/32/rln-v1).
If `proof` is invalid then the message is discarded.
#### Spam detection
@@ -162,17 +161,17 @@ An overview of the routing procedure and slashing is provided in Figure 2.
<!-- TODO: may consider [validator functions](https://github.com/libp2p/specs/tree/master/pubsub#topic-validation) or [extended validators](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md#extended-validators) for the spam detection -->
<!-- TODO: may consider [validator functions](https://github.com/libp2p/specs/tree/master/pubsub#topic-validation) or [extended validators](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1##extended-validators) for the spam detection -->
![Figure 2: Publishing, Routing and Slashing workflow.](./17/images/rln-message-verification.png)
![Figure 2: Publishing, Routing and Slashing workflow.](./images/rln-message-verification.png)
-------
## Payloads
Payloads are protobuf messages implemented using [protocol buffers v3](https://developers.google.com/protocol-buffers/).
Nodes MAY extend the [14/WAKU2-MESSAGE](../14/message.md) with a `rate_limit_proof` field to indicate that their message is not spam.
Nodes MAY extend the [14/WAKU2-MESSAGE](../14/message) with a `rate_limit_proof` field to indicate that their message is not spam.
```diff
@@ -208,10 +207,10 @@ Below is the description of the fields of `RateLimitProof` and their types.
| ----: | ----------- | ----------- |
| `proof` | array of 256 bytes | the zkSNARK proof as explained in the [Publishing process](##Publishing) |
| `merkle_root` | array of 32 bytes in little-endian order | the root of membership group Merkle tree at the time of publishing the message |
| `share_x` and `share_y`| array of 32 bytes each | Shamir secret shares of the user's secret identity key `sk` . `share_x` is the Poseidon hash of the `WakuMessage`'s `payload` concatenated with its `contentTopic` . `share_y` is calculated using [Shamir secret sharing scheme](../../../../vac/32/rln-v1.md) |
| `share_x` and `share_y`| array of 32 bytes each | Shamir secret shares of the user's secret identity key `sk` . `share_x` is the Poseidon hash of the `WakuMessage`'s `payload` concatenated with its `contentTopic` . `share_y` is calculated using [Shamir secret sharing scheme](../../../../vac/32/rln-v1) |
<!-- todo specify the poseidon hash setting -->
| `nullifier` | array of 32 bytes | internal nullifier derived from `epoch` and peer's `sk` as explained in [RLN construct](../../../../vac/32/rln-v1.md)|
| `nullifier` | array of 32 bytes | internal nullifier derived from `epoch` and peer's `sk` as explained in [RLN construct](../../../../vac/32/rln-v1)|
## Recommended System Parameters

13
waku/standards/core/lightpush.md → waku/standards/core/19/lightpush.md
View File

@@ -6,7 +6,6 @@ editor: Hanno Cornelius \<hanno@status.im\>
contributors:
- Daniel Kaiser \<danielkaiser@status.im\>
- Oskar Thorén \<oskarth@titanproxy.com\>
sidebar_position: 19
---
- Status: draft
- Editor: Hanno Cornelius \<hanno@status.im\>
@@ -50,14 +49,14 @@ message PushRPC {
### Message Relaying
Nodes that respond to `PushRequests` MUST either
relay the encapsulated message via [11/WAKU2-RELAY](../11/relay.md) protocol on the specified `pubsub_topic`,
or forward the `PushRequest` via 19/LIGHTPUSH on a [WAKU2-DANDELION](https://github.com/waku-org/specs/blob/waku-RFC/standards/application/dandelion.md) stem.
relay the encapsulated message via [11/WAKU2-RELAY](../11/relay) protocol on the specified `pubsub_topic`,
or forward the `PushRequest` via 19/LIGHTPUSH on a [WAKU2-DANDELION](https://github.com/waku-org/specs/blob/waku-RFC/standards/application/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](../17/rln-relay.md).
This can be done by rate limiting via [17/WAKU2-RLN-RELAY](../17/rln-relay).
Note that the above is currently not fully implemented.
@@ -67,6 +66,6 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public
## References
* [11/WAKU2-RELAY](../11/relay.md)
* [WAKU2-DANDELION](https://github.com/waku-org/specs/blob/waku-RFC/standards/application/dandelion.md)
* [17/WAKU2-RLN-RELAY](../17/rln-relay.md)
* [11/WAKU2-RELAY](../11/relay)
* [WAKU2-DANDELION](https://github.com/waku-org/specs/blob/waku-RFC/standards/application/dandelion)
* [17/WAKU2-RLN-RELAY](../17/rln-relay)

45
waku/standards/core/discv5.md → waku/standards/core/33/discv5.md
View File

@@ -4,21 +4,20 @@ name: Waku v2 Discv5 Ambient Peer Discovery
status: draft
editor: Daniel Kaiser \<danielkaiser@status.im\>
contributors:
sidebar_position: 33
---
- Status: draft
- Editor: Daniel Kaiser \<danielkaiser@status.im\>
## Abstract
`33/WAKU2-DISCV5` specifies a modified version of [Ethereum's Node Discovery Protocol v5](https://github.com/ethereum/devp2p/blob/master/discv5/discv5.md) as a means for ambient node discovery.
[10/WAKU2](../10/waku2.md) uses the `33/WAKU2-DISCV5` ambient node discovery network for establishing a decentralized network of interconnected Waku2 nodes.
`33/WAKU2-DISCV5` specifies a modified version of [Ethereum's Node Discovery Protocol v5](https://github.com/ethereum/devp2p/blob/master/discv5/discv5) as a means for ambient node discovery.
[10/WAKU2](../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](../10/waku2.md).
This version of `33/WAKU2-DISCV5` has a focus on timely deployment of an efficient discovery method for [10/WAKU2](../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](https://forum.vac.dev/t/waku-v2-discv5-roadmap-discussion/121/8)
and researching hybrid approaches.
@@ -26,16 +25,16 @@ and researching hybrid approaches.
## Background and Rationale
[11/WAKU2-RELAY](../11/relay.md) assumes the existence of a network of Waku2 nodes.
[11/WAKU2-RELAY](../11/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](../10/waku2.md) supports the following discovery methods in order of increasing decentralization
[10/WAKU2](../10/waku2) supports the following discovery methods in order of increasing decentralization
* hard coded bootstrap nodes
* [`DNS discovery`](https://rfc.vac.dev/spec/10/#discovery-domain) (based on [EIP-1459](https://eips.ethereum.org/EIPS/eip-1459))
* `peer-exchange` (work in progress)
* `33/WAKU2-DISCV5` (specified in this document)
The purpose of ambient node discovery within [10/WAKU2](../10/waku2.md) is discovering Waku2 nodes in a decentralized way.
The purpose of ambient node discovery within [10/WAKU2](../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.
@@ -44,7 +43,7 @@ Future iterations of this document will add the possibility of efficiently disco
#### w.r.t. Waku2 Relay Network
`33/WAKU2-DISCV5` spans an overlay network separate from the [GossipSub](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/README.md) network [11/WAKU2-RELAY](../11/relay.md) builds on.
`33/WAKU2-DISCV5` spans an overlay network separate from the [GossipSub](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/README) network [11/WAKU2-RELAY](../11/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.
@@ -54,7 +53,7 @@ This also increases decentralization.
`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](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/enr.md).
Another simple solution would be taking part in the Ethereum Discovery network, and filtering Waku nodes based on whether they support [WAKU2-ENR](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/enr).
This solution is more resilient towards eclipse attacks.
However, this discovery method is very inefficient for small percentages of Waku nodes (see [estimation](https://forum.vac.dev/t/waku-v2-discv5-roadmap-discussion/121/8)).
It boils down to random walk discovery and does not offer a O(log(n)) hop bound.
@@ -62,7 +61,7 @@ The rarer the requested property (in this case Waku), the longer a random walk w
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](https://github.com/ethereum/devp2p/blob/master/discv5/discv5-theory.md#topic-advertisement).
A more sophisticated solution would be using [Discv5 topic discovery](https://github.com/ethereum/devp2p/blob/master/discv5/discv5-theory##topic-advertisement).
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](https://github.com/ethereum/devp2p/issues/199)).
Currently, the Ethereum discv5 network is very efficient in finding other discv5 nodes,
@@ -70,21 +69,21 @@ but it is not so efficient for finding discv5 nodes that have a specific propert
As part of our [discv5 roadmap](https://forum.vac.dev/t/waku-v2-discv5-roadmap-discussion/121), we consider two ideas for future versions of `33/WAKU2-DISCV5`
* [Discv5 topic discovery](https://github.com/ethereum/devp2p/blob/master/discv5/discv5-theory.md#topic-advertisement) with adjustments (ideally upstream)
* [Discv5 topic discovery](https://github.com/ethereum/devp2p/blob/master/discv5/discv5-theory##topic-advertisement) 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](https://github.com/ethereum/devp2p/blob/master/discv5/discv5-theory.md).
`33/WAKU2-DISCV5` fully inherits the [discv5 semantics](https://github.com/ethereum/devp2p/blob/master/discv5/discv5-theory).
Before announcing their address via Waku2 discv5, nodes SHOULD check if this address is publicly reachable.
Nodes MAY use the [libp2p AutoNAT protocol](https://github.com/libp2p/specs/blob/master/autonat/README.md) to perform that check.
Nodes MAY use the [libp2p AutoNAT protocol](https://github.com/libp2p/specs/blob/master/autonat/README) 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](https://github.com/ethereum/devp2p/blob/master/discv5/discv5-wire.md) except for the following differences
`33/WAKU2-DISCV5` inherits the [discv5 wire protocol](https://github.com/ethereum/devp2p/blob/master/discv5/discv5-wire) except for the following differences
## WAKU2-Specific `protocol-id`
@@ -157,17 +156,17 @@ Properly protecting against eclipse attacks is challenging and raises research q
## References
1. [10/WAKU2](../10/waku2.md)
1. [11/WAKU2-RELAY](../11/relay.md)
1. [`WAKU2-ENR`](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/enr.md)
1. [Node Discovery Protocol v5 (`discv5`)](https://github.com/ethereum/devp2p/blob/master/discv5/discv5.md)
1. [`discv5` semantics](https://github.com/ethereum/devp2p/blob/master/discv5/discv5-theory.md).
1. [`discv5` wire protocol](https://github.com/ethereum/devp2p/blob/master/discv5/discv5-wire.md)
1. [`discv5` topic discovery](https://github.com/ethereum/devp2p/blob/master/discv5/discv5-theory.md#topic-advertisement)
1. [10/WAKU2](../10/waku2)
1. [11/WAKU2-RELAY](../11/relay)
1. [`WAKU2-ENR`](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/enr)
1. [Node Discovery Protocol v5 (`discv5`)](https://github.com/ethereum/devp2p/blob/master/discv5/discv5)
1. [`discv5` semantics](https://github.com/ethereum/devp2p/blob/master/discv5/discv5-theory).
1. [`discv5` wire protocol](https://github.com/ethereum/devp2p/blob/master/discv5/discv5-wire)
1. [`discv5` topic discovery](https://github.com/ethereum/devp2p/blob/master/discv5/discv5-theory##topic-advertisement)
1. [Waku DNS discovery](https://rfc.vac.dev/spec/10/#discovery-domain)
1. [libp2p AutoNAT protocol](https://github.com/libp2p/specs/blob/master/autonat/README.md)
1. [libp2p AutoNAT protocol](https://github.com/libp2p/specs/blob/master/autonat/README)
1. [`EIP-1459`](https://eips.ethereum.org/EIPS/eip-1459)
1. [`GossipSub`](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/README.md)
1. [`GossipSub`](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/README)
1. [Waku discv5 roadmap discussion](https://forum.vac.dev/t/waku-v2-discv5-roadmap-discussion/121)
1. [discovery efficiency estimation](https://forum.vac.dev/t/waku-v2-discv5-roadmap-discussion/121/8)
1. [implementation: Nim](https://github.com/kaiserd/nim-eth/blob/add-selectable-protocol-id-static/eth/p2p/discoveryv5/encoding.nim)

27
waku/standards/core/bindings-api.md → waku/standards/core/36/bindings-api.md
View File

@@ -5,7 +5,6 @@ status: draft
editor: Richard Ramos \<richard@status.im\>
contributors:
- Franck Royer \<franck@status.im\>
sidebar_position: 36
---
- Status: draft
- Editor: Richard Ramos \<richard@status.im\>
@@ -700,7 +699,7 @@ This list has this format:
### `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](../../../informational/23/topics.md).
Create a content topic string according to [RFC 23](../../../informational/23/topics).
**Parameters**
@@ -713,14 +712,14 @@ Create a content topic string according to [RFC 23](../../../informational/23/to
**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](../../../informational/23/topics.md): `/{application-name}/{version-of-the-application}/{content-topic-name}/{encoding}`
- 0 - The operation was completed successfuly. `onOkCb` will receive the content topic formatted according to [RFC 23](../../../informational/23/topics): `/{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
### `extern int waku_pubsub_topic(char* name, char* encoding, WakuCallBack onOkCb)`
Create a pubsub topic string according to [RFC 23](../../../informational/23/topics.md).
Create a pubsub topic string according to [RFC 23](../../../informational/23/topics).
**Parameters**
@@ -731,13 +730,13 @@ Create a pubsub topic string according to [RFC 23](../../../informational/23/top
**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](../../../informational/23/topics.md): `/waku/2/{topic-name}/{encoding}`
- 0 - The operation was completed successfuly. `onOkCb` will get populated with a pubsub topic formatted according to [RFC 23](../../../informational/23/topics): `/waku/2/{topic-name}/{encoding}`
- 1 - The operation failed for any reason.
- 2 - The function is missing the `onOkCb` callback
### `extern int waku_default_pubsub_topic(WakuCallBack onOkCb)`
Returns the default pubsub topic used for exchanging waku messages defined in [RFC 10](../10/waku2.md).
Returns the default pubsub topic used for exchanging waku messages defined in [RFC 10](../10/waku2).
**Parameters**
1. `WakuCallBack onOkCb`: callback to be executed if the function is succesful
@@ -755,7 +754,7 @@ Publish a message using Waku Relay.
**Parameters**
1. `char* messageJson`: JSON string containing the [Waku Message](../14/message.md) as [`JsonMessage`](#jsonmessage-type).
1. `char* messageJson`: JSON string containing the [Waku Message](../14/message) as [`JsonMessage`](#jsonmessage-type).
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.
@@ -1016,7 +1015,7 @@ Sends a requests to a service node (or all service nodes) to stop pushing messag
### `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`](https://github.com/libp2p/specs/blob/master/pubsub/README.md#the-topic-descriptor).
Creates a subscription in a lightnode for messages that matches a content filter and optionally a [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README##the-topic-descriptor).
**Parameters**
@@ -1066,7 +1065,7 @@ For Example:
### `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`](https://github.com/libp2p/specs/blob/master/pubsub/README.md#the-topic-descriptor).
Removes subscriptions in a light node matching a content filter and, optionally, a [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README##the-topic-descriptor).
**Parameters**
@@ -1092,7 +1091,7 @@ Publish a message using Waku Lightpush.
**Parameters**
1. `char* messageJson`: JSON string containing the [Waku Message](../14/message.md) as [`JsonMessage`](#jsonmessage-type).
1. `char* messageJson`: JSON string containing the [Waku Message](../14/message) as [`JsonMessage`](#jsonmessage-type).
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.
@@ -1180,7 +1179,7 @@ Encrypt a message using symmetric encryption and optionally sign the message
**Parameters**
1. `char* messageJson`: JSON string containing the [Waku Message](../14/message.md) as [`JsonMessage`](#jsonmessage-type).
1. `char* messageJson`: JSON string containing the [Waku Message](../14/message) as [`JsonMessage`](#jsonmessage-type).
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
@@ -1201,7 +1200,7 @@ Encrypt a message using asymmetric encryption and optionally sign the message
**Parameters**
1. `char* messageJson`: JSON string containing the [Waku Message](../14/message.md) as [`JsonMessage`](#jsonmessage-type).
1. `char* messageJson`: JSON string containing the [Waku Message](../14/message) as [`JsonMessage`](#jsonmessage-type).
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
@@ -1224,7 +1223,7 @@ Decrypt a message using a symmetric key
**Parameters**
1. `char* messageJson`: JSON string containing the [Waku Message](../14/message.md) as [`JsonMessage`](#jsonmessage-type).
1. `char* messageJson`: JSON string containing the [Waku Message](../14/message) as [`JsonMessage`](#jsonmessage-type).
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
@@ -1252,7 +1251,7 @@ Decrypt a message using a secp256k1 private key
**Parameters**
1. `char* messageJson`: JSON string containing the [Waku Message](../14/message.md) as [`JsonMessage`](#jsonmessage-type).
1. `char* messageJson`: JSON string containing the [Waku Message](../14/message) as [`JsonMessage`](#jsonmessage-type).
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

5
waku/standards/core/metadata.md → waku/standards/core/66/metadata.md
View File

@@ -4,13 +4,12 @@ name: Waku Metadata Protocol
status: draft
editor: Alvaro Revuelta \<alrevuelta@status.im\>
contributors:
sidebar_position: 66
---
- Status: draft
- Editor: Alvaro Revuelta \<alrevuelta@status.im\>
## Abstract
This specification describes the metadata that can be associated with a [10/WAKU2](../10/waku2.md) node.
This specification describes the metadata that can be associated with a [10/WAKU2](../10/waku2) node.
## Metadata Protocol
@@ -50,4 +49,4 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public
## References
- [10/WAKU2](../10/waku2.md)
- [10/WAKU2](../10/waku2)

279
waku/standards/core/filter.md
View File

@@ -1,279 +0,0 @@
---
title: 12/WAKU2-FILTER
name: Waku v2 Filter
status: draft
version: 01
editor: Hanno Cornelius \<hanno@status.im\>
contributors:
- Dean Eigenmann \<dean@status.im\>
- Oskar Thorén \<oskar@status.im\>
- Sanaz Taheri \<sanaz@status.im\>
- Ebube Ud \<ebube@status.im\>
sidebar_position: 12
---
- Status: draft
- Editor: Hanno Cornelius \<hanno@status.im\>
- Contributors::
- Dean Eigenmann \<dean@status.im\>
- Oskar Thorén \<oskar@status.im\>
- Sanaz Taheri \<sanaz@status.im\>
- Ebube Ud \<ebube@status.im\>
- Contributors::
previous versions: [00](./previous-versions00)
---
`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 identifiers**:
- _filter-subscribe_: `/vac/waku/filter-subscribe/2.0.0-beta1`
- _filter-push_: `/vac/waku/filter-push/2.0.0-beta1`
Content filtering is a way to do [message-based
filtering](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern#Message_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](#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
```protobuf
syntax = "proto3";
// 12/WAKU2-FILTER rfc: https://rfc.vac.dev/spec/12/
package waku.filter.v2;
// 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.
An incentive mechanism is currently planned but underspecified.
#### 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
In return to any `FilterSubscribeRequest`,
a filter service node SHOULD respond with 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 `WakuMessage` 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 following filter subscribe types are defined:
##### SUBSCRIBER_PING
A filter client that sends a `FilterSubscribeRequest` with `filter_subscribe_type` set to `SUBSCRIBER_PING`
requests that the 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 code if it has any active subscriptions for this client
or an error 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 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 code if it successfully honored this request
or an error code if not.
The filter service node SHOULD respond with an error code and discard the request
if the subscribe request 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 code if it successfully honored this request
or an error code if not.
The filter service node SHOULD respond with an error 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 code if it successfully honored this request
or an error 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 [`WakuMessage`s](../14/message.md) are likely to come from [`11/WAKU2-RELAY`](../11/relay.md),
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.
We consider `1 minute` to be 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.
---
## Future Work
<!-- Alternative title: Filter-subscriber unlinkability -->
**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
<!-- TODO: if nodes have to disclose their PeerIDs (e.g., for authentication purposes) when connecting to other nodes in the WakuFilter protocol, then Tor does not preserve anonymity since it only helps in hiding the IP. So, the PeerId usage in switches must be investigated further. Depending on how PeerId is used, one may be able to link between a subscriber and its content filter despite hiding the IP address-->
.
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](https://link.springer.com/referenceworkentry/10.1007%2F978-1-4419-5906-5_9#:~:text=Oblivious%20transfer%20(OT)%20is%20a,information%20the%20receiver%20actually%20obtains.) and one-way Private Set Intersections (PSI).
## Changelog
### Next
- Added initial threat model and security analysis.
### 2.0.0-beta2
Initial draft version. Released [2020-10-28](https://github.com/vacp2p/specs/commit/5ceeb88cee7b918bb58f38e7c4de5d581ff31e68)
- Fix: Ensure contentFilter is a repeated field, on implementation
- Change: Add ability to unsubscribe from filters. Make `subscribe` an explicit boolean indication. Edit protobuf field order to be consistent with libp2p.
### 2.0.0-beta1
Initial draft version. Released [2020-10-05](https://github.com/vacp2p/specs/commit/31857c7434fa17efc00e3cd648d90448797d107b)
## Copyright
Copyright and related rights waived via
[CC0](https://creativecommons.org/publicdomain/zero/1.0/).
## References
- [message-based
filtering](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern#Message_filtering)
- [`WakuMessage`s](../14/message.md)
- [`11/WAKU2-RELAY`](../11/relay.md)
- [Oblivious Transfers](https://link.springer.com/referenceworkentry/10.1007%2F978-1-4419-5906-5_9#:~:text=Oblivious%20transfer%20(OT)%20is%20a,information%20the%20receiver%20actually%20obtains)
- previous versions: [00](./previous-versions00)
1. [Message Filtering (Wikipedia)](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern#Message_filtering)
2. [Libp2p PubSub spec - topic validation](https://github.com/libp2p/specs/tree/master/pubsub#topic-validation)

21
waku/standards/legacy/waku1.md → waku/standards/legacy/6/waku1.md
View File

@@ -8,7 +8,6 @@ contributors:
- Andrea Maria Piana \<andreap@status.im\>
- Dean Eigenmann \<dean@status.im\>
- Kim De Mey \<kimdemey@status.im\>
sidebar_position: 6
---
- Status: stable
- Editor: Oskar Thorén \<oskarth@titanproxy.com\>
@@ -43,7 +42,7 @@ This protocol needs to advertise the `waku/1` [capability](https://ethereum.gitb
### Gossip based routing
In Whisper, envelopes are gossiped between peers. Whisper is a form of rumor-mongering protocol that works by flooding to its connected peers based on some factors. Envelopes are eligible for retransmission until their TTL expires. A node SHOULD relay envelopes to all connected nodes if an envelope matches their PoW and bloom filter settings. If a node works in light mode, it MAY choose not to forward envelopes. A node MUST NOT send expired envelopes, unless the envelopes are sent as a [8/WAKU-MAIL](../8/mail.md) response. A node SHOULD NOT send an envelope to a peer that it has already sent before.
In Whisper, envelopes are gossiped between peers. Whisper is a form of rumor-mongering protocol that works by flooding to its connected peers based on some factors. Envelopes are eligible for retransmission until their TTL expires. A node SHOULD relay envelopes to all connected nodes if an envelope matches their PoW and bloom filter settings. If a node works in light mode, it MAY choose not to forward envelopes. A node MUST NOT send expired envelopes, unless the envelopes are sent as a [8/WAKU-MAIL](../8/mail) response. A node SHOULD NOT send an envelope to a peer that it has already sent before.
### Maximum Packet Size
@@ -350,7 +349,7 @@ The drawback of sending message confirmations is that it increases the noise in
#### P2P Request
This packet is used for sending Dapp-level peer-to-peer requests, e.g. Waku Mail Client requesting historic (expired) envelopes from the [Waku Mail Server](../8/mail.md).
This packet is used for sending Dapp-level peer-to-peer requests, e.g. Waku Mail Client requesting historic (expired) envelopes from the [Waku Mail Server](../8/mail).
#### P2P Message
@@ -360,7 +359,7 @@ This packet is used for sending the peer-to-peer envelopes, which are not suppos
This packet is used to indicate that all envelopes, requested earlier with a P2P Request packet (`0x7E`), have been sent via one or more P2P Message packets (`0x7F`).
The content of the packet is explained in the [Waku Mail Server](../8/mail.md) specification.
The content of the packet is explained in the [Waku Mail Server](../8/mail) specification.
### Payload Encryption
@@ -380,7 +379,7 @@ Packet codes `0x7E` and `0x7F` may be used to implement Waku Mail Server and Cli
Waku supports multiple capabilities. These include light node, rate limiting and bridging of traffic. Here we list these capabilities, how they are identified, what properties they have and what invariants they must maintain.
Additionally there is the capability of a mailserver which is documented in its on [specification](../8/mail.md).
Additionally there is the capability of a mailserver which is documented in its on [specification](../8/mail).
### Light node
@@ -459,7 +458,7 @@ It is desirable to have a strategy for maintaining forward compatibility between
## Appendix A: Security considerations
There are several security considerations to take into account when running Waku. Chief among them are: scalability, DDoS-resistance and privacy. These also vary depending on what capabilities are used. The security considerations for extra capabilities such as [mailservers](../8/mail.md#security-considerations) can be found in their respective specifications.
There are several security considerations to take into account when running Waku. Chief among them are: scalability, DDoS-resistance and privacy. These also vary depending on what capabilities are used. The security considerations for extra capabilities such as [mailservers](../8/mail##security-considerations) can be found in their respective specifications.
### Scalability and UX
@@ -519,8 +518,8 @@ By default Devp2p runs on port `30303`, which is not commonly used for any other
| Client | Spec supported | Details |
|--------|----------------|---------|
| **Status-go** | 0.5 | [details](https://github.com/status-im/status-go/blob/develop/WAKU.md) |
| **Nim-waku** | 1.0 | [details](https://github.com/status-im/nim-waku/blob/master/README.md) |
| **Status-go** | 0.5 | [details](https://github.com/status-im/status-go/blob/develop/WAKU) |
| **Nim-waku** | 1.0 | [details](https://github.com/status-im/nim-waku/blob/master/README) |
### Recommendations for clients
@@ -600,7 +599,7 @@ Released [February 13, 2020](https://github.com/vacp2p/specs/commit/73138d6ba954
### Version 0.2
Released [December 10, 2019](https://github.com/vacp2p/specs/blob/waku-0.2.0/waku.md).
Released [December 10, 2019](https://github.com/vacp2p/specs/blob/waku-0.2.0/waku).
- General style improvements.
- Fix ABNF grammar.
@@ -618,7 +617,7 @@ Released [December 10, 2019](https://github.com/vacp2p/specs/blob/waku-0.2.0/wak
### Version 0.1
Initial version. Released [November 21, 2019](https://github.com/vacp2p/specs/blob/b59b9247f2ac1bf45c75bd3227a2e5dd87b6d7b0/waku.md).
Initial version. Released [November 21, 2019](https://github.com/vacp2p/specs/blob/b59b9247f2ac1bf45c75bd3227a2e5dd87b6d7b0/waku).
### Differences between shh/6 and waku/1
@@ -639,4 +638,4 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public
## Footnotes
[^1]: Felix Lange et al. [The RLPx Transport Protocol](https://github.com/ethereum/devp2p/blob/master/rlpx.md). Ethereum.
[^1]: Felix Lange et al. [The RLPx Transport Protocol](https://github.com/ethereum/devp2p/blob/master/rlpx). Ethereum.

3
waku/standards/legacy/data.md → waku/standards/legacy/7/data.md
View File

@@ -6,7 +6,6 @@ editor: Oskar Thorén \<oskarth@titanproxy.com\>
contributors:
- Dean Eigenmann \<dean@status.im\>
- Kim De Mey \<kimdemey@status.im\>
sidebar_position: 7
---
- Status: stable
- Editor: Oskar Thorén \<oskarth@titanproxy.com\>
@@ -14,7 +13,7 @@ sidebar_position: 7
- Dean Eigenmann \<dean@status.im\>
- Kim De Mey \<kimdemey@status.im\>
This specification describes the encryption, decryption and signing of the content in the [data field used in Waku](../6/waku1.md/#abnf-specification).
This specification describes the encryption, decryption and signing of the content in the [data field used in Waku](../6/waku1#abnf-specification).
## Specification

5
waku/standards/legacy/mail.md → waku/standards/legacy/8/mail.md
View File

@@ -7,7 +7,6 @@ contributors:
- Adam Babik \<adam@status.im\>
- Dean Eigenmann \<dean@status.im\>
- Oskar Thorén \<oskarth@titanproxy.com\>
sidebar_position: 8
---
- Status: stable
- Editor: Andrea Maria Piana \<andreap@status.im\>
@@ -106,7 +105,7 @@ A mailserver client fetches archival envelopes from a mailserver through a direc
In this direct connection, the client discloses its IP/ID as well as the topics/ bloom filter it is interested in to the mailserver.
The collection of such information allows the mailserver to link clients' IP/IDs to their topic interests and build a profile for each client over time.
As such, the mailserver client has to trust the mailserver with this level of information.
A similar concern exists for the light nodes and their direct peers which is discussed in the security considerations of [6/WAKU1](../6/waku1.md).
A similar concern exists for the light nodes and their direct peers which is discussed in the security considerations of [6/WAKU1](../6/waku1).
**Mailserver trusted connection:**
@@ -118,7 +117,7 @@ A mailserver has a direct TCP connection, which means they are trusted to send t
| :--------------------------------------------------------------------------------------------: | ------- |
| [1.0.0](https://github.com/vacp2p/specs/commit/bc7e75ebb2e45d2cbf6ab27352c113e666df37c8) | marked stable as it is in use. |
| 0.2.0 | Add topic interest to reduce bandwidth usage |
| [0.1.0](https://github.com/vacp2p/specs/blob/06d4c736c920526472a507e5d842212843a112ed/wms.md) | Initial Release |
| [0.1.0](https://github.com/vacp2p/specs/blob/06d4c736c920526472a507e5d842212843a112ed/wms) | Initial Release |
### Difference between wms 0.1 and wms 0.2

3
waku/standards/legacy/rpc.md → waku/standards/legacy/9/rpc.md
View File

@@ -6,7 +6,6 @@ editor: Andrea Maria Piana \<andreap@status.im\>
contributors:
- Dean Eigenmann \<dean@status.im\>
- Oskar Thorén \<oskarth@titanproxy.com\>
sidebar_position: 9
---
- Status: stable
- Editor: Andrea Maria Piana \<andreap@status.im\>
@@ -51,7 +50,7 @@ In this section you will find objects used throughout the JSON RPC API.
#### Message
The message object represents a Waku message. Below you will find the description of the attributes contained in the message object. A message is the decrypted payload and padding of an [envelope](../7/data.md) along with all of its metadata and other extra information such as the hash.
The message object represents a Waku message. Below you will find the description of the attributes contained in the message object. A message is the decrypted payload and padding of an [envelope](../7/data) along with all of its metadata and other extra information such as the hash.
| Field | Type | Description |
| ----: | :--: | ----------- |