swaitsandClaude Opus 4.7
4a13c12ee9
Prepare the repo for public release by stating openly: - The spec is AI-authored (Claude / Anthropic) under Stephen Waits's direction. It is an independent project, not affiliated with the upstream MeshCore project. - The official MeshCore C++ firmware is the golden source of truth for all protocol behavior; when this spec and upstream disagree, upstream wins. - Clarifications have been driven by observations from building DongLoRa firmware and apps against live deployments, but DongLoRa divergences from upstream are treated as DongLoRa bugs, not spec changes. - Conformance against this corpus is a useful signal but not a substitute for cross-checking against upstream. Tighten Project Status to reference the new section. Add an Author section with attribution. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
102 lines
4.3 KiB
Markdown
102 lines
4.3 KiB
Markdown
# MeshCore Spec
|
|
|
|
A comprehensive specification and conformance test suite for the
|
|
[MeshCore](https://github.com/meshcore-dev/MeshCore) mesh networking protocol.
|
|
|
|
MeshCore Spec aims to be the authoritative, machine-readable definition of the
|
|
MeshCore wire format — much like [RubySpec](https://github.com/ruby/spec) became
|
|
the definitive specification of the Ruby language. Any implementation that passes
|
|
the full test corpus can claim bit-perfect MeshCore compatibility.
|
|
|
|
## Provenance
|
|
|
|
This is an **independent, AI-authored project**. It is not affiliated with,
|
|
endorsed by, or maintained by the upstream MeshCore project. Read this section
|
|
before relying on the spec for anything load-bearing.
|
|
|
|
- **Authorship.** The spec, the corpus, and the tooling were written by Claude
|
|
(Anthropic, primarily Opus 4.x) under the direction of Stephen Waits.
|
|
Substantive edits — additions, clarifications, audit passes — are produced
|
|
through model-driven analysis of the official MeshCore source and reviewed
|
|
before commit.
|
|
- **Source of truth.** The official MeshCore firmware at
|
|
[meshcore-dev/MeshCore](https://github.com/meshcore-dev/MeshCore) is the
|
|
**golden source of truth** for all protocol behavior. Whenever this spec and
|
|
the upstream C++ disagree, **upstream wins** — this spec is downstream and
|
|
the canonical text is the C++. Each substantive change in `CHANGELOG.md`
|
|
records the upstream commit hash it was validated against.
|
|
- **Refined through DongLoRa.** Clarifications and edge-case detail in this
|
|
spec have been driven in part by observations from building DongLoRa
|
|
firmware and apps against live MeshCore deployments. Where DongLoRa
|
|
behavior diverges from upstream, this spec follows upstream and treats the
|
|
DongLoRa side as a follow-up bug, not a spec change.
|
|
- **Use it carefully.** Conformance against this corpus is a useful signal
|
|
but not a substitute for cross-checking against upstream firmware for any
|
|
behavior that affects interoperability. If you find a divergence from
|
|
upstream, please file an issue — that is exactly the kind of report this
|
|
project exists to catch.
|
|
|
|
## What's Here
|
|
|
|
- **`spec/`** — RFC-style protocol specification in Markdown, covering every
|
|
layer from packet framing to cryptographic operations.
|
|
- **`corpus/`** — JSON test vectors organized by protocol layer.
|
|
Each vector pairs a structured representation with its exact binary encoding,
|
|
enabling any implementation to verify encode and decode correctness.
|
|
- **`tools/`** — Validation and generation utilities.
|
|
|
|
## Test Vector Format
|
|
|
|
Test vectors are JSON files. Binary data is represented as uppercase hex strings
|
|
(whitespace allowed for readability). Each file contains an array of vectors in
|
|
one of three modes:
|
|
|
|
- **`encode_decode`** — Structured input paired with expected binary output.
|
|
Implementations MUST produce the given binary when encoding, and MUST recover
|
|
the given structure when decoding.
|
|
- **`decode_only`** — Binary input with expected structured output. Used for
|
|
alternate valid encodings that an encoder need not produce but a decoder MUST
|
|
accept.
|
|
- **`invalid`** — Binary input that MUST be rejected by a conforming decoder.
|
|
|
|
See `corpus/schema/test-vector.schema.json` for the full schema.
|
|
|
|
## Using the Corpus
|
|
|
|
1. Parse each JSON file in `corpus/`.
|
|
2. For `encode_decode` vectors: encode the `structured` form and compare to
|
|
`binary`; decode `binary` and compare to `structured`.
|
|
3. For `invalid` vectors: attempt to decode `binary` and verify failure.
|
|
|
|
No special tooling is required — just a JSON parser and your MeshCore
|
|
implementation.
|
|
|
|
## Project Status
|
|
|
|
This project is under active development. See [Provenance](#provenance) above
|
|
for how the spec is produced and what to verify against.
|
|
|
|
## Protocol Versions
|
|
|
|
The corpus covers all known MeshCore protocol versions. Each test vector file
|
|
includes a `protocol_version` field. Version 1 (the current production version)
|
|
has the most comprehensive coverage.
|
|
|
|
## License
|
|
|
|
MIT — see [LICENSE](LICENSE).
|
|
|
|
## Contributing
|
|
|
|
See [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
|
|
## Acknowledgments
|
|
|
|
This spec would not exist without the [MeshCore firmware](https://github.com/meshcore-dev/MeshCore)
|
|
by the MeshCore developers and the official [MeshCore docs](https://docs.meshcore.io),
|
|
which together are the authoritative reference this spec derives from.
|
|
|
|
## Author
|
|
|
|
Stephen Waits <steve@waits.net>
|