From 0d78df1b8a2f45048e3398a752b860426fb3787b Mon Sep 17 00:00:00 2001 From: Matthew Sainsbury Date: Fri, 20 Jun 2025 17:59:55 -0700 Subject: [PATCH] minor changes and fixes to docs --- docs/packet_structure.md | 19 ++++++++++-------- docs/payloads.md | 42 ++++++++++++++++++++++++---------------- 2 files changed, 36 insertions(+), 25 deletions(-) diff --git a/docs/packet_structure.md b/docs/packet_structure.md index b02c3c3..4a28526 100644 --- a/docs/packet_structure.md +++ b/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 diff --git a/docs/payloads.md b/docs/payloads.md index 2c40210..72ce0a8 100644 --- a/docs/payloads.md +++ b/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 | @@ -45,12 +49,18 @@ Appdata Flags | `0x80` | 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 +70,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 +168,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 `: ` (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