How markqvist/reticulum works
─────────────────────────────────────────────
Project Type and Purpose
─────────────────────────────────────────────
• Project Type: Reticulum is a complete networking stack implemented in Python. It’s designed for building local and wide‑area networks using diverse physical media.
• Purpose: It provides end‑to‑end encryption, multi‑hop routing based on cryptographic principles, and a flexible, modular interface system. The system is intended for constructing resilient, decentralized networks without traditional IP dependencies.
─────────────────────────────────────────────
File Structure and Main Code Components
─────────────────────────────────────────────
• Core Library Directories:
• “RNS”: This is the heart of the network stack that contains modules such as:
• Cryptography modules (located in RNS/Cryptography): Implements AES, Ed25519, HKDF, HMAC, and other primitives. It also includes both OpenSSL‑backed and pure‑Python implementations.
• Network interfaces (RNS/Interfaces): Contains a variety of interface types (TCP, UDP, serial, Android, pipe, I2P) – these are the pluggable modules that allow Reticulum to communicate over different physical media.
• Core Networking Modules: Files like Buffer.py, Channel.py, Destination.py, Identity.py, Link.py, Packet.py, Resolver.py, Resource.py, Reticulum.py, and Transport.py represent various layers of the network stack (from link and packet management up to transport and routing).
• Utilities (RNS/Utilities): Contains helper modules such as rncp, rnid, rnprobe, rnpath, rnstatus, and rnx which are also exposed as command-line tools.
• “CRNS”: Likely represents an earlier or complementary core library (possibly encapsulating lower‑level network routines) with its own __init__.py file.
• Examples & Tests:
• “Examples”: Simple demonstration scripts (e.g., Announce.py, Echo.py, Filetransfer.py) showing how to use the networking stack.
• “tests”: Contains test suites for verifying functionality of channels, hashes, identity, links, and configuration.
• Documentation & Community Files:
• “docs” and README, Roadmap, Changelog, and Contributing files provide further context on the architecture and usage.
─────────────────────────────────────────────
Main Components
─────────────────────────────────────────────
A. Application/Utility Layer
– Reticulum Daemon (rnsd): Runs the networking system as a service.
– Command‑line utilities (rnstatus, rnpath, rnprobe, rnid, rncp, rnx) that interact with the core stack to manage and diagnose the network.
B. Core Networking Stack (RNS)
– Packet, Channel, and Buffer: Responsible for data segmentation, reliable delivery, and sequencing (ensuring unforgeable delivery acknowledgements and sequential packet handling).
– Link and Transport Management: Modules that establish and manage physical or virtual links between nodes and handle multi‑hop routing.
– Identity and Routing: Components that manage globally unique addressing, routing, and identity keys.
C. Cryptography Subsystem (RNS/Cryptography and sub‑directories)
– Cryptographic Primitives: Implements symmetric (AES‑128 in CBC mode, PKCS7 padding) and asymmetric algorithms (Ed25519 signatures, X25519 ECDH), as well as hashing functions (SHA‑256, SHA‑512).
– Dual Implementations: Shows dependency on external PyCA/cryptography/OpenSSL if available, with an internal pure‑Python fallback.
D. Interface Modules Layer (RNS/Interfaces)
– Multiple interface implementations (e.g., TCPInterface, UDPInterface, KISSInterface, SerialInterface, Android interfaces, I2PInterface, LocalInterface) that abstract the actual connectivity over diverse physical and virtual mediums.
E. External Dependencies
– Third‑party libraries: PyCA/cryptography, pyserial, and others which gate the functionality (e.g., faster cryptographic operations with OpenSSL vs. fallback on slower pure‑Python variants).
– System configuration files and build scripts (e.g., setup.py, Makefile, GitHub workflows) support testing and continuous integration.
─────────────────────────────────────────────
Relationships and Interactions Between Components
─────────────────────────────────────────────
• The Application/Utility Layer (rnsd and CLI utilities) calls into the Core Networking Stack.
• The Core Stack leverages:
• The Cryptography Subsystem to secure network communications (signing, encryption/decryption, token generation).
• The Interface Layer to send and receive data over various physical media.
• Data and commands typically flow as follows:
1. User initiates a command via a utility (e.g., rnstatus).
2. The utility interfaces with the core (RNS modules) to interpret routing, identity, and packet information.
3. The core interacts with one or more interface modules for actual data transmission or reception.
4. During these operations, cryptographic modules secure data and verify communications.
5. Underneath, lower-level packet handling (channel, link, buffer management) provides reliable data transfer.
• Command/control flow (utilities → core stack).
• Data flow between the core stack and the interfaces.
• Security dependency flow (from core stack to cryptographic modules).
• External dependency linkages (showing where PyCA/cryptography and pyserial integrate).
─────────────────────────────────────────────
Architectural Patterns and Principles
─────────────────────────────────────────────
• Layered Architecture: Separate layers for interfaces, core network logic, and security.
• Modularity: Pluggable interface modules that allow users to extend or customize functionality easily without rewriting core logic.
• Separation of Concerns: Distinct categorizations for networking, identity management, transport, and encryption.
• Redundancy & Fallback: Dual cryptographic implementations (external libraries versus pure‑Python), ensuring flexibility in deployment across different systems.
─────────────────────────────────────────────
─────────────────────────────────────────────
• Start at the top with the “Application/Utility Layer” (rnsd, rnstatus, etc.) that manages and interacts with the entire system.
• Underneath, have a large container for the “Core Networking Stack (RNS)” that further divides into:
• Packet/Channel/Buffer Management, Link/Transport Handling, and Identity/Routing Management.
• Finally, annotate dependencies on external libraries (PyCA/cryptography, pyserial), configuration and build scripts, and testing/doc components.
• That each component is:
• Clearly labeled.
─────────────────────────────────────────────
Conclusion
─────────────────────────────────────────────