Skip to content

Commit

Permalink
feat: improvements on docs (#24)
Browse files Browse the repository at this point in the history 
* 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 <[email protected]>

* Update docs/Concepts/2.md

Co-authored-by: fryorcraken.eth <[email protected]>

* Update docs/Concepts/2.md

Co-authored-by: fryorcraken.eth <[email protected]>

* Update docs/Concepts/7.md

Co-authored-by: fryorcraken.eth <[email protected]>

* Update docs/Concepts/7.md

Co-authored-by: fryorcraken.eth <[email protected]>

* 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 <[email protected]>
  • Loading branch information
@danisharora099 @fryorcraken
danisharora099 and fryorcraken committed Jan 23, 2023
1 parent 3e27f8f commit 671674d
Show file tree
Hide file tree
Showing 16 changed files with 25,469 additions and 8,868 deletions.
43 changes: 39 additions & 4 deletions .cspell.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -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.*/"
Expand Down
24 changes: 24 additions & 0 deletions .github/workflows/ci.yml
View file
Original file line number Diff line number Diff line change
@@ -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
70 changes: 14 additions & 56 deletions docs/Concepts/1.md
View file
Original file line number Diff line number Diff line change
@@ -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.
70 changes: 64 additions & 6 deletions docs/Concepts/2.md
View file
Original file line number Diff line number Diff line change
@@ -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).
63 changes: 33 additions & 30 deletions docs/Concepts/3.md
View file
Original file line number Diff line number Diff line change
@@ -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.
Loading

0 comments on commit 671674d

Please sign in to comment.