Mixnet Module

The mixnet module is the core of the Nym SDK. It provides MixnetClient (opens in a new tab) for connecting to the Nym Mixnet, sending messages through Sphinx packet encryption and 5-hop routing, and receiving reconstructed messages on the other side.

⚠️

Messages are individually routed through the Mixnet with no guaranteed ordering or persistent connections. If you want familiar socket-like I/O (read/write), use the Stream module instead. See the Tour for how the two approaches compare.

Two operating modes

The client operates in one of two mutually exclusive modes:

Message mode (default): send and receive raw message payloads:

use nym_sdk::mixnet::{self, MixnetMessageSender};
 
let mut client = mixnet::MixnetClient::connect_new().await.unwrap();
 
// Send a message
client.send_plain_message(*client.nym_address(), "hello").await.unwrap();
 
// Receive messages
if let Some(msgs) = client.wait_for_messages().await {
    for msg in msgs {
        println!("Got: {}", String::from_utf8_lossy(&msg.message));
    }
}
 
client.disconnect().await;

Stream mode: persistent AsyncRead + AsyncWrite channels. See the Stream module for details.

Stream mode is activated by calling open_stream() or listener(). Once active, message-mode methods return Error::StreamModeActive. This is a one-way transition.

API reference

API reference on docs.rs (opens in a new tab): full architecture documentation, all types, builder methods, traits, and configuration options
Examples on GitHub (opens in a new tab): runnable examples covering simple send/receive, builder patterns, custom topologies, SOCKS proxy, anonymous replies, and more

Run any example with:

cargo run --example <example_name>

Next steps

Tutorial: Send your first private message: step-by-step guide covering sending, receiving, SURBs, and persistent identity
Troubleshooting: common issues with logging, empty messages, and client lifecycle
Stream module: if you need persistent bidirectional byte channels

Installation Tutorial