acid-info
/
rnd-rfc.vac.dev
mirror of https://github.com/acid-info/rnd-rfc.vac.dev.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

feat: update folder structure

This commit is contained in:
jinhojang6 2024-03-28 01:01:17 +09:00
parent f051721df3
commit 2a91b48efd
58 changed files with 549 additions and 532 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
fetch-content.js
View File

@ -43,7 +43,7 @@ async function fetchFromGitHub(url, callback) {
res.on('end', () => {
const parsedData = JSON.parse(data)
console.log('parsedData:', parsedData)
// console.log('parsedData:', parsedData)
callback(null, parsedData)
})
},
@ -70,7 +70,20 @@ async function fetchDirectoryContents(dirUrl, basePath, prefixToRemove) {
new RegExp(`^${prefixToRemove}`),
'',
)
const filePath = path.join(basePath, relativePath)
function adjustPathForMarkdown(filePath) {
const parts = filePath.split('/')
if (parts?.length === 1) return filePath
if (parts[parts.length - 1].endsWith('.md')) {
parts.splice(parts.length - 2, 1)
}
return parts.join('/')
}
const filePath = path.join(basePath, adjustPathForMarkdown(relativePath))
if (file.type === 'file') {
await downloadAndSaveFile(file.download_url, filePath)
@ -85,11 +98,14 @@ function parseSlugFromFrontmatter(content) {
const frontmatterMatch = content.match(/---\s*\n([\s\S]*?)\n---/)
if (frontmatterMatch) {
const frontmatterContent = frontmatterMatch[1]
const slugMatch = frontmatterContent.match(/^slug:\s*(\d+)/m)
if (slugMatch) {
return parseInt(slugMatch[1], 10)
function extractNumberFromTitle(content) {
const parts = content.split('/')
return parseInt(parts[0].split(' ')[1], 10)
}
const number = extractNumberFromTitle(frontmatterContent)
return number
}
return 1 // Return null if not found
}
@ -109,6 +125,12 @@ async function downloadAndSaveFile(url, filePath) {
const fileExtension = path.extname(filePath)
function updateMarkdownImagePath(content, number) {
const regex = /(!\[.*?\]\(\.\/)images/g
return content.replace(regex, `$1${number}/images`)
}
if (fileExtension === '.md' || fileExtension === '.mdx') {
// Remove 'tags' line from frontmatter because the format is wrong
content = content.replace(/tags:.*\n?/, '')
@ -129,6 +151,8 @@ async function downloadAndSaveFile(url, filePath) {
// // parse sidebarPosition from the slug in the frontmatter
const sidebarPosition = parseSlugFromFrontmatter(content) || 1
content = updateMarkdownImagePath(content, sidebarPosition)
// Insert sidebar_position at the end of frontmatter if it doesn't exist
if (
/^---\s*[\s\S]+?---/.test(content) &&
@ -143,10 +167,10 @@ async function downloadAndSaveFile(url, filePath) {
fs.writeFile(fullFilePath, content, err => {
if (err) {
console.error('Error saving file:', err.message)
// console.error('Error saving file:', err.message)
return
}
console.log('Downloaded and saved:', filePath)
// console.log('Downloaded and saved:', filePath)
})
})
})
@ -163,6 +187,6 @@ directoriesToSync.forEach(dirName => {
const prefixToRemove = dirName + '/'
fetchDirectoryContents(baseUrl, baseSavePath, prefixToRemove).then(() => {
console.log(`Synced ${dirName}`)
// console.log(`Synced ${dirName}`)
})
})

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

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

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

@ -11,7 +11,7 @@ contributors:
- Corey Petty \<corey@status.im\>
- Oskar Thorén \<oskarth@titanproxy.com\>
- Dean Eigenmann \<dean@status.im\>
sidebar_position: 1
sidebar_position: 55
---
## Abstract
@ -39,7 +39,7 @@ 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/waku-RFC/standards/core/noise.md)
2. [WAKU2-NOISE](https://github.com/waku-org/specs/blob/master/standards/application/noise.md)
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.
@ -66,7 +66,7 @@ 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)
2. [WAKU2-NOISE](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/noise.md), the session management is described in [WAKU2-NOISE-SESSIONS](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/noise-sessions/noise-sessions.md)
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)
## Negotiation of a 1:1 chat amongst multiple participants (group chat)
@ -202,7 +202,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/waku-RFC/standards/core/noise.md)
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)
## Copyright
@ -211,10 +211,10 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public
## References
1. [53/WAKU2-X3DH](../../waku/standards/application/53/x3dh.md)
2. [35/WAKU2-NOISE](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/noise.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. [37/WAKU2-NOISE-SESSIONS](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/noise-sessions/noise-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)
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)

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

@ -9,7 +9,7 @@ contributors:
- Corey Petty \<corey@status.im\>
- Oskar Thorén \<oskarth@titanproxy.com\>
- Samuel Hawksby-Robinson \<samuel@status.im\>
sidebar_position: 1
sidebar_position: 65
---
## Abstract

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

@ -7,7 +7,7 @@ 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: 1
sidebar_position: 56
---
## Abstract

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

@ -8,7 +8,7 @@ editor: r4bbit \<r4bbit@status.im\>
contributors:
- Sanaz Taheri \<sanaz@status.im\>
- John Lea \<john@status.im\>
sidebar_position: 1
sidebar_position: 61
---
## Abstract
@ -321,7 +321,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-PAYLOAD](../62/payload.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.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)).
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.
@ -389,4 +389,4 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public
* [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-PAYLOAD](../62/payload.md)
* [62/STATUS-PAYLOADS](../62/payloads.md)

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

@ -4,7 +4,7 @@ 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: 1
sidebar_position: 24
---
## Abstract

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

@ -4,7 +4,7 @@ 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: 1
sidebar_position: 28
---
## Abstract

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

@ -7,7 +7,7 @@ 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: 1
sidebar_position: 63
---
## Terminology

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

@ -8,7 +8,7 @@ contributors:
- Andrea Maria Piana \<andreap@status.im\>
- Oskar Thoren \<oskarth@titanproxy.com\>
- Samuel Hawksby-Robinson \<samuel@status.im\>
sidebar_position: 1
sidebar_position: 62
---
## Abstract

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

