reticiulum-specification/flows/send-announce.md

Flow: send an announce

What happens chronologically when a node emits an announce — the periodic broadcast that lets the rest of the mesh discover or refresh a path to this destination. Pinned against RNS 1.2.0.

Out of scope: the relay-side rebroadcast (forward-announce.md — see ../SPEC.md §12.3) and path-response announces (already covered in path-discovery.md).

---

Sequence

1. Caller invokes Destination.announce(app_data=...)

RNS/Destination.py:243-318. Triggers:

• Periodic re-announce loop (every 5-15 minutes per §7.5; LXMF runs this from LXMRouter.jobs).
• Application-explicit announce (e.g. user clicks "announce now" in Sideband).
• Path-response branch — see path-discovery.md step 6.

2. Build random_hash

random_hash = RNS.Identity.get_random_hash()[:5] + int(time.time()).to_bytes(5, "big")

5 random bytes + 5 bytes big-endian uint40 unix-seconds timestamp per ../SPEC.md §4.1. The timestamp is used by transit relays for path-table replay-ordering decisions per §4.5 step 6.3.

3. Optional ratchet rotation

If the destination has ratchets enabled (destination.ratchets != None), rotate_ratchets() runs (Destination.py:227-235):

if now > self.latest_ratchet_time + self.ratchet_interval:
    new_ratchet = Identity._generate_ratchet()             # X25519 keypair, 32B priv
    self.ratchets.insert(0, new_ratchet)                   # most-recent-first
    self.latest_ratchet_time = now
    self._clean_ratchets()                                 # cap at RATCHET_COUNT = 512
    self._persist_ratchets()                               # storagepath/ratchets/<hex>

The new ratchet's public key is what gets included in this announce. RATCHET_INTERVAL = 30*60s so a ratchet rotates at most every 30 minutes — back-to-back announces within that window reuse the current ratchet (per §7.3 the relays would dedup them on (dest_hash, ratchet_pub) if even the random_hash collided, but the 10 random bytes prevent that).

4. Build signed_data

Per §4.2:

signed_data = self.hash + self.identity.get_public_key() + self.name_hash + random_hash + ratchet
if app_data is not None:
    signed_data += app_data

self.hash is the destination_hash (which appears in the outer Reticulum header on the wire, but is also signed). ratchet is b"" when no ratchet is included.

5. Sign and pack the announce body

signature = self.identity.sign(signed_data)                # Ed25519 long-term key
announce_data = self.identity.get_public_key() + self.name_hash + random_hash + ratchet + signature
if app_data is not None:
    announce_data += app_data

The dest_hash is not in announce_data even though it's in signed_data — the receiver gets dest_hash from the outer packet header per §4.1.

6. Cache the body for path-response replay

Destination.py:303-309: store self.path_responses[tag] = [time.time(), announce_data] if a tag was supplied (path-response branch). The cache TTL is PR_TAG_WINDOW = 30s per §7.2.4 — same wire bytes served to multiple racing relays for dedup convergence.

7. Construct and emit the Reticulum ANNOUNCE packet

context_flag = FLAG_SET if ratchet else FLAG_UNSET
announce_context = PATH_RESPONSE if path_response else NONE
announce_packet = RNS.Packet(self, announce_data,
                             RNS.Packet.ANNOUNCE,
                             context = announce_context,
                             attached_interface = attached_interface,
                             context_flag = context_flag)
announce_packet.send()

Wire form per §4.1:

• packet_type = ANNOUNCE (1), transport_type = BROADCAST (0), destination_type = SINGLE (0)
• header_type = HEADER_1 (the ratchet rotation announce is always broadcast — no transport_id at this stage)
• context = NONE (0x00) for periodic re-announces, PATH_RESPONSE (0x0B) for path-response announces
• context_flag = 1 if ratchet present (signals the optional ratchet_pub slot in the body)

Announce packets are NOT encrypted — Packet.pack (RNS/Packet.py:189-191) special-cases ANNOUNCE to skip encryption. The body is signed but plaintext, so anyone in earshot can validate the signature and decode the public key.

8. Transport.outbound broadcasts on every OUT interface

Same broadcast branch as a path? request (flows/path-discovery.md step 2) — the dest_hash isn't in path_table (it's our own destination, not a remote one), so the broadcast branch at RNS/Transport.py:1119+ fires, emitting on every interface where interface.OUT == True. Per §7.5 the announce is rate-limited by ANNOUNCE_CAP = 2.0 (2% airtime) on each interface.

9. Periodic re-announce loop

LXMF runs this via LXMRouter.jobs calling LXMRouter.announce_propagation_node and LXMRouter.announce_destination (for delivery destinations) at the configured cadence. Default re-announce interval is 5-15 minutes per §7.5. Without it, transit-relay path tables age out within minutes and peers can't message you.

---

Wire-byte summary

[ 1B flags: HEADER_1 | context_flag | BROADCAST | SINGLE | ANNOUNCE ]
[ 1B hops=0 ]
[ 16B dest_hash ]
[ 1B context: 0x00 normal / 0x0B PATH_RESPONSE ]
[ 64B public_key (X25519 || Ed25519) ]
[ 10B name_hash ]
[ 10B random_hash (5B random || 5B big-endian uint40 unix_seconds) ]
[ 32B ratchet_pub ]   ← present iff context_flag bit set
[ 64B Ed25519 signature ]
[ N B  app_data ]     ← may be empty

---

Source map

Step	File	Function / line
1	RNS/Destination.py	announce, line 243
2	RNS/Destination.py	random_hash construction, line 282
3	RNS/Destination.py	rotate_ratchets, line 227
4	RNS/Destination.py	signed_data assembly, line 297
5	RNS/Destination.py	sign + pack, line 300-303
6	RNS/Destination.py	path_responses cache, line 305
7	RNS/Destination.py	Packet construction, line 313
7	RNS/Packet.py	ANNOUNCE-skips-encryption, line 189-191
8	RNS/Transport.py	outbound broadcast branch, line 1119
9	LXMF/LXMRouter.py	jobs / re-announce cadence