LXMFKit

A pure-Swift implementation of LXMF, the Lightweight Extensible Message Format, built on top of ReticulumKit.

LXMFKit gives Apple-platform apps a native, encrypted, store-and-forward messaging layer that works over any Reticulum transport: LoRa, packet radio, WiFi, or TCP/IP. It is wire-compatible with the reference Python LXMF, so messages you send interoperate with Sideband, MeshChat, NomadNet, and other LXMF clients.

Independent project. LXMFKit is an independent, clean-room Swift implementation of the LXMF protocol. LXMF, Reticulum, and their reference Python implementations are created by Mark Qvist. LXMFKit is not affiliated with or endorsed by the LXMF or Reticulum projects.

Built with AI assistance. LXMFKit is written and maintained by a Swift developer, with AI assistance used as part of the development workflow. The code is human-reviewed and backed by a test suite verified against the reference implementation.

Status: alpha (v0.1.0). The public API may change before 1.0. It is wire-tested against Python LXMF, but treat it as pre-release and pin to an exact version.

What is LXMF?

LXMF is a messaging format and delivery protocol for Reticulum. It defines how a message is composed, signed, and delivered: directly to an online peer, opportunistically as a single encrypted packet, or via a propagation node that stores messages for offline recipients and forwards them later (store-and-forward, like email for the mesh). Messages carry rich, extensible fields: file attachments, inline images, audio, telemetry, and sender appearance.

Features

• Message composition: build, pack, sign (Ed25519), and verify LXMF messages with full wire-format fidelity.
• Delivery methods:
  • Direct: over an established Reticulum Link for reliable, acknowledged delivery.
  • Opportunistic: a single encrypted packet for short messages with no link setup.
  • Propagation: sync to/from a propagation node for offline store-and-forward.
• Rich fields: typed parsers and builders for file attachments, images, audio, icon/appearance, and telemetry.
• Receipts: delivery-state tracking with callbacks as a message progresses.
• Peer discovery: resolve LXMF peers and their display names from Reticulum announces, including advertised stamp cost.
• Stamps: proof-of-work "stamps" (LXStamper) for spam resistance on destinations that require them.

Requirements

• Swift 6.1+
• iOS 16+ / macOS 13+
• Xcode 16+

Installation

Add LXMFKit to your Package.swift:

dependencies: [
    .package(url: "https://github.com/J-Krush/LXMFKit.git", from: "0.1.0"),
],
targets: [
    .target(
        name: "YourApp",
        dependencies: [
            .product(name: "LXMFKit", package: "LXMFKit"),
        ]
    ),
]

LXMFKit pulls in ReticulumKit automatically as a dependency. Or in Xcode: File > Add Package Dependencies and enter the repository URL.

Quick start

Stand up a router on top of a Reticulum transport, then send and receive messages:

import ReticulumKit
import LXMFKit

// 1. Bring up a Reticulum transport with an interface (see ReticulumKit docs).
let identity = Identity()
let transport = Transport()
let tcp = TCPInterface(host: "amsterdam.connect.reticulum.network", port: 4965)
await transport.addInterface(tcp)
try await tcp.start()

// 2. Create the LXMF router. This registers your "lxmf.delivery" destination.
let router = await LXMRouter(transport: transport, identity: identity)

// 3. Handle incoming messages.
await router.onMessage { message in
    let text = String(data: message.content, encoding: .utf8) ?? ""
    print("New message: \(text)")
}

// 4. Announce yourself so peers can find you (with a display name).
try await router.announce(appData: Data("Alice".utf8))

Compose and send a message to a peer:

// `peerHash` is the recipient's LXMF delivery destination hash.
var message = try LXMessage.compose(
    destination: peerHash,
    source: router.destination.hash,
    sourceIdentity: identity,
    title: "Hello",
    content: "Sent from LXMFKit over Reticulum.",
    fields: [:],
    method: .direct          // or .opportunistic / .propagated
)

try await router.send(&message)

Sync from a propagation node to pick up messages received while you were offline:

await router.setPropagationNode(destinationHash: propagationNodeHash)
try await router.syncPropagation()

Architecture

+-----------------------------------------------+
|  Your app                                     |
+-----------------------------------------------+
|  LXMRouter (actor)                            |
|   - send: direct / opportunistic / propagated  |
|   - receive + verify    - delivery receipts     |
|   - peer discovery via announces                |
+--------------+----------------+---------------+
|  LXMessage   |  Fields        |  Propagation  |
|  compose /   |  files, images |  client +     |
|  pack / sign |  audio, etc.   |  stamps (PoW) |
+--------------+----------------+---------------+
|  ReticulumKit  (Transport . Link . Identity)  |
+-----------------------------------------------+

LXMRouter and PropagationClient are Swift actors, so message state is managed without manual locking. The package compiles under Swift 6 strict concurrency checking.

Interoperability

LXMFKit follows the Python LXMF wire format: message packing, the dest + source + signature + msgpack(payload) layout, message-ID hashing, field encoding, and propagation-node sync are all implemented to match the reference. Source references to the corresponding Python modules are cited in the code.

If you find a case where LXMFKit and Python LXMF disagree on the wire, that's a bug. Please open an issue with a fixture or capture.

Related projects

• ReticulumKit: the underlying Reticulum networking stack (required dependency).
• LXMF: the reference Python implementation and format specification.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening a pull request, and note the Code of Conduct. Security issues should follow the process in SECURITY.md; please do not file them as public issues.

License

LXMFKit is released under the MIT License. LXMF and its reference Python implementation, created by Mark Qvist, are likewise MIT-licensed.