Update network_tunnel_manager.sh

wg_meta_change - WIP
feat: DKG contract method for updating announce address (#6050 )
2025-10-03 13:02:16 +02:00 · 2025-10-02 17:19:03 +01:00 · 2025-10-02 16:00:53 +02:00 · 2025-10-02 16:27:48 +03:00 · 2025-10-02 12:53:51 +00:00 · 2025-10-02 14:05:43 +02:00
331 changed files with 19384 additions and 6331 deletions
@@ -10,7 +10,7 @@ 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
@@ -11,7 +11,7 @@ jobs:
    strategy:
      fail-fast: false
      matrix:
-        platform: [ arc-ubuntu-22.04 ]
+        platform: [ arc-linux-latest-dind ]

    runs-on: ${{ matrix.platform }}
    env:
@@ -28,18 +28,11 @@ jobs:
          mkdir -p $OUTPUT_DIR
          echo $OUTPUT_DIR

-      - name: Install Rust stable
-        uses: actions-rs/toolchain@v1
-        with:
-          toolchain: stable
-          target: wasm32-unknown-unknown
-          override: true
+      - name: Build contracts
+        run: make optimize-contracts

-      - name: Install cosmwasm-check
-        run: cargo install cosmwasm-check
-
-      - name: Build release contracts
-        run: make publish-contracts
+      - name: Check optimized contracts
+        run: make docker-check-contracts

      - name: Prepare build output
        shell: bash
@@ -17,7 +17,7 @@ jobs:
  build:
    # since it's going to be compiled into wasm, there's absolutely
    # no point in running CI on different OS-es
-    runs-on: ubuntu-22.04
+    runs-on: arc-linux-latest
    env:
      CARGO_TERM_COLOR: always
      RUSTUP_PERMIT_COPY_RENAME: 1
@@ -21,7 +21,7 @@ jobs:
      fail-fast: false
      matrix:
        include:
-          - os: arc-ubuntu-22.04
+          - os: arc-linux-latest
            target: x86_64-unknown-linux-gnu
    runs-on:  ${{ matrix.os }}

@@ -30,11 +30,13 @@ 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 }}
@@ -74,6 +76,7 @@ jobs:
            target/release/nym-network-requester
            target/release/nym-cli
            target/release/nymvisor
+            target/release/nym-node
          retention-days: 30
    
      - id: create-release
