Importing and using a custom network topology

If you want to send traffic through a sub-set of nodes (for instance, ones you control, or a small test setup) when developing, debugging, or performing research, you will need to import these nodes as a custom network topology, instead of grabbing it from the Mainnet Nym-API (examples/custom_topology_provider.rs).

There are two ways to do this:

Import a custom Nym API endpoint

If you are also running a Validator and Nym API for your network, you can specify that endpoint as such and interact with it as clients usually do (under the hood):

// Copyright 2023 - Nym Technologies SA <contact@nymtech.net>
// SPDX-License-Identifier: Apache-2.0

use nym_sdk::mixnet;
use nym_sdk::mixnet::MixnetMessageSender;
use nym_topology::provider_trait::{async_trait, TopologyProvider};
use nym_topology::{nym_topology_from_detailed, NymTopology};
use url::Url;

struct MyTopologyProvider {
    validator_client: nym_validator_client::client::NymApiClient,
}

impl MyTopologyProvider {
    fn new(nym_api_url: Url) -> MyTopologyProvider {
        MyTopologyProvider {
            validator_client: nym_validator_client::client::NymApiClient::new(nym_api_url),
        }
    }

    async fn get_topology(&self) -> NymTopology {
        let mixnodes = self
            .validator_client
            .get_cached_active_mixnodes()
            .await
            .unwrap();

        // in our topology provider only use mixnodes that have mix_id divisible by 3
        // and have more than 100k nym (i.e. 100'000'000'000 unym) in stake
        // why? because this is just an example to showcase arbitrary uses and capabilities of this trait
        let filtered_mixnodes = mixnodes
            .into_iter()
            .filter(|mix| {
                mix.mix_id() % 3 == 0 && mix.total_stake() > "100000000000".parse().unwrap()
            })
            .collect::<Vec<_>>();

        let gateways = self.validator_client.get_cached_gateways().await.unwrap();

        nym_topology_from_detailed(filtered_mixnodes, gateways)
    }
}

#[async_trait]
impl TopologyProvider for MyTopologyProvider {
    // this will be manually refreshed on a timer specified inside mixnet client config
    async fn get_new_topology(&mut self) -> Option<NymTopology> {
        Some(self.get_topology().await)
    }
}

#[tokio::main]
async fn main() {
    nym_bin_common::logging::setup_logging();

    let nym_api = "https://validator.nymtech.net/api/".parse().unwrap();
    let my_topology_provider = MyTopologyProvider::new(nym_api);

    // Passing no config makes the client fire up an ephemeral session and figure things out on its own
    let mut client = mixnet::MixnetClientBuilder::new_ephemeral()
        .custom_topology_provider(Box::new(my_topology_provider))
        .build()
        .unwrap()
        .connect_to_mixnet()
        .await
        .unwrap();

    let our_address = client.nym_address();
    println!("Our client nym address is: {our_address}");

    // Send a message through the mixnet to ourselves
    client
        .send_plain_message(*our_address, "hello there")
        .await
        .unwrap();

    println!("Waiting for message (ctrl-c to exit)");
    client
        .on_messages(|msg| println!("Received: {}", String::from_utf8_lossy(&msg.message)))
        .await;
}

Import a specific topology manually

If you aren’t running a Validator and Nym API, and just want to import a specific sub-set of mix nodes, you can simply overwrite the grabbed topology manually:

// Copyright 2023 - Nym Technologies SA <contact@nymtech.net>
// SPDX-License-Identifier: Apache-2.0

use nym_sdk::mixnet;
use nym_sdk::mixnet::MixnetMessageSender;
use nym_topology::mix::Layer;
use nym_topology::{mix, NymTopology};
use std::collections::BTreeMap;

#[tokio::main]
async fn main() {
    nym_bin_common::logging::setup_logging();

    // Passing no config makes the client fire up an ephemeral session and figure shit out on its own
    let mut client = mixnet::MixnetClient::connect_new().await.unwrap();
    let starting_topology = client.read_current_topology().await.unwrap();

    // but we don't like our default topology, we want to use only those very specific, hardcoded, nodes:
    let mut mixnodes = BTreeMap::new();
    mixnodes.insert(
        1,
        vec![mix::Node {
            mix_id: 63,
            owner: "n1k52k5n45cqt5qpjh8tcwmgqm0wkt355yy0g5vu".to_string(),
            host: "172.105.92.48".parse().unwrap(),
            mix_host: "172.105.92.48:1789".parse().unwrap(),
            identity_key: "GLdR2NRVZBiCoCbv4fNqt9wUJZAnNjGXHkx3TjVAUzrK"
                .parse()
                .unwrap(),
            sphinx_key: "CBmYewWf43iarBq349KhbfYMc9ys2ebXWd4Vp4CLQ5Rq"
                .parse()
                .unwrap(),
            layer: Layer::One,
            version: "1.1.0".into(),
        }],
    );
    mixnodes.insert(
        2,
        vec![mix::Node {
            mix_id: 23,
            owner: "n1fzv4jc7fanl9s0qj02ge2ezk3kts545kjtek47".to_string(),
            host: "178.79.143.65".parse().unwrap(),
            mix_host: "178.79.143.65:1789".parse().unwrap(),
            identity_key: "4Yr4qmEHd9sgsuQ83191FR2hD88RfsbMmB4tzhhZWriz"
                .parse()
                .unwrap(),
            sphinx_key: "8ndjk5oZ6HxUZNScLJJ7hk39XtUqGexdKgW7hSX6kpWG"
                .parse()
                .unwrap(),
            layer: Layer::Two,
            version: "1.1.0".into(),
        }],
    );
    mixnodes.insert(
        3,
        vec![mix::Node {
            mix_id: 66,
            owner: "n1ae2pjd7q9p0dea65pqkvcm4x9s264v4fktpyru".to_string(),
            host: "139.162.247.97".parse().unwrap(),
            mix_host: "139.162.247.97:1789".parse().unwrap(),
            identity_key: "66UngapebhJRni3Nj52EW1qcNsWYiuonjkWJzHFsmyYY"
                .parse()
                .unwrap(),
            sphinx_key: "7KyZh8Z8KxuVunqytAJ2eXFuZkCS7BLTZSzujHJZsGa2"
                .parse()
                .unwrap(),
            layer: Layer::Three,
            version: "1.1.0".into(),
        }],
    );

    // but we like the available gateways, so keep using them!
    // (we like them because the author of this example is too lazy to use the same hardcoded gateway
    // during client initialisation to make sure we are able to send to ourselves : )  )
    let custom_topology = NymTopology::new(mixnodes, starting_topology.gateways().to_vec());

    client.manually_overwrite_topology(custom_topology).await;

    // and everything we send now should only ever go via those nodes

    let our_address = client.nym_address();
    println!("Our client nym address is: {our_address}");

    // Send a message through the mixnet to ourselves
    client
        .send_plain_message(*our_address, "hello there")
        .await
        .unwrap();

    println!("Waiting for message (ctrl-c to exit)");
    client
        .on_messages(|msg| println!("Received: {}", String::from_utf8_lossy(&msg.message)))
        .await;
}