Rust Parallel Implementation

Document Type: Architecture vision and migration strategy Last Updated: 2026-02-24 Status: Active

Styrene’s wire protocol is the shared contract between implementations. This document describes the Rust parallel implementation — a fork of FreeTAKTeam/LXMF-rs — that will run alongside the Python stack, share the wire protocol, and eventually enable selective component replacement.

Document Hierarchy

Motivation

Why Rust

Python is correct for rapid iteration on protocol semantics, TUI development, and ecosystem compatibility. It is not correct for:

• Edge device resource constraints — 512 MB RAM on Pi Zero 2W, shared with BATMAN-adv, RNS, and application workloads. Python’s memory overhead (~30-50 MB baseline for styrened) is significant on constrained devices.
• Transport-layer performance — Packet processing, cryptographic operations (X25519, Ed25519, AES-256), and high-throughput mesh routing benefit from native code. RNS’s Python crypto layer is a measurable bottleneck on ARM.
• Static binaries for fleet deployment — A single styrened-rs binary with no runtime dependencies simplifies Styrix NixOS images, eliminates Python version management on edge devices, and reduces attack surface.
• Concurrency model — Tokio async runtime vs Python’s GIL for handling simultaneous RNS links, LXMF deliveries, RPC handlers, and terminal sessions.

Why Fork LXMF-rs

An audit of every non-Python Reticulum implementation (20 projects across 7 languages — Rust, C, C++, Go, Java, Kotlin, TypeScript) found that FreeTAKTeam/LXMF-rs is the most complete:

• Working: TCP/UDP transport, identity management (X25519 + Ed25519), destinations, links, resources, ratchets
• Working (legacy location): LXMF router, propagation, stamps, delivery pipeline, message packing/unpacking
• Scaffolding: Serial/KISS transport stubs, partial I2P integration
• 55-job CI proving active development (overly complex, but evidence of investment)

No other implementation covers both RNS and LXMF. Starting from a working TCP handshake and identity exchange saves months compared to greenfield.

What Python Keeps

Python remains the primary implementation until the Rust stack passes the interop gate (Phase 3). Specifically:

• styrened — Production daemon, all RPC services, IPC server, conversation/node services
• styrene-tui — Textual TUI (Rust has no equivalent TUI framework at this maturity)
• Wire protocol authority — styrene_wire.py is the reference; Rust must match byte-for-byte
• Ecosystem compatibility — NomadNet, Sideband, MeshChat interop testing stays in Python

Fork Assessment: FreeTAKTeam/LXMF-rs

What Works

What’s Broken

What’s Scaffolding

• Serial/KISS transport — type stubs only, no implementation
• I2P transport — partial integration, non-functional
• crates/internal/ separation — “legacy” crates contain the working LXMF code; “libs” versions are incomplete rewrites

Crate Architecture

Workspace Layout

styrene-rs/
  Cargo.toml              # workspace root
  justfile
  LICENSE                  # MIT (preserved from fork)
  UPSTREAM.md              # Fork attribution, upstream tracking
  CLAUDE.md

  crates/
    libs/
      styrene-rns/         # RNS protocol core
      styrene-rns-transport/  # Transport interfaces
      styrene-lxmf/        # LXMF messaging protocol
      styrene-mesh/         # Styrene wire protocol envelope
    apps/
      styrened-rs/          # Daemon binary (skeleton)
      interop-test/         # Interop test harness
    meta/
      styrene/              # Meta-crate re-exporting all libs

  tests/
    interop/
      python/              # Python scripts for cross-impl testing
      fixtures/            # Binary test vectors generated from Python

Crate Dependency Graph

styrene (meta-crate)
├── re-exports styrene-rns
├── re-exports styrene-lxmf
├── re-exports styrene-rns-transport
└── re-exports styrene-mesh

styrene-lxmf
├── styrene-rns (identity, destinations, links)
└── styrene-rns-transport (send/receive)

styrene-mesh
├── styrene-rns (identity for signing)
└── styrene-lxmf (LXMF envelope)

styrene-rns-transport
└── styrene-rns (packet types, identity)

styrened-rs
├── styrene (all libs via meta-crate)
├── tokio (async runtime)
└── clap (CLI)

interop-test
├── styrene (all libs via meta-crate)
└── test fixtures from Python

Crate Descriptions

Wire Protocol Contract

The wire protocol is the shared contract between Python and Rust implementations. Both must produce and consume identical byte sequences.

Reference Implementation

Python: styrened/src/styrened/models/styrene_wire.py

Wire Format v2

[namespace:10][version:1][type:1][request_id:16][payload:variable]
 "styrene.io"   0x01    enum    os.urandom(16)    msgpack-encoded

Message Type Ranges