@ -7,7 +7,7 @@ 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: 1
sidebar_position: 71
---
## Abstract
@ -62,11 +62,11 @@ The party releasing the app MUST run its own [gorush](https://github.com/applebo
### Push Notification Server Flow
#### Registration Process:
![registration](./images/registration.png)
![registration](./71/images/registration.png)
#### Sending and Receiving Notification Process:
![notification](./images/notification.png)
![notification](./71/images/notification.png)
### Registering Client
@ -406,7 +406,7 @@ 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.md) with type set to<EFBFBD><EFBFBD>`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.

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

@ -7,7 +7,7 @@ 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: 1
sidebar_position: 57
---
## Abstract

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

11
vac/README.md
View File

@ -1,9 +1,4 @@
# Vac RFCs
# Vac Raw Specifications
Vac builds public good protocols for the decentralise web.
Vac acts as a custodian for the protocols that live in the RFC-Index repository.
With the goal of widespread adoption,
Vac will make sure the protocols adhere to the set of principles,
including but not limited to liberty, security, privacy, decentralisation, and inclusivity.
To learn more, visit [Vac Research](https://vac.dev/)
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).

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

@ -104,7 +104,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](./images/lifecycle.png)
![Lifecycle diagram](./1/images/lifecycle.png)
### Raw Specifications

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

@ -5,7 +5,7 @@ status: raw
category: Standards Track
editor: Ramses Fernandez \<ramses@status.im\>
contributors:
sidebar_position: 1
sidebar_position: 70
---
## Motivation
@ -16,7 +16,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](https://rfc.vac.dev/spec/20/),
Rooted in the existing [model](../../waku/standards/application/20/toy-eth-pm.md),
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/46/gossipsub-tor-push.md → vac/gossipsub-tor-push.md
View File

@ -5,7 +5,7 @@ status: raw
category: Standards Track
editor: Daniel Kaiser \<danielkaiser@status.im\>
contributors:
sidebar_position: 1
sidebar_position: 46
---
## Abstract

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

@ -4,12 +4,12 @@ name: Libp2p Peer Discovery via DNS
status: deleted
editor: Hanno Cornelius \<hanno@status.im\>
contributors:
sidebar_position: 1
sidebar_position: 25
---
`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`](https://rfc.vac.dev/spec/10/) currently specifies use of [`libp2p` peer identities](https://docs.libp2p.io/concepts/peer-id/),
Since [`10/WAKU2`](../../waku/standards/core/10/waku2.md) 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),
@ -126,7 +126,7 @@ Copyright and related rights waived via
# References
1. [`10/WAKU2`](https://rfc.vac.dev/spec/10/)
1. [`10/WAKU2`](../../waku/standards/core/10/waku2.md)
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/)

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

@ -7,7 +7,7 @@ contributors:
- Dean Eigenmann \<dean@status.im\>
- Andrea Maria Piana \<andreap@status.im\>
- Oskar Thorén \<oskarth@titanproxy.com\>
sidebar_position: 1
sidebar_position: 4
---
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.

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

@ -6,7 +6,7 @@ editor: Sanaz Taheri \<sanaz@status.im\>
contributors:
- Dean Eigenmann \<dean@status.im\>
- Oskar Thorén \<oskarth@titanproxy.com\>
sidebar_position: 1
sidebar_position: 2
---
In this specification, we describe a minimum viable protocol for data synchronization inspired by the Bramble Synchronization Protocol[^1]. This protocol is designed to ensure reliable messaging between peers across an unreliable peer-to-peer (P2P) network where they may be unreachable or unresponsive.

4
vac/raw/README.md
View File

@ -1,4 +0,0 @@
# 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).

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

@ -5,7 +5,7 @@ status: draft
editor: Oskar Thorén \<oskarth@titanproxy.com\>
contributors:
- Dean Eigenmann \<dean@status.im\>
sidebar_position: 1
sidebar_position: 3
---
A remote log is a replication of a local log. This means a node can read data that originally came from a node that is offline.

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

@ -5,7 +5,7 @@ status: raw
category:
editor: Aaryamann Challani \<aaryamann@status.im\>
contributors:
sidebar_position: 1
sidebar_position: 48
---
## Abstract

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

@ -9,7 +9,7 @@ contributors:
- Oskar Thorén \<oskarth@titanproxy.com\>
- Onur Kilic \<onurkilic1004@gmail.com\>
- Blagoj Dimovski \<blagoj.dimovski@yandex.com\>
sidebar_position: 1
sidebar_position: 32
---
## Abstract
@ -52,7 +52,7 @@ Depending on the application requirements, the registration can be implemented i
- centralized registrations, by using a central server
- decentralized registrations, by using a smart contract
What is important is that the users' identity commitments (explained in section [User Indetity](#user-identity)) are stored in a Merkle tree,
What is important is that the users' identity commitments (explained in section [User Identity](#user-identity)) are stored in a Merkle tree,
and the users can obtain a Merkle proof proving that they are part of the group.
Also depending on the application requirements,

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

@ -5,7 +5,7 @@ status: raw
editor: Rasul Ibragimov \<curryrasul@gmail.com\>
contributors:
- Lev Soukhanov \<0xdeadfae@gmail.com\>
sidebar_position: 1
sidebar_position: 58
---
## Abstract

9
waku/README.md
View File

@ -1,5 +1,6 @@
## Waku RFCs
## Deprecated RFCs
Waku builds a family of privacy-preserving, censorship-resistant communication protocols for web3 applications.
Contributors can visit [Waku RFCs](https://github.com/waku-org/specs) for new Waku specifications under discussion.
Deprecated specifications are no longer used in Waku products.
This subdirectory is for achrive purpose and
should not be used in production ready implementations.
Visit [Waku RFCs](https://github.com/waku-org/specs) for new Waku specifications under discussion.

6
waku/deprecated/README.md
View File

@ -1,6 +0,0 @@
## Deprecated RFCs
Deprecated specifications are no longer used in Waku products.
This subdirectory is for achrive purpose and
should not be used in production ready implementations.
Visit [Waku RFCs](https://github.com/waku-org/specs) for new Waku specifications under discussion.

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

@ -8,7 +8,7 @@ contributors:
- Andrea Maria Piana \<andreap@status.im\>
- Dean Eigenmann \<dean@status.im\>
- Kim De Mey \<kimdemey@status.im\>
sidebar_position: 1
sidebar_position: 5
---
This specification describes the format of Waku messages within the ÐΞVp2p Wire Protocol. This spec substitutes [EIP-627](https://eips.ethereum.org/EIPS/eip-627). Waku is a fork of the original Whisper protocol that enables better usability for resource restricted devices, such as mostly-offline bandwidth-constrained smartphones. It does this through (a) light node support, (b) historic messages (with a mailserver) (c) expressing topic interest for better bandwidth usage and (d) basic rate limiting.

BIN
waku/informational/30/images/adaptive_protocol_selection.jpg
View File

Binary file not shown.

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

@ -4,7 +4,7 @@ name: Adaptive nodes
status: draft
editor: Oskar Thorén \<oskarth@titanproxy.com\>
contributors:
sidebar_position: 1
sidebar_position: 30
---
This is an informational spec that show cases the concept of adaptive nodes.
@ -13,7 +13,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](./images/adaptive_node_continuum2.png)
![Node types - a continuum](./30/images/adaptive_node_continuum2.png)
### Possible limitations
@ -53,7 +53,7 @@ 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](./images/adaptive_node_protocol_selection2.png)
![Protocol selection](./30/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.
@ -69,11 +69,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](./images/adaptive_node_network_topology_protocols2.png)
![Waku Network visualization](./30/images/adaptive_node_network_topology_protocols2.png)
### Legend
![Waku Network visualization legend](./images/adaptive_node_network_topology_protocols_legend.png)
![Waku Network visualization legend](./30/images/adaptive_node_network_topology_protocols_legend.png)
The dotted box shows what content topics (application-specific) a node is interested in.
@ -91,7 +91,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](./images/adaptive_node_cross_section2.png)
![Node Cross Section](./30/images/adaptive_node_cross_section2.png)
## Copyright

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

@ -4,7 +4,7 @@ name: Waku v2 Client Parameter Configuration Recommendations
status: draft
editor: Hanno Cornelius \<hanno@status.im\>
contributors:
sidebar_position: 1
sidebar_position: 29
---
`29/WAKU2-CONFIG` describes the RECOMMENDED values to assign to configurable parameters for Waku v2 clients.

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

@ -4,7 +4,7 @@ name: Waku v2 Client Peer Management Recommendations
status: draft
editor: Hanno Cornelius \<hanno@status.im\>
contributors:
sidebar_position: 1
sidebar_position: 27
---
`27/WAKU2-PEERS` describes a recommended minimal set of peer storage and peer management features to be implemented by Waku v2 clients.
@ -74,7 +74,7 @@ This requires keeping track of the [last time each peer was disconnected](#track
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.md/#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.
@ -96,4 +96,4 @@ Copyright and related rights waived via
- [`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)
- [libp2p pings](https://docs.libp2p.io/concepts/protocols/#ping)
- [`10/WAKU2` client recommendations](https://rfc.vac.dev/spec/10/#recommendations-for-clients)
- [`10/WAKU2` client recommendations](../../standards/core/10/waku2.md/#recommendations-for-clients)

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

@ -7,7 +7,7 @@ editor: Oskar Thoren \<oskarth@titanproxy.com\>
contributors:
- Hanno Cornelius \<hanno@status.im\>
- Daniel Kaiser \<danielkaiser@status.im\>
sidebar_position: 1
sidebar_position: 23
---
This document outlines recommended usage of topic names in Waku v2.
@ -89,7 +89,7 @@ This is used for content based filtering.
See [14/WAKU2-MESSAGE spec](../../standards/core/14/message.md) 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/14/filter.md) and [13/WAKU2-STORE](../../standards/core/13/store.md) are used.
[12/WAKU2-FILTER](../../standards/core/12/filter.md) and [13/WAKU2-STORE](../../standards/core/13/store.md) 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.
@ -163,7 +163,7 @@ Copyright and related rights waived via
* [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/14/filter.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)

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

@ -5,7 +5,7 @@ status: draft
editor: Franck Royer \<franck@status.im\>
contributors:
- Hanno Cornelius \<hanno@status.im\>
sidebar_position: 1
sidebar_position: 22
---
**Content Topic**: `/toy-chat/2/huilong/proto`.

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

@ -4,17 +4,17 @@ name: Waku v2 Fault-Tolerant Store
status: draft
editor: Sanaz Taheri \<sanaz@status.im\>
contributors:
sidebar_position: 1
sidebar_position: 21
---
The reliability of [13/WAKU2-STORE](../../standards/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.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.
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](../../standards/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.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.
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
@ -23,7 +23,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](../../standards/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.md/#payloads) protobuf message with two fields of `start_time` and `end_time` to signify the time range to be queried.
### Payloads
@ -46,10 +46,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`](../../standards/core/13/store.md/#HistoryResponse) MUST contain historical waku messages whose [`timestamp`](../../standards/core/14/message.md/#Payloads) is larger than or equal to the `start_time`.
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`.
- `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`](../../standards/core/13/store.md/#HistoryResponse) MUST contain historical waku messages whose [`timestamp`](../../standards/core/14/message.md/#Payloads) is less than or equal to the `end_time`.
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`.
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.
@ -61,7 +61,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`](../../standards/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.md/#HistoryResponse) MUST contain historical waku messages that satisfy the indicated `pubsubtopic` AND `contentFilters` AND the time range [`start_time`, `end_time`].
## Copyright
@ -70,5 +70,5 @@ Copyright and related rights waived via
## References
- [13/WAKU2-STORE](../../standards/core/13/store.md)
- [13/WAKU2-STORE](../../core/13/store.md)
- [`timestamp`](../../standards/core/14/message.md/#Payloads)

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

@ -4,13 +4,13 @@ name: Waku Message Payload Encryption
status: draft
editor: Oskar Thoren \<oskarth@titanproxy.com\>
contributors:
sidebar_position: 1
sidebar_position: 26
---
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](../../standards/core/6/waku1.md) and in [10/WAKU2 spec](../../standards/core/10/waku2.md) with [14/WAKU-MESSAGE version 1](../../standards/core/14/message.md/#version1).
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).
This specification effectively replaces [7/WAKU-DATA](../../standards/application/7/DATA.md) as well as [6/WAKU1 Payload encryption](../../standards/core/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.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.
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.
@ -42,9 +42,9 @@ ECIES is using the following cryptosystem:
## Specification
For 6/WAKU1, the `data` field is used in the `waku envelope`, and the field MAY contain the encrypted payload.
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 10/WAKU2, the `payload` field is used in `WakuMessage` and 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.
The fields that are concatenated and encrypted as part of the `data` (Waku v1) / `payload` (Waku v2) field are:
- flags
@ -142,10 +142,10 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public
## References
1. [6/WAKU1](../../standards/core/6/waku1.md)
2. [10/WAKU2 spec](../../standards/core/10/waku2.md)
3. [14/WAKU-MESSAGE version 1](../../standards/core/14/message.md/#version1)
4. [7/WAKU-DATA](../../standards/application/7/DATA.md)
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)
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)
7. [Status 5/SECURE-TRANSPORT](https://specs.status.im/spec/5)

6
waku/standards/application/18/swap.md → waku/standards/application/swap.md
View File

@ -4,7 +4,7 @@ name: Waku SWAP Accounting
status: draft
editor: Oskar Thorén \<oskarth@titanproxy.com\>
contributor: Ebube Ud \<ebube@status.im\>
sidebar_position: 1
sidebar_position: 18
---
## Abstract
@ -141,7 +141,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](../../standards/core/13/store.md)
It SHOULD be done for [13/WAKU2-STORE](../../core/13/store.md)
and it MAY be done for other request/reply protocols.
A client SHOULD log accounting state per peer
@ -173,7 +173,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](../../standards/core/13/store.md)
4. [13/WAKU2-STORE](../../core/13/store.md)
\<!--

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

@ -4,7 +4,7 @@ name: Toy Ethereum Private Message
status: draft
editor: Franck Royer \<franck@status.im\>
contributors:
sidebar_position: 1
sidebar_position: 20
---
**Content Topics**:
@ -45,10 +45,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](../../standards/core/10/waku2.md),
5. Bob SHOULD be able to get `M` using [10/WAKU2 spec](../../core/10/waku2.md),
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](../../standards/application/26/payload.md) Asymmetric Encryption is used for encryption purposes.
8. [Waku Message Version 1](../26/payload.md) Asymmetric Encryption is used for encryption purposes.
## Limitations
@ -154,7 +154,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](../../standards/core/13/store.md)),
Moreover, nim-waku, the reference implementation of [13/WAKU2-STORE](../../core/13/store.md),
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.
@ -201,10 +201,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](../../standards/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.md), 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](../../standards/application/26/payload.md/#asymmetric).
as per [26/WAKU-PAYLOAD Asymmetric Encryption specs](../26/payload.md/#asymmetric).
Alice SHOULD now publish this message on the Private Message content topic.
@ -213,12 +213,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](../../standards/core/10/waku2.md)
- [Waku Message Version 1](../../standards/application/26/payload.md)
- [10/WAKU2 spec](../../core/10/waku2.md)
- [Waku Message Version 1](../26/payload.md)
- [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](../../standards/core/13/store.md))
- [13/WAKU2-STORE](../../core/13/store.md)
- [The Graph](https://thegraph.com/)

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

@ -10,7 +10,7 @@ contributors:
- Corey Petty \<corey@status.im\>
- Oskar Thorén \<oskarth@titanproxy.com\>
- Dean Eigenmann \<dean@status.im\>
sidebar_position: 1
sidebar_position: 54
---
## Abstract
@ -18,7 +18,7 @@ sidebar_position: 1
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](../../standards/application/53/X3DH.md) specifies the Waku `X3DH` protocol for end-to-end encryption.
[53/WAKU2-X3DH](../53/x3dh.md) 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
@ -145,7 +145,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](../../standards/application/53/X3DH.md).
1. Inherits all security considerations from [53/WAKU2-X3DH](../53/x3dh.md).
### Recommendations
@ -158,6 +158,6 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public
## References
1. [53/WAKU2-X3DH](../../standards/application/53/X3DH.md)
1. [53/WAKU2-X3DH](../53/x3dh.md)
2. [Signal's Sesame Algorithm](https://signal.org/docs/specifications/sesame/)

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

@ -10,7 +10,7 @@ contributors:
- Corey Petty \<corey@status.im\>
- Oskar Thorén \<oskarth@titanproxy.com\>
- Dean Eigenmann \<dean@status.im\>
sidebar_position: 1
sidebar_position: 53
---
## Abstract
@ -53,7 +53,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](../../standards/core/10/waku2.md) subsequently encrypts the message payload, using symmetric key encryption.
[The Waku v2 protocol](../../core/10/waku2.md) 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.
@ -229,7 +229,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](../../standards/core/10/waku2.md).
2. Inherits the security considerations of the [Waku v2 protocol](../../core/10/waku2.md).
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.
@ -248,7 +248,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](../../standards/core/10/waku2.md)
- [The Waku v2 protocol](../../core/10/waku2.md)
- [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)

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

