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

3.5 KiB

Raw Blame History

MeshCore Protocol Specification

Section 4: Payload — ACK

Overview

The ACK (acknowledgment) payload is the simplest payload type. It consists of a single 4-byte CRC value used to confirm receipt of a previously sent message. The CRC is a truncated SHA-256 over the original TXT_MSG plaintext prefix concatenated with the sender's public key.

Payload Type

Header payload type field: 0x03 (ACK)

Wire Format

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                      ACK CRC (uint32_le)                      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Fields

Field	Offset	Size	Type	Description
ack_crc	0	4 bytes	uint32_le	CRC identifying the acknowledged message

ACK CRC Computation

The 4-byte ACK CRC is computed as the first 4 bytes of a SHA-256 digest over the acknowledged TXT_MSG's plaintext prefix followed by the sender's Ed25519 public key:

ack_crc = SHA-256( plaintext_prefix || sender_pub_key )[0..3]

Where plaintext_prefix is the TXT_MSG plaintext up to and including the message text, excluding any trailing NUL terminator:

plaintext_prefix = timestamp_le(4) || txt_type_attempt(1) || text

timestamp_le and txt_type_attempt are defined in Section 6.
text is the raw UTF-8 message bytes with no NUL terminator.
sender_pub_key is the full 32-byte Ed25519 public key of the node that originated the TXT_MSG (i.e., the node expecting this ACK back).

For TXT_TYPE_SIGNED_PLAIN messages, the 4-byte signature prefix is included:

plaintext_prefix = timestamp_le(4) || txt_type_attempt(1) || signature(4) || text
ack_crc = SHA-256( plaintext_prefix || receiver_pub_key )[0..3]

Note the SIGNED_PLAIN variant hashes against the receiver's public key; see BaseChatMesh::onPeerDataRecv().

Because txt_type_attempt includes the 2-bit attempt counter, each retry with an incremented attempt produces a different ACK CRC. This lets the sender attribute each received ACK to a specific transmission attempt. See Section 6: Reliable DM Delivery.

Encoding

Compute the 4-byte CRC value for the message being acknowledged (above).
Write the CRC as a little-endian 32-bit unsigned integer.
Set payload_len to 4.

Decoding

Read 4 bytes from the payload as a little-endian uint32.
If fewer than 4 bytes are available, the packet is INVALID.

Constraints

The payload MUST be exactly 4 bytes.
Implementations SHOULD log or discard ACK packets with payload_len < 4.

Cross-References

Section 1: Wire Format — Packet framing
Section 11: Multipart — Multipart ACK encoding
Test vectors: corpus/payloads/ack/

Reference Implementation

Mesh::createAck() in src/Mesh.cpp — Packet construction
BaseChatMesh::composeMsgPacket() in src/helpers/BaseChatMesh.cpp — Sender-side expected-ACK computation (expected_ack)
BaseChatMesh::onPeerDataRecv() in src/helpers/BaseChatMesh.cpp — Receiver-side ACK CRC computation (ack_hash)
ACK reception in Mesh::onRecvPacket(), case PAYLOAD_TYPE_ACK

3.5 KiB Raw Blame History