jlpoole/reticiulum-specification
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
reticiulum-specification/flows/README.md
Rob abf66b9cef Add four more verifiers + receive-propagated flow + frontmatter version 
Verifiers:
  tools/verify_proof_packet.py — locks in §6.5. Toggles
    Reticulum.__use_implicit_proof to test both modes; confirms
    Identity.prove emits 64B (implicit) or 96B (explicit) proof
    body; PacketReceipt.validate_proof accepts both lengths and
    rejects an 80B body.
  tools/verify_link_handshake.py — locks in §6.1, §6.2, §6.3, §6.6.
    Most importantly verifies the previously-corrected §6.2 LRPROOF
    body order (signature(64) || responder_X25519_pub(32) ||
    [signalling]) and §6.3 link_id offsets (N=2 for HEADER_1) by
    actually building a Link initiator-side, capturing the
    LINKREQUEST raw bytes, computing link_id by the spec recipe,
    running validate_request inline (since the upstream wrapper
    swallows exceptions), and confirming the responder's LRPROOF
    bytes match the spec layout. This was the single most
    interop-critical correction we made.
  tools/verify_rnode_split.py — locks in §8.3. Pure-function
    re-implementation of the canonical TX and RX state machines
    from RNode_Firmware.ino:359-446 + 716-742; tests header-byte
    layout, single-frame TX, split-frame TX (300B → 254+46 with
    shared header byte), all four RX state-machine cases (a/b/c/d
    from the spec table), and end-to-end TX/RX round-trip at
    sizes 50, 254, 255, 300, 508.
  tools/verify_msgpack_quirk.py — locks in §9.3. Confirms umsgpack
    distinguishes str (fixstr/0xa5) from bytes (bin8/0xc4); confirms
    LXMF.display_name_from_app_data parses bytes-encoded display
    names correctly and silently returns None (not crash) on
    str-encoded ones, matching the bug-tolerance documented in §9.3.

All 11 verifiers pass against RNS 1.2.0 / LXMF 0.9.6.

Plus:
  - SPEC.md frontmatter: 'Last verified against' line per agent.md §7.
  - flows/receive-propagated-lxmf.md: closing half of the propagated
    LXMF lifecycle. /get listing query, fetch query, ack-and-purge
    via the have_ids slot, message-bundle unpack and dispatch
    through lxmf_delivery.
  - tools/README.md status table refreshed; flows/README.md flips
    receive-propagated-lxmf.md to ✅.

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

2.9 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 ✅
receive-opportunistic-lxmf.md ✅
send-link-lxmf.md (DIRECT method, over a Reticulum Link) ✅
receive-announce.md ✅
send-resource.md (Resource fragmentation over a Link) ✅
path-discovery.md (path? request, path-response wire detail, path-table population) ✅
receive-resource.md (inverse of send-resource: ADV ingestion, part assembly, proof emission) ✅
receive-link-lxmf.md (inverse of send-link-lxmf, including responder side of the handshake) ✅
send-announce.md (build, sign, transmit, ratchet rotation, periodic re-announce) ✅
forward-announce.md (transport-node rebroadcast logic, announce_cap, queue) ✅
send-propagated-lxmf.md (PROPAGATED method, via a propagation node) ✅
receive-propagated-lxmf.md (recipient pulling messages via /get) ✅

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.