@ -2,27 +2,22 @@
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\>
- Oskar Thorén \<oskarth@titanproxy.com\>
- Sanaz Taheri \<sanaz@status.im\>
- Ebube Ud \<ebube@status.im\>
sidebar_position: 1
sidebar_position: 12
---
previous versions: [00](./previous-versions00)
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 identifiers**:
- _filter-subscribe_: `/vac/waku/filter-subscribe/2.0.0-beta1`
- _filter-push_: `/vac/waku/filter-push/2.0.0-beta1`
**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).
@ -67,164 +62,80 @@ The following are not considered as part of the adversarial model:
### Protobuf
```protobuf
syntax = "proto3";
message FilterRequest {
bool subscribe = 1;
string topic = 2;
repeated ContentFilter contentFilters = 3;
// 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;
message ContentFilter {
string contentTopic = 1;
}
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;
repeated WakuMessage messages = 1;
}
message FilterRPC {
string requestId = 1;
FilterRequest request = 2;
MessagePush push = 3;
}
```
### Filter-Subscribe
#### FilterRPC
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.
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.
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.
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.
#### Filter Subscribe Request
#### FilterRequest
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 `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'.
#### Filter Subscribe Response
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.
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.
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.
#### Filter matching
The filter matches when content filter and, optionally, a topic is matched.
Content filter is matched when a `WakuMessage` `contentTopic` field is the same.
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`.
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.
#### Filter Subscribe Types
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.
The following filter subscribe types are defined:
#### MessagePush
##### SUBSCRIBER_PING
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.
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.
A filter node MUST NOT send a push message for messages that have not been
requested via a FilterRequest.
##### 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.
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
# 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--\>.
@ -254,13 +165,6 @@ 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.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)

