nym/smolmix/core/src/ARCHITECTURE.md

Architecture

smolmix is a TCP/UDP tunnel over the Nym mixnet. It gives you standard TcpStream and UdpSocket types that work transparently with the async Rust ecosystem (tokio-rustls, hyper, tokio-tungstenite, etc.) while routing all traffic through the mixnet for metadata privacy.

Stack

┌─────────────────────────────────────────────────────────────────┐
│  User code                                                      │
│  tunnel.tcp_connect() → TcpStream (AsyncRead + AsyncWrite)      │
│  tunnel.udp_socket()  → UdpSocket (send_to / recv_from)         │
├─────────────────────────────────────────────────────────────────┤
│  tokio-smoltcp::Net                                             │
│  Owns the smoltcp Interface + SocketSet + async poll loop.      │
│  Manages TCP state machines, retransmits, port allocation.      │
├─────────────────────────────────────────────────────────────────┤
│  NymAsyncDevice  (device.rs)                                    │
│  Stream + Sink adapter for raw IP packets over mpsc channels.   │
├─────────────────────────────────────────────────────────────────┤
│  NymIprBridge  (bridge.rs)                                      │
│  Background task shuttling packets between channels and the     │
│  mixnet. Bundles outgoing packets with MultiIpPacketCodec       │
│  (required by the IPR protocol).                                │
├─────────────────────────────────────────────────────────────────┤
│  IpMixStream → MixnetClient → Nym mixnet → IPR exit node        │
└─────────────────────────────────────────────────────────────────┘

Data flow

outgoing: smoltcp → NymAsyncDevice (Sink) → channel → NymIprBridge → IpMixStream → mixnet
incoming: mixnet → IpMixStream → NymIprBridge → channel → NymAsyncDevice (Stream) → smoltcp

tokio-smoltcp handles all the hard parts (smoltcp polling, TCP state machines, port allocation, waker management). We just give it a device that produces and consumes raw IP packets — NymAsyncDevice wraps the mpsc channel ends in the Stream/Sink traits that tokio-smoltcp requires.

Key design decisions

• Single async device adapter. All traffic flows through one NymAsyncDevice. If you need a new transport type (e.g. ICMP), add a method to Tunnel rather than introducing a separate device — the device and bridge don't need to change. smoltcp already supports ICMP sockets; you'd enable the socket-icmp feature in Cargo.toml, add a method like Tunnel::icmp_socket() that calls the appropriate Net method, and expose the socket type via a re-export in lib.rs.

• Tokio-only. The bridge, SDK (IpMixStream, MixnetClient), and shutdown signaling are tokio-based. The data-plane channels use futures::channel::mpsc because UnboundedSender implements Sink — required by tokio-smoltcp's AsyncDevice trait. An earlier version had a sync smoltcp Device adapter for use without tokio-smoltcp, but it still required a tokio runtime underneath (for the bridge and SDK), so it provided no real runtime independence — just duplicated the bridging logic. If alternative-runtime support is ever needed, it would require swapping out the bridge, SDK, and channel layers — a separate crate, not a feature flag on this one.

• Unbounded channels. The channels between the device and bridge are unbounded. Backpressure is handled at the mixnet layer (IPR protocol), not at the channel level. If that assumption changes, consider bounded channels with a drop policy.

• Medium::Ip (no Ethernet framing). Raw IP packets go in and out, matching what the IPR protocol expects.