Real interop bug found while checking what the
thatSFguy/reticulum-lora-repeater stack does with the random_hash
field. The repeater is a thin wrapper around attermann/microReticulum,
which emits 10 fully-random bytes for random_hash rather than the
upstream Python form of 5 random bytes + 5 bytes of big-endian uint40
unix_seconds. The Python form is preserved as a comment in
microReticulum src/Destination.cpp:270-272, with a "CBA TODO add in
time to random hash" next to the random-only implementation.
Effect: Python RNS receivers parse random_hash[5:10] as an emission
timestamp via Transport.timebase_from_random_blob (RNS/Transport.py:
3100-3101), and use it for path-table replacement decisions in the
equal-or-greater-hop branch (RNS/Transport.py:1721-1745). A
uniformly-random uint40 has median ~5.5e11 ≈ year 19403 AD, so
microReticulum announces look "far-future" to Python receivers and
permanently win replay-ordering comparisons until the path TTL
expires.
First-contact path-table population is unaffected — the bug only
surfaces on path replacement, which makes it a quiet failure mode
in mixed-vendor meshes (microReticulum repeater + Python rnsd).
Symmetry: microReticulum receivers don't consult the timestamp half,
so microReticulum-to-microReticulum traffic is unaffected. The
asymmetry is what makes the symptom show up only when a Python
relay is also in the mesh.
The repeater's pre_build.py aggressively patches FIVE other
microReticulum protocol bugs (ratchet announce parsing, identity
hash length 16→32, validate_announce/announce diagnostics, DATA/
PROOF forwarding for transport-mode, path-table write dedup) — but
not this one. Filed as an outreach todo to upstream the fix to
attermann/microReticulum.
SPEC.md §4.1 — adds an UNVERIFIED callout naming the deviation,
citing the exact source location and explaining
the propagation path through Python's path-table
logic.
SPEC.md §9.10 — gotcha entry making the bug findable from the
gotchas list, with a suggested clean-room
workaround (emit the timestamp half yourself,
even just seconds-since-boot).
todo.md — outreach entry to file an issue on
attermann/microReticulum proposing the fix.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Closes Tier 1 #3. The previous §6.5 was one paragraph that named
"a PROOF packet" without specifying its body shape, signing input,
or explicit/implicit choice — exactly the level of vagueness that
caused the SF mobile client to ship the wrong proof shape on its
first cut.
New §6.5 has six sub-sections:
§6.5.1 Two body formats:
explicit = packet_hash(32) || signature(64) = 96B
implicit = signature(64) = 64B
Distinguished purely by length at the receiver per
PacketReceipt.validate_proof (RNS/Packet.py:497-548).
§6.5.2 Sender-side policy. Opportunistic DATA proofs default to
the IMPLICIT form (Reticulum.__use_implicit_proof = True
at RNS/Reticulum.py:259), only switching to explicit when
the operator's config sets use_implicit_proof = No. Link
DATA proofs are hardcoded explicit on both emit
(Link.prove_packet at RNS/Link.py:383-394) and validate
(validate_link_proof at RNS/Packet.py:449-494, with the
implicit branch commented out).
§6.5.3 Where the proof is addressed:
opportunistic -> packet_hash[:16] as a synthetic
ProofDestination
link -> link.link_id
§6.5.4 Wire summary with byte-position ladders for both forms.
§6.5.5 Receiver tolerance: validators MUST accept both 64- and
96-byte bodies for opportunistic DATA proofs since the
upstream default differs from what most non-RNS clients
assume.
§6.5.6 Restates the Link-DATA mandatory-receipt rule with
context-byte clarification.
Side fix: §2.5 contexts table description for LINKPROOF (0xFD)
corrected. The constant is defined upstream but NOT actually emitted
by either Identity.prove or Link.prove_packet — both build their
proof packets with packet_type = PROOF and context = NONE (0x00).
LINKPROOF (0xFD) is reserved but unused in RNS 1.2.0; the proof-ness
of a packet is conveyed by packet_type, not context.
todo.md gets a new "tools/verify_proof_packet.py" entry under the
runtime-verifier section to lock the explicit/implicit dispatch in
with a runtime test.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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>
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>
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>
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>
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>
