swaitsandClaude Opus 4.7
d785e35919
Set up the protocol spec as an mdBook and add a GitHub Actions workflow that builds it on every push/PR and deploys to GitHub Pages on main. The repo is now both a machine-readable corpus and a browsable, searchable site. Structure changes (one-time, mechanical): - Rename the spec source directory from `spec/` to `src/` to match mdBook's default convention. All 21 chapter files move; their internal relative cross-links are unchanged. - Add `src/SUMMARY.md` as the mdBook table of contents, grouping chapters under Wire Format, Payloads, Cryptography & Identity, and Routing & Higher-Layer Protocols. - Add `book.toml` at repo root: title, author, search enabled, fold enabled, edit-on-GitHub links, navy theme. - Add `.github/workflows/mdbook.yml`: build on push + PR, deploy on push to main only (configure-pages + upload-pages-artifact + deploy-pages from actions/). - Add `/book/` to .gitignore. Reference updates so the old path is fully retired: - Every `spec_ref` in `corpus/**/*.json` rewritten from `spec/` to `src/` (54 files). - Schema description text and example path in `corpus/schema/test-vector.schema.json`. - `README.md`: prominent link to the published site near the top; "What's Here" updated for the new layout. - `CONTRIBUTING.md`: spec-editing instructions point at `src/` and note the SUMMARY.md requirement. - `CLAUDE.md`: directory-layout notes updated. CHANGELOG.md historical entries intentionally keep their `spec/` paths since those record what the paths were at the time of those commits. After this lands, the user needs to enable GitHub Pages in repo settings with source = "GitHub Actions" (one-time, manual). The workflow will then publish to https://swaits.github.io/meshcore-spec/ on every push to main. Verified locally: `mdbook build` produces a clean book/ tree with all 21 chapters rendered and the SUMMARY-driven sidebar populated. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
109 lines
4.7 KiB
Markdown
109 lines
4.7 KiB
Markdown
# MeshCore Spec
|
|
|
|
A comprehensive specification and conformance test suite for the
|
|
[MeshCore](https://github.com/meshcore-dev/MeshCore) mesh networking protocol.
|
|
|
|
**📖 Read the spec online:** <https://swaits.github.io/meshcore-spec/>
|
|
|
|
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
|
|
|
|
- **`src/`** — RFC-style protocol specification in Markdown, covering every
|
|
layer from packet framing to cryptographic operations. Also the source root
|
|
for the [mdBook](https://rust-lang.github.io/mdBook/) build published to
|
|
GitHub Pages.
|
|
- **`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.
|
|
- **`book.toml`** + **`.github/workflows/mdbook.yml`** — mdBook configuration
|
|
and the GitHub Actions workflow that builds and deploys the spec on every
|
|
push to `main`.
|
|
|
|
## 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>
|