lxmf-rs

A Rust implementation of LXMF (LoRa eXtended Messaging Format) for delay-tolerant, low-bandwidth networks. LXMF provides reliable message delivery with end-to-end encryption over networks like LoRa, packet radio, and other constrained communication channels.

Overview

LXMF is a messaging protocol built on Reticulum, designed for reliable communication over extremely constrained networks. It enables store-and-forward messaging, automatic retries, and proof-of-work stamping for spam prevention. This is a Rust port of the Python LXMF v0.9.4 implementation, maintaining full wire compatibility with the Python version.

This implementation is built on top of rns-rs, the Rust implementation of Reticulum, providing a robust foundation for delay-tolerant networking. LXMF-rs is particularly well-suited for embedded systems, Android applications, and any scenario where Rust's performance and no_std support are advantageous.

The project is organized as a Cargo workspace with three crates: lxmf-core (lightweight, no_std compatible), lxmf (full-featured message router), and lxmd (propagation daemon with configurable logging). All 129 tests pass, and the implementation is ready for crates.io publication.

Workspace Crates

Quick Start

Add to your Cargo.toml:

[dependencies]
lxmf = "0.1"

A minimal example that sends a message:

use lxmf::router::{LxmRouter, RouterConfig, OutboundMessage};
use lxmf_core::{constants::*, message};
use rns_crypto::identity::Identity;
use rns_net::node::{RnsNode, NodeConfig};

fn main() {
    // Create identity and router
    let identity = Identity::new(&mut rns_crypto::OsRng);
    let mut router = LxmRouter::new(
        identity,
        RouterConfig::default(),
    );

    // Pack a message
    let timestamp = std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .unwrap()
        .as_secs_f64();
    let packed = message::pack(
        &destination_hash,
        &source_hash,
        timestamp,
        b"Hello",
        b"World!",
        vec![],
        None,
        |data| identity.sign(data).map_err(|_| message::Error::SignError),
    ).expect("pack message");

    // Send via the router (handles retries automatically)
    router.handle_outbound(OutboundMessage {
        destination_hash,
        source_hash,
        packed: packed.packed,
        message_hash: packed.message_hash,
        method: DeliveryMethod::Opportunistic,
        ..Default::default()
    });
}

Embedded / no_std Usage

The lxmf-core crate supports no_std environments for embedded systems. To use without the standard library:

[dependencies]
# Core only - no std, no alloc
lxmf-core = { version = "0.1", default-features = false }

# Or with alloc support (requires defining a global allocator)
lxmf-core = { version = "0.1", default-features = false, features = ["alloc"] }

With alloc (requires global allocator)

#[global_allocator]
static ALLOCATOR: cortex_m_rt::Heap = cortex_m_rt::Heap::empty();

use lxmf_core::{constants::*, message, stamp};

fn pack_message() {
    // Pack/unpack messages
    let packed = message::pack(
        &dest_hash,
        &src_hash,
        timestamp,
        b"Hello",
        b"World",
        alloc::vec::[],  // Use alloc::vec![] with feature
        None,
        |data| Ok([0u8; 64]), // Your signing implementation
    ).unwrap();

    // Validate stamps
    let workblock = stamp::stamp_workblock(&message_hash, 3000);
    let is_valid = stamp::stamp_valid(&stamp, 16, &workblock);
}

Core-only (no alloc)

Without the alloc feature, you get:

• All constants from constants module
• Message enums (MessageState, DeliveryMethod, etc.)
• Stamp validation functions that take slices
• Hash and field parsing utilities

This is useful when you want to implement your own memory management.

Key Features

Messaging

• Multiple Delivery Methods: Opportunistic, direct (link-based), propagated (store-and-forward), and paper (QR/URI)
• Encryption: End-to-end encryption using Ed25519 signatures and Curve25519 ECDH
• Automatic Retries: Configurable retry logic with exponential backoff
• Stamp System: Proof-of-work stamps for spam prevention with ticket-based bypass
• Message Fields: Extensible field system for attachments, telemetry, and custom data

Propagation

• Store-and-Forward: Deliver messages to offline recipients via propagation nodes
• Peer Synchronization: Automatic peer discovery and message distribution
• Stamp Costs: Configurable proof-of-work requirements for anti-spam
• Message Prioritization: Weighted culling and priority destination support

Platform

• no_std Support: lxmf-core works in embedded environments
• Swappable Logger: Use env_logger, Android logcat, or your own logger
• Cross-Platform: Linux, Android, Windows, macOS support

Delivery Methods

Documentation

• Design Document - Comprehensive protocol reference
• lxmd README - Propagation daemon documentation
• Reticulum - Underlying network layer
• rns-rs - Rust Reticulum implementation

Examples

Run examples:

# Send a message (requires RNS transport node)
RUST_LOG=info cargo run --example send_message -- <host:port> <dest_hash>

# Listen for announces
RUST_LOG=info cargo run --example send_message -- <host:port> listen

Project Status

• Version: 0.1.0
• Tests: 129 passing
• Compatibility: Wire-compatible with Python LXMF v0.9.4
• Repository: https://github.com/lelloman/lxmf-rs

Contributing

Contributions are welcome! Please see the design document for detailed technical information about the protocol and implementation architecture.

License

This project is licensed under the Reticulum License - see LICENSE for details.

Key license restrictions:

• The software shall not be used in systems designed to harm human beings
• The software shall not be used to train AI/ML models or create training datasets

Copyright (c) 2016-2026 Mark Qvist Copyright (c) 2025-2026 lxmf-rs contributors