feat: improvements on docs (#24)
* add: security features * add: protocols overview by example * add: different protocols * add: spell check on CI * rm: yarn.lock to avoid inconsistencies * Update docs/Concepts/1.md Co-authored-by: fryorcraken.eth <110212804+fryorcraken@users.noreply.github.com> * Update docs/Concepts/2.md Co-authored-by: fryorcraken.eth <110212804+fryorcraken@users.noreply.github.com> * Update docs/Concepts/2.md Co-authored-by: fryorcraken.eth <110212804+fryorcraken@users.noreply.github.com> * Update docs/Concepts/7.md Co-authored-by: fryorcraken.eth <110212804+fryorcraken@users.noreply.github.com> * Update docs/Concepts/7.md Co-authored-by: fryorcraken.eth <110212804+fryorcraken@users.noreply.github.com> * convert mscgen sequence to mermaid * partially adress review comments * address: comments * fix: ci * chore: address minor typos/changes in docs * add: pros/cons for discv5 and peer-exchange * fix: minor typo * chore: address refactoring Co-authored-by: fryorcraken.eth <110212804+fryorcraken@users.noreply.github.com>
This commit is contained in:
Danish Arora
GitHub
parent
4656af3c37
commit
4413612924
43
.cspell.json
43
.cspell.json
|
|
@ -2,7 +2,33 @@
|
|||
"version": "0.2",
|
||||
"$schema": "https://raw.githubusercontent.com/streetsidesoftware/cspell/master/cspell.schema.json",
|
||||
"language": "en",
|
||||
"words": ["waku"],
|
||||
"words": [
|
||||
"linkability",
|
||||
"Unlinkability",
|
||||
"waku",
|
||||
"deplatforming",
|
||||
"gossipsub",
|
||||
"incentivized",
|
||||
"incentivizing",
|
||||
"XMTP",
|
||||
"RAILGUN",
|
||||
"nwaku",
|
||||
"deanonymization",
|
||||
"ECIES",
|
||||
"Discv5",
|
||||
"Gossipsub",
|
||||
"LIGHTPUSH",
|
||||
"pubtopic1",
|
||||
"proto",
|
||||
"multiaddr",
|
||||
"multiaddrs",
|
||||
"Multiaddrs",
|
||||
"keyturn",
|
||||
"Comms",
|
||||
"Protobuf",
|
||||
"supercrypto",
|
||||
"QUIC"
|
||||
],
|
||||
"flagWords": [],
|
||||
"ignorePaths": [
|
||||
"package.json",
|
||||
|
|
@ -12,9 +38,18 @@
|
|||
"node_modules/**"
|
||||
],
|
||||
"patterns": [
|
||||
{ "name": "multiaddr", "pattern": "/p2p.*/" },
|
||||
{ "name": "dnsMultiaddr", "pattern": "//dns4.*/" },
|
||||
{ "name": "wss", "pattern": "/wss:.*/" },
|
||||
{
|
||||
"name": "multiaddr",
|
||||
"pattern": "/p2p.*/"
|
||||
},
|
||||
{
|
||||
"name": "dnsMultiaddr",
|
||||
"pattern": "//dns4.*/"
|
||||
},
|
||||
{
|
||||
"name": "wss",
|
||||
"pattern": "/wss:.*/"
|
||||
},
|
||||
{
|
||||
"name": "youtube-link",
|
||||
"pattern": "/< youtube.*/"
|
||||
|
|
|
|||
|
|
@ -0,0 +1,24 @@
|
|||
name: CI
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- "master"
|
||||
- "staging"
|
||||
- "trying"
|
||||
pull_request:
|
||||
|
||||
env:
|
||||
NODE_JS: "18"
|
||||
|
||||
jobs:
|
||||
check:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- uses: actions/setup-node@v3
|
||||
with:
|
||||
node-version: ${{ env.NODE_JS }}
|
||||
- uses: bahmutov/npm-install@v1
|
||||
- run: npm run check:spell
|
||||
- run: npm run build
|
||||
|
|
@ -1,69 +1,27 @@
|
|||
---
|
||||
title: Protocols Explained
|
||||
title: Different Types of Protocols in Waku
|
||||
---
|
||||
|
||||
Currently the main protocols used for Waku are:
|
||||
Waku is modular: several protocols are available and applications can decide on how they want to turn the dials on the [Anonymity Trilemma](https://freedom.cs.purdue.edu/projects/trilemma.html). Here are the different types of protocols Waku offers:
|
||||
|
||||
### [Waku Relay](https://rfc.vac.dev/spec/11/)
|
||||
## 1. Discovery Domain
|
||||
|
||||
`WAKU2-RELAY` specifies a Publish/Subscribe approach to peer-to-peer messaging with a strong focus on privacy, censorship-resistance, security and scalability.
|
||||
Its current implementation is a minor extension of the libp2p GossipSub protocol and prescribes gossip-based dissemination.
|
||||
Node discovery is the mechanism that enables a Waku node to find other nodes. Waku is a modular protocol, several discovery mechanisms are and will be included in Waku (eg: [`Discv5`](https://rfc.vac.dev/spec/33/) and [`Peer Exchange`](https://rfc.vac.dev/spec/34/) ) so that developers can select the best mechanism(s) based for their use case and the user’s environment (e.g. mobile phone, desktop browser, server, etc).
|
||||
|
||||
An extension of this is `WAKU-RLN-RELAY`, a privacy-preserving economic spam protection mechanism.
|
||||
## 2. Gossip Domain
|
||||
|
||||
### [Waku Filter](https://rfc.vac.dev/spec/12/)
|
||||
Gossipsub is named after the fact that in a pub-sub network, the peers gossip to each other about which messages they have seen and use this information to maintain a message delivery network.
|
||||
|
||||
`WAKU2-FILTER` is a protocol that enables subscribing to messages that a peer receives.
|
||||
It enables a node to access the relay network without the connectivity and bandwidth requirements of relay nodes, but it comes with privacy drawbacks.
|
||||
Light nodes subscribe to service nodes and only receive the messages they desire.
|
||||
Waku is using gossiping to disseminate messages throughout the network using [`WAKU-RELAY`](https://rfc.vac.dev/spec/11/).
|
||||
An extension of this is [`WAKU-RLN-RELAY`](https://rfc.vac.dev/spec/17/): an experimental privacy-preserving economic spam protection mechanism.
|
||||
|
||||
This is used to make fetching of a subset of messages more bandwidth preserving.
|
||||
## 3. Request/Response Domain
|
||||
|
||||
### [Waku Store](https://rfc.vac.dev/spec/13/)
|
||||
In addition to the Gossip domain, Waku provides a set of Request/Reply protocols. They are primarily used in order to get Waku to run in resource restricted environments, such as low bandwidth or being mostly offline.
|
||||
|
||||
DApps running on a phone or in a browser are often offline:
|
||||
The browser could be closed or mobile app in the background.
|
||||
- [`WAKU-STORE`](https://rfc.vac.dev/spec/13/) is used to fetch historical messages for mostly offline devices.
|
||||
|
||||
[Waku Relay](https://rfc.vac.dev/spec/11/) is a gossip protocol.
|
||||
As a user, it means that your peers forward you messages they just received.
|
||||
If you cannot be reached by your peers, then messages are not relayed;
|
||||
relay peers do **not** save messages for later.
|
||||
:::info There is also an experimental fault-tolerant addition to the store protocol (WAKU-FT-STORE) that relaxes the high availability requirement.
|
||||
|
||||
However, [Waku Store](https://rfc.vac.dev/spec/13/) peers do save messages they relay,
|
||||
allowing you to retrieve them at a later time.
|
||||
The Waku Store protocol is best-effort and does not guarantee data availability.
|
||||
Waku Relay or Waku Filter should still be preferred when online;
|
||||
Waku Store can be used after resuming connectivity:
|
||||
For example, when the dApp starts.
|
||||
|
||||
### [Waku Light Push](https://rfc.vac.dev/spec/19/)
|
||||
|
||||
Waku Light Push enables a client to receive a confirmation when sending a message.
|
||||
|
||||
The Waku Relay protocol sends messages to connected peers but does not provide any information on whether said peers have received messages.
|
||||
This can be an issue when facing potential connectivity issues.
|
||||
For example, when the connection drops easily, or it is connected to a small number of relay peers.
|
||||
|
||||
Waku Light Push allows a client to get a response from a remote peer when sending a message.
|
||||
Note this only guarantees that the remote peer has received the message,
|
||||
it cannot guarantee propagation to the network.
|
||||
|
||||
It also means weaker privacy properties as the remote peer knows the client is the originator of the message.
|
||||
Whereas with Waku Relay, a remote peer would not know whether the client created or forwarded the message.
|
||||
|
||||
You can find Waku Light Push's specifications on [Vac RFC](https://rfc.vac.dev/spec/19/).
|
||||
|
||||
`WAKU2-LIGHTPUSH` is a request/response protocol for this.
|
||||
|
||||
## Additional Protocols
|
||||
|
||||
This is in addition to protocols that specify messages, payloads, and recommended usages.
|
||||
For example:
|
||||
|
||||
- [14/WAKU2-MESSAGE](https://rfc.vac.dev/spec/14) and [26/WAKU2-PAYLOAD](https://rfc.vac.dev/spec/26) for message payloads
|
||||
- [23/WAKU2-TOPICS](https://rfc.vac.dev/spec/23) and [27/WAKU2-PEERS](https://rfc.vac.dev/spec/27) for recommendations around usage
|
||||
|
||||
There are also more experimental libp2p protocols such as
|
||||
[`WAKU-RLN-RELAY`](https://rfc.vac.dev/spec/17/)
|
||||
|
||||
You can find more information on this [here](./6.md).
|
||||
- [`WAKU-FILTER`](https://rfc.vac.dev/spec/12/) is used to make fetching of a subset of messages more bandwidth preserving.
|
||||
- [`WAKU-LIGHTPUSH`](https://rfc.vac.dev/spec/19/) is used for nodes with short connection windows and limited bandwidth to publish messages into the Waku network.
|
||||
|
|
|
|||
|
|
@ -1,11 +1,69 @@
|
|||
---
|
||||
title: Transports in Waku
|
||||
title: Protocols Explained
|
||||
---
|
||||
|
||||
Waku v2 is built in top of libp2p, and like libp2p it strives to be transport agnostic. We define a set of recommended transports in order to achieve a baseline of interoperability between clients.
|
||||
Currently, the main Waku protocols are:
|
||||
|
||||
This section describes these recommended transports:
|
||||
### [Waku Relay](https://rfc.vac.dev/spec/11/)
|
||||
|
||||
- Waku nodes uses TCP to communicate by default. A service node should be using TCP to connect to other nodes and listen to
|
||||
- In environments where TCP is not available, such as browser, secure websocket is used. service nodes are encouraged to setup a SSL certificate to enable incoming connections from browser and serve them.
|
||||
- Other protocols such as [WebRTC](https://github.com/waku-org/js-waku/issues/20), [WebTransport](https://github.com/waku-org/js-waku/issues/697) and QUIC have been studied.
|
||||
`WAKU2-RELAY` specifies a Publish/Subscribe approach to peer-to-peer messaging with a strong focus on privacy, censorship-resistance, security and scalability.
|
||||
Its current implementation is a minor extension of the libp2p GossipSub protocol and prescribes gossip-based dissemination.
|
||||
|
||||
An extension of this is `WAKU-RLN-RELAY`, a privacy-preserving economic spam protection mechanism.
|
||||
|
||||
### [Waku Filter](https://rfc.vac.dev/spec/12/)
|
||||
|
||||
`WAKU2-FILTER` is a protocol that enables subscribing to messages that a peer receives.
|
||||
It enables a node to access the relay network without the connectivity and bandwidth requirements of relay nodes, but it comes with privacy drawbacks.
|
||||
Light nodes subscribe to service nodes and only receive the messages they desire.
|
||||
|
||||
It makes receiving messages more bandwidth preserving.
|
||||
|
||||
### [Waku Store](https://rfc.vac.dev/spec/13/)
|
||||
|
||||
DApps running on a phone or in a browser are often offline:
|
||||
The browser could be closed or mobile app in the background.
|
||||
|
||||
[Waku Relay](https://rfc.vac.dev/spec/11/) is a gossip protocol.
|
||||
As a user, it means that your peers forward you messages they just received.
|
||||
If you cannot be reached by your peers, then messages are not relayed;
|
||||
relay peers do **not** save messages for later.
|
||||
|
||||
However, [Waku Store](https://rfc.vac.dev/spec/13/) peers do save messages they relay,
|
||||
allowing you to retrieve them at a later time.
|
||||
The Waku Store protocol is best-effort and does not guarantee data availability.
|
||||
Waku Relay or Waku Filter should still be preferred when online;
|
||||
Waku Store can be used after resuming connectivity:
|
||||
For example, when the dApp starts.
|
||||
|
||||
### [Waku Light Push](https://rfc.vac.dev/spec/19/)
|
||||
|
||||
Waku Light Push enables a client to receive a confirmation when sending a message.
|
||||
|
||||
The Waku Relay protocol sends messages to connected peers but does not provide any information on whether said peers have received messages.
|
||||
This can be an issue when facing potential connectivity issues.
|
||||
For example, when the connection drops easily, or it is connected to a small number of relay peers.
|
||||
|
||||
Waku Light Push allows a client to get a response from a remote peer when sending a message.
|
||||
Note this only guarantees that the remote peer has received the message,
|
||||
it cannot guarantee propagation to the network.
|
||||
|
||||
It also means weaker privacy properties as the remote peer knows the client is the originator of the message.
|
||||
Whereas with Waku Relay, a remote peer would not know whether the client created or forwarded the message.
|
||||
|
||||
You can find Waku Light Push's specifications on [Vac RFC](https://rfc.vac.dev/spec/19/).
|
||||
|
||||
`WAKU2-LIGHTPUSH` is a request/response protocol for this.
|
||||
|
||||
## Additional Protocols
|
||||
|
||||
This is in addition to protocols that specify messages, payloads, and recommended usages.
|
||||
For example:
|
||||
|
||||
- [14/WAKU2-MESSAGE](https://rfc.vac.dev/spec/14) and [26/WAKU2-PAYLOAD](https://rfc.vac.dev/spec/26) for message payloads
|
||||
- [23/WAKU2-TOPICS](https://rfc.vac.dev/spec/23) and [27/WAKU2-PEERS](https://rfc.vac.dev/spec/27) for recommendations around usage
|
||||
|
||||
There are also more experimental libp2p protocols such as
|
||||
[`WAKU-RLN-RELAY`](https://rfc.vac.dev/spec/17/)
|
||||
|
||||
You can find more information on this [here](./6.md).
|
||||
|
|
|
|||
|
|
@ -1,46 +1,49 @@
|
|||
---
|
||||
title: Content Topic and How to Choose One
|
||||
title: Protocols Overview by Example
|
||||
---
|
||||
|
||||
A content topic is used for content based filtering and allows you to filter out the messages that your dApp processes,
|
||||
both when receiving live messages (Relay or Filter) or retrieving historical messages (Store).
|
||||
We have six nodes, A-F.
|
||||
|
||||
The recommended format for content topics is as follows:
|
||||
The protocols initially mounted are indicated as such.
|
||||
|
||||
`/{dapp-name}/{version}/{content-topic-name}/{encoding}`
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant A as A relay(0)
|
||||
participant B as B relay(pubtopic1)(0)
|
||||
participant C as C relay(pubtopic1)(0)
|
||||
participant D as D relay(pubtopic1), store(pubtopic1), filter(0)
|
||||
participant E as E relay, store(0)
|
||||
participant F as F relay, filter(0)
|
||||
|
||||
- `dapp-name`: The name of your dApp, it must be unique to avoid conflict with other dApps.
|
||||
- `version`: We usually start at `1`, useful when introducing breaking changes in your messages.
|
||||
- `content-topic-name`: The actual content topic name to use for filtering.
|
||||
If your dApp uses Waku for several features,
|
||||
you should use a content topic per feature.
|
||||
- `encoding`: The encoding format of the message, [Protobuf](https://developers.google.com/protocol-buffers) is most often used: `proto`.
|
||||
A ->> A: msg1=WakuMessage(contentTopic1, data) [14/WAKU2-MESSAGE] (1)
|
||||
Note right of A: If version=1, encrypt data per [7/WAKU-DATA] (1)
|
||||
|
||||
For example: Your dApp's name is SuperCrypto,
|
||||
it enables users to receive notifications and send private messages.
|
||||
You may want to use the following content topics:
|
||||
F ->> D: FilterRequest(pubtopic1, contentTopic1) [12/WAKU2-FILTER] (2)
|
||||
D ->> D: Subscribe F to filter [12/WAKU2-FILTER] (2)
|
||||
|
||||
- `/supercrypto/1/notification/proto`
|
||||
- `/supercrypto/1/private-message/proto`
|
||||
A ->> B: Publish msg1 on pubtopic1 [11/WAKU2-RELAY] (3)
|
||||
B ->> D: relay msg1 on pubtopic1 [11/WAKU2-RELAY] (3)
|
||||
|
||||
## PubSub topic
|
||||
D ->> D: store: saves msg1 [13/WAKU2-STORE] (4)
|
||||
|
||||
There is another type of a _topic_ in Waku: A pubsub topic is used for routing of messages between the relaying nodes in the Waku network.
|
||||
D ->> F: MessagePush(msg1)[12/WAKU2-FILTER] (5)
|
||||
|
||||
> This section talks more about how networking and relaying of messages is handled by the nodes in the network,
|
||||
> and has little to do with the application layer of Waku.
|
||||
> Feel free to skip ahead this section if you are not interested in the details of how Waku works.
|
||||
E ->> E: E comes online (6)
|
||||
E ->> D: HistoryQuery(pubtopic1, contentTopic1) [13/WAKU2-STORE] (6)
|
||||
D ->> E: HistoryResponse(msg1, ...) [13/WAKU2-STORE] (6)
|
||||
|
||||
The format for a pubsub topic is as follows:
|
||||
`/waku/2/{topic-name}/{encoding}` and the default pubsub topic is `/waku/2/default-waku/proto`.
|
||||
```
|
||||
|
||||
This indicates to:
|
||||
The PubSub topic `pubtopic1` is used for routing (the network uses a default pubsub topic) and indicates that it is subscribed to messages on that topic for relay.Ditto for Waku Store where it indicates that these messages are persisted on that node.
|
||||
|
||||
1. `waku`: Waku problem domain
|
||||
2. `2`: Version is 2
|
||||
3. `default-waku`: Default topic for exchanging WakuMessages
|
||||
4. `proto`: The data field in PubSub is serialized/encoded as Protobuf as determined by WakuMessage
|
||||
1. Node A creates a WakuMessage `msg1` with a ContentTopic `/my-dapp/0/notifications/proto`.
|
||||
|
||||
Unless there’s a good reason, the default PubSub topic is used for all protocols. However, in certain situations other topics may be used.
|
||||
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.
|
||||
|
||||
Using a single PubSub topic ensures a connected network, as well some degree of metadata protection. See [Anonymity/Unlinkability](https://rfc.vac.dev/spec/10/#anonymity--unlinkability) for more details.
|
||||
3. Node A publishes `msg1` on `pubtopic1` and subscribes to that relay topic pick it up. It then gets relayed further from B to D, but not C since it doesn't subscribe to that topic.
|
||||
|
||||
4. Node D saves `msg1` for possible later retrieval by other nodes.
|
||||
|
||||
5. Node D also pushes `msg1` to F, as it has previously subscribed F to this filter.
|
||||
|
||||
6. At a later time, Node E comes online. It then requests messages matching `pubtopic1` and `contentTopic1` from Node D. Node D responds with messages meeting this (and possibly other) criteria.
|
||||
|
|
|
|||
|
|
@ -1,60 +1,95 @@
|
|||
---
|
||||
title: Security Features
|
||||
title: Discovery & Bootstrap Nodes
|
||||
---
|
||||
|
||||
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.
|
||||
Node discovery is the mechanism that enables a Waku node to find other nodes.
|
||||
|
||||
The security models are detailed in the RFC of the protocols.
|
||||
That 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.
|
||||
When starting a Waku node, it needs to connect to other nodes to be able to send, receive and retrieve messages.
|
||||
This means there needs to be a discovery mechanism that enables finding other nodes when its initially not connected to any nodes.
|
||||
This process is called _bootstrapping_.
|
||||
|
||||
Some of the security features of Waku v2 are:
|
||||
Once connected, the node needs to find additional peers to have:
|
||||
|
||||
### Pseudonymity
|
||||
- Enough peers in the Waku Relay mesh (target is 6),
|
||||
- Enough peers in reserve, in case current peers are overloaded or go offline,
|
||||
- Peers with specific Waku capabilities (e.g. Store, Light Push, Filter).
|
||||
|
||||
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.
|
||||
## Predefined Bootstrap Nodes
|
||||
|
||||
### Anonymity / Unlinkability
|
||||
An application using Waku can hardcode the addresses of bootstrap nodes directly in their codebase.
|
||||
|
||||
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:
|
||||
You can choose to use Status' deployed nodes, or run your own.
|
||||
|
||||
**Publisher-Message Unlinkability**:
|
||||
This feature signifies the unlinkability of a publisher to its published messages in the `WAKU-RELAY` protocol.
|
||||
:::info Developers have the choice to run their own [nwaku](https://github.com/status-im/nim-waku/) nodes. Read [Nwaku Service Node](https://github.com/status-im/nwaku/tree/master/docs/operators) to learn how to run your own node.
|
||||
|
||||
**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.
|
||||
**Pros:**
|
||||
|
||||
### Spam protection
|
||||
- Low latency
|
||||
- Low resource requirements
|
||||
|
||||
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.
|
||||
**Cons:**
|
||||
|
||||
There's also further research being done in this domain, including the designing of (RLN (Rate Limiting Nullifiers))[./7.md]
|
||||
- Prone to censorship: node IPs can be blocked
|
||||
- Limited: Static number of nodes
|
||||
- Poor maintainability: Code needs to be changed to update the list
|
||||
|
||||
### Data confidentiality, Integrity, and Authenticity
|
||||
## DNS Discovery
|
||||
|
||||
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.
|
||||
[EIP-1459: Node Discovery via DNS](https://eips.ethereum.org/EIPS/eip-1459) has been implemented in js-waku, nwaku and go-waku with some modification on the [ENR format](https://rfc.vac.dev/spec/31/).
|
||||
|
||||
> `WAKU-NOISE` enables secure channel negotiation over Waku.
|
||||
DNS Discovery enables anyone to register an ENR tree in the `TXT` field of a domain name.
|
||||
|
||||
## Security Considerations
|
||||
_ENR_ is the format used to store node connection details (IP, port, multiaddr, etc).
|
||||
|
||||
**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.
|
||||
This enables a separation of software development and operations as dApp developers can include one or several domain names to use for DNS discovery, while operators can handle the update of the dns record.
|
||||
|
||||
It also enables more decentralized bootstrapping as anyone can register a domain name and publish it for others to use.
|
||||
|
||||
**Pros:**
|
||||
|
||||
- Low latency, low resource requirements,
|
||||
- Bootstrap list can be updated by editing a domain name: no code change is needed,
|
||||
- Can reference to a greater list of nodes by pointing to other domain names in the code or in the ENR tree.
|
||||
|
||||
**Cons:**
|
||||
|
||||
- Prone to censorship: domain names can be blocked,
|
||||
- Limited: Static number of nodes, operators must provide their ENR to the domain owner to get their node listed.
|
||||
|
||||
## Discv5
|
||||
|
||||
Discovery v5 is an ambient peer discovery method for Waku v2: it is decentralized, efficient, actively researched, and has web3 as its main application area.
|
||||
As Discv5 uses [DHT](https://en.wikipedia.org/wiki/Distributed_hash_table) to store ENR records, it is more resilient to censorship than DNS discovery.
|
||||
And one of the main benefits of DHTs is offering a global view over participating nodes. This, in turn, allows sampling random sets of nodes which is important for equally distributing load.
|
||||
|
||||
Without discv5 and similar methods, the bootstrap nodes are used as part of the gossipsub mesh. This might put heavy load on these nodes and further, might open pathways to inference attacks. Discv5, on the other hand, uses the bootstrap nodes merely as an entry to the discovery network and can provide random sets of nodes (sampled from a global view) for bootstrapping or expanding the mesh.
|
||||
|
||||
**_Pros:_**
|
||||
|
||||
- Decentralized; random sampling of nodes from a global view
|
||||
- Actively researched
|
||||
|
||||
**_Cons:_**
|
||||
|
||||
- High resource requirements
|
||||
- Nodes behind restrictive NAT setups cannot run this protocol
|
||||
|
||||
## Peer Exchange
|
||||
|
||||
While discv5 based ambient peer discovery has many desirable properties, resource restricted nodes and nodes behind restrictive NAT setups cannot run discv5 satisfactory.
|
||||
With these nodes in mind, [Peer Exchange](https://rfc.vac.dev/spec/34/) was introduced.
|
||||
|
||||
The main purpose of this protocol is providing resource restricted devices with peers.
|
||||
The peer exchange protocol allows resource restricted nodes (light nodes) to ask for peers from other nodes in the network. This allows light nodes to bootstrap and expand their mesh without relying on discv5 or bootstrap nodes.
|
||||
|
||||
This protocol should only be used if discv5 is infeasible.
|
||||
|
||||
**_Pros:_**
|
||||
|
||||
- Low resource requirements
|
||||
- Decentralized; random sampling of nodes from a global view (via discv5)
|
||||
|
||||
**_Cons:_**
|
||||
|
||||
- Reduced anonymity
|
||||
- Cause load on responder nodes
|
||||
|
|
|
|||
|
|
@ -1,19 +1,11 @@
|
|||
---
|
||||
title: Research in Progress
|
||||
title: Transports in Waku
|
||||
---
|
||||
|
||||
The following features are currently experimental and under research and initial implementation:
|
||||
Waku v2 is built in top of libp2p, and like libp2p it strives to be transport agnostic. We define a set of recommended transports in order to achieve a baseline of interoperability between clients.
|
||||
|
||||
**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.
|
||||
This section describes these recommended transports:
|
||||
|
||||
**Prevention of Denial of Service (DoS) and Node Incentivization**:
|
||||
Denial of service signifies the case where an adversarial node exhausts another node's service capacity (e.g., by making a large number of requests) and makes it unavailable to the rest of the system.
|
||||
DoS attack is to be mitigated through the accounting model as described in [18/WAKU2-SWAP](https://rfc.vac.dev/spec/18).
|
||||
In a nutshell, peers have to pay for the service they obtain from each other.
|
||||
In addition to incentivizing the service provider, accounting also makes DoS attacks costly for malicious peers.
|
||||
The accounting model can be used in `13/WAKU2-STORE` and `12/WAKU2-FILTER` to protect against DoS attacks.
|
||||
|
||||
Additionally, this gives node operators who provide a useful service to the network an incentive to perform that service.
|
||||
- Waku nodes uses TCP to communicate by default. A service node should be using TCP to listen to, and connect to other nodes.
|
||||
- For browser environments, secure websocket is used. Service nodes are encouraged to setup a SSL certificate to enable incoming connections from browser and serve them.
|
||||
- Other protocols such as [WebRTC](https://github.com/waku-org/js-waku/issues/20), [WebTransport](https://github.com/waku-org/js-waku/issues/697) and QUIC have been studied.
|
||||
|
|
|
|||
|
|
@ -1,22 +1,24 @@
|
|||
---
|
||||
title: Waku vs libp2p - what's the difference?
|
||||
title: Content Topic and How to Choose One
|
||||
---
|
||||
|
||||
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.
|
||||
A content topic is used for content based filtering and allows you to filter out the messages that your dApp processes,
|
||||
both when receiving live messages (Relay or Filter) or retrieving historical messages (Store).
|
||||
|
||||
### Waku as a service network
|
||||
The recommended format for content topics is as follows:
|
||||
|
||||
Waku offers incentivization mechanisms to run nodes, whereas libp2p does not.
|
||||
`/{dapp-name}/{version}/{content-topic-name}/{encoding}`
|
||||
|
||||
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.
|
||||
- `dapp-name`: The name of your dApp, it must be unique to avoid conflict with other dApps.
|
||||
- `version`: We usually start at `1`, useful when introducing breaking changes in your messages.
|
||||
- `content-topic-name`: The actual content topic name to use for filtering.
|
||||
If your dApp uses Waku for several features,
|
||||
you should use a content topic per feature.
|
||||
- `encoding`: The encoding format of the message, [Protobuf](https://developers.google.com/protocol-buffers) is most often used: `proto`.
|
||||
|
||||
### Waku as a keyturn solution
|
||||
For example: Your dApp's name is SuperCrypto,
|
||||
it enables users to receive notifications and send private messages.
|
||||
You may want to use the following content topics:
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
- `/supercrypto/1/notification/proto`
|
||||
- `/supercrypto/1/private-message/proto`
|
||||
|
|
|
|||
|
|
@ -0,0 +1,62 @@
|
|||
---
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
Some of the security features of Waku v2 are:
|
||||
|
||||
### 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.
|
||||
|
||||
### 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:
|
||||
|
||||
**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.
|
||||
|
||||
### 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))[./7.md]
|
||||
|
||||
https://github.com/vacp2p/research/issues/148
|
||||
|
||||
### 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.
|
||||
|
||||
> `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.
|
||||
|
|
@ -0,0 +1,23 @@
|
|||
---
|
||||
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.
|
||||
|
||||
We have prepared a PoC implementation of this method in JS: https://examples.waku.org/rln-js/
|
||||
|
||||
**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.
|
||||
|
||||
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
|
||||
|
|
@ -0,0 +1,22 @@
|
|||
---
|
||||
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.
|
||||
|
||||
### Waku as a service network
|
||||
|
||||
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.
|
||||
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 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
|
||||
|
||||
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.
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 72 KiB |
|
|
@ -24,7 +24,7 @@ const config = {
|
|||
// to replace "en" with "zh-Hans".
|
||||
i18n: {
|
||||
defaultLocale: "en",
|
||||
locales: ["en"]
|
||||
locales: ["en"],
|
||||
},
|
||||
|
||||
presets: [
|
||||
|
|
@ -37,25 +37,25 @@ const config = {
|
|||
sidebarPath: require.resolve("./sidebars.js"),
|
||||
// Please change this to your repo.
|
||||
// Remove this to remove the "edit this page" links.
|
||||
editUrl: "https://github.com/waku-org/waku.guide/tree/staging/"
|
||||
editUrl: "https://github.com/waku-org/waku.guide/tree/staging/",
|
||||
},
|
||||
theme: {
|
||||
customCss: require.resolve("./src/css/custom.css")
|
||||
}
|
||||
})
|
||||
]
|
||||
customCss: require.resolve("./src/css/custom.css"),
|
||||
},
|
||||
}),
|
||||
],
|
||||
],
|
||||
themeConfig: {
|
||||
colorMode: {
|
||||
defaultMode: "dark",
|
||||
disableSwitch: false,
|
||||
respectPrefersColorScheme: true
|
||||
respectPrefersColorScheme: true,
|
||||
},
|
||||
navbar: {
|
||||
title: "Waku",
|
||||
logo: {
|
||||
alt: "Waku Logo",
|
||||
src: "img/logo.svg"
|
||||
src: "img/logo.svg",
|
||||
},
|
||||
|
||||
items: [
|
||||
|
|
@ -63,9 +63,9 @@ const config = {
|
|||
type: "doc",
|
||||
docId: "Concepts/1",
|
||||
position: "left",
|
||||
label: "Concepts"
|
||||
}
|
||||
]
|
||||
label: "Concepts",
|
||||
},
|
||||
],
|
||||
},
|
||||
footer: {
|
||||
style: "dark",
|
||||
|
|
@ -75,26 +75,30 @@ const config = {
|
|||
items: [
|
||||
{
|
||||
label: "Discourse",
|
||||
href: "https://forum.vac.dev/"
|
||||
href: "https://forum.vac.dev/",
|
||||
},
|
||||
{
|
||||
label: "Discord",
|
||||
href: "https://discord.gg/j5pGbn7MHZ"
|
||||
href: "https://discord.gg/j5pGbn7MHZ",
|
||||
},
|
||||
{
|
||||
label: "Twitter",
|
||||
href: "https://twitter.com/waku-org"
|
||||
}
|
||||
]
|
||||
}
|
||||
href: "https://twitter.com/waku-org",
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
copyright: `Copyright © ${new Date().getFullYear()} Status Gmbh. Built with Docusaurus.`
|
||||
copyright: `Copyright © ${new Date().getFullYear()} Status Gmbh. Built with Docusaurus.`,
|
||||
},
|
||||
prism: {
|
||||
theme: lightCodeTheme,
|
||||
darkTheme: darkCodeTheme
|
||||
}
|
||||
}
|
||||
darkTheme: darkCodeTheme,
|
||||
},
|
||||
},
|
||||
themes: ["@docusaurus/theme-mermaid"],
|
||||
markdown: {
|
||||
mermaid: true,
|
||||
},
|
||||
};
|
||||
|
||||
module.exports = config;
|
||||
|
|
|
|||
File diff suppressed because it is too large
Load Diff
13
package.json
13
package.json
|
|
@ -12,20 +12,25 @@
|
|||
"serve": "docusaurus serve",
|
||||
"write-translations": "docusaurus write-translations",
|
||||
"write-heading-ids": "docusaurus write-heading-ids",
|
||||
"typecheck": "tsc"
|
||||
"typecheck": "tsc",
|
||||
"check:spell": "cspell \"**/*.{md,mdx}\""
|
||||
},
|
||||
"dependencies": {
|
||||
"@docusaurus/core": "2.0.1",
|
||||
"@docusaurus/preset-classic": "2.0.1",
|
||||
"@docusaurus/core": "2.2.0",
|
||||
"@docusaurus/preset-classic": "2.2.0",
|
||||
"@docusaurus/theme-mermaid": "^2.2.0",
|
||||
"@mdx-js/react": "^1.6.22",
|
||||
"clsx": "^1.2.1",
|
||||
"mermaid": "^9.2.2",
|
||||
"prism-react-renderer": "^1.3.5",
|
||||
"react": "^17.0.2",
|
||||
"react-dom": "^17.0.2"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@docusaurus/module-type-aliases": "2.0.1",
|
||||
"@docusaurus/module-type-aliases": "2.2.0",
|
||||
"@docusaurus/types": "^2.2.0",
|
||||
"@tsconfig/docusaurus": "^1.0.5",
|
||||
"cspell": "^6.16.0",
|
||||
"husky": "^8.0.2",
|
||||
"lint-staged": "^13.0.3",
|
||||
"prettier": "^2.7.1",
|
||||
|
|
|
|||
Loading…
Reference in New Issue