Interop Contract

1. Python encodes a message → Rust decodes it → fields match exactly
2. Rust encodes a message → Python decodes it → fields match exactly
3. Both derive identical destination hashes from the same identity
4. Both produce compatible LXMF envelopes (FIELD_CUSTOM_TYPE, FIELD_DATA)
5. Both handle ratchet key rotation identically (forward secrecy preserved across implementations)

Rust Implementation

The styrene-mesh crate implements this contract:

• StyreneMessage struct matching Python’s wire format
• StyreneMessageType enum with identical byte values
• encode() / decode() producing byte-identical output to Python
• msgpack serialization via rmp-serde
• Property-based tests with Python-generated fixtures

Key Decisions

Fork Over Greenfield

Decision: Fork FreeTAKTeam/LXMF-rs rather than writing Rust RNS from scratch.

Rationale: The fork provides working TCP/UDP transport, complete identity management, and a real LXMF implementation. Greenfield would require 6-12 months to reach the same baseline. Known bugs (IFAC, HMAC timing, double-ephemeral) are fixable; missing features are additive.

Trade-off: Inherit upstream code style and structure. Mitigated by immediate restructuring (crate rename, legacy merge, workspace reorganization).

Wire Protocol as Contract

Decision: The wire protocol (not a library API) is the integration boundary between Python and Rust.

Rationale: This is already the architecture — architecture-decisions.md specifies “coupling at the package boundary (dependency declaration + IPC/wire protocol) rather than deep library entanglement, enabling future rewrites of individual components in other languages.” The Rust implementation validates this architectural choice.

Implication: No FFI, no PyO3 bindings, no shared memory. Implementations communicate over LXMF like any two Reticulum nodes. A Python styrened and a Rust styrened-rs can coexist on the same mesh without knowing about each other.

styrene- Crate Namespace

Decision: All crates use the styrene- prefix (not rns- or lxmf-).

Rationale: Upstream uses rns-core, lxmf-core — generic names that could conflict with other RNS implementations. The styrene- prefix claims a clear namespace, signals that these are Styrene project crates (not official RNS), and aligns with the styrene-lab org name.

Python Primary Until Interop Gate

Decision: Python styrened remains the production implementation until Rust passes the interop gate (Phase 3).

Rationale: The Rust stack must prove wire compatibility before it replaces anything. The interop gate is a hard requirement: Python-generated test vectors must round-trip through Rust perfectly. Until then, Rust is experimental and Python is production.

Migration Phases

Phase 1: Fork and Foundation

Goal: Clean fork, restructured workspace, all crates build and test.

Phase 2: Wire Parity

Goal: styrene-mesh crate produces byte-identical output to styrene_wire.py.

Phase 3: Interop Gate

Goal: Python and Rust implementations communicate over a live Reticulum mesh.

Gate criteria: All tests in tests/interop/ pass with a Python RNS/LXMF/styrened instance and a Rust styrene-rs instance on the same Reticulum mesh.

Phase 4: Transport Expansion

Goal: Rust implementation covers transport types beyond TCP/UDP.

ESP32 detail: A 4-phase ESP32 bring-up plan in styrene-edge covers the full path from ESP-IDF validation through direct SX126x SPI radio drivers. ESP32 cannot run Python styrened — Rust is the only viable path to autonomous Styrene on ESP32.

Phase 5: Selective Replacement

Goal: Rust replaces Python on resource-constrained edge devices.

Parallel Development Strategy

What Each Language Owns

Synchronization Points

1. Wire protocol changes — Any change to styrene_wire.py must be reflected in styrene-mesh before merge. CI enforces this via interop tests.
2. Message type additions — New StyreneMessageType values added to Python enum must be added to Rust enum. The interop test suite catches drift.
3. Crypto algorithm changes — Any change to RNS identity, encryption, or ratchet algorithms must be synchronized. This is rare (RNS upstream changes).
4. Transport behavior — TCP/UDP framing, handshake sequences, and packet formats must match. Verified by interop transport tests.

Development Workflow

Python (styrened)                    Rust (styrene-rs)
     │                                    │
     │  wire protocol change              │
     ├──────────────────────────────────►  │
     │                                    │  update styrene-mesh
     │                                    │
     │  generate test vectors             │
     ├──────────────────────────────────►  │
     │                                    │  run interop tests
     │                                    │
     │         interop CI gate            │
     │◄──────────────────────────────────►│
     │    (both must pass before merge)   │

References

• architecture-decisions — Distribution model enabling language-independent replacement
• PROVISIONING-VISION — Wire Format v2 specification
• components — Component inventory including Rust crates
• FreeTAKTeam/LXMF-rs — Upstream fork source
• Reticulum Documentation — Protocol specification

Revision History