Reticulum/docs/source/networks.rst

.. _networks-main:

*****************
Building Networks
*****************

This chapter will provide you with the high-level knowledge needed to build networks with
Reticulum. It will not, however tell you all you need to know to succesfully
design and configure every kind of network you can imagine. For this, you will
most likely need to read this manual in its entirity, invest significant time
into experimenting with the stack, and learning functionality intuitively.

Still, after reading this chapter, you should be well equipped to *start* that
journey. While Reticulum is **fundamentally different** compared to other
networking technologies, it can often be easier than using traditional stacks.
If you've built networks before, you will probably have to forget, or at least
temporarily ignore, a lot of things at this point. It will all makes sense in
the end though. Hopefully.

If you're used to protocols like IP, let's at least start with some relief:
You don't have to worry about coordinating addresses, subnets and routing for an
entire network that you might not know how will evolve in the future. With
Reticulum, you can simply add more segments to your network when it becomes
necessary, and Reticulum will handle the convergence of the entire network
automatically. There's plenty more neat aspects like that to Reticulum, but
we're getting ahead of ourselves. Let's cover the basics first.

Concepts & Overview
--------------------

Before you start building your own networks, it's important to understand the
fundamental principles that distinguish Reticulum networks from traditional
networking approaches. These principles shape how you design your network,
what trade-offs you encounter, and what capabilities you can rely on.

Reticulum is not a single network you "join", it is a toolkit for *creating* networks.
You decide what mediums to use, how nodes connect, what trust boundaries exist,
and what the network's purpose is. Reticulum provides the cryptographic foundation,
the transport mechanisms, and the convergence algorithms that make your design
workable. You provide the intent and the structure.

This approach offers tremendous flexibility, but it requires thinking in terms of
different abstractions than those used in conventional networking.

Introductory Considerations
^^^^^^^^^^^^^^^^^^^^^^^^^^^

There are important points that need to be kept in mind when building networks
with Reticulum:

 * | In a Reticulum network, any node can autonomously generate as many addresses
     (called *destinations* in Reticulum terminology) as it needs, which become
     globally reachable to the rest of the network. There is no central point of
     control over the address space.

 * | Reticulum was designed to handle both very small, and very large networks.
     While the address space can support billions of endpoints, Reticulum is
     also very useful when just a few devices needs to communicate.

 * | Low-bandwidth networks, like LoRa and packet radio, can interoperate and
     interconnect with much larger and higher bandwidth networks without issue.
     Reticulum automatically manages the flow of information to and from various
     network segments, and when bandwidth is limited, local traffic is prioritised.
     You will, however, need to configure your interfaces correctly. If you tell
     Reticulum to pass all announce traffic from a gigabit link to a LoRa interfaces,
     it will try as best as possible to comply with this, while still respecting
     bandwidth limits, but you *will* waste a lot of precious bandwidth and airtime,
     and your LoRa network will not work very well.

 * | Reticulum provides sender/initiator anonymity by default. There is no way
     to filter traffic or discriminate it based on the source of the traffic.

 * | All traffic is encrypted using ephemeral keys generated by an Elliptic Curve
     Diffie-Hellman key exchange on Curve25519. There is no way to inspect traffic
     contents, and no way to prioritise or throttle certain kinds of traffic.
     All transport and routing layers are thus completely agnostic to traffic type,
     and will pass all traffic equally.

 * | Reticulum can function both with and without infrastructure. When *transport
     nodes* are available, they can route traffic over multiple hops for other
     nodes, and will function as a distributed cryptographic keystore. When there
     is no transport nodes available, all nodes that are within communication range
     can still communicate.

 * | Every node can become a transport node, simply by enabling it in it's
     configuration, but there is no need for every node on the network to be a
     transport node. Letting every node be a transport node will in most cases
     degrade the performance and reliability of the network.

     *In general terms, if a node is stationary, well-connected and kept running
     most of the time, it is a good candidate to be a transport node. For optimal
     performance, a network should contain the amount of transport nodes that
     provides connectivity to the intended area / topography, and not many more
     than that.*

 * | Reticulum is designed to work reliably in open, trustless environments. This
     means you can use it to create open-access networks, where participants can
     join and leave in a free and unorganised manner. This property allows an
     entirely new, and so far, mostly unexplored class of networked applications,
     where networks, and the information flow within them can form and dissolve
     organically.

 * | You can just as easily create closed networks, since Reticulum allows you to
     add authentication to any interface. This means you can restrict access on
     any interface type, even when using legacy devices, such as modems. You can
     also mix authenticated and open interfaces on the same system. See the
     :ref:`Common Interface Options<interfaces-options>` section of the :ref:`Interfaces<interfaces-main>`
     chapter of this manual for information on how to set up interface authentication.


