jlpoole/reticiulum-specification
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
reticiulum-specification/flows/README.md
Rob 282d5d59eb Add five companion flow docs 
- flows/receive-resource.md: inverse of send-resource. ADV
    ingestion, accept/reject decision, request_next loop,
    receive_part insertion, assemble + decrypt + hash-validate,
    RESOURCE_PRF emission, multi-segment continuation.

  - flows/receive-link-lxmf.md: responder side of the link
    handshake plus inbound LXMF DATA handling. validate_request
    -> handshake -> prove (LRPROOF emission) -> link_established
    callback wires delivery_packet. PACKET-form inbound runs
    delivery_packet directly; RESOURCE-form inbound runs through
    delivery_resource_advertised + delivery_resource_concluded
    pipeline.

  - flows/send-announce.md: random_hash construction (5B random +
    5B BE-uint40 timestamp), optional ratchet rotation, signed_data
    assembly, sign + pack, the broadcast emission. Notes that
    ANNOUNCE packets are NOT encrypted (Packet.pack special-cases
    line 189-191) and the periodic re-announce loop drives 5-15min
    cadence.

  - flows/forward-announce.md: relay-side rebroadcast for
    transport-mode nodes. Eligibility checks (transport_enabled,
    not PATH_RESPONSE, not rate_blocked), announce_table queue,
    Transport.jobs drain with PATH_REQUEST_GRACE = 0.4s,
    per-interface announce_queue with ANNOUNCE_CAP = 2.0% airtime
    enforcement, lowest-hop-count-first emission order, hops byte
    increment, local-rebroadcast counter for loop break.

  - flows/send-propagated-lxmf.md: PROPAGATED method end to end.
    LXMessage.pack with body encrypted to recipient (propagation
    node never decrypts), Link establishment to the propagation
    node, optional propagation stamp (1000 PoW rounds vs 3000 for
    regular stamps), submission via Link DATA or Resource,
    state goes to SENT (not DELIVERED — recipient pulls via /get
    later per §5.8.3).

flows/README.md status table updated; receive-propagated-lxmf.md
added as the only remaining ⏳ flow.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-03 12:21:05 -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.