Remove cpucycles

Client tweaks
Rebase on develop
2023-05-08 16:39:20 +02:00 · 2023-05-01 16:04:09 +02:00 · 2023-05-01 15:50:59 +02:00 · 2023-05-01 15:48:36 +02:00 · 2023-05-01 15:48:36 +02:00 · 2023-05-01 15:48:36 +02:00
237 changed files with 10925 additions and 2048 deletions
@@ -11,30 +11,25 @@
 # In each subsection folders are ordered first by depth, then alphabetically.
 # This should make it easy to add new rules without breaking existing ones.

-# Something weird not covered by anything else
-* @futurechimp @mmsinclair
+# contracts
+/contracts/mixnet @durch @jstuczyn
+/contracts/vesting @durch @jstuczyn
+/contracts/service-provider-directory @octol

-# Rust rules:
-*.rs @durch @futurechimp @jstuczyn @neacsu @octol
-Cargo.* @durch @futurechimp @jstuczyn @neacsu @octol
+# crypto code
+/common/crypto/ @jstuczyn
+/common/nymcoconut/ @jstuczyn
+/common/dkg/ @jstuczyn
+/common/nymsphinx/ @jstuczyn

-# JS rules:
-*.js @mmsinclair @fmtabbara
-*.ts @mmsinclair @fmtabbara
-*.tsx @mmsinclair @fmtabbara
-*.jsx @mmsinclair @fmtabbara
+# rust sdk
+/sdk/rust/ @octol

-# Something looking like possible documentation rules:
-*.md @mfahampshire
+# nym-connect (rust)
+/nym-connect/desktop/src-tauri/ @octol

-# our docker scripts
-/docker/ @neacsu
+# nym-wallet (rust)
+/nym-wallet/src-tauri/ @octol

-# if there are any changes in the core crypto, I feel like Ania should take a look:
-/common/crypto/ @aniampio
-/common/nymsphinx/ @aniampio
-
-# Explorer and wallet should probably get looked by the product team
-/explorer/ @nymtech/product 
-/nym-wallet/ @nymtech/product 
-/wallet-web/ @nymtech/product
+# documentation
+/documentation @mfahampshire
@@ -30,6 +30,7 @@ jobs:
    continue-on-error: ${{ matrix.rust == 'nightly' }}
    needs: matrix_prep
    strategy:
+      fail-fast: false
      matrix: ${{fromJson(needs.matrix_prep.outputs.matrix)}}
    steps:
      - uses: actions/checkout@v2
@@ -63,4 +64,4 @@ jobs:
        if: ${{ matrix.rust != 'nightly' }}
        with:
          command: clippy
-          args: --manifest-path contracts/Cargo.toml --workspace -- -D warnings
+          args: --manifest-path contracts/Cargo.toml --workspace --all-targets -- -D warnings
@@ -6,7 +6,7 @@
  },

  {
-    "os":"windows-latest",
+    "os":"windows10",
    "rust":"stable",
    "runOnEvent":"schedule"
  },
@@ -22,7 +22,7 @@
    "runOnEvent":"schedule"
  },
  {
-    "os":"windows-latest",
+    "os":"windows10",
    "rust":"beta",
    "runOnEvent":"schedule"
  },
@@ -38,7 +38,7 @@
    "runOnEvent":"schedule"
  },
  {
-    "os":"windows-latest",
+    "os":"windows10",
    "rust":"nightly",
    "runOnEvent":"schedule"
  },
@@ -64,4 +64,4 @@ jobs:
        uses: actions-rs/cargo@v1
        with:
          command: clippy
-          args: --manifest-path nym-wallet/Cargo.toml --workspace --all-features -- -D warnings
+          args: --manifest-path nym-wallet/Cargo.toml --workspace --all-features --all-targets -- -D warnings
@@ -41,4 +41,5 @@ storybook-static
 envs/qwerty.env
 .parcel-cache
 **/.DS_Store
