smolmix

smolmix is a TCP/UDP tunnel over the Nym mixnet. It uses a userspace network stack smoltcp (opens in a new tab) to provide TcpStream and UdpSocket types that work with the async tokio (opens in a new tab) Rust ecosystem e.g. tokio-rustls (opens in a new tab), hyper (opens in a new tab), tokio-tungstenite (opens in a new tab), etc.

The TcpStream type implements tokio's AsyncRead/AsyncWrite traits and UdpSocket provides send_to/recv_from for datagrams.

┌──────────────────────────────────────────────────────────────┐
│  Your application (TLS, HTTP, WebSocket, DNS, etc.)          │
│       └─ smolmix::TcpStream / UdpSocket                      │
│            └─ smoltcp (userspace TCP/IP)                     │
│                 └─ Nym mixnet → IPR exit gateway → internet  │
└──────────────────────────────────────────────────────────────┘

Traffic exits the mixnet at an IPR (Internet Packet Router) exit gateway. The exit IP is the gateway's, not yours.

Runtime and platform support

Other runtimes

smolmix currently requires tokio. The internal pipeline is tokio-based: the bridge task that shuttles packets to the mixnet, the Nym SDK's MixnetClient, and the tokio-smoltcp (opens in a new tab) reactor that drives the userspace TCP/IP stack all run on the tokio runtime.

This means smolmix is not directly compatible with alternative async runtimes like smol (opens in a new tab) or async-std (opens in a new tab). If you need to use smolmix from another runtime, the async-compat (opens in a new tab) crate can bridge the gap.

Non-native smolmix

A WASM version of smolmix is planned for a future release.

Installation

Add smolmix to your Cargo.toml:

[dependencies]
smolmix = "1.21.0"
nym-bin-common = { version = "1.21.0", features = ["basic_tracing"] }
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }

tokio is a transitive dependency of smolmix, but you need to enable rt-multi-thread (the default runtime spun up by #[tokio::main]) and macros (for the #[tokio::main] attribute itself).

nym-bin-common is optional but recommended: it sets up tracing (opens in a new tab) logging so you can see mixnet connection progress.

Minimum Rust version: 1.87+

From Git

For unreleased changes, import directly from the repository:

smolmix = { git = "https://github.com/nymtech/nym", branch = "develop" }

When to use smolmix

Security model

What's protected

The Sphinx encryption is the mixnet transport layer: it protects packets as they traverse the mix nodes. At the exit gateway, the Sphinx layers are stripped and the original IP packet is forwarded to the destination. This is analogous to how a Tor exit node or VPN endpoint unwraps its tunnel.

What's inside that IP packet is up to you. If you connect with TLS (as in the TCP example (opens in a new tab)), the IPR sees encrypted TLS ciphertext going to a destination IP: it knows where but not what. If you send plaintext HTTP, the IPR can read the full request and response.

Trust boundaries

• You trust the mixnet to provide unlinkability between sender and receiver. This is enforced cryptographically by the Sphinx packet format and mixing.
• You trust the IPR exit gateway in the same way you trust a VPN exit or Tor exit node: it can inspect your raw IP packets. The difference is that the IPR doesn't know who is sending the traffic (the mixnet hides your identity).
• Application-layer encryption closes the gap. TLS, Noise Protocol, or any authenticated encryption keeps the payload as ciphertext to the IPR. It can see destination IP and port, but not payload content.

Comparison with other privacy tools

Examples

Runnable examples in smolmix/core/examples/ (opens in a new tab). Each is self-contained; read the //! doc comments at the top of each file for a walkthrough.

cargo run -p smolmix --example <name>

All examples accept --ipr <ADDRESS> to target a specific exit node (pass a Recipient address to Tunnel::builder().ipr_address()).

Architecture

The internal stack (smoltcp reactor, device adapter, bridge task, packet flow) is documented in ARCHITECTURE.md (opens in a new tab). This is also the crate-level documentation on docs.rs.

API reference

Full API documentation is available on docs.rs/smolmix (opens in a new tab).