One wire-format detail the upstream spec leaves implicit: microReticulum splices the request payload and the response into their msgpack envelopes verbatim, so both directions carry the smolmail payload as a msgpack binary. The shim unpacks on the way in and packs on the way out; the Rust side only ever sees `op u8 || body` and `status u8 || payload`.
Only AUTH and REGISTER differ between transports. Both substitutes are 32 bytes; neither input is length-prefixed, and both are fixed-width, so concatenation stays unambiguous.
The second term is AUTH carrying a full token set: ≈32 KiB at the 1024-token default. Enforced in the RNS request handler (`src/rns.rs`); oversized requests answer TOO_LARGE. RNS defaults: `max_envelope` 32 KiB, `fetch_budget` 32 KiB.
`Store::pending` applies the fetch budget per batch and always returns at least one message, so an envelope larger than the budget is still delivered rather than blocking the mailbox head. Over a shared database this means a 768 KiB envelope accepted on TCP will be returned whole to an RNS FETCH. Operators whose users are mesh-first should apply the smaller cap to the whole mailbox (upstream spec 13.7) rather than per transport.
Upstream maintains a [Community Implementations](https://github.com/markqvist/Reticulum#community-implementations) list; the bar is wire-compatibility, sensible security practice, and ≥18 months of active development.
`response_generator` is a plain function pointer with no userdata argument (`Destination.h:43`), so `link_id` arrives as a handler argument and bind values are derived per request; nothing needs mutable per-link setup in C++.
Build: root `CMakeLists.txt`, C++17. Dependencies (ArduinoJson, MsgPack, rweather/Crypto, microStore, ArxContainer, ArxTypeTraits, DebugLog) are pulled with `FetchContent`, each overridable via `RNS_<DEP>_SOURCE_DIR` — which the Nix build uses to vendor everything.
-`Curve25519::eval` does not clamp the scalar (rweather/Crypto), so an independent Rust derivation of the identity's x25519 public key — and therefore of the destination hash — produces a different hash than microReticulum itself. `rns-keygen` prints the hash computed by the shim (`smolmail_rns_destination_hash`), never a Rust-side rederivation.
- Upstream master needs `#include <cstdint>` added to `Utilities/Memory.h` under current libstdc++/libc++; `build.rs` patches its copy of the source, since the input may be a read-only store path.
`src/bind.rs` holds `TransportBindValues { h, server_static }` with two constructors: `tcp(handshake_hash, server_static)` and `rns(destination, link_id)`. `Session` stores the struct instead of a handshake hash; AUTH verifies over `bind.h`, REGISTER over `bind.server_static`. `ServerConfig` carries `fetch_budget` (TCP sets the old `FETCH_BUDGET` const as its default; the RNS carrier sets it from `--rns-fetch-budget`) and no longer carries `server_static` — each transport puts its own value in the bind struct.
| `shim/smolmail_rns.cpp`, `shim/smolmail_rns.h` | C ABI over the C++ API: `smolmail_rns_start` (identity, UDP endpoints, storage dir), `smolmail_rns_destination_hash`, the request handler, link callbacks, and the loop thread driving `Reticulum::loop()` at 10 ms |
| `shim/udp_interface.{h,cpp}` | UDP interface adapted from microReticulum's Apache-2.0 example, with caller-supplied endpoints; with no forward target it sends to the source address of the last datagram received |
| `build.rs` | copies the microReticulum source into `OUT_DIR` (patched), configures and builds it with cmake, compiles the shim with `cc`, and links both archives |
The shim ABI: `smolmail_rns_start` takes the 64-byte identity by pointer (raw bytes, not a C string — a NUL inside the key is valid), and returns the destination hash by pointer. The Rust callbacks (`smolmail_rns_on_request`, `_take_response`, `_on_link_opened`, `_on_link_closed`) fire on the shim's loop thread; the response travels through a single-slot buffer that the shim copies out before the next request.
| `response_generator` is a bare function pointer with no userdata | Rust state lives in `static OnceLock<RnsState>`; `link_id` is the map key |
| Handler is called on microReticulum's thread | the shim owns a dedicated loop thread; `RnsState` holds `Mutex<HashMap<[u8;16], Session>>`, one `Store` per link |
| `Session.username` must live for the link, not the request | session inserted on first request, evicted on link close |
| Link lifecycle | `Destination::set_link_established_callback` installs `Link::set_link_closed_callback` per link; both use `Link::link_id()` as the map key |
| Over-cap teardown would re-enter transport processing | links over `--rns-max-links` are deferred to a queue the loop thread drains after `Reticulum::loop()` returns |
| No `hex` dependency | `data_encoding::HEXLOWER`, already a dependency |
| One process, both carriers | `serve --rns` starts the RNS carrier on the shim's thread and then runs the TCP loop on the main thread; the purge loop stays in `server::run` |
| Identity | `rns-keygen` writes 64 random bytes itself — the exact layout `Identity::to_file` writes and `load_private_key` expects |
`ALLOW_ALL` (microReticulum `Type::Destination::request_policies`, 0x01) admits every requester, matching the Python reference's `Destination.ALLOW_ALL`; registration stays open by design and invite tokens gate it at the operation level, not the link level.
If the shim stalls, run the reference `smolmaild_rns.py` as a sidecar against the same SQLite file. `Store::open` sets WAL and a 10 s busy timeout, so concurrent writers are safe. Cost: a Python runtime in the closure and two implementations of the session rules. Not needed so far.
`--rns-udp`/`--rns-udp-forward` extend the original plan: microReticulum ships no interfaces at all (only examples), so the server needs at least one programmatically. The UDP interface is wire-compatible with the Python reference's `UDPInterface`; TCP and I2P interfaces remain open work.
The per-link request limiter reuses `RateLimiter` keyed by the link hex. The per-IP send limiter has no analogue (upstream spec 13.8); it is disabled for RNS sessions, and the accept-token limiter stays on because a token never needed a peer identity.
- Every microReticulum dependency is a pinned `flake = false` input, passed to build.rs through `RNS_<DEP>_SOURCE_DIR`, so the sandboxed build never fetches.
-`packages.default` builds without the feature; `packages.rns` sets `buildFeatures = [ "rns" ]` and adds cmake/ninja/gcc to `nativeBuildInputs`. `dontUseNinja*` keeps ninja's setup hook from claiming the build phase in place of cargo.
- The dev shell exports the same source variables, so `cargo build --features rns` works in it without a network.
-`services.bunshin.rns.*` mirrors §7.4; the single `bunshin` systemd unit gains the `--rns` flags, since a second `DynamicUser` unit gets a different UID and cannot open the same `mail.db`.
- Firewall: only the RNS UDP interface's port (`openFirewall` opens it); RNS reaches the mesh through a configured interface, not a listening TCP port.
1. Cross-transport envelope size: per-transport caps are enforced; a 768 KiB TCP envelope is still delivered whole to an RNS FETCH. Operators should apply the smaller cap mailbox-wide when in doubt (upstream spec 13.7).
2. Upstream `microReticulum` deadlock: a client dying mid-resource-transfer wedges the single transport loop forever — `Resource::request_next` sends its `RESOURCE_REQ` through `Transport::outbound` from inside the `jobs()` resource tick, and `outbound` busy-waits on `_jobs_running`, a flag `jobs()` itself holds. No announces, no new links, mesh dead until restart. The vendored source is a local fork carrying the fix (same-thread reentrant calls skip the cycle wait); the equivalent report is filed upstream.
3. Interfaces beyond UDP (RNS-compatible TCP hub/client, I2P): microReticulum ships none; the UDP interface is the first supported one.
4. The reference `test_interop/run_request_response.sh` harness was not rerun against the shim; its PlatformIO build step is unavailable here. The equivalent interop was exercised directly against `smolmail_rns.py` (§10.6).
Formerly open items resolved during implementation: raw identity bytes exist (`load_private_key`); the shim ABI and run-loop drive pattern are §7.1/§7.2; `ALLOW_ALL` matches the reference; announcing at startup + every 2 h, unconditional even when invite-only (the invite gates REGISTER, not the link); the interface question is §7.4.
1.`cargo test` — 16 tests pass without the feature, 17 with it.
2.`TransportBindValues::rns` against independently computed SHA-256 vectors — pass.
3. AUTH and REGISTER accept a signature made over the derived values and reject one made over the other transport's, in both directions — pass (`src/session.rs` tests).
4. TCP regression: the 1.1 reference client registers, sends, fetches and deletes against a 1.2 server unchanged — pass.
5. See §9.3 for the upstream interop harness.
6. End-to-end against `smolmail_rns.py` over a local UDP Reticulum testnet: register (two accounts), auth, send, fetch, delete (implicit in the client's fetch-acknowledge) — pass.
7. Same database, both carriers: send over TCP fetched over RNS, and send over RNS fetched over TCP, with the same mailbox identity authenticating over both — pass.
8. Per-link limits: past `--rns-rate-link-requests` the link's requests answer RATE_LIMITED (8); past `--rns-max-links` the extra link is torn down — pass.
9.`nix build .#rns` and `.#default` in a sandboxed build with all dependencies vendored — pass; `nix flake check --no-build` passes; the nix-built `.#rns` binary serves both carriers.
