LXMF (Lightweight Extensible Message Format)

Reticulum decouples Identity from Location. In traditional networking (like IP), an address is a location (a coordinate in a grid). In Reticulum, an address is a Hash of an Identity.

• Portable Identity: Because an address is a cryptographic representation of who you are rather than where you are, it is portable. You can move between different physical layers (WiFi, LoRa mesh, packet radio) without changing your address.
• Destination Hash: When sending a packet, you target a specific Destination Hash. The network dynamically discovers where that entity currently resides without needing a central directory or a static coordinate.

// The Old Way (IP): "I am at 192.168.1.5. Come find me"
// The Zen Way (Reticulum): "I am <327c1b2f87c9353e01769b01090b18f2>. Wherever I am, my peers can reach me"

LXMF uses end-to-end encryption provided by Reticulum. The specific scheme depends on the delivery method:

1. Standard Reticulum Link: Uses ephemeral AES-128 keys derived with ECDH on Curve25519 (provides Forward Secrecy).
2. Opportunistic Delivery: Embedded in a single Reticulum packet; uses per-packet AES-128 keys derived with ECDH on Curve25519.
3. GROUP Destination: Uses the symmetric AES-128 key of the Reticulum GROUP destination.

LXMF messages are stored in an efficient format designed for low bandwidth. A message is identified by a message-id (a SHA-256 hash of the Destination, Source, and Payload).

Mandatory Fields:

• Destination: 16-byte Reticulum destination hash.
• Source: 16-byte Reticulum source hash.
• Signature: 64-byte Ed25519 signature of the Destination, Source, Payload, and message-id.
• Payload: A msgpack list containing:
  • Timestamp: Double-precision float (UNIX epoch).
  • Content: The message body (optional, but must be present in structure).
  • Title: Optional title.
  • Fields: Optional dictionary for metadata or command structures.

Wire Format Overhead: The total overhead is 111 bytes (16 destination + 16 source + 64 signature + msgpack payload overhead).

Unlike traditional decentralized systems (like some blockchains or federated protocols) that may still rely on dominant nodes or central authorities, Reticulum is designed for Uncentralizability.

Key characteristics include:

• No Privileged Nodes: Every peer is treated as potentially hostile. There are no administrative hierarchies.
• Blind Routing: While some nodes act as Transport Instances to forward traffic, they do so blindly. They route based on cryptographic proofs rather than administrative privilege and cannot see the content or the ultimate identity of the participants.
• Structural Impossibility of Hierarchy: Because there is no central registry, addresses cannot be hijacked, and there is no central switch to block users.

Reticulum operates on a Zero-Trust architecture, assuming that every environment is hostile and every link is potentially compromised.

• Encryption as a Fundamental Requirement: Encryption is not an optional feature or a plugin; it is the core mechanism that enables routing. The Transport system uses cryptographic signatures and entropy to verify paths. Without encryption, the routing logic itself would fail.
• Cryptographic Proof vs. Institutional Trust: Instead of relying on Certificate Authorities or institutional gatekeepers, Reticulum relies on Cryptographic Proof. Trust is binary and mathematical: you trust a destination because you have verified its hash fingerprint, and the math confirms the signature matches the private key.

The Reticulum reference implementation is governed by a specific ethical framework known as the Harm Principle.

Key distinctions:

• The Protocol vs. The Implementation: The mathematical rules of the Reticulum protocol are in the Public Domain and can be used by anyone to build any system. However, the specific reference implementation (the Python code and maintained software) is licensed to forbid use in systems designed to harm humans (e.g., weaponized drone controllers, torture devices, or mass surveillance systems).
• AI Appropriation Protection: The license is designed to protect the software from being used as a dataset for machine learning/AI training that seeks to replace human agency.
• Intent: The software is intended to be a tool for human-to-human connection and sovereign peer interaction, rather than a tool for extraction or centralized control.

You can install LXMF using pip or pipx.

If your operating system blocks normal user package installation via pip, you can enable it by adding break-system-packages = true to the [global] section of your ~/.config/pip/pip.conf file.

# Using pip
pip install lxmf

# Using pipx for an isolated environment
pipx install lxmf

The LXMRouter is the primary API interaction point for client programs. It manages message packing, encryption, delivery confirmation, path lookup, routing, retries, and failure notifications. To send a message, instantiate an LXMRouter, create an LXMessage, and pass it to handle_outbound().

import LXMF

# Initialize the router
lxm_router = LXMF.LXMRouter()

# Create a message with destination, source, and content
message = LXMF.LXMessage(destination, source, "This is a short, simple message.")

# Send the message
lxm_router.handle_outbound(message)

The lxmd daemon accepts the following command-line options:

• -h, --help: show this help message and exit
• --config CONFIG: path to alternative lxmd config directory
• --rnsconfig RNSCONFIG: path to alternative Reticulum config directory
• -p, --propagation-node: run an LXMF Propagation Node
• -i PATH, --on-inbound PATH: executable to run when a message is received
• -v: verbose mode
• -q: quiet mode
• -s, --service: lxmd is running as a service and should log to file
• --exampleconfig: print verbose configuration example to stdout and exit
• --version: show program's version number and exit

The lxmd program is a lightweight LXMF message router and propagation node daemon. You can run it with various flags to configure its behavior, such as enabling propagation node functionality or specifying custom configuration paths.

# View help for the daemon
$ lxmd --help

# Generate a commented example configuration
$ lxmd --exampleconfig