Reticulum allows you to mix very different kinds of networking mediums into a
unified mesh, or to keep everything within one medium. You could build a "virtual
network" running entirely over the Internet, where all nodes communicate over TCP
and UDP "channels". You could also build such a network using other already-established
communications channels as the underlying carrier for Reticulum.

However, most real-world networks will probably involve either some form of
wireless or direct hardline communications. To allow Reticulum to communicate
over any type of medium, you must specify it in the configuration file, by default
located at ``~/.reticulum/config``. See the :ref:`Supported Interfaces<interfaces-main>`
chapter of this manual for interface configuration examples.

Any number of interfaces can be configured, and Reticulum will automatically
decide which are suitable to use in any given situation, depending on where
traffic needs to flow.

Destinations, Not Addresses
^^^^^^^^^^^^^^^^^^^^^^^^^^^

In traditional networking, addresses are allocated from a managed space. If you want to
communicate with another node, you need to know its address, and that address
must be unique within the network segment. This requires coordination, either
through manual assignment, DHCP servers, or other allocation mechanisms.

Reticulum replaces addresses with **destinations**. A destination is identified by a 16-byte
hash (128 bits) derived from a SHA-256 hash of the destination's identifying
characteristics. This hash serves as the address on the network. On the network, it
is represented in binary, but when displayed to human users, it will usually look something like
this ``<13425ec15b621c1d928589718000d814>``.

The critical difference is that *any node can generate as many destinations as it
needs, without coordination*. A destination's uniqueness is guaranteed by the
collision resistance of SHA-256 and the inclusion of the node's public key in the
hash calculation. Two nodes can both use the destination name
``messenger.user.inbox``, but they will have different destination hashes because
their public keys differ. Both can coexist on the same network without conflict.

This has profound implications for network design:

* **No address allocation planning:** You never need to reserve address ranges,
  plan subnets, or coordinate with other network operators. Nodes simply generate
  destinations and announce them.

* **Global portability:** A destination is not tied to a physical location or
  network segment. A node can move its destinations across interfaces, mediums,
  or even between entirely separate Reticulum networks simply by sending an
  announce on the new medium.

* **Implicit authentication:** Because destinations are bound to public keys,
  communication to a destination is inherently cryptographically authenticated.
  Only the holder of the corresponding private key can decrypt and respond to
  traffic addressed to that destination. This also makes application-level
  authentication *much* simpler, since it can directly use the foundational
  identity verification built into the core networking layer.

* **Identity abstraction:** A single Reticulum Identity can create multiple
  destinations. This allows a single entity (a person, a device, a service) to
  present multiple endpoints without needing multiple cryptographic keypairs.


Transport Nodes and Instances
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Reticulum distinguishes between two types of nodes: **Instances**
and **Transport Nodes**. Every node running Reticulum is an Instance, but not
every Instance is a Transport Node.

