Research Index

Purpose: Active research notes and concept references supporting Styrene development. These documents inform implementation decisions in architecture-decisions, provisioning-vision, and styrene-tui-vision.

How to Use This Index

Foundational Concepts

Reference documentation for technologies Styrene builds upon.

Reticulum

Type: Transport Layer

Cryptography-based networking stack. Identity-based routing, end-to-end encryption, transport-agnostic. The foundation for all Styrene fleet communication.

LXMF

Type: Message Protocol

Lightweight Extensible Message Format. Provides reliable message delivery with store-and-forward capability. Wire format for Styrene RPC.

BATMAN-adv

Type: Layer 2 Mesh

Linux kernel module creating virtual network switch across wireless hops. Solves physical connectivity while Reticulum solves logical connectivity.

NomadNet

Type: Application Platform

Text-based communication platform on Reticulum/LXMF. Serves as Styrene Hub for fleet configuration and identity registry.

LoRa

Type: Radio Technology

Long-range, low-power radio. Supplementary transport for Styrene when WiFi unavailable.

BLE Mesh Transport

Type: Radio Technology / Transport Layer

Bluetooth Low Energy as a mesh carrier, phone bridge relay, and WiFi downgrade path. Fills the gap between LoRa (long range, very low throughput) and WiFi (high throughput, needs infrastructure). Covers: phone bridge architecture, BitChat analysis, hardware matrix, power data, implementation roadmap.

NixOS

Type: Operating System

Declarative Linux distribution for fleet devices. Atomic upgrades, reproducible builds, remote management.

Nix Docker Image Building

Type: Build Tooling

Using Nix dockerTools to build reproducible, minimal Docker images without a Dockerfile or Docker daemon. Complements NixOS fleet pattern for containerized workloads.

Textual

Type: TUI Framework

Python framework for terminal interfaces. Powers the styrened TUI (styrened.tui).

Core Styrene Research

Architecture and protocol design for the Styrene system.

Organic Documentation (Polymers)

Status: Reference document

The molecular metaphor mapping Styrene components to polymer chemistry:

• Atoms (C1-C6, H1-H8) = protocol components and ecosystem apps
• Polymers (PS, EPS, ABS, SAN, etc.) = reference architectures for different fleet topologies
• Current implementation status and roadmap

Rust Parallel Implementation

Status: Phase 1 (Fork and Foundation)

Parallel Rust implementation of the RNS/LXMF stack, forked from FreeTAKTeam/LXMF-rs:

• Fork assessment: what works, what’s broken, what’s scaffolding
• Crate architecture: styrene-rns, styrene-lxmf, styrene-mesh, styrene-rns-transport
• Wire protocol contract: Python and Rust must produce identical byte sequences
• 5-phase migration: Fork → Wire Parity → Interop Gate → Transport Expansion → Selective Replacement

Wire Protocol v2 Migration

Status: Approved, implementation complete (tests pending)

Consolidating RPC and StyreneProtocol into a single binary wire format:

• LXMF FIELD_CUSTOM_TYPE integration
• 16-byte random request_id for correlation
• Message type allocation (256 types, semantic ranges)
• Backward compatibility with non-Styrene LXMF clients

Mesh VPN: LXMF-Negotiated WireGuard Tunnels

Status: Architecture / Design — Phase 1 planned

Using LXMF as the signaling and key exchange channel to bootstrap WireGuard mesh VPNs:

• Separation of control plane (LXMF/RNS, any transport) and data plane (WireGuard over 802.11s/Ethernet)
• Trust model: RNS identity authenticates WireGuard pubkey exchange — no PKI, no key ceremonies
• Wire protocol extension: TUNNEL_OFFER/ACCEPT/REJECT/TEARDOWN/REKEY/KEEPALIVE/TOPOLOGY (0xD8–0xDE)
• 4-tier transport model: OFFLINE → RNS_LORA → RNS_WIFI → FULL (automatic promotion/demotion)
• Overlay IP assignment: deterministic from RNS hash, hub-assigned, or static
• 802.11s mesh integration with optional SAE (WPA3) passphrase distribution via LXMF
• 3-phase implementation: LAN tunnel negotiation → 802.11s integration → fleet-wide mesh VPN

Fleet Provisioning via Typed RPC

Status: Draft

Expanding the 0x40-0x5F RPC command range with typed provisioning operations instead of tunneling SSH/Ansible over the mesh:

• 7 new command types: CONFIG_PUSH, PACKAGE_ENSURE, SERVICE_STATE, FILE_WRITE, SCRIPT_EXEC, SYSTEM_UPDATE, HEALTH_CHECK
• Idempotent, declarative operations over LXMF store-and-forward
• Ansible connection plugin mapping modules to Styrene RPCs
• Store-and-forward advantage for offline fleet provisioning
• Per-type authorization tiers and security model

RNS Ecosystem Research

Understanding and leveraging the Reticulum application ecosystem.

Application Stack Survey

Status: Survey complete