170
waku/standards/core/12/previous-versions00/filter.md
View File

@ -1,170 +0,0 @@
---
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\>
sidebar_position: 1
---
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.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.
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)

BIN
waku/standards/core/17/images/rln-relay.png
View File

Binary file not shown.

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

@ -5,7 +5,7 @@ status: draft
editor: Richard Ramos \<richard@status.im\>
contributors:
- Franck Royer \<franck@status.im\>
sidebar_position: 1
sidebar_position: 36
---
# Introduction
@ -696,7 +696,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](https://rfc.vac.dev/spec/23/).
Create a content topic string according to [RFC 23](../../../informational/23/topics.md).
**Parameters**
@ -709,14 +709,14 @@ Create a content topic string according to [RFC 23](https://rfc.vac.dev/spec/23/
**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](https://rfc.vac.dev/spec/23/): `/{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.md): `/{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](https://rfc.vac.dev/spec/23/).
Create a pubsub topic string according to [RFC 23](../../../informational/23/topics.md).
**Parameters**
@ -727,13 +727,13 @@ Create a pubsub topic string according to [RFC 23](https://rfc.vac.dev/spec/23/)
**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](https://rfc.vac.dev/spec/23/): `/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.md): `/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](https://rfc.vac.dev/spec/10/).
Returns the default pubsub topic used for exchanging waku messages defined in [RFC 10](../10/waku2.md).
**Parameters**
1. `WakuCallBack onOkCb`: callback to be executed if the function is succesful
@ -751,7 +751,7 @@ Publish a message using Waku Relay.
**Parameters**
1. `char* messageJson`: JSON string containing the [Waku Message](https://rfc.vac.dev/spec/14/) as [`JsonMessage`](#jsonmessage-type).
1. `char* messageJson`: JSON string containing the [Waku Message](../14/message.md) 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.
@ -1088,7 +1088,7 @@ Publish a message using Waku Lightpush.
**Parameters**
1. `char* messageJson`: JSON string containing the [Waku Message](https://rfc.vac.dev/spec/14/) as [`JsonMessage`](#jsonmessage-type).
1. `char* messageJson`: JSON string containing the [Waku Message](../14/message.md) 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.
@ -1176,7 +1176,7 @@ Encrypt a message using symmetric encryption and optionally sign the message
**Parameters**
1. `char* messageJson`: JSON string containing the [Waku Message](https://rfc.vac.dev/spec/14/) as [`JsonMessage`](#jsonmessage-type).
1. `char* messageJson`: JSON string containing the [Waku Message](../14/message.md) 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
@ -1197,7 +1197,7 @@ Encrypt a message using asymmetric encryption and optionally sign the message
**Parameters**
1. `char* messageJson`: JSON string containing the [Waku Message](https://rfc.vac.dev/spec/14/) as [`JsonMessage`](#jsonmessage-type).
1. `char* messageJson`: JSON string containing the [Waku Message](../14/message.md) 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
@ -1220,7 +1220,7 @@ Decrypt a message using a symmetric key
**Parameters**
1. `char* messageJson`: JSON string containing the [Waku Message](https://rfc.vac.dev/spec/14/) as [`JsonMessage`](#jsonmessage-type).
1. `char* messageJson`: JSON string containing the [Waku Message](../14/message.md) 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
@ -1248,7 +1248,7 @@ Decrypt a message using a secp256k1 private key
**Parameters**
1. `char* messageJson`: JSON string containing the [Waku Message](https://rfc.vac.dev/spec/14/) as [`JsonMessage`](#jsonmessage-type).
1. `char* messageJson`: JSON string containing the [Waku Message](../14/message.md) 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

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

@ -3,7 +3,7 @@ title: 15/WAKU-BRIDGE
name: Waku Bridge
status: draft
editor: Hanno Cornelius \<hanno@status.im\>
sidebar_position: 1
sidebar_position: 15
---
A bridge between Waku v1 and Waku v2.

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

@ -4,7 +4,7 @@ name: Waku v2 Discv5 Ambient Peer Discovery
status: draft
editor: Daniel Kaiser \<danielkaiser@status.im\>
contributors:
sidebar_position: 1
sidebar_position: 33
---
## Abstract
@ -52,7 +52,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 [31/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.md).
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.
@ -157,7 +157,7 @@ Properly protecting against eclipse attacks is challenging and raises research q
1. [10/WAKU2](../10/waku2.md)
1. [11/WAKU2-RELAY](../11/relay.md)
1. [`31/WAKU2-ENR`](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/enr.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)

266
waku/standards/core/filter.md Normal file
View File

@ -0,0 +1,266 @@
---
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
---
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)

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

@ -2,10 +2,11 @@
title: 19/WAKU2-LIGHTPUSH
name: Waku v2 Light Push
status: draft
editor: Oskar Thorén \<oskarth@titanproxy.com\>
editor: Hanno Cornelius \<hanno@status.im\>
contributors:
- Daniel Kaiser \<danielkaiser@status.im\>
sidebar_position: 1
- Oskar Thorén \<oskarth@titanproxy.com\>
sidebar_position: 19
---
**Protocol identifier**: `/vac/waku/lightpush/2.0.0-beta1`
@ -45,13 +46,13 @@ message PushRPC {
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 [44/WAKU2-DANDELION](https://github.com/waku-org/specs/blob/waku-RFC/standards/application/dandelion.md) stem.
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.
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](https://rfc.vac.dev/spec/17/).
This can be done by rate limiting via [17/WAKU2-RLN-RELAY](../17/rln-relay.md).
Note that the above is currently not fully implemented.
@ -62,5 +63,5 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public
## References
* [11/WAKU2-RELAY](../11/relay.md)
* [44/WAKU2-DANDELION](https://github.com/waku-org/specs/blob/waku-RFC/standards/application/dandelion.md)
* [WAKU2-DANDELION](https://github.com/waku-org/specs/blob/waku-RFC/standards/application/dandelion.md)
* [17/WAKU2-RLN-RELAY](../17/rln-relay.md)

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

@ -3,13 +3,14 @@ title: 14/WAKU2-MESSAGE
name: Waku v2 Message
status: draft
category: Standards Track
editor: Oskar Thorén \<oskarth@titanproxy.com\>
editor: Hanno Cornelius \<hanno@status.im\>
contributors:
- Sanaz Taheri \<sanaz@status.im\>
- Aaryamann Challani \<aaryamann@status.im\>
- Lorenzo Delgado \<lorenzo@status.im\>
- Abhimanyu Rawat \<abhi@status.im\>
sidebar_position: 1
- Oskar Thorén \<oskarth@titanproxy.com\>
sidebar_position: 14
---
## Abstract
@ -27,7 +28,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](../6/waku1.md).
- One may want to provide compatibility with [Waku v1 envelopes](../../legacy/6/waku1.md).
- One may want encrypted payloads by default.
- One may want to provide unlinkability to get metadata protection.
@ -194,7 +195,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 [6/PAYLOADS](../6/waku1.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.md/#clock-vs-timestamp-and-message-ordering).
### Reliability of the `ephemeral` attribute
@ -209,8 +210,8 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public
## References
- [6/WAKU1](/spec/6/)
- [6/WAKU1](../../legacy/6/waku1.md)
- [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))
- [6/PAYLOADS](https://specs.status.im/spec/6#clock-vs-timestamp-and-message-ordering)
- [62/STATUS-PAYLOADS](../../../../status/62/payloads.md/#clock-vs-timestamp-and-message-ordering)

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

@ -6,7 +6,7 @@ editor: Hanno Cornelius \<hanno@status.im\>
contributors:
- Oskar Thorén \<oskarth@titanproxy.com\>
- Sanaz Taheri \<sanaz@status.im\>
sidebar_position: 1
sidebar_position: 11
---
`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.

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

@ -2,11 +2,13 @@
title: 17/WAKU2-RLN-RELAY
name: Waku v2 RLN Relay
status: draft
editor: Sanaz Taheri \<sanaz@status.im\>
editor: Alvaro Revuelta \<alvaro@status.im\>
contributors:
- Oskar Thorén \<oskarth@titanproxy.com\>
- Aaryamann Challani \<aaryamann@status.im\>
sidebar_position: 1
- Sanaz Taheri \<sanaz@status.im\>
- Hanno Cornelius \<hanno@status.im\>
sidebar_position: 17
---
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).
@ -18,16 +20,16 @@ Spammers are also financially punished and removed from the system.
\<!-- **Protocol identifier***: `/vac/waku/waku-rln-relay/2.0.0-alpha1` --\>
# Motivation
## Motivation
In open and anonymous p2p messaging networks, one big problem is spam resistance.
Existing solutions, such as Whisper’s proof of work are computationally expensive hence not suitable for resource-limited nodes.
Other reputation-based approaches might not be desirable, due to issues around arbitrary exclusion and privacy.
We augment the [`11/WAKU2-RELAY`](/spec/11) protocol with a novel construct of [RLN](/spec/32) to enable an efficient economic spam prevention mechanism that can be run in resource-constrained environments.
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.
# Flow
## Flow
The messaging rate is defined by the `period` which indicates how many messages can be sent in a given period.
@ -39,12 +41,12 @@ 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](/spec/32).
### Setup and Registration
Peers subscribed to a specific `pubsubTopic` form a [RLN group](../../../../vac/32/rln-v1.md).
\<!-- 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](/spec/32) denoted by `sk` and `pk`.
Each peer has an [RLN key pair](../../../../vac/32/rln-v1.md) 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.
@ -56,12 +58,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.](./images/rln-relay.png)
![Figure 1: Registration.](./17/images/rln-relay.png)
## Publishing
### Publishing
To publish at a given `epoch`, the publishing peer proceeds based on the regular [`11/WAKU2-RELAY`](/spec/11) protocol.
To publish at a given `epoch`, the publishing peer proceeds based on the regular [`11/WAKU2-RELAY`](../11/relay.md) 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.
@ -73,7 +75,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](/spec/32).
They are derived deterministically from peer's `sk` and current `epoch` using [Shamir secret sharing scheme](../../../../vac/32/rln-v1.md).
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.
@ -81,13 +83,13 @@ 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](/spec/32)
For more details about the proof generation check [RLN](../../../../vac/32/rln-v1.md)
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 --\>
The proof generation also requires a set of public inputs which are: the Merkle tree root `merkle_root`, the current `epoch`, and the message for which the proof is going to be generated.
In `17/WAKU2-RLN-RELAY`, the message is the concatenation of `WakuMessage`'s `payload` filed and its `contentTopic` i.e., `payload||contentTopic`.
## Group Synchronization
### Group Synchronization
Proof generation relies on the knowledge of Merkle tree root `merkle_root` and `authPath` which both require access to the membership Merkle tree.
Getting access to the Merkle tree can be done in various ways.
@ -103,17 +105,17 @@ where the delay is due to mining the slashing transaction.
For the group synchronization, one important security consideration is that peers MUST make sure they always use the most recent Merkle tree root in their proof generation.
The reason is that using an old root can allow inference about the index of the user's `pk` in the membership tree hence compromising user privacy and breaking message unlinkability.
## Routing
### Routing
Upon the receipt of a PubSub message via [`11/WAKU2-RELAY`](/spec/11) 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.md) 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
#### Epoch Validation
If the `epoch` attached to the message is more than `max_epoch_gap` apart from the routing peer's current `epoch` then the message is discarded and considered invalid.
This is to prevent a newly registered peer from spamming the system by messaging for all the past epochs.
`max_epoch_gap` is a system parameter for which we provide some recommendations in section [Recommended System Parameters](#recommended-system-parameters).
### Merkle Root Validation
#### Merkle Root Validation
The routing peers MUST check whether the provided Merkle root in the `RateLimitProof` is valid.
It can do so by maintaining a local set of valid Merkle roots, which consist of `acceptable_root_window_size` past roots.
These roots refer to the final state of the Merkle tree after a whole block consisting of group changes is processed.
@ -127,12 +129,12 @@ This also allows peers which are not well connected to the network to be able to
This network delay is related to the nature of asynchronous network conditions, which means that peers see membership changes asynchronously, and therefore may have differing local Merkle trees.
See [Recommended System Parameters](#recommended-system-parameters) on choosing an appropriate `acceptable_root_window_size`.
### Proof Verification
#### 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](/spec/32).
It does so by running the zk verification algorithm as explained in [RLN](../../../../vac/32/rln-v1.md).
If `proof` is invalid then the message is discarded.
### Spam detection
#### Spam detection
To enable local spam detection and slashing, routing peers MUST record the `nullifier`, `share_x`, and `share_y` of incoming messages which are not discarded i.e., not found spam or with invalid proof or epoch.
To spot spam messages, the peer checks whether a message with an identical `nullifier` has already been relayed.
1. If such a message exists and its `share_x` and `share_y` components are different from the incoming message, then slashing takes place.
@ -146,14 +148,14 @@ 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 --\>
![Figure 2: Publishing, Routing and Slashing workflow.](./images/rln-message-verification.png)
![Figure 2: Publishing, Routing and Slashing workflow.](./17/images/rln-message-verification.png)
-------
# Payloads
## Payloads
Payloads are protobuf messages implemented using [protocol buffers v3](https://developers.google.com/protocol-buffers/).
Nodes MAY extend the [14/WAKU2-MESSAGE](/spec/14) with a `rate_limit_proof` field to indicate that their message is not spam.
Nodes MAY extend the [14/WAKU2-MESSAGE](../14/message.md) with a `rate_limit_proof` field to indicate that their message is not spam.
```diff
@ -178,22 +180,22 @@ message WakuMessage {
}
```
## WakuMessage
### WakuMessage
`rate_limit_proof` holds the information required to prove that the message owner has not exceeded the message rate limit.
## RateLimitProof
### RateLimitProof
Below is the description of the fields of `RateLimitProof` and their types.
| Parameter | Type | Description |
| ----: | ----------- | ----------- |
| `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](/spec/32) | \<!-- 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](/spec/32)|
| `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) | \<!-- 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)|
# Recommended System Parameters
## Recommended System Parameters
The system parameters are summarized in the following table, and the recommended values for a subset of them are presented next.
| Parameter | Description |
@ -204,14 +206,14 @@ The system parameters are summarized in the following table, and the recommended
| `max_epoch_gap` | the maximum allowed gap between the `epoch` of a routing peer and the incoming message |
| `acceptable_root_window_size` | The maximum number of past Merkle roots to store |
## Epoch Length
### Epoch Length
A sensible value for the `period` depends on the application for which the spam protection is going to be used.
For example, while the `period` of `1` second i.e., messaging rate of `1` per second, might be acceptable for a chat application, might be too low for communication among Ethereum network validators.
One should look at the desired throughput of the application to decide on a proper `period` value.
In the proof of concept implementation of `17/WAKU2-RLN-RELAY` protocol which is available in [nim-waku](https://github.com/status-im/nim-waku), the `period` is set to `1` second.
Nevertheless, this value is also subject to change depending on user experience.
## Maximum Epoch Gap
### Maximum Epoch Gap
We discussed in the [Routing](#routing) section that the gap between the epoch observed by the routing peer and the one attached to the incoming message should not exceed a threshold denoted by `max_epoch_gap` .
The value of `max_epoch_gap` can be measured based on the following factors.
- Network transmission delay `Network_Delay`: the maximum time that it takes for a message to be fully disseminated in the GossipSub network.
@ -234,11 +236,11 @@ The `acceptable_root_window_size` should indicate how many blocks may have been
This formula represents a lower bound of the number of acceptable roots.
# Copyright
## Copyright
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
# References
## References
1. [RLN documentation](https://hackmd.io/tMTLMYmTR5eynw2lwK9n1w?view)
2. [Public inputs to the RLN circuit](https://hackmd.io/tMTLMYmTR5eynw2lwK9n1w?view#Public-Inputs)

4
waku/standards/core/16/rpc.md → waku/standards/core/rpc.md
View File

@ -3,7 +3,7 @@ title: 16/WAKU2-RPC
name: Waku v2 RPC API
status: draft
editor: Hanno Cornelius \<hanno@status.im\>
sidebar_position: 1
sidebar_position: 16
---
## Introduction
@ -175,7 +175,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](../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.md).
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

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

@ -2,12 +2,14 @@
title: 13/WAKU2-STORE
name: Waku v2 Store
status: draft
editor: Sanaz Taheri \<sanaz@status.im\>
editor: Simon-Pierre Vivier \<simvivier@status.im\>
contributors:
- Dean Eigenmann \<dean@status.im\>
- Oskar Thorén \<oskarth@titanproxy.com\>
- Aaryamann Challani \<aaryamann@status.im\>
sidebar_position: 1
- Sanaz Taheri \<sanaz@status.im\>
- Hanno Cornelius \<hanno@status.im\>
sidebar_position: 13
---
## Abstract

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

@ -2,13 +2,14 @@
title: 10/WAKU2
name: Waku v2
status: draft
editor: Oskar Thorén \<oskarth@titanproxy.com\>
editor: Hanno Cornelius \<hanno@status.im\>
contributors:
- Sanaz Taheri \<sanaz@status.im\>
- Hanno Cornelius \<hanno@status.im\>
- Reeshav Khan \<reeshav@status.im\>
- Daniel Kaiser \<danielkaiser@status.im\>
sidebar_position: 1
- Oskar Thorén \<oskarth@titanproxy.com\>
sidebar_position: 10
---
## Abstract
@ -23,7 +24,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](../6/waku1.md),
Historically, it has its roots in [6/WAKU1](../../legacy/6/waku1.md),
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.
@ -211,7 +212,7 @@ This is used to fetch historical messages for mostly offline devices.
See [13/WAKU2-STORE spec](../13/store.md) 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/ft-store.md)
See [21/WAKU2-FT-STORE](../../application/21/fault-tolerant-store.md)
#### Content filtering
@ -236,7 +237,7 @@ 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.](./images/overview.png)
![Overview of how protocols interact in Waku v2.](./10/images/overview.png)
0. We have six nodes, A-F.
The protocols initially mounted are indicated as such.
@ -244,9 +245,9 @@ The PubSub topics `pubtopic1` and `pubtopic2` is used for routing and indicates
Ditto for [13/WAKU2-STORE](../13/store.md) 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](../core/14/message.md) for more details.
If WakuMessage version is set to 1, we use the [6/WAKU1](../6/waku1.md) compatible `data` field with encryption.
See [7/WAKU-DATA](../../application/7/data.md) for more details.
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.
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.
@ -362,10 +363,10 @@ 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](../6/waku1.md)|✔|||
|[7/WAKU-DATA](../7/data.md)|✔|✔||
|[8/WAKU-MAIL](../../application/8/mail.md)|✔|||
|[9/WAKU-RPC](../9/waku2-rpc.md)|✔|||
|[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)|✔|✔||
@ -393,7 +394,7 @@ To implement a minimal Waku v2 client, we recommend implementing the following s
To get compatibility with Waku v1:
- [7/WAKU-DATA](../7/data.md)
- [7/WAKU-DATA](../../legacy/7/data.md)
- [14/WAKU2-MESSAGE](../14/message.md) - version 1 (encrypted with `7/WAKU-DATA`)
For an interoperable keep-alive mechanism:
@ -429,7 +430,7 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public
1. [libp2p specs](https://github.com/libp2p/specs)
2. [6/WAKU1](../6/waku1.md)
2. [6/WAKU1](../../legacy/6/waku1.md)
3. [Whisper spec (EIP627)](https://eips.ethereum.org/EIPS/eip-627)
@ -473,7 +474,7 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public
23. [19/WAKU2-LIGHTPUSH](../19/lightpush.md)
24. [7/WAKU-DATA](../../application/7/data.md)
24. [7/WAKU-DATA](../../legacy/7/data.md)
25. [15/WAKU-BRIDGE](../15/bridge.md)
@ -487,9 +488,9 @@ 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](../../application/8/mail.md)
31. [8/WAKU-MAIL](../../legacy/8/mail.md)
32. [9/WAKU-RPC](../9/waku2-rpc.md)
32. [9/WAKU-RPC](../../legacy/9/rpc.md)
33. [16/WAKU2-RPC](../16/rpc.md)

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

@ -6,10 +6,10 @@ editor: Oskar Thorén \<oskarth@titanproxy.com\>
contributors:
- Dean Eigenmann \<dean@status.im\>
- Kim De Mey \<kimdemey@status.im\>
sidebar_position: 1
sidebar_position: 7
---
This specification describes the encryption, decryption and signing of the content in the [data field used in Waku](../../standards/core/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.md/#abnf-specification).
## Specification

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

@ -7,7 +7,7 @@ contributors:
- Adam Babik \<adam@status.im\>
- Dean Eigenmann \<dean@status.im\>
- Oskar Thorén \<oskarth@titanproxy.com\>
sidebar_position: 1
sidebar_position: 8
---
## Abstract
@ -100,7 +100,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](/spec/7).
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).
**Mailserver trusted connection:**

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

@ -6,7 +6,7 @@ editor: Andrea Maria Piana \<andreap@status.im\>
contributors:
- Dean Eigenmann \<dean@status.im\>
- Oskar Thorén \<oskarth@titanproxy.com\>
sidebar_position: 1
sidebar_position: 9
---
This specification describes the RPC API that Waku nodes MAY adhere to. The unified API allows clients to easily
@ -46,7 +46,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](/spec/7) 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.md) along with all of its metadata and other extra information such as the hash.
| Field | Type | Description |
| ----: | :--: | ----------- |

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

@ -8,7 +8,7 @@ contributors:
- Andrea Maria Piana \<andreap@status.im\>
- Dean Eigenmann \<dean@status.im\>
- Kim De Mey \<kimdemey@status.im\>
sidebar_position: 1
sidebar_position: 6
---
This specification describes the format of Waku packets within the ÐΞVp2p Wire Protocol. This spec substitutes [EIP-627](https://eips.ethereum.org/EIPS/eip-627). Waku is a fork of the original Whisper protocol that enables better usability for resource restricted devices, such as mostly-offline bandwidth-constrained smartphones. It does this through (a) light node support, (b) historic envelopes (with a mailserver) (c) expressing topic interest for better bandwidth usage and (d) basic rate limiting.
@ -36,7 +36,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](../../application/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.md) response. A node SHOULD NOT send an envelope to a peer that it has already sent before.
### Maximum Packet Size
@ -343,7 +343,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](../../application/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.md).
#### P2P Message
@ -353,7 +353,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](../../application/8/mail.md) specification.
The content of the packet is explained in the [Waku Mail Server](../8/mail.md) specification.
### Payload Encryption
@ -373,7 +373,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](../../application/8/mail.md).
Additionally there is the capability of a mailserver which is documented in its on [specification](../8/mail.md).
### Light node
@ -452,7 +452,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](../../application/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.md#security-considerations) can be found in their respective specifications.
### Scalability and UX