Introduce event backchannel (#6119 )

* Introduce even backchannel * Rust fmt * Rename Event to MixnetClientEvent * Use unbounded_send for events * Remove unused file * Remove mut borrow * Event hierarchy and mixnet client intermediary * Export MixTrafficEvent in sdk
Registration Client (#6059 )
2025-10-17 08:47:43 +03:00 · 2025-09-30 15:50:04 +02:00 · 2025-09-30 13:30:54 +00:00 · 2025-09-30 14:30:05 +02:00 · 2025-09-29 16:27:10 +01:00 · 2025-09-29 14:53:15 +01:00
571 changed files with 19480 additions and 14225 deletions
@@ -21,7 +21,7 @@ jobs:
    strategy:
      fail-fast: false
      matrix:
-        platform: [ arc-ubuntu-22.04 ]
+        platform: [ arc-linux-latest ]

    runs-on: ${{ matrix.platform }}
    env:
@@ -9,7 +9,7 @@ on:

 jobs:
  wasm:
-    runs-on: arc-ubuntu-22.04
+    runs-on: arc-linux-latest
    env:
      CARGO_TERM_COLOR: always
      RUSTUP_PERMIT_COPY_RENAME: 1
@@ -10,13 +10,13 @@ env:

 jobs:
  check-if-tag-exists:
-    runs-on: arc-ubuntu-22.04-dind
+    runs-on: arc-linux-latest-dind
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4

      - name: Get version from cargo.toml
-        uses: mikefarah/yq@v4.45.4
+        uses: mikefarah/yq@v4.47.1
        id: get_version
        with:
          cmd: yq -oy '.package.version' ${{ env.WORKING_DIRECTORY }}/Cargo.toml
@@ -16,7 +16,7 @@ jobs:
        uses: actions/checkout@v4

      - name: Get version from cargo.toml
-        uses: mikefarah/yq@v4.45.4
+        uses: mikefarah/yq@v4.47.1
        id: get_version
        with:
          cmd: yq -oy '.package.version' ${{ env.WORKING_DIRECTORY }}/Cargo.toml
@@ -11,7 +11,7 @@ on:

 jobs:
  build:
-    runs-on: arc-ubuntu-22.04
+    runs-on: arc-linux-latest
    env:
      CARGO_TERM_COLOR: always
      RUSTUP_PERMIT_COPY_RENAME: 1
@@ -11,7 +11,7 @@ on:

 jobs:
  wasm:
-    runs-on: arc-ubuntu-22.04
+    runs-on: arc-linux-latest
    env:
      CARGO_TERM_COLOR: always
      RUSTUP_PERMIT_COPY_RENAME: 1
@@ -6,7 +6,7 @@ jobs:
  greeting:
    runs-on: ubuntu-latest
    steps:
-    - uses: actions/first-interaction@v1
+    - uses: actions/first-interaction@v3
      with:
        repo-token: ${{ secrets.GITHUB_TOKEN }}
        issue-message: 'Thank you for raising this issue'
@@ -31,7 +31,7 @@ jobs:
      - name: Check out repository code
        uses: actions/checkout@v4
      - name: Download report from previous job
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v5
        with:
          name: report
          path: .github/workflows/support-files/notifications
@@ -30,13 +30,11 @@ jobs:
      release_date: ${{ fromJSON(steps.create-release.outputs.assets)[0].published_at }}
      client_hash: ${{ steps.binary-hashes.outputs.client_hash }}
      nymvisor_hash: ${{ steps.binary-hashes.outputs.nymvisor_hash }}
-      nymnode_hash: ${{ steps.binary-hashes.outputs.nymnode_hash }}
      socks5_hash: ${{ steps.binary-hashes.outputs.socks5_hash }}
      netreq_hash: ${{ steps.binary-hashes.outputs.netreq_hash }}
      cli_hash: ${{ steps.binary-hashes.outputs.cli_hash }}
      client_version: ${{ steps.binary-versions.outputs.client_version }}
      nymvisor_version: ${{ steps.binary-versions.outputs.nymvisor_version }}
-      nymnode_version: ${{ steps.binary-versions.outputs.nymnode_version }}
      socks5_version: ${{ steps.binary-versions.outputs.socks5_version }}
      netreq_version: ${{ steps.binary-versions.outputs.netreq_version }}
      cli_version: ${{ steps.binary-versions.outputs.cli_version }}
@@ -56,7 +54,7 @@ jobs:
      - name: Install Rust stable
        uses: actions-rs/toolchain@v1
        with:
-          toolchain: 1.86.0
+          toolchain: 1.88.0
          override: true

      - name: Build all binaries
@@ -76,7 +74,6 @@ jobs:
            target/release/nym-network-requester
            target/release/nym-cli
            target/release/nymvisor
-            target/release/nym-node
          retention-days: 30
    
      - id: create-release
@@ -91,7 +88,6 @@ jobs:
            target/release/nym-network-requester
            target/release/nym-cli
            target/release/nymvisor
-            target/release/nym-node

  push-release-data-client:
    if: ${{ (startsWith(github.ref, 'refs/tags/nym-binaries-') && github.event_name == 'release') || github.event_name == 'workflow_dispatch' }}
@@ -25,7 +25,7 @@ jobs:
        uses: actions/checkout@v4

      - name: Install Java
-        uses: actions/setup-java@v4
+        uses: actions/setup-java@v5
        with:
          distribution: "temurin"
          java-version: "17"
@@ -91,7 +91,7 @@ jobs:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Download binary artifact
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v5
        with:
          name: nyms5-apk-arch64
          path: apk
@@ -26,7 +26,7 @@ jobs:
          git config --global user.name "Lawrence Stalder"

      - name: Get version from cargo.toml
-        uses: mikefarah/yq@v4.45.4
+        uses: mikefarah/yq@v4.47.1
        id: get_version
        with:
          cmd: yq -oy '.package.version' ${{ env.WORKING_DIRECTORY }}/nym-credential-proxy/Cargo.toml
@@ -26,7 +26,7 @@ jobs:
          git config --global user.name "Lawrence Stalder"

      - name: Get version from cargo.toml
-        uses: mikefarah/yq@v4.45.4
+        uses: mikefarah/yq@v4.47.1
        id: get_version
        with:
          cmd: yq -oy '.package.version' ${{ env.WORKING_DIRECTORY }}/Cargo.toml
@@ -26,7 +26,7 @@ jobs:
          git config --global user.name "Lawrence Stalder"

      - name: Get version from cargo.toml
-        uses: mikefarah/yq@v4.45.4
+        uses: mikefarah/yq@v4.47.1
        id: get_version
        with:
          cmd: yq -oy '.package.version' ${{ env.WORKING_DIRECTORY }}/nym-network-monitor/Cargo.toml
@@ -20,7 +20,7 @@ env:

 jobs:
  build-container:
-    runs-on: arc-ubuntu-22.04-dind
+    runs-on: arc-linux-latest-dind
    steps:
      - name: Login to Harbor
        uses: docker/login-action@v3
@@ -14,7 +14,7 @@ env:

 jobs:
  build-container:
-    runs-on: arc-ubuntu-22.04-dind
+    runs-on: arc-linux-latest-dind
    steps:
      - name: Login to Harbor
        uses: docker/login-action@v3
@@ -34,18 +34,22 @@ jobs:
      - name: Get version from cargo.toml
        id: get_version
        run: |
-          yq -oy '.package.version' ${{ env.WORKING_DIRECTORY }}/Cargo.toml
+          VERSION=$(yq -oy '.package.version' ${{ env.WORKING_DIRECTORY }}/Cargo.toml)
+          echo "result=$VERSION" >> $GITHUB_OUTPUT

      - name: Set GIT_TAG variable
        run: echo "GIT_TAG=${{ env.WORKING_DIRECTORY }}-${{ steps.get_version.outputs.result }}" >> $GITHUB_ENV

-      - name: Set RELEASE_TAG variable
+      - name: Initialise RELEASE_TAG
+        run: echo "RELEASE_TAG=" >> $GITHUB_ENV
+      
+      - name: Set RELEASE_TAG for release
        if: github.event.inputs.release_image == 'true'
        run: echo "RELEASE_TAG=golden-" >> $GITHUB_ENV
-
+      
      - name: Set IMAGE_NAME_AND_TAGS variable
        run: echo "IMAGE_NAME_AND_TAGS=${{ env.CONTAINER_NAME }}:${{ env.RELEASE_TAG }}${{ steps.get_version.outputs.result }}" >> $GITHUB_ENV
-
+        
      - name: New env vars
        run: echo "RELEASE_TAG='$RELEASE_TAG' GIT_TAG='$GIT_TAG' IMAGE_NAME_AND_TAGS='$IMAGE_NAME_AND_TAGS'"        

@@ -26,7 +26,7 @@ jobs:
          git config --global user.name "Lawrence Stalder"

      - name: Get version from cargo.toml
-        uses: mikefarah/yq@v4.45.4
+        uses: mikefarah/yq@v4.47.1
        id: get_version
        with:
          cmd: yq -oy '.package.version' ${{ env.WORKING_DIRECTORY }}/nym-api/Cargo.toml
@@ -26,7 +26,7 @@ jobs:
          git config --global user.name "Lawrence Stalder"

      - name: Get version from cargo.toml
-        uses: mikefarah/yq@v4.45.4
+        uses: mikefarah/yq@v4.47.1
        id: get_version
        with:
          cmd: yq -oy '.package.version' ${{ env.WORKING_DIRECTORY }}/Cargo.toml
@@ -26,7 +26,7 @@ jobs:
          git config --global user.name "Lawrence Stalder"

      - name: Get version from cargo.toml
-        uses: mikefarah/yq@v4.45.4
+        uses: mikefarah/yq@v4.47.1
        id: get_version
        with:
          cmd: yq -oy '.package.version' ${{ env.WORKING_DIRECTORY }}/Cargo.toml
@@ -26,7 +26,7 @@ jobs:
          git config --global user.name "Lawrence Stalder"

      - name: Get version from cargo.toml
-        uses: mikefarah/yq@v4.45.4
+        uses: mikefarah/yq@v4.47.1
        id: get_version
        with:
          cmd: yq -oy '.package.version' ${{ env.WORKING_DIRECTORY }}/Cargo.toml
@@ -26,7 +26,7 @@ jobs:
          git config --global user.name "Lawrence Stalder"

      - name: Get version from cargo.toml
-        uses: mikefarah/yq@v4.45.4
+        uses: mikefarah/yq@v4.47.1
        id: get_version
        with:
          cmd: yq -oy '.package.version' ${{ env.WORKING_DIRECTORY }}/Cargo.toml
@@ -4,6 +4,48 @@ Post 1.0.0 release, the changelog format is based on [Keep a Changelog](https://

 ## [Unreleased]

+## [2025.16-halloumi] (2025-09-16)
+
+- Backport metadata endpoint ([#6010])
+- bugfix: make sure tables are removed in correct order to not trigger FK constraint issue ([#5987])
+- chore: move authenticator into gateway crate ([#5982])
+- Fix the ns api ci workflow ([#5981])
+- Remove freshness check on testrun submit ([#5977])
+- Update sysinfo to the latest ([#5976])
+- bugfix: manually calculate per node work on rewarded set changes ([#5972])
+- fixing the ci for ns agent ([#5965])
+- Feature/testing utils ([#5963])
+- bugfix: fix ci-build for linux (and use updated runner) ([#5958])
+- chore: updated refs to cheddar rev of nym repo ([#5955])
+- http api client adjustment ([#5953])
+- chore: fix rust 1.89 clippy issues ([#5944])
+- Wireguard metadata client library ([#5943])
+- chore: remove unused import ([#5942])
+- feat: introduce additional checks when attempting to send to bounded channels ([#5941])
+- Move credential verifier in peer controller ([#5938])
+- change PK/FK on expiration date signatures tables ([#5934])
+- Wireguard private metadata ([#5915])
+
+[#6010]: https://github.com/nymtech/nym/pull/6010
+[#5987]: https://github.com/nymtech/nym/pull/5987
+[#5982]: https://github.com/nymtech/nym/pull/5982
+[#5981]: https://github.com/nymtech/nym/pull/5981
+[#5977]: https://github.com/nymtech/nym/pull/5977
+[#5976]: https://github.com/nymtech/nym/pull/5976
+[#5972]: https://github.com/nymtech/nym/pull/5972
+[#5965]: https://github.com/nymtech/nym/pull/5965
+[#5963]: https://github.com/nymtech/nym/pull/5963
+[#5958]: https://github.com/nymtech/nym/pull/5958
+[#5955]: https://github.com/nymtech/nym/pull/5955
+[#5953]: https://github.com/nymtech/nym/pull/5953
+[#5944]: https://github.com/nymtech/nym/pull/5944
+[#5943]: https://github.com/nymtech/nym/pull/5943
+[#5942]: https://github.com/nymtech/nym/pull/5942
+[#5941]: https://github.com/nymtech/nym/pull/5941
+[#5938]: https://github.com/nymtech/nym/pull/5938
+[#5934]: https://github.com/nymtech/nym/pull/5934
+[#5915]: https://github.com/nymtech/nym/pull/5915
+
 ## [2025.15-gruyere] (2025-08-20)

 - Migrate strum to 0.27.2 ([#5960])
@@ -43,6 +43,7 @@ members = [
    "common/cosmwasm-smart-contracts/nym-performance-contract",
    "common/cosmwasm-smart-contracts/nym-pool-contract",
    "common/cosmwasm-smart-contracts/vesting-contract",
+    "common/credential-proxy",
    "common/credential-storage",
    "common/credential-utils",
    "common/credential-verification",
@@ -53,12 +54,11 @@ members = [
    "common/ecash-signer-check",
    "common/ecash-signer-check-types",
    "common/ecash-time",
-    "common/execute",
    "common/exit-policy",
    "common/gateway-requests",
    "common/gateway-stats-storage",
    "common/gateway-storage",
-    "common/http-api-client",
+    "common/http-api-client", "common/http-api-client-macro",
    "common/http-api-common",
    "common/inclusion-probability",
    "common/ip-packet-requests",
@@ -66,7 +66,7 @@ members = [
    "common/mixnode-common",
    "common/network-defaults",
    "common/node-tester-utils",
-    "common/nonexhaustive-delayqueue",
+    "common/nonexhaustive-delayqueue", "common/nym-cache",
    "common/nym-id",
    "common/nym-metrics",
    "common/nym_offline_compact_ecash",
@@ -85,6 +85,7 @@ members = [
    "common/nymsphinx/types",
    "common/nyxd-scraper",
    "common/pemstore",
+    "common/registration",
    "common/serde-helpers",
    "common/service-provider-requests-common",
    "common/socks5-client-core",
@@ -92,11 +93,12 @@ members = [
    "common/socks5/requests",
    "common/statistics",
    "common/store-cipher",
-    "common/task", "common/test-utils",
+    "common/task",
+    "common/test-utils",
    "common/ticketbooks-merkle",
    "common/topology",
    "common/tun",
-    "common/types",
+    "common/types", "common/upgrade-mode-check",
    "common/verloc",
    "common/wasm/client-core",
    "common/wasm/storage",
@@ -125,10 +127,11 @@ members = [
    "nym-node-status-api/nym-node-status-client",
    "nym-node/nym-node-metrics",
    "nym-node/nym-node-requests",
-    "nym-outfox",
+    "nym-outfox", 
+    "nym-registration-client",
+    "nym-signers-monitor",
    "nym-statistics-api",
    "nym-validator-rewarder",
-    "nym-wg-gateway-client",
    "nyx-chain-watcher",
    "sdk/ffi/cpp",
    "sdk/ffi/go",
@@ -145,7 +148,6 @@ members = [
    # "tools/internal/sdk-version-bump",
    "tools/internal/ssl-inject",
    "tools/internal/testnet-manager",
-    "tools/internal/testnet-manager",
    "tools/internal/testnet-manager/dkg-bypass-contract",
    "tools/internal/validator-status-check",
    "tools/nym-cli",
@@ -226,7 +228,7 @@ clap_complete = "4.5"
 clap_complete_fig = "4.5"
 colored = "2.2"
 comfy-table = "7.1.4"
-console = "0.15.11"
+console = "0.16.0"
 console-subscriber = "0.4.1"
 console_error_panic_hook = "0.1"
 const-str = "0.5.6"
@@ -273,11 +275,13 @@ humantime = "2.2.0"
 humantime-serde = "1.1.1"
 hyper = "1.6.0"
 hyper-util = "0.1"
-indicatif = "0.17.11"
+indicatif = "0.18.0"
 inquire = "0.6.2"
+inventory = "0.3.21"
 ip_network = "0.4.1"
 ipnetwork = "0.20"
 itertools = "0.14.0"
+jwt-simple = { version = "0.12.12", default-features = false, features = ["pure-rust"] }
 k256 = "0.13"
 lazy_static = "1.5.0"
 ledger-transport = "0.10.0"
@@ -321,6 +325,7 @@ serde_json_path = "0.7.2"
 serde_repr = "0.1"
 serde_with = "3.9.0"
 serde_yaml = "0.9.25"
+serde_plain = "1.0.2"
 sha2 = "0.10.9"
 si-scale = "0.2.3"
 snow = "0.9.6"
@@ -329,14 +334,15 @@ sqlx = "0.8.6"
 strum = "0.27.2"
 strum_macros = "0.27.2"
 subtle-encoding = "0.5"
-syn = "1"
+syn = "2"
 sysinfo = "0.37.0"
 tap = "1.0.1"
 tar = "0.4.44"
+test-with = { version = "0.15.4", default-features = false }
 tempfile = "3.20"
 thiserror = "2.0"
 time = "0.3.41"
-tokio = "1.45"
+tokio = "1.47"
 tokio-postgres = "0.7"
 tokio-stream = "0.1.17"
 tokio-test = "0.4.4"
@@ -1,6 +1,6 @@
 [package]
 name = "nym-client"
-version = "1.1.61"
+version = "1.1.63"
 authors = ["Dave Hrycyszyn <futurechimp@users.noreply.github.com>", "Jędrzej Stuczyński <andrew@nymtech.net>"]
 description = "Implementation of the Nym Client"
 edition = "2021"
@@ -11,7 +11,7 @@ use nym_client_core::client::base_client::{
    BaseClientBuilder, ClientInput, ClientOutput, ClientState,
 };
 use nym_sphinx::params::PacketType;
-use nym_task::TaskHandle;
+use nym_task::ShutdownManager;
 use nym_validator_client::QueryHttpRpcNyxdClient;
 use std::error::Error;
 use std::path::PathBuf;
@@ -29,6 +29,8 @@ pub struct SocketClient {

    /// Optional path to a .json file containing standalone network details.
    custom_mixnet: Option<PathBuf>,
+
+    shutdown_manager: ShutdownManager,
 }

 impl SocketClient {
@@ -40,6 +42,7 @@ impl SocketClient {
        SocketClient {
            config,
            custom_mixnet,
+            shutdown_manager: Default::default(),
        }
    }

@@ -49,7 +52,7 @@ impl SocketClient {
        client_output: ClientOutput,
        client_state: ClientState,
        self_address: &Recipient,
-        task_client: nym_task::TaskClient,
+        shutdown_token: nym_task::ShutdownToken,
        packet_type: PacketType,
    ) {
        info!("Starting websocket listener...");
@@ -77,24 +80,24 @@ impl SocketClient {
            shared_lane_queue_lengths,
            reply_controller_sender,
            Some(packet_type),
-            task_client.fork("websocket_handler"),
+            shutdown_token.clone(),
        );

        websocket::Listener::new(
            config.socket.host,
            config.socket.listening_port,
-            task_client.with_suffix("websocket_listener"),
+            shutdown_token.child_token(),
        )
        .start(websocket_handler);
    }

    /// blocking version of `start_socket` method. Will run forever (or until SIGINT is sent)
    pub async fn run_socket_forever(self) -> Result<(), Box<dyn Error + Send + Sync>> {
-        let shutdown = self.start_socket().await?;
+        let mut shutdown = self.start_socket().await?;

-        let res = shutdown.wait_for_shutdown().await;
+        shutdown.run_until_shutdown().await;
        log::info!("Stopping nym-client");
-        res
+        Ok(())
    }

    async fn initialise_storage(&self) -> Result<OnDiskPersistent, ClientError> {
@@ -119,6 +122,7 @@ impl SocketClient {

        let mut base_client =
            BaseClientBuilder::new(self.config().base(), storage, dkg_query_client)
+                .with_shutdown(self.shutdown_manager.shutdown_tracker_owned())
                .with_user_agent(user_agent);

        if let Some(custom_mixnet) = &self.custom_mixnet {
@@ -128,7 +132,7 @@ impl SocketClient {
        Ok(base_client)
    }

-    pub async fn start_socket(self) -> Result<TaskHandle, ClientError> {
+    pub async fn start_socket(self) -> Result<ShutdownManager, ClientError> {
        if !self.config.socket.socket_type.is_websocket() {
            return Err(ClientError::InvalidSocketMode);
        }
@@ -147,13 +151,13 @@ impl SocketClient {
            client_output,
            client_state,
            &self_address,
-            started_client.task_handle.get_handle(),
+            self.shutdown_manager.child_shutdown_token(),
            packet_type,
        );

        info!("Client startup finished!");
        info!("The address of this client is: {self_address}");

-        Ok(started_client.task_handle)
+        Ok(self.shutdown_manager)
    }
 }
@@ -19,7 +19,7 @@ use nym_sphinx::receiver::ReconstructedMessage;
 use nym_task::connections::{
    ConnectionCommand, ConnectionCommandSender, ConnectionId, LaneQueueLengths, TransmissionLane,
 };
-use nym_task::TaskClient;
+use nym_task::ShutdownToken;
 use std::time::Duration;
 use tokio::net::TcpStream;
 use tokio::time::Instant;
@@ -44,7 +44,7 @@ pub(crate) struct HandlerBuilder {
    lane_queue_lengths: LaneQueueLengths,
    reply_controller_sender: ReplyControllerSender,
    packet_type: Option<PacketType>,
-    task_client: TaskClient,
+    shutdown_token: ShutdownToken,
 }

 impl HandlerBuilder {
@@ -57,7 +57,7 @@ impl HandlerBuilder {
        lane_queue_lengths: LaneQueueLengths,
        reply_controller_sender: ReplyControllerSender,
        packet_type: Option<PacketType>,
-        task_client: TaskClient,
+        shutdown_token: ShutdownToken,
    ) -> Self {
        Self {
            msg_input,
@@ -67,14 +67,13 @@ impl HandlerBuilder {
            lane_queue_lengths,
            reply_controller_sender,
            packet_type,
-            task_client,
+            shutdown_token,
        }
    }

    // TODO: make sure we only ever have one active handler
    pub fn create_active_handler(&self) -> Handler {
-        let mut task_client = self.task_client.fork("active_handler");
-        task_client.disarm();
+        let shutdown_token = self.shutdown_token.clone();
        Handler {
            msg_input: self.msg_input.clone(),
            client_connection_tx: self.client_connection_tx.clone(),
@@ -85,7 +84,7 @@ impl HandlerBuilder {
            lane_queue_lengths: self.lane_queue_lengths.clone(),
            reply_controller_sender: self.reply_controller_sender.clone(),
            packet_type: self.packet_type,
-            task_client,
+            shutdown_token,
        }
    }
 }
@@ -100,19 +99,14 @@ pub(crate) struct Handler {
    lane_queue_lengths: LaneQueueLengths,
    reply_controller_sender: ReplyControllerSender,
    packet_type: Option<PacketType>,
-    task_client: TaskClient,
+    shutdown_token: ShutdownToken,
 }

 impl Drop for Handler {
    fn drop(&mut self) {
-        if let Err(err) = self
+        let _ = self
            .buffer_requester
-            .unbounded_send(ReceivedBufferMessage::ReceiverDisconnect)
-        {
-            if !self.task_client.is_shutdown_poll() {
-                error!("failed to disconnect the receiver from the buffer: {err}");
-            }
-        }
+            .unbounded_send(ReceivedBufferMessage::ReceiverDisconnect);
    }
 }

@@ -142,7 +136,7 @@ impl Handler {
        {
            Ok(length) => length,
            Err(err) => {
-                if !self.task_client.is_shutdown_poll() {
+                if !self.shutdown_token.is_cancelled() {
                    error!(
                        "Failed to get reply queue length for connection {connection_id}: {err}"
                    );
@@ -192,7 +186,7 @@ impl Handler {
        // the ack control is now responsible for chunking, etc.
        let input_msg = InputMessage::new_regular(recipient, message, lane, self.packet_type);
        if let Err(err) = self.msg_input.send(input_msg).await {
-            if !self.task_client.is_shutdown_poll() {
+            if !self.shutdown_token.is_cancelled() {
                error!("Failed to send message to the input buffer: {err}");
            }
        }
@@ -225,7 +219,7 @@ impl Handler {
        let input_msg =
            InputMessage::new_anonymous(recipient, message, reply_surbs, lane, self.packet_type);
        if let Err(err) = self.msg_input.send(input_msg).await {
-            if !self.task_client.is_shutdown_poll() {
+            if !self.shutdown_token.is_cancelled() {
                error!("Failed to send anonymous message to the input buffer: {err}");
            }
        }
@@ -253,7 +247,7 @@ impl Handler {

        let input_msg = InputMessage::new_reply(recipient_tag, message, lane, self.packet_type);
        if let Err(err) = self.msg_input.send(input_msg).await {
-            if !self.task_client.is_shutdown_poll() {
+            if !self.shutdown_token.is_cancelled() {
                error!("Failed to send reply message to the input buffer: {err}");
            }
        }
@@ -275,7 +269,7 @@ impl Handler {
            .client_connection_tx
            .unbounded_send(ConnectionCommand::Close(connection_id))
        {
-            if !self.task_client.is_shutdown_poll() {
+            if !self.shutdown_token.is_cancelled() {
                error!("Failed to send close connection command: {err}");
            }
        }
@@ -394,11 +388,14 @@ impl Handler {
    }

    async fn listen_for_requests(&mut self, mut msg_receiver: ReconstructedMessagesReceiver) {
-        let mut task_client = self.task_client.fork("select");
-        task_client.disarm();
+        let shutdown_token = self.shutdown_token.clone();

-        while !task_client.is_shutdown() {
+        loop {
            tokio::select! {
+                  _ = shutdown_token.cancelled() => {
+                    log::trace!("Websocket handler: Received shutdown");
+                    break;
+                }
                // we can either get a client request from the websocket
                socket_msg = self.next_websocket_request() => {
                    if socket_msg.is_none() {
@@ -436,9 +433,6 @@ impl Handler {
                        break;
                    }
                }
-                _ = task_client.recv() => {
-                    log::trace!("Websocket handler: Received shutdown");
-                }
            }
        }
        log::debug!("Websocket handler: Exiting");
@@ -464,7 +458,7 @@ impl Handler {
                    reconstructed_sender,
                ))
        {
-            if !self.task_client.is_shutdown_poll() {
+            if !self.shutdown_token.is_cancelled() {
                error!("failed to announce the receiver to the buffer: {err}");
            }
        }
@@ -3,7 +3,7 @@

 use super::handler::HandlerBuilder;
 use log::*;
-use nym_task::TaskClient;
+use nym_task::ShutdownToken;
 use std::net::IpAddr;
 use std::{net::SocketAddr, process, sync::Arc};
 use tokio::io::AsyncWriteExt;
@@ -23,15 +23,15 @@ impl State {
 pub(crate) struct Listener {
    address: SocketAddr,
    state: State,
-    task_client: TaskClient,
+    shutdown_token: ShutdownToken,
 }

 impl Listener {
-    pub(crate) fn new(host: IpAddr, port: u16, task_client: TaskClient) -> Self {
+    pub(crate) fn new(host: IpAddr, port: u16, shutdown_token: ShutdownToken) -> Self {
        Listener {
            address: SocketAddr::new(host, port),
            state: State::AwaitingConnection,
-            task_client,
+            shutdown_token,
        }
    }

@@ -46,11 +46,11 @@ impl Listener {

        let notify = Arc::new(Notify::new());

-        while !self.task_client.is_shutdown() {
+        while !self.shutdown_token.is_cancelled() {
            tokio::select! {
                // When the handler finishes we check if shutdown is signalled
                _ = notify.notified() => {
-                    if self.task_client.is_shutdown() {
+                    if self.shutdown_token.is_cancelled() {
                        log::trace!("Websocket listener: detected shutdown after connection closed");
                        break;
                    }
@@ -59,7 +59,7 @@ impl Listener {
                }
                // ... but when there is no connected client at the time of shutdown being
                // signalled, we handle it here.
-                _ = self.task_client.recv() => {
+                _ = self.shutdown_token.cancelled() => {
                    if !self.state.is_connected() {
                        log::trace!("Not connected: shutting down");
                        break;
@@ -1,6 +1,6 @@
 [package]
 name = "nym-socks5-client"
-version = "1.1.61"
+version = "1.1.63"
 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"
@@ -13,6 +13,8 @@ base64 = { workspace = true }
 bincode = { workspace = true }
 rand = { workspace = true }
 serde = { workspace = true, features = ["derive"] }
+semver = { workspace = true }
+strum_macros = { workspace = true }
 thiserror = { workspace = true }

 nym-credentials-interface = { path = "../credentials-interface" }
@@ -0,0 +1,272 @@
+// Copyright 2025 Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: GPL-3.0-only
+
+use nym_sphinx::addressing::Recipient;
+use nym_wireguard_types::PeerPublicKey;
+
+use crate::{
+    latest::registration::IpPair,
+    traits::{FinalMessage, InitMessage, QueryBandwidthMessage, TopUpMessage, Versionable},
+    v2, v3, v4, v5, AuthenticatorVersion, Error,
+};
+
+// This is very redundant with AuthenticatorRequest and I reckon they could be smooshed.
+// It is a bit out of scope for me at the moment though
+#[derive(Debug)]
+pub enum ClientMessage {
+    Initial(Box<dyn InitMessage + Send + Sync + 'static>),
+    Final(Box<dyn FinalMessage + Send + Sync + 'static>),
+    Query(Box<dyn QueryBandwidthMessage + Send + Sync + 'static>),
+    TopUp(Box<dyn TopUpMessage + Send + Sync + 'static>),
+}
+
+impl ClientMessage {
+    // check if message is wasteful e.g. contains a credential
+    pub fn is_wasteful(&self) -> bool {
+        match self {
+            Self::Final(msg) => msg.credential().is_some(),
+            Self::TopUp(_) => true,
+            Self::Initial(_) | Self::Query(_) => false,
+        }
+    }
+
+    fn version(&self) -> AuthenticatorVersion {
+        match self {
+            ClientMessage::Initial(msg) => msg.version(),
+            ClientMessage::Final(msg) => msg.version(),
+            ClientMessage::Query(msg) => msg.version(),
+            ClientMessage::TopUp(msg) => msg.version(),
+        }
+    }
+
+    pub fn bytes(&self, reply_to: Recipient) -> Result<(Vec<u8>, u64), Error> {
+        match self.version() {
+            AuthenticatorVersion::V1 => Err(Error::UnsupportedVersion),
+            AuthenticatorVersion::V2 => {
+                use v2::{
+                    registration::{ClientMac, FinalMessage, GatewayClient, InitMessage},
+                    request::AuthenticatorRequest,
+                };
+                match self {
+                    ClientMessage::Initial(init_message) => {
+                        let (req, id) = AuthenticatorRequest::new_initial_request(
+                            InitMessage {
+                                pub_key: init_message.pub_key(),
+                            },
+                            reply_to,
+                        );
+                        Ok((req.to_bytes()?, id))
+                    }
+                    ClientMessage::Final(final_message) => {
+                        let (req, id) = AuthenticatorRequest::new_final_request(
+                            FinalMessage {
+                                gateway_client: GatewayClient {
+                                    pub_key: final_message.gateway_client_pub_key(),
+                                    private_ip: final_message
+                                        .gateway_client_ipv4()
+                                        .ok_or(Error::UnsupportedMessage)?
+                                        .into(),
+                                    mac: ClientMac::new(final_message.gateway_client_mac()),
+                                },
+                                credential: final_message.credential(),
+                            },
+                            reply_to,
+                        );
+                        Ok((req.to_bytes()?, id))
+                    }
+                    ClientMessage::Query(query_message) => {
+                        let (req, id) = AuthenticatorRequest::new_query_request(
+                            query_message.pub_key(),
+                            reply_to,
+                        );
+                        Ok((req.to_bytes()?, id))
+                    }
+                    _ => Err(Error::UnsupportedMessage),
+                }
+            }
+            AuthenticatorVersion::V3 => {
+                use v3::{
+                    registration::{ClientMac, FinalMessage, GatewayClient, InitMessage},
+                    request::AuthenticatorRequest,
+                    topup::TopUpMessage,
+                };
+                match self {
+                    ClientMessage::Initial(init_message) => {
+                        let (req, id) = AuthenticatorRequest::new_initial_request(
+                            InitMessage {
+                                pub_key: init_message.pub_key(),
+                            },
+                            reply_to,
+                        );
+                        Ok((req.to_bytes()?, id))
+                    }
+                    ClientMessage::Final(final_message) => {
+                        let (req, id) = AuthenticatorRequest::new_final_request(
+                            FinalMessage {
+                                gateway_client: GatewayClient {
+                                    pub_key: final_message.gateway_client_pub_key(),
+                                    private_ip: final_message
+                                        .gateway_client_ipv4()
+                                        .ok_or(Error::UnsupportedMessage)?
+                                        .into(),
+                                    mac: ClientMac::new(final_message.gateway_client_mac()),
+                                },
+                                credential: final_message.credential(),
+                            },
+                            reply_to,
+                        );
+                        Ok((req.to_bytes()?, id))
+                    }
+                    ClientMessage::Query(query_message) => {
+                        let (req, id) = AuthenticatorRequest::new_query_request(
+                            query_message.pub_key(),
+                            reply_to,
+                        );
+                        Ok((req.to_bytes()?, id))
+                    }
+                    ClientMessage::TopUp(top_up_message) => {
+                        let (req, id) = AuthenticatorRequest::new_topup_request(
+                            TopUpMessage {
+                                pub_key: top_up_message.pub_key(),
+                                credential: top_up_message.credential(),
+                            },
+                            reply_to,
+                        );
+                        Ok((req.to_bytes()?, id))
+                    }
+                }
+            }
+            AuthenticatorVersion::V4 => {
+                use v4::{
+                    registration::{ClientMac, FinalMessage, GatewayClient, InitMessage},
+                    request::AuthenticatorRequest,
+                    topup::TopUpMessage,
+                };
+                match self {
+                    ClientMessage::Initial(init_message) => {
+                        let (req, id) = AuthenticatorRequest::new_initial_request(
+                            InitMessage {
+                                pub_key: init_message.pub_key(),
+                            },
+                            reply_to,
+                        );
+                        Ok((req.to_bytes()?, id))
+                    }
+                    ClientMessage::Final(final_message) => {
+                        let (req, id) = AuthenticatorRequest::new_final_request(
+                            FinalMessage {
+                                gateway_client: GatewayClient {
+                                    pub_key: final_message.gateway_client_pub_key(),
+                                    private_ips: IpPair {
+                                        ipv4: final_message
+                                            .gateway_client_ipv4()
+                                            .ok_or(Error::UnsupportedMessage)?,
+                                        ipv6: final_message
+                                            .gateway_client_ipv6()
+                                            .ok_or(Error::UnsupportedMessage)?,
+                                    }
+                                    .into(),
+                                    mac: ClientMac::new(final_message.gateway_client_mac()),
+                                },
+                                credential: final_message.credential(),
+                            },
+                            reply_to,
+                        );
+                        Ok((req.to_bytes()?, id))
+                    }
+                    ClientMessage::Query(query_message) => {
+                        let (req, id) = AuthenticatorRequest::new_query_request(
+                            query_message.pub_key(),
+                            reply_to,
+                        );
+                        Ok((req.to_bytes()?, id))
+                    }
+                    ClientMessage::TopUp(top_up_message) => {
+                        let (req, id) = AuthenticatorRequest::new_topup_request(
+                            TopUpMessage {
+                                pub_key: top_up_message.pub_key(),
+                                credential: top_up_message.credential(),
+                            },
+                            reply_to,
+                        );
+                        Ok((req.to_bytes()?, id))
+                    }
+                }
+            }
+            AuthenticatorVersion::V5 => {
+                use v5::{
+                    registration::{ClientMac, FinalMessage, GatewayClient, InitMessage},
+                    request::AuthenticatorRequest,
+                    topup::TopUpMessage,
+                };
+                match self {
+                    ClientMessage::Initial(init_message) => {
+                        let (req, id) = AuthenticatorRequest::new_initial_request(InitMessage {
+                            pub_key: init_message.pub_key(),
+                        });
+                        Ok((req.to_bytes()?, id))
+                    }
+                    ClientMessage::Final(final_message) => {
+                        let (req, id) = AuthenticatorRequest::new_final_request(FinalMessage {
+                            gateway_client: GatewayClient {
+                                pub_key: final_message.gateway_client_pub_key(),
+                                private_ips: IpPair {
+                                    ipv4: final_message
+                                        .gateway_client_ipv4()
+                                        .ok_or(Error::UnsupportedMessage)?,
+                                    ipv6: final_message
+                                        .gateway_client_ipv6()
+                                        .ok_or(Error::UnsupportedMessage)?,
+                                },
+                                mac: ClientMac::new(final_message.gateway_client_mac()),
+                            },
+                            credential: final_message.credential(),
+                        });
+                        Ok((req.to_bytes()?, id))
+                    }
+                    ClientMessage::Query(query_message) => {
+                        let (req, id) =
+                            AuthenticatorRequest::new_query_request(query_message.pub_key());
+                        Ok((req.to_bytes()?, id))
+                    }
+                    ClientMessage::TopUp(top_up_message) => {
+                        let (req, id) = AuthenticatorRequest::new_topup_request(TopUpMessage {
+                            pub_key: top_up_message.pub_key(),
+                            credential: top_up_message.credential(),
+                        });
+                        Ok((req.to_bytes()?, id))
+                    }
+                }
+            }
+            AuthenticatorVersion::UNKNOWN => Err(Error::UnknownVersion),
+        }
+    }
+
+    pub fn use_surbs(&self) -> bool {
+        use AuthenticatorVersion::*;
+        match self.version() {
+            V1 | V2 | V3 | V4 => false,
+            V5 => true,
+            UNKNOWN => true,
+        }
+    }
+}
+
+// Same comment as above struct
+#[derive(Debug)]
+pub struct QueryMessageImpl {
+    pub pub_key: PeerPublicKey,
+    pub version: AuthenticatorVersion,
+}
+
+impl Versionable for QueryMessageImpl {
+    fn version(&self) -> AuthenticatorVersion {
+        self.version
+    }
+}
+
+impl QueryBandwidthMessage for QueryMessageImpl {
+    fn pub_key(&self) -> PeerPublicKey {
+        self.pub_key
+    }
+}
@@ -23,6 +23,17 @@ pub enum Error {
    #[error("conversion: {0}")]
    Conversion(String),

-    #[error("failed to serialize response packet: {source}")]
-    FailedToSerializeResponsePacket { source: Box<bincode::ErrorKind> },
+    // TODO add version number for debugging
+    #[error("unknown version number")]
+    UnknownVersion,
+
+    // TODO add version number for debugging
+    #[error("unsupported request version")]
+    UnsupportedVersion,
+
+    #[error("gateway doesn't support this type of message")]
+    UnsupportedMessage,
+
+    #[error(transparent)]
+    Bincode(#[from] bincode::Error),
 }
@@ -1,6 +1,9 @@
 // Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

+pub mod client_message;
+pub mod request;
+pub mod response;
 pub mod traits;
 pub mod v1;
 pub mod v2;
@@ -10,11 +13,13 @@ pub mod v5;

 mod error;
 mod util;
+mod version;

 pub use error::Error;
 pub use v5 as latest;
+pub use version::AuthenticatorVersion;

-pub const CURRENT_VERSION: u8 = 5;
+pub const CURRENT_VERSION: u8 = latest::VERSION;

 fn make_bincode_serializer() -> impl bincode::Options {
    use bincode::Options;
@@ -0,0 +1,204 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use nym_service_provider_requests_common::{Protocol, ServiceProviderType};
+use nym_sphinx::addressing::Recipient;
+
+use crate::traits::{FinalMessage, InitMessage, QueryBandwidthMessage, TopUpMessage};
+use crate::{v1, v2, v3, v4, v5};
+
+#[derive(Debug)]
+pub enum AuthenticatorRequest {
+    Initial {
+        msg: Box<dyn InitMessage + Send + Sync + 'static>,
+        protocol: Protocol,
+        reply_to: Option<Recipient>,
+        request_id: u64,
+    },
+    Final {
+        msg: Box<dyn FinalMessage + Send + Sync + 'static>,
+        protocol: Protocol,
+        reply_to: Option<Recipient>,
+        request_id: u64,
+    },
+    QueryBandwidth {
+        msg: Box<dyn QueryBandwidthMessage + Send + Sync + 'static>,
+        protocol: Protocol,
+        reply_to: Option<Recipient>,
+        request_id: u64,
+    },
+    TopUpBandwidth {
+        msg: Box<dyn TopUpMessage + Send + Sync + 'static>,
+        protocol: Protocol,
+        reply_to: Option<Recipient>,
+        request_id: u64,
+    },
+}
+
+impl From<v1::request::AuthenticatorRequest> for AuthenticatorRequest {
+    fn from(value: v1::request::AuthenticatorRequest) -> Self {
+        match value.data {
+            v1::request::AuthenticatorRequestData::Initial(init_message) => Self::Initial {
+                msg: Box::new(init_message),
+                protocol: Protocol {
+                    version: value.version,
+                    service_provider_type: ServiceProviderType::Authenticator,
+                },
+                reply_to: Some(value.reply_to),
+                request_id: value.request_id,
+            },
+            v1::request::AuthenticatorRequestData::Final(gateway_client) => Self::Final {
+                msg: Box::new(gateway_client),
+                protocol: Protocol {
+                    version: value.version,
+                    service_provider_type: ServiceProviderType::Authenticator,
+                },
+                reply_to: Some(value.reply_to),
+                request_id: value.request_id,
+            },
+            v1::request::AuthenticatorRequestData::QueryBandwidth(peer_public_key) => {
+                Self::QueryBandwidth {
+                    msg: Box::new(peer_public_key),
+                    protocol: Protocol {
+                        version: value.version,
+                        service_provider_type: ServiceProviderType::Authenticator,
+                    },
+                    reply_to: Some(value.reply_to),
+                    request_id: value.request_id,
+                }
+            }
+        }
+    }
+}
+
+impl From<v2::request::AuthenticatorRequest> for AuthenticatorRequest {
+    fn from(value: v2::request::AuthenticatorRequest) -> Self {
+        match value.data {
+            v2::request::AuthenticatorRequestData::Initial(init_message) => Self::Initial {
+                msg: Box::new(init_message),
+                protocol: value.protocol,
+                reply_to: Some(value.reply_to),
+                request_id: value.request_id,
+            },
+            v2::request::AuthenticatorRequestData::Final(final_message) => Self::Final {
+                msg: final_message,
+                protocol: value.protocol,
+                reply_to: Some(value.reply_to),
+                request_id: value.request_id,
+            },
+            v2::request::AuthenticatorRequestData::QueryBandwidth(peer_public_key) => {
+                Self::QueryBandwidth {
+                    msg: Box::new(peer_public_key),
+                    protocol: value.protocol,
+                    reply_to: Some(value.reply_to),
+                    request_id: value.request_id,
+                }
+            }
+        }
+    }
+}
+
+impl From<v3::request::AuthenticatorRequest> for AuthenticatorRequest {
+    fn from(value: v3::request::AuthenticatorRequest) -> Self {
+        match value.data {
+            v3::request::AuthenticatorRequestData::Initial(init_message) => Self::Initial {
+                msg: Box::new(init_message),
+                protocol: value.protocol,
+                reply_to: Some(value.reply_to),
+                request_id: value.request_id,
+            },
+            v3::request::AuthenticatorRequestData::Final(final_message) => Self::Final {
+                msg: final_message,
+                protocol: value.protocol,
+                reply_to: Some(value.reply_to),
+                request_id: value.request_id,
+            },
+            v3::request::AuthenticatorRequestData::QueryBandwidth(peer_public_key) => {
+                Self::QueryBandwidth {
+                    msg: Box::new(peer_public_key),
+                    protocol: value.protocol,
+                    reply_to: Some(value.reply_to),
+                    request_id: value.request_id,
+                }
+            }
+            v3::request::AuthenticatorRequestData::TopUpBandwidth(top_up_message) => {
+                Self::TopUpBandwidth {
+                    msg: top_up_message,
+                    protocol: value.protocol,
+                    reply_to: Some(value.reply_to),
+                    request_id: value.request_id,
+                }
+            }
+        }
+    }
+}
+
+impl From<v4::request::AuthenticatorRequest> for AuthenticatorRequest {
+    fn from(value: v4::request::AuthenticatorRequest) -> Self {
+        match value.data {
+            v4::request::AuthenticatorRequestData::Initial(init_message) => Self::Initial {
+                msg: Box::new(init_message),
+                protocol: value.protocol,
+                reply_to: Some(value.reply_to),
+                request_id: value.request_id,
+            },
+            v4::request::AuthenticatorRequestData::Final(final_message) => Self::Final {
+                msg: final_message,
+                protocol: value.protocol,
+                reply_to: Some(value.reply_to),
+                request_id: value.request_id,
+            },
+            v4::request::AuthenticatorRequestData::QueryBandwidth(peer_public_key) => {
+                Self::QueryBandwidth {
+                    msg: Box::new(peer_public_key),
+                    protocol: value.protocol,
+                    reply_to: Some(value.reply_to),
+                    request_id: value.request_id,
+                }
+            }
+            v4::request::AuthenticatorRequestData::TopUpBandwidth(top_up_message) => {
+                Self::TopUpBandwidth {
+                    msg: top_up_message,
+                    protocol: value.protocol,
+                    reply_to: Some(value.reply_to),
+                    request_id: value.request_id,
+                }
+            }
+        }
+    }
+}
+
+impl From<v5::request::AuthenticatorRequest> for AuthenticatorRequest {
+    fn from(value: v5::request::AuthenticatorRequest) -> Self {
+        match value.data {
+            v5::request::AuthenticatorRequestData::Initial(init_message) => Self::Initial {
+                msg: Box::new(init_message),
+                protocol: value.protocol,
+                reply_to: None,
+                request_id: value.request_id,
+            },
+            v5::request::AuthenticatorRequestData::Final(final_message) => Self::Final {
+                msg: final_message,
+                protocol: value.protocol,
+                reply_to: None,
+                request_id: value.request_id,
+            },
+            v5::request::AuthenticatorRequestData::QueryBandwidth(peer_public_key) => {
+                Self::QueryBandwidth {
+                    msg: Box::new(peer_public_key),
+                    protocol: value.protocol,
+                    reply_to: None,
+                    request_id: value.request_id,
+                }
+            }
+            v5::request::AuthenticatorRequestData::TopUpBandwidth(top_up_message) => {
+                Self::TopUpBandwidth {
+                    msg: top_up_message,
+                    protocol: value.protocol,
+                    reply_to: None,
+                    request_id: value.request_id,
+                }
+            }
+        }
+    }
+}
@@ -0,0 +1,106 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::traits::{
+    Id, PendingRegistrationResponse, RegisteredResponse, RemainingBandwidthResponse,
+    TopUpBandwidthResponse,
+};
+use crate::{v2, v3, v4, v5};
+
+#[derive(Debug)]
+pub enum AuthenticatorResponse {
+    PendingRegistration(Box<dyn PendingRegistrationResponse + Send + Sync + 'static>),
+    Registered(Box<dyn RegisteredResponse + Send + Sync + 'static>),
+    RemainingBandwidth(Box<dyn RemainingBandwidthResponse + Send + Sync + 'static>),
+    TopUpBandwidth(Box<dyn TopUpBandwidthResponse + Send + Sync + 'static>),
+}
+
+impl Id for AuthenticatorResponse {
+    fn id(&self) -> u64 {
+        match self {
+            AuthenticatorResponse::PendingRegistration(pending_registration_response) => {
+                pending_registration_response.id()
+            }
+            AuthenticatorResponse::Registered(registered_response) => registered_response.id(),
+            AuthenticatorResponse::RemainingBandwidth(remaining_bandwidth_response) => {
+                remaining_bandwidth_response.id()
+            }
+            AuthenticatorResponse::TopUpBandwidth(top_up_bandwidth_response) => {
+                top_up_bandwidth_response.id()
+            }
+        }
+    }
+}
+
+impl From<v2::response::AuthenticatorResponse> for AuthenticatorResponse {
+    fn from(value: v2::response::AuthenticatorResponse) -> Self {
+        match value.data {
+            v2::response::AuthenticatorResponseData::PendingRegistration(
+                pending_registration_response,
+            ) => Self::PendingRegistration(Box::new(pending_registration_response)),
+            v2::response::AuthenticatorResponseData::Registered(registered_response) => {
+                Self::Registered(Box::new(registered_response))
+            }
+            v2::response::AuthenticatorResponseData::RemainingBandwidth(
+                remaining_bandwidth_response,
+            ) => Self::RemainingBandwidth(Box::new(remaining_bandwidth_response)),
+        }
+    }
+}
+
+impl From<v3::response::AuthenticatorResponse> for AuthenticatorResponse {
+    fn from(value: v3::response::AuthenticatorResponse) -> Self {
+        match value.data {
+            v3::response::AuthenticatorResponseData::PendingRegistration(
+                pending_registration_response,
+            ) => Self::PendingRegistration(Box::new(pending_registration_response)),
+            v3::response::AuthenticatorResponseData::Registered(registered_response) => {
+                Self::Registered(Box::new(registered_response))
+            }
+            v3::response::AuthenticatorResponseData::RemainingBandwidth(
+                remaining_bandwidth_response,
+            ) => Self::RemainingBandwidth(Box::new(remaining_bandwidth_response)),
+            v3::response::AuthenticatorResponseData::TopUpBandwidth(top_up_bandwidth_response) => {
+                Self::TopUpBandwidth(Box::new(top_up_bandwidth_response))
+            }
+        }
+    }
+}
+
+impl From<v4::response::AuthenticatorResponse> for AuthenticatorResponse {
+    fn from(value: v4::response::AuthenticatorResponse) -> Self {
+        match value.data {
+            v4::response::AuthenticatorResponseData::PendingRegistration(
+                pending_registration_response,
+            ) => Self::PendingRegistration(Box::new(pending_registration_response)),
+            v4::response::AuthenticatorResponseData::Registered(registered_response) => {
+                Self::Registered(Box::new(registered_response))
+            }
+            v4::response::AuthenticatorResponseData::RemainingBandwidth(
+                remaining_bandwidth_response,
+            ) => Self::RemainingBandwidth(Box::new(remaining_bandwidth_response)),
+            v4::response::AuthenticatorResponseData::TopUpBandwidth(top_up_bandwidth_response) => {
+                Self::TopUpBandwidth(Box::new(top_up_bandwidth_response))
+            }
+        }
+    }
+}
+
+impl From<v5::response::AuthenticatorResponse> for AuthenticatorResponse {
+    fn from(value: v5::response::AuthenticatorResponse) -> Self {
+        match value.data {
+            v5::response::AuthenticatorResponseData::PendingRegistration(
+                pending_registration_response,
+            ) => Self::PendingRegistration(Box::new(pending_registration_response)),
+            v5::response::AuthenticatorResponseData::Registered(registered_response) => {
+                Self::Registered(Box::new(registered_response))
+            }
+            v5::response::AuthenticatorResponseData::RemainingBandwidth(
+                remaining_bandwidth_response,
+            ) => Self::RemainingBandwidth(Box::new(remaining_bandwidth_response)),
+            v5::response::AuthenticatorResponseData::TopUpBandwidth(top_up_bandwidth_response) => {
+                Self::TopUpBandwidth(Box::new(top_up_bandwidth_response))
+            }
+        }
+    }
+}
@@ -1,49 +1,105 @@
 // Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

+use std::fmt;
+use std::net::{Ipv4Addr, Ipv6Addr};
+
 use nym_credentials_interface::CredentialSpendingData;
 use nym_crypto::asymmetric::x25519::PrivateKey;
-use nym_service_provider_requests_common::{Protocol, ServiceProviderType};
-use nym_sphinx::addressing::clients::Recipient;
 use nym_wireguard_types::PeerPublicKey;

-use crate::{
-    v1, v2, v3, v4,
-    v5::{self, registration::IpPair},
-    Error,
-};
+use crate::latest::registration::IpPair;
+use crate::{v1, v2, v3, v4, v5, AuthenticatorVersion, Error};

-#[derive(Copy, Clone, Debug)]
-pub enum AuthenticatorVersion {
-    V1,
-    V2,
-    V3,
-    V4,
-    V5,
-    UNKNOWN,
+pub trait Versionable {
+    fn version(&self) -> AuthenticatorVersion;
 }

-impl From<Protocol> for AuthenticatorVersion {
-    fn from(value: Protocol) -> Self {
-        if value.service_provider_type != ServiceProviderType::Authenticator {
-            AuthenticatorVersion::UNKNOWN
-        } else if value.version == v1::VERSION {
-            AuthenticatorVersion::V1
-        } else if value.version == v2::VERSION {
-            AuthenticatorVersion::V2
-        } else if value.version == v3::VERSION {
-            AuthenticatorVersion::V3
-        } else if value.version == v4::VERSION {
-            AuthenticatorVersion::V4
-        } else if value.version == v5::VERSION {
-            AuthenticatorVersion::V5
-        } else {
-            AuthenticatorVersion::UNKNOWN
-        }
+impl Versionable for v1::GatewayClient {
+    fn version(&self) -> AuthenticatorVersion {
+        AuthenticatorVersion::V1
    }
 }

-pub trait InitMessage {
+impl Versionable for v1::registration::InitMessage {
+    fn version(&self) -> AuthenticatorVersion {
+        AuthenticatorVersion::V1
+    }
+}
+
+impl Versionable for v2::registration::InitMessage {
+    fn version(&self) -> AuthenticatorVersion {
+        AuthenticatorVersion::V2
+    }
+}
+
+impl Versionable for v3::registration::InitMessage {
+    fn version(&self) -> AuthenticatorVersion {
+        AuthenticatorVersion::V3
+    }
+}
+
+impl Versionable for v4::registration::InitMessage {
+    fn version(&self) -> AuthenticatorVersion {
+        AuthenticatorVersion::V4
+    }
+}
+
+impl Versionable for v5::registration::InitMessage {
+    fn version(&self) -> AuthenticatorVersion {
+        AuthenticatorVersion::V5
+    }
+}
+
+impl Versionable for v2::registration::FinalMessage {
+    fn version(&self) -> AuthenticatorVersion {
+        AuthenticatorVersion::V2
+    }
+}
+
+impl Versionable for v3::registration::FinalMessage {
+    fn version(&self) -> AuthenticatorVersion {
+        AuthenticatorVersion::V3
+    }
+}
+
+impl Versionable for v4::registration::FinalMessage {
+    fn version(&self) -> AuthenticatorVersion {
+        AuthenticatorVersion::V4
+    }
+}
+
+impl Versionable for v5::registration::FinalMessage {
+    fn version(&self) -> AuthenticatorVersion {
+        AuthenticatorVersion::V5
+    }
+}
+
+impl Versionable for PeerPublicKey {
+    fn version(&self) -> AuthenticatorVersion {
+        AuthenticatorVersion::V3
+    }
+}
+
+impl Versionable for v3::topup::TopUpMessage {
+    fn version(&self) -> AuthenticatorVersion {
+        AuthenticatorVersion::V3
+    }
+}
+
+impl Versionable for v4::topup::TopUpMessage {
+    fn version(&self) -> AuthenticatorVersion {
+        AuthenticatorVersion::V4
+    }
+}
+
+impl Versionable for v5::topup::TopUpMessage {
+    fn version(&self) -> AuthenticatorVersion {
+        AuthenticatorVersion::V5
+    }
+}
+
+pub trait InitMessage: Versionable + fmt::Debug {
    fn pub_key(&self) -> PeerPublicKey;
 }

@@ -77,15 +133,18 @@ impl InitMessage for v5::registration::InitMessage {
    }
 }

-pub trait FinalMessage {
-    fn pub_key(&self) -> PeerPublicKey;
+pub trait FinalMessage: Versionable + fmt::Debug {
+    fn gateway_client_pub_key(&self) -> PeerPublicKey;
    fn verify(&self, private_key: &PrivateKey, nonce: u64) -> Result<(), Error>;
    fn private_ips(&self) -> IpPair;
+    fn gateway_client_ipv4(&self) -> Option<Ipv4Addr>;
+    fn gateway_client_ipv6(&self) -> Option<Ipv6Addr>;
+    fn gateway_client_mac(&self) -> Vec<u8>;
    fn credential(&self) -> Option<CredentialSpendingData>;
 }

 impl FinalMessage for v1::GatewayClient {
-    fn pub_key(&self) -> PeerPublicKey {
+    fn gateway_client_pub_key(&self) -> PeerPublicKey {
        self.pub_key
    }

@@ -97,13 +156,28 @@ impl FinalMessage for v1::GatewayClient {
        self.private_ip.into()
    }

+    fn gateway_client_ipv4(&self) -> Option<Ipv4Addr> {
+        match self.private_ip {
+            std::net::IpAddr::V4(ipv4_addr) => Some(ipv4_addr),
+            std::net::IpAddr::V6(_) => None,
+        }
+    }
+
+    fn gateway_client_ipv6(&self) -> Option<Ipv6Addr> {
+        None
+    }
+
+    fn gateway_client_mac(&self) -> Vec<u8> {
+        self.mac.to_vec()
+    }
+
    fn credential(&self) -> Option<CredentialSpendingData> {
        None
    }
 }

 impl FinalMessage for v2::registration::FinalMessage {
-    fn pub_key(&self) -> PeerPublicKey {
+    fn gateway_client_pub_key(&self) -> PeerPublicKey {
        self.gateway_client.pub_key
    }

@@ -115,13 +189,28 @@ impl FinalMessage for v2::registration::FinalMessage {
        self.gateway_client.private_ip.into()
    }

+    fn gateway_client_ipv4(&self) -> Option<Ipv4Addr> {
+        match self.gateway_client.private_ip {
+            std::net::IpAddr::V4(ipv4_addr) => Some(ipv4_addr),
+            std::net::IpAddr::V6(_) => None,
+        }
+    }
+
+    fn gateway_client_ipv6(&self) -> Option<Ipv6Addr> {
+        None
+    }
+
+    fn gateway_client_mac(&self) -> Vec<u8> {
+        self.gateway_client.mac.to_vec()
+    }
+
    fn credential(&self) -> Option<CredentialSpendingData> {
        self.credential.clone()
    }
 }

 impl FinalMessage for v3::registration::FinalMessage {
-    fn pub_key(&self) -> PeerPublicKey {
+    fn gateway_client_pub_key(&self) -> PeerPublicKey {
        self.gateway_client.pub_key
    }

@@ -133,13 +222,28 @@ impl FinalMessage for v3::registration::FinalMessage {
        self.gateway_client.private_ip.into()
    }

+    fn gateway_client_ipv4(&self) -> Option<Ipv4Addr> {
+        match self.gateway_client.private_ip {
+            std::net::IpAddr::V4(ipv4_addr) => Some(ipv4_addr),
+            std::net::IpAddr::V6(_) => None,
+        }
+    }
+
+    fn gateway_client_ipv6(&self) -> Option<Ipv6Addr> {
+        None
+    }
+
+    fn gateway_client_mac(&self) -> Vec<u8> {
+        self.gateway_client.mac.to_vec()
+    }
+
    fn credential(&self) -> Option<CredentialSpendingData> {
        self.credential.clone()
    }
 }

 impl FinalMessage for v4::registration::FinalMessage {
-    fn pub_key(&self) -> PeerPublicKey {
+    fn gateway_client_pub_key(&self) -> PeerPublicKey {
        self.gateway_client.pub_key
    }

@@ -151,13 +255,25 @@ impl FinalMessage for v4::registration::FinalMessage {
        self.gateway_client.private_ips.into()
    }

+    fn gateway_client_ipv4(&self) -> Option<Ipv4Addr> {
+        Some(self.gateway_client.private_ips.ipv4)
+    }
+
+    fn gateway_client_ipv6(&self) -> Option<Ipv6Addr> {
+        Some(self.gateway_client.private_ips.ipv6)
+    }
+
+    fn gateway_client_mac(&self) -> Vec<u8> {
+        self.gateway_client.mac.to_vec()
+    }
+
    fn credential(&self) -> Option<CredentialSpendingData> {
        self.credential.clone()
    }
 }

 impl FinalMessage for v5::registration::FinalMessage {
-    fn pub_key(&self) -> PeerPublicKey {
+    fn gateway_client_pub_key(&self) -> PeerPublicKey {
        self.gateway_client.pub_key
    }

@@ -169,12 +285,24 @@ impl FinalMessage for v5::registration::FinalMessage {
        self.gateway_client.private_ips
    }

+    fn gateway_client_ipv4(&self) -> Option<Ipv4Addr> {
+        Some(self.gateway_client.private_ips.ipv4)
+    }
+
+    fn gateway_client_ipv6(&self) -> Option<Ipv6Addr> {
+        Some(self.gateway_client.private_ips.ipv6)
+    }
+
+    fn gateway_client_mac(&self) -> Vec<u8> {
+        self.gateway_client.mac.to_vec()
+    }
+
    fn credential(&self) -> Option<CredentialSpendingData> {
        self.credential.clone()
    }
 }

-pub trait QueryBandwidthMessage {
+pub trait QueryBandwidthMessage: Versionable + fmt::Debug {
    fn pub_key(&self) -> PeerPublicKey;
 }

@@ -184,7 +312,7 @@ impl QueryBandwidthMessage for PeerPublicKey {
    }
 }

-pub trait TopUpMessage {
+pub trait TopUpMessage: Versionable + fmt::Debug {
    fn pub_key(&self) -> PeerPublicKey;
    fn credential(&self) -> CredentialSpendingData;
 }
@@ -219,197 +347,286 @@ impl TopUpMessage for v5::topup::TopUpMessage {
    }
 }

-pub enum AuthenticatorRequest {
-    Initial {
-        msg: Box<dyn InitMessage + Send + Sync + 'static>,
-        protocol: Protocol,
-        reply_to: Option<Recipient>,
-        request_id: u64,
-    },
-    Final {
-        msg: Box<dyn FinalMessage + Send + Sync + 'static>,
-        protocol: Protocol,
-        reply_to: Option<Recipient>,
-        request_id: u64,
-    },
-    QueryBandwidth {
-        msg: Box<dyn QueryBandwidthMessage + Send + Sync + 'static>,
-        protocol: Protocol,
-        reply_to: Option<Recipient>,
-        request_id: u64,
-    },
-    TopUpBandwidth {
-        msg: Box<dyn TopUpMessage + Send + Sync + 'static>,
-        protocol: Protocol,
-        reply_to: Option<Recipient>,
-        request_id: u64,
-    },
+pub trait Id {
+    fn id(&self) -> u64;
 }

-impl From<v1::request::AuthenticatorRequest> for AuthenticatorRequest {
-    fn from(value: v1::request::AuthenticatorRequest) -> Self {
-        match value.data {
-            v1::request::AuthenticatorRequestData::Initial(init_message) => Self::Initial {
-                msg: Box::new(init_message),
-                protocol: Protocol {
-                    version: value.version,
-                    service_provider_type: ServiceProviderType::Authenticator,
-                },
-                reply_to: Some(value.reply_to),
-                request_id: value.request_id,
-            },
-            v1::request::AuthenticatorRequestData::Final(gateway_client) => Self::Final {
-                msg: Box::new(gateway_client),
-                protocol: Protocol {
-                    version: value.version,
-                    service_provider_type: ServiceProviderType::Authenticator,
-                },
-                reply_to: Some(value.reply_to),
-                request_id: value.request_id,
-            },
-            v1::request::AuthenticatorRequestData::QueryBandwidth(peer_public_key) => {
-                Self::QueryBandwidth {
-                    msg: Box::new(peer_public_key),
-                    protocol: Protocol {
-                        version: value.version,
-                        service_provider_type: ServiceProviderType::Authenticator,
-                    },
-                    reply_to: Some(value.reply_to),
-                    request_id: value.request_id,
-                }
-            }
-        }
+impl Id for v2::response::PendingRegistrationResponse {
+    fn id(&self) -> u64 {
+        self.request_id
    }
 }

-impl From<v2::request::AuthenticatorRequest> for AuthenticatorRequest {
-    fn from(value: v2::request::AuthenticatorRequest) -> Self {
-        match value.data {
-            v2::request::AuthenticatorRequestData::Initial(init_message) => Self::Initial {
-                msg: Box::new(init_message),
-                protocol: value.protocol,
-                reply_to: Some(value.reply_to),
-                request_id: value.request_id,
-            },
-            v2::request::AuthenticatorRequestData::Final(final_message) => Self::Final {
-                msg: final_message,
-                protocol: value.protocol,
-                reply_to: Some(value.reply_to),
-                request_id: value.request_id,
-            },
-            v2::request::AuthenticatorRequestData::QueryBandwidth(peer_public_key) => {
-                Self::QueryBandwidth {
-                    msg: Box::new(peer_public_key),
-                    protocol: value.protocol,
-                    reply_to: Some(value.reply_to),
-                    request_id: value.request_id,
-                }
-            }
-        }
+impl Id for v3::response::PendingRegistrationResponse {
+    fn id(&self) -> u64 {
+        self.request_id
    }
 }

-impl From<v3::request::AuthenticatorRequest> for AuthenticatorRequest {
-    fn from(value: v3::request::AuthenticatorRequest) -> Self {
-        match value.data {
-            v3::request::AuthenticatorRequestData::Initial(init_message) => Self::Initial {
-                msg: Box::new(init_message),
-                protocol: value.protocol,
-                reply_to: Some(value.reply_to),
-                request_id: value.request_id,
-            },
-            v3::request::AuthenticatorRequestData::Final(final_message) => Self::Final {
-                msg: final_message,
-                protocol: value.protocol,
-                reply_to: Some(value.reply_to),
-                request_id: value.request_id,
-            },
-            v3::request::AuthenticatorRequestData::QueryBandwidth(peer_public_key) => {
-                Self::QueryBandwidth {
-                    msg: Box::new(peer_public_key),
-                    protocol: value.protocol,
-                    reply_to: Some(value.reply_to),
-                    request_id: value.request_id,
-                }
-            }
-            v3::request::AuthenticatorRequestData::TopUpBandwidth(top_up_message) => {
-                Self::TopUpBandwidth {
-                    msg: top_up_message,
-                    protocol: value.protocol,
-                    reply_to: Some(value.reply_to),
-                    request_id: value.request_id,
-                }
-            }
-        }
+impl Id for v4::response::PendingRegistrationResponse {
+    fn id(&self) -> u64 {
+        self.request_id
    }
 }

-impl From<v4::request::AuthenticatorRequest> for AuthenticatorRequest {
-    fn from(value: v4::request::AuthenticatorRequest) -> Self {
-        match value.data {
-            v4::request::AuthenticatorRequestData::Initial(init_message) => Self::Initial {
-                msg: Box::new(init_message),
-                protocol: value.protocol,
-                reply_to: Some(value.reply_to),
-                request_id: value.request_id,
-            },
-            v4::request::AuthenticatorRequestData::Final(final_message) => Self::Final {
-                msg: final_message,
-                protocol: value.protocol,
-                reply_to: Some(value.reply_to),
-                request_id: value.request_id,
-            },
-            v4::request::AuthenticatorRequestData::QueryBandwidth(peer_public_key) => {
-                Self::QueryBandwidth {
-                    msg: Box::new(peer_public_key),
-                    protocol: value.protocol,
-                    reply_to: Some(value.reply_to),
-                    request_id: value.request_id,
-                }
-            }
-            v4::request::AuthenticatorRequestData::TopUpBandwidth(top_up_message) => {
-                Self::TopUpBandwidth {
-                    msg: top_up_message,
-                    protocol: value.protocol,
-                    reply_to: Some(value.reply_to),
-                    request_id: value.request_id,
-                }
-            }
-        }
+impl Id for v5::response::PendingRegistrationResponse {
+    fn id(&self) -> u64 {
+        self.request_id
    }
 }

-impl From<v5::request::AuthenticatorRequest> for AuthenticatorRequest {
-    fn from(value: v5::request::AuthenticatorRequest) -> Self {
-        match value.data {
-            v5::request::AuthenticatorRequestData::Initial(init_message) => Self::Initial {
-                msg: Box::new(init_message),
-                protocol: value.protocol,
-                reply_to: None,
-                request_id: value.request_id,
-            },
-            v5::request::AuthenticatorRequestData::Final(final_message) => Self::Final {
-                msg: final_message,
-                protocol: value.protocol,
-                reply_to: None,
-                request_id: value.request_id,
-            },
-            v5::request::AuthenticatorRequestData::QueryBandwidth(peer_public_key) => {
-                Self::QueryBandwidth {
-                    msg: Box::new(peer_public_key),
-                    protocol: value.protocol,
-                    reply_to: None,
-                    request_id: value.request_id,
-                }
-            }
-            v5::request::AuthenticatorRequestData::TopUpBandwidth(top_up_message) => {
-                Self::TopUpBandwidth {
-                    msg: top_up_message,
-                    protocol: value.protocol,
-                    reply_to: None,
-                    request_id: value.request_id,
-                }
-            }
-        }
+impl Id for v2::response::RegisteredResponse {
+    fn id(&self) -> u64 {
+        self.request_id
+    }
+}
+
+impl Id for v3::response::RegisteredResponse {
+    fn id(&self) -> u64 {
+        self.request_id
+    }
+}
+
+impl Id for v4::response::RegisteredResponse {
+    fn id(&self) -> u64 {
+        self.request_id
+    }
+}
+
+impl Id for v5::response::RegisteredResponse {
+    fn id(&self) -> u64 {
+        self.request_id
+    }
+}
+
+impl Id for v2::response::RemainingBandwidthResponse {
+    fn id(&self) -> u64 {
+        self.request_id
+    }
+}
+
+impl Id for v3::response::RemainingBandwidthResponse {
+    fn id(&self) -> u64 {
+        self.request_id
+    }
+}
+
+impl Id for v4::response::RemainingBandwidthResponse {
+    fn id(&self) -> u64 {
+        self.request_id
+    }
+}
+
+impl Id for v5::response::RemainingBandwidthResponse {
+    fn id(&self) -> u64 {
+        self.request_id
+    }
+}
+
+impl Id for v3::response::TopUpBandwidthResponse {
+    fn id(&self) -> u64 {
+        self.request_id
+    }
+}
+
+impl Id for v4::response::TopUpBandwidthResponse {
+    fn id(&self) -> u64 {
+        self.request_id
+    }
+}
+
+impl Id for v5::response::TopUpBandwidthResponse {
+    fn id(&self) -> u64 {
+        self.request_id
+    }
+}
+
+pub trait PendingRegistrationResponse: Id + fmt::Debug {
+    fn nonce(&self) -> u64;
+    fn verify(&self, gateway_key: &PrivateKey) -> std::result::Result<(), Error>;
+    fn pub_key(&self) -> PeerPublicKey;
+    fn private_ips(&self) -> IpPair;
+}
+
+impl PendingRegistrationResponse for v2::response::PendingRegistrationResponse {
+    fn nonce(&self) -> u64 {
+        self.reply.nonce
+    }
+
+    fn verify(&self, gateway_key: &PrivateKey) -> std::result::Result<(), Error> {
+        self.reply.gateway_data.verify(gateway_key, self.nonce())
+    }
+
+    fn pub_key(&self) -> PeerPublicKey {
+        self.reply.gateway_data.pub_key
+    }
+
+    fn private_ips(&self) -> IpPair {
+        self.reply.gateway_data.private_ip.into()
+    }
+}
+
+impl PendingRegistrationResponse for v3::response::PendingRegistrationResponse {
+    fn nonce(&self) -> u64 {
+        self.reply.nonce
+    }
+
+    fn verify(&self, gateway_key: &PrivateKey) -> std::result::Result<(), Error> {
+        self.reply.gateway_data.verify(gateway_key, self.nonce())
+    }
+
+    fn pub_key(&self) -> PeerPublicKey {
+        self.reply.gateway_data.pub_key
+    }
+
+    fn private_ips(&self) -> IpPair {
+        self.reply.gateway_data.private_ip.into()
+    }
+}
+
+impl PendingRegistrationResponse for v4::response::PendingRegistrationResponse {
+    fn nonce(&self) -> u64 {
+        self.reply.nonce
+    }
+
+    fn verify(&self, gateway_key: &PrivateKey) -> std::result::Result<(), Error> {
+        self.reply.gateway_data.verify(gateway_key, self.nonce())
+    }
+
+    fn pub_key(&self) -> PeerPublicKey {
+        self.reply.gateway_data.pub_key
+    }
+
+    fn private_ips(&self) -> IpPair {
+        self.reply.gateway_data.private_ips.into()
+    }
+}
+
+impl PendingRegistrationResponse for v5::response::PendingRegistrationResponse {
+    fn nonce(&self) -> u64 {
+        self.reply.nonce
+    }
+
+    fn verify(&self, gateway_key: &PrivateKey) -> std::result::Result<(), Error> {
+        self.reply.gateway_data.verify(gateway_key, self.nonce())
+    }
+
+    fn pub_key(&self) -> PeerPublicKey {
+        self.reply.gateway_data.pub_key
+    }
+
+    fn private_ips(&self) -> IpPair {
+        self.reply.gateway_data.private_ips
+    }
+}
+
+pub trait RegisteredResponse: Id + fmt::Debug {
+    fn private_ips(&self) -> IpPair;
+    fn pub_key(&self) -> PeerPublicKey;
+    fn wg_port(&self) -> u16;
+}
+
+impl RegisteredResponse for v2::response::RegisteredResponse {
+    fn private_ips(&self) -> IpPair {
+        self.reply.private_ip.into()
+    }
+
+    fn pub_key(&self) -> PeerPublicKey {
+        self.reply.pub_key
+    }
+
+    fn wg_port(&self) -> u16 {
+        self.reply.wg_port
+    }
+}
+
+impl RegisteredResponse for v3::response::RegisteredResponse {
+    fn private_ips(&self) -> IpPair {
+        self.reply.private_ip.into()
+    }
+
+    fn pub_key(&self) -> PeerPublicKey {
+        self.reply.pub_key
+    }
+
+    fn wg_port(&self) -> u16 {
+        self.reply.wg_port
+    }
+}
+impl RegisteredResponse for v4::response::RegisteredResponse {
+    fn private_ips(&self) -> IpPair {
+        self.reply.private_ips.into()
+    }
+
+    fn pub_key(&self) -> PeerPublicKey {
+        self.reply.pub_key
+    }
+
+    fn wg_port(&self) -> u16 {
+        self.reply.wg_port
+    }
+}
+
+impl RegisteredResponse for v5::response::RegisteredResponse {
+    fn private_ips(&self) -> IpPair {
+        self.reply.private_ips
+    }
+
+    fn pub_key(&self) -> PeerPublicKey {
+        self.reply.pub_key
+    }
+
+    fn wg_port(&self) -> u16 {
+        self.reply.wg_port
+    }
+}
+
+pub trait RemainingBandwidthResponse: Id + fmt::Debug {
+    fn available_bandwidth(&self) -> Option<i64>;
+}
+
+impl RemainingBandwidthResponse for v2::response::RemainingBandwidthResponse {
+    fn available_bandwidth(&self) -> Option<i64> {
+        self.reply.as_ref().map(|r| r.available_bandwidth)
+    }
+}
+
+impl RemainingBandwidthResponse for v3::response::RemainingBandwidthResponse {
+    fn available_bandwidth(&self) -> Option<i64> {
+        self.reply.as_ref().map(|r| r.available_bandwidth)
+    }
+}
+
+impl RemainingBandwidthResponse for v4::response::RemainingBandwidthResponse {
+    fn available_bandwidth(&self) -> Option<i64> {
+        self.reply.as_ref().map(|r| r.available_bandwidth)
+    }
+}
+
+impl RemainingBandwidthResponse for v5::response::RemainingBandwidthResponse {
+    fn available_bandwidth(&self) -> Option<i64> {
+        self.reply.as_ref().map(|r| r.available_bandwidth)
+    }
+}
+
+pub trait TopUpBandwidthResponse: Id + fmt::Debug {
+    fn available_bandwidth(&self) -> i64;
+}
+
+impl TopUpBandwidthResponse for v3::response::TopUpBandwidthResponse {
+    fn available_bandwidth(&self) -> i64 {
+        self.reply.available_bandwidth
+    }
+}
+
+impl TopUpBandwidthResponse for v4::response::TopUpBandwidthResponse {
+    fn available_bandwidth(&self) -> i64 {
+        self.reply.available_bandwidth
+    }
+}
+
+impl TopUpBandwidthResponse for v5::response::TopUpBandwidthResponse {
+    fn available_bandwidth(&self) -> i64 {
+        self.reply.available_bandwidth
    }
 }
@@ -0,0 +1,191 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use super::{v1, v2, v3, v4, v5};
+use nym_service_provider_requests_common::{Protocol, ServiceProviderType};
+
+#[derive(Copy, Clone, Debug, PartialEq, strum_macros::Display)]
+#[strum(serialize_all = "snake_case")]
+pub enum AuthenticatorVersion {
+    /// introduced in wispa release (1.1.5)
+    V1,
+
+    /// introduced in aero release (1.1.9)
+    V2,
+
+    /// introduced in magura release (1.1.10)
+    V3,
+
+    /// introduced in crunch release (1.2.0)
+    V4,
+
+    /// introduced in dorina-patched release (1.6.1)
+    V5,
+
+    UNKNOWN,
+}
+
+impl AuthenticatorVersion {
+    pub const LATEST: Self = Self::V5;
+
+    pub const fn release_version(&self) -> semver::Version {
+        match self {
+            AuthenticatorVersion::V1 => semver::Version::new(1, 1, 5),
+            AuthenticatorVersion::V2 => semver::Version::new(1, 1, 9),
+            AuthenticatorVersion::V3 => semver::Version::new(1, 1, 10),
+            AuthenticatorVersion::V4 => semver::Version::new(1, 2, 0),
+            AuthenticatorVersion::V5 => semver::Version::new(1, 6, 1),
+            AuthenticatorVersion::UNKNOWN => semver::Version::new(0, 0, 0),
+        }
+    }
+}
+
+impl From<Protocol> for AuthenticatorVersion {
+    fn from(value: Protocol) -> Self {
+        if value.service_provider_type != ServiceProviderType::Authenticator {
+            AuthenticatorVersion::UNKNOWN
+        } else if value.version == v1::VERSION {
+            AuthenticatorVersion::V1
+        } else if value.version == v2::VERSION {
+            AuthenticatorVersion::V2
+        } else if value.version == v3::VERSION {
+            AuthenticatorVersion::V3
+        } else if value.version == v4::VERSION {
+            AuthenticatorVersion::V4
+        } else if value.version == v5::VERSION {
+            AuthenticatorVersion::V5
+        } else {
+            AuthenticatorVersion::UNKNOWN
+        }
+    }
+}
+
+impl From<u8> for AuthenticatorVersion {
+    fn from(value: u8) -> Self {
+        if value == v1::VERSION {
+            AuthenticatorVersion::V1
+        } else if value == v2::VERSION {
+            AuthenticatorVersion::V2
+        } else if value == v3::VERSION {
+            AuthenticatorVersion::V3
+        } else if value == v4::VERSION {
+            AuthenticatorVersion::V4
+        } else if value == v5::VERSION {
+            AuthenticatorVersion::V5
+        } else {
+            AuthenticatorVersion::UNKNOWN
+        }
+    }
+}
+
+impl From<&str> for AuthenticatorVersion {
+    fn from(value: &str) -> Self {
+        let Ok(semver) = semver::Version::parse(value) else {
+            return Self::UNKNOWN;
+        };
+
+        semver.into()
+    }
+}
+
+impl From<Option<&String>> for AuthenticatorVersion {
+    fn from(value: Option<&String>) -> Self {
+        match value {
+            None => Self::UNKNOWN,
+            Some(value) => value.as_str().into(),
+        }
+    }
+}
+
+impl From<String> for AuthenticatorVersion {
+    fn from(value: String) -> Self {
+        Self::from(value.as_str())
+    }
+}
+
+impl From<Option<String>> for AuthenticatorVersion {
+    fn from(value: Option<String>) -> Self {
+        value.as_ref().into()
+    }
+}
+
+impl From<semver::Version> for AuthenticatorVersion {
+    fn from(semver: semver::Version) -> Self {
+        if semver < AuthenticatorVersion::V1.release_version() {
+            return Self::UNKNOWN;
+        }
+        if semver < AuthenticatorVersion::V2.release_version() {
+            return Self::V1;
+        }
+        if semver < AuthenticatorVersion::V3.release_version() {
+            return Self::V2;
+        }
+        if semver < AuthenticatorVersion::V4.release_version() {
+            return Self::V3;
+        }
+        if semver < AuthenticatorVersion::V5.release_version() {
+            return Self::V4;
+        }
+        // if provided version is higher (or equal) to release version of V5,
+        // we return the latest (i.e. v5)
+
+        debug_assert_eq!(Self::V5, Self::LATEST, "a new AuthenticatorVersion variant has been introduced without adjusting the `From<semver::Version>` trait");
+        Self::LATEST
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::latest;
+    use super::*;
+
+    #[test]
+    fn strum_display() {
+        // sanity check on formatting and casing
+        assert_eq!("v1", AuthenticatorVersion::V1.to_string());
+        assert_eq!("v2", AuthenticatorVersion::V2.to_string());
+        assert_eq!("unknown", AuthenticatorVersion::UNKNOWN.to_string());
+    }
+
+    #[test]
+    fn u8_conversion() {
+        assert_eq!(AuthenticatorVersion::V1, AuthenticatorVersion::from(1u8));
+        assert_eq!(AuthenticatorVersion::V2, AuthenticatorVersion::from(2u8));
+
+        assert_eq!(
+            AuthenticatorVersion::UNKNOWN,
+            AuthenticatorVersion::from(latest::VERSION + 1)
+        );
+        assert_eq!(
+            AuthenticatorVersion::UNKNOWN,
+            AuthenticatorVersion::from(0u8)
+        );
+        assert_eq!(
+            AuthenticatorVersion::UNKNOWN,
+            AuthenticatorVersion::from(255u8)
+        );
+    }
+
+    #[test]
+    fn semver_checks() {
+        assert_eq!(AuthenticatorVersion::UNKNOWN, "1.1.4".into());
+        assert_eq!(AuthenticatorVersion::UNKNOWN, "0.1.0".into());
+        assert_eq!(AuthenticatorVersion::UNKNOWN, "1.0.4".into());
+        assert_eq!(AuthenticatorVersion::V1, "1.1.5".into());
+        assert_eq!(AuthenticatorVersion::V1, "1.1.6".into());
+        assert_eq!(AuthenticatorVersion::V1, "1.1.8".into());
+        assert_eq!(AuthenticatorVersion::V2, "1.1.9".into());
+        assert_eq!(AuthenticatorVersion::V3, "1.1.10".into());
+        assert_eq!(AuthenticatorVersion::V3, "1.1.11".into());
+        assert_eq!(AuthenticatorVersion::V3, "1.1.60".into());
+        assert_eq!(AuthenticatorVersion::V4, "1.2.0".into());
+        assert_eq!(AuthenticatorVersion::V4, "1.2.1".into());
+        assert_eq!(AuthenticatorVersion::V4, "1.5.1".into());
+        assert_eq!(AuthenticatorVersion::V4, "1.6.0".into());
+        assert_eq!(AuthenticatorVersion::V5, "1.6.1".into());
+        assert_eq!(AuthenticatorVersion::V5, "1.6.11".into());
+        assert_eq!(AuthenticatorVersion::V5, "1.7.0".into());
+        assert_eq!(AuthenticatorVersion::V5, "1.16.11".into());
+        assert_eq!(AuthenticatorVersion::V5, "1.17.0".into());
+    }
+}
@@ -7,6 +7,7 @@ license.workspace = true
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

 [dependencies]
+async-trait = { workspace =  true }
 bip39 = { workspace = true }
 log = { workspace = true }
 rand = { workspace = true }
@@ -23,10 +23,12 @@ use nym_validator_client::nym_api::EpochId;
 use nym_validator_client::nyxd::contract_traits::DkgQueryClient;

 pub use event::BandwidthStatusMessage;
+pub use traits::{BandwidthTicketProvider, DEFAULT_TICKETS_TO_SPEND};

 pub mod acquire;
 pub mod error;
 mod event;
+mod traits;
 mod utils;

 #[derive(Debug)]
@@ -0,0 +1,42 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use async_trait::async_trait;
+use nym_credential_storage::storage::Storage;
+use nym_credentials_interface::TicketType;
+use nym_crypto::asymmetric::ed25519;
+use nym_validator_client::nyxd::contract_traits::DkgQueryClient;
+
+use crate::{error::BandwidthControllerError, BandwidthController, PreparedCredential};
+
+pub const DEFAULT_TICKETS_TO_SPEND: u32 = 1;
+
+#[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
+#[cfg_attr(not(target_arch = "wasm32"), async_trait)]
+pub trait BandwidthTicketProvider: Send + Sync {
+    async fn get_ecash_ticket(
+        &self,
+        ticket_type: TicketType,
+        gateway_id: ed25519::PublicKey,
+        tickets_to_spend: u32,
+    ) -> Result<PreparedCredential, BandwidthControllerError>;
+}
+
+#[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
+#[cfg_attr(not(target_arch = "wasm32"), async_trait)]
+impl<C, St> BandwidthTicketProvider for BandwidthController<C, St>
+where
+    C: DkgQueryClient + Sync + Send,
+    St: nym_credential_storage::storage::Storage,
+    <St as Storage>::StorageError: Send + Sync + 'static,
+{
+    async fn get_ecash_ticket(
+        &self,
+        ticket_type: TicketType,
+        gateway_id: ed25519::PublicKey,
+        tickets_to_spend: u32,
+    ) -> Result<PreparedCredential, BandwidthControllerError> {
+        self.prepare_ecash_ticket(ticket_type, gateway_id.to_bytes(), tickets_to_spend)
+            .await
+    }
+}
@@ -7,11 +7,12 @@ use super::statistics_control::StatisticsControl;
 use crate::client::base_client::storage::helpers::store_client_keys;
 use crate::client::base_client::storage::MixnetClientStorage;
 use crate::client::cover_traffic_stream::LoopCoverTrafficStream;
+use crate::client::event_control::EventControl;
 use crate::client::inbound_messages::{InputMessage, InputMessageReceiver, InputMessageSender};
 use crate::client::key_manager::persistence::KeyStore;
 use crate::client::key_manager::ClientKeys;
 use crate::client::mix_traffic::transceiver::{GatewayReceiver, GatewayTransceiver, RemoteGateway};
-use crate::client::mix_traffic::{BatchMixMessageSender, MixTrafficController};
+use crate::client::mix_traffic::{BatchMixMessageSender, MixTrafficController, MixTrafficEvent};
 use crate::client::real_messages_control;
 use crate::client::real_messages_control::RealMessagesController;
 use crate::client::received_buffer::{
@@ -27,13 +28,13 @@ use crate::client::topology_control::nym_api_provider::NymApiTopologyProvider;
 use crate::client::topology_control::{
    TopologyAccessor, TopologyRefresher, TopologyRefresherConfig,
 };
+use crate::config;
 use crate::config::{Config, DebugConfig};
 use crate::error::ClientCoreError;
 use crate::init::{
    setup_gateway,
    types::{GatewaySetup, InitialisationResult},
 };
-use crate::{config, spawn_future};
 use futures::channel::mpsc;
 use nym_bandwidth_controller::BandwidthController;
 use nym_client_core_config_types::{ForgetMe, RememberMe};
@@ -48,12 +49,11 @@ use nym_gateway_client::{
 use nym_sphinx::acknowledgements::AckKey;
 use nym_sphinx::addressing::clients::Recipient;
 use nym_sphinx::addressing::nodes::NodeIdentity;
-use nym_sphinx::params::PacketType;
 use nym_sphinx::receiver::{ReconstructedMessage, SphinxMessageReceiver};
 use nym_statistics_common::clients::ClientStatsSender;
 use nym_statistics_common::generate_client_stats_id;
 use nym_task::connections::{ConnectionCommandReceiver, ConnectionCommandSender, LaneQueueLengths};
-use nym_task::{TaskClient, TaskHandle};
+use nym_task::ShutdownTracker;
 use nym_topology::provider_trait::TopologyProvider;
 use nym_topology::HardcodedTopologyProvider;
 use nym_validator_client::nym_api::NymApiClientExt;
@@ -67,7 +67,6 @@ use std::path::Path;
 use std::sync::Arc;
 use time::OffsetDateTime;
 use tokio::sync::mpsc::Sender;
-use tracing::*;
 use url::Url;

 #[cfg(all(
@@ -80,6 +79,23 @@ pub mod non_wasm_helpers;
 pub mod helpers;
 pub mod storage;

+#[derive(Clone, Copy, Debug)]
+pub enum MixnetClientEvent {
+    Traffic(MixTrafficEvent),
+}
+
+pub type EventReceiver = mpsc::UnboundedReceiver<MixnetClientEvent>;
+#[derive(Clone)]
+pub struct EventSender(pub mpsc::UnboundedSender<MixnetClientEvent>);
+
+impl EventSender {
+    pub fn send(&self, event: MixnetClientEvent) {
+        if let Err(err) = self.0.unbounded_send(event) {
+            tracing::warn!("Failed to send error event. The caller event reader was closed: {err}");
+        }
+    }
+}
+
 #[derive(Clone)]
 pub struct ClientInput {
    pub connection_command_sender: ConnectionCommandSender,
@@ -95,7 +111,6 @@ impl ClientInput {
    }
 }

-#[derive(Clone)]
 pub struct ClientOutput {
    pub received_buffer_request_sender: ReceivedBufferRequestSender,
 }
@@ -195,7 +210,8 @@ pub struct BaseClientBuilder<C, S: MixnetClientStorage> {
    wait_for_gateway: bool,
    custom_topology_provider: Option<Box<dyn TopologyProvider + Send + Sync>>,
    custom_gateway_transceiver: Option<Box<dyn GatewayTransceiver + Send>>,
-    shutdown: Option<TaskClient>,
+    shutdown: Option<ShutdownTracker>,
+    event_tx: Option<EventSender>,
    user_agent: Option<UserAgent>,

    setup_method: GatewaySetup,
@@ -224,6 +240,7 @@ where
            custom_topology_provider: None,
            custom_gateway_transceiver: None,
            shutdown: None,
+            event_tx: None,
            user_agent: None,
            setup_method: GatewaySetup::MustLoad { gateway_id: None },
            #[cfg(unix)]
@@ -281,11 +298,17 @@ where
    }

    #[must_use]
-    pub fn with_shutdown(mut self, shutdown: TaskClient) -> Self {
+    pub fn with_shutdown(mut self, shutdown: ShutdownTracker) -> Self {
        self.shutdown = Some(shutdown);
        self
    }

+    #[must_use]
+    pub fn with_event_tx(mut self, event_tx: EventSender) -> Self {
+        self.event_tx = Some(event_tx);
+        self
+    }
+
    #[must_use]
    pub fn with_user_agent(mut self, user_agent: UserAgent) -> Self {
        self.user_agent = Some(user_agent);
@@ -316,6 +339,18 @@ where
        details.client_address()
    }

+    fn start_event_control(
+        parent_event_tx: Option<EventSender>,
+        children_event_rx: EventReceiver,
+        shutdown_tracker: &ShutdownTracker,
+    ) {
+        let event_control = EventControl::new(parent_event_tx, children_event_rx);
+        shutdown_tracker.try_spawn_named_with_shutdown(
+            async move { event_control.run().await },
+            "EventControl",
+        );
+    }
+
    // future constantly pumping loop cover traffic at some specified average rate
    // the pumped traffic goes to the MixTrafficController
    fn start_cover_traffic_stream(
@@ -325,11 +360,11 @@ where
        topology_accessor: TopologyAccessor,
        mix_tx: BatchMixMessageSender,
        stats_tx: ClientStatsSender,
-        task_client: TaskClient,
+        shutdown_tracker: &ShutdownTracker,
    ) {
-        info!("Starting loop cover traffic stream...");
+        tracing::info!("Starting loop cover traffic stream...");

-        let stream = LoopCoverTrafficStream::new(
+        let mut stream = LoopCoverTrafficStream::new(
            ack_key,
            debug_config.acknowledgements.average_ack_delay,
            mix_tx,
@@ -338,10 +373,9 @@ where
            debug_config.traffic,
            debug_config.cover_traffic,
            stats_tx,
-            task_client,
        );
-
-        stream.start();
+        shutdown_tracker
+            .try_spawn_named_with_shutdown(async move { stream.run().await }, "CoverTrafficStream");
    }

    #[allow(clippy::too_many_arguments)]
@@ -357,13 +391,12 @@ where
        reply_controller_receiver: ReplyControllerReceiver,
        lane_queue_lengths: LaneQueueLengths,
        client_connection_rx: ConnectionCommandReceiver,
-        task_client: TaskClient,
-        packet_type: PacketType,
        stats_tx: ClientStatsSender,
+        shutdown_tracker: &ShutdownTracker,
    ) {
-        info!("Starting real traffic stream...");
+        tracing::info!("Starting real traffic stream...");

-        RealMessagesController::new(
+        let real_messages_controller = RealMessagesController::new(
            controller_config,
            key_rotation_config,
            ack_receiver,
@@ -376,9 +409,63 @@ where
            lane_queue_lengths,
            client_connection_rx,
            stats_tx,
-            task_client,
-        )
-        .start(packet_type);
+            shutdown_tracker.clone_shutdown_token(),
+        );
+
+        // break out all the subtasks
+        let (mut out_queue_control, mut reply_controller, ack_controller) =
+            real_messages_controller.into_tasks();
+        let (
+            mut ack_listener,
+            mut input_listener,
+            mut retransmission_listener,
+            mut sent_notification_listener,
+            mut ack_action_controller,
+        ) = ack_controller.into_tasks();
+
+        shutdown_tracker.try_spawn_named(
+            async move { out_queue_control.run().await },
+            "RealMessagesController::OutQueueControl",
+        );
+
+        let shutdown_token = shutdown_tracker.clone_shutdown_token();
+        shutdown_tracker.try_spawn_named(
+            async move { reply_controller.run(shutdown_token).await },
+            "RealMessagesController::ReplyController",
+        );
+
+        let shutdown_token = shutdown_tracker.clone_shutdown_token();
+        shutdown_tracker.try_spawn_named(
+            async move { ack_listener.run(shutdown_token).await },
+            "AcknowledgementController::AcknowledgementListener",
+        );
+
+        let shutdown_token = shutdown_tracker.clone_shutdown_token();
+        shutdown_tracker.try_spawn_named(
+            async move { input_listener.run(shutdown_token).await },
+            "AcknowledgementController::InputMessageListener",
+        );
+
+        let shutdown_token = shutdown_tracker.clone_shutdown_token();
+        shutdown_tracker.try_spawn_named(
+            async move { retransmission_listener.run(shutdown_token).await },
+            "AcknowledgementController::RetransmissionRequestListener",
+        );
+
+        shutdown_tracker.try_spawn_named_with_shutdown(
+            async move {
+                sent_notification_listener.run().await;
+            },
+            "AcknowledgementController::SentNotificationListener",
+        );
+
+        let shutdown_token = shutdown_tracker.clone_shutdown_token();
+        shutdown_tracker.try_spawn_named(
+            async move { ack_action_controller.run(shutdown_token).await },
+            "AcknowledgementController::ActionController",
+        );
+
+        // .start(packet_type);
    }

    // buffer controlling all messages fetched from provider
@@ -389,21 +476,29 @@ where
        mixnet_receiver: MixnetMessageReceiver,
        reply_key_storage: SentReplyKeys,
        reply_controller_sender: ReplyControllerSender,
-        shutdown: TaskClient,
        metrics_reporter: ClientStatsSender,
+        shutdown_tracker: &ShutdownTracker,
    ) {
-        info!("Starting received messages buffer controller...");
-        let controller: ReceivedMessagesBufferController<SphinxMessageReceiver> =
-            ReceivedMessagesBufferController::new(
-                local_encryption_keypair,
-                query_receiver,
-                mixnet_receiver,
-                reply_key_storage,
-                reply_controller_sender,
-                metrics_reporter,
-                shutdown,
-            );
-        controller.start()
+        tracing::info!("Starting received messages buffer controller...");
+        let controller = ReceivedMessagesBufferController::<SphinxMessageReceiver>::new(
+            local_encryption_keypair,
+            query_receiver,
+            mixnet_receiver,
+            reply_key_storage,
+            reply_controller_sender,
+            metrics_reporter,
+            shutdown_tracker.clone_shutdown_token(),
+        );
+        let (mut msg_receiver, mut req_receiver) = controller.into_tasks();
+
+        shutdown_tracker.try_spawn_named(
+            async move { msg_receiver.run().await },
+            "ReceivedMessagesBufferController::FragmentedMessageReceiver",
+        );
+        shutdown_tracker.try_spawn_named(
+            async move { req_receiver.run().await },
+            "ReceivedMessagesBufferController::RequestReceiver",
+        );
    }

    #[allow(clippy::too_many_arguments)]
@@ -415,7 +510,7 @@ where
        packet_router: PacketRouter,
        stats_reporter: ClientStatsSender,
        #[cfg(unix)] connection_fd_callback: Option<Arc<dyn Fn(RawFd) + Send + Sync>>,
-        shutdown: TaskClient,
+        shutdown_tracker: &ShutdownTracker,
    ) -> Result<GatewayClient<C, S::CredentialStore>, ClientCoreError>
    where
        <S::KeyStore as KeyStore>::StorageError: Send + Sync + 'static,
@@ -434,7 +529,7 @@ where
                    packet_router,
                    bandwidth_controller,
                    stats_reporter,
-                    shutdown,
+                    shutdown_tracker.clone_shutdown_token(),
                )
            } else {
                let cfg = GatewayConfig::new(
@@ -459,7 +554,7 @@ where
                    stats_reporter,
                    #[cfg(unix)]
                    connection_fd_callback,
-                    shutdown,
+                    shutdown_tracker.clone_shutdown_token(),
                )
            };

@@ -495,7 +590,7 @@ where
            details_store
                .upgrade_stored_remote_gateway_key(gateway_client.gateway_identity(), &updated_key)
                .await.map_err(|err| {
-                error!("failed to store upgraded gateway key! this connection might be forever broken now: {err}");
+                tracing::error!("failed to store upgraded gateway key! this connection might be forever broken now: {err}");
                ClientCoreError::GatewaysDetailsStoreError { source: Box::new(err) }
            })?
        }
@@ -522,7 +617,7 @@ where
        packet_router: PacketRouter,
        stats_reporter: ClientStatsSender,
        #[cfg(unix)] connection_fd_callback: Option<Arc<dyn Fn(RawFd) + Send + Sync>>,
-        mut shutdown: TaskClient,
+        shutdown_tracker: &ShutdownTracker,
    ) -> Result<Box<dyn GatewayTransceiver + Send>, ClientCoreError>
    where
        <S::KeyStore as KeyStore>::StorageError: Send + Sync + 'static,
@@ -539,7 +634,6 @@ where
                Err(ClientCoreError::CustomGatewaySelectionExpected)
            } else {
                // and make sure to invalidate the task client, so we wouldn't cause premature shutdown
-                shutdown.disarm();
                custom_gateway_transceiver.set_packet_router(packet_router)?;
                Ok(custom_gateway_transceiver)
            };
@@ -555,7 +649,7 @@ where
            stats_reporter,
            #[cfg(unix)]
            connection_fd_callback,
-            shutdown,
+            shutdown_tracker,
        )
        .await?;

@@ -586,26 +680,24 @@ where
        topology_accessor: TopologyAccessor,
        local_gateway: NodeIdentity,
        wait_for_gateway: bool,
-        mut task_client: TaskClient,
+        shutdown_tracker: &ShutdownTracker,
    ) -> Result<(), ClientCoreError> {
        let topology_refresher_config =
            TopologyRefresherConfig::new(topology_config.topology_refresh_rate);

        if topology_config.disable_refreshing {
            // if we're not spawning the refresher, don't cause shutdown immediately
-            info!("The background topology refesher is not going to be started");
-            task_client.disarm();
+            tracing::info!("The background topology refresher is not going to be started");
        }

        let mut topology_refresher = TopologyRefresher::new(
            topology_refresher_config,
            topology_accessor,
            topology_provider,
-            task_client,
        );
        // before returning, block entire runtime to refresh the current network view so that any
        // components depending on topology would see a non-empty view
-        info!("Obtaining initial network topology");
+        tracing::info!("Obtaining initial network topology");
        topology_refresher.try_refresh().await;

        if let Err(err) = topology_refresher.ensure_topology_is_routable().await {
@@ -631,13 +723,13 @@ where
                    .wait_for_gateway(local_gateway, waiting_timeout)
                    .await
                {
-                    error!(
+                    tracing::error!(
                        "the gateway did not come back online within the specified timeout: {err}"
                    );
                    return Err(err.into());
                }
            } else {
-                error!("the gateway we're supposedly connected to does not exist. We'll not be able to send any packets to ourselves: {err}");
+                tracing::error!("the gateway we're supposedly connected to does not exist. We'll not be able to send any packets to ourselves: {err}");
                return Err(err.into());
            }
        }
@@ -645,8 +737,11 @@ where
        if !topology_config.disable_refreshing {
            // 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();
+            tracing::info!("Starting topology refresher...");
+            shutdown_tracker.try_spawn_named_with_shutdown(
+                async move { topology_refresher.run().await },
+                "TopologyRefresher",
+            );
        }

        Ok(())
@@ -657,9 +752,9 @@ where
        user_agent: Option<UserAgent>,
        client_stats_id: String,
        input_sender: Sender<InputMessage>,
-        task_client: TaskClient,
+        shutdown_tracker: &ShutdownTracker,
    ) -> ClientStatsSender {
-        info!("Starting statistics control...");
+        tracing::info!("Starting statistics control...");
        StatisticsControl::create_and_start(
            config.debug.stats_reporting,
            user_agent
@@ -667,18 +762,27 @@ where
                .unwrap_or("unknown".to_string()),
            client_stats_id,
            input_sender.clone(),
-            task_client,
+            shutdown_tracker,
        )
    }

    fn start_mix_traffic_controller(
        gateway_transceiver: Box<dyn GatewayTransceiver + Send>,
-        shutdown: TaskClient,
+        shutdown_tracker: &ShutdownTracker,
+        event_tx: EventSender,
    ) -> (BatchMixMessageSender, ClientRequestSender) {
-        info!("Starting mix traffic controller...");
-        let (mix_traffic_controller, mix_tx, client_tx) =
-            MixTrafficController::new(gateway_transceiver, shutdown);
-        mix_traffic_controller.start();
+        tracing::info!("Starting mix traffic controller...");
+        let (mut mix_traffic_controller, mix_tx, client_tx) = MixTrafficController::new(
+            gateway_transceiver,
+            shutdown_tracker.clone_shutdown_token(),
+            event_tx,
+        );
+
+        shutdown_tracker.try_spawn_named(
+            async move { mix_traffic_controller.run().await },
+            "MixTrafficController",
+        );
+
        (mix_tx, client_tx)
    }

@@ -686,7 +790,7 @@ where
    async fn setup_persistent_reply_storage(
        backend: S::ReplyStore,
        key_rotation_config: KeyRotationConfig,
-        shutdown: TaskClient,
+        shutdown_tracker: &ShutdownTracker,
    ) -> Result<CombinedReplyStorage, ClientCoreError>
    where
        <S::ReplyStore as ReplyStorageBackend>::StorageError: Sync + Send,
@@ -711,13 +815,14 @@ where
            })?;

        let store_clone = mem_store.clone();
-        spawn_future!(
+        let shutdown_token = shutdown_tracker.clone_shutdown_token();
+        shutdown_tracker.try_spawn_named(
            async move {
                persistent_storage
-                    .flush_on_shutdown(store_clone, shutdown)
+                    .flush_on_shutdown(store_clone, shutdown_token)
                    .await
            },
-            "PersistentReplyStorage::flush_on_shutdown"
+            "PersistentReplyStorage::flush_on_shutdown",
        );

        Ok(mem_store)
@@ -735,7 +840,7 @@ where
    {
        // if client keys do not exist already, create and persist them
        if key_store.load_keys().await.is_err() {
-            info!("could not find valid client keys - a new set will be generated");
+            tracing::info!("could not find valid client keys - a new set will be generated");
            let mut rng = OsRng;
            let keys = if let Some(derivation_material) = derivation_material {
                ClientKeys::from_master_key(&mut rng, &derivation_material)
@@ -756,15 +861,8 @@ where
        let mut nym_api_urls = config.get_nym_api_endpoints();
        nym_api_urls.shuffle(&mut thread_rng());

-        let mut builder = nym_http_api_client::Client::builder::<
-            _,
-            nym_validator_client::models::RequestError,
-        >(nym_api_urls[0].clone())
-        .map_err(|e| ClientCoreError::NymApiQueryFailure {
-            source: nym_validator_client::nym_api::error::NymAPIError::GenericRequestFailure(
-                e.to_string(),
-            ),
-        })?;
+        let mut builder = nym_http_api_client::Client::builder(nym_api_urls[0].clone())
+            .map_err(ClientCoreError::from)?;

        if let Some(user_agent) = user_agent {
            builder = builder.with_user_agent(user_agent);
@@ -772,13 +870,7 @@ where

        builder = builder.with_bincode();

-        builder
-            .build::<nym_validator_client::models::RequestError>()
-            .map_err(|e| ClientCoreError::NymApiQueryFailure {
-                source: nym_validator_client::nym_api::error::NymAPIError::GenericRequestFailure(
-                    e.to_string(),
-                ),
-            })
+        builder.build().map_err(ClientCoreError::from)
    }

    async fn determine_key_rotation_state(
@@ -795,7 +887,7 @@ where
        <S::CredentialStore as CredentialStorage>::StorageError: Send + Sync + 'static,
        <S::GatewaysDetailsStore as GatewaysDetailsStore>::StorageError: Sync + Send,
    {
-        info!("Starting nym client");
+        tracing::info!("Starting nym client");

        // derive (or load) client keys and gateway configuration
        let init_res = Self::initialise_keys_and_gateway(
@@ -824,17 +916,22 @@ where
        // channels responsible for controlling real messages
        let (input_sender, input_receiver) = tokio::sync::mpsc::channel::<InputMessage>(1);

+        // channels responsible for event management
+        let (event_sender, event_receiver) = mpsc::unbounded();
+
        // channels responsible for controlling ack messages
        let (ack_sender, ack_receiver) = mpsc::unbounded();
        let shared_topology_accessor =
            TopologyAccessor::new(self.config.debug.topology.ignore_egress_epoch_role);

-        // Shutdown notifier for signalling tasks to stop
-        let shutdown = self
-            .shutdown
-            .map(Into::<TaskHandle>::into)
-            .unwrap_or_default()
-            .name_if_unnamed("BaseNymClient");
+        // Create a shutdown tracker for this client - either as a child of provided tracker
+        // or get one from the registry
+        let shutdown_tracker = match self.shutdown {
+            Some(parent_tracker) => parent_tracker.child_tracker(),
+            None => nym_task::get_sdk_shutdown_tracker()?,
+        };
+
+        Self::start_event_control(self.event_tx, event_receiver, &shutdown_tracker);

        // channels responsible for dealing with reply-related fun
        let (reply_controller_sender, reply_controller_receiver) =
@@ -866,7 +963,7 @@ where
            self.user_agent.clone(),
            generate_client_stats_id(*self_address.identity()),
            input_sender.clone(),
-            shutdown.fork("statistics_control"),
+            &shutdown_tracker.child_tracker(),
        );

        // needs to be started as the first thing to block if required waiting for the gateway
@@ -876,14 +973,14 @@ where
            shared_topology_accessor.clone(),
            self_address.gateway(),
            self.wait_for_gateway,
-            shutdown.fork("topology_refresher"),
+            &shutdown_tracker.child_tracker(),
        )
        .await?;

        let gateway_packet_router = PacketRouter::new(
            ack_sender,
            mixnet_messages_sender,
-            shutdown.get_handle().named("gateway-packet-router"),
+            shutdown_tracker.clone_shutdown_token(),
        );

        let gateway_transceiver = Self::setup_gateway_transceiver(
@@ -896,7 +993,7 @@ where
            stats_reporter.clone(),
            #[cfg(unix)]
            self.connection_fd_callback,
-            shutdown.fork("gateway_transceiver"),
+            &shutdown_tracker.child_tracker(),
        )
        .await?;
        let gateway_ws_fd = gateway_transceiver.ws_fd();
@@ -904,7 +1001,7 @@ where
        let reply_storage = Self::setup_persistent_reply_storage(
            reply_storage_backend,
            key_rotation_config,
-            shutdown.fork("persistent_reply_storage"),
+            &shutdown_tracker.child_tracker(),
        )
        .await?;

@@ -914,8 +1011,8 @@ where
            mixnet_messages_receiver,
            reply_storage.key_storage(),
            reply_controller_sender.clone(),
-            shutdown.fork("received_messages_buffer"),
            stats_reporter.clone(),
+            &shutdown_tracker.child_tracker(),
        );

        // The message_sender is the transmitter for any component generating sphinx packets
@@ -925,7 +1022,8 @@ where

        let (message_sender, client_request_sender) = Self::start_mix_traffic_controller(
            gateway_transceiver,
-            shutdown.fork("mix_traffic_controller"),
+            &shutdown_tracker.child_tracker(),
+            EventSender(event_sender),
        );

        // Channels that the websocket listener can use to signal downstream to the real traffic
@@ -954,9 +1052,8 @@ where
            reply_controller_receiver,
            shared_lane_queue_lengths.clone(),
            client_connection_rx,
-            shutdown.fork("real_traffic_controller"),
-            self.config.debug.traffic.packet_type,
            stats_reporter.clone(),
+            &shutdown_tracker.child_tracker(),
        );

        if !self
@@ -972,12 +1069,12 @@ where
                shared_topology_accessor.clone(),
                message_sender,
                stats_reporter.clone(),
-                shutdown.fork("cover_traffic_stream"),
+                &shutdown_tracker.child_tracker(),
            );
        }

-        debug!("Core client startup finished!");
-        debug!("The address of this client is: {self_address}");
+        tracing::debug!("Core client startup finished!");
+        tracing::debug!("The address of this client is: {self_address}");

        Ok(BaseClient {
            address: self_address,
@@ -1000,7 +1097,7 @@ where
                gateway_connection: GatewayConnection { gateway_ws_fd },
            },
            stats_reporter,
-            task_handle: shutdown,
+            shutdown_handle: shutdown_tracker, // The primary tracker for this client
            client_request_sender,
            forget_me: self.config.debug.forget_me,
            remember_me: self.config.debug.remember_me,
@@ -1016,7 +1113,7 @@ pub struct BaseClient {
    pub client_state: ClientState,
    pub stats_reporter: ClientStatsSender,
    pub client_request_sender: ClientRequestSender,
-    pub task_handle: TaskHandle,
+    pub shutdown_handle: ShutdownTracker,
    pub forget_me: ForgetMe,
    pub remember_me: RememberMe,
 }
@@ -3,7 +3,7 @@

 use crate::client::mix_traffic::BatchMixMessageSender;
 use crate::client::topology_control::TopologyAccessor;
-use crate::{config, spawn_future};
+use crate::config;
 use futures::task::{Context, Poll};
 use futures::{Future, Stream, StreamExt};
 use nym_sphinx::acknowledgements::AckKey;
@@ -12,7 +12,6 @@ use nym_sphinx::cover::generate_loop_cover_packet;
 use nym_sphinx::params::{PacketSize, PacketType};
 use nym_sphinx::utils::sample_poisson_duration;
 use nym_statistics_common::clients::{packet_statistics::PacketStatisticsEvent, ClientStatsSender};
-use nym_task::TaskClient;
 use rand::{rngs::OsRng, CryptoRng, Rng};
 use std::pin::Pin;
 use std::sync::Arc;
@@ -69,8 +68,6 @@ where
    packet_type: PacketType,

    stats_tx: ClientStatsSender,
-
-    task_client: TaskClient,
 }

 impl<R> Stream for LoopCoverTrafficStream<R>
@@ -117,7 +114,6 @@ impl LoopCoverTrafficStream<OsRng> {
        traffic_config: config::Traffic,
        cover_config: config::CoverTraffic,
        stats_tx: ClientStatsSender,
-        task_client: TaskClient,
    ) -> Self {
        let rng = OsRng;

@@ -137,7 +133,6 @@ impl LoopCoverTrafficStream<OsRng> {
            use_legacy_sphinx_format: traffic_config.use_legacy_sphinx_format,
            packet_type: traffic_config.packet_type,
            stats_tx,
-            task_client,
        }
    }

@@ -235,12 +230,13 @@ impl LoopCoverTrafficStream<OsRng> {
        tokio::task::yield_now().await;
    }

+    // it's fine if cover traffic stream task gets killed whilst processing next message
    #[allow(clippy::panic)]
-    pub fn start(mut self) {
+    pub async fn run(&mut self) {
        if self.cover_traffic.disable_loop_cover_traffic_stream {
            // we should have never got here in the first place - the task should have never been created to begin with
            // so panic and review the code that lead to this branch
-            panic!("attempted to start LoopCoverTrafficStream while config explicitly disabled it.")
+            panic!("attempted to run LoopCoverTrafficStream while config explicitly disabled it.")
        }

        // we should set initial delay only when we actually start the stream
@@ -250,32 +246,11 @@ impl LoopCoverTrafficStream<OsRng> {
        );
        self.set_next_delay(sampled);

-        let mut shutdown = self.task_client.fork("select");
+        while self.next().await.is_some() {
+            self.on_new_message().await;
+        }

-        spawn_future!(
-            async move {
-                debug!("Started LoopCoverTrafficStream with graceful shutdown support");
-
-                while !shutdown.is_shutdown() {
-                    tokio::select! {
-                        biased;
-                        _ = shutdown.recv() => {
-                            tracing::trace!("LoopCoverTrafficStream: Received shutdown");
-                        }
-                        next = self.next() => {
-                            if next.is_some() {
-                                self.on_new_message().await;
-                            } else {
-                                tracing::trace!("LoopCoverTrafficStream: Stopping since channel closed");
-                                break;
-                            }
-                        }
-                    }
-                }
-                shutdown.recv_timeout().await;
-                tracing::debug!("LoopCoverTrafficStream: Exiting");
-            },
-            "LoopCoverTrafficStream"
-        )
+        // this should never get triggered
+        error!("cover traffic stream has been exhausted!")
    }
 }
@@ -0,0 +1,40 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use futures::StreamExt;
+
+use crate::client::base_client::{EventReceiver, EventSender, MixnetClientEvent};
+
+/// Launches and manages task events, propagating upwards what is not strictly internal.
+pub(crate) struct EventControl {
+    parent_event_tx: Option<EventSender>,
+    children_event_rx: EventReceiver,
+}
+
+impl EventControl {
+    pub(crate) fn new(
+        parent_event_tx: Option<EventSender>,
+        children_event_rx: EventReceiver,
+    ) -> Self {
+        EventControl {
+            parent_event_tx,
+            children_event_rx,
+        }
+    }
+
+    fn is_internal(event: MixnetClientEvent) -> bool {
+        match event {
+            MixnetClientEvent::Traffic(_) => false,
+        }
+    }
+
+    pub(crate) async fn run(mut self) {
+        while let Some(event) = self.children_event_rx.next().await {
+            if let Some(parent_event_tx) = &self.parent_event_tx {
+                if !Self::is_internal(event) {
+                    parent_event_tx.send(event);
+                }
+            }
+        }
+    }
+}
@@ -1,12 +1,13 @@
 // Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

-use crate::client::mix_traffic::transceiver::GatewayTransceiver;
-use crate::error::ClientCoreError;
-use crate::spawn_future;
+use crate::client::{
+    base_client::{EventSender, MixnetClientEvent},
+    mix_traffic::transceiver::GatewayTransceiver,
+};
 use nym_gateway_requests::ClientRequest;
 use nym_sphinx::forwarding::packet::MixPacket;
-use nym_task::TaskClient;
+use nym_task::ShutdownToken;
 use tracing::*;
 use transceiver::ErasedGatewayError;

@@ -24,6 +25,11 @@ const MAX_FAILURE_COUNT: usize = 100;
 // that's also disgusting.
 pub struct Empty;

+#[derive(Clone, Copy, Debug)]
+pub enum MixTrafficEvent {
+    FailedSendingSphinx,
+}
+
 pub struct MixTrafficController {
    gateway_transceiver: Box<dyn GatewayTransceiver + Send>,

@@ -34,13 +40,15 @@ pub struct MixTrafficController {
    // in long run `gateway_client` will be moved away from `MixTrafficController` anyway.
    consecutive_gateway_failure_count: usize,

-    task_client: TaskClient,
+    shutdown_token: ShutdownToken,
+    event_tx: EventSender,
 }

 impl MixTrafficController {
    pub fn new<T>(
        gateway_transceiver: T,
-        task_client: TaskClient,
+        shutdown_token: ShutdownToken,
+        event_tx: EventSender,
    ) -> (
        MixTrafficController,
        BatchMixMessageSender,
@@ -60,7 +68,8 @@ impl MixTrafficController {
                mix_rx: message_receiver,
                client_rx: client_receiver,
                consecutive_gateway_failure_count: 0,
-                task_client,
+                shutdown_token,
+                event_tx,
            },
            message_sender,
            client_sender,
@@ -69,7 +78,8 @@ impl MixTrafficController {

    pub fn new_dynamic(
        gateway_transceiver: Box<dyn GatewayTransceiver + Send>,
-        task_client: TaskClient,
+        shutdown_token: ShutdownToken,
+        event_tx: EventSender,
    ) -> (
        MixTrafficController,
        BatchMixMessageSender,
@@ -84,7 +94,8 @@ impl MixTrafficController {
                mix_rx: message_receiver,
                client_rx: client_receiver,
                consecutive_gateway_failure_count: 0,
-                task_client,
+                shutdown_token,
+                event_tx,
            },
            message_sender,
            client_sender,
@@ -107,7 +118,7 @@ impl MixTrafficController {

        tokio::select! {
            biased;
-            _ = self.task_client.recv() => {
+            _ = self.shutdown_token.cancelled() => {
                trace!("received shutdown while handling messages");
                Ok(())
            }
@@ -127,7 +138,7 @@ impl MixTrafficController {
    async fn on_client_request(&mut self, client_request: ClientRequest) {
        tokio::select! {
            biased;
-             _ = self.task_client.recv() => {
+             _ = self.shutdown_token.cancelled() => {
                trace!("received shutdown while handling client request");
            }
            result = self.gateway_transceiver.send_client_request(client_request) => {
@@ -138,51 +149,46 @@ impl MixTrafficController {
        }
    }

-    pub fn start(mut self) {
-        spawn_future!(
-            async move {
-                debug!("Started MixTrafficController with graceful shutdown support");
-                while !self.task_client.is_shutdown() {
-                    tokio::select! {
-                        biased;
-                        _ = self.task_client.recv() => {
-                            tracing::trace!("MixTrafficController: Received shutdown");
-                            break;
-                        }
-                        mix_packets = self.mix_rx.recv() => match mix_packets {
-                            Some(mix_packets) => {
-                                if let Err(err) = self.on_messages(mix_packets).await {
-                                    error!("Failed to send sphinx packet(s) to the gateway: {err}");
-                                    if self.consecutive_gateway_failure_count == MAX_FAILURE_COUNT {
-                                        // Disconnect from the gateway. If we should try to re-connect
-                                        // is handled at a higher layer.
-                                        error!("Failed to send sphinx packet to the gateway {MAX_FAILURE_COUNT} times in a row - assuming the gateway is dead");
-                                        // Do we need to handle the embedded mixnet client case
-                                        // separately?
-                                        self.task_client.send_we_stopped(Box::new(ClientCoreError::GatewayFailedToForwardMessages));
-                                        break;
-                                    }
-                                }
-                            },
-                            None => {
-                                tracing::trace!("MixTrafficController: Stopping since channel closed");
+    pub async fn run(&mut self) {
+        debug!("Started MixTrafficController with graceful shutdown support");
+        loop {
+            tokio::select! {
+                biased;
+                _ = self.shutdown_token.cancelled() => {
+                    trace!("MixTrafficController: Received shutdown");
+                    break;
+                }
+                mix_packets = self.mix_rx.recv() => match mix_packets {
+                    Some(mix_packets) => {
+                        if let Err(err) = self.on_messages(mix_packets).await {
+                            error!("Failed to send sphinx packet(s) to the gateway: {err}");
+                            if self.consecutive_gateway_failure_count == MAX_FAILURE_COUNT {
+                                // Disconnect from the gateway. If we should try to re-connect
+                                // is handled at a higher layer.
+                                error!("Failed to send sphinx packet to the gateway {MAX_FAILURE_COUNT} times in a row - assuming the gateway is dead");
+                                // Do we need to handle the embedded mixnet client case
+                                // separately?
+                                self.event_tx.send(MixnetClientEvent::Traffic(MixTrafficEvent::FailedSendingSphinx));
                                break;
                            }
-                        },
-                        client_request = self.client_rx.recv() => match client_request {
-                            Some(client_request) => {
-                                self.on_client_request(client_request).await;
-                            },
-                            None => {
-                                tracing::trace!("MixTrafficController, client request channel closed");
-                            }
-                        },
+                        }
+                    },
+                    None => {
+                        trace!("MixTrafficController: Stopping since channel closed");
+                        break;
                    }
-                }
-                self.task_client.recv_timeout().await;
-                tracing::debug!("MixTrafficController: Exiting");
-            },
-            "MixTrafficController"
-        );
+                },
+                client_request = self.client_rx.recv() => match client_request {
+                    Some(client_request) => {
+                        self.on_client_request(client_request).await;
+                    },
+                    None => {
+                        trace!("MixTrafficController, client request channel closed");
+                        break
+                    }
+                },
+            }
+        }
+        debug!("MixTrafficController: Exiting");
    }
 }
@@ -3,6 +3,7 @@

 pub mod base_client;
 pub mod cover_traffic_stream;
+pub(crate) mod event_control;
 pub(crate) mod helpers;
 pub mod inbound_messages;
 pub mod key_manager;
@@ -10,18 +10,17 @@ use nym_sphinx::{
    acknowledgements::{identifier::recover_identifier, AckKey},
    chunking::fragment::{FragmentIdentifier, COVER_FRAG_ID},
 };
-use nym_task::TaskClient;
+use nym_task::ShutdownToken;
 use std::sync::Arc;
 use tracing::*;

 /// Module responsible for listening for any data resembling acknowledgements from the network
 /// and firing actions to remove them from the 'Pending' state.
-pub(super) struct AcknowledgementListener {
+pub(crate) struct AcknowledgementListener {
    ack_key: Arc<AckKey>,
    ack_receiver: AcknowledgementReceiver,
    action_sender: AckActionSender,
    stats_tx: ClientStatsSender,
-    task_client: TaskClient,
 }

 impl AcknowledgementListener {
@@ -30,14 +29,12 @@ impl AcknowledgementListener {
        ack_receiver: AcknowledgementReceiver,
        action_sender: AckActionSender,
        stats_tx: ClientStatsSender,
-        task_client: TaskClient,
    ) -> Self {
        AcknowledgementListener {
            ack_key,
            ack_receiver,
            action_sender,
            stats_tx,
-            task_client,
        }
    }

@@ -68,14 +65,9 @@ impl AcknowledgementListener {
        trace!("Received {frag_id} from the mix network");
        self.stats_tx
            .report(PacketStatisticsEvent::RealAckReceived(ack_content.len()).into());
-        if let Err(err) = self
+        let _ = self
            .action_sender
-            .unbounded_send(Action::new_remove(frag_id))
-        {
-            if !self.task_client.is_shutdown_poll() {
-                error!("Failed to send remove action to action controller: {err}");
-            }
-        }
+            .unbounded_send(Action::new_remove(frag_id));
    }

    async fn handle_ack_receiver_item(&mut self, item: Vec<Vec<u8>>) {
@@ -85,11 +77,16 @@ impl AcknowledgementListener {
        }
    }

-    pub(super) async fn run(&mut self) {
+    pub(crate) async fn run(&mut self, shutdown_token: ShutdownToken) {
        debug!("Started AcknowledgementListener with graceful shutdown support");

-        while !self.task_client.is_shutdown() {
+        loop {
            tokio::select! {
+                biased;
+                _ = shutdown_token.cancelled() => {
+                    tracing::trace!("AcknowledgementListener: Received shutdown");
+                    break;
+                }
                acks = self.ack_receiver.next() => match acks {
                    Some(acks) => self.handle_ack_receiver_item(acks).await,
                    None => {
@@ -97,12 +94,9 @@ impl AcknowledgementListener {
                        break;
                    }
                },
-                _ = self.task_client.recv() => {
-                    tracing::trace!("AcknowledgementListener: Received shutdown");
-                }
+
            }
        }
-        self.task_client.recv_timeout().await;
        tracing::debug!("AcknowledgementListener: Exiting");
    }
 }
@@ -8,7 +8,7 @@ use futures::StreamExt;
 use nym_nonexhaustive_delayqueue::{Expired, NonExhaustiveDelayQueue, QueueKey};
 use nym_sphinx::chunking::fragment::FragmentIdentifier;
 use nym_sphinx::Delay as SphinxDelay;
-use nym_task::TaskClient;
+use nym_task::ShutdownToken;
 use std::collections::HashMap;
 use std::sync::Arc;
 use std::time::Duration;
@@ -82,7 +82,7 @@ impl Config {
    }
 }

-pub(super) struct ActionController {
+pub(crate) struct ActionController {
    /// Configurable parameters of the `ActionController`
    config: Config,

@@ -102,8 +102,6 @@ pub(super) struct ActionController {

    /// Channel for notifying `RetransmissionRequestListener` about expired acknowledgements.
    retransmission_sender: RetransmissionRequestSender,
-
-    task_client: TaskClient,
 }

 impl ActionController {
@@ -111,7 +109,6 @@ impl ActionController {
        config: Config,
        retransmission_sender: RetransmissionRequestSender,
        incoming_actions: AckActionReceiver,
-        task_client: TaskClient,
    ) -> Self {
        ActionController {
            config,
@@ -119,7 +116,6 @@ impl ActionController {
            pending_acks_timers: NonExhaustiveDelayQueue::new(),
            incoming_actions,
            retransmission_sender,
-            task_client,
        }
    }

@@ -226,14 +222,9 @@ impl ActionController {
            // downgrading an arc and then upgrading vs cloning is difference of 30ns vs 15ns
            // so it's literally a NO difference while it might prevent us from unnecessarily
            // resending data (in maybe 1 in 1 million cases, but it's something)
-            if let Err(err) = self
+            let _ = self
                .retransmission_sender
-                .unbounded_send(Arc::downgrade(pending_ack_data))
-            {
-                if !self.task_client.is_shutdown_poll() {
-                    tracing::error!("Failed to send pending ack for retransmission: {err}");
-                }
-            }
+                .unbounded_send(Arc::downgrade(pending_ack_data));
        } else {
            // this shouldn't cause any issues but shouldn't have happened to begin with!
            error!("An already removed pending ack has expired")
@@ -251,11 +242,16 @@ impl ActionController {
        }
    }

-    pub(super) async fn run(&mut self) {
+    pub(crate) async fn run(&mut self, shutdown_token: ShutdownToken) {
        debug!("Started ActionController with graceful shutdown support");

-        while !self.task_client.is_shutdown() {
+        loop {
            tokio::select! {
+                biased;
+                _ = shutdown_token.cancelled() => {
+                    tracing::trace!("ActionController: Received shutdown");
+                    break;
+                }
                action = self.incoming_actions.next() => match action {
                    Some(action) => self.process_action(action),
                    None => {
@@ -272,13 +268,8 @@ impl ActionController {
                        break;
                    }
                },
-                _ = self.task_client.recv() => {
-                    tracing::trace!("ActionController: Received shutdown");
-                    break;
-                }
            }
        }
-        self.task_client.recv_timeout().await;
        tracing::debug!("ActionController: Exiting");
    }
 }
@@ -10,21 +10,20 @@ use nym_sphinx::anonymous_replies::requests::AnonymousSenderTag;
 use nym_sphinx::forwarding::packet::MixPacket;
 use nym_sphinx::params::PacketType;
 use nym_task::connections::TransmissionLane;
-use nym_task::TaskClient;
+use nym_task::ShutdownToken;
 use rand::{CryptoRng, Rng};
 use tracing::*;

 /// Module responsible for dealing with the received messages: splitting them, creating acknowledgements,
 /// putting everything into sphinx packets, etc.
 /// It also makes an initial sending attempt for said messages.
-pub(super) struct InputMessageListener<R>
+pub(crate) struct InputMessageListener<R>
 where
    R: CryptoRng + Rng,
 {
    input_receiver: InputMessageReceiver,
    message_handler: MessageHandler<R>,
    reply_controller_sender: ReplyControllerSender,
-    task_client: TaskClient,
 }

 impl<R> InputMessageListener<R>
@@ -38,13 +37,11 @@ where
        input_receiver: InputMessageReceiver,
        message_handler: MessageHandler<R>,
        reply_controller_sender: ReplyControllerSender,
-        task_client: TaskClient,
    ) -> Self {
        InputMessageListener {
            input_receiver,
            message_handler,
            reply_controller_sender,
-            task_client,
        }
    }

@@ -68,14 +65,9 @@ where
        max_retransmissions: Option<u32>,
    ) {
        // offload reply handling to the dedicated task
-        if let Err(err) =
+        let _ =
            self.reply_controller_sender
-                .send_reply(recipient_tag, data, lane, max_retransmissions)
-        {
-            if !self.task_client.is_shutdown_poll() {
-                error!("failed to send a reply - {err}");
-            }
-        }
+                .send_reply(recipient_tag, data, lane, max_retransmissions);
    }

    async fn handle_plain_message(
@@ -221,13 +213,13 @@ where
        };
    }

-    pub(super) async fn run(&mut self) {
+    pub(crate) async fn run(&mut self, shutdown_token: ShutdownToken) {
        debug!("Started InputMessageListener with graceful shutdown support");

-        while !self.task_client.is_shutdown() {
+        loop {
            tokio::select! {
                biased;
-                _ = self.task_client.recv() => {
+                _ = shutdown_token.cancelled() => {
                    tracing::trace!("InputMessageListener: Received shutdown");
                    break;
                }
@@ -243,7 +235,6 @@ where

            }
        }
-        self.task_client.recv_timeout().await;
        tracing::debug!("InputMessageListener: Exiting");
    }
 }
@@ -10,7 +10,6 @@ use self::{
 use crate::client::inbound_messages::InputMessageReceiver;
 use crate::client::real_messages_control::message_handler::MessageHandler;
 use crate::client::replies::reply_controller::ReplyControllerSender;
-use crate::spawn_future;
 use action_controller::AckActionReceiver;
 use futures::channel::mpsc;
 use nym_gateway_client::AcknowledgementReceiver;
@@ -23,13 +22,11 @@ use nym_sphinx::{
    Delay as SphinxDelay,
 };
 use nym_statistics_common::clients::ClientStatsSender;
-use nym_task::TaskClient;
 use rand::{CryptoRng, Rng};
 use std::{
    sync::{Arc, Weak},
    time::Duration,
 };
-use tracing::*;

 pub(crate) use action_controller::{AckActionSender, Action};

@@ -190,6 +187,9 @@ pub(super) struct Config {

    /// Predefined packet size used for the encapsulated messages.
    packet_size: PacketSize,
+
+    /// Type of packets used for retransmissions
+    packet_type: PacketType,
 }

 impl Config {
@@ -197,12 +197,14 @@ impl Config {
        maximum_retransmissions: Option<u32>,
        ack_wait_addition: Duration,
        ack_wait_multiplier: f64,
+        packet_type: PacketType,
    ) -> Self {
        Config {
            maximum_retransmissions,
            ack_wait_addition,
            ack_wait_multiplier,
            packet_size: Default::default(),
+            packet_type,
        }
    }

@@ -212,7 +214,7 @@ impl Config {
    }
 }

-pub(super) struct AcknowledgementController<R>
+pub(crate) struct AcknowledgementController<R>
 where
    R: CryptoRng + Rng,
 {
@@ -234,7 +236,6 @@ where
        message_handler: MessageHandler<R>,
        reply_controller_sender: ReplyControllerSender,
        stats_tx: ClientStatsSender,
-        task_client: TaskClient,
    ) -> Self {
        let (retransmission_tx, retransmission_rx) = mpsc::unbounded();

@@ -244,7 +245,6 @@ where
            action_config,
            retransmission_tx,
            connectors.ack_action_receiver,
-            task_client.fork("action_controller"),
        );

        // will listen for any acks coming from the network
@@ -253,7 +253,6 @@ where
            connectors.ack_receiver,
            connectors.ack_action_sender.clone(),
            stats_tx,
-            task_client.fork("acknowledgement_listener"),
        );

        // will listen for any new messages from the client
@@ -261,7 +260,6 @@ where
            connectors.input_receiver,
            message_handler.clone(),
            reply_controller_sender.clone(),
-            task_client.fork("input_message_listener"),
        );

        // will listen for any ack timeouts and trigger retransmission
@@ -271,16 +269,13 @@ where
            message_handler,
            retransmission_rx,
            reply_controller_sender,
-            task_client.fork("retransmission_request_listener"),
+            config.packet_type,
        );

        // will listen for events indicating the packet was sent through the network so that
        // the retransmission timer should be started.
-        let sent_notification_listener = SentNotificationListener::new(
-            connectors.sent_notifier,
-            connectors.ack_action_sender,
-            task_client.with_suffix("sent_notification_listener"),
-        );
+        let sent_notification_listener =
+            SentNotificationListener::new(connectors.sent_notifier, connectors.ack_action_sender);

        AcknowledgementController {
            acknowledgement_listener,
@@ -291,51 +286,21 @@ where
        }
    }

-    pub(super) fn start(self, packet_type: PacketType) {
-        let mut acknowledgement_listener = self.acknowledgement_listener;
-        let mut input_message_listener = self.input_message_listener;
-        let mut retransmission_request_listener = self.retransmission_request_listener;
-        let mut sent_notification_listener = self.sent_notification_listener;
-        let mut action_controller = self.action_controller;
-
-        spawn_future!(
-            async move {
-                acknowledgement_listener.run().await;
-                debug!("The acknowledgement listener has finished execution!");
-            },
-            "AcknowledgementController::AcknowledgementListener"
-        );
-
-        spawn_future!(
-            async move {
-                input_message_listener.run().await;
-                debug!("The input listener has finished execution!");
-            },
-            "AcknowledgementController::InputMessageListener"
-        );
-
-        spawn_future!(
-            async move {
-                retransmission_request_listener.run(packet_type).await;
-                debug!("The retransmission request listener has finished execution!");
-            },
-            "AcknowledgementController::RetransmissionRequestListener"
-        );
-
-        spawn_future!(
-            async move {
-                sent_notification_listener.run().await;
-                debug!("The sent notification listener has finished execution!");
-            },
-            "AcknowledgementController::SentNotificationListener"
-        );
-
-        spawn_future!(
-            async move {
-                action_controller.run().await;
-                debug!("The controller has finished execution!");
-            },
-            "AcknowledgementController::ActionController"
-        );
+    pub(crate) fn into_tasks(
+        self,
+    ) -> (
+        AcknowledgementListener,
+        InputMessageListener<R>,
+        RetransmissionRequestListener<R>,
+        SentNotificationListener,
+        ActionController,
+    ) {
+        (
+            self.acknowledgement_listener,
+            self.input_message_listener,
+            self.retransmission_request_listener,
+            self.sent_notification_listener,
+            self.action_controller,
+        )
    }
 }
@@ -13,19 +13,19 @@ use futures::StreamExt;
 use nym_sphinx::chunking::fragment::Fragment;
 use nym_sphinx::preparer::PreparedFragment;
 use nym_sphinx::{addressing::clients::Recipient, params::PacketType};
-use nym_task::{connections::TransmissionLane, TaskClient};
+use nym_task::{connections::TransmissionLane, ShutdownToken};
 use rand::{CryptoRng, Rng};
 use std::sync::{Arc, Weak};
 use tracing::*;

 // responsible for packet retransmission upon fired timer
-pub(super) struct RetransmissionRequestListener<R> {
+pub(crate) struct RetransmissionRequestListener<R> {
    maximum_retransmissions: Option<u32>,
    action_sender: AckActionSender,
    message_handler: MessageHandler<R>,
    request_receiver: RetransmissionRequestReceiver,
    reply_controller_sender: ReplyControllerSender,
-    task_client: TaskClient,
+    packet_type: PacketType,
 }

 impl<R> RetransmissionRequestListener<R>
@@ -38,7 +38,7 @@ where
        message_handler: MessageHandler<R>,
        request_receiver: RetransmissionRequestReceiver,
        reply_controller_sender: ReplyControllerSender,
-        task_client: TaskClient,
+        packet_type: PacketType,
    ) -> Self {
        RetransmissionRequestListener {
            maximum_retransmissions,
@@ -46,7 +46,7 @@ where
            message_handler,
            request_receiver,
            reply_controller_sender,
-            task_client,
+            packet_type,
        }
    }

@@ -67,7 +67,6 @@ where
    async fn on_retransmission_request(
        &mut self,
        weak_timed_out_ack: Weak<PendingAcknowledgement>,
-        packet_type: PacketType,
    ) {
        let timed_out_ack = match weak_timed_out_ack.upgrade() {
            Some(timed_out_ack) => timed_out_ack,
@@ -97,22 +96,18 @@ where
            } => {
                // if this is retransmission for reply, offload it to the dedicated task
                // that deals with all the surbs
-                if let Err(err) = self.reply_controller_sender.send_retransmission_data(
+                let _ = self.reply_controller_sender.send_retransmission_data(
                    *recipient_tag,
                    weak_timed_out_ack,
                    *extra_surb_request,
-                ) {
-                    if !self.task_client.is_shutdown_poll() {
-                        error!("Failed to send retransmission data to the reply controller: {err}");
-                    }
-                }
+                );
                return;
            }
            PacketDestination::KnownRecipient(recipient) => {
                self.prepare_normal_retransmission_chunk(
                    **recipient,
                    timed_out_ack.message_chunk.clone(),
-                    packet_type,
+                    self.packet_type,
                )
                .await
            }
@@ -153,14 +148,9 @@ where
        // is sent to the `OutQueueControl` and has gone through its internal queue
        // with the additional poisson delay.
        // And since Actions are executed in order `UpdateTimer` will HAVE TO be executed before `StartTimer`
-        if let Err(err) = self
+        let _ = self
            .action_sender
-            .unbounded_send(Action::new_update_pending_ack(frag_id, new_delay))
-        {
-            if !self.task_client.is_shutdown_poll() {
-                error!("Failed to send update pending ack action to the controller: {err}");
-            }
-        }
+            .unbounded_send(Action::new_update_pending_ack(frag_id, new_delay));

        // send to `OutQueueControl` to eventually send to the mix network
        self.message_handler
@@ -174,18 +164,18 @@ where
            .await
    }

-    pub(super) async fn run(&mut self, packet_type: PacketType) {
+    pub(crate) async fn run(&mut self, shutdown_token: ShutdownToken) {
        debug!("Started RetransmissionRequestListener with graceful shutdown support");

-        while !self.task_client.is_shutdown() {
+        loop {
            tokio::select! {
                biased;
-                 _ = self.task_client.recv() => {
+                _ = shutdown_token.cancelled() => {
                    tracing::trace!("RetransmissionRequestListener: Received shutdown");
                    break;
                }
                timed_out_ack = self.request_receiver.next() => match timed_out_ack {
-                    Some(timed_out_ack) => self.on_retransmission_request(timed_out_ack, packet_type).await,
+                    Some(timed_out_ack) => self.on_retransmission_request(timed_out_ack).await,
                    None => {
                        tracing::trace!("RetransmissionRequestListener: Stopping since channel closed");
                        break;
@@ -194,7 +184,6 @@ where

            }
        }
-        self.task_client.recv_timeout().await;
        tracing::debug!("RetransmissionRequestListener: Exiting");
    }
 }
@@ -5,29 +5,25 @@ use super::action_controller::{AckActionSender, Action};
 use super::SentPacketNotificationReceiver;
 use futures::StreamExt;
 use nym_sphinx::chunking::fragment::{FragmentIdentifier, COVER_FRAG_ID};
-use nym_task::TaskClient;
 use tracing::*;

 /// Module responsible for starting up retransmission timers.
 /// It is required because when we send our packet to the `real traffic stream` controlled
 /// by a poisson timer, there's no guarantee the message will be sent immediately, so we might
 /// accidentally fire retransmission way quicker than we should have.
-pub(super) struct SentNotificationListener {
+pub(crate) struct SentNotificationListener {
    sent_notifier: SentPacketNotificationReceiver,
    action_sender: AckActionSender,
-    task_client: TaskClient,
 }

 impl SentNotificationListener {
    pub(super) fn new(
        sent_notifier: SentPacketNotificationReceiver,
        action_sender: AckActionSender,
-        task_client: TaskClient,
    ) -> Self {
        SentNotificationListener {
            sent_notifier,
            action_sender,
-            task_client,
        }
    }

@@ -36,37 +32,18 @@ impl SentNotificationListener {
            trace!("sent off a cover message - no need to start retransmission timer!");
            return;
        }
-        if let Err(err) = self
+        let _ = self
            .action_sender
-            .unbounded_send(Action::new_start_timer(frag_id))
-        {
-            if !self.task_client.is_shutdown_poll() {
-                error!("Failed to send start timer action to action controller: {err}");
-            }
-        }
+            .unbounded_send(Action::new_start_timer(frag_id));
    }

-    pub(super) async fn run(&mut self) {
+    pub(crate) async fn run(&mut self) {
        debug!("Started SentNotificationListener with graceful shutdown support");

-        while !self.task_client.is_shutdown() {
-            tokio::select! {
-                frag_id = self.sent_notifier.next() => match frag_id {
-                    Some(frag_id) => {
-                        self.on_sent_message(frag_id).await;
-                    }
-                    None => {
-                        tracing::trace!("SentNotificationListener: Stopping since channel closed");
-                        break;
-                    }
-                },
-                _ = self.task_client.recv() => {
-                    tracing::trace!("SentNotificationListener: Received shutdown");
-                    break;
-                }
-            }
+        while let Some(frag_id) = self.sent_notifier.next().await {
+            self.on_sent_message(frag_id).await;
        }
-        assert!(self.task_client.is_shutdown_poll());
+
        tracing::debug!("SentNotificationListener: Exiting");
    }
 }
@@ -20,7 +20,7 @@ use nym_sphinx::params::{PacketSize, PacketType};
 use nym_sphinx::preparer::{MessagePreparer, PreparedFragment};
 use nym_sphinx::Delay;
 use nym_task::connections::TransmissionLane;
-use nym_task::TaskClient;
+use nym_task::ShutdownToken;
 use nym_topology::{NymRouteProvider, NymTopologyError};
 use rand::{CryptoRng, Rng};
 use std::collections::HashMap;
@@ -189,7 +189,7 @@ pub(crate) struct MessageHandler<R> {
    topology_access: TopologyAccessor,
    reply_key_storage: SentReplyKeys,
    tag_storage: UsedSenderTags,
-    task_client: TaskClient,
+    shutdown_token: ShutdownToken,
 }

 impl<R> MessageHandler<R>
@@ -205,7 +205,7 @@ where
        topology_access: TopologyAccessor,
        reply_key_storage: SentReplyKeys,
        tag_storage: UsedSenderTags,
-        task_client: TaskClient,
+        shutdown_token: ShutdownToken,
    ) -> Self
    where
        R: Copy,
@@ -228,7 +228,7 @@ where
            topology_access,
            reply_key_storage,
            tag_storage,
-            task_client,
+            shutdown_token,
        }
    }

@@ -712,7 +712,7 @@ where
            .action_sender
            .unbounded_send(Action::UpdatePendingAck(id, new_delay))
        {
-            if !self.task_client.is_shutdown_poll() {
+            if !self.shutdown_token.is_cancelled() {
                error!("Failed to send update action to the controller: {err}");
            }
        }
@@ -723,7 +723,7 @@ where
            .action_sender
            .unbounded_send(Action::new_insert(pending_acks))
        {
-            if !self.task_client.is_shutdown_poll() {
+            if !self.shutdown_token.is_cancelled() {
                error!("Failed to send insert action to the controller: {err}");
            }
        }
@@ -737,7 +737,7 @@ where
    ) {
        tokio::select! {
            biased;
-            _ = self.task_client.recv() => {
+            _ = self.shutdown_token.cancelled() => {
                trace!("received shutdown while attempting to forward mixnet messages");
            }
            sending_res = self.real_message_sender.send((messages, transmission_lane)) => {
@@ -14,26 +14,21 @@ use crate::client::replies::reply_controller::{
    ReplyController, ReplyControllerReceiver, ReplyControllerSender,
 };
 use crate::client::replies::reply_storage::CombinedReplyStorage;
-use crate::config;
-use crate::{
-    client::{
-        inbound_messages::InputMessageReceiver, mix_traffic::BatchMixMessageSender,
-        real_messages_control::acknowledgement_control::AcknowledgementControllerConnectors,
-        topology_control::TopologyAccessor,
-    },
-    spawn_future,
+use crate::client::{
+    inbound_messages::InputMessageReceiver, mix_traffic::BatchMixMessageSender,
+    real_messages_control::acknowledgement_control::AcknowledgementControllerConnectors,
+    topology_control::TopologyAccessor,
 };
+use crate::config;
 use futures::channel::mpsc;
 use nym_gateway_client::AcknowledgementReceiver;
 use nym_sphinx::acknowledgements::AckKey;
 use nym_sphinx::addressing::clients::Recipient;
-use nym_sphinx::params::PacketType;
 use nym_statistics_common::clients::ClientStatsSender;
 use nym_task::connections::{ConnectionCommandReceiver, LaneQueueLengths};
-use nym_task::TaskClient;
+use nym_task::ShutdownToken;
 use rand::{rngs::OsRng, CryptoRng, Rng};
 use std::sync::Arc;
-use tracing::*;

 use crate::client::replies::reply_controller::key_rotation_helpers::KeyRotationConfig;
 pub(crate) use acknowledgement_control::{AckActionSender, Action};
@@ -69,6 +64,7 @@ impl<'a> From<&'a Config> for acknowledgement_control::Config {
            cfg.traffic.maximum_number_of_retransmissions,
            cfg.acks.ack_wait_addition,
            cfg.acks.ack_wait_multiplier,
+            cfg.traffic.packet_type,
        )
        .with_custom_packet_size(cfg.traffic.primary_packet_size)
    }
@@ -146,7 +142,7 @@ impl RealMessagesController<OsRng> {
        lane_queue_lengths: LaneQueueLengths,
        client_connection_rx: ConnectionCommandReceiver,
        stats_tx: ClientStatsSender,
-        task_client: TaskClient,
+        shutdown_token: ShutdownToken,
    ) -> Self {
        let rng = OsRng;

@@ -178,7 +174,7 @@ impl RealMessagesController<OsRng> {
            topology_access.clone(),
            reply_storage.key_storage(),
            reply_storage.tags_storage(),
-            task_client.fork("message_handler"),
+            shutdown_token.clone(),
        );

        let ack_control = AcknowledgementController::new(
@@ -188,7 +184,6 @@ impl RealMessagesController<OsRng> {
            message_handler.clone(),
            reply_controller_sender,
            stats_tx.clone(),
-            task_client.fork("ack_control"),
        );

        let reply_control = ReplyController::new(
@@ -196,7 +191,6 @@ impl RealMessagesController<OsRng> {
            message_handler,
            reply_storage,
            reply_controller_receiver,
-            task_client.fork("reply_controller"),
        );

        let out_queue_control = OutQueueControl::new(
@@ -209,7 +203,7 @@ impl RealMessagesController<OsRng> {
            lane_queue_lengths,
            client_connection_rx,
            stats_tx,
-            task_client.with_suffix("out_queue_control"),
+            shutdown_token.clone(),
        );

        RealMessagesController {
@@ -219,26 +213,13 @@ impl RealMessagesController<OsRng> {
        }
    }

-    pub fn start(self, packet_type: PacketType) {
-        let mut out_queue_control = self.out_queue_control;
-        let ack_control = self.ack_control;
-        let mut reply_control = self.reply_control;
-
-        spawn_future!(
-            async move {
-                out_queue_control.run().await;
-                debug!("The out queue controller has finished execution!");
-            },
-            "RealMessagesController::OutQueueControl)"
-        );
-        spawn_future!(
-            async move {
-                reply_control.run().await;
-                debug!("The reply controller has finished execution!");
-            },
-            "RealMessagesController::ReplyController"
-        );
-
-        ack_control.start(packet_type);
+    pub fn into_tasks(
+        self,
+    ) -> (
+        OutQueueControl<OsRng>,
+        ReplyController<OsRng>,
+        AcknowledgementController<OsRng>,
+    ) {
+        (self.out_queue_control, self.reply_control, self.ack_control)
    }
 }
@@ -21,7 +21,7 @@ use nym_statistics_common::clients::{packet_statistics::PacketStatisticsEvent, C
 use nym_task::connections::{
    ConnectionCommand, ConnectionCommandReceiver, ConnectionId, LaneQueueLengths, TransmissionLane,
 };
-use nym_task::TaskClient;
+use nym_task::ShutdownToken;
 use rand::{CryptoRng, Rng};
 use std::pin::Pin;
 use std::sync::Arc;
@@ -119,7 +119,7 @@ where
    /// Channel used for sending metrics events (specifically `PacketStatistics` events) to the metrics tracker.
    stats_tx: ClientStatsSender,

-    task_client: TaskClient,
+    shutdown_token: ShutdownToken,
 }

 #[derive(Debug)]
@@ -179,7 +179,7 @@ where
        lane_queue_lengths: LaneQueueLengths,
        client_connection_rx: ConnectionCommandReceiver,
        stats_tx: ClientStatsSender,
-        task_client: TaskClient,
+        shutdown_token: ShutdownToken,
    ) -> Self {
        OutQueueControl {
            config,
@@ -194,7 +194,7 @@ where
            client_connection_rx,
            lane_queue_lengths,
            stats_tx,
-            task_client,
+            shutdown_token,
        }
    }

@@ -282,7 +282,7 @@ where

        let sending_res = tokio::select! {
            biased;
-            _ = self.task_client.recv() => {
+            _ = self.shutdown_token.cancelled() => {
                trace!("received shutdown signal while attempting to send mix message");
                return
            }
@@ -293,7 +293,7 @@ where

        match sending_res {
            Err(_) => {
-                if !self.task_client.is_shutdown_poll() {
+                if !self.shutdown_token.is_cancelled() {
                    tracing::error!(
                        "failed to send mixnet packet due to closed channel (outside of shutdown!)"
                    );
@@ -536,9 +536,7 @@ where
    }

    #[cfg(not(target_arch = "wasm32"))]
-    fn log_status(&self, shutdown: &mut TaskClient) {
-        use crate::error::ClientCoreStatusMessage;
-
+    fn log_status(&self) {
        let packets = self.transmission_buffer.total_size();
        let lanes = self.transmission_buffer.lanes();
        let mult = self.sending_delay_controller.current_multiplier();
@@ -567,32 +565,33 @@ where
            tracing::debug!("{status_str}");
        }

-        // Send status message to whoever is listening (possibly UI)
-        if mult == self.sending_delay_controller.max_multiplier() {
-            shutdown.send_status_msg(Box::new(ClientCoreStatusMessage::GatewayIsVerySlow));
-        } else if mult > self.sending_delay_controller.min_multiplier() {
-            shutdown.send_status_msg(Box::new(ClientCoreStatusMessage::GatewayIsSlow));
-        }
+        // leave the code commented in case somebody wanted to restore this logic with a different channel
+        // // Send status message to whoever is listening (possibly UI)
+        // if mult == self.sending_delay_controller.max_multiplier() {
+        //     shutdown.send_status_msg(Box::new(ClientCoreStatusMessage::GatewayIsVerySlow));
+        // } else if mult > self.sending_delay_controller.min_multiplier() {
+        //     shutdown.send_status_msg(Box::new(ClientCoreStatusMessage::GatewayIsSlow));
+        // }
    }

-    pub(super) async fn run(&mut self) {
+    pub(crate) async fn run(&mut self) {
        debug!("Started OutQueueControl with graceful shutdown support");

-        let mut shutdown = self.task_client.fork("select");
-
+        // avoid borrow on self
+        let shutdown_token = self.shutdown_token.clone();
        #[cfg(not(target_arch = "wasm32"))]
        {
            let mut status_timer = tokio::time::interval(Duration::from_secs(5));

-            while !shutdown.is_shutdown() {
+            loop {
                tokio::select! {
                    biased;
-                    _ = shutdown.recv() => {
+                    _ = shutdown_token.cancelled() => {
                        tracing::trace!("OutQueueControl: Received shutdown");
                        break;
                    }
                    _ = status_timer.tick() => {
-                        self.log_status(&mut shutdown);
+                        self.log_status();
                    }
                    next_message = self.next() => if let Some(next_message) = next_message {
                        self.on_message(next_message).await;
@@ -602,16 +601,16 @@ where
                    }
                }
            }
-            shutdown.recv_timeout().await;
        }

        #[cfg(target_arch = "wasm32")]
        {
-            while !shutdown.is_shutdown() {
+            loop {
                tokio::select! {
                    biased;
-                    _ = shutdown.recv() => {
+                    _ = shutdown_token.cancelled() => {
                        tracing::trace!("OutQueueControl: Received shutdown");
+                        break;
                    }
                    next_message = self.next() => if let Some(next_message) = next_message {
                        self.on_message(next_message).await;
@@ -83,11 +83,13 @@ impl SendingDelayController {
        self.current_multiplier
    }

+    #[allow(dead_code)]
    #[cfg(not(target_arch = "wasm32"))]
    pub(crate) fn min_multiplier(&self) -> u32 {
        self.lower_bound
    }

+    #[allow(dead_code)]
    #[cfg(not(target_arch = "wasm32"))]
    pub(crate) fn max_multiplier(&self) -> u32 {
        self.upper_bound
@@ -1,10 +1,10 @@
 // Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

+use crate::client::helpers::get_time_now;
 use crate::client::replies::{
    reply_controller::ReplyControllerSender, reply_storage::SentReplyKeys,
 };
-use crate::spawn_future;
 use futures::channel::mpsc;
 use futures::lock::Mutex;
 use futures::StreamExt;
@@ -19,10 +19,10 @@ use nym_sphinx::message::{NymMessage, PlainMessage};
 use nym_sphinx::params::ReplySurbKeyDigestAlgorithm;
 use nym_sphinx::receiver::{MessageReceiver, MessageRecoveryError, ReconstructedMessage};
 use nym_statistics_common::clients::{packet_statistics::PacketStatisticsEvent, ClientStatsSender};
-use nym_task::TaskClient;
+use nym_task::ShutdownToken;
 use std::collections::HashSet;
 use std::sync::Arc;
-use std::time::{Duration, Instant};
+use std::time::Duration;
 use tracing::*;

 // The interval at which we check for stale buffers
@@ -54,7 +54,7 @@ struct ReceivedMessagesBufferInner<R: MessageReceiver> {
    stats_tx: ClientStatsSender,

    // Periodically check for stale buffers to clean up
-    last_stale_check: Instant,
+    last_stale_check: crate::client::helpers::Instant,
 }

 impl<R: MessageReceiver> ReceivedMessagesBufferInner<R> {
@@ -154,7 +154,7 @@ impl<R: MessageReceiver> ReceivedMessagesBufferInner<R> {
    }

    fn cleanup_stale_buffers(&mut self) {
-        let now = Instant::now();
+        let now = get_time_now();
        if now - self.last_stale_check > STALE_BUFFER_CHECK_INTERVAL {
            self.last_stale_check = now;
            self.message_receiver
@@ -171,7 +171,7 @@ struct ReceivedMessagesBuffer<R: MessageReceiver> {
    inner: Arc<Mutex<ReceivedMessagesBufferInner<R>>>,
    reply_key_storage: SentReplyKeys,
    reply_controller_sender: ReplyControllerSender,
-    task_client: TaskClient,
+    shutdown_token: ShutdownToken,
 }

 impl<R: MessageReceiver> ReceivedMessagesBuffer<R> {
@@ -180,7 +180,7 @@ impl<R: MessageReceiver> ReceivedMessagesBuffer<R> {
        reply_key_storage: SentReplyKeys,
        reply_controller_sender: ReplyControllerSender,
        stats_tx: ClientStatsSender,
-        task_client: TaskClient,
+        shutdown_token: ShutdownToken,
    ) -> Self {
        ReceivedMessagesBuffer {
            inner: Arc::new(Mutex::new(ReceivedMessagesBufferInner {
@@ -190,11 +190,11 @@ impl<R: MessageReceiver> ReceivedMessagesBuffer<R> {
                message_sender: None,
                recently_reconstructed: HashSet::new(),
                stats_tx,
-                last_stale_check: Instant::now(),
+                last_stale_check: get_time_now(),
            })),
            reply_key_storage,
            reply_controller_sender,
-            task_client,
+            shutdown_token,
        }
    }

@@ -315,7 +315,7 @@ impl<R: MessageReceiver> ReceivedMessagesBuffer<R> {
                    reply_surbs,
                    from_surb_request,
                ) {
-                    if !self.task_client.is_shutdown_poll() {
+                    if !self.shutdown_token.is_cancelled() {
                        error!("{err}");
                    }
                }
@@ -338,7 +338,7 @@ impl<R: MessageReceiver> ReceivedMessagesBuffer<R> {
                        .reply_controller_sender
                        .send_additional_surbs_request(*recipient, amount)
                    {
-                        if !self.task_client.is_shutdown_poll() {
+                        if !self.shutdown_token.is_cancelled() {
                            error!("{err}");
                        }
                    }
@@ -465,22 +465,22 @@ pub enum ReceivedBufferMessage {
    ReceiverDisconnect,
 }

-struct RequestReceiver<R: MessageReceiver> {
+pub(crate) struct RequestReceiver<R: MessageReceiver> {
    received_buffer: ReceivedMessagesBuffer<R>,
    query_receiver: ReceivedBufferRequestReceiver,
-    task_client: TaskClient,
+    shutdown_token: ShutdownToken,
 }

 impl<R: MessageReceiver> RequestReceiver<R> {
    fn new(
        received_buffer: ReceivedMessagesBuffer<R>,
        query_receiver: ReceivedBufferRequestReceiver,
-        task_client: TaskClient,
+        shutdown_token: ShutdownToken,
    ) -> Self {
        RequestReceiver {
            received_buffer,
            query_receiver,
-            task_client,
+            shutdown_token,
        }
    }

@@ -495,66 +495,70 @@ impl<R: MessageReceiver> RequestReceiver<R> {
        }
    }

-    async fn run(&mut self) {
+    pub(crate) async fn run(&mut self) {
        debug!("Started RequestReceiver with graceful shutdown support");
-        while !self.task_client.is_shutdown() {
+        loop {
            tokio::select! {
                biased;
-                _ = self.task_client.recv() => {
+                _ = self.shutdown_token.cancelled() => {
                    tracing::trace!("RequestReceiver: Received shutdown");
+                    break;
                }
                request = self.query_receiver.next() => {
                    if let Some(message) = request {
                        self.handle_message(message).await
                    } else {
                        tracing::trace!("RequestReceiver: Stopping since channel closed");
+                        self.shutdown_token.cancelled().await;
                        break;
                    }
                },
            }
        }
-        self.task_client.recv().await;
        tracing::debug!("RequestReceiver: Exiting");
    }
 }

-struct FragmentedMessageReceiver<R: MessageReceiver> {
+pub(crate) struct FragmentedMessageReceiver<R: MessageReceiver> {
    received_buffer: ReceivedMessagesBuffer<R>,
    mixnet_packet_receiver: MixnetMessageReceiver,
-    task_client: TaskClient,
+    shutdown_token: ShutdownToken,
 }

 impl<R: MessageReceiver> FragmentedMessageReceiver<R> {
    fn new(
        received_buffer: ReceivedMessagesBuffer<R>,
        mixnet_packet_receiver: MixnetMessageReceiver,
-        task_client: TaskClient,
+        shutdown_token: ShutdownToken,
    ) -> Self {
        FragmentedMessageReceiver {
            received_buffer,
            mixnet_packet_receiver,
-            task_client,
+            shutdown_token,
        }
    }

-    async fn run(&mut self) -> Result<(), MessageRecoveryError> {
+    pub(crate) async fn run(&mut self) -> Result<(), MessageRecoveryError> {
        debug!("Started FragmentedMessageReceiver with graceful shutdown support");
-        while !self.task_client.is_shutdown() {
+        loop {
            tokio::select! {
+                biased;
+                _ = self.shutdown_token.cancelled() => {
+                    tracing::trace!("FragmentedMessageReceiver: Received shutdown");
+                    break;
+                }
                new_messages = self.mixnet_packet_receiver.next() => {
                    if let Some(new_messages) = new_messages {
                        self.received_buffer.handle_new_received(new_messages).await?;
                    } else {
                        tracing::trace!("FragmentedMessageReceiver: Stopping since channel closed");
+                        self.shutdown_token.cancelled().await;
                        break;
                    }
                },
-                _ = self.task_client.recv_with_delay() => {
-                    tracing::trace!("FragmentedMessageReceiver: Received shutdown");
-                }
+
            }
        }
-        self.task_client.recv_timeout().await;
        tracing::debug!("FragmentedMessageReceiver: Exiting");
        Ok(())
    }
@@ -573,48 +577,31 @@ impl<R: MessageReceiver + Clone + Send + 'static> ReceivedMessagesBufferControll
        reply_key_storage: SentReplyKeys,
        reply_controller_sender: ReplyControllerSender,
        metrics_reporter: ClientStatsSender,
-        task_client: TaskClient,
+        shutdown_token: ShutdownToken,
    ) -> Self {
        let received_buffer = ReceivedMessagesBuffer::new(
            local_encryption_keypair,
            reply_key_storage,
            reply_controller_sender,
            metrics_reporter,
-            task_client.fork("received_messages_buffer"),
+            shutdown_token.clone(),
        );

        ReceivedMessagesBufferController {
            fragmented_message_receiver: FragmentedMessageReceiver::new(
                received_buffer.clone(),
                mixnet_packet_receiver,
-                task_client.fork("fragmented_message_receiver"),
+                shutdown_token.clone(),
            ),
            request_receiver: RequestReceiver::new(
                received_buffer,
                query_receiver,
-                task_client.with_suffix("request_receiver"),
+                shutdown_token.clone(),
            ),
        }
    }

-    pub fn start(self) {
-        let mut fragmented_message_receiver = self.fragmented_message_receiver;
-        let mut request_receiver = self.request_receiver;
-
-        spawn_future!(
-            async move {
-                match fragmented_message_receiver.run().await {
-                    Ok(_) => {}
-                    Err(e) => error!("{e}"),
-                }
-            },
-            "ReceivedMessagesBufferController::FragmentedMessageReceiver"
-        );
-        spawn_future!(
-            async move {
-                request_receiver.run().await;
-            },
-            "ReceivedMessagesBufferController::RequestReceiver"
-        );
+    pub(crate) fn into_tasks(self) -> (FragmentedMessageReceiver<R>, RequestReceiver<R>) {
+        (self.fragmented_message_receiver, self.request_receiver)
    }
 }
@@ -7,7 +7,7 @@ use crate::client::replies::reply_controller::key_rotation_helpers::KeyRotationC
 use crate::client::replies::reply_storage::CombinedReplyStorage;
 use crate::config;
 use futures::StreamExt;
-use nym_task::TaskClient;
+use nym_task::ShutdownToken;
 use rand::rngs::OsRng;
 use rand::{CryptoRng, Rng};
 use std::time::Duration;
@@ -60,9 +60,6 @@ pub struct ReplyController<R> {
    receiver_controller: ReceiverReplyController<R>,

    request_receiver: ReplyControllerReceiver,
-
-    // Listen for shutdown signals
-    task_client: TaskClient,
 }

 impl ReplyController<OsRng> {
@@ -71,7 +68,6 @@ impl ReplyController<OsRng> {
        message_handler: MessageHandler<OsRng>,
        full_reply_storage: CombinedReplyStorage,
        request_receiver: ReplyControllerReceiver,
-        task_client: TaskClient,
    ) -> Self {
        ReplyController {
            config,
@@ -86,7 +82,6 @@ impl ReplyController<OsRng> {
                message_handler,
            ),
            request_receiver,
-            task_client,
        }
    }
 }
@@ -148,22 +143,21 @@ where
        self.sender_controller.inspect_and_clear_stale_data(now)
    }

-    pub(crate) async fn run(&mut self) {
+    pub(crate) async fn run(&mut self, shutdown_token: ShutdownToken) {
        debug!("Started ReplyController with graceful shutdown support");

-        let mut shutdown = self.task_client.fork("reply-controller");
-
        let polling_rate = Duration::from_secs(5);
        let mut stale_inspection = new_interval_stream(polling_rate);

        let polling_rate = self.config.key_rotation.epoch_duration / 8;
        let mut invalidation_inspection = new_interval_stream(polling_rate);

-        while !shutdown.is_shutdown() {
+        loop {
            tokio::select! {
                biased;
-                _ = shutdown.recv() => {
+                _ = shutdown_token.cancelled() => {
                    tracing::trace!("ReplyController: Received shutdown");
+                    break;
                },
                req = self.request_receiver.next() => match req {
                    Some(req) => self.handle_request(req).await,
@@ -181,7 +175,6 @@ where
                }
            }
        }
-        assert!(shutdown.is_shutdown_poll());
        tracing::debug!("ReplyController: Exiting");
    }
 }
@@ -16,21 +16,17 @@
 #![warn(clippy::todo)]
 #![warn(clippy::dbg_macro)]

+use crate::client::inbound_messages::{InputMessage, InputMessageSender};
 use futures::StreamExt;
 use nym_client_core_config_types::StatsReporting;
 use nym_sphinx::addressing::Recipient;
 use nym_statistics_common::clients::{
    ClientStatsController, ClientStatsReceiver, ClientStatsSender,
 };
-use nym_task::{connections::TransmissionLane, TaskClient};
+use nym_task::{connections::TransmissionLane, ShutdownToken, ShutdownTracker};
 use std::time::Duration;

-use crate::{
-    client::inbound_messages::{InputMessage, InputMessageSender},
-    spawn_future,
-};
-
-/// Time interval between reporting statistics locally (logging/task_client)
+/// Time interval between reporting statistics locally (logging/shutdown_token)
 const LOCAL_REPORT_INTERVAL: Duration = Duration::from_secs(2);
 /// Interval for taking snapshots of the statistics
 const SNAPSHOT_INTERVAL: Duration = Duration::from_millis(500);
@@ -51,9 +47,6 @@ pub(crate) struct StatisticsControl {

    /// Config for stats reporting (enabled, address, interval)
    reporting_config: StatsReporting,
-
-    /// Task client for listening for shutdown
-    task_client: TaskClient,
 }

 impl StatisticsControl {
@@ -62,24 +55,20 @@ impl StatisticsControl {
        client_type: String,
        client_stats_id: String,
        report_tx: InputMessageSender,
-        task_client: TaskClient,
+        shutdown_token: ShutdownToken,
    ) -> (Self, ClientStatsSender) {
        let (stats_tx, stats_rx) = tokio::sync::mpsc::unbounded_channel();

        let stats = ClientStatsController::new(client_stats_id, client_type);

-        let mut task_client_stats_sender = task_client.fork("stats_sender");
-        task_client_stats_sender.disarm();
-
        (
            StatisticsControl {
                stats,
                stats_rx,
                report_tx,
                reporting_config,
-                task_client,
            },
-            ClientStatsSender::new(Some(stats_tx), task_client_stats_sender),
+            ClientStatsSender::new(Some(stats_tx), shutdown_token),
        )
    }

@@ -99,7 +88,8 @@ impl StatisticsControl {
        }
    }

-    async fn run(&mut self) {
+    // manually control the shutdown mechanism as we don't want to get interrupted mid-snapshot
+    pub async fn run(&mut self, shutdown_token: ShutdownToken) {
        tracing::debug!("Started StatisticsControl with graceful shutdown support");

        #[cfg(not(target_arch = "wasm32"))]
@@ -129,10 +119,10 @@ impl StatisticsControl {
        let mut snapshot_interval =
            gloo_timers::future::IntervalStream::new(SNAPSHOT_INTERVAL.as_millis() as u32);

-        while !self.task_client.is_shutdown() {
+        loop {
            tokio::select! {
                biased;
-                _ = self.task_client.recv() => {
+                _ = shutdown_token.cancelled() => {
                    tracing::trace!("StatisticsControl: Received shutdown");
                    break;
                },
@@ -157,37 +147,34 @@ impl StatisticsControl {
                }

                _ = local_report_interval.next() => {
-                    self.stats.local_report(&mut self.task_client);
+                    self.stats.local_report();
                }
            }
        }
        tracing::debug!("StatisticsControl: Exiting");
    }

-    pub(crate) fn start(mut self) {
-        spawn_future!(
-            async move {
-                self.run().await;
-            },
-            "StatisticsControl"
-        )
-    }
-
    pub(crate) fn create_and_start(
        reporting_config: StatsReporting,
        client_type: String,
        client_stats_id: String,
        report_tx: InputMessageSender,
-        task_client: TaskClient,
+        shutdown_tracker: &ShutdownTracker,
    ) -> ClientStatsSender {
-        let (controller, sender) = Self::create(
+        let (mut controller, sender) = Self::create(
            reporting_config,
            client_type,
            client_stats_id,
            report_tx,
-            task_client,
+            shutdown_tracker.child_shutdown_token(),
+        );
+        let shutdown_token = shutdown_tracker.clone_shutdown_token();
+        shutdown_tracker.try_spawn_named(
+            async move {
+                controller.run(shutdown_token).await;
+            },
+            "StatisticsControl",
        );
-        controller.start();
        sender
    }
 }
@@ -1,11 +1,9 @@
 // Copyright 2021-2023 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

-use crate::spawn_future;
 pub(crate) use accessor::{TopologyAccessor, TopologyReadPermit};
 use futures::StreamExt;
 use nym_sphinx::addressing::nodes::NodeIdentity;
-use nym_task::TaskClient;
 use nym_topology::NymTopologyError;
 use std::time::Duration;
 use tracing::*;
@@ -41,8 +39,6 @@ pub struct TopologyRefresher {

    refresh_rate: Duration,
    consecutive_failure_count: usize,
-
-    task_client: TaskClient,
 }

 impl TopologyRefresher {
@@ -50,14 +46,12 @@ impl TopologyRefresher {
        cfg: TopologyRefresherConfig,
        topology_accessor: TopologyAccessor,
        topology_provider: Box<dyn TopologyProvider + Send + Sync>,
-        task_client: TaskClient,
    ) -> Self {
        TopologyRefresher {
            topology_provider,
            topology_accessor,
            refresh_rate: cfg.refresh_rate,
            consecutive_failure_count: 0,
-            task_client,
        }
    }

@@ -144,40 +138,30 @@ impl TopologyRefresher {
        }
    }

-    pub fn start(mut self) {
-        spawn_future!(
-            async move {
-                debug!("Started TopologyRefresher with graceful shutdown support");
+    // it's perfectly fine if task is interrupted mid-refresh
+    // there's no data to persist or send over
+    pub async fn run(&mut self) {
+        debug!("Started TopologyRefresher with graceful shutdown support");

-                #[cfg(not(target_arch = "wasm32"))]
-                let mut interval = tokio_stream::wrappers::IntervalStream::new(
-                    tokio::time::interval(self.refresh_rate),
-                );
+        #[cfg(not(target_arch = "wasm32"))]
+        let mut interval =
+            tokio_stream::wrappers::IntervalStream::new(tokio::time::interval(self.refresh_rate));

-                #[cfg(target_arch = "wasm32")]
-                let mut interval =
-                    gloo_timers::future::IntervalStream::new(self.refresh_rate.as_millis() as u32);
+        #[cfg(target_arch = "wasm32")]
+        let mut interval =
+            gloo_timers::future::IntervalStream::new(self.refresh_rate.as_millis() as u32);

-                // We already have an initial topology, so no need to refresh it immediately.
-                // My understanding is that js setInterval does not fire immediately, so it's not
-                // needed there.
-                #[cfg(not(target_arch = "wasm32"))]
-                interval.next().await;
+        // We already have an initial topology, so no need to refresh it immediately.
+        // My understanding is that js setInterval does not fire immediately, so it's not
+        // needed there.
+        #[cfg(not(target_arch = "wasm32"))]
+        interval.next().await;

-                while !self.task_client.is_shutdown() {
-                    tokio::select! {
-                        _ = interval.next() => {
-                            self.try_refresh().await;
-                        },
-                        _ = self.task_client.recv() => {
-                            tracing::trace!("TopologyRefresher: Received shutdown");
-                        },
-                    }
-                }
-                self.task_client.recv_timeout().await;
-                tracing::debug!("TopologyRefresher: Exiting");
-            },
-            "TopologyRefresher"
-        )
+        while interval.next().await.is_some() {
+            self.try_refresh().await;
+        }
+
+        // this should never get triggered
+        error!("topology refresher interval has been exhausted!")
    }
 }
@@ -4,6 +4,7 @@
 use crate::client::mix_traffic::transceiver::ErasedGatewayError;
 use nym_crypto::asymmetric::ed25519::Ed25519RecoveryError;
 use nym_gateway_client::error::GatewayClientError;
+use nym_task::RegistryAccessError;
 use nym_topology::node::RoutingNodeError;
 use nym_topology::{NodeId, NymTopologyError};
 use nym_validator_client::nym_api::error::NymAPIError;
@@ -56,10 +57,7 @@ pub enum ClientCoreError {
    ListOfNymApisIsEmpty,

    #[error("failed to resolve a query to nym API: {source}")]
-    NymApiQueryFailure {
-        #[from]
-        source: NymAPIError,
-    },
+    NymApiQueryFailure { source: Box<NymAPIError> },

    #[error(
        "the current network topology seem to be insufficient to route any packets through:\n\t{0}"
@@ -245,6 +243,9 @@ pub enum ClientCoreError {

    #[error("failed to select valid gateway due to incomputable latency")]
    GatewaySelectionFailure { source: WeightedError },
+
+    #[error("Could not access task registry, {0}")]
+    RegistryAccess(#[from] RegistryAccessError),
 }

 impl From<tungstenite::Error> for ClientCoreError {
@@ -255,6 +256,14 @@ impl From<tungstenite::Error> for ClientCoreError {
    }
 }

+impl From<NymAPIError> for ClientCoreError {
+    fn from(err: NymAPIError) -> ClientCoreError {
+        ClientCoreError::NymApiQueryFailure {
+            source: Box::new(err),
+        }
+    }
+}
+
 /// Set of messages that the client can send to listeners via the task manager
 #[derive(Debug)]
 pub enum ClientCoreStatusMessage {
@@ -146,9 +146,9 @@ pub async fn gateways_for_init<R: Rng>(
    // Use the unified HTTP client directly with optional user agent
    let mut builder = nym_http_api_client::Client::builder(nym_api.clone())
        .map_err(|e| {
-            ClientCoreError::ValidatorClientError(
-                nym_validator_client::ValidatorClientError::NymAPIError { source: e },
-            )
+            ClientCoreError::ValidatorClientError(nym_validator_client::ValidatorClientError::from(
+                e,
+            ))
        })?
        .with_bincode(); // Use bincode for better performance

@@ -156,13 +156,9 @@ pub async fn gateways_for_init<R: Rng>(
        builder = builder.with_user_agent(user_agent);
    }

-    let client = builder
-        .build::<nym_validator_client::models::RequestError>()
-        .map_err(|e| {
-            ClientCoreError::ValidatorClientError(
-                nym_validator_client::ValidatorClientError::NymAPIError { source: e },
-            )
-        })?;
+    let client = builder.build().map_err(|e| {
+        ClientCoreError::ValidatorClientError(nym_validator_client::ValidatorClientError::from(e))
+    })?;

    tracing::debug!("Fetching list of gateways from: {nym_api}");

@@ -17,7 +17,9 @@ pub use nym_topology::{
    HardcodedTopologyProvider, NymRouteProvider, NymTopology, NymTopologyError, TopologyProvider,
 };

+#[deprecated(note = "use spawn_future from nym_task crate instead")]
 #[cfg(target_arch = "wasm32")]
+#[track_caller]
 pub fn spawn_future<F>(future: F)
 where
    F: Future<Output = ()> + 'static,
@@ -25,9 +27,7 @@ where
    wasm_bindgen_futures::spawn_local(future);
 }

-// TODO: expose similar API to the rest of the codebase,
-// perhaps with some simple trait for a task to define its name
-
+#[deprecated(note = "use spawn_future from nym_task crate instead")]
 #[cfg(not(target_arch = "wasm32"))]
 #[track_caller]
 pub fn spawn_future<F>(future: F)
@@ -37,35 +37,3 @@ where
 {
    tokio::spawn(future);
 }
-
-#[cfg(not(target_arch = "wasm32"))]
-#[track_caller]
-pub fn spawn_named_future<F>(future: F, name: &str)
-where
-    F: Future + Send + 'static,
-    F::Output: Send + 'static,
-{
-    cfg_if::cfg_if! {if #[cfg(tokio_unstable)] {
-        #[allow(clippy::expect_used)]
-        tokio::task::Builder::new().name(name).spawn(future).expect("failed to spawn future");
-    } else {
-        let _ = name;
-        tracing::debug!(r#"the underlying binary hasn't been built with `RUSTFLAGS="--cfg tokio_unstable"` - the future naming won't do anything"#);
-        spawn_future(future);
-    }}
-}
-
-#[macro_export]
-macro_rules! spawn_future {
-    ($future:expr) => {{
-        $crate::spawn_future($future)
-    }};
-    ($future:expr, $name:expr) => {{
-        cfg_if::cfg_if! {if #[cfg(not(target_arch = "wasm32"))] {
-            $crate::spawn_named_future($future, $name)
-        } else {
-            let _ = $name;
-            $crate::spawn_future($future)
-        }}
-    }};
-}
@@ -40,7 +40,7 @@ where
    pub async fn flush_on_shutdown(
        mut self,
        mem_state: CombinedReplyStorage,
-        mut shutdown: nym_task::TaskClient,
+        shutdown: nym_task::ShutdownToken,
    ) {
        use tracing::{debug, error, info};

@@ -50,7 +50,7 @@ where
            return;
        }

-        shutdown.recv().await;
+        shutdown.cancelled().await;

        info!("PersistentReplyStorage is flushing all reply-related data to underlying storage");
        if let Err(err) = self.backend.flush_surb_storage(&mem_state).await {
@@ -12,7 +12,7 @@ use crate::socket_state::{ws_fd, PartiallyDelegatedHandle, SocketState};
 use crate::traits::GatewayPacketRouter;
 use crate::{cleanup_socket_message, try_decrypt_binary_message};
 use futures::{SinkExt, StreamExt};
-use nym_bandwidth_controller::{BandwidthController, BandwidthStatusMessage};
+use nym_bandwidth_controller::BandwidthController;
 use nym_credential_storage::ephemeral_storage::EphemeralStorage as EphemeralCredentialStorage;
 use nym_credential_storage::storage::Storage as CredentialStorage;
 use nym_credentials::CredentialSpendingData;
@@ -27,7 +27,7 @@ use nym_gateway_requests::{
 use nym_sphinx::forwarding::packet::MixPacket;
 use nym_statistics_common::clients::connection::ConnectionStatsEvent;
 use nym_statistics_common::clients::ClientStatsSender;
-use nym_task::TaskClient;
+use nym_task::ShutdownToken;
 use nym_validator_client::nyxd::contract_traits::DkgQueryClient;
 use rand::rngs::OsRng;
 use std::sync::Arc;
@@ -109,7 +109,7 @@ pub struct GatewayClient<C, St = EphemeralCredentialStorage> {
    connection_fd_callback: Option<Arc<dyn Fn(RawFd) + Send + Sync>>,

    /// Listen to shutdown messages and send notifications back to the task manager
-    task_client: TaskClient,
+    shutdown_token: ShutdownToken,
 }

 impl<C, St> GatewayClient<C, St> {
@@ -124,7 +124,7 @@ impl<C, St> GatewayClient<C, St> {
        bandwidth_controller: Option<BandwidthController<C, St>>,
        stats_reporter: ClientStatsSender,
        #[cfg(unix)] connection_fd_callback: Option<Arc<dyn Fn(RawFd) + Send + Sync>>,
-        task_client: TaskClient,
+        shutdown_token: ShutdownToken,
    ) -> Self {
        GatewayClient {
            cfg,
@@ -141,7 +141,7 @@ impl<C, St> GatewayClient<C, St> {
            negotiated_protocol: None,
            #[cfg(unix)]
            connection_fd_callback,
-            task_client,
+            shutdown_token,
        }
    }

@@ -293,7 +293,7 @@ impl<C, St> GatewayClient<C, St> {

        loop {
            tokio::select! {
-                _ = self.task_client.recv() => {
+                _ = self.shutdown_token.cancelled() => {
                    log::trace!("GatewayClient control response: Received shutdown");
                    log::debug!("GatewayClient control response: Exiting");
                    break Err(GatewayClientError::ConnectionClosedGatewayShutdown);
@@ -514,7 +514,7 @@ impl<C, St> GatewayClient<C, St> {
                self.cfg.bandwidth.require_tickets,
                derive_aes256_gcm_siv_key,
                #[cfg(not(target_arch = "wasm32"))]
-                self.task_client.clone(),
+                self.shutdown_token.clone(),
            )
            .await
            .map_err(GatewayClientError::RegistrationFailure),
@@ -631,9 +631,6 @@ impl<C, St> GatewayClient<C, St> {
                self.negotiated_protocol = protocol_version;
                log::debug!("authenticated: {status}, bandwidth remaining: {bandwidth_remaining}");

-                self.task_client.send_status_msg(Box::new(
-                    BandwidthStatusMessage::RemainingBandwidth(bandwidth_remaining),
-                ));
                Ok(())
            }
            ServerResponse::Error { message } => Err(GatewayClientError::GatewayError(message)),
@@ -1069,7 +1066,7 @@ impl<C, St> GatewayClient<C, St> {
                                .expect("no shared key present even though we're authenticated!"),
                        ),
                        self.bandwidth.clone(),
-                        self.task_client.clone(),
+                        self.shutdown_token.clone(),
                    )
                }
                _ => unreachable!(),
@@ -1143,8 +1140,8 @@ impl GatewayClient<InitOnly, EphemeralCredentialStorage> {
        // perfectly fine here, because it's not meant to be used
        let (ack_tx, _) = mpsc::unbounded();
        let (mix_tx, _) = mpsc::unbounded();
-        let task_client = TaskClient::dummy();
-        let packet_router = PacketRouter::new(ack_tx, mix_tx, task_client.clone());
+        let shutdown_token = ShutdownToken::default();
+        let packet_router = PacketRouter::new(ack_tx, mix_tx, shutdown_token.clone());

        GatewayClient {
            cfg: GatewayClientConfig::default().with_disabled_credentials_mode(true),
@@ -1157,11 +1154,11 @@ impl GatewayClient<InitOnly, EphemeralCredentialStorage> {
            connection: SocketState::NotConnected,
            packet_router,
            bandwidth_controller: None,
-            stats_reporter: ClientStatsSender::new(None, task_client.clone()),
+            stats_reporter: ClientStatsSender::new(None, shutdown_token.clone()),
            negotiated_protocol: None,
            #[cfg(unix)]
            connection_fd_callback,
-            task_client,
+            shutdown_token,
        }
    }

@@ -1170,7 +1167,7 @@ impl GatewayClient<InitOnly, EphemeralCredentialStorage> {
        packet_router: PacketRouter,
        bandwidth_controller: Option<BandwidthController<C, St>>,
        stats_reporter: ClientStatsSender,
-        task_client: TaskClient,
+        shutdown_token: ShutdownToken,
    ) -> GatewayClient<C, St> {
        // invariants that can't be broken
        // (unless somebody decided to expose some field that wasn't meant to be exposed)
@@ -1193,7 +1190,7 @@ impl GatewayClient<InitOnly, EphemeralCredentialStorage> {
            negotiated_protocol: self.negotiated_protocol,
            #[cfg(unix)]
            connection_fd_callback: self.connection_fd_callback,
-            task_client,
+            shutdown_token,
        }
    }
 }
@@ -7,7 +7,7 @@
 use crate::error::GatewayClientError;
 use crate::GatewayPacketRouter;
 use futures::channel::mpsc;
-use nym_task::TaskClient;
+use nym_task::ShutdownToken;

 pub type MixnetMessageSender = mpsc::UnboundedSender<Vec<Vec<u8>>>;
 pub type MixnetMessageReceiver = mpsc::UnboundedReceiver<Vec<Vec<u8>>>;
@@ -19,14 +19,14 @@ pub type AcknowledgementReceiver = mpsc::UnboundedReceiver<Vec<Vec<u8>>>;
 pub struct PacketRouter {
    ack_sender: AcknowledgementSender,
    mixnet_message_sender: MixnetMessageSender,
-    shutdown: TaskClient,
+    shutdown: ShutdownToken,
 }

 impl PacketRouter {
    pub fn new(
        ack_sender: AcknowledgementSender,
        mixnet_message_sender: MixnetMessageSender,
-        shutdown: TaskClient,
+        shutdown: ShutdownToken,
    ) -> Self {
        PacketRouter {
            ack_sender,
@@ -42,7 +42,7 @@ impl PacketRouter {
        if let Err(err) = self.mixnet_message_sender.unbounded_send(received_messages) {
            // check if the failure is due to the shutdown being in progress and thus the receiver channel
            // having already been dropped
-            if self.shutdown.is_shutdown_poll() || self.shutdown.is_dummy() {
+            if self.shutdown.is_cancelled() {
                // This should ideally not happen, but it's ok
                tracing::warn!("Failed to send mixnet messages due to receiver task shutdown");
                return Err(GatewayClientError::ShutdownInProgress);
@@ -58,7 +58,7 @@ impl PacketRouter {
        if let Err(err) = self.ack_sender.unbounded_send(received_acks) {
            // check if the failure is due to the shutdown being in progress and thus the receiver channel
            // having already been dropped
-            if self.shutdown.is_shutdown_poll() || self.shutdown.is_dummy() {
+            if self.shutdown.is_cancelled() {
                // This should ideally not happen, but it's ok
                tracing::warn!("Failed to send acks due to receiver task shutdown");
                return Err(GatewayClientError::ShutdownInProgress);
@@ -69,10 +69,6 @@ impl PacketRouter {
        }
        Ok(())
    }
-
-    pub fn disarm(&mut self) {
-        self.shutdown.disarm();
-    }
 }

 impl GatewayPacketRouter for PacketRouter {
@@ -11,7 +11,7 @@ use futures::stream::{SplitSink, SplitStream};
 use futures::{SinkExt, StreamExt};
 use nym_gateway_requests::shared_key::SharedGatewayKey;
 use nym_gateway_requests::{SensitiveServerResponse, ServerResponse, SimpleGatewayRequestsError};
-use nym_task::TaskClient;
+use nym_task::ShutdownToken;
 use si_scale::helpers::bibytes2;
 use std::os::raw::c_int as RawFd;
 use std::sync::Arc;
@@ -87,13 +87,13 @@ impl PartiallyDelegatedRouter {
        }
    }

-    async fn run(mut self, mut split_stream: SplitStream<WsConn>, mut task_client: TaskClient) {
+    async fn run(mut self, mut split_stream: SplitStream<WsConn>, shutdown_token: ShutdownToken) {
        let mut chunked_stream = (&mut split_stream).ready_chunks(8);
        let ret: Result<_, GatewayClientError> = loop {
            tokio::select! {
                biased;
                // received system-wide shutdown
-                _ = task_client.recv() => {
+                _ = shutdown_token.cancelled() => {
                    log::trace!("GatewayClient listener: Received shutdown");
                    log::debug!("GatewayClient listener: Exiting");
                    return;
@@ -118,11 +118,7 @@ impl PartiallyDelegatedRouter {

        let return_res = match ret {
            Err(err) => self.stream_return.send(Err(err)),
-            Ok(_) => {
-                self.packet_router.disarm();
-                task_client.disarm();
-                self.stream_return.send(Ok(split_stream))
-            }
+            Ok(_) => self.stream_return.send(Ok(split_stream)),
        };

        if return_res.is_err() {
@@ -266,8 +262,8 @@ impl PartiallyDelegatedRouter {
        Ok(plaintexts)
    }

-    fn spawn(self, split_stream: SplitStream<WsConn>, task_client: TaskClient) {
-        let fut = async move { self.run(split_stream, task_client).await };
+    fn spawn(self, split_stream: SplitStream<WsConn>, shutdown_token: ShutdownToken) {
+        let fut = async move { self.run(split_stream, shutdown_token).await };

        #[cfg(target_arch = "wasm32")]
        wasm_bindgen_futures::spawn_local(fut);
@@ -283,7 +279,7 @@ impl PartiallyDelegatedHandle {
        packet_router: PacketRouter,
        shared_key: Arc<SharedGatewayKey>,
        client_bandwidth: ClientBandwidth,
-        shutdown: TaskClient,
+        shutdown: ShutdownToken,
    ) -> Self {
        // when called for, it NEEDS TO yield back the stream so that we could merge it and
        // read control request responses.
@@ -20,11 +20,9 @@ use nym_api_requests::ecash::{
    PartialExpirationDateSignatureResponse, VerificationKeyResponse,
 };
 use nym_api_requests::models::{
-    ApiHealthResponse, GatewayBondAnnotated, GatewayCoreStatusResponse,
-    HistoricalPerformanceResponse, MixnodeCoreStatusResponse, MixnodeStatusResponse,
-    NymNodeDescription, RewardEstimationResponse, StakeSaturationResponse,
+    ApiHealthResponse, GatewayCoreStatusResponse, HistoricalPerformanceResponse,
+    MixnodeCoreStatusResponse, NymNodeDescription,
 };
-use nym_api_requests::models::{LegacyDescribedGateway, MixNodeBondAnnotated};
 use nym_api_requests::nym_nodes::{
    NodesByAddressesResponse, SemiSkimmedNodesWithMetadata, SkimmedNode, SkimmedNodesWithMetadata,
 };
@@ -249,65 +247,6 @@ impl<C, S> Client<C, S> {
        self.nym_api.change_base_urls(vec![new_endpoint.into()])
    }

-    #[deprecated]
-    pub async fn get_cached_mixnodes(&self) -> Result<Vec<MixNodeDetails>, ValidatorClientError> {
-        Ok(self.nym_api.get_mixnodes().await?)
-    }
-
-    #[deprecated]
-    pub async fn get_cached_mixnodes_detailed(
-        &self,
-    ) -> Result<Vec<MixNodeBondAnnotated>, ValidatorClientError> {
-        Ok(self.nym_api.get_mixnodes_detailed().await?)
-    }
-
-    #[deprecated]
-    pub async fn get_cached_mixnodes_detailed_unfiltered(
-        &self,
-    ) -> Result<Vec<MixNodeBondAnnotated>, ValidatorClientError> {
-        Ok(self.nym_api.get_mixnodes_detailed_unfiltered().await?)
-    }
-
-    #[deprecated]
-    pub async fn get_cached_rewarded_mixnodes(
-        &self,
-    ) -> Result<Vec<MixNodeDetails>, ValidatorClientError> {
-        Ok(self.nym_api.get_rewarded_mixnodes().await?)
-    }
-
-    #[deprecated]
-    pub async fn get_cached_rewarded_mixnodes_detailed(
-        &self,
-    ) -> Result<Vec<MixNodeBondAnnotated>, ValidatorClientError> {
-        Ok(self.nym_api.get_rewarded_mixnodes_detailed().await?)
-    }
-
-    #[deprecated]
-    pub async fn get_cached_active_mixnodes(
-        &self,
-    ) -> Result<Vec<MixNodeDetails>, ValidatorClientError> {
-        Ok(self.nym_api.get_active_mixnodes().await?)
-    }
-
-    #[deprecated]
-    pub async fn get_cached_active_mixnodes_detailed(
-        &self,
-    ) -> Result<Vec<MixNodeBondAnnotated>, ValidatorClientError> {
-        Ok(self.nym_api.get_active_mixnodes_detailed().await?)
-    }
-
-    #[deprecated]
-    pub async fn get_cached_gateways(&self) -> Result<Vec<GatewayBond>, ValidatorClientError> {
-        Ok(self.nym_api.get_gateways().await?)
-    }
-
-    #[deprecated]
-    pub async fn get_cached_gateways_detailed_unfiltered(
-        &self,
-    ) -> Result<Vec<GatewayBondAnnotated>, ValidatorClientError> {
-        Ok(self.nym_api.get_gateways_detailed_unfiltered().await?)
-    }
-
    pub async fn get_full_node_performance_history(
        &self,
        node_id: NodeId,
@@ -418,10 +357,10 @@ impl NymApiClient {
    }

    pub fn new_with_user_agent(api_url: Url, user_agent: impl Into<UserAgent>) -> Self {
-        let nym_api = nym_http_api_client::Client::builder::<_, ValidatorClientError>(api_url)
+        let nym_api = nym_http_api_client::Client::builder(api_url)
            .expect("invalid api url")
            .with_user_agent(user_agent.into())
-            .build::<ValidatorClientError>()
+            .build()
            .expect("failed to build nym api client");

        NymApiClient {
@@ -558,37 +497,6 @@ impl NymApiClient {
        Ok(self.nym_api.health().await?)
    }

-    #[deprecated]
-    pub async fn get_cached_active_mixnodes(
-        &self,
-    ) -> Result<Vec<MixNodeDetails>, ValidatorClientError> {
-        Ok(self.nym_api.get_active_mixnodes().await?)
-    }
-
-    #[deprecated]
-    pub async fn get_cached_rewarded_mixnodes(
-        &self,
-    ) -> Result<Vec<MixNodeDetails>, ValidatorClientError> {
-        Ok(self.nym_api.get_rewarded_mixnodes().await?)
-    }
-
-    #[deprecated]
-    pub async fn get_cached_mixnodes(&self) -> Result<Vec<MixNodeDetails>, ValidatorClientError> {
-        Ok(self.nym_api.get_mixnodes().await?)
-    }
-
-    #[deprecated]
-    pub async fn get_cached_gateways(&self) -> Result<Vec<GatewayBond>, ValidatorClientError> {
-        Ok(self.nym_api.get_gateways().await?)
-    }
-
-    #[deprecated]
-    pub async fn get_cached_described_gateways(
-        &self,
-    ) -> Result<Vec<LegacyDescribedGateway>, ValidatorClientError> {
-        Ok(self.nym_api.get_gateways_described().await?)
-    }
-
    pub async fn get_all_described_nodes(
        &self,
    ) -> Result<Vec<NymNodeDescription>, ValidatorClientError> {
@@ -655,30 +563,6 @@ impl NymApiClient {
            .await?)
    }

-    #[deprecated]
-    pub async fn get_mixnode_status(
-        &self,
-        mix_id: NodeId,
-    ) -> Result<MixnodeStatusResponse, ValidatorClientError> {
-        Ok(self.nym_api.get_mixnode_status(mix_id).await?)
-    }
-
-    #[deprecated]
-    pub async fn get_mixnode_reward_estimation(
-        &self,
-        mix_id: NodeId,
-    ) -> Result<RewardEstimationResponse, ValidatorClientError> {
-        Ok(self.nym_api.get_mixnode_reward_estimation(mix_id).await?)
-    }
-
-    #[deprecated]
-    pub async fn get_mixnode_stake_saturation(
-        &self,
-        mix_id: NodeId,
-    ) -> Result<StakeSaturationResponse, ValidatorClientError> {
-        Ok(self.nym_api.get_mixnode_stake_saturation(mix_id).await?)
-    }
-
    pub async fn blind_sign(
        &self,
        request_body: &BlindSignRequestBody,
@@ -24,10 +24,15 @@ impl Display for EcashApiClient {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        write!(
            f,
-            "[id: {}] {} @ {:?}",
+            "[id: {}] {} @ ({})",
            self.node_id,
            self.cosmos_address,
-            self.api_client.base_urls()
+            self.api_client
+                .base_urls()
+                .iter()
+                .map(|url| url.to_string())
+                .collect::<Vec<String>>()
+                .join(", ")
        )
    }
 }
@@ -91,13 +96,10 @@ impl TryFrom<ContractVKShare> for EcashApiClient {
        // In non-client applications this resolver can cause warning logs about H2 connection
        // failure. This indicates that the long lived https connection was closed by the remote
        // peer and the resolver will have to reconnect. It should not impact actual functionality
-        let api_client = nym_http_api_client::Client::builder::<
-            _,
-            nym_api_requests::models::RequestError,
-        >(url_address)
-        .map_err(|e| EcashApiError::ClientError(e.to_string()))?
-        .build::<nym_api_requests::models::RequestError>()
-        .map_err(|e| EcashApiError::ClientError(e.to_string()))?;
+        let api_client = nym_http_api_client::Client::builder(url_address)
+            .map_err(|e| EcashApiError::ClientError(e.to_string()))?
+            .build()
+            .map_err(|e| EcashApiError::ClientError(e.to_string()))?;

        Ok(EcashApiClient {
            api_client,
@@ -89,9 +89,7 @@ fn setup_connection_tests<H: BuildHasher + 'static>(
    });

    let api_connection_test_clients = api_urls.filter_map(|(network, url)| {
-        match nym_http_api_client::Client::builder(url.clone())
-            .and_then(|b| b.build::<nym_api_requests::models::RequestError>())
-        {
+        match nym_http_api_client::Client::builder(url.clone()).and_then(|b| b.build()) {
            Ok(client) => Some(ClientForConnectionTest::Api(network, url, client)),
            Err(err) => {
                eprintln!(
@@ -9,8 +9,7 @@ use thiserror::Error;
 pub enum ValidatorClientError {
    #[error("nym api request failed: {source}")]
    NymAPIError {
-        #[from]
-        source: nym_api::error::NymAPIError,
+        source: Box<nym_api::error::NymAPIError>,
    },

    #[error("Tendermint RPC request failure: {0}")]
@@ -28,3 +27,11 @@ pub enum ValidatorClientError {
    #[error("No validator API url has been provided")]
    NoAPIUrlAvailable,
 }
+
+impl From<nym_api::error::NymAPIError> for ValidatorClientError {
+    fn from(source: nym_api::error::NymAPIError) -> Self {
+        ValidatorClientError::NymAPIError {
+            source: Box::new(source),
+        }
+    }
+}
@@ -1,7 +1,6 @@
 // Copyright 2022-2023 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

-use nym_api_requests::models::RequestError;
 use nym_http_api_client::HttpClientError;

-pub type NymAPIError = HttpClientError<RequestError>;
+pub type NymAPIError = HttpClientError;
@@ -16,9 +16,8 @@ use nym_api_requests::ecash::models::{
 use nym_api_requests::ecash::VerificationKeyResponse;
 use nym_api_requests::models::{
    AnnotationResponse, ApiHealthResponse, BinaryBuildInformationOwned, ChainBlocksStatusResponse,
-    ChainStatusResponse, KeyRotationInfoResponse, LegacyDescribedMixNode, NodePerformanceResponse,
-    NodeRefreshBody, NymNodeDescription, PerformanceHistoryResponse, RewardedSetResponse,
-    SignerInformationResponse,
+    ChainStatusResponse, KeyRotationInfoResponse, NodePerformanceResponse, NodeRefreshBody,
+    NymNodeDescription, PerformanceHistoryResponse, RewardedSetResponse, SignerInformationResponse,
 };
 use nym_api_requests::nym_nodes::{
    NodesByAddressesRequestBody, NodesByAddressesResponse, PaginatedCachedNodesResponseV1,
@@ -32,19 +31,15 @@ pub use nym_api_requests::{
        VerifyEcashCredentialBody,
    },
    models::{
-        ComputeRewardEstParam, GatewayBondAnnotated, GatewayCoreStatusResponse,
-        GatewayStatusReportResponse, GatewayUptimeHistoryResponse, LegacyDescribedGateway,
-        MixNodeBondAnnotated, MixnodeCoreStatusResponse, MixnodeStatusReportResponse,
-        MixnodeStatusResponse, MixnodeUptimeHistoryResponse, RewardEstimationResponse,
-        StakeSaturationResponse, UptimeResponse,
+        GatewayCoreStatusResponse, GatewayStatusReportResponse, GatewayUptimeHistoryResponse,
+        MixnodeCoreStatusResponse, MixnodeStatusReportResponse, MixnodeStatusResponse,
+        MixnodeUptimeHistoryResponse, StakeSaturationResponse, UptimeResponse,
    },
    nym_nodes::{CachedNodesResponse, SemiSkimmedNode, SemiSkimmedNodesWithMetadata, SkimmedNode},
    NymNetworkDetailsResponse,
 };
-use nym_contracts_common::IdentityKey;
 use nym_http_api_client::{ApiClient, NO_PARAMS};
-use nym_mixnet_contract_common::mixnode::MixNodeDetails;
-use nym_mixnet_contract_common::{GatewayBond, IdentityKeyRef, NodeId, NymNodeDetails};
+use nym_mixnet_contract_common::{IdentityKeyRef, NodeId, NymNodeDetails};
 use std::net::IpAddr;
 use time::format_description::BorrowedFormatItem;
 use time::Date;
@@ -91,104 +86,6 @@ pub trait NymApiClientExt: ApiClient {
        .await
    }

-    #[deprecated]
-    #[instrument(level = "debug", skip(self))]
-    async fn get_mixnodes(&self) -> Result<Vec<MixNodeDetails>, NymAPIError> {
-        self.get_json(&[routes::V1_API_VERSION, routes::MIXNODES], NO_PARAMS)
-            .await
-    }
-
-    #[deprecated]
-    #[instrument(level = "debug", skip(self))]
-    async fn get_mixnodes_detailed(&self) -> Result<Vec<MixNodeBondAnnotated>, NymAPIError> {
-        self.get_json(
-            &[
-                routes::V1_API_VERSION,
-                routes::STATUS,
-                routes::MIXNODES,
-                routes::DETAILED,
-            ],
-            NO_PARAMS,
-        )
-        .await
-    }
-
-    #[deprecated]
-    #[instrument(level = "debug", skip(self))]
-    async fn get_gateways_detailed(&self) -> Result<Vec<GatewayBondAnnotated>, NymAPIError> {
-        self.get_json(
-            &[
-                routes::V1_API_VERSION,
-                routes::STATUS,
-                routes::GATEWAYS,
-                routes::DETAILED,
-            ],
-            NO_PARAMS,
-        )
-        .await
-    }
-
-    #[deprecated]
-    #[instrument(level = "debug", skip(self))]
-    async fn get_gateways_detailed_unfiltered(
-        &self,
-    ) -> Result<Vec<GatewayBondAnnotated>, NymAPIError> {
-        self.get_json(
-            &[
-                routes::V1_API_VERSION,
-                routes::STATUS,
-                routes::GATEWAYS,
-                routes::DETAILED_UNFILTERED,
-            ],
-            NO_PARAMS,
-        )
-        .await
-    }
-
-    #[deprecated]
-    #[instrument(level = "debug", skip(self))]
-    async fn get_mixnodes_detailed_unfiltered(
-        &self,
-    ) -> Result<Vec<MixNodeBondAnnotated>, NymAPIError> {
-        self.get_json(
-            &[
-                routes::V1_API_VERSION,
-                routes::STATUS,
-                routes::MIXNODES,
-                routes::DETAILED_UNFILTERED,
-            ],
-            NO_PARAMS,
-        )
-        .await
-    }
-
-    #[deprecated]
-    #[instrument(level = "debug", skip(self))]
-    async fn get_gateways(&self) -> Result<Vec<GatewayBond>, NymAPIError> {
-        self.get_json(&[routes::V1_API_VERSION, routes::GATEWAYS], NO_PARAMS)
-            .await
-    }
-
-    #[deprecated]
-    #[instrument(level = "debug", skip(self))]
-    async fn get_gateways_described(&self) -> Result<Vec<LegacyDescribedGateway>, NymAPIError> {
-        self.get_json(
-            &[routes::V1_API_VERSION, routes::GATEWAYS, routes::DESCRIBED],
-            NO_PARAMS,
-        )
-        .await
-    }
-
-    #[deprecated]
-    #[instrument(level = "debug", skip(self))]
-    async fn get_mixnodes_described(&self) -> Result<Vec<LegacyDescribedMixNode>, NymAPIError> {
-        self.get_json(
-            &[routes::V1_API_VERSION, routes::MIXNODES, routes::DESCRIBED],
-            NO_PARAMS,
-        )
-        .await
-    }
-
    #[tracing::instrument(level = "debug", skip_all)]
    async fn get_node_performance_history(
        &self,
@@ -273,11 +170,9 @@ pub trait NymApiClientExt: ApiClient {

            if !metadata.consistency_check(&res.metadata) {
                // Create a custom error for inconsistent metadata
-                return Err(NymAPIError::EndpointFailure {
-                    status: reqwest::StatusCode::INTERNAL_SERVER_ERROR,
-                    error: nym_api_requests::models::RequestError::new(
-                        "Inconsistent paged metadata",
-                    ),
+                return Err(NymAPIError::InternalResponseInconsistency {
+                    url: self.api_url().clone(),
+                    details: "Inconsistent paged metadata".to_string(),
                });
            }

@@ -316,11 +211,9 @@ pub trait NymApiClientExt: ApiClient {
                .await?;

            if !metadata.consistency_check(&res.metadata) {
-                return Err(NymAPIError::EndpointFailure {
-                    status: reqwest::StatusCode::INTERNAL_SERVER_ERROR,
-                    error: nym_api_requests::models::RequestError::new(
-                        "Inconsistent paged metadata",
-                    ),
+                return Err(NymAPIError::InternalResponseInconsistency {
+                    url: self.api_url().clone(),
+                    details: "Inconsistent paged metadata".to_string(),
                });
            }

@@ -361,11 +254,9 @@ pub trait NymApiClientExt: ApiClient {
                .await?;

            if !metadata.consistency_check(&res.metadata) {
-                return Err(NymAPIError::EndpointFailure {
-                    status: reqwest::StatusCode::INTERNAL_SERVER_ERROR,
-                    error: nym_api_requests::models::RequestError::new(
-                        "Inconsistent paged metadata",
-                    ),
+                return Err(NymAPIError::InternalResponseInconsistency {
+                    url: self.api_url().clone(),
+                    details: "Inconsistent paged metadata".to_string(),
                });
            }

@@ -856,42 +747,6 @@ pub trait NymApiClientExt: ApiClient {
        .await
    }

-    #[deprecated]
-    #[instrument(level = "debug", skip(self))]
-    async fn get_active_mixnodes(&self) -> Result<Vec<MixNodeDetails>, NymAPIError> {
-        self.get_json(
-            &[routes::V1_API_VERSION, routes::MIXNODES, routes::ACTIVE],
-            NO_PARAMS,
-        )
-        .await
-    }
-
-    #[deprecated]
-    #[instrument(level = "debug", skip(self))]
-    async fn get_active_mixnodes_detailed(&self) -> Result<Vec<MixNodeBondAnnotated>, NymAPIError> {
-        self.get_json(
-            &[
-                routes::V1_API_VERSION,
-                routes::STATUS,
-                routes::MIXNODES,
-                routes::ACTIVE,
-                routes::DETAILED,
-            ],
-            NO_PARAMS,
-        )
-        .await
-    }
-
-    #[deprecated]
-    #[instrument(level = "debug", skip(self))]
-    async fn get_rewarded_mixnodes(&self) -> Result<Vec<MixNodeDetails>, NymAPIError> {
-        self.get_json(
-            &[routes::V1_API_VERSION, routes::MIXNODES, routes::REWARDED],
-            NO_PARAMS,
-        )
-        .await
-    }
-
    #[deprecated]
    #[instrument(level = "debug", skip(self))]
    async fn get_mixnode_report(
@@ -968,24 +823,6 @@ pub trait NymApiClientExt: ApiClient {
        .await
    }

-    #[deprecated]
-    #[instrument(level = "debug", skip(self))]
-    async fn get_rewarded_mixnodes_detailed(
-        &self,
-    ) -> Result<Vec<MixNodeBondAnnotated>, NymAPIError> {
-        self.get_json(
-            &[
-                routes::V1_API_VERSION,
-                routes::STATUS,
-                routes::MIXNODES,
-                routes::REWARDED,
-                routes::DETAILED,
-            ],
-            NO_PARAMS,
-        )
-        .await
-    }
-
    #[deprecated]
    #[instrument(level = "debug", skip(self))]
    async fn get_gateway_core_status_count(
@@ -1053,104 +890,6 @@ pub trait NymApiClientExt: ApiClient {
        }
    }

-    #[deprecated]
-    #[instrument(level = "debug", skip(self))]
-    async fn get_mixnode_status(
-        &self,
-        mix_id: NodeId,
-    ) -> Result<MixnodeStatusResponse, NymAPIError> {
-        self.get_json(
-            &[
-                routes::V1_API_VERSION,
-                routes::STATUS_ROUTES,
-                routes::MIXNODE,
-                &mix_id.to_string(),
-                routes::STATUS,
-            ],
-            NO_PARAMS,
-        )
-        .await
-    }
-
-    #[deprecated]
-    #[instrument(level = "debug", skip(self))]
-    async fn get_mixnode_reward_estimation(
-        &self,
-        mix_id: NodeId,
-    ) -> Result<RewardEstimationResponse, NymAPIError> {
-        self.get_json(
-            &[
-                routes::V1_API_VERSION,
-                routes::STATUS_ROUTES,
-                routes::MIXNODE,
-                &mix_id.to_string(),
-                routes::REWARD_ESTIMATION,
-            ],
-            NO_PARAMS,
-        )
-        .await
-    }
-
-    #[deprecated]
-    #[instrument(level = "debug", skip(self))]
-    async fn compute_mixnode_reward_estimation(
-        &self,
-        mix_id: NodeId,
-        request_body: &ComputeRewardEstParam,
-    ) -> Result<RewardEstimationResponse, NymAPIError> {
-        self.post_json(
-            &[
-                routes::V1_API_VERSION,
-                routes::STATUS_ROUTES,
-                routes::MIXNODE,
-                &mix_id.to_string(),
-                routes::COMPUTE_REWARD_ESTIMATION,
-            ],
-            NO_PARAMS,
-            request_body,
-        )
-        .await
-    }
-
-    #[deprecated]
-    #[instrument(level = "debug", skip(self))]
-    async fn get_mixnode_stake_saturation(
-        &self,
-        mix_id: NodeId,
-    ) -> Result<StakeSaturationResponse, NymAPIError> {
-        self.get_json(
-            &[
-                routes::V1_API_VERSION,
-                routes::STATUS_ROUTES,
-                routes::MIXNODE,
-                &mix_id.to_string(),
-                routes::STAKE_SATURATION,
-            ],
-            NO_PARAMS,
-        )
-        .await
-    }
-
-    #[deprecated]
-    #[allow(deprecated)]
-    #[instrument(level = "debug", skip(self))]
-    async fn get_mixnode_inclusion_probability(
-        &self,
-        mix_id: NodeId,
-    ) -> Result<nym_api_requests::models::InclusionProbabilityResponse, NymAPIError> {
-        self.get_json(
-            &[
-                routes::V1_API_VERSION,
-                routes::STATUS_ROUTES,
-                routes::MIXNODE,
-                &mix_id.to_string(),
-                routes::INCLUSION_CHANCE,
-            ],
-            NO_PARAMS,
-        )
-        .await
-    }
-
    #[instrument(level = "debug", skip(self))]
    async fn get_current_node_performance(
        &self,
@@ -1199,34 +938,6 @@ pub trait NymApiClientExt: ApiClient {
        .await
    }

-    #[deprecated]
-    #[instrument(level = "debug", skip(self))]
-    async fn get_mixnodes_blacklisted(&self) -> Result<Vec<NodeId>, NymAPIError> {
-        self.get_json(
-            &[
-                routes::V1_API_VERSION,
-                routes::MIXNODES,
-                routes::BLACKLISTED,
-            ],
-            NO_PARAMS,
-        )
-        .await
-    }
-
-    #[deprecated]
-    #[instrument(level = "debug", skip(self))]
-    async fn get_gateways_blacklisted(&self) -> Result<Vec<IdentityKey>, NymAPIError> {
-        self.get_json(
-            &[
-                routes::V1_API_VERSION,
-                routes::GATEWAYS,
-                routes::BLACKLISTED,
-            ],
-            NO_PARAMS,
-        )
-        .await
-    }
-
    #[instrument(level = "debug", skip(self, request_body))]
    async fn blind_sign(
        &self,
@@ -28,7 +28,7 @@ use cosmrs::proto::cosmwasm::wasm::v1::{
    QueryRawContractStateResponse, QuerySmartContractStateRequest, QuerySmartContractStateResponse,
 };
 use cosmrs::tendermint::{block, chain, Hash};
-use cosmrs::{AccountId, Coin as CosmosCoin, Tx};
+use cosmrs::{AccountId, Coin as CosmosCoin};
 use prost::Message;
 use serde::{Deserialize, Serialize};

@@ -556,23 +556,12 @@ pub trait CosmWasmClient: TendermintRpcClient {
        Ok(serde_json::from_slice(&res.data)?)
    }

-    // deprecation warning is due to the fact the protobuf files built were based on cosmos-sdk 0.44,
-    // where they prefer using tx_bytes directly. However, in 0.42, which we are using at the time
-    // of writing this, the option does not work
-    // TODO: we should really stop using the `tx` argument here and use `tx_bytes` exlusively,
-    // however, at the time of writing this update, while our QA and mainnet networks do support it,
-    // sandbox is still running old version of wasmd that lacks support for `tx_bytes`
-    #[allow(deprecated)]
-    async fn query_simulate(
-        &self,
-        tx: Option<Tx>,
-        tx_bytes: Vec<u8>,
-    ) -> Result<SimulateResponse, NyxdError> {
+    async fn query_simulate(&self, tx_bytes: Vec<u8>) -> Result<SimulateResponse, NyxdError> {
        let path = Some("/cosmos.tx.v1beta1.Service/Simulate".to_owned());

        let req = SimulateRequest {
-            tx: tx.map(Into::into),
            tx_bytes,
+            ..Default::default()
        };

        let res = self
@@ -81,17 +81,14 @@ where
            auth_info: single_unspecified_signer_auth(public_key, sequence_response.sequence),
            signatures: vec![Vec::new()],
        };
-        self.query_simulate(Some(partial_tx), Vec::new()).await

-        // for completion sake, once we're able to transition into using `tx_bytes`,
-        // we might want to use something like this instead:
-        // let tx_raw: tx::Raw = cosmrs::proto::cosmos::tx::v1beta1::TxRaw {
-        //     body_bytes: partial_tx.body.into_bytes().unwrap(),
-        //     auth_info_bytes: partial_tx.auth_info.into_bytes().unwrap(),
-        //     signatures: partial_tx.signatures,
-        // }
-        // .into();
-        // self.query_simulate(None, tx_raw.to_bytes().unwrap()).await
+        let tx_raw: tx::Raw = cosmrs::proto::cosmos::tx::v1beta1::TxRaw {
+            body_bytes: partial_tx.body.into_bytes()?,
+            auth_info_bytes: partial_tx.auth_info.into_bytes()?,
+            signatures: partial_tx.signatures,
+        }
+        .into();
+        self.query_simulate(tx_raw.to_bytes()?).await
    }

    async fn upload(
@@ -1,3 +1,3 @@
 // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.

-export type Role = "EntryGateway" | "Layer1" | "Layer2" | "Layer3" | "ExitGateway" | "Standby";
+export type Role = "entry_gateway" | "layer1" | "layer2" | "layer3" | "exit_gateway" | "standby";
@@ -23,6 +23,7 @@ use serde_repr::{Deserialize_repr, Serialize_repr};

 /// Full details associated with given mixnode.
 #[cw_serde]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
 pub struct MixNodeDetails {
    /// Basic bond information of this mixnode, such as owner address, original pledge, etc.
    pub bond_information: MixNodeBond,
@@ -695,6 +696,7 @@ impl From<LegacyMixLayer> for u8 {
    Copy,
 )]
 #[schemars(crate = "::cosmwasm_schema::schemars")]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
 pub struct PendingMixNodeChanges {
    pub pledge_change: Option<EpochEventId>,

@@ -0,0 +1,56 @@
+[package]
+name = "nym-credential-proxy-lib"
+version = "0.1.0"
+authors.workspace = true
+repository.workspace = true
+homepage.workspace = true
+documentation.workspace = true
+edition.workspace = true
+license.workspace = true
+rust-version.workspace = true
+readme.workspace = true
+
+[dependencies]
+anyhow = { workspace = true }
+axum = { workspace = true }
+bip39 = { workspace = true, features = ["zeroize"] }
+bs58 = { workspace = true }
+futures = { workspace = true }
+humantime = { workspace = true }
+rand = { workspace = true }
+reqwest = { workspace = true, features = ["rustls-tls"] }
+serde = { workspace = true, features = ["derive"] }
+serde_json = { workspace = true }
+strum = { workspace = true, features = ["derive"] }
+strum_macros = { workspace = true }
+sqlx = { workspace = true, features = ["runtime-tokio-rustls", "sqlite", "macros", "migrate", "time"] }
+time = { workspace = true }
+thiserror = { workspace = true }
+tokio = { workspace = true, features = ["sync"] }
+tokio-util = { workspace = true, features = ["rt"] }
+tracing = { workspace = true }
+uuid = { workspace = true, features = ["serde"] }
+url = { workspace = true }
+zeroize = { workspace = true }
+
+nym-credentials = { path = "../credentials" }
+nym-crypto = { path = "../crypto", features = ["asymmetric", "rand", "serde"] }
+nym-credentials-interface = { path = "../credentials-interface" }
+nym-credential-proxy-requests = { path = "../../nym-credential-proxy/nym-credential-proxy-requests" }
+nym-ecash-signer-check = { path = "../ecash-signer-check" }
+nym-ecash-contract-common = { path = "../cosmwasm-smart-contracts/ecash-contract" }
+nym-compact-ecash = { path = "../nym_offline_compact_ecash" }
+nym-validator-client = { path = "../client-libs/validator-client" }
+nym-network-defaults = { path = "../network-defaults" }
+nym-cache = { path = "../nym-cache" }
+
+[dev-dependencies]
+tempfile = { workspace = true }
+
+[build-dependencies]
+anyhow = { workspace = true }
+tokio = { workspace = true, features = ["rt-multi-thread", "macros"] }
+sqlx = { workspace = true, features = ["runtime-tokio-rustls", "sqlite", "macros", "migrate"] }
+
+[lints]
+workspace = true
@@ -0,0 +1,180 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: GPL-3.0-only
+
+use crate::error::CredentialProxyError;
+use crate::shared_state::nyxd_client::ChainClient;
+use crate::storage::models::StorableEcashDeposit;
+use nym_compact_ecash::WithdrawalRequest;
+use nym_credentials::IssuanceTicketBook;
+use nym_crypto::asymmetric::ed25519;
+use nym_validator_client::nyxd::cosmwasm_client::ContractResponseData;
+use nym_validator_client::nyxd::{Coin, Hash};
+use rand::rngs::OsRng;
+use std::fmt::Debug;
+use time::OffsetDateTime;
+use tokio_util::sync::CancellationToken;
+use tracing::{error, info, instrument};
+use zeroize::Zeroizing;
+
+pub struct BufferedDeposit {
+    pub deposit_id: u32,
+
+    // note: this type implements `ZeroizeOnDrop`
+    pub ed25519_private_key: ed25519::PrivateKey,
+}
+
+impl TryFrom<StorableEcashDeposit> for BufferedDeposit {
+    type Error = CredentialProxyError;
+
+    fn try_from(deposit: StorableEcashDeposit) -> Result<Self, Self::Error> {
+        let ed25519_private_key = ed25519::PrivateKey::from_bytes(
+            deposit.ed25519_deposit_private_key.as_ref(),
+        )
+        .map_err(|err| CredentialProxyError::DatabaseInconsistency {
+            reason: format!("one of the stored deposit ed25519 private keys is malformed: {err}"),
+        })?;
+
+        Ok(BufferedDeposit {
+            deposit_id: deposit.deposit_id,
+            ed25519_private_key,
+        })
+    }
+}
+
+impl BufferedDeposit {
+    pub fn new(deposit_id: u32, ed25519_private_key: ed25519::PrivateKey) -> Self {
+        BufferedDeposit {
+            deposit_id,
+            ed25519_private_key,
+        }
+    }
+
+    pub fn sign_ticketbook_plaintext(
+        &self,
+        withdrawal_request: &WithdrawalRequest,
+    ) -> ed25519::Signature {
+        let plaintext = IssuanceTicketBook::request_plaintext(withdrawal_request, self.deposit_id);
+        self.ed25519_private_key.sign(plaintext)
+    }
+}
+
+pub struct PerformedDeposits {
+    pub deposits_data: Vec<BufferedDeposit>,
+
+    // shared by all performed deposits as they were included in the same tx
+    pub tx_hash: Hash,
+    pub requested_on: OffsetDateTime,
+    pub deposit_amount: Coin,
+}
+
+impl PerformedDeposits {
+    pub(crate) fn to_storable(&self) -> Vec<StorableEcashDeposit> {
+        self.deposits_data
+            .iter()
+            .map(|d| StorableEcashDeposit {
+                deposit_id: d.deposit_id,
+                deposit_tx_hash: self.tx_hash.to_string(),
+                requested_on: self.requested_on,
+                deposit_amount: self.deposit_amount.to_string(),
+                ed25519_deposit_private_key: Zeroizing::new(d.ed25519_private_key.to_bytes()),
+            })
+            .collect()
+    }
+}
+
+#[instrument(skip(client, cancellation_on_critical_failure), err(Display))]
+pub async fn make_deposits_request(
+    client: &ChainClient,
+    deposit_amount: Coin,
+    memo: impl Into<String> + Debug,
+    amount: usize,
+    cancellation_on_critical_failure: &CancellationToken,
+) -> Result<PerformedDeposits, CredentialProxyError> {
+    let requested_on = OffsetDateTime::now_utc();
+    let chain_write_permit = client.start_chain_tx().await;
+    let mut rng = OsRng;
+
+    let keys = (0..amount)
+        .map(|_| ed25519::PrivateKey::new(&mut rng))
+        .collect::<Vec<_>>();
+
+    info!("starting {amount} deposits");
+    let mut contents = Vec::new();
+    for key in &keys {
+        let public_key: ed25519::PublicKey = key.into();
+        contents.push((public_key.to_base58_string(), deposit_amount.clone()));
+    }
+
+    let execute_res = chain_write_permit
+        .make_deposits(memo.into(), contents)
+        .await?;
+
+    let tx_hash = execute_res.transaction_hash;
+    info!("{amount} deposits made in transaction: {tx_hash}");
+
+    let contract_data = match execute_res.to_contract_data() {
+        Ok(contract_data) => contract_data,
+        Err(err) => {
+            // that one is tricky. deposits technically got made, but we somehow failed to parse response,
+            // in this case terminate the proxy with 0 exit code so it wouldn't get automatically restarted
+            // because it requires some serious MANUAL intervention
+            error!("CRITICAL FAILURE: failed to parse out deposit information from the contract transaction. either the chain got upgraded and the schema changed or the ecash contract got changed! terminating the process. it has to be inspected manually. error was: {err}");
+            cancellation_on_critical_failure.cancel();
+            return Err(CredentialProxyError::DepositFailure);
+        }
+    };
+
+    if contract_data.len() != amount {
+        // another critical failure, that one should be quite impossible and thus has to be manually inspected
+        error!("CRITICAL FAILURE: failed to parse out all deposit information from the contract transaction. got {} responses while we sent {amount} deposits! either the chain got upgraded and the schema changed or the ecash contract got changed! terminating the process. it has to be inspected manually", contract_data.len());
+        cancellation_on_critical_failure.cancel();
+        return Err(CredentialProxyError::DepositFailure);
+    }
+
+    let mut deposits_data = Vec::new();
+    for (key, response) in keys.into_iter().zip(contract_data) {
+        let response_index = response.message_index;
+        let deposit_id = match response.parse_singleton_u32_contract_data() {
+            Ok(deposit_id) => deposit_id,
+            Err(err) => {
+                // another impossibility
+                error!("CRITICAL FAILURE: failed to parse out deposit id out of the response at index {response_index}: {err}. either the chain got upgraded and the schema changed or the ecash contract got changed! terminating the process. it has to be inspected manually");
+                cancellation_on_critical_failure.cancel();
+                return Err(CredentialProxyError::DepositFailure);
+            }
+        };
+
+        deposits_data.push(BufferedDeposit::new(deposit_id, key));
+    }
+
+    Ok(PerformedDeposits {
+        deposits_data,
+        tx_hash,
+        requested_on,
+        deposit_amount,
+    })
+}
+
+pub fn split_deposits(total: usize, max_request_size: usize) -> impl Iterator<Item = usize> {
+    (0..total)
+        .step_by(max_request_size)
+        .map(move |start| std::cmp::min(max_request_size, total - start))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn request_sizes_test() {
+        assert_eq!(
+            split_deposits(100, 32).collect::<Vec<_>>(),
+            vec![32, 32, 32, 4]
+        );
+
+        assert_eq!(split_deposits(10, 32).collect::<Vec<_>>(), vec![10]);
+        assert_eq!(split_deposits(32, 32).collect::<Vec<_>>(), vec![32]);
+        assert_eq!(split_deposits(33, 32).collect::<Vec<_>>(), vec![32, 1]);
+        assert_eq!(split_deposits(1, 32).collect::<Vec<_>>(), vec![1]);
+    }
+}
@@ -1,26 +1,24 @@
 // Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: GPL-3.0-only

-use crate::deposits_buffer::helpers::{request_sizes, BufferedDeposit, PerformedDeposits};
 use crate::deposits_buffer::refill_task::RefillTask;
 use crate::error::CredentialProxyError;
-use crate::http::state::required_deposit_cache::RequiredDepositCache;
-use crate::http::state::ChainClient;
+use crate::shared_state::nyxd_client::ChainClient;
+use crate::shared_state::required_deposit_cache::RequiredDepositCache;
 use crate::storage::CredentialProxyStorage;
 use nym_compact_ecash::PublicKeyUser;
-use nym_crypto::asymmetric::ed25519;
 use nym_ecash_contract_common::deposit::DepositId;
-use nym_validator_client::nyxd::cosmwasm_client::ContractResponseData;
 use nym_validator_client::nyxd::Coin;
-use rand::rngs::OsRng;
 use std::sync::Arc;
 use std::time::Duration;
 use time::OffsetDateTime;
 use tokio::sync::Mutex as AsyncMutex;
 use tokio_util::sync::CancellationToken;
-use tracing::{debug, error, info, instrument, warn};
+use tracing::{debug, info, instrument, warn};
 use uuid::Uuid;

+pub use helpers::{make_deposits_request, split_deposits, BufferedDeposit, PerformedDeposits};
+
 pub(crate) mod helpers;
 mod refill_task;

@@ -43,12 +41,12 @@ struct DepositsBufferInner {
 }

 #[derive(Clone)]
-pub(crate) struct DepositsBuffer {
+pub struct DepositsBuffer {
    inner: Arc<DepositsBufferInner>,
 }

 impl DepositsBuffer {
-    pub(crate) async fn new(
+    pub async fn new(
        storage: CredentialProxyStorage,
        client: ChainClient,
        required_deposit_cache: RequiredDepositCache,
@@ -87,70 +85,20 @@ impl DepositsBuffer {
        &self,
        amount: usize,
    ) -> Result<PerformedDeposits, CredentialProxyError> {
-        let requested_on = OffsetDateTime::now_utc();
-        let chain_write_permit = self.inner.client.start_chain_tx().await;
-        let mut rng = OsRng;
-
+        let memo = format!(
+            "credential-proxy-{}: performing {amount} deposits",
+            self.inner.short_sha
+        );
        let deposit_amount = self.deposit_amount().await?;
-        let keys = (0..amount)
-            .map(|_| ed25519::PrivateKey::new(&mut rng))
-            .collect::<Vec<_>>();

-        info!("starting {amount} deposits");
-        let mut contents = Vec::new();
-        for key in &keys {
-            let public_key: ed25519::PublicKey = key.into();
-            contents.push((public_key.to_base58_string(), deposit_amount.clone()));
-        }
-
-        let execute_res = chain_write_permit
-            .make_deposits(self.inner.short_sha, contents)
-            .await?;
-
-        let tx_hash = execute_res.transaction_hash;
-        info!("{amount} deposits made in transaction: {tx_hash}");
-
-        let contract_data = match execute_res.to_contract_data() {
-            Ok(contract_data) => contract_data,
-            Err(err) => {
-                // that one is tricky. deposits technically got made, but we somehow failed to parse response,
-                // in this case terminate the proxy with 0 exit code so it wouldn't get automatically restarted
-                // because it requires some serious MANUAL intervention
-                error!("CRITICAL FAILURE: failed to parse out deposit information from the contract transaction. either the chain got upgraded and the schema changed or the ecash contract got changed! terminating the process. it has to be inspected manually. error was: {err}");
-                self.inner.cancellation_token.cancel();
-                return Err(CredentialProxyError::DepositFailure);
-            }
-        };
-
-        if contract_data.len() != amount {
-            // another critical failure, that one should be quite impossible and thus has to be manually inspected
-            error!("CRITICAL FAILURE: failed to parse out all deposit information from the contract transaction. got {} responses while we sent {amount} deposits! either the chain got upgraded and the schema changed or the ecash contract got changed! terminating the process. it has to be inspected manually", contract_data.len());
-            self.inner.cancellation_token.cancel();
-            return Err(CredentialProxyError::DepositFailure);
-        }
-
-        let mut deposits_data = Vec::new();
-        for (key, response) in keys.into_iter().zip(contract_data) {
-            let response_index = response.message_index;
-            let deposit_id = match response.parse_singleton_u32_contract_data() {
-                Ok(deposit_id) => deposit_id,
-                Err(err) => {
-                    // another impossibility
-                    error!("CRITICAL FAILURE: failed to parse out deposit id out of the response at index {response_index}: {err}. either the chain got upgraded and the schema changed or the ecash contract got changed! terminating the process. it has to be inspected manually");
-                    self.inner.cancellation_token.cancel();
-                    return Err(CredentialProxyError::DepositFailure);
-                }
-            };
-
-            deposits_data.push(BufferedDeposit::new(deposit_id, key));
-        }
-
-        Ok(PerformedDeposits {
-            deposits_data,
-            tx_hash,
-            requested_on,
+        make_deposits_request(
+            &self.inner.client,
            deposit_amount,
-        })
+            &memo,
+            amount,
+            &self.inner.cancellation_token,
+        )
+        .await
    }

    async fn insert_new_deposits(
@@ -178,7 +126,7 @@ impl DepositsBuffer {
        let target = self.deposits_upper_threshold();
        let to_request = target - available;

-        for request_chunk in request_sizes(to_request, self.inner.max_concurrent_deposits) {
+        for request_chunk in split_deposits(to_request, self.inner.max_concurrent_deposits) {
            // note: we check for cancellation between individual requests
            // as opposed to wrapping that in tokio::select! so that we would never abandon chain operations
            // as we wouldn't want to lose funds
@@ -250,7 +198,7 @@ impl DepositsBuffer {
        }
    }

-    pub(crate) async fn get_valid_deposit(
+    pub async fn get_valid_deposit(
        &self,
        request_uuid: Uuid,
        requested_on: OffsetDateTime,
@@ -290,7 +238,7 @@ impl DepositsBuffer {
        }
    }

-    pub(crate) async fn wait_for_shutdown(&self) {
+    pub async fn wait_for_shutdown(&self) {
        let task_handle = self.inner.deposits_refill_task.take_task_join_handle();
        if let Some(task_handle) = task_handle {
            if !task_handle.is_finished() {
@@ -1,4 +1,4 @@
-// Copyright 2024 Nym Technologies SA <contact@nymtech.net>
+// Copyright 2025 Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: GPL-3.0-only

 use nym_ecash_signer_check::SignerCheckError;
@@ -72,10 +72,7 @@ pub enum CredentialProxyError {
    },

    #[error("Nym API request failed: {source}")]
-    NymApiFailure {
-        #[from]
-        source: NymAPIError,
-    },
+    NymApiFailure { source: Box<NymAPIError> },

    #[error("Compact ecash internal error: {0}")]
    CompactEcashInternalError(#[from] nym_compact_ecash::error::CompactEcashError),
@@ -134,6 +131,38 @@ pub enum CredentialProxyError {
        #[from]
        source: SignerCheckError,
    },
+
+    #[error(
+        "this operation couldn't be completed as the program is in the process of shutting down"
+    )]
+    ShutdownInProgress,
+
+    #[error("failed to obtain wallet shares with id {id}: {message}")]
+    ShareByIdLoadError { message: String, id: i64 },
+
+    #[error("failed to obtain wallet shares with device_id {device_id} and credential_id: {credential_id}: {message}")]
+    ShareByDeviceLoadError {
+        message: String,
+        device_id: String,
+        credential_id: String,
+    },
+
+    #[error("could not find shares with id {id}")]
+    SharesByIdNotFound { id: i64 },
+
+    #[error("could not find shares with device_id {device_id} and credential_id: {credential_id}")]
+    SharesByDeviceNotFound {
+        device_id: String,
+        credential_id: String,
+    },
+}
+
+impl From<NymAPIError> for CredentialProxyError {
+    fn from(source: NymAPIError) -> Self {
+        CredentialProxyError::NymApiFailure {
+            source: Box::new(source),
+        }
+    }
 }

 impl CredentialProxyError {
@@ -0,0 +1,67 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: GPL-3.0-only
+
+use rand::rngs::OsRng;
+use rand::RngCore;
+use time::OffsetDateTime;
+use tracing::{debug, info, warn};
+use uuid::Uuid;
+
+pub fn random_uuid() -> Uuid {
+    let mut bytes = [0u8; 16];
+    let mut rng = OsRng;
+    rng.fill_bytes(&mut bytes);
+    Uuid::from_bytes(bytes)
+}
+
+pub struct LockTimer {
+    created: OffsetDateTime,
+    message: String,
+}
+
+impl LockTimer {
+    pub fn new<S: Into<String>>(message: S) -> Self {
+        LockTimer {
+            message: message.into(),
+            ..Default::default()
+        }
+    }
+}
+
+impl Drop for LockTimer {
+    fn drop(&mut self) {
+        let time_taken = OffsetDateTime::now_utc() - self.created;
+        let time_taken_formatted = humantime::format_duration(time_taken.unsigned_abs());
+        if time_taken > time::Duration::SECOND * 10 {
+            warn!(time_taken = %time_taken_formatted, "{}", self.message)
+        } else if time_taken > time::Duration::SECOND * 5 {
+            info!(time_taken = %time_taken_formatted, "{}", self.message)
+        } else {
+            debug!(time_taken = %time_taken_formatted, "{}", self.message)
+        };
+    }
+}
+
+impl Default for LockTimer {
+    fn default() -> Self {
+        LockTimer {
+            created: OffsetDateTime::now_utc(),
+            message: "released the lock".to_string(),
+        }
+    }
+}
+
+// #[allow(clippy::panic)]
+// fn build_sha_short() -> &'static str {
+//     let bin_info = bin_info!();
+//     if bin_info.commit_sha.len() < 7 {
+//         panic!("unavailable build commit sha")
+//     }
+//
+//     if bin_info.commit_sha == "VERGEN_IDEMPOTENT_OUTPUT" {
+//         error!("the binary hasn't been built correctly. it doesn't have a commit sha information");
+//         return "unknown";
+//     }
+//
+//     &bin_info.commit_sha[..7]
+// }
@@ -1,11 +1,12 @@
-// Copyright 2024 Nym Technologies SA <contact@nymtech.net>
-// SPDX-License-Identifier: GPL-3.0-only
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0

 use crate::error::CredentialProxyError;
 use axum::http::StatusCode;
 use axum::response::{IntoResponse, Response};
 use axum::Json;
 use nym_credential_proxy_requests::api::v1::ErrorResponse;
+use tracing::warn;
 use uuid::Uuid;

 #[derive(Debug, Clone)]
@@ -35,6 +36,10 @@ impl RequestError {
        }
    }

+    pub fn new_plain_error(err: CredentialProxyError) -> Self {
+        Self::from_err(err, StatusCode::INTERNAL_SERVER_ERROR)
+    }
+
    pub fn new_server_error(err: CredentialProxyError, uuid: Uuid) -> Self {
        RequestError::new_with_uuid(err.to_string(), uuid, StatusCode::INTERNAL_SERVER_ERROR)
    }
@@ -59,3 +64,12 @@ impl IntoResponse for RequestError {
        (self.status, Json(self.inner)).into_response()
    }
 }
+
+pub fn db_failure<T>(err: CredentialProxyError, uuid: Uuid) -> Result<T, RequestError> {
+    warn!("db failure: {err}");
+    Err(RequestError::new_with_uuid(
+        format!("oh no, something went wrong {err}"),
+        uuid,
+        StatusCode::INTERNAL_SERVER_ERROR,
+    ))
+}
@@ -0,0 +1,13 @@
+// Copyright 2025 Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: GPL-3.0-only
+
+pub mod deposits_buffer;
+pub mod error;
+pub mod helpers;
+pub mod http_helpers;
+pub mod nym_api_helpers;
+pub mod quorum_checker;
+pub mod shared_state;
+pub mod storage;
+pub mod ticketbook_manager;
+pub mod webhook;
@@ -6,22 +6,20 @@

 use crate::error::CredentialProxyError;
 use futures::{stream, StreamExt};
+use nym_cache::CachedImmutableItems;
 use nym_credentials::ecash::utils::{cred_exp_date, ecash_today, EcashTime};
 use nym_validator_client::nym_api::EpochId;
 use nym_validator_client::nyxd::contract_traits::dkg_query_client::Epoch;
 use nym_validator_client::EcashApiClient;
 use std::cmp::min;
-use std::collections::HashMap;
 use std::future::Future;
-use std::hash::Hash;
-use std::ops::Deref;
 use time::{Date, OffsetDateTime};
-use tokio::sync::{Mutex, RwLock, RwLockReadGuard};
+use tokio::sync::Mutex;
 use tracing::warn;

-pub(crate) struct CachedEpoch {
+pub struct CachedEpoch {
    valid_until: OffsetDateTime,
-    pub(crate) current_epoch: Epoch,
+    pub current_epoch: Epoch,
 }

 impl Default for CachedEpoch {
@@ -34,11 +32,11 @@ impl Default for CachedEpoch {
 }

 impl CachedEpoch {
-    pub(crate) fn is_valid(&self) -> bool {
+    pub fn is_valid(&self) -> bool {
        self.valid_until > OffsetDateTime::now_utc()
    }

-    pub(crate) fn update(&mut self, epoch: Epoch) {
+    pub fn update(&mut self, epoch: Epoch) {
        let now = OffsetDateTime::now_utc();

        let validity_duration = if let Some(epoch_finish) = epoch.deadline {
@@ -57,81 +55,10 @@ impl CachedEpoch {
    }
 }

-// a map of items that never change for given key
-pub(crate) struct CachedImmutableItems<K, V> {
-    // I wonder if there's a more efficient structure with OnceLock or OnceCell or something
-    inner: RwLock<HashMap<K, V>>,
-}
-
 // an item that stays constant throughout given epoch
-pub(crate) type CachedImmutableEpochItem<T> = CachedImmutableItems<EpochId, T>;
+pub type CachedImmutableEpochItem<T> = CachedImmutableItems<EpochId, T>;

-impl<K, V> Default for CachedImmutableItems<K, V> {
-    fn default() -> Self {
-        CachedImmutableItems {
-            inner: RwLock::new(HashMap::new()),
-        }
-    }
-}
-
-impl<K, V> Deref for CachedImmutableItems<K, V> {
-    type Target = RwLock<HashMap<K, V>>;
-
-    fn deref(&self) -> &Self::Target {
-        &self.inner
-    }
-}
-
-impl<K, V> CachedImmutableItems<K, V>
-where
-    K: Eq + Hash,
-{
-    pub(crate) async fn get_or_init<F, U, E>(
-        &self,
-        key: K,
-        f: F,
-    ) -> Result<RwLockReadGuard<'_, V>, E>
-    where
-        F: FnOnce() -> U,
-        U: Future<Output = Result<V, E>>,
-        K: Clone,
-    {
-        // 1. see if we already have the item cached
-        let guard = self.inner.read().await;
-        if let Ok(item) = RwLockReadGuard::try_map(guard, |map| map.get(&key)) {
-            return Ok(item);
-        }
-
-        // 2. attempt to retrieve (and cache) it
-        let mut write_guard = self.inner.write().await;
-
-        // see if another task has already set the item whilst we were waiting for the lock
-        if write_guard.get(&key).is_some() {
-            let read_guard = write_guard.downgrade();
-
-            // SAFETY: we just checked the entry exists and we never dropped the guard
-            #[allow(clippy::unwrap_used)]
-            return Ok(RwLockReadGuard::map(read_guard, |map| {
-                map.get(&key).unwrap()
-            }));
-        }
-
-        let init = f().await?;
-        write_guard.insert(key.clone(), init);
-
-        let guard = write_guard.downgrade();
-
-        // SAFETY:
-        // we just inserted the entry into the map while NEVER dropping the lock (only downgraded it)
-        // so it MUST exist and thus the unwrap is fine
-        #[allow(clippy::unwrap_used)]
-        Ok(RwLockReadGuard::map(guard, |map| map.get(&key).unwrap()))
-    }
-}
-
-pub(crate) fn ensure_sane_expiration_date(
-    expiration_date: Date,
-) -> Result<(), CredentialProxyError> {
+pub fn ensure_sane_expiration_date(expiration_date: Date) -> Result<(), CredentialProxyError> {
    let today = ecash_today();

    if expiration_date < today.date() {
@@ -146,7 +73,7 @@ pub(crate) fn ensure_sane_expiration_date(
    Ok(())
 }

-pub(crate) async fn query_all_threshold_apis<F, T, U>(
+pub async fn query_all_threshold_apis<F, T, U>(
    all_apis: Vec<EcashApiClient>,
    threshold: u64,
    f: F,
@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: GPL-3.0-only

 use crate::error::CredentialProxyError;
-use crate::http::state::ChainClient;
+use crate::shared_state::nyxd_client::ChainClient;
 use nym_ecash_signer_check::{check_known_dealers, dkg_details_with_client};
 use std::ops::Deref;
 use std::sync::atomic::{AtomicBool, Ordering};
@@ -12,17 +12,17 @@ use tokio_util::sync::CancellationToken;
 use tracing::{error, info, warn};

 #[derive(Clone)]
-pub(crate) struct QuorumState {
+pub struct QuorumState {
    available: Arc<AtomicBool>,
 }

 impl QuorumState {
-    pub(crate) fn available(&self) -> bool {
+    pub fn available(&self) -> bool {
        self.available.load(Ordering::Acquire)
    }
 }

-pub(crate) struct QuorumStateChecker {
+pub struct QuorumStateChecker {
    client: ChainClient,
    cancellation_token: CancellationToken,
    check_interval: Duration,
@@ -0,0 +1,376 @@
+// Copyright 2025 Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: GPL-3.0-only
+
+use crate::error::CredentialProxyError;
+use crate::nym_api_helpers::{
+    ensure_sane_expiration_date, query_all_threshold_apis, CachedEpoch, CachedImmutableEpochItem,
+};
+use crate::quorum_checker::QuorumState;
+use crate::shared_state::nyxd_client::ChainClient;
+use crate::shared_state::required_deposit_cache::RequiredDepositCache;
+use crate::storage::traits::GlobalEcashDataCache;
+use nym_cache::CachedImmutableItems;
+use nym_compact_ecash::scheme::coin_indices_signatures::aggregate_annotated_indices_signatures;
+use nym_compact_ecash::scheme::expiration_date_signatures::aggregate_annotated_expiration_signatures;
+use nym_credentials::ecash::utils::EcashTime;
+use nym_credentials::{
+    AggregatedCoinIndicesSignatures, AggregatedExpirationDateSignatures, EpochVerificationKey,
+};
+use nym_validator_client::client::NymApiClientExt;
+use nym_validator_client::coconut::EcashApiError;
+use nym_validator_client::nym_api::EpochId;
+use nym_validator_client::nyxd::contract_traits::dkg_query_client::Epoch;
+use nym_validator_client::nyxd::contract_traits::{DkgQueryClient, PagedDkgQueryClient};
+use nym_validator_client::nyxd::Coin;
+use nym_validator_client::EcashApiClient;
+use time::{Date, OffsetDateTime};
+use tokio::sync::{RwLock, RwLockReadGuard};
+use tracing::info;
+
+pub use nym_compact_ecash::scheme::coin_indices_signatures::CoinIndexSignatureShare;
+pub use nym_compact_ecash::scheme::expiration_date_signatures::ExpirationDateSignatureShare;
+pub use nym_compact_ecash::VerificationKeyAuth;
+pub use nym_credentials::{IssuanceTicketBook, IssuedTicketBook};
+pub use nym_credentials_interface::{TicketType, TicketTypeRepr};
+
+pub struct EcashState {
+    pub required_deposit_cache: RequiredDepositCache,
+
+    pub quorum_state: QuorumState,
+
+    pub cached_epoch: RwLock<CachedEpoch>,
+
+    pub master_verification_key: CachedImmutableEpochItem<VerificationKeyAuth>,
+
+    pub threshold_values: CachedImmutableEpochItem<u64>,
+
+    pub epoch_clients: CachedImmutableEpochItem<Vec<EcashApiClient>>,
+
+    pub coin_index_signatures: CachedImmutableEpochItem<AggregatedCoinIndicesSignatures>,
+
+    pub expiration_date_signatures:
+        CachedImmutableItems<(EpochId, Date), AggregatedExpirationDateSignatures>,
+}
+
+impl EcashState {
+    pub fn new(
+        required_deposit_cache: RequiredDepositCache,
+        quorum_state: QuorumState,
+    ) -> EcashState {
+        EcashState {
+            required_deposit_cache,
+            quorum_state,
+            cached_epoch: Default::default(),
+            master_verification_key: Default::default(),
+            threshold_values: Default::default(),
+            epoch_clients: Default::default(),
+            coin_index_signatures: Default::default(),
+            expiration_date_signatures: Default::default(),
+        }
+    }
+
+    pub async fn ensure_credentials_issuable(
+        &self,
+        client: &ChainClient,
+    ) -> Result<(), CredentialProxyError> {
+        let epoch = self.current_epoch(client).await?;
+
+        if epoch.state.is_final() {
+            Ok(())
+        } else if let Some(final_timestamp) = epoch.final_timestamp_secs() {
+            // SAFETY: the timestamp values in our DKG contract should be valid timestamps,
+            // otherwise it means the chain is seriously misbehaving
+            #[allow(clippy::unwrap_used)]
+            let finish_dt = OffsetDateTime::from_unix_timestamp(final_timestamp as i64).unwrap();
+
+            Err(CredentialProxyError::CredentialsNotYetIssuable {
+                availability: finish_dt,
+            })
+        } else if epoch.state.is_waiting_initialisation() {
+            Err(CredentialProxyError::UninitialisedDkg)
+        } else {
+            Err(CredentialProxyError::UnknownEcashFailure)
+        }
+    }
+
+    pub async fn deposit_amount(&self, client: &ChainClient) -> Result<Coin, CredentialProxyError> {
+        self.required_deposit_cache.get_or_update(client).await
+    }
+
+    pub async fn ecash_clients(
+        &self,
+        client: &ChainClient,
+        epoch_id: EpochId,
+    ) -> Result<RwLockReadGuard<'_, Vec<EcashApiClient>>, CredentialProxyError> {
+        self.epoch_clients
+            .get_or_init(epoch_id, || async {
+                Ok(client
+                    .query_chain()
+                    .await
+                    .get_all_verification_key_shares(epoch_id)
+                    .await?
+                    .into_iter()
+                    .map(TryInto::try_into)
+                    .collect::<anyhow::Result<Vec<_>, EcashApiError>>()?)
+            })
+            .await
+    }
+
+    pub async fn current_epoch(&self, client: &ChainClient) -> Result<Epoch, CredentialProxyError> {
+        let read_guard = self.cached_epoch.read().await;
+        if read_guard.is_valid() {
+            return Ok(read_guard.current_epoch);
+        }
+
+        // update cache
+        drop(read_guard);
+        let mut write_guard = self.cached_epoch.write().await;
+        let epoch = client.query_chain().await.get_current_epoch().await?;
+
+        write_guard.update(epoch);
+        Ok(epoch)
+    }
+
+    pub async fn current_epoch_id(
+        &self,
+        client: &ChainClient,
+    ) -> Result<EpochId, CredentialProxyError> {
+        let read_guard = self.cached_epoch.read().await;
+        if read_guard.is_valid() {
+            return Ok(read_guard.current_epoch.epoch_id);
+        }
+
+        // update cache
+        drop(read_guard);
+        let mut write_guard = self.cached_epoch.write().await;
+        let epoch = client.query_chain().await.get_current_epoch().await?;
+
+        write_guard.update(epoch);
+        Ok(epoch.epoch_id)
+    }
+
+    pub async fn master_verification_key<S>(
+        &self,
+        client: &ChainClient,
+        storage: &S,
+        epoch_id: Option<EpochId>,
+    ) -> Result<RwLockReadGuard<'_, VerificationKeyAuth>, CredentialProxyError>
+    where
+        S: GlobalEcashDataCache,
+    {
+        let epoch_id = match epoch_id {
+            Some(id) => id,
+            None => self.current_epoch_id(client).await?,
+        };
+
+        self.master_verification_key
+            .get_or_init(epoch_id, || async {
+                // 1. check the storage
+                if let Some(stored) = storage.get_master_verification_key(epoch_id).await? {
+                    return Ok(stored.key);
+                }
+
+                info!("attempting to establish master verification key for epoch {epoch_id}...");
+
+                // 2. perform actual aggregation
+                let all_apis = self.ecash_clients(client, epoch_id).await?;
+                let threshold = self.ecash_threshold(client, epoch_id).await?;
+
+                if all_apis.len() < threshold as usize {
+                    return Err(CredentialProxyError::InsufficientNumberOfSigners {
+                        threshold,
+                        available: all_apis.len(),
+                    });
+                }
+
+                let master_key = nym_credentials::aggregate_verification_keys(&all_apis)?;
+
+                let epoch = EpochVerificationKey {
+                    epoch_id,
+                    key: master_key,
+                };
+
+                // 3. save the key in the storage for when we reboot
+                storage.insert_master_verification_key(&epoch).await?;
+
+                Ok(epoch.key)
+            })
+            .await
+    }
+
+    pub async fn master_coin_index_signatures<S>(
+        &self,
+        client: &ChainClient,
+        storage: &S,
+        epoch_id: Option<EpochId>,
+    ) -> Result<RwLockReadGuard<'_, AggregatedCoinIndicesSignatures>, CredentialProxyError>
+    where
+        S: GlobalEcashDataCache,
+    {
+        let epoch_id = match epoch_id {
+            Some(id) => id,
+            None => self.current_epoch_id(client).await?,
+        };
+
+        self.coin_index_signatures
+            .get_or_init(epoch_id, || async {
+                // 1. check the storage
+                if let Some(master_sigs) =
+                    storage.get_master_coin_index_signatures(epoch_id).await?
+                {
+                    return Ok(master_sigs);
+                }
+
+                info!(
+                    "attempting to establish master coin index signatures for epoch {epoch_id}..."
+                );
+
+                // 2. go around APIs and attempt to aggregate the data
+                let master_vk = self
+                    .master_verification_key(client, storage, Some(epoch_id))
+                    .await?;
+                let all_apis = self.ecash_clients(client, epoch_id).await?;
+                let threshold = self.ecash_threshold(client, epoch_id).await?;
+
+                let get_partial_signatures = |api: EcashApiClient| async {
+                    // move the api into the closure
+                    let api = api;
+                    let node_index = api.node_id;
+                    let partial_vk = api.verification_key;
+
+                    let partial = api
+                        .api_client
+                        .partial_coin_indices_signatures(Some(epoch_id))
+                        .await?
+                        .signatures;
+                    Ok(CoinIndexSignatureShare {
+                        index: node_index,
+                        key: partial_vk,
+                        signatures: partial,
+                    })
+                };
+
+                let shares =
+                    query_all_threshold_apis(all_apis.clone(), threshold, get_partial_signatures)
+                        .await?;
+
+                let aggregated = aggregate_annotated_indices_signatures(
+                    nym_credentials_interface::ecash_parameters(),
+                    &master_vk,
+                    &shares,
+                )?;
+
+                let sigs = AggregatedCoinIndicesSignatures {
+                    epoch_id,
+                    signatures: aggregated,
+                };
+
+                // 3. save the signatures in the storage for when we reboot
+                storage.insert_master_coin_index_signatures(&sigs).await?;
+
+                Ok(sigs)
+            })
+            .await
+    }
+
+    pub async fn master_expiration_date_signatures<S>(
+        &self,
+        client: &ChainClient,
+        storage: &S,
+        epoch_id: EpochId,
+        expiration_date: Date,
+    ) -> Result<RwLockReadGuard<'_, AggregatedExpirationDateSignatures>, CredentialProxyError>
+    where
+        S: GlobalEcashDataCache,
+    {
+        self
+            .expiration_date_signatures
+            .get_or_init((epoch_id, expiration_date), || async {
+                // 1. sanity check to see if the expiration_date is not nonsense
+                ensure_sane_expiration_date(expiration_date)?;
+
+                // 2. check the storage
+                if let Some(master_sigs) = storage
+                    .get_master_expiration_date_signatures(expiration_date, epoch_id)
+                    .await?
+                {
+                    return Ok(master_sigs);
+                }
+
+
+                info!(
+                    "attempting to establish master expiration date signatures for {expiration_date} and epoch {epoch_id}..."
+                );
+
+                // 3. go around APIs and attempt to aggregate the data
+                let epoch_id = self.current_epoch_id(client).await?;
+                let master_vk = self.master_verification_key(client, storage, Some(epoch_id)).await?;
+                let all_apis = self.ecash_clients(client, epoch_id).await?;
+                let threshold = self.ecash_threshold(client, epoch_id).await?;
+
+                let get_partial_signatures = |api: EcashApiClient| async {
+                    // move the api into the closure
+                    let api = api;
+                    let node_index = api.node_id;
+                    let partial_vk = api.verification_key;
+
+                    let partial = api
+                        .api_client
+                        .partial_expiration_date_signatures(Some(expiration_date), Some(epoch_id))
+                        .await?
+                        .signatures;
+                    Ok(ExpirationDateSignatureShare {
+                        index: node_index,
+                        key: partial_vk,
+                        signatures: partial,
+                    })
+                };
+
+                let shares =
+                    query_all_threshold_apis(all_apis.clone(), threshold, get_partial_signatures)
+                        .await?;
+
+                let aggregated = aggregate_annotated_expiration_signatures(
+                    &master_vk,
+                    expiration_date.ecash_unix_timestamp(),
+                    &shares,
+                )?;
+
+                let sigs = AggregatedExpirationDateSignatures {
+                    epoch_id,
+                    expiration_date,
+                    signatures: aggregated,
+                };
+
+                // 4. save the signatures in the storage for when we reboot
+                storage
+                    .insert_master_expiration_date_signatures(&sigs)
+                    .await?;
+
+                Ok(sigs)
+            })
+            .await
+    }
+
+    pub async fn ecash_threshold(
+        &self,
+        client: &ChainClient,
+        epoch_id: EpochId,
+    ) -> Result<u64, CredentialProxyError> {
+        self.threshold_values
+            .get_or_init(epoch_id, || async {
+                if let Some(threshold) = client
+                    .query_chain()
+                    .await
+                    .get_epoch_threshold(epoch_id)
+                    .await?
+                {
+                    Ok(threshold)
+                } else {
+                    Err(CredentialProxyError::UnavailableThreshold { epoch_id })
+                }
+            })
+            .await
+            .map(|t| *t)
+    }
+}
@@ -0,0 +1,242 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: GPL-3.0-only
+
+use crate::deposits_buffer::{BufferedDeposit, DepositsBuffer};
+use crate::error::CredentialProxyError;
+use crate::shared_state::ecash_state::EcashState;
+use crate::shared_state::nyxd_client::ChainClient;
+use crate::storage::CredentialProxyStorage;
+use nym_compact_ecash::{Base58, PublicKeyUser, VerificationKeyAuth};
+use nym_credential_proxy_requests::api::v1::ticketbook::models::{
+    AggregatedCoinIndicesSignaturesResponse, AggregatedExpirationDateSignaturesResponse,
+    GlobalDataParams, MasterVerificationKeyResponse,
+};
+use nym_credentials::{AggregatedCoinIndicesSignatures, AggregatedExpirationDateSignatures};
+use nym_ecash_contract_common::deposit::DepositId;
+use nym_validator_client::nym_api::EpochId;
+use nym_validator_client::nyxd::contract_traits::dkg_query_client::Epoch;
+use nym_validator_client::nyxd::Coin;
+use nym_validator_client::EcashApiClient;
+use std::sync::Arc;
+use std::time::Duration;
+use time::{Date, OffsetDateTime};
+use tokio::sync::RwLockReadGuard;
+use tokio::time::Instant;
+use tracing::{debug, error, warn};
+use uuid::Uuid;
+
+pub mod ecash_state;
+pub mod nyxd_client;
+pub mod required_deposit_cache;
+
+#[derive(Clone)]
+pub struct CredentialProxyState {
+    inner: Arc<CredentialProxyStateInner>,
+}
+
+impl CredentialProxyState {
+    pub fn new(
+        storage: CredentialProxyStorage,
+        client: ChainClient,
+        deposits_buffer: DepositsBuffer,
+        ecash_state: EcashState,
+    ) -> Self {
+        CredentialProxyState {
+            inner: Arc::new(CredentialProxyStateInner {
+                storage,
+                client,
+                deposits_buffer,
+                ecash_state,
+            }),
+        }
+    }
+
+    pub fn storage(&self) -> &CredentialProxyStorage {
+        &self.inner.storage
+    }
+
+    pub async fn deposit_amount(&self) -> Result<Coin, CredentialProxyError> {
+        self.ecash_state().deposit_amount(self.client()).await
+    }
+
+    pub fn client(&self) -> &ChainClient {
+        &self.inner.client
+    }
+
+    pub fn deposits_buffer(&self) -> &DepositsBuffer {
+        &self.inner.deposits_buffer
+    }
+
+    pub fn ecash_state(&self) -> &EcashState {
+        &self.inner.ecash_state
+    }
+
+    pub async fn ensure_credentials_issuable(&self) -> Result<(), CredentialProxyError> {
+        self.ecash_state()
+            .ensure_credentials_issuable(self.client())
+            .await
+    }
+
+    pub async fn get_deposit(
+        &self,
+        request_uuid: Uuid,
+        requested_on: OffsetDateTime,
+        client_pubkey: PublicKeyUser,
+    ) -> Result<BufferedDeposit, CredentialProxyError> {
+        let start = Instant::now();
+        let deposit = self
+            .deposits_buffer()
+            .get_valid_deposit(request_uuid, requested_on, client_pubkey)
+            .await;
+
+        let time_taken = start.elapsed();
+        let formatted = humantime::format_duration(time_taken);
+        if time_taken > Duration::from_secs(10) {
+            warn!("attempting to get buffered deposit took {formatted}. perhaps the buffer is too small or the process/chain is overloaded?")
+        } else {
+            debug!("attempting to get buffered deposit took {formatted}")
+        };
+
+        deposit
+    }
+
+    pub async fn insert_deposit_usage_error(&self, deposit_id: DepositId, error: String) {
+        if let Err(err) = self
+            .storage()
+            .insert_deposit_usage_error(deposit_id, error)
+            .await
+        {
+            error!("failed to insert information about deposit (id: {deposit_id}) usage failure: {err}")
+        }
+    }
+
+    pub async fn current_epoch_id(&self) -> Result<EpochId, CredentialProxyError> {
+        self.ecash_state().current_epoch_id(self.client()).await
+    }
+
+    pub async fn current_epoch(&self) -> Result<Epoch, CredentialProxyError> {
+        self.ecash_state().current_epoch(self.client()).await
+    }
+
+    pub async fn global_data(
+        &self,
+        global_data: GlobalDataParams,
+        epoch_id: EpochId,
+        expiration_date: Date,
+    ) -> Result<
+        (
+            Option<MasterVerificationKeyResponse>,
+            Option<AggregatedExpirationDateSignaturesResponse>,
+            Option<AggregatedCoinIndicesSignaturesResponse>,
+        ),
+        CredentialProxyError,
+    > {
+        let master_verification_key = if global_data.include_master_verification_key {
+            debug!("including master verification key in the response");
+            Some(
+                self.master_verification_key(Some(epoch_id))
+                    .await
+                    .map(|key| MasterVerificationKeyResponse {
+                        epoch_id,
+                        bs58_encoded_key: key.to_bs58(),
+                    })
+                    .inspect_err(|err| warn!("request failure: {err}"))?,
+            )
+        } else {
+            None
+        };
+
+        let aggregated_expiration_date_signatures =
+            if global_data.include_expiration_date_signatures {
+                debug!("including expiration date signatures in the response");
+                Some(
+                    self.master_expiration_date_signatures(epoch_id, expiration_date)
+                        .await
+                        .map(|signatures| AggregatedExpirationDateSignaturesResponse {
+                            signatures: signatures.clone(),
+                        })
+                        .inspect_err(|err| warn!("request failure: {err}"))?,
+                )
+            } else {
+                None
+            };
+
+        let aggregated_coin_index_signatures = if global_data.include_coin_index_signatures {
+            debug!("including coin index signatures in the response");
+            Some(
+                self.master_coin_index_signatures(Some(epoch_id))
+                    .await
+                    .map(|signatures| AggregatedCoinIndicesSignaturesResponse {
+                        signatures: signatures.clone(),
+                    })
+                    .inspect_err(|err| warn!("request failure: {err}"))?,
+            )
+        } else {
+            None
+        };
+
+        Ok((
+            master_verification_key,
+            aggregated_expiration_date_signatures,
+            aggregated_coin_index_signatures,
+        ))
+    }
+
+    pub async fn master_verification_key(
+        &self,
+        epoch_id: Option<EpochId>,
+    ) -> Result<RwLockReadGuard<'_, VerificationKeyAuth>, CredentialProxyError> {
+        self.ecash_state()
+            .master_verification_key(self.client(), self.storage(), epoch_id)
+            .await
+    }
+
+    pub async fn master_coin_index_signatures(
+        &self,
+        epoch_id: Option<EpochId>,
+    ) -> Result<RwLockReadGuard<'_, AggregatedCoinIndicesSignatures>, CredentialProxyError> {
+        self.ecash_state()
+            .master_coin_index_signatures(self.client(), self.storage(), epoch_id)
+            .await
+    }
+
+    pub async fn master_expiration_date_signatures(
+        &self,
+        epoch_id: EpochId,
+        expiration_date: Date,
+    ) -> Result<RwLockReadGuard<'_, AggregatedExpirationDateSignatures>, CredentialProxyError> {
+        self.ecash_state()
+            .master_expiration_date_signatures(
+                self.client(),
+                self.storage(),
+                epoch_id,
+                expiration_date,
+            )
+            .await
+    }
+
+    pub async fn ecash_clients(
+        &self,
+        epoch_id: EpochId,
+    ) -> Result<RwLockReadGuard<'_, Vec<EcashApiClient>>, CredentialProxyError> {
+        self.ecash_state()
+            .ecash_clients(self.client(), epoch_id)
+            .await
+    }
+
+    pub async fn ecash_threshold(&self, epoch_id: EpochId) -> Result<u64, CredentialProxyError> {
+        self.ecash_state()
+            .ecash_threshold(self.client(), epoch_id)
+            .await
+    }
+}
+
+struct CredentialProxyStateInner {
+    storage: CredentialProxyStorage,
+
+    client: ChainClient,
+
+    deposits_buffer: DepositsBuffer,
+
+    ecash_state: EcashState,
+}
@@ -0,0 +1,127 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::error::CredentialProxyError;
+use crate::helpers::LockTimer;
+use nym_ecash_contract_common::msg::ExecuteMsg;
+use nym_validator_client::nyxd::contract_traits::NymContractsProvider;
+use nym_validator_client::nyxd::cosmwasm_client::types::ExecuteResult;
+use nym_validator_client::nyxd::{Coin, Config, CosmWasmClient, NyxdClient};
+use nym_validator_client::{nyxd, DirectSigningHttpRpcNyxdClient};
+use std::ops::Deref;
+use std::sync::Arc;
+use std::time::Duration;
+use tokio::sync::{RwLock, RwLockReadGuard, RwLockWriteGuard};
+use tracing::{instrument, warn};
+
+#[derive(Clone)]
+pub struct ChainClient(Arc<RwLock<DirectSigningHttpRpcNyxdClient>>);
+
+impl ChainClient {
+    pub fn new(mnemonic: bip39::Mnemonic) -> Result<Self, CredentialProxyError> {
+        let network_details = nym_network_defaults::NymNetworkDetails::new_from_env();
+        let client_config = nyxd::Config::try_from_nym_network_details(&network_details)?;
+
+        let nyxd_url = network_details
+            .endpoints
+            .first()
+            .ok_or_else(|| CredentialProxyError::NoNyxEndpointsAvailable)?
+            .nyxd_url
+            .as_str();
+
+        Self::new_with_config(client_config, nyxd_url, mnemonic)
+    }
+
+    pub fn new_with_config(
+        client_config: Config,
+        nyxd_url: &str,
+        mnemonic: bip39::Mnemonic,
+    ) -> Result<Self, CredentialProxyError> {
+        let client = NyxdClient::connect_with_mnemonic(client_config, nyxd_url, mnemonic)?;
+
+        if client.ecash_contract_address().is_none() {
+            return Err(CredentialProxyError::UnavailableEcashContract);
+        }
+
+        if client.dkg_contract_address().is_none() {
+            return Err(CredentialProxyError::UnavailableDKGContract);
+        }
+
+        Ok(ChainClient(Arc::new(RwLock::new(client))))
+    }
+
+    pub async fn query_chain(&self) -> ChainReadPermit<'_> {
+        let _acquire_timer = LockTimer::new("acquire chain query permit");
+        self.0.read().await
+    }
+
+    pub async fn start_chain_tx(&self) -> ChainWritePermit<'_> {
+        let _acquire_timer = LockTimer::new("acquire exclusive chain write permit");
+
+        ChainWritePermit {
+            lock_timer: LockTimer::new("exclusive chain access permit"),
+            inner: self.0.write().await,
+        }
+    }
+}
+
+pub type ChainReadPermit<'a> = RwLockReadGuard<'a, DirectSigningHttpRpcNyxdClient>;
+
+// explicitly wrap the WriteGuard for extra information regarding time taken
+pub struct ChainWritePermit<'a> {
+    // it's not really dead, we only care about it being dropped
+    #[allow(dead_code)]
+    lock_timer: LockTimer,
+    inner: RwLockWriteGuard<'a, DirectSigningHttpRpcNyxdClient>,
+}
+
+impl ChainWritePermit<'_> {
+    #[instrument(skip(self, memo, info), err(Display))]
+    pub async fn make_deposits(
+        self,
+        memo: String,
+        info: Vec<(String, Coin)>,
+    ) -> Result<ExecuteResult, CredentialProxyError> {
+        let address = self.inner.address();
+        let starting_sequence = self.inner.get_sequence(&address).await?.sequence;
+
+        let ecash_contract = self
+            .inner
+            .ecash_contract_address()
+            .ok_or(CredentialProxyError::UnavailableEcashContract)?;
+        let deposit_messages = info
+            .into_iter()
+            .map(|(identity_key, amount)| {
+                (
+                    ExecuteMsg::DepositTicketBookFunds { identity_key },
+                    vec![amount],
+                )
+            })
+            .collect::<Vec<_>>();
+
+        let res = self
+            .inner
+            .execute_multiple(ecash_contract, deposit_messages, None, memo)
+            .await?;
+
+        loop {
+            let updated_sequence = self.inner.get_sequence(&address).await?.sequence;
+
+            if updated_sequence > starting_sequence {
+                break;
+            }
+            warn!("wrong sequence number... waiting before releasing chain lock");
+            tokio::time::sleep(Duration::from_millis(50)).await;
+        }
+
+        Ok(res)
+    }
+}
+
+impl Deref for ChainWritePermit<'_> {
+    type Target = DirectSigningHttpRpcNyxdClient;
+
+    fn deref(&self) -> &Self::Target {
+        self.inner.deref()
+    }
+}
@@ -2,14 +2,14 @@
 // SPDX-License-Identifier: GPL-3.0-only

 use crate::error::CredentialProxyError;
-use crate::http::state::ChainClient;
+use crate::shared_state::nyxd_client::ChainClient;
 use nym_validator_client::nyxd::contract_traits::EcashQueryClient;
 use nym_validator_client::nyxd::Coin;
 use std::sync::Arc;
 use time::OffsetDateTime;
 use tokio::sync::RwLock;

-pub(crate) struct CachedDeposit {
+pub struct CachedDeposit {
    valid_until: OffsetDateTime,
    required_amount: Coin,
 }
@@ -40,12 +40,12 @@ impl Default for CachedDeposit {
 }

 #[derive(Clone, Default)]
-pub(crate) struct RequiredDepositCache {
+pub struct RequiredDepositCache {
    inner: Arc<RwLock<CachedDeposit>>,
 }

 impl RequiredDepositCache {
-    pub(crate) async fn get_or_update(
+    pub async fn get_or_update(
        &self,
        chain_client: &ChainClient,
    ) -> Result<Coin, CredentialProxyError> {
@@ -1,7 +1,6 @@
 // Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: GPL-3.0-only

-use crate::credentials::ticketbook::NodeId;
 use crate::deposits_buffer::helpers::{BufferedDeposit, PerformedDeposits};
 use crate::error::CredentialProxyError;
 use crate::storage::manager::SqliteStorageManager;
@@ -26,6 +25,11 @@ use uuid::Uuid;

 mod manager;
 pub mod models;
+pub(crate) mod pruner;
+pub mod traits;
+
+// TODO: proper import
+type NodeId = u64;

 #[derive(Clone)]
 pub struct CredentialProxyStorage {
@@ -74,7 +78,7 @@ impl CredentialProxyStorage {
    }

    #[allow(dead_code)]
-    pub(crate) async fn load_blinded_shares_status_by_shares_id(
+    pub async fn load_blinded_shares_status_by_shares_id(
        &self,
        id: i64,
    ) -> Result<Option<BlindedShares>, CredentialProxyError> {
@@ -84,7 +88,7 @@ impl CredentialProxyStorage {
            .await?)
    }

-    pub(crate) async fn load_wallet_shares_by_shares_id(
+    pub async fn load_wallet_shares_by_shares_id(
        &self,
        id: i64,
    ) -> Result<Vec<MinimalWalletShare>, CredentialProxyError> {
@@ -94,7 +98,7 @@ impl CredentialProxyStorage {
            .await?)
    }

-    pub(crate) async fn load_shares_error_by_shares_id(
+    pub async fn load_shares_error_by_shares_id(
        &self,
        id: i64,
    ) -> Result<Option<String>, CredentialProxyError> {
@@ -105,7 +109,7 @@ impl CredentialProxyStorage {
    }

    #[allow(dead_code)]
-    pub(crate) async fn load_blinded_shares_status_by_device_and_credential_id(
+    pub async fn load_blinded_shares_status_by_device_and_credential_id(
        &self,
        device_id: &str,
        credential_id: &str,
@@ -116,7 +120,7 @@ impl CredentialProxyStorage {
            .await?)
    }

-    pub(crate) async fn load_wallet_shares_by_device_and_credential_id(
+    pub async fn load_wallet_shares_by_device_and_credential_id(
        &self,
        device_id: &str,
        credential_id: &str,
@@ -127,7 +131,7 @@ impl CredentialProxyStorage {
            .await?)
    }

-    pub(crate) async fn load_shares_error_by_device_and_credential_id(
+    pub async fn load_shares_error_by_device_and_credential_id(
        &self,
        device_id: &str,
        credential_id: &str,
@@ -138,7 +142,7 @@ impl CredentialProxyStorage {
            .await?)
    }

-    pub(crate) async fn insert_new_pending_async_shares_request(
+    pub async fn insert_new_pending_async_shares_request(
        &self,
        request: Uuid,
        device_id: &str,
@@ -150,7 +154,7 @@ impl CredentialProxyStorage {
            .await?)
    }

-    pub(crate) async fn update_pending_async_blinded_shares_issued(
+    pub async fn update_pending_async_blinded_shares_issued(
        &self,
        available_shares: usize,
        device_id: &str,
@@ -166,7 +170,7 @@ impl CredentialProxyStorage {
            .await?)
    }

-    pub(crate) async fn update_pending_async_blinded_shares_error(
+    pub async fn update_pending_async_blinded_shares_error(
        &self,
        available_shares: usize,
        device_id: &str,
@@ -184,7 +188,7 @@ impl CredentialProxyStorage {
            .await?)
    }

-    pub(crate) async fn prune_old_blinded_shares(&self) -> Result<(), CredentialProxyError> {
+    pub async fn prune_old_blinded_shares(&self) -> Result<(), CredentialProxyError> {
        let max_age = OffsetDateTime::now_utc() - time::Duration::days(31);

        self.storage_manager
@@ -199,7 +203,7 @@ impl CredentialProxyStorage {
        Ok(())
    }

-    pub(crate) async fn insert_new_deposits(
+    pub async fn insert_new_deposits(
        &self,
        deposits: &PerformedDeposits,
    ) -> Result<(), CredentialProxyError> {
@@ -211,9 +215,7 @@ impl CredentialProxyStorage {
        Ok(())
    }

-    pub(crate) async fn load_unused_deposits(
-        &self,
-    ) -> Result<Vec<BufferedDeposit>, CredentialProxyError> {
+    pub async fn load_unused_deposits(&self) -> Result<Vec<BufferedDeposit>, CredentialProxyError> {
        self.storage_manager
            .load_unused_deposits()
            .await?
@@ -222,7 +224,7 @@ impl CredentialProxyStorage {
            .collect()
    }

-    pub(crate) async fn insert_deposit_usage(
+    pub async fn insert_deposit_usage(
        &self,
        deposit_id: DepositId,
        requested_on: OffsetDateTime,
@@ -240,7 +242,7 @@ impl CredentialProxyStorage {
        Ok(())
    }

-    pub(crate) async fn insert_deposit_usage_error(
+    pub async fn insert_deposit_usage_error(
        &self,
        deposit_id: DepositId,
        error: String,
@@ -251,7 +253,7 @@ impl CredentialProxyStorage {
        Ok(())
    }

-    pub(crate) async fn insert_partial_wallet_share(
+    pub async fn insert_partial_wallet_share(
        &self,
        deposit_id: DepositId,
        epoch_id: EpochId,
@@ -291,7 +293,7 @@ impl CredentialProxyStorage {
        Ok(())
    }

-    pub(crate) async fn get_master_verification_key(
+    pub async fn get_master_verification_key(
        &self,
        epoch_id: EpochId,
    ) -> Result<Option<EpochVerificationKey>, CredentialProxyError> {
@@ -309,7 +311,7 @@ impl CredentialProxyStorage {
        Ok(Some(deserialised))
    }

-    pub(crate) async fn insert_master_verification_key(
+    pub async fn insert_master_verification_key(
        &self,
        key: &EpochVerificationKey,
    ) -> Result<(), CredentialProxyError> {
@@ -320,7 +322,7 @@ impl CredentialProxyStorage {
            .await?)
    }

-    pub(crate) async fn get_master_coin_index_signatures(
+    pub async fn get_master_coin_index_signatures(
        &self,
        epoch_id: EpochId,
    ) -> Result<Option<AggregatedCoinIndicesSignatures>, CredentialProxyError> {
@@ -340,7 +342,7 @@ impl CredentialProxyStorage {
        Ok(Some(deserialised))
    }

-    pub(crate) async fn insert_master_coin_index_signatures(
+    pub async fn insert_master_coin_index_signatures(
        &self,
        signatures: &AggregatedCoinIndicesSignatures,
    ) -> Result<(), CredentialProxyError> {
@@ -355,7 +357,7 @@ impl CredentialProxyStorage {
        Ok(())
    }

-    pub(crate) async fn get_master_expiration_date_signatures(
+    pub async fn get_master_expiration_date_signatures(
        &self,
        expiration_date: Date,
        epoch_id: EpochId,
@@ -376,7 +378,7 @@ impl CredentialProxyStorage {
        Ok(Some(deserialised))
    }

-    pub(crate) async fn insert_master_expiration_date_signatures(
+    pub async fn insert_master_expiration_date_signatures(
        &self,
        signatures: &AggregatedExpirationDateSignatures,
    ) -> Result<(), CredentialProxyError> {
@@ -398,7 +400,7 @@ impl CredentialProxyStorage {
 #[cfg(test)]
 mod tests {
    use super::*;
-    use crate::http::helpers;
+    use crate::helpers::random_uuid;
    use crate::storage::models::BlindedSharesStatus;
    use nym_compact_ecash::scheme::keygen::KeyPairUser;
    use nym_crypto::asymmetric::ed25519;
@@ -480,7 +482,7 @@ mod tests {
    async fn test_add() -> anyhow::Result<()> {
        let storage = get_storage().await?;

-        let dummy_uuid = helpers::random_uuid();
+        let dummy_uuid = random_uuid();
        println!("🚀 insert_pending_blinded_share...");

        storage.insert_dummy_used_deposit(dummy_uuid).await?;
@@ -1,5 +1,5 @@
-// Copyright 2024 Nym Technologies SA <contact@nymtech.net>
-// SPDX-License-Identifier: GPL-3.0-only
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0

 use crate::storage::CredentialProxyStorage;
 use tokio_util::sync::CancellationToken;
@@ -0,0 +1,94 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: GPL-3.0-only
+
+use crate::error::CredentialProxyError;
+use crate::storage::CredentialProxyStorage;
+use nym_validator_client::nym_api::EpochId;
+use time::Date;
+
+pub use nym_credentials::ecash::bandwidth::serialiser::VersionedSerialise;
+pub use nym_credentials::{
+    AggregatedCoinIndicesSignatures, AggregatedExpirationDateSignatures, EpochVerificationKey,
+};
+
+// we use it in our code so it's fine
+#[allow(async_fn_in_trait)]
+pub trait GlobalEcashDataCache {
+    async fn get_master_verification_key(
+        &self,
+        epoch_id: EpochId,
+    ) -> Result<Option<EpochVerificationKey>, CredentialProxyError>;
+
+    async fn insert_master_verification_key(
+        &self,
+        key: &EpochVerificationKey,
+    ) -> Result<(), CredentialProxyError>;
+
+    async fn get_master_coin_index_signatures(
+        &self,
+        epoch_id: EpochId,
+    ) -> Result<Option<AggregatedCoinIndicesSignatures>, CredentialProxyError>;
+
+    async fn insert_master_coin_index_signatures(
+        &self,
+        signatures: &AggregatedCoinIndicesSignatures,
+    ) -> Result<(), CredentialProxyError>;
+
+    async fn get_master_expiration_date_signatures(
+        &self,
+        expiration_date: Date,
+        epoch_id: EpochId,
+    ) -> Result<Option<AggregatedExpirationDateSignatures>, CredentialProxyError>;
+
+    async fn insert_master_expiration_date_signatures(
+        &self,
+        signatures: &AggregatedExpirationDateSignatures,
+    ) -> Result<(), CredentialProxyError>;
+}
+
+impl GlobalEcashDataCache for CredentialProxyStorage {
+    async fn get_master_verification_key(
+        &self,
+        epoch_id: EpochId,
+    ) -> Result<Option<EpochVerificationKey>, CredentialProxyError> {
+        self.get_master_verification_key(epoch_id).await
+    }
+
+    async fn insert_master_verification_key(
+        &self,
+        key: &EpochVerificationKey,
+    ) -> Result<(), CredentialProxyError> {
+        self.insert_master_verification_key(key).await
+    }
+
+    async fn get_master_coin_index_signatures(
+        &self,
+        epoch_id: EpochId,
+    ) -> Result<Option<AggregatedCoinIndicesSignatures>, CredentialProxyError> {
+        self.get_master_coin_index_signatures(epoch_id).await
+    }
+
+    async fn insert_master_coin_index_signatures(
+        &self,
+        signatures: &AggregatedCoinIndicesSignatures,
+    ) -> Result<(), CredentialProxyError> {
+        self.insert_master_coin_index_signatures(signatures).await
+    }
+
+    async fn get_master_expiration_date_signatures(
+        &self,
+        expiration_date: Date,
+        epoch_id: EpochId,
+    ) -> Result<Option<AggregatedExpirationDateSignatures>, CredentialProxyError> {
+        self.get_master_expiration_date_signatures(expiration_date, epoch_id)
+            .await
+    }
+
+    async fn insert_master_expiration_date_signatures(
+        &self,
+        signatures: &AggregatedExpirationDateSignatures,
+    ) -> Result<(), CredentialProxyError> {
+        self.insert_master_expiration_date_signatures(signatures)
+            .await
+    }
+}
--- a/Show More
+++ b/Show More