MeshCore Protocol Specification

Section 3: Path

Overview

The path field carries routing information as a sequence of node hashes. In flood routing, intermediate nodes append their hash to the path as they forward the packet. In direct routing, the sender supplies the full path. The path length byte uses bit packing to encode both the number of hashes and the size of each hash.

Path Length Byte

The path length byte immediately follows the header (and transport codes, if present). It encodes two values:

  Bit:  7   6   5   4   3   2   1   0
      +---+---+---+---+---+---+---+---+
      | S1  S0| C5  C4  C3  C2  C1  C0|
      +---+---+---+---+---+---+---+---+
             |              |
             |              +-- Hash Count (bits 0-5): 0-63
             +----------------- Hash Size Code (bits 6-7): 0-2 (3 is reserved)

The actual hash size in bytes is:

hash_size = (path_len >> 6) + 1

The path length byte is constructed as:

path_len = ((hash_size - 1) << 6) | (hash_count & 0x3F)

Path Field

The path field immediately follows the path length byte. Its size in bytes is:

path_byte_length = hash_count × hash_size

The path contains hash_count consecutive hashes, each hash_size bytes long. Each hash is a prefix of a node’s Ed25519 public key (see Section 15).

+----------+----------+-----+----------+
| Hash 0   | Hash 1   | ... | Hash N-1 |
| (H bytes)| (H bytes)| ... | (H bytes)|
+----------+----------+-----+----------+

where H = hash_size, N = hash_count

When hash_count is 0, the path field is empty (zero bytes on the wire).

Validation Rules

A conforming implementation MUST reject a packet if any of the following are true:

1. Reserved hash size: Hash size code is 3 (bits 6-7 = 0b11), meaning hash_size would be 4. This value is reserved for future use.

2. Path overflow: hash_count × hash_size > MAX_PATH_SIZE (64 bytes).

The maximum number of hashes depends on hash size:

Note: With 1-byte hashes the maximum hash count is 63 (not 64), because the count field is only 6 bits wide. With 2-byte hashes, 32 × 2 = 64 bytes exactly fills MAX_PATH_SIZE. With 3-byte hashes, 21 × 3 = 63 bytes is the maximum before 22 × 3 = 66 would overflow.

Path Manipulation

Appending a hash (flood routing): When a node forwards a flood-routed packet, it appends its own hash to the path:

1. Let n = current hash_count.
2. Verify (n + 1) × hash_size <= MAX_PATH_SIZE. If not, the node MUST NOT forward the packet.
3. Copy the node’s hash (first hash_size bytes of its public key) to path[n × hash_size].
4. Increment hash_count: setPathHashCount(n + 1).

Setting hash size and count:

path_len = ((hash_size - 1) << 6) | (hash_count & 0x3F)

Encoding Examples

Known Implementation Discrepancy

The Rust implementation meshcore-rs treats the path_len byte as a raw byte count rather than decoding hash_count and hash_size from the bitfields. For example, a path_len value of 0x42 (binary 01 000010) should decode as hash_size=2, hash_count=2, path_bytes=4. The incorrect interpretation reads it as a raw count of 66 bytes.

Test vectors in this corpus specifically exercise multi-byte hash sizes to catch this class of bug.

Cross-References

• Section 1: Wire Format — Overall packet structure
• Section 2: Header — Header encoding
• Section 15: Identity — Hash derivation from public keys
• Test vectors: corpus/wire-format/path/

Reference Implementation

• Packet::getPathHashSize() in src/Packet.h — (path_len >> 6) + 1
• Packet::getPathHashCount() in src/Packet.h — path_len & 63
• Packet::getPathByteLen() in src/Packet.h — getPathHashCount() * getPathHashSize()
• Packet::setPathHashSizeAndCount() in src/Packet.h — ((sz - 1) << 6) | (n & 63)
• Packet::isValidPathLen() in src/Packet.cpp — Validation logic
• Packet::writePath() in src/Packet.cpp — Path serialization