formatting

fix examples and simpligy imports
test the piecewise api provider against local nym api
2025-03-13 15:43:38 -06:00 · 2025-03-13 15:38:18 -06:00 · 2025-03-13 14:58:51 -06:00 · 2025-03-13 14:58:51 -06:00 · 2025-03-13 14:58:48 -06:00 · 2025-03-13 14:54:23 -06:00
544 changed files with 77260 additions and 9829 deletions
@@ -26,6 +26,7 @@ jobs:
    runs-on: ${{ matrix.platform }}
    env:
      CARGO_TERM_COLOR: always
+      RUSTUP_PERMIT_COPY_RENAME: 1
    steps:
      - uses: actions/checkout@v4

@@ -12,6 +12,7 @@ jobs:
    runs-on: arc-ubuntu-22.04
    env:
      CARGO_TERM_COLOR: always
+      RUSTUP_PERMIT_COPY_RENAME: 1
    steps:
      - name: Check out repository code
        uses: actions/checkout@v4
@@ -37,6 +37,7 @@ jobs:
    env:
      CARGO_TERM_COLOR: always
      IPINFO_API_TOKEN: ${{ secrets.IPINFO_API_TOKEN }}
+      RUSTUP_PERMIT_COPY_RENAME: 1
    steps:
      - name: Install Dependencies (Linux)
        run: sudo apt-get update && sudo apt-get -y install libwebkit2gtk-4.0-dev build-essential curl wget libssl-dev libgtk-3-dev libudev-dev squashfs-tools protobuf-compiler