A **Reticulum Instance** is any system running the Reticulum stack. It can create
destinations, send and receive packets, establish links, and communicate with
other nodes. It can also host destinations that are connectable for *anyone* else
in the network. This means you can easily host globally available services from
any location, including your home or office. Network-wide, global connectivity
for all destinations is guaranteed, as long as there is *some* physical way to
actually transport the packets. Instances are the default state and are appropriate for most end-user devices,
such as phones, laptops, sensors, or any device that primarily consumes network services.

A **Transport Node** is an Instance that has been explicitly configured to
participate in network-wide transport. Transport nodes forward packets across
hops, propagate announces, maintain path tables, and serve path requests on
behalf of other nodes. When a destination sends an announce, Transport Nodes
receive it, remember the path, and rebroadcast it to other interfaces. When a node
needs to reach a destination it doesn't have a path for, Transport Nodes help
resolve the path through the network.

Even devices hosting services or serving content should probably just be configured
as instances, and themselves connect to wider networks via a Transport Node.
In some situations, this may not be practical though, and as an example, it is
entirely viable to host a personal Transport Node on a Raspberry Pi, while it
is at the same time running an LXMF propagation node, and hosting your personal
site or files over Reticulum.

The distinction is important. **Not** every node should be a Transport Node:

* **Resource consumption:** Transport nodes maintain path tables, process
  announces, and forward traffic. This requires memory and CPU resources that
  may be limited on low-powered devices.

* **Stability requirements:** Transport nodes contribute to network convergence.
  If Transport Nodes frequently go offline, path tables become stale and
  convergence suffers. Stable, always-on nodes make better Transport Nodes.

* **Bandwidth considerations:** Transport nodes process and rebroadcast network
  maintenance traffic. On very low-bandwidth mediums, having too many Transport
  Nodes will consume capacity that should be used for actual data.

In practice, a network typically has a relatively small number of Transport Nodes
strategically placed to provide coverage and connectivity. End-user devices run
as Instances, connecting through nearby Transport Nodes to reach the wider network.
This pattern mirrors traditional networking where routers forward traffic while
end hosts simply consume connectivity, but with the crucial difference that any
node *can* become a router if needed, and the decision is yours to make based on
your network's requirements.

Transport nodes also function as distributed cryptographic keystores. When a
destination announces itself, Transport Nodes cache the public key and destination
information. Other nodes can request unknown public keys from the network, and
Transport Nodes respond with the cached information. This eliminates the need for
a central directory service while ensuring that public keys remain available
throughout the network.

Trustless Networking
^^^^^^^^^^^^^^^^^^^^

Traditional network security models assume high levels of trust at
specific layers. You might trust your ISP to deliver packets without inspection,
or trust your VPN provider to handle your traffic, or trust the network
administrator to configure firewalls appropriately. These trust relationships
create vulnerabilities and dependencies.

Reticulum is designed to function in **open, trustless environments**. This
means the protocol makes no assumptions about the trustworthiness of the network
infrastructure, the other participants, or the transport mediums. Every aspect
of communication is secured cryptographically:

* **Traffic encryption:** All traffic to single destinations is encrypted using
  ephemeral keys.

* **Source anonymity:** Reticulum packets do not include source addresses.
  An observer intercepting a packet cannot determine who sent it, only who it is
  addressed to (unless IFAC is enabled, in which case nothing can be determined).
  This provides initiator anonymity by default.

* **Path verification:** The announce mechanism includes cryptographic signatures that
  prove the authenticity of destination announcements.

* **Unforgeable delivery confirmations:** When a destination proves receipt of a
  packet, the proof is signed with the destination's identity key. This prevents
  false acknowledgments and ensures reliable delivery verification.

* **Interface authentication:** When using Interface Access Codes (IFAC), packets
  on authenticated interfaces carry signatures derived from a shared secret. Only
  nodes with the correct network name and passphrase can generate valid packets, allowing creation
  of virtual private networks on shared mediums.

The trustless design has important consequences for network design:

