mirror of https://github.com/vacp2p/rfc.git
rename mailserver to history node
Signed-off-by: Jakub Sokołowski <jakub@status.im>
This commit is contained in:
parent
e624b2b2a0
commit
93775000f1
|
|
@ -20,7 +20,7 @@ Waku is a protocol that substitutes [EIP-627](https://eips.ethereum.org/EIPS/eip
|
|||
|
||||
- [waku](./specs/waku/waku.md) - ÐΞVp2p wire protocol, substituting [EIP-627](https://eips.ethereum.org/EIPS/eip-627).
|
||||
- [envelope data format](./specs/waku/envelope-data-format.md) - [waku](./specs/waku/waku.md) envelope data field specification.
|
||||
- [mailserver](./specs/waku/mailserver.md) - Mailserver specification for archiving and delivering historical [waku](./specs/waku/waku.md) envelopes on demand.
|
||||
- [history node](./specs/waku/historynode.md) - History node specification for archiving and delivering historical [waku](./specs/waku/waku.md) envelopes on demand.
|
||||
|
||||
## Style guide
|
||||
|
||||
|
|
|
|||
|
|
@ -3,5 +3,5 @@
|
|||
- [waku/0](./waku-0.md) specs for `waku/0` version, now deprecated
|
||||
- [waku/1](./waku-1.md) specs for `waku/1` version, current stable version
|
||||
- [envelope data format](./envelope-data-format.md) - [waku](./waku.md) envelope data field specification.
|
||||
- [mailserver](./mailserver.md) - Mailserver specification for archiving and delivering historical [waku](./waku.md) envelopes on demand.
|
||||
- [history node](./historynode.md) - History node specification for archiving and delivering historical [waku](./waku.md) envelopes on demand.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,10 +1,10 @@
|
|||
---
|
||||
title: Waku Mailserver
|
||||
title: Waku History Node
|
||||
version: 0.2.0
|
||||
status: Draft
|
||||
authors: Adam Babik <adam@status.im>, Dean Eigenmann <dean@status.im>, Oskar Thorén <oskar@status.im>
|
||||
redirect_from:
|
||||
- /waku/mailserver.html
|
||||
- /waku/historynode.html
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
|
@ -18,17 +18,17 @@ redirect_from:
|
|||
|
||||
## Abstract
|
||||
|
||||
In this specification, we describe Mailservers. These are nodes responsible for archiving envelopes and delivering them to peers on-demand.
|
||||
In this specification, we describe History nodes. These are nodes responsible for archiving envelopes and delivering them to peers on-demand.
|
||||
|
||||
## Specification
|
||||
|
||||
A node which wants to provide mailserver functionality MUST store envelopes from incoming Messages packets (Waku packet-code `0x01`). The envelopes can be stored in any format, however they MUST be serialized and deserialized to the Waku envelope format.
|
||||
A node which wants to provide history node functionality MUST store envelopes from incoming Messages packets (Waku packet-code `0x01`). The envelopes can be stored in any format, however they MUST be serialized and deserialized to the Waku envelope format.
|
||||
|
||||
A mailserver SHOULD store envelopes for all topics to be generally useful for any peer, however for specific use cases it MAY store envelopes for a subset of topics.
|
||||
A history node SHOULD store envelopes for all topics to be generally useful for any peer, however for specific use cases it MAY store envelopes for a subset of topics.
|
||||
|
||||
### Requesting Historic Envelopes
|
||||
|
||||
In order to request historic envelopes, a node MUST send a packet P2P Request (`0x7e`) to a peer providing mailserver functionality. This packet requires one argument which MUST be a Waku envelope.
|
||||
In order to request historic envelopes, a node MUST send a packet P2P Request (`0x7e`) to a peer providing history node functionality. This packet requires one argument which MUST be a Waku envelope.
|
||||
|
||||
In the Waku envelope's payload section, there MUST be RLP-encoded information about the details of the request:
|
||||
|
||||
|
|
@ -61,21 +61,21 @@ payload-with-topic = "[" lower upper bloom limit cursor [ topics ] "]"
|
|||
payload = payload-with-topic | payload-without-topic
|
||||
```
|
||||
|
||||
The `Cursor` field SHOULD be filled in if a number of envelopes between `Lower` and `Upper` is greater than `Limit` so that the requester can send another request using the obtained `Cursor` value. What exactly is in the `Cursor` is up to the implementation. The requester SHOULD NOT use a `Cursor` obtained from one mailserver in a request to another mailserver because the format or the result MAY be different.
|
||||
The `Cursor` field SHOULD be filled in if a number of envelopes between `Lower` and `Upper` is greater than `Limit` so that the requester can send another request using the obtained `Cursor` value. What exactly is in the `Cursor` is up to the implementation. The requester SHOULD NOT use a `Cursor` obtained from one history node in a request to another history node because the format or the result MAY be different.
|
||||
|
||||
The envelope MUST be encrypted with a symmetric key agreed between the requester and Mailserver.
|
||||
The envelope MUST be encrypted with a symmetric key agreed between the requester and history node.
|
||||
|
||||
If `Topics` is used the `Cursor` field MUST be specified for the argument order to be unambiguous. However, it MAY be set to `null`. `Topics` is used to specify which topics a node is interested in. If `Topics` is not empty, a mailserver MUST only send envelopes that belong to a topic from `Topics` list and `Bloom` value MUST be ignored.
|
||||
If `Topics` is used the `Cursor` field MUST be specified for the argument order to be unambiguous. However, it MAY be set to `null`. `Topics` is used to specify which topics a node is interested in. If `Topics` is not empty, a history node MUST only send envelopes that belong to a topic from `Topics` list and `Bloom` value MUST be ignored.
|
||||
|
||||
### Receiving Historic Envelopes
|
||||
|
||||
Historic envelopes MUST be sent to a peer as a packet with a P2P Message code (`0x7f`) followed by an array of Waku envelopes. A Mailserver MUST limit the amount of messages sent, either by the `Limit` specified in the request or limited to the maximum [RLPx packet size](./waku#maximum-packet-size), whichever limit comes first.
|
||||
Historic envelopes MUST be sent to a peer as a packet with a P2P Message code (`0x7f`) followed by an array of Waku envelopes. A history node MUST limit the amount of messages sent, either by the `Limit` specified in the request or limited to the maximum [RLPx packet size](./waku#maximum-packet-size), whichever limit comes first.
|
||||
|
||||
In order to receive historic envelopes from a mailserver, a node MUST trust the selected mailserver, that is allow to receive expired packets with the P2P Message code. By default, such packets are discarded.
|
||||
In order to receive historic envelopes from a history node, a node MUST trust the selected history node, that is allow to receive expired packets with the P2P Message code. By default, such packets are discarded.
|
||||
|
||||
Received envelopes MUST be passed through the Whisper envelope pipelines so that they are picked up by registered filters and passed to subscribers.
|
||||
|
||||
For a requester, to know that all envelopes have been sent by mailserver, it SHOULD handle P2P Request Complete code (`0x7d`). This code is followed by a list with:
|
||||
For a requester, to know that all envelopes have been sent by history node, it SHOULD handle P2P Request Complete code (`0x7d`). This code is followed by a list with:
|
||||
|
||||
```abnf
|
||||
; array with a Keccak-256 hash of the envelope containing the original request.
|
||||
|
|
@ -94,19 +94,19 @@ If `Cursor` is not empty, it means that not all envelopes were sent due to the s
|
|||
|
||||
### Security considerations
|
||||
|
||||
There are several security considerations to take into account when running or interacting with Mailservers. Chief among them are: scalability, DDoS-resistance and privacy.
|
||||
There are several security considerations to take into account when running or interacting with History nodes. Chief among them are: scalability, DDoS-resistance and privacy.
|
||||
|
||||
**Mailserver High Availability requirement:**
|
||||
**History Node High Availability requirement:**
|
||||
|
||||
A mailserver has to be online to receive envelopes for other nodes, this puts a high availability requirement on it.
|
||||
A history node has to be online to receive envelopes for other nodes, this puts a high availability requirement on it.
|
||||
|
||||
**Mailserver client privacy:**
|
||||
**history node client privacy:**
|
||||
|
||||
A mailserver client has to trust a mailserver, which means they can send direct traffic. This reveals what topics / bloom filter a node is interested in, along with its peerID (with IP).
|
||||
A history node client has to trust a history node, which means they can send direct traffic. This reveals what topics / bloom filter a node is interested in, along with its peerID (with IP).
|
||||
|
||||
**Mailserver trusted connection:**
|
||||
**History node trusted connection:**
|
||||
|
||||
A mailserver has a direct TCP connection, which means they are trusted to send traffic. This means a malicious or malfunctioning mailserver can overwhelm an individual node.
|
||||
A history node has a direct TCP connection, which means they are trusted to send traffic. This means a malicious or malfunctioning history node can overwhelm an individual node.
|
||||
|
||||
## Changelog
|
||||
|
||||
|
|
@ -52,7 +52,7 @@ redirect_from:
|
|||
|
||||
## Abstract
|
||||
|
||||
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.
|
||||
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 history node) (c) expressing topic interest for better bandwidth usage and (d) basic rate limiting.
|
||||
|
||||
## Motivation
|
||||
|
||||
|
|
@ -77,7 +77,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 [mailserver](./mailserver.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 [history node](./historynode.md) response. A node SHOULD NOT send an envelope to a peer that it has already sent before.
|
||||
|
||||
### Maximum Packet Size
|
||||
|
||||
|
|
@ -178,7 +178,7 @@ nonce = 8OCTET
|
|||
|
||||
messages = 1*waku-envelope
|
||||
|
||||
; mail server / client specific
|
||||
; history node / client specific
|
||||
p2p-request = waku-envelope
|
||||
p2p-message = 1*waku-envelope
|
||||
|
||||
|
|
@ -383,17 +383,17 @@ 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](./mailserver.md).
|
||||
This packet is used for sending Dapp-level peer-to-peer requests, e.g. Waku History Client requesting historic (expired) envelopes from the [Waku History Node](./historynode.md).
|
||||
|
||||
#### P2P Message
|
||||
|
||||
This packet is used for sending the peer-to-peer envelopes, which are not supposed to be forwarded any further. E.g. it might be used by the Waku Mail Server for delivery of historic (expired) envelopes, which is otherwise not allowed.
|
||||
This packet is used for sending the peer-to-peer envelopes, which are not supposed to be forwarded any further. E.g. it might be used by the Waku History Server for delivery of historic (expired) envelopes, which is otherwise not allowed.
|
||||
|
||||
#### P2P Request Complete
|
||||
|
||||
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](./mailserver.md) specification.
|
||||
The content of the packet is explained in the [Waku History node](./historynode.md) specification.
|
||||
|
||||
### Payload Encryption
|
||||
|
||||
|
|
@ -407,13 +407,13 @@ Packet codes `0x00` and `0x01` are already used in all Waku / Whisper versions.
|
|||
|
||||
Packet code `0x22` is used to dynamically change the settings of a node.
|
||||
|
||||
Packet codes `0x7E` and `0x7F` may be used to implement Waku Mail Server and Client. Without the P2P Message packet it would be impossible to deliver the historic envelopes, since they will be recognized as expired, and the peer will be disconnected for violating the Waku protocol. They might be useful for other purposes when it is not possible to spend time on PoW, e.g. if a stock exchange will want to provide live feed about the latest trades.
|
||||
Packet codes `0x7E` and `0x7F` may be used to implement Waku History Server and Client. Without the P2P Message packet it would be impossible to deliver the historic envelopes, since they will be recognized as expired, and the peer will be disconnected for violating the Waku protocol. They might be useful for other purposes when it is not possible to spend time on PoW, e.g. if a stock exchange will want to provide live feed about the latest trades.
|
||||
|
||||
## Additional capabilities
|
||||
|
||||
Waku supports multiple capabilities. These include light node, rate limiting and bridging of traffic. Here we list these capabilities, how they are identified, what properties they have and what invariants they must maintain.
|
||||
|
||||
Additionally there is the capability of a mailserver which is documented in its on [specification](mailserver.md).
|
||||
Additionally there is the capability of a history node which is documented in its on [specification](historynode.md).
|
||||
|
||||
### Light node
|
||||
|
||||
|
|
@ -492,7 +492,7 @@ It is desirable to have a strategy for maintaining forward compatibility between
|
|||
|
||||
## Appendix A: Security considerations
|
||||
|
||||
There are several security considerations to take into account when running Waku. Chief among them are: scalability, DDoS-resistance and privacy. These also vary depending on what capabilities are used. The security considerations for extra capabilities such as [mailservers](./mailserver.md#security-considerations) can be found in their respective specifications.
|
||||
There are several security considerations to take into account when running Waku. Chief among them are: scalability, DDoS-resistance and privacy. These also vary depending on what capabilities are used. The security considerations for extra capabilities such as [history nodes](./historynode.md#security-considerations) can be found in their respective specifications.
|
||||
|
||||
### Scalability and UX
|
||||
|
||||
|
|
@ -628,7 +628,7 @@ Released [December 10, 2019](https://github.com/vacp2p/specs/blob/waku-0.2.0/wak
|
|||
|
||||
- General style improvements.
|
||||
- Fix ABNF grammar.
|
||||
- Mailserver requesting/receiving.
|
||||
- History node requesting/receiving.
|
||||
- New packet codes: topic-interest (experimental), rate limits (experimental).
|
||||
- More details on handshake modifications.
|
||||
- Accounting for resources mode (experimental)
|
||||
|
|
@ -636,7 +636,7 @@ Released [December 10, 2019](https://github.com/vacp2p/specs/blob/waku-0.2.0/wak
|
|||
- Appendix with implementation notes and implementation matrix across various clients with breakdown per capability.
|
||||
- More details on handshake and parameters.
|
||||
- Describe rate limits in more detail.
|
||||
- More details on mailserver and mail client API.
|
||||
- More details on history node and history client API.
|
||||
- Accounting for resources mode (very experimental).
|
||||
- Clarify differences with Whisper.
|
||||
|
||||
|
|
@ -653,7 +653,7 @@ Summary of main differences between this spec and Whisper v6, as described in [E
|
|||
- Optional rate limiting is added.
|
||||
- Status packet has following additional parameters: light-node,
|
||||
confirmations-enabled and rate-limits
|
||||
- Mail Server and Mail Client functionality is now part of the specification.
|
||||
- History Server and History Client functionality is now part of the specification.
|
||||
- P2P Message packet contains a list of envelopes instead of a single envelope.
|
||||
|
||||
## Copyright
|
||||
|
|
|
|||
|
|
@ -61,8 +61,8 @@ libp2p
|
|||
lifecycle
|
||||
LLC
|
||||
localHash
|
||||
mailserver
|
||||
mailservers
|
||||
historynode
|
||||
historynodes
|
||||
Markou
|
||||
metainformation
|
||||
Mey
|
||||
|
|
|
|||
Loading…
Reference in New Issue