@@ -4,6 +4,118 @@ Post 1.0.0 release, the changelog format is based on [Keep a Changelog](https://

 ## [Unreleased]

+## [2025.4-dorina-patched] (2025-03-06)
+
+- use legacy crypto for constructing SURB headers ([#5579])
+- bugfix: make sure to correctly decode response content when putting it into error message ([#5571])
+- Tweak surb management to be more conservative ([#5570])
+- Deserialize v5 authenticator requests ([#5568])
+- chore: additional logs when attempting to load ecash keys ([#5567])
+- add full response body to error message upon decoding failure ([#5566])
+- hotfix: ensure we bail on merkle leaves insertion upon missing data ([#5565])
+- feature: v2 authentication request (#5537) ([#5563])
+- Create authenticator v5 request/response types ([#5561])
+
+[#5579]: https://github.com/nymtech/nym/pull/5579
+[#5571]: https://github.com/nymtech/nym/pull/5571
+[#5570]: https://github.com/nymtech/nym/pull/5570
+[#5568]: https://github.com/nymtech/nym/pull/5568
+[#5567]: https://github.com/nymtech/nym/pull/5567
+[#5566]: https://github.com/nymtech/nym/pull/5566
+[#5565]: https://github.com/nymtech/nym/pull/5565
+[#5563]: https://github.com/nymtech/nym/pull/5563
+[#5561]: https://github.com/nymtech/nym/pull/5561
+
+## [2025.4-dorina] (2025-03-04)
+
+- fixed sphinx version metrics registration ([#5546])
+- Feature/chain status api ([#5539])
+- Add SURBs soft threshold ([#5535])
+- Simplify IPR v8 ([#5532])
+- Shared instance for DNS AsyncResolver ([#5523])
+- merge #5512 again after reverting due to incorrect rebase ([#5520])
+- cherry-pick 17d3ff2d775f61aee381d90a304ed416c08f33fc onto dorina ([#5519])
+- cherry-pick 6e5d0dac1b75413c5f09122b0d953f8ec6ef48df onto dorina ([#5518])
+- chore: workspace global panic preventing lints ([#5512])
+- bugfix: dont query for ecash apis unless necessary when spending ticketbooks ([#5508])
+- bugfix: bound check when recovering a reply SURB ([#5502])
+- chore: removed all old coconut code ([#5500])
+- IPR request types v8 ([#5498])
+- Support static routes for HTTP requests ([#5487])
+- build(deps): bump the patch-updates group across 1 directory with 3 updates ([#5482])
+- added missing import to doctest ([#5480])
+- adjusted TestSetup::new_complex to ensure bonded node's existence ([#5478])
+- Trigger contracts CI on main workspace Cargo changes ([#5477])
+- build(deps): bump http from 1.1.0 to 1.2.0 ([#5472])
+- build(deps): bump utoipa-swagger-ui from 8.0.3 to 8.1.0 ([#5471])
+- build(deps): bump colored from 2.1.0 to 2.2.0 ([#5470])
+- build(deps): bump celes from 2.4.0 to 2.5.0 ([#5469])
+- build(deps): bump the patch-updates group with 2 updates ([#5467])
+- build(deps): bump elliptic from 6.5.4 to 6.6.1 in /docker/typescript_client/upload_contract ([#5463])
+- Run cargo autoinherit ([#5460])
+- Fix clippy::precedence ([#5457])
+- Provide Interval context with node descriptor endpoints ([#5456])
+- fix: update fx average rate calcs to ignore 0 values ([#5454])
+- Feature/add gbp currency ([#5453])
+- Add helper to extract a list of sqlite files with journal files wal/shm ([#5452])
+- Add a middleware layer to the nym api allowing for data compression ([#5451])
+- Condense core API functionalities and enable gzip decompression for reqwest payloads ([#5450])
+- build(deps): bump uniffi_build from 0.25.3 to 0.29.0 ([#5448])
+- Upgrade tower to 0.5.2 ([#5446])
+- build(deps): bump hickory-proto from 0.24.2 to 0.24.3 ([#5444])
+- Seedable clients ([#5440])
+- build(deps): bump the patch-updates group across 1 directory with 10 updates ([#5439])
+- Remove all recv_with_delay and add shutdown condition to loops in client-core ([#5435])
+- Disable the test for checking the remaining bandwidth in nym-node-status-api ([#5425])
+- Dz nym node stats ([#5418])
+- build(deps): bump hyper from 1.4.1 to 1.6.0 ([#5416])
+- build(deps): bump publicsuffix from 2.2.3 to 2.3.0 ([#5367])
+- Nymnode entrypoint docker ([#5300])
+
+[#5546]: https://github.com/nymtech/nym/pull/5546
+[#5539]: https://github.com/nymtech/nym/pull/5539
+[#5535]: https://github.com/nymtech/nym/pull/5535
+[#5532]: https://github.com/nymtech/nym/pull/5532
+[#5523]: https://github.com/nymtech/nym/pull/5523
+[#5520]: https://github.com/nymtech/nym/pull/5520
+[#5519]: https://github.com/nymtech/nym/pull/5519
+[#5518]: https://github.com/nymtech/nym/pull/5518
+[#5512]: https://github.com/nymtech/nym/pull/5512
+[#5508]: https://github.com/nymtech/nym/pull/5508
+[#5502]: https://github.com/nymtech/nym/pull/5502
+[#5500]: https://github.com/nymtech/nym/pull/5500
+[#5498]: https://github.com/nymtech/nym/pull/5498
+[#5487]: https://github.com/nymtech/nym/pull/5487
+[#5482]: https://github.com/nymtech/nym/pull/5482
+[#5480]: https://github.com/nymtech/nym/pull/5480
+[#5478]: https://github.com/nymtech/nym/pull/5478
+[#5477]: https://github.com/nymtech/nym/pull/5477
+[#5472]: https://github.com/nymtech/nym/pull/5472
+[#5471]: https://github.com/nymtech/nym/pull/5471
+[#5470]: https://github.com/nymtech/nym/pull/5470
+[#5469]: https://github.com/nymtech/nym/pull/5469
+[#5467]: https://github.com/nymtech/nym/pull/5467
+[#5463]: https://github.com/nymtech/nym/pull/5463
+[#5460]: https://github.com/nymtech/nym/pull/5460
+[#5457]: https://github.com/nymtech/nym/pull/5457
+[#5456]: https://github.com/nymtech/nym/pull/5456
+[#5454]: https://github.com/nymtech/nym/pull/5454
+[#5453]: https://github.com/nymtech/nym/pull/5453
+[#5452]: https://github.com/nymtech/nym/pull/5452
+[#5451]: https://github.com/nymtech/nym/pull/5451
+[#5450]: https://github.com/nymtech/nym/pull/5450
+[#5448]: https://github.com/nymtech/nym/pull/5448
+[#5446]: https://github.com/nymtech/nym/pull/5446
+[#5444]: https://github.com/nymtech/nym/pull/5444
+[#5440]: https://github.com/nymtech/nym/pull/5440
+[#5439]: https://github.com/nymtech/nym/pull/5439
+[#5435]: https://github.com/nymtech/nym/pull/5435
+[#5425]: https://github.com/nymtech/nym/pull/5425
+[#5418]: https://github.com/nymtech/nym/pull/5418
+[#5416]: https://github.com/nymtech/nym/pull/5416
+[#5367]: https://github.com/nymtech/nym/pull/5367
+[#5300]: https://github.com/nymtech/nym/pull/5300
+
 ## [2025.3-ruta] (2025-02-10)

 - Push down forget me to client configs ([#5431])
@@ -137,7 +137,7 @@ members = [
    "tools/internal/testnet-manager",
    "tools/internal/testnet-manager",
    "tools/internal/testnet-manager/dkg-bypass-contract",
-    "tools/internal/testnet-manager/dkg-bypass-contract",
+    "tools/internal/testnet-manager/dkg-bypass-contract", "tools/internal/validator-status-check",
    "tools/nym-cli",
    "tools/nym-id-cli",
    "tools/nym-nr-query",
@@ -191,10 +191,10 @@ aes = "0.8.1"
 aes-gcm = "0.10.1"
 aes-gcm-siv = "0.11.1"
 ammonia = "4"
-anyhow = "1.0.95"
+anyhow = "1.0.97"
 arc-swap = "1.7.1"
 argon2 = "0.5.0"
-async-trait = "0.1.86"
+async-trait = "0.1.87"
 axum = "0.7.5"
 axum-client-ip = "0.6.1"
 axum-extra = "0.9.4"
@@ -205,24 +205,24 @@ bincode = "1.3.3"
 bip39 = { version = "2.0.0", features = ["zeroize"] }
 bit-vec = "0.7.0"                                     # can we unify those?
 bitvec = "1.0.0"
-blake3 = "1.5.5"
+blake3 = "1.6.1"
 bloomfilter = "1.0.14"
 bs58 = "0.5.1"
 bytecodec = "0.4.15"
-bytes = "1.7.2"
+bytes = "1.10.1"
 cargo_metadata = "0.18.1"
 celes = "2.5.0"
 cfg-if = "1.0.0"
 chacha20 = "0.9.0"
 chacha20poly1305 = "0.10.1"
-chrono = "0.4.39"
+chrono = "0.4.40"
 cipher = "0.4.3"
-clap = "4.5.30"
+clap = "4.5.31"
 clap_complete = "4.5"
 clap_complete_fig = "4.5"
 colored = "2.2"
 comfy-table = "7.1.4"
-console = "0.15.10"
+console = "0.15.11"
 console-subscriber = "0.1.1"
 console_error_panic_hook = "0.1"
 const-str = "0.5.6"
@@ -241,22 +241,23 @@ doc-comment = "0.3"
 dotenvy = "0.15.6"
 ecdsa = "0.16"
 ed25519-dalek = "2.1"
+encoding_rs = "0.8.35"
 env_logger = "0.11.6"
 envy = "0.4"
 etherparse = "0.13.0"
 eyre = "0.6.9"
 fastrand = "2.1.1"
-flate2 = "1.0.35"
+flate2 = "1.1.0"
 futures = "0.3.31"
 futures-util = "0.3"
 generic-array = "0.14.7"
 getrandom = "0.2.10"
-getset = "0.1.4"
+getset = "0.1.5"
 handlebars = "3.5.5"
 headers = "0.4.0"
 hex = "0.4.3"
 hex-literal = "0.3.3"
-hickory-resolver = "0.24.3"
+hickory-resolver = "0.24.4"
 hkdf = "0.12.3"
 hmac = "0.12.1"
 http = "1"
@@ -272,7 +273,7 @@ inquire = "0.6.2"
 ip_network = "0.4.1"
 ipnetwork = "0.20"
 isocountry = "0.3.2"
-itertools = "0.13.0"
+itertools = "0.14.0"
 k256 = "0.13"
 lazy_static = "1.5.0"
 ledger-transport = "0.10.0"
@@ -307,21 +308,21 @@ reqwest = { version = "0.12.4", default-features = false }
 rocket = "0.5.0"
 rocket_cors = "0.6.0"
 rocket_okapi = "0.8.0"
-rs_merkle = "1.4.2"
+rs_merkle = "1.5.0"
 safer-ffi = "0.1.13"
-schemars = "0.8.21"
-semver = "1.0.25"
-serde = "1.0.217"
-serde_bytes = "0.11.15"
+schemars = "0.8.22"
+semver = "1.0.26"
+serde = "1.0.219"
+serde_bytes = "0.11.17"
 serde_derive = "1.0"
-serde_json = "1.0.138"
+serde_json = "1.0.140"
 serde_json_path = "0.7.2"
 serde_repr = "0.1"
 serde_with = "3.9.0"
 serde_yaml = "0.9.25"
 sha2 = "0.10.8"
 si-scale = "0.2.3"
-sphinx-packet = "0.3.1"
+sphinx-packet = "=0.3.2"
 sqlx = "0.7.4"
 strum = "0.26"
 strum_macros = "0.26"
@@ -329,11 +330,11 @@ subtle-encoding = "0.5"
 syn = "1"
 sysinfo = "0.33.0"
 tap = "1.0.1"
-tar = "0.4.43"
-tempfile = "3.15"
+tar = "0.4.44"
+tempfile = "3.18"
 thiserror = "2.0"
-time = "0.3.37"
-tokio = "1.43"
+time = "0.3.39"
+tokio = "1.44"
 tokio-postgres = "0.7"
 tokio-stream = "0.1.17"
 tokio-test = "0.4.4"
@@ -369,9 +370,9 @@ prometheus = { version = "0.13.0" }
 # unfortunately until https://github.com/zkcrypto/bls12_381/issues/10 is resolved, we have to rely on the fork
 # as we need to be able to serialize Gt so that we could create the lookup table for baby-step-giant-step algorithm
 # plus to make our live easier we need serde support from https://github.com/zkcrypto/bls12_381/pull/125
-bls12_381 = { git = "https://github.com/jstuczyn/bls12_381", default-features = false, branch = "temp/experimental-serdect" }
+bls12_381 = { git = "https://github.com/jstuczyn/bls12_381", default-features = false, branch = "temp/experimental-serdect-updated" }
 group = { version = "0.13.0", default-features = false }
-ff = { version = "0.13.0", default-features = false }
+ff = { version = "0.13.1", default-features = false }
 subtle = "2.5.0"

 # cosmwasm-related
@@ -437,3 +438,13 @@ opt-level = 'z'
 [profile.release.package.mix-fetch-wasm]
 # lto = true
 opt-level = 'z'
+
+[workspace.lints.clippy]
+unwrap_used = "deny"
+expect_used = "deny"
+todo = "deny"
+dbg_macro = "deny"
+exit = "deny"
+panic = "deny"
+unimplemented = "deny"
+unreachable = "deny"
@@ -67,3 +67,13 @@ As a general approach, licensing is as follows this pattern:
 - documentation is Apache 2.0 or CC0-1.0

 Nym Node Operators and Validators Terms and Conditions can be found [here](https://nym.com/operators-validators-terms).
+
+## Getting Started
+
+```bash
+yarn install
+```
+
+```bash
+yarn build
+```
@@ -1,6 +1,6 @@
 [package]
 name = "nym-client"
-version = "1.1.49"
+version = "1.1.50"
 authors = ["Dave Hrycyszyn <futurechimp@users.noreply.github.com>", "Jędrzej Stuczyński <andrew@nymtech.net>"]
 description = "Implementation of the Nym Client"
 edition = "2021"
@@ -1,6 +1,6 @@
 [package]
 name = "nym-socks5-client"
-version = "1.1.49"
+version = "1.1.50"
 authors = ["Dave Hrycyszyn <futurechimp@users.noreply.github.com>"]
 description = "A SOCKS5 localhost proxy that converts incoming messages to Sphinx and sends them to a Nym address"
 edition = "2021"
@@ -1,2 +1,3 @@
 allow-unwrap-in-tests = true
 allow-expect-in-tests = true
+allow-panic-in-tests = true
@@ -6,14 +6,15 @@ pub mod v1;
 pub mod v2;
 pub mod v3;
 pub mod v4;
+pub mod v5;

 mod error;
 mod util;

 pub use error::Error;
-pub use v4 as latest;
+pub use v5 as latest;

-pub const CURRENT_VERSION: u8 = 4;
+pub const CURRENT_VERSION: u8 = 5;

 fn make_bincode_serializer() -> impl bincode::Options {
    use bincode::Options;
@@ -8,8 +8,8 @@ use nym_sphinx::addressing::clients::Recipient;
 use nym_wireguard_types::PeerPublicKey;

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

@@ -19,6 +19,7 @@ pub enum AuthenticatorVersion {
    V2,
    V3,
    V4,
+    V5,
    UNKNOWN,
 }

@@ -34,6 +35,8 @@ impl From<Protocol> for AuthenticatorVersion {
            AuthenticatorVersion::V3
        } else if value.version == v4::VERSION {
            AuthenticatorVersion::V4
+        } else if value.version == v5::VERSION {
+            AuthenticatorVersion::V5
        } else {
            AuthenticatorVersion::UNKNOWN
        }
@@ -68,6 +71,12 @@ impl InitMessage for v4::registration::InitMessage {
    }
 }

+impl InitMessage for v5::registration::InitMessage {
+    fn pub_key(&self) -> PeerPublicKey {
+        self.pub_key
+    }
+}
+
 pub trait FinalMessage {
    fn pub_key(&self) -> PeerPublicKey;
    fn verify(&self, private_key: &PrivateKey, nonce: u64) -> Result<(), Error>;
@@ -138,6 +147,24 @@ impl FinalMessage for v4::registration::FinalMessage {
        self.gateway_client.verify(private_key, nonce)
    }

+    fn private_ips(&self) -> IpPair {
+        self.gateway_client.private_ips.into()
+    }
+
+    fn credential(&self) -> Option<CredentialSpendingData> {
+        self.credential.clone()
+    }
+}
+
+impl FinalMessage for v5::registration::FinalMessage {
+    fn pub_key(&self) -> PeerPublicKey {
+        self.gateway_client.pub_key
+    }
+
+    fn verify(&self, private_key: &PrivateKey, nonce: u64) -> Result<(), Error> {
+        self.gateway_client.verify(private_key, nonce)
+    }
+
    fn private_ips(&self) -> IpPair {
        self.gateway_client.private_ips
    }
@@ -182,29 +209,39 @@ impl TopUpMessage for v4::topup::TopUpMessage {
    }
 }

+impl TopUpMessage for v5::topup::TopUpMessage {
+    fn pub_key(&self) -> PeerPublicKey {
+        self.pub_key
+    }
+
+    fn credential(&self) -> CredentialSpendingData {
+        self.credential.clone()
+    }
+}
+
 pub enum AuthenticatorRequest {
    Initial {
        msg: Box<dyn InitMessage + Send + Sync + 'static>,
        protocol: Protocol,
-        reply_to: Recipient,
+        reply_to: Option<Recipient>,
        request_id: u64,
    },
    Final {
        msg: Box<dyn FinalMessage + Send + Sync + 'static>,
        protocol: Protocol,
-        reply_to: Recipient,
+        reply_to: Option<Recipient>,
        request_id: u64,
    },
    QueryBandwidth {
        msg: Box<dyn QueryBandwidthMessage + Send + Sync + 'static>,
        protocol: Protocol,
-        reply_to: Recipient,
+        reply_to: Option<Recipient>,
        request_id: u64,
    },
    TopUpBandwidth {
        msg: Box<dyn TopUpMessage + Send + Sync + 'static>,
        protocol: Protocol,
-        reply_to: Recipient,
+        reply_to: Option<Recipient>,
        request_id: u64,
    },
 }
@@ -218,7 +255,7 @@ impl From<v1::request::AuthenticatorRequest> for AuthenticatorRequest {
                    version: value.version,
                    service_provider_type: ServiceProviderType::Authenticator,
                },
-                reply_to: value.reply_to,
+                reply_to: Some(value.reply_to),
                request_id: value.request_id,
            },
            v1::request::AuthenticatorRequestData::Final(gateway_client) => Self::Final {
@@ -227,7 +264,7 @@ impl From<v1::request::AuthenticatorRequest> for AuthenticatorRequest {
                    version: value.version,
                    service_provider_type: ServiceProviderType::Authenticator,
                },
-                reply_to: value.reply_to,
+                reply_to: Some(value.reply_to),
                request_id: value.request_id,
            },
            v1::request::AuthenticatorRequestData::QueryBandwidth(peer_public_key) => {
@@ -237,7 +274,7 @@ impl From<v1::request::AuthenticatorRequest> for AuthenticatorRequest {
                        version: value.version,
                        service_provider_type: ServiceProviderType::Authenticator,
                    },
-                    reply_to: value.reply_to,
+                    reply_to: Some(value.reply_to),
                    request_id: value.request_id,
                }
            }
@@ -251,20 +288,20 @@ impl From<v2::request::AuthenticatorRequest> for AuthenticatorRequest {
            v2::request::AuthenticatorRequestData::Initial(init_message) => Self::Initial {
                msg: Box::new(init_message),
                protocol: value.protocol,
-                reply_to: value.reply_to,
+                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: value.reply_to,
+                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: value.reply_to,
+                    reply_to: Some(value.reply_to),
                    request_id: value.request_id,
                }
            }
@@ -278,20 +315,20 @@ impl From<v3::request::AuthenticatorRequest> for AuthenticatorRequest {
            v3::request::AuthenticatorRequestData::Initial(init_message) => Self::Initial {
                msg: Box::new(init_message),
                protocol: value.protocol,
-                reply_to: value.reply_to,
+                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: value.reply_to,
+                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: value.reply_to,
+                    reply_to: Some(value.reply_to),
                    request_id: value.request_id,
                }
            }
@@ -299,7 +336,7 @@ impl From<v3::request::AuthenticatorRequest> for AuthenticatorRequest {
                Self::TopUpBandwidth {
                    msg: top_up_message,
                    protocol: value.protocol,
-                    reply_to: value.reply_to,
+                    reply_to: Some(value.reply_to),
                    request_id: value.request_id,
                }
            }
@@ -313,20 +350,20 @@ impl From<v4::request::AuthenticatorRequest> for AuthenticatorRequest {
            v4::request::AuthenticatorRequestData::Initial(init_message) => Self::Initial {
                msg: Box::new(init_message),
                protocol: value.protocol,
-                reply_to: value.reply_to,
+                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: value.reply_to,
+                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: value.reply_to,
+                    reply_to: Some(value.reply_to),
                    request_id: value.request_id,
                }
            }
@@ -334,7 +371,42 @@ impl From<v4::request::AuthenticatorRequest> for AuthenticatorRequest {
                Self::TopUpBandwidth {
                    msg: top_up_message,
                    protocol: value.protocol,
-                    reply_to: value.reply_to,
+                    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,478 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use nym_service_provider_requests_common::{Protocol, ServiceProviderType};
+
+use crate::{v4, v5};
+
+impl From<v4::request::AuthenticatorRequest> for v5::request::AuthenticatorRequest {
+    fn from(authenticator_request: v4::request::AuthenticatorRequest) -> Self {
+        Self {
+            protocol: Protocol {
+                version: 5,
+                service_provider_type: ServiceProviderType::Authenticator,
+            },
+            data: authenticator_request.data.into(),
+            request_id: authenticator_request.request_id,
+        }
+    }
+}
+
+impl From<v4::request::AuthenticatorRequestData> for v5::request::AuthenticatorRequestData {
+    fn from(authenticator_request_data: v4::request::AuthenticatorRequestData) -> Self {
+        match authenticator_request_data {
+            v4::request::AuthenticatorRequestData::Initial(init_msg) => {
+                v5::request::AuthenticatorRequestData::Initial(init_msg.into())
+            }
+            v4::request::AuthenticatorRequestData::Final(final_msg) => {
+                v5::request::AuthenticatorRequestData::Final(Box::new((*final_msg).into()))
+            }
+            v4::request::AuthenticatorRequestData::QueryBandwidth(pub_key) => {
+                v5::request::AuthenticatorRequestData::QueryBandwidth(pub_key)
+            }
+            v4::request::AuthenticatorRequestData::TopUpBandwidth(top_up_message) => {
+                v5::request::AuthenticatorRequestData::TopUpBandwidth(top_up_message.into())
+            }
+        }
+    }
+}
+
+impl From<v4::registration::InitMessage> for v5::registration::InitMessage {
+    fn from(init_msg: v4::registration::InitMessage) -> Self {
+        Self {
+            pub_key: init_msg.pub_key,
+        }
+    }
+}
+
+impl From<v4::registration::FinalMessage> for v5::registration::FinalMessage {
+    fn from(final_msg: v4::registration::FinalMessage) -> Self {
+        Self {
+            gateway_client: final_msg.gateway_client.into(),
+            credential: final_msg.credential,
+        }
+    }
+}
+
+impl From<v4::registration::GatewayClient> for v5::registration::GatewayClient {
+    fn from(gateway_client: v4::registration::GatewayClient) -> Self {
+        Self {
+            pub_key: gateway_client.pub_key,
+            private_ips: gateway_client.private_ips.into(),
+            mac: gateway_client.mac.into(),
+        }
+    }
+}
+
+impl From<v5::registration::GatewayClient> for v4::registration::GatewayClient {
+    fn from(gateway_client: v5::registration::GatewayClient) -> Self {
+        Self {
+            pub_key: gateway_client.pub_key,
+            private_ips: gateway_client.private_ips.into(),
+            mac: gateway_client.mac.into(),
+        }
+    }
+}
+
+impl From<v4::registration::ClientMac> for v5::registration::ClientMac {
+    fn from(client_mac: v4::registration::ClientMac) -> Self {
+        Self::new((*client_mac).clone())
+    }
+}
+
+impl From<v5::registration::ClientMac> for v4::registration::ClientMac {
+    fn from(client_mac: v5::registration::ClientMac) -> Self {
+        Self::new((*client_mac).clone())
+    }
+}
+
+impl From<Box<v4::topup::TopUpMessage>> for Box<v5::topup::TopUpMessage> {
+    fn from(top_up_message: Box<v4::topup::TopUpMessage>) -> Self {
+        Box::new(v5::topup::TopUpMessage {
+            pub_key: top_up_message.pub_key,
+            credential: top_up_message.credential,
+        })
+    }
+}
+
+impl From<v4::response::AuthenticatorResponse> for v5::response::AuthenticatorResponse {
+    fn from(value: v4::response::AuthenticatorResponse) -> Self {
+        Self {
+            protocol: Protocol {
+                version: 5,
+                service_provider_type: value.protocol.service_provider_type,
+            },
+            data: value.data.into(),
+        }
+    }
+}
+
+impl From<v4::response::AuthenticatorResponseData> for v5::response::AuthenticatorResponseData {
+    fn from(authenticator_response_data: v4::response::AuthenticatorResponseData) -> Self {
+        match authenticator_response_data {
+            v4::response::AuthenticatorResponseData::PendingRegistration(pending_response) => {
+                v5::response::AuthenticatorResponseData::PendingRegistration(
+                    pending_response.into(),
+                )
+            }
+            v4::response::AuthenticatorResponseData::Registered(registered_response) => {
+                v5::response::AuthenticatorResponseData::Registered(registered_response.into())
+            }
+            v4::response::AuthenticatorResponseData::RemainingBandwidth(
+                remaining_bandwidth_response,
+            ) => v5::response::AuthenticatorResponseData::RemainingBandwidth(
+                remaining_bandwidth_response.into(),
+            ),
+            v4::response::AuthenticatorResponseData::TopUpBandwidth(top_up_response) => {
+                v5::response::AuthenticatorResponseData::TopUpBandwidth(top_up_response.into())
+            }
+        }
+    }
+}
+
+impl From<v4::response::RegisteredResponse> for v5::response::RegisteredResponse {
+    fn from(value: v4::response::RegisteredResponse) -> Self {
+        Self {
+            request_id: value.request_id,
+            reply: value.reply.into(),
+        }
+    }
+}
+
+impl From<v4::response::PendingRegistrationResponse> for v5::response::PendingRegistrationResponse {
+    fn from(value: v4::response::PendingRegistrationResponse) -> Self {
+        Self {
+            request_id: value.request_id,
+            reply: value.reply.into(),
+        }
+    }
+}
+
+impl From<v4::registration::RegistrationData> for v5::registration::RegistrationData {
+    fn from(value: v4::registration::RegistrationData) -> Self {
+        Self {
+            nonce: value.nonce,
+            gateway_data: value.gateway_data.into(),
+            wg_port: value.wg_port,
+        }
+    }
+}
+
+impl From<v5::registration::RegistrationData> for v4::registration::RegistrationData {
+    fn from(value: v5::registration::RegistrationData) -> Self {
+        Self {
+            nonce: value.nonce,
+            gateway_data: value.gateway_data.into(),
+            wg_port: value.wg_port,
+        }
+    }
+}
+
+impl From<v4::response::RemainingBandwidthResponse> for v5::response::RemainingBandwidthResponse {
+    fn from(value: v4::response::RemainingBandwidthResponse) -> Self {
+        Self {
+            request_id: value.request_id,
+            reply: value.reply.map(Into::into),
+        }
+    }
+}
+
+impl From<v4::response::TopUpBandwidthResponse> for v5::response::TopUpBandwidthResponse {
+    fn from(value: v4::response::TopUpBandwidthResponse) -> Self {
+        Self {
+            request_id: value.request_id,
+            reply: value.reply.into(),
+        }
+    }
+}
+
+impl From<v4::registration::RegistredData> for v5::registration::RegistredData {
+    fn from(value: v4::registration::RegistredData) -> Self {
+        Self {
+            pub_key: value.pub_key,
+            private_ips: value.private_ips.into(),
+            wg_port: value.wg_port,
+        }
+    }
+}
+
+impl From<v4::registration::RemainingBandwidthData> for v5::registration::RemainingBandwidthData {
+    fn from(value: v4::registration::RemainingBandwidthData) -> Self {
+        Self {
+            available_bandwidth: value.available_bandwidth,
+        }
+    }
+}
+
+impl From<v4::registration::IpPair> for v5::registration::IpPair {
+    fn from(value: v4::registration::IpPair) -> Self {
+        Self {
+            ipv4: value.ipv4,
+            ipv6: value.ipv6,
+        }
+    }
+}
+
+impl From<v5::registration::IpPair> for v4::registration::IpPair {
+    fn from(value: v5::registration::IpPair) -> Self {
+        Self {
+            ipv4: value.ipv4,
+            ipv6: value.ipv6,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::{
+        net::{Ipv4Addr, Ipv6Addr},
+        str::FromStr,
+    };
+
+    use nym_credentials_interface::CredentialSpendingData;
+    use nym_crypto::asymmetric::encryption::PrivateKey;
+    use nym_sphinx::addressing::Recipient;
+    use nym_wireguard_types::PeerPublicKey;
+    use x25519_dalek::PublicKey;
+
+    use super::*;
+    use crate::{
+        util::tests::{CREDENTIAL_BYTES, RECIPIENT},
+        v4,
+    };
+
+    #[test]
+    fn upgrade_initial_req() {
+        let pub_key = PeerPublicKey::new(PublicKey::from([0; 32]));
+        let reply_to = Recipient::try_from_base58_string(RECIPIENT).unwrap();
+
+        let (msg, _) = v4::request::AuthenticatorRequest::new_initial_request(
+            v4::registration::InitMessage::new(pub_key),
+            reply_to,
+        );
+        let upgraded_msg = v5::request::AuthenticatorRequest::from(msg);
+
+        assert_eq!(
+            upgraded_msg.protocol,
+            Protocol {
+                version: 5,
+                service_provider_type: ServiceProviderType::Authenticator
+            }
+        );
+        assert_eq!(
+            upgraded_msg.data,
+            v5::request::AuthenticatorRequestData::Initial(v5::registration::InitMessage {
+                pub_key
+            })
+        );
+    }
+
+    #[test]
+    fn upgrade_final_req() {
+        let mut rng = rand::thread_rng();
+
+        let local_secret = PrivateKey::new(&mut rng);
+        let remote_secret = x25519_dalek::StaticSecret::random_from_rng(&mut rng);
+        let ipv4 = Ipv4Addr::from_str("10.10.10.10").unwrap();
+        let ipv6 = Ipv6Addr::from_str("fc01::a0a").unwrap();
+        let ips = v4::registration::IpPair::new(ipv4, ipv6);
+        let nonce = 42;
+        let gateway_client = v4::registration::GatewayClient::new(
+            &local_secret,
+            (&remote_secret).into(),
+            ips,
+            nonce,
+        );
+        let credential = Some(CredentialSpendingData::try_from_bytes(&CREDENTIAL_BYTES).unwrap());
+        let final_message = v4::registration::FinalMessage {
+            gateway_client: gateway_client.clone(),
+            credential: credential.clone(),
+        };
+        let reply_to = Recipient::try_from_base58_string(RECIPIENT).unwrap();
+
+        let (msg, _) =
+            v4::request::AuthenticatorRequest::new_final_request(final_message, reply_to);
+        let upgraded_msg = v5::request::AuthenticatorRequest::from(msg);
+
+        assert_eq!(
+            upgraded_msg.protocol,
+            Protocol {
+                version: 5,
+                service_provider_type: ServiceProviderType::Authenticator
+            }
+        );
+        assert_eq!(
+            upgraded_msg.data,
+            v5::request::AuthenticatorRequestData::Final(Box::new(
+                v5::registration::FinalMessage {
+                    gateway_client: v5::registration::GatewayClient::new(
+                        &local_secret,
+                        (&remote_secret).into(),
+                        v5::registration::IpPair::new(ipv4, ipv6),
+                        nonce
+                    ),
+                    credential
+                }
+            ))
+        );
+    }
+
+    #[test]
+    fn upgrade_query_req() {
+        let pub_key = PeerPublicKey::new(PublicKey::from([0; 32]));
+        let reply_to = Recipient::try_from_base58_string(RECIPIENT).unwrap();
+
+        let (msg, _) = v4::request::AuthenticatorRequest::new_query_request(pub_key, reply_to);
+        let upgraded_msg = v5::request::AuthenticatorRequest::from(msg);
+
+        assert_eq!(
+            upgraded_msg.protocol,
+            Protocol {
+                version: 5,
+                service_provider_type: ServiceProviderType::Authenticator
+            }
+        );
+        assert_eq!(
+            upgraded_msg.data,
+            v5::request::AuthenticatorRequestData::QueryBandwidth(pub_key)
+        );
+    }
+
+    #[test]
+    fn upgrade_pending_reg_resp() {
+        let mut rng = rand::thread_rng();
+
+        let local_secret = PrivateKey::new(&mut rng);
+        let remote_secret = x25519_dalek::StaticSecret::random_from_rng(&mut rng);
+        let ipv4 = Ipv4Addr::from_str("10.10.10.10").unwrap();
+        let ipv6 = Ipv6Addr::from_str("fc01::a0a").unwrap();
+        let ips = v4::registration::IpPair::new(ipv4, ipv6);
+        let nonce = 42;
+        let wg_port = 51822;
+        let gateway_data = v4::registration::GatewayClient::new(
+            &local_secret,
+            (&remote_secret).into(),
+            ips,
+            nonce,
+        );
+        let registration_data = v4::registration::RegistrationData {
+            nonce,
+            gateway_data,
+            wg_port,
+        };
+        let request_id = 123;
+        let reply_to = Recipient::try_from_base58_string(RECIPIENT).unwrap();
+
+        let msg = v4::response::AuthenticatorResponse::new_pending_registration_success(
+            registration_data,
+            request_id,
+            reply_to,
+        );
+        let upgraded_msg = v5::response::AuthenticatorResponse::from(msg);
+
+        assert_eq!(
+            upgraded_msg.protocol,
+            Protocol {
+                version: 5,
+                service_provider_type: ServiceProviderType::Authenticator
+            }
+        );
+
+        assert_eq!(
+            upgraded_msg.data,
+            v5::response::AuthenticatorResponseData::PendingRegistration(
+                v5::response::PendingRegistrationResponse {
+                    request_id,
+                    reply: v5::registration::RegistrationData {
+                        nonce,
+                        gateway_data: v5::registration::GatewayClient::new(
+                            &local_secret,
+                            (&remote_secret).into(),
+                            v5::registration::IpPair::new(ipv4, ipv6),
+                            nonce
+                        ),
+                        wg_port
+                    }
+                }
+            )
+        );
+    }
+
+    #[test]
+    fn upgrade_registered_resp() {
+        let pub_key = PeerPublicKey::new(PublicKey::from([0; 32]));
+        let ipv4 = Ipv4Addr::from_str("10.1.10.10").unwrap();
+        let ipv6 = Ipv6Addr::from_str("fc01::a0a").unwrap();
+        let private_ips = v4::registration::IpPair::new(ipv4, ipv6);
+        let wg_port = 51822;
+        let registred_data = v4::registration::RegistredData {
+            pub_key,
+            private_ips,
+            wg_port,
+        };
+        let request_id = 123;
+        let reply_to = Recipient::try_from_base58_string(RECIPIENT).unwrap();
+
+        let msg = v4::response::AuthenticatorResponse::new_registered(
+            registred_data,
+            reply_to,
+            request_id,
+        );
+        let upgraded_msg = v5::response::AuthenticatorResponse::from(msg);
+
+        assert_eq!(
+            upgraded_msg.protocol,
+            Protocol {
+                version: 5,
+                service_provider_type: ServiceProviderType::Authenticator
+            }
+        );
+        assert_eq!(
+            upgraded_msg.data,
+            v5::response::AuthenticatorResponseData::Registered(v5::response::RegisteredResponse {
+                request_id,
+                reply: v5::registration::RegistredData {
+                    wg_port,
+                    pub_key,
+                    private_ips: v5::registration::IpPair::new(ipv4, ipv6)
+                }
+            })
+        );
+    }
+
+    #[test]
+    fn upgrade_remaining_bandwidth_resp() {
+        let available_bandwidth = 42;
+        let remaining_bandwidth_data = Some(v4::registration::RemainingBandwidthData {
+            available_bandwidth,
+        });
+        let request_id = 123;
+        let reply_to = Recipient::try_from_base58_string(RECIPIENT).unwrap();
+
+        let msg = v4::response::AuthenticatorResponse::new_remaining_bandwidth(
+            remaining_bandwidth_data,
+            reply_to,
+            request_id,
+        );
+        let upgraded_msg = v5::response::AuthenticatorResponse::from(msg);
+
+        assert_eq!(
+            upgraded_msg.protocol,
+            Protocol {
+                version: 5,
+                service_provider_type: ServiceProviderType::Authenticator
+            }
+        );
+        assert_eq!(
+            upgraded_msg.data,
+            v5::response::AuthenticatorResponseData::RemainingBandwidth(
+                v5::response::RemainingBandwidthResponse {
+                    request_id,
+                    reply: Some(v5::registration::RemainingBandwidthData {
+                        available_bandwidth,
+                    })
+                }
+            )
+        );
+    }
+}
@@ -0,0 +1,10 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+pub mod conversion;
+pub mod registration;
+pub mod request;
+pub mod response;
+pub mod topup;
+
+pub const VERSION: u8 = 5;
@@ -0,0 +1,287 @@
+// -2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::error::Error;
+use base64::{engine::general_purpose, Engine};
+use nym_credentials_interface::CredentialSpendingData;
+use nym_network_defaults::constants::{WG_TUN_DEVICE_IP_ADDRESS_V4, WG_TUN_DEVICE_IP_ADDRESS_V6};
+use nym_wireguard_types::PeerPublicKey;
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
+use std::time::SystemTime;
+use std::{fmt, ops::Deref, str::FromStr};
+
+#[cfg(feature = "verify")]
+use hmac::{Hmac, Mac};
+#[cfg(feature = "verify")]
+use nym_crypto::asymmetric::encryption::PrivateKey;
+#[cfg(feature = "verify")]
+use sha2::Sha256;
+
+pub type PendingRegistrations = HashMap<PeerPublicKey, RegistrationData>;
+pub type PrivateIPs = HashMap<IpPair, Taken>;
+
+#[cfg(feature = "verify")]
+pub type HmacSha256 = Hmac<Sha256>;
+
+pub type Nonce = u64;
+pub type Taken = Option<SystemTime>;
+
+pub const BANDWIDTH_CAP_PER_DAY: u64 = 250 * 1024 * 1024 * 1024; // 250 GB
+
+#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub struct IpPair {
+    pub ipv4: Ipv4Addr,
+    pub ipv6: Ipv6Addr,
+}
+
+impl IpPair {
+    pub fn new(ipv4: Ipv4Addr, ipv6: Ipv6Addr) -> Self {
+        IpPair { ipv4, ipv6 }
+    }
+}
+
+impl From<(Ipv4Addr, Ipv6Addr)> for IpPair {
+    fn from((ipv4, ipv6): (Ipv4Addr, Ipv6Addr)) -> Self {
+        IpPair { ipv4, ipv6 }
+    }
+}
+
+impl fmt::Display for IpPair {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "({}, {})", self.ipv4, self.ipv6)
+    }
+}
+
+impl From<IpAddr> for IpPair {
+    fn from(value: IpAddr) -> Self {
+        let (before_last_byte, last_byte) = match value {
+            std::net::IpAddr::V4(ipv4_addr) => (ipv4_addr.octets()[2], ipv4_addr.octets()[3]),
+            std::net::IpAddr::V6(ipv6_addr) => (ipv6_addr.octets()[14], ipv6_addr.octets()[15]),
+        };
+        let last_bytes = ((before_last_byte as u16) << 8) | last_byte as u16;
+        let ipv4 = Ipv4Addr::new(
+            WG_TUN_DEVICE_IP_ADDRESS_V4.octets()[0],
+            WG_TUN_DEVICE_IP_ADDRESS_V4.octets()[1],
+            before_last_byte,
+            last_byte,
+        );
+        let ipv6 = Ipv6Addr::new(
+            WG_TUN_DEVICE_IP_ADDRESS_V6.segments()[0],
+            WG_TUN_DEVICE_IP_ADDRESS_V6.segments()[1],
+            WG_TUN_DEVICE_IP_ADDRESS_V6.segments()[2],
+            WG_TUN_DEVICE_IP_ADDRESS_V6.segments()[3],
+            WG_TUN_DEVICE_IP_ADDRESS_V6.segments()[4],
+            WG_TUN_DEVICE_IP_ADDRESS_V6.segments()[5],
+            WG_TUN_DEVICE_IP_ADDRESS_V6.segments()[6],
+            last_bytes,
+        );
+        IpPair::new(ipv4, ipv6)
+    }
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
+pub struct InitMessage {
+    /// Base64 encoded x25519 public key
+    pub pub_key: PeerPublicKey,
+}
+
+impl InitMessage {
+    pub fn new(pub_key: PeerPublicKey) -> Self {
+        InitMessage { pub_key }
+    }
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
+pub struct FinalMessage {
+    /// Gateway client data
+    pub gateway_client: GatewayClient,
+
+    /// Ecash credential
+    pub credential: Option<CredentialSpendingData>,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
+pub struct RegistrationData {
+    pub nonce: u64,
+    pub gateway_data: GatewayClient,
+    pub wg_port: u16,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
+pub struct RegistredData {
+    pub pub_key: PeerPublicKey,
+    pub private_ips: IpPair,
+    pub wg_port: u16,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
+pub struct RemainingBandwidthData {
+    pub available_bandwidth: i64,
+}
+
+/// Client that wants to register sends its PublicKey bytes mac digest encrypted with a DH shared secret.
+/// Gateway/Nym node can then verify pub_key payload using the same process
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
+pub struct GatewayClient {
+    /// Base64 encoded x25519 public key
+    pub pub_key: PeerPublicKey,
+
+    /// Assigned private IPs (v4 and v6)
+    pub private_ips: IpPair,
+
+    /// Sha256 hmac on the data (alongside the prior nonce)
+    pub mac: ClientMac,
+}
+
+impl GatewayClient {
+    #[cfg(feature = "verify")]
+    pub fn new(
+        local_secret: &PrivateKey,
+        remote_public: x25519_dalek::PublicKey,
+        private_ips: IpPair,
+        nonce: u64,
+    ) -> Self {
+        // convert from 1.0 x25519-dalek private key into 2.0 x25519-dalek
+        #[allow(clippy::expect_used)]
+        let static_secret = x25519_dalek::StaticSecret::from(local_secret.to_bytes());
+        let local_public: x25519_dalek::PublicKey = (&static_secret).into();
+
+        let dh = static_secret.diffie_hellman(&remote_public);
+
+        // TODO: change that to use our nym_crypto::hmac module instead
+        #[allow(clippy::expect_used)]
+        let mut mac = HmacSha256::new_from_slice(dh.as_bytes())
+            .expect("x25519 shared secret is always 32 bytes long");
+
+        mac.update(local_public.as_bytes());
+        mac.update(private_ips.to_string().as_bytes());
+        mac.update(&nonce.to_le_bytes());
+
+        GatewayClient {
+            pub_key: PeerPublicKey::new(local_public),
+            private_ips,
+            mac: ClientMac(mac.finalize().into_bytes().to_vec()),
+        }
+    }
+
+    // Reusable secret should be gateways Wireguard PK
+    // Client should perform this step when generating its payload, using its own WG PK
+    #[cfg(feature = "verify")]
+    pub fn verify(&self, gateway_key: &PrivateKey, nonce: u64) -> Result<(), Error> {
+        // convert from 1.0 x25519-dalek private key into 2.0 x25519-dalek
+        #[allow(clippy::expect_used)]
+        let static_secret = x25519_dalek::StaticSecret::from(gateway_key.to_bytes());
+
+        let dh = static_secret.diffie_hellman(&self.pub_key);
+
+        // TODO: change that to use our nym_crypto::hmac module instead
+        #[allow(clippy::expect_used)]
+        let mut mac = HmacSha256::new_from_slice(dh.as_bytes())
+            .expect("x25519 shared secret is always 32 bytes long");
+
+        mac.update(self.pub_key.as_bytes());
+        mac.update(self.private_ips.to_string().as_bytes());
+        mac.update(&nonce.to_le_bytes());
+
+        mac.verify_slice(&self.mac)
+            .map_err(|source| Error::FailedClientMacVerification {
+                client: self.pub_key.to_string(),
+                source,
+            })
+    }
+
+    pub fn pub_key(&self) -> PeerPublicKey {
+        self.pub_key
+    }
+}
+
+// TODO: change the inner type into generic array of size HmacSha256::OutputSize
+// TODO2: rely on our internal crypto/hmac
+#[derive(Debug, Clone, PartialEq)]
+pub struct ClientMac(Vec<u8>);
+
+impl fmt::Display for ClientMac {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}", general_purpose::STANDARD.encode(&self.0))
+    }
+}
+
+impl ClientMac {
+    #[allow(dead_code)]
+    pub fn new(mac: Vec<u8>) -> Self {
+        ClientMac(mac)
+    }
+}
+
+impl Deref for ClientMac {
+    type Target = Vec<u8>;
+
+    fn deref(&self) -> &Self::Target {
+        &self.0
+    }
+}
+
+impl FromStr for ClientMac {
+    type Err = Error;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        let mac_bytes: Vec<u8> =
+            general_purpose::STANDARD
+                .decode(s)
+                .map_err(|source| Error::MalformedClientMac {
+                    mac: s.to_string(),
+                    source,
+                })?;
+
+        Ok(ClientMac(mac_bytes))
+    }
+}
+
+impl Serialize for ClientMac {
+    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        let encoded_key = general_purpose::STANDARD.encode(self.0.clone());
+        serializer.serialize_str(&encoded_key)
+    }
+}
+
+impl<'de> Deserialize<'de> for ClientMac {
+    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+        let encoded_key = String::deserialize(deserializer)?;
+        ClientMac::from_str(&encoded_key).map_err(serde::de::Error::custom)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use nym_crypto::asymmetric::encryption;
+
+    #[test]
+    fn create_ip_pair() {
+        let ipv4: IpAddr = Ipv4Addr::from_str("10.1.10.50").unwrap().into();
+        let ipv6: IpAddr = Ipv6Addr::from_str("fc01::0a32").unwrap().into();
+
+        assert_eq!(IpPair::from(ipv4), IpPair::from(ipv6));
+    }
+
+    #[test]
+    #[cfg(feature = "verify")]
+    fn client_request_roundtrip() {
+        let mut rng = rand::thread_rng();
+
+        let gateway_key_pair = encryption::KeyPair::new(&mut rng);
+        let client_key_pair = encryption::KeyPair::new(&mut rng);
+
+        let nonce = 1234567890;
+
+        let client = GatewayClient::new(
+            client_key_pair.private_key(),
+            x25519_dalek::PublicKey::from(gateway_key_pair.public_key().to_bytes()),
+            IpPair::new("10.0.0.42".parse().unwrap(), "fc00::42".parse().unwrap()),
+            nonce,
+        );
+        assert!(client.verify(gateway_key_pair.private_key(), nonce).is_ok())
+    }
+}
@@ -0,0 +1,132 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use super::{
+    registration::{FinalMessage, InitMessage},
+    topup::TopUpMessage,
+};
+use nym_service_provider_requests_common::{Protocol, ServiceProviderType};
+use nym_wireguard_types::PeerPublicKey;
+use serde::{Deserialize, Serialize};
+
+use crate::make_bincode_serializer;
+
+use super::VERSION;
+
+fn generate_random() -> u64 {
+    use rand::RngCore;
+    let mut rng = rand::rngs::OsRng;
+    rng.next_u64()
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+pub struct AuthenticatorRequest {
+    pub protocol: Protocol,
+    pub data: AuthenticatorRequestData,
+    pub request_id: u64,
+}
+
+impl AuthenticatorRequest {
+    pub fn from_reconstructed_message(
+        message: &nym_sphinx::receiver::ReconstructedMessage,
+    ) -> Result<Self, bincode::Error> {
+        use bincode::Options;
+        make_bincode_serializer().deserialize(&message.message)
+    }
+
+    pub fn new_initial_request(init_message: InitMessage) -> (Self, u64) {
+        let request_id = generate_random();
+        (
+            Self {
+                protocol: Protocol {
+                    service_provider_type: ServiceProviderType::Authenticator,
+                    version: VERSION,
+                },
+                data: AuthenticatorRequestData::Initial(init_message),
+                request_id,
+            },
+            request_id,
+        )
+    }
+
+    pub fn new_final_request(final_message: FinalMessage) -> (Self, u64) {
+        let request_id = generate_random();
+        (
+            Self {
+                protocol: Protocol {
+                    service_provider_type: ServiceProviderType::Authenticator,
+                    version: VERSION,
+                },
+                data: AuthenticatorRequestData::Final(Box::new(final_message)),
+                request_id,
+            },
+            request_id,
+        )
+    }
+
+    pub fn new_query_request(peer_public_key: PeerPublicKey) -> (Self, u64) {
+        let request_id = generate_random();
+        (
+            Self {
+                protocol: Protocol {
+                    service_provider_type: ServiceProviderType::Authenticator,
+                    version: VERSION,
+                },
+                data: AuthenticatorRequestData::QueryBandwidth(peer_public_key),
+                request_id,
+            },
+            request_id,
+        )
+    }
+
+    pub fn new_topup_request(top_up_message: TopUpMessage) -> (Self, u64) {
+        let request_id = generate_random();
+        (
+            Self {
+                protocol: Protocol {
+                    service_provider_type: ServiceProviderType::Authenticator,
+                    version: VERSION,
+                },
+                data: AuthenticatorRequestData::TopUpBandwidth(Box::new(top_up_message)),
+                request_id,
+            },
+            request_id,
+        )
+    }
+
+    pub fn to_bytes(&self) -> Result<Vec<u8>, bincode::Error> {
+        use bincode::Options;
+        make_bincode_serializer().serialize(self)
+    }
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+pub enum AuthenticatorRequestData {
+    Initial(InitMessage),
+    Final(Box<FinalMessage>),
+    QueryBandwidth(PeerPublicKey),
+    TopUpBandwidth(Box<TopUpMessage>),
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::str::FromStr;
+
+    #[test]
+    fn check_first_bytes_protocol() {
+        let version = 5;
+        let data = AuthenticatorRequest {
+            protocol: Protocol {
+                version,
+                service_provider_type: ServiceProviderType::Authenticator,
+            },
+            data: AuthenticatorRequestData::Initial(InitMessage::new(
+                PeerPublicKey::from_str("yvNUDpT5l7W/xDhiu6HkqTHDQwbs/B3J5UrLmORl1EQ=").unwrap(),
+            )),
+            request_id: 1,
+        };
+        let bytes = *data.to_bytes().unwrap().first_chunk::<2>().unwrap();
+        assert_eq!(bytes, [version, ServiceProviderType::Authenticator as u8]);
+    }
+}
@@ -0,0 +1,132 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use super::registration::{RegistrationData, RegistredData, RemainingBandwidthData};
+use nym_service_provider_requests_common::{Protocol, ServiceProviderType};
+use serde::{Deserialize, Serialize};
+
+use crate::make_bincode_serializer;
+
+use super::VERSION;
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+pub struct AuthenticatorResponse {
+    pub protocol: Protocol,
+    pub data: AuthenticatorResponseData,
+}
+
+impl AuthenticatorResponse {
+    pub fn new_pending_registration_success(
+        registration_data: RegistrationData,
+        request_id: u64,
+    ) -> Self {
+        Self {
+            protocol: Protocol {
+                service_provider_type: ServiceProviderType::Authenticator,
+                version: VERSION,
+            },
+            data: AuthenticatorResponseData::PendingRegistration(PendingRegistrationResponse {
+                reply: registration_data,
+                request_id,
+            }),
+        }
+    }
+
+    pub fn new_registered(registred_data: RegistredData, request_id: u64) -> Self {
+        Self {
+            protocol: Protocol {
+                service_provider_type: ServiceProviderType::Authenticator,
+                version: VERSION,
+            },
+            data: AuthenticatorResponseData::Registered(RegisteredResponse {
+                reply: registred_data,
+                request_id,
+            }),
+        }
+    }
+
+    pub fn new_remaining_bandwidth(
+        remaining_bandwidth_data: Option<RemainingBandwidthData>,
+        request_id: u64,
+    ) -> Self {
+        Self {
+            protocol: Protocol {
+                service_provider_type: ServiceProviderType::Authenticator,
+                version: VERSION,
+            },
+            data: AuthenticatorResponseData::RemainingBandwidth(RemainingBandwidthResponse {
+                reply: remaining_bandwidth_data,
+                request_id,
+            }),
+        }
+    }
+
+    pub fn new_topup_bandwidth(
+        remaining_bandwidth_data: RemainingBandwidthData,
+        request_id: u64,
+    ) -> Self {
+        Self {
+            protocol: Protocol {
+                service_provider_type: ServiceProviderType::Authenticator,
+                version: VERSION,
+            },
+            data: AuthenticatorResponseData::TopUpBandwidth(TopUpBandwidthResponse {
+                reply: remaining_bandwidth_data,
+                request_id,
+            }),
+        }
+    }
+
+    pub fn to_bytes(&self) -> Result<Vec<u8>, bincode::Error> {
+        use bincode::Options;
+        make_bincode_serializer().serialize(self)
+    }
+
+    pub fn from_reconstructed_message(
+        message: &nym_sphinx::receiver::ReconstructedMessage,
+    ) -> Result<Self, bincode::Error> {
+        use bincode::Options;
+        make_bincode_serializer().deserialize(&message.message)
+    }
+
+    pub fn id(&self) -> Option<u64> {
+        match &self.data {
+            AuthenticatorResponseData::PendingRegistration(response) => Some(response.request_id),
+            AuthenticatorResponseData::Registered(response) => Some(response.request_id),
+            AuthenticatorResponseData::RemainingBandwidth(response) => Some(response.request_id),
+            AuthenticatorResponseData::TopUpBandwidth(response) => Some(response.request_id),
+        }
+    }
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+pub enum AuthenticatorResponseData {
+    PendingRegistration(PendingRegistrationResponse),
+    Registered(RegisteredResponse),
+    RemainingBandwidth(RemainingBandwidthResponse),
+    TopUpBandwidth(TopUpBandwidthResponse),
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+pub struct PendingRegistrationResponse {
+    pub request_id: u64,
+    pub reply: RegistrationData,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+pub struct RegisteredResponse {
+    pub request_id: u64,
+    pub reply: RegistredData,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+pub struct RemainingBandwidthResponse {
+    pub request_id: u64,
+    pub reply: Option<RemainingBandwidthData>,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+pub struct TopUpBandwidthResponse {
+    pub request_id: u64,
+    pub reply: RemainingBandwidthData,
+}
@@ -0,0 +1,15 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use nym_credentials_interface::CredentialSpendingData;
+use nym_wireguard_types::PeerPublicKey;
+use serde::{Deserialize, Serialize};
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
+pub struct TopUpMessage {
+    /// Base64 encoded x25519 public key
+    pub pub_key: PeerPublicKey,
+
+    /// Ecash credential
+    pub credential: CredentialSpendingData,
+}
@@ -45,11 +45,12 @@ const DEFAULT_COVER_TRAFFIC_PRIMARY_SIZE_RATIO: f64 = 0.70;
 // clients/client-core/src/client/replies/reply_storage/surb_storage.rs
 const DEFAULT_MINIMUM_REPLY_SURB_STORAGE_THRESHOLD: usize = 10;
 const DEFAULT_MAXIMUM_REPLY_SURB_STORAGE_THRESHOLD: usize = 200;
+const DEFAULT_MINIMUM_REPLY_SURB_THRESHOLD_BUFFER: usize = 0;

 // define how much to request at once
 // clients/client-core/src/client/replies/reply_controller.rs
 const DEFAULT_MINIMUM_REPLY_SURB_REQUEST_SIZE: u32 = 10;
-const DEFAULT_MAXIMUM_REPLY_SURB_REQUEST_SIZE: u32 = 100;
+const DEFAULT_MAXIMUM_REPLY_SURB_REQUEST_SIZE: u32 = 50;

 const DEFAULT_MAXIMUM_ALLOWED_SURB_REQUEST_SIZE: u32 = 500;

@@ -621,6 +622,10 @@ pub struct ReplySurbs {
    /// Defines the maximum number of reply surbs the client wants to keep in its storage at any times.
    pub maximum_reply_surb_storage_threshold: usize,

+    /// Defines the soft threshold ontop of the minimum reply surb storage threshold for when the client
+    /// should proactively request additional reply surbs.
+    pub minimum_reply_surb_threshold_buffer: usize,
+
    /// Defines the minimum number of reply surbs the client would request.
    pub minimum_reply_surb_request_size: u32,

@@ -653,6 +658,9 @@ pub struct ReplySurbs {
    /// Specifies the number of mixnet hops the packet should go through. If not specified, then
    /// the default value is used.
    pub surb_mix_hops: Option<u8>,
+
+    /// Specifies if we should reset all the sender tags on startup
+    pub fresh_sender_tags: bool,
 }

 impl Default for ReplySurbs {
@@ -660,6 +668,7 @@ impl Default for ReplySurbs {
        ReplySurbs {
            minimum_reply_surb_storage_threshold: DEFAULT_MINIMUM_REPLY_SURB_STORAGE_THRESHOLD,
            maximum_reply_surb_storage_threshold: DEFAULT_MAXIMUM_REPLY_SURB_STORAGE_THRESHOLD,
+            minimum_reply_surb_threshold_buffer: DEFAULT_MINIMUM_REPLY_SURB_THRESHOLD_BUFFER,
            minimum_reply_surb_request_size: DEFAULT_MINIMUM_REPLY_SURB_REQUEST_SIZE,
            maximum_reply_surb_request_size: DEFAULT_MAXIMUM_REPLY_SURB_REQUEST_SIZE,
            maximum_allowed_reply_surb_request_size: DEFAULT_MAXIMUM_ALLOWED_SURB_REQUEST_SIZE,
@@ -669,6 +678,7 @@ impl Default for ReplySurbs {
            maximum_reply_surb_age: DEFAULT_MAXIMUM_REPLY_SURB_AGE,
            maximum_reply_key_age: DEFAULT_MAXIMUM_REPLY_KEY_AGE,
            surb_mix_hops: None,
+            fresh_sender_tags: false,
        }
    }
 }
@@ -181,6 +181,7 @@ impl From<ConfigV5> for Config {
                    maximum_reply_surb_age: value.debug.reply_surbs.maximum_reply_surb_age,
                    maximum_reply_key_age: value.debug.reply_surbs.maximum_reply_key_age,
                    surb_mix_hops: value.debug.reply_surbs.surb_mix_hops,
+                    ..Default::default()
                },
                ..Default::default()
            },
@@ -22,7 +22,7 @@ use crate::client::replies::reply_controller::{ReplyControllerReceiver, ReplyCon
 use crate::client::replies::reply_storage::{
    CombinedReplyStorage, PersistentReplyStorage, ReplyStorageBackend, SentReplyKeys,
 };
-use crate::client::topology_control::nym_api_provider::NymApiTopologyProvider;
+use crate::client::topology_control::smart_api_provider::NymApiTopologyProvider;
 use crate::client::topology_control::{
    TopologyAccessor, TopologyRefresher, TopologyRefresherConfig,
 };
@@ -54,8 +54,7 @@ use nym_statistics_common::clients::ClientStatsSender;
 use nym_statistics_common::generate_client_stats_id;
 use nym_task::connections::{ConnectionCommandReceiver, ConnectionCommandSender, LaneQueueLengths};
 use nym_task::{TaskClient, TaskHandle};
-use nym_topology::provider_trait::TopologyProvider;
-use nym_topology::HardcodedTopologyProvider;
+use nym_topology::providers::{HardcodedTopologyProvider, TopologyProvider};
 use nym_validator_client::{nyxd::contract_traits::DkgQueryClient, UserAgent};
 use rand::rngs::OsRng;
 use std::fmt::Debug;
@@ -557,6 +556,7 @@ where
                config_topology,
                nym_api_urls,
                user_agent,
+                None,
            )),
            config::TopologyStructure::GeoAware(group_by) => {
                warn!("using deprecated 'GeoAware' topology provider - this option will be removed very soon");
@@ -88,7 +88,7 @@ pub async fn setup_fs_reply_surb_backend<P: AsRef<Path>>(
    let db_path = db_path.as_ref();
    if db_path.exists() {
        info!("loading existing surb database");
-        match fs_backend::Backend::try_load(db_path).await {
+        match fs_backend::Backend::try_load(db_path, surb_config.fresh_sender_tags).await {
            Ok(backend) => Ok(backend),
            Err(err) => {
                error!("failed to setup persistent storage backend for our reply needs: {err}. We're going to create a fresh database instead. This behaviour might change in the future");
@@ -33,10 +33,12 @@ pub enum PreparationError {
    #[error(transparent)]
    NymTopologyError(#[from] NymTopologyError),

-    #[error("The received message cannot be sent using a single reply surb. It ended up getting split into {fragments} fragments.")]
+    #[error("message too long for a single SURB, splitting into {fragments} fragments.")]
    MessageTooLongForSingleSurb { fragments: usize },

-    #[error("Not enough reply SURBs to send the message. We have {available} available and require at least {required}.")]
+    #[error(
+        "not enough reply SURBs to send the message, available: {available} required: {required}."
+    )]
    NotEnoughSurbs { available: usize, required: usize },
 }

@@ -517,17 +517,25 @@ where
        use crate::error::ClientCoreStatusMessage;

        let packets = self.transmission_buffer.total_size();
-        let backlog = self.transmission_buffer.total_size_in_bytes() as f64 / 1024.0;
-        let lanes = self.transmission_buffer.num_lanes();
+        let lanes = self.transmission_buffer.lanes();
        let mult = self.sending_delay_controller.current_multiplier();
        let delay = self.current_average_message_sending_delay().as_millis();
+
+        let lane_status = lanes
+            .iter()
+            .map(|lane_name| {
+                let lane_length = self.transmission_buffer.lane_length(lane_name).unwrap_or(0);
+                format!("{lane_name:?}: {lane_length}")
+            })
+            .collect::<Vec<String>>()
+            .join(", ");
+
        let status_str = if self.config.traffic.disable_main_poisson_packet_distribution {
-            format!("Packet backlog: {backlog:.2} kiB ({packets}), {lanes} lanes, no delay")
+            format!("Packet backlog: {lane_status}, no delay")
        } else {
-            format!(
-                "Packet backlog: {backlog:.2} kiB ({packets}), {lanes} lanes, avg delay: {delay}ms ({mult})"
-            )
+            format!("Packet backlog: {lane_status}, avg delay: {delay}ms ({mult})")
        };
+
        if packets > 1000 {
            log::warn!("{status_str}");
        } else if packets > 0 {
@@ -102,6 +102,7 @@ where
        fragments: I,
        lane: TransmissionLane,
    ) {
+        trace!("buffering pending replies for {recipient}");
        self.pending_replies
            .entry(*recipient)
            .or_insert_with(TransmissionBuffer::new)
@@ -113,6 +114,7 @@ where
        recipient: &AnonymousSenderTag,
        fragments: Vec<(TransmissionLane, Fragment)>,
    ) {
+        trace!("re-inserting pending replies for {recipient}");
        // the buffer should ALWAYS exist at this point, if it doesn't, it's a bug...
        self.pending_replies
            .entry(*recipient)
@@ -125,6 +127,7 @@ where
        recipient: &AnonymousSenderTag,
        data: Vec<Arc<PendingAcknowledgement>>,
    ) {
+        trace!("re-inserting pending retransmissions for {recipient}");
        // the underlying entry MUST exist as we've just got data from there
        let map_entry = self
            .pending_retransmissions
@@ -142,7 +145,7 @@ where
    }

    fn should_request_more_surbs(&self, target: &AnonymousSenderTag) -> bool {
-        trace!("checking if we should request more surbs from {:?}", target);
+        trace!("checking if we should request more surbs from {target}");

        let pending_queue_size = self
            .pending_replies
@@ -158,11 +161,6 @@ where

        let total_queue = pending_queue_size + retransmission_queue;

-        // simple as that - there's absolutely nothing to retransmit
-        if total_queue == 0 {
-            return false;
-        }
-
        let available_surbs = self
            .full_reply_storage
            .surbs_storage_ref()
@@ -179,11 +177,27 @@ where
            .full_reply_storage
            .surbs_storage_ref()
            .max_surb_threshold();
+        let min_surbs_threshold_buffer =
+            self.config.reply_surbs.minimum_reply_surb_threshold_buffer;

-        debug!("total queue size: {total_queue} = pending data {pending_queue_size} + pending retransmission {retransmission_queue}, available surbs: {available_surbs} pending surbs: {pending_surbs} threshold range: {min_surbs_threshold}..{max_surbs_threshold}");
+        // After clearing the queue, we want to have at least `min_surbs_threshold` surbs available
+        // and reserved for requesting additional surbs, and in addition to that we also want to
+        // have `min_surbs_threshold_buffer` surbs available proactively.
+        let target_surbs_after_clearing_queue = min_surbs_threshold + min_surbs_threshold_buffer;

-        (pending_surbs + available_surbs) < max_surbs_threshold
-            && (pending_surbs + available_surbs) < (total_queue + min_surbs_threshold)
+        // Check if we have enough surbs to handle the total queue and maintain minimum thresholds
+        let total_required_surbs = total_queue + target_surbs_after_clearing_queue;
+        let total_available_surbs = pending_surbs + available_surbs;
+
+        debug!("total queue size: {total_queue} = pending data {pending_queue_size} + pending retransmission {retransmission_queue}, available surbs: {available_surbs} pending surbs: {pending_surbs} threshold range: {min_surbs_threshold}..+{min_surbs_threshold_buffer}..{max_surbs_threshold}");
+
+        // We should request more surbs if:
+        // 1. We haven't hit the maximum surb threshold, and
+        // 2. We don't have enough surbs to handle the queue plus minimum thresholds
+        let is_below_max_threshold = total_available_surbs < max_surbs_threshold;
+        let is_below_required_surbs = total_available_surbs < total_required_surbs;
+
+        is_below_max_threshold && is_below_required_surbs
    }

    async fn handle_send_reply(
@@ -244,6 +258,10 @@ where
                        &recipient_tag,
                    );
                    warn!("failed to send reply to {recipient_tag}: {err}");
+                    info!(
+                        "buffering {no_fragments} fragments for {recipient_tag}",
+                        no_fragments = to_send.len()
+                    );
                    self.insert_pending_replies(&recipient_tag, to_send, lane);
                }
            }
@@ -251,6 +269,13 @@ where

        // if there's leftover data we didn't send because we didn't have enough (or any) surbs - buffer it
        if !fragments.is_empty() {
+            // Ideally we should have enough surbs above the minimum threshold to handle sending
+            // new replies without having to first request more surbs. That's why I'd like to log
+            // these cases as they might indicate a problem with the surb management.
+            debug!(
+                "buffering {no_fragments} fragments for {recipient_tag}",
+                no_fragments = fragments.len()
+            );
            self.insert_pending_replies(&recipient_tag, fragments, lane);
        }

@@ -265,6 +290,7 @@ where
        target: AnonymousSenderTag,
        amount: u32,
    ) -> Result<(), PreparationError> {
+        debug!("requesting {amount} additional reply surbs for {target}");
        let reply_surb = self
            .full_reply_storage
            .surbs_storage_ref()
@@ -686,7 +712,7 @@ where
    // it should take into consideration the average latency, sending rate and queue size.
    // it should request as many surbs as it takes to saturate its sending rate before next batch arrives
    async fn request_reply_surbs_for_queue_clearing(&mut self, target: AnonymousSenderTag) {
-        trace!("requesting surbs for queues clearing");
+        trace!("requesting surbs for queue clearing");

        let pending_queue_size = self
            .pending_replies
@@ -700,17 +726,18 @@ where
            .map(|pending_queue| pending_queue.len())
            .unwrap_or_default();

+        let min_surbs_buffer = self.config.reply_surbs.minimum_reply_surb_threshold_buffer as u32;
+
        let total_queue = (pending_queue_size + retransmission_queue) as u32;

-        if total_queue == 0 {
-            trace!("the pending queues for {:?} are already empty", target);
-            return;
-        }
+        // To proactively request additional surbs, we aim to have a buffer of extra surbs in our
+        // storage.
+        let total_queue_with_buffer = total_queue + min_surbs_buffer;

        let request_size = min(
            self.config.reply_surbs.maximum_reply_surb_request_size,
            max(
-                total_queue,
+                total_queue_with_buffer,
                self.config.reply_surbs.minimum_reply_surb_request_size,
            ),
        );
@@ -719,7 +746,7 @@ where
            .request_additional_reply_surbs(target, request_size)
            .await
        {
-            warn!("failed to request additional surbs... - {err}")
+            info!("{err}")
        }
    }

@@ -3,7 +3,7 @@ use log::{debug, error};
 use nym_explorer_client::{ExplorerClient, PrettyDetailedMixNodeBond};
 use nym_network_defaults::var_names::EXPLORER_API;
 use nym_topology::{
-    provider_trait::{async_trait, TopologyProvider},
+    providers::{async_trait, TopologyProvider},
    NymTopology,
 };
 use nym_validator_client::client::NodeId;
@@ -19,11 +19,12 @@ use wasmtimer::tokio::sleep;
 mod accessor;
 pub mod geo_aware_provider;
 pub mod nym_api_provider;
+pub mod smart_api_provider;

 #[allow(deprecated)]
 pub use geo_aware_provider::GeoAwareTopologyProvider;
-pub use nym_api_provider::{Config as NymApiTopologyProviderConfig, NymApiTopologyProvider};
-pub use nym_topology::provider_trait::TopologyProvider;
+pub use nym_topology::providers::TopologyProvider;
+pub use smart_api_provider::{Config as NymApiTopologyProviderConfig, NymApiTopologyProvider};

 // TODO: move it to config later
 const MAX_FAILURE_COUNT: usize = 10;
@@ -3,8 +3,7 @@

 use async_trait::async_trait;
 use log::{debug, error, warn};
-use nym_topology::provider_trait::TopologyProvider;
-use nym_topology::NymTopology;
+use nym_topology::{NymTopology, TopologyProvider};
 use nym_validator_client::UserAgent;
 use rand::prelude::SliceRandom;
 use rand::thread_rng;
@@ -0,0 +1,230 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: GPL-3.0-only
+
+//! Caching, piecewise API Topology Provider
+//!
+
+#![warn(missing_docs)]
+
+use async_trait::async_trait;
+use log::{debug, error, warn};
+pub use nym_topology::providers::piecewise::Config;
+use nym_topology::{
+    providers::piecewise::{NymTopologyProvider, PiecewiseTopologyProvider},
+    EpochRewardedSet, NymTopology, RoutingNode, TopologyProvider,
+};
+use nym_validator_client::UserAgent;
+use rand::{prelude::SliceRandom, thread_rng};
+use url::Url;
+
+/// Topology Provider build around a cached piecewise provider that uses the Nym API to
+/// fetch changes and node details.
+#[derive(Clone)]
+pub struct NymApiTopologyProvider {
+    inner: NymTopologyProvider<NymApiPiecewiseProvider>,
+}
+
+impl NymApiTopologyProvider {
+    /// Construct a new thread safe Cached topology provider using the Nym API
+    pub fn new(
+        config: impl Into<Config>,
+        nym_api_urls: Vec<Url>,
+        user_agent: Option<UserAgent>,
+        initial_topology: Option<NymTopology>,
+    ) -> Self {
+        let manager = NymApiPiecewiseProvider::new(nym_api_urls, user_agent);
+        let inner = NymTopologyProvider::new(manager, config.into(), initial_topology);
+
+        Self { inner }
+    }
+}
+
+impl AsRef<NymTopologyProvider<NymApiPiecewiseProvider>> for NymApiTopologyProvider {
+    fn as_ref(&self) -> &NymTopologyProvider<NymApiPiecewiseProvider> {
+        &self.inner
+    }
+}
+
+impl AsMut<NymTopologyProvider<NymApiPiecewiseProvider>> for NymApiTopologyProvider {
+    fn as_mut(&mut self) -> &mut NymTopologyProvider<NymApiPiecewiseProvider> {
+        &mut self.inner
+    }
+}
+
+#[cfg(not(target_arch = "wasm32"))]
+#[async_trait]
+impl TopologyProvider for NymApiTopologyProvider {
+    async fn get_new_topology(&mut self) -> Option<NymTopology> {
+        self.as_mut().get_new_topology().await
+    }
+}
+
+#[cfg(target_arch = "wasm32")]
+#[async_trait(?Send)]
+impl TopologyProvider for NymApiTopologyProvider {
+    async fn get_new_topology(&mut self) -> Option<NymTopology> {
+        self.as_mut().get_new_topology().await
+    }
+}
+
+#[derive(Clone)]
+struct NymApiPiecewiseProvider {
+    validator_client: nym_validator_client::client::NymApiClient,
+    nym_api_urls: Vec<Url>,
+    currently_used_api: usize,
+}
+
+impl NymApiPiecewiseProvider {
+    fn new(mut nym_api_urls: Vec<Url>, user_agent: Option<UserAgent>) -> Self {
+        nym_api_urls.shuffle(&mut thread_rng());
+
+        let validator_client = if let Some(user_agent) = user_agent {
+            nym_validator_client::client::NymApiClient::new_with_user_agent(
+                nym_api_urls[0].clone(),
+                user_agent,
+            )
+        } else {
+            nym_validator_client::client::NymApiClient::new(nym_api_urls[0].clone())
+        };
+
+        Self {
+            validator_client,
+            nym_api_urls,
+            currently_used_api: 0,
+        }
+    }
+
+    fn use_next_nym_api(&mut self) {
+        if self.nym_api_urls.len() == 1 {
+            warn!("There's only a single nym API available - it won't be possible to use a different one");
+            return;
+        }
+
+        self.currently_used_api = (self.currently_used_api + 1) % self.nym_api_urls.len();
+        self.validator_client
+            .change_nym_api(self.nym_api_urls[self.currently_used_api].clone())
+    }
+
+    async fn get_full_topology_inner(&mut self) -> Option<NymTopology> {
+        let layer_assignments = self.get_layer_assignments().await?;
+
+        let mut topology = NymTopology::new_empty(layer_assignments);
+
+        let all_nodes = self
+            .validator_client
+            .get_all_basic_nodes()
+            .await
+            .inspect_err(|err| {
+                self.use_next_nym_api();
+                error!("failed to get network nodes: {err}");
+            })
+            .ok()?;
+
+        debug!("there are {} nodes on the network", all_nodes.len());
+        topology.add_additional_nodes(all_nodes.iter());
+
+        if !topology.is_minimally_routable() {
+            error!("the current filtered active topology can't be used to construct any packets");
+            return None;
+        }
+
+        Some(topology)
+    }
+
+    async fn get_descriptor_batch_inner(&mut self, ids: &[u32]) -> Option<Vec<RoutingNode>> {
+        // Does this need to return a hashmap of RoutingNodes? that is moderately inconvenient
+        // especially when the nodes themselves contain their node_id unless we expect to directly
+        // use the result of this fn for lookups where we would otherwise for example, have to
+        // iterate over a whole vec to find a specific node_id.
+        let descriptor_vec = self
+            .validator_client
+            .retrieve_basic_nodes_batch(ids)
+            .await
+            .inspect_err(|err| {
+                self.use_next_nym_api();
+                error!("failed to get current rewarded set: {err}");
+            })
+            .ok()?;
+
+        let mut out = Vec::new();
+        for node in descriptor_vec {
+            if let Ok(routing_node) = RoutingNode::try_from(&node) {
+                out.push(routing_node);
+            }
+        }
+        Some(out)
+    }
+
+    async fn get_layer_assignments_inner(&mut self) -> Option<EpochRewardedSet> {
+        self.validator_client
+            .get_current_rewarded_set()
+            .await
+            .inspect_err(|err| {
+                self.use_next_nym_api();
+                error!("failed to get current rewarded set: {err}");
+            })
+            .ok()
+    }
+}
+
+#[cfg(not(target_arch = "wasm32"))]
+#[async_trait]
+impl PiecewiseTopologyProvider for NymApiPiecewiseProvider {
+    async fn get_full_topology(&mut self) -> Option<NymTopology> {
+        self.get_full_topology_inner().await
+    }
+
+    async fn get_descriptor_batch(&mut self, ids: &[u32]) -> Option<Vec<RoutingNode>> {
+        self.get_descriptor_batch_inner(ids).await
+    }
+
+    async fn get_layer_assignments(&mut self) -> Option<EpochRewardedSet> {
+        self.get_layer_assignments_inner().await
+    }
+}
+
+#[cfg(target_arch = "wasm32")]
+#[async_trait(?Send)]
+impl PiecewiseTopologyProvider for NymApiPiecewiseProvider {
+    async fn get_full_topology(&mut self) -> Option<NymTopology> {
+        self.get_full_topology_inner().await
+    }
+
+    async fn get_descriptor_batch(&mut self, ids: &[u32]) -> Option<Vec<RoutingNode>> {
+        self.get_descriptor_batch_inner(ids).await
+    }
+
+    async fn get_layer_assignments(&mut self) -> Option<EpochRewardedSet> {
+        self.get_layer_assignments_inner().await
+    }
+}
+
+// // Test requires running a local instance of the nym-api binary, for example using:
+// //   `RUST_LOG="info" ./target/debug/nym-api run --nyxd-validator "https://rpc.nymtech.net"`
+
+// #[cfg(test)]
+// mod test {
+//     use std::time::Duration;
+
+//     use super::*;
+//     use nym_bin_common::logging::setup_tracing_logger;
+
+//     #[tokio::test]
+//     async fn local_api_provider_test() {
+//         setup_tracing_logger();
+//         let mut provider = NymApiTopologyProvider::new(
+//             Config::default(),
+//             vec!["http://localhost:8000"
+//                 .parse()
+//                 .expect("failed to parse api url")],
+//             None,
+//             None,
+//         );
+
+//         for _ in 0..180 {
+//             let topo = provider.get_new_topology().await;
+//             assert!(topo.is_some());
+//             tokio::time::sleep(Duration::from_secs(30)).await;
+//         }
+//     }
+// }
@@ -58,8 +58,8 @@ impl<T> TransmissionBuffer<T> {
    }

    #[cfg(not(target_arch = "wasm32"))]
-    pub(crate) fn num_lanes(&self) -> usize {
-        self.buffer.keys().count()
+    pub(crate) fn lanes(&self) -> Vec<TransmissionLane> {
+        self.buffer.keys().cloned().collect()
    }

    pub(crate) fn lane_length(&self, lane: &TransmissionLane) -> Option<usize> {
@@ -83,6 +83,7 @@ impl<T> TransmissionBuffer<T> {
    }

    #[cfg(not(target_arch = "wasm32"))]
+    #[allow(unused)]
    pub(crate) fn total_size_in_bytes(&self) -> usize
    where
        T: SizedData,
@@ -14,7 +14,8 @@ pub mod error;
 pub mod init;

 pub use nym_topology::{
-    HardcodedTopologyProvider, NymRouteProvider, NymTopology, NymTopologyError, TopologyProvider,
+    providers::HardcodedTopologyProvider, NymRouteProvider, NymTopology, NymTopologyError,
+    TopologyProvider,
 };

 #[cfg(target_arch = "wasm32")]
@@ -10,7 +10,7 @@ use crate::{
    CombinedReplyStorage, ReceivedReplySurbsMap, ReplyStorageBackend, SentReplyKeys, UsedSenderTags,
 };
 use async_trait::async_trait;
-use log::{error, info, warn};
+use log::{debug, error, info, warn};
 use nym_sphinx::anonymous_replies::requests::AnonymousSenderTag;
 use std::fs;
 use std::path::{Path, PathBuf};
@@ -52,7 +52,10 @@ impl Backend {
        Ok(backend)
    }

-    pub async fn try_load<P: AsRef<Path>>(database_path: P) -> Result<Self, StorageError> {
+    pub async fn try_load<P: AsRef<Path>>(
+        database_path: P,
+        fresh_sender_tags: bool,
+    ) -> Result<Self, StorageError> {
        let owned_path: PathBuf = database_path.as_ref().into();
        if owned_path.file_name().is_none() {
            return Err(StorageError::DatabasePathWithoutFilename {
@@ -118,6 +121,9 @@ impl Backend {
        if days > 2 {
            info!("it's been over {days} days and {hours} hours since we last used our data store. our used sender tags are already outdated - we're going to purge them now.");
            manager.delete_all_tags().await?;
+        } else if fresh_sender_tags {
+            debug!("starting with fresh sender tags");
+            manager.delete_all_tags().await?;
        }

        Ok(Backend {
@@ -20,8 +20,8 @@ use nym_credentials_interface::TicketType;
 use nym_crypto::asymmetric::identity;
 use nym_gateway_requests::registration::handshake::client_handshake;
 use nym_gateway_requests::{
-    BinaryRequest, ClientControlRequest, ClientRequest, SensitiveServerResponse, ServerResponse,
-    SharedGatewayKey, SharedSymmetricKey, AES_GCM_SIV_PROTOCOL_VERSION,
+    BinaryRequest, ClientControlRequest, ClientRequest, GatewayProtocolVersionExt,
+    SensitiveServerResponse, ServerResponse, SharedGatewayKey, SharedSymmetricKey,
    CREDENTIAL_UPDATE_V2_PROTOCOL_VERSION, CURRENT_PROTOCOL_VERSION,
 };
 use nym_sphinx::forwarding::packet::MixPacket;
@@ -204,15 +204,15 @@ impl<C, St> GatewayClient<C, St> {
            "Attemting to establish connection to gateway at: {}",
            self.gateway_address
        );
-        let (ws_stream, _) = connect_async(&self.gateway_address).await?;
+        let (ws_stream, _) = connect_async(
+            &self.gateway_address,
+            #[cfg(unix)]
+            self.connection_fd_callback.clone(),
+        )
+        .await?;

        self.connection = SocketState::Available(Box::new(ws_stream));

-        #[cfg(unix)]
-        if let (Some(callback), Some(fd)) = (self.connection_fd_callback.as_ref(), self.ws_fd()) {
-            callback.as_ref()(fd);
-        }
-
        Ok(())
    }

@@ -563,28 +563,10 @@ impl<C, St> GatewayClient<C, St> {
        Ok(zeroizing_updated_key)
    }

-    async fn authenticate(&mut self) -> Result<(), GatewayClientError> {
-        let Some(shared_key) = self.shared_key.as_ref() else {
-            return Err(GatewayClientError::NoSharedKeyAvailable);
-        };
-
-        if !self.connection.is_established() {
-            return Err(GatewayClientError::ConnectionNotEstablished);
-        }
-        debug!("authenticating with gateway");
-
-        let self_address = self
-            .local_identity
-            .as_ref()
-            .public_key()
-            .derive_destination_address();
-
-        let msg = ClientControlRequest::new_authenticate(
-            self_address,
-            shared_key,
-            self.cfg.bandwidth.require_tickets,
-        )?;
-
+    async fn send_authenticate_request_and_handle_response(
+        &mut self,
+        msg: ClientControlRequest,
+    ) -> Result<(), GatewayClientError> {
        match self.send_websocket_message(msg).await? {
            ServerResponse::Authenticate {
                protocol_version,
@@ -608,6 +590,51 @@ impl<C, St> GatewayClient<C, St> {
        }
    }

+    async fn authenticate_v1(&mut self) -> Result<(), GatewayClientError> {
+        debug!("using v1 authentication");
+
+        let Some(shared_key) = self.shared_key.as_ref() else {
+            return Err(GatewayClientError::NoSharedKeyAvailable);
+        };
+
+        let self_address = self
+            .local_identity
+            .public_key()
+            .derive_destination_address();
+
+        let msg = ClientControlRequest::new_authenticate(
+            self_address,
+            shared_key,
+            self.cfg.bandwidth.require_tickets,
+        )?;
+        self.send_authenticate_request_and_handle_response(msg)
+            .await
+    }
+
+    async fn authenticate_v2(&mut self) -> Result<(), GatewayClientError> {
+        debug!("using v2 authentication");
+        let Some(shared_key) = self.shared_key.as_ref() else {
+            return Err(GatewayClientError::NoSharedKeyAvailable);
+        };
+
+        let msg = ClientControlRequest::new_authenticate_v2(shared_key, &self.local_identity)?;
+        self.send_authenticate_request_and_handle_response(msg)
+            .await
+    }
+
+    async fn authenticate(&mut self, use_v2: bool) -> Result<(), GatewayClientError> {
+        if !self.connection.is_established() {
+            return Err(GatewayClientError::ConnectionNotEstablished);
+        }
+        debug!("authenticating with gateway");
+
+        if use_v2 {
+            self.authenticate_v2().await
+        } else {
+            self.authenticate_v1().await
+        }
+    }
+
    /// Helper method to either call register or authenticate based on self.shared_key value
    #[instrument(skip_all,
        fields(
@@ -623,19 +650,25 @@ impl<C, St> GatewayClient<C, St> {
        }

        // 1. check gateway's protocol version
-        let supports_aes_gcm_siv = match self.get_gateway_protocol().await {
-            Ok(protocol) => protocol >= AES_GCM_SIV_PROTOCOL_VERSION,
+        let gw_protocol = match self.get_gateway_protocol().await {
+            Ok(protocol) => Some(protocol),
            Err(_) => {
                // if we failed to send the request, it means the gateway is running the old binary,
                // so it has reset our connection - we have to reconnect
                self.establish_connection().await?;
-                false
+                None
            }
        };

+        let supports_aes_gcm_siv = gw_protocol.supports_aes256_gcm_siv();
+        let supports_auth_v2 = gw_protocol.supports_authenticate_v2();
+
        if !supports_aes_gcm_siv {
            warn!("this gateway is on an old version that doesn't support AES256-GCM-SIV");
        }
+        if !supports_auth_v2 {
+            warn!("this gateway is on an old version that doesn't support authentication v2")
+        }

        if self.authenticated {
            debug!("Already authenticated");
@@ -650,7 +683,7 @@ impl<C, St> GatewayClient<C, St> {
        }

        if self.shared_key.is_some() {
-            self.authenticate().await?;
+            self.authenticate(supports_auth_v2).await?;

            if self.authenticated {
                // if we are authenticated it means we MUST have an associated shared_key
@@ -983,7 +1016,8 @@ impl<C, St> GatewayClient<C, St> {
        }

        // if we're reconnecting, because we lost connection, we need to re-authenticate the connection
-        self.authenticate().await?;
+        self.authenticate(self.negotiated_protocol.supports_authenticate_v2())
+            .await?;

        // this call is NON-blocking
        self.start_listening_for_mixnet_messages()?;
@@ -1,6 +1,11 @@
 use crate::error::GatewayClientError;

 use nym_http_api_client::HickoryDnsResolver;
+#[cfg(unix)]
+use std::{
+    os::fd::{AsRawFd, RawFd},
+    sync::Arc,
+};
 use tokio::net::TcpStream;
 use tokio_tungstenite::{MaybeTlsStream, WebSocketStream};
 use tungstenite::handshake::client::Response;
@@ -11,7 +16,10 @@ use std::net::SocketAddr;
 #[cfg(not(target_arch = "wasm32"))]
 pub(crate) async fn connect_async(
    endpoint: &str,
+    #[cfg(unix)] connection_fd_callback: Option<Arc<dyn Fn(RawFd) + Send + Sync>>,
 ) -> Result<(WebSocketStream<MaybeTlsStream<TcpStream>>, Response), GatewayClientError> {
+    use tokio::net::TcpSocket;
+
    let resolver = HickoryDnsResolver::default();
    let uri =
        Url::parse(endpoint).map_err(|_| GatewayClientError::InvalidUrl(endpoint.to_owned()))?;
@@ -37,14 +45,41 @@ pub(crate) async fn connect_async(
        }
    };

-    let stream = TcpStream::connect(&sock_addrs[..]).await.map_err(|error| {
-        GatewayClientError::NetworkConnectionFailed {
-            address: endpoint.to_owned(),
-            source: error.into(),
+    let mut stream = Err(GatewayClientError::NoEndpointForConnection {
+        address: endpoint.to_owned(),
+    });
+    for sock_addr in sock_addrs {
+        let socket = if sock_addr.is_ipv4() {
+            TcpSocket::new_v4()
+        } else {
+            TcpSocket::new_v6()
        }
-    })?;
+        .map_err(|err| GatewayClientError::NetworkConnectionFailed {
+            address: endpoint.to_owned(),
+            source: err.into(),
+        })?;

-    tokio_tungstenite::client_async_tls(endpoint, stream)
+        #[cfg(unix)]
+        if let Some(callback) = connection_fd_callback.as_ref() {
+            callback.as_ref()(socket.as_raw_fd());
+        }
+
+        match socket.connect(sock_addr).await {
+            Ok(s) => {
+                stream = Ok(s);
+                break;
+            }
+            Err(err) => {
+                stream = Err(GatewayClientError::NetworkConnectionFailed {
+                    address: endpoint.to_owned(),
+                    source: err.into(),
+                });
+                continue;
+            }
+        }
+    }
+
+    tokio_tungstenite::client_async_tls(endpoint, stream?)
        .await
        .map_err(|error| GatewayClientError::NetworkConnectionFailed {
            address: endpoint.to_owned(),
@@ -43,6 +43,9 @@ pub enum GatewayClientError {
    #[error("connection failed: {address}: {source}")]
    NetworkConnectionFailed { address: String, source: WsError },

+    #[error("no socket address for endpoint: {address}")]
+    NoEndpointForConnection { address: String },
+
    #[error("Invalid URL: {0}")]
    InvalidUrl(String),

@@ -23,11 +23,12 @@ use nym_api_requests::models::{
    NymNodeDescription, RewardEstimationResponse, StakeSaturationResponse,
 };
 use nym_api_requests::models::{LegacyDescribedGateway, MixNodeBondAnnotated};
-use nym_api_requests::nym_nodes::SkimmedNode;
+use nym_api_requests::nym_nodes::{NodesByAddressesResponse, SkimmedNode};
 use nym_coconut_dkg_common::types::EpochId;
 use nym_ecash_contract_common::deposit::DepositId;
 use nym_http_api_client::UserAgent;
 use nym_network_defaults::NymNetworkDetails;
+use std::net::IpAddr;
 use time::Date;
 use url::Url;

@@ -497,6 +498,21 @@ impl NymApiClient {
        Ok(nodes)
    }

+    /// Batch request for node descriptors in the current topology.
+    ///
+    /// Given the set of node IDs included in the request body, provide the descriptor for each
+    /// associated node in if it is available in the current topology.
+    pub async fn retrieve_basic_nodes_batch(
+        &self,
+        node_ids: &[u32],
+    ) -> Result<Vec<SkimmedNode>, ValidatorClientError> {
+        Ok(self
+            .nym_api
+            .retrieve_basic_nodes_batch(node_ids)
+            .await?
+            .nodes)
+    }
+
    pub async fn health(&self) -> Result<ApiHealthResponse, ValidatorClientError> {
        Ok(self.nym_api.health().await?)
    }
@@ -710,4 +726,11 @@ impl NymApiClient {
            .issued_ticketbooks_challenge(expiration_date, deposits)
            .await?)
    }
+
+    pub async fn nodes_by_addresses(
+        &self,
+        addresses: Vec<IpAddr>,
+    ) -> Result<NodesByAddressesResponse, ValidatorClientError> {
+        Ok(self.nym_api.nodes_by_addresses(addresses).await?)
+    }
 }
@@ -83,6 +83,12 @@ impl TryFrom<ContractVKShare> for EcashApiClient {

        let url_address = Url::parse(&share.announce_address)?;

+        // The NymApiClient constructed here uses the default (hickory DoT/DoH) resolver because
+        // this EcashApiClient is used by both client and non-client applications.
+        //
+        // In non-client applications this resolver can cause warning logs about H2 connection
+        // failure. This indicates that the long lived https connection was closed by the remote
+        // peer and the resolver will have to reconnect. It should not impact actual functionality
        Ok(EcashApiClient {
            api_client: NymApiClient::new(url_address),
            verification_key: VerificationKeyAuth::try_from_bs58(&share.share)?,
@@ -12,10 +12,13 @@ use nym_api_requests::ecash::models::{
 };
 use nym_api_requests::ecash::VerificationKeyResponse;
 use nym_api_requests::models::{
-    AnnotationResponse, ApiHealthResponse, LegacyDescribedMixNode, NodePerformanceResponse,
-    NodeRefreshBody, NymNodeDescription, PerformanceHistoryResponse, RewardedSetResponse,
+    AnnotationResponse, ApiHealthResponse, BinaryBuildInformationOwned, ChainStatusResponse,
+    LegacyDescribedMixNode, NodePerformanceResponse, NodeRefreshBody, NymNodeDescription,
+    PerformanceHistoryResponse, RewardedSetResponse,
+};
+use nym_api_requests::nym_nodes::{
+    NodesByAddressesRequestBody, NodesByAddressesResponse, PaginatedCachedNodesResponse,
 };
-use nym_api_requests::nym_nodes::PaginatedCachedNodesResponse;
 use nym_api_requests::pagination::PaginatedResponse;
 pub use nym_api_requests::{
    ecash::{
@@ -40,6 +43,7 @@ pub use nym_http_api_client::Client;
 use nym_http_api_client::{ApiClient, NO_PARAMS};
 use nym_mixnet_contract_common::mixnode::MixNodeDetails;
 use nym_mixnet_contract_common::{GatewayBond, IdentityKeyRef, NodeId, NymNodeDetails};
+use std::net::IpAddr;
 use time::format_description::BorrowedFormatItem;
 use time::Date;
 use tracing::instrument;
@@ -66,6 +70,19 @@ pub trait NymApiClientExt: ApiClient {
        .await
    }

+    #[instrument(level = "debug", skip(self))]
+    async fn build_information(&self) -> Result<BinaryBuildInformationOwned, NymAPIError> {
+        self.get_json(
+            &[
+                routes::API_VERSION,
+                routes::API_STATUS_ROUTES,
+                routes::BUILD_INFORMATION,
+            ],
+            NO_PARAMS,
+        )
+        .await
+    }
+
    #[deprecated]
    #[instrument(level = "debug", skip(self))]
    async fn get_mixnodes(&self) -> Result<Vec<MixNodeDetails>, NymAPIError> {
@@ -253,10 +270,10 @@ pub trait NymApiClientExt: ApiClient {
        self.get_json(
            &[
                routes::API_VERSION,
-                "unstable",
+                routes::UNSTABLE,
                routes::NYM_NODES_ROUTES,
                "mixnodes",
-                "skimmed",
+                routes::SKIMMED,
            ],
            NO_PARAMS,
        )
@@ -269,10 +286,10 @@ pub trait NymApiClientExt: ApiClient {
        self.get_json(
            &[
                routes::API_VERSION,
-                "unstable",
+                routes::UNSTABLE,
                routes::NYM_NODES_ROUTES,
                "gateways",
-                "skimmed",
+                routes::SKIMMED,
            ],
            NO_PARAMS,
        )
@@ -318,9 +335,9 @@ pub trait NymApiClientExt: ApiClient {
        self.get_json(
            &[
                routes::API_VERSION,
-                "unstable",
+                routes::UNSTABLE,
                routes::NYM_NODES_ROUTES,
-                "skimmed",
+                routes::SKIMMED,
                "entry-gateways",
                "all",
            ],
@@ -355,9 +372,9 @@ pub trait NymApiClientExt: ApiClient {
        self.get_json(
            &[
                routes::API_VERSION,
-                "unstable",
+                routes::UNSTABLE,
                routes::NYM_NODES_ROUTES,
-                "skimmed",
+                routes::SKIMMED,
                "mixnodes",
                "active",
            ],
@@ -392,9 +409,9 @@ pub trait NymApiClientExt: ApiClient {
        self.get_json(
            &[
                routes::API_VERSION,
-                "unstable",
+                routes::UNSTABLE,
                routes::NYM_NODES_ROUTES,
-                "skimmed",
+                routes::SKIMMED,
                "mixnodes",
                "all",
            ],
@@ -403,6 +420,31 @@ pub trait NymApiClientExt: ApiClient {
        .await
    }

+    /// Send a Post request with a set of node ids. A successful response will contain descriptors
+    /// for all nodes associated with those node IDs available in the current full topology.
+    ///
+    /// If a provided node ID is not present there will be no descriptor for that node in the response.
+    ///
+    /// If no node IDs are provided the response will contain no descriptors.
+    #[instrument(level = "debug", skip(self))]
+    async fn retrieve_basic_nodes_batch(
+        &self,
+        node_ids: &[NodeId],
+    ) -> Result<CachedNodesResponse<SkimmedNode>, NymAPIError> {
+        self.post_json(
+            &[
+                routes::API_VERSION,
+                routes::UNSTABLE,
+                routes::NYM_NODES_ROUTES,
+                routes::SKIMMED,
+                routes::BATCH,
+            ],
+            NO_PARAMS,
+            node_ids,
+        )
+        .await
+    }
+
    #[instrument(level = "debug", skip(self))]
    async fn get_basic_nodes(
        &self,
@@ -427,9 +469,9 @@ pub trait NymApiClientExt: ApiClient {
        self.get_json(
            &[
                routes::API_VERSION,
-                "unstable",
+                routes::UNSTABLE,
                routes::NYM_NODES_ROUTES,
-                "skimmed",
+                routes::SKIMMED,
            ],
            &params,
        )
@@ -1015,6 +1057,23 @@ pub trait NymApiClientExt: ApiClient {
        .await
    }

+    async fn nodes_by_addresses(
+        &self,
+        addresses: Vec<IpAddr>,
+    ) -> Result<NodesByAddressesResponse, NymAPIError> {
+        self.post_json(
+            &[
+                routes::API_VERSION,
+                "unstable",
+                routes::NYM_NODES_ROUTES,
+                routes::nym_nodes::BY_ADDRESSES,
+            ],
+            NO_PARAMS,
+            &NodesByAddressesRequestBody { addresses },
+        )
+        .await
+    }
+
    #[instrument(level = "debug", skip(self))]
    async fn get_network_details(&self) -> Result<NymNetworkDetailsResponse, NymAPIError> {
        self.get_json(
@@ -1023,6 +1082,15 @@ pub trait NymApiClientExt: ApiClient {
        )
        .await
    }
+
+    #[instrument(level = "debug", skip(self))]
+    async fn get_chain_status(&self) -> Result<ChainStatusResponse, NymAPIError> {
+        self.get_json(
+            &[routes::API_VERSION, routes::NETWORK, routes::CHAIN_STATUS],
+            NO_PARAMS,
+        )
+        .await
+    }
 }

 #[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
@@ -43,11 +43,14 @@ pub mod nym_nodes {
    pub const NYM_NODES_BONDED: &str = "bonded";
    pub const NYM_NODES_REWARDED_SET: &str = "rewarded-set";
    pub const NYM_NODES_REFRESH_DESCRIBED: &str = "refresh-described";
+    pub const BY_ADDRESSES: &str = "by-addresses";
 }

 pub const STATUS_ROUTES: &str = "status";
 pub const API_STATUS_ROUTES: &str = "api-status";
 pub const HEALTH: &str = "health";
+pub const BUILD_INFORMATION: &str = "build-information";
+
 pub const MIXNODE: &str = "mixnode";
 pub const GATEWAY: &str = "gateway";
 pub const NYM_NODES: &str = "nym-nodes";
@@ -69,4 +72,9 @@ pub const SUBMIT_NODE: &str = "submit-node-monitoring-results";
 pub const SERVICE_PROVIDERS: &str = "services";

 pub const DETAILS: &str = "details";
+pub const CHAIN_STATUS: &str = "chain-status";
 pub const NETWORK: &str = "network";
+
+pub const UNSTABLE: &str = "unstable";
+pub const SKIMMED: &str = "skimmed";
+pub const BATCH: &str = "batch";
@@ -28,7 +28,6 @@ use nym_network_defaults::{ChainDetails, NymNetworkDetails};
 use serde::{de::DeserializeOwned, Serialize};
 use std::fmt::Debug;
 use std::time::SystemTime;
-use tendermint_rpc::endpoint::block::Response as BlockResponse;
 use tendermint_rpc::endpoint::*;
 use tendermint_rpc::{Error as TendermintRpcError, Order};
 use url::Url;
@@ -63,6 +62,8 @@ pub use cw3;
 pub use cw4;
 pub use cw_controllers;
 pub use fee::{gas_price::GasPrice, GasAdjustable, GasAdjustment};
+pub use prost::Name;
+pub use tendermint_rpc::endpoint::block::Response as BlockResponse;
 pub use tendermint_rpc::{
    endpoint::{tx::Response as TxResponse, validators::Response as ValidatorResponse},
    query::Query,
@@ -25,15 +25,6 @@ pub fn in6addr_any_init() -> IpAddr {
    IpAddr::V6(Ipv6Addr::UNSPECIFIED)
 }

-/// Helper for providing binding warnings if node tries to bind to any of those
-pub const SPECIAL_ADDRESSES: &[IpAddr] = &[
-    IpAddr::V4(Ipv4Addr::LOCALHOST),
-    IpAddr::V4(Ipv4Addr::UNSPECIFIED),
-    IpAddr::V4(Ipv4Addr::BROADCAST),
-    IpAddr::V6(Ipv6Addr::LOCALHOST),
-    IpAddr::V6(Ipv6Addr::UNSPECIFIED),
-];
-
 // TODO: is it really part of 'Config'?
 pub trait OptionalSet {
    /// If the value is available (i.e. `Some`), the provided closure is applied.
@@ -43,4 +43,7 @@ serde = ["dep:serde", "serde_bytes", "ed25519-dalek/serde", "x25519-dalek/serde"
 asymmetric = ["x25519-dalek", "ed25519-dalek", "zeroize"]
 hashing = ["blake3", "digest", "hkdf", "hmac", "generic-array", "sha2"]
 stream_cipher = ["aes", "ctr", "cipher", "generic-array"]
-sphinx = ["nym-sphinx-types/sphinx"]
+sphinx = ["nym-sphinx-types/sphinx"]
+
+[lints]
+workspace = true
@@ -16,8 +16,11 @@ pub fn compute_keyed_hmac<D>(key: &[u8], data: &[u8]) -> HmacOutput<D>
 where
    D: Digest + BlockSizeUser,
 {
-    let mut hmac = SimpleHmac::<D>::new_from_slice(key)
-        .expect("HMAC was instantiated with a key of an invalid size!");
+    // SAFETY: hmac is fine with keys of any size; if they're smaller than the block size of the underlying
+    // digest, they're padded with 0. if they're larger they're hashed and padded
+    // the reason for `Result` return type is due to the trait definition
+    #[allow(clippy::unwrap_used)]
+    let mut hmac = SimpleHmac::<D>::new_from_slice(key).unwrap();
    hmac.update(data);
    hmac.finalize()
 }
@@ -27,8 +30,11 @@ pub fn recompute_keyed_hmac_and_verify_tag<D>(key: &[u8], data: &[u8], tag: &[u8
 where
    D: Digest + BlockSizeUser,
 {
-    let mut hmac = SimpleHmac::<D>::new_from_slice(key)
-        .expect("HMAC was instantiated with a key of an invalid size!");
+    // SAFETY: hmac is fine with keys of any size; if they're smaller than the block size of the underlying
+    // digest, they're padded with 0. if they're larger they're hashed and padded
+    // the reason for `Result` return type is due to the trait definition
+    #[allow(clippy::unwrap_used)]
+    let mut hmac = SimpleHmac::<D>::new_from_slice(key).unwrap();
    hmac.update(data);

    let tag_arr = Output::<D>::from_slice(tag);
@@ -27,12 +27,16 @@ where
    // after performing diffie-hellman we don't care about the private component anymore
    let dh_result = ephemeral_keypair.private_key().diffie_hellman(remote_key);

-    // there is no reason for this to fail as our okm is expected to be only C::KeySize bytes
+    // SAFETY: while this is a relatively weak assumption, it's unlikely that any stream cipher has `C::key_size()`
+    // larger than 255 * chunk_size of the digest (so for example keys larger than 8160 bytes if sh256 is used)
+    #[allow(clippy::expect_used)]
    let okm = hkdf::extract_then_expand::<D>(None, &dh_result, None, C::key_size())
        .expect("somehow too long okm was provided");

-    let derived_shared_key =
-        Key::<C>::from_exact_iter(okm).expect("okm was expanded to incorrect length!");
+    // SAFETY: the generated okm has exactly `C::key_size()` elements,
+    // so this call is safe
+    #[allow(clippy::unwrap_used)]
+    let derived_shared_key = Key::<C>::from_exact_iter(okm).unwrap();

    (ephemeral_keypair, derived_shared_key)
 }
@@ -48,9 +52,14 @@ where
 {
    let dh_result = local_key.diffie_hellman(remote_key);

-    // there is no reason for this to fail as our okm is expected to be only C::KeySize bytes
+    // SAFETY: while this is a relatively weak assumption, it's unlikely that any stream cipher has `C::key_size()`
+    // larger than 255 * chunk_size of the digest (so for example keys larger than 8160 bytes if sh256 is used)
+    #[allow(clippy::expect_used)]
    let okm = hkdf::extract_then_expand::<D>(None, &dh_result, None, C::key_size())
        .expect("somehow too long okm was provided");

-    Key::<C>::from_exact_iter(okm).expect("okm was expanded to incorrect length!")
+    // SAFETY: the generated okm has exactly `C::key_size()` elements,
+    // so this call is safe
+    #[allow(clippy::unwrap_used)]
+    Key::<C>::from_exact_iter(okm).unwrap()
 }
@@ -60,20 +60,15 @@ where
    Iv::<C>::default()
 }

-pub fn iv_from_slice<C>(b: &[u8]) -> &IV<C>
+pub fn try_iv_from_slice<C>(b: &[u8]) -> Option<&IV<C>>
 where
    C: IvSizeUser,
 {
    if b.len() != C::iv_size() {
-        // `from_slice` would have caused a panic about this issue anyway.
-        // Now we at least have slightly more information
-        panic!(
-            "Tried to convert {} bytes to IV. Expected {}",
-            b.len(),
-            C::iv_size()
-        )
+        None
+    } else {
+        Some(IV::<C>::from_slice(b))
    }
-    IV::<C>::from_slice(b)
 }

 // TODO: there's really no way to use more parts of the keystream if it was required at some point.
@@ -21,7 +21,7 @@ lazy_static = { workspace = true }
 rand = { workspace = true }
 rand_chacha = { workspace = true }
 rand_core = { workspace = true }
-sha2 = "0.9"
+sha2 = { workspace = true }
 serde = { workspace = true }
 serde_derive = { workspace = true }
 thiserror = { workspace = true }
@@ -54,12 +54,12 @@ pub(crate) fn hash_to_scalar<M: AsRef<[u8]>>(msg: M, domain: &[u8]) -> Scalar {
 pub(crate) fn hash_to_scalars<M: AsRef<[u8]>>(msg: M, domain: &[u8], n: usize) -> Vec<Scalar> {
    let mut output = vec![Scalar::zero(); n];

-    Scalar::hash_to_field::<ExpandMsgXmd<Sha256>>(msg.as_ref(), domain, &mut output);
+    Scalar::hash_to_field::<ExpandMsgXmd<Sha256>, _>([msg], domain, &mut output);
    output
 }

 pub(crate) fn hash_g2<M: AsRef<[u8]>>(msg: M, domain: &[u8]) -> G2Projective {
-    <G2Projective as HashToCurve<ExpandMsgXmd<Sha256>>>::hash_to_curve(msg, domain)
+    <G2Projective as HashToCurve<ExpandMsgXmd<Sha256>>>::hash_to_curve([msg], domain)
 }

 pub(crate) fn combine_scalar_chunks(chunks: &[Scalar]) -> Scalar {
@@ -112,3 +112,97 @@ pub(crate) fn deserialize_g2(b: &[u8]) -> Option<G2Projective> {
        G2Projective::from_bytes(&encoding).into()
    }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use bls12_381::G2Affine;
+
+    #[test]
+    fn test_hash_to_scalar() {
+        let msg1 = "foo";
+        let expected1 = Scalar::from_bytes(&[
+            253, 57, 224, 227, 175, 195, 226, 82, 46, 175, 33, 126, 171, 239, 255, 92, 108, 168, 6,
+            79, 90, 11, 235, 236, 221, 10, 85, 133, 42, 81, 95, 30,
+        ])
+        .unwrap();
+
+        let msg2 = "bar";
+        let expected2 = Scalar::from_bytes(&[
+            48, 83, 69, 52, 42, 18, 135, 244, 211, 190, 160, 196, 118, 154, 24, 126, 0, 125, 72,
+            201, 170, 225, 123, 201, 52, 120, 171, 132, 235, 182, 20, 26,
+        ])
+        .unwrap();
+
+        let msg3 = [
+            33, 135, 76, 234, 71, 35, 247, 216, 39, 242, 42, 88, 152, 29, 74, 135, 9, 29, 216, 123,
+            250, 87, 108, 29, 245, 126, 109, 102, 84, 71, 158, 224, 145, 243, 49, 121, 244, 27,
+            115, 121, 25, 66, 216, 67, 97, 101, 140, 160, 77, 239, 114, 215, 152, 48, 15, 231, 101,
+            60, 42, 92, 128, 131, 161, 43,
+        ];
+        let expected3 = Scalar::from_bytes(&[
+            128, 189, 8, 43, 186, 55, 52, 61, 171, 196, 159, 177, 162, 100, 27, 143, 85, 83, 218,
+            171, 91, 220, 155, 25, 7, 38, 2, 36, 4, 93, 136, 4,
+        ])
+        .unwrap();
+
+        assert_eq!(
+            hash_to_scalar(msg1, b"NYMECASH-V01-CS02-with-expander-SHA256"),
+            expected1
+        );
+        assert_eq!(
+            hash_to_scalar(msg2, b"NYMECASH-V01-CS02-with-expander-SHA256"),
+            expected2
+        );
+        assert_eq!(
+            hash_to_scalar(msg3, b"NYMECASH-V01-CS02-with-expander-SHA256"),
+            expected3
+        );
+    }
+
+    #[test]
+    fn test_hash_g2() {
+        let msg1 = "foo";
+        let expected1 = G2Affine::from_compressed(&[
+            175, 187, 62, 7, 29, 17, 42, 93, 28, 93, 234, 253, 101, 166, 158, 187, 153, 82, 93, 18,
+            11, 233, 36, 107, 51, 117, 30, 127, 32, 254, 210, 77, 133, 12, 253, 255, 84, 128, 36,
+            214, 234, 103, 50, 21, 26, 78, 112, 49, 20, 69, 19, 109, 7, 78, 33, 227, 196, 180, 168,
+            219, 73, 251, 192, 221, 41, 138, 160, 131, 191, 186, 156, 117, 179, 179, 191, 235, 171,
+            26, 219, 148, 170, 179, 11, 38, 137, 14, 95, 115, 171, 186, 163, 82, 158, 6, 239, 88,
+        ])
+        .unwrap()
+        .into();
+
+        let msg2 = "bar";
+        let expected2 = G2Affine::from_compressed(&[
+            183, 25, 90, 187, 34, 184, 30, 182, 215, 242, 158, 83, 116, 34, 210, 96, 188, 79, 83,
+            255, 100, 122, 90, 188, 196, 93, 164, 253, 20, 106, 205, 33, 48, 140, 60, 149, 66, 246,
+            121, 244, 146, 66, 170, 60, 113, 95, 102, 237, 25, 231, 8, 42, 121, 124, 180, 140, 34,
+            104, 173, 251, 89, 189, 28, 196, 49, 66, 101, 38, 68, 44, 40, 235, 21, 35, 204, 123,
+            218, 238, 216, 92, 134, 217, 212, 246, 176, 77, 187, 0, 245, 134, 132, 73, 31, 44, 137,
+            197,
+        ])
+        .unwrap()
+        .into();
+        let msg3 = [
+            33, 135, 76, 234, 71, 35, 247, 216, 39, 242, 42, 88, 152, 29, 74, 135, 9, 29, 216, 123,
+            250, 87, 108, 29, 245, 126, 109, 102, 84, 71, 158, 224, 145, 243, 49, 121, 244, 27,
+            115, 121, 25, 66, 216, 67, 97, 101, 140, 160, 77, 239, 114, 215, 152, 48, 15, 231, 101,
+            60, 42, 92, 128, 131, 161, 43,
+        ];
+        let expected3 = G2Affine::from_compressed(&[
+            151, 185, 8, 123, 223, 150, 192, 192, 115, 10, 3, 129, 49, 179, 31, 108, 0, 17, 46,
+            231, 184, 164, 247, 228, 22, 142, 87, 70, 120, 111, 154, 15, 245, 110, 32, 84, 53, 117,
+            239, 93, 89, 119, 32, 17, 39, 250, 198, 137, 6, 95, 137, 202, 54, 244, 238, 190, 11,
+            217, 237, 95, 72, 59, 140, 56, 3, 42, 61, 195, 192, 101, 46, 204, 207, 75, 70, 176,
+            207, 48, 24, 195, 248, 234, 178, 168, 54, 109, 19, 189, 51, 52, 120, 69, 248, 226, 102,
+            91,
+        ])
+        .unwrap()
+        .into();
+
+        assert_eq!(hash_g2(msg1, b"DUMMY_TEST_DOMAIN"), expected1);
+        assert_eq!(hash_g2(msg2, b"DUMMY_TEST_DOMAIN"), expected2);
+        assert_eq!(hash_g2(msg3, b"DUMMY_TEST_DOMAIN"), expected3);
+    }
+}
@@ -20,11 +20,14 @@ 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-crypto = { path = "../crypto", features = ["aead", "hashing"] }
 nym-pemstore = { path = "../pemstore" }
 nym-sphinx = { path = "../nymsphinx" }
+nym-serde-helpers = { path = "../serde-helpers", features = ["base64"] }
 nym-task = { path = "../task" }

 nym-credentials = { path = "../credentials" }
@@ -15,6 +15,12 @@ use thiserror::Error;
 // this is no longer constant size due to the differences in ciphertext between aes128ctr and aes256gcm-siv (inclusion of tag)
 pub struct EncryptedAddressBytes(Vec<u8>);

+impl From<Vec<u8>> for EncryptedAddressBytes {
+    fn from(encrypted_address: Vec<u8>) -> Self {
+        EncryptedAddressBytes(encrypted_address)
+    }
+}
+
 #[derive(Debug, Error)]
 pub enum EncryptedAddressConversionError {
    #[error("Failed to decode the encrypted address - {0}")]
@@ -19,7 +19,7 @@ pub use shared_key::{
    SharedGatewayKey, SharedKeyConversionError, SharedKeyUsageError, SharedSymmetricKey,
 };

-pub const CURRENT_PROTOCOL_VERSION: u8 = AES_GCM_SIV_PROTOCOL_VERSION;
+pub const CURRENT_PROTOCOL_VERSION: u8 = AUTHENTICATE_V2_PROTOCOL_VERSION;

 /// Defines the current version of the communication protocol between gateway and clients.
 /// It has to be incremented for any breaking change.
@@ -27,10 +27,29 @@ pub const CURRENT_PROTOCOL_VERSION: u8 = AES_GCM_SIV_PROTOCOL_VERSION;
 // 1 - initial release
 // 2 - changes to client credentials structure
 // 3 - change to AES-GCM-SIV and non-zero IVs
+// 4 - introduction of v2 authentication protocol to prevent reply attacks
 pub const INITIAL_PROTOCOL_VERSION: u8 = 1;
 pub const CREDENTIAL_UPDATE_V2_PROTOCOL_VERSION: u8 = 2;
 pub const AES_GCM_SIV_PROTOCOL_VERSION: u8 = 3;
+pub const AUTHENTICATE_V2_PROTOCOL_VERSION: u8 = 4;

 // TODO: could using `Mac` trait here for OutputSize backfire?
 // Should hmac itself be exposed, imported and used instead?
 pub type LegacyGatewayMacSize = <GatewayIntegrityHmacAlgorithm as OutputSizeUser>::OutputSize;
+
+pub trait GatewayProtocolVersionExt {
+    fn supports_aes256_gcm_siv(&self) -> bool;
+    fn supports_authenticate_v2(&self) -> bool;
+}
+
+impl GatewayProtocolVersionExt for Option<u8> {
+    fn supports_aes256_gcm_siv(&self) -> bool {
+        let Some(protocol) = *self else { return false };
+        protocol >= AES_GCM_SIV_PROTOCOL_VERSION
+    }
+
+    fn supports_authenticate_v2(&self) -> bool {
+        let Some(protocol) = *self else { return false };
+        protocol >= AUTHENTICATE_V2_PROTOCOL_VERSION
+    }
+}
@@ -3,12 +3,14 @@

 use crate::SharedKeyUsageError;
 use nym_credentials_interface::CompactEcashError;
+use nym_crypto::asymmetric::ed25519::SignatureError;
 use nym_sphinx::addressing::nodes::NymNodeRoutingAddressError;
 use nym_sphinx::forwarding::packet::MixPacketFormattingError;
 use nym_sphinx::params::packet_sizes::PacketSize;
 use serde::{Deserialize, Serialize};
 use std::string::FromUtf8Error;
 use thiserror::Error;
+use time::OffsetDateTime;

 // specific errors (that should not be nested!!) for clients to match on
 #[derive(Debug, Copy, Clone, Error, Serialize, Deserialize)]
@@ -92,7 +94,34 @@ pub enum GatewayRequestsError {
    #[error("the provided [v1] credential has invalid number of parameters - {0}")]
    InvalidNumberOfEmbededParameters(u32),

+    #[error("failed to authenticate the client: {0}")]
+    Authentication(#[from] AuthenticationFailure),
+
    // variant to catch legacy errors
    #[error("{0}")]
    Other(String),
 }
+
+#[derive(Debug, Error)]
+pub enum AuthenticationFailure {
+    #[error(transparent)]
+    KeyUsageFailure(#[from] SharedKeyUsageError),
+
+    #[error("failed to verify provided address ciphertext")]
+    MalformedCiphertext,
+
+    #[error("failed to verify request signature")]
+    InvalidSignature(#[from] SignatureError),
+
+    #[error("the client is not registered")]
+    NotRegistered,
+
+    #[error("the provided request timestamp is excessively skewed. got {received} whilst the server time is {server}")]
+    ExcessiveTimestampSkew {
+        received: OffsetDateTime,
+        server: OffsetDateTime,
+    },
+
+    #[error("the provided request timestamp is smaller or equal to one previously used")]
+    RequestReuse,
+}
@@ -0,0 +1,151 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: GPL-3.0-only
+
+use crate::{AuthenticationFailure, GatewayRequestsError, SharedGatewayKey};
+use nym_crypto::asymmetric::ed25519;
+use serde::{Deserialize, Serialize};
+use std::iter;
+use std::time::Duration;
+use subtle::ConstantTimeEq;
+use time::OffsetDateTime;
+
+#[derive(Serialize, Deserialize, Debug)]
+#[serde(rename_all = "camelCase")]
+pub struct AuthenticateRequest {
+    #[serde(flatten)]
+    pub content: AuthenticateRequestContent,
+
+    pub request_signature: ed25519::Signature,
+}
+
+impl AuthenticateRequest {
+    pub fn new(
+        protocol_version: u8,
+        shared_key: &SharedGatewayKey,
+        identity_keys: &ed25519::KeyPair,
+    ) -> Result<AuthenticateRequest, GatewayRequestsError> {
+        let content = AuthenticateRequestContent::new(
+            protocol_version,
+            shared_key,
+            *identity_keys.public_key(),
+        )?;
+        let plaintext = content.plaintext();
+        let request_signature = identity_keys.private_key().sign(&plaintext);
+
+        Ok(AuthenticateRequest {
+            content,
+            request_signature,
+        })
+    }
+
+    pub fn verify_timestamp(
+        &self,
+        max_request_timestamp_skew: Duration,
+    ) -> Result<(), AuthenticationFailure> {
+        let now = OffsetDateTime::now_utc();
+        if self.content.request_timestamp() < now - max_request_timestamp_skew {
+            return Err(AuthenticationFailure::ExcessiveTimestampSkew {
+                received: self.content.request_timestamp(),
+                server: now,
+            });
+        }
+        if self.content.request_timestamp() - max_request_timestamp_skew > now {
+            return Err(AuthenticationFailure::ExcessiveTimestampSkew {
+                received: self.content.request_timestamp(),
+                server: now,
+            });
+        }
+        Ok(())
+    }
+
+    pub fn ensure_timestamp_not_reused(
+        &self,
+        previous: OffsetDateTime,
+    ) -> Result<(), AuthenticationFailure> {
+        if self.content.request_timestamp() <= previous {
+            return Err(AuthenticationFailure::RequestReuse);
+        }
+        Ok(())
+    }
+
+    pub fn verify_ciphertext(
+        &self,
+        shared_key: &SharedGatewayKey,
+    ) -> Result<(), AuthenticationFailure> {
+        let expected = shared_key.encrypt(
+            self.content
+                .client_identity
+                .derive_destination_address()
+                .as_bytes_ref(),
+            Some(&self.content.nonce),
+        )?;
+
+        if !bool::from(expected.ct_eq(&self.content.address_ciphertext)) {
+            return Err(AuthenticationFailure::MalformedCiphertext);
+        }
+        Ok(())
+    }
+
+    pub fn verify_signature(&self) -> Result<(), AuthenticationFailure> {
+        let plaintext = self.content.plaintext();
+        self.content
+            .client_identity
+            .verify(plaintext, &self.request_signature)
+            .map_err(Into::into)
+    }
+}
+
+#[derive(Serialize, Deserialize, Debug)]
+#[serde(rename_all = "camelCase")]
+pub struct AuthenticateRequestContent {
+    pub protocol_version: u8,
+
+    // this is identical to the client's address
+    pub client_identity: ed25519::PublicKey,
+
+    #[serde(with = "nym_serde_helpers::base64")]
+    pub address_ciphertext: Vec<u8>,
+
+    #[serde(with = "nym_serde_helpers::base64")]
+    pub nonce: Vec<u8>,
+
+    pub request_unix_timestamp: u64,
+}
+
+impl AuthenticateRequestContent {
+    fn new(
+        protocol_version: u8,
+        shared_key: &SharedGatewayKey,
+        client_identity: ed25519::PublicKey,
+    ) -> Result<AuthenticateRequestContent, GatewayRequestsError> {
+        let nonce = shared_key.random_nonce_or_iv();
+        let destination_address = client_identity.derive_destination_address();
+
+        let address_ciphertext =
+            shared_key.encrypt(destination_address.as_bytes_ref(), Some(&nonce))?;
+        let now = OffsetDateTime::now_utc();
+        Ok(AuthenticateRequestContent {
+            protocol_version,
+            client_identity,
+            address_ciphertext,
+            nonce,
+            request_unix_timestamp: now.unix_timestamp() as u64, // SAFETY: we're running this in post 1970...
+        })
+    }
+}
+
+impl AuthenticateRequestContent {
+    pub fn plaintext(&self) -> Vec<u8> {
+        iter::once(self.protocol_version)
+            .chain(self.client_identity.to_bytes())
+            .chain(self.address_ciphertext.iter().copied())
+            .chain(self.nonce.iter().copied())
+            .chain(self.request_unix_timestamp.to_be_bytes())
+            .collect()
+    }
+
+    pub fn request_timestamp(&self) -> OffsetDateTime {
+        OffsetDateTime::from_unix_timestamp(self.request_unix_timestamp as i64)
+            .unwrap_or(OffsetDateTime::UNIX_EPOCH)
+    }
+}
@@ -2,16 +2,21 @@
 // SPDX-License-Identifier: Apache-2.0

 use crate::models::CredentialSpendingRequest;
+use crate::text_request::authenticate::AuthenticateRequest;
 use crate::{
    GatewayRequestsError, SharedGatewayKey, SymmetricKey, AES_GCM_SIV_PROTOCOL_VERSION,
-    CREDENTIAL_UPDATE_V2_PROTOCOL_VERSION, INITIAL_PROTOCOL_VERSION,
+    AUTHENTICATE_V2_PROTOCOL_VERSION, CREDENTIAL_UPDATE_V2_PROTOCOL_VERSION,
+    INITIAL_PROTOCOL_VERSION,
 };
 use nym_credentials_interface::CredentialSpendingData;
+use nym_crypto::asymmetric::ed25519;
 use nym_sphinx::DestinationAddressBytes;
 use serde::{Deserialize, Serialize};
 use std::str::FromStr;
 use tungstenite::Message;

+pub mod authenticate;
+
 // wrapper for all encrypted requests for ease of use
 #[derive(Serialize, Deserialize, Debug, Clone)]
 #[non_exhaustive]
@@ -68,6 +73,9 @@ pub enum ClientControlRequest {
        enc_address: String,
        iv: String,
    },
+
+    AuthenticateV2(Box<AuthenticateRequest>),
+
    #[serde(alias = "handshakePayload")]
    RegisterHandshakeInitRequest {
        #[serde(default)]
@@ -123,9 +131,22 @@ impl ClientControlRequest {
        })
    }

+    pub fn new_authenticate_v2(
+        shared_key: &SharedGatewayKey,
+        identity_keys: &ed25519::KeyPair,
+    ) -> Result<Self, GatewayRequestsError> {
+        // if we're using v2 authentication, we must announce at least that protocol version
+        let protocol_version = AUTHENTICATE_V2_PROTOCOL_VERSION;
+
+        Ok(ClientControlRequest::AuthenticateV2(Box::new(
+            AuthenticateRequest::new(protocol_version, shared_key, identity_keys)?,
+        )))
+    }
+
    pub fn name(&self) -> String {
        match self {
            ClientControlRequest::Authenticate { .. } => "Authenticate".to_string(),
+            ClientControlRequest::AuthenticateV2(..) => "AuthenticateV2".to_string(),
            ClientControlRequest::RegisterHandshakeInitRequest { .. } => {
                "RegisterHandshakeInitRequest".to_string()
            }
@@ -0,0 +1,7 @@
+/*
+ * Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+ * SPDX-License-Identifier: GPL-3.0-only
+ */
+
+ALTER TABLE shared_keys
+    ADD COLUMN last_used_authentication TIMESTAMP WITHOUT TIME ZONE;
@@ -200,6 +200,20 @@ impl GatewayStorage {
        Ok(())
    }

+    pub async fn update_last_used_authentication_timestamp(
+        &self,
+        client_id: i64,
+        last_used_authentication_timestamp: OffsetDateTime,
+    ) -> Result<(), GatewayStorageError> {
+        self.shared_key_manager
+            .update_last_used_authentication_timestamp(
+                client_id,
+                last_used_authentication_timestamp,
+            )
+            .await?;
+        Ok(())
+    }
+
    pub async fn get_client(&self, client_id: i64) -> Result<Option<Client>, GatewayStorageError> {
        let client = self.client_manager.get_client(client_id).await?;
        Ok(client)
@@ -14,13 +14,13 @@ pub struct Client {

 #[derive(FromRow)]
 pub struct PersistedSharedKeys {
-    #[allow(dead_code)]
    pub client_id: i64,

    #[allow(dead_code)]
    pub client_address_bs58: String,
    pub derived_aes128_ctr_blake3_hmac_keys_bs58: Option<String>,
    pub derived_aes256_gcm_siv_key: Option<Vec<u8>>,
+    pub last_used_authentication: Option<OffsetDateTime>,
 }

 impl TryFrom<PersistedSharedKeys> for SharedGatewayKey {
@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: GPL-3.0-only

 use crate::models::PersistedSharedKeys;
+use time::OffsetDateTime;

 #[derive(Clone)]
 pub(crate) struct SharedKeysManager {
@@ -68,6 +69,22 @@ impl SharedKeysManager {
        Ok(())
    }

+    pub(crate) async fn update_last_used_authentication_timestamp(
+        &self,
+        client_id: i64,
+        last_used: OffsetDateTime,
+    ) -> Result<(), sqlx::Error> {
+        sqlx::query!(
+            "UPDATE shared_keys SET last_used_authentication = ? WHERE client_id = ?;",
+            last_used,
+            client_id
+        )
+        .execute(&self.connection_pool)
+        .await?;
+
+        Ok(())
+    }
+
    /// Tries to retrieve shared keys stored for the particular client.
    ///
    /// # Arguments
@@ -77,13 +94,10 @@ impl SharedKeysManager {
        &self,
        client_address_bs58: &str,
    ) -> Result<Option<PersistedSharedKeys>, sqlx::Error> {
-        sqlx::query_as!(
-            PersistedSharedKeys,
-            "SELECT * FROM shared_keys WHERE client_address_bs58 = ?",
-            client_address_bs58
-        )
-        .fetch_optional(&self.connection_pool)
-        .await
+        sqlx::query_as("SELECT * FROM shared_keys WHERE client_address_bs58 = ?")
+            .bind(client_address_bs58)
+            .fetch_optional(&self.connection_pool)
+            .await
    }

    /// Removes from the database shared keys derived with the particular client.
@@ -21,6 +21,12 @@ serde_json = { workspace = true }
 thiserror = { workspace = true }
 tracing = { workspace = true }

+# used for decoding text responses (they were already implicitly included)
+bytes = { workspace = true }
+encoding_rs = { workspace = true }
+mime = { workspace = true }
+
+
 nym-bin-common = { path = "../bin-common" }

 [target."cfg(not(target_arch = \"wasm32\"))".dependencies]
@@ -32,4 +38,4 @@ workspace = true
 features = ["tokio"]

 [dev-dependencies]
-tokio = { workspace = true, features=["rt", "macros"] }
+tokio = { workspace = true, features = ["rt", "macros"] }
@@ -1,3 +1,6 @@
+// Copyright 2023 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
 //! DNS resolver configuration for internal lookups.
 //!
 //! The resolver itself is the set combination of the google, cloudflare, and quad9 endpoints
@@ -9,19 +12,35 @@
 //!
 //! Requires the `dns-over-https-rustls`, `webpki-roots` feature for the
 //! `hickory-resolver` crate
+//!
+//!
+//! Note: The hickory DoH resolver can cause warning logs about H2 connection failure. This
+//! indicates that the long lived https connection was closed by the remote peer and the resolver
+//! will have to reconnect. It should not impact actual functionality.
+//!
+//! code ref: https://github.com/hickory-dns/hickory-dns/blob/06a8b1ce9bd9322d8e6accf857d30257e1274427/crates/proto/src/h2/h2_client_stream.rs#L534
+//!
+//! example log:
+//!
+//! ```txt
+//!   WARN /home/ubuntu/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/hickory-proto-0.24.3/src/h2/h2_client_stream.rs:493: h2 connection failed: unexpected end of file
+//! ```
 #![deny(missing_docs)]

 use crate::ClientBuilder;

-use std::{net::SocketAddr, sync::Arc};
+use std::{
+    net::SocketAddr,
+    sync::{Arc, LazyLock},
+};

-use hickory_resolver::lookup_ip::LookupIp;
 use hickory_resolver::{
    config::{LookupIpStrategy, NameServerConfigGroup, ResolverConfig, ResolverOpts},
    error::ResolveError,
    lookup_ip::LookupIpIntoIter,
    TokioAsyncResolver,
 };
+use hickory_resolver::{error::ResolveErrorKind, lookup_ip::LookupIp};
 use once_cell::sync::OnceCell;
 use reqwest::dns::{Addrs, Name, Resolve, Resolving};
 use tracing::warn;
@@ -30,6 +49,13 @@ impl ClientBuilder {
    /// Override the DNS resolver implementation used by the underlying http client.
    pub fn dns_resolver<R: Resolve + 'static>(mut self, resolver: Arc<R>) -> Self {
        self.reqwest_client_builder = self.reqwest_client_builder.dns_resolver(resolver);
+        self.use_secure_dns = false;
+        self
+    }
+
+    /// Override the DNS resolver implementation used by the underlying http client.
+    pub fn no_hickory_dns(mut self) -> Self {
+        self.use_secure_dns = false;
        self
    }
 }
@@ -38,6 +64,14 @@ struct SocketAddrs {
    iter: LookupIpIntoIter,
 }

+// n.b. static items do not call [`Drop`] on program termination, so this won't be deallocated.
+// this is fine, as the OS can deallocate the terminated program faster than we can free memory
+// but tools like valgrind might report "memory leaks" as it isn't obvious this is intentional.
+static SHARED_RESOLVER: LazyLock<HickoryDnsResolver> = LazyLock::new(|| {
+    tracing::debug!("Initializing shared DNS resolver");
+    HickoryDnsResolver::default()
+});
+
 #[derive(Debug, thiserror::Error)]
 #[error("hickory-dns resolver error: {hickory_error}")]
 /// Error occurring while resolving a hostname into an IP address.
@@ -47,29 +81,62 @@ pub struct HickoryDnsError {
 }

 /// Wrapper around an `AsyncResolver`, which implements the `Resolve` trait.
+///
+/// Typical use involves instantiating using the `Default` implementation and then resolving using
+/// methods or trait implementations.
+///
+/// The default initialization uses a shared underlying `AsyncResolver`. If a thread local resolver
+/// is required use `thread_resolver()` to build a resolver with an independently instantiated
+/// internal `AsyncResolver`.
 #[derive(Debug, Default, Clone)]
 pub struct HickoryDnsResolver {
-    /// Since we might not have been called in the context of a
-    /// Tokio Runtime in initialization, so we must delay the actual
-    /// construction of the resolver.
+    // Since we might not have been called in the context of a
+    // Tokio Runtime in initialization, so we must delay the actual
+    // construction of the resolver.
    state: Arc<OnceCell<TokioAsyncResolver>>,
    fallback: Arc<OnceCell<TokioAsyncResolver>>,
+    dont_use_shared: bool,
 }

 impl Resolve for HickoryDnsResolver {
    fn resolve(&self, name: Name) -> Resolving {
        let resolver = self.state.clone();
        let fallback = self.fallback.clone();
+        let independent = self.dont_use_shared;
        Box::pin(async move {
-            let resolver = resolver.get_or_try_init(new_resolver)?;
+            let resolver = resolver.get_or_try_init(|| {
+                // using a closure here is slightly gross, but this makes sure that if the
+                // lazy-init returns an error it can be handled by the client
+                if independent {
+                    new_resolver()
+                } else {
+                    Ok(SHARED_RESOLVER.state.get_or_try_init(new_resolver)?.clone())
+                }
+            })?;

            // try the primary DNS resolver that we set up (DoH or DoT or whatever)
            let lookup = match resolver.lookup_ip(name.as_str()).await {
                Ok(res) => res,
                Err(e) => {
                    // on failure use the fall back system configured DNS resolver
-                    warn!("primary DNS failed w/ error {e}: using system fallback");
-                    let resolver = fallback.get_or_try_init(new_resolver_system)?;
+                    match e.kind() {
+                        ResolveErrorKind::NoRecordsFound { .. } => {}
+                        _ => {
+                            warn!("primary DNS failed w/ error {e}: using system fallback");
+                        }
+                    }
+                    let resolver = fallback.get_or_try_init(|| {
+                        // using a closure here is slightly gross, but this makes sure that if the
+                        // lazy-init returns an error it can be handled by the client
+                        if independent {
+                            new_resolver_system()
+                        } else {
+                            Ok(SHARED_RESOLVER
+                                .fallback
+                                .get_or_try_init(new_resolver_system)?
+                                .clone())
+                        }
+                    })?;
                    resolver.lookup_ip(name.as_str()).await?
                }
            };
@@ -93,21 +160,55 @@ impl Iterator for SocketAddrs {
 impl HickoryDnsResolver {
    /// Attempt to resolve a domain name to a set of ['IpAddr']s
    pub async fn resolve_str(&self, name: &str) -> Result<LookupIp, HickoryDnsError> {
-        let resolver = self.state.get_or_try_init(new_resolver)?;
+        let resolver = self.state.get_or_try_init(|| self.new_resolver())?;

        // try the primary DNS resolver that we set up (DoH or DoT or whatever)
        let lookup = match resolver.lookup_ip(name).await {
            Ok(res) => res,
            Err(e) => {
                // on failure use the fall back system configured DNS resolver
-                warn!("primary DNS failed w/ error {e}: using system fallback");
-                let resolver = self.fallback.get_or_try_init(new_resolver_system)?;
+                match e.kind() {
+                    ResolveErrorKind::NoRecordsFound { .. } => {}
+                    _ => {
+                        warn!("primary DNS failed w/ error {e}: using system fallback");
+                    }
+                }
+                let resolver = self
+                    .fallback
+                    .get_or_try_init(|| self.new_resolver_system())?;
                resolver.lookup_ip(name).await?
            }
        };

        Ok(lookup)
    }
+
+    /// Create a (lazy-initialized) resolver that is not shared across threads.
+    pub fn thread_resolver() -> Self {
+        Self {
+            dont_use_shared: true,
+            ..Default::default()
+        }
+    }
+
+    fn new_resolver(&self) -> Result<TokioAsyncResolver, HickoryDnsError> {
+        if self.dont_use_shared {
+            new_resolver()
+        } else {
+            Ok(SHARED_RESOLVER.state.get_or_try_init(new_resolver)?.clone())
+        }
+    }
+
+    fn new_resolver_system(&self) -> Result<TokioAsyncResolver, HickoryDnsError> {
+        if self.dont_use_shared {
+            new_resolver_system()
+        } else {
+            Ok(SHARED_RESOLVER
+                .fallback
+                .get_or_try_init(new_resolver_system)?
+                .clone())
+        }
+    }
 }

 /// Create a new resolver with a custom DoT based configuration. The options are overridden to look
@@ -147,13 +147,13 @@ use thiserror::Error;
 use tracing::{instrument, warn};
 use url::Url;

+use http::HeaderMap;
+pub use reqwest::IntoUrl;
 #[cfg(not(target_arch = "wasm32"))]
 use std::net::SocketAddr;
 #[cfg(not(target_arch = "wasm32"))]
 use std::sync::Arc;

-pub use reqwest::IntoUrl;
-
 mod user_agent;
 pub use user_agent::UserAgent;

@@ -210,6 +210,12 @@ pub enum HttpClientError<E: Display = String> {
    #[error("failed to resolve request. status: '{status}', additional error message: {error}")]
    EndpointFailure { status: StatusCode, error: E },

+    #[error("failed to decode response body: {source} from {content}")]
+    ResponseDecodeFailure {
+        source: serde_json::Error,
+        content: String,
+    },
+
    #[cfg(target_arch = "wasm32")]
    #[error("the request has timed out")]
    RequestTimeout,
@@ -222,6 +228,8 @@ pub struct ClientBuilder {
    timeout: Option<Duration>,
    custom_user_agent: bool,
    reqwest_client_builder: reqwest::ClientBuilder,
+    #[allow(dead_code)] // not dead code, just unused in wasm
+    use_secure_dns: bool,
 }

 impl ClientBuilder {
@@ -233,37 +241,46 @@ impl ClientBuilder {
        U: IntoUrl,
        E: Display,
    {
-        // a naive check: if the provided URL does not start with http(s), add that scheme
        let str_url = url.as_str();

+        // a naive check: if the provided URL does not start with http(s), add that scheme
        if !str_url.starts_with("http") {
            let alt = format!("http://{str_url}");
            warn!("the provided url ('{str_url}') does not contain scheme information. Changing it to '{alt}' ...");
            // TODO: or should we maybe default to https?
            Self::new(alt)
        } else {
-            #[cfg(target_arch = "wasm32")]
-            let reqwest_client_builder = reqwest::ClientBuilder::new();
+            Ok(Self::new_with_url(url.into_url()?))
+        }
+    }

-            #[cfg(not(target_arch = "wasm32"))]
-            let reqwest_client_builder = {
-                let r = reqwest::ClientBuilder::new()
-                    .dns_resolver(Arc::new(HickoryDnsResolver::default()));
+    /// Constructs a new http `ClientBuilder` from a valid url.
+    pub fn new_with_url(url: Url) -> Self {
+        if !url.scheme().starts_with("http") {
+            warn!("the provided url ('{url}') does not use HTTP / HTTPS scheme");
+        }

-                // Note this is extra as the `gzip` feature for `reqwest` crate should be enabled which
-                // `"Enable[s] auto gzip decompression by checking the Content-Encoding response header."`
-                //
-                // I am going to leave it here anyways so that gzip decompression is attempted even if
-                // that feature is removed.
-                r.gzip(true)
-            };
+        #[cfg(target_arch = "wasm32")]
+        let reqwest_client_builder = reqwest::ClientBuilder::new();

-            Ok(ClientBuilder {
-                url: url.into_url()?,
-                timeout: None,
-                custom_user_agent: false,
-                reqwest_client_builder,
-            })
+        #[cfg(not(target_arch = "wasm32"))]
+        let reqwest_client_builder = {
+            let r = reqwest::ClientBuilder::new();
+
+            // Note this is extra as the `gzip` feature for `reqwest` crate should be enabled which
+            // `"Enable[s] auto gzip decompression by checking the Content-Encoding response header."`
+            //
+            // I am going to leave it here anyways so that gzip decompression is attempted even if
+            // that feature is removed.
+            r.gzip(true)
+        };
+
+        ClientBuilder {
+            url,
+            timeout: None,
+            custom_user_agent: false,
+            reqwest_client_builder,
+            use_secure_dns: true,
        }
    }

@@ -319,10 +336,18 @@ impl ClientBuilder {
            let mut builder = self
                .reqwest_client_builder
                .timeout(self.timeout.unwrap_or(DEFAULT_TIMEOUT));
+
+            // if no custom user agent was set, use a default
            if !self.custom_user_agent {
                builder =
                    builder.user_agent(format!("nym-http-api-client/{}", env!("CARGO_PKG_VERSION")))
            }
+
+            // unless explicitly disabled use the DoT/DoH enabled resolver
+            if self.use_secure_dns {
+                builder = builder.dns_resolver(Arc::new(HickoryDnsResolver::default()));
+            }
+
            builder.build()?
        };

@@ -349,6 +374,9 @@ pub struct Client {
 impl Client {
    /// Create a new http `Client`
    // no timeout until https://github.com/seanmonstar/reqwest/issues/1135 is fixed
+    //
+    // In order to prevent interference in API requests at the DNS phase we default to a resolver
+    // that uses DoT and DoH.
    pub fn new(base_url: Url, timeout: Option<Duration>) -> Self {
        Self::new_url::<_, String>(base_url, timeout).expect(
            "we provided valid url and we were unwrapping previous construction errors anyway",
@@ -849,6 +877,26 @@ fn sanitize_url<K: AsRef<str>, V: AsRef<str>>(
    url
 }

+fn decode_as_text(bytes: &bytes::Bytes, headers: HeaderMap) -> String {
+    use encoding_rs::{Encoding, UTF_8};
+    use mime::Mime;
+
+    let content_type = headers
+        .get(http::header::CONTENT_TYPE)
+        .and_then(|value| value.to_str().ok())
+        .and_then(|value| value.parse::<Mime>().ok());
+
+    let encoding_name = content_type
+        .as_ref()
+        .and_then(|mime| mime.get_param("charset").map(|charset| charset.as_str()))
+        .unwrap_or("utf-8");
+
+    let encoding = Encoding::for_label(encoding_name.as_bytes()).unwrap_or(UTF_8);
+
+    let (text, _, _) = encoding.decode(bytes);
+    text.into_owned()
+}
+
 /// Attempt to parse a json object from an HTTP response
 #[instrument(level = "debug", skip_all)]
 pub async fn parse_response<T, E>(res: Response, allow_empty: bool) -> Result<T, HttpClientError<E>>
@@ -864,21 +912,23 @@ where
            return Err(HttpClientError::EmptyResponse { status });
        }
    }
+    let headers = res.headers().clone();
+    tracing::trace!("headers: {:?}", headers);

    if res.status().is_success() {
-        #[cfg(debug_assertions)]
-        {
-            let text = res.text().await.inspect_err(|err| {
-                tracing::error!("Couldn't even get response text: {err}");
-            })?;
-            tracing::trace!("Result:\n{:#?}", text);
-
-            serde_json::from_str(&text)
-                .map_err(|err| HttpClientError::GenericRequestFailure(err.to_string()))
+        // internally reqwest is first retrieving bytes and then performing parsing via serde_json
+        // (and similarly does the same thing for text())
+        let full = res.bytes().await?;
+        match serde_json::from_slice(&full) {
+            Ok(data) => Ok(data),
+            Err(err) => {
+                let content = decode_as_text(&full, headers);
+                Err(HttpClientError::ResponseDecodeFailure {
+                    source: err,
+                    content,
+                })
+            }
        }
-
-        #[cfg(not(debug_assertions))]
-        Ok(res.json().await?)
    } else if res.status() == StatusCode::NOT_FOUND {
        Err(HttpClientError::NotFound)
    } else {
@@ -13,6 +13,7 @@ bincode = { workspace = true }
 bytes = { workspace = true }
 nym-bin-common = { path = "../bin-common" }
 nym-crypto = { path = "../crypto" }
+nym-service-provider-requests-common = { path = "../service-provider-requests-common" }
 nym-sphinx = { path = "../nymsphinx" }
 rand = { workspace = true }
 serde = { workspace = true, features = ["derive"] }
@@ -2,24 +2,18 @@ use serde::{Deserialize, Serialize};
 use std::fmt::{Display, Formatter};
 use std::net::{Ipv4Addr, Ipv6Addr};

-// The current version of the protocol.
-// The idea here is that we add new request response types at least one version before we start
-// using them.
-// Also, depending on the version in the client connect message the IPR could respond with a
-// matching older version.
-pub use v6::request;
-pub use v6::response;
-
 pub mod codec;
+pub mod sign;
 pub mod v6;
 pub mod v7;
+pub mod v8;

 // version 3: initial version
 // version 4: IPv6 support
 // version 5: Add severity level to info response
 // version 6: Increase the available IPs
 // version 7: Add signature support (for the future)
-pub const CURRENT_VERSION: u8 = 6;
+// version 8: Anonymous sends

 #[derive(Copy, Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
 pub struct IpPair {
@@ -45,3 +39,9 @@ fn make_bincode_serializer() -> impl bincode::Options {
        .with_big_endian()
        .with_varint_encoding()
 }
+
+fn generate_random() -> u64 {
+    use rand::RngCore;
+    let mut rng = rand::rngs::OsRng;
+    rng.next_u64()
+}
@@ -1,6 +1,7 @@
 use std::time::Duration;

-use nym_crypto::asymmetric::identity;
+use nym_crypto::asymmetric::ed25519;
+use time::OffsetDateTime;

 // For reply protection, if a request is older than this, it will be rejected
 const MAX_REQUEST_AGE: Duration = Duration::from_secs(10);
@@ -22,29 +23,37 @@ pub enum SignatureError {
    #[error("signature verification failed")]
    VerificationFailed {
        message: String,
-        error: identity::SignatureError,
+        error: ed25519::SignatureError,
    },
 }

 pub trait SignedRequest {
-    fn identity(&self) -> &identity::PublicKey;
+    fn identity(&self) -> Option<&ed25519::PublicKey>;

-    fn request(&self) -> Result<Vec<u8>, SignatureError>;
+    fn request_as_bytes(&self) -> Result<Vec<u8>, SignatureError>;

-    fn signature(&self) -> Option<&identity::Signature>;
+    fn signature(&self) -> Option<&ed25519::Signature>;

-    fn timestamp(&self) -> time::OffsetDateTime;
+    fn timestamp(&self) -> OffsetDateTime;

    fn verify(&self) -> Result<(), SignatureError> {
+        let identity = match self.identity() {
+            Some(identity) => identity,
+            None => {
+                // If we are not revealing our identity, we don't need to verify anything
+                return Ok(());
+            }
+        };
+
        if let Some(signature) = self.signature() {
            // First check that the request is recent enough
-            if time::OffsetDateTime::now_utc() - self.timestamp() > MAX_REQUEST_AGE {
+            if OffsetDateTime::now_utc() - self.timestamp() > MAX_REQUEST_AGE {
                return Err(SignatureError::RequestOutOfDate);
            }

-            let request_as_bytes = self.request()?;
+            let request_as_bytes = self.request_as_bytes()?;

-            self.identity()
+            identity
                .verify(request_as_bytes, signature)
                .map_err(|error| SignatureError::VerificationFailed {
                    message: "signature verification failed".to_string(),
@@ -1,69 +0,0 @@
-// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
-// SPDX-License-Identifier: Apache-2.0
-
-use crate::{v6, v7};
-
-impl From<v7::response::StaticConnectFailureReason> for v6::response::StaticConnectFailureReason {
-    fn from(failure: v7::response::StaticConnectFailureReason) -> Self {
-        match failure {
-            v7::response::StaticConnectFailureReason::RequestedIpAlreadyInUse => {
-                v6::response::StaticConnectFailureReason::RequestedIpAlreadyInUse
-            }
-            v7::response::StaticConnectFailureReason::RequestedNymAddressAlreadyInUse => {
-                v6::response::StaticConnectFailureReason::RequestedNymAddressAlreadyInUse
-            }
-            v7::response::StaticConnectFailureReason::OutOfDateTimestamp => {
-                v6::response::StaticConnectFailureReason::Other("out of date timestamp".to_string())
-            }
-            v7::response::StaticConnectFailureReason::Other(reason) => {
-                v6::response::StaticConnectFailureReason::Other(reason)
-            }
-        }
-    }
-}
-
-impl From<v7::response::DynamicConnectFailureReason> for v6::response::DynamicConnectFailureReason {
-    fn from(failure: v7::response::DynamicConnectFailureReason) -> Self {
-        match failure {
-            v7::response::DynamicConnectFailureReason::RequestedNymAddressAlreadyInUse => {
-                v6::response::DynamicConnectFailureReason::RequestedNymAddressAlreadyInUse
-            }
-            v7::response::DynamicConnectFailureReason::NoAvailableIp => {
-                v6::response::DynamicConnectFailureReason::NoAvailableIp
-            }
-            v7::response::DynamicConnectFailureReason::Other(err) => {
-                v6::response::DynamicConnectFailureReason::Other(err)
-            }
-        }
-    }
-}
-
-impl From<v7::response::InfoResponseReply> for v6::response::InfoResponseReply {
-    fn from(reply: v7::response::InfoResponseReply) -> Self {
-        match reply {
-            v7::response::InfoResponseReply::Generic { msg } => {
-                v6::response::InfoResponseReply::Generic { msg }
-            }
-            v7::response::InfoResponseReply::VersionMismatch {
-                request_version,
-                response_version,
-            } => v6::response::InfoResponseReply::VersionMismatch {
-                request_version,
-                response_version,
-            },
-            v7::response::InfoResponseReply::ExitPolicyFilterCheckFailed { dst } => {
-                v6::response::InfoResponseReply::ExitPolicyFilterCheckFailed { dst }
-            }
-        }
-    }
-}
-
-impl From<v7::response::InfoLevel> for v6::response::InfoLevel {
-    fn from(level: v7::response::InfoLevel) -> Self {
-        match level {
-            v7::response::InfoLevel::Info => v6::response::InfoLevel::Info,
-            v7::response::InfoLevel::Warn => v6::response::InfoLevel::Warn,
-            v7::response::InfoLevel::Error => v6::response::InfoLevel::Error,
-        }
-    }
-}
@@ -1,4 +1,3 @@
-pub mod conversion;
 pub mod request;
 pub mod response;

@@ -1,125 +0,0 @@
-use time::OffsetDateTime;
-
-use crate::{v6, v7};
-
-impl From<v6::request::IpPacketRequest> for v7::request::IpPacketRequest {
-    fn from(ip_packet_request: v6::request::IpPacketRequest) -> Self {
-        Self {
-            version: 7,
-            data: ip_packet_request.data.into(),
-        }
-    }
-}
-
-impl From<v6::request::IpPacketRequestData> for v7::request::IpPacketRequestData {
-    fn from(ip_packet_request_data: v6::request::IpPacketRequestData) -> Self {
-        match ip_packet_request_data {
-            v6::request::IpPacketRequestData::StaticConnect(r) => {
-                v7::request::IpPacketRequestData::StaticConnect(
-                    v7::request::SignedStaticConnectRequest {
-                        request: r.into(),
-                        signature: None,
-                    },
-                )
-            }
-            v6::request::IpPacketRequestData::DynamicConnect(r) => {
-                v7::request::IpPacketRequestData::DynamicConnect(
-                    v7::request::SignedDynamicConnectRequest {
-                        request: r.into(),
-                        signature: None,
-                    },
-                )
-            }
-            v6::request::IpPacketRequestData::Disconnect(r) => {
-                v7::request::IpPacketRequestData::Disconnect(v7::request::SignedDisconnectRequest {
-                    request: r.into(),
-                    signature: None,
-                })
-            }
-            v6::request::IpPacketRequestData::Data(r) => {
-                v7::request::IpPacketRequestData::Data(r.into())
-            }
-            v6::request::IpPacketRequestData::Ping(r) => {
-                v7::request::IpPacketRequestData::Ping(r.into())
-            }
-            v6::request::IpPacketRequestData::Health(r) => {
-                v7::request::IpPacketRequestData::Health(r.into())
-            }
-        }
-    }
-}
-
-impl From<v6::request::StaticConnectRequest> for v7::request::StaticConnectRequest {
-    fn from(static_connect_request: v6::request::StaticConnectRequest) -> Self {
-        Self {
-            request_id: static_connect_request.request_id,
-            ips: static_connect_request.ips,
-            reply_to: static_connect_request.reply_to,
-            reply_to_hops: static_connect_request.reply_to_hops,
-            reply_to_avg_mix_delays: static_connect_request.reply_to_avg_mix_delays,
-            buffer_timeout: static_connect_request.buffer_timeout,
-            timestamp: OffsetDateTime::now_utc(),
-        }
-    }
-}
-
-#[allow(deprecated)]
-impl From<v6::request::DynamicConnectRequest> for v7::request::DynamicConnectRequest {
-    fn from(dynamic_connect_request: v6::request::DynamicConnectRequest) -> Self {
-        Self {
-            request_id: dynamic_connect_request.request_id,
-            reply_to: dynamic_connect_request.reply_to,
-            reply_to_hops: dynamic_connect_request.reply_to_hops,
-            reply_to_avg_mix_delays: dynamic_connect_request.reply_to_avg_mix_delays,
-            buffer_timeout: dynamic_connect_request.buffer_timeout,
-            timestamp: OffsetDateTime::now_utc(),
-        }
-    }
-}
-
-impl From<v6::request::DisconnectRequest> for v7::request::SignedDisconnectRequest {
-    fn from(disconnect_request: v6::request::DisconnectRequest) -> Self {
-        Self {
-            request: disconnect_request.into(),
-            signature: None,
-        }
-    }
-}
-
-impl From<v6::request::DisconnectRequest> for v7::request::DisconnectRequest {
-    fn from(disconnect_request: v6::request::DisconnectRequest) -> Self {
-        Self {
-            request_id: disconnect_request.request_id,
-            reply_to: disconnect_request.reply_to,
-            timestamp: OffsetDateTime::now_utc(),
-        }
-    }
-}
-
-impl From<v6::request::DataRequest> for v7::request::DataRequest {
-    fn from(data_request: v6::request::DataRequest) -> Self {
-        Self {
-            ip_packets: data_request.ip_packets,
-        }
-    }
-}
-
-impl From<v6::request::PingRequest> for v7::request::PingRequest {
-    fn from(ping_request: v6::request::PingRequest) -> Self {
-        Self {
-            request_id: ping_request.request_id,
-            reply_to: ping_request.reply_to,
-            timestamp: OffsetDateTime::now_utc(),
-        }
-    }
-}
-
-impl From<v6::request::HealthRequest> for v7::request::HealthRequest {
-    fn from(health_request: v6::request::HealthRequest) -> Self {
-        Self {
-            request_id: health_request.request_id,
-            reply_to: health_request.reply_to,
-            timestamp: OffsetDateTime::now_utc(),
-        }
-    }
-}
@@ -1,6 +1,4 @@
-pub mod conversion;
 pub mod request;
 pub mod response;
-pub mod signature;

 pub const VERSION: u8 = 7;
@@ -1,22 +1,18 @@
+use std::fmt;
+
 use nym_crypto::asymmetric::identity;
 use nym_sphinx::addressing::clients::Recipient;
 use serde::{Deserialize, Serialize};
 use time::OffsetDateTime;

-use crate::{make_bincode_serializer, IpPair};
-
-use super::{
-    signature::{SignatureError, SignedRequest},
-    VERSION,
+use crate::{
+    sign::{SignatureError, SignedRequest},
+    IpPair,
 };

-fn generate_random() -> u64 {
-    use rand::RngCore;
-    let mut rng = rand::rngs::OsRng;
-    rng.next_u64()
-}
+use super::VERSION;

-#[derive(Clone, Debug, Serialize, Deserialize)]
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 pub struct IpPacketRequest {
    pub version: u8,
    pub data: IpPacketRequestData,
@@ -30,7 +26,7 @@ impl IpPacketRequest {
        reply_to_avg_mix_delays: Option<f64>,
        buffer_timeout: Option<u64>,
    ) -> (Self, u64) {
-        let request_id = generate_random();
+        let request_id = crate::generate_random();
        (
            Self {
                version: VERSION,
@@ -58,7 +54,7 @@ impl IpPacketRequest {
        reply_to_avg_mix_delays: Option<f64>,
        buffer_timeout: Option<u64>,
    ) -> (Self, u64) {
-        let request_id = generate_random();
+        let request_id = crate::generate_random();
        (
            Self {
                version: VERSION,
@@ -79,7 +75,7 @@ impl IpPacketRequest {
    }

    pub fn new_disconnect_request(reply_to: Recipient) -> (Self, u64) {
-        let request_id = generate_random();
+        let request_id = crate::generate_random();
        (
            Self {
                version: VERSION,
@@ -104,7 +100,7 @@ impl IpPacketRequest {
    }

    pub fn new_ping(reply_to: Recipient) -> (Self, u64) {
-        let request_id = generate_random();
+        let request_id = crate::generate_random();
        (
            Self {
                version: VERSION,
@@ -119,7 +115,7 @@ impl IpPacketRequest {
    }

    pub fn new_health_request(reply_to: Recipient) -> (Self, u64) {
-        let request_id = generate_random();
+        let request_id = crate::generate_random();
        (
            Self {
                version: VERSION,
@@ -155,16 +151,27 @@ impl IpPacketRequest {
        }
    }

+    pub fn verify(&self) -> Result<(), SignatureError> {
+        match &self.data {
+            IpPacketRequestData::StaticConnect(request) => request.verify(),
+            IpPacketRequestData::DynamicConnect(request) => request.verify(),
+            IpPacketRequestData::Disconnect(request) => request.verify(),
+            IpPacketRequestData::Data(_) => Ok(()),
+            IpPacketRequestData::Ping(_) => Ok(()),
+            IpPacketRequestData::Health(_) => Ok(()),
+        }
+    }
+
    pub fn to_bytes(&self) -> Result<Vec<u8>, bincode::Error> {
        use bincode::Options;
-        make_bincode_serializer().serialize(self)
+        crate::make_bincode_serializer().serialize(self)
    }

    pub fn from_reconstructed_message(
        message: &nym_sphinx::receiver::ReconstructedMessage,
    ) -> Result<Self, bincode::Error> {
        use bincode::Options;
-        make_bincode_serializer().deserialize(&message.message)
+        crate::make_bincode_serializer().deserialize(&message.message)
    }
 }

@@ -179,6 +186,19 @@ pub enum IpPacketRequestData {
    Health(HealthRequest),
 }

+impl fmt::Display for IpPacketRequestData {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            IpPacketRequestData::StaticConnect(_) => write!(f, "StaticConnect"),
+            IpPacketRequestData::DynamicConnect(_) => write!(f, "DynamicConnect"),
+            IpPacketRequestData::Disconnect(_) => write!(f, "Disconnect"),
+            IpPacketRequestData::Data(_) => write!(f, "Data"),
+            IpPacketRequestData::Ping(_) => write!(f, "Ping"),
+            IpPacketRequestData::Health(_) => write!(f, "Health"),
+        }
+    }
+}
+
 impl IpPacketRequestData {
    pub fn add_signature(&mut self, signature: identity::Signature) -> Option<identity::Signature> {
        match self {
@@ -202,9 +222,9 @@ impl IpPacketRequestData {

    pub fn signable_request(&self) -> Option<Result<Vec<u8>, SignatureError>> {
        match self {
-            IpPacketRequestData::StaticConnect(request) => Some(request.request()),
-            IpPacketRequestData::DynamicConnect(request) => Some(request.request()),
-            IpPacketRequestData::Disconnect(request) => Some(request.request()),
+            IpPacketRequestData::StaticConnect(request) => Some(request.request_as_bytes()),
+            IpPacketRequestData::DynamicConnect(request) => Some(request.request_as_bytes()),
+            IpPacketRequestData::Disconnect(request) => Some(request.request_as_bytes()),
            IpPacketRequestData::Data(_) => None,
            IpPacketRequestData::Ping(_) => None,
            IpPacketRequestData::Health(_) => None,
@@ -242,7 +262,7 @@ pub struct StaticConnectRequest {
 impl StaticConnectRequest {
    pub fn to_bytes(&self) -> Result<Vec<u8>, bincode::Error> {
        use bincode::Options;
-        make_bincode_serializer().serialize(self)
+        crate::make_bincode_serializer().serialize(self)
    }
 }

@@ -253,11 +273,11 @@ pub struct SignedStaticConnectRequest {
 }

 impl SignedRequest for SignedStaticConnectRequest {
-    fn identity(&self) -> &identity::PublicKey {
-        self.request.reply_to.identity()
+    fn identity(&self) -> Option<&identity::PublicKey> {
+        Some(self.request.reply_to.identity())
    }

-    fn request(&self) -> Result<Vec<u8>, SignatureError> {
+    fn request_as_bytes(&self) -> Result<Vec<u8>, SignatureError> {
        self.request
            .to_bytes()
            .map_err(|error| SignatureError::RequestSerializationError {
@@ -306,7 +326,7 @@ pub struct DynamicConnectRequest {
 impl DynamicConnectRequest {
    pub fn to_bytes(&self) -> Result<Vec<u8>, bincode::Error> {
        use bincode::Options;
-        make_bincode_serializer().serialize(self)
+        crate::make_bincode_serializer().serialize(self)
    }
 }

@@ -317,11 +337,11 @@ pub struct SignedDynamicConnectRequest {
 }

 impl SignedRequest for SignedDynamicConnectRequest {
-    fn identity(&self) -> &identity::PublicKey {
-        self.request.reply_to.identity()
+    fn identity(&self) -> Option<&identity::PublicKey> {
+        Some(self.request.reply_to.identity())
    }

-    fn request(&self) -> Result<Vec<u8>, SignatureError> {
+    fn request_as_bytes(&self) -> Result<Vec<u8>, SignatureError> {
        self.request
            .to_bytes()
            .map_err(|error| SignatureError::RequestSerializationError {
@@ -355,7 +375,7 @@ pub struct DisconnectRequest {
 impl DisconnectRequest {
    pub fn to_bytes(&self) -> Result<Vec<u8>, bincode::Error> {
        use bincode::Options;
-        make_bincode_serializer().serialize(self)
+        crate::make_bincode_serializer().serialize(self)
    }
 }

@@ -366,11 +386,11 @@ pub struct SignedDisconnectRequest {
 }

 impl SignedRequest for SignedDisconnectRequest {
-    fn identity(&self) -> &identity::PublicKey {
-        self.request.reply_to.identity()
+    fn identity(&self) -> Option<&identity::PublicKey> {
+        Some(self.request.reply_to.identity())
    }

-    fn request(&self) -> Result<Vec<u8>, SignatureError> {
+    fn request_as_bytes(&self) -> Result<Vec<u8>, SignatureError> {
        self.request
            .to_bytes()
            .map_err(|error| SignatureError::RequestSerializationError {
@@ -0,0 +1,4 @@
+pub mod request;
+pub mod response;
+
+pub const VERSION: u8 = 8;
@@ -0,0 +1,304 @@
+use std::fmt;
+
+use nym_service_provider_requests_common::{Protocol, ServiceProviderType};
+use serde::{Deserialize, Serialize};
+use time::OffsetDateTime;
+
+use super::VERSION;
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+pub struct IpPacketRequest {
+    pub protocol: Protocol,
+    pub data: IpPacketRequestData,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+pub enum IpPacketRequestData {
+    Data(DataRequest),
+    Control(Box<ControlRequest>),
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+pub enum ControlRequest {
+    Connect(ConnectRequest),
+    Disconnect(DisconnectRequest),
+    Ping(PingRequest),
+    Health(HealthRequest),
+}
+
+// A data request is when the client wants to send an IP packet to a destination.
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+pub struct DataRequest {
+    pub ip_packets: bytes::Bytes,
+}
+
+// A dynamic connect request is when the client does not provide the internal IP address it will use
+// on the ip packet router, and instead requests one to be assigned to it.
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+pub struct ConnectRequest {
+    pub request_id: u64,
+
+    // The maximum time in milliseconds the IPR should wait when filling up a mix packet
+    // with ip packets.
+    pub buffer_timeout: Option<u64>,
+
+    // Timestamp of when the request was sent by the client.
+    pub timestamp: OffsetDateTime,
+}
+
+// A disconnect request is when the client wants to disconnect from the ip packet router and free
+// up the allocated IP address.
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+pub struct DisconnectRequest {
+    pub request_id: u64,
+
+    // Timestamp of when the request was sent by the client.
+    pub timestamp: OffsetDateTime,
+}
+
+// A ping request is when the client wants to check if the ip packet router is still alive.
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+pub struct PingRequest {
+    pub request_id: u64,
+
+    // Timestamp of when the request was sent by the client.
+    pub timestamp: OffsetDateTime,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+pub struct HealthRequest {
+    pub request_id: u64,
+
+    // Timestamp of when the request was sent by the client.
+    pub timestamp: OffsetDateTime,
+}
+
+impl IpPacketRequest {
+    pub fn new_connect_request(buffer_timeout: Option<u64>) -> (Self, u64) {
+        let protocol = Protocol {
+            version: VERSION,
+            service_provider_type: ServiceProviderType::IpPacketRouter,
+        };
+        let request_id = rand::random();
+        let timestamp = OffsetDateTime::now_utc();
+        let connect = ConnectRequest {
+            request_id,
+            buffer_timeout,
+            timestamp,
+        };
+        let request = Self {
+            protocol,
+            data: IpPacketRequestData::Control(Box::new(ControlRequest::Connect(connect))),
+        };
+        (request, request_id)
+    }
+
+    pub fn new_disconnect_request() -> (Self, u64) {
+        let protocol = Protocol {
+            version: VERSION,
+            service_provider_type: ServiceProviderType::IpPacketRouter,
+        };
+        let request_id = rand::random();
+        let timestamp = OffsetDateTime::now_utc();
+        let disconnect = DisconnectRequest {
+            request_id,
+            timestamp,
+        };
+        let request = Self {
+            protocol,
+            data: IpPacketRequestData::Control(Box::new(ControlRequest::Disconnect(disconnect))),
+        };
+        (request, request_id)
+    }
+
+    pub fn new_data_request(ip_packets: bytes::Bytes) -> Self {
+        Self {
+            protocol: Protocol {
+                version: VERSION,
+                service_provider_type: ServiceProviderType::IpPacketRouter,
+            },
+            data: IpPacketRequestData::Data(DataRequest { ip_packets }),
+        }
+    }
+
+    pub fn new_ping() -> (Self, u64) {
+        let protocol = Protocol {
+            version: VERSION,
+            service_provider_type: ServiceProviderType::IpPacketRouter,
+        };
+        let request_id = rand::random();
+        let timestamp = OffsetDateTime::now_utc();
+        let ping_request = PingRequest {
+            request_id,
+            timestamp,
+        };
+        let request = Self {
+            protocol,
+            data: IpPacketRequestData::Control(Box::new(ControlRequest::Ping(ping_request))),
+        };
+        (request, request_id)
+    }
+
+    pub fn new_health_request() -> (Self, u64) {
+        let protocol = Protocol {
+            version: VERSION,
+            service_provider_type: ServiceProviderType::IpPacketRouter,
+        };
+        let request_id = rand::random();
+        let timestamp = OffsetDateTime::now_utc();
+        let health_request = HealthRequest {
+            request_id,
+            timestamp,
+        };
+        let request = Self {
+            protocol,
+            data: IpPacketRequestData::Control(Box::new(ControlRequest::Health(health_request))),
+        };
+        (request, request_id)
+    }
+
+    pub fn id(&self) -> Option<u64> {
+        match self.data {
+            IpPacketRequestData::Control(ref c) => Some(c.id()),
+            IpPacketRequestData::Data(_) => None,
+        }
+    }
+
+    pub fn to_bytes(&self) -> Result<Vec<u8>, bincode::Error> {
+        use bincode::Options;
+        crate::make_bincode_serializer().serialize(self)
+    }
+
+    pub fn from_reconstructed_message(
+        message: &nym_sphinx::receiver::ReconstructedMessage,
+    ) -> Result<Self, bincode::Error> {
+        use bincode::Options;
+        crate::make_bincode_serializer().deserialize(&message.message)
+    }
+}
+
+impl fmt::Display for IpPacketRequest {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(
+            f,
+            "IpPacketRequest {{ version: {}, data: {} }}",
+            self.protocol.version, self.data
+        )
+    }
+}
+
+impl fmt::Display for IpPacketRequestData {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            IpPacketRequestData::Data(_) => write!(f, "Data"),
+            IpPacketRequestData::Control(c) => write!(f, "Control({})", c),
+        }
+    }
+}
+
+impl ControlRequest {
+    fn id(&self) -> u64 {
+        match self {
+            ControlRequest::Connect(request) => request.request_id,
+            ControlRequest::Disconnect(request) => request.request_id,
+            ControlRequest::Ping(request) => request.request_id,
+            ControlRequest::Health(request) => request.request_id,
+        }
+    }
+}
+
+impl fmt::Display for ControlRequest {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            ControlRequest::Connect(_) => write!(f, "Connect"),
+            ControlRequest::Disconnect(_) => write!(f, "Disconnect"),
+            ControlRequest::Ping(_) => write!(f, "Ping"),
+            ControlRequest::Health(_) => write!(f, "Health"),
+        }
+    }
+}
+
+impl ConnectRequest {
+    pub fn to_bytes(&self) -> Result<Vec<u8>, bincode::Error> {
+        use bincode::Options;
+        crate::make_bincode_serializer().serialize(self)
+    }
+}
+
+impl DisconnectRequest {
+    pub fn to_bytes(&self) -> Result<Vec<u8>, bincode::Error> {
+        use bincode::Options;
+        crate::make_bincode_serializer().serialize(self)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use time::macros::datetime;
+
+    use super::*;
+
+    #[test]
+    fn check_size_of_request() {
+        let connect = IpPacketRequest {
+            protocol: Protocol {
+                version: 4,
+                service_provider_type: ServiceProviderType::IpPacketRouter,
+            },
+            data: IpPacketRequestData::Control(Box::new(ControlRequest::Connect(ConnectRequest {
+                request_id: 123,
+                buffer_timeout: None,
+                timestamp: datetime!(2024-01-01 12:59:59.5 UTC),
+            }))),
+        };
+        assert_eq!(connect.to_bytes().unwrap().len(), 21);
+    }
+
+    #[test]
+    fn check_size_of_data() {
+        let data = IpPacketRequest {
+            protocol: Protocol {
+                version: 4,
+                service_provider_type: ServiceProviderType::IpPacketRouter,
+            },
+            data: IpPacketRequestData::Data(DataRequest {
+                ip_packets: bytes::Bytes::from(vec![1u8; 32]),
+            }),
+        };
+        assert_eq!(data.to_bytes().unwrap().len(), 36);
+    }
+
+    #[test]
+    fn serialize_and_deserialize_data_request() {
+        let data = IpPacketRequest {
+            protocol: Protocol {
+                version: 4,
+                service_provider_type: ServiceProviderType::IpPacketRouter,
+            },
+            data: IpPacketRequestData::Data(DataRequest {
+                ip_packets: bytes::Bytes::from(vec![1, 2, 4, 2, 5]),
+            }),
+        };
+
+        let serialized = data.to_bytes().unwrap();
+        let deserialized = IpPacketRequest::from_reconstructed_message(
+            &nym_sphinx::receiver::ReconstructedMessage {
+                message: serialized,
+                sender_tag: None,
+            },
+        )
+        .unwrap();
+
+        assert_eq!(deserialized.protocol.version, 4);
+        assert_eq!(
+            deserialized.protocol.service_provider_type,
+            ServiceProviderType::IpPacketRouter
+        );
+        assert_eq!(
+            deserialized.data,
+            IpPacketRequestData::Data(DataRequest {
+                ip_packets: bytes::Bytes::from(vec![1, 2, 4, 2, 5]),
+            })
+        );
+    }
+}
@@ -0,0 +1,219 @@
+use nym_bin_common::build_information::BinaryBuildInformationOwned;
+use serde::{Deserialize, Serialize};
+
+use crate::{make_bincode_serializer, IpPair};
+
+use super::VERSION;
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct IpPacketResponse {
+    pub version: u8,
+    pub data: IpPacketResponseData,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub enum IpPacketResponseData {
+    Data(DataResponse),
+    Control(Box<ControlResponse>),
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct DataResponse {
+    pub ip_packet: bytes::Bytes,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub enum ControlResponse {
+    // Response for a connect request
+    Connect(ConnectResponse),
+
+    // Response for a disconnect initiqated by the client
+    Disconnect(DisconnectResponse),
+
+    // Message from the server that the client got disconnected without the client initiating it
+    UnrequestedDisconnect(UnrequestedDisconnect),
+
+    // Response to ping request
+    Pong(PongResponse),
+
+    // Response for a health request
+    Health(Box<HealthResponse>),
+
+    // Info response. This can be anything from informative messages to errors
+    Info(InfoResponse),
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct ConnectResponse {
+    pub request_id: u64,
+    pub reply: ConnectResponseReply,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub enum ConnectResponseReply {
+    Success(ConnectSuccess),
+    Failure(ConnectFailureReason),
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct ConnectSuccess {
+    pub ips: IpPair,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, thiserror::Error)]
+pub enum ConnectFailureReason {
+    #[error("client is already connected")]
+    ClientAlreadyConnected,
+
+    #[error("no available ip address")]
+    NoAvailableIp,
+
+    #[error("{0}")]
+    Other(String),
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct DisconnectResponse {
+    pub request_id: u64,
+    pub reply: DisconnectResponseReply,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub enum DisconnectResponseReply {
+    Success,
+    Failure(DisconnectFailureReason),
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, thiserror::Error)]
+pub enum DisconnectFailureReason {
+    #[error("client is not connected")]
+    ClientNotConnected,
+
+    #[error("{0}")]
+    Other(String),
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct UnrequestedDisconnect {
+    pub reason: UnrequestedDisconnectReason,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, thiserror::Error)]
+pub enum UnrequestedDisconnectReason {
+    #[error("client mixnet traffic timeout")]
+    ClientMixnetTrafficTimeout,
+
+    #[error("client tun traffic timeout")]
+    ClientTunTrafficTimeout,
+
+    #[error("{0}")]
+    Other(String),
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct PongResponse {
+    pub request_id: u64,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct HealthResponse {
+    pub request_id: u64,
+    pub reply: HealthResponseReply,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct HealthResponseReply {
+    // Return the binary build information of the IPR
+    pub build_info: BinaryBuildInformationOwned,
+
+    // Return if the IPR has performed a successful routing test.
+    pub routable: Option<bool>,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct InfoResponse {
+    pub request_id: u64,
+    pub reply: InfoResponseReply,
+    pub level: InfoLevel,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, thiserror::Error)]
+pub enum InfoResponseReply {
+    #[error("{msg}")]
+    Generic { msg: String },
+
+    #[error(
+        "version mismatch: response is v{request_version} and response is v{response_version}"
+    )]
+    VersionMismatch {
+        request_version: u8,
+        response_version: u8,
+    },
+
+    #[error("destination failed exit policy filter check: {dst}")]
+    ExitPolicyFilterCheckFailed { dst: String },
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub enum InfoLevel {
+    Info,
+    Warn,
+    Error,
+}
+
+impl IpPacketResponse {
+    pub fn new_ip_packet(ip_packet: bytes::Bytes) -> Self {
+        Self {
+            version: VERSION,
+            data: IpPacketResponseData::Data(DataResponse { ip_packet }),
+        }
+    }
+
+    pub fn id(&self) -> Option<u64> {
+        match &self.data {
+            IpPacketResponseData::Data(_) => None,
+            IpPacketResponseData::Control(response) => response.id(),
+        }
+    }
+
+    pub fn to_bytes(&self) -> Result<Vec<u8>, bincode::Error> {
+        use bincode::Options;
+        make_bincode_serializer().serialize(self)
+    }
+
+    pub fn from_reconstructed_message(
+        message: &nym_sphinx::receiver::ReconstructedMessage,
+    ) -> Result<Self, bincode::Error> {
+        use bincode::Options;
+        make_bincode_serializer().deserialize(&message.message)
+    }
+}
+
+impl IpPacketResponseData {
+    pub fn to_bytes(&self) -> Result<Vec<u8>, bincode::Error> {
+        use bincode::Options;
+        make_bincode_serializer().serialize(self)
+    }
+}
+
+impl ControlResponse {
+    fn id(&self) -> Option<u64> {
+        match self {
+            ControlResponse::Connect(response) => Some(response.request_id),
+            ControlResponse::Disconnect(response) => Some(response.request_id),
+            ControlResponse::UnrequestedDisconnect(_) => None,
+            ControlResponse::Pong(response) => Some(response.request_id),
+            ControlResponse::Health(response) => Some(response.request_id),
+            ControlResponse::Info(response) => Some(response.request_id),
+        }
+    }
+}
+
+impl ConnectResponseReply {
+    pub fn is_success(&self) -> bool {
+        match self {
+            ConnectResponseReply::Success(_) => true,
+            ConnectResponseReply::Failure(_) => false,
+        }
+    }
+}
@@ -15,10 +15,10 @@ bls12_381 = { workspace = true, features = ["alloc", "pairings", "experimental",
 bincode.workspace = true
 cfg-if.workspace = true
 itertools = { workspace = true }
-digest = "0.9"
+digest = { workspace = true }
 rand = { workspace = true }
 thiserror = { workspace = true }
-sha2 = "0.9"
+sha2 = { workspace = true }
 bs58 = { workspace = true }
 serde = { workspace = true, features = ["derive"] }
 rayon = { workspace = true, optional = true }
@@ -113,17 +113,13 @@ const G1_HASH_DOMAIN: &[u8] = b"NYMECASH-V01-CS02-with-BLS12381G1_XMD:SHA-256_SS
 const SCALAR_HASH_DOMAIN: &[u8] = b"NYMECASH-V01-CS02-with-expander-SHA256";

 pub fn hash_g1<M: AsRef<[u8]>>(msg: M) -> G1Projective {
-    <G1Projective as HashToCurve<ExpandMsgXmd<sha2::Sha256>>>::hash_to_curve(msg, G1_HASH_DOMAIN)
+    <G1Projective as HashToCurve<ExpandMsgXmd<sha2::Sha256>>>::hash_to_curve([msg], G1_HASH_DOMAIN)
 }

 pub fn hash_to_scalar<M: AsRef<[u8]>>(msg: M) -> Scalar {
    let mut output = vec![Scalar::zero()];

-    Scalar::hash_to_field::<ExpandMsgXmd<sha2::Sha256>>(
-        msg.as_ref(),
-        SCALAR_HASH_DOMAIN,
-        &mut output,
-    );
+    Scalar::hash_to_field::<ExpandMsgXmd<sha2::Sha256>, _>([msg], SCALAR_HASH_DOMAIN, &mut output);
    output[0]
 }

@@ -401,4 +397,75 @@ mod tests {
        assert_eq!(hash_to_scalar(msg2), hash_to_scalar(msg2));
        assert_ne!(hash_to_scalar(msg1), hash_to_scalar(msg2));
    }
+
+    #[test]
+    fn test_hash_to_scalar() {
+        let msg1 = "foo";
+        let expected1 = Scalar::from_bytes(&[
+            253, 57, 224, 227, 175, 195, 226, 82, 46, 175, 33, 126, 171, 239, 255, 92, 108, 168, 6,
+            79, 90, 11, 235, 236, 221, 10, 85, 133, 42, 81, 95, 30,
+        ])
+        .unwrap();
+
+        let msg2 = "bar";
+        let expected2 = Scalar::from_bytes(&[
+            48, 83, 69, 52, 42, 18, 135, 244, 211, 190, 160, 196, 118, 154, 24, 126, 0, 125, 72,
+            201, 170, 225, 123, 201, 52, 120, 171, 132, 235, 182, 20, 26,
+        ])
+        .unwrap();
+
+        let msg3 = [
+            33, 135, 76, 234, 71, 35, 247, 216, 39, 242, 42, 88, 152, 29, 74, 135, 9, 29, 216, 123,
+            250, 87, 108, 29, 245, 126, 109, 102, 84, 71, 158, 224, 145, 243, 49, 121, 244, 27,
+            115, 121, 25, 66, 216, 67, 97, 101, 140, 160, 77, 239, 114, 215, 152, 48, 15, 231, 101,
+            60, 42, 92, 128, 131, 161, 43,
+        ];
+        let expected3 = Scalar::from_bytes(&[
+            128, 189, 8, 43, 186, 55, 52, 61, 171, 196, 159, 177, 162, 100, 27, 143, 85, 83, 218,
+            171, 91, 220, 155, 25, 7, 38, 2, 36, 4, 93, 136, 4,
+        ])
+        .unwrap();
+
+        assert_eq!(hash_to_scalar(msg1), expected1);
+        assert_eq!(hash_to_scalar(msg2), expected2);
+        assert_eq!(hash_to_scalar(msg3), expected3);
+    }
+
+    #[test]
+    fn test_hash_to_g1() {
+        let msg1 = "foo";
+        let expected1 = G1Affine::from_compressed(&[
+            161, 109, 186, 0, 192, 221, 83, 87, 71, 31, 120, 201, 185, 35, 62, 239, 46, 120, 117,
+            150, 191, 227, 128, 161, 78, 201, 207, 167, 86, 181, 229, 115, 2, 6, 178, 16, 251, 118,
+            219, 115, 184, 96, 2, 10, 31, 63, 150, 70,
+        ])
+        .unwrap()
+        .into();
+
+        let msg2 = "bar";
+        let expected2 = G1Affine::from_compressed(&[
+            135, 102, 204, 42, 221, 49, 209, 192, 250, 87, 59, 255, 197, 93, 37, 113, 38, 2, 154,
+            233, 68, 234, 206, 182, 121, 212, 166, 210, 74, 155, 190, 33, 203, 237, 176, 60, 249,
+            241, 53, 170, 18, 168, 49, 35, 1, 151, 205, 174,
+        ])
+        .unwrap()
+        .into();
+        let msg3 = [
+            33, 135, 76, 234, 71, 35, 247, 216, 39, 242, 42, 88, 152, 29, 74, 135, 9, 29, 216, 123,
+            250, 87, 108, 29, 245, 126, 109, 102, 84, 71, 158, 224, 145, 243, 49, 121, 244, 27,
+            115, 121, 25, 66, 216, 67, 97, 101, 140, 160, 77, 239, 114, 215, 152, 48, 15, 231, 101,
+            60, 42, 92, 128, 131, 161, 43,
+        ];
+        let expected3 = G1Affine::from_compressed(&[
+            184, 200, 211, 115, 47, 45, 39, 185, 105, 9, 222, 247, 132, 241, 121, 130, 238, 224,
+            155, 109, 105, 201, 137, 154, 132, 149, 214, 233, 136, 69, 77, 132, 174, 30, 46, 123,
+            20, 92, 219, 18, 45, 29, 208, 127, 158, 145, 130, 41,
+        ])
+        .unwrap()
+        .into();
+
+        assert_eq!(hash_g1(msg1), expected1);
+        assert_eq!(hash_g1(msg2), expected2);
+        assert_eq!(hash_g1(msg3), expected3);
+    }
 }
@@ -2,7 +2,9 @@
 // SPDX-License-Identifier: Apache-2.0

 use crate::AckKey;
-use nym_crypto::symmetric::stream_cipher::{self, encrypt, iv_from_slice, random_iv, IvSizeUser};
+use nym_crypto::symmetric::stream_cipher::{
+    self, encrypt, random_iv, try_iv_from_slice, IvSizeUser,
+};
 use nym_sphinx_params::{AckEncryptionAlgorithm, SerializedFragmentIdentifier, FRAG_ID_LEN};
 use rand::{CryptoRng, RngCore};

@@ -25,7 +27,11 @@ pub fn recover_identifier(
    iv_id_ciphertext: &[u8],
 ) -> Option<SerializedFragmentIdentifier> {
    let iv_size = AckEncryptionAlgorithm::iv_size();
-    let iv = iv_from_slice::<AckEncryptionAlgorithm>(&iv_id_ciphertext[..iv_size]);
+    if iv_id_ciphertext.len() < FRAG_ID_LEN + iv_size {
+        return None;
+    }
+
+    let iv = try_iv_from_slice::<AckEncryptionAlgorithm>(&iv_id_ciphertext[..iv_size])?;

    let id = stream_cipher::decrypt::<AckEncryptionAlgorithm>(
        key.inner(),
@@ -161,6 +161,12 @@ impl From<NymNodeRoutingAddress> for SocketAddr {
    }
 }

+impl AsRef<SocketAddr> for NymNodeRoutingAddress {
+    fn as_ref(&self) -> &SocketAddr {
+        &self.0
+    }
+}
+
 impl TryInto<NodeAddressBytes> for NymNodeRoutingAddress {
    type Error = NymNodeRoutingAddressError;

@@ -30,7 +30,6 @@ pub use sphinx_packet::{
    route::{Destination, DestinationAddressBytes, Node, NodeAddressBytes, SURBIdentifier},
    surb::{SURBMaterial, SURB},
    version::Version,
-    version::UPDATED_LEGACY_VERSION,
    Error as SphinxError, ProcessedPacket, ProcessedPacketData,
 };

@@ -91,12 +90,8 @@ impl NymPacket {
        destination: &Destination,
        delays: &[Delay],
    ) -> Result<NymPacket, NymPacketError> {
-        // FIXME:
-        // for now explicitly use the legacy version until sufficient number of nodes
-        // understand both variants
        Ok(NymPacket::Sphinx(
            SphinxPacketBuilder::new()
-                .with_version(UPDATED_LEGACY_VERSION)
                .with_payload_size(size)
                .build_packet(message, route, destination, delays)?,
        ))
@@ -182,9 +182,11 @@ impl BlockProcessor {
            // the ones concerned with individual messages
            for (index, msg) in block_tx.tx.body.messages.iter().enumerate() {
                for msg_module in &mut self.msg_modules {
-                    msg_module
-                        .handle_msg(index, msg, &block_tx, &mut tx)
-                        .await?
+                    if msg.type_url == msg_module.type_url() {
+                        msg_module
+                            .handle_msg(index, msg, &block_tx, &mut tx)
+                            .await?
+                    }
                }
            }
        }
@@ -83,6 +83,15 @@ pub enum ScraperError {
        source: cosmrs::ErrorReport,
    },

+    #[error("could not parse msg in tx {hash} at index {index} into {type_url}: {source}")]
+    MsgParseFailure {
+        hash: Hash,
+        index: usize,
+        type_url: String,
+        #[source]
+        source: cosmrs::ErrorReport,
+    },
+
    #[error("received an invalid chain subscription event of kind {kind} while we were waiting for new block data (query: '{query}')")]
    InvalidSubscriptionEvent { query: String, kind: String },

@@ -9,6 +9,8 @@ use cosmrs::Any;

 #[async_trait]
 pub trait MsgModule {
+    fn type_url(&self) -> String;
+
    async fn handle_msg(
        &mut self,
        index: usize,
@@ -9,3 +9,4 @@ repository = { workspace = true }

 [dependencies]
 pem = { workspace = true }
+tracing = { workspace = true }
@@ -6,6 +6,7 @@ use pem::Pem;
 use std::fs::File;
 use std::io::{self, Read, Write};
 use std::path::{Path, PathBuf};
+use tracing::debug;

 pub mod traits;

@@ -46,6 +47,10 @@ where
    T: PemStorableKey,
    P: AsRef<Path>,
 {
+    debug!(
+        "attempting to load key with the following pem type: {}",
+        T::pem_type()
+    );
    let key_pem = read_pem_file(path)?;

    if T::pem_type() != key_pem.tag {
@@ -12,3 +12,7 @@ readme.workspace = true

 [dependencies]
 serde = { workspace = true, features = ["derive"] }
+thiserror.workspace = true
+
+[dev-dependencies]
+bincode.workspace = true
@@ -1,8 +1,16 @@
 // Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

+use std::fmt;
+
 use serde::{Deserialize, Serialize};

+#[derive(thiserror::Error, Debug)]
+pub enum ProtocolError {
+    #[error("invalid service provider type: {0}")]
+    InvalidServiceProviderType(u8),
+}
+
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
 #[repr(u8)]
 pub enum ServiceProviderType {
@@ -11,8 +19,103 @@ pub enum ServiceProviderType {
    Authenticator = 2,
 }

+impl fmt::Display for ServiceProviderType {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::NetworkRequester => write!(f, "NetworkRequester"),
+            Self::IpPacketRouter => write!(f, "IpPacketRouter"),
+            Self::Authenticator => write!(f, "Authenticator"),
+        }
+    }
+}
+
+impl TryFrom<u8> for ServiceProviderType {
+    type Error = ProtocolError;
+
+    fn try_from(value: u8) -> Result<Self, Self::Error> {
+        match value {
+            0 => Ok(Self::NetworkRequester),
+            1 => Ok(Self::IpPacketRouter),
+            2 => Ok(Self::Authenticator),
+            _ => Err(ProtocolError::InvalidServiceProviderType(value)),
+        }
+    }
+}
+
 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 pub struct Protocol {
    pub version: u8,
    pub service_provider_type: ServiceProviderType,
 }
+
+impl TryFrom<&[u8; 2]> for Protocol {
+    type Error = ProtocolError;
+
+    fn try_from(bytes: &[u8; 2]) -> Result<Self, Self::Error> {
+        let version = bytes[0];
+        let service_provider_type = ServiceProviderType::try_from(bytes[1])
+            .map_err(|_| ProtocolError::InvalidServiceProviderType(bytes[1]))?;
+
+        Ok(Self {
+            version,
+            service_provider_type,
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use bincode::Options;
+
+    fn make_bincode_serializer() -> impl bincode::Options {
+        bincode::DefaultOptions::new()
+            .with_big_endian()
+            .with_varint_encoding()
+    }
+
+    #[test]
+    fn protocol_serialization() {
+        let protocol = Protocol {
+            version: 4,
+            service_provider_type: ServiceProviderType::NetworkRequester,
+        };
+
+        let serialized = make_bincode_serializer().serialize(&protocol).unwrap();
+        let deserialized: Protocol = make_bincode_serializer().deserialize(&serialized).unwrap();
+
+        assert_eq!(protocol, deserialized);
+    }
+
+    #[test]
+    fn compact_serialization() {
+        let protocol = Protocol {
+            version: 4,
+            service_provider_type: ServiceProviderType::NetworkRequester,
+        };
+
+        let serialized = make_bincode_serializer().serialize(&protocol).unwrap();
+        assert_eq!(serialized.len(), 2);
+    }
+
+    #[test]
+    fn protocol_deserialization() {
+        let bytes = [4, ServiceProviderType::NetworkRequester as u8];
+        let deserialized = Protocol::try_from(&bytes).unwrap();
+
+        let expected = Protocol {
+            version: 4,
+            service_provider_type: ServiceProviderType::NetworkRequester,
+        };
+
+        assert_eq!(expected, deserialized);
+    }
+
+    #[test]
+    fn invalid_protocol_deserialization() {
+        let bytes = [4, 3];
+        let deserialized = Protocol::try_from(&bytes);
+
+        assert!(deserialized.is_err());
+    }
+}
@@ -103,4 +103,8 @@ impl LaneQueueLengthsInner {
    {
        self.map.entry(*lane).and_modify(f);
    }
+
+    pub fn total(&self) -> usize {
+        self.map.values().sum()
+    }
 }
@@ -17,6 +17,9 @@ rand = { workspace = true }
 reqwest = { workspace = true, features = ["json"] }
 serde = { workspace = true, features = ["derive"] }
 thiserror = { workspace = true }
+time = { workspace = true }
+tokio = { workspace = true, features = ["macros", "sync"] }
+

 # 'serde' feature
 serde_json = { workspace = true, optional = true }
@@ -35,7 +38,9 @@ nym-sphinx-types = { path = "../nymsphinx/types", features = [
    "outfox",
 ] }
 nym-sphinx-routing = { path = "../nymsphinx/routing" }
-
+nym-client-core-config-types = { path = "../client-core/config-types", features = [
+    "disk-persistence",
+] }

 # I'm not sure how to feel about pulling in this dependency here...
 nym-api-requests = { path = "../../nym-api/nym-api-requests" }
@@ -45,8 +50,8 @@ nym-api-requests = { path = "../../nym-api/nym-api-requests" }
 wasm-utils = { path = "../wasm/utils", default-features = false, optional = true }

 [features]
-default = ["provider-trait"]
-provider-trait = ["async-trait"]
+default = ["providers"]
+providers = ["async-trait"]
 wasm-serde-types = ["tsify", "wasm-bindgen", "wasm-utils"]
 persistence = ["serde_json"]
 outfox = []
@@ -23,13 +23,13 @@ pub mod error;
 pub mod node;
 pub mod rewarded_set;

-#[cfg(feature = "provider-trait")]
-pub mod provider_trait;
 #[cfg(feature = "wasm-serde-types")]
 pub mod wasm_helpers;

-#[cfg(feature = "provider-trait")]
-pub use provider_trait::{HardcodedTopologyProvider, TopologyProvider};
+#[cfg(feature = "providers")]
+pub mod providers;
+#[cfg(feature = "providers")]
+pub use providers::TopologyProvider;

 #[deprecated]
 #[derive(Debug, Clone)]
@@ -91,18 +91,6 @@ mod deprecated_network_address_impls {

 pub type MixLayer = u8;

-#[derive(Clone, Debug, Default, Serialize, Deserialize)]
-pub struct NymTopology {
-    // for the purposes of future VRF, everyone will need the same view of the network, regardless of performance filtering
-    // so we use the same 'master' rewarded set information for that
-    //
-    // how do we solve the problem of "we have to go through a node that we want to filter out?"
-    // ¯\_(ツ)_/¯ that's a future problem
-    rewarded_set: CachedEpochRewardedSet,
-
-    node_details: HashMap<NodeId, RoutingNode>,
-}
-
 #[derive(Clone, Debug, Default)]
 pub struct NymRouteProvider {
    pub topology: NymTopology,
@@ -189,6 +177,18 @@ impl NymRouteProvider {
    }
 }

+#[derive(Clone, Debug, Default, Serialize, Deserialize, PartialEq)]
+pub struct NymTopology {
+    // for the purposes of future VRF, everyone will need the same view of the network, regardless of performance filtering
+    // so we use the same 'master' rewarded set information for that
+    //
+    // how do we solve the problem of "we have to go through a node that we want to filter out?"
+    // ¯\_(ツ)_/¯ that's a future problem
+    rewarded_set: CachedEpochRewardedSet,
+
+    node_details: HashMap<NodeId, RoutingNode>,
+}
+
 impl NymTopology {
    pub fn new_empty(rewarded_set: impl Into<CachedEpochRewardedSet>) -> Self {
        NymTopology {
@@ -254,6 +254,15 @@ impl NymTopology {
        }
    }

+    pub fn with_additional_nodes<N>(mut self, nodes: impl Iterator<Item = N>) -> Self
+    where
+        N: TryInto<RoutingNode>,
+        <N as TryInto<RoutingNode>>::Error: Display,
+    {
+        self.add_additional_nodes(nodes);
+        self
+    }
+
    pub fn has_node_details(&self, node_id: NodeId) -> bool {
        self.node_details.contains_key(&node_id)
    }
@@ -537,4 +546,19 @@ impl NymTopology {
            .values()
            .filter(|n| self.rewarded_set.is_active_mixnode(&n.node_id))
    }
+
+    pub fn all_nodes(&self) -> impl Iterator<Item = &RoutingNode> {
+        self.node_details.values()
+    }
+
+    pub fn all_node_ids(&self) -> impl Iterator<Item = &NodeId> {
+        self.node_details.keys()
+    }
+
+    pub fn gateways(&self) -> impl Iterator<Item = &RoutingNode> {
+        self.node_details.values().filter(|n| {
+            self.rewarded_set.entry_gateways.contains(&n.node_id)
+                || self.rewarded_set.exit_gateways.contains(&n.node_id)
+        })
+    }
 }
@@ -11,6 +11,7 @@ use serde::{Deserialize, Serialize};
 use std::net::{IpAddr, SocketAddr};
 use thiserror::Error;

+pub use nym_mixnet_contract_common::reward_params::Performance;
 pub use nym_mixnet_contract_common::LegacyMixLayer;

 #[derive(Error, Debug)]
@@ -19,7 +20,7 @@ pub enum RoutingNodeError {
    NoIpAddressesProvided { node_id: NodeId, identity: String },
 }

-#[derive(Clone, Debug, Serialize, Deserialize)]
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 pub struct EntryDetails {
    // to allow client to choose ipv6 preference, if available
    pub ip_addresses: Vec<IpAddr>,
@@ -28,7 +29,7 @@ pub struct EntryDetails {
    pub clients_wss_port: Option<u16>,
 }

-#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq)]
 pub struct SupportedRoles {
    pub mixnode: bool,
    pub mixnet_entry: bool,
@@ -45,7 +46,7 @@ impl From<DeclaredRoles> for SupportedRoles {
    }
 }

-#[derive(Clone, Debug, Serialize, Deserialize)]
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 pub struct RoutingNode {
    pub node_id: NodeId,

@@ -56,6 +57,7 @@ pub struct RoutingNode {
    pub sphinx_key: x25519::PublicKey,

    pub supported_roles: SupportedRoles,
+    pub performance: Performance,
 }

 impl RoutingNode {
@@ -109,6 +111,12 @@ impl<'a> From<&'a RoutingNode> for SphinxNode {
    }
 }

+impl<'a> From<&'a RoutingNode> for RoutingNode {
+    fn from(node: &'a RoutingNode) -> Self {
+        node.clone()
+    }
+}
+
 impl<'a> TryFrom<&'a SkimmedNode> for RoutingNode {
    type Error = RoutingNodeError;

@@ -138,6 +146,7 @@ impl<'a> TryFrom<&'a SkimmedNode> for RoutingNode {
            identity_key: value.ed25519_identity_pubkey,
            sphinx_key: value.x25519_sphinx_pubkey,
            supported_roles: value.supported_roles.into(),
+            performance: value.performance,
        })
    }
 }
@@ -4,7 +4,9 @@
 use crate::NymTopology;
 pub use async_trait::async_trait;

-// hehe, wasm
+/// Cached Topology Provider built using efficient piecewise requests.
+pub mod piecewise;
+
 #[cfg(not(target_arch = "wasm32"))]
 #[async_trait]
 pub trait TopologyProvider: Send {
@@ -0,0 +1,482 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: GPL-3.0-only
+
+//!
+//!
+#![warn(missing_docs)]
+
+use crate::{EpochRewardedSet, NymTopology, RoutingNode, TopologyProvider};
+
+use async_trait::async_trait;
+use time::OffsetDateTime;
+use tokio::sync::Mutex;
+use tracing::{debug, warn};
+
+use std::{cmp::min, collections::HashSet, sync::Arc, time::Duration};
+
+/// Topology filtering and caching configuration
+#[derive(Debug)]
+pub struct Config {
+    /// Specifies a minimum performance of a mixnode that is used on route construction.
+    /// This setting is only applicable when `NymApi` topology is used.
+    pub min_mixnode_performance: u8,
+
+    /// Specifies a minimum performance of a gateway that is used on route construction.
+    /// This setting is only applicable when `NymApi` topology is used.
+    pub min_gateway_performance: u8,
+
+    /// Specifies whether this client should attempt to retrieve all available network nodes
+    /// as opposed to just active mixnodes/gateways.
+    pub use_extended_topology: bool,
+
+    /// Specifies whether this client should ignore the current epoch role of the target egress node
+    /// when constructing the final hop packets.
+    pub ignore_egress_epoch_role: bool,
+
+    /// Minimum duration during which querying the topology will NOT attempt to re-fetch data, and
+    /// will be served from cache.
+    pub cache_ttl: Duration,
+}
+
+impl Default for Config {
+    fn default() -> Self {
+        Self {
+            min_mixnode_performance: 50,
+            min_gateway_performance: 0,
+            use_extended_topology: false,
+            ignore_egress_epoch_role: true,
+            cache_ttl: Self::DEFAULT_TOPOLOGY_CACHE_TTL,
+        }
+    }
+}
+
+impl From<nym_client_core_config_types::Topology> for Config {
+    fn from(value: nym_client_core_config_types::Topology) -> Self {
+        Config {
+            min_mixnode_performance: value.minimum_mixnode_performance,
+            min_gateway_performance: value.minimum_gateway_performance,
+            use_extended_topology: value.use_extended_topology,
+            ignore_egress_epoch_role: value.ignore_egress_epoch_role,
+            cache_ttl: value.topology_refresh_rate,
+        }
+    }
+}
+
+impl Config {
+    /// Default duration during which the topology will be reproduced from cache.
+    pub const DEFAULT_TOPOLOGY_CACHE_TTL: Duration = Duration::from_secs(120);
+
+    // if we're using 'extended' topology, filter the nodes based on the lowest set performance
+    fn min_node_performance(&self) -> u8 {
+        min(self.min_mixnode_performance, self.min_gateway_performance)
+    }
+}
+
+/// Topology Provider build around a cached piecewise provider that uses the Nym API to
+/// fetch changes and node details.
+#[derive(Clone)]
+pub struct NymTopologyProvider<M: PiecewiseTopologyProvider> {
+    inner: Arc<Mutex<NymTopologyProviderInner<M>>>,
+}
+
+impl<M: PiecewiseTopologyProvider> NymTopologyProvider<M> {
+    /// Construct a new thread safe Cached topology provider
+    pub fn new(
+        manager: M,
+        config: Config,
+        initial_topology: Option<NymTopology>,
+    ) -> NymTopologyProvider<M> {
+        let inner = NymTopologyProviderInner::new(config, manager, initial_topology);
+
+        NymTopologyProvider {
+            inner: Arc::new(Mutex::new(inner)),
+        }
+    }
+
+    /// Bypass the caching for the topology and force a check for the latest updates next time the
+    /// topology is requested. This fn requires async to get lock in case other threads have access
+    /// to the cached topology state.
+    pub async fn force_refresh(&self) {
+        let mut guard = self.inner.lock().await;
+        guard.cached_at = OffsetDateTime::UNIX_EPOCH;
+    }
+
+    /// Remove all stored topology state. The next time the topology is requested this will force a
+    /// pull of all topology information. This fn requires async to get lock in case other threads
+    /// have access to the cached topology state.
+    ///
+    /// WARNING: This may be slow / require non-trivial bandwidth.
+    pub async fn force_clear(&self) {
+        let mut guard = self.inner.lock().await;
+        guard.cached = None;
+    }
+}
+
+#[cfg(not(target_arch = "wasm32"))]
+#[async_trait]
+impl<M: PiecewiseTopologyProvider> TopologyProvider for NymTopologyProvider<M> {
+    async fn get_new_topology(&mut self) -> Option<NymTopology> {
+        let mut guard = self.inner.lock().await;
+        // check the cache
+        if let Some(cached) = guard.get_current_compatible_topology().await {
+            return Some(cached);
+        }
+
+        // not cached, or cache expired. try update.
+        guard.update_cache().await;
+        guard.get_current_compatible_topology().await
+    }
+}
+
+#[cfg(target_arch = "wasm32")]
+#[async_trait(?Send)]
+impl<M: PiecewiseTopologyProvider> TopologyProvider for NymTopologyProvider<M> {
+    async fn get_new_topology(&mut self) -> Option<NymTopology> {
+        let mut guard = self.inner.lock().await;
+        // check the cache
+        if let Some(cached) = guard.get_current_compatible_topology().await {
+            return Some(cached);
+        }
+
+        // not cached, or cache expired. try update.
+        guard.update_cache().await;
+        guard.get_current_compatible_topology().await
+    }
+}
+
+struct NymTopologyProviderInner<M: PiecewiseTopologyProvider> {
+    config: Config,
+
+    cached: Option<NymTopology>,
+    cached_at: OffsetDateTime,
+
+    topology_manager: M,
+}
+
+impl<M: PiecewiseTopologyProvider> NymTopologyProviderInner<M> {
+    pub fn new(
+        config: impl Into<Config>,
+        manager: M,
+        initial_topology: Option<NymTopology>,
+    ) -> Self {
+        Self {
+            config: config.into(),
+            cached_at: OffsetDateTime::UNIX_EPOCH,
+            cached: initial_topology,
+            topology_manager: manager,
+        }
+    }
+
+    fn cached_topology(&self) -> Option<NymTopology> {
+        if let Some(cached_topology) = &self.cached {
+            if self.cached_at + self.config.cache_ttl > OffsetDateTime::now_utc() {
+                return Some(cached_topology.clone());
+            }
+        }
+
+        None
+    }
+
+    async fn update_cache(&mut self) {
+        if let Some(ref mut cached_topology) = self.cached {
+            // get layer assignment map
+            let response = self.topology_manager.get_layer_assignments().await;
+            if response.is_none() {
+                warn!("pulled layer assignments and got no response");
+                self.cached_at = OffsetDateTime::now_utc();
+                return;
+            }
+
+            let layer_assignments = response.unwrap();
+            // Check if we already know about the epoch
+            if cached_topology.rewarded_set.epoch_id == layer_assignments.epoch_id {
+                debug!("pulled layer assignments, epoch already known");
+                self.cached_at = OffsetDateTime::now_utc();
+                return;
+            }
+
+            cached_topology.rewarded_set = layer_assignments.into();
+
+            // get the set of node IDs
+            let new_id_set = cached_topology.rewarded_set.all_ids();
+            let known_id_set = HashSet::<u32>::from_iter(cached_topology.all_node_ids().copied());
+            let unknown_node_ids: Vec<_> = new_id_set.difference(&known_id_set).copied().collect();
+
+            // Pull node descriptors for unknown IDs
+            let response = self
+                .topology_manager
+                .get_descriptor_batch(&unknown_node_ids[..])
+                .await;
+
+            // Add the new nodes to our cached topology
+            if let Some(new_descriptors) = response {
+                cached_topology.add_routing_nodes(new_descriptors);
+            }
+
+            // double check that we have the expected nodes
+            let known_id_set = HashSet::<u32>::from_iter(cached_topology.all_node_ids().copied());
+            let unknown_node_ids: Vec<_> = new_id_set.difference(&known_id_set).collect();
+            if !unknown_node_ids.is_empty() {
+                warn!(
+                    "still missing descriptors for nodes in the assigned set: {:?}",
+                    unknown_node_ids
+                );
+            }
+        } else {
+            self.cached = self.topology_manager.get_full_topology().await;
+        }
+
+        self.cached_at = OffsetDateTime::now_utc();
+    }
+
+    /// Gets the current topology state using `Self::cached_topology` and then applies any filters
+    /// defined in the provided Config.
+    async fn get_current_compatible_topology(&mut self) -> Option<NymTopology> {
+        let full_topology = self.cached_topology()?;
+
+        let mut topology = NymTopology::new_empty(full_topology.rewarded_set().clone());
+
+        if self.config.use_extended_topology {
+            topology.add_additional_nodes(full_topology.all_nodes().filter(|n| {
+                n.performance.round_to_integer() >= self.config.min_node_performance()
+            }));
+
+            return Some(full_topology);
+        }
+
+        topology.add_additional_nodes(
+            full_topology.mixnodes().filter(|m| {
+                m.performance.round_to_integer() >= self.config.min_mixnode_performance
+            }),
+        );
+        topology.add_additional_nodes(
+            full_topology.gateways().filter(|m| {
+                m.performance.round_to_integer() >= self.config.min_gateway_performance
+            }),
+        );
+
+        Some(topology)
+    }
+}
+
+#[cfg(not(target_arch = "wasm32"))]
+#[async_trait]
+impl<P: PiecewiseTopologyProvider> TopologyProvider for NymTopologyProviderInner<P> {
+    async fn get_new_topology(&mut self) -> Option<NymTopology> {
+        self.get_current_compatible_topology().await
+    }
+}
+
+#[cfg(target_arch = "wasm32")]
+#[async_trait(?Send)]
+impl<P: PiecewiseTopologyProvider> TopologyProvider for NymTopologyProviderInner<P> {
+    async fn get_new_topology(&mut self) -> Option<NymTopology> {
+        self.get_current_compatible_topology().await
+    }
+}
+
+#[cfg(not(target_arch = "wasm32"))]
+/// Trait allowing construction and upkeep of a
+#[async_trait]
+pub trait PiecewiseTopologyProvider: Send {
+    /// Pull a copy of the full topology.
+    ///
+    /// This is intended to be used sparingly as repeated usage could result in fetching duplicate
+    /// information more often than necessary.
+    async fn get_full_topology(&mut self) -> Option<NymTopology>;
+
+    /// Fetch a node descriptors for the set of provided IDs if available.
+    async fn get_descriptor_batch(&mut self, ids: &[u32]) -> Option<Vec<RoutingNode>>;
+
+    /// Fetch the latest mapping of node IDs to Nym Network layer.
+    async fn get_layer_assignments(&mut self) -> Option<EpochRewardedSet>;
+}
+
+#[cfg(target_arch = "wasm32")]
+/// Trait allowing construction and upkeep of a
+#[async_trait(?Send)]
+pub trait PiecewiseTopologyProvider: Send {
+    /// Pull a copy of the full topology.
+    ///
+    /// This is intended to be used sparingly as repeated usage could result in fetching duplicate
+    /// information more often than necessary.
+    async fn get_full_topology(&mut self) -> Option<NymTopology>;
+
+    /// Fetch a node descriptors for the set of provided IDs if available.
+    async fn get_descriptor_batch(&mut self, ids: &[u32]) -> Option<Vec<RoutingNode>>;
+
+    /// Fetch the latest mapping of node IDs to Nym Network layer.
+    async fn get_layer_assignments(&mut self) -> Option<EpochRewardedSet>;
+}
+
+#[cfg(test)]
+#[cfg(not(target_arch = "wasm32"))]
+mod test {
+    use super::*;
+    use crate::SupportedRoles;
+    use nym_crypto::asymmetric::encryption::PublicKey as SphinxPubkey;
+    use nym_crypto::asymmetric::identity::PublicKey as IdentityPubkey;
+    use nym_mixnet_contract_common::Percent;
+
+    #[derive(Clone)]
+    struct PassthroughPiecewiseTopologyProvider {
+        topo: NymTopology,
+    }
+
+    #[async_trait]
+    impl PiecewiseTopologyProvider for PassthroughPiecewiseTopologyProvider {
+        async fn get_full_topology(&mut self) -> Option<NymTopology> {
+            Some(self.topo.clone())
+        }
+
+        async fn get_descriptor_batch(&mut self, ids: &[u32]) -> Option<Vec<RoutingNode>> {
+            let mut nodes = Vec::new();
+            ids.iter().for_each(|id| {
+                if let Some(node) = self.topo.node_details.get(id) {
+                    nodes.push(node.clone());
+                }
+            });
+
+            Some(nodes)
+        }
+
+        async fn get_layer_assignments(&mut self) -> Option<EpochRewardedSet> {
+            return Some(self.topo.rewarded_set.clone().into());
+        }
+    }
+
+    #[tokio::test]
+    async fn test_topology_provider() -> Result<(), Box<dyn std::error::Error>> {
+        let mut topo_mgr = PassthroughPiecewiseTopologyProvider {
+            topo: NymTopology::default(),
+        };
+
+        let mut topo_provider =
+            NymTopologyProviderInner::new(Config::default(), topo_mgr.clone(), None);
+
+        // No initial topology was provided, No update has run yet, None should be returned
+        assert_eq!(topo_provider.cached_topology(), None);
+
+        // force an update of the cached topology
+        topo_provider.update_cache().await;
+
+        let topo = topo_provider.cached_topology();
+        assert!(topo.is_some());
+        let topo = topo.unwrap();
+        assert!(topo.is_empty());
+
+        // create a change in the manager to make sure it is propogated to the provider cache on update
+        topo_mgr.topo.rewarded_set.epoch_id += 1;
+        topo_mgr.topo.rewarded_set.entry_gateways = HashSet::from([123]);
+        assert_eq!(topo_mgr.topo.node_details.insert(123, fake_node(123)), None);
+        topo_provider.topology_manager = topo_mgr.clone();
+
+        // force an update of the cached topology
+        topo_provider.update_cache().await;
+
+        let topo = topo_provider.cached_topology();
+        assert!(topo.is_some());
+        let topo1 = topo.unwrap();
+        assert!(!topo1.is_empty());
+        assert!(topo1.node_details.contains_key(&123));
+
+        // try forcing an update even though the epoch has not changed. Should result in no change
+        topo_provider.update_cache().await;
+        let topo2 = topo_provider.cached_topology().unwrap();
+        assert_eq!(topo1, topo2);
+
+        // Add a node without a descriptor to make sure warning is printed.
+        topo_mgr.topo.rewarded_set.epoch_id += 1;
+        topo_mgr.topo.rewarded_set.entry_gateways = HashSet::from([123, 456]);
+        topo_provider.topology_manager = topo_mgr.clone();
+
+        // try forcing an update even though the epoch has not changed. Should result in no change
+        topo_provider.update_cache().await;
+        let _ = topo_provider.cached_topology().unwrap();
+
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn test_topology_provider_by_trait() -> Result<(), Box<dyn std::error::Error>> {
+        let mut topo_mgr = PassthroughPiecewiseTopologyProvider {
+            topo: NymTopology::default(),
+        };
+
+        let mut topo_provider = NymTopologyProvider::new(topo_mgr.clone(), Config::default(), None);
+
+        // No initial topology was provided, the NymTopologyProvider should do an update from the
+        // manager to build its cache. This should be our empty topology initialized in the manage
+        // above
+        let maybe_topo = topo_provider.get_new_topology().await;
+        assert!(maybe_topo.is_some());
+        let topo1 = maybe_topo.unwrap();
+        assert!(topo1.is_empty());
+
+        // Try pulling again, should give response from cache because we are under ttl
+        let maybe_topo = topo_provider.get_new_topology().await;
+        assert!(maybe_topo.is_some());
+        let topo2 = maybe_topo.unwrap();
+        assert_eq!(topo1, topo2);
+
+        // create a change in the manager
+        topo_mgr.topo.rewarded_set.epoch_id += 1;
+        topo_mgr.topo.rewarded_set.entry_gateways = HashSet::from([123]);
+        assert_eq!(topo_mgr.topo.node_details.insert(123, fake_node(123)), None);
+        {
+            let mut guard = topo_provider.inner.lock().await;
+            guard.topology_manager = topo_mgr.clone();
+            drop(guard)
+        }
+
+        // The NymTopologyProvider should still serve from cache because we haven't crossed ttl
+        // despite updates being available in the manager
+        let maybe_topo = topo_provider.get_new_topology().await;
+        assert!(maybe_topo.is_some());
+        let topo3 = maybe_topo.unwrap();
+        assert_eq!(topo2, topo3);
+
+        // force ttl timeout should allow refresh that includes latest changes from manager
+        topo_provider.force_refresh().await;
+        let maybe_topo = topo_provider.get_new_topology().await;
+        assert!(maybe_topo.is_some());
+        let topo4 = maybe_topo.unwrap();
+        assert_ne!(topo3, topo4);
+        assert!(topo4.node_details.contains_key(&123));
+
+        // create another change in the manager
+        topo_mgr.topo.rewarded_set.epoch_id += 1;
+        topo_mgr.topo.rewarded_set.entry_gateways = HashSet::from([123, 456]);
+        assert_eq!(topo_mgr.topo.node_details.insert(456, fake_node(456)), None);
+        {
+            let mut guard = topo_provider.inner.lock().await;
+            guard.topology_manager = topo_mgr.clone();
+            drop(guard)
+        }
+
+        // force clear cache should also pull latest full topology
+        topo_provider.force_clear().await;
+        let maybe_topo = topo_provider.get_new_topology().await;
+        assert!(maybe_topo.is_some());
+        let topo5 = maybe_topo.unwrap();
+        assert!(topo5.node_details.contains_key(&456));
+
+        Ok(())
+    }
+
+    fn fake_node(node_id: u32) -> RoutingNode {
+        RoutingNode {
+            node_id,
+            mix_host: "127.0.0.1:2345".parse().unwrap(),
+            entry: None,
+            identity_key: IdentityPubkey::from_bytes(&[0u8; 32][..]).unwrap(),
+            sphinx_key: SphinxPubkey::from_bytes(&[0u8; 32][..]).unwrap(),
+            supported_roles: SupportedRoles {
+                mixnode: true,
+                mixnet_entry: true,
+                mixnet_exit: true,
+            },
+            performance: Percent::hundred(),
+        }
+    }
+}
@@ -6,7 +6,7 @@ use nym_mixnet_contract_common::{EpochId, EpochRewardedSet, NodeId, RewardedSet}
 use serde::{Deserialize, Serialize};
 use std::collections::HashSet;

-#[derive(Clone, Debug, Default, Serialize, Deserialize)]
+#[derive(Clone, Debug, Default, Serialize, Deserialize, PartialEq)]
 pub struct CachedEpochRewardedSet {
    pub epoch_id: EpochId,

@@ -119,4 +119,22 @@ impl CachedEpochRewardedSet {
        mixnodes.extend(&self.layer3);
        mixnodes
    }
+
+    pub fn all_ids(&self) -> HashSet<NodeId> {
+        let mut mixnodes = HashSet::with_capacity(
+            self.entry_gateways.len()
+                + self.exit_gateways.len()
+                + self.layer1.len()
+                + self.layer2.len()
+                + self.layer3.len()
+                + self.standby.len(),
+        );
+        mixnodes.extend(&self.entry_gateways);
+        mixnodes.extend(&self.exit_gateways);
+        mixnodes.extend(&self.layer1);
+        mixnodes.extend(&self.layer2);
+        mixnodes.extend(&self.layer3);
+        mixnodes.extend(&self.standby);
+        mixnodes
+    }
 }
@@ -6,6 +6,7 @@

 use crate::node::{EntryDetails, RoutingNode, RoutingNodeError, SupportedRoles};
 use crate::{CachedEpochRewardedSet, NymTopology};
+use nym_mixnet_contract_common::reward_params::Performance;
 use serde::{Deserialize, Serialize};
 use std::collections::HashMap;
 use std::net::SocketAddr;
@@ -105,6 +106,8 @@ impl TryFrom<WasmFriendlyRoutingNode> for RoutingNode {
                }
            })?,
            supported_roles: value.supported_roles,
+
+            performance: Performance::hundred(),
        })
    }
 }
@@ -462,6 +462,10 @@ pub struct ReplySurbsWasm {
    /// Defines the maximum number of reply surbs the client wants to keep in its storage at any times.
    pub maximum_reply_surb_storage_threshold: usize,

+    /// Defines the soft threshold ontop of the minimum reply surb storage threshold for when the client
+    /// should proactively request additional reply surbs.
+    pub minimum_reply_surb_threshold_buffer: usize,
+
    /// Defines the minimum number of reply surbs the client would request.
    pub minimum_reply_surb_request_size: u32,

@@ -490,6 +494,9 @@ pub struct ReplySurbsWasm {
    /// Defines how many mix nodes the reply surb should go through.
    /// If not set, the default value is going to be used.
    pub surb_mix_hops: Option<u8>,
+
+    /// Specifies if we should reset all the sender tags on startup
+    pub fresh_sender_tags: bool,
 }

 impl Default for ReplySurbsWasm {
@@ -503,6 +510,7 @@ impl From<ReplySurbsWasm> for ConfigReplySurbs {
        ConfigReplySurbs {
            minimum_reply_surb_storage_threshold: reply_surbs.minimum_reply_surb_storage_threshold,
            maximum_reply_surb_storage_threshold: reply_surbs.maximum_reply_surb_storage_threshold,
+            minimum_reply_surb_threshold_buffer: reply_surbs.minimum_reply_surb_threshold_buffer,
            minimum_reply_surb_request_size: reply_surbs.minimum_reply_surb_request_size,
            maximum_reply_surb_request_size: reply_surbs.maximum_reply_surb_request_size,
            maximum_allowed_reply_surb_request_size: reply_surbs
@@ -520,6 +528,7 @@ impl From<ReplySurbsWasm> for ConfigReplySurbs {
                reply_surbs.maximum_reply_key_age_ms as u64,
            ),
            surb_mix_hops: reply_surbs.surb_mix_hops,
+            fresh_sender_tags: reply_surbs.fresh_sender_tags,
        }
    }
 }
@@ -529,6 +538,7 @@ impl From<ConfigReplySurbs> for ReplySurbsWasm {
        ReplySurbsWasm {
            minimum_reply_surb_storage_threshold: reply_surbs.minimum_reply_surb_storage_threshold,
            maximum_reply_surb_storage_threshold: reply_surbs.maximum_reply_surb_storage_threshold,
+            minimum_reply_surb_threshold_buffer: reply_surbs.minimum_reply_surb_threshold_buffer,
            minimum_reply_surb_request_size: reply_surbs.minimum_reply_surb_request_size,
            maximum_reply_surb_request_size: reply_surbs.maximum_reply_surb_request_size,
            maximum_allowed_reply_surb_request_size: reply_surbs
@@ -542,6 +552,7 @@ impl From<ConfigReplySurbs> for ReplySurbsWasm {
            maximum_reply_surb_age_ms: reply_surbs.maximum_reply_surb_age.as_millis() as u32,
            maximum_reply_key_age_ms: reply_surbs.maximum_reply_key_age.as_millis() as u32,
            surb_mix_hops: reply_surbs.surb_mix_hops,
+            fresh_sender_tags: reply_surbs.fresh_sender_tags,
        }
    }
 }
@@ -339,6 +339,11 @@ pub struct ReplySurbsWasmOverride {
    #[tsify(optional)]
    pub maximum_reply_surb_storage_threshold: Option<usize>,

+    /// Defines the soft threshold ontop of the minimum reply surb storage threshold for when the client
+    /// should proactively request additional reply surbs.
+    #[tsify(optional)]
+    pub minimum_reply_surb_threshold_buffer: Option<usize>,
+
    /// Defines the minimum number of reply surbs the client would request.
    #[tsify(optional)]
    pub minimum_reply_surb_request_size: Option<u32>,
@@ -373,6 +378,9 @@ pub struct ReplySurbsWasmOverride {

    #[tsify(optional)]
    pub surb_mix_hops: Option<u8>,
+
+    /// Specifies if we should reset all the sender tags on startup
+    pub fresh_sender_tags: bool,
 }

 impl From<ReplySurbsWasmOverride> for ReplySurbsWasm {
@@ -386,6 +394,9 @@ impl From<ReplySurbsWasmOverride> for ReplySurbsWasm {
            maximum_reply_surb_storage_threshold: value
                .maximum_reply_surb_storage_threshold
                .unwrap_or(def.maximum_reply_surb_storage_threshold),
+            minimum_reply_surb_threshold_buffer: value
+                .minimum_reply_surb_threshold_buffer
+                .unwrap_or(def.minimum_reply_surb_threshold_buffer),
            minimum_reply_surb_request_size: value
                .minimum_reply_surb_request_size
                .unwrap_or(def.minimum_reply_surb_request_size),
@@ -408,6 +419,7 @@ impl From<ReplySurbsWasmOverride> for ReplySurbsWasm {
                .maximum_reply_key_age_ms
                .unwrap_or(def.maximum_reply_key_age_ms),
            surb_mix_hops: value.surb_mix_hops,
+            fresh_sender_tags: value.fresh_sender_tags,
        }
    }
 }
@@ -28,7 +28,9 @@ pub use nym_sphinx::{
 };
 pub use nym_statistics_common::clients::ClientStatsSender;
 pub use nym_task;
-pub use nym_topology::{HardcodedTopologyProvider, MixLayer, NymTopology, TopologyProvider};
+pub use nym_topology::{
+    providers::HardcodedTopologyProvider, MixLayer, NymTopology, TopologyProvider,
+};
 pub use nym_validator_client::nym_api::Client as ApiClient;
 pub use nym_validator_client::{DirectSigningReqwestRpcNyxdClient, QueryReqwestRpcNyxdClient};
 // TODO: that's a very nasty import path. it should come from contracts instead!
@@ -1185,6 +1185,7 @@ name = "nym-pemstore"
 version = "0.3.0"
 dependencies = [
 "pem",
+ "tracing",
 ]

 [[package]]
@@ -1251,6 +1252,12 @@ dependencies = [
 "regex",
 ]

+[[package]]
+name = "pin-project-lite"
+version = "0.2.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3b3cff922bd51709b605d9ead9aa71031d81447142d828eb4a6eba76fe619f9b"
+
 [[package]]
 name = "pkcs8"
 version = "0.9.0"
@@ -1470,9 +1477,9 @@ checksum = "6ea1a2d0a644769cc99faa24c3ad26b379b786fe7c36fd3c546254801650e6dd"

 [[package]]
 name = "schemars"
-version = "0.8.21"
+version = "0.8.22"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "09c024468a378b7e36765cd36702b7a90cc3cba11654f6685c8f233408e89e92"
+checksum = "3fbf2ae1b8bc8e02df939598064d22402220cd5bbcca1c76f7d6a310974d5615"
 dependencies = [
 "dyn-clone",
 "schemars_derive",
@@ -1482,9 +1489,9 @@ dependencies = [

 [[package]]
 name = "schemars_derive"
-version = "0.8.21"
+version = "0.8.22"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b1eee588578aff73f856ab961cd2f79e36bc45d7ded33a7562adba4667aecc0e"
+checksum = "32e265784ad618884abaea0600a9adf15393368d840e0222d101a072f3f7534d"
 dependencies = [
 "proc-macro2",
 "quote",
@@ -1522,18 +1529,18 @@ dependencies = [

 [[package]]
 name = "semver"
-version = "1.0.25"
+version = "1.0.26"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f79dfe2d285b0488816f30e700a7438c5a73d816b5b7d3ac72fbc48b0d185e03"
+checksum = "56e6fa9c48d24d85fb3de5ad847117517440f6beceb7798af16b4a87d616b8d0"
 dependencies = [
 "serde",
 ]

 [[package]]
 name = "serde"
-version = "1.0.217"
+version = "1.0.219"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "02fc4265df13d6fa1d00ecff087228cc0a2b5f3c0e87e258d8b94a156e984c70"
+checksum = "5f0e2c6ed6606019b4e29e69dbaba95b11854410e5347d525002456dbbb786b6"
 dependencies = [
 "serde_derive",
 ]
@@ -1558,9 +1565,9 @@ dependencies = [

 [[package]]
 name = "serde_derive"
-version = "1.0.217"
+version = "1.0.219"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5a9bf7cf98d04a2b28aead066b7496853d4779c9cc183c440dbac457641e19a0"
+checksum = "5b0276cf7f2c73365f7157c8123c21cd9a50fbbd844757af28ca1f5925fc2a00"
 dependencies = [
 "proc-macro2",
 "quote",
@@ -1777,9 +1784,9 @@ dependencies = [

 [[package]]
 name = "time"
-version = "0.3.37"
+version = "0.3.39"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "35e7868883861bd0e56d9ac6efcaaca0d6d5d82a2a7ec8209ff492c07cf37b21"
+checksum = "dad298b01a40a23aac4580b67e3dbedb7cc8402f3592d7f49469de2ea4aecdd8"
 dependencies = [
 "deranged",
 "itoa",
@@ -1794,15 +1801,15 @@ dependencies = [

 [[package]]
 name = "time-core"
-version = "0.1.2"
+version = "0.1.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ef927ca75afb808a4d64dd374f00a2adf8d0fcff8e7b184af886c3c87ec4a3f3"
+checksum = "765c97a5b985b7c11d7bc27fa927dc4fe6af3a6dfb021d28deb60d3bf51e76ef"

 [[package]]
 name = "time-macros"
-version = "0.2.19"
+version = "0.2.20"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2834e6017e3e5e4b9834939793b282bc03b37a3336245fa820e35e233e2a85de"
+checksum = "e8093bc3e81c3bc5f7879de09619d06c9a5a5e45ca44dfeeb7225bae38005c5c"
 dependencies = [
 "num-conv",
 "time-core",
@@ -1840,6 +1847,37 @@ dependencies = [
 "winnow",
 ]

+[[package]]
+name = "tracing"
+version = "0.1.41"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "784e0ac535deb450455cbfa28a6f0df145ea1bb7ae51b821cf5e7927fdcfbdd0"
+dependencies = [
+ "pin-project-lite",
+ "tracing-attributes",
+ "tracing-core",
+]
+
+[[package]]
+name = "tracing-attributes"
+version = "0.1.28"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "395ae124c09f9e6918a2310af6038fba074bcf474ac352496d5910dd59a2226d"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.98",
+]
+
+[[package]]
+name = "tracing-core"
+version = "0.1.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e672c95779cf947c5311f83787af4fa8fffd12fb27e4993211a84bdfd9610f9c"
+dependencies = [
+ "once_cell",
+]
+
 [[package]]
 name = "typenum"
 version = "1.18.0"
@@ -122,6 +122,7 @@ exceptions = [
    { allow = ["GPL-3.0"], crate = "nym-network-requester" },
    { allow = ["GPL-3.0"], crate = "nym-node" },
    { allow = ["GPL-3.0"], crate = "nym-validator-rewarder" },
+    { allow = ["GPL-3.0"], crate = "nym-ip-packet-router" },
 ]

 # Some crates don't have (easily) machine readable licensing information,
@@ -7,4 +7,6 @@ package-lock.json

 # local env files
 .env*.local
-.env
+.env
+
+scratch.md
@@ -0,0 +1,10 @@
+- Run synchronization against [pool.ntp.org](https://www.ntppool.org/en/):
+```bash
+ntpdate -q pool.ntp.org
+```
+- Enable `ntp` service, start and review the status:
+```bash
+systemctl enable --now ntp
+service ntp start
+service ntp status
+```
@@ -1 +1 @@
-807_251_217
+808_623_916
@@ -1 +1 @@
-0.64%
+0.68%
--- a/Show More
+++ b/Show More
@@ -1 +1 @@
 .64%
 .68%