Comprehensive catalog of the RNS ecosystem:

• Protocols: LXMF (mature), LXST (alpha), RRC (functional)
• Clients: Sideband, NomadNet, MeshChat, MeshChatX, Columba
• Remote access: rnsh (production-ready with LoRa caveats)
• Automation: LXMFy bot framework
• Maturity ratings for all projects

YubiKey-Backed RNS Identity

Status: Research complete, Phase 1 implementation planned

Hardware-backed operator identity using YubiKey FIDO2 hmac-secret:

• RNS identity internals: 64-byte raw binary (X25519 + Ed25519), no PKCS/PEM
• Approach A (recommended): FIDO2 hmac-secret PRF → deterministic keypair derivation, zero RNS patches
• Phase 1 implementation in styrened as identity provider

Terminal Session Design

Status: Shipped (TerminalService)

Interactive terminal sessions over the mesh:

• rnsh analysis: Protocol, state machine, auth model
• Implemented: LXMF control + RNS Link data channel (Option B)
• EXEC command for non-interactive use (Option C)

Pub/Sub over LXMF

Status: Options documented

Message broker patterns for mesh networks:

• Why traditional brokers (AMQP, MQTT) don’t fit Reticulum
• Native LXMF pub/sub proposal (recommended)
• MQTT bridge at edge for external integration
• Scaling considerations (local registry vs. infrastructure mode)

Matrix + Reticulum Integration

Status: Research complete

Feasibility of integrating Matrix with the Reticulum network stack:

• lxmf_bridge_matrix — the only existing implementation (message-level bridge)
• Architectural incompatibility prevents native Matrix-over-Reticulum
• Assessment: nice-to-have gateway for fleet alerts/monitoring, not a transport replacement

TUI Device Experience

Status: Research complete, implementation plan drafted

Unified TUI environment for fleet devices without graphical desktop:

• Recommendation: Zellij session shell + styrene-tui dashboard pane
• 5-phase implementation plan: NixOS session module → dashboard mode → WASM status bar → textual-web → Cage kiosk
• NixOS module design with per-device-tier layouts (headless/constrained/capable)

Hardened Mobile Platform

Status: Research complete — not yet filed as vault document

Landscape assessment of hardened Android ROMs for the Styrene mobile tier (GrapheneOS, CalyxOS, iodéOS). Current decision: generic Android + Sideband. iOS out of scope. Hardened ROM recommendations deferred until hands-on testing with flashed devices.

Forge Sovereignty Assessment

Status: Concept — not yet written

EU data sovereignty migration assessment for styrene-lab source code hosting. Self-hosted Forgejo on Hetzner as leading candidate.

Organizational

Non-core research supporting styrene-lab operations.

Centralized Skills Repository

Status: Superseded by pi-kit

Originally proposed styrene-lab/claude-skills — now handled by pi-kit.

GitHub Operations

Status: Reference

CLI patterns for styrene-lab org management: repository transfers, secrets management, graduation checklist.

Infrastructure (Vanderlyn-Specific)

Research supporting vanderlyn homelab infrastructure.

mTLS via Vault PKI

Status: Future exploration

Client certificate authentication at Traefik ingress via Vault PKI secrets engine.

Implementation Status Summary

Open Threads

Active questions and gaps across research:

1. Terminal integration — TerminalService shipped; TUI integration via IPC pending
2. Hub/NomadNet testing — Micron pages untested on actual Hub
3. Pub/sub — Native LXMF approach approved, no implementation
4. Scaling — Infrastructure mode for 10K+ nodes documented but not built
5. Offline provisioning — Pre-caching strategy TBD for air-gapped scenarios
6. TUI device experience — Hybrid approach (Zellij + styrene-tui) planned, NixOS module not yet built
7. YubiKey identity — FIDO2 hmac-secret derivation approved, styrened integration planned. Open: revocation strategy, multi-identity namespace, fleet device key management.
8. Mobile platform — Current stance: generic Android + Sideband. Future: acquire test devices, flash ROMs, validate connectivity.
9. Forge sovereignty — Self-hosted Forgejo on Hetzner recommended. Open: domain choice, container registry strategy, migration timeline.
10. BLE mesh transport — Research complete with 4-phase roadmap. Open: Phase 1 phone bridge, nRF52840 dongle evaluation, BLEInterface class design.
11. Rust parallel implementation — Fork complete, Phase 1. Open: crate rename, interop test harness, crates.io placeholder publishing.
12. Fleet provisioning RPC — Draft complete. Open: LXMF size limits, Nix-specific semantics, rollback strategy.
13. Mesh VPN / WireGuard tunnels — Architecture complete. Open: key derivation strategy, IPv6 overlay, bridge mode for LoRa↔WiFi routing.

Research Workflow

When adding new research:

1. Create file in appropriate subdirectory (or root for core Styrene)
2. Add frontmatter with status, date, tags, and up link
3. Update this index with brief description
4. Link to/from relevant vision documents

Last updated: 2026-03-05