mfahampshire
7ceaf9a40e
* Add mixtcp crate
Components:
- NymIprDevice: smoltcp::phy::Device impl using channel-based I/O
- NymIprBridge: async task bridging the device to IpMixStream
- create_device(): helper to set up the complete stack
* - Cleanup
- Add graceful shutdown
- Declutter logging - move a lot of bridge info! -> trace!
- Move rustls, nym-bin-common, bytes to dev-dependencies
- Extract TlsOverTcp to mod.rs
- Make timing more granular
- Update readme
* Add UDP example
* Add UDP example to readme
* rename mixtcp -> smolmix
* Add Tunnel API with TcpStream and UdpSocket over tokio-smoltcp
* Re-export Tunnel API and add init_logging convenience function
* Remove raw smoltcp path, flatten tunnel module
* Clean up bridge, device, and tunnel code
* Consolidate architecture docs, tidy examples and README
- Add src/ARCHITECTURE.md as single source of truth for architecture
- Include in docs.rs via doc = include_str!
- Strip duplicated diagrams from tunnel.rs, device.rs, README
- Extract tls_connector() helper in HTTPS example to match websocket example
- Use consistent 'smolmix' casing in README
* Update smolmix imports for ipr_wrapper API
- stream_wrapper::{IpMixStream, NetworkEnvironment} → ipr_wrapper::
- connect_tunnel() → check_connected()
- disconnect_stream() → disconnect()
- allocated_ips() returns &IpPair directly (no Option)
* Add Tunnel::new_with_ipr, re-export IpPair/Recipient, tidy examples
- Add Tunnel::new_with_ipr() for targeting a specific exit node
- Re-export IpPair and Recipient so users don't need direct deps
- Add DNS leak warning to WebSocket example
- Await hyper connection task in HTTPS example
* Restructure smolmix into multi-crate workspace
- Move core tunnel code to smolmix/core/- Rewrite examples for each crate with clearnet/mixnet comparisons
* Add workspace README with architecture overview
* Update nym-sdk README module descriptions
- Replace stale stream_wrapper description with ipr_wrapper + mixnet::stream
- Remove TODO comment
* Remove companion crates, scope to smolmix-core
* Comment out additional components on -core branch README.md
* Cargo.lock fix for compilation issue
* Downgrade accidentally bumped dependencies in Cargo lock + change
smolmix dependencies to import from workspace
* Fix workspace deps + move nym-bin-common to dev-deps
* PR review changes + fix Sink delegation
* Fix borked merge + update README.md
* Fix up stale docs + rewrite examples to use proper imports and timing
logs
* Update readmes + architecture file
* Impl Drop for BridgeShutdownHandle + update comment
3.5 KiB
3.5 KiB
smolmix
TCP/UDP tunnel over the Nym mixnet. Uses a userspace network stack (smoltcp)
to provide real TcpStream and UdpSocket types that work transparently
with the async Rust ecosystem — tokio-rustls, hyper, tokio-tungstenite,
libp2p, and anything else built on AsyncRead + AsyncWrite.
Why IP, not messages
The Nym SDK works at the message layer: you send and receive Vec<u8>
payloads through the mixnet. Every protocol must be hand-adapted — you need
custom framing, ordering, connection state, and flow control.
smolmix operates at the IP layer. A userspace smoltcp stack manages
real TCP state machines (retransmits, windowing, port allocation) and UDP
datagram delivery, and the mixnet becomes a transparent transport underneath.
Any protocol that works over TCP or UDP works over smolmix — with zero
adaptation.
┌──────────────────────────────────────────────────────────────────┐
│ Application protocols that "just work" over smolmix │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────────┐ ┌────────────────┐ │
│ │ TLS │ │ HTTP/1.1 │ │ WebSocket │ │ libp2p │ │
│ │ (rustls) │ │ (hyper) │ │ (tungstenite)│ │ (noise+yamux) │ │
│ └────┬─────┘ └────┬─────┘ └──────┬───────┘ └───────┬────────┘ │
│ │ │ │ │ │
│ └─────────────┴──────────────┴─────────────────┘ │
│ │ │
│ tokio_smoltcp::TcpStream │
│ (AsyncRead + AsyncWrite, Send, Unpin) │
├──────────────────────────────────────────────────────────────────┤
│ smolmix Tunnel │
│ (smoltcp → mixnet → IPR) │
└──────────────────────────────────────────────────────────────────┘
Quick start
use smolmix::Tunnel;
use tokio::io::{AsyncReadExt, AsyncWriteExt};
let tunnel = Tunnel::new().await?;
// Raw TCP — works with any protocol
let mut tcp = tunnel.tcp_connect("1.1.1.1:80".parse()?).await?;
tcp.write_all(b"GET / HTTP/1.1\r\nHost: 1.1.1.1\r\nConnection: close\r\n\r\n").await?;
// Raw UDP — datagrams over the mixnet
let udp = tunnel.udp_socket().await?;
udp.send_to(&packet, "1.1.1.1:53".parse()?).await?;
Examples
cargo run -p smolmix --example tcp # HTTPS via hyper
cargo run -p smolmix --example udp # DNS via hickory-proto
cargo run -p smolmix --example websocket # WebSocket via tungstenite
Architecture
See core/src/ARCHITECTURE.md for the internal
stack (smoltcp, device adapter, bridge, mixnet client).