jlpoole/reticiulum-specification
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
reticiulum-specification/flows/README.md
Rob ac898a414d Add flows/ directory with opportunistic-LXMF send sequence 
flows/ documents end-to-end chronological narratives for common Reticulum
operations, complementing SPEC.md (which is organized by protocol layer).
Each step cross-references the SPEC.md section that defines the wire
bytes, so the directory introduces no new normative claims.

First flow: send-opportunistic-lxmf.md walks the 13-step sequence from
LXMRouter.handle_outbound through LXMessage.pack, the path-request
preamble, Token encryption, Transport.outbound HEADER_1→HEADER_2
conversion, and per-interface KISS/HDLC framing. Pinned against RNS 1.2.0
/ LXMF 0.9.6 with file+line citations for each step.

README.md updated to advertise flows/ and tools/ alongside SPEC.md and
test-vectors/.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-03 10:15:03 -04:00

2.2 KiB
Raw Blame History

Flows

End-to-end chronological narratives for common Reticulum operations. Where SPEC.md is organized by layer (identity, header, token crypto, announce, LXMF, link, transport, framing), the documents here are organized by operation and walk through what each layer contributes in order — app-call → wire bytes.

The two views are complementary: SPEC.md tells you what each piece looks like; the flows tell you when each piece runs and what calls what. A flow document should not introduce new normative claims — every byte-level detail should be a cross-reference to the relevant SPEC.md section. If you find yourself describing wire bytes here that aren't in SPEC.md, that's a sign the spec has a gap to fill.

Status

Flow Status
send-opportunistic-lxmf.md ✅
send-link-lxmf.md (DIRECT method, over a Reticulum Link) ⏳
send-propagated-lxmf.md (PROPAGATED method, via a propagation node) ⏳
receive-opportunistic-lxmf.md (the inverse of the opportunistic-send flow) ⏳
announce.md (build, sign, transmit, ratchet rotation) ⏳
path-discovery.md (request, response, path-table population) ⏳

Conventions

  • Each flow targets one specific upstream operation. send-opportunistic-lxmf.md documents what LXMRouter.handle_outbound(lxm) does for an opportunistic message; it does not also cover Link or propagation paths — those get their own docs so the chronology stays linear.
  • Numbered steps are chronological. Each step that produces wire bytes cross-references the SPEC.md section that defines those bytes.
  • Source citations use the standard pip install rns lxmf install layout (RNS/, LXMF/) with file + line. Line numbers are pinned to the RNS / LXMF version named at the top of each flow; out-of-date line numbers should be fixed in a PR.
  • "Verified" claims must be backed by a tools/ script per ../agent.md §1. Flow docs inherit the verification status of the SPEC.md sections they reference — if a flow step relies on an unverified SPEC.md callout, the flow should mark that step as inheriting the unverified status rather than silently treat it as fact.