Closes Tier 1 #2. Without this, a client can't send any LXMF body
larger than LINK_PACKET_MAX_CONTENT ≈ 360 B, can't receive a NomadNet
page that doesn't fit in one MTU, and can't transfer files via rncp.
SPEC.md §10 (new): full Resource fragmentation protocol with citations
to RNS/Resource.py. 13 sub-sections covering preparation pipeline
(metadata prefix → optional bz2 → random_hash prefix → SHA-256 over
data||random_hash → link.encrypt of the WHOLE blob → part-split into
SDU-sized chunks → 4-byte map_hash hashmap with collision guard within
COLLISION_GUARD_SIZE = 2*WINDOW_MAX + HASHMAP_MAX_LEN), wire context
inventory (RESOURCE_ADV / RESOURCE / RESOURCE_REQ / RESOURCE_HMU /
RESOURCE_PRF / RESOURCE_ICL / RESOURCE_RCL), the msgpack dict for the
advertisement (t/d/n/h/r/o/i/l/q/f/m), the request payload format with
the hashmap_exhausted sentinel, the lazy-hashmap RESOURCE_HMU
continuation that lets large hashmaps avoid breaking small-MTU links,
the proof body
resource_hash(32) || full_proof = SHA256(data||hash) (32)
returned in a PROOF-type packet, the sliding window dynamics
(WINDOW=4 → WINDOW_MAX_FAST=75 / WINDOW_MAX_VERY_SLOW=4 with rate
detection), multi-segment cutover at MAX_EFFICIENT_SIZE = 1 MiB - 1
with the lazy `__prepare_next_segment` pattern, and the
encryption-before-split layering that means a missing part can't be
decrypted in isolation.
flows/send-resource.md: 10-step chronology from RNS.Resource()
construction through advertise → req/parts loop → HMU continuation →
final RESOURCE_PRF → multi-segment fan-out, with a wire-byte ladder
diagram and a per-step source map.
Side fixes found while drafting:
- SPEC.md §2.5 contexts table was wildly incomplete and had a real
bug: KEEPALIVE was listed as 0xFD; upstream is 0xFA per
RNS/Packet.py:87. 0xFD is actually LINKPROOF (the regular
DATA-receipt context, §6.5). Replaced with the full upstream
context inventory: NONE, RESOURCE_*, CACHE_REQUEST, REQUEST,
RESPONSE, PATH_RESPONSE, COMMAND, COMMAND_STATUS, CHANNEL,
KEEPALIVE, LINKIDENTIFY, LINKCLOSE, LINKPROOF, LRRTT, LRPROOF.
- SPEC.md §6.5 reworded: "send back a PROOF packet (no context
byte specifics)" → "send back a PROOF-type packet with
context = LINKPROOF (0xFD)" for clarity.
- The previously-numbered §10 "Test vectors" and §11 "Source map"
are renumbered to §11 / §12 so the new Resource section lands in
its correct protocol-stack position. agent.md §5 audit table
updated accordingly.
flows/README.md status table updated; receive-resource.md added as
the next pending flow.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Closes the highest-priority Tier 1 gap. Without this, a from-scratch
client can't learn any peers exist; known_destinations stays empty and
every outbound message fails at recall(dest_hash).
SPEC.md §4.5 (new): announce validation rules with full citations to
RNS/Identity.py::validate_announce (line 496) and the dispatch path in
RNS/Transport.py:1623-2024. Covers the body parse with context_flag
branch, signed_data reconstruction (including the empty-bytes-not-absent
ratchet rule), Ed25519 signature verification, dest_hash recomputation,
public-key collision rejection, blackhole list, cache update order
(known_destinations -> known_ratchets -> path_table), PATH_RESPONSE
distinction, and the implementation-private SHOULD rules around
ingress rate limiting, random_blob history caps, and self-announce
filtering.
flows/receive-announce.md: chronological walk through 9 steps from
deframing to handler dispatch, with the cheap-pre-filter design
(signature-checked-then-counted) called out, the burst-active ingress
limiter explained against IC_BURST_FREQ_NEW=6Hz / IC_BURST_FREQ=35Hz,
the path-table decision tree, and the announce_handlers fan-out with
aspect_filter and PATH_RESPONSE filtering. Ends with a wire-byte
diagram and a per-step source map.
Two side fixes found while drafting:
- SPEC.md §4.1 had random_hash described as "10 random bytes". It's
actually random_hash = get_random_hash()[0:5] + int(time.time()).to_bytes(5, "big")
per RNS/Destination.py:282. Transit relays parse the trailing 5
bytes via timebase_from_random_blob (RNS/Transport.py:3100) for
replay-ordering decisions.
- SPEC.md §2.5 contexts table was missing PATH_RESPONSE = 0x0B
(RNS/Packet.py:83).
flows/README.md status table updated; the priority-ordered todo list
also gets a few new entries spun off from the work
(send-announce, forward-announce, send-resource, path-discovery flows).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Captures the full Tier 1/2/3 list of missing protocol specification
needed for a from-scratch client to interoperate with upstream
Reticulum / LXMF / RNode-firmware.
Each item carries the source-citation hooks I gathered while answering
the question, so whoever picks the work up doesn't have to re-research
where the upstream code lives. Highlights:
Tier 1 (barebones interop): receive-announce flow + §4.5 validation
rules, Resource fragmentation §12, regular PROOF body §6.5 expansion,
3-byte MTU/mode signalling field §6, path-response context 0x0B
distinction, identity on-disk format §1.3 expansion.
Tier 2 (useful in the wild): propagation node protocol, KEEPALIVE
and link teardown §6, LXMF stamps + tickets, NomadNet page protocol
§13, GROUP destinations, CSMA / airtime tracking, RNode KISS
configuration handshake §8.5, implicit vs explicit proof mode.
Tier 3 (transport / relay): DATA forwarding rules §7.7, ANNOUNCE
rebroadcasting §4.6, path table management §7.8, tunnels and
shared-instance protocol §7.9, reverse-table link transport §6.x.
Folds the previous "Document the Reticulum Resource fragmentation
protocol" and "Document the Propagation /get pull protocol" entries
from the lower polishing section into Tier 1 / Tier 2 respectively
so they're tracked at the right priority.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The previous one-sentence §8.3 was wrong about scope: it said KISS hosts
treat the 1-byte header as opaque pass-through, which is misleading —
the byte lives between RNodes on the LoRa air-frame, not on the KISS
channel. Hosts (RNS, Sideband, etc.) never see it. Any alternative
implementation that talks LoRa to an RNode must construct/parse it
bit-exactly, or its TX is invisible and its RX mistakes the header for
the first payload byte.
New text covers:
- Header byte layout: bit 7..4 random seq nibble, bit 0 FLAG_SPLIT,
SEQ_UNSET=0xFF sentinel (Framing.h:105-108).
- TX rules: header = random(256) & 0xF0 | (FLAG_SPLIT iff
payload > 254). Both halves of a split share the same byte byte-
for-byte. Split at 255 bytes total per LoRa frame; max reassembled
payload 508. (RNode_Firmware.ino:716-742; Config.h:59-61.)
- RX state machine: at most one buffered first-half keyed by seq
nibble; four cases for inbound frames (RNode_Firmware.ino:359-446).
- Reassembly timeout: upstream firmware has none (relies on
subsequent traffic to evict). The clean-room repeater adds a 500ms
defensive timeout (reticulum-lora-repeater/src/Radio.cpp:189-194)
— implementation-private, not part of the wire spec.
- Sequence-collision ceiling: 4 random bits = 1/16 collision per
overlapping split-packet pair from the same sender. Don't burst.
- Note that a "header rotates between transmissions" memory of this
protocol is a fading recall of the per-TX random seq nibble — there
is no retransmit-driven byte rotation or rechunk. LoRa TX is
fire-and-forget; higher-layer retransmit just re-runs the TX path
and gets a fresh random seq.
todo.md gets an entry for tools/verify_rnode_split.py to lock the
new §8.3 in with a runtime test.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
receive-opportunistic-lxmf.md mirrors the send flow on the recipient
side: KISS/HDLC deframe -> Transport.inbound -> packet_filter dedup ->
DATA/SINGLE branch -> Destination.receive -> Identity.decrypt with the
ratchet ring + long-term-key fallback -> LXMRouter.delivery_packet (which
fires the PROOF receipt before parsing) -> LXMessage.unpack_from_bytes
with msgpack stamp-strip -> ticket/stamp/dedup checks -> __delivery_callback
to the app. Notes upstream's narrower variant tolerance vs SPEC.md §5.6
and the missing clockless-sender fix-up vs §9.6.
send-link-lxmf.md walks the DIRECT method end-to-end: process_outbound
DIRECT branch decides reuse-vs-establish, RNS.Link.__init__ builds the
unencrypted LINKREQUEST body (initiator_X25519_pub || initiator_Ed25519_pub
|| optional signalling), link_id derived from get_hashable_part, LRPROOF
arrives back and validate_proof verifies signature against the responder's
long-term Ed25519 pub recalled from a prior announce, handshake() does
ECDH+HKDF over the shared secret with salt=link_id, lxmessage.send sends
the full LXMF body (with dest_hash, per §5.2) over the link with Token
encryption that omits the eph_pub prefix per §3.1, mandatory PROOF
receipts per §6.5 resolve the PacketReceipt. Sketches the RESOURCE
representation for oversize bodies and the backchannel-identify trick
that makes the link bidirectional.
flows/README.md status table updated.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two source-cited corrections found while drafting the link send flow:
§6.2 — the LRPROOF body is signature(64) || responder_X25519_pub(32) ||
[signalling], not link_id || responder_X25519_pub || signature ||
[signalling]. The link_id appears in the packet header (dest_hash
position) per RNS/Packet.py:182-184 when context==LRPROOF, not in the
body. The responder's long-term Ed25519 pub is also NOT on the wire —
both sides know it from a prior announce, and it is included only in the
signature input. Citations: RNS/Link.py:373 (signer), :376 (proof_data),
:417 (validator).
§6.3 — get_hashable_part offsets N are 2 for HEADER_1 and 18 for HEADER_2
(skip flags+hops, and additionally skip transport_id for HEADER_2),
producing the same hashable_part on both sides regardless of relay
conversion. Previously listed as 18/34, which would have stripped the
dest_hash. Citation: RNS/Packet.py:354-361.
Both corrections are direct upstream source citations (criterion #2 from
agent.md §1) so they are recorded as verified. todo.md adds an entry to
write tools/verify_link_handshake.py to lock them in with a runtime test.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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>
Adds tools/ verifier scripts that exercise upstream RNS / LXMF and confirm
(or correct) the SPEC.md callouts:
- §2.3 HEADER_1→HEADER_2 conversion: verified by stubbing Transport.transmit
and seeding a multi-hop path_table entry.
- §4.3 app_data 3-element variant: producer in LXMF 0.9.6 actually emits
2 elements only (supported_functionality at LXMRouter.py:999 is dead
code); parser tolerates 1/2/3-element + raw UTF-8.
- §7.1 path? always-precedes claim: actually conditional on
not has_path() AND method==OPPORTUNISTIC.
- §7.4 ratchet ring default 8: actually Destination.RATCHET_COUNT = 512
at RNS/Destination.py:85.
Also fixes a documentation bug in §1.2: the rnstransport.path.request row
of the well-known-hash table had the dest-hash prefix where the name_hash
should be (correct name_hash is 7926bbe7dd7f9aba88b0).
Seeds test-vectors/identities.json (Alice + Bob) with a regenerator
(tools/regen_identities.py) and verifier (tools/verify_destination_hash.py)
covering §1.1 and §1.2.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Captures the four next-task buckets:
- Outreach (file issue on markqvist/Reticulum)
- Test infrastructure (bootstrap test-vectors/, write priority verifier scripts)
- Open UNVERIFIED items in SPEC.md to resolve
- Spec polishing (split SPEC.md, document Resource and Propagation /get)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Bootstrapped from the working notes of two reverse-engineering efforts:
- reticulum-lora-webclient (web/Capacitor)
- reticulum-mobile-app (Kotlin Multiplatform / Android)
SPEC.md consolidates byte-level wire format findings that aren't in the
upstream Reticulum manual. Each section grounded in upstream Python
source citations (file + line) where possible.
agent.md establishes the verification rules:
- Every claim is verified, unverified, or speculation; markers required
- Verification means a runnable script or a source citation
- PRs that quietly remove markers get rejected
tools/ and test-vectors/ are placeholder scaffolding with READMEs
describing the work needed.
Sections in SPEC.md flagged as currently UNVERIFIED:
- §2.3 Originator HEADER_1 -> HEADER_2 conversion
- §4.3 app_data 3-element variant with capabilities
- §7.1 path? always precedes LXMF (vs only on stale paths)
- §7.4 ratchet ring count default = 8
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
