Protocol architecture
This page explains how Reticulum addresses, discovers, and forwards traffic. Packet constants below match the Reticulum source bundled with Ratspeak 1.1.0; standalone configuration examples target rsReticulum 1.5.0, the same release. It is the technical follow-up to What is Reticulum?, but it still focuses on the concepts operators and advanced users need rather than implementation internals.
Destination-Based Addressing
Reticulum does not route to hosts, subnets, ports, or DNS names. It routes to destination hashes.
A destination is created from an application name, optional aspects, and, for Single or Group destinations, an identity. Reticulum hashes that material down to a 16-byte address:
name_hash = SHA-256("lxmf.delivery")[:10]
identity_hash = SHA-256(identity_public_keys)[:16]
destination_hash = SHA-256(name_hash + identity_hash)[:16]
That final 16-byte value is displayed as 32 hex characters. It is the address you share when you share a Reticulum destination.
Two people can both run an lxmf.delivery destination without colliding because each identity produces a different identity hash. Plain destinations omit the identity from their hash, so the same application name and aspects produce the same Plain address. Group destinations still include an identity hash; sharing only a destination name and a symmetric key is not enough to make separately created Group destinations use the same address.
Destination Types
| Type | Encryption | Multi-hop | Typical use |
|---|---|---|---|
| Single | Asymmetric, per-packet ECDH | Yes | Private application endpoints, including LXMF inboxes |
| Link | Ephemeral ECDH session | Yes | Reliable channels, requests, responses, resources |
| Group | Symmetric pre-shared key | No | Direct local group traffic with a shared key |
| Plain | None | No | Direct local public broadcast or discovery |
Only Single and Link destinations are transported across multiple hops. Plain destinations are intentionally local/direct, and Group destinations are currently direct-only.
Destination Names
Destinations use dotted names. The top-level name should identify the application, and later aspects should describe the purpose of the destination.
| Name | Purpose |
|---|---|
lxmf.delivery | LXMF message delivery destination |
lxmf.propagation | LXMF propagation node endpoint |
nomadnetwork.node | NomadNet node endpoint |
Long names do not make packets larger because only hashes are placed on the wire.
Announces
An announce is how a destination becomes reachable. A Single destination announce includes:
| Field | Purpose |
|---|---|
| Destination hash | The 16-byte address being announced |
| Public key material | X25519 and Ed25519 public keys for the identity |
| Name hash | The compact hash of the application destination name |
| Random hash | Freshness material used in announce validation |
| Ratchet key | Optional current ratchet public key |
| Signature | Ed25519 signature proving the announce belongs to the identity |
| Application data | Optional metadata such as display hints or capabilities |
Transport nodes that hear an announce record where it came from, increment the hop count, and may re-broadcast it. This is how paths form without a central registry.
Announce Propagation
Reticulum's announce behavior is designed to keep slow networks useful instead of letting routing chatter consume the link.
| Rule | Effect |
|---|---|
| Duplicate filtering | Already-seen announces are ignored |
| Hop limit | The default maximum announce depth is 128 hops |
| Bandwidth cap | Scheduled announces are limited by a bandwidth budget, 2% by default |
| Randomized delay | Re-broadcasts are delayed to avoid synchronized floods |
| Locality priority | Lower-hop announces are sent before distant ones when bandwidth is scarce |
| Replacement | Newer application data can replace a queued older announce |
Slow segments do not need perfect global convergence to be useful. If a destination is needed and a wider segment knows a path, path requests can pull the relevant reachability information across the constrained link.
Routing
Reticulum routing is next-hop routing built from announces.
- Node A announces its destination on its interfaces.
- A transport node hears the announce and records "A is reachable through this neighbor on this interface."
- The transport node re-broadcasts the announce with an incremented hop count.
- Other transport nodes repeat that process until the announce has reached the reachable mesh.
When Node B sends to Node A, it looks up A's destination hash. If a path exists, B sends the packet to the next hop. Each transport node repeats the lookup locally until the packet reaches the destination.
If no path exists, the sender can request a path or wait for the destination to announce again.
Transport Nodes and Metadata
Transport nodes forward encrypted private LXMF message bodies and application payloads without decrypting them.
They do still see transport metadata needed for forwarding: interface activity, timing, packet sizes, hop counts, and destination hashes. Reticulum packets do not carry source addresses, which improves initiator privacy, but it does not make traffic analysis impossible. The carrier can expose additional metadata: a TCP peer sees the connection’s IP address, and a radio observer can detect transmissions. A Ratspeak Channels hub is also an application endpoint and can read room messages.
Network Identities
A Network Identity is a normal Reticulum identity used to represent a logical network, organization, or group of transport nodes.
Today, its main user-facing role is interface discovery. A transport node can sign discoverable interface announces with a Network Identity. Peers can then accept only discovery data signed by identities they trust. If encrypted discovery announces are enabled, peers need the Network Identity key material to decrypt the interface information.
Example:
[reticulum]
network_identity = <reticulum-config-dir>/storage/identities/community_mesh
discover_interfaces = yes
interface_discovery_sources = 0123456789abcdef0123456789abcdef
The identity file is sensitive. If you share the full keyset, the recipient can act as that Network Identity.
Wire Format
The base Reticulum packet structure, before an optional interface authentication field, is:
[HEADER: 2 bytes] [ADDRESSES: 16 or 32 bytes] [CONTEXT: 1 byte] [DATA]
The default network MTU is 500 bytes.
Header Byte 1
| Bit | Field | Values |
|---|---|---|
| 7 | IFAC flag | 0 open, 1 interface authentication present |
| 6 | Header type | 0 one address, 1 two addresses |
| 5 | Context flag | Meaning depends on packet context |
| 4 | Propagation type | 0 broadcast, 1 transport |
| 3-2 | Destination type | 00 Single, 01 Group, 10 Plain, 11 Link |
| 1-0 | Packet type | 00 Data, 01 Announce, 10 Link Request, 11 Proof |
Header Byte 2
The second byte is the hop count. It is incremented by transport nodes as the packet moves through the network.
Address Field
| Header type | Size | Contents |
|---|---|---|
| Type 1 | 16 bytes | Destination hash |
| Type 2 | 32 bytes | Transport ID hash, then destination hash |
Type 2 headers are used for transported packets that need an explicit transport identifier.
Packet Size Limits
| Limit | Size | Meaning |
|---|---|---|
| MTU | 500 bytes | Maximum on-wire Reticulum packet size |
| Plain packet MDU | 464 bytes | Maximum protocol payload for direct Plain packets |
| Encrypted Single packet payload | 383 bytes | Maximum encrypted Single destination packet payload |
| Link packet MDU | 431 bytes | Default payload size for encrypted Link packets |
These are default protocol budgets, not guaranteed application payload sizes on every interface. IFAC overhead and interface/link capacity can reduce the usable budget. Ratspeak 1.1.0 also turns on link MTU discovery by default, so a link over a fast interface can carry larger packets than the default link MDU; Settings → Network → Links turns it off.
LXMF messages have smaller content limits because LXMF adds destination fields, timestamps, signatures, and structured-message overhead. The default LXMF opportunistic content ceiling is 287 bytes before additional title/fields/stamp effects. It is not a fixed app text limit; larger messages use Direct link delivery or resources.
Interface Access Codes
When IFAC is enabled, an interface derives signing material from the configured network_name and/or passphrase. Outbound packets receive an interface authentication code, which may be a full or truncated Ed25519 signature depending on interface configuration. IFAC also masks the packet header and payload with material derived from the shared interface key.
Receivers verify that code before passing the packet to Reticulum. Invalid packets are dropped silently. IFAC is useful for private segments over shared carriers, but it is not a substitute for Reticulum identity encryption.
Receipt Proofs
Packet receipt proofs are cryptographic. A destination can prove receipt by signing the hash of the received packet with its Ed25519 signing key. The proof can travel back through the network, and the sender verifies it against the destination's known public key.
For Single-destination packet receipts, verification uses the destination’s signing key. Link packet proofs instead use the proof sender’s signing key: the initiator’s temporary link key or the responder’s destination key. The peer that received the packet creates this proof; the original packet sender verifies it. A proof confirms the protocol receipt it covers; it does not prove that a person read a message.
Traffic Handling
Routing does not guarantee application-level delivery order or priority. Use a Reticulum Channel when ordered delivery is needed, or a Resource for a larger reliable transfer. Interface queues, airtime limits and announce scheduling affect when traffic can leave a node.