Skip to main content

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​

TypeEncryptionMulti-hopTypical use
SingleAsymmetric, per-packet ECDHYesPrivate application endpoints, including LXMF inboxes
LinkEphemeral ECDH sessionYesReliable channels, requests, responses, resources
GroupSymmetric pre-shared keyNoDirect local group traffic with a shared key
PlainNoneNoDirect 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.

NamePurpose
lxmf.deliveryLXMF message delivery destination
lxmf.propagationLXMF propagation node endpoint
nomadnetwork.nodeNomadNet 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:

FieldPurpose
Destination hashThe 16-byte address being announced
Public key materialX25519 and Ed25519 public keys for the identity
Name hashThe compact hash of the application destination name
Random hashFreshness material used in announce validation
Ratchet keyOptional current ratchet public key
SignatureEd25519 signature proving the announce belongs to the identity
Application dataOptional 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.

RuleEffect
Duplicate filteringAlready-seen announces are ignored
Hop limitThe default maximum announce depth is 128 hops
Bandwidth capScheduled announces are limited by a bandwidth budget, 2% by default
Randomized delayRe-broadcasts are delayed to avoid synchronized floods
Locality priorityLower-hop announces are sent before distant ones when bandwidth is scarce
ReplacementNewer 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.

  1. Node A announces its destination on its interfaces.
  2. A transport node hears the announce and records "A is reachable through this neighbor on this interface."
  3. The transport node re-broadcasts the announce with an incremented hop count.
  4. 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​

BitFieldValues
7IFAC flag0 open, 1 interface authentication present
6Header type0 one address, 1 two addresses
5Context flagMeaning depends on packet context
4Propagation type0 broadcast, 1 transport
3-2Destination type00 Single, 01 Group, 10 Plain, 11 Link
1-0Packet type00 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 typeSizeContents
Type 116 bytesDestination hash
Type 232 bytesTransport ID hash, then destination hash

Type 2 headers are used for transported packets that need an explicit transport identifier.

Packet Size Limits​

LimitSizeMeaning
MTU500 bytesMaximum on-wire Reticulum packet size
Plain packet MDU464 bytesMaximum protocol payload for direct Plain packets
Encrypted Single packet payload383 bytesMaximum encrypted Single destination packet payload
Link packet MDU431 bytesDefault 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.