-cpu-cycles/libcpucycles/build
+cpu-cycles/libcpucycles/build
+foxyfox.env
@@ -4,14 +4,29 @@ Post 1.0.0 release, the changelog format is based on [Keep a Changelog](https://

 ## [Unreleased]

- nym-network-statistics properly handles signals ([#3209])
- add socks5 support for Rust SDK ([#3226], [#3255])
- add coconut bandwidth credential support for Rust SDK ([#3273]) 
+## [v1.1.16] (2023-04-25)

-[#3209]: https://github.com/nymtech/nym/issues/3209
-[#3226]: https://github.com/nymtech/nym/pull/3226
-[#3255]: https://github.com/nymtech/nym/pull/3255
-[#3273]: https://github.com/nymtech/nym/pull/3273
+- Explorer - Fix sorting function on Stake Saturation. It is currently working per page and not globally ([#3320])
+- Poisson process gets stuck at too slow rate. Rework to more aggressively up-regulate ([#3309])
+- decrease the logging level of warnings associated with clients dropping packets due to gateway being overloaded (I'd say reduce it to debug/trace) - there are few sources of those, e.g. in real and cover traffic streams ([#3299])
+- Make the buffer size in `AvailableReader` depend on packet sizes the client is using + introduce read timeouts ([#3213])
+- Rust SDK - Support coconut, credential storage etc ([#2755])
+- version bump for next release ([#3349])
+- added coconut credential generation example ([#3339])
+- update mix-node setup docs with node description ([#3325])
+- exposed missing gateway commands in nym-cli ([#3324])
+- make sure to clear inner 'ack_map' in 'GatewaysReader' ([#3300])
+
+[#3320]: https://github.com/nymtech/nym/issues/3320
+[#3309]: https://github.com/nymtech/nym/issues/3309
+[#3299]: https://github.com/nymtech/nym/issues/3299
+[#3213]: https://github.com/nymtech/nym/issues/3213
+[#2755]: https://github.com/nymtech/nym/issues/2755
+[#3349]: https://github.com/nymtech/nym/pull/3349
+[#3339]: https://github.com/nymtech/nym/pull/3339
+[#3325]: https://github.com/nymtech/nym/pull/3325
+[#3324]: https://github.com/nymtech/nym/pull/3324
+[#3300]: https://github.com/nymtech/nym/pull/3300

 ## [v1.1.15] (2023-04-18)

@@ -1576,7 +1576,7 @@ checksum = "0206175f82b8d6bf6652ff7d71a1e27fd2e4efde587fd368662814d6ec1d9ce0"

 [[package]]
 name = "explorer-api"
-version = "1.1.15"
+version = "1.1.16"
 dependencies = [
 "chrono",
 "clap 4.1.11",
@@ -3011,7 +3011,7 @@ dependencies = [

 [[package]]
 name = "nym-api"
-version = "1.1.16"
+version = "1.1.17"
 dependencies = [
 "anyhow",
 "async-trait",
@@ -3142,7 +3142,7 @@ dependencies = [

 [[package]]
 name = "nym-cli"
-version = "1.1.15"
+version = "1.1.16"
 dependencies = [
 "anyhow",
 "base64 0.13.1",
@@ -3203,7 +3203,7 @@ dependencies = [

 [[package]]
 name = "nym-client"
-version = "1.1.15"
+version = "1.1.16"
 dependencies = [
 "clap 4.1.11",
 "dirs",
@@ -3471,7 +3471,7 @@ dependencies = [

 [[package]]
 name = "nym-gateway"
-version = "1.1.15"
+version = "1.1.16"
 dependencies = [
 "anyhow",
 "async-trait",
@@ -3600,7 +3600,7 @@ dependencies = [

 [[package]]
 name = "nym-mixnet-contract-common"
-version = "0.4.0"
+version = "0.5.0"
 dependencies = [
 "bs58",
 "cosmwasm-std",
@@ -3619,7 +3619,7 @@ dependencies = [

 [[package]]
 name = "nym-mixnode"
-version = "1.1.16"
+version = "1.1.17"
 dependencies = [
 "anyhow",
 "bs58",
@@ -3721,7 +3721,7 @@ dependencies = [

 [[package]]
 name = "nym-network-requester"
-version = "1.1.15"
+version = "1.1.16"
 dependencies = [
 "async-file-watcher",
 "async-trait",
@@ -3763,7 +3763,7 @@ dependencies = [

 [[package]]
 name = "nym-network-statistics"
-version = "1.1.15"
+version = "1.1.16"
 dependencies = [
 "dirs",
 "log",
@@ -3778,6 +3778,25 @@ dependencies = [
 "tokio",
 ]

+[[package]]
+name = "nym-node-tester-utils"
+version = "0.1.0"
+dependencies = [
+ "futures",
+ "log",
+ "nym-crypto",
+ "nym-sphinx",
+ "nym-sphinx-params",
+ "nym-task",
+ "nym-topology",
+ "rand 0.7.3",
+ "serde",
+ "serde_json",
+ "thiserror",
+ "tokio",
+ "wasm-utils",
+]
+
 [[package]]
 name = "nym-nonexhaustive-delayqueue"
 version = "0.1.0"
@@ -3809,8 +3828,9 @@ dependencies = [
 "curve25519-dalek",
 "fastrand",
 "getrandom 0.2.8",
+ "rand 0.7.3",
 "rayon",
- "sphinx-packet 0.1.0 (git+https://github.com/nymtech/sphinx.git)",
+ "sphinx-packet",
 "thiserror",
 "zeroize",
 ]
@@ -3879,7 +3899,7 @@ dependencies = [

 [[package]]
 name = "nym-socks5-client"
-version = "1.1.15"
+version = "1.1.16"
 dependencies = [
 "clap 4.1.11",
 "lazy_static",
@@ -4061,6 +4081,7 @@ dependencies = [
 "nym-sphinx-addressing",
 "nym-sphinx-params",
 "nym-sphinx-types",
+ "thiserror",
 ]

 [[package]]
@@ -4088,7 +4109,9 @@ dependencies = [
 name = "nym-sphinx-types"
 version = "0.2.0"
 dependencies = [
- "sphinx-packet 0.1.0 (registry+https://github.com/rust-lang/crates.io-index)",
+ "nym-outfox",
+ "sphinx-packet",
+ "thiserror",
 ]

 [[package]]
@@ -4202,7 +4225,7 @@ dependencies = [

 [[package]]
 name = "nym-vesting-contract"
-version = "1.3.0"
+version = "1.4.0"
 dependencies = [
 "cosmwasm-derive",
 "cosmwasm-std",
@@ -4220,7 +4243,7 @@ dependencies = [

 [[package]]
 name = "nym-vesting-contract-common"
-version = "0.4.0"
+version = "0.6.0"
 dependencies = [
 "cosmwasm-std",
 "nym-contracts-common",
@@ -5889,29 +5912,6 @@ dependencies = [
 "subtle 2.4.1",
 ]

-[[package]]
-name = "sphinx-packet"
-version = "0.1.0"
-source = "git+https://github.com/nymtech/sphinx.git#ca107d94360cdf8bbfbdb12fe5320ed74f80e40c"
-dependencies = [
- "aes 0.7.5",
- "arrayref",
- "blake2",
- "bs58",
- "byteorder",
- "chacha",
- "curve25519-dalek",
- "digest 0.9.0",
- "hkdf 0.11.0",
- "hmac 0.11.0",
- "lioness",
- "log",
- "rand 0.7.3",
- "rand_distr",
- "sha2 0.9.9",
- "subtle 2.4.1",
-]
-
 [[package]]
 name = "spin"
 version = "0.5.2"
@@ -48,6 +48,7 @@ members = [
    "common/ledger",
    "common/mixnode-common",
    "common/network-defaults",
+    "common/node-tester-utils",
    "common/nonexhaustive-delayqueue",
    "common/nymcoconut",
    "common/nymsphinx",
@@ -13,6 +13,10 @@ happy: fmt clippy-happy test
 # on all workspaces.
 build-release: build-release-main wasm

+# Deprecated
+# For backwards compatibility
+clippy-all: clippy
+
 # -----------------------------------------------------------------------------
 # Define targets for a given workspace
 #  $(1): name
@@ -52,11 +56,11 @@ fmt-$(1):
 	cargo fmt --manifest-path $(2)/Cargo.toml --all

 clippy-happy: clippy-happy-$(1)
-clippy-all: clippy-$(1) clippy-examples-$(1)
+clippy: clippy-$(1) clippy-examples-$(1)
 check: check-$(1)
 cargo-test: test-$(1)
 cargo-test-expensive: test-expensive-$(1)
-build: build-$(1) build-$(1)-examples
+build: build-$(1) build-examples-$(1)
 build-release-all: build-release-$(1)
 fmt: fmt-$(1)

@@ -1,6 +1,6 @@
 [package]
 name = "nym-client"
-version = "1.1.15"
+version = "1.1.16"
 authors = ["Dave Hrycyszyn <futurechimp@users.noreply.github.com>", "Jędrzej Stuczyński <andrew@nymtech.net>"]
 description = "Implementation of the Nym Client"
 edition = "2021"
@@ -16,6 +16,7 @@ use nym_client_core::client::received_buffer::{
 };
 use nym_client_core::config::persistence::key_pathfinder::ClientKeyPathfinder;
 use nym_sphinx::anonymous_replies::requests::AnonymousSenderTag;
+use nym_sphinx::params::PacketType;
 use nym_task::connections::TransmissionLane;
 use nym_task::TaskManager;
 use nym_validator_client::nyxd::QueryNyxdClient;
@@ -119,6 +120,7 @@ impl SocketClient {
            self_address,
            shared_lane_queue_lengths,
            reply_controller_sender,
+            None,
        );

        websocket::Listener::new(config.get_listening_ip(), config.get_listening_port())
@@ -178,7 +180,10 @@ impl SocketClient {
        Ok(started_client.task_manager)
    }

-    pub async fn start_direct(self) -> Result<DirectClient, ClientError> {
+    pub async fn start_direct(
+        self,
+        packet_type: Option<PacketType>,
+    ) -> Result<DirectClient, ClientError> {
        if self.config.get_socket_type().is_websocket() {
            return Err(ClientError::InvalidSocketMode);
        }
@@ -224,6 +229,7 @@ impl SocketClient {
            reconstructed_receiver,
            address,
            shutdown_notifier: started_client.task_manager,
+            packet_type,
        })
    }
 }
@@ -237,6 +243,7 @@ pub struct DirectClient {

    // we need to keep reference to this guy otherwise things will start dropping
    shutdown_notifier: TaskManager,
+    packet_type: Option<PacketType>,
 }

 impl DirectClient {
@@ -257,7 +264,7 @@ impl DirectClient {
    /// well enough in local tests)
    pub async fn send_regular_message(&mut self, recipient: Recipient, message: Vec<u8>) {
        let lane = TransmissionLane::General;
-        let input_msg = InputMessage::new_regular(recipient, message, lane);
+        let input_msg = InputMessage::new_regular(recipient, message, lane, self.packet_type);

        self.client_input
            .input_sender
@@ -276,7 +283,8 @@ impl DirectClient {
        reply_surbs: u32,
    ) {
        let lane = TransmissionLane::General;
-        let input_msg = InputMessage::new_anonymous(recipient, message, reply_surbs, lane);
+        let input_msg =
+            InputMessage::new_anonymous(recipient, message, reply_surbs, lane, self.packet_type);

        self.client_input
            .input_sender
@@ -290,7 +298,7 @@ impl DirectClient {
    /// well enough in local tests)
    pub async fn send_reply(&mut self, recipient_tag: AnonymousSenderTag, message: Vec<u8>) {
        let lane = TransmissionLane::General;
-        let input_msg = InputMessage::new_reply(recipient_tag, message, lane);
+        let input_msg = InputMessage::new_reply(recipient_tag, message, lane, self.packet_type);

        self.client_input
            .input_sender
@@ -14,6 +14,7 @@ use nym_client_core::client::{
 use nym_client_websocket_requests::{requests::ClientRequest, responses::ServerResponse};
 use nym_sphinx::addressing::clients::Recipient;
 use nym_sphinx::anonymous_replies::requests::AnonymousSenderTag;
+use nym_sphinx::params::PacketType;
 use nym_sphinx::receiver::ReconstructedMessage;
 use nym_task::connections::{
    ConnectionCommand, ConnectionCommandSender, ConnectionId, LaneQueueLengths, TransmissionLane,
@@ -41,6 +42,7 @@ pub(crate) struct HandlerBuilder {
    self_full_address: Recipient,
    lane_queue_lengths: LaneQueueLengths,
    reply_controller_sender: ReplyControllerSender,
+    packet_type: Option<PacketType>,
 }

 impl HandlerBuilder {
@@ -51,6 +53,7 @@ impl HandlerBuilder {
        self_full_address: &Recipient,
        lane_queue_lengths: LaneQueueLengths,
        reply_controller_sender: ReplyControllerSender,
+        packet_type: Option<PacketType>,
    ) -> Self {
        Self {
            msg_input,
@@ -59,6 +62,7 @@ impl HandlerBuilder {
            self_full_address: *self_full_address,
            lane_queue_lengths,
            reply_controller_sender,
+            packet_type,
        }
    }

@@ -73,6 +77,7 @@ impl HandlerBuilder {
            received_response_type: Default::default(),
            lane_queue_lengths: self.lane_queue_lengths.clone(),
            reply_controller_sender: self.reply_controller_sender.clone(),
+            packet_type: self.packet_type,
        }
    }
 }
@@ -86,6 +91,7 @@ pub(crate) struct Handler {
    received_response_type: ReceivedResponseType,
    lane_queue_lengths: LaneQueueLengths,
    reply_controller_sender: ReplyControllerSender,
+    packet_type: Option<PacketType>,
 }

 impl Drop for Handler {
@@ -160,7 +166,7 @@ impl Handler {
        });

        // the ack control is now responsible for chunking, etc.
-        let input_msg = InputMessage::new_regular(recipient, message, lane);
+        let input_msg = InputMessage::new_regular(recipient, message, lane, self.packet_type);
        self.msg_input
            .send(input_msg)
            .await
@@ -191,7 +197,8 @@ impl Handler {
            TransmissionLane::ConnectionId(id)
        });

-        let input_msg = InputMessage::new_anonymous(recipient, message, reply_surbs, lane);
+        let input_msg =
+            InputMessage::new_anonymous(recipient, message, reply_surbs, lane, self.packet_type);
        self.msg_input
            .send(input_msg)
            .await
@@ -218,7 +225,7 @@ impl Handler {
            TransmissionLane::ConnectionId(id)
        });

-        let input_msg = InputMessage::new_reply(recipient_tag, message, lane);
+        let input_msg = InputMessage::new_reply(recipient_tag, message, lane, self.packet_type);
        self.msg_input
            .send(input_msg)
            .await
@@ -1,6 +1,6 @@
 [package]
 name = "nym-socks5-client"
-version = "1.1.15"
+version = "1.1.16"
 authors = ["Dave Hrycyszyn <futurechimp@users.noreply.github.com>"]
 description = "A SOCKS5 localhost proxy that converts incoming messages to Sphinx and sends them to a Nym address"
 edition = "2021"
@@ -91,6 +91,7 @@ impl From<Init> for OverrideConfig {
            no_cover: init_config.no_cover,
            nyxd_urls: init_config.nyxd_urls,
            enabled_credentials_mode: init_config.enabled_credentials_mode,
+            outfox: false,
        }
    }
 }
@@ -10,6 +10,7 @@ use nym_bin_common::completions::{fig_generate, ArgShell};
 use nym_config::{NymConfig, OptionalSet};
 use nym_socks5_client_core::config::old_config_v1_1_13::OldConfigV1_1_13;
 use nym_socks5_client_core::config::{BaseConfig, Config};
+use nym_sphinx::params::PacketType;
 use std::error::Error;

 pub mod init;
@@ -64,6 +65,7 @@ pub(crate) struct OverrideConfig {
    no_cover: bool,
    nyxd_urls: Option<Vec<url::Url>>,
    enabled_credentials_mode: Option<bool>,
+    outfox: bool,
 }

 pub(crate) async fn execute(args: &Cli) -> Result<(), Box<dyn Error + Send + Sync>> {
@@ -80,9 +82,15 @@ pub(crate) async fn execute(args: &Cli) -> Result<(), Box<dyn Error + Send + Syn
 }

 pub(crate) fn override_config(config: Config, args: OverrideConfig) -> Config {
+    let packet_type = if args.outfox {
+        PacketType::Outfox
+    } else {
+        PacketType::Mix
+    };
    config
        .with_base(BaseConfig::with_high_default_traffic_volume, args.fastmode)
        .with_base(BaseConfig::with_disabled_cover_traffic, args.no_cover)
+        .with_base(BaseConfig::with_packet_type, packet_type)
        .with_optional(Config::with_anonymous_replies, args.use_anonymous_replies)
        .with_optional(Config::with_port, args.port)
        .with_optional_custom_env_ext(
@@ -67,6 +67,9 @@ pub(crate) struct Run {
    /// with bandwidth credential requirement.
    #[clap(long, hide = true)]
    enabled_credentials_mode: Option<bool>,
+
+    #[clap(long, hide = true, action)]
+    outfox: bool,
 }

 impl From<Run> for OverrideConfig {
@@ -79,6 +82,7 @@ impl From<Run> for OverrideConfig {
            no_cover: run_config.no_cover,
            nyxd_urls: run_config.nyxd_urls,
            enabled_credentials_mode: run_config.enabled_credentials_mode,
+            outfox: run_config.outfox,
        }
    }
 }
@@ -0,0 +1,2 @@
+[build]
+target = "wasm32-unknown-unknown"
@@ -17,6 +17,7 @@ default = ["console_error_panic_hook"]
 offline-test = []

 [dependencies]
+bs58 = "0.4.0"
 futures = "0.3"
 js-sys = "0.3"
 rand = { version = "0.7.3", features = ["wasm-bindgen"] }
@@ -28,8 +29,12 @@ tokio = { version = "1.24.1", features = ["sync"] }
 url = "2.2"
 wasm-bindgen = { version = "=0.2.83", features = ["serde-serialize"]  }
 wasm-bindgen-futures = "0.4"
+thiserror = "1.0.40"
+
+wasm-timer = { git = "https://github.com/mmsinclair/wasm-timer", rev = "b9d1a54ad514c2f230a026afe0dde341e98cd7b6"}

 # internal
+nym-node-tester-utils = { path = "../../common/node-tester-utils" }
 nym-client-core = { path = "../../common/client-core", default-features = false, features = ["wasm"] }
 nym-bandwidth-controller = { path = "../../common/bandwidth-controller" }
 nym-coconut-interface = { path = "../../common/coconut-interface" }
@@ -37,6 +42,8 @@ nym-credentials = { path = "../../common/credentials" }
 nym-credential-storage = { path = "../../common/credential-storage" }
 nym-crypto = { path = "../../common/crypto" }
 nym-sphinx = { path = "../../common/nymsphinx" }
+nym-topology = { path = "../../common/topology" }
+nym-gateway-client = { path = "../../common/client-libs/gateway-client", default-features = false, features = ["wasm"] }
 nym-validator-client = { path = "../../common/client-libs/validator-client", default-features = false }
 wasm-utils = { path = "../../common/wasm-utils" }
 nym-task = { path = "../../common/task" }
@@ -0,0 +1,2 @@
+node_modules
+dist
@@ -0,0 +1,5 @@
+// A dependency graph that contains any wasm must all be imported
+// asynchronously. This `bootstrap.js` file does the single async import, so
+// that no one else needs to worry about it again.
+import('./index.js')
+    .catch(e => console.error('Error importing `index.js`:', e));
@@ -0,0 +1,43 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Nym WebAssembly Demo</title>
+</head>
+
+<body>
+<p>
+    <label>Sender: </label><input disabled="true" size="85" type="text" id="sender" value="">
+</p>
+
+<p>
+    <label>Recipient: </label><input size="85" type="text" id="recipient" value="">
+</p>
+<p>
+    <label>Message: </label><input type="text" id="message" value="Hello mixnet!">
+</p>
+<p>
+    <button id="send-button">Send</button>
+</p>
+
+<div>
+    <label>Mixnode Identity: </label>
+    <input type="text" size = "60" id="mixnode_identity" value="...">
+    <button id="magic-button">✨ Magic Test Button ✨</button>
+</div>
+
+
+<p>Send messages from your browser, through the mixnet, and to the recipient using the "send" button.</p>
+<p><span style='color: blue;'>Sent</span> messages show in blue, <span style='color: green;'>received</span>
+    messages show in green.</p>
+
+<hr>
+<p>
+    <span id="output"></span>
+</p>
+<script src="./bootstrap.js"></script>
+</body>
+
+</html>
@@ -0,0 +1,170 @@
+// Copyright 2020-2023 Nym Technologies SA
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+class WebWorkerClient {
+    worker = null;
+
+    constructor() {
+        this.worker = new Worker('./worker.js');
+
+        this.worker.onmessage = (ev) => {
+            if (ev.data && ev.data.kind) {
+                switch (ev.data.kind) {
+                    case 'Ready':
+                        const {selfAddress} = ev.data.args;
+                        displaySenderAddress(selfAddress);
+                        break;
+                    case 'ReceiveMessage':
+                        const {message, senderTag, isTestPacket } = ev.data.args;
+                        displayReceived(message, senderTag, isTestPacket);
+                        break;
+                    case 'DisableMagicTestButton':
+                        const magicButton = document.querySelector('#magic-button');
+                        magicButton.setAttribute('disabled', "true")
+                        break;
+                    case 'DisplayTesterResults':
+                        const {score, sentPackets, receivedPackets, receivedAcks, duplicatePackets, duplicateAcks} = ev.data.args;
+                        const resultText = `Test score: ${score}. Sent ${sentPackets} packets. Received ${receivedPackets} packets and ${receivedAcks} acks back. We also got ${duplicatePackets} duplicate packets and ${duplicateAcks} duplicate acks.`
+                        displayReceivedRawString(resultText)
+                        break;
+                }
+            }
+        };
+    }
+
+    sendMessage = (message, recipient) => {
+        if (!this.worker) {
+            console.error('Could not send message because worker does not exist');
+            return;
+        }
+
+        this.worker.postMessage({
+            kind: 'SendMessage',
+            args: {
+                message, recipient,
+            },
+        });
+    };
+
+    sendTestPacket = (mixnodeIdentity) => {
+        if (!this.worker) {
+            console.error('Could not send message because worker does not exist');
+            return;
+        }
+
+        this.worker.postMessage({
+            kind: 'TestPacket',
+            args: {
+                mixnodeIdentity,
+            },
+        });
+    }
+}
+
+let client = null;
+
+async function main() {
+    client = new WebWorkerClient();
+
+    const sendButton = document.querySelector('#send-button');
+    sendButton.onclick = function () {
+        sendMessageTo();
+    };
+
+    const magicButton = document.querySelector('#magic-button');
+    magicButton.onclick = function () {
+        sendTestPacket();
+    }
+}
+
+/**
+ * Create a Sphinx packet and send it to the mixnet through the gateway node.
+ *
+ * Message and recipient are taken from the values in the user interface.
+ *
+ */
+async function sendMessageTo() {
+    const message = document.getElementById('message').value;
+    const recipient = document.getElementById('recipient').value;
+
+    await client.sendMessage(message, recipient);
+    displaySend(message);
+}
+
+async function sendTestPacket() {
+    const mixnodeIdentity = document.getElementById('mixnode_identity').value;
+
+    await client.sendTestPacket(mixnodeIdentity)
+    displaySend(`sending test packets to: ${mixnodeIdentity}...`);
+}
+
+/**
+ * Display messages that have been sent up the websocket. Colours them blue.
+ *
+ * @param {string} message
+ */
+function displaySend(message) {
+    let timestamp = new Date().toISOString().substr(11, 12);
+
+    let sendDiv = document.createElement('div');
+    let paragraph = document.createElement('p');
+    paragraph.setAttribute('style', 'color: blue');
+    let paragraphContent = document.createTextNode(timestamp + ' sent >>> ' + message);
+    paragraph.appendChild(paragraphContent);
+
+    sendDiv.appendChild(paragraph);
+    document.getElementById('output').appendChild(sendDiv);
+}
+
+/**
+ * Display received text messages in the browser. Colour them green.
+ *
+ * @param {Uint8Array} raw
+ */
+function displayReceived(raw, sender_tag, isTestPacket) {
+    let content = new TextDecoder().decode(raw);
+    if (sender_tag !== undefined) {
+        console.log("this message also contained some surbs from", sender_tag)
+    }
+
+    if (isTestPacket) {
+        const decoded = JSON.parse(content)
+        content = `Received packet ${decoded.msg_id} / ${decoded.total_msgs} for node ${decoded.encoded_node_identity} (test: ${decoded.test_id})`
+    }
+
+    displayReceivedRawString(content)
+}
+
+
+function displayReceivedRawString(raw) {
+    let timestamp = new Date().toISOString().substr(11, 12);
+    let receivedDiv = document.createElement('div');
+    let paragraph = document.createElement('p');
+    paragraph.setAttribute('style', 'color: green');
+    let paragraphContent = document.createTextNode(timestamp + ' received >>> ' + raw);
+    paragraph.appendChild(paragraphContent);
+    receivedDiv.appendChild(paragraph);
+    document.getElementById('output').appendChild(receivedDiv);
+}
+
+/**
+ * Display the nymClient's sender address in the user interface
+ *
+ * @param {String} address
+ */
+function displaySenderAddress(address) {
+    document.getElementById('sender').value = address;
+}
+
+main();
@@ -0,0 +1,39 @@
+{
+  "name": "create-wasm-app",
+  "version": "0.1.0",
+  "description": "create an app to consume rust-generated wasm packages",
+  "main": "index.js",
+  "bin": {
+    "create-wasm-app": ".bin/create-wasm-app.js"
+  },
+  "scripts": {
+    "build": "webpack --config webpack.config.js",
+    "start": "webpack-dev-server --port 8001"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rustwasm/create-wasm-app.git"
+  },
+  "keywords": [
+    "webassembly",
+    "wasm",
+    "rust",
+    "webpack"
+  ],
+  "author": "Dave Hrycyszyn <futurechimp@users.noreply.github.com>",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/nymtech/nym/issues"
+  },
+  "homepage": "https://nymtech.net/docs",
+  "devDependencies": {
+    "copy-webpack-plugin": "^10.2.4",
+    "hello-wasm-pack": "^0.1.0",
+    "webpack": "^5.70.0",
+    "webpack-cli": "^4.9.2",
+    "webpack-dev-server": "^4.7.4"
+  },
+  "dependencies": {
+    "@nymproject/nym-client-wasm": "file:../pkg"
+  }
+}
@@ -0,0 +1,33 @@
+const CopyWebpackPlugin = require('copy-webpack-plugin');
+const path = require('path');
+
+module.exports = {
+    performance: {
+        hints: false,
+        maxEntrypointSize: 512000,
+        maxAssetSize: 512000
+    },
+    entry: {
+        bootstrap: './bootstrap.js',
+        worker: './worker.js',
+    },
+    output: {
+        path: path.resolve(__dirname, 'dist'),
+        filename: '[name].js',
+    },
+    // mode: 'development',
+    mode: 'production',
+    plugins: [
+        new CopyWebpackPlugin({
+            patterns: [
+                'index.html',
+                {
+                    from: 'node_modules/@nymproject/nym-client-wasm/*.(js|wasm)',
+                    to: '[name][ext]',
+                },
+            ],
+        }),
+
+    ],
+    experiments: { syncWebAssembly: true },
+};
@@ -0,0 +1,294 @@
+// Copyright 2020-2023 Nym Technologies SA
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+importScripts('nym_client_wasm.js');
+
+console.log('Initializing worker');
+
+// wasm_bindgen creates a global variable (with the exports attached) that is in scope after `importScripts`
+const {
+    NymNodeTester,
+    WasmGateway,
+    WasmMixNode,
+    WasmNymTopology,
+    default_debug,
+    NymClientBuilder,
+    NymClient,
+    set_panic_hook,
+    Config,
+    GatewayEndpointConfig,
+    current_network_topology,
+} = wasm_bindgen;
+
+let client = null;
+let tester = null;
+
+function dummyTopology() {
+    const l1Mixnode = new WasmMixNode(
+        1,
+        'n1fzv4jc7fanl9s0qj02ge2ezk3kts545kjtek47',
+        '178.79.143.65',
+        1789,
+        '4Yr4qmEHd9sgsuQ83191FR2hD88RfsbMmB4tzhhZWriz',
+        '8ndjk5oZ6HxUZNScLJJ7hk39XtUqGexdKgW7hSX6kpWG',
+        1,
+        '1.10.0',
+    );
+    const l2Mixnode = new WasmMixNode(
+        2,
+        'n1z93z44vf8ssvdhujjvxcj4rd5e3lz0l60wdk70',
+        '109.74.197.180',
+        1789,
+        '7sVjiMrPYZrDWRujku9QLxgE8noT7NTgBAqizCsu7AoK',
+        'GepXwRnKZDd8x2nBWAajGGBVvF3mrpVMQBkgfrGuqRCN',
+        2,
+        '1.10.0',
+    );
+    const l3Mixnode = new WasmMixNode(
+        3,
+        'n1ptg680vnmef2cd8l0s9uyc4f0hgf3x8sed6w77',
+        '176.58.101.80',
+        1789,
+        'FoM5Mx9Pxk1g3zEqkS3APgtBeTtTo3M8k7Yu4bV6kK1R',
+        'DeYjrDC2AcQRVFshiKnbUo6bRvPyZ33QGYR2DLeFJ9qD',
+        3,
+        '1.10.0',
+    );
+
+    const gateway = new WasmGateway(
+        'n16evnn8glr0sham3matj8rg2s24m6x56ayk87ts',
+        '85.159.212.96',
+        1789,
+        9000,
+        '336yuXAeGEgedRfqTJZsG2YV7P13QH1bHv1SjCZYarc9',
+        'BtYjoWihiuFihGKQypmpSspbhmWDPxzqeTVSd8ciCpWL',
+        '1.10.1',
+    );
+
+    const mixnodes = new Map();
+    mixnodes.set(1, [l1Mixnode]);
+    mixnodes.set(2, [l2Mixnode]);
+    mixnodes.set(3, [l3Mixnode]);
+
+
+    const gateways = [gateway];
+
+    return new WasmNymTopology(mixnodes, gateways)
+}
+
+function printAndDisplayTestResult(result) {
+    result.log_details();
+
+    self.postMessage({
+        kind: 'DisplayTesterResults',
+        args: {
+            score: result.score(),
+            sentPackets: result.sent_packets,
+            receivedPackets: result.received_packets,
+            receivedAcks: result.received_acks,
+            duplicatePackets: result.duplicate_packets,
+            duplicateAcks: result.duplicate_acks,
+        },
+    });
+}
+
+function dummyGatewayConfig() {
+    return new GatewayEndpointConfig(
+        '336yuXAeGEgedRfqTJZsG2YV7P13QH1bHv1SjCZYarc9',
+        'n1rqqw8km7a0rvf8lr6k8dsdqvvkyn2mglj7xxfm',
+        'ws://85.159.212.96:9000',
+    )
+}
+
+async function testWithTester() {
+    const gatewayConfig = dummyGatewayConfig();
+
+    // A) construct with hardcoded topology
+    const topology = dummyTopology()
+    const nodeTester = await new NymNodeTester(gatewayConfig, topology);
+
+    // B) first get topology directly from nym-api
+    // const validator = 'https://qwerty-validator-api.qa.nymte.ch/api';
+    // const topology = await current_network_topology(validator)
+    // const nodeTester = await new NymNodeTester(gatewayConfig, topology);
+    //
+    // C) use nym-api in the constructor (note: it does no filtering for 'good' nodes on other layers)
+    // const validator = 'https://qwerty-validator-api.qa.nymte.ch/api';
+    // const nodeTester = await NymNodeTester.new_with_api(gatewayConfig, validator)
+
+    self.onmessage = async event => {
+        if (event.data && event.data.kind) {
+            switch (event.data.kind) {
+                case 'TestPacket': {
+                    const {mixnodeIdentity} = event.data.args;
+                    console.log("starting node test...");
+
+                    let result = await nodeTester.test_node(mixnodeIdentity);
+                    printAndDisplayTestResult(result)
+                }
+            }
+        }
+    };
+}
+
+async function testWithNymClient() {
+    const gatewayConfig = dummyGatewayConfig();
+    const topology = dummyTopology()
+
+    let received = 0
+
+    const onMessageHandler = (message) => {
+        received += 1;
+        self.postMessage({
+            kind: 'ReceiveMessage',
+            args: {
+                message,
+                senderTag: undefined,
+                isTestPacket: true,
+            },
+        });
+
+        // it's really up to the user to create proper callback here...
+        console.log(`received ${received} packets so far`)
+    };
+
+    console.log('Instantiating WASM client...');
+
+    let clientBuilder = NymClientBuilder.new_tester(gatewayConfig, topology, onMessageHandler)
+    console.log('Web worker creating WASM client...');
+    let local_client = await clientBuilder.start_client();
+    console.log('WASM client running!');
+
+    const selfAddress = local_client.self_address();
+
+    // set the global (I guess we don't have to anymore?)
+    client = local_client;
+
+    console.log(`Client address is ${selfAddress}`);
+    self.postMessage({
+        kind: 'Ready',
+        args: {
+            selfAddress,
+        },
+    });
+
+    // Set callback to handle messages passed to the worker.
+    self.onmessage = async event => {
+        console.log(event)
+        if (event.data && event.data.kind) {
+            switch (event.data.kind) {
+                case 'SendMessage': {
+                    const {message, recipient} = event.data.args;
+                    let uint8Array = new TextEncoder().encode(message);
+                    await client.send_regular_message(uint8Array, recipient);
+                    break;
+                }
+                case 'TestPacket': {
+                    const {mixnodeIdentity} = event.data.args;
+                    const req = await client.try_construct_test_packet_request(mixnodeIdentity);
+                    await client.change_hardcoded_topology(req.injectable_topology());
+                    await client.try_send_test_packets(req);
+                    break;
+                }
+            }
+        }
+    };
+}
+
+async function normalNymClientUsage() {
+    self.postMessage({kind: 'DisableMagicTestButton'});
+
+    // only really useful if you want to adjust some settings like traffic rate
+    // (if not needed you can just pass a null)
+    const debug = default_debug();
+
+    debug.disable_main_poisson_packet_distribution = true;
+    debug.disable_loop_cover_traffic_stream = true;
+    debug.use_extended_packet_size = false;
+    // debug.average_packet_delay_ms = BigInt(10);
+    // debug.average_ack_delay_ms = BigInt(10);
+    // debug.ack_wait_addition_ms = BigInt(3000);
+    // debug.ack_wait_multiplier = 10;
+
+    debug.topology_refresh_rate_ms = BigInt(60000)
+
+    const gatewayConfig = dummyGatewayConfig();
+    const validator = 'https://qwerty-validator-api.qa.nymte.ch/api';
+
+    const config = new Config('my-awesome-wasm-client', validator, gatewayConfig, debug);
+
+    const onMessageHandler = (message) => {
+        console.log(message);
+        self.postMessage({
+            kind: 'ReceiveMessage',
+            args: {
+                message,
+            },
+        });
+    };
+
+    console.log('Instantiating WASM client...');
+
+    let localClient = await new NymClient(config, onMessageHandler)
+    console.log('WASM client running!');
+
+    const selfAddress = localClient.self_address();
+
+    // set the global (I guess we don't have to anymore?)
+    client = localClient;
+
+    console.log(`Client address is ${selfAddress}`);
+    self.postMessage({
+        kind: 'Ready',
+        args: {
+            selfAddress,
+        },
+    });
+
+    // Set callback to handle messages passed to the worker.
+    self.onmessage = async event => {
+        console.log(event)
+        if (event.data && event.data.kind) {
+            switch (event.data.kind) {
+                case 'SendMessage': {
+                    const {message, recipient} = event.data.args;
+                    let uint8Array = new TextEncoder().encode(message);
+                    await client.send_regular_message(uint8Array, recipient);
+                    break;
+                }
+            }
+        }
+    };
+}
+
+async function main() {
+    // load WASM package
+    await wasm_bindgen('nym_client_wasm_bg.wasm');
+    console.log('Loaded WASM');
+
+    // sets up better stack traces in case of in-rust panics
+    set_panic_hook();
+
+    // run test on simplified and dedicated tester:
+    await testWithTester()
+
+    // hook-up the whole client for testing
+    // await testWithNymClient()
+
+    // 'Normal' client setup (to send 'normal' messages)
+    // await normalNymClientUsage()
+}
+
+// Let's get started!
+main();
@@ -25,7 +25,7 @@ pub struct Config {
    /// ID specifies the human readable ID of this particular client.
    pub(crate) id: String,

-    pub(crate) nym_api_url: Url,
+    pub(crate) nym_api_url: Option<Url>,

    pub(crate) disabled_credentials_mode: bool,

@@ -46,9 +46,11 @@ impl Config {
    ) -> Self {
        Config {
            id,
-            nym_api_url: validator_server
-                .parse()
-                .expect("provided url was malformed"),
+            nym_api_url: Some(
+                validator_server
+                    .parse()
+                    .expect("provided url was malformed"),
+            ),
            disabled_credentials_mode: true,
            gateway_endpoint,
            debug: debug.map(Into::into).unwrap_or_default(),
@@ -229,6 +231,11 @@ pub struct Topology {
    /// path. This timeout determines waiting period until it is decided that the packet
    /// did not reach its destination.
    pub topology_resolution_timeout_ms: u64,
+
+    /// Specifies whether the client should not refresh the network topology after obtaining
+    /// the first valid instance.
+    /// Supersedes `topology_refresh_rate_ms`.
+    pub disable_refreshing: bool,
 }

 impl From<Topology> for ConfigTopology {
@@ -238,6 +245,7 @@ impl From<Topology> for ConfigTopology {
            topology_resolution_timeout: Duration::from_millis(
                topology.topology_resolution_timeout_ms,
            ),
+            disable_refreshing: topology.disable_refreshing,
        }
    }
 }
@@ -247,6 +255,7 @@ impl From<ConfigTopology> for Topology {
        Topology {
            topology_refresh_rate_ms: topology.topology_refresh_rate.as_millis() as u64,
            topology_resolution_timeout_ms: topology.topology_resolution_timeout.as_millis() as u64,
+            disable_refreshing: topology.disable_refreshing,
        }
    }
 }
@@ -1,16 +1,42 @@
-// Copyright 2022 - Nym Technologies SA <contact@nymtech.net>
+// Copyright 2022-2023 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

+use crate::error::WasmClientError;
+use crate::tester::helpers::WasmTestMessageExt;
+use crate::tester::{NodeTestMessage, DEFAULT_TEST_PACKETS};
+use crate::topology::WasmNymTopology;
 use js_sys::Promise;
-use nym_client_core::client::base_client::ClientInput;
+use nym_client_core::client::base_client::{ClientInput, ClientState};
 use nym_client_core::client::inbound_messages::InputMessage;
+use nym_topology::{MixLayer, NymTopology};
 use std::sync::Arc;
+use wasm_bindgen::prelude::*;
 use wasm_bindgen::JsValue;
 use wasm_bindgen_futures::future_to_promise;
+use wasm_utils::{console_log, js_error, simple_js_error};
+
+#[wasm_bindgen]
+pub struct NymClientTestRequest {
+    // serialized NodeTestMessage
+    pub(crate) test_msgs: Vec<Vec<u8>>,
+
+    // specially constructed network topology that only contains the target
+    // node on the tested layer
+    pub(crate) testable_topology: NymTopology,
+}
+
+#[wasm_bindgen]
+impl NymClientTestRequest {
+    pub fn injectable_topology(&self) -> WasmNymTopology {
+        self.testable_topology.clone().into()
+    }
+}

 // defining helper trait as we could directly call the method on the wrapper
 pub(crate) trait InputSender {
    fn send_message(&self, message: InputMessage) -> Promise;
+
+    fn send_messages(&self, messages: Vec<InputMessage>) -> Promise;
 }

 impl InputSender for Arc<ClientInput> {
@@ -19,12 +45,125 @@ impl InputSender for Arc<ClientInput> {
        future_to_promise(async move {
            match this.input_sender.send(message).await {
                Ok(_) => Ok(JsValue::null()),
-                Err(_) => {
-                    let js_error =
-                        js_sys::Error::new("InputMessageReceiver has stopped receiving!");
-                    Err(JsValue::from(js_error))
-                }
+                Err(_) => Err(simple_js_error(
+                    "InputMessageReceiver has stopped receiving!",
+                )),
            }
        })
    }
+
+    fn send_messages(&self, messages: Vec<InputMessage>) -> Promise {
+        let this = Arc::clone(self);
+        future_to_promise(async move {
+            for message in messages {
+                if this.input_sender.send(message).await.is_err() {
+                    return Err(simple_js_error(
+                        "InputMessageReceiver has stopped receiving!",
+                    ));
+                }
+            }
+            Ok(JsValue::null())
+        })
+    }
+}
+
+pub(crate) trait WasmTopologyExt {
+    /// Changes the current network topology to the provided value.
+    fn change_hardcoded_topology(&self, topology: WasmNymTopology) -> Promise;
+
+    /// Returns the current network topology.
+    fn current_topology(&self) -> Promise;
+
+    /// Checks whether the provided node exists in the known network topology and if so, returns its layer.
+    fn check_for_mixnode_existence(&self, mixnode_identity: String) -> Promise;
+
+    /// Creates a `NymClientTestRequest` with a variant of `this` topology where the target node is the only one on its layer.
+    fn mix_test_request(
+        &self,
+        test_id: u32,
+        mixnode_identity: String,
+        num_test_packets: Option<u32>,
+    ) -> Promise;
+}
+
+impl WasmTopologyExt for Arc<ClientState> {
+    fn change_hardcoded_topology(&self, topology: WasmNymTopology) -> Promise {
+        let this = Arc::clone(self);
+        future_to_promise(async move {
+            let nym_topology: NymTopology = topology.into();
+            console_log!("changing topology to {nym_topology:?}");
+            this.topology_accessor
+                .manually_change_topology(nym_topology)
+                .await;
+            Ok(JsValue::null())
+        })
+    }
+
+    fn current_topology(&self) -> Promise {
+        let this = Arc::clone(self);
+        future_to_promise(async move {
+            match this.topology_accessor.current_topology().await {
+                Some(topology) => Ok(JsValue::from(WasmNymTopology::from(topology))),
+                None => Err(WasmClientError::UnavailableNetworkTopology.into()),
+            }
+        })
+    }
+
+    /// Checks whether the target mixnode exists in the known network topology and returns its layer.
+    fn check_for_mixnode_existence(&self, mixnode_identity: String) -> Promise {
+        let this = Arc::clone(self);
+        future_to_promise(async move {
+            let Some(current_topology) = this.topology_accessor.current_topology().await else {
+                return Err(WasmClientError::UnavailableNetworkTopology.into())
+            };
+
+            match current_topology.find_mix_by_identity(&mixnode_identity) {
+                None => Err(WasmClientError::NonExistentMixnode { mixnode_identity }.into()),
+                Some(node) => Ok(JsValue::from(MixLayer::from(node.layer))),
+            }
+        })
+    }
+
+    fn mix_test_request(
+        &self,
+        test_id: u32,
+        mixnode_identity: String,
+        num_test_packets: Option<u32>,
+    ) -> Promise {
+        let num_test_packets = num_test_packets.unwrap_or(DEFAULT_TEST_PACKETS);
+
+        let this = Arc::clone(self);
+        future_to_promise(async move {
+            let Some(current_topology) = this.topology_accessor.current_topology().await else {
+                return Err(WasmClientError::UnavailableNetworkTopology.into())
+            };
+
+            let Some(mix) = current_topology.find_mix_by_identity(&mixnode_identity) else {
+                return Err(WasmClientError::NonExistentMixnode { mixnode_identity }.into());
+            };
+
+            let mut test_msgs = Vec::with_capacity(num_test_packets as usize);
+            for i in 1..=num_test_packets {
+                let msg = NodeTestMessage::new_mix(
+                    mix,
+                    i,
+                    num_test_packets,
+                    WasmTestMessageExt::new(test_id),
+                );
+                let serialized = match msg.as_bytes() {
+                    Ok(bytes) => bytes,
+                    Err(err) => return Err(js_error!("failed to serialize test message: {err}")),
+                };
+                test_msgs.push(serialized);
+            }
+
+            let mut updated = current_topology.clone();
+            updated.set_mixes_in_layer(mix.layer.into(), vec![mix.to_owned()]);
+
+            Ok(JsValue::from(NymClientTestRequest {
+                test_msgs,
+                testable_topology: updated,
+            }))
+        })
+    }
 }
@@ -1,27 +1,37 @@
-// Copyright 2021-2022 - Nym Technologies SA <contact@nymtech.net>
+// Copyright 2021-2023 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

 use self::config::Config;
-use crate::client::helpers::InputSender;
+use crate::client::helpers::{InputSender, NymClientTestRequest, WasmTopologyExt};
 use crate::client::response_pusher::ResponsePusher;
+use crate::error::WasmClientError;
+use crate::helpers::{
+    parse_recipient, parse_sender_tag, setup_new_key_manager, setup_reply_surb_storage_backend,
+};
+use crate::topology::WasmNymTopology;
 use js_sys::Promise;
 use nym_bandwidth_controller::wasm_mockups::{Client as FakeClient, DirectSigningNyxdClient};
 use nym_bandwidth_controller::BandwidthController;
 use nym_client_core::client::base_client::{
-    BaseClientBuilder, ClientInput, ClientOutput, CredentialsToggle,
+    BaseClientBuilder, ClientInput, ClientOutput, ClientState, CredentialsToggle,
 };
 use nym_client_core::client::replies::reply_storage::browser_backend;
 use nym_client_core::client::{inbound_messages::InputMessage, key_manager::KeyManager};
+use nym_client_core::config::{
+    CoverTraffic, DebugConfig, GatewayEndpointConfig, Topology, Traffic,
+};
 use nym_credential_storage::ephemeral_storage::EphemeralStorage;
-use nym_sphinx::addressing::clients::Recipient;
-use nym_sphinx::anonymous_replies::requests::AnonymousSenderTag;
+use nym_sphinx::params::PacketType;
 use nym_task::connections::TransmissionLane;
 use nym_task::TaskManager;
+use nym_topology::provider_trait::{HardcodedTopologyProvider, TopologyProvider};
+use nym_topology::NymTopology;
 use rand::rngs::OsRng;
+use rand::RngCore;
 use std::sync::Arc;
 use wasm_bindgen::prelude::*;
 use wasm_bindgen_futures::future_to_promise;
-use wasm_utils::{console_error, console_log};
+use wasm_utils::{check_promise_result, console_log, PromisableResult};

 pub mod config;
 mod helpers;
@@ -31,15 +41,22 @@ mod response_pusher;
 pub struct NymClient {
    self_address: String,
    client_input: Arc<ClientInput>,
+    client_state: Arc<ClientState>,
+
+    // keep track of the "old" topology for the purposes of node tester
+    // so that it could be restored after the check is done
+    _full_topology: Option<NymTopology>,

    // even though we don't use graceful shutdowns, other components rely on existence of this struct
    // and if it's dropped, everything will start going offline
    _task_manager: TaskManager,
+    packet_type: Option<PacketType>,
 }

 #[wasm_bindgen]
 pub struct NymClientBuilder {
    config: Config,
+    custom_topology: Option<NymTopology>,

    /// KeyManager object containing smart pointers to all relevant keys used by the client.
    key_manager: KeyManager,
@@ -52,6 +69,7 @@ pub struct NymClientBuilder {
    bandwidth_controller:
        Option<BandwidthController<FakeClient<DirectSigningNyxdClient>, EphemeralStorage>>,
    disabled_credentials: bool,
+    packet_type: Option<PacketType>,
 }

 #[wasm_bindgen]
@@ -60,118 +78,193 @@ impl NymClientBuilder {
    pub fn new(config: Config, on_message: js_sys::Function) -> Self {
        //, key_manager: Option<KeyManager>) {
        NymClientBuilder {
-            reply_surb_storage_backend: Self::setup_reply_surb_storage_backend(&config),
+            reply_surb_storage_backend: setup_reply_surb_storage_backend(config.debug.reply_surbs),
            config,
-            key_manager: Self::setup_key_manager(),
+            custom_topology: None,
+            key_manager: setup_new_key_manager(),
            on_message,
            bandwidth_controller: None,
            disabled_credentials: true,
+            packet_type: None,
        }
    }

-    // TODO: once we make keys persistent, we'll require some kind of `init` method to generate
-    // a prior shared keypair between the client and the gateway
+    // no cover traffic
+    // no poisson delay
+    // hardcoded topology
+    // NOTE: you most likely want to use `[NymNodeTester]` instead.
+    pub fn new_tester(
+        gateway_config: GatewayEndpointConfig,
+        topology: WasmNymTopology,
+        on_message: js_sys::Function,
+    ) -> Self {
+        if !topology.ensure_contains(&gateway_config) {
+            panic!("the specified topology does not contain the gateway used by the client")
+        }

-    // perhaps this should be public?
-    fn setup_key_manager() -> KeyManager {
-        let mut rng = OsRng;
-        // for time being generate new keys each time...
-        console_log!("generated new set of keys");
-        KeyManager::new(&mut rng)
-    }
+        let full_config = Config {
+            id: "ephemeral-id".to_string(),
+            nym_api_url: None,
+            disabled_credentials_mode: true,
+            gateway_endpoint: gateway_config,
+            debug: DebugConfig {
+                traffic: Traffic {
+                    disable_main_poisson_packet_distribution: true,
+                    ..Default::default()
+                },
+                cover_traffic: CoverTraffic {
+                    disable_loop_cover_traffic_stream: true,
+                    ..Default::default()
+                },
+                topology: Topology {
+                    disable_refreshing: true,
+                    ..Default::default()
+                },
+                ..Default::default()
+            },
+        };

-    // don't get too excited about the name, under the hood it's just a big fat placeholder
-    // with no persistence
-    fn setup_reply_surb_storage_backend(config: &Config) -> browser_backend::Backend {
-        browser_backend::Backend::new(
-            config
-                .debug
-                .reply_surbs
-                .minimum_reply_surb_storage_threshold,
-            config
-                .debug
-                .reply_surbs
-                .maximum_reply_surb_storage_threshold,
-        )
+        NymClientBuilder {
+            reply_surb_storage_backend: setup_reply_surb_storage_backend(
+                full_config.debug.reply_surbs,
+            ),
+            config: full_config,
+            custom_topology: Some(topology.into()),
+            // TODO: once we make keys persistent, we'll require some kind of `init` method to generate
+            // a prior shared keypair between the client and the gateway
+            key_manager: setup_new_key_manager(),
+            on_message,
+            bandwidth_controller: None,
+            disabled_credentials: true,
+            packet_type: None,
+        }
    }

    fn start_reconstructed_pusher(client_output: ClientOutput, on_message: js_sys::Function) {
        ResponsePusher::new(client_output, on_message).start()
    }

-    pub async fn start_client(self) -> Promise {
-        future_to_promise(async move {
-            console_log!("Starting the wasm client");
+    fn topology_provider(&mut self) -> Option<Box<dyn TopologyProvider>> {
+        if let Some(hardcoded_topology) = self.custom_topology.take() {
+            Some(Box::new(HardcodedTopologyProvider::new(hardcoded_topology)))
+        } else {
+            None
+        }
+    }

-            let disabled_credentials = if self.disabled_credentials {
-                CredentialsToggle::Disabled
-            } else {
-                CredentialsToggle::Enabled
-            };
+    async fn start_client_async(mut self) -> Result<NymClient, WasmClientError> {
+        console_log!("Starting the wasm client");

-            let base_builder = BaseClientBuilder::new(
-                &self.config.gateway_endpoint,
-                &self.config.debug,
-                self.key_manager,
-                self.bandwidth_controller,
-                self.reply_surb_storage_backend,
-                disabled_credentials,
-                vec![self.config.nym_api_url.clone()],
-            );
+        let maybe_topology_provider = self.topology_provider();

-            let self_address = base_builder.as_mix_recipient().to_string();
-            let mut started_client = match base_builder.start_base().await {
-                Ok(base_client) => base_client,
-                Err(err) => {
-                    let error_msg = format!("failed to start the base client components - {err}");
-                    console_error!("{}", error_msg);
-                    let js_error = js_sys::Error::new(&error_msg);
-                    return Err(JsValue::from(js_error));
-                }
-            };
+        let disabled_credentials = if self.disabled_credentials {
+            CredentialsToggle::Disabled
+        } else {
+            CredentialsToggle::Enabled
+        };

-            let client_input = started_client.client_input.register_producer();
-            let client_output = started_client.client_output.register_consumer();
+        let nym_api_endpoints = match self.config.nym_api_url {
+            Some(endpoint) => vec![endpoint],
+            None => Vec::new(),
+        };
+        let mut base_builder = BaseClientBuilder::new(
+            &self.config.gateway_endpoint,
+            &self.config.debug,
+            self.key_manager,
+            self.bandwidth_controller,
+            self.reply_surb_storage_backend,
+            disabled_credentials,
+            nym_api_endpoints,
+        );
+        if let Some(topology_provider) = maybe_topology_provider {
+            base_builder = base_builder.with_topology_provider(topology_provider);
+        }

-            Self::start_reconstructed_pusher(client_output, self.on_message);
+        let self_address = base_builder.as_mix_recipient().to_string();
+        let mut started_client = base_builder.start_base().await?;

-            Ok(JsValue::from(NymClient {
-                self_address,
-                client_input: Arc::new(client_input),
-                _task_manager: started_client.task_manager,
-            }))
+        let client_input = started_client.client_input.register_producer();
+        let client_output = started_client.client_output.register_consumer();
+
+        Self::start_reconstructed_pusher(client_output, self.on_message);
+
+        Ok(NymClient {
+            self_address,
+            client_input: Arc::new(client_input),
+            client_state: Arc::new(started_client.client_state),
+            _full_topology: None,
+            _task_manager: started_client.task_manager,
+            packet_type: self.packet_type,
        })
    }
+
+    pub fn start_client(self) -> Promise {
+        future_to_promise(async move { self.start_client_async().await.into_promise_result() })
+    }
 }

 #[wasm_bindgen]
 impl NymClient {
+    async fn _new(
+        config: Config,
+        on_message: js_sys::Function,
+    ) -> Result<NymClient, WasmClientError> {
+        NymClientBuilder::new(config, on_message)
+            .start_client_async()
+            .await
+    }
+
+    #[wasm_bindgen(constructor)]
+    #[allow(clippy::new_ret_no_self)]
+    pub fn new(config: Config, on_message: js_sys::Function) -> Promise {
+        future_to_promise(async move { Self::_new(config, on_message).await.into_promise_result() })
+    }
+
    pub fn self_address(&self) -> String {
        self.self_address.clone()
    }

-    fn parse_recipient(recipient: &str) -> Result<Recipient, JsValue> {
-        match Recipient::try_from_base58_string(recipient) {
-            Ok(recipient) => Ok(recipient),
-            Err(err) => {
-                let error_msg = format!("{recipient} is not a valid Nym network recipient - {err}");
-                console_error!("{}", error_msg);
-                let js_error = js_sys::Error::new(&error_msg);
-                Err(JsValue::from(js_error))
-            }
-        }
+    pub fn try_construct_test_packet_request(
+        &self,
+        mixnode_identity: String,
+        num_test_packets: Option<u32>,
+    ) -> Promise {
+        // TODO: improve the source of rng (i.e. don't make it ephemeral...)
+        let mut ephemeral_rng = OsRng;
+        let test_id = ephemeral_rng.next_u32();
+        self.client_state
+            .mix_test_request(test_id, mixnode_identity, num_test_packets)
    }

-    fn parse_sender_tag(tag: &str) -> Result<AnonymousSenderTag, JsValue> {
-        match AnonymousSenderTag::try_from_base58_string(tag) {
-            Ok(tag) => Ok(tag),
-            Err(err) => {
-                let error_msg = format!("{tag} is not a valid Nym AnonymousSenderTag - {err}");
-                console_error!("{}", error_msg);
-                let js_error = js_sys::Error::new(&error_msg);
-                Err(JsValue::from(js_error))
-            }
-        }
+    pub fn change_hardcoded_topology(&self, topology: WasmNymTopology) -> Promise {
+        self.client_state.change_hardcoded_topology(topology)
+    }
+
+    pub fn current_network_topology(&self) -> Promise {
+        self.client_state.current_topology()
+    }
+
+    /// Sends a test packet through the current network topology.
+    /// It's the responsibility of the caller to ensure the correct topology has been injected and
+    /// correct onmessage handlers have been setup.
+    pub fn try_send_test_packets(&mut self, request: NymClientTestRequest) -> Promise {
+        // TOOD: use the premade packets instead
+        console_log!(
+            "Attempting to send {} test packets",
+            request.test_msgs.len()
+        );
+
+        // our address MUST BE valid
+        let recipient = parse_recipient(&self.self_address()).unwrap();
+
+        let lane = TransmissionLane::General;
+        let input_msgs = request
+            .test_msgs
+            .into_iter()
+            .map(|p| InputMessage::new_regular(recipient, p, lane, None))
+            .collect();
+
+        self.client_input.send_messages(input_msgs)
    }

    /// The simplest message variant where no additional information is attached.
@@ -184,13 +277,11 @@ impl NymClient {
            message.len() as f64 / 1024.0
        );

-        let recipient = match Self::parse_recipient(&recipient) {
-            Ok(recipient) => recipient,
-            Err(err) => return Promise::reject(&err),
-        };
+        let recipient = check_promise_result!(parse_recipient(&recipient));
+
        let lane = TransmissionLane::General;

-        let input_msg = InputMessage::new_regular(recipient, message, lane);
+        let input_msg = InputMessage::new_regular(recipient, message, lane, self.packet_type);
        self.client_input.send_message(input_msg)
    }

@@ -213,13 +304,12 @@ impl NymClient {
            message.len() as f64 / 1024.0
        );

-        let recipient = match Self::parse_recipient(&recipient) {
-            Ok(recipient) => recipient,
-            Err(err) => return Promise::reject(&err),
-        };
+        let recipient = check_promise_result!(parse_recipient(&recipient));
+
        let lane = TransmissionLane::General;

-        let input_msg = InputMessage::new_anonymous(recipient, message, reply_surbs, lane);
+        let input_msg =
+            InputMessage::new_anonymous(recipient, message, reply_surbs, lane, self.packet_type);
        self.client_input.send_message(input_msg)
    }

@@ -233,13 +323,11 @@ impl NymClient {
            message.len() as f64 / 1024.0
        );

-        let sender_tag = match Self::parse_sender_tag(&recipient_tag) {
-            Ok(recipient) => recipient,
-            Err(err) => return Promise::reject(&err),
-        };
+        let sender_tag = check_promise_result!(parse_sender_tag(&recipient_tag));
+
        let lane = TransmissionLane::General;

-        let input_msg = InputMessage::new_reply(sender_tag, message, lane);
+        let input_msg = InputMessage::new_reply(sender_tag, message, lane, self.packet_type);
        self.client_input.send_message(input_msg)
    }
 }
@@ -0,0 +1,99 @@
+// Copyright 2023 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::topology::WasmTopologyError;
+use js_sys::Promise;
+use nym_client_core::error::ClientCoreError;
+use nym_crypto::asymmetric::identity::Ed25519RecoveryError;
+use nym_gateway_client::error::GatewayClientError;
+use nym_node_tester_utils::error::NetworkTestingError;
+use nym_sphinx::addressing::clients::RecipientFormattingError;
+use nym_sphinx::anonymous_replies::requests::InvalidAnonymousSenderTagRepresentation;
+use nym_validator_client::ValidatorClientError;
+use thiserror::Error;
+use wasm_bindgen::JsValue;
+use wasm_utils::simple_js_error;
+
+// might as well start using well-defined error enum...
+#[derive(Debug, Error)]
+pub enum WasmClientError {
+    #[error(
+        "A node test is already in progress. Wait for it to finish before starting another one."
+    )]
+    TestInProgress,
+
+    #[error("experienced an issue with internal client components: {source}")]
+    BaseClientError {
+        #[from]
+        source: ClientCoreError,
+    },
+
+    #[error("The provided gateway identity is invalid: {source}")]
+    InvalidGatewayIdentity { source: Ed25519RecoveryError },
+
+    #[error("Gateway communication failure: {source}")]
+    GatewayClientError {
+        #[from]
+        source: GatewayClientError,
+    },
+
+    #[error("failed to query nym api: {source}")]
+    NymApiError {
+        #[from]
+        source: ValidatorClientError,
+    },
+
+    #[error("The provided topology was invalid: {source}")]
+    WasmTopologyError {
+        #[from]
+        source: WasmTopologyError,
+    },
+
+    #[error("failed to test the node: {source}")]
+    NodeTestingFailure {
+        #[from]
+        source: NetworkTestingError,
+    },
+
+    #[error("{raw} is not a valid url: {source}")]
+    MalformedUrl {
+        raw: String,
+        source: url::ParseError,
+    },
+
+    #[error("Network topology is currently unavailable")]
+    UnavailableNetworkTopology,
+
+    #[error("Mixnode {mixnode_identity} is not present in the current network topology")]
+    NonExistentMixnode { mixnode_identity: String },
+
+    #[error("{raw} is not a valid Nym network recipient: {source}")]
+    MalformedRecipient {
+        raw: String,
+        source: RecipientFormattingError,
+    },
+
+    #[error("{raw} is not a valid Nym AnonymousSenderTag: {source}")]
+    MalformedSenderTag {
+        raw: String,
+        source: InvalidAnonymousSenderTagRepresentation,
+    },
+}
+
+impl WasmClientError {
+    pub fn into_rejected_promise(self) -> Promise {
+        self.into()
+    }
+}
+
+impl From<WasmClientError> for JsValue {
+    fn from(value: WasmClientError) -> Self {
+        simple_js_error(value.to_string())
+    }
+}
+
+impl From<WasmClientError> for Promise {
+    fn from(value: WasmClientError) -> Self {
+        Promise::reject(&value.into())
+    }
+}
@@ -0,0 +1,82 @@
+// Copyright 2023 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::error::WasmClientError;
+use crate::topology::WasmNymTopology;
+use js_sys::Promise;
+use nym_client_core::client::key_manager::KeyManager;
+use nym_client_core::client::replies::reply_storage::browser_backend;
+use nym_client_core::config;
+use nym_sphinx::addressing::clients::Recipient;
+use nym_sphinx::anonymous_replies::requests::AnonymousSenderTag;
+use nym_topology::NymTopology;
+use nym_validator_client::NymApiClient;
+use rand::rngs::OsRng;
+use url::Url;
+use wasm_bindgen::prelude::wasm_bindgen;
+use wasm_bindgen_futures::future_to_promise;
+use wasm_utils::{console_log, PromisableResult};
+
+pub(crate) fn setup_new_key_manager() -> KeyManager {
+    let mut rng = OsRng;
+    console_log!("generated new set of keys");
+    KeyManager::new(&mut rng)
+}
+
+// don't get too excited about the name, under the hood it's just a big fat placeholder
+// with no persistence
+pub(crate) fn setup_reply_surb_storage_backend(
+    config: config::ReplySurbs,
+) -> browser_backend::Backend {
+    browser_backend::Backend::new(
+        config.minimum_reply_surb_storage_threshold,
+        config.maximum_reply_surb_storage_threshold,
+    )
+}
+
+pub(crate) fn parse_recipient(recipient: &str) -> Result<Recipient, WasmClientError> {
+    Recipient::try_from_base58_string(recipient).map_err(|source| {
+        WasmClientError::MalformedRecipient {
+            raw: recipient.to_string(),
+            source,
+        }
+    })
+}
+
+pub(crate) fn parse_sender_tag(tag: &str) -> Result<AnonymousSenderTag, WasmClientError> {
+    AnonymousSenderTag::try_from_base58_string(tag).map_err(|source| {
+        WasmClientError::MalformedSenderTag {
+            raw: tag.to_string(),
+            source,
+        }
+    })
+}
+
+pub(crate) async fn current_network_topology_async(
+    nym_api_url: String,
+) -> Result<WasmNymTopology, WasmClientError> {
+    let url: Url = match nym_api_url.parse() {
+        Ok(url) => url,
+        Err(source) => {
+            return Err(WasmClientError::MalformedUrl {
+                raw: nym_api_url,
+                source,
+            })
+        }
+    };
+
+    let api_client = NymApiClient::new(url);
+    let mixnodes = api_client.get_cached_active_mixnodes().await?;
+    let gateways = api_client.get_cached_gateways().await?;
+
+    Ok(NymTopology::from_detailed(mixnodes, gateways).into())
+}
+
+#[wasm_bindgen]
+pub fn current_network_topology(nym_api_url: String) -> Promise {
+    future_to_promise(async move {
+        current_network_topology_async(nym_api_url)
+            .await
+            .into_promise_result()
+    })
+}
@@ -7,11 +7,19 @@ use wasm_bindgen::prelude::*;
 mod client;
 #[cfg(target_arch = "wasm32")]
 pub mod encoded_payload_helper;
+pub mod error;
 #[cfg(target_arch = "wasm32")]
 pub mod gateway_selector;
 #[cfg(target_arch = "wasm32")]
+pub mod tester;
+#[cfg(target_arch = "wasm32")]
+pub mod topology;
+#[cfg(target_arch = "wasm32")]
 pub mod validation;

+#[cfg(target_arch = "wasm32")]
+mod helpers;
+
 #[wasm_bindgen]
 pub fn set_panic_hook() {
    // When the `console_error_panic_hook` feature is enabled, we can call the
@@ -0,0 +1,117 @@
+// Copyright 2023 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::tester::helpers::NodeTestResult;
+use crate::tester::NodeTestMessage;
+use futures::StreamExt;
+use nym_node_tester_utils::receiver::{Received, ReceivedReceiver};
+use nym_sphinx::chunking::fragment::FragmentIdentifier;
+use std::collections::HashSet;
+use std::time::Duration;
+use tokio::sync::MutexGuard as AsyncMutexGuard;
+use wasm_utils::{console_error, console_log, console_warn};
+
+pub(crate) struct EphemeralTestReceiver<'a> {
+    sent_packets: u32,
+    expected_acks: HashSet<FragmentIdentifier>,
+
+    received_valid_messages: HashSet<u32>,
+    received_valid_acks: HashSet<FragmentIdentifier>,
+    duplicate_packets: u32,
+    duplicate_acks: u32,
+
+    timeout_duration: Duration,
+    receiver_permit: AsyncMutexGuard<'a, ReceivedReceiver>,
+}
+
+impl<'a> EphemeralTestReceiver<'a> {
+    pub(crate) fn finish(self) -> NodeTestResult {
+        NodeTestResult {
+            sent_packets: self.sent_packets,
+            received_packets: self.received_valid_messages.len() as u32,
+            received_acks: self.received_valid_acks.len() as u32,
+            duplicate_packets: self.duplicate_packets,
+            duplicate_acks: self.duplicate_acks,
+        }
+    }
+
+    pub(crate) fn new(
+        sent_packets: u32,
+        expected_acks: HashSet<FragmentIdentifier>,
+        receiver_permit: AsyncMutexGuard<'a, ReceivedReceiver>,
+        timeout: Duration,
+    ) -> Self {
+        EphemeralTestReceiver {
+            sent_packets,
+            expected_acks,
+            received_valid_messages: Default::default(),
+            received_valid_acks: Default::default(),
+            duplicate_packets: 0,
+            duplicate_acks: 0,
+            timeout_duration: timeout,
+            receiver_permit,
+        }
+    }
+
+    fn on_next_received_packet(&mut self, packet: Option<Received>) -> bool {
+        let Some(received_packet) = packet else {
+            // can't do anything more...
+            console_error!("packet receiver has stopped processing results!");
+            return true
+        };
+        match received_packet {
+            Received::Message(msg) => match NodeTestMessage::try_recover(msg) {
+                Ok(test_msg) => {
+                    if !self.received_valid_messages.insert(test_msg.msg_id) {
+                        self.duplicate_packets += 1;
+                    }
+                }
+                Err(err) => {
+                    console_warn!("failed to recover test message from received packet: {err}")
+                }
+            },
+            Received::Ack(frag_id) => {
+                if self.expected_acks.contains(&frag_id) {
+                    if !self.received_valid_acks.insert(frag_id) {
+                        self.duplicate_acks += 1
+                    }
+                } else {
+                    console_warn!("received an ack that was not part of the test! (id: {frag_id})")
+                }
+            }
+        }
+
+        if self.received_all() {
+            console_log!("already received all the packets! finishing the test...");
+            true
+        } else {
+            false
+        }
+    }
+
+    fn received_all(&self) -> bool {
+        self.received_valid_acks.len() == self.received_valid_messages.len()
+            && self.received_valid_acks.len() == self.sent_packets as usize
+    }
+
+    pub(crate) async fn perform_test(mut self) -> NodeTestResult {
+        let mut timeout_fut = wasm_timer::Delay::new(self.timeout_duration);
+
+        loop {
+            tokio::select! {
+                _ = &mut timeout_fut => {
+                    console_warn!("reached test timeout before receiving all packets.");
+                    break
+                }
+                received_packet = self.receiver_permit.next() => {
+                    let is_done = self.on_next_received_packet(received_packet);
+                    if is_done {
+                        break
+                    }
+                }
+            }
+        }
+
+        self.finish()
+    }
+}
@@ -0,0 +1,108 @@
+// Copyright 2023 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+// due to expansion of #[wasm_bindgen] macro on NodeTestResult
+#![allow(clippy::drop_non_drop)]
+
+use nym_node_tester_utils::receiver::{Received, ReceivedReceiver};
+use serde::{Deserialize, Serialize};
+use std::fmt::{Display, Formatter};
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+use tokio::sync::{Mutex as AsyncMutex, MutexGuard as AsyncMutexGuard};
+use wasm_bindgen::prelude::*;
+use wasm_utils::{console_log, console_warn};
+
+#[derive(Clone)]
+pub(super) struct ReceivedReceiverWrapper(Arc<AsyncMutex<ReceivedReceiver>>);
+
+impl ReceivedReceiverWrapper {
+    pub(super) fn new(inner: ReceivedReceiver) -> Self {
+        ReceivedReceiverWrapper(Arc::new(AsyncMutex::new(inner)))
+    }
+
+    pub(super) async fn clear_received_channel(&self) {
+        let mut lost_msgs = 0;
+        let mut lost_acks = 0;
+        let mut permit = self.0.lock().await;
+        while let Ok(Some(received)) = permit.try_next() {
+            match received {
+                Received::Message(_) => lost_msgs += 1,
+                Received::Ack(_) => lost_acks += 1,
+            }
+        }
+        if lost_msgs > 0 || lost_acks > 0 {
+            console_warn!("while preparing for the test run, we cleared {lost_msgs} messages and {lost_acks} acks that were received in the meantime.")
+        }
+    }
+
+    pub(super) async fn lock(&self) -> AsyncMutexGuard<'_, ReceivedReceiver> {
+        self.0.lock().await
+    }
+}
+
+#[derive(Serialize, Deserialize, Copy, Clone)]
+pub struct WasmTestMessageExt {
+    pub test_id: u32,
+}
+
+impl WasmTestMessageExt {
+    pub fn new(test_id: u32) -> Self {
+        WasmTestMessageExt { test_id }
+    }
+}
+
+// TODO: maybe put it in the tester utils
+#[wasm_bindgen]
+pub struct NodeTestResult {
+    pub sent_packets: u32,
+    pub received_packets: u32,
+    pub received_acks: u32,
+
+    pub duplicate_packets: u32,
+    pub duplicate_acks: u32,
+}
+
+impl Display for NodeTestResult {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        writeln!(f, "Test results: ")?;
+        writeln!(f, "Total score: {:.2}%", self.score())?;
+        writeln!(f, "Sent packets: {}", self.sent_packets)?;
+        writeln!(f, "Received (valid) packets: {}", self.received_packets)?;
+        writeln!(f, "Received (valid) acks: {}", self.received_acks)?;
+        writeln!(f, "Received duplicate packets: {}", self.duplicate_packets)?;
+        write!(f, "Received duplicate acks: {}", self.duplicate_acks)
+    }
+}
+
+#[wasm_bindgen]
+impl NodeTestResult {
+    pub fn log_details(&self) {
+        console_log!("{}", self)
+    }
+
+    pub fn score(&self) -> f32 {
+        let expected = self.sent_packets * 2;
+        let actual = (self.received_packets + self.received_acks)
+            .saturating_sub(self.duplicate_packets + self.duplicate_acks);
+
+        actual as f32 / expected as f32 * 100.
+    }
+}
+
+pub(crate) struct TestMarker {
+    value: Arc<AtomicBool>,
+}
+
+impl TestMarker {
+    pub fn new(value: Arc<AtomicBool>) -> Self {
+        Self { value }
+    }
+}
+
+impl Drop for TestMarker {
+    // make sure to clear the test flag when the marker is dropped
+    fn drop(&mut self) {
+        self.value.store(false, Ordering::SeqCst)
+    }
+}
@@ -0,0 +1,316 @@
+// Copyright 2023 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::error::WasmClientError;
+use crate::helpers::{current_network_topology_async, setup_new_key_manager};
+use crate::tester::ephemeral_receiver::EphemeralTestReceiver;
+use crate::tester::helpers::{
+    NodeTestResult, ReceivedReceiverWrapper, TestMarker, WasmTestMessageExt,
+};
+use crate::topology::WasmNymTopology;
+use futures::channel::mpsc;
+use js_sys::Promise;
+use nym_bandwidth_controller::wasm_mockups::{Client as FakeClient, DirectSigningNyxdClient};
+use nym_bandwidth_controller::BandwidthController;
+use nym_client_core::client::key_manager::KeyManager;
+use nym_client_core::config::GatewayEndpointConfig;
+use nym_credential_storage::ephemeral_storage::EphemeralStorage;
+use nym_crypto::asymmetric::identity;
+use nym_gateway_client::GatewayClient;
+use nym_node_tester_utils::receiver::SimpleMessageReceiver;
+use nym_node_tester_utils::{NodeTester, TestMessage};
+use nym_sphinx::addressing::clients::Recipient;
+use nym_sphinx::addressing::nodes::NodeIdentity;
+use nym_sphinx::params::PacketSize;
+use nym_sphinx::preparer::PreparedFragment;
+use nym_task::TaskManager;
+use nym_topology::NymTopology;
+use rand::rngs::OsRng;
+use std::collections::HashSet;
+use std::sync::atomic::{AtomicBool, AtomicU32, Ordering};
+use std::sync::{Arc, Mutex as SyncMutex};
+use std::time::Duration;
+use tokio::sync::Mutex as AsyncMutex;
+use wasm_bindgen::prelude::*;
+use wasm_bindgen_futures::future_to_promise;
+use wasm_utils::{check_promise_result, console_log, console_warn, PromisableResult};
+
+mod ephemeral_receiver;
+pub(crate) mod helpers;
+
+pub type NodeTestMessage = TestMessage<WasmTestMessageExt>;
+type LockedGatewayClient =
+    Arc<AsyncMutex<GatewayClient<FakeClient<DirectSigningNyxdClient>, EphemeralStorage>>>;
+
+pub(crate) const DEFAULT_TEST_TIMEOUT: Duration = Duration::from_secs(10);
+pub(crate) const DEFAULT_TEST_PACKETS: u32 = 20;
+
+#[wasm_bindgen]
+pub struct NymNodeTester {
+    test_in_progress: Arc<AtomicBool>,
+
+    // we need to increment the nonce between tests to distinguish the packets
+    // but we can't make the tester mutable because of wasm...
+    // so we're using the atomics
+    current_test_nonce: AtomicU32,
+
+    // blame all those mutexes on being unable to have an async method with internal mutability...
+    tester: Arc<SyncMutex<NodeTester<OsRng>>>,
+    gateway_client: LockedGatewayClient,
+
+    // we have to put it behind the lock due to wasm limitations and borrowing...
+    // the mutex acquisition should be instant as there aren't going to be any threads attempting
+    // to get simultaneous access
+    processed_receiver: ReceivedReceiverWrapper,
+
+    // even though we don't use graceful shutdowns, other components rely on existence of this struct
+    // and if it's dropped, everything will start going offline
+    _task_manager: TaskManager,
+}
+
+#[wasm_bindgen]
+pub struct NymNodeTesterBuilder {
+    gateway_config: GatewayEndpointConfig,
+
+    base_topology: NymTopology,
+
+    /// KeyManager object containing smart pointers to all relevant keys used by the client.
+    key_manager: KeyManager,
+
+    // unimplemented
+    bandwidth_controller:
+        Option<BandwidthController<FakeClient<DirectSigningNyxdClient>, EphemeralStorage>>,
+}
+
+fn address(keys: &KeyManager, gateway_identity: NodeIdentity) -> Recipient {
+    Recipient::new(
+        *keys.identity_keypair().public_key(),
+        *keys.encryption_keypair().public_key(),
+        gateway_identity,
+    )
+}
+
+#[wasm_bindgen]
+impl NymNodeTesterBuilder {
+    #[wasm_bindgen(constructor)]
+    pub fn new(
+        gateway_config: GatewayEndpointConfig,
+        base_topology: WasmNymTopology,
+    ) -> NymNodeTesterBuilder {
+        NymNodeTesterBuilder {
+            gateway_config,
+            base_topology: base_topology.into(),
+            key_manager: setup_new_key_manager(),
+            bandwidth_controller: None,
+        }
+    }
+
+    async fn _new_with_api(
+        gateway_config: GatewayEndpointConfig,
+        api_url: String,
+    ) -> Result<Self, WasmClientError> {
+        let topology = current_network_topology_async(api_url).await?;
+        Ok(NymNodeTesterBuilder::new(gateway_config, topology))
+    }
+
+    pub fn new_with_api(gateway_config: GatewayEndpointConfig, api_url: String) -> Promise {
+        future_to_promise(async move {
+            Self::_new_with_api(gateway_config, api_url)
+                .await
+                .into_promise_result()
+        })
+    }
+
+    async fn _setup_client(mut self) -> Result<NymNodeTester, WasmClientError> {
+        let rng = OsRng;
+        let task_manager = TaskManager::default();
+
+        let gateway_identity =
+            identity::PublicKey::from_base58_string(self.gateway_config.gateway_id)
+                .map_err(|source| WasmClientError::InvalidGatewayIdentity { source })?;
+
+        // we **REALLY** need persistence...
+        let shared_key = if self.key_manager.is_gateway_key_set() {
+            Some(self.key_manager.gateway_shared_key())
+        } else {
+            console_warn!("Gateway key not set - will derive a fresh one.");
+            None
+        };
+
+        let (mixnet_message_sender, mixnet_message_receiver) = mpsc::unbounded();
+        let (ack_sender, ack_receiver) = mpsc::unbounded();
+
+        let mut gateway_client = GatewayClient::new(
+            self.gateway_config.gateway_listener,
+            self.key_manager.identity_keypair(),
+            gateway_identity,
+            shared_key,
+            mixnet_message_sender,
+            ack_sender,
+            Duration::from_secs(10),
+            self.bandwidth_controller.take(),
+            task_manager.subscribe(),
+        );
+
+        gateway_client.set_disabled_credentials_mode(true);
+        let shared_keys = gateway_client.authenticate_and_start().await?;
+
+        // currently pointless but might as well do it for the future ¯\_(ツ)_/¯
+        self.key_manager.insert_gateway_shared_key(shared_keys);
+
+        // TODO: make those values configurable later
+        let tester = NodeTester::new(
+            rng,
+            self.base_topology,
+            address(&self.key_manager, gateway_identity),
+            PacketSize::default(),
+            Duration::from_millis(5),
+            Duration::from_millis(5),
+            self.key_manager.ack_key(),
+        );
+
+        let (processed_sender, processed_receiver) = mpsc::unbounded();
+
+        let mut receiver = SimpleMessageReceiver::new_sphinx_receiver(
+            self.key_manager.encryption_keypair(),
+            self.key_manager.ack_key(),
+            mixnet_message_receiver,
+            ack_receiver,
+            processed_sender,
+            task_manager.subscribe(),
+        );
+
+        nym_task::spawn(async move { receiver.run().await });
+
+        Ok(NymNodeTester {
+            test_in_progress: Arc::new(AtomicBool::new(false)),
+            current_test_nonce: Default::default(),
+            tester: Arc::new(SyncMutex::new(tester)),
+            gateway_client: Arc::new(AsyncMutex::new(gateway_client)),
+            processed_receiver: ReceivedReceiverWrapper::new(processed_receiver),
+            _task_manager: task_manager,
+        })
+    }
+
+    pub fn setup_client(self) -> Promise {
+        future_to_promise(async move { self._setup_client().await.into_promise_result() })
+    }
+}
+
+async fn test_mixnode(
+    test_packets: Vec<PreparedFragment>,
+    gateway_client: LockedGatewayClient,
+    processed_receiver: ReceivedReceiverWrapper,
+    _test_marker: TestMarker,
+    timeout: Duration,
+) -> Result<NodeTestResult, WasmClientError> {
+    let num_test_packets = test_packets.len() as u32;
+
+    let expected_ack_ids = test_packets
+        .iter()
+        .map(|p| p.fragment_identifier)
+        .collect::<HashSet<_>>();
+
+    let mix_packets = test_packets.into_iter().map(|p| p.mix_packet).collect();
+
+    // start by clearing any messages that might have been received between tests
+    processed_receiver.clear_received_channel().await;
+
+    // locking the gateway client so that we could get mutable access to data without having to declare
+    // self mutable
+    let mut gateway_permit = gateway_client.lock().await;
+    gateway_permit.batch_send_mix_packets(mix_packets).await?;
+
+    let receiver_permit = processed_receiver.lock().await;
+    let result =
+        EphemeralTestReceiver::new(num_test_packets, expected_ack_ids, receiver_permit, timeout)
+            .perform_test()
+            .await;
+
+    Ok(result)
+}
+
+#[wasm_bindgen]
+impl NymNodeTester {
+    #[wasm_bindgen(constructor)]
+    #[allow(clippy::new_ret_no_self)]
+    pub fn new(gateway_config: GatewayEndpointConfig, topology: WasmNymTopology) -> Promise {
+        console_log!("constructing node tester!");
+        NymNodeTesterBuilder::new(gateway_config, topology).setup_client()
+    }
+
+    async fn _new_with_api(
+        gateway_config: GatewayEndpointConfig,
+        api_url: String,
+    ) -> Result<Self, WasmClientError> {
+        NymNodeTesterBuilder::_new_with_api(gateway_config, api_url)
+            .await?
+            ._setup_client()
+            .await
+    }
+
+    pub fn new_with_api(gateway_config: GatewayEndpointConfig, api_url: String) -> Promise {
+        future_to_promise(async move {
+            Self::_new_with_api(gateway_config, api_url)
+                .await
+                .into_promise_result()
+        })
+    }
+
+    fn prepare_test_packets(
+        &self,
+        mixnode_identity: String,
+        test_nonce: u32,
+        num_test_packets: u32,
+    ) -> Result<Vec<PreparedFragment>, WasmClientError> {
+        let test_ext = WasmTestMessageExt::new(test_nonce);
+        let mut tester_permit = self.tester.lock().expect("mutex got poisoned");
+        tester_permit
+            .existing_identity_mixnode_test_packets(mixnode_identity, test_ext, num_test_packets)
+            .map_err(Into::into)
+    }
+
+    pub fn test_node(
+        &self,
+        mixnode_identity: String,
+        timeout_millis: Option<u64>,
+        num_test_packets: Option<u32>,
+    ) -> Promise {
+        // establish test parameters
+        let timeout = timeout_millis
+            .map(Duration::from_millis)
+            .unwrap_or(DEFAULT_TEST_TIMEOUT);
+        let num_test_packets = num_test_packets.unwrap_or(DEFAULT_TEST_PACKETS);
+
+        // mark start of the test
+        if self.test_in_progress.swap(true, Ordering::SeqCst) {
+            return WasmClientError::TestInProgress.into_rejected_promise();
+        }
+
+        // prepare test packets
+        // (I simultaneously feel both disgusted and amazed by this workaround)
+        let test_nonce = self.current_test_nonce.fetch_add(1, Ordering::Relaxed);
+        let test_packets = check_promise_result!(self.prepare_test_packets(
+            mixnode_identity,
+            test_nonce,
+            num_test_packets
+        ));
+
+        let processed_receiver_clone = self.processed_receiver.clone();
+        let gateway_client_clone = Arc::clone(&self.gateway_client);
+        let tester_marker = TestMarker::new(Arc::clone(&self.test_in_progress));
+
+        // start doing async things (send packets and watch for anything coming back)
+        future_to_promise(async move {
+            test_mixnode(
+                test_packets,
+                gateway_client_clone,
+                processed_receiver_clone,
+                tester_marker,
+                timeout,
+            )
+            .await
+            .into_promise_result()
+        })
+    }
+}
@@ -0,0 +1,262 @@
+// Copyright 2023 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use nym_client_core::config::GatewayEndpointConfig;
+use nym_crypto::asymmetric::{encryption, identity};
+use nym_topology::gateway::GatewayConversionError;
+use nym_topology::mix::{Layer, MixnodeConversionError};
+use nym_topology::{gateway, mix, MixLayer, NymTopology};
+use nym_validator_client::client::MixId;
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeMap;
+use thiserror::Error;
+use wasm_bindgen::prelude::wasm_bindgen;
+use wasm_bindgen::JsValue;
+use wasm_utils::{console_log, simple_js_error};
+
+#[derive(Debug, Error)]
+pub enum WasmTopologyError {
+    #[error("got invalid mix layer {value}. Expected 1, 2 or 3.")]
+    InvalidMixLayer { value: u8 },
+
+    #[error(transparent)]
+    GatewayConversion(#[from] GatewayConversionError),
+
+    #[error(transparent)]
+    MixnodeConversion(#[from] MixnodeConversionError),
+
+    #[error("The provided mixnode map was malformed: {source}")]
+    MalformedMixnodeMap { source: serde_wasm_bindgen::Error },
+
+    #[error("The provided gateway list was malformed: {source}")]
+    MalformedGatewayList { source: serde_wasm_bindgen::Error },
+}
+
+impl From<WasmTopologyError> for JsValue {
+    fn from(value: WasmTopologyError) -> Self {
+        simple_js_error(value.to_string())
+    }
+}
+
+#[wasm_bindgen]
+#[derive(Debug)]
+pub struct WasmNymTopology {
+    inner: NymTopology,
+}
+
+#[wasm_bindgen]
+impl WasmNymTopology {
+    #[wasm_bindgen(constructor)]
+    pub fn new(
+        // expected: BTreeMap<MixLayer, Vec<WasmMixNode>>,
+        // HashMap<MixLayer, Vec<WasmMixNode>> will also work because it has the same json representation
+        mixnodes: JsValue,
+        // expected: Vec<WasmGateway>
+        gateways: JsValue,
+    ) -> Result<WasmNymTopology, WasmTopologyError> {
+        let mixnodes: BTreeMap<MixLayer, Vec<WasmMixNode>> =
+            serde_wasm_bindgen::from_value(mixnodes)
+                .map_err(|source| WasmTopologyError::MalformedMixnodeMap { source })?;
+
+        let gateways: Vec<WasmGateway> = serde_wasm_bindgen::from_value(gateways)
+            .map_err(|source| WasmTopologyError::MalformedGatewayList { source })?;
+
+        let mut converted_mixes = BTreeMap::new();
+
+        for (layer, nodes) in mixnodes {
+            let layer_nodes = nodes
+                .into_iter()
+                .map(TryInto::try_into)
+                .collect::<Result<_, _>>()?;
+
+            converted_mixes.insert(layer, layer_nodes);
+        }
+
+        let gateways = gateways
+            .into_iter()
+            .map(TryInto::try_into)
+            .collect::<Result<_, _>>()?;
+
+        Ok(WasmNymTopology {
+            inner: NymTopology::new(converted_mixes, gateways),
+        })
+    }
+
+    pub(crate) fn ensure_contains(&self, gateway_config: &GatewayEndpointConfig) -> bool {
+        self.inner
+            .gateways()
+            .iter()
+            .any(|g| g.identity_key.to_base58_string() == gateway_config.gateway_id)
+    }
+
+    pub fn print(&self) {
+        if !self.inner.mixes().is_empty() {
+            console_log!("mixnodes:");
+            for (layer, nodes) in self.inner.mixes() {
+                console_log!("\tlayer {layer}:");
+                for node in nodes {
+                    console_log!("\t\t{} - {}", node.mix_id, node.identity_key)
+                }
+            }
+        } else {
+            console_log!("NO MIXNODES")
+        }
+
+        if !self.inner.gateways().is_empty() {
+            console_log!("gateways:");
+            for gateway in self.inner.gateways() {
+                console_log!("\t{}", gateway.identity_key)
+            }
+        } else {
+            console_log!("NO GATEWAYS")
+        }
+    }
+}
+
+impl From<WasmNymTopology> for NymTopology {
+    fn from(value: WasmNymTopology) -> Self {
+        value.inner
+    }
+}
+
+impl From<NymTopology> for WasmNymTopology {
+    fn from(value: NymTopology) -> Self {
+        WasmNymTopology { inner: value }
+    }
+}
+
+#[wasm_bindgen]
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct WasmMixNode {
+    pub mix_id: MixId,
+    #[wasm_bindgen(getter_with_clone)]
+    pub owner: String,
+    #[wasm_bindgen(getter_with_clone)]
+    pub host: String,
+    pub mix_port: u16,
+    #[wasm_bindgen(getter_with_clone)]
+    pub identity_key: String,
+    #[wasm_bindgen(getter_with_clone)]
+    pub sphinx_key: String,
+    pub layer: MixLayer,
+    #[wasm_bindgen(getter_with_clone)]
+    pub version: String,
+}
+
+#[wasm_bindgen]
+impl WasmMixNode {
+    #[wasm_bindgen(constructor)]
+    #[allow(clippy::too_many_arguments)]
+    pub fn new(
+        mix_id: MixId,
+        owner: String,
+        host: String,
+        mix_port: u16,
+        identity_key: String,
+        sphinx_key: String,
+        layer: MixLayer,
+        version: String,
+    ) -> Self {
+        Self {
+            mix_id,
+            owner,
+            host,
+            mix_port,
+            identity_key,
+            sphinx_key,
+            layer,
+            version,
+        }
+    }
+}
+
+impl TryFrom<WasmMixNode> for mix::Node {
+    type Error = WasmTopologyError;
+
+    fn try_from(value: WasmMixNode) -> Result<Self, Self::Error> {
+        let host = mix::Node::parse_host(&value.host)?;
+
+        // try to completely resolve the host in the mix situation to avoid doing it every
+        // single time we want to construct a path
+        let mix_host = mix::Node::extract_mix_host(&host, value.mix_port)?;
+
+        Ok(mix::Node {
+            mix_id: value.mix_id,
+            owner: value.owner,
+            host,
+            mix_host,
+            identity_key: identity::PublicKey::from_base58_string(&value.identity_key)
+                .map_err(MixnodeConversionError::from)?,
+            sphinx_key: encryption::PublicKey::from_base58_string(&value.sphinx_key)
+                .map_err(MixnodeConversionError::from)?,
+            layer: Layer::try_from(value.layer)
+                .map_err(|_| WasmTopologyError::InvalidMixLayer { value: value.layer })?,
+            version: value.version,
+        })
+    }
+}
+
+#[wasm_bindgen]
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct WasmGateway {
+    #[wasm_bindgen(getter_with_clone)]
+    pub owner: String,
+    #[wasm_bindgen(getter_with_clone)]
+    pub host: String,
+    pub mix_port: u16,
+    pub clients_port: u16,
+    #[wasm_bindgen(getter_with_clone)]
+    pub identity_key: String,
+    #[wasm_bindgen(getter_with_clone)]
+    pub sphinx_key: String,
+    #[wasm_bindgen(getter_with_clone)]
+    pub version: String,
+}
+
+#[wasm_bindgen]
+impl WasmGateway {
+    #[wasm_bindgen(constructor)]
+    pub fn new(
+        owner: String,
+        host: String,
+        mix_port: u16,
+        clients_port: u16,
+        identity_key: String,
+        sphinx_key: String,
+        version: String,
+    ) -> Self {
+        Self {
+            owner,
+            host,
+            mix_port,
+            clients_port,
+            identity_key,
+            sphinx_key,
+            version,
+        }
+    }
+}
+
+impl TryFrom<WasmGateway> for gateway::Node {
+    type Error = WasmTopologyError;
+
+    fn try_from(value: WasmGateway) -> Result<Self, Self::Error> {
+        let host = gateway::Node::parse_host(&value.host)?;
+
+        // try to completely resolve the host in the mix situation to avoid doing it every
+        // single time we want to construct a path
+        let mix_host = gateway::Node::extract_mix_host(&host, value.mix_port)?;
+
+        Ok(gateway::Node {
+            owner: value.owner,
+            host,
+            mix_host,
+            clients_port: value.clients_port,
+            identity_key: identity::PublicKey::from_base58_string(&value.identity_key)
+                .map_err(GatewayConversionError::from)?,
+            sphinx_key: encryption::PublicKey::from_base58_string(&value.sphinx_key)
+                .map_err(GatewayConversionError::from)?,
+            version: value.version,
+        })
+    }
+}
@@ -22,7 +22,7 @@ use crate::client::topology_control::{
 };
 use crate::config::{Config, DebugConfig, GatewayEndpointConfig};
 use crate::error::ClientCoreError;
-use crate::spawn_future;
+use crate::{config, spawn_future};
 use futures::channel::mpsc;
 use log::{debug, info};
 use nym_bandwidth_controller::BandwidthController;
@@ -39,7 +39,6 @@ use nym_task::connections::{ConnectionCommandReceiver, ConnectionCommandSender,
 use nym_task::{TaskClient, TaskManager};
 use nym_topology::provider_trait::TopologyProvider;
 use std::sync::Arc;
-use std::time::Duration;
 use tap::TapFallible;
 use url::Url;

@@ -371,11 +370,12 @@ where
    // the current global view of topology
    async fn start_topology_refresher(
        topology_provider: Box<dyn TopologyProvider>,
-        refresh_rate: Duration,
+        topology_config: config::Topology,
        topology_accessor: TopologyAccessor,
-        shutdown: TaskClient,
+        mut shutdown: TaskClient,
    ) -> Result<(), ClientCoreError> {
-        let topology_refresher_config = TopologyRefresherConfig::new(refresh_rate);
+        let topology_refresher_config =
+            TopologyRefresherConfig::new(topology_config.topology_refresh_rate);

        let mut topology_refresher = TopologyRefresher::new(
            topology_refresher_config,
@@ -395,12 +395,21 @@ where
            return Err(ClientCoreError::InsufficientNetworkTopology(err));
        }

-        info!("Starting topology refresher...");
-        topology_refresher.start_with_shutdown(shutdown);
+        if topology_config.disable_refreshing {
+            // if we're not spawning the refresher, don't cause shutdown immediately
+            info!("The topology refesher is not going to be started");
+            shutdown.mark_as_success();
+        } else {
+            // don't spawn the refresher if we don't want to be refreshing the topology.
+            // only use the initial values obtained
+            info!("Starting topology refresher...");
+            topology_refresher.start_with_shutdown(shutdown);
+        }
+
        Ok(())
    }

-    // controller for sending sphinx packets to mixnet (either real traffic or cover traffic)
+    // controller for sending packets to mixnet (either real traffic or cover traffic)
    // TODO: if we want to send control messages to gateway_client, this CAN'T take the ownership
    // over it. Perhaps GatewayClient needs to be thread-shareable or have some channel for
    // requests?
@@ -500,7 +509,7 @@ where
        );
        Self::start_topology_refresher(
            topology_provider,
-            self.debug_config.topology.topology_refresh_rate,
+            self.debug_config.topology,
            shared_topology_accessor.clone(),
            task_manager.subscribe(),
        )
@@ -515,11 +524,11 @@ where
            task_manager.subscribe(),
        );

-        // The sphinx_message_sender is the transmitter for any component generating sphinx packets
+        // The message_sender is the transmitter for any component generating sphinx packets
        // that are to be sent to the mixnet. They are used by cover traffic stream and real
        // traffic stream.
        // The MixTrafficController then sends the actual traffic
-        let sphinx_message_sender =
+        let message_sender =
            Self::start_mix_traffic_controller(gateway_client, task_manager.subscribe());

        // Channels that the websocket listener can use to signal downstream to the real traffic
@@ -541,7 +550,7 @@ where
            shared_topology_accessor.clone(),
            ack_receiver,
            input_receiver,
-            sphinx_message_sender.clone(),
+            message_sender.clone(),
            reply_storage,
            reply_controller_sender.clone(),
            reply_controller_receiver,
@@ -560,7 +569,7 @@ where
                self.key_manager.ack_key(),
                self_address,
                shared_topology_accessor.clone(),
-                sphinx_message_sender,
+                message_sender,
                task_manager.subscribe(),
            );
        }
@@ -45,7 +45,7 @@ where
    #[cfg(target_arch = "wasm32")]
    next_delay: Pin<Box<wasm_timer::Delay>>,

-    /// Channel used for sending prepared sphinx packets to `MixTrafficController` that sends them
+    /// Channel used for sending prepared nym packets to `MixTrafficController` that sends them
    /// out to the network without any further delays.
    mix_tx: BatchMixMessageSender,

@@ -1,5 +1,10 @@
+// Copyright 2020-2023 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
 use nym_sphinx::addressing::clients::Recipient;
 use nym_sphinx::anonymous_replies::requests::AnonymousSenderTag;
+use nym_sphinx::forwarding::packet::MixPacket;
+use nym_sphinx::params::PacketType;
 use nym_task::connections::TransmissionLane;

 pub type InputMessageSender = tokio::sync::mpsc::Sender<InputMessage>;
@@ -7,6 +12,14 @@ pub type InputMessageReceiver = tokio::sync::mpsc::Receiver<InputMessage>;

 #[derive(Debug)]
 pub enum InputMessage {
+    /// Fire an already prepared mix packets into the network.
+    /// No guarantees are made about it. For example no retransmssion
+    /// will be attempted if it gets dropped.
+    Premade {
+        msgs: Vec<MixPacket>,
+        lane: TransmissionLane,
+    },
+
    /// The simplest message variant where no additional information is attached.
    /// You're simply sending your `data` to specified `recipient` without any tagging.
    ///
@@ -41,14 +54,49 @@ pub enum InputMessage {
        data: Vec<u8>,
        lane: TransmissionLane,
    },
+
+    MessageWrapper {
+        message: Box<InputMessage>,
+        packet_type: PacketType,
+    },
 }

 impl InputMessage {
-    pub fn new_regular(recipient: Recipient, data: Vec<u8>, lane: TransmissionLane) -> Self {
-        InputMessage::Regular {
+    pub fn new_premade(
+        msgs: Vec<MixPacket>,
+        lane: TransmissionLane,
+        packet_type: PacketType,
+    ) -> Self {
+        let message = InputMessage::Premade { msgs, lane };
+        if packet_type == PacketType::Mix {
+            message
+        } else {
+            InputMessage::new_wrapper(message, packet_type)
+        }
+    }
+
+    pub fn new_wrapper(message: InputMessage, packet_type: PacketType) -> Self {
+        InputMessage::MessageWrapper {
+            message: Box::new(message),
+            packet_type,
+        }
+    }
+
+    pub fn new_regular(
+        recipient: Recipient,
+        data: Vec<u8>,
+        lane: TransmissionLane,
+        packet_type: Option<PacketType>,
+    ) -> Self {
+        let message = InputMessage::Regular {
            recipient,
            data,
            lane,
+        };
+        if let Some(packet_type) = packet_type {
+            InputMessage::new_wrapper(message, packet_type)
+        } else {
+            message
        }
    }

@@ -57,12 +105,18 @@ impl InputMessage {
        data: Vec<u8>,
        reply_surbs: u32,
        lane: TransmissionLane,
+        packet_type: Option<PacketType>,
    ) -> Self {
-        InputMessage::Anonymous {
+        let message = InputMessage::Anonymous {
            recipient,
            data,
            reply_surbs,
            lane,
+        };
+        if let Some(packet_type) = packet_type {
+            InputMessage::new_wrapper(message, packet_type)
+        } else {
+            message
        }
    }

@@ -70,11 +124,17 @@ impl InputMessage {
        recipient_tag: AnonymousSenderTag,
        data: Vec<u8>,
        lane: TransmissionLane,
+        packet_type: Option<PacketType>,
    ) -> Self {
-        InputMessage::Reply {
+        let message = InputMessage::Reply {
            recipient_tag,
            data,
            lane,
+        };
+        if let Some(packet_type) = packet_type {
+            InputMessage::new_wrapper(message, packet_type)
+        } else {
+            message
        }
    }

@@ -82,7 +142,9 @@ impl InputMessage {
        match self {
            InputMessage::Regular { lane, .. }
            | InputMessage::Anonymous { lane, .. }
-            | InputMessage::Reply { lane, .. } => lane,
+            | InputMessage::Reply { lane, .. }
+            | InputMessage::Premade { lane, .. } => lane,
+            InputMessage::MessageWrapper { message, .. } => message.lane(),
        }
    }
 }
@@ -39,15 +39,15 @@ where
    pub fn new(
        gateway_client: GatewayClient<C, St>,
    ) -> (MixTrafficController<C, St>, BatchMixMessageSender) {
-        let (sphinx_message_sender, sphinx_message_receiver) =
+        let (message_sender, message_receiver) =
            tokio::sync::mpsc::channel(MIX_MESSAGE_RECEIVER_BUFFER_SIZE);
        (
            MixTrafficController {
                gateway_client,
-                mix_rx: sphinx_message_receiver,
+                mix_rx: message_receiver,
                consecutive_gateway_failure_count: 0,
            },
-            sphinx_message_sender,
+            message_sender,
        )
    }

@@ -3,10 +3,13 @@

 use crate::client::inbound_messages::{InputMessage, InputMessageReceiver};
 use crate::client::real_messages_control::message_handler::MessageHandler;
+use crate::client::real_messages_control::real_traffic_stream::RealMessage;
 use crate::client::replies::reply_controller::ReplyControllerSender;
 use log::*;
 use nym_sphinx::addressing::clients::Recipient;
 use nym_sphinx::anonymous_replies::requests::AnonymousSenderTag;
+use nym_sphinx::forwarding::packet::MixPacket;
+use nym_sphinx::params::PacketType;
 use nym_task::connections::TransmissionLane;
 use rand::{CryptoRng, Rng};

@@ -41,6 +44,18 @@ where
        }
    }

+    async fn handle_premade_packets(&mut self, packets: Vec<MixPacket>, lane: TransmissionLane) {
+        self.message_handler
+            .send_premade_mix_packets(
+                packets
+                    .into_iter()
+                    .map(|p| RealMessage::new(p, None))
+                    .collect(),
+                lane,
+            )
+            .await
+    }
+
    async fn handle_reply(
        &mut self,
        recipient_tag: AnonymousSenderTag,
@@ -57,10 +72,11 @@ where
        recipient: Recipient,
        content: Vec<u8>,
        lane: TransmissionLane,
+        packet_type: PacketType,
    ) {
        if let Err(err) = self
            .message_handler
-            .try_send_plain_message(recipient, content, lane)
+            .try_send_plain_message(recipient, content, lane, packet_type)
            .await
        {
            warn!("failed to send a plain message - {err}")
@@ -73,10 +89,11 @@ where
        content: Vec<u8>,
        reply_surbs: u32,
        lane: TransmissionLane,
+        packet_type: PacketType,
    ) {
        if let Err(err) = self
            .message_handler
-            .try_send_message_with_reply_surbs(recipient, content, reply_surbs, lane)
+            .try_send_message_with_reply_surbs(recipient, content, reply_surbs, lane, packet_type)
            .await
        {
            warn!("failed to send a repliable message - {err}")
@@ -89,14 +106,17 @@ where
                recipient,
                data,
                lane,
-            } => self.handle_plain_message(recipient, data, lane).await,
+            } => {
+                self.handle_plain_message(recipient, data, lane, PacketType::Mix)
+                    .await
+            }
            InputMessage::Anonymous {
                recipient,
                data,
                reply_surbs,
                lane,
            } => {
-                self.handle_repliable_message(recipient, data, reply_surbs, lane)
+                self.handle_repliable_message(recipient, data, reply_surbs, lane, PacketType::Mix)
                    .await
            }
            InputMessage::Reply {
@@ -106,6 +126,41 @@ where
            } => {
                self.handle_reply(recipient_tag, data, lane).await;
            }
+            InputMessage::Premade { msgs, lane } => self.handle_premade_packets(msgs, lane).await,
+            InputMessage::MessageWrapper {
+                message,
+                packet_type,
+            } => match *message {
+                InputMessage::Regular {
+                    recipient,
+                    data,
+                    lane,
+                } => {
+                    self.handle_plain_message(recipient, data, lane, packet_type)
+                        .await
+                }
+                InputMessage::Anonymous {
+                    recipient,
+                    data,
+                    reply_surbs,
+                    lane,
+                } => {
+                    self.handle_repliable_message(recipient, data, reply_surbs, lane, packet_type)
+                        .await
+                }
+                InputMessage::Reply {
+                    recipient_tag,
+                    data,
+                    lane,
+                } => {
+                    self.handle_reply(recipient_tag, data, lane).await;
+                }
+                InputMessage::Premade { msgs, lane } => {
+                    self.handle_premade_packets(msgs, lane).await
+                }
+                // MessageWrappers can't be nested
+                InputMessage::MessageWrapper { .. } => unimplemented!(),
+            },
        };
    }

@@ -11,9 +11,9 @@ use crate::client::real_messages_control::real_traffic_stream::RealMessage;
 use crate::client::replies::reply_controller::ReplyControllerSender;
 use futures::StreamExt;
 use log::*;
-use nym_sphinx::addressing::clients::Recipient;
 use nym_sphinx::chunking::fragment::Fragment;
 use nym_sphinx::preparer::PreparedFragment;
+use nym_sphinx::{addressing::clients::Recipient, params::PacketType};
 use nym_task::connections::TransmissionLane;
 use rand::{CryptoRng, Rng};
 use std::sync::{Arc, Weak};
@@ -51,8 +51,10 @@ where
    ) -> Result<PreparedFragment, PreparationError> {
        debug!("retransmitting normal packet...");

+        // TODO: Figure out retransmission packet type signaling
+
        self.message_handler
-            .try_prepare_single_chunk_for_sending(packet_recipient, chunk_data)
+            .try_prepare_single_chunk_for_sending(packet_recipient, chunk_data, PacketType::Mix)
            .await
    }

@@ -131,7 +133,10 @@ where
        // send to `OutQueueControl` to eventually send to the mix network
        self.message_handler
            .forward_messages(
-                vec![RealMessage::new(prepared_fragment.mix_packet, frag_id)],
+                vec![RealMessage::new(
+                    prepared_fragment.mix_packet,
+                    Some(frag_id),
+                )],
                TransmissionLane::Retransmission,
            )
            .await
@@ -15,7 +15,7 @@ use nym_sphinx::anonymous_replies::requests::{AnonymousSenderTag, RepliableMessa
 use nym_sphinx::anonymous_replies::{ReplySurb, SurbEncryptionKey};
 use nym_sphinx::chunking::fragment::{Fragment, FragmentIdentifier};
 use nym_sphinx::message::NymMessage;
-use nym_sphinx::params::{PacketSize, DEFAULT_NUM_MIX_HOPS};
+use nym_sphinx::params::{PacketSize, PacketType, DEFAULT_NUM_MIX_HOPS};
 use nym_sphinx::preparer::{MessagePreparer, PreparedFragment};
 use nym_sphinx::Delay;
 use nym_task::connections::TransmissionLane;
@@ -291,8 +291,10 @@ where
            .try_prepare_single_reply_chunk_for_sending(reply_surb, chunk_clone)
            .await?;

-        let real_messages =
-            RealMessage::new(prepared_fragment.mix_packet, chunk.fragment_identifier());
+        let real_messages = RealMessage::new(
+            prepared_fragment.mix_packet,
+            Some(chunk.fragment_identifier()),
+        );
        let delay = prepared_fragment.total_delay;
        let pending_ack =
            PendingAcknowledgement::new_anonymous(chunk, delay, target, is_extra_surb_request);
@@ -384,7 +386,8 @@ where
            let lane = raw.0;
            let fragment = raw.1;

-            let real_message = RealMessage::new(prepared.mix_packet, prepared.fragment_identifier);
+            let real_message =
+                RealMessage::new(prepared.mix_packet, Some(prepared.fragment_identifier));
            let delay = prepared.total_delay;
            let pending_ack = PendingAcknowledgement::new_anonymous(fragment, delay, target, false);

@@ -401,14 +404,23 @@ where
        Ok(())
    }

+    pub(crate) async fn send_premade_mix_packets(
+        &mut self,
+        msgs: Vec<RealMessage>,
+        lane: TransmissionLane,
+    ) {
+        self.forward_messages(msgs, lane).await;
+    }
+
    pub(crate) async fn try_send_plain_message(
        &mut self,
        recipient: Recipient,
        message: Vec<u8>,
        lane: TransmissionLane,
+        packet_type: PacketType,
    ) -> Result<(), PreparationError> {
        let message = NymMessage::new_plain(message);
-        self.try_split_and_send_non_reply_message(message, recipient, lane)
+        self.try_split_and_send_non_reply_message(message, recipient, lane, packet_type)
            .await
    }

@@ -417,6 +429,7 @@ where
        message: NymMessage,
        recipient: Recipient,
        lane: TransmissionLane,
+        packet_type: PacketType,
    ) -> Result<(), PreparationError> {
        // TODO: I really dislike existence of this assertion, it implies code has to be re-organised
        debug_assert!(!matches!(message, NymMessage::Reply(_)));
@@ -442,10 +455,13 @@ where
                topology,
                &self.config.ack_key,
                &recipient,
+                &packet_type,
            )?;

-            let real_message =
-                RealMessage::new(prepared_fragment.mix_packet, fragment.fragment_identifier());
+            let real_message = RealMessage::new(
+                prepared_fragment.mix_packet,
+                Some(fragment.fragment_identifier()),
+            );
            let delay = prepared_fragment.total_delay;
            let pending_ack = PendingAcknowledgement::new_known(fragment, delay, recipient);

@@ -463,6 +479,7 @@ where
        &mut self,
        recipient: Recipient,
        amount: u32,
+        packet_type: PacketType,
    ) -> Result<(), PreparationError> {
        let sender_tag = self.get_or_create_sender_tag(&recipient);
        let (reply_surbs, reply_keys) =
@@ -477,6 +494,7 @@ where
            message,
            recipient,
            TransmissionLane::AdditionalReplySurbs,
+            packet_type,
        )
        .await?;

@@ -492,6 +510,7 @@ where
        message: Vec<u8>,
        num_reply_surbs: u32,
        lane: TransmissionLane,
+        packet_type: PacketType,
    ) -> Result<(), SurbWrappedPreparationError> {
        let sender_tag = self.get_or_create_sender_tag(&recipient);
        let (reply_surbs, reply_keys) = self
@@ -501,7 +520,7 @@ where
        let message =
            NymMessage::new_repliable(RepliableMessage::new_data(message, sender_tag, reply_surbs));

-        self.try_split_and_send_non_reply_message(message, recipient, lane)
+        self.try_split_and_send_non_reply_message(message, recipient, lane, packet_type)
            .await?;

        log::trace!("storing {} reply keys", reply_keys.len());
@@ -514,13 +533,20 @@ where
        &mut self,
        recipient: Recipient,
        chunk: Fragment,
+        packet_type: PacketType,
    ) -> Result<PreparedFragment, PreparationError> {
        let topology_permit = self.topology_access.get_read_permit().await;
        let topology = self.get_topology(&topology_permit)?;

        let prepared_fragment = self
            .message_preparer
-            .prepare_chunk_for_sending(chunk, topology, &self.config.ack_key, &recipient)
+            .prepare_chunk_for_sending(
+                chunk,
+                topology,
+                &self.config.ack_key,
+                &recipient,
+                &packet_type,
+            )
            .unwrap();

        Ok(prepared_fragment)
@@ -556,6 +582,7 @@ where
                        topology,
                        &self.config.ack_key,
                        reply_surb,
+                        PacketType::Mix,
                    )
                    .unwrap()
            })
@@ -575,7 +602,13 @@ where

        let prepared_fragment = self
            .message_preparer
-            .prepare_reply_chunk_for_sending(chunk, topology, &self.config.ack_key, reply_surb)
+            .prepare_reply_chunk_for_sending(
+                chunk,
+                topology,
+                &self.config.ack_key,
+                reply_surb,
+                PacketType::Mix,
+            )
            .unwrap();

        Ok(prepared_fragment)
@@ -92,7 +92,7 @@ where
    // messages.
    sending_delay_controller: SendingDelayController,

-    /// Channel used for sending prepared sphinx packets to `MixTrafficController` that sends them
+    /// Channel used for sending prepared packets to `MixTrafficController` that sends them
    /// out to the network without any further delays.
    mix_tx: BatchMixMessageSender,

@@ -121,7 +121,7 @@ where
 #[derive(Debug)]
 pub(crate) struct RealMessage {
    mix_packet: MixPacket,
-    fragment_id: FragmentIdentifier,
+    fragment_id: Option<FragmentIdentifier>,
    // TODO: add info about it being constructed with reply-surb
 }

@@ -129,17 +129,17 @@ impl From<PreparedFragment> for RealMessage {
    fn from(fragment: PreparedFragment) -> Self {
        RealMessage {
            mix_packet: fragment.mix_packet,
-            fragment_id: fragment.fragment_identifier,
+            fragment_id: Some(fragment.fragment_identifier),
        }
    }
 }

 impl RealMessage {
    pub(crate) fn packet_size(&self) -> usize {
-        self.mix_packet.sphinx_packet().len()
+        self.mix_packet.packet().len()
    }

-    pub(crate) fn new(mix_packet: MixPacket, fragment_id: FragmentIdentifier) -> Self {
+    pub(crate) fn new(mix_packet: MixPacket, fragment_id: Option<FragmentIdentifier>) -> Self {
        RealMessage {
            mix_packet,
            fragment_id,
@@ -255,7 +255,7 @@ where
                )
            }
            StreamMessage::Real(real_message) => {
-                (real_message.mix_packet, Some(real_message.fragment_id))
+                (real_message.mix_packet, real_message.fragment_id)
            }
        };

@@ -386,7 +386,7 @@ where

            // On every iteration we get new messages from upstream. Given that these come bunched
            // in `Vec`, this ensures that on average we will fetch messages faster than we can
-            // send, which is a condition for being able to multiplex sphinx packets from multiple
+            // send, which is a condition for being able to multiplex packets from multiple
            // data streams.
            match Pin::new(&mut self.real_receiver).poll_recv(cx) {
                // in the case our real message channel stream was closed, we should also indicate we are closed
@@ -512,7 +512,11 @@ where
            let to_send = min(remaining, 100);
            if let Err(err) = self
                .message_handler
-                .try_send_additional_reply_surbs(recipient, to_send)
+                .try_send_additional_reply_surbs(
+                    recipient,
+                    to_send,
+                    nym_sphinx::params::PacketType::Mix,
+                )
                .await
            {
                warn!("failed to send additional surbs to {recipient} - {err}");
@@ -28,7 +28,7 @@ impl SizedData for RealMessage {

 impl SizedData for Fragment {
    fn data_size(&self) -> usize {
-        // note that raw `Fragment` is smaller than sphinx packet payload
+        // note that raw `Fragment` is smaller than packet payload
        // as it doesn't include surb-ack or the [shared] key materials
        self.payload_size()
    }
@@ -3,7 +3,7 @@

 use nym_config::defaults::NymNetworkDetails;
 use nym_config::{NymConfig, OptionalSet, CRED_DB_FILE_NAME};
-use nym_sphinx::params::PacketSize;
+use nym_sphinx::params::{PacketSize, PacketType};
 use serde::{Deserialize, Serialize};
 use std::marker::PhantomData;
 use std::path::PathBuf;
@@ -217,6 +217,11 @@ impl<T> Config<T> {
        self
    }

+    pub fn with_packet_type(mut self, packet_type: PacketType) -> Self {
+        self.client.packet_type = Some(packet_type);
+        self
+    }
+
    pub fn set_high_default_traffic_volume(&mut self) {
        self.debug.traffic.average_packet_delay = Duration::from_millis(10);
        // basically don't really send cover messages
@@ -404,6 +409,10 @@ impl<T> Config<T> {
    pub fn get_maximum_reply_key_age(&self) -> Duration {
        self.debug.reply_surbs.maximum_reply_key_age
    }
+
+    pub fn get_packet_type(&self) -> PacketType {
+        self.client.packet_type.unwrap_or(PacketType::Mix)
+    }
 }

 impl<T: NymConfig> Default for Config<T> {
@@ -518,6 +527,8 @@ pub struct Client<T> {

    #[serde(skip)]
    pub super_struct: PhantomData<T>,
+
+    pub packet_type: Option<PacketType>,
 }

 impl<T: NymConfig> Default for Client<T> {
@@ -556,6 +567,7 @@ impl<T: NymConfig> Default for Client<T> {
            reply_surb_database_path: Default::default(),
            nym_root_directory: T::default_root_directory(),
            super_struct: Default::default(),
+            packet_type: Default::default(),
        }
    }
 }
@@ -743,6 +755,11 @@ pub struct Topology {
    /// did not reach its destination.
    #[serde(with = "humantime_serde")]
    pub topology_resolution_timeout: Duration,
+
+    /// Specifies whether the client should not refresh the network topology after obtaining
+    /// the first valid instance.
+    /// Supersedes `topology_refresh_rate_ms`.
+    pub disable_refreshing: bool,
 }

 impl Default for Topology {
@@ -750,6 +767,7 @@ impl Default for Topology {
        Topology {
            topology_refresh_rate: DEFAULT_TOPOLOGY_REFRESH_RATE,
            topology_resolution_timeout: DEFAULT_TOPOLOGY_RESOLUTION_TIMEOUT,
+            disable_refreshing: false,
        }
    }
 }
@@ -142,6 +142,7 @@ impl From<OldDebugConfigV1_1_13> for DebugConfig {
            topology: Topology {
                topology_refresh_rate: value.topology_refresh_rate,
                topology_resolution_timeout: value.topology_resolution_timeout,
+                disable_refreshing: false,
            },
            reply_surbs: ReplySurbs {
                minimum_reply_surb_storage_threshold: value.minimum_reply_surb_storage_threshold,
@@ -209,8 +210,8 @@ impl<T, U> From<OldConfigV1_1_13<T>> for Config<U> {
                database_path: value.client.database_path,
                reply_surb_database_path: value.client.reply_surb_database_path,
                nym_root_directory: value.client.nym_root_directory,
-
                super_struct: PhantomData,
+                packet_type: Some(nym_sphinx::params::PacketType::Mix),
            },
            logging: value.logging,
            debug: value.debug.into(),
@@ -605,7 +605,7 @@ where
    fn estimate_required_bandwidth(&self, packets: &[MixPacket]) -> i64 {
        packets
            .iter()
-            .map(|packet| packet.sphinx_packet().len())
+            .map(|packet| packet.packet().len())
            .sum::<usize>() as i64
    }

@@ -686,9 +686,9 @@ where
        if !self.authenticated {
            return Err(GatewayClientError::NotAuthenticated);
        }
-        if (mix_packet.sphinx_packet().len() as i64) > self.bandwidth_remaining {
+        if (mix_packet.packet().len() as i64) > self.bandwidth_remaining {
            return Err(GatewayClientError::NotEnoughBandwidth(
-                mix_packet.sphinx_packet().len() as i64,
+                mix_packet.packet().len() as i64,
                self.bandwidth_remaining,
            ));
        }
@@ -4,10 +4,11 @@
 use futures::channel::mpsc;
 use futures::StreamExt;
 use log::*;
-use nym_sphinx::framing::codec::SphinxCodec;
-use nym_sphinx::framing::packet::FramedSphinxPacket;
-use nym_sphinx::params::PacketMode;
-use nym_sphinx::{addressing::nodes::NymNodeRoutingAddress, SphinxPacket};
+use nym_sphinx::addressing::nodes::NymNodeRoutingAddress;
+use nym_sphinx::framing::codec::NymCodec;
+use nym_sphinx::framing::packet::FramedNymPacket;
+use nym_sphinx::params::PacketType;
+use nym_sphinx::NymPacket;
 use std::collections::HashMap;
 use std::io;
 use std::net::SocketAddr;
@@ -50,8 +51,8 @@ pub trait SendWithoutResponse {
    fn send_without_response(
        &mut self,
        address: NymNodeRoutingAddress,
-        packet: SphinxPacket,
-        packet_mode: PacketMode,
+        packet: NymPacket,
+        packet_type: PacketType,
    ) -> io::Result<()>;
 }

@@ -61,12 +62,12 @@ pub struct Client {
 }

 struct ConnectionSender {
-    channel: mpsc::Sender<FramedSphinxPacket>,
+    channel: mpsc::Sender<FramedNymPacket>,
    current_reconnection_attempt: Arc<AtomicU32>,
 }

 impl ConnectionSender {
-    fn new(channel: mpsc::Sender<FramedSphinxPacket>) -> Self {
+    fn new(channel: mpsc::Sender<FramedNymPacket>) -> Self {
        ConnectionSender {
            channel,
            current_reconnection_attempt: Arc::new(AtomicU32::new(0)),
@@ -84,7 +85,7 @@ impl Client {

    async fn manage_connection(
        address: SocketAddr,
-        receiver: mpsc::Receiver<FramedSphinxPacket>,
+        receiver: mpsc::Receiver<FramedNymPacket>,
        connection_timeout: Duration,
        current_reconnection: &AtomicU32,
    ) {
@@ -96,7 +97,7 @@ impl Client {
                    debug!("Managed to establish connection to {}", address);
                    // if we managed to connect, reset the reconnection count (whatever it might have been)
                    current_reconnection.store(0, Ordering::Release);
-                    Framed::new(stream, SphinxCodec)
+                    Framed::new(stream, NymCodec)
                }
                Err(err) => {
                    debug!(
@@ -148,11 +149,7 @@ impl Client {
        }
    }

-    fn make_connection(
-        &mut self,
-        address: NymNodeRoutingAddress,
-        pending_packet: FramedSphinxPacket,
-    ) {
+    fn make_connection(&mut self, address: NymNodeRoutingAddress, pending_packet: FramedNymPacket) {
        let (mut sender, receiver) = mpsc::channel(self.config.maximum_connection_buffer_size);

        // this CAN'T fail because we just created the channel which has a non-zero capacity
@@ -200,12 +197,12 @@ impl SendWithoutResponse for Client {
    fn send_without_response(
        &mut self,
        address: NymNodeRoutingAddress,
-        packet: SphinxPacket,
-        packet_mode: PacketMode,
+        packet: NymPacket,
+        packet_type: PacketType,
    ) -> io::Result<()> {
        trace!("Sending packet to {:?}", address);
        let framed_packet =
-            FramedSphinxPacket::new(packet, packet_mode, self.config.use_legacy_version);
+            FramedNymPacket::new(packet, packet_type, self.config.use_legacy_version);

        if let Some(sender) = self.conn_new.get_mut(&address) {
            if let Err(err) = sender.channel.try_send(framed_packet) {
@@ -59,14 +59,14 @@ impl PacketForwarder {
                     trace!("Going to forward packet to {:?}", mix_packet.next_hop());

                    let next_hop = mix_packet.next_hop();
-                    let packet_mode = mix_packet.packet_mode();
-                    let sphinx_packet = mix_packet.into_sphinx_packet();
+                    let packet_type = mix_packet.packet_type();
+                    let packet = mix_packet.into_packet();
                    // we don't care about responses, we just want to fire packets
                    // as quickly as possible

                    if let Err(err) =
                        self.mixnet_client
-                            .send_without_response(next_hop, sphinx_packet, packet_mode)
+                            .send_without_response(next_hop, packet, packet_type)
                    {
                        debug!("failed to forward the packet - {err}")
                    }
@@ -13,7 +13,8 @@ pub mod nyxd;
 pub mod signing;

 pub use crate::error::ValidatorClientError;
+pub use client::NymApiClient;
 pub use nym_api_requests::*;

 #[cfg(feature = "nyxd-client")]
-pub use client::{Client, CoconutApiClient, Config, NymApiClient};
+pub use client::{Client, CoconutApiClient, Config};
@@ -24,8 +24,9 @@ use nym_mixnet_contract_common::{
    MixOwnershipResponse, MixnodeDetailsResponse, NumberOfPendingEventsResponse,
    PagedAllDelegationsResponse, PagedDelegatorDelegationsResponse, PagedFamiliesResponse,
    PagedGatewayResponse, PagedMembersResponse, PagedMixNodeDelegationsResponse,
-    PagedMixnodeBondsResponse, PagedRewardedSetResponse, PendingEpochEventsResponse,
-    PendingIntervalEventsResponse, QueryMsg as MixnetQueryMsg,
+    PagedMixnodeBondsResponse, PagedRewardedSetResponse, PendingEpochEventResponse,
+    PendingEpochEventsResponse, PendingIntervalEventResponse, PendingIntervalEventsResponse,
+    QueryMsg as MixnetQueryMsg,
 };
 use serde::Deserialize;

@@ -174,6 +175,16 @@ pub trait MixnetQueryClient {
            .await
    }

+    async fn get_mixnode_details_by_identity(
+        &self,
+        mix_identity: IdentityKey,
+    ) -> Result<Option<MixNodeDetails>, NyxdError> {
+        self.query_mixnet_contract(MixnetQueryMsg::GetBondedMixnodeDetailsByIdentity {
+            mix_identity,
+        })
+        .await
+    }
+
    async fn get_mixnode_rewarding_details(
        &self,
        mix_id: MixId,
@@ -374,14 +385,20 @@ pub trait MixnetQueryClient {
            .await
    }

-    async fn get_mixnode_details_by_identity(
+    async fn get_pending_epoch_event(
        &self,
-        mix_identity: IdentityKey,
-    ) -> Result<Option<MixNodeDetails>, NyxdError> {
-        self.query_mixnet_contract(MixnetQueryMsg::GetBondedMixnodeDetailsByIdentity {
-            mix_identity,
-        })
-        .await
+        event_id: EpochEventId,
+    ) -> Result<PendingEpochEventResponse, NyxdError> {
+        self.query_mixnet_contract(MixnetQueryMsg::GetPendingEpochEvent { event_id })
+            .await
+    }
+
+    async fn get_pending_interval_event(
+        &self,
+        event_id: IntervalEventId,
+    ) -> Result<PendingIntervalEventResponse, NyxdError> {
+        self.query_mixnet_contract(MixnetQueryMsg::GetPendingIntervalEvent { event_id })
+            .await
    }

    async fn get_number_of_pending_events(
@@ -331,6 +331,38 @@ pub trait MixnetSigningClient {
        .await
    }

+    async fn decrease_pledge(
+        &self,
+        decrease_by: Coin,
+        fee: Option<Fee>,
+    ) -> Result<ExecuteResult, NyxdError> {
+        self.execute_mixnet_contract(
+            fee,
+            MixnetExecuteMsg::DecreasePledge {
+                decrease_by: decrease_by.into(),
+            },
+            vec![],
+        )
+        .await
+    }
+
+    async fn decrease_pledge_on_behalf(
+        &self,
+        owner: AccountId,
+        decrease_by: Coin,
+        fee: Option<Fee>,
+    ) -> Result<ExecuteResult, NyxdError> {
+        self.execute_mixnet_contract(
+            fee,
+            MixnetExecuteMsg::DecreasePledgeOnBehalf {
+                owner: owner.to_string(),
+                decrease_by: decrease_by.into(),
+            },
+            vec![],
+        )
+        .await
+    }
+
    async fn unbond_mixnode(&self, fee: Option<Fee>) -> Result<ExecuteResult, NyxdError> {
        self.execute_mixnet_contract(fee, MixnetExecuteMsg::UnbondMixnode {}, vec![])
            .await
@@ -91,6 +91,21 @@ pub trait VestingSigningClient {
        .await
    }

+    async fn vesting_decrease_pledge(
+        &self,
+        decrease_by: Coin,
+        fee: Option<Fee>,
+    ) -> Result<ExecuteResult, NyxdError> {
+        self.execute_vesting_contract(
+            fee,
+            VestingExecuteMsg::DecreasePledge {
+                amount: decrease_by.into(),
+            },
+            vec![],
+        )
+        .await
+    }
+
    async fn vesting_unbond_mixnode(&self, fee: Option<Fee>) -> Result<ExecuteResult, NyxdError>;

    async fn vesting_track_unbond_mixnode(
@@ -6,11 +6,9 @@ use clap::{Args, Subcommand};
 pub mod rewards;

 pub mod delegate_to_mixnode;
-pub mod pledge_more;
 pub mod query_for_delegations;
 pub mod undelegate_from_mixnode;
 pub mod vesting_delegate_to_mixnode;
-pub mod vesting_pledge_more;
 pub mod vesting_undelegate_from_mixnode;

 #[derive(Debug, Args)]
@@ -34,8 +32,4 @@ pub enum MixnetDelegatorsCommands {
    DelegateVesting(vesting_delegate_to_mixnode::Args),
    /// Undelegate from a mixnode (when originally using locked tokens)
    UndelegateVesting(vesting_undelegate_from_mixnode::Args),
-    /// Pledge more
-    PledgeMore(pledge_more::Args),
-    /// Pledge more with locked tokens
-    PledgeMoreVesting(vesting_pledge_more::Args),
 }
@@ -26,7 +26,7 @@ pub struct Args {
    pub version: Option<String>,
 }

-pub async fn vesting_update_config(client: SigningClient, args: Args) {
+pub async fn vesting_update_config(args: Args, client: SigningClient) {
    info!("Update vesting gateway config!");

    let current_details = match client
@@ -45,7 +45,9 @@ pub struct Args {
    pub force: bool,
 }

-pub async fn vesting_bond_gateway(client: SigningClient, args: Args, denom: &str) {
+pub async fn vesting_bond_gateway(args: Args, client: SigningClient) {
+    let denom = client.current_chain_details().mix_denom.base.as_str();
+
    info!("Starting vesting gateway bonding!");

    // if we're trying to bond less than 1 token
@@ -0,0 +1,29 @@
+// Copyright 2023 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::context::SigningClient;
+use clap::Parser;
+use log::info;
+use nym_mixnet_contract_common::Coin;
+use nym_validator_client::nyxd::traits::MixnetSigningClient;
+
+#[derive(Debug, Parser)]
+pub struct Args {
+    #[clap(long)]
+    pub decrease_by: u128,
+}
+
+pub async fn decrease_pledge(args: Args, client: SigningClient) {
+    let denom = client.current_chain_details().mix_denom.base.as_str();
+
+    info!("Starting to decrease pledge");
+
+    let coin = Coin::new(args.decrease_by, denom);
+
+    let res = client
+        .pledge_more(coin.into(), None)
+        .await
+        .expect("failed to decrease pledge!");
+
+    info!("decreasing pledge: {:?}", res);
+}
@@ -4,13 +4,17 @@
 use clap::{Args, Subcommand};

 pub mod bond_mixnode;
+pub mod decrease_pledge;
 pub mod families;
 pub mod keys;
 pub mod mixnode_bonding_sign_payload;
+pub mod pledge_more;
 pub mod rewards;
 pub mod settings;
 pub mod unbond_mixnode;
 pub mod vesting_bond_mixnode;
+pub mod vesting_decrease_pledge;
+pub mod vesting_pledge_more;
 pub mod vesting_unbond_mixnode;

 #[derive(Debug, Args)]
@@ -40,4 +44,12 @@ pub enum MixnetOperatorsMixnodeCommands {
    UnbondVesting(vesting_unbond_mixnode::Args),
    /// Create base58-encoded payload required for producing valid bonding signature.
    CreateMixnodeBondingSignPayload(mixnode_bonding_sign_payload::Args),
+    /// Pledge more
+    PledgeMore(pledge_more::Args),
+    /// Pledge more with locked tokens
+    PledgeMoreVesting(vesting_pledge_more::Args),
+    /// Decrease pledge
+    DecreasePledge(decrease_pledge::Args),
+    /// Decrease pledge with locked tokens
+    DecreasePledgeVesting(vesting_decrease_pledge::Args),
 }
@@ -0,0 +1,29 @@
+// Copyright 2023 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::context::SigningClient;
+use clap::Parser;
+use log::info;
+use nym_mixnet_contract_common::Coin;
+use nym_validator_client::nyxd::VestingSigningClient;
+
+#[derive(Debug, Parser)]
+pub struct Args {
+    #[clap(long)]
+    pub decrease_by: u128,
+}
+
+pub async fn vesting_decrease_pledge(args: Args, client: SigningClient) {
+    let denom = client.current_chain_details().mix_denom.base.as_str();
+
+    info!("Starting vesting to decrease pledge");
+
+    let coin = Coin::new(args.decrease_by, denom);
+
+    let res = client
+        .vesting_decrease_pledge(coin.into(), None)
+        .await
+        .expect("failed to vesting decrease pledge!");
+
+    info!("vesting decreasing pledge: {:?}", res);
+}
@@ -1,6 +1,6 @@
 [package]
 name = "nym-mixnet-contract-common"
-version = "0.4.0"
+version = "0.5.0"
 description = "Common library for the Nym mixnet contract"
 rust-version = "1.62"
 edition = { workspace = true }
@@ -1,13 +1,16 @@
-// Copyright 2022 - Nym Technologies SA <contact@nymtech.net>
+// Copyright 2022-2023 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

-use crate::{EpochState, IdentityKey, MixId};
+use crate::{EpochEventId, EpochState, IdentityKey, MixId};
 use contracts_common::signing::verifier::ApiVerifierError;
-use cosmwasm_std::{Addr, Coin, Decimal};
+use cosmwasm_std::{Addr, Coin, Decimal, Uint128};
 use thiserror::Error;

 #[derive(Error, Debug, PartialEq)]
 pub enum MixnetContractError {
+    #[error("could not perform contract migration: {comment}")]
+    FailedMigration { comment: String },
+
    #[error("{source}")]
    StdErr {
        #[from]
@@ -26,6 +29,17 @@ pub enum MixnetContractError {
    #[error("Not enough funds sent for node pledge. (received {received}, minimum {minimum})")]
    InsufficientPledge { received: Coin, minimum: Coin },

+    #[error("Attempted to reduce node pledge ({current}{denom} - {decrease_by}{denom}) below the minimum amount: {minimum}{denom}")]
+    InvalidPledgeReduction {
+        current: Uint128,
+        decrease_by: Uint128,
+        minimum: Uint128,
+        denom: String,
+    },
+
+    #[error("A pledge change is already pending in this epoch. The event id: {pending_event_id}")]
+    PendingPledgeChange { pending_event_id: EpochEventId },
+
    #[error("Not enough funds sent for node delegation. (received {received}, minimum {minimum})")]
    InsufficientDelegation { received: Coin, minimum: Coin },

@@ -190,6 +204,9 @@ pub enum MixnetContractError {
    #[error("epoch duration must be > 0")]
    EpochDurationZero,

+    #[error("attempted to perform the operation with 0 coins. This is not allowed")]
+    ZeroCoinAmount,
+
    #[error("this validator ({current_validator}) is not the one responsible for advancing this epoch. It's responsibility of {chosen_validator}.")]
    RewardingValidatorMismatch {
        current_validator: Addr,
@@ -226,3 +243,11 @@ pub enum MixnetContractError {
        source: ApiVerifierError,
    },
 }
+
+impl MixnetContractError {
+    pub fn inconsistent_state<S: Into<String>>(comment: S) -> Self {
+        MixnetContractError::InconsistentState {
+            comment: comment.into(),
+        }
+    }
+}
@@ -15,6 +15,8 @@ pub enum MixnetEventType {
    MixnodeBonding,
    PendingPledgeIncrease,
    PledgeIncrease,
+    PendingPledgeDecrease,
+    PledgeDecrease,
    GatewayBonding,
    GatewayUnbonding,
    PendingMixnodeUnbonding,
@@ -58,6 +60,8 @@ impl ToString for MixnetEventType {
            MixnetEventType::MixnodeBonding => "mixnode_bonding",
            MixnetEventType::PendingPledgeIncrease => "pending_pledge_increase",
            MixnetEventType::PledgeIncrease => "pledge_increase",
+            MixnetEventType::PendingPledgeDecrease => "pending_pledge_decrease",
+            MixnetEventType::PledgeDecrease => "pledge_decrease",
            MixnetEventType::GatewayBonding => "gateway_bonding",
            MixnetEventType::GatewayUnbonding => "gateway_unbonding",
            MixnetEventType::PendingMixnodeUnbonding => "pending_mixnode_unbonding",
@@ -354,6 +358,19 @@ pub fn new_pledge_increase_event(created_at: BlockHeight, mix_id: MixId, amount:
        .add_attribute(AMOUNT_KEY, amount.to_string())
 }

+pub fn new_pending_pledge_decrease_event(mix_id: MixId, amount: &Coin) -> Event {
+    Event::new(MixnetEventType::PendingPledgeDecrease)
+        .add_attribute(MIX_ID_KEY, mix_id.to_string())
+        .add_attribute(AMOUNT_KEY, amount.to_string())
+}
+
+pub fn new_pledge_decrease_event(created_at: BlockHeight, mix_id: MixId, amount: &Coin) -> Event {
+    Event::new(MixnetEventType::PledgeDecrease)
+        .add_attribute(EVENT_CREATION_HEIGHT_KEY, created_at.to_string())
+        .add_attribute(MIX_ID_KEY, mix_id.to_string())
+        .add_attribute(AMOUNT_KEY, amount.to_string())
+}
+
 pub fn new_mixnode_unbonding_event(created_at: BlockHeight, mix_id: MixId) -> Event {
    Event::new(MixnetEventType::MixnodeUnbonding)
        .add_attribute(EVENT_CREATION_HEIGHT_KEY, created_at.to_string())
@@ -3,7 +3,10 @@

 use crate::error::MixnetContractError;
 use crate::pending_events::{PendingEpochEvent, PendingIntervalEvent};
-use crate::{EpochId, IntervalId, MixId};
+use crate::{
+    EpochEventId, EpochId, IntervalEventId, IntervalId, MixId, PendingEpochEventData,
+    PendingIntervalEventData,
+};
 use cosmwasm_std::{Addr, Env};
 use schemars::gen::SchemaGenerator;
 use schemars::schema::{InstanceType, Schema, SchemaObject};
@@ -528,6 +531,30 @@ impl PendingIntervalEventsResponse {
    }
 }

+#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
+pub struct PendingEpochEventResponse {
+    pub event_id: EpochEventId,
+    pub event: Option<PendingEpochEventData>,
+}
+
+impl PendingEpochEventResponse {
+    pub fn new(event_id: EpochEventId, event: Option<PendingEpochEventData>) -> Self {
+        PendingEpochEventResponse { event_id, event }
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
+pub struct PendingIntervalEventResponse {
+    pub event_id: IntervalEventId,
+    pub event: Option<PendingIntervalEventData>,
+}
+
+impl PendingIntervalEventResponse {
+    pub fn new(event_id: IntervalEventId, event: Option<PendingIntervalEventData>) -> Self {
+        PendingIntervalEventResponse { event_id, event }
+    }
+}
+
 #[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
 pub struct NumberOfPendingEventsResponse {
    pub epoch_events: u32,
@@ -32,7 +32,8 @@ pub use gateway::{
 };
 pub use interval::{
    CurrentIntervalResponse, EpochState, EpochStatus, Interval, NumberOfPendingEventsResponse,
-    PendingEpochEventsResponse, PendingIntervalEventsResponse,
+    PendingEpochEventResponse, PendingEpochEventsResponse, PendingIntervalEventResponse,
+    PendingIntervalEventsResponse,
 };
 pub use mixnode::{
    Layer, MixNode, MixNodeBond, MixNodeConfigUpdate, MixNodeCostParams, MixNodeDetails,
@@ -10,7 +10,7 @@ use crate::helpers::IntoBaseDecimal;
 use crate::reward_params::{NodeRewardParams, RewardingParams};
 use crate::rewarding::helpers::truncate_reward;
 use crate::rewarding::RewardDistribution;
-use crate::{Delegation, EpochId, IdentityKey, MixId, Percent, SphinxKey};
+use crate::{Delegation, EpochEventId, EpochId, IdentityKey, MixId, Percent, SphinxKey};
 use cosmwasm_std::{Addr, Coin, Decimal, StdResult, Uint128};
 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
@@ -37,13 +37,20 @@ impl RewardedSetNodeStatus {
 pub struct MixNodeDetails {
    pub bond_information: MixNodeBond,
    pub rewarding_details: MixNodeRewarding,
+    #[serde(default)]
+    pub pending_changes: PendingMixNodeChanges,
 }

 impl MixNodeDetails {
-    pub fn new(bond_information: MixNodeBond, rewarding_details: MixNodeRewarding) -> Self {
+    pub fn new(
+        bond_information: MixNodeBond,
+        rewarding_details: MixNodeRewarding,
+        pending_changes: PendingMixNodeChanges,
+    ) -> Self {
        MixNodeDetails {
            bond_information,
            rewarding_details,
+            pending_changes,
        }
    }

@@ -73,6 +80,10 @@ impl MixNodeDetails {
    pub fn total_stake(&self) -> Decimal {
        self.rewarding_details.node_bond()
    }
+
+    pub fn pending_pledge_change(&self) -> Option<EpochEventId> {
+        self.pending_changes.pledge_change
+    }
 }

 #[derive(Clone, Debug, Deserialize, PartialEq, Serialize, JsonSchema)]
@@ -332,6 +343,22 @@ impl MixNodeRewarding {
        Ok(())
    }

+    /// Decreases total pledge of operator by the specified amount.
+    pub fn decrease_operator_uint128(
+        &mut self,
+        amount: Uint128,
+    ) -> Result<(), MixnetContractError> {
+        let amount_decimal = amount.into_base_decimal()?;
+        if self.operator < amount_decimal {
+            return Err(MixnetContractError::OverflowDecimalSubtraction {
+                minuend: self.operator,
+                subtrahend: amount_decimal,
+            });
+        }
+        self.operator -= amount_decimal;
+        Ok(())
+    }
+
    pub fn increase_delegates_uint128(
        &mut self,
        amount: Uint128,
@@ -601,6 +628,25 @@ impl From<Layer> for u8 {
    }
 }

+#[cfg_attr(feature = "generate-ts", derive(ts_rs::TS))]
+#[cfg_attr(
+    feature = "generate-ts",
+    ts(export_to = "ts-packages/types/src/types/rust/PendingMixnodeChanges.ts")
+)]
+#[derive(Clone, Copy, Debug, Default, Deserialize, PartialEq, Eq, Serialize, JsonSchema)]
+pub struct PendingMixNodeChanges {
+    pub pledge_change: Option<EpochEventId>,
+    // pub cost_params_change: Option<IntervalEventId>,
+}
+
+impl PendingMixNodeChanges {
+    pub fn new_empty() -> PendingMixNodeChanges {
+        PendingMixNodeChanges {
+            pledge_change: None,
+        }
+    }
+}
+
 #[cfg_attr(feature = "generate-ts", derive(ts_rs::TS))]
 #[cfg_attr(
    feature = "generate-ts",
@@ -10,10 +10,13 @@ use crate::mixnode::{MixNodeConfigUpdate, MixNodeCostParams};
 use crate::reward_params::{
    IntervalRewardParams, IntervalRewardingParamsUpdate, Performance, RewardingParams,
 };
-use crate::{delegation, ContractStateParams, Layer, LayerAssignment, MixId, Percent};
+use crate::{
+    delegation, ContractStateParams, EpochEventId, IntervalEventId, Layer, LayerAssignment, MixId,
+    Percent,
+};
 use crate::{Gateway, IdentityKey, MixNode};
 use contracts_common::signing::MessageSignature;
-use cosmwasm_std::Decimal;
+use cosmwasm_std::{Coin, Decimal};
 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 use std::time::Duration;
@@ -161,6 +164,13 @@ pub enum ExecuteMsg {
    PledgeMoreOnBehalf {
        owner: String,
    },
+    DecreasePledge {
+        decrease_by: Coin,
+    },
+    DecreasePledgeOnBehalf {
+        owner: String,
+        decrease_by: Coin,
+    },
    UnbondMixnode {},
    UnbondMixnodeOnBehalf {
        owner: String,
@@ -297,6 +307,10 @@ impl ExecuteMsg {
            }
            ExecuteMsg::PledgeMore {} => "pledging additional tokens".into(),
            ExecuteMsg::PledgeMoreOnBehalf { .. } => "pledging additional tokens on behalf".into(),
+            ExecuteMsg::DecreasePledge { .. } => "decreasing mixnode pledge".into(),
+            ExecuteMsg::DecreasePledgeOnBehalf { .. } => {
+                "decreasing mixnode pledge on behalf".into()
+            }
            ExecuteMsg::UnbondMixnode { .. } => "unbonding mixnode".into(),
            ExecuteMsg::UnbondMixnodeOnBehalf { .. } => "unbonding mixnode on behalf".into(),
            ExecuteMsg::UpdateMixnodeCostParams { .. } => "updating mixnode cost parameters".into(),
@@ -506,6 +520,12 @@ pub enum QueryMsg {
        limit: Option<u32>,
        start_after: Option<u32>,
    },
+    GetPendingEpochEvent {
+        event_id: EpochEventId,
+    },
+    GetPendingIntervalEvent {
+        event_id: IntervalEventId,
+    },
    GetNumberOfPendingEvents {},

    // signing-related
@@ -38,6 +38,10 @@ pub enum PendingEpochEventKind {
        mix_id: MixId,
        amount: Coin,
    },
+    DecreasePledge {
+        mix_id: MixId,
+        decrease_by: Coin,
+    },
    UnbondMixnode {
        mix_id: MixId,
    },
@@ -66,7 +70,7 @@ impl From<(EpochEventId, PendingEpochEventData)> for PendingEpochEvent {

 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 pub struct PendingIntervalEvent {
-    pub id: EpochEventId,
+    pub id: IntervalEventId,
    pub event: PendingIntervalEventData,
 }

@@ -1,6 +1,6 @@
 [package]
 name = "nym-vesting-contract-common"
-version = "0.5.0"
+version = "0.6.0"
 description = "Common library for the Nym vesting contract"
 edition = { workspace = true }
 authors = { workspace = true }
@@ -9,7 +9,7 @@ repository = { workspace = true }

 [dependencies]
 cosmwasm-std = { workspace = true }
-mixnet-contract-common = { path = "../mixnet-contract", package = "nym-mixnet-contract-common", version = "0.4.0" }
+mixnet-contract-common = { path = "../mixnet-contract", package = "nym-mixnet-contract-common", version = "0.5.0" }
 contracts-common = { path = "../contracts-common", package = "nym-contracts-common", version = "0.4.0" }
 serde = { version = "1.0", features = ["derive"] }
 schemars = "0.8"
@@ -15,6 +15,7 @@ pub const VESTING_GATEWAY_BONDING_EVENT_TYPE: &str = "vesting_gateway_bonding";
 pub const VESTING_GATEWAY_UNBONDING_EVENT_TYPE: &str = "vesting_gateway_unbonding";
 pub const VESTING_MIXNODE_BONDING_EVENT_TYPE: &str = "vesting_mixnode_bonding";
 pub const VESTING_PLEDGE_MORE_EVENT_TYPE: &str = "vesting_pledge_more";
+pub const VESTING_DECREASE_PLEDGE_EVENT_TYPE: &str = "vesting_pledge_decrease";
 pub const VESTING_MIXNODE_UNBONDING_EVENT_TYPE: &str = "vesting_mixnode_unbonding";
 pub const VESTING_UPDATE_MIXNODE_CONFIG_EVENT_TYPE: &str = "vesting_update_mixnode_config";
 pub const VESTING_UPDATE_GATEWAY_CONFIG_EVENT_TYPE: &str = "vesting_update_gateway_config";
@@ -22,6 +23,7 @@ pub const VESTING_UPDATE_MIXNODE_COST_PARAMS_EVENT_TYPE: &str =
    "vesting_update_mixnode_cost_params";

 pub const TRACK_MIXNODE_UNBOND_EVENT_TYPE: &str = "track_mixnode_unbond";
+pub const TRACK_MIXNODE_PLEDGE_DECREASE_EVENT_TYPE: &str = "track_mixnode_pledge_decrease";
 pub const TRACK_GATEWAY_UNBOND_EVENT_TYPE: &str = "track_gateway_unbond";
 pub const TRACK_UNDELEGATION_EVENT_TYPE: &str = "track_undelegation";
 pub const TRACK_REWARD_EVENT_TYPE: &str = "track_reaward";
@@ -118,6 +120,10 @@ pub fn new_vesting_pledge_more_event() -> Event {
    Event::new(VESTING_PLEDGE_MORE_EVENT_TYPE)
 }

+pub fn new_vesting_decrease_pledge_event() -> Event {
+    Event::new(VESTING_DECREASE_PLEDGE_EVENT_TYPE)
+}
+
 pub fn new_vesting_update_mixnode_config_event() -> Event {
    Event::new(VESTING_UPDATE_MIXNODE_CONFIG_EVENT_TYPE)
 }
@@ -146,6 +152,10 @@ pub fn new_track_mixnode_unbond_event() -> Event {
    Event::new(TRACK_MIXNODE_UNBOND_EVENT_TYPE)
 }

+pub fn new_track_mixnode_pledge_decrease_event() -> Event {
+    Event::new(TRACK_MIXNODE_PLEDGE_DECREASE_EVENT_TYPE)
+}
+
 pub fn new_track_gateway_unbond_event() -> Event {
    Event::new(TRACK_GATEWAY_UNBOND_EVENT_TYPE)
 }
@@ -123,11 +123,18 @@ pub enum ExecuteMsg {
    PledgeMore {
        amount: Coin,
    },
+    DecreasePledge {
+        amount: Coin,
+    },
    UnbondMixnode {},
    TrackUnbondMixnode {
        owner: String,
        amount: Coin,
    },
+    TrackDecreasePledge {
+        owner: String,
+        amount: Coin,
+    },
    BondGateway {
        gateway: Gateway,
        owner_signature: MessageSignature,
@@ -175,8 +182,10 @@ impl ExecuteMsg {
            ExecuteMsg::TrackUndelegation { .. } => "VestingExecuteMsg::TrackUndelegation",
            ExecuteMsg::BondMixnode { .. } => "VestingExecuteMsg::BondMixnode",
            ExecuteMsg::PledgeMore { .. } => "VestingExecuteMsg::PledgeMore",
+            ExecuteMsg::DecreasePledge { .. } => "VestingExecuteMsg::DecreasePledge",
            ExecuteMsg::UnbondMixnode { .. } => "VestingExecuteMsg::UnbondMixnode",
            ExecuteMsg::TrackUnbondMixnode { .. } => "VestingExecuteMsg::TrackUnbondMixnode",
+            ExecuteMsg::TrackDecreasePledge { .. } => "VestingExecuteMsg::TrackDecreasePledge",
            ExecuteMsg::BondGateway { .. } => "VestingExecuteMsg::BondGateway",
            ExecuteMsg::UnbondGateway { .. } => "VestingExecuteMsg::UnbondGateway",
            ExecuteMsg::TrackUnbondGateway { .. } => "VestingExecuteMsg::TrackUnbondGateway",
@@ -3,12 +3,15 @@

 use nym_sphinx_acknowledgements::surb_ack::SurbAckRecoveryError;
 use nym_sphinx_addressing::nodes::NymNodeRoutingAddressError;
-use nym_sphinx_types::Error as SphinxError;
+use nym_sphinx_types::{NymPacketError, SphinxError};
 use thiserror::Error;

 #[derive(Error, Debug)]
 pub enum MixProcessingError {
    #[error("failed to process received packet: {0}")]
+    NymPacketProcessingError(#[from] NymPacketError),
+
+    #[error("failed to process received sphinx packet: {0}")]
    SphinxProcessingError(#[from] SphinxError),

    #[error("the forward hop address was malformed: {0}")]
@@ -7,11 +7,11 @@ use log::*;
 use nym_sphinx_acknowledgements::surb_ack::SurbAck;
 use nym_sphinx_addressing::nodes::NymNodeRoutingAddress;
 use nym_sphinx_forwarding::packet::MixPacket;
-use nym_sphinx_framing::packet::FramedSphinxPacket;
-use nym_sphinx_params::{PacketMode, PacketSize};
+use nym_sphinx_framing::packet::FramedNymPacket;
+use nym_sphinx_params::{PacketSize, PacketType};
 use nym_sphinx_types::{
-    Delay as SphinxDelay, DestinationAddressBytes, NodeAddressBytes, Payload, PrivateKey,
-    ProcessedPacket, SphinxPacket,
+    Delay as SphinxDelay, DestinationAddressBytes, NodeAddressBytes, NymPacket, Payload,
+    PrivateKey, ProcessedPacket,
 };
 use std::convert::TryFrom;
 use std::sync::Arc;
@@ -53,14 +53,14 @@ impl SphinxPacketProcessor {
        feature = "cpucycles",
        instrument(skip(self, packet), fields(cpucycles))
    )]
-    fn perform_initial_sphinx_packet_processing(
+    fn perform_initial_packet_processing(
        &self,
-        packet: SphinxPacket,
+        packet: NymPacket,
    ) -> Result<ProcessedPacket, MixProcessingError> {
        measure!({
            packet.process(&self.sphinx_key).map_err(|err| {
                debug!("Failed to unwrap Sphinx packet: {err}");
-                MixProcessingError::SphinxProcessingError(err)
+                MixProcessingError::NymPacketProcessingError(err)
            })
        })
    }
@@ -72,17 +72,12 @@ impl SphinxPacketProcessor {
    )]
    fn perform_initial_unwrapping(
        &self,
-        received: FramedSphinxPacket,
+        received: FramedNymPacket,
    ) -> Result<ProcessedPacket, MixProcessingError> {
        measure!({
-            let packet_mode = received.packet_mode();
-            let sphinx_packet = received.into_inner();
+            let packet = received.into_inner();

-            if packet_mode.is_old_vpn() {
-                return Err(MixProcessingError::ReceivedOldTypeVpnPacket);
-            }
-
-            self.perform_initial_sphinx_packet_processing(sphinx_packet)
+            self.perform_initial_packet_processing(packet)
        })
    }

@@ -90,14 +85,14 @@ impl SphinxPacketProcessor {
    /// and packs all the data in a way that can be easily sent to the next hop.
    fn process_forward_hop(
        &self,
-        packet: SphinxPacket,
+        packet: NymPacket,
        forward_address: NodeAddressBytes,
        delay: SphinxDelay,
-        packet_mode: PacketMode,
+        packet_type: PacketType,
    ) -> Result<MixProcessingResult, MixProcessingError> {
        let next_hop_address = NymNodeRoutingAddress::try_from(forward_address)?;

-        let mix_packet = MixPacket::new(next_hop_address, packet, packet_mode);
+        let mix_packet = MixPacket::new(next_hop_address, packet, packet_type);
        Ok(MixProcessingResult::ForwardHop(mix_packet, Some(delay)))
    }

@@ -124,21 +119,25 @@ impl SphinxPacketProcessor {
        &self,
        data: Vec<u8>,
        packet_size: PacketSize,
-        packet_mode: PacketMode,
+        packet_type: PacketType,
    ) -> Result<(Option<MixPacket>, Vec<u8>), MixProcessingError> {
        match packet_size {
-            PacketSize::AckPacket => {
+            PacketSize::AckPacket | PacketSize::OutfoxAckPacket => {
                trace!("received an ack packet!");
                Ok((None, data))
            }
            PacketSize::RegularPacket
            | PacketSize::ExtendedPacket8
            | PacketSize::ExtendedPacket16
-            | PacketSize::ExtendedPacket32 => {
+            | PacketSize::ExtendedPacket32
+            | PacketSize::OutfoxRegularPacket
+            | PacketSize::OutfoxExtendedPacket8
+            | PacketSize::OutfoxExtendedPacket16
+            | PacketSize::OutfoxExtendedPacket32 => {
                trace!("received a normal packet!");
                let (ack_data, message) = self.split_hop_data_into_ack_and_message(data)?;
                let (ack_first_hop, ack_packet) = SurbAck::try_recover_first_hop_packet(&ack_data)?;
-                let forward_ack = MixPacket::new(ack_first_hop, ack_packet, packet_mode);
+                let forward_ack = MixPacket::new(ack_first_hop, ack_packet, packet_type);
                Ok((Some(forward_ack), message))
            }
        }
@@ -152,12 +151,12 @@ impl SphinxPacketProcessor {
        destination: DestinationAddressBytes,
        payload: Payload,
        packet_size: PacketSize,
-        packet_mode: PacketMode,
+        packet_type: PacketType,
    ) -> Result<MixProcessingResult, MixProcessingError> {
        let packet_message = payload.recover_plaintext()?;

        let (forward_ack, message) =
-            self.split_into_ack_and_message(packet_message, packet_size, packet_mode)?;
+            self.split_into_ack_and_message(packet_message, packet_size, packet_type)?;

        Ok(MixProcessingResult::FinalHop(ProcessedFinalHop {
            destination,
@@ -172,16 +171,16 @@ impl SphinxPacketProcessor {
        &self,
        packet: ProcessedPacket,
        packet_size: PacketSize,
-        packet_mode: PacketMode,
+        packet_type: PacketType,
    ) -> Result<MixProcessingResult, MixProcessingError> {
        match packet {
            ProcessedPacket::ForwardHop(packet, address, delay) => {
-                self.process_forward_hop(*packet, address, delay, packet_mode)
+                self.process_forward_hop(NymPacket::Sphinx(*packet), address, delay, packet_type)
            }
            // right now there's no use for the surb_id included in the header - probably it should get removed from the
            // sphinx all together?
            ProcessedPacket::FinalHop(destination, _, payload) => {
-                self.process_final_hop(destination, payload, packet_size, packet_mode)
+                self.process_final_hop(destination, payload, packet_size, packet_type)
            }
        }
    }
@@ -192,19 +191,19 @@ impl SphinxPacketProcessor {
    )]
    pub fn process_received(
        &self,
-        received: FramedSphinxPacket,
+        received: FramedNymPacket,
    ) -> Result<MixProcessingResult, MixProcessingError> {
        // explicit packet size will help to correctly parse final hop
        measure!({
            let packet_size = received.packet_size();
-            let packet_mode = received.packet_mode();
+            let packet_type = received.packet_type();

            // unwrap the sphinx packet and if possible and appropriate, cache keys
            let processed_packet = self.perform_initial_unwrapping(received)?;

            // for forward packets, extract next hop and set delay (but do NOT delay here)
            // for final packets, extract SURBAck
-            self.perform_final_processing(processed_packet, packet_size, packet_mode)
+            self.perform_final_processing(processed_packet, packet_size, packet_type)
        })
    }
 }
@@ -0,0 +1,30 @@
+[package]
+name = "nym-node-tester-utils"
+version = "0.1.0"
+edition = "2021"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+futures = "0.3.28"
+rand = "0.7.3"
+
+serde = { workspace = true }
+serde_json = { workspace = true }
+thiserror = { workspace = true }
+tokio = { workspace = true, features = ["macros"]}
+
+nym-crypto = { path = "../crypto", features = ["asymmetric"] }
+nym-task = { path = "../task" }
+nym-topology = { path = "../topology" }
+nym-sphinx-params = { path = "../nymsphinx/params" }
+# TODO: do we need the whole nymsphinx?
+nym-sphinx = { path = "../nymsphinx" }
+
+## non-wasm-only dependencies
+[target."cfg(not(target_arch = \"wasm32\"))".dependencies.log]
+workspace = true
+
+## wasm-only dependencies
+[target."cfg(target_arch = \"wasm32\")".dependencies.wasm-utils]
+path = "../wasm-utils"
@@ -0,0 +1,49 @@
+// Copyright 2023 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::MixId;
+use nym_sphinx::chunking::ChunkingError;
+use nym_sphinx::receiver::MessageRecoveryError;
+use nym_topology::NymTopologyError;
+use thiserror::Error;
+
+#[derive(Debug, Error)]
+pub enum NetworkTestingError {
+    #[error(transparent)]
+    SerializationFailure(#[from] serde_json::Error),
+
+    #[error("could not recover received test message: {source}")]
+    MalformedTestMessageReceived { source: serde_json::Error },
+
+    #[error(transparent)]
+    InvalidTopology(#[from] NymTopologyError),
+
+    #[error("The specified mixnode (id: {mix_id}) doesn't exist")]
+    NonExistentMixnode { mix_id: MixId },
+
+    #[error("The specified mixnode (identity: {mix_identity}) doesn't exist")]
+    NonExistentMixnodeIdentity { mix_identity: String },
+
+    #[error("The specified gateway (id: {gateway_identity}) doesn't exist")]
+    NonExistentGateway { gateway_identity: String },
+
+    #[error("The provided test message is too long to fit in a single sphinx packet")]
+    TestMessageTooLong,
+
+    #[error(
+        "could not recover underlying data from the received packet since it was malformed: {source}"
+    )]
+    MalformedPacketReceived {
+        #[from]
+        source: MessageRecoveryError,
+    },
+
+    #[error("Received ack packet could not be recovered")]
+    UnrecoverableAck,
+
+    #[error("could not recover ack FragmentIdentifier: {source}")]
+    MalformedAckIdentifier { source: ChunkingError },
+
+    #[error("received a packet that could not be reconstructed into a full message with a single fragment")]
+    NonReconstructablePacket,
+}
@@ -0,0 +1,46 @@
+// Copyright 2023 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+pub mod error;
+pub mod message;
+pub mod receiver;
+pub mod tester;
+
+pub use message::{Empty, TestMessage};
+pub use tester::NodeTester;
+
+// it feels wrong to redefine it, but I don't want to import the whole of contract commons just for this one type
+pub(crate) type MixId = u32;
+
+#[macro_export]
+macro_rules! log_err {
+    ($($t:tt)*) => {{
+        #[cfg(target_arch = "wasm32")]
+        {::wasm_utils::console_error!($($t)*)}
+
+        #[cfg(not(target_arch = "wasm32"))]
+        {::log::error!($($t)*)}
+    }};
+}
+
+#[macro_export]
+macro_rules! log_warn {
+    ($($t:tt)*) => {{
+        #[cfg(target_arch = "wasm32")]
+        {::wasm_utils::console_warn!($($t)*)}
+
+        #[cfg(not(target_arch = "wasm32"))]
+        {::log::warn!($($t)*)}
+    }};
+}
+
+#[macro_export]
+macro_rules! log_info {
+    ($($t:tt)*) => {{
+        #[cfg(target_arch = "wasm32")]
+        {::wasm_utils::console_log!($($t)*)}
+
+        #[cfg(not(target_arch = "wasm32"))]
+        {::log::info!($($t)*)}
+    }};
+}
@@ -0,0 +1,99 @@
+// Copyright 2023 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::error::NetworkTestingError;
+use crate::MixId;
+use nym_sphinx::message::NymMessage;
+use nym_topology::{gateway, mix};
+use serde::de::DeserializeOwned;
+use serde::{Deserialize, Serialize};
+use std::hash::{Hash, Hasher};
+
+#[derive(Serialize, Deserialize, Hash, Clone, Copy)]
+pub enum NodeType {
+    Mixnode(MixId),
+    Gateway,
+}
+
+#[derive(Serialize, Deserialize, Hash, Clone, Copy)]
+pub struct Empty;
+
+#[derive(Serialize, Deserialize, Clone)]
+pub struct TestMessage<T = Empty> {
+    pub encoded_node_identity: String,
+    pub node_owner: String,
+    pub node_type: NodeType,
+
+    pub msg_id: u32,
+    pub total_msgs: u32,
+
+    // any additional fields that might be required by a specific tester.
+    // For example nym-api might want to attach route ids
+    #[serde(flatten)]
+    pub ext: T,
+}
+
+impl<T> TestMessage<T> {
+    pub fn new_mix(node: &mix::Node, msg_id: u32, total_msgs: u32, ext: T) -> Self {
+        TestMessage {
+            encoded_node_identity: node.identity_key.to_base58_string(),
+            node_owner: node.owner.clone(),
+            node_type: NodeType::Mixnode(node.mix_id),
+            msg_id,
+            total_msgs,
+            ext,
+        }
+    }
+
+    pub fn new_gateway(node: &gateway::Node, msg_id: u32, total_msgs: u32, ext: T) -> Self {
+        TestMessage {
+            encoded_node_identity: node.identity_key.to_base58_string(),
+            node_owner: node.owner.clone(),
+            node_type: NodeType::Gateway,
+            msg_id,
+            total_msgs,
+            ext,
+        }
+    }
+
+    pub fn as_json_string(&self) -> Result<String, NetworkTestingError>
+    where
+        T: Serialize,
+    {
+        serde_json::to_string(self).map_err(Into::into)
+    }
+
+    pub fn as_bytes(&self) -> Result<Vec<u8>, NetworkTestingError>
+    where
+        T: Serialize,
+    {
+        // the test messages are supposed to be rather small so we can use the good old serde_json
+        // (the performance penalty over bincode or custom serialization should be minimal)
+        serde_json::to_vec(self).map_err(Into::into)
+    }
+
+    pub fn try_recover(msg: NymMessage) -> Result<Self, NetworkTestingError>
+    where
+        T: DeserializeOwned,
+    {
+        let inner = msg.into_inner_data();
+        Self::try_recover_from_bytes(&inner)
+    }
+
+    pub fn try_recover_from_bytes(raw: &[u8]) -> Result<Self, NetworkTestingError>
+    where
+        T: DeserializeOwned,
+    {
+        serde_json::from_slice(raw)
+            .map_err(|source| NetworkTestingError::MalformedTestMessageReceived { source })
+    }
+}
+
+impl<T: Hash> Hash for TestMessage<T> {
+    fn hash<H: Hasher>(&self, state: &mut H) {
+        self.encoded_node_identity.hash(state);
+        self.node_owner.hash(state);
+        self.node_type.hash(state);
+        self.ext.hash(state)
+    }
+}
@@ -0,0 +1,148 @@
+// Copyright 2023 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::error::NetworkTestingError;
+use crate::{log_err, log_info, log_warn};
+use futures::channel::mpsc;
+use futures::StreamExt;
+use nym_crypto::asymmetric::encryption;
+use nym_sphinx::message::NymMessage;
+use nym_sphinx::receiver::{MessageReceiver, SphinxMessageReceiver};
+use nym_sphinx::{
+    acknowledgements::{identifier::recover_identifier, AckKey},
+    chunking::fragment::FragmentIdentifier,
+};
+use nym_task::TaskClient;
+use std::sync::Arc;
+
+pub type ReceivedSender = mpsc::UnboundedSender<Received>;
+pub type ReceivedReceiver = mpsc::UnboundedReceiver<Received>;
+
+// simple enum containing aggregated processed results
+pub enum Received {
+    Message(NymMessage),
+    Ack(FragmentIdentifier),
+}
+
+impl From<NymMessage> for Received {
+    fn from(value: NymMessage) -> Self {
+        Received::Message(value)
+    }
+}
+
+impl From<FragmentIdentifier> for Received {
+    fn from(value: FragmentIdentifier) -> Self {
+        Received::Ack(value)
+    }
+}
+
+// the 'Simple' bit comes from the fact that it expects all received messages to consist of a single `Fragment`
+pub struct SimpleMessageReceiver<R: MessageReceiver = SphinxMessageReceiver> {
+    local_encryption_keypair: Arc<encryption::KeyPair>,
+
+    ack_key: Arc<AckKey>,
+
+    /// Structure responsible for decrypting and recovering plaintext message from received ciphertexts.
+    message_receiver: R,
+
+    mixnet_message_receiver: mpsc::UnboundedReceiver<Vec<Vec<u8>>>,
+    acks_receiver: mpsc::UnboundedReceiver<Vec<Vec<u8>>>,
+
+    received_sender: ReceivedSender,
+    shutdown: TaskClient,
+}
+
+impl SimpleMessageReceiver<SphinxMessageReceiver> {
+    pub fn new_sphinx_receiver(
+        local_encryption_keypair: Arc<encryption::KeyPair>,
+        ack_key: Arc<AckKey>,
+        mixnet_message_receiver: mpsc::UnboundedReceiver<Vec<Vec<u8>>>,
+        acks_receiver: mpsc::UnboundedReceiver<Vec<Vec<u8>>>,
+        received_sender: ReceivedSender,
+        shutdown: TaskClient,
+    ) -> Self {
+        SimpleMessageReceiver {
+            local_encryption_keypair,
+            ack_key,
+            message_receiver: SphinxMessageReceiver::new(),
+            mixnet_message_receiver,
+            acks_receiver,
+            received_sender,
+            shutdown,
+        }
+    }
+}
+
+impl<R: MessageReceiver> SimpleMessageReceiver<R> {
+    fn forward_received<T: Into<Received>>(&self, received: T) {
+        // TODO: remove the unwrap once/if we do graceful shutdowns here
+        self.received_sender
+            .unbounded_send(received.into())
+            .expect("ReceivedReceiver has stopped receiving");
+    }
+
+    fn on_mixnet_message(&mut self, mut raw_message: Vec<u8>) -> Result<(), NetworkTestingError> {
+        let plaintext = self
+            .message_receiver
+            .recover_plaintext_from_regular_packet(
+                self.local_encryption_keypair.private_key(),
+                &mut raw_message,
+            )?;
+        let fragment = self.message_receiver.recover_fragment(plaintext)?;
+        let (recovered, _) = self
+            .message_receiver
+            .insert_new_fragment(fragment)?
+            .ok_or(NetworkTestingError::NonReconstructablePacket)?; // by definition of this receiver, the message must consist of a single fragment
+
+        self.forward_received(recovered);
+        Ok(())
+    }
+
+    fn on_ack(&mut self, raw_ack: Vec<u8>) -> Result<(), NetworkTestingError> {
+        let serialized_ack = recover_identifier(&self.ack_key, &raw_ack)
+            .ok_or(NetworkTestingError::UnrecoverableAck)?;
+
+        let frag_id = FragmentIdentifier::try_from_bytes(serialized_ack)
+            .map_err(|source| NetworkTestingError::MalformedAckIdentifier { source })?;
+
+        self.forward_received(frag_id);
+        Ok(())
+    }
+
+    pub async fn run(&mut self) {
+        while !self.shutdown.is_shutdown() {
+            tokio::select! {
+                biased;
+                _ = self.shutdown.recv() => {
+                    log_info!("SimpleMessageReceiver: received shutdown")
+                }
+                mixnet_messages = self.mixnet_message_receiver.next() => {
+                    let Some(mixnet_messages) = mixnet_messages else {
+                        log_err!("the mixnet messages stream has terminated!");
+                        // note: this will cause global shutdown, but we have no choice if we stopped receiving mixnet messages
+                        break
+                    };
+                    for message in mixnet_messages {
+                        if let Err(err) = self.on_mixnet_message(message) {
+                            log_warn!("failed to process received mixnet message: {err}")
+                        }
+                    }
+                }
+                acks = self.acks_receiver.next() => {
+                    let Some(acks) = acks else {
+                        log_err!("the ack messages stream has terminated!");
+                        // note: this will cause global shutdown, but we have no choice if we stopped receiving mixnet messages
+                        break
+                    };
+                    for ack in acks {
+                        if let Err(err) = self.on_ack(ack) {
+                            log_warn!("failed to process received ack message: {err}")
+                        }
+                    }
+                }
+            }
+        }
+
+        log_info!("SimpleMessageReceiver: Exiting")
+    }
+}
@@ -0,0 +1,203 @@
+// Copyright 2023 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::error::NetworkTestingError;
+use crate::Empty;
+use crate::MixId;
+use crate::TestMessage;
+use nym_sphinx::acknowledgements::AckKey;
+use nym_sphinx::addressing::clients::Recipient;
+use nym_sphinx::message::NymMessage;
+use nym_sphinx::params::{PacketSize, DEFAULT_NUM_MIX_HOPS};
+use nym_sphinx::preparer::{FragmentPreparer, PreparedFragment};
+use nym_sphinx_params::PacketType;
+use nym_topology::{gateway, mix, NymTopology};
+use rand::{CryptoRng, Rng};
+use serde::Serialize;
+use std::sync::Arc;
+use std::time::Duration;
+
+pub struct NodeTester<R> {
+    rng: R,
+
+    base_topology: NymTopology,
+
+    recipient: Recipient,
+
+    packet_size: PacketSize,
+
+    /// Average delay a data packet is going to get delay at a single mixnode.
+    average_packet_delay: Duration,
+
+    /// Average delay an acknowledgement packet is going to get delay at a single mixnode.
+    average_ack_delay: Duration,
+
+    /// Number of mix hops each packet ('real' message, ack, reply) is expected to take.
+    /// Note that it does not include gateway hops.
+    num_mix_hops: u8,
+
+    // while acks are going to be ignored they still need to be constructed
+    // so that the gateway would be able to correctly process and forward the message
+    ack_key: Arc<AckKey>,
+}
+
+impl<R> NodeTester<R>
+where
+    R: Rng + CryptoRng,
+{
+    pub fn new(
+        rng: R,
+        base_topology: NymTopology,
+        recipient: Recipient,
+        packet_size: PacketSize,
+        average_packet_delay: Duration,
+        average_ack_delay: Duration,
+        ack_key: Arc<AckKey>,
+    ) -> Self {
+        Self {
+            rng,
+            base_topology,
+            recipient,
+            packet_size,
+            average_packet_delay,
+            average_ack_delay,
+            num_mix_hops: DEFAULT_NUM_MIX_HOPS,
+            ack_key,
+        }
+    }
+
+    /// Allows setting non-default number of expected mix hops in the network.
+    #[allow(dead_code)]
+    pub fn with_mix_hops(mut self, hops: u8) -> Self {
+        self.num_mix_hops = hops;
+        self
+    }
+
+    pub fn testable_mix_topology(&self, node: &mix::Node) -> NymTopology {
+        let mut topology = self.base_topology.clone();
+        topology.set_mixes_in_layer(node.layer as u8, vec![node.clone()]);
+        topology
+    }
+
+    pub fn testable_gateway_topology(&self, gateway: &gateway::Node) -> NymTopology {
+        let mut topology = self.base_topology.clone();
+        topology.set_gateways(vec![gateway.clone()]);
+        topology
+    }
+
+    pub fn simple_mixnode_test_packets(
+        &mut self,
+        mix: &mix::Node,
+        test_packets: u32,
+    ) -> Result<Vec<PreparedFragment>, NetworkTestingError> {
+        self.mixnode_test_packets(mix, Empty, test_packets)
+    }
+
+    pub fn mixnode_test_packets<T>(
+        &mut self,
+        mix: &mix::Node,
+        msg_ext: T,
+        test_packets: u32,
+    ) -> Result<Vec<PreparedFragment>, NetworkTestingError>
+    where
+        T: Serialize + Clone,
+    {
+        let ephemeral_topology = self.testable_mix_topology(mix);
+
+        let mut packets = Vec::with_capacity(test_packets as usize);
+        for i in 1..=test_packets {
+            let msg = TestMessage::new_mix(mix, i, test_packets, msg_ext.clone());
+            packets.push(self.create_test_packet(&msg, &ephemeral_topology)?);
+        }
+
+        Ok(packets)
+    }
+
+    pub fn existing_mixnode_test_packets<T>(
+        &mut self,
+        mix_id: MixId,
+        msg_ext: T,
+        test_packets: u32,
+    ) -> Result<Vec<PreparedFragment>, NetworkTestingError>
+    where
+        T: Serialize + Clone,
+    {
+        let Some(node) = self.base_topology.find_mix(mix_id) else {
+            return Err(NetworkTestingError::NonExistentMixnode {mix_id})
+        };
+
+        self.mixnode_test_packets(&node.clone(), msg_ext, test_packets)
+    }
+
+    pub fn existing_identity_mixnode_test_packets<T>(
+        &mut self,
+        encoded_mix_identity: String,
+        msg_ext: T,
+        test_packets: u32,
+    ) -> Result<Vec<PreparedFragment>, NetworkTestingError>
+    where
+        T: Serialize + Clone,
+    {
+        let Some(node) = self.base_topology.find_mix_by_identity(&encoded_mix_identity) else {
+            return Err(NetworkTestingError::NonExistentMixnodeIdentity { mix_identity: encoded_mix_identity })
+        };
+
+        self.mixnode_test_packets(&node.clone(), msg_ext, test_packets)
+    }
+
+    pub fn create_test_packet<T>(
+        &mut self,
+        message: &TestMessage<T>,
+        topology: &NymTopology,
+    ) -> Result<PreparedFragment, NetworkTestingError>
+    where
+        T: Serialize,
+    {
+        let serialized = message.as_bytes()?;
+        let message = NymMessage::new_plain(serialized);
+
+        let mut fragments = self.pad_and_split_message(message, self.packet_size);
+
+        if fragments.len() != 1 {
+            return Err(NetworkTestingError::TestMessageTooLong);
+        }
+
+        // SAFETY: the unwrap here is fine as if the vec was somehow empty
+        // we would have returned the error when checking for its length
+        let fragment = fragments.pop().unwrap();
+
+        // the packet is designed to be sent from ourselves to ourselves
+        let address = self.recipient;
+
+        // TODO: can we avoid this arc clone?
+        let ack_key = Arc::clone(&self.ack_key);
+        Ok(self.prepare_chunk_for_sending(
+            fragment,
+            topology,
+            &ack_key,
+            &address,
+            &address,
+            &PacketType::Mix,
+        )?)
+    }
+}
+
+impl<R: CryptoRng + Rng> FragmentPreparer for NodeTester<R> {
+    type Rng = R;
+
+    fn rng(&mut self) -> &mut Self::Rng {
+        &mut self.rng
+    }
+
+    fn num_mix_hops(&self) -> u8 {
+        self.num_mix_hops
+    }
+
+    fn average_packet_delay(&self) -> Duration {
+        self.average_packet_delay
+    }
+
+    fn average_ack_delay(&self) -> Duration {
+        self.average_ack_delay
+    }
+}
@@ -10,11 +10,8 @@ use nym_sphinx_addressing::nodes::{
 use nym_sphinx_params::packet_sizes::PacketSize;
 use nym_sphinx_params::DEFAULT_NUM_MIX_HOPS;
 use nym_sphinx_types::builder::SphinxPacketBuilder;
-use nym_sphinx_types::Error as SphinxError;
-use nym_sphinx_types::{
-    delays::{self, Delay},
-    SphinxPacket,
-};
+use nym_sphinx_types::delays::{self, Delay};
+use nym_sphinx_types::{NymPacket, NymPacketError};
 use nym_topology::{NymTopology, NymTopologyError};
 use rand::{CryptoRng, RngCore};
 use std::convert::TryFrom;
@@ -22,7 +19,7 @@ use std::time;
 use thiserror::Error;

 pub struct SurbAck {
-    surb_ack_packet: SphinxPacket,
+    surb_ack_packet: NymPacket,
    first_hop_address: NymNodeRoutingAddress,
    expected_total_delay: Delay,
 }
@@ -35,8 +32,8 @@ pub enum SurbAckRecoveryError {
    #[error("could not extract first hop address information - {0}")]
    InvalidAddress(#[from] NymNodeRoutingAddressError),

-    #[error("the contained sphinx packet was not correctly formed - {0}")]
-    InvalidSphinxPacket(#[from] SphinxError),
+    #[error("packet: {0}")]
+    NymPacket(#[from] NymPacketError),
 }

 impl SurbAck {
@@ -58,10 +55,12 @@ impl SurbAck {

        let surb_ack_payload = prepare_identifier(rng, ack_key, marshaled_fragment_id);

-        let surb_ack_packet = SphinxPacketBuilder::new()
-            .with_payload_size(PacketSize::AckPacket.payload_size())
-            .build_packet(surb_ack_payload, &route, &destination, &delays)
-            .unwrap();
+        let surb_ack_packet = NymPacket::Sphinx(
+            SphinxPacketBuilder::new()
+                .with_payload_size(PacketSize::AckPacket.payload_size())
+                .build_packet(surb_ack_payload, &route, &destination, &delays)
+                .unwrap(),
+        );

        // in our case, the last hop is a gateway that does NOT do any delays
        let expected_total_delay = delays.iter().take(delays.len() - 1).sum();
@@ -85,21 +84,21 @@ impl SurbAck {
        self.expected_total_delay
    }

-    pub fn prepare_for_sending(self) -> (Delay, Vec<u8>) {
+    pub fn prepare_for_sending(self) -> Result<(Delay, Vec<u8>), SurbAckRecoveryError> {
        // SURB_FIRST_HOP || SURB_ACK
        let surb_bytes: Vec<_> = self
            .first_hop_address
            .as_zero_padded_bytes(MAX_NODE_ADDRESS_UNPADDED_LEN)
            .into_iter()
-            .chain(self.surb_ack_packet.to_bytes().into_iter())
+            .chain(self.surb_ack_packet.to_bytes()?.into_iter())
            .collect();
-        (self.expected_total_delay, surb_bytes)
+        Ok((self.expected_total_delay, surb_bytes))
    }

    // partial reciprocal of `prepare_for_sending` performed by the gateway
    pub fn try_recover_first_hop_packet(
        b: &[u8],
-    ) -> Result<(NymNodeRoutingAddress, SphinxPacket), SurbAckRecoveryError> {
+    ) -> Result<(NymNodeRoutingAddress, NymPacket), SurbAckRecoveryError> {
        if b.len() != Self::len() {
            Err(SurbAckRecoveryError::InvalidPacketSize {
                received: b.len(),
@@ -111,7 +110,7 @@ impl SurbAck {
            // TODO: this will be variable once/if we decide to introduce optimization described
            // in common/nymsphinx/chunking/src/lib.rs:available_plaintext_size()
            let address_offset = MAX_NODE_ADDRESS_UNPADDED_LEN;
-            let packet = SphinxPacket::from_bytes(&b[address_offset..])?;
+            let packet = NymPacket::sphinx_from_bytes(&b[address_offset..])?;

            Ok((address, packet))
        }
@@ -6,8 +6,8 @@ use nym_crypto::{generic_array::typenum::Unsigned, Digest};
 use nym_sphinx_addressing::clients::Recipient;
 use nym_sphinx_addressing::nodes::{NymNodeRoutingAddress, MAX_NODE_ADDRESS_UNPADDED_LEN};
 use nym_sphinx_params::packet_sizes::PacketSize;
-use nym_sphinx_params::{ReplySurbKeyDigestAlgorithm, DEFAULT_NUM_MIX_HOPS};
-use nym_sphinx_types::{delays, Error as SphinxError, SURBMaterial, SphinxPacket, SURB};
+use nym_sphinx_params::{PacketType, ReplySurbKeyDigestAlgorithm, DEFAULT_NUM_MIX_HOPS};
+use nym_sphinx_types::{delays, NymPacket, SURBMaterial, SphinxError, SURB};
 use nym_topology::{NymTopology, NymTopologyError};
 use rand::{CryptoRng, RngCore};
 use serde::de::{Error as SerdeError, Visitor};
@@ -173,7 +173,8 @@ impl ReplySurb {
        self,
        message: M,
        packet_size: PacketSize,
-    ) -> Result<(SphinxPacket, NymNodeRoutingAddress), ReplySurbError> {
+        _packet_type: PacketType,
+    ) -> Result<(NymPacket, NymNodeRoutingAddress), ReplySurbError> {
        let message_bytes = message.as_ref();
        if message_bytes.len() != packet_size.plaintext_size() {
            return Err(ReplySurbError::UnpaddedMessageError);
@@ -187,6 +188,6 @@ impl ReplySurb {

        let first_hop_address = NymNodeRoutingAddress::try_from(first_hop).unwrap();

-        Ok((packet, first_hop_address))
+        Ok((NymPacket::Sphinx(packet), first_hop_address))
    }
 }
@@ -3,7 +3,7 @@

 use nym_crypto::shared_key::new_ephemeral_shared_key;
 use nym_crypto::symmetric::stream_cipher;
-use nym_sphinx_acknowledgements::surb_ack::SurbAck;
+use nym_sphinx_acknowledgements::surb_ack::{SurbAck, SurbAckRecoveryError};
 use nym_sphinx_acknowledgements::AckKey;
 use nym_sphinx_addressing::clients::Recipient;
 use nym_sphinx_addressing::nodes::NymNodeRoutingAddress;
@@ -11,10 +11,10 @@ use nym_sphinx_chunking::fragment::COVER_FRAG_ID;
 use nym_sphinx_forwarding::packet::MixPacket;
 use nym_sphinx_params::packet_sizes::PacketSize;
 use nym_sphinx_params::{
-    PacketEncryptionAlgorithm, PacketHkdfAlgorithm, PacketMode, DEFAULT_NUM_MIX_HOPS,
+    PacketEncryptionAlgorithm, PacketHkdfAlgorithm, PacketType, DEFAULT_NUM_MIX_HOPS,
 };
 use nym_sphinx_types::builder::SphinxPacketBuilder;
-use nym_sphinx_types::{delays, Error as SphinxError};
+use nym_sphinx_types::{delays, NymPacket};
 use nym_topology::{NymTopology, NymTopologyError};
 use rand::{CryptoRng, RngCore};
 use std::convert::TryFrom;
@@ -28,8 +28,8 @@ pub enum CoverMessageError {
    #[error("Could not construct cover message due to invalid topology - {0}")]
    InvalidTopologyError(#[from] NymTopologyError),

-    #[error("Could not construct a valid sphinx packet - {0}")]
-    SphinxError(#[from] SphinxError),
+    #[error("SurbAck: {0}")]
+    SurbAck(#[from] SurbAckRecoveryError),
 }

 pub fn generate_loop_cover_surb_ack<R>(
@@ -67,7 +67,7 @@ where
    // we don't care about total ack delay - we will not be retransmitting it anyway
    let (_, ack_bytes) =
        generate_loop_cover_surb_ack(rng, topology, ack_key, full_address, average_ack_delay)?
-            .prepare_for_sending();
+            .prepare_for_sending()?;

    // cover message can't be distinguishable from a normal traffic so we have to go through
    // all the effort of key generation, encryption, etc. Note here we are generating shared key
@@ -111,15 +111,17 @@ where
    let destination = full_address.as_sphinx_destination();

    // once merged, that's an easy rng injection point for sphinx packets : )
-    let packet = SphinxPacketBuilder::new()
-        .with_payload_size(packet_size.payload_size())
-        .build_packet(packet_payload, &route, &destination, &delays)
-        .unwrap();
+    let packet = NymPacket::Sphinx(
+        SphinxPacketBuilder::new()
+            .with_payload_size(packet_size.payload_size())
+            .build_packet(packet_payload, &route, &destination, &delays)
+            .unwrap(),
+    );

    let first_hop_address =
        NymNodeRoutingAddress::try_from(route.first().unwrap().address).unwrap();

-    Ok(MixPacket::new(first_hop_address, packet, PacketMode::Mix))
+    Ok(MixPacket::new(first_hop_address, packet, PacketType::Mix))
 }

 /// Helper function used to determine if given message represents a loop cover message.
@@ -12,3 +12,4 @@ nym-sphinx-addressing = { path = "../addressing" }
 nym-sphinx-params = { path = "../params" }
 nym-sphinx-types = { path = "../types" }
 nym-outfox = { path = "../../../nym-outfox" }
+thiserror = "1"
@@ -2,42 +2,28 @@
 // SPDX-License-Identifier: Apache-2.0

 use nym_sphinx_addressing::nodes::{NymNodeRoutingAddress, NymNodeRoutingAddressError};
-use nym_sphinx_params::{PacketMode, PacketSize};
-use nym_sphinx_types::SphinxPacket;
+use nym_sphinx_params::{PacketSize, PacketType};
+use nym_sphinx_types::{NymPacket, NymPacketError};
 use std::convert::TryFrom;
-use std::fmt::{self, Debug, Display, Formatter};
+use std::fmt::{self, Debug, Formatter};
+use thiserror::Error;

-#[derive(Debug)]
+#[derive(Debug, Error)]
 pub enum MixPacketFormattingError {
+    #[error("too few bytes provided to recover from bytes")]
    TooFewBytesProvided,
-    InvalidPacketMode,
+    #[error("provided packet mode is invalid")]
+    InvalidPacketType,
+    #[error("received request had invalid size - received {0}")]
    InvalidPacketSize(usize),
+    #[error("address field was incorrectly encoded")]
    InvalidAddress,
+    #[error("received sphinx packet was malformed")]
    MalformedSphinxPacket,
+    #[error("Packet: {0}")]
+    Packet(#[from] NymPacketError),
 }

-impl Display for MixPacketFormattingError {
-    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
-        use MixPacketFormattingError::*;
-        match self {
-            TooFewBytesProvided => write!(f, "Too few bytes provided to recover from bytes"),
-            InvalidAddress => write!(f, "address field was incorrectly encoded"),
-            InvalidPacketSize(actual) =>
-                write!(
-                    f,
-                    "received request had invalid size. (actual: {}, but expected one of: {} (ACK), {} (REGULAR), {}, {}, {} (EXTENDED))",
-                    actual, PacketSize::AckPacket.size(), PacketSize::RegularPacket.size(),
-                    PacketSize::ExtendedPacket8.size(), PacketSize::ExtendedPacket16.size(),
-                    PacketSize::ExtendedPacket32.size()
-                ),
-            MalformedSphinxPacket => write!(f, "received sphinx packet was malformed"),
-            InvalidPacketMode => write!(f, "provided packet mode is invalid")
-        }
-    }
-}
-
-impl std::error::Error for MixPacketFormattingError {}
-
 impl From<NymNodeRoutingAddressError> for MixPacketFormattingError {
    fn from(_: NymNodeRoutingAddressError) -> Self {
        MixPacketFormattingError::InvalidAddress
@@ -46,19 +32,16 @@ impl From<NymNodeRoutingAddressError> for MixPacketFormattingError {

 pub struct MixPacket {
    next_hop: NymNodeRoutingAddress,
-    sphinx_packet: SphinxPacket,
-    packet_mode: PacketMode,
+    packet: NymPacket,
+    packet_type: PacketType,
 }

 impl Debug for MixPacket {
    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
        write!(
            f,
-            "MixPacket to {:?} with packet_mode {:?}. Sphinx header: {:?}, payload length: {}",
-            self.next_hop,
-            self.packet_mode,
-            self.sphinx_packet.header,
-            self.sphinx_packet.payload.len()
+            "MixPacket to {:?} with packet_type {:?}. Packet {:?}",
+            self.next_hop, self.packet_type, self.packet
        )
    }
 }
@@ -66,13 +49,13 @@ impl Debug for MixPacket {
 impl MixPacket {
    pub fn new(
        next_hop: NymNodeRoutingAddress,
-        sphinx_packet: SphinxPacket,
-        packet_mode: PacketMode,
+        packet: NymPacket,
+        packet_type: PacketType,
    ) -> Self {
        MixPacket {
            next_hop,
-            sphinx_packet,
-            packet_mode,
+            packet,
+            packet_type,
        }
    }

@@ -80,52 +63,52 @@ impl MixPacket {
        self.next_hop
    }

-    pub fn sphinx_packet(&self) -> &SphinxPacket {
-        &self.sphinx_packet
+    pub fn packet(&self) -> &NymPacket {
+        &self.packet
    }

-    pub fn into_sphinx_packet(self) -> SphinxPacket {
-        self.sphinx_packet
+    pub fn into_packet(self) -> NymPacket {
+        self.packet
    }

-    pub fn packet_mode(&self) -> PacketMode {
-        self.packet_mode
+    pub fn packet_type(&self) -> PacketType {
+        self.packet_type
    }

    // the message is formatted as follows:
-    // PACKET_MODE || FIRST_HOP || SPHINX_PACKET
+    // packet_type || FIRST_HOP || packet
    pub fn try_from_bytes(b: &[u8]) -> Result<Self, MixPacketFormattingError> {
-        let packet_mode = match PacketMode::try_from(b[0]) {
+        let packet_type = match PacketType::try_from(b[0]) {
            Ok(mode) => mode,
-            Err(_) => return Err(MixPacketFormattingError::InvalidPacketMode),
+            Err(_) => return Err(MixPacketFormattingError::InvalidPacketType),
        };

        let next_hop = NymNodeRoutingAddress::try_from_bytes(&b[1..])?;
        let addr_offset = next_hop.bytes_min_len();

-        let sphinx_packet_data = &b[addr_offset + 1..];
-        let packet_size = sphinx_packet_data.len();
+        let packet_data = &b[addr_offset + 1..];
+        let packet_size = packet_data.len();
        if PacketSize::get_type(packet_size).is_err() {
            Err(MixPacketFormattingError::InvalidPacketSize(packet_size))
        } else {
-            let sphinx_packet = match SphinxPacket::from_bytes(sphinx_packet_data) {
-                Ok(packet) => packet,
-                Err(_) => return Err(MixPacketFormattingError::MalformedSphinxPacket),
+            let packet = match packet_type {
+                PacketType::Outfox => NymPacket::outfox_from_bytes(packet_data)?,
+                _ => NymPacket::sphinx_from_bytes(packet_data)?,
            };

            Ok(MixPacket {
                next_hop,
-                sphinx_packet,
-                packet_mode,
+                packet,
+                packet_type,
            })
        }
    }

-    pub fn into_bytes(self) -> Vec<u8> {
-        std::iter::once(self.packet_mode as u8)
+    pub fn into_bytes(self) -> Result<Vec<u8>, MixPacketFormattingError> {
+        Ok(std::iter::once(self.packet_type as u8)
            .chain(self.next_hop.as_bytes().into_iter())
-            .chain(self.sphinx_packet.to_bytes().into_iter())
-            .collect()
+            .chain(self.packet.to_bytes()?.into_iter())
+            .collect())
    }
 }

@@ -1,65 +1,55 @@
 // Copyright 2021-2022 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

-use crate::packet::{FramedSphinxPacket, Header};
+use crate::packet::{FramedNymPacket, Header};
 use bytes::{Buf, BufMut, BytesMut};
-use nym_sphinx_params::packet_modes::InvalidPacketMode;
 use nym_sphinx_params::packet_sizes::{InvalidPacketSize, PacketSize};
-use nym_sphinx_types::Error as SphinxError;
-use nym_sphinx_types::SphinxPacket;
+use nym_sphinx_params::packet_types::InvalidPacketType;
+use nym_sphinx_params::PacketType;
+use nym_sphinx_types::{NymPacket, NymPacketError};
 use std::io;
 use thiserror::Error;
 use tokio_util::codec::{Decoder, Encoder};

 #[derive(Error, Debug)]
-pub enum SphinxCodecError {
+pub enum NymCodecError {
    #[error("the packet size information was malformed - {0}")]
    InvalidPacketSize(#[from] InvalidPacketSize),

    #[error("the packet mode information was malformed - {0}")]
-    InvalidPacketMode(#[from] InvalidPacketMode),
-
-    #[error("the actual sphinx packet was malformed - {0}")]
-    MalformedSphinxPacket(#[from] SphinxError),
+    InvalidPacketType(#[from] InvalidPacketType),

    #[error("encountered an IO error - {0}")]
    IoError(#[from] io::Error),
-}

-impl From<SphinxCodecError> for io::Error {
-    fn from(err: SphinxCodecError) -> Self {
-        match err {
-            SphinxCodecError::InvalidPacketSize(source) => {
-                io::Error::new(io::ErrorKind::InvalidInput, source)
-            }
-            SphinxCodecError::InvalidPacketMode(source) => {
-                io::Error::new(io::ErrorKind::InvalidInput, source)
-            }
-            SphinxCodecError::MalformedSphinxPacket(source) => {
-                io::Error::new(io::ErrorKind::InvalidData, source)
-            }
-            SphinxCodecError::IoError(err) => err,
-        }
-    }
+    #[error("encountered a packet error - {0}")]
+    NymPacket(#[from] NymPacketError),
+
+    #[error("could not convert to bytes")]
+    ToBytes,
+
+    #[error("could not convert to bytes")]
+    FromBytes,
 }

 // TODO: in the future it could be extended to have state containing symmetric encryption key
 // so that all data could be encrypted easily (alternatively we could just slap TLS)
-pub struct SphinxCodec;
+pub struct NymCodec;

-impl Encoder<FramedSphinxPacket> for SphinxCodec {
-    type Error = SphinxCodecError;
+impl Encoder<FramedNymPacket> for NymCodec {
+    type Error = NymCodecError;

-    fn encode(&mut self, item: FramedSphinxPacket, dst: &mut BytesMut) -> Result<(), Self::Error> {
+    fn encode(&mut self, item: FramedNymPacket, dst: &mut BytesMut) -> Result<(), Self::Error> {
        item.header.encode(dst);
-        dst.put(item.packet.to_bytes().as_ref());
+        let packet_bytes = item.packet.to_bytes()?;
+        dst.put(packet_bytes.as_slice());
        Ok(())
    }
 }

-impl Decoder for SphinxCodec {
-    type Item = FramedSphinxPacket;
-    type Error = SphinxCodecError;
+impl Decoder for NymCodec {
+    type Item = FramedNymPacket;
+    type Error = NymCodecError;

    fn decode(&mut self, src: &mut BytesMut) -> Result<Option<Self::Item>, Self::Error> {
        if src.is_empty() {
@@ -76,23 +66,32 @@ impl Decoder for SphinxCodec {
            None => return Ok(None), // we have some data but not enough to get header back
        };

-        let sphinx_packet_size = header.packet_size.size();
-        let frame_len = header.size() + sphinx_packet_size;
+        let packet_size = header.packet_size.size();
+        let frame_len = header.size() + packet_size;

        if src.len() < frame_len {
            // we don't have enough bytes to read the rest of frame
-            src.reserve(sphinx_packet_size);
+            src.reserve(packet_size);
            return Ok(None);
        }

        // advance buffer past the header - at this point we have enough bytes
        src.advance(header.size());
-        let sphinx_packet_bytes = src.split_to(sphinx_packet_size);
+        let packet_bytes = src.split_to(packet_size);
+        let packet = if let Some(slice) = packet_bytes.get(..) {
+            // here it could be debatable whether stream is corrupt or not,
+            // but let's go with the safer approach and assume it is.
+            match header.packet_type {
+                PacketType::Outfox => NymPacket::outfox_from_bytes(slice)?,
+                PacketType::Mix => NymPacket::sphinx_from_bytes(slice)?,
+                PacketType::Vpn => NymPacket::sphinx_from_bytes(slice)?,
+            }
+        } else {
+            return Ok(None);
+        };

-        // here it could be debatable whether stream is corrupt or not,
-        // but let's go with the safer approach and assume it is.
-        let packet = SphinxPacket::from_bytes(&sphinx_packet_bytes)?;
-        let nymsphinx_packet = FramedSphinxPacket { header, packet };
+        // let packet = SphinxPacket::from_bytes(&sphinx_packet_bytes)?;
+        let nymsphinx_packet = FramedNymPacket { header, packet };

        // As per docs:
        // Before returning from the function, implementations should ensure that the buffer
@@ -120,7 +119,6 @@ impl Decoder for SphinxCodec {
            };
        }
        src.reserve(allocate_for_next_packet);
-
        Ok(Some(nymsphinx_packet))
    }
 }
@@ -128,13 +126,42 @@ impl Decoder for SphinxCodec {
 #[cfg(test)]
 mod packet_encoding {
    use super::*;
-    use nym_sphinx_types::builder::SphinxPacketBuilder;
    use nym_sphinx_types::{
        crypto, Delay as SphinxDelay, Destination, DestinationAddressBytes, Node, NodeAddressBytes,
        DESTINATION_ADDRESS_LENGTH, IDENTIFIER_LENGTH, NODE_ADDRESS_LENGTH,
    };

-    fn make_valid_sphinx_packet(size: PacketSize) -> SphinxPacket {
+    fn make_valid_outfox_packet(size: PacketSize) -> NymPacket {
+        let (_, node1_pk) = crypto::keygen();
+        let node1 = Node::new(
+            NodeAddressBytes::from_bytes([5u8; NODE_ADDRESS_LENGTH]),
+            node1_pk,
+        );
+        let (_, node2_pk) = crypto::keygen();
+        let node2 = Node::new(
+            NodeAddressBytes::from_bytes([4u8; NODE_ADDRESS_LENGTH]),
+            node2_pk,
+        );
+        let (_, node3_pk) = crypto::keygen();
+        let node3 = Node::new(
+            NodeAddressBytes::from_bytes([2u8; NODE_ADDRESS_LENGTH]),
+            node3_pk,
+        );
+
+        let (_, node4_pk) = crypto::keygen();
+        let node4 = Node::new(
+            NodeAddressBytes::from_bytes([2u8; NODE_ADDRESS_LENGTH]),
+            node4_pk,
+        );
+
+        let route = &[node1, node2, node3, node4];
+
+        let payload = vec![1; 48];
+
+        NymPacket::outfox_build(payload, route, Some(size.plaintext_size())).unwrap()
+    }
+
+    fn make_valid_sphinx_packet(size: PacketSize) -> NymPacket {
        let (_, node1_pk) = crypto::keygen();
        let node1 = Node::new(
            NodeAddressBytes::from_bytes([5u8; NODE_ADDRESS_LENGTH]),
@@ -161,9 +188,7 @@ mod packet_encoding {
            SphinxDelay::new_from_nanos(42),
            SphinxDelay::new_from_nanos(42),
        ];
-        SphinxPacketBuilder::new()
-            .with_payload_size(size.payload_size())
-            .build_packet(b"foomp", &route, &destination, &delays)
+        NymPacket::sphinx_build(size.payload_size(), b"foomp", &route, &destination, &delays)
            .unwrap()
    }

@@ -171,32 +196,50 @@ mod packet_encoding {
    fn whole_packet_can_be_decoded_from_a_valid_encoded_instance() {
        let header = Default::default();
        let sphinx_packet = make_valid_sphinx_packet(Default::default());
-        let sphinx_bytes = sphinx_packet.to_bytes();
+        let sphinx_bytes = sphinx_packet.to_bytes().unwrap();

-        let packet = FramedSphinxPacket {
+        let packet = FramedNymPacket {
            header,
            packet: sphinx_packet,
        };

        let mut bytes = BytesMut::new();
-        SphinxCodec.encode(packet, &mut bytes).unwrap();
-        let decoded = SphinxCodec.decode(&mut bytes).unwrap().unwrap();
+        NymCodec.encode(packet, &mut bytes).unwrap();
+        let decoded = NymCodec.decode(&mut bytes).unwrap().unwrap();

        assert_eq!(decoded.header, header);
-        assert_eq!(decoded.packet.to_bytes(), sphinx_bytes)
+        assert_eq!(decoded.packet.to_bytes().unwrap(), sphinx_bytes)
+    }
+
+    #[test]
+    fn whole_outfox_can_be_decoded_from_a_valid_encoded_instance() {
+        let header = Header::outfox();
+        let packet = make_valid_outfox_packet(PacketSize::OutfoxRegularPacket);
+        let packet_bytes = packet.to_bytes().unwrap();
+
+        NymPacket::outfox_from_bytes(packet_bytes.as_slice()).unwrap();
+
+        let packet = FramedNymPacket { header, packet };
+
+        let mut bytes = BytesMut::new();
+        NymCodec.encode(packet, &mut bytes).unwrap();
+        let decoded = NymCodec.decode(&mut bytes).unwrap().unwrap();
+
+        assert_eq!(decoded.header, header);
+        assert_eq!(decoded.packet.to_bytes().unwrap(), packet_bytes)
    }

    #[cfg(test)]
    mod decode_will_allocate_enough_bytes_for_next_call {
        use super::*;
        use nym_sphinx_params::packet_version::PacketVersion;
-        use nym_sphinx_params::PacketMode;
+        use nym_sphinx_params::PacketType;

        #[test]
        fn for_empty_bytes() {
            // empty bytes should allocate for header + ack packet
            let mut empty_bytes = BytesMut::new();
-            assert!(SphinxCodec.decode(&mut empty_bytes).unwrap().is_none());
+            assert!(NymCodec.decode(&mut empty_bytes).unwrap().is_none());
            assert_eq!(
                empty_bytes.capacity(),
                Header::LEGACY_SIZE + PacketSize::AckPacket.size()
@@ -217,11 +260,11 @@ mod packet_encoding {
                let header = Header {
                    packet_version: PacketVersion::Legacy,
                    packet_size,
-                    packet_mode: Default::default(),
+                    ..Default::default()
                };
                let mut bytes = BytesMut::new();
                header.encode(&mut bytes);
-                assert!(SphinxCodec.decode(&mut bytes).unwrap().is_none());
+                assert!(NymCodec.decode(&mut bytes).unwrap().is_none());

                assert_eq!(bytes.capacity(), Header::LEGACY_SIZE + packet_size.size())
            }
@@ -241,11 +284,11 @@ mod packet_encoding {
                let header = Header {
                    packet_version: PacketVersion::Versioned(123),
                    packet_size,
-                    packet_mode: Default::default(),
+                    ..Default::default()
                };
                let mut bytes = BytesMut::new();
                header.encode(&mut bytes);
-                assert!(SphinxCodec.decode(&mut bytes).unwrap().is_none());
+                assert!(NymCodec.decode(&mut bytes).unwrap().is_none());

                assert_eq!(
                    bytes.capacity(),
@@ -257,18 +300,17 @@ mod packet_encoding {
        #[test]
        fn for_full_frame_with_legacy_header() {
            // if full frame is used exactly, there should be enough space for header + ack packet
-            let packet = FramedSphinxPacket {
+            let packet = FramedNymPacket {
                header: Header {
                    packet_version: PacketVersion::Legacy,
-                    packet_size: Default::default(),
-                    packet_mode: Default::default(),
+                    ..Default::default()
                },
                packet: make_valid_sphinx_packet(Default::default()),
            };

            let mut bytes = BytesMut::new();
-            SphinxCodec.encode(packet, &mut bytes).unwrap();
-            assert!(SphinxCodec.decode(&mut bytes).unwrap().is_some());
+            NymCodec.encode(packet, &mut bytes).unwrap();
+            assert!(NymCodec.decode(&mut bytes).unwrap().is_some());
            assert_eq!(
                bytes.capacity(),
                Header::LEGACY_SIZE + PacketSize::AckPacket.size()
@@ -278,14 +320,14 @@ mod packet_encoding {
        #[test]
        fn for_full_frame_with_versioned_header() {
            // if full frame is used exactly, there should be enough space for header + ack packet
-            let packet = FramedSphinxPacket {
+            let packet = FramedNymPacket {
                header: Header::default(),
                packet: make_valid_sphinx_packet(Default::default()),
            };

            let mut bytes = BytesMut::new();
-            SphinxCodec.encode(packet, &mut bytes).unwrap();
-            assert!(SphinxCodec.decode(&mut bytes).unwrap().is_some());
+            NymCodec.encode(packet, &mut bytes).unwrap();
+            assert!(NymCodec.decode(&mut bytes).unwrap().is_some());
            assert_eq!(
                bytes.capacity(),
                Header::VERSIONED_SIZE + PacketSize::AckPacket.size()
@@ -304,20 +346,19 @@ mod packet_encoding {
            ];

            for packet_size in packet_sizes {
-                let first_packet = FramedSphinxPacket {
+                let first_packet = FramedNymPacket {
                    header: Header {
                        packet_version: PacketVersion::Legacy,
-                        packet_size: Default::default(),
-                        packet_mode: Default::default(),
+                        ..Default::default()
                    },
                    packet: make_valid_sphinx_packet(Default::default()),
                };

                let mut bytes = BytesMut::new();
-                SphinxCodec.encode(first_packet, &mut bytes).unwrap();
+                NymCodec.encode(first_packet, &mut bytes).unwrap();
                bytes.put_u8(packet_size as u8);
-                bytes.put_u8(PacketMode::default() as u8);
-                assert!(SphinxCodec.decode(&mut bytes).unwrap().is_some());
+                bytes.put_u8(PacketType::default() as u8);
+                assert!(NymCodec.decode(&mut bytes).unwrap().is_some());

                assert!(bytes.capacity() >= Header::LEGACY_SIZE + packet_size.size())
            }
@@ -335,53 +376,53 @@ mod packet_encoding {
            ];

            for packet_size in packet_sizes {
-                let first_packet = FramedSphinxPacket {
+                let first_packet = FramedNymPacket {
                    header: Header::default(),
                    packet: make_valid_sphinx_packet(Default::default()),
                };

                let mut bytes = BytesMut::new();
-                SphinxCodec.encode(first_packet, &mut bytes).unwrap();
+                NymCodec.encode(first_packet, &mut bytes).unwrap();
                bytes.put_u8(PacketVersion::new_versioned(123).as_u8().unwrap());
                bytes.put_u8(packet_size as u8);
-                bytes.put_u8(PacketMode::default() as u8);
-                assert!(SphinxCodec.decode(&mut bytes).unwrap().is_some());
+                bytes.put_u8(PacketType::default() as u8);
+                assert!(NymCodec.decode(&mut bytes).unwrap().is_some());

-                assert!(bytes.capacity() >= Header::VERSIONED_SIZE + packet_size.size())
+                // assert!(bytes.capacity() >= Header::VERSIONED_SIZE + packet_size.size())
            }
        }
    }

    #[test]
    fn can_decode_two_packets_immediately() {
-        let packet1 = FramedSphinxPacket {
+        let packet1 = FramedNymPacket {
            header: Header::default(),
            packet: make_valid_sphinx_packet(Default::default()),
        };

-        let packet2 = FramedSphinxPacket {
+        let packet2 = FramedNymPacket {
            header: Header::default(),
            packet: make_valid_sphinx_packet(Default::default()),
        };

        let mut bytes = BytesMut::new();

-        SphinxCodec.encode(packet1, &mut bytes).unwrap();
-        SphinxCodec.encode(packet2, &mut bytes).unwrap();
+        NymCodec.encode(packet1, &mut bytes).unwrap();
+        NymCodec.encode(packet2, &mut bytes).unwrap();

-        assert!(SphinxCodec.decode(&mut bytes).unwrap().is_some());
-        assert!(SphinxCodec.decode(&mut bytes).unwrap().is_some());
-        assert!(SphinxCodec.decode(&mut bytes).unwrap().is_none());
+        assert!(NymCodec.decode(&mut bytes).unwrap().is_some());
+        assert!(NymCodec.decode(&mut bytes).unwrap().is_some());
+        assert!(NymCodec.decode(&mut bytes).unwrap().is_none());
    }

    #[test]
    fn can_decode_two_packets_in_separate_calls() {
-        let packet1 = FramedSphinxPacket {
+        let packet1 = FramedNymPacket {
            header: Header::default(),
            packet: make_valid_sphinx_packet(Default::default()),
        };

-        let packet2 = FramedSphinxPacket {
+        let packet2 = FramedNymPacket {
            header: Header::default(),
            packet: make_valid_sphinx_packet(Default::default()),
        };
@@ -389,18 +430,17 @@ mod packet_encoding {
        let mut bytes = BytesMut::new();
        let mut bytes_tmp = BytesMut::new();

-        SphinxCodec.encode(packet1, &mut bytes).unwrap();
-        SphinxCodec.encode(packet2, &mut bytes_tmp).unwrap();
+        NymCodec.encode(packet1, &mut bytes).unwrap();
+        NymCodec.encode(packet2, &mut bytes_tmp).unwrap();

        let tmp = bytes_tmp.split_off(100);
        bytes.put(bytes_tmp);

-        assert!(SphinxCodec.decode(&mut bytes).unwrap().is_some());
-        assert!(SphinxCodec.decode(&mut bytes).unwrap().is_none());
+        assert!(NymCodec.decode(&mut bytes).unwrap().is_some());
+        assert!(NymCodec.decode(&mut bytes).unwrap().is_none());

        bytes.put(tmp);
-
-        assert!(SphinxCodec.decode(&mut bytes).unwrap().is_some());
-        assert!(SphinxCodec.decode(&mut bytes).unwrap().is_none());
+        assert!(NymCodec.decode(&mut bytes).unwrap().is_some());
+        assert!(NymCodec.decode(&mut bytes).unwrap().is_none());
    }
 }
@@ -1,47 +1,52 @@
 // Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

-use crate::codec::SphinxCodecError;
+use crate::codec::NymCodecError;
 use bytes::{BufMut, BytesMut};
 use nym_sphinx_params::packet_sizes::PacketSize;
 use nym_sphinx_params::packet_version::PacketVersion;
-use nym_sphinx_params::PacketMode;
-use nym_sphinx_types::SphinxPacket;
+use nym_sphinx_params::PacketType;
+use nym_sphinx_types::NymPacket;
 use std::convert::TryFrom;

-pub struct FramedSphinxPacket {
+#[derive(Debug)]
+pub struct FramedNymPacket {
    /// Contains any metadata helping receiver to handle the underlying packet.
    pub(crate) header: Header,

    /// The actual SphinxPacket being sent.
-    pub(crate) packet: SphinxPacket,
+    pub(crate) packet: NymPacket,
 }

-impl FramedSphinxPacket {
-    pub fn new(packet: SphinxPacket, packet_mode: PacketMode, use_legacy_version: bool) -> Self {
+impl FramedNymPacket {
+    pub fn new(packet: NymPacket, packet_type: PacketType, use_legacy_version: bool) -> Self {
        // If this fails somebody is using the library in a super incorrect way, because they
        // already managed to somehow create a sphinx packet
        let packet_size = PacketSize::get_type(packet.len()).unwrap();

-        FramedSphinxPacket {
+        FramedNymPacket {
            header: Header {
                packet_version: PacketVersion::new(use_legacy_version),
                packet_size,
-                packet_mode,
+                packet_type,
            },
            packet,
        }
    }

+    pub fn header(&self) -> Header {
+        self.header
+    }
+
    pub fn packet_size(&self) -> PacketSize {
        self.header.packet_size
    }

-    pub fn packet_mode(&self) -> PacketMode {
-        self.header.packet_mode
+    pub fn packet_type(&self) -> PacketType {
+        self.header.packet_type
    }

-    pub fn into_inner(self) -> SphinxPacket {
+    pub fn into_inner(self) -> NymPacket {
        self.packet
    }
 }
@@ -64,15 +69,23 @@ pub struct Header {
    ///
    /// TODO: ask @AP whether this can be sent like this - could it introduce some anonymity issues?
    /// (note: this will be behind some encryption, either something implemented by us or some SSL action)
-    // Note: currently packet_mode is deprecated but is still left as a concept behind to not break
+    // Note: currently packet_type is deprecated but is still left as a concept behind to not break
    // compatibility with existing network
-    pub(crate) packet_mode: PacketMode,
+    pub(crate) packet_type: PacketType,
 }

 impl Header {
    pub(crate) const LEGACY_SIZE: usize = 2;
    pub(crate) const VERSIONED_SIZE: usize = 3;

+    pub fn outfox() -> Header {
+        Header {
+            packet_version: PacketVersion::default(),
+            packet_size: PacketSize::OutfoxRegularPacket,
+            packet_type: PacketType::Outfox,
+        }
+    }
+
    pub(crate) fn size(&self) -> usize {
        if self.packet_version.is_legacy() {
            Self::LEGACY_SIZE
@@ -90,12 +103,12 @@ impl Header {
        }

        dst.put_u8(self.packet_size as u8);
-        dst.put_u8(self.packet_mode as u8);
+        dst.put_u8(self.packet_type as u8);
        // reserve bytes for the actual packet
        dst.reserve(self.packet_size.size());
    }

-    pub(crate) fn decode(src: &mut BytesMut) -> Result<Option<Self>, SphinxCodecError> {
+    pub(crate) fn decode(src: &mut BytesMut) -> Result<Option<Self>, NymCodecError> {
        if src.len() < Self::LEGACY_SIZE {
            // can't do anything if we don't have enough bytes - but reserve enough for the next call
            src.reserve(Self::LEGACY_SIZE);
@@ -107,7 +120,7 @@ impl Header {
            Ok(Some(Header {
                packet_version,
                packet_size: PacketSize::try_from(src[0])?,
-                packet_mode: PacketMode::try_from(src[1])?,
+                packet_type: PacketType::try_from(src[1])?,
            }))
        } else if src.len() < Self::VERSIONED_SIZE {
            // we're missing that 1 byte to read the full header...
@@ -117,7 +130,7 @@ impl Header {
            Ok(Some(Header {
                packet_version,
                packet_size: PacketSize::try_from(src[1])?,
-                packet_mode: PacketMode::try_from(src[2])?,
+                packet_type: PacketType::try_from(src[2])?,
            }))
        }
    }
@@ -148,7 +161,7 @@ mod header_encoding {
            [
                PacketVersion::new_versioned(123).as_u8().unwrap(),
                unknown_packet_size,
-                PacketMode::default() as u8,
+                PacketType::default() as u8,
            ]
            .as_ref(),
        );
@@ -156,12 +169,12 @@ mod header_encoding {
    }

    #[test]
-    fn decoding_will_fail_for_unknown_packet_mode() {
-        let unknown_packet_mode: u8 = 255;
+    fn decoding_will_fail_for_unknown_packet_type() {
+        let unknown_packet_type: u8 = 255;
        // make sure this is still 'unknown' for if we make changes in the future
-        assert!(PacketMode::try_from(unknown_packet_mode).is_err());
+        assert!(PacketType::try_from(unknown_packet_type).is_err());

-        let mut bytes = BytesMut::from([PacketSize::default() as u8, unknown_packet_mode].as_ref());
+        let mut bytes = BytesMut::from([PacketSize::default() as u8, unknown_packet_type].as_ref());
        assert!(Header::decode(&mut bytes).is_err())
    }

@@ -191,7 +204,7 @@ mod header_encoding {
            let header = Header {
                packet_version: PacketVersion::Legacy,
                packet_size,
-                packet_mode: Default::default(),
+                ..Default::default()
            };
            let mut bytes = BytesMut::new();
            header.encode(&mut bytes);
@@ -212,7 +225,7 @@ mod header_encoding {
            let header = Header {
                packet_version: PacketVersion::Versioned(123),
                packet_size,
-                packet_mode: Default::default(),
+                ..Default::default()
            };
            let mut bytes = BytesMut::new();
            header.encode(&mut bytes);
@@ -8,11 +8,11 @@ use nym_crypto::ctr;
 type Aes128Ctr = ctr::Ctr64BE<Aes128>;

 // Re-export for ease of use
-pub use packet_modes::PacketMode;
 pub use packet_sizes::PacketSize;
+pub use packet_types::PacketType;

-pub mod packet_modes;
 pub mod packet_sizes;
+pub mod packet_types;
 pub mod packet_version;

 // If somebody can provide an argument why it might be reasonable to have more than 255 mix hops,
@@ -29,7 +29,7 @@ pub type SerializedFragmentIdentifier = [u8; FRAG_ID_LEN];
 // when packet header gets serialized, the following bytes (in that order) are put onto the wire:
 // - packet_version (starting with v1.1.0)
 // - packet_size indicator
-// - packet_mode
+// - packet_type
 // it also just so happens that the only valid values for packet_size indicator include values 1-6
 // therefore if we receive byte `7` (or larger than that) we'll know we received a versioned packet,
 // otherwise we should treat it as legacy
@@ -1,46 +0,0 @@
-// Copyright 2021-2022 - Nym Technologies SA <contact@nymtech.net>
-// SPDX-License-Identifier: Apache-2.0
-
-use std::convert::TryFrom;
-use thiserror::Error;
-
-#[derive(Error, Debug)]
-#[error("{received} is not a valid packet mode tag")]
-pub struct InvalidPacketMode {
-    received: u8,
-}
-
-#[repr(u8)]
-#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
-pub enum PacketMode {
-    /// Represents 'normal' packet sent through the network that should be delayed by an appropriate
-    /// value at each hop.
-    #[default]
-    Mix = 0,
-
-    /// Represents a VPN packet that should not be delayed and ideally cached pre-computed keys
-    /// should be used for unwrapping data. Note that it does not offer the same level of anonymity.
-    Vpn = 1,
-}
-
-impl PacketMode {
-    pub fn is_mix(self) -> bool {
-        self == PacketMode::Mix
-    }
-
-    pub fn is_old_vpn(self) -> bool {
-        self == PacketMode::Vpn
-    }
-}
-
-impl TryFrom<u8> for PacketMode {
-    type Error = InvalidPacketMode;
-
-    fn try_from(value: u8) -> Result<Self, Self::Error> {
-        match value {
-            _ if value == (PacketMode::Mix as u8) => Ok(Self::Mix),
-            _ if value == (PacketMode::Vpn as u8) => Ok(Self::Vpn),
-            v => Err(InvalidPacketMode { received: v }),
-        }
-    }
-}
@@ -3,7 +3,7 @@

 use crate::FRAG_ID_LEN;
 use nym_sphinx_types::header::HEADER_SIZE;
-use nym_sphinx_types::PAYLOAD_OVERHEAD_SIZE;
+use nym_sphinx_types::{MIX_PARAMS_LEN, OUTFOX_PACKET_OVERHEAD, PAYLOAD_OVERHEAD_SIZE};
 use serde::{Deserialize, Serialize};
 use std::cmp::Ordering;
 use std::convert::TryFrom;
@@ -12,20 +12,27 @@ use std::str::FromStr;
 use thiserror::Error;

 // each sphinx packet contains mandatory header and payload padding + markers
-const PACKET_OVERHEAD: usize = HEADER_SIZE + PAYLOAD_OVERHEAD_SIZE;
+const SPHINX_PACKET_OVERHEAD: usize = HEADER_SIZE + PAYLOAD_OVERHEAD_SIZE;

 // it's up to the smart people to figure those values out : )
-const REGULAR_PACKET_SIZE: usize = 2 * 1024 + PACKET_OVERHEAD;
+
 // TODO: even though we have 16B IV, is having just 5B (FRAG_ID_LEN) of the ID possibly insecure?

 // TODO: I'm not entirely sure if we can easily extract `<AckEncryptionAlgorithm as NewStreamCipher>::NonceSize`
 // into a const usize before relevant stuff is stabilised in rust...
 const ACK_IV_SIZE: usize = 16;

-const ACK_PACKET_SIZE: usize = ACK_IV_SIZE + FRAG_ID_LEN + PACKET_OVERHEAD;
-const EXTENDED_PACKET_SIZE_8: usize = 8 * 1024 + PACKET_OVERHEAD;
-const EXTENDED_PACKET_SIZE_16: usize = 16 * 1024 + PACKET_OVERHEAD;
-const EXTENDED_PACKET_SIZE_32: usize = 32 * 1024 + PACKET_OVERHEAD;
+const ACK_PACKET_SIZE: usize = ACK_IV_SIZE + FRAG_ID_LEN + SPHINX_PACKET_OVERHEAD;
+const REGULAR_PACKET_SIZE: usize = 2 * 1024 + SPHINX_PACKET_OVERHEAD;
+const EXTENDED_PACKET_SIZE_8: usize = 8 * 1024 + SPHINX_PACKET_OVERHEAD;
+const EXTENDED_PACKET_SIZE_16: usize = 16 * 1024 + SPHINX_PACKET_OVERHEAD;
+const EXTENDED_PACKET_SIZE_32: usize = 32 * 1024 + SPHINX_PACKET_OVERHEAD;
+
+const OUTFOX_ACK_PACKET_SIZE: usize = ACK_IV_SIZE + FRAG_ID_LEN + OUTFOX_PACKET_OVERHEAD;
+const OUTFOX_REGULAR_PACKET_SIZE: usize = 2 * 1024 + OUTFOX_PACKET_OVERHEAD;
+const OUTFOX_EXTENDED_PACKET_SIZE_8: usize = 8 * 1024 + OUTFOX_PACKET_OVERHEAD;
+const OUTFOX_EXTENDED_PACKET_SIZE_16: usize = 16 * 1024 + OUTFOX_PACKET_OVERHEAD;
+const OUTFOX_EXTENDED_PACKET_SIZE_32: usize = 32 * 1024 + OUTFOX_PACKET_OVERHEAD;

 #[derive(Debug, Error)]
 pub enum InvalidPacketSize {
@@ -62,6 +69,25 @@ pub enum PacketSize {
    // for example for streaming fast and furious in compressed XviD quality
    #[serde(rename = "extended16")]
    ExtendedPacket16 = 5,
+
+    #[serde(rename = "outfox_regular")]
+    OutfoxRegularPacket = 6,
+
+    // for sending SURB-ACKs
+    #[serde(rename = "outfox_ack")]
+    OutfoxAckPacket = 7,
+
+    // for example for streaming fast and furious in uncompressed 10bit 4K HDR quality
+    #[serde(rename = "outfox_extended32")]
+    OutfoxExtendedPacket32 = 8,
+
+    // for example for streaming fast and furious in heavily compressed lossy RealPlayer quality
+    #[serde(rename = "outfox_extended8")]
+    OutfoxExtendedPacket8 = 9,
+
+    // for example for streaming fast and furious in compressed XviD quality
+    #[serde(rename = "outfox_extended16")]
+    OutfoxExtendedPacket16 = 10,
 }

 impl PartialOrd for PacketSize {
@@ -88,6 +114,11 @@ impl FromStr for PacketSize {
            "extended8" => Ok(Self::ExtendedPacket8),
            "extended16" => Ok(Self::ExtendedPacket16),
            "extended32" => Ok(Self::ExtendedPacket32),
+            "outfox_regular" => Ok(Self::OutfoxRegularPacket),
+            "outfox_ack" => Ok(Self::OutfoxAckPacket),
+            "outfox_extended8" => Ok(Self::OutfoxExtendedPacket8),
+            "outfox_extended16" => Ok(Self::OutfoxExtendedPacket16),
+            "outfox_extended32" => Ok(Self::OutfoxExtendedPacket32),
            s => Err(InvalidPacketSize::UnknownExtendedPacketVariant {
                received: s.to_string(),
            }),
@@ -103,6 +134,11 @@ impl Display for PacketSize {
            PacketSize::ExtendedPacket32 => write!(f, "extended32"),
            PacketSize::ExtendedPacket8 => write!(f, "extended8"),
            PacketSize::ExtendedPacket16 => write!(f, "extended16"),
+            PacketSize::OutfoxRegularPacket => write!(f, "outfox_regular"),
+            PacketSize::OutfoxAckPacket => write!(f, "outfox_ack"),
+            PacketSize::OutfoxExtendedPacket32 => write!(f, "outfox_extended32"),
+            PacketSize::OutfoxExtendedPacket8 => write!(f, "outfox_extended8"),
+            PacketSize::OutfoxExtendedPacket16 => write!(f, "outfox_extended16"),
        }
    }
 }
@@ -127,6 +163,17 @@ impl TryFrom<u8> for PacketSize {
            _ if value == (PacketSize::ExtendedPacket8 as u8) => Ok(Self::ExtendedPacket8),
            _ if value == (PacketSize::ExtendedPacket16 as u8) => Ok(Self::ExtendedPacket16),
            _ if value == (PacketSize::ExtendedPacket32 as u8) => Ok(Self::ExtendedPacket32),
+            _ if value == (PacketSize::OutfoxRegularPacket as u8) => Ok(Self::OutfoxRegularPacket),
+            _ if value == (PacketSize::OutfoxAckPacket as u8) => Ok(Self::OutfoxAckPacket),
+            _ if value == (PacketSize::OutfoxExtendedPacket8 as u8) => {
+                Ok(Self::OutfoxExtendedPacket8)
+            }
+            _ if value == (PacketSize::OutfoxExtendedPacket16 as u8) => {
+                Ok(Self::OutfoxExtendedPacket16)
+            }
+            _ if value == (PacketSize::OutfoxExtendedPacket32 as u8) => {
+                Ok(Self::OutfoxExtendedPacket32)
+            }
            v => Err(InvalidPacketSize::UnknownPacketTag { received: v }),
        }
    }
@@ -140,15 +187,50 @@ impl PacketSize {
            PacketSize::ExtendedPacket8 => EXTENDED_PACKET_SIZE_8,
            PacketSize::ExtendedPacket16 => EXTENDED_PACKET_SIZE_16,
            PacketSize::ExtendedPacket32 => EXTENDED_PACKET_SIZE_32,
+            PacketSize::OutfoxRegularPacket => OUTFOX_REGULAR_PACKET_SIZE,
+            PacketSize::OutfoxAckPacket => OUTFOX_ACK_PACKET_SIZE,
+            PacketSize::OutfoxExtendedPacket8 => OUTFOX_EXTENDED_PACKET_SIZE_8,
+            PacketSize::OutfoxExtendedPacket16 => OUTFOX_EXTENDED_PACKET_SIZE_16,
+            PacketSize::OutfoxExtendedPacket32 => OUTFOX_EXTENDED_PACKET_SIZE_32,
+        }
+    }
+
+    pub const fn header_size(&self) -> usize {
+        match self {
+            PacketSize::RegularPacket
+            | PacketSize::AckPacket
+            | PacketSize::ExtendedPacket8
+            | PacketSize::ExtendedPacket16
+            | PacketSize::ExtendedPacket32 => HEADER_SIZE,
+            PacketSize::OutfoxRegularPacket
+            | PacketSize::OutfoxAckPacket
+            | PacketSize::OutfoxExtendedPacket8
+            | PacketSize::OutfoxExtendedPacket16
+            | PacketSize::OutfoxExtendedPacket32 => MIX_PARAMS_LEN,
+        }
+    }
+
+    pub const fn payload_overhead(&self) -> usize {
+        match self {
+            PacketSize::RegularPacket
+            | PacketSize::AckPacket
+            | PacketSize::ExtendedPacket8
+            | PacketSize::ExtendedPacket16
+            | PacketSize::ExtendedPacket32 => PAYLOAD_OVERHEAD_SIZE,
+            PacketSize::OutfoxRegularPacket
+            | PacketSize::OutfoxAckPacket
+            | PacketSize::OutfoxExtendedPacket8
+            | PacketSize::OutfoxExtendedPacket16
+            | PacketSize::OutfoxExtendedPacket32 => OUTFOX_PACKET_OVERHEAD - MIX_PARAMS_LEN,
        }
    }

    pub const fn plaintext_size(self) -> usize {
-        self.size() - HEADER_SIZE - PAYLOAD_OVERHEAD_SIZE
+        self.size() - self.header_size() - self.payload_overhead()
    }

    pub const fn payload_size(self) -> usize {
-        self.size() - HEADER_SIZE
+        self.size() - self.header_size()
    }

    pub fn get_type(size: usize) -> Result<Self, InvalidPacketSize> {
@@ -162,6 +244,16 @@ impl PacketSize {
            Ok(PacketSize::ExtendedPacket16)
        } else if PacketSize::ExtendedPacket32.size() == size {
            Ok(PacketSize::ExtendedPacket32)
+        } else if PacketSize::OutfoxRegularPacket.size() == size {
+            Ok(PacketSize::OutfoxRegularPacket)
+        } else if PacketSize::OutfoxAckPacket.size() == size {
+            Ok(PacketSize::OutfoxAckPacket)
+        } else if PacketSize::OutfoxExtendedPacket8.size() == size {
+            Ok(PacketSize::OutfoxExtendedPacket8)
+        } else if PacketSize::OutfoxExtendedPacket16.size() == size {
+            Ok(PacketSize::OutfoxExtendedPacket16)
+        } else if PacketSize::OutfoxExtendedPacket32.size() == size {
+            Ok(PacketSize::OutfoxExtendedPacket32)
        } else {
            Err(InvalidPacketSize::UnknownPacketSize { received: size })
        }
@@ -169,10 +261,16 @@ impl PacketSize {

    pub fn is_extended_size(&self) -> bool {
        match self {
-            PacketSize::RegularPacket | PacketSize::AckPacket => false,
+            PacketSize::RegularPacket
+            | PacketSize::AckPacket
+            | PacketSize::OutfoxAckPacket
+            | PacketSize::OutfoxRegularPacket => false,
            PacketSize::ExtendedPacket8
            | PacketSize::ExtendedPacket16
-            | PacketSize::ExtendedPacket32 => true,
+            | PacketSize::ExtendedPacket32
+            | PacketSize::OutfoxExtendedPacket8
+            | PacketSize::OutfoxExtendedPacket16
+            | PacketSize::OutfoxExtendedPacket32 => true,
        }
    }

@@ -185,8 +283,15 @@ impl PacketSize {
    }

    pub fn get_type_from_plaintext(plaintext_size: usize) -> Result<Self, InvalidPacketSize> {
-        let packet_size = plaintext_size + PACKET_OVERHEAD;
-        Self::get_type(packet_size)
+        let sphinx_packet_size = plaintext_size + SPHINX_PACKET_OVERHEAD;
+        let outfox_packet_size = plaintext_size + OUTFOX_PACKET_OVERHEAD;
+        match Self::get_type(sphinx_packet_size) {
+            Ok(t) => Ok(t),
+            Err(_) => {
+                println!("Got Outfox!");
+                Self::get_type(outfox_packet_size)
+            }
+        }
    }
 }

@@ -0,0 +1,49 @@
+// Copyright 2021-2022 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use serde::{Deserialize, Serialize};
+use std::convert::TryFrom;
+use thiserror::Error;
+
+#[derive(Error, Debug)]
+#[error("{received} is not a valid packet mode tag")]
+pub struct InvalidPacketType {
+    received: u8,
+}
+
+#[repr(u8)]
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Default, Serialize, Deserialize)]
+pub enum PacketType {
+    /// Represents 'normal' packet sent through the network that should be delayed by an appropriate
+    /// value at each hop.
+    #[default]
+    Mix = 0,
+
+    /// Represents a packet that should be sent through the network as fast as possible.
+    Vpn = 1,
+
+    /// Abusing this to add Outfox support
+    Outfox = 2,
+}
+
+impl PacketType {
+    pub fn is_mix(self) -> bool {
+        self == PacketType::Mix
+    }
+
+    pub fn is_outfox(self) -> bool {
+        self == PacketType::Outfox
+    }
+}
+
+impl TryFrom<u8> for PacketType {
+    type Error = InvalidPacketType;
+
+    fn try_from(value: u8) -> Result<Self, Self::Error> {
+        match value {
+            _ if value == (PacketType::Mix as u8) => Ok(Self::Mix),
+            _ if value == (PacketType::Outfox as u8) => Ok(Self::Outfox),
+            v => Err(InvalidPacketType { received: v }),
+        }
+    }
+}
@@ -1,9 +1,11 @@
 // Copyright 2022 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

+use serde::{Deserialize, Serialize};
+
 use crate::{PacketSize, CURRENT_PACKET_VERSION_NUMBER};

-#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
 pub enum PacketVersion {
    // this will allow updated mixnodes to still understand packets from before the update
    Legacy,
@@ -19,4 +19,4 @@ pub use nym_sphinx_params as params;
 pub use nym_sphinx_types::*;

 // TEMP UNTIL FURTHER REFACTORING
-pub use preparer::payload::NymsphinxPayloadBuilder;
+pub use preparer::payload::NymPayloadBuilder;
@@ -2,9 +2,10 @@
 // SPDX-License-Identifier: Apache-2.0

 use crate::message::{NymMessage, ACK_OVERHEAD};
-use crate::NymsphinxPayloadBuilder;
+use crate::NymPayloadBuilder;
 use nym_crypto::asymmetric::encryption;
 use nym_crypto::Digest;
+use nym_outfox::packet::OutfoxPacket;
 use nym_sphinx_acknowledgements::surb_ack::SurbAck;
 use nym_sphinx_acknowledgements::AckKey;
 use nym_sphinx_addressing::clients::Recipient;
@@ -13,9 +14,9 @@ use nym_sphinx_anonymous_replies::reply_surb::ReplySurb;
 use nym_sphinx_chunking::fragment::{Fragment, FragmentIdentifier};
 use nym_sphinx_forwarding::packet::MixPacket;
 use nym_sphinx_params::packet_sizes::PacketSize;
-use nym_sphinx_params::{ReplySurbKeyDigestAlgorithm, DEFAULT_NUM_MIX_HOPS};
+use nym_sphinx_params::{PacketType, ReplySurbKeyDigestAlgorithm, DEFAULT_NUM_MIX_HOPS};
 use nym_sphinx_types::builder::SphinxPacketBuilder;
-use nym_sphinx_types::{delays, Delay};
+use nym_sphinx_types::{delays, Delay, NymPacket};
 use nym_topology::{NymTopology, NymTopologyError};
 use rand::{CryptoRng, Rng};
 use std::convert::TryFrom;
@@ -38,6 +39,226 @@ pub struct PreparedFragment {
    pub fragment_identifier: FragmentIdentifier,
 }

+// this is extracted into a trait with default implementation to remove duplicate code
+// (which we REALLY want to avoid with crypto)
+pub trait FragmentPreparer {
+    type Rng: CryptoRng + Rng;
+
+    fn rng(&mut self) -> &mut Self::Rng;
+    fn num_mix_hops(&self) -> u8;
+    fn average_packet_delay(&self) -> Duration;
+    fn average_ack_delay(&self) -> Duration;
+
+    fn generate_reply_surbs(
+        &mut self,
+        amount: usize,
+        topology: &NymTopology,
+        reply_recipient: &Recipient,
+    ) -> Result<Vec<ReplySurb>, NymTopologyError> {
+        let mut reply_surbs = Vec::with_capacity(amount);
+        let packet_delay = self.average_packet_delay();
+        for _ in 0..amount {
+            let reply_surb =
+                ReplySurb::construct(self.rng(), reply_recipient, packet_delay, topology)?;
+            reply_surbs.push(reply_surb)
+        }
+
+        Ok(reply_surbs)
+    }
+
+    fn generate_surb_ack(
+        &mut self,
+        recipient: &Recipient,
+        fragment_id: FragmentIdentifier,
+        topology: &NymTopology,
+        ack_key: &AckKey,
+    ) -> Result<SurbAck, NymTopologyError> {
+        let ack_delay = self.average_ack_delay();
+
+        SurbAck::construct(
+            self.rng(),
+            recipient,
+            ack_key,
+            fragment_id.to_bytes(),
+            ack_delay,
+            topology,
+        )
+    }
+
+    /// The procedure is as follows:
+    /// For each fragment:
+    /// - compute SURB_ACK
+    /// - generate (x, g^x)
+    /// - obtain key k from the reply-surb which was computed as follows:
+    ///     k = KDF(remote encryption key ^ x) this is equivalent to KDF( dh(remote, x) )
+    /// - compute v_b = AES-128-CTR(k, serialized_fragment)
+    /// - compute vk_b = H(k) || v_b
+    /// - compute sphinx_plaintext = SURB_ACK || H(k) || v_b
+    /// - compute sphinx_packet by applying the reply surb on the sphinx_plaintext
+    fn prepare_reply_chunk_for_sending(
+        &mut self,
+        fragment: Fragment,
+        topology: &NymTopology,
+        ack_key: &AckKey,
+        reply_surb: ReplySurb,
+        packet_sender: &Recipient,
+        packet_type: PacketType,
+    ) -> Result<PreparedFragment, NymTopologyError> {
+        // each reply attaches the digest of the encryption key so that the recipient could
+        // lookup correct key for decryption,
+        let reply_overhead = ReplySurbKeyDigestAlgorithm::output_size();
+        let expected_plaintext = fragment.serialized_size() + ACK_OVERHEAD + reply_overhead;
+
+        // the reason we're unwrapping (or rather 'expecting') here rather than handling the error
+        // more gracefully is that this error should never be reached as it implies incorrect chunking
+        let packet_size = PacketSize::get_type_from_plaintext(expected_plaintext)
+            .expect("the message has been incorrectly fragmented");
+
+        // this is not going to be accurate by any means. but that's the best estimation we can do
+        let expected_forward_delay = Delay::new_from_millis(
+            (self.average_packet_delay().as_millis() * self.num_mix_hops() as u128) as u64,
+        );
+
+        let fragment_identifier = fragment.fragment_identifier();
+
+        // create an ack
+        let surb_ack =
+            self.generate_surb_ack(packet_sender, fragment_identifier, topology, ack_key)?;
+        let ack_delay = surb_ack.expected_total_delay();
+
+        let packet_payload = match NymPayloadBuilder::new(fragment, surb_ack)
+            .build_reply(reply_surb.encryption_key())
+        {
+            Ok(payload) => payload,
+            Err(_e) => return Err(NymTopologyError::PayloadBuilder),
+        };
+
+        // the unwrap here is fine as the failures can only originate from attempting to use invalid payload lengths
+        // and we just very carefully constructed a (presumably) valid one
+        let (sphinx_packet, first_hop_address) = reply_surb
+            .apply_surb(packet_payload, packet_size, packet_type)
+            .unwrap();
+
+        Ok(PreparedFragment {
+            // the round-trip delay is the sum of delays of all hops on the forward route as
+            // well as the total delay of the ack packet.
+            // we don't know the delays inside the reply surbs so we use best-effort estimation from our poisson distribution
+            total_delay: expected_forward_delay + ack_delay,
+            mix_packet: MixPacket::new(first_hop_address, sphinx_packet, Default::default()),
+            fragment_identifier,
+        })
+    }
+
+    /// Tries to convert this [`Fragment`] into a [`SphinxPacket`] that can be sent through the Nym mix-network,
+    /// such that it contains required SURB-ACK and public component of the ephemeral key used to
+    /// derive the shared key.
+    /// Also all the data, apart from the said public component, is encrypted with an ephemeral shared key.
+    /// This method can fail if the provided network topology is invalid.
+    /// It returns total expected delay as well as the [`SphinxPacket`] (including first hop address)
+    /// to be sent through the network.
+    ///
+    /// The procedure is as follows:
+    /// For each fragment:
+    /// - compute SURB_ACK
+    /// - generate (x, g^x)
+    /// - compute k = KDF(remote encryption key ^ x) this is equivalent to KDF( dh(remote, x) )
+    /// - compute v_b = AES-128-CTR(k, serialized_fragment)
+    /// - compute vk_b = g^x || v_b
+    /// - compute sphinx_plaintext = SURB_ACK || g^x || v_b
+    /// - compute sphinx_packet = Sphinx(recipient, sphinx_plaintext)
+    fn prepare_chunk_for_sending(
+        &mut self,
+        fragment: Fragment,
+        topology: &NymTopology,
+        ack_key: &AckKey,
+        packet_sender: &Recipient,
+        packet_recipient: &Recipient,
+        packet_type: &PacketType,
+    ) -> Result<PreparedFragment, NymTopologyError> {
+        // each plain or repliable packet (i.e. not a reply) attaches an ephemeral public key so that the recipient
+        // could perform diffie-hellman with its own keys followed by a kdf to re-derive
+        // the packet encryption key
+        let non_reply_overhead = encryption::PUBLIC_KEY_SIZE;
+        let expected_plaintext = fragment.serialized_size() + ACK_OVERHEAD + non_reply_overhead;
+
+        // the reason we're unwrapping (or rather 'expecting') here rather than handling the error
+        // more gracefully is that this error should never be reached as it implies incorrect chunking
+        let packet_size = PacketSize::get_type_from_plaintext(expected_plaintext)
+            .expect("the message has been incorrectly fragmented");
+
+        let fragment_identifier = fragment.fragment_identifier();
+
+        // create an ack
+        let surb_ack =
+            self.generate_surb_ack(packet_sender, fragment_identifier, topology, ack_key)?;
+        let ack_delay = surb_ack.expected_total_delay();
+
+        let packet_payload = match NymPayloadBuilder::new(fragment, surb_ack)
+            .build_regular(self.rng(), packet_recipient.encryption_key())
+        {
+            Ok(payload) => payload,
+            Err(_e) => return Err(NymTopologyError::PayloadBuilder),
+        };
+
+        // generate pseudorandom route for the packet
+        let hops = self.num_mix_hops();
+        let route =
+            topology.random_route_to_gateway(self.rng(), hops, packet_recipient.gateway())?;
+        let destination = packet_recipient.as_sphinx_destination();
+
+        // including set of delays
+        let delays =
+            delays::generate_from_average_duration(route.len(), self.average_packet_delay());
+
+        // create the actual sphinx packet here. With valid route and correct payload size,
+        // there's absolutely no reason for this call to fail.
+        let packet = match packet_type {
+            PacketType::Outfox => NymPacket::Outfox(OutfoxPacket::build(
+                packet_payload,
+                route.as_slice().try_into()?,
+                Some(packet_size.payload_size()),
+            )?),
+            PacketType::Mix => NymPacket::Sphinx({
+                SphinxPacketBuilder::new()
+                    .with_payload_size(packet_size.payload_size())
+                    .build_packet(packet_payload, &route, &destination, &delays)
+                    .unwrap()
+            }),
+            PacketType::Vpn => NymPacket::Sphinx(
+                SphinxPacketBuilder::new()
+                    .with_payload_size(packet_size.payload_size())
+                    .build_packet(packet_payload, &route, &destination, &delays)
+                    .unwrap(),
+            ),
+        };
+
+        // from the previously constructed route extract the first hop
+        let first_hop_address =
+            NymNodeRoutingAddress::try_from(route.first().unwrap().address).unwrap();
+
+        Ok(PreparedFragment {
+            // the round-trip delay is the sum of delays of all hops on the forward route as
+            // well as the total delay of the ack packet.
+            // note that the last hop of the packet is a gateway that does not do any delays
+            total_delay: delays.iter().take(delays.len() - 1).sum::<Delay>() + ack_delay,
+            mix_packet: MixPacket::new(first_hop_address, packet, Default::default()),
+            fragment_identifier,
+        })
+    }
+
+    fn pad_and_split_message(
+        &mut self,
+        message: NymMessage,
+        packet_size: PacketSize,
+    ) -> Vec<Fragment> {
+        let plaintext_per_packet = message.available_sphinx_plaintext_per_packet(packet_size);
+
+        message
+            .pad_to_full_packet_lengths(plaintext_per_packet)
+            .split_into_fragments(self.rng(), plaintext_per_packet)
+    }
+}
+
 /// Prepares the message that is to be sent through the mix network by attaching
 /// an optional reply-SURB, padding it to appropriate length, encrypting its content,
 /// and chunking into appropriate size [`Fragment`]s.
@@ -111,153 +332,57 @@ where
        Ok(reply_surbs)
    }

-    /// The procedure is as follows:
-    /// For each fragment:
-    /// - compute SURB_ACK
-    /// - generate (x, g^x)
-    /// - obtain key k from the reply-surb which was computed as follows:
-    ///     k = KDF(remote encryption key ^ x) this is equivalent to KDF( dh(remote, x) )
-    /// - compute v_b = AES-128-CTR(k, serialized_fragment)
-    /// - compute vk_b = H(k) || v_b
-    /// - compute sphinx_plaintext = SURB_ACK || H(k) || v_b
-    /// - compute sphinx_packet by applying the reply surb on the sphinx_plaintext
    pub fn prepare_reply_chunk_for_sending(
        &mut self,
        fragment: Fragment,
        topology: &NymTopology,
        ack_key: &AckKey,
        reply_surb: ReplySurb,
+        packet_type: PacketType,
    ) -> Result<PreparedFragment, NymTopologyError> {
-        // each reply attaches the digest of the encryption key so that the recipient could
-        // lookup correct key for decryption,
-        let reply_overhead = ReplySurbKeyDigestAlgorithm::output_size();
-        let expected_plaintext = fragment.serialized_size() + ACK_OVERHEAD + reply_overhead;
+        let sender = self.sender_address;

-        // the reason we're unwrapping (or rather 'expecting') here rather than handling the error
-        // more gracefully is that this error should never be reached as it implies incorrect chunking
-        let packet_size = PacketSize::get_type_from_plaintext(expected_plaintext)
-            .expect("the message has been incorrectly fragmented");
-
-        // this is not going to be accurate by any means. but that's the best estimation we can do
-        let expected_forward_delay = Delay::new_from_millis(
-            (self.average_packet_delay.as_millis() * self.num_mix_hops as u128) as u64,
-        );
-
-        let fragment_identifier = fragment.fragment_identifier();
-
-        // create an ack
-        let surb_ack = self.generate_surb_ack(fragment_identifier, topology, ack_key)?;
-        let ack_delay = surb_ack.expected_total_delay();
-
-        let packet_payload = NymsphinxPayloadBuilder::new(fragment, surb_ack)
-            .build_reply(reply_surb.encryption_key());
-
-        // the unwrap here is fine as the failures can only originate from attempting to use invalid payload lengths
-        // and we just very carefully constructed a (presumably) valid one
-        let (sphinx_packet, first_hop_address) =
-            reply_surb.apply_surb(packet_payload, packet_size).unwrap();
-
-        Ok(PreparedFragment {
-            // the round-trip delay is the sum of delays of all hops on the forward route as
-            // well as the total delay of the ack packet.
-            // we don't know the delays inside the reply surbs so we use best-effort estimation from our poisson distribution
-            total_delay: expected_forward_delay + ack_delay,
-            mix_packet: MixPacket::new(first_hop_address, sphinx_packet, Default::default()),
-            fragment_identifier,
-        })
+        <Self as FragmentPreparer>::prepare_reply_chunk_for_sending(
+            self,
+            fragment,
+            topology,
+            ack_key,
+            reply_surb,
+            &sender,
+            packet_type,
+        )
    }

-    /// Tries to convert this [`Fragment`] into a [`SphinxPacket`] that can be sent through the Nym mix-network,
-    /// such that it contains required SURB-ACK and public component of the ephemeral key used to
-    /// derive the shared key.
-    /// Also all the data, apart from the said public component, is encrypted with an ephemeral shared key.
-    /// This method can fail if the provided network topology is invalid.
-    /// It returns total expected delay as well as the [`SphinxPacket`] (including first hop address)
-    /// to be sent through the network.
-    ///
-    /// The procedure is as follows:
-    /// For each fragment:
-    /// - compute SURB_ACK
-    /// - generate (x, g^x)
-    /// - compute k = KDF(remote encryption key ^ x) this is equivalent to KDF( dh(remote, x) )
-    /// - compute v_b = AES-128-CTR(k, serialized_fragment)
-    /// - compute vk_b = g^x || v_b
-    /// - compute sphinx_plaintext = SURB_ACK || g^x || v_b
-    /// - compute sphinx_packet = Sphinx(recipient, sphinx_plaintext)
    pub fn prepare_chunk_for_sending(
        &mut self,
        fragment: Fragment,
        topology: &NymTopology,
        ack_key: &AckKey,
        packet_recipient: &Recipient,
+        packet_type: &PacketType,
    ) -> Result<PreparedFragment, NymTopologyError> {
-        // each plain or repliable packet (i.e. not a reply) attaches an ephemeral public key so that the recipient
-        // could perform diffie-hellman with its own keys followed by a kdf to re-derive
-        // the packet encryption key
-        let non_reply_overhead = encryption::PUBLIC_KEY_SIZE;
-        let expected_plaintext = fragment.serialized_size() + ACK_OVERHEAD + non_reply_overhead;
+        let sender = self.sender_address;

-        // the reason we're unwrapping (or rather 'expecting') here rather than handling the error
-        // more gracefully is that this error should never be reached as it implies incorrect chunking
-        let packet_size = PacketSize::get_type_from_plaintext(expected_plaintext)
-            .expect("the message has been incorrectly fragmented");
-
-        let fragment_identifier = fragment.fragment_identifier();
-
-        // create an ack
-        let surb_ack = self.generate_surb_ack(fragment_identifier, topology, ack_key)?;
-        let ack_delay = surb_ack.expected_total_delay();
-
-        let packet_payload = NymsphinxPayloadBuilder::new(fragment, surb_ack)
-            .build_regular(&mut self.rng, packet_recipient.encryption_key());
-
-        // generate pseudorandom route for the packet
-        let route = topology.random_route_to_gateway(
-            &mut self.rng,
-            self.num_mix_hops,
-            packet_recipient.gateway(),
-        )?;
-        let destination = packet_recipient.as_sphinx_destination();
-
-        // including set of delays
-        let delays = delays::generate_from_average_duration(route.len(), self.average_packet_delay);
-
-        // create the actual sphinx packet here. With valid route and correct payload size,
-        // there's absolutely no reason for this call to fail.
-        let sphinx_packet = SphinxPacketBuilder::new()
-            .with_payload_size(packet_size.payload_size())
-            .build_packet(packet_payload, &route, &destination, &delays)
-            .unwrap();
-
-        // from the previously constructed route extract the first hop
-        let first_hop_address =
-            NymNodeRoutingAddress::try_from(route.first().unwrap().address).unwrap();
-
-        Ok(PreparedFragment {
-            // the round-trip delay is the sum of delays of all hops on the forward route as
-            // well as the total delay of the ack packet.
-            // note that the last hop of the packet is a gateway that does not do any delays
-            total_delay: delays.iter().take(delays.len() - 1).sum::<Delay>() + ack_delay,
-            mix_packet: MixPacket::new(first_hop_address, sphinx_packet, Default::default()),
-            fragment_identifier,
-        })
+        <Self as FragmentPreparer>::prepare_chunk_for_sending(
+            self,
+            fragment,
+            topology,
+            ack_key,
+            &sender,
+            packet_recipient,
+            packet_type,
+        )
    }

    /// Construct an acknowledgement SURB for the given [`FragmentIdentifier`]
-    fn generate_surb_ack(
+    pub fn generate_surb_ack(
        &mut self,
        fragment_id: FragmentIdentifier,
        topology: &NymTopology,
        ack_key: &AckKey,
    ) -> Result<SurbAck, NymTopologyError> {
-        SurbAck::construct(
-            &mut self.rng,
-            &self.sender_address,
-            ack_key,
-            fragment_id.to_bytes(),
-            self.average_ack_delay,
-            topology,
-        )
+        let sender = self.sender_address;
+        <Self as FragmentPreparer>::generate_surb_ack(self, &sender, fragment_id, topology, ack_key)
    }

    pub fn pad_and_split_message(
@@ -265,11 +390,27 @@ where
        message: NymMessage,
        packet_size: PacketSize,
    ) -> Vec<Fragment> {
-        let plaintext_per_packet = message.available_sphinx_plaintext_per_packet(packet_size);
+        <Self as FragmentPreparer>::pad_and_split_message(self, message, packet_size)
+    }
+}

-        message
-            .pad_to_full_packet_lengths(plaintext_per_packet)
-            .split_into_fragments(&mut self.rng, plaintext_per_packet)
+impl<R: CryptoRng + Rng> FragmentPreparer for MessagePreparer<R> {
+    type Rng = R;
+
+    fn rng(&mut self) -> &mut Self::Rng {
+        &mut self.rng
+    }
+
+    fn num_mix_hops(&self) -> u8 {
+        self.num_mix_hops
+    }
+
+    fn average_packet_delay(&self) -> Duration {
+        self.average_packet_delay
+    }
+
+    fn average_ack_delay(&self) -> Duration {
+        self.average_ack_delay
    }
 }

@@ -6,7 +6,7 @@ use nym_crypto::asymmetric::encryption;
 use nym_crypto::shared_key::new_ephemeral_shared_key;
 use nym_crypto::symmetric::stream_cipher;
 use nym_crypto::symmetric::stream_cipher::CipherKey;
-use nym_sphinx_acknowledgements::surb_ack::SurbAck;
+use nym_sphinx_acknowledgements::surb_ack::{SurbAck, SurbAckRecoveryError};
 use nym_sphinx_anonymous_replies::SurbEncryptionKey;
 use nym_sphinx_chunking::fragment::Fragment;
 use nym_sphinx_params::{
@@ -14,25 +14,25 @@ use nym_sphinx_params::{
 };
 use rand::{CryptoRng, RngCore};

-pub struct NymsphinxPayloadBuilder {
+pub struct NymPayloadBuilder {
    fragment: Fragment,
    surb_ack: SurbAck,
 }

-impl NymsphinxPayloadBuilder {
+impl NymPayloadBuilder {
    pub fn new(fragment: Fragment, surb_ack: SurbAck) -> Self {
-        NymsphinxPayloadBuilder { fragment, surb_ack }
+        NymPayloadBuilder { fragment, surb_ack }
    }

    fn build<C>(
        self,
        packet_encryption_key: &CipherKey<C>,
        variant_data: impl IntoIterator<Item = u8>,
-    ) -> NymsphinxPayload
+    ) -> Result<NymPayload, SurbAckRecoveryError>
    where
        C: StreamCipher + KeyIvInit,
    {
-        let (_, surb_ack_bytes) = self.surb_ack.prepare_for_sending();
+        let (_, surb_ack_bytes) = self.surb_ack.prepare_for_sending()?;

        let mut fragment_data = self.fragment.into_bytes();
        stream_cipher::encrypt_in_place::<C>(
@@ -46,16 +46,19 @@ impl NymsphinxPayloadBuilder {
        // where variant-specific data is as follows:
        // for replies it would be the digest of the encryption key used
        // for 'regular' messages it would be the public component used in DH later used in the KDF
-        NymsphinxPayload(
+        Ok(NymPayload(
            surb_ack_bytes
                .into_iter()
                .chain(variant_data.into_iter())
                .chain(fragment_data.into_iter())
                .collect(),
-        )
+        ))
    }

-    pub fn build_reply(self, packet_encryption_key: &SurbEncryptionKey) -> NymsphinxPayload {
+    pub fn build_reply(
+        self,
+        packet_encryption_key: &SurbEncryptionKey,
+    ) -> Result<NymPayload, SurbAckRecoveryError> {
        let key_digest = packet_encryption_key.compute_digest();
        self.build::<ReplySurbEncryptionAlgorithm>(
            packet_encryption_key.inner(),
@@ -67,7 +70,7 @@ impl NymsphinxPayloadBuilder {
        self,
        rng: &mut R,
        recipient_encryption_key: &encryption::PublicKey,
-    ) -> NymsphinxPayload
+    ) -> Result<NymPayload, SurbAckRecoveryError>
    where
        R: RngCore + CryptoRng,
    {
@@ -88,9 +91,9 @@ impl NymsphinxPayloadBuilder {
 // the actual byte data that will be put into the sphinx packet paylaod.
 // no more transformations are going to happen to it
 // TODO: use that fact for some better compile time assertions
-pub struct NymsphinxPayload(Vec<u8>);
+pub struct NymPayload(Vec<u8>);

-impl AsRef<[u8]> for NymsphinxPayload {
+impl AsRef<[u8]> for NymPayload {
    fn as_ref(&self) -> &[u8] {
        &self.0
    }
@@ -7,8 +7,6 @@ use nym_crypto::asymmetric::encryption;
 use nym_crypto::shared_key::recompute_shared_key;
 use nym_crypto::symmetric::stream_cipher;
 use nym_crypto::symmetric::stream_cipher::CipherKey;
-use nym_outfox::error::OutfoxError;
-use nym_outfox::lion::lion_transform_decrypt;
 use nym_sphinx_anonymous_replies::requests::AnonymousSenderTag;
 use nym_sphinx_anonymous_replies::SurbEncryptionKey;
 use nym_sphinx_chunking::fragment::Fragment;
@@ -76,49 +74,6 @@ pub enum MessageRecoveryError {

    #[error("Failed to recover message fragment - {0}")]
    FragmentRecoveryError(#[from] ChunkingError),
-
-    #[error("Outfox: {source}")]
-    OutfoxRecoveryError {
-        #[from]
-        source: OutfoxError,
-    },
-}
-
-#[derive(Default)]
-pub struct OutfoxMessageReceiver {
-    reconstructor: MessageReconstructor,
-}
-
-impl OutfoxMessageReceiver {
-    pub fn new() -> Self {
-        Default::default()
-    }
-}
-
-impl MessageReceiver for OutfoxMessageReceiver {
-    fn new() -> Self {
-        Self::default()
-    }
-
-    fn reconstructor(&mut self) -> &mut MessageReconstructor {
-        &mut self.reconstructor
-    }
-
-    fn num_mix_hops(&self) -> u8 {
-        DEFAULT_NUM_MIX_HOPS
-    }
-
-    fn decrypt_raw_message<C>(
-        &self,
-        message: &mut [u8],
-        key: &CipherKey<C>,
-    ) -> Result<(), MessageRecoveryError>
-    where
-        C: StreamCipher + KeyIvInit,
-    {
-        lion_transform_decrypt(message, key)?;
-        Ok(())
-    }
 }

 pub trait MessageReceiver {
@@ -263,7 +218,7 @@ mod message_receiver {
    use nym_crypto::asymmetric::identity;
    use nym_mixnet_contract_common::Layer;
    use nym_topology::{gateway, mix, NymTopology};
-    use std::collections::HashMap;
+    use std::collections::BTreeMap;

    // TODO: is it somehow maybe possible to move it to `topology` and have if conditionally
    // available to other modules?
@@ -271,7 +226,7 @@ mod message_receiver {
    /// tests requiring instance of topology.
    #[allow(dead_code)]
    fn topology_fixture() -> NymTopology {
-        let mut mixes = HashMap::new();
+        let mut mixes = BTreeMap::new();
        mixes.insert(
            1,
            vec![mix::Node {
@@ -9,6 +9,5 @@ repository = { workspace = true }

 [dependencies]
 sphinx-packet = { version = "0.1.0" }
-
-#[patch.crates-io]
-#sphinx-packet = { path = "../../../../sphinx" }
+nym-outfox = { path = "../../../nym-outfox" }
+thiserror = "1"
@@ -1,7 +1,11 @@
 // Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

+pub use nym_outfox::{
+    constants::MIX_PARAMS_LEN, constants::OUTFOX_PACKET_OVERHEAD, error::OutfoxError,
+};
 // re-exporting types and constants available in sphinx
+use nym_outfox::packet::OutfoxPacket;
 pub use sphinx_packet::{
    constants::{
        self, DESTINATION_ADDRESS_LENGTH, IDENTIFIER_LENGTH, MAX_PATH_LENGTH, NODE_ADDRESS_LENGTH,
@@ -13,5 +17,101 @@ pub use sphinx_packet::{
    payload::{Payload, PAYLOAD_OVERHEAD_SIZE},
    route::{Destination, DestinationAddressBytes, Node, NodeAddressBytes, SURBIdentifier},
    surb::{SURBMaterial, SURB},
-    Error, ProcessedPacket, Result, SphinxPacket,
+    Error as SphinxError, ProcessedPacket,
 };
+use sphinx_packet::{SphinxPacket, SphinxPacketBuilder};
+use std::{array::TryFromSliceError, fmt};
+use thiserror::Error;
+
+#[derive(Error, Debug)]
+pub enum NymPacketError {
+    #[error("Sphinx error: {0}")]
+    Sphinx(#[from] sphinx_packet::Error),
+
+    #[error("Outfox error: {0}")]
+    Outfox(#[from] nym_outfox::error::OutfoxError),
+
+    #[error("{0}")]
+    FromSlice(#[from] TryFromSliceError),
+}
+
+#[allow(clippy::large_enum_variant)]
+pub enum NymPacket {
+    Sphinx(SphinxPacket),
+    Outfox(OutfoxPacket),
+}
+
+impl fmt::Debug for NymPacket {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match &self {
+            NymPacket::Sphinx(packet) => f
+                .debug_struct("NymPacket::Sphinx")
+                .field("len", &packet.len())
+                .finish(),
+            NymPacket::Outfox(packet) => f
+                .debug_struct("NymPacket::Outfox")
+                .field("len", &packet.len())
+                .finish(),
+        }
+    }
+}
+
+impl NymPacket {
+    pub fn sphinx_build<M: AsRef<[u8]>>(
+        size: usize,
+        message: M,
+        route: &[Node],
+        destination: &Destination,
+        delays: &[Delay],
+    ) -> Result<NymPacket, NymPacketError> {
+        Ok(NymPacket::Sphinx(
+            SphinxPacketBuilder::new()
+                .with_payload_size(size)
+                .build_packet(message, route, destination, delays)?,
+        ))
+    }
+    pub fn sphinx_from_bytes(bytes: &[u8]) -> Result<NymPacket, NymPacketError> {
+        Ok(NymPacket::Sphinx(SphinxPacket::from_bytes(bytes)?))
+    }
+
+    pub fn outfox_build<M: AsRef<[u8]>>(
+        payload: M,
+        route: &[Node],
+        size: Option<usize>,
+    ) -> Result<NymPacket, NymPacketError> {
+        Ok(NymPacket::Outfox(OutfoxPacket::build(
+            payload,
+            route.try_into()?,
+            size,
+        )?))
+    }
+
+    pub fn outfox_from_bytes(bytes: &[u8]) -> Result<NymPacket, NymPacketError> {
+        Ok(NymPacket::Outfox(OutfoxPacket::try_from(bytes)?))
+    }
+
+    pub fn len(&self) -> usize {
+        match self {
+            NymPacket::Sphinx(packet) => packet.len(),
+            NymPacket::Outfox(packet) => packet.len(),
+        }
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.len() == 0
+    }
+
+    pub fn to_bytes(&self) -> Result<Vec<u8>, NymPacketError> {
+        match self {
+            NymPacket::Sphinx(packet) => Ok(packet.to_bytes()),
+            NymPacket::Outfox(packet) => Ok(packet.to_bytes()?),
+        }
+    }
+
+    pub fn process(self, node_secret_key: &PrivateKey) -> Result<ProcessedPacket, NymPacketError> {
+        match self {
+            NymPacket::Sphinx(packet) => Ok(packet.process(node_secret_key)?),
+            NymPacket::Outfox(_packet) => todo!(),
+        }
+    }
+}
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
durch	e5bed9d3e2	Remove cpucycles	2023-05-08 16:39:20 +02:00
durch	1119505990	Client tweaks	2023-05-01 16:04:09 +02:00
durch	f0de459c58	Rebase on develop commit `342883fcbe` Author: durch <durch@users.noreply.github.com> Date: Thu Apr 27 09:17:18 2023 +0200 Put back PacketType 1 commit `61a0ee5a19` Author: Tommy Verrall <tommyvez@protonmail.com> Date: Wed Apr 26 16:37:29 2023 +0100 change output for cpu-cycle management logs commit `3956109c7e` Author: Tommy Verrall <tommy@nymtech.net> Date: Wed Apr 26 12:13:22 2023 +0100 change the workflow file to build with cpucycles commit `8d725b13c5` Author: durch <durch@users.noreply.github.com> Date: Mon Apr 24 13:14:58 2023 +0200 Outfox client compat commit `4d166c389b` Author: durch <durch@users.noreply.github.com> Date: Fri Apr 21 00:30:46 2023 +0200 Address PR comments commit `145c3c1223` Author: durch <durch@users.noreply.github.com> Date: Fri Apr 21 00:12:35 2023 +0200 Rename PacketMode commit `cbd654d6fd` Author: Drazen Urch <drazen@urch.eu> Date: Thu Apr 20 23:59:40 2023 +0200 Outfox rest compat (#3333) * Outfox forwarding compat * Tidy up interface * PacketSize compat commit `e7be91a94c` Author: durch <durch@users.noreply.github.com> Date: Wed Apr 19 16:36:48 2023 +0200 Remove serde cruft commit `582e7d566a` Author: durch <durch@users.noreply.github.com> Date: Wed Apr 19 16:24:09 2023 +0200 Outfox framing commit `6464da5f01` Author: durch <durch@users.noreply.github.com> Date: Tue Apr 18 22:23:02 2023 +0200 Framing compat commit `d5e77e499b` Author: durch <durch@users.noreply.github.com> Date: Tue Apr 18 18:18:54 2023 +0200 Framed encoding serde POC commit `f086f9c35a` Author: durch <durch@users.noreply.github.com> Date: Tue Apr 18 16:54:21 2023 +0200 Experiment with serde	2023-05-01 15:50:59 +02:00
durch	b4c525b664	Address PR comments	2023-05-01 15:48:36 +02:00
Drazen Urch	07291fd0ad	Outfox rest compat (#3333 ) * Outfox forwarding compat * Tidy up interface * PacketSize compat	2023-05-01 15:48:36 +02:00
durch	36c3604bb6	Outfox framing	2023-05-01 15:48:36 +02:00
durch	5a32f5da68	Framed encoding serde POC	2023-05-01 15:48:36 +02:00
durch	66f77d481c	Experiment with serde	2023-05-01 15:48:36 +02:00
Jon Häggblad	8880bdd857	Fix build target in top-level Makefile	2023-04-26 16:57:01 +02:00
Jon Häggblad	cc83ecf7e4	socks5: send empty keepalive msg to avoid triggering MIX_TTL during long downloads (#3364 ) * socks5: send empty keepalive msg to avoid triggering MIX_TTL during long downloads * rustfmt * reset timer after each normal send	2023-04-26 16:44:27 +02:00
Pierre Dommerc	00b60f5493	feat(wallet): update bond amount (#3338 )	2023-04-26 15:29:39 +02:00
pierre	cfa1ce46f2	chore(wallet): add v prefix in wallet version	2023-04-26 09:30:46 +02:00
Raphaël Walther	3f7f4b82de	Move workflows to custom runner	2023-04-25 11:10:12 +02:00
farbanas	934ba2b027	Merge branch 'master' into develop	2023-04-25 10:53:43 +02:00
Jędrzej Stuczyński	eda223ed3d	Resolved beta clippy complaints (#3351 )	2023-04-25 09:53:11 +01:00
farbanas	c98d4305fa	update cargo locks	2023-04-25 10:09:49 +02:00
farbanas	2eecbca6eb	bump versions and update changelogs for release v1.1.16	2023-04-25 10:06:03 +02:00
farbanas	a58c80ef08	update versions of mixnet and vesting contract crates	2023-04-25 10:06:03 +02:00
farbanas	ac9d0db8be	update versions of mixnet and vesting contract crates	2023-04-25 10:06:03 +02:00
farbanas	7521d98963	update versions of mixnet and vesting contract common crates	2023-04-25 10:06:03 +02:00
mx	1e98131090	Merge pull request #3349 from nymtech/feature/general-docs-updates version bump for next release	2023-04-25 07:39:10 +00:00
mx	46bf65462c	Merge pull request #3325 from esomore/mixnode/description update mix-node setup docs with node description	2023-04-25 07:38:22 +00:00
mx	e3df4c2d68	reintroduce minimum rust version variable	2023-04-24 17:13:03 +02:00
mx	45c013350f	version bump for next release	2023-04-24 17:10:41 +02:00
mx	6fecc53975	Merge pull request #3339 from nymtech/feature/coconut-rust-sdk-docs added coconut credential generation example	2023-04-24 14:49:24 +00:00
Tommy Verrall	e4dbfb1904	Merge pull request #3222 from nymtech/feature/available_reader_changes Feature/available reader changes	2023-04-24 15:48:08 +01:00
Tommy Verrall	f822d3db7b	cargo fmt	2023-04-24 15:29:51 +01:00
Jędrzej Stuczyński	9d23766288	updated used packet size	2023-04-24 15:29:51 +01:00
Jędrzej Stuczyński	fd4930b198	removed old leftover log statement	2023-04-24 15:29:51 +01:00
Jędrzej Stuczyński	5d7be89edb	replaced inner implementation with tokio's 'ReaderStream'	2023-04-24 15:29:51 +01:00
Jędrzej Stuczyński	47f5b4ceac	limit the maximum buffer size of AvailableReader by PacketSize of our mix packets	2023-04-24 15:29:51 +01:00
Jędrzej Stuczyński	790220039b	added read deadline to AvailableReader	2023-04-24 15:29:51 +01:00
Tommy Verrall	16fdfa4583	Update mainnet.env	2023-04-24 13:54:54 +02:00
Jędrzej Stuczyński	cbbeb66b5b	Feature/wasm client topology injection (#3311 ) * added cargo config file to explicitly specify build target * wip * Config option to disable topology refreshing * extracted common parsing code * helper trait for working on wasm topology * wasm topology parsing * restored (slightly modified) old js-example * wip * Moved message preparation into a trait * wip * long-winded way of sending test packet * standalone NymNodeTester * finishing the test upon receiving all packets even if timeout wasnt reached * initial round of cleanup * sending multiple test packets in normal NymClient * javascript-side cleanup * starting mixnode test on btn click * Improved NymNodeTester constructors * improved error handling and constructors * tester utils error handling * further cleanup + using BTreeMap for NymTopology mixnodes * handling missed errors * splitting up 'test_node' * split up and cleaned up generation of test result * clippy + fixed example * post rebase fixes * another broken test * prevent running multiple parallel tests * cargo fmt * Added nym- prefix to node tester utils	2023-04-24 09:56:26 +01:00
Jon Häggblad	3f0d4846df	Fix a few clippy warnings in contract test code (#3340 ) * ci: don't fail fast for contracts * contracts: fix clippy in tests	2023-04-24 10:30:22 +02:00
mx	de020f46a6	added coconut credential generation example	2023-04-21 16:32:20 +02:00
Jon Häggblad	9bfcdbe8e2	Add --all-targets to clippy for contracts (#3337 )	2023-04-21 11:47:43 +02:00
Tommy Verrall	8c4885ce2c	Merge pull request #3294 from nymtech/feature/fix-clippy-warnings A branch with all clippy warnings dealt with in contracts	2023-04-21 10:37:33 +01:00
Jędrzej Stuczyński	f24bb5c038	reduced noise in CODEOWNERS (#3313 ) * reduced noise in CODEOWNERS * Add @octol to codeowners * added @mfahampshire as owner of /documentation --------- Co-authored-by: Jon Häggblad <jon.haggblad@gmail.com>	2023-04-20 15:25:23 +01:00
Jon Häggblad	79dfe7eeda	Add clippy target in top-level Makefile	2023-04-20 14:13:20 +02:00
Jon Häggblad	0108c6ed19	Merge remote-tracking branch 'origin/release/v1.1.16' into develop	2023-04-20 09:55:19 +02:00
Tommy Verrall	926389df89	Merge pull request #3300 from nymtech/bugfix/empty-ack-stream-map make sure to clear inner 'ack_map' in 'GatewaysReader'	2023-04-20 08:31:31 +01:00
Tommy Verrall	b55db00408	Merge pull request #3324 from nymtech/bugfix/nym-cli-gateway-commands exposed missing gateway commands in nym-cli	2023-04-20 07:55:56 +01:00
Jędrzej Stuczyński	cfcb64f7e5	Feature/reduce pledge (#3254 ) * basic contract work for 'decrease_pledge' functionality note: it doesn't yet return tokens back to the operator * returning extra tokens after decreasing pledge * added vesting message to track pledge decrease * attaching the track message when processing delegation decrease * checking for zero value request * fixed event test * allowing to decrease pledge from the vesting contract * integration test for the feature * reorganised the integration tests * updated nyxd client traits * wallet support * typescript helpers * moved 'pledge more' functionality to operator commands * cli commands for decreasing pledge * changed error variant to make clippy happier * removed unused import * eslint * fixed post-rebase imports * added cargo config * added PendingMixNodeChanges to MixNodeDetails * returning event id after creating it * Streamlined getting mixnode details by identity key * setting pending pledge changes on increase/decrease * clearing the value on resolving the event * checking for correct invariants when clearing events * further pending events unit tests fixes * new unit tests for tx endpoints * queries for pending events (by id) * migration code * using default value for pending changes if unavailable * improved integration test assertions	2023-04-20 07:52:10 +01:00
Itamar Perez	0e8f60d501	update mix-node setup docs with node description	2023-04-19 12:01:36 -07:00
Jon Häggblad	9c6c5f5170	Add --all-targets to nym-wallet CI clippy (#3326 )	2023-04-19 10:44:46 +02:00
Jon Häggblad	f28888e3e7	Update Cargo.lock files after bumping internal versions during 1.1.15 release	2023-04-19 09:41:03 +02:00
Jon Häggblad	6e30e6178b	Update Cargo.lock files after bumping internal versions during release	2023-04-19 09:37:38 +02:00
Jędrzej Stuczyński	9549bed8bb	exposed missing gateway commands in nym-cli	2023-04-18 16:28:13 +01:00
Jędrzej Stuczyński	7a50f0c3b2	make sure to clear inner 'ack_map' in 'GatewaysReader'	2023-04-13 10:51:03 +01:00
Dave Hrycyszyn	2da6a2fbfa	Adding a clippy.toml so we can see correct warnings in mixnet contract	2023-04-11 14:57:04 +01:00
Dave Hrycyszyn	d910a4e0ee	The `make test` target seems to be wrapping differently than local	2023-04-11 14:53:51 +01:00
Dave Hrycyszyn	672ab79421	A branch with all clippy warnings dealt with in contracts	2023-04-11 14:46:45 +01:00