Merge pull request #431 from mattsains/packet-structure

minor changes and fixes to docs

Author: ripplebiz

docs/packet_structure.md

@@ -11,20 +11,22 @@ Note: see the [payloads doc](./payloads.md) for more information about the conte
 
 ## Header Breakdown
 
+bit 0 means the lowest bit (1s place)
+
 | Bits  | Mask   | Field           | Description                                   |
 |-------|--------|-----------------|-----------------------------------------------|
 | 0-1   | `0x03` | Route Type      | Flood, Direct, Reserved - see below.          |
-| 2-5   | `0x0F` | Payload Type    | Request, Response, ACK, etc. - see below.     |
-| 6-7   | `0x03` | Payload Version | Versioning of the payload format - see below. |
+| 2-5   | `0x3C` | Payload Type    | Request, Response, ACK, etc. - see below.     |
+| 6-7   | `0xC0` | Payload Version | Versioning of the payload format - see below. |
 
 ## Route Type Values
 
-| Value  | Name                   | Description                          |
-|--------|------------------------|--------------------------------------|
-| `0x00` | `ROUTE_TYPE_RESERVED1` | Reserved for future use.             |
-| `0x01` | `ROUTE_TYPE_FLOOD`     | Flood routing mode (builds up path). |
-| `0x02` | `ROUTE_TYPE_DIRECT`    | Direct route (path is supplied).     |
-| `0x03` | `ROUTE_TYPE_RESERVED2` | Reserved for future use.             |
+| Value  | Name                          | Description                          |
+|--------|-------------------------------|--------------------------------------|
+| `0x00` | `ROUTE_TYPE_TRANSPORT_FLOOD`  | Flood routing mode + transport codes |
+| `0x01` | `ROUTE_TYPE_FLOOD`            | Flood routing mode (builds up path). |
+| `0x02` | `ROUTE_TYPE_DIRECT`           | Direct route (path is supplied).     |
+| `0x03` | `ROUTE_TYPE_TRANSPORT_DIRECT` | direct route + transport codes       |
 
 ## Payload Type Values
 
@@ -39,6 +41,7 @@ Note: see the [payloads doc](./payloads.md) for more information about the conte
 | `0x06` | `PAYLOAD_TYPE_GRP_DATA`   | Group datagram (unverified).                  |
 | `0x07` | `PAYLOAD_TYPE_ANON_REQ`   | Anonymous request.                            |
 | `0x08` | `PAYLOAD_TYPE_PATH`       | Returned path.                                |
+| `0x09` | `PAYLOAD_TYPE_TRACE`      | trace a path, collecting SNI for each hop.    |
 | `0x0F` | `PAYLOAD_TYPE_RAW_CUSTOM` | Custom packet (raw bytes, custom encryption). |
 
 ## Payload Version Values

docs/payloads.md

@@ -1,25 +1,29 @@
 # Meshcore payloads
 Inside of each [meshcore packet](./packet_structure.md) is a payload, identified by the payload type in the packet header. The types of payloads are:
 
+* Node advertisement.
+* Acknowledgment.
+* Returned path.
 * Request (destination/source hashes + MAC).
 * Response to REQ or ANON_REQ.
 * Plain text message.
-* Acknowledgment.
-* Node advertisement.
+* Anonymous request.
 * Group text message (unverified).
 * Group datagram (unverified).
-* Anonymous request.
-* Returned path.
 * Custom packet (raw bytes, custom encryption).
 
 This document defines the structure of each of these payload types
 
+## Important concepts:
+
+* Node/channel hash: the first byte of the node or channel's public key
+
 # Node advertisement
 This kind of payload notifies receivers that a node exists, and gives information about the node
 
 | Field         | Size (bytes)    | Description                                              |
 |---------------|-----------------|----------------------------------------------------------|
-| public key    | 32              | Ed25519 public key                                       |
+| public key    | 32              | Ed25519 public key of the node                           |
 | timestamp     | 4               | unix timestamp of advertisement                          |
 | signature     | 64              | Ed25519 signature of public key, timestamp, and app data |
 | appdata       | rest of payload | optional, see below                                      |
