swaits/meshcore-spec

0 Fork 0

Files

T

swaitsandClaude Opus 4.7 9232c16f7c

mdBook / build (push) Canceled after 0s

Details

mdBook / deploy (push) Canceled after 0s

Details

feat(versioning): snapshot corpus per spec version

A frozen spec is only meaningful if it's paired with the corpus
that was current at release time — otherwise a v0.1.0 reader
follows "see corpus/payloads/ack/" and lands on a file whose
test vectors may have changed since v0.1.0 was cut.

Three changes:

1. `cut-version` now copies BOTH src/ AND corpus/ into the
   snapshot directory. A release is the pair, not just the text.

2. The corpus URL rewriting in cut-version now retargets
   /tree/main/corpus -> /tree/main/versions/<v>/corpus (and the
   blob variant). This lets the link resolve on GitHub from main
   alone — no git tag required, since the frozen copy is a real
   path under main. Downgrades the "tag is REQUIRED" message from
   last commit back to "optionally tag the commit".

3. The frozen corpus's spec_ref fields get rewritten too: from
   `src/04-payload-ack.md` to `versions/<v>/04-payload-ack.md`,
   so a reader following a test vector lands on the spec text the
   vector was paired with at release time.

versions/v0.1.0/ regenerated from scratch via `just cut-version v0.1.0`
to pick up the corpus snapshot + the new sed patterns. The release
is now self-consistent: v0.1.0 spec links go to v0.1.0 corpus, which
links back to v0.1.0 spec.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-12 10:38:02 -06:00

2.2 KiB

Raw Permalink Blame History

MeshCore Protocol Specification

Section 16: Packet Hash

Overview

MeshCore uses SHA-256 hashing for packet deduplication. Each node maintains a table of recently seen packet hashes and discards packets it has already processed. The hash is computed over the payload type and payload contents, with a special case for TRACE packets.

Hash Computation

The packet hash is computed as:

hash = SHA-256(payload_type_byte || payload_data)[0..MAX_HASH_SIZE-1]

Where:

payload_type_byte is a single byte: (header >> 2) & 0x0F
payload_data is the raw payload bytes (payload_len bytes)
The SHA-256 output is truncated to MAX_HASH_SIZE (8) bytes

TRACE Packet Special Case

For TRACE packets (payload_type = 0x09), the path_len byte is included in the hash to distinguish trace packets that revisit the same node on their return path:

hash = SHA-256(payload_type_byte || path_len_byte || payload_data)[0..MAX_HASH_SIZE-1]

Algorithm

function calculatePacketHash(packet):
    sha = SHA256_init()
    type_byte = getPayloadType(packet.header)  // single byte
    SHA256_update(sha, type_byte)
    if type_byte == 0x09:  // TRACE
        SHA256_update(sha, packet.path_len)  // 1 byte (as uint8)
    SHA256_update(sha, packet.payload, packet.payload_len)
    hash = SHA256_finalize(sha)
    return hash[0..7]  // first MAX_HASH_SIZE bytes

Properties

The hash does NOT include the header byte, path, or transport codes. This means the same logical message received via different routes produces the same hash.
The hash does NOT include the route type or version. Only the payload type and payload content determine the hash.
For TRACE packets, including path_len ensures that the same trace payload at different stages of traversal produces different hashes.

Cross-References

Section 10: Trace — TRACE packet special handling
Test vectors: corpus/crypto/sha256/packet-hash.json

Reference Implementation

Packet::calculatePacketHash() in src/Packet.cpp
MeshTables::hasSeen() — Deduplication table lookup

2.2 KiB Raw Permalink Blame History