diff --git a/specs/waku/envelope-data-format.md b/specs/waku/envelope-data-format.md index 21e937fb..d20d813f 100644 --- a/specs/waku/envelope-data-format.md +++ b/specs/waku/envelope-data-format.md @@ -57,7 +57,7 @@ signature = 65OCTET ; 2 bytes, if present (in case of symmetric encryption). salt = 2OCTET -envelope = flags auxiliary-field payload padding [signature] [salt] +data = flags auxiliary-field payload padding [signature] [salt] ``` ### Signature diff --git a/specs/waku/waku-1.md b/specs/waku/waku-1.md index 271e1e94..96a79b9e 100644 --- a/specs/waku/waku-1.md +++ b/specs/waku/waku-1.md @@ -170,7 +170,7 @@ topic = 4OCTET ; byte array of arbitrary size ; (contains encrypted payload) -data = OCTET +data = *OCTET ; 8 bytes of arbitrary data ; (used for PoW calculation) @@ -178,9 +178,36 @@ nonce = 8OCTET messages = 1*waku-envelope +; version of the confirmation packet +version = 1*DIGIT + +; keccak256 hash of the envelopes batch data (raw bytes) +; for which the confirmation is sent +hash = *OCTET + +hasherror = *OCTET + +; error code +code = 1*DIGIT + +; a descriptive error message +description = *ALPHA + +error = "[" hasherror code description "]" +errors = *error + +response = "[" hash errors "]" + +confirmation = "[" version response "]" + +; message confirmation packet types +batch-ack = confirmation +message-response = confirmation + ; mail server / client specific p2p-request = waku-envelope p2p-message = 1*waku-envelope +p2p-request-complete = *OCTET ; packet-format needs to be paired with its ; corresponding packet-format @@ -342,45 +369,19 @@ When the node's `confirmations-enabled` field is set to true, the node SHOULD se #### Batch Ack and Message Response -Message confirmations tell a node that a envelope originating from it has been received by its peers, allowing a node to know whether an envelope has or has not been received. +Message confirmations tell a node that an envelope originating from it has been received by its peers, allowing a node to know whether an envelope has or has not been received. A node MAY send a message confirmation for any batch of envelopes received with a Messages packet (`0x01`). -A message confirmation is sent using Batch Ack packet (`0x0B`) or Message Response packet (`0x0C`). The message confirmation is specified in the ABNF specification below. +A message confirmation is sent using Batch Ack packet (`0x0B`) or Message Response packet (`0x0C`). The message confirmation is specified in the [ABNF specification](#abnf-specification). -The current `version` of the Message Response is `1`. +The current `version` in the `confirmation` is `1`. -Using [Augmented Backus-Naur form (ABNF)](https://tools.ietf.org/html/rfc5234) we have the following format: - -```abnf -; a version of the Message Response -version = 1*DIGIT - -; keccak256 hash of the envelopes batch data (raw bytes) for which the confirmation is sent -hash = *OCTET - -hasherror = *OCTET - -; error code -code = 1*DIGIT - -; a descriptive error message -description = *ALPHA - -error = "[" hasherror code description "]" -errors = *error - -response = "[" hash errors "]" - -confirmation = "[" version response "]" -``` - -The supported codes: -`1`: means time sync error which happens when an envelope is too old or created in the future (the root cause is no time sync between nodes). +The supported error codes: +- `1`: time sync error which happens when an envelope is too old or was created in the future (typically because of an unsynchronized clock of a node). The drawback of sending message confirmations is that it increases the noise in the network because for each sent envelope, a corresponding confirmation is broadcast by one or more peers. - #### 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). @@ -573,6 +574,7 @@ Known static nodes MAY also be used. - Correct the header hierarchy for the status-options fields. - Consistent use of the words packet, message and envelope. - Added section on max packet size +- Complete the ABNF specification and minor ABNF fixes. ### Version 1.1 diff --git a/specs/waku/waku-v2.md b/specs/waku/waku-v2.md index 9b1ea30e..f68e29f2 100644 --- a/specs/waku/waku-v2.md +++ b/specs/waku/waku-v2.md @@ -47,7 +47,7 @@ map](https://vac.dev/waku-v2-plan). protocol to communicate between different subsystems or different nodes. This messaging can be human-to-human or machine-to-machine or a mix. -2. **Peer-to-peer.**These applications sometimes have requirements that make +2. **Peer-to-peer.** These applications sometimes have requirements that make them suitable for peer-to-peer solutions. 3. **Resource restricted**.These applications often run in constrained @@ -79,8 +79,8 @@ provided for by the environment. ### PubSub interface Waku v2 is implementing the PubSub interface in Libp2p. See [PubSub interface -for libp2p (r2, -2019-02-01)](https://github.com/libp2p/specs/blob/master/pubsub/README.md) for +for libp2p (r2, 2019-02-01)](https://github.com/libp2p/specs/blob/master/pubsub/README.md) +for more details. ### Protocol Identifier @@ -91,10 +91,8 @@ is: `/wakusub/2.0.0-alpha1`. ### FloodSub WakuSub is currently a subprotocol of FloodSub. Future versions of WakuSub will -support [GossipSub -v1.0](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.0.md) -and [GossipSub -1.1](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md). +support [GossipSub v1.0](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.0.md) +and [GossipSub 1.1](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md). ### Bridge mode @@ -206,7 +204,7 @@ TODO(Dean): Fill out this section with historical message API. TODO(Oskar): Update changelog once we are in draft, which is when implementation matches spec -Initial draft version. Released []() +Initial raw version. Released []() ## Copyright diff --git a/wordlist.txt b/wordlist.txt index aa2f5121..407cd5b3 100644 --- a/wordlist.txt +++ b/wordlist.txt @@ -138,6 +138,7 @@ ttl uint underspecified unencrypted +unsynchronized upgradability UX vac