073203abae
Upstream RNS enforces two requirements in code that SPEC.md left implicit;
both caused silent message loss in a clean-room Go LXMF service against
upstream Python rns 1.2.4 / lxmf 0.9.7.
§6.4.2 LRRTT — initiator's link-activation packet
- HEADER_1, DATA, dest_type=LINK (0x03), ctx=0xfe; body is
`umsgpack.packb(rtt_seconds)` encrypted with the link's session keys.
- The responder transitions HANDSHAKE→ACTIVE only on LRRTT receipt
(Link.py:534-553), which is also what fires the link_established
callback. LXMF's set_resource_strategy(ACCEPT_APP) is installed
from that callback; without it, every RESOURCE_ADV the initiator
sends hits the silent ACCEPT_NONE branch at Link.py:1087.
§6.4.3 Header type for post-handshake DATA and Resource
- Link-addressed packets are routed via link_table, which forwards
header bytes verbatim (Transport.py:1587-1622). HEADER_2 with a
relay's transport_id therefore arrives at the destination intact
and is dropped by packet_filter (Transport.py:1283-1285) as
"for another transport instance".
- Mandates HEADER_1 with no transport_id for all post-handshake
link DATA / Resource / control packets regardless of hop count.
- Asymmetry with LINKREQUEST (which IS path_table-routed and so
HEADER_2-eligible) is spelled out.
Companion changes:
- §6.4 renamed to "Session keys and link activation"; existing
HKDF content moved into §6.4.1.
- §2.5 LRRTT context-byte entry points at §6.4.2.
- §12.5.2 (Link DATA forwarding) cross-references §6.4.3.
- §14 failure-modes table: two new entries for the silent-drop
chains documented above.
- flows/send-link-lxmf.md step 4 strengthened (LRRTT is mandatory,
not informational); step 6 corrected (Transport.outbound does NOT
apply HEADER_1→HEADER_2 for link DATA — that conversion is
path_table-keyed, link DATA is link_table-keyed).
- test-vectors/links.json extended with an LRRTT entry: pinned
rtt_seconds=0.05 + pinned 16-byte IV produces deterministic
wire bytes for the encrypted body.
- tools/regen_links.py drives the LRRTT generation with an
os.urandom patch for the Token IV.
- tools/verify_link_lrrtt.py (new) locks the wire claims:
HEADER_1, ctx=0xfe, dest=link_id, body decrypts under
derived_key to msgpack float64 matching rtt_seconds.
Citations all verified against installed RNS 1.2.4 / LXMF 0.9.7.
All 14 verifiers PASS.
|
||
|---|---|---|
| .. | ||
| forward-announce.md | ||
| lxmf-outbound-retry.md | ||
| path-discovery.md | ||
| README.md | ||
| receive-announce.md | ||
| receive-link-lxmf.md | ||
| receive-opportunistic-lxmf.md | ||
| receive-propagated-lxmf.md | ||
| receive-resource.md | ||
| send-announce.md | ||
| send-link-lxmf.md | ||
| send-opportunistic-lxmf.md | ||
| send-propagated-lxmf.md | ||
| send-resource.md | ||
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) |
✅ |
lxmf-outbound-retry.md (process_outbound retry loop, per-message state machine, fail_message) |
✅ |
Conventions
- Each flow targets one specific upstream operation.
send-opportunistic-lxmf.mddocuments whatLXMRouter.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 lxmfinstall 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.