@@ -88,6 +91,7 @@ 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' }}
@@ -8,7 +8,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
@@ -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
@@ -8,7 +8,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
@@ -4,6 +4,84 @@ Post 1.0.0 release, the changelog format is based on [Keep a Changelog](https://

 ## [Unreleased]

+## [2025.17-isabirra] (2025-09-29)
+
+- Bugfix | Fix the registration handshake ([#6062])
+- Convenience for ShutdownTracker ([#6038])
+- chore: made http-api-client-macro doctest compile ([#6037])
+- feat: refresh mixnet contract on epoch progression ([#6023])
+- chore: remove legacy nodes from nym api [and kinda-ish from node status api] ([#6021])
+- Feature/credential proxy crate ([#6018])
+- Moving clients crate from vpn-client repo to here ([#6015])
+- Feature/cancellation migration ([#6014])
+- Use default value for the ports until api is deployed ([#6007])
+- bugfix: return from MixTrafficController if client request channel has closed ([#6002])
+- Revert "Create an axum_test client for more integrated unit testing (… ([#5999])
+- chore: upgraded syn to 2.0 and removed nym-execute ([#5998])
+- feat: use `ShutdownToken` (`CancellationToken` inside) for nym-api ([#5997])
+- bugfix: Recipient deserialisation for deserialisers missing bytes specialisation ([#5991])
+- chore: use updated version of simulate endpoint ([#5988])
+- chore: purge temp databases on build ([#5984])
+- Bump sha.js from 2.4.11 to 2.4.12 ([#5983])
+- Feature: Delegation program stake checker and adjuster ([#5980])
+- build(deps): bump actions/setup-java from 4 to 5 ([#5975])
+- Domain fronting integration ([#5974])
+- chore: internal hidden command to force advance nyx epoch ([#5964])
+- Create an axum_test client for more integrated unit testing ([#5956])
+- feat: shared library for attempting to retrieve update mode attestation ([#5954])
+- Bump slab from 0.4.10 to 0.4.11 ([#5952])
+- build(deps): bump actions/first-interaction from 1 to 3 ([#5950])
+- fix: use WASM compatible time API in client ([#5948])
+- feat: credential proxy deposit pool ([#5945])
+- build(deps): bump actions/download-artifact from 4 to 5 ([#5939])
+- feat: nym signers monitor ([#5933])
+- Bump console from 0.15.11 to 0.16.0 ([#5931])
+- Bump mock_instant from 0.5.3 to 0.6.0 ([#5930])
+- Bump tokio from 1.46.1 to 1.47.1 ([#5929])
+- Bump defguard_wireguard_rs from v0.4.7 to v0.7.5 ([#5928])
+- Bump indicatif from 0.17.11 to 0.18.0 ([#5924])
+- Feature: Nym node autorun CLI ([#5916])
+- build(deps): bump mikefarah/yq from 4.45.4 to 4.47.1 ([#5911])
+- build(deps): bump pbkdf2 from 3.1.2 to 3.1.3 ([#5869])
+
+[#6062]: https://github.com/nymtech/nym/pull/6062
+[#6038]: https://github.com/nymtech/nym/pull/6038
+[#6037]: https://github.com/nymtech/nym/pull/6037
+[#6023]: https://github.com/nymtech/nym/pull/6023
+[#6021]: https://github.com/nymtech/nym/pull/6021
+[#6018]: https://github.com/nymtech/nym/pull/6018
+[#6015]: https://github.com/nymtech/nym/pull/6015
+[#6014]: https://github.com/nymtech/nym/pull/6014
+[#6007]: https://github.com/nymtech/nym/pull/6007
+[#6002]: https://github.com/nymtech/nym/pull/6002
+[#5999]: https://github.com/nymtech/nym/pull/5999
+[#5998]: https://github.com/nymtech/nym/pull/5998
+[#5997]: https://github.com/nymtech/nym/pull/5997
+[#5991]: https://github.com/nymtech/nym/pull/5991
+[#5988]: https://github.com/nymtech/nym/pull/5988
+[#5984]: https://github.com/nymtech/nym/pull/5984
+[#5983]: https://github.com/nymtech/nym/pull/5983
+[#5980]: https://github.com/nymtech/nym/pull/5980
+[#5975]: https://github.com/nymtech/nym/pull/5975
+[#5974]: https://github.com/nymtech/nym/pull/5974
+[#5964]: https://github.com/nymtech/nym/pull/5964
+[#5956]: https://github.com/nymtech/nym/pull/5956
+[#5954]: https://github.com/nymtech/nym/pull/5954
+[#5952]: https://github.com/nymtech/nym/pull/5952
+[#5950]: https://github.com/nymtech/nym/pull/5950
+[#5948]: https://github.com/nymtech/nym/pull/5948
+[#5945]: https://github.com/nymtech/nym/pull/5945
+[#5939]: https://github.com/nymtech/nym/pull/5939
+[#5933]: https://github.com/nymtech/nym/pull/5933
+[#5931]: https://github.com/nymtech/nym/pull/5931
+[#5930]: https://github.com/nymtech/nym/pull/5930
+[#5929]: https://github.com/nymtech/nym/pull/5929
+[#5928]: https://github.com/nymtech/nym/pull/5928
+[#5924]: https://github.com/nymtech/nym/pull/5924
+[#5916]: https://github.com/nymtech/nym/pull/5916
+[#5911]: https://github.com/nymtech/nym/pull/5911
+[#5869]: https://github.com/nymtech/nym/pull/5869
+
 ## [2025.16-halloumi] (2025-09-16)

 - Backport metadata endpoint ([#6010])
@@ -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,7 +93,8 @@ 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",
@@ -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-signers-monitor",
+    "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",
@@ -292,11 +294,8 @@ nix = "0.27.1"
 notify = "5.1.0"
 okapi = "0.7.0"
 once_cell = "1.21.3"
-opentelemetry = "0.30.0"
-opentelemetry-otlp = "0.30.0"
-opentelemetry-semantic-conventions = "0.30.0"
-opentelemetry_sdk = "0.30.0"
-opentelemetry-stdout = "0.30.0"
+opentelemetry = "0.19.0"
+opentelemetry-jaeger = "0.18.0"
 parking_lot = "0.12.3"
 pem = "0.8"
 petgraph = "0.6.5"
@@ -354,10 +353,8 @@ toml = "0.8.22"
 tower = "0.5.2"
 tower-http = "0.5.2"
 tracing = "0.1.41"
-tracing-core = "0.1.33"
 tracing-log = "0.2"
-tracing-opentelemetry = "0.31.0"
-tracing-serde = "0.2.0"
+tracing-opentelemetry = "0.19.0"
 tracing-subscriber = "0.3.19"
 tracing-tree = "0.2.2"
 tracing-indicatif = "0.3.9"
@@ -154,6 +154,7 @@ CONTRACTS_OUT_DIR = contracts/artifacts
 #
 COSMWASM_OPTIMIZER_IMAGE ?= cosmwasm/optimizer:0.17.0
 COSMWASM_OPTIMIZER_PLATFORM ?= linux/amd64
+COSMWASM_CHECK_IMAGE ?= rust:1.88

 # Ensure clean build environment and run the optimizer
 optimize-contracts:
@@ -179,6 +180,13 @@ optimize-contracts:
 	# Cleanup temporary artefacts directory
 	@rm -rf artifacts 2>/dev/null || true

+# Check artifacts with cosmwasm-check inside the optimizer image
+docker-check-contracts:
+	@docker run --rm --platform $(COSMWASM_OPTIMIZER_PLATFORM) \
+	  -v $(CURDIR):/code --workdir /code \
+	  --entrypoint /bin/sh \
+	  $(COSMWASM_CHECK_IMAGE) -lc 'apt-get update && apt-get install -y --no-install-recommends llvm-dev libclang-dev pkg-config && export PATH="/usr/local/cargo/bin:/usr/local/rustup/bin:$$PATH" && cargo install cosmwasm-check --locked && WASMER_ENGINE=universal WASMER_COMPILER=singlepass cosmwasm-check contracts/artifacts/*.wasm'
+
 wasm-opt-contracts:
 	@for WASM in $(WASM_CONTRACT_DIR)/*.wasm; do \
 	  echo "Running wasm-opt on $$WASM"; \
@@ -46,6 +46,7 @@ nym-bandwidth-controller = { path = "../../common/bandwidth-controller" }
 nym-bin-common = { path = "../../common/bin-common", features = [
    "output_format",
    "clap",
+    "basic_tracing",
 ] }
 nym-client-core = { path = "../../common/client-core", features = [
    "fs-credentials-storage",
@@ -4,7 +4,7 @@
 use std::error::Error;

 use clap::{crate_name, crate_version, Parser};
-use nym_bin_common::logging::{maybe_print_banner, setup_no_otel_logger};
+use nym_bin_common::logging::{maybe_print_banner, setup_tracing_logger};
 use nym_network_defaults::setup_env;

 pub mod client;
@@ -20,7 +20,7 @@ async fn main() -> Result<(), Box<dyn Error + Send + Sync>> {
    if !args.no_banner {
        maybe_print_banner(crate_name!(), crate_version!());
    }
-    setup_no_otel_logger().expect("failed to initialize logging");
+    setup_tracing_logger();

    if let Err(err) = commands::execute(args).await {
        log::error!("{err}");
@@ -184,7 +184,7 @@ impl Handler {
        });

        // the ack control is now responsible for chunking, etc.
-        let input_msg = InputMessage::new_regular(recipient, message, lane, self.packet_type, None);
+        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.shutdown_token.is_cancelled() {
                error!("Failed to send message to the input buffer: {err}");
@@ -217,7 +217,7 @@ impl Handler {
        });

        let input_msg =
-            InputMessage::new_anonymous(recipient, message, reply_surbs, lane, self.packet_type, None);
+            InputMessage::new_anonymous(recipient, message, reply_surbs, lane, self.packet_type);
        if let Err(err) = self.msg_input.send(input_msg).await {
            if !self.shutdown_token.is_cancelled() {
                error!("Failed to send anonymous message to the input buffer: {err}");
@@ -27,6 +27,7 @@ zeroize = { workspace = true }
 nym-bin-common = { path = "../../common/bin-common", features = [
    "output_format",
    "clap",
+    "basic_tracing",
 ] }
 nym-client-core = { path = "../../common/client-core", features = [
    "fs-credentials-storage",
@@ -4,7 +4,7 @@
 use std::error::Error;

 use clap::{crate_name, crate_version, Parser};
-use nym_bin_common::logging::{maybe_print_banner, setup_no_otel_logger};
+use nym_bin_common::logging::{maybe_print_banner, setup_tracing_logger};
 use nym_network_defaults::setup_env;

 mod commands;
@@ -19,7 +19,7 @@ async fn main() -> Result<(), Box<dyn Error + Send + Sync>> {
    if !args.no_banner {
        maybe_print_banner(crate_name!(), crate_version!());
    }
-    setup_no_otel_logger().expect("failed to initialize logging");
+    setup_tracing_logger();

    if let Err(err) = commands::execute(args).await {
        log::error!("{err}");
@@ -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
+    }
+}
@@ -8,30 +8,24 @@ license = { workspace = true }
 repository = { workspace = true }

 [dependencies]
-chrono = { workspace = true, optional = true }
-cfg-if = { workspace = true }
 clap = { workspace = true, features = ["derive"], optional = true }
 clap_complete = { workspace = true, optional = true }
 clap_complete_fig = { workspace = true, optional = true }
 const-str = { workspace = true }
-opentelemetry = { workspace = true, optional = true }
-opentelemetry-otlp = { workspace = true,features=["metrics", "grpc-tonic", "tls",
-    "tls-webpki-roots"], optional = true }
-opentelemetry-semantic-conventions = { workspace = true, features = ["semconv_experimental"], optional = true }
-opentelemetry-stdout = { workspace = true, features = ["trace", "metrics"], optional = true }
-opentelemetry_sdk = { workspace = true, optional = true }
-rand = { workspace = true, optional = true }
+log = { workspace = true }
 schemars = { workspace = true, features = ["preserve_order"], optional = true }
 serde = { workspace = true, features = ["derive"] }
 serde_json = { workspace = true, optional = true }
-thiserror = { workspace = true }
-tracing = { workspace = true }
-tracing-core = { workspace = true }
+
+## tracing
+tracing-subscriber = { workspace = true, features = ["env-filter"], optional = true }
+tracing-tree = { workspace = true, optional = true }
+tracing = { workspace = true, optional = true }
+opentelemetry-jaeger = { workspace = true, features = ["rt-tokio", "collector_client", "isahc_collector_client"], optional = true }
 tracing-opentelemetry = { workspace = true, optional = true }
-tracing-serde = { workspace = true }
-tracing-subscriber = { workspace = true, features = ["env-filter", "json"] }
-tracing-tree = { workspace = true }
 utoipa = { workspace = true, optional = true }
+opentelemetry = { workspace = true, features = ["rt-tokio"], optional = true }
+

 [build-dependencies]
 vergen = { workspace = true, features = ["build", "git", "gitcl", "rustc", "cargo"] }
@@ -41,17 +35,13 @@ default = []
 openapi = ["utoipa"]
 output_format = ["serde_json", "dep:clap"]
 bin_info_schema = ["schemars"]
-tokio-console = ["otel"]
-otel = [
-    "chrono",
+basic_tracing = ["dep:tracing", "tracing-subscriber"]
+tracing = [
+    "basic_tracing",
+    "tracing-tree",
+    "opentelemetry-jaeger",
    "tracing-opentelemetry",
    "opentelemetry",
-    "opentelemetry-otlp",
-    "opentelemetry-semantic-conventions",
-    "opentelemetry-stdout",
-    "opentelemetry_sdk",
-    "serde_json",
-    "rand",
 ]
 clap = ["dep:clap", "dep:clap_complete", "dep:clap_complete_fig"]
 models = []
@@ -4,9 +4,6 @@
 pub mod build_information;
 pub mod logging;

-#[cfg(feature = "otel")]
-pub mod opentelemetry;
-
 #[cfg(feature = "clap")]
 pub mod completions;

@@ -1,20 +0,0 @@
-// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
-// SPDX-License-Identifier: Apache-2.0
-#[cfg(feature = "otel")]
-use opentelemetry_otlp::ExporterBuildError;
-
-#[derive(thiserror::Error, Debug)]
-pub enum TracingError {
-    #[error("tracing logger already initialised")]
-    TracingLoggerAlreadyInitialised,
-
-    #[error("Logging error: {0}")]
-    TracingTryInitError(tracing_subscriber::util::TryInitError),
-
-    #[cfg(feature = "otel")]
-    #[error("{0}")]
-    TracingExporterBuildError(#[from] ExporterBuildError),
-
-    #[error("{0}")]
-    TracingFilterParseError(#[from] tracing_subscriber::filter::ParseError),
-}
@@ -1,12 +1,19 @@
 // Copyright 2022-2023 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

-pub mod error;
-
-use error::TracingError;
 use serde::{Deserialize, Serialize};
 use std::io::IsTerminal;
-use tracing_subscriber::{filter::Directive, layer::SubscriberExt, util::SubscriberInitExt};
+
+#[cfg(feature = "tracing")]
+pub use opentelemetry;
+#[cfg(feature = "tracing")]
+pub use opentelemetry_jaeger;
+#[cfg(feature = "tracing")]
+pub use tracing_opentelemetry;
+#[cfg(feature = "tracing")]
+pub use tracing_subscriber;
+#[cfg(feature = "tracing")]
+pub use tracing_tree;

 #[derive(Debug, Default, Copy, Clone, Deserialize, PartialEq, Eq, Serialize)]
 #[serde(deny_unknown_fields)]
@@ -15,6 +22,7 @@ pub struct LoggingSettings {
 }

 // don't call init so that we could attach additional layers
+#[cfg(feature = "basic_tracing")]
 pub fn build_tracing_logger() -> impl tracing_subscriber::layer::SubscriberExt {
    use tracing_subscriber::prelude::*;

@@ -23,6 +31,7 @@ pub fn build_tracing_logger() -> impl tracing_subscriber::layer::SubscriberExt {
        .with(default_tracing_env_filter())
 }

+#[cfg(feature = "basic_tracing")]
 pub fn default_tracing_env_filter() -> tracing_subscriber::filter::EnvFilter {
    if ::std::env::var("RUST_LOG").is_ok() {
        tracing_subscriber::filter::EnvFilter::from_default_env()
@@ -34,6 +43,7 @@ pub fn default_tracing_env_filter() -> tracing_subscriber::filter::EnvFilter {
    }
 }

+#[cfg(feature = "basic_tracing")]
 pub fn default_tracing_fmt_layer<S, W>(
    writer: W,
 ) -> impl tracing_subscriber::Layer<S> + Sync + Send + 'static
@@ -53,47 +63,45 @@ where
        .with_target(false)
 }

-/// Creates a tracing filter that sets more granular log levels for specific crates.
-/// This allows for finer control over logging verbosity.
-pub(crate) fn granual_filtered_env() -> Result<tracing_subscriber::filter::EnvFilter, TracingError>
-{
-    fn directive_checked(directive: impl Into<String>) -> Result<Directive, TracingError> {
-        directive.into().parse().map_err(From::from)
-    }
-
-    let mut filter = default_tracing_env_filter();
-
-    // these crates are more granularly filtered
-    let filter_crates = ["defguard_wireguard_rs"];
-    for crate_name in filter_crates {
-        filter = filter.add_directive(directive_checked(format!("{crate_name}=warn"))?);
-    }
-    Ok(filter)
-}
-
-pub fn setup_no_otel_logger() -> Result<(), TracingError> {
-    // Only set up if not already initialized
-    if tracing::dispatcher::has_been_set() {
-        // It shouldn't be - this is really checking that it is torn down between async command executions
-        return Err(TracingError::TracingLoggerAlreadyInitialised);
-    }
-
-    let registry = tracing_subscriber::registry()
-        .with(default_tracing_fmt_layer(std::io::stderr))
-        .with(granual_filtered_env()?);
-
-    registry
-        .try_init()
-        .map_err(|e| TracingError::TracingTryInitError(e))?;
-
-    Ok(())
+#[cfg(feature = "basic_tracing")]
+pub fn setup_tracing_logger() {
+    use tracing_subscriber::util::SubscriberInitExt;
+    build_tracing_logger().init()
 }

 // TODO: This has to be a macro, running it as a function does not work for the file_appender for some reason
+#[cfg(feature = "tracing")]
 #[macro_export]
 macro_rules! setup_tracing {
    ($service_name: expr) => {
-        setup_no_otel_logger()
+        use nym_bin_common::logging::tracing_subscriber::layer::SubscriberExt;
+        use nym_bin_common::logging::tracing_subscriber::util::SubscriberInitExt;
+
+        let registry = nym_bin_common::logging::tracing_subscriber::Registry::default()
+            .with(nym_bin_common::logging::tracing_subscriber::EnvFilter::from_default_env())
+            .with(
+                nym_bin_common::logging::tracing_tree::HierarchicalLayer::new(4)
+                    .with_targets(true)
+                    .with_bracketed_fields(true),
+            );
+
+        let tracer = nym_bin_common::logging::opentelemetry_jaeger::new_collector_pipeline()
+            .with_endpoint("http://44.199.230.10:14268/api/traces")
+            .with_service_name($service_name)
+            .with_isahc()
+            .with_trace_config(
+                nym_bin_common::logging::opentelemetry::sdk::trace::config().with_sampler(
+                    nym_bin_common::logging::opentelemetry::sdk::trace::Sampler::TraceIdRatioBased(
+                        0.1,
+                    ),
+                ),
+            )
+            .install_batch(nym_bin_common::logging::opentelemetry::runtime::Tokio)
+            .expect("Could not init tracer");
+
+        let telemetry = nym_bin_common::logging::tracing_opentelemetry::layer().with_tracer(tracer);
+
+        registry.with(telemetry).init();
    };
 }

@@ -1,47 +0,0 @@
-use opentelemetry_sdk::trace::IdGenerator;
-use opentelemetry::trace::{TraceId, SpanId};
-use rand::RngCore;
-
-#[derive(Clone, Debug)]
-pub struct Compact13BytesIdGenerator;
-
-impl IdGenerator for Compact13BytesIdGenerator {
-    fn new_trace_id(&self) -> TraceId {
-        let mut rng = rand::thread_rng();
-        let mut bytes = [0u8; 16];
-
-        // Fill the first 13 bytes with random data
-        rng.fill_bytes(&mut bytes[0..12]);
-        // Set the last 4 bytes to zero
-        bytes[12] = 0;
-        bytes[13] = 0;
-        bytes[14] = 0;
-        bytes[15] = 0;
-
-        TraceId::from_bytes(bytes)
-    }
-
-    fn new_span_id(&self) -> SpanId {
-        let mut rng = rand::thread_rng();
-        let mut bytes = [0u8; 8];
-        rng.fill_bytes(&mut bytes);
-        
-        SpanId::from_bytes(bytes)
-    }
-}
-
-pub fn compress_trace_id(trace_id: &TraceId) -> [u8; 12] {
-    let bytes = trace_id.to_bytes();
-
-    let mut compressed = [0u8; 12];
-    compressed.copy_from_slice(&bytes[0..12]);
-
-    compressed
-}
-
-pub fn decompress_trace_id(compressed: &[u8; 12]) -> [u8; 16] {
-    let mut bytes = [0u8; 16];
-    bytes[0..12].copy_from_slice(compressed);
-    bytes[12..].copy_from_slice(&[0u8; 4]);
-    bytes
-}
@@ -1,156 +0,0 @@
-use opentelemetry::{Context, TraceFlags};
-use opentelemetry::propagation::{Injector, Extractor, TextMapPropagator};
-use opentelemetry::trace::{SpanContext, TraceContextExt, TraceId};
-use opentelemetry_sdk::{propagation::TraceContextPropagator, trace::IdGenerator};
-use tracing_opentelemetry::OpenTelemetrySpanExt;
-use std::collections::HashMap;
-use std::fmt::Display;
-use tracing::instrument;
-
-/// Make a Carrier for context propagation
-pub struct ContextCarrier {
-    data: HashMap<String, String>,
-}
-
-impl ContextCarrier {
-    pub fn new_empty() -> Self {
-        ContextCarrier {
-            data: HashMap::new(),
-        }
-    }
-
-    pub fn new_with_data(data: HashMap<String, String>) -> Self {
-        if data.is_empty() {
-            return ContextCarrier::new_empty();
-        }
-        
-        ContextCarrier { data }
-    }
-
-    pub fn new_with_current_context(context: Context) -> Self {
-        let mut carrier = ContextCarrier::new_empty();
-        let propagator = TraceContextPropagator::new();
-        propagator.inject_context(&context, &mut carrier);
-        carrier
-    }
-
-    pub fn iter(&self) -> impl Iterator<Item = (&String, &String)> {
-        self.data.iter()
-    }
-
-    pub fn from_map(data: HashMap<String, String>) -> Self {
-        ContextCarrier { data }
-    }
-
-    pub fn into_map(self) -> HashMap<String, String> {
-        self.data
-    }
-
-    pub fn extract_trace_id(&self) -> Option<TraceId> {
-        self.get("traceparent").and_then(|tp| {
-            let parts: Vec<&str> = tp.split('-').collect();
-            if parts.len() == 4 {
-                TraceId::from_hex(parts[1]).ok()
-            } else {
-                None
-            }
-        })
-    }
-
-    pub fn extract_trace_id_into_bytes(&self) -> Option<[u8; 16]> {
-        self.extract_trace_id().map(|id| id.to_bytes())
-    }
-
-    pub fn extract_traceparent(&self) -> Option<String> {
-        self.get("traceparent").map(|s| s.to_string())
-    }
-}
-
-impl Injector for ContextCarrier {
-    fn set(&mut self, key: &str, value: String) {
-        self.data.insert(key.to_string(), value);
-    }
-}
-
-impl Extractor for ContextCarrier {
-    fn get(&self, key: &str) -> Option<&str> {
-        self.data.get(key).map(|s| s.as_str())
-    }
-
-    fn keys(&self) -> Vec<&str> {
-        self.data.keys().map(|k| k.as_str()).collect()
-    }
-}
-
-impl Display for ContextCarrier {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        write!(f, "{:?}", self.data)
-    }
-}
-
-pub struct ManualContextPropagator {
-    pub root_span: tracing::Span,
-    pub trace_id: TraceId,
-}
-
-impl ManualContextPropagator {
-    #[instrument(skip_all, level = "debug")]
-    pub fn new(name: &str, context: HashMap<String, String>) -> Self {
-        let carrier = ContextCarrier::new_with_data(context);
-        let trace_id = match carrier.extract_trace_id() {
-            Some(id) => id,
-            None => Context::current().span().span_context().trace_id(),
-        };
-
-        let root_span_builder = new_span_context_with_id(trace_id.clone());
-
-        let root_span = tracing::info_span!("trace_root", name = %name, trace_id = %trace_id);
-        root_span.set_parent(root_span_builder);
-
-        ManualContextPropagator {
-            root_span,
-            trace_id,
-        }
-    }
-
-    #[instrument(skip_all, level = "debug")]
-    pub fn new_from_tid(name: &str, trace_id: TraceId) -> Self {
-        let root_span_builder = new_span_context_with_id(trace_id.clone());
-
-        let root_span = tracing::info_span!("trace_root", name = %name, trace_id = %trace_id);
-        root_span.set_parent(root_span_builder);
-
-        ManualContextPropagator {
-            root_span,
-            trace_id,
-        }
-    }
-
-    pub fn root_span(&self) -> &tracing::Span {
-        &self.root_span
-    }
-
-}
-
-#[instrument(skip_all, level = "debug")]
-pub fn new_span_context_with_id(trace_id: TraceId) -> Context {
-    let id_gen = opentelemetry_sdk::trace::RandomIdGenerator::default();
-    let span_id = id_gen.new_span_id();
-    let span_context = SpanContext::new(
-        trace_id,
-        span_id,
-        TraceFlags::SAMPLED,
-        true,
-        Default::default(),
-    );
-
-    Context::current().with_remote_span_context(span_context)
-}
-
-#[instrument(skip_all, level = "debug")]
-pub fn extract_trace_id_from_tracing_cx() -> TraceId {
-    let cx = tracing::Span::current().context();
-    let binding = cx.span();
-    let trace_id = binding.span_context().trace_id();
-    trace_id
-}
@@ -1,308 +0,0 @@
-pub mod context;
-pub mod compact_id_generator;
-mod trace_id_format;
-
-use tracing::{info, Level};
-use tracing_subscriber::filter::Directive;
-use tracing_subscriber::layer::SubscriberExt;
-use tracing_subscriber::util::SubscriberInitExt;
-use tracing_subscriber::fmt;
-
-use crate::logging::default_tracing_env_filter;
-use crate::logging::error::TracingError;
-use crate::opentelemetry::compact_id_generator::Compact13BytesIdGenerator;
-use opentelemetry::trace::TracerProvider;
-use opentelemetry::{global, KeyValue};
-use opentelemetry_otlp::tonic_types::metadata::MetadataMap;
-use opentelemetry_otlp::tonic_types::transport::ClientTlsConfig;
-use opentelemetry_otlp::{WithExportConfig, WithTonicConfig};
-use opentelemetry_sdk::metrics::{MeterProviderBuilder, PeriodicReader, SdkMeterProvider};
-use opentelemetry_sdk::trace::SdkTracerProvider;
-use opentelemetry_sdk::{trace::Sampler, Resource};
-use opentelemetry_semantic_conventions::resource::{DEPLOYMENT_ENVIRONMENT_NAME, SERVICE_VERSION};
-use opentelemetry_semantic_conventions::SCHEMA_URL;
-use tracing_opentelemetry::{MetricsLayer, OpenTelemetryLayer};
-use tracing_subscriber::fmt::format::FmtSpan;
-
-pub struct TracerProviderGuard(Option<SdkTracerProvider>);
-
-impl Drop for TracerProviderGuard {
-    fn drop(&mut self) {
-        if let Some(tracer_provider) = self.0.take() {
-            // Ensure all spans are flushed before exit
-            if let Err(e) = tracer_provider.shutdown() {
-                eprintln!("Error shutting down tracer provider: {:?}", e);
-            }
-        }
-    }
-}
-
-pub(crate) fn granual_filtered_env() -> Result<tracing_subscriber::filter::EnvFilter, TracingError>
-{
-    fn directive_checked(directive: impl Into<String>) -> Result<Directive, TracingError> {
-        directive.into().parse().map_err(From::from)
-    }
-
-    let mut filter = default_tracing_env_filter();
-
-    // these crates are more granularly filtered
-    let filter_crates = ["defguard_wireguard_rs"];
-    for crate_name in filter_crates {
-        filter = filter.add_directive(directive_checked(format!("{crate_name}=warn"))?);
-    }
-    Ok(filter)
-}
-
-pub fn setup_tracing_logger(service_name: String) -> Result<TracerProviderGuard, TracingError> {
-    if tracing::dispatcher::has_been_set() {
-        // It shouldn't be - this is really checking that it is torn down between async command executions
-        return Err(TracingError::TracingLoggerAlreadyInitialised);
-    }
-
-    // define ingestion points
-    let endpoint = std::env::var("SIGNOZ_ENDPOINT").expect("SIGNOZ_ENDPOINT not set");
-    let key = std::env::var("SIGNOZ_INGESTION_KEY").expect("SIGNOZ_INGESTION_KEY not set");
-    let mut metadata = MetadataMap::new();
-    metadata.insert(
-        "signoz-ingestion-key",
-        key.parse().expect("Could not parse signoz ingestion key"),
-    );
-
-    // Build resources
-    let resource = build_resource(&service_name);
-
-    // Initialize tracer and meter providers
-    let tracer_provider = init_tracer_provider(&endpoint, metadata.clone(), resource.clone())?;
-    let meter_provider = init_meter_provider(&endpoint, metadata.clone(), resource.clone())?;
-
-    // Bridge tracing and opentelemetry
-    let tracer = tracer_provider.tracer("otel-subscriber");
-    let fmt_layer = fmt::layer()
-        .json()
-        .with_writer(std::io::stderr)
-        .with_span_events(FmtSpan::NEW | FmtSpan::CLOSE)
-        .with_span_list(false)
-        .with_current_span(true)
-        .event_format(trace_id_format::TraceIdFormat);
-
-    let registry = tracing_subscriber::registry()
-        .with(fmt_layer)
-        .with(granual_filtered_env()?)
-        .with(tracing_subscriber::filter::LevelFilter::from_level(Level::INFO))
-        .with(MetricsLayer::new(meter_provider.clone()))
-        .with(OpenTelemetryLayer::new(tracer));
-
-    registry.try_init().map_err(TracingError::TracingTryInitError)?;
-
-    global::set_tracer_provider(tracer_provider.clone());
-    global::set_meter_provider(meter_provider.clone());
-
-    info!("Tracing initialized with service name: {}", service_name);
-
-    Ok(TracerProviderGuard(Some(tracer_provider)))
-}
-
-fn build_resource(service_name: &str) -> Resource {
-    Resource::builder()
-        .with_service_name(service_name.to_string())
-        .with_schema_url(
-            [
-                KeyValue::new(SERVICE_VERSION, env!("CARGO_PKG_VERSION")),
-                KeyValue::new(DEPLOYMENT_ENVIRONMENT_NAME, "develop"),
-            ],
-            SCHEMA_URL,
-        )
-        .build()
-}
-
-fn init_tracer_provider(
-    endpoint: &str,
-    metadata: MetadataMap,
-    resource: Resource,
-) -> Result<SdkTracerProvider, TracingError> {
-    let mut exporter_builder = opentelemetry_otlp::SpanExporter::builder()
-        .with_tonic()
-        .with_metadata(metadata)
-        .with_endpoint(endpoint);
-
-    if endpoint.starts_with("https://") {
-        exporter_builder =
-            exporter_builder.with_tls_config(ClientTlsConfig::new().with_enabled_roots());
-    }
-
-    let exporter = exporter_builder.build()?;
-
-    let tracer = SdkTracerProvider::builder()
-        .with_sampler(Sampler::ParentBased(Box::new(Sampler::TraceIdRatioBased(
-            1.0,
-        ))))
-        .with_id_generator(Compact13BytesIdGenerator)
-        .with_resource(resource)
-        .with_batch_exporter(exporter)
-        .build();
-
-    global::set_tracer_provider(tracer.clone());
-    Ok(tracer)
-}
-
-fn init_meter_provider(
-    endpoint: &str,
-    metadata: MetadataMap,
-    resource: Resource,
-) -> Result<SdkMeterProvider, TracingError> {
-    let mut exporter_builder = opentelemetry_otlp::MetricExporter::builder()
-        .with_tonic()
-        .with_metadata(metadata)
-        .with_endpoint(endpoint)
-        .with_temporality(opentelemetry_sdk::metrics::Temporality::default());
-
-    if endpoint.starts_with("https://") {
-        exporter_builder = exporter_builder.with_tls_config(ClientTlsConfig::new().with_enabled_roots());
-    }
-
-    let exporter = exporter_builder.build()?;
-
-    let reader = PeriodicReader::builder(exporter)
-        .with_interval(std::time::Duration::from_secs(30))
-        .build();
-
-    let stdout_reader =
-        PeriodicReader::builder(opentelemetry_stdout::MetricExporter::default()).build();
-
-    let meter_provider = MeterProviderBuilder::default()
-        .with_resource(resource)
-        .with_reader(reader)
-        .with_reader(stdout_reader)
-        .build();
-
-    global::set_meter_provider(meter_provider.clone());
-
-    Ok(meter_provider)
-}
-
-// pub fn setup_tracing_logger(service_name: String) -> Result<(), TracingError> {
-//     if tracing::dispatcher::has_been_set() {
-//         // It shouldn't be - this is really checking that it is torn down between async command executions
-//         return Err(TracingError::TracingLoggerAlreadyInitialised);
-//     }
-
-//     let key =
-//         std::env::var("SIGNOZ_INGESTION_KEY".to_string()).expect("SIGNOZ_INGESTION_KEY not set");
-//     let mut metadata = MetadataMap::new();
-//     metadata.insert(
-//         "signoz-ingestion-key",
-//         key.parse().expect("Could not parse signoz ingestion key"),
-//     );
-
-//     let tracer_provider = init_tracer_provider(metadata.clone(), service_name.clone())?;
-//     let meter_provider = init_meter_provider(metadata.clone(), service_name.clone())?;
-//     let tracer = tracer_provider.tracer("tracing-otel-subscriber");
-//     let fmt_layer = fmt::layer()
-//         .json()
-//         .with_writer(std::io::stderr)
-//         .with_span_events(FmtSpan::NEW | FmtSpan::CLOSE)
-//         .with_span_list(false)
-//         .with_current_span(true)
-//         .event_format(trace_id_format::TraceIdFormat);
-
-//     cfg_if::cfg_if! {if #[cfg(feature = "tokio-console")] {
-//         // instrument tokio console subscriber needs RUSTFLAGS="--cfg tokio_unstable" at build time
-//         let console_layer = console_subscriber::spawn();
-
-//         tracing_subscriber::registry()
-//             .with(console_layer)
-//             .with(fmt_layer)
-//             .with(granual_filtered_env()?)
-//             .with(tracing_subscriber::filter::LevelFilter::from_level(Level::INFO))
-//             .with(MetricsLayer::new(meter_provider))
-//             .with(OpenTelemetryLayer::new(tracer))
-//             .try_init()
-//             .map_err(|e| TracingError::TracingTryInitError(e))?;
-//     } else {
-//         tracing_subscriber::registry()
-//             .with(fmt_layer)
-//             .with(granual_filtered_env()?)
-//             .with(tracing_subscriber::filter::LevelFilter::from_level(Level::INFO))
-//             .with(MetricsLayer::new(meter_provider))
-//             .with(OpenTelemetryLayer::new(tracer))
-//             .try_init()
-//             .map_err(|e| TracingError::TracingTryInitError(e))?;
-//     }}
-
-//     Ok(())
-// }
-
-// fn resource(service_name: String) -> Resource {
-//     Resource::builder()
-//         .with_service_name(service_name)
-//         .with_schema_url(
-//             [
-//                 KeyValue::new(SERVICE_VERSION, env!("CARGO_PKG_VERSION")),
-//                 KeyValue::new(DEPLOYMENT_ENVIRONMENT_NAME, "develop"),
-//             ],
-//             SCHEMA_URL,
-//         )
-//         .build()
-// }
-
-// fn init_tracer_provider(metadata: MetadataMap, service_name: String) -> Result<SdkTracerProvider, TracingError> {
-//     let endpoint = std::env::var("SIGNOZ_ENDPOINT".to_string()).expect("SIGNOZ_ENDPOINT not set");
-//     info!("SIGNOZ_ENDPOINT = {}", endpoint);
-
-//     let mut exporter_builder = opentelemetry_otlp::SpanExporter::builder()
-//         .with_tonic()
-//         .with_metadata(metadata)
-//         .with_endpoint(&endpoint);
-
-//     if endpoint.starts_with("https://") {
-//         exporter_builder =
-//             exporter_builder.with_tls_config(ClientTlsConfig::new().with_enabled_roots());
-//     }
-
-//     let exporter = exporter_builder.build()?;
-
-//     let tracer = SdkTracerProvider::builder()
-//         .with_sampler(Sampler::ParentBased(Box::new(Sampler::TraceIdRatioBased(
-//             1.0,
-//         ))))
-//         .with_id_generator(Compact13BytesIdGenerator)
-//         .with_resource(resource(service_name))
-//         .with_batch_exporter(exporter)
-//         .build();
-
-//     global::set_tracer_provider(tracer.clone());
-//     Ok(tracer)
-// }
-
-// fn init_meter_provider(metadata: MetadataMap, service_name: String) -> Result<SdkMeterProvider, TracingError> {
-//     let endpoint = std::env::var("SIGNOZ_ENDPOINT".to_string()).expect("SIGNOZ_ENDPOINT not set");
-
-//     let mut exporter_builder = opentelemetry_otlp::MetricExporter::builder()
-//         .with_tonic()
-//         .with_metadata(metadata)
-//         .with_endpoint(&endpoint)
-//         .with_temporality(opentelemetry_sdk::metrics::Temporality::default());
-
-//     if endpoint.starts_with("https://") {
-//         exporter_builder = exporter_builder.with_tls_config(ClientTlsConfig::new().with_enabled_roots());
-//     }
-
-//     let exporter = exporter_builder.build()?;
-
-//     let reader = PeriodicReader::builder(exporter)
-//         .with_interval(std::time::Duration::from_secs(30))
-//         .build();
-
-//     let stdout_reader =
-//         PeriodicReader::builder(opentelemetry_stdout::MetricExporter::default()).build();
-
-//     let meter_provider = MeterProviderBuilder::default()
-//         .with_resource(resource(service_name))
-//         .with_reader(reader)
-//         .with_reader(stdout_reader)
-//         .build();
-
-//     global::set_meter_provider(meter_provider.clone());
-
-//     Ok(meter_provider)
-// }
@@ -1,88 +0,0 @@
-use chrono::Utc;
-use opentelemetry::trace::TraceContextExt;
-use opentelemetry::{SpanId, TraceId};
-use serde::ser::{SerializeMap, Serializer as _};
-use std::io;
-use tracing::{Event, Subscriber};
-use tracing_opentelemetry::OpenTelemetrySpanExt;
-use tracing_serde::fields::AsMap;
-use tracing_serde::AsSerde;
-use tracing_subscriber::fmt::format::Writer;
-use tracing_subscriber::fmt::{FmtContext, FormatEvent, FormatFields};
-use tracing_subscriber::registry::LookupSpan;
-
-pub struct WriteAdaptor<'a> {
-    fmt_write: &'a mut dyn std::fmt::Write,
-}
-
-impl<'a> WriteAdaptor<'a> {
-    pub fn new(fmt_write: &'a mut dyn std::fmt::Write) -> Self {
-        Self { fmt_write }
-    }
-}
-
-impl<'a> io::Write for WriteAdaptor<'a> {
-    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
-        let s =
-            std::str::from_utf8(buf).map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e))?;
-
-        self.fmt_write
-            .write_str(s)
-            .map_err(|e| io::Error::new(io::ErrorKind::Other, e))?;
-
-        Ok(s.as_bytes().len())
-    }
-
-    fn flush(&mut self) -> io::Result<()> {
-        Ok(())
-    }
-}
-
-pub struct TraceIdFormat;
-
-impl<S, N> FormatEvent<S, N> for TraceIdFormat
-where
-    S: Subscriber + for<'lookup> LookupSpan<'lookup>,
-    N: for<'writer> FormatFields<'writer> + 'static,
-{
-    fn format_event(
-        &self,
-        _ctx: &FmtContext<'_, S, N>,
-        mut writer: Writer<'_>,
-        event: &Event<'_>,
-    ) -> std::fmt::Result
-    where
-        S: Subscriber + for<'a> LookupSpan<'a>,
-    {
-        let meta = event.metadata();
-
-        let mut visit = || {
-            let mut serializer = serde_json::Serializer::new(WriteAdaptor::new(&mut writer));
-            let mut serializer = serializer.serialize_map(None)?;
-            serializer.serialize_entry("timestamp", &Utc::now().to_rfc3339())?;
-            serializer.serialize_entry("level", &meta.level().as_serde())?;
-            serializer.serialize_entry("fields", &event.field_map())?;
-            serializer.serialize_entry("target", meta.target())?;
-
-            let current_span = tracing::Span::current();
-            let context = current_span.context();
-            let span_ref = context.span();
-            let span_context = span_ref.span_context();
-
-            let trace_id = span_context.trace_id();
-            if trace_id != TraceId::INVALID {
-                serializer.serialize_entry("trace_id", &trace_id.to_string())?;
-
-                let span_id = span_context.span_id();
-                if span_id != SpanId::INVALID {
-                    serializer.serialize_entry("span_id", &span_id.to_string())?;
-                }
-            }
-
-            serializer.end()
-        };
-
-        visit().map_err(|_| std::fmt::Error)?;
-        writeln!(writer)
-    }
-}
@@ -123,7 +123,6 @@ cli = ["clap", "comfy-table"]
 fs-credentials-storage = ["nym-credential-storage/persistent-storage"]
 fs-surb-storage = ["nym-client-core-surb-storage/fs-surb-storage"]
 fs-gateways-storage = ["nym-client-core-gateways-storage/fs-gateways-storage"]
-otel = ["nym-sphinx/otel"]
 wasm = ["nym-gateway-client/wasm"]
 metrics-server = []

@@ -99,7 +99,6 @@ pub struct ClientOutput {
 }

 impl ClientOutput {
-    #[instrument(name = "ClientOutput::register_receiver", skip_all)]
    pub fn register_receiver(
        &mut self,
    ) -> Result<mpsc::UnboundedReceiver<Vec<ReconstructedMessage>>, ClientCoreError> {
@@ -434,7 +433,6 @@ where

    // buffer controlling all messages fetched from provider
    // required so that other components would be able to use them (say the websocket)
-    #[instrument(skip_all)]
    fn start_received_messages_buffer_controller(
        local_encryption_keypair: Arc<x25519::KeyPair>,
        query_receiver: ReceivedBufferRequestReceiver,
@@ -467,7 +465,6 @@ where
    }

    #[allow(clippy::too_many_arguments)]
-    #[instrument(skip_all)]
    async fn start_gateway_client(
        config: &Config,
        initialisation_result: InitialisationResult,
@@ -574,7 +571,6 @@ where
    }

    #[allow(clippy::too_many_arguments)]
-    #[instrument(skip_all)]
    async fn setup_gateway_transceiver(
        custom_gateway_transceiver: Option<Box<dyn GatewayTransceiver + Send>>,
        config: &Config,
@@ -732,7 +728,7 @@ where
            shutdown_tracker,
        )
    }
-    #[instrument(skip_all)]
+
    fn start_mix_traffic_controller(
        gateway_transceiver: Box<dyn GatewayTransceiver + Send>,
        shutdown_tracker: &ShutdownTracker,
@@ -842,7 +838,6 @@ where
        Ok(client.get_key_rotation_info().await?.into())
    }

-    #[instrument(skip_all)]
    pub async fn start_base(mut self) -> Result<BaseClient, ClientCoreError>
    where
        S::ReplyStore: Send + Sync,
@@ -1055,7 +1050,7 @@ where
                gateway_connection: GatewayConnection { gateway_ws_fd },
            },
            stats_reporter,
-            shutdown_handle: Some(shutdown_tracker), // The primary tracker for this client
+            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,
@@ -1071,7 +1066,7 @@ pub struct BaseClient {
    pub client_state: ClientState,
    pub stats_reporter: ClientStatsSender,
    pub client_request_sender: ClientRequestSender,
-    pub shutdown_handle: Option<ShutdownTracker>,
+    pub shutdown_handle: ShutdownTracker,
    pub forget_me: ForgetMe,
    pub remember_me: RememberMe,
 }
@@ -29,8 +29,6 @@ pub enum InputMessage {
        data: Vec<u8>,
        lane: TransmissionLane,
        max_retransmissions: Option<u32>,
-        // add trace_id for optional tracing of individual messages in debug mode
-        trace_id: Option<[u8; 12]>,
    },

    /// Creates a message used for a duplex anonymous communication where the recipient
@@ -47,7 +45,6 @@ pub enum InputMessage {
        reply_surbs: u32,
        lane: TransmissionLane,
        max_retransmissions: Option<u32>,
-        trace_id: Option<[u8; 12]>,
    },

    /// Attempt to use our internally received and stored `ReplySurb` to send the message back
@@ -93,14 +90,12 @@ impl InputMessage {
        data: Vec<u8>,
        lane: TransmissionLane,
        packet_type: Option<PacketType>,
-        trace_id: Option<[u8; 12]>,
    ) -> Self {
        let message = InputMessage::Regular {
            recipient,
            data,
            lane,
            max_retransmissions: None,
-            trace_id,
        };
        if let Some(packet_type) = packet_type {
            InputMessage::new_wrapper(message, packet_type)
@@ -115,7 +110,6 @@ impl InputMessage {
        reply_surbs: u32,
        lane: TransmissionLane,
        packet_type: Option<PacketType>,
-        trace_id: Option<[u8; 12]>,
    ) -> Self {
        let message = InputMessage::Anonymous {
            recipient,
@@ -123,7 +117,6 @@ impl InputMessage {
            reply_surbs,
            lane,
            max_retransmissions: None,
-            trace_id,
        };
        if let Some(packet_type) = packet_type {
            InputMessage::new_wrapper(message, packet_type)
@@ -192,13 +185,4 @@ impl InputMessage {
        self.set_max_retransmissions(max_retransmissions);
        self
    }
-
-    pub fn trace_id(&self) -> Option<[u8; 12]> {
-        match self {
-            InputMessage::Regular { trace_id, .. } => *trace_id,
-            InputMessage::Anonymous { trace_id, .. } => *trace_id,
-            InputMessage::Premade { .. } | InputMessage::Reply { .. } => None,
-            InputMessage::MessageWrapper { message, .. } => message.trace_id(),
-        }
-    }
 }
@@ -170,7 +170,8 @@ impl MixTrafficController {
                    },
                    None => {
                        trace!("MixTrafficController, client request channel closed");
-                    break}
+                        break
+                    }
                },
            }
        }
@@ -70,7 +70,6 @@ where
                .send_reply(recipient_tag, data, lane, max_retransmissions);
    }

-    #[instrument(skip_all)]
    async fn handle_plain_message(
        &mut self,
        recipient: Recipient,
@@ -78,18 +77,16 @@ where
        lane: TransmissionLane,
        packet_type: PacketType,
        max_retransmissions: Option<u32>,
-        trace_id: Option<[u8; 12]>,
    ) {
        if let Err(err) = self
            .message_handler
-            .try_send_plain_message(recipient, content, lane, packet_type, max_retransmissions, trace_id)
+            .try_send_plain_message(recipient, content, lane, packet_type, max_retransmissions)
            .await
        {
            warn!("failed to send a plain message - {err}")
        }
    }

-    #[instrument(skip_all)]
    async fn handle_repliable_message(
        &mut self,
        recipient: Recipient,
@@ -98,7 +95,6 @@ where
        lane: TransmissionLane,
        packet_type: PacketType,
        max_retransmissions: Option<u32>,
-        trace_id: Option<[u8; 12]>,
    ) {
        if let Err(err) = self
            .message_handler
@@ -109,7 +105,6 @@ where
                lane,
                packet_type,
                max_retransmissions,
-                trace_id,
            )
            .await
        {
@@ -118,29 +113,20 @@ where
    }

    #[allow(clippy::panic)]
-    #[instrument(skip_all)]
    async fn on_input_message(&mut self, msg: InputMessage) {
-        let trace_id = msg.trace_id();
-        if let Some(tid) = trace_id {
-            tracing::warn!("Processing input message with trace_id: {:?}", tid);
-        }
-
        match msg {
            InputMessage::Regular {
                recipient,
                data,
                lane,
                max_retransmissions,
-                ..
            } => {
-                warn!("Handling regular input message with trace_id: {:?}", trace_id);
                self.handle_plain_message(
                    recipient,
                    data,
                    lane,
                    PacketType::Mix,
                    max_retransmissions,
-                    trace_id
                )
                .await
            }
@@ -150,9 +136,7 @@ where
                reply_surbs,
                lane,
                max_retransmissions,
-                ..
            } => {
-                warn!("Handling anonymous input message with trace_id: {:?}", trace_id);
                self.handle_repliable_message(
                    recipient,
                    data,
@@ -160,7 +144,6 @@ where
                    lane,
                    PacketType::Mix,
                    max_retransmissions,
-                    trace_id
                )
                .await
            }
@@ -170,7 +153,6 @@ where
                lane,
                max_retransmissions,
            } => {
-                warn!("Handling reply input message with trace_id: {:?}", trace_id);
                self.handle_reply(recipient_tag, data, lane, max_retransmissions)
                    .await;
            }
@@ -184,16 +166,13 @@ where
                    data,
                    lane,
                    max_retransmissions,
-                    ..
                } => {
-                    tracing::warn!("Handling regular input message with trace_id: {:?}", trace_id);
                    self.handle_plain_message(
                        recipient,
                        data,
                        lane,
                        packet_type,
                        max_retransmissions,
-                        trace_id
                    )
                    .await
                }
@@ -203,7 +182,6 @@ where
                    reply_surbs,
                    lane,
                    max_retransmissions,
-                    ..
                } => {
                    self.handle_repliable_message(
                        recipient,
@@ -212,7 +190,6 @@ where
                        lane,
                        packet_type,
                        max_retransmissions,
-                        trace_id
                    )
                    .await
                }
@@ -236,7 +213,6 @@ where
        };
    }

-    #[instrument(skip_all)]
    pub(crate) async fn run(&mut self, shutdown_token: ShutdownToken) {
        debug!("Started InputMessageListener with graceful shutdown support");

@@ -60,7 +60,7 @@ where

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

@@ -27,7 +27,7 @@ use std::collections::HashMap;
 use std::sync::Arc;
 use std::time::Duration;
 use thiserror::Error;
-use tracing::{debug, error, info, instrument, trace, warn};
+use tracing::{debug, error, info, trace, warn};

 // TODO: move that error elsewhere since it seems to be contaminating different files
 #[derive(Debug, Error)]
@@ -476,7 +476,6 @@ where
        self.forward_messages(msgs, lane).await;
    }

-    #[instrument(skip_all)]
    pub(crate) async fn try_send_plain_message(
        &mut self,
        recipient: Recipient,
@@ -484,7 +483,6 @@ where
        lane: TransmissionLane,
        packet_type: PacketType,
        max_retransmissions: Option<u32>,
-        trace_id: Option<[u8; 12]>,
    ) -> Result<(), PreparationError> {
        let message = NymMessage::new_plain(message);
        self.try_split_and_send_non_reply_message(
@@ -493,12 +491,10 @@ where
            lane,
            packet_type,
            max_retransmissions,
-            trace_id,
        )
        .await
    }

-    #[instrument(skip_all)]
    pub(crate) async fn try_split_and_send_non_reply_message(
        &mut self,
        message: NymMessage,
@@ -506,7 +502,6 @@ where
        lane: TransmissionLane,
        packet_type: PacketType,
        max_retransmissions: Option<u32>,
-        trace_id: Option<[u8; 12]>,
    ) -> Result<(), PreparationError> {
        debug!("Sending non-reply message with packet type {packet_type}");
        // TODO: I really dislike existence of this assertion, it implies code has to be re-organised
@@ -539,7 +534,6 @@ where
                &self.config.ack_key,
                &recipient,
                packet_type,
-                trace_id
            )?;

            let real_message = RealMessage::new(
@@ -591,7 +585,6 @@ where
            TransmissionLane::AdditionalReplySurbs,
            packet_type,
            max_retransmissions,
-            None,
        )
        .await?;

@@ -609,7 +602,6 @@ where
        lane: TransmissionLane,
        packet_type: PacketType,
        max_retransmissions: Option<u32>,
-        trace_id: Option<[u8; 12]>,
    ) -> Result<(), SurbWrappedPreparationError> {
        debug!("Sending message with reply SURBs with packet type {packet_type}");
        let sender_tag = self.get_or_create_sender_tag(&recipient);
@@ -633,7 +625,6 @@ where
            lane,
            packet_type,
            max_retransmissions,
-            trace_id,
        )
        .await?;

@@ -648,7 +639,6 @@ where
        recipient: Recipient,
        chunk: Fragment,
        packet_type: PacketType,
-        trace_id: Option<[u8; 12]>,
    ) -> Result<PreparedFragment, PreparationError> {
        debug!("Sending single chunk with packet type {packet_type}");
        let topology_permit = self.topology_access.get_read_permit().await;
@@ -660,7 +650,6 @@ where
            &self.config.ack_key,
            &recipient,
            packet_type,
-            trace_id,
        )?;

        Ok(prepared_fragment)
@@ -80,7 +80,6 @@ impl StatisticsControl {
            stats_report.into(),
            TransmissionLane::General,
            None,
-            None,
        );
        if let Err(err) = self.report_tx.send(report_message).await {
            tracing::error!("Failed to report client stats: {err:?}");
@@ -1043,12 +1043,6 @@ impl<C, St> GatewayClient<C, St> {
    }

    // Note: this requires prior authentication
-    #[instrument(skip_all,
-        fields(
-            gateway = %self.gateway_identity,
-            gateway_address = %self.gateway_address
-        )
-    )]
    pub fn start_listening_for_mixnet_messages(&mut self) -> Result<(), GatewayClientError> {
        if !self.authenticated {
            return Err(GatewayClientError::NotAuthenticated);
@@ -136,6 +136,27 @@ pub trait DkgSigningClient {
        self.execute_dkg_contract(fee, req, "trigger DKG resharing".to_string(), vec![])
            .await
    }
+
+    async fn transfer_ownership(
+        &self,
+        transfer_to: String,
+        fee: Option<Fee>,
+    ) -> Result<ExecuteResult, NyxdError> {
+        let req = DkgExecuteMsg::TransferOwnership { transfer_to };
+
+        self.execute_dkg_contract(fee, req, "".to_string(), vec![])
+            .await
+    }
+    async fn update_announce_address(
+        &self,
+        new_address: String,
+        fee: Option<Fee>,
+    ) -> Result<ExecuteResult, NyxdError> {
+        let req = DkgExecuteMsg::UpdateAnnounceAddress { new_address };
+
+        self.execute_dkg_contract(fee, req, "".to_string(), vec![])
+            .await
+    }
 }

 #[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
@@ -168,6 +189,7 @@ where
 mod tests {
    use super::*;
    use crate::nyxd::contract_traits::tests::IgnoreValue;
+    use nym_coconut_dkg_common::msg::ExecuteMsg;

    // it's enough that this compiles and clippy is happy about it
    #[allow(dead_code)]
@@ -210,6 +232,12 @@ mod tests {
            DkgExecuteMsg::AdvanceEpochState {} => client.advance_dkg_epoch_state(None).ignore(),
            DkgExecuteMsg::TriggerReset {} => client.trigger_dkg_reset(None).ignore(),
            DkgExecuteMsg::TriggerResharing {} => client.trigger_dkg_resharing(None).ignore(),
+            ExecuteMsg::TransferOwnership { transfer_to } => {
+                client.transfer_ownership(transfer_to, None).ignore()
+            }
+            ExecuteMsg::UpdateAnnounceAddress { new_address } => {
+                client.update_announce_address(new_address, None).ignore()
+            }
        };
    }
 }
@@ -5,6 +5,16 @@ use crate::types::{EncodedBTEPublicKeyWithProof, NodeIndex};
 use cosmwasm_schema::cw_serde;
 use cosmwasm_std::Addr;

+pub type BlockHeight = u64;
+pub type TransactionIndex = u32;
+
+#[cw_serde]
+pub struct OwnershipTransfer {
+    pub node_index: NodeIndex,
+    pub from: Addr,
+    pub to: Addr,
+}
+
 #[cw_serde]
 pub struct DealerDetails {
    pub address: Addr,
@@ -73,6 +73,17 @@ pub enum ExecuteMsg {
    TriggerReset {},

    TriggerResharing {},
+
+    /// Transfers ownership of the epoch dealer to another address.
+    /// This assumes off-chain hand-over of keys
+    TransferOwnership {
+        transfer_to: String,
+    },
+
+    /// Update announce address of this signer
+    UpdateAnnounceAddress {
+        new_address: String,
+    },
 }

 #[cw_serde]
@@ -20,5 +20,7 @@ rand_chacha = { workspace = true }
 rand = { workspace = true }
 cw-multi-test = { workspace = true }

+nym-contracts-common = { path = "../contracts-common" }
+
 [lints]
 workspace = true
@@ -3,18 +3,98 @@

 use cosmwasm_std::testing::{message_info, MockApi, MockQuerier, MockStorage};
 use cosmwasm_std::{
-    coins, Addr, BankMsg, CosmosMsg, Empty, Env, MemoryStorage, MessageInfo, Order, OwnedDeps,
-    Response, StdResult, Storage,
+    coins, Addr, BankMsg, CosmosMsg, Decimal, Empty, Env, MemoryStorage, MessageInfo, Order,
+    OwnedDeps, Response, StdResult, Storage,
 };
 use cw_storage_plus::{KeyDeserialize, Map, Prefix, PrimaryKey};
+use nym_contracts_common::events::may_find_attribute;
 use rand::{RngCore, SeedableRng};
 use rand_chacha::ChaCha20Rng;
 use serde::de::DeserializeOwned;
 use serde::Serialize;
+use std::fmt::Debug;
+use std::str::FromStr;

 pub const TEST_DENOM: &str = "unym";
 pub const TEST_PREFIX: &str = "n";

+pub trait FindAttribute {
+    fn attribute<E, S>(&self, event_type: E, attribute: &str) -> String
+    where
+        E: Into<Option<S>>,
+        S: Into<String>;
+
+    fn any_attribute(&self, attribute: &str) -> String {
+        self.attribute::<_, String>(None, attribute)
+    }
+
+    fn any_parsed_attribute<T>(&self, attribute: &str) -> T
+    where
+        T: FromStr,
+        <T as FromStr>::Err: Debug,
+    {
+        self.parsed_attribute::<_, String, T>(None, attribute)
+    }
+
+    fn parsed_attribute<E, S, T>(&self, event_type: E, attribute: &str) -> T
+    where
+        E: Into<Option<S>>,
+        S: Into<String>,
+        T: FromStr,
+        <T as FromStr>::Err: Debug;
+
+    fn decimal<E, S>(&self, event_type: E, attribute: &str) -> Decimal
+    where
+        E: Into<Option<S>>,
+        S: Into<String>,
+    {
+        self.parsed_attribute(event_type, attribute)
+    }
+}
+
+#[track_caller]
+pub fn find_attribute<S: Into<String>>(
+    event_type: Option<S>,
+    attribute: &str,
+    response: &Response,
+) -> String {
+    let event_type = event_type.map(Into::into);
+    for event in &response.events {
+        if let Some(typ) = &event_type {
+            if &event.ty != typ {
+                continue;
+            }
+        }
+        if let Some(attr) = may_find_attribute(event, attribute) {
+            return attr;
+        }
+    }
+    // this is only used in tests so panic here is fine
+    panic!("did not find the attribute")
+}
+
+impl FindAttribute for Response {
+    fn attribute<E, S>(&self, event_type: E, attribute: &str) -> String
+    where
+        E: Into<Option<S>>,
+        S: Into<String>,
+    {
+        find_attribute(event_type.into(), attribute, self)
+    }
+
+    fn parsed_attribute<E, S, T>(&self, event_type: E, attribute: &str) -> T
+    where
+        E: Into<Option<S>>,
+        S: Into<String>,
+        T: FromStr,
+        <T as FromStr>::Err: Debug,
+    {
+        find_attribute(event_type.into(), attribute, self)
+            .parse()
+            .unwrap()
+    }
+}
+
 pub fn mock_api() -> MockApi {
    MockApi::default().with_prefix(TEST_PREFIX)
 }
@@ -4,8 +4,8 @@
 use crate::{ContractTester, TestableNymContract};
 use cosmwasm_std::testing::{message_info, mock_env};
 use cosmwasm_std::{
-    from_json, Addr, Coin, ContractInfo, Deps, DepsMut, Env, MessageInfo, Response, StdResult,
-    Storage, Timestamp,
+    from_json, Addr, BlockInfo, Coin, ContractInfo, Deps, DepsMut, Env, MessageInfo, Response,
+    StdResult, Storage, Timestamp,
 };
 use cw_multi_test::{next_block, AppResponse, Executor};
 use serde::de::DeserializeOwned;
@@ -62,6 +62,8 @@ pub trait ContractOpts {
        coins: &[Coin],
        message: Self::ExecuteMsg,
    ) -> Result<Response, Self::ContractError>;
+
+    fn unchecked_contract_address<D: TestableNymContract>(&self) -> Addr;
 }

 impl<C> ContractOpts for ContractTester<C>
@@ -130,14 +132,47 @@ where

        C::execute()(self.deps_mut(), env, info, message)
    }
+
+    fn unchecked_contract_address<D: TestableNymContract>(&self) -> Addr {
+        self.unchecked_contract_address::<D>()
+    }
 }

 pub trait ChainOpts: ContractOpts {
    fn set_contract_balance(&mut self, balance: Coin);

-    fn next_block(&mut self);
+    fn update_block<F: Fn(&mut BlockInfo)>(&mut self, action: F);
+    fn set_to_epoch(&mut self) {
+        self.set_block_time(Timestamp::from_seconds(0))
+    }

-    fn set_block_time(&mut self, time: Timestamp);
+    fn set_to_genesis(&mut self) {
+        self.update_block(|block| {
+            block.height = 1;
+        })
+    }
+
+    fn next_block(&mut self) {
+        self.update_block(next_block)
+    }
+
+    fn advance_day_of_blocks(&mut self) {
+        self.update_block(|block| {
+            block.time = block.time.plus_seconds(24 * 60 * 60);
+            block.height += 17280;
+        })
+    }
+
+    fn advance_time_by(&mut self, delta_secs: u64) {
+        self.update_block(|block| {
+            block.time = block.time.plus_seconds(delta_secs);
+            block.height += 1
+        })
+    }
+
+    fn set_block_time(&mut self, time: Timestamp) {
+        self.update_block(|b| b.time = time)
+    }

    fn execute_msg(
        &mut self,
@@ -186,12 +221,9 @@ where
            )
            .unwrap();
    }
-    fn next_block(&mut self) {
-        self.app.update_block(next_block)
-    }

-    fn set_block_time(&mut self, time: Timestamp) {
-        self.app.update_block(|b| b.time = time)
+    fn update_block<F: Fn(&mut BlockInfo)>(&mut self, action: F) {
+        self.app.update_block(action)
    }

    fn execute_msg(
@@ -11,13 +11,14 @@ use cosmwasm_std::{
 };
 use cw_multi_test::Executor;
 use cw_storage_plus::{Key, Path, PrimaryKey};
-use rand::RngCore;
 use rand_chacha::ChaCha20Rng;
 use serde::de::DeserializeOwned;
 use serde::Serialize;
 use std::any::type_name;
 use std::ops::Deref;

+pub use rand::prelude::*;
+
 pub trait StorageReader {
    fn common_key(&self, key: CommonStorageKeys) -> Option<&[u8]>;

@@ -47,27 +47,11 @@ pub trait TestableNymContract {
    fn query() -> QueryFn<Self::QueryMsg, Self::ContractError>;
    fn migrate() -> PermissionedFn<Self::MigrateMsg, Self::ContractError>;

-    fn base_init_msg() -> Self::InitMsg;
-
-    // // for now we don't care about custom queriers
-    // fn contract_wrapper() -> ContractWrapper<
-    //     Self::ExecuteMsg,
-    //     Self::InitMsg,
-    //     Self::QueryMsg,
-    //     Self::ContractError,
-    //     anyhow::Error,
-    //     anyhow::Error,
-    //     Empty,
-    //     Empty,
-    //     Empty,
-    //     Self::ContractError,
-    //     Self::ContractError,
-    //     Self::MigrateMsg,
-    //     Self::ContractError,
-    // > {
-    //     ContractWrapper::new(Self::execute(), Self::instantiate(), Self::query())
-    //         .with_migrate(Self::migrate())
-    // }
+    // not all instances will require default init message, some will always have to provide customised values
+    #[allow(clippy::unimplemented)]
+    fn base_init_msg() -> Self::InitMsg {
+        unimplemented!("attempted to instantiate contract without defining instantiate message")
+    }

    fn dyn_contract() -> Box<dyn Contract<Empty>> {
        Box::new(
@@ -92,6 +76,7 @@ pub struct ContractTesterBuilder<C> {
    app: App<BankKeeper, MockApi, StorageWrapper>,
    storage: StorageWrapper,
    pub well_known_contracts: HashMap<&'static str, Addr>,
+    code_ids: HashMap<&'static str, u64>,
 }

 impl<C> ContractTesterBuilder<C> {
@@ -125,20 +110,33 @@ impl<C> ContractTesterBuilder<C> {
            app,
            storage,
            well_known_contracts: Default::default(),
+            code_ids: Default::default(),
        }
    }

+    pub fn master_address(&self) -> Addr {
+        self.master_address.clone()
+    }
+
    pub fn instantiate<D: TestableNymContract>(
        mut self,
        custom_init_msg: Option<D::InitMsg>,
    ) -> ContractTesterBuilder<C> {
+        self.instantiate_contract::<D>(custom_init_msg);
+        self
+    }
+
+    pub fn instantiate_contract<D: TestableNymContract>(
+        &mut self,
+        custom_init_msg: Option<D::InitMsg>,
+    ) {
        let code_id = self.app.store_code(D::dyn_contract());
        let contract_address = self
            .app
            .instantiate_contract(
                code_id,
                self.master_address.clone(),
-                &custom_init_msg.unwrap_or(D::base_init_msg()),
+                &custom_init_msg.unwrap_or_else(|| D::base_init_msg()),
                &[],
                D::NAME,
                Some(self.master_address.to_string()),
@@ -154,8 +152,28 @@ impl<C> ContractTesterBuilder<C> {
            )
            .unwrap();

+        self.code_ids.insert(D::NAME, code_id);
        self.well_known_contracts.insert(D::NAME, contract_address);
-        self
+    }
+
+    // uses the SAME code
+    pub fn migrate_contract<D: TestableNymContract>(&mut self, migrate_msg: &D::MigrateMsg) {
+        self.app
+            .migrate_contract(
+                self.master_address.clone(),
+                self.unchecked_contract_address::<D>(),
+                migrate_msg,
+                self.unchecked_contract_code_id::<D>(),
+            )
+            .unwrap();
+    }
+
+    pub fn unchecked_contract_address<D: TestableNymContract>(&self) -> Addr {
+        self.well_known_contracts.get(D::NAME).unwrap().clone()
+    }
+
+    fn unchecked_contract_code_id<D: TestableNymContract>(&self) -> u64 {
+        *self.code_ids.get(D::NAME).unwrap()
    }

    pub fn build(self) -> ContractTester<C>
@@ -229,6 +247,10 @@ where
        self.insert_common_storage_key(key, value);
        self
    }
+
+    pub fn unchecked_contract_address<D: TestableNymContract>(&self) -> Addr {
+        self.well_known_contracts.get(D::NAME).unwrap().clone()
+    }
 }

 impl<C> Storage for ContractTester<C>
@@ -0,0 +1,53 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use cosmwasm_std::{from_json, Binary, CustomQuery, QuerierWrapper, StdResult};
+use serde::de::DeserializeOwned;
+use serde::Serialize;
+
+// re-expose methods from QuerierWrapper as traits so that we could more easily define extension traits
+pub trait ContractQuerier {
+    fn query_contract<T: DeserializeOwned>(
+        &self,
+        address: impl Into<String>,
+        msg: &impl Serialize,
+    ) -> StdResult<T>;
+
+    fn query_contract_storage(
+        &self,
+        address: impl Into<String>,
+        key: impl Into<Binary>,
+    ) -> StdResult<Option<Vec<u8>>>;
+
+    fn query_contract_storage_value<T: DeserializeOwned>(
+        &self,
+        address: impl Into<String>,
+        key: impl Into<Binary>,
+    ) -> StdResult<Option<T>> {
+        match self.query_contract_storage(address, key)? {
+            None => Ok(None),
+            Some(value) => Ok(Some(from_json(&value)?)),
+        }
+    }
+}
+
+impl<C> ContractQuerier for QuerierWrapper<'_, C>
+where
+    C: CustomQuery,
+{
+    fn query_contract<T: DeserializeOwned>(
+        &self,
+        address: impl Into<String>,
+        msg: &impl Serialize,
+    ) -> StdResult<T> {
+        self.query_wasm_smart(address, msg)
+    }
+
+    fn query_contract_storage(
+        &self,
+        address: impl Into<String>,
+        key: impl Into<Binary>,
+    ) -> StdResult<Option<Vec<u8>>> {
+        self.query_wasm_raw(address, key)
+    }
+}
@@ -10,6 +10,7 @@ pub mod events;
 pub mod signing;
 pub mod types;

+pub mod contract_querier;
 pub mod helpers;

 pub use types::*;
@@ -42,6 +42,7 @@ 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 }
@@ -2,12 +2,18 @@
 // 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 {
@@ -76,7 +82,80 @@ impl PerformedDeposits {
    }
 }

-pub(super) fn request_sizes(total: usize, max_request_size: usize) -> impl Iterator<Item = usize> {
+#[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))
@@ -89,13 +168,13 @@ mod tests {
    #[test]
    fn request_sizes_test() {
        assert_eq!(
-            request_sizes(100, 32).collect::<Vec<_>>(),
+            split_deposits(100, 32).collect::<Vec<_>>(),
            vec![32, 32, 32, 4]
        );

-        assert_eq!(request_sizes(10, 32).collect::<Vec<_>>(), vec![10]);
-        assert_eq!(request_sizes(32, 32).collect::<Vec<_>>(), vec![32]);
-        assert_eq!(request_sizes(33, 32).collect::<Vec<_>>(), vec![32, 1]);
-        assert_eq!(request_sizes(1, 32).collect::<Vec<_>>(), vec![1]);
+        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,27 +1,23 @@
 // Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: GPL-3.0-only

-use crate::deposits_buffer::helpers::request_sizes;
 use crate::deposits_buffer::refill_task::RefillTask;
 use crate::error::CredentialProxyError;
 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::{BufferedDeposit, PerformedDeposits};
+pub use helpers::{make_deposits_request, split_deposits, BufferedDeposit, PerformedDeposits};

 pub(crate) mod helpers;
 mod refill_task;
@@ -89,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(
@@ -180,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
@@ -6,17 +6,15 @@

 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 struct CachedEpoch {
@@ -57,74 +55,9 @@ impl CachedEpoch {
    }
 }

-// a map of items that never change for given key
-pub 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 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 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 fn ensure_sane_expiration_date(expiration_date: Date) -> Result<(), CredentialProxyError> {
    let today = ecash_today();

@@ -1,15 +1,37 @@
 // Copyright 2025 Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: GPL-3.0-only

-use crate::nym_api_helpers::{CachedEpoch, CachedImmutableEpochItem, CachedImmutableItems};
+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 nym_compact_ecash::VerificationKeyAuth;
-use nym_credentials::{AggregatedCoinIndicesSignatures, AggregatedExpirationDateSignatures};
+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;
-use tokio::sync::RwLock;
+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,
@@ -46,4 +68,309 @@ impl EcashState {
            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)
+    }
 }
@@ -3,39 +3,26 @@

 use crate::deposits_buffer::{BufferedDeposit, DepositsBuffer};
 use crate::error::CredentialProxyError;
-use crate::nym_api_helpers::{ensure_sane_expiration_date, query_all_threshold_apis};
 use crate::shared_state::ecash_state::EcashState;
 use crate::shared_state::nyxd_client::ChainClient;
 use crate::storage::CredentialProxyStorage;
-use nym_compact_ecash::scheme::coin_indices_signatures::{
-    aggregate_annotated_indices_signatures, CoinIndexSignatureShare,
-};
-use nym_compact_ecash::scheme::expiration_date_signatures::{
-    aggregate_annotated_expiration_signatures, ExpirationDateSignatureShare,
-};
 use nym_compact_ecash::{Base58, PublicKeyUser, VerificationKeyAuth};
 use nym_credential_proxy_requests::api::v1::ticketbook::models::{
    AggregatedCoinIndicesSignaturesResponse, AggregatedExpirationDateSignaturesResponse,
    GlobalDataParams, MasterVerificationKeyResponse,
 };
-use nym_credentials::ecash::utils::EcashTime;
-use nym_credentials::{
-    AggregatedCoinIndicesSignatures, AggregatedExpirationDateSignatures, EpochVerificationKey,
-};
+use nym_credentials::{AggregatedCoinIndicesSignatures, AggregatedExpirationDateSignatures};
 use nym_ecash_contract_common::deposit::DepositId;
-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::{DirectSigningHttpRpcNyxdClient, EcashApiClient};
+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, info, warn};
+use tracing::{debug, error, warn};
 use uuid::Uuid;

 pub mod ecash_state;
@@ -69,10 +56,7 @@ impl CredentialProxyState {
    }

    pub async fn deposit_amount(&self) -> Result<Coin, CredentialProxyError> {
-        self.ecash_state()
-            .required_deposit_cache
-            .get_or_update(self.client())
-            .await
+        self.ecash_state().deposit_amount(self.client()).await
    }

    pub fn client(&self) -> &ChainClient {
@@ -87,29 +71,10 @@ impl CredentialProxyState {
        &self.inner.ecash_state
    }

-    pub(crate) async fn query_chain(&self) -> RwLockReadGuard<'_, DirectSigningHttpRpcNyxdClient> {
-        self.inner.client.query_chain().await
-    }
-
    pub async fn ensure_credentials_issuable(&self) -> Result<(), CredentialProxyError> {
-        let epoch = self.current_epoch().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)
-        }
+        self.ecash_state()
+            .ensure_credentials_issuable(self.client())
+            .await
    }

    pub async fn get_deposit(
@@ -146,33 +111,11 @@ impl CredentialProxyState {
    }

    pub async fn current_epoch_id(&self) -> Result<EpochId, CredentialProxyError> {
-        let read_guard = self.inner.ecash_state.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.inner.ecash_state.cached_epoch.write().await;
-        let epoch = self.query_chain().await.get_current_epoch().await?;
-
-        write_guard.update(epoch);
-        Ok(epoch.epoch_id)
+        self.ecash_state().current_epoch_id(self.client()).await
    }

    pub async fn current_epoch(&self) -> Result<Epoch, CredentialProxyError> {
-        let read_guard = self.ecash_state().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.ecash_state().cached_epoch.write().await;
-        let epoch = self.query_chain().await.get_current_epoch().await?;
-
-        write_guard.update(epoch);
-        Ok(epoch)
+        self.ecash_state().current_epoch(self.client()).await
    }

    pub async fn global_data(
@@ -243,53 +186,8 @@ impl CredentialProxyState {
        &self,
        epoch_id: Option<EpochId>,
    ) -> Result<RwLockReadGuard<'_, VerificationKeyAuth>, CredentialProxyError> {
-        let epoch_id = match epoch_id {
-            Some(id) => id,
-            None => self.current_epoch_id().await?,
-        };
-
-        self.inner
-            .ecash_state
-            .master_verification_key
-            .get_or_init(epoch_id, || async {
-                // 1. check the storage
-                if let Some(stored) = self
-                    .inner
-                    .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(epoch_id).await?;
-                let threshold = self.ecash_threshold(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
-                self.inner
-                    .storage
-                    .insert_master_verification_key(&epoch)
-                    .await?;
-
-                Ok(epoch.key)
-            })
+        self.ecash_state()
+            .master_verification_key(self.client(), self.storage(), epoch_id)
            .await
    }

@@ -297,75 +195,8 @@ impl CredentialProxyState {
        &self,
        epoch_id: Option<EpochId>,
    ) -> Result<RwLockReadGuard<'_, AggregatedCoinIndicesSignatures>, CredentialProxyError> {
-        let epoch_id = match epoch_id {
-            Some(id) => id,
-            None => self.current_epoch_id().await?,
-        };
-
-        self.inner
-            .ecash_state
-            .coin_index_signatures
-            .get_or_init(epoch_id, || async {
-                // 1. check the storage
-                if let Some(master_sigs) = self
-                    .inner
-                    .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(Some(epoch_id)).await?;
-                let all_apis = self.ecash_clients(epoch_id).await?;
-                let threshold = self.ecash_threshold(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
-                self.inner
-                    .storage
-                    .insert_master_coin_index_signatures(&sigs)
-                    .await?;
-
-                Ok(sigs)
-            })
+        self.ecash_state()
+            .master_coin_index_signatures(self.client(), self.storage(), epoch_id)
            .await
    }

@@ -374,73 +205,13 @@ impl CredentialProxyState {
        epoch_id: EpochId,
        expiration_date: Date,
    ) -> Result<RwLockReadGuard<'_, AggregatedExpirationDateSignatures>, CredentialProxyError> {
-        self.inner.ecash_state
-            .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) = self
-                    .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().await?;
-                let master_vk = self.master_verification_key(Some(epoch_id)).await?;
-                let all_apis = self.ecash_clients(epoch_id).await?;
-                let threshold = self.ecash_threshold(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
-                self.inner.storage
-                    .insert_master_expiration_date_signatures(&sigs)
-                    .await?;
-
-                Ok(sigs)
-            })
+        self.ecash_state()
+            .master_expiration_date_signatures(
+                self.client(),
+                self.storage(),
+                epoch_id,
+                expiration_date,
+            )
            .await
    }

@@ -448,40 +219,15 @@ impl CredentialProxyState {
        &self,
        epoch_id: EpochId,
    ) -> Result<RwLockReadGuard<'_, Vec<EcashApiClient>>, CredentialProxyError> {
-        self.inner
-            .ecash_state
-            .epoch_clients
-            .get_or_init(epoch_id, || async {
-                Ok(self
-                    .query_chain()
-                    .await
-                    .get_all_verification_key_shares(epoch_id)
-                    .await?
-                    .into_iter()
-                    .map(TryInto::try_into)
-                    .collect::<anyhow::Result<Vec<_>, EcashApiError>>()?)
-            })
+        self.ecash_state()
+            .ecash_clients(self.client(), epoch_id)
            .await
    }

    pub async fn ecash_threshold(&self, epoch_id: EpochId) -> Result<u64, CredentialProxyError> {
-        self.inner
-            .ecash_state
-            .threshold_values
-            .get_or_init(epoch_id, || async {
-                if let Some(threshold) = self
-                    .query_chain()
-                    .await
-                    .get_epoch_threshold(epoch_id)
-                    .await?
-                {
-                    Ok(threshold)
-                } else {
-                    Err(CredentialProxyError::UnavailableThreshold { epoch_id })
-                }
-            })
+        self.ecash_state()
+            .ecash_threshold(self.client(), epoch_id)
            .await
-            .map(|t| *t)
    }
 }

@@ -6,7 +6,7 @@ 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, CosmWasmClient, NyxdClient};
+use nym_validator_client::nyxd::{Coin, Config, CosmWasmClient, NyxdClient};
 use nym_validator_client::{nyxd, DirectSigningHttpRpcNyxdClient};
 use std::ops::Deref;
 use std::sync::Arc;
@@ -29,6 +29,14 @@ impl ChainClient {
            .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() {
@@ -68,17 +76,15 @@ pub struct ChainWritePermit<'a> {
 }

 impl ChainWritePermit<'_> {
-    #[instrument(skip(self, short_sha, info), err(Display))]
+    #[instrument(skip(self, memo, info), err(Display))]
    pub async fn make_deposits(
        self,
-        short_sha: &'static str,
+        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 deposits = info.len();
-
        let ecash_contract = self
            .inner
            .ecash_contract_address()
@@ -95,12 +101,7 @@ impl ChainWritePermit<'_> {

        let res = self
            .inner
-            .execute_multiple(
-                ecash_contract,
-                deposit_messages,
-                None,
-                format!("cp-{short_sha}: performing {deposits} deposits"),
-            )
+            .execute_multiple(ecash_contract, deposit_messages, None, memo)
            .await?;

        loop {
@@ -26,6 +26,7 @@ use uuid::Uuid;
 mod manager;
 pub mod models;
 pub(crate) mod pruner;
+pub mod traits;

 // TODO: proper import
 type NodeId = u64;
@@ -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
+    }
+}
@@ -11,7 +11,7 @@ use crate::shared_state::CredentialProxyState;
 use crate::storage::pruner::StoragePruner;
 use crate::storage::CredentialProxyStorage;
 use crate::webhook::ZkNymWebhook;
-use nym_credentials::ecash::utils::ecash_today;
+use nym_credentials::ecash::utils::ecash_default_expiration_date;
 use nym_validator_client::nym_api::EpochId;
 use std::future::Future;
 use std::time::Duration;
@@ -100,7 +100,7 @@ impl TicketbookManager {
    }

    async fn build_initial_cache(&self) -> Result<(), CredentialProxyError> {
-        let today = ecash_today().date();
+        let default_expiration = ecash_default_expiration_date();

        let epoch_id = self.state.current_epoch_id().await?;
        let _ = self.state.deposit_amount().await?;
@@ -113,7 +113,7 @@ impl TicketbookManager {
            .await?;
        let _ = self
            .state
-            .master_expiration_date_signatures(epoch_id, today)
+            .master_expiration_date_signatures(epoch_id, default_expiration)
            .await?;

        Ok(())
@@ -33,6 +33,14 @@ workspace = true
 features = ["rt-multi-thread", "net", "signal", "fs"]


+[dev-dependencies]
+anyhow = { workspace = true }
+nym-crypto = { path = "../crypto", features = ["asymmetric", "rand"] }
+nym-test-utils = { path = "../test-utils" }
+nym-credentials-interface = { path = "../credentials-interface" }
+nym-compact-ecash = { path = "../nym_offline_compact_ecash" }
+
+
 [build-dependencies]
 anyhow = { workspace = true }
 sqlx = { workspace = true, features = [
@@ -44,6 +44,7 @@ impl EcashCredentialManagerInner {
 fn hack_clone_ticketbook(book: &IssuedTicketBook) -> IssuedTicketBook {
    let ser = book.pack();
    let data = Zeroizing::new(ser.data);
+    #[allow(clippy::unwrap_used)]
    IssuedTicketBook::try_unpack(&data, None).unwrap()
 }

@@ -79,18 +80,24 @@ impl MemoryEcachTicketbookManager {
        let mut guard = self.inner.write().await;

        for t in guard.ticketbooks.values_mut() {
-            if !t.ticketbook.expired()
-                && t.ticketbook.spent_tickets() + tickets as u64
-                    <= t.ticketbook.params_total_tickets()
-                && t.ticketbook.ticketbook_type().to_string() == ticketbook_type
-            {
-                t.ticketbook
-                    .update_spent_tickets(t.ticketbook.spent_tickets() + tickets as u64);
-                return Some(RetrievedTicketbook {
-                    ticketbook_id: t.ticketbook_id,
-                    ticketbook: hack_clone_ticketbook(&t.ticketbook),
-                });
+            if t.ticketbook.expired() {
+                continue;
            }
+            if t.ticketbook.spent_tickets() + tickets as u64 > t.total_tickets as u64 {
+                continue;
+            }
+            if t.ticketbook.ticketbook_type().to_string() != ticketbook_type {
+                continue;
+            }
+
+            let cloned = hack_clone_ticketbook(&t.ticketbook);
+            t.ticketbook
+                .update_spent_tickets(t.ticketbook.spent_tickets() + tickets as u64);
+            return Some(RetrievedTicketbook {
+                ticketbook_id: t.ticketbook_id,
+                total_tickets: t.total_tickets,
+                ticketbook: cloned,
+            });
        }

        None
@@ -156,18 +163,25 @@ impl MemoryEcachTicketbookManager {
        guard.pending.remove(&pending_id);
    }

-    pub(crate) async fn insert_new_ticketbook(&self, ticketbook: &IssuedTicketBook) {
+    pub(crate) async fn insert_new_ticketbook(
+        &self,
+        ticketbook: &IssuedTicketBook,
+        total_tickets: u32,
+        used_tickets: u32,
+    ) {
        let mut guard = self.inner.write().await;
        let id = guard.next_id();

-        // hehe, that's hacky AF, but it works as a **TEMPORARY** workaround
-        let ser = ticketbook.pack();
-        let data = Zeroizing::new(ser.data);
+        #[allow(clippy::unwrap_used)]
+        let mut nasty_clone = hack_clone_ticketbook(ticketbook);
+        nasty_clone.update_spent_tickets(used_tickets as u64);
+
        guard.ticketbooks.insert(
            id,
            RetrievedTicketbook {
                ticketbook_id: id,
-                ticketbook: IssuedTicketBook::try_unpack(&data, None).unwrap(),
+                total_tickets,
+                ticketbook: nasty_clone,
            },
        );
    }
@@ -199,7 +213,7 @@ impl MemoryEcachTicketbookManager {
                ticketbook_type: t.ticketbook.ticketbook_type().to_string(),
                epoch_id: t.ticketbook.epoch_id() as u32,
                total_tickets: t.ticketbook.spent_tickets() as u32,
-                used_tickets: t.ticketbook.params_total_tickets() as u32,
+                used_tickets: t.total_tickets,
            })
            .collect()
    }
@@ -66,7 +66,42 @@ impl Storage for EphemeralStorage {
        &self,
        ticketbook: &IssuedTicketBook,
    ) -> Result<(), StorageError> {
-        self.storage_manager.insert_new_ticketbook(ticketbook).await;
+        self.storage_manager
+            .insert_new_ticketbook(
+                ticketbook,
+                ticketbook.params_total_tickets() as u32,
+                ticketbook.spent_tickets() as u32,
+            )
+            .await;
+        Ok(())
+    }
+
+    async fn insert_partial_issued_ticketbook(
+        &self,
+        ticketbook: &IssuedTicketBook,
+        allowed_start_ticket_index: u32,
+        allowed_final_ticket_index: u32,
+    ) -> Result<(), Self::StorageError> {
+        // sanity check: start <= final && final <= params max
+        if allowed_start_ticket_index > allowed_final_ticket_index {
+            return Err(StorageError::database_inconsistency(
+                "start_ticket_index must be less than or equal to final_ticket_index",
+            ));
+        }
+
+        if allowed_final_ticket_index > ticketbook.params_total_tickets() as u32 {
+            return Err(StorageError::database_inconsistency(
+                "final ticket index must be less than or equal to params_total_tickets()",
+            ));
+        }
+
+        self.storage_manager
+            .insert_new_ticketbook(
+                ticketbook,
+                allowed_final_ticket_index + 1,
+                allowed_start_ticket_index,
+            )
+            .await;
        Ok(())
    }

@@ -184,3 +219,104 @@ impl Storage for EphemeralStorage {
        Ok(())
    }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use nym_compact_ecash::tests::helpers::generate_expiration_date_signatures;
+    use nym_compact_ecash::{issue, ttp_keygen};
+    use nym_credentials_interface::TicketType;
+    use nym_crypto::asymmetric::ed25519;
+    use nym_ecash_time::EcashTime;
+    use nym_test_utils::helpers::deterministic_rng;
+
+    fn mock_ticketbook() -> anyhow::Result<IssuedTicketBook> {
+        let signing_keys = ttp_keygen(1, 1)?.remove(0);
+
+        let deposit_id = 42;
+        let identifier = "foomp";
+        let mut rng = deterministic_rng();
+        let key = ed25519::PrivateKey::new(&mut rng);
+        let typ = TicketType::V1MixnetEntry;
+
+        let issuance = IssuanceTicketBook::new(deposit_id, identifier, key, typ);
+        let expiration_date = issuance.expiration_date();
+
+        let sig_req = issuance.prepare_for_signing();
+        let _exp_date_sigs = generate_expiration_date_signatures(
+            sig_req.expiration_date.ecash_unix_timestamp(),
+            &[signing_keys.secret_key()],
+            &vec![signing_keys.verification_key()],
+            &signing_keys.verification_key(),
+            &[1],
+        )?;
+        let blind_sig = issue(
+            signing_keys.secret_key(),
+            sig_req.ecash_pub_key,
+            &sig_req.withdrawal_request,
+            expiration_date.ecash_unix_timestamp(),
+            issuance.ticketbook_type().encode(),
+        )?;
+
+        let partial_wallet =
+            issuance.unblind_signature(&signing_keys.verification_key(), &sig_req, blind_sig, 1)?;
+
+        let wallet = issuance.aggregate_signature_shares(
+            &signing_keys.verification_key(),
+            &vec![partial_wallet],
+            sig_req,
+        )?;
+
+        Ok(issuance.into_issued_ticketbook(wallet, 1))
+    }
+
+    #[tokio::test]
+    async fn storing_partial_ticketbook() -> anyhow::Result<()> {
+        let storage = EphemeralStorage::default();
+        let ticketbook = mock_ticketbook()?;
+        let typ = ticketbook.ticketbook_type();
+
+        storage
+            .insert_partial_issued_ticketbook(&ticketbook, 5, 5)
+            .await?;
+        let retrieved = storage
+            .get_next_unspent_usable_ticketbook(typ.to_string(), 1)
+            .await?;
+        assert!(retrieved.is_some());
+        let val = retrieved.unwrap();
+        assert_eq!(val.total_tickets, 6);
+        assert_eq!(val.ticketbook.spent_tickets(), 5);
+
+        // we only had 1 ticket
+        let retrieved2 = storage
+            .get_next_unspent_usable_ticketbook(typ.to_string(), 1)
+            .await?;
+        assert!(retrieved2.is_none());
+
+        let _another = mock_ticketbook()?;
+        let typ = ticketbook.ticketbook_type();
+
+        // 3 tickets (4, 5, 6)
+        storage
+            .insert_partial_issued_ticketbook(&ticketbook, 4, 6)
+            .await?;
+        assert!(storage
+            .get_next_unspent_usable_ticketbook(typ.to_string(), 1)
+            .await?
+            .is_some());
+        assert!(storage
+            .get_next_unspent_usable_ticketbook(typ.to_string(), 1)
+            .await?
+            .is_some());
+        assert!(storage
+            .get_next_unspent_usable_ticketbook(typ.to_string(), 1)
+            .await?
+            .is_some());
+        assert!(storage
+            .get_next_unspent_usable_ticketbook(typ.to_string(), 1)
+            .await?
+            .is_none());
+
+        Ok(())
+    }
+}
@@ -7,6 +7,7 @@ use zeroize::{Zeroize, ZeroizeOnDrop};

 pub struct RetrievedTicketbook {
    pub ticketbook_id: i64,
+    pub total_tickets: u32,
    pub ticketbook: IssuedTicketBook,
 }

@@ -149,6 +149,44 @@ impl Storage for PersistentStorage {
        Ok(())
    }

+    async fn insert_partial_issued_ticketbook(
+        &self,
+        ticketbook: &IssuedTicketBook,
+        allowed_start_ticket_index: u32,
+        allowed_final_ticket_index: u32,
+    ) -> Result<(), Self::StorageError> {
+        // sanity check: start <= final && final <= params max
+        if allowed_start_ticket_index > allowed_final_ticket_index {
+            return Err(StorageError::database_inconsistency(
+                "start_ticket_index must be less than or equal to final_ticket_index",
+            ));
+        }
+
+        if allowed_final_ticket_index > ticketbook.params_total_tickets() as u32 {
+            return Err(StorageError::database_inconsistency(
+                "final ticket index must be less than or equal to params_total_tickets()",
+            ));
+        }
+
+        let ser = ticketbook.pack();
+        let data = Zeroizing::new(ser.data);
+        let serialisation_revision = ser.revision;
+
+        self.storage_manager
+            .insert_new_ticketbook(
+                serialisation_revision,
+                &data,
+                ticketbook.expiration_date(),
+                &ticketbook.ticketbook_type().to_string(),
+                ticketbook.epoch_id() as u32,
+                allowed_final_ticket_index + 1,
+                allowed_start_ticket_index,
+            )
+            .await?;
+
+        Ok(())
+    }
+
    async fn contains_issued_ticketbook(
        &self,
        ticketbook: &IssuedTicketBook,
@@ -235,6 +273,7 @@ impl Storage for PersistentStorage {
        deserialised.update_spent_tickets(raw.used_tickets as u64);
        Ok(Some(RetrievedTicketbook {
            ticketbook_id: raw.id,
+            total_tickets: raw.total_tickets,
            ticketbook: deserialised,
        }))
    }
@@ -3,8 +3,6 @@

 use crate::models::{BasicTicketbookInformation, RetrievedPendingTicketbook, RetrievedTicketbook};
 use async_trait::async_trait;
-use nym_compact_ecash::scheme::coin_indices_signatures::AnnotatedCoinIndexSignature;
-use nym_compact_ecash::scheme::expiration_date_signatures::AnnotatedExpirationDateSignature;
 use nym_compact_ecash::VerificationKeyAuth;
 use nym_credentials::ecash::bandwidth::serialiser::keys::EpochVerificationKey;
 use nym_credentials::ecash::bandwidth::serialiser::signatures::{
@@ -14,6 +12,9 @@ use nym_credentials::{IssuanceTicketBook, IssuedTicketBook};
 use nym_ecash_time::Date;
 use std::error::Error;

+pub use nym_compact_ecash::scheme::coin_indices_signatures::AnnotatedCoinIndexSignature;
+pub use nym_compact_ecash::scheme::expiration_date_signatures::AnnotatedExpirationDateSignature;
+
 // for future reference, if you want to make a query for "how much bandwidth do we have left"
 // do something along the lines of
 // `SELECT total_tickets, used_tickets FROM ecash_ticketbook WHERE expiration_date >= ?`, today_date
@@ -37,6 +38,14 @@ pub trait Storage: Clone + Send + Sync {
        ticketbook: &IssuedTicketBook,
    ) -> Result<(), Self::StorageError>;

+    // note that both start and final are **INCLUSIVE**
+    async fn insert_partial_issued_ticketbook(
+        &self,
+        ticketbook: &IssuedTicketBook,
+        allowed_start_ticket_index: u32,
+        allowed_final_ticket_index: u32,
+    ) -> Result<(), Self::StorageError>;
+
    async fn contains_issued_ticketbook(
        &self,
        ticketbook: &IssuedTicketBook,
@@ -1,7 +1,6 @@
 // Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

-use nym_network_defaults::TicketTypeRepr;
 use rand::Rng;
 use serde::{Deserialize, Serialize};
 use thiserror::Error;
@@ -29,6 +28,7 @@ pub use nym_compact_ecash::{
    PartialWallet, PayInfo, PublicKeyUser, SecretKeyUser, VerificationKeyAuth, WithdrawalRequest,
 };
 pub use nym_ecash_time::{ecash_today, EcashTime};
+pub use nym_network_defaults::TicketTypeRepr;

 #[derive(Debug, Clone)]
 pub struct CredentialSigningData {
@@ -64,6 +64,22 @@ impl IssuanceTicketBook {
        expiration_date: Date,
    ) -> Self {
        let ecash_keypair = generate_keypair_user_from_seed(identifier);
+        Self::new_with_keypair(
+            deposit_id,
+            ecash_keypair,
+            signing_key,
+            ticketbook_type,
+            expiration_date,
+        )
+    }
+
+    pub fn new_with_keypair(
+        deposit_id: DepositId,
+        ecash_keypair: KeyPairUser,
+        signing_key: ed25519::PrivateKey,
+        ticketbook_type: TicketType,
+        expiration_date: Date,
+    ) -> Self {
        IssuanceTicketBook {
            deposit_id,
            signing_key,
@@ -103,10 +103,14 @@ impl IssuedTicketBook {
        self.expiration_date < ecash_today().date()
    }

-    pub fn params_total_tickets(&self) -> u64 {
+    pub fn global_total_tickets() -> u64 {
        nym_credentials_interface::ecash_parameters().get_total_coins()
    }

+    pub fn params_total_tickets(&self) -> u64 {
+        Self::global_total_tickets()
+    }
+
    pub fn spent_tickets(&self) -> u64 {
        self.spent_tickets
    }
@@ -17,7 +17,6 @@ pub struct VersionSerialised<T: ?Sized> {
    pub data: Vec<u8>,
    pub revision: u8,

-    // still wondering if there's any point in having the phantom in here
    #[zeroize(skip)]
    #[serde(skip)]
    _phantom: PhantomData<T>,
@@ -13,7 +13,9 @@ use nym_validator_client::client::EcashApiClient;
 use nym_validator_client::nym_api::NymApiClientExt;

 // so we wouldn't break all the existing imports
-pub use nym_ecash_time::{cred_exp_date, ecash_date_offset, ecash_today, EcashTime};
+pub use nym_ecash_time::{
+    cred_exp_date, ecash_date_offset, ecash_default_expiration_date, ecash_today, EcashTime,
+};

 pub fn aggregate_verification_keys(
    api_clients: &[EcashApiClient],
@@ -19,11 +19,11 @@ serde = { workspace = true, features = ["derive"] }
 serde_json = { workspace = true }
 strum = { workspace = true }
 thiserror = { workspace = true }
+tracing = { workspace = true, features = ["log"] }
 time = { workspace = true }
 subtle = { workspace = true }
 zeroize = { workspace = true }

-nym-bin-common = { path = "../bin-common" }
 nym-crypto = { path = "../crypto", features = ["aead", "hashing"] }
 nym-pemstore = { path = "../pemstore" }
 nym-sphinx = { path = "../nymsphinx" }
@@ -34,11 +34,6 @@ nym-task = { path = "../task" }
 nym-credentials = { path = "../credentials" }
 nym-credentials-interface = { path = "../credentials-interface" }

-opentelemetry = { workspace = true, features = ["trace"], optional = true }
-opentelemetry_sdk = { workspace = true, optional = true }
-tracing-opentelemetry = { workspace = true, optional = true }
-tracing = { workspace = true, features = ["std", "attributes", "tracing-attributes"] }
-
 [target."cfg(not(target_arch = \"wasm32\"))".dependencies.tokio]
 workspace = true
 features = ["time"]
@@ -56,12 +51,3 @@ anyhow = { workspace = true }
 nym-compact-ecash = { path = "../nym_offline_compact_ecash" } # we need specific imports in tests
 nym-test-utils = { path = "../test-utils" }
 tokio = { workspace = true, features = ["full"] }
-
-[features]
-default = []
-otel = [
-    "nym-bin-common/otel",
-    "opentelemetry",
-    "opentelemetry_sdk",
-    "tracing-opentelemetry",
-]
@@ -4,7 +4,6 @@
 use crate::{AuthenticationFailure, GatewayRequestsError, SharedGatewayKey};
 use nym_crypto::asymmetric::ed25519;
 use serde::{Deserialize, Serialize};
-use std::collections::HashMap;
 use std::iter;
 use std::time::Duration;
 use subtle::ConstantTimeEq;
@@ -17,9 +16,6 @@ pub struct AuthenticateRequest {
    pub content: AuthenticateRequestContent,

    pub request_signature: ed25519::Signature,
-
-    #[serde(default)]
-    pub otel_context: Option<HashMap<String, String>>,
 }

 impl AuthenticateRequest {
@@ -27,7 +23,6 @@ impl AuthenticateRequest {
        protocol_version: u8,
        shared_key: &SharedGatewayKey,
        identity_keys: &ed25519::KeyPair,
-        otel_context: Option<HashMap<String, String>>,
    ) -> Result<AuthenticateRequest, GatewayRequestsError> {
        let content = AuthenticateRequestContent::new(
            protocol_version,
@@ -40,7 +35,6 @@ impl AuthenticateRequest {
        Ok(AuthenticateRequest {
            content,
            request_signature,
-            otel_context,
        })
    }

@@ -8,16 +8,12 @@ use crate::{
    AUTHENTICATE_V2_PROTOCOL_VERSION, CREDENTIAL_UPDATE_V2_PROTOCOL_VERSION,
    INITIAL_PROTOCOL_VERSION,
 };
-#[cfg(feature = "otel")]
-use nym_bin_common::opentelemetry::context::ContextCarrier;
 use nym_credentials_interface::CredentialSpendingData;
 use nym_crypto::asymmetric::ed25519;
 use nym_sphinx::DestinationAddressBytes;
 use nym_statistics_common::types::SessionType;
 use serde::{Deserialize, Serialize};
-use std::collections::HashMap;
 use std::str::FromStr;
-use tracing::{instrument, warn};
 use tungstenite::Message;

 pub mod authenticate;
@@ -80,13 +76,8 @@ pub enum ClientControlRequest {
        address: String,
        enc_address: String,
        iv: String,
-        /// this is a trace id that is used in testing and performance verification
-        /// in mainnet, this will always be set to None
-        #[serde(default)]
-        otel_context: Option<HashMap<String, String>>,
    },

-
    AuthenticateV2(Box<AuthenticateRequest>),

    #[serde(alias = "handshakePayload")]
@@ -136,25 +127,14 @@ impl ClientControlRequest {
        let nonce = shared_key.random_nonce_or_iv();
        let ciphertext = shared_key.encrypt_naive(address.as_bytes_ref(), Some(&nonce))?;

-        #[cfg(feature = "otel")]
-        let context_carrier = {
-            let context = opentelemetry::Context::current();
-            ContextCarrier::new_with_current_context(context).into_map()
-        };
-
        Ok(ClientControlRequest::Authenticate {
            protocol_version,
            address: address.as_base58_string(),
            enc_address: bs58::encode(&ciphertext).into_string(),
            iv: bs58::encode(&nonce).into_string(),
-            #[cfg(feature = "otel")]
-            otel_context: Some(context_carrier),
-            #[cfg(not(feature = "otel"))]
-            otel_context: None,
        })
    }

-    #[instrument]
    pub fn new_authenticate_v2(
        shared_key: &SharedGatewayKey,
        identity_keys: &ed25519::KeyPair,
@@ -162,27 +142,8 @@ impl ClientControlRequest {
        // if we're using v2 authentication, we must announce at least that protocol version
        let protocol_version = AUTHENTICATE_V2_PROTOCOL_VERSION;

-        #[cfg(feature = "otel")]
-        let context_carrier = {
-            use nym_bin_common::opentelemetry::context::extract_trace_id_from_tracing_cx;
-            let trace_id = extract_trace_id_from_tracing_cx();
-
-            use tracing_opentelemetry::OpenTelemetrySpanExt;
-
-            let current_span = tracing::Span::current();
-            let otel_context = current_span.context();
-            ContextCarrier::new_with_current_context(otel_context).into_map()
-        };
-        #[cfg(not(feature = "otel"))]
-        let context_carrier: HashMap<String, String> = HashMap::new();
-
        Ok(ClientControlRequest::AuthenticateV2(Box::new(
-            AuthenticateRequest::new(
-                protocol_version,
-                shared_key,
-                identity_keys,
-                Some(context_carrier)
-            )?,
+            AuthenticateRequest::new(protocol_version, shared_key, identity_keys)?,
        )))
    }

@@ -11,11 +11,9 @@ license.workspace = true
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

 [features]
-# TODO: Remove otel from default before release
 default=["tunneling"]
 tunneling=[]
 network-defaults = ["dep:nym-network-defaults"]
-otel = ["nym-bin-common/otel", "opentelemetry", "opentelemetry_sdk"]
 debug-inventory = ["nym-http-api-client-macro/debug-inventory"]

 [dependencies]
@@ -26,8 +24,6 @@ reqwest = { workspace = true, features = ["json", "gzip", "deflate", "brotli", "
 http.workspace = true
 url = { workspace = true }
 once_cell = { workspace = true }
-opentelemetry = { workspace = true, optional = true }
-opentelemetry_sdk = { workspace = true, optional = true }
 serde = { workspace = true }
 serde_json = { workspace = true }
 serde_yaml = { workspace = true}
@@ -57,3 +53,4 @@ features = ["tokio"]

 [dev-dependencies]
 tokio = { workspace = true, features = ["rt", "macros"] }
+
@@ -976,22 +976,6 @@ impl ApiClientCore for Client {

        self.apply_hosts_to_req(&mut req);

-        // if opentelemetry is activated add the current trace context to the request
-        #[cfg(feature = "otel")]
-        {
-            use opentelemetry::Context;
-            use nym_bin_common::opentelemetry::context::ContextCarrier;
-
-            let carrier = ContextCarrier::new_with_current_context(Context::current());
-
-            if let Some(traceparent) = carrier.extract_traceparent() {
-                if let Ok(header_value) = HeaderValue::from_str(&traceparent) {
-                    req.headers_mut()
-                        .insert("traceparent", header_value);
-                }
-            }
-        }
-
        let mut rb = RequestBuilder::from_parts(self.reqwest_client.clone(), req);

        rb = rb
@@ -18,7 +18,6 @@ bytes = { workspace = true, optional = true }
 colored = { workspace = true, optional = true }
 futures = { workspace = true, optional = true }
 mime = { workspace = true, optional = true }
-nym-bin-common = { path = "../bin-common" }
 serde = { workspace = true, features = ["derive"] }
 serde_json = { workspace = true }
 serde_yaml = { workspace = true, optional = true }
@@ -50,8 +49,6 @@ middleware = [
    "zeroize"
 ]

-otel = ["nym-bin-common/otel"]
-
 utoipa = ["dep:utoipa"]

 [lints]
@@ -56,16 +56,6 @@ async fn log_request(

    let host = header_map(request.headers().get(HOST), "Unknown Host".to_string());

-    // Extract traceparent from headers if it exists
-    #[cfg(feature = "otel")]
-    let traceparent = request
-        .headers()
-        .get("traceparent")
-        .and_then(|h| h.to_str().ok())
-        .map(|s| s.to_string());
-    #[cfg(not(feature = "otel"))]
-    let traceparent: Option<String> = None;
-
    let start = Instant::now();
    // run request through all middleware, incl. extractors
    let res = next.run(request).await;
@@ -92,10 +82,10 @@ async fn log_request(

    match level {
        LogLevel::Debug => debug!(
-            "[{addr} -> {host}] {method} '{uri}': {print_status} {time_taken} {agent_str}: {agent} traceparent: {traceparent:?}",
+            "[{addr} -> {host}] {method} '{uri}': {print_status} {time_taken} {agent_str}: {agent}"
        ),
        LogLevel::Info => info!(
-            "[{addr} -> {host}] {method} '{uri}': {print_status} {time_taken} {agent_str}: {agent} traceparent: {traceparent:?}"
+            "[{addr} -> {host}] {method} '{uri}': {print_status} {time_taken} {agent_str}: {agent}"
        ),
    }

@@ -231,7 +231,6 @@ where
            &address,
            &address,
            PacketType::Mix,
-            None
        )?)
    }

@@ -0,0 +1,17 @@
+[package]
+name = "nym-cache"
+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]
+tokio = { workspace = true, features = ["sync"] }
+
+[lints]
+workspace = true
@@ -0,0 +1,77 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use std::collections::HashMap;
+use std::future::Future;
+use std::hash::Hash;
+use std::ops::Deref;
+use tokio::sync::{RwLock, RwLockReadGuard};
+
+/// A map of items that never change for given key
+pub struct CachedImmutableItems<K, V> {
+    // I wonder if there's a more efficient structure with OnceLock or OnceCell or something
+    inner: RwLock<HashMap<K, V>>,
+}
+
+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 async fn get_or_init<F, U, E>(
+        &self,
+        key: K,
+        initialiser: 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 = initialiser().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()))
+    }
+}
@@ -8,14 +8,12 @@ license = { workspace = true }
 repository = { workspace = true }

 [dependencies]
-sphinx-packet = { workspace = true }
 tracing = { workspace = true }
 rand = { workspace = true }
 rand_distr = { workspace = true }
 rand_chacha = { workspace = true }
 thiserror = { workspace = true }

-nym-bin-common = { path = "../bin-common" }
 nym-sphinx-acknowledgements = { path = "acknowledgements" }
 nym-sphinx-addressing = { path = "addressing" }
 nym-sphinx-anonymous-replies = { path = "anonymous-replies" }
@@ -57,7 +55,3 @@ outfox = [
    "nym-sphinx-params/outfox",
    "nym-sphinx-types/outfox",
 ]
-
-otel = [
-    "nym-bin-common/otel",
-] 
@@ -59,7 +59,7 @@ impl SurbAck {
        };

        let delays = nym_sphinx_routing::generate_hop_delays(average_delay, route.len());
-        let destination = recipient.as_sphinx_destination(None);
+        let destination = recipient.as_sphinx_destination();

        let surb_ack_payload = prepare_identifier(rng, ack_key, marshaled_fragment_id);
        let packet_size = match packet_type {
@@ -8,20 +8,14 @@ license = { workspace = true }
 repository = { workspace = true }

 [dependencies]
-nym-bin-common = { path = "../../bin-common", features = ["opentelemetry"] } # for trace id compression/decompression
 nym-crypto = { path = "../../crypto", features = ["asymmetric", "sphinx"] } # all addresses are expressed in terms on their crypto keys
 nym-sphinx-types = { path = "../types", features = ["sphinx"] } # we need to be able to refer to some types defined inside sphinx crate
 serde = { workspace = true } # implementing serialization/deserialization for some types, like `Recipient`
 thiserror = { workspace = true }
-tracing = { workspace = true }

 [dev-dependencies]
 rand = { workspace = true }
 nym-crypto = { path = "../../crypto", features = ["rand"] }
 bincode = { workspace = true }
 serde_json = { workspace = true }
-serde = { workspace = true, features = ["derive"] }
-
-[features]
-default = []
-otel = ["nym-bin-common/otel"]
+serde = { workspace = true, features = ["derive"] }
@@ -150,26 +150,12 @@ impl Recipient {
    // TODO: Currently the `DestinationAddress` is equivalent to `ClientIdentity`, but perhaps
    // it shouldn't be? Maybe it should be (for example) H(`ClientIdentity || ClientEncryptionKey`)
    // instead? That is an open question.
-    pub fn as_sphinx_destination(&self, trace_id: Option<[u8; 12]>) -> Destination {
-        #[cfg(feature = "otel")]
-        use nym_bin_common::opentelemetry::compact_id_generator::decompress_trace_id;
-        #[cfg(feature = "otel")]
-        let trace_id_16 = if let Some(trace_id) = trace_id {
-            decompress_trace_id(&trace_id)
-        } else {
-            decompress_trace_id(&[0u8; 12])
-        };
-        #[cfg(not(feature = "otel"))]
-        let trace_id_16 = {
-            _ = trace_id;
-            [0u8; 16]
-        };
-
+    pub fn as_sphinx_destination(&self) -> Destination {
        // since the nym mix network differs slightly in design from loopix, we do not care
        // about "surb_id" field at all and just use the default value.
        Destination::new(
            self.client_identity.derive_destination_address(),
-            trace_id_16,
+            Default::default(),
        )
    }

@@ -82,7 +82,7 @@ impl ReplySurb {
            topology.random_route_to_egress(rng, recipient.gateway())?
        };
        let delays = nym_sphinx_routing::generate_hop_delays(average_delay, route.len());
-        let destination = recipient.as_sphinx_destination(None);
+        let destination = recipient.as_sphinx_destination();

        let mut surb_material = SURBMaterial::new(route, delays, destination);
        if use_legacy_surb_format && !disable_mix_hops {
@@ -125,7 +125,7 @@ where

    let route = topology.random_route_to_egress(rng, full_address.gateway())?;
    let delays = nym_sphinx_routing::generate_hop_delays(average_packet_delay, route.len());
-    let destination = full_address.as_sphinx_destination(None);
+    let destination = full_address.as_sphinx_destination();

    let rotation_id = topology.current_key_rotation();
    let sphinx_key_rotation = SphinxKeyRotation::from(rotation_id);
@@ -11,10 +11,8 @@ repository = { workspace = true }
 bytes = { workspace = true }
 tokio-util = { workspace = true, features = ["codec"] }
 thiserror = { workspace = true }
-opentelemetry = { workspace = true }
 tracing = { workspace = true }

-nym-bin-common = { path = "../../bin-common" }
 nym-sphinx-types = { path = "../types", features = ["sphinx", "outfox"] }
 nym-sphinx-params = { path = "../params", features = ["sphinx", "outfox"] }
 nym-sphinx-forwarding = { path = "../forwarding" }
@@ -23,7 +21,3 @@ nym-sphinx-acknowledgements = { path = "../acknowledgements" }

 [dev-dependencies]
 tokio = { workspace = true, features = ["full"] }
-
-[features]
-default = []
-otel = ["nym-bin-common/otel"]
@@ -2,12 +2,6 @@
 // SPDX-License-Identifier: Apache-2.0

 use crate::packet::FramedNymPacket;
-#[cfg(feature = "otel")]
-use nym_bin_common::opentelemetry::{
-    compact_id_generator::decompress_trace_id,
-    context::ManualContextPropagator,
-};
-
 use nym_sphinx_acknowledgements::surb_ack::{SurbAck, SurbAckRecoveryError};
 use nym_sphinx_addressing::nodes::{NymNodeRoutingAddress, NymNodeRoutingAddressError};
 use nym_sphinx_forwarding::packet::MixPacket;
@@ -20,9 +14,7 @@ use nym_sphinx_types::{
 };
 use std::fmt::Display;
 use thiserror::Error;
-use tracing::{debug, error, info, instrument, trace, warn};
-#[cfg(feature = "otel")]
-use tracing::warn_span;
+use tracing::{debug, error, info, trace};

 #[derive(Debug)]
 pub enum MixProcessingResultData {
@@ -244,7 +236,6 @@ fn perform_framed_packet_processing(
    })
 }

-#[instrument(skip_all)]
 fn wrap_processed_sphinx_packet(
    packet: nym_sphinx_types::ProcessedPacket,
    packet_size: PacketSize,
@@ -267,36 +258,15 @@ fn wrap_processed_sphinx_packet(
        // sphinx all together?
        ProcessedPacketData::FinalHop {
            destination,
-            #[cfg(feature = "otel")]
-            identifier,
-            #[cfg(not(feature = "otel"))]
            identifier: _,
            payload,
-        } => {
-            // if we have a trace id in the destination, we log it for easier correlation later on
-            #[cfg(feature = "otel")]
-            let span = match identifier[0..12].try_into().map(|b: [u8; 12]| b) {
-                Ok(trace_bytes) if !trace_bytes.iter().all(|b| *b == 0) => {
-                    let full_trace_id_bytes = decompress_trace_id(&trace_bytes);
-                    let full_trace_id = opentelemetry::trace::TraceId::from_bytes(full_trace_id_bytes);
-                    let context_propagator = ManualContextPropagator::new_from_tid("final_hop", full_trace_id);
-                    warn_span!(parent: &context_propagator.root_span, "final_hop_processing", trace_id=%full_trace_id)
-                }
-                _ => {
-                    warn_span!("final_hop_processing")
-                }
-            };
-            #[cfg(feature = "otel")]
-            let _entered_span = span.enter();
-
-            process_final_hop(
-                destination,
-                payload.recover_plaintext()?,
-                packet_size,
-                packet_type,
-                key_rotation,
-            )
-        }
+        } => process_final_hop(
+            destination,
+            payload.recover_plaintext()?,
+            packet_size,
+            packet_type,
+            key_rotation,
+        ),
    }?;

    Ok(MixProcessingResult {
@@ -163,6 +163,19 @@ pub trait FragmentPreparer {
        })
    }

+    /// Tries to convert this [`Fragment`] into a [`SphinxPacket`] that can be sent through the Nym mix-network,
+    /// such that it contains required SURB-ACK and public component of the ephemeral key used to
+    /// derive the shared key.
+    /// Also all the data, apart from the said public component, is encrypted with an ephemeral shared key.
+    /// This method can fail if the provided network topology is invalid.
+    /// It returns total expected delay as well as the [`SphinxPacket`] (including first hop address)
+    /// to be sent through the network.
+    ///
+    /// The procedure is as follows:
+    /// For each fragment:
+    /// - compute SURB_ACK
+    /// - generate (x, g^x)
+    /// - compute k = KDF(remote encryption key ^ x) this is equivalent to KDF( dh(remote, x) )
    /// - compute v_b = AES-128-CTR(k, serialized_fragment)
    /// - compute vk_b = g^x || v_b
    /// - compute sphinx_plaintext = SURB_ACK || g^x || v_b
@@ -176,7 +189,6 @@ pub trait FragmentPreparer {
        packet_sender: &Recipient,
        packet_recipient: &Recipient,
        packet_type: PacketType,
-        trace_id: Option<[u8; 12]>,
    ) -> Result<PreparedFragment, NymTopologyError> {
        debug!("Preparing chunk for sending");
        // each plain or repliable packet (i.e. not a reply) attaches an ephemeral public key so that the recipient
@@ -237,8 +249,7 @@ pub trait FragmentPreparer {
            topology.random_route_to_egress(&mut rng, destination)?
        };

-        let destination = packet_recipient.as_sphinx_destination(trace_id);
-        tracing::warn!("Packet destination with trace id: {:?}", &destination.identifier);
+        let destination = packet_recipient.as_sphinx_destination();

        // including set of delays
        let delays =
@@ -263,10 +274,9 @@ pub trait FragmentPreparer {
            )?,
        };

-    // - compute k = KDF(remote encryption key ^ x) this is equivalent to KDF( dh(remote, x) )
-    // from the previously constructed route extract the first hop
-    let first_hop_address =
-        NymNodeRoutingAddress::try_from(route.first().unwrap().address).unwrap();
+        // from the previously constructed route extract the first hop
+        let first_hop_address =
+            NymNodeRoutingAddress::try_from(route.first().unwrap().address).unwrap();

        Ok(PreparedFragment {
            // the round-trip delay is the sum of delays of all hops on the forward route as
@@ -418,7 +428,6 @@ where
        ack_key: &AckKey,
        packet_recipient: &Recipient,
        packet_type: PacketType,
-        trace_id: Option<[u8; 12]>,
    ) -> Result<PreparedFragment, NymTopologyError> {
        let sender = self.sender_address;

@@ -430,7 +439,6 @@ where
            &sender,
            packet_recipient,
            packet_type,
-            trace_id,
        )
    }

@@ -10,8 +10,6 @@ repository = { workspace = true }
 [dependencies]
 sphinx-packet = { workspace = true, optional = true }
 nym-outfox = { path = "../../../nym-outfox", optional = true }
-# TODO add optional
-nym-bin-common = { path = "../../../common/bin-common" }
 thiserror = { workspace = true }

 [features]
@@ -32,6 +32,8 @@ tracing.workspace = true
 url.workspace = true


+# TEMP
+#nym-bin-common = { path = "../bin-common", features = ["basic_tracing"]}


 [build-dependencies]
@@ -0,0 +1,20 @@
+[package]
+name = "nym-registration-common"
+version = "0.1.0"
+authors.workspace = true
+repository.workspace = true
+homepage.workspace = true
+documentation.workspace = true
+edition.workspace = true
+license.workspace = true
+
+[lints]
+workspace = true
+
+[dependencies]
+tokio-util.workspace = true
+
+nym-authenticator-requests = { path = "../authenticator-requests" }
+nym-crypto = { path = "../crypto" }
+nym-ip-packet-requests = { path = "../ip-packet-requests" }
+nym-sphinx = { path = "../nymsphinx" }
@@ -0,0 +1,35 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use std::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr};
+
+use nym_authenticator_requests::AuthenticatorVersion;
+use nym_crypto::asymmetric::x25519::PublicKey;
+use nym_ip_packet_requests::IpPair;
+use nym_sphinx::addressing::{NodeIdentity, Recipient};
+
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct NymNode {
+    pub identity: NodeIdentity,
+    pub ip_address: IpAddr,
+    pub ipr_address: Option<Recipient>,
+    pub authenticator_address: Option<Recipient>,
+    pub version: AuthenticatorVersion,
+}
+
+#[derive(Clone, Debug)]
+pub struct GatewayData {
+    pub public_key: PublicKey,
+    pub endpoint: SocketAddr,
+    pub private_ipv4: Ipv4Addr,
+    pub private_ipv6: Ipv6Addr,
+}
+
+#[derive(Clone, Copy, Debug)]
+pub struct AssignedAddresses {
+    pub entry_mixnet_gateway_ip: IpAddr,
+    pub exit_mixnet_gateway_ip: IpAddr,
+    pub mixnet_client_address: Recipient,
+    pub exit_mix_address: Recipient,
+    pub interface_addresses: IpPair,
+}
@@ -42,6 +42,40 @@ impl TryFrom<u8> for ServiceProviderType {
    }
 }

+pub trait ServiceProviderTypeExt {
+    fn is_network_requester(&self) -> bool;
+    fn is_ip_packet_router(&self) -> bool;
+    fn is_authenticator(&self) -> bool;
+}
+
+impl ServiceProviderTypeExt for ServiceProviderType {
+    fn is_network_requester(&self) -> bool {
+        matches!(self, Self::NetworkRequester)
+    }
+
+    fn is_ip_packet_router(&self) -> bool {
+        matches!(self, Self::IpPacketRouter)
+    }
+
+    fn is_authenticator(&self) -> bool {
+        matches!(self, Self::Authenticator)
+    }
+}
+
+impl ServiceProviderTypeExt for u8 {
+    fn is_network_requester(&self) -> bool {
+        ServiceProviderType::NetworkRequester as u8 == *self
+    }
+
+    fn is_ip_packet_router(&self) -> bool {
+        ServiceProviderType::IpPacketRouter as u8 == *self
+    }
+
+    fn is_authenticator(&self) -> bool {
+        ServiceProviderType::Authenticator as u8 == *self
+    }
+}
+
 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 pub struct Protocol {
    pub version: u8,
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Tommy Verrall	88e39e22fb	Update network_tunnel_manager.sh wg_meta_change - WIP	2025-10-03 13:02:16 +02:00
Jędrzej Stuczyński	fc98c497b4	feat: DKG contract method for updating announce address (#6050 ) * added new dkg execute methods for ownership transfer and announce address update * cherry-pick TestableNymContract for the dkg contract from #5091 * tests * schema fixes * removed old queued migrations	2025-10-02 17:19:03 +01:00
benedetta davico	92a88cdf9a	Merge pull request #6079 from nymtech/release/2025.17-isabirra Release/2025.17 isabirra	2025-10-02 16:00:53 +02:00
Bogdan-Ștefan Neacşu	026d3a6466	Get wireguard keypair as arg instead of reading it from disk (#6078 ) * Get wireguard keypair as arg instead of reading it from disk * Move keypair out of NymNode * Remove legacy auth client	2025-10-02 16:27:48 +03:00
import this	53c4fde314	Hotfix: Update API source in node ping tester script (#6082 )	2025-10-02 12:53:51 +00:00
Simon Wicky	3f55e62764	ci fixes (cherry picked from commit `caf40e7a37`)	2025-10-02 14:05:43 +02:00
import this	00cc54f5c3	[DOCs/operators]: Release notes 2025.17-isabirra & New tools documentation (#6081 ) * initialise release update notes * add api changes * create tools page and document nym-node-cli usage * syntax fix * document cmd tools * add tools and ufw command to changelog * add ufw 51830 to nym-node ports snippet * ready for review except missing version hash info * finished - ready for review * add spectre delegation wizzard	2025-10-02 11:56:12 +00:00
import this	c1904840e1	Feature: Node rewards tracker (#6064 )	2025-10-02 08:52:46 +00:00
benedetta davico	c652e3bdcd	Benny/ci contract fix (#5962 ) * use different runner * Update Makefile * Update Makefile * Update ci-contracts-upload-binaries.yml change to dtolnay * Update ci-contracts-upload-binaries.yml allow features alloc * Update ci-contracts-upload-binaries.yml try a specific cosmwasm-check * Update ci-contracts-upload-binaries.yml temp disable - until the right cosm check is found * try new runner * remove version check * try to dockerize * test * remove rust install * test * change runner * . * set cargo path * set path * diff image * error * set path * . * aah * . * remove singlepass feature * change runner * Update ci-contracts-upload-binaries.yml --------- Co-authored-by: Tommy Verrall <60836166+tommyv1987@users.noreply.github.com>	2025-10-02 09:15:48 +01:00
benedetta davico	f9844416df	Update ci-contracts.yml	2025-10-01 12:45:18 +02:00
benedetta davico	bbea2ff9e9	Add nym-node binary	2025-10-01 12:06:07 +02:00
Simon Wicky	4acaec48b4	update runner for nym stats api build (#6077 )	2025-10-01 09:48:16 +02:00
Simon Wicky	51779c06a4	Registration Client (#6059 ) * removing wg-gateway-client * bandwidth_provider trait * authenticator client * adapt ip-packet-client * nit * registration_client * accomodate new shutdown and bugfix * sdk changes * cleanup and shutdown management * remove credential mode * error cleanup * better error handling * removing useless cover traffic delay * wasm client stuff * cfg unix * more wasm stuff * change authenticator client to not be blocked by mixnet client	2025-09-30 15:50:04 +02:00
import this	5cc650e901	Feature: Ping probe all nodes /described from a server (#6074 ) * initialise test-nodes-pings.sh * add retry	2025-09-30 13:30:54 +00:00
Simon Wicky	a7ec178c9f	[Stats API] Add flat table to stats API (#6073 ) * add flat table to stats API * remove day column	2025-09-30 14:30:05 +02:00
benedetta davico	4e97a2f871	Update push-credential-proxy.yaml	2025-09-30 12:03:04 +02:00
benedetta davico	5fbfc21fb2	Bump cred proxy version	2025-09-30 11:22:18 +02:00
benedettadavico	3d45801bb7	Fix swagger v2 endpoint	2025-09-30 10:26:55 +02:00
benedettadavico	3aea9f127b	Update changelog	2025-09-30 10:23:55 +02:00
benedetta davico	a26ff644cc	Update mainnet.rs	2025-09-29 19:16:49 +02:00
Mark Sinclair	a0e37e78e2	Node Status API: add bridge information to dVPN endpoint (#6069 ) * ns api: add node scraper for bridge information and add to dVPN gateway output * extra error reporting * run sqlx-prepare * fix clippy --------- Co-authored-by: Mark Sinclair <mmsinclair@users.noreply.github.com> Co-authored-by: benedettadavico <benedetta.davico@gmail.com>	2025-09-29 16:27:10 +01:00
Jędrzej Stuczyński	b3d02e3ba7	feat: NS ticket faucet (#6047 ) * ns-api: remove sqlite support ns-api: add env var to skip migrations for local dev ns-api: tidy up imports ns-api: fix deserialisation fo node descriptions update dockerfile update README fix up README and example env ns-api: bump major version to 4 ns-api: add more geoip data and new performance field in dvpn responses * ability to import partial ticketbooks * wip: adding common ecash state to NS API * buffering ticketbooks * wip * distribute tickets when getting testrun assignment * passing ticketbook data to gateway probe * wrapped around storage tx * ticketbook query fixes * clippy * modified testrun assignment to always return tickets * Update version * Update push-node-status-agent.yaml * Update Cargo.toml * add entrypoint for ns agents * sqlx prepare and cargo fmt * clippy fixes * Update ci-check-ns-api-version.yml --------- Co-authored-by: Mark Sinclair <mmsinclair@users.noreply.github.com> Co-authored-by: benedetta davico <46782255+benedettadavico@users.noreply.github.com> Co-authored-by: benedettadavico <benedetta.davico@gmail.com>	2025-09-29 14:53:15 +01:00
Mark Sinclair	f5b5177073	Update push-node-status-api.yaml	2025-09-26 20:14:30 +01:00