overhaul reference docs
This commit is contained in:
LordGhostX
parent
66c8a05e7b
commit
5a22c37ca9
|
|
@ -2,7 +2,7 @@
|
|||
title: Content Topics
|
||||
---
|
||||
|
||||
Content topics optimize node bandwidth usage by filtering messages based on specific topics of interest. They enable dApps to selectively process incoming live messages (`Relay` or `Filter`) and retrieve historical messages (`Store`) that match their filtering criteria. For more information, please refer to the [23/WAKU2-TOPICS](https://rfc.vac.dev/spec/23/#content-topics) specification.
|
||||
Content topics optimize node bandwidth usage by filtering messages based on specific topics of interest. They enable dApps to selectively process incoming live messages ([Relay](/overview/concepts/protocols#waku-relay) or [Filter](/overview/concepts/protocols#waku-filter)) and retrieve historical messages ([Store](/overview/concepts/protocols#waku-store)) that match their filtering criteria. For more information, please refer to the [WAKU2-TOPICS](https://rfc.vac.dev/spec/23/#content-topics) specification.
|
||||
|
||||
## Content Topic Format
|
||||
|
||||
|
|
@ -13,7 +13,7 @@ Here is the recommended format for content topics:
|
|||
- `application-name`: This is the unique name of your decentralized application (dApp) to prevent conflicts with other dApps.
|
||||
- `version`: Typically starting at 1, this field helps track breaking changes in your messages.
|
||||
- `content-topic-name`: The specific name of the content topic used for filtering. If your dApp utilizes Waku for multiple features, it is advisable to have a separate content topic for each feature.
|
||||
- `encoding`: The message encoding format, with [Protobuf](https://developers.google.com/protocol-buffers) (`proto`) being the commonly used choice.
|
||||
- `encoding`: The message serialization/encoding format, with [Protobuf](https://protobuf.dev/) (`proto`) being the commonly used choice.
|
||||
|
||||
For instance, if your dApp is called `SuperCrypto` and it allows users to receive notifications and send private messages, you can consider utilizing the following content topics:
|
||||
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ Node discovery in Waku facilitates locating other nodes within the network. As a
|
|||
|
||||
## Gossip Domain
|
||||
|
||||
Gossipsub derives its name from the practice within pub-sub networks where peers gossip about the messages they have encountered, thus establishing a message delivery network.
|
||||
Gossipsub derives its name from the practice within Pub/Sub networks where peers gossip about the messages they have encountered, thus establishing a message delivery network.
|
||||
|
||||
Waku employs gossiping through [`WAKU-RELAY`](/overview/concepts/protocols#waku-relay) to distribute messages across the network. Additionally, Waku introduces [`WAKU-RLN-RELAY`](/overview/concepts/protocols#waku-rln-relay), an experimental mechanism that combines privacy preservation and economic spam protection.
|
||||
|
||||
|
|
@ -45,7 +45,7 @@ E ->> D: HistoryQuery(pubtopic1, contentTopic1) (6)
|
|||
D ->> E: HistoryResponse(msg1, ...) (6)
|
||||
```
|
||||
|
||||
The Publish/Subscribe topic `pubtopic1` serves as a means of routing messages (the network employs a default pub-sub topic) and indicates that it is subscribed to messages on that topic for a relay. In the context of Waku Store, Node D is responsible for persisting these messages.
|
||||
The Pub/Sub topic `pubtopic1` serves as a means of routing messages (the network employs a default pubsub topic) and indicates that it is subscribed to messages on that topic for a relay. In the context of Waku Store, Node D is responsible for persisting these messages.
|
||||
|
||||
1. Node A creates a WakuMessage `msg1` with a [ContentTopic](/overview/concepts/content-topics) `contentTopic1`.
|
||||
2. Node F requests to get messages filtered by Pub/Sub topic `pubtopic1` and ContentTopic `contentTopic1`. Node D subscribes F to this filter and will forward messages that match that filter in the future.
|
||||
|
|
|
|||
|
|
@ -6,9 +6,9 @@ When initializing a Waku node, it must connect with other nodes to enable messag
|
|||
|
||||
After establishing a connection, the node must actively seek out additional peers to have:
|
||||
|
||||
- Sufficient peers in the `Waku Relay` mesh: The goal is to have at least 6 peers in the mesh. This ensures a robust network where messages can be efficiently relayed.
|
||||
- Sufficient peers in the [Waku Relay](/overview/concepts/protocols#waku-relay) mesh: The goal is to have at least 6 peers in the mesh. This ensures a robust network where messages can be efficiently relayed.
|
||||
- Reserve peers for backup: It is essential to have a surplus of peers available as reserves. These reserves are backups when the current peers become overloaded or experience unexpected disconnections.
|
||||
- Peers with specific Waku capabilities: The node seeks out peers with specific Waku capabilities, such as `Store`, `Light Push`, or `Filter`. This allows for targeted interactions and enhanced functionality based on the desired capabilities.
|
||||
- Peers with specific Waku capabilities: The node seeks out peers with specific Waku capabilities, such as [Store](/overview/concepts/protocols#waku-store), [Light Push](/overview/concepts/protocols#waku-light-push), or [Filter](/overview/concepts/protocols#waku-filter). This allows for targeted interactions and enhanced functionality based on the desired capabilities.
|
||||
|
||||
## Predefined Bootstrap Nodes
|
||||
|
||||
|
|
@ -58,7 +58,7 @@ This bootstrapping method allows anyone to register and publish a domain name fo
|
|||
|
||||
## [Peer Exchange](https://rfc.vac.dev/spec/34/)
|
||||
|
||||
The primary objective of this protocol is to facilitate peer connectivity for resource-restricted devices. The peer exchange protocol enables lightweight nodes to request peers from other nodes within the network. Light nodes can bootstrap and expand their mesh independently without relying on `Discv5` or bootstrap nodes.
|
||||
The primary objective of this protocol is to facilitate peer connectivity for resource-restricted devices. The peer exchange protocol enables lightweight nodes to request peers from other nodes within the network. Light nodes can bootstrap and expand their mesh independently without relying on [Discv5](#discv5) or bootstrap nodes.
|
||||
|
||||
:::info
|
||||
This protocol is intended for situations where the use of `Discv5` is not feasible.
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ Waku takes a modular approach, providing a range of protocols that enable applic
|
|||
|
||||
### [Waku Relay](https://rfc.vac.dev/spec/11/)
|
||||
|
||||
`WAKU2-RELAY` is a privacy-focused peer-to-peer messaging protocol that extends the `libp2p GossipSub` protocol. It utilizes a Publish/Subscribe approach to enable secure communication channels, encryption, and protection against censorship. With a strong emphasis on privacy, `Waku Relay` ensures scalability, allowing many peers and messages to coexist within the network.
|
||||
`WAKU2-RELAY` is a privacy-focused peer-to-peer messaging protocol that extends the `libp2p GossipSub` protocol. It utilizes a Pub/Sub approach to enable secure communication channels, encryption, and protection against censorship. With a strong emphasis on privacy, `Waku Relay` ensures scalability, allowing many peers and messages to coexist within the network.
|
||||
|
||||
### [Waku Filter](https://rfc.vac.dev/spec/12/)
|
||||
|
||||
|
|
|
|||
|
|
@ -2,14 +2,14 @@
|
|||
title: Transports in Waku
|
||||
---
|
||||
|
||||
Waku aims to be transport agnostic, providing flexibility in selecting suitable transports. However, a set of recommended transports is defined to establish a baseline of client interoperability.
|
||||
Transports facilitate data packet movement across networks with TCP and UDP being standard protocols. However, alternatives are at lower (Ethernet, Bluetooth) and higher (QUIC) levels. Waku, aiming to be transport agnostic, enables developers to choose and support multiple protocols based on their needs.
|
||||
|
||||
The recommended transports for Waku nodes are as follows:
|
||||
|
||||
- TCP: By default, Waku nodes utilize TCP for communication. Service nodes should employ TCP for listening to and connecting with other nodes.
|
||||
- Secure WebSocket: In browser environments, secure WebSocket is used. Service nodes are encouraged to set up SSL certificates to enable incoming connections from browsers and serve them securely.
|
||||
- Other protocols like [WebRTC](https://github.com/waku-org/js-waku/issues/20), [WebTransport](https://github.com/waku-org/js-waku/issues/697), and QUIC have been investigated and studied for potential integration.
|
||||
- **TCP:** By default, Waku nodes utilize TCP for communication. Service nodes should employ TCP for listening to and connecting with other nodes.
|
||||
- **Secure WebSocket:** In browser environments, secure WebSocket is used. Service nodes are encouraged to set up SSL certificates to enable incoming connections from browsers and serve them securely.
|
||||
- Other protocols like [WebRTC](https://github.com/waku-org/js-waku/issues/20), [WebTransport](https://github.com/waku-org/js-waku/issues/697), and QUIC have been researched and studied for potential integration.
|
||||
|
||||
:::note
|
||||
Waku ensures compatibility and enhanced communication capabilities among nodes by adhering to these recommended transports.
|
||||
:::info
|
||||
Waku ensures compatibility and improved communication capabilities by following these recommended transports.
|
||||
:::
|
||||
|
|
@ -4,20 +4,18 @@ title: Research in Progress
|
|||
|
||||
The following features are currently experimental and under research and initial implementation:
|
||||
|
||||
**Economic Spam resistance**:
|
||||
We aim to enable an incentivized spam protection technique to enhance `WAKU-RELAY` by using rate limiting nullifiers.
|
||||
More details on this can be found in [17/WAKU2-RLN-RELAY](https://rfc.vac.dev/spec/17).
|
||||
In this advanced method, peers are limited to a certain rate of messaging per epoch and an immediate financial penalty is enforced for spammers who break this rate.
|
||||
## Economic Spam Resistance
|
||||
|
||||
We have prepared a PoC implementation of this method in JS: https://examples.waku.org/rln-js/
|
||||
We aim to enable an incentivized spam protection technique to enhance `WAKU-RELAY` by using rate limiting nullifiers. More details on this can be found in [WAKU2-RLN-RELAY](https://rfc.vac.dev/spec/17). In this advanced method, peers are limited to a certain rate of messaging per epoch and an immediate financial penalty is enforced for spammers who break this rate.
|
||||
|
||||
**Prevention of Denial of Service (DoS) and Node Incentivization**:
|
||||
Denial of service signifies the case where an adversarial node exhausts another node's service capacity (e.g., by making a large number of requests) and makes it unavailable to the rest of the system.
|
||||
RnD on DoS attack mitigation can tracked from here: https://github.com/vacp2p/research/issues/148
|
||||
In a nutshell, peers have to pay for the service they obtain from each other.
|
||||
In addition to incentivizing the service provider, accounting also makes DoS attacks costly for malicious peers.
|
||||
The accounting model can be used in `13/WAKU2-STORE` and `12/WAKU2-FILTER` to protect against DoS attacks.
|
||||
We have prepared a PoC implementation of this method in JS: <https://examples.waku.org/rln-js/>
|
||||
|
||||
Additionally, along with RLN, this gives node operators who provide a useful service to the network an incentive to perform that service. Read more here: https://vac.dev/building-privacy-protecting-infrastructure
|
||||
## Prevention of Denial of Service (DoS) and Node Incentivization
|
||||
|
||||
You can also read more about the current open problems the Vac/Waku team is working on here: https://vac.dev/open-problems
|
||||
Denial of service signifies the case where an adversarial node exhausts another node's service capacity (e.g., by making a large number of requests) and makes it unavailable to the rest of the system. RnD on DoS attack mitigation can tracked from here: <https://github.com/vacp2p/research/issues/148>.
|
||||
|
||||
In a nutshell, peers have to pay for the service they obtain from each other. In addition to incentivizing the service provider, accounting also makes DoS attacks costly for malicious peers. The accounting model can be used in `WAKU2-STORE` and `WAKU2-FILTER` to protect against DoS attacks.
|
||||
|
||||
Additionally, along with RLN, this gives node operators who provide a useful service to the network an incentive to perform that service. Read more here: <https://vac.dev/building-privacy-protecting-infrastructure>
|
||||
|
||||
You can also read more about the current open problems the Vac/Waku team is working on here: <https://vac.dev/open-problems>
|
||||
|
|
|
|||
|
|
@ -2,62 +2,44 @@
|
|||
title: Security Features
|
||||
---
|
||||
|
||||
Each protocol layer of Waku v2 provides a distinct service and is associated with a separate set of security features and concerns.
|
||||
Therefore, the overall security of Waku v2 depends on how the different layers are utilized.
|
||||
Each protocol layer of Waku provides a distinct service and is associated with a separate set of security features and concerns. Therefore, the overall security of Waku depends on how the different layers are utilized.
|
||||
|
||||
The security models are detailed in the RFC of the protocols.
|
||||
We strive to provide well documented and open source RFCs so that Waku users know what security guarantees are and aren't provided by each protocol.
|
||||
The security models are detailed in the RFC of the protocols. We strive to provide well documented and [open source RFCs](https://rfc.vac.dev/) so that Waku users know what security guarantees are and aren't provided by each protocol.
|
||||
|
||||
Some of the security features of Waku v2 are:
|
||||
Some of the security features of Waku are:
|
||||
|
||||
### Pseudonymity
|
||||
## Pseudonymity
|
||||
|
||||
Waku v2 by default guarantees pseudonymity for all of the protocol layers since parties do not have to disclose their true identity
|
||||
and instead they utilize libp2p `PeerID` as their identifiers.
|
||||
While pseudonymity is an appealing security feature, it does not guarantee full anonymity since the actions taken under the same pseudonym
|
||||
i.e., `PeerID`, can be linked together and potentially result in the re-identification of the true actor.
|
||||
Waku by default guarantees pseudonymity for all of the protocol layers since parties do not have to disclose their true identity
|
||||
and instead they utilize libp2p `PeerID` as their identifiers. While pseudonymity is an appealing security feature, it does not guarantee full anonymity since the actions taken under the same pseudonym i.e., `PeerID`, can be linked together and potentially result in the re-identification of the true actor.
|
||||
|
||||
### Anonymity / Unlinkability
|
||||
## Anonymity/Unlinkability
|
||||
|
||||
At a high level, anonymity is the inability of an adversary in linking an actor to its data/performed action (the actor and action are context-dependent).
|
||||
To be precise about linkability, we use the term Personally Identifiable Information (PII) to refer to any piece of data that could potentially be used to uniquely identify a party.
|
||||
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.
|
||||
Notice that users' actions can be traced through their PIIs (e.g., signatures) and hence result in their re-identification risk.
|
||||
As such, we seek anonymity by avoiding linkability between actions and the actors / actors' PII. Concerning anonymity, Waku v2 provides the following features:
|
||||
At a high level, anonymity is the inability of an adversary in linking an actor to its data/performed action (the actor and action are context-dependent). To be precise about linkability, we use the term Personally Identifiable Information (PII) to refer to any piece of data that could potentially be used to uniquely identify a party.
|
||||
|
||||
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. Notice that users' actions can be traced through their PIIs (e.g., signatures) and hence result in their re-identification risk. As such, we seek anonymity by avoiding linkability between actions and the actors / actors' PII. Concerning anonymity, Waku provides the following features:
|
||||
|
||||
### Publisher-Message Unlinkability
|
||||
|
||||
**Publisher-Message Unlinkability**:
|
||||
This feature signifies the unlinkability of a publisher to its published messages in the `WAKU-RELAY` protocol.
|
||||
|
||||
**Subscriber-Topic Unlinkability**:
|
||||
This feature stands for the unlinkability of the subscriber to its subscribed topics in the `WAKU-RELAY` protocol.
|
||||
The [Subscriber-Topic Unlinkability](https://rfc.vac.dev/spec/11/#security-analysis) is achieved through the utilization of a single PubSub topic.
|
||||
As such, subscribers are not re-identifiable from their subscribed topic IDs as the entire network is linked to the same topic ID.
|
||||
This level of unlinkability / anonymity is known as [k-anonymity](https://www.privitar.com/blog/k-anonymity-an-introduction/) where k is proportional to the system size (number of subscribers).
|
||||
Note that there is no hard limit on the number of the pubsub topics, however, the use of one topic is recommended for the sake of anonymity.
|
||||
### Subscriber-Topic Unlinkability
|
||||
|
||||
### Spam protection
|
||||
This feature stands for the unlinkability of the subscriber to its subscribed topics in the `WAKU-RELAY` protocol. The [Subscriber-Topic Unlinkability](https://rfc.vac.dev/spec/11/#security-analysis) is achieved through the utilization of a single PubSub topic. As such, subscribers are not re-identifiable from their subscribed topic IDs as the entire network is linked to the same topic ID. This level of unlinkability / anonymity is known as [k-anonymity](https://www.privitar.com/blog/k-anonymity-an-introduction/) where k is proportional to the system size (number of subscribers). Note that there is no hard limit on the number of the pubsub topics, however, the use of one topic is recommended for the sake of anonymity.
|
||||
|
||||
## Spam Protection
|
||||
|
||||
This property indicates that no adversary can flood the system (i.e., publishing a large number of messages in a short amount of time), either accidentally or deliberately, with any kind of message i.e. even if the message content is valid or useful.
|
||||
Spam protection is partly provided in `WAKU2-RELAY` through the [scoring mechanism](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md#spam-protection-measures) provided for by GossipSub v1.1.
|
||||
At a high level, peers utilize a scoring function to locally score the behavior of their connections and remove peers with a low score.
|
||||
|
||||
There's also further research being done in this domain, including the designing of [RLN (Rate Limiting Nullifiers)](./research-in-progress.md)
|
||||
Spam protection is partly provided in `WAKU2-RELAY` through the [scoring mechanism](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md#spam-protection-measures) provided for by GossipSub v1.1. At a high level, peers utilize a scoring function to locally score the behavior of their connections and remove peers with a low score.
|
||||
|
||||
https://github.com/vacp2p/research/issues/148
|
||||
There's also further research being done in this domain, including the designing of [RLN (Rate Limiting Nullifiers)](https://rfc.vac.dev/spec/32/): <https://github.com/vacp2p/research/issues/148>.
|
||||
|
||||
### Data confidentiality, Integrity, and Authenticity
|
||||
## Data Confidentiality, Integrity, and Authenticity
|
||||
|
||||
Confidentiality can be addressed through data encryption whereas integrity and authenticity are achievable through digital signatures.
|
||||
These features are provided for in [WAKU-MESSAGE (version 1)](https://rfc.vac.dev/spec/14#version-1) and [WAKU-NOISE](https://rfc.vac.dev/spec/35/) through payload encryption as well as encrypted signatures.
|
||||
|
||||
:::info `WAKU-NOISE` enables secure channel negotiation over Waku.
|
||||
:::
|
||||
These features are provided for in [WAKU-MESSAGE (version 1)](https://rfc.vac.dev/spec/14#version-1) and [WAKU-NOISE](https://rfc.vac.dev/spec/35/) through payload encryption as well as encrypted signatures. `WAKU-NOISE` enables secure channel negotiation over Waku.
|
||||
|
||||
## Security Considerations
|
||||
|
||||
**Lack of anonymity/unlinkability in the protocols involving direct connections including [`13/WAKU2-STORE`](https://rfc.vac.dev/spec/13/) and [`12/WAKU2-FILTER`](https://rfc.vac.dev/spec/12/) protocols**:
|
||||
The anonymity/unlinkability is not guaranteed in the protocols like `13/WAKU2-STORE` and `12/WAKU2-FILTER` where peers need to have direct connections to benefit from the designated service.
|
||||
This is because during the direct connections peers utilize `PeerID` to identify each other,
|
||||
therefore the service obtained in the protocol is linkable to the beneficiary's `PeerID` (which counts as PII).
|
||||
For `13/WAKU2-STORE`, the queried node would be able to link the querying node's `PeerID` to its queried topics.
|
||||
Likewise, in the `12/WAKU2-FILTER`, a full node can link the light node's `PeerID`s to its content filter.
|
||||
The anonymity/unlinkability is not guaranteed in the protocols like `WAKU2-STORE` and `WAKU2-FILTER` where peers need to have direct connections to benefit from the designated service. This is because during the direct connections peers utilize `PeerID` to identify each other, therefore the service obtained in the protocol is linkable to the beneficiary's `PeerID` (which counts as PII). For `WAKU2-STORE`, the queried node would be able to link the querying node's `PeerID` to its queried topics. Likewise, in the `WAKU2-FILTER`, a full node can link the light node's `PeerID` to its content filter.
|
||||
|
|
@ -1,22 +1,21 @@
|
|||
---
|
||||
title: Waku vs libp2p - what's the difference?
|
||||
title: Waku vs libp2p - What's the difference?
|
||||
---
|
||||
|
||||
Since Waku v2 is built on top of libp2p, they share a lot of concepts and terminologies between them. However, there are key differences between them that are worth noting.
|
||||
Since Waku is built on top of libp2p, they share a lot of concepts and terminologies between them. However, there are key differences between them that are worth noting.
|
||||
|
||||
### Waku as a service network
|
||||
## Waku as a Service Network
|
||||
|
||||
Waku offers incentivization mechanisms to run nodes, whereas libp2p does not.
|
||||
Waku offers incentivization mechanisms to run nodes, whereas libp2p does not. Additionally, a user or a developer does not have to deploy own infra as a prerequisite to use Waku, it is a service network.
|
||||
|
||||
Additionally, a user or a developer does not have to deploy own infra as a prerequisite to use Waku, it is a service network.
|
||||
However, it is encouraged to [run your own node](https://github.com/status-im/nwaku/tree/master/docs/operators) to support and decentralize the network.
|
||||
|
||||
### Waku as a keyturn solution
|
||||
## Waku as a Keyturn Solution
|
||||
|
||||
Waku includes a number of protocol covering the following domains like privacy preservation, censorship resistance, portability/runs anywhere.
|
||||
|
||||
libp2p does not provide out of the box protocols to enable mostly offline/resource restricted devices, [WAKU-STORE](https://rfc.vac.dev/spec/13/)/[WAKU-LIGHTPUSH](https://rfc.vac.dev/spec/19/)/[WAKU-FILTER](https://rfc.vac.dev/spec/12/) caters to those use cases.
|
||||
|
||||
### Economic spam protection
|
||||
## Economic Spam Protection
|
||||
|
||||
libp2p does not have strong spam protection guarantees, [RLN (Rate Limit Nullifier)](https://rfc.vac.dev/spec/32/) is a protocol being developed by the Waku team towards this goal.
|
||||
|
|
|
|||
|
|
@ -47,7 +47,7 @@ These options are part of the [Anonymity Trilemma](https://eprint.iacr.org/2017/
|
|||
|
||||
## How Does Waku Work?
|
||||
|
||||
The Waku Relay protocol is the foundation of the Waku Network, which employs a `pubsub` architecture built on the `libp2p gossipsub` protocol. In addition to this, various other Waku protocols have been created to facilitate specific functionalities, including but not limited to:
|
||||
The Waku Relay protocol is the foundation of the Waku Network, which employs a Pub/Sub architecture built on the `libp2p gossipsub` protocol. In addition to this, various other Waku protocols have been created to facilitate specific functionalities, including but not limited to:
|
||||
|
||||
1. Facilitating the retrieval of historical messages for primarily offline devices.
|
||||
2. Providing solutions for encrypted communication, such as symmetric encryption, ECIES/asymmetric encryption, and noise handshake-based key turns.
|
||||
|
|
|
|||
|
|
@ -19,8 +19,8 @@ const sidebars = {
|
|||
"overview/concepts/protocols",
|
||||
"overview/concepts/network-domains",
|
||||
"overview/concepts/node-discovery",
|
||||
"overview/concepts/transports",
|
||||
"overview/concepts/content-topics",
|
||||
"overview/concepts/transports",
|
||||
],
|
||||
},
|
||||
{
|
||||
|
|
|
|||
Loading…
Reference in New Issue