From 7098bb6db91c498330bd29b34a4811ff9ca649ee Mon Sep 17 00:00:00 2001 From: Kim De Mey Date: Mon, 6 Jul 2020 14:55:34 +0200 Subject: [PATCH] Add missing packet types to abnf + abnf minor fixes (#146) --- specs/waku/envelope-data-format.md | 2 +- specs/waku/waku-1.md | 66 +++++++++++++++--------------- wordlist.txt | 1 + 3 files changed, 36 insertions(+), 33 deletions(-) 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/wordlist.txt b/wordlist.txt index 3ddb60ec..53815a1a 100644 --- a/wordlist.txt +++ b/wordlist.txt @@ -128,6 +128,7 @@ ttl uint underspecified unencrypted +unsynchronized upgradability UX vac