Reticulum Specifications

Byte-level interoperability specifications for the Reticulum Network Stack and LXMF — the parts that aren’t in the upstream manuals but are needed to build a working client from scratch.

Upstream Reticulum has excellent operator-facing documentation (config, deployment, design philosophy). What’s missing — and what every alternative implementation has had to reverse-engineer from the Python source — is an authoritative wire-level spec: header bit layouts, msgpack field types, signature input formats, the exact behavior of Transport.outbound, and the long list of “would never guess from reading the manual” gotchas that cost hours of debugging each.

This repo collects those findings in one place. The hope is that future client authors (Kotlin, Swift, Rust, Go, embedded C — pick your stack) can read this instead of re-deriving everything from RNS/Transport.py.

Status

Early days, contributions welcome. Current content was bootstrapped from the working notes of two reverse-engineering efforts:

Each finding is grounded in upstream source citations (file + line) so it can be re-verified as RNS evolves.

Current upstream target (verified 2026-06-09): markqvist/Reticulum@422dc055 (RNS 1.3.5) and markqvist/LXMF@fab12ad (LXMF 1.0.1). Full commit hashes are pinned in tools/requirements.txt; all 28 verifiers pass.

Method

This fork proceeds with a three-tier evidence model that preserves the existing Claude-assisted work while promoting claims only after verification:

  1. Source analysis report — answer one narrow protocol question from pinned upstream source, with exact citations and unresolved cases.
  2. Executable verification — add runnable evidence under tools/ and deterministic vectors under test-vectors/ where bytes are involved.
  3. Specification promotion — update SPEC.md as normative prose only after the verifier/vector exists; add correction or incident notes when earlier text would mislead implementers.

See agent.md §3 for the detailed rules.

Verify a Clone

The verifier suite has no dependency on a particular user’s virtual environment. From a fresh clone, create any isolated Python environment and install the exact upstream Git commit pins:

python3 -m venv .venv
.venv/bin/python -m pip install -r tools/requirements.txt
.venv/bin/python tools/verify_all.py

On Windows, use .venv\Scripts\python.exe in place of .venv/bin/python. Activation is optional; verify_all.py uses the interpreter that launched it and refuses to run when installed versions or Git commit origins do not match.

What’s here

As content grows, SPEC.md will be split into per-layer files (packet header, identity, announce, token-crypto, LXMF, link, resource, transport).

Spec corrections

Errata that may invalidate code built against an earlier revision of SPEC.md. Newest first. Feature additions and ordinary edits live in git log — this section is reserved for cases where the spec said one thing, that turned out to be wrong, and an implementer who pulled the bad version needs to fix their code.

Scope

In scope:

Out of scope:

Source citations

Where a finding cites upstream Python code, the path is relative to a standard pip install rns lxmf installation, e.g. RNS/Transport.py, LXMF/LXMF.py. Where the bundled umsgpack is referenced, the path is RNS/vendor/umsgpack.py.

When upstream code changes such that a citation no longer matches, file an issue or PR — the goal is to track the de-facto wire spec as it actually behaves, not as it was at any single snapshot.

Contributing

If you’ve debugged a Reticulum interop problem and the answer wasn’t in the upstream docs, please add it. Format:

### N.M Short description of the finding

**Symptom:** what you observed that prompted the investigation.

**What's happening:** the actual mechanism, ideally with upstream source citation (file + line).

**Implication / fix:** what an implementation must do to interop.

**Source:** upstream file paths and approximate line numbers.

Add a worked test vector to test-vectors/ if the finding is byte-level.

Provenance

This project is a fork (June 8, 2026) of https://github.com/thatSFguy/reticulum-specifications. thatSFguy’s approach was to use Claude, I use Codex and have applied the approach I used for the LXMF-specification project here.

License

CC BY 4.0 — use freely, attribution appreciated.