release: v0.1.0

First cut release. Snapshots ./src/ as ./versions/v0.1.0/ via `just cut-version v0.1.0` (22 files: 21 chapter MDs + SUMMARY.md). Deployed alongside `latest` at: https://swaits.github.io/meshcore-spec/v0.1.0/ Also: - CHANGELOG.md adopts Keep a Changelog-style version sections. Future entries land under [Unreleased] and graduate to a version heading when cut. The existing date-stamped pass entries stay put as a historical record of the work captured in v0.1.0. - README.md fixes a stale "per vX.Y.Z tag" mention left over from the tag-based versioning model, and links the current release explicitly. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-12 10:04:40 -06:00
1 parent 74864761fa
commit 44305a06db
@@ -0,0 +1,125 @@
+# MeshCore Protocol Specification
+
+## Section 2: Header
+
+### Overview
+
+The header is the first byte of every MeshCore packet. It encodes three fields
+using bit packing: the route type (2 bits), the payload type (4 bits), and the
+protocol version (2 bits).
+
+### Bit Layout
+
+```
+  Bit:  7   6   5   4   3   2   1   0
+      +---+---+---+---+---+---+---+---+
+      | V1  V0| P3  P2  P1  P0| R1  R0|
+      +---+---+---+---+---+---+---+---+
+             |         |           |
+             |         |           +-- Route Type (bits 0-1)
+             |         +-------------- Payload Type (bits 2-5)
+             +------------------------ Protocol Version (bits 6-7)
+```
+
+The header byte value is computed as:
+
+```
+header = (version << 6) | (payload_type << 2) | route_type
+```
+
+And fields are extracted as:
+
+```
+route_type   = header & 0x03
+payload_type = (header >> 2) & 0x0F
+version      = (header >> 6) & 0x03
+```
+
+### Route Type (bits 0-1)
+
+The route type determines how the packet is routed through the mesh and whether
+transport codes are present.
+
+| Value | Name | Transport Codes | Description |
+|-------|------|----------------|-------------|
+| 0x00 | TRANSPORT_FLOOD | Yes (4 bytes) | Flood routing with transport codes for regional scoping |
+| 0x01 | FLOOD | No | Standard flood routing; path is built up by intermediate nodes |
+| 0x02 | DIRECT | No | Direct routing; path is supplied by the sender |
+| 0x03 | TRANSPORT_DIRECT | Yes (4 bytes) | Direct routing with transport codes |
+
+Transport codes MUST be present in the wire format when route type is 0x00 or
+0x03, and MUST NOT be present when route type is 0x01 or 0x02.
+
+### Payload Type (bits 2-5)
+
+The payload type identifies the structure of the payload data.
+
+| Value | Name | Description |
+|-------|------|-------------|
+| 0x00 | REQUEST | Encrypted request (dest_hash + src_hash + MAC + ciphertext) |
+| 0x01 | RESPONSE | Encrypted response to REQ or ANON_REQ |
+| 0x02 | TXT_MSG | Encrypted text message |
+| 0x03 | ACK | Simple acknowledgment (4-byte CRC) |
+| 0x04 | ADVERT | Node identity advertisement |
+| 0x05 | GRP_TXT | Encrypted group text message |
+| 0x06 | GRP_DATA | Encrypted group datagram |
+| 0x07 | ANON_REQ | Anonymous request (full public key instead of hash) |
+| 0x08 | PATH | Encrypted returned path information |
+| 0x09 | TRACE | Path trace with per-hop SNR collection |
+| 0x0A | MULTIPART | One part of a multi-packet sequence |
+| 0x0B | CONTROL | Control/discovery packet |
+| 0x0C | (reserved) | Reserved for future use |
+| 0x0D | (reserved) | Reserved for future use |
+| 0x0E | (reserved) | Reserved for future use |
+| 0x0F | RAW_CUSTOM | Custom raw bytes for application-defined payloads |
+
+Implementations SHOULD silently discard packets with reserved payload type values
+(0x0C-0x0E) unless they have explicit support for extended types.
+
+### Protocol Version (bits 6-7)
+
+| Value | Name | Description |
+|-------|------|-------------|
+| 0x00 | V1 | Current version: 1-byte src/dest hashes, 2-byte MAC |
+| 0x01 | V2 | Reserved for future use |
+| 0x02 | V3 | Reserved for future use |
+| 0x03 | V4 | Reserved for future use |
+
+Implementations MUST support version 0x00 (V1). Implementations SHOULD reject
+packets with unrecognized version values.
+
+### Special Header Values
+
+The header value `0xFF` is used internally as a "do not retransmit" marker. This
+is an in-memory sentinel only and MUST NOT appear on the wire. A header of
+`0xFF` would decode as version=3, payload_type=0x0F (RAW_CUSTOM), route_type=3
+(TRANSPORT_DIRECT).
+
+### Encoding Examples
+
+| Header Byte | Binary | Version | Payload Type | Route Type |
+|-------------|--------|---------|-------------|------------|
+| `0x01` | `00 000000 01` | V1 (0) | REQUEST (0) | FLOOD (1) |
+| `0x05` | `00 000001 01` | V1 (0) | RESPONSE (1) | FLOOD (1) |
+| `0x09` | `00 000010 01` | V1 (0) | TXT_MSG (2) | FLOOD (1) |
+| `0x0D` | `00 000011 01` | V1 (0) | ACK (3) | FLOOD (1) |
+| `0x11` | `00 000100 01` | V1 (0) | ADVERT (4) | FLOOD (1) |
+| `0x0C` | `00 000011 00` | V1 (0) | ACK (3) | TRANSPORT_FLOOD (0) |
+| `0x0E` | `00 000011 10` | V1 (0) | ACK (3) | DIRECT (2) |
+| `0x0F` | `00 000011 11` | V1 (0) | ACK (3) | TRANSPORT_DIRECT (3) |
+| `0x4D` | `01 000011 01` | V2 (1, reserved) | ACK (3) | FLOOD (1) |
+
+### Cross-References
+
+- [Section 1: Wire Format](01-wire-format.md) — Overall packet structure
+- [Section 3: Path](03-path.md) — Path encoding
+- Test vectors: `corpus/wire-format/header/`
+
+### Reference Implementation
+
+- `Packet::getRouteType()` in `src/Packet.h` — `header & 0x03`
+- `Packet::getPayloadType()` in `src/Packet.h` — `(header >> 2) & 0x0F`
+- `Packet::getPayloadVer()` in `src/Packet.h` — `(header >> 6) & 0x03`
+- `Packet::hasTransportCodes()` in `src/Packet.h` — route type 0x00 or 0x03
+- Route type constants in `src/Packet.h`
+- Payload type constants in `src/Packet.h`