* **Open-access networks are viable:** You can build networks that anyone can
  join without pre-approval. Because traffic is encrypted and authenticated end-
  to-end, participants cannot interfere with each other's private communication,
  even if they share the same transport infrastructure.

* **No traffic inspection or prioritization:** Because traffic contents and
  sources are opaque to intermediate nodes, there is no mechanism for filtering,
  prioritizing, or throttling traffic based on its type or origin. All traffic
  is treated equally. From a neutrality perspective, this is a feature.

* **Adversarial resilience:** The network can operate even if some nodes are
  malicious or controlled by adversaries. While a malicious Transport Node could
  refuse to forward certain traffic or drop packets, it cannot decrypt, modify,
  or impersonate legitimate traffic. Redundant paths and multiple Transport Nodes
  mitigate the impact of malicious nodes.

Of course, you can also create closed networks. Interface Access
Codes allow you to restrict participation on specific interfaces. Network
Identities enable you to verify that discovered interfaces belong to trusted
operators. Blackhole management lets you block malicious identities. Reticulum
provides both the tools for open networks and the controls for closed ones. The
choice is yours based on your requirements.


Heterogeneous Connectivity
^^^^^^^^^^^^^^^^^^^^^^^^^^

In conventional networking, mixing different transport mediums typically requires
gateways, translation layers, and careful configuration. A WiFi network doesn't
natively interoperate with a packet radio network without additional infrastructure,
and you can't just download a car over a serial port, or send an encrypted message
in a QR code.

Reticulum treats **heterogeneity as a core premise**. The protocol is designed
to seamlessly mix mediums with vastly different characteristics:

* **Bandwidth:** LoRa links operating at a few hundred bits per second can
  interconnect with gigabit Ethernet backbones. Reticulum automatically manages
  the flow of information, prioritizing local traffic on slow segments while
  allowing global convergence.

* **Latency:** Satellite links with multi-second latency can coexist with local
  links measured in milliseconds. The transport system handles timing, asynchronous
  delivery and retransmissions transparently.

* **Topology:** Point-to-point microwave links, broadcast radio networks,
  switched Ethernet fabrics, and virtual tunnels over the Internet can all be
  part of the same Reticulum network.

* **Reliability:** Intermittent connections that come and go (such as mobile
  devices or opportunistic radio contacts) can participate alongside always-on
  infrastructure. Reticulum gracefully handles link loss and reconnection.

This heterogeneity is achieved through several design elements:

* **Expandable, medium-agnostic interface system:** Reticulum communicates with the physical
  world through interface modules. Adding support for a new medium is a matter
  of implementing an interface class. The protocol itself remains unchanged.

* **Interface modes:** Different modes (``full``, ``gateway``, ``access_point``,
  ``roaming``, ``boundary``) allow you to configure how interfaces interact with
  the wider network based on their characteristics and role.

* **Announce propagation rules:** Announces are forwarded between interfaces
  according to rules that account for bandwidth limitations and interface modes.
  Slow segments are not overwhelmed by traffic from fast segments.

* **Local traffic prioritization:** When bandwidth is constrained, Reticulum
  prioritizes announces for nearby destinations. This ensures that local
  connectivity remains functional even when global convergence is incomplete.

For network designers, this means you are free to use whatever mediums are
available, affordable, or appropriate for your situation. You might use LoRa for
wide-area low-bandwidth coverage, WiFi for local high-capacity links, I2P for
anonymous Internet connectivity, and Ethernet for infrastructure backhauls, all
within the same network. Reticulum handles the translation and coordination
automatically.

The key design consideration is not whether different mediums can work together
(they can), but **how** they should work together based on your goals. A node
with multiple interfaces spanning heterogeneous mediums needs to be configured
with appropriate interface modes so that traffic flows efficiently. A gateway
connecting a slow LoRa segment to a fast Internet backbone should be configured
differently than a mobile device roaming between radio cells.