@@ -37,20 +41,29 @@ Appdata
 
 Appdata Flags
 
-| Value  | Name      | Description                           |
-|--------|-----------|---------------------------------------|
-| `0x10` | location  | appdata contains lat/long information |
-| `0x20` | feature 1 | Reserved for future use.              |
-| `0x40` | feature 2 | Reserved for future use.              |
-| `0x80` | name      | appdata contains a node name          |
+| Value  | Name           | Description                           |
+|--------|----------------|---------------------------------------|
+| `0x01` | is chat node   | advert is for a chat node             |
+| `0x02` | is repeater    | advert is for a repeater              |
+| `0x03` | is room server | advert is for a room server           |
+| `0x10` | has location   | appdata contains lat/long information |
+| `0x20` | has feature 1  | Reserved for future use.              |
+| `0x40` | has feature 2  | Reserved for future use.              |
+| `0x80` | has name       | appdata contains a node name          |
 
 # Acknowledgement
+
+An acknowledgement that a message was received. Note that for returned path messages, an acknowledgement will be sent in the "extra" payload (see [Returned Path](#returned-path)) and not as a discrete ackowledgement. CLI commands do not require an acknowledgement, neither discrete nor extra.
+
 | Field    | Size (bytes) | Description                                                |
 |----------|--------------|------------------------------------------------------------|
 | checksum | 4            | CRC checksum of message timestamp, text, and sender pubkey |
 
 
 # Returned path, request, response, and plain text message
+
+Returned path, request, response, and plain text messages are all formatted in the same way. See the subsection for more details about the ciphertext's associated plaintext representation.
+
 | Field            | Size (bytes)    | Description                                          |
 |------------------|-----------------|------------------------------------------------------|
 | destination hash | 1               | first byte of destination node public key            |
@@ -60,11 +73,13 @@ Appdata Flags
 
 ## Returned path
 
+Returned path messages provide a description of the route a packet took from the original author. Receivers will send returned path messages to the author of the original message.
+
 | Field       | Size (bytes) | Description                                                                                  |
 |-------------|--------------|----------------------------------------------------------------------------------------------|
 | path length | 1            | length of next field                                                                         |
-| path        | see above    | a list of node hashes (one byte each) describing the route from us to the packet author      |
-| extra type  | 1            | extra, bundled payload type, eg., acknowledgement or response. See packet structure spec     |
+| path        | see above    | a list of node hashes (one byte each) |
+| extra type  | 1            | extra, bundled payload type, eg., acknowledgement or response. Same values as in [packet structure](./packet_structure.md) |
 | extra       | rest of data | extra, bundled payload content, follows same format as main content defined by this document |
 
 ## Request
@@ -156,18 +171,14 @@ Plaintext message
 
 # Group text message / datagram
 
-| Field        | Size (bytes)    | Description                              |
-|--------------|-----------------|------------------------------------------|
-| channel hash | 1               | TODO                                     | 
-| cipher MAC   | 2               | MAC for encrypted data in next field     |
-| ciphertext   | rest of payload | encrypted message, see below for details |
+| Field        | Size (bytes)    | Description                                |
+|--------------|-----------------|--------------------------------------------|
+| channel hash | 1               | the first byte of the channel's public key | 
+| cipher MAC   | 2               | MAC for encrypted data in next field       |
+| ciphertext   | rest of payload | encrypted message, see below for details   |
 
-Plaintext for text message
+The plaintext contained in the ciphertext matches the format described in [plain text message](#plain-text-message). Specifically, it consists of a four byte timestamp, a flags byte, and the message. The flags byte will generally be `0x00` because it is a "plain text message". The message will be of the form `<sender name>: <message body>` (eg., `user123: I'm on my way`).
 
-| Field     | Size (bytes)    | Description                      |
-|-----------|-----------------|----------------------------------|
-| timestamp | 4               | send time (unix timestamp)       |
-| content   | rest of message | plain group text message content |
 
 TODO: describe what datagram looks like