meshcore-dev/MeshCore
1
0
Fork 0
mirror of https://github.com/meshcore-dev/MeshCore.git synced 2026-04-20 22:13:47 +00:00
Code Issues Projects Releases Packages Wiki Activity

Merge pull request #431 from mattsains/packet-structure

Browse source 
minor changes and fixes to docs
This commit is contained in:
ripplebiz 2025-06-21 13:54:53 +10:00 • committed by GitHub
commit 5b1f4b0166
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 45 additions and 31 deletions
Download patch file Download diff file Expand all files Collapse all files

19
docs/packet_structure.md
View file

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

57
docs/payloads.md
View file

@ -1,25 +1,29 @@
# Meshcore payloads # 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: 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). * Request (destination/source hashes + MAC).
* Response to REQ or ANON_REQ. * Response to REQ or ANON_REQ.
* Plain text message. * Plain text message.
* Acknowledgment. * Anonymous request.
* Node advertisement.
* Group text message (unverified). * Group text message (unverified).
* Group datagram (unverified). * Group datagram (unverified).
* Anonymous request.
* Returned path.
* Custom packet (raw bytes, custom encryption). * Custom packet (raw bytes, custom encryption).
This document defines the structure of each of these payload types 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 # Node advertisement
This kind of payload notifies receivers that a node exists, and gives information about the node This kind of payload notifies receivers that a node exists, and gives information about the node
| Field | Size (bytes) | Description | | 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 | | timestamp | 4 | unix timestamp of advertisement |
| signature | 64 | Ed25519 signature of public key, timestamp, and app data | | signature | 64 | Ed25519 signature of public key, timestamp, and app data |
| appdata | rest of payload | optional, see below | | appdata | rest of payload | optional, see below |
@ -37,20 +41,29 @@ Appdata
Appdata Flags Appdata Flags
| Value | Name | Description | | Value | Name | Description |
|--------|-----------|---------------------------------------| |--------|----------------|---------------------------------------|
| `0x10` | location | appdata contains lat/long information | | `0x01` | is chat node | advert is for a chat node |
| `0x20` | feature 1 | Reserved for future use. | | `0x02` | is repeater | advert is for a repeater |
| `0x40` | feature 2 | Reserved for future use. | | `0x03` | is room server | advert is for a room server |
| `0x80` | name | appdata contains a node name | | `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 # 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 | | Field | Size (bytes) | Description |
|----------|--------------|------------------------------------------------------------| |----------|--------------|------------------------------------------------------------|
| checksum | 4 | CRC checksum of message timestamp, text, and sender pubkey | | 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 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 | | Field | Size (bytes) | Description |
|------------------|-----------------|------------------------------------------------------| |------------------|-----------------|------------------------------------------------------|
| destination hash | 1 | first byte of destination node public key | | destination hash | 1 | first byte of destination node public key |
@ -60,11 +73,13 @@ Appdata Flags
## Returned path ## 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 | | Field | Size (bytes) | Description |
|-------------|--------------|----------------------------------------------------------------------------------------------| |-------------|--------------|----------------------------------------------------------------------------------------------|
| path length | 1 | length of next field | | 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 | | path | see above | a list of node hashes (one byte each) |
| extra type | 1 | extra, bundled payload type, eg., acknowledgement or response. See packet structure spec | | 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 | | extra | rest of data | extra, bundled payload content, follows same format as main content defined by this document |
## Request ## Request
@ -156,18 +171,14 @@ Plaintext message
# Group text message / datagram # Group text message / datagram
| Field | Size (bytes) | Description | | Field | Size (bytes) | Description |
|--------------|-----------------|------------------------------------------| |--------------|-----------------|--------------------------------------------|
| channel hash | 1 | TODO | | channel hash | 1 | the first byte of the channel's public key |
| cipher MAC | 2 | MAC for encrypted data in next field | | cipher MAC | 2 | MAC for encrypted data in next field |
| ciphertext | rest of payload | encrypted message, see below for details | | 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 TODO: describe what datagram looks like