update changelog

[bugfix] Tunnel not waiting on MixnetClient to shut down cleanly (#6225 )
* return the handlefor a clean shutdown * cargo lock
2025-11-25 15:16:42 +01:00 · 2025-11-21 16:39:12 +01:00 · 2025-11-14 11:23:47 +01:00 · 2025-11-14 11:21:13 +01:00 · 2025-11-14 10:36:23 +01:00 · 2025-11-14 10:36:11 +01:00
213 changed files with 6544 additions and 8187 deletions
@@ -8,10 +8,13 @@ on:
      - 'gateway/**'
      - 'integrations/**'
      - 'nym-api/**'
+      - 'nym-authenticator-client/**'
      - 'nym-credential-proxy/**'
+      - 'nym-ip-packet-client/**'
      - 'nym-network-monitor/**'
      - 'nym-node/**'
      - 'nym-node-status-api/**'
+      - 'nym-registration-client/**'
      - 'nym-statistics-api/**'
      - 'nym-outfox/**'
      - 'nym-validator-rewarder/**'
@@ -6,16 +6,14 @@ on:
    paths:
      - "ts-packages/**"
      - "sdk/typescript/**"
-      - "nym-connect/desktop/src/**"
-      - "nym-connect/desktop/package.json"
      - "nym-wallet/src/**"
      - "nym-wallet/package.json"
-      - "explorer/**"
+      - "explorer-v2/**"
      - ".github/workflows/ci-lint-typescript.yml"

 jobs:
  build:
-    runs-on: ubuntu-22.04
+    runs-on: arc-linux-latest
    env:
      RUSTUP_PERMIT_COPY_RENAME: 1
    steps:
@@ -25,6 +23,7 @@ jobs:
      - uses: actions/setup-node@v4
        with:
          node-version: 20
+
      - name: Setup yarn
        run: npm install -g yarn

@@ -37,14 +36,12 @@ jobs:
        run: curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh

      - name: Install wasm-opt
-        uses: ./.github/actions/install-wasm-opt
-        with:
-          version: '116'
+        run: cargo install wasm-opt

      - name: Set up Go
-        uses: actions/setup-go@v5
+        uses: actions/setup-go@v6
        with:
-          go-version: "1.23.7"
+          go-version: "1.24.6"

      - name: Install
        run: yarn
@@ -52,7 +49,11 @@ jobs:
      - name: Build packages
        run: yarn build:ci

+      - name: Install again
+        run: yarn
+
      - name: Lint
        run: yarn lint
+
      - name: Typecheck with tsc
        run: yarn tsc
@@ -8,7 +8,7 @@ on:

 jobs:
  build:
-    runs-on: custom-linux
+    runs-on: arc-linux-latest
    steps:
      - uses: actions/checkout@v4

@@ -4,7 +4,7 @@ on:

 jobs:
  publish:
-    runs-on: arc-ubuntu-22.04
+    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

@@ -17,10 +17,13 @@ jobs:
      - name: Setup yarn
        run: npm install -g yarn

-      - name: Install Rust stable
+      - name: Install rust toolchain
        uses: actions-rs/toolchain@v1
        with:
+          profile: minimal
          toolchain: stable
+          override: true
+          components: rustfmt, clippy

      - name: Install wasm-pack
        run: curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
@@ -29,9 +32,9 @@ jobs:
        run: cargo install wasm-opt

      - name: Set up Go
-        uses: actions/setup-go@v5
+        uses: actions/setup-go@v6
        with:
-          go-version: "1.23.7"
+          go-version: "1.24.6"

      - name: Install dependencies
        run: yarn
@@ -4,6 +4,60 @@ Post 1.0.0 release, the changelog format is based on [Keep a Changelog](https://

 ## [Unreleased]

+## [2025.21-mozzarella] (2025-11-25)
+
+- [bugfix] Tunnel not waiting on MixnetClient to shut down cleanly ([#6225])
+- bugfix: fix credential proxy upgrade mode attestation url arg ([#6202])
+- HTTP API resilience enable & domain rotation conditions ([#6200])
+- Remove debug feature from http-macro spec in gateway probe ([#6195])
+- DNS relibility and troubleshooting  ([#6179])
+- [bugfix] Distinguish authenticator errors by credential spent ([#6176])
+- Typescript SDK 1.4.1 ([#6146])
+- Enable URL rotation and retries for mixnet gateway init ([#6126])
+- Feature/credential proxy jwt ([#5957])
+
+[#6225]: https://github.com/nymtech/nym/pull/6225
+[#6202]: https://github.com/nymtech/nym/pull/6202
+[#6200]: https://github.com/nymtech/nym/pull/6200
+[#6195]: https://github.com/nymtech/nym/pull/6195
+[#6179]: https://github.com/nymtech/nym/pull/6179
+[#6176]: https://github.com/nymtech/nym/pull/6176
+[#6146]: https://github.com/nymtech/nym/pull/6146
+[#6126]: https://github.com/nymtech/nym/pull/6126
+[#5957]: https://github.com/nymtech/nym/pull/5957
+
+## [2025.20-leerdammer] (2025-11-12)
+
+- Max/tweak ts sdk actions ([#6185])
+- chore: resolve clippy 1.91 warnings ([#6168])
+- [chore] Remove unused dependencies ([#6151])
+- Use typed-builder for registration client builder config ([#6150])
+- tommy is too quick ([#6149])
+- configurable mixnet client startup timeout ([#6148])
+- [Feature/operators]: QUIC bridge deployment script v2 ([#6145])
+- Bugfix: Add circuit breaker ([#6143])
+- bugfix: update internal owner address in transferred share ([#6139])
+- Update quic_bridge_deployment.sh for IPv4 and .deb package ([#6138])
+- feat: expose more explicit new_with_fronted_urls builder for http API client ([#6136])
+- bugfix: update stored epoch share when changing ownership ([#6135])
+- Domain fronting ([#6134])
+- bugfix: update stored epoch share when changing announce address ([#6131])
+
+[#6185]: https://github.com/nymtech/nym/pull/6185
+[#6168]: https://github.com/nymtech/nym/pull/6168
+[#6151]: https://github.com/nymtech/nym/pull/6151
+[#6150]: https://github.com/nymtech/nym/pull/6150
+[#6149]: https://github.com/nymtech/nym/pull/6149
+[#6148]: https://github.com/nymtech/nym/pull/6148
+[#6145]: https://github.com/nymtech/nym/pull/6145
+[#6143]: https://github.com/nymtech/nym/pull/6143
+[#6139]: https://github.com/nymtech/nym/pull/6139
+[#6138]: https://github.com/nymtech/nym/pull/6138
+[#6136]: https://github.com/nymtech/nym/pull/6136
+[#6135]: https://github.com/nymtech/nym/pull/6135
+[#6134]: https://github.com/nymtech/nym/pull/6134
+[#6131]: https://github.com/nymtech/nym/pull/6131
+
 ## [2025.19-kase] (2025-10-30)

 - update ns agent workflow ([#6154])
@@ -2579,7 +2579,7 @@ dependencies = [

 [[package]]
 name = "extension-storage"
-version = "1.4.0-rc.0"
+version = "1.4.1"
 dependencies = [
 "bip39",
 "console_error_panic_hook",
@@ -4478,7 +4478,7 @@ dependencies = [

 [[package]]
 name = "mix-fetch-wasm"
-version = "1.4.0-rc.0"
+version = "1.4.1"
 dependencies = [
 "async-trait",
 "futures",
@@ -4488,6 +4488,7 @@ dependencies = [
 "nym-ordered-buffer",
 "nym-service-providers-common",
 "nym-socks5-requests",
+ "nym-validator-client",
 "rand 0.8.5",
 "serde",
 "serde-wasm-bindgen 0.6.5",
@@ -4824,7 +4825,7 @@ dependencies = [

 [[package]]
 name = "nym-api"
-version = "1.1.68"
+version = "1.1.70"
 dependencies = [
 "anyhow",
 "async-trait",
@@ -5050,7 +5051,7 @@ dependencies = [

 [[package]]
 name = "nym-cli"
-version = "1.1.65"
+version = "1.1.67"
 dependencies = [
 "anyhow",
 "base64 0.22.1",
@@ -5133,7 +5134,7 @@ dependencies = [

 [[package]]
 name = "nym-client"
-version = "1.1.65"
+version = "1.1.67"
 dependencies = [
 "bs58",
 "clap",
@@ -5283,7 +5284,7 @@ dependencies = [

 [[package]]
 name = "nym-client-wasm"
-version = "1.4.0-rc.0"
+version = "1.4.1"
 dependencies = [
 "anyhow",
 "futures",
@@ -6057,6 +6058,7 @@ dependencies = [
 "thiserror 2.0.12",
 "tokio",
 "tracing",
+ "tracing-subscriber",
 "url",
 "wasmtimer",
 ]
@@ -6361,7 +6363,7 @@ dependencies = [

 [[package]]
 name = "nym-network-requester"
-version = "1.1.66"
+version = "1.1.68"
 dependencies = [
 "addr",
 "anyhow",
@@ -6411,7 +6413,7 @@ dependencies = [

 [[package]]
 name = "nym-node"
-version = "1.20.0"
+version = "1.22.0"
 dependencies = [
 "anyhow",
 "arc-swap",
@@ -6649,7 +6651,7 @@ dependencies = [

 [[package]]
 name = "nym-node-tester-wasm"
-version = "1.3.0-rc.0"
+version = "1.3.1"
 dependencies = [
 "futures",
 "js-sys",
@@ -6938,7 +6940,7 @@ dependencies = [

 [[package]]
 name = "nym-socks5-client"
-version = "1.1.65"
+version = "1.1.67"
 dependencies = [
 "bs58",
 "clap",
@@ -7679,7 +7681,7 @@ dependencies = [

 [[package]]
 name = "nymvisor"
-version = "0.1.30"
+version = "0.1.32"
 dependencies = [
 "anyhow",
 "bytes",
@@ -7833,9 +7835,9 @@ checksum = "d05e27ee213611ffe7d6348b942e8f942b37114c00cc03cec254295a4a17852e"

 [[package]]
 name = "openssl-sys"
-version = "0.9.109"
+version = "0.9.110"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "90096e2e47630d78b7d1c20952dc621f957103f8bc2c8359ec81290d75238571"
+checksum = "0a9f0075ba3c21b09f8e8b2026584b1d18d49388648f2fbbf3c97ea8deced8e2"
 dependencies = [
 "cc",
 "libc",
@@ -150,7 +150,7 @@ members = [
    "tools/internal/contract-state-importer/importer-cli",
    "tools/internal/contract-state-importer/importer-contract",
    "tools/internal/mixnet-connectivity-check",
-    # "tools/internal/sdk-version-bump",
+#    "tools/internal/sdk-version-bump",
    "tools/internal/ssl-inject",
    "tools/internal/testnet-manager",
    "tools/internal/testnet-manager/dkg-bypass-contract",
@@ -107,16 +107,16 @@ sdk-wasm-build:
 	$(MAKE) -C nym-browser-extension/storage wasm-pack
 	$(MAKE) -C wasm/client
 	$(MAKE) -C wasm/node-tester
-	# $(MAKE) -C wasm/mix-fetch
+	$(MAKE) -C wasm/mix-fetch
 	$(MAKE) -C wasm/zknym-lib
 	# $(MAKE) -C wasm/full-nym-wasm

 # run this from npm/yarn to ensure tools are in the path, e.g. yarn build:sdk from root of repo
 sdk-typescript-build:
 	npx lerna run --scope @nymproject/sdk build --stream
-	# npx lerna run --scope @nymproject/mix-fetch build --stream
-	# npx lerna run --scope @nymproject/node-tester build --stream
-	# yarn --cwd sdk/typescript/codegen/contract-clients build
+	npx lerna run --scope @nymproject/mix-fetch build --stream
+	npx lerna run --scope @nymproject/node-tester build --stream
+	yarn --cwd sdk/typescript/codegen/contract-clients build

 # NOTE: These targets are part of the main workspace (but not as wasm32-unknown-unknown)
 WASM_CRATES = extension-storage nym-client-wasm nym-node-tester-wasm zknym-lib
@@ -1,6 +1,6 @@
 [package]
 name = "nym-client"
-version = "1.1.65"
+version = "1.1.67"
 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.65"
+version = "1.1.67"
 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"
@@ -45,7 +45,7 @@ pub enum ClientCoreError {

    #[cfg(not(target_arch = "wasm32"))]
    #[error("resolution failed: {0}")]
-    ResolutionFailed(#[from] nym_http_api_client::HickoryDnsError),
+    ResolutionFailed(#[from] nym_http_api_client::ResolveError),

    #[error("no gateways on network")]
    NoGatewaysOnNetwork,
@@ -30,7 +30,6 @@ pub(crate) async fn connect_async(
            resolver
                .resolve_str(domain)
                .await?
-                .into_iter()
                .map(|a| SocketAddr::new(a, port))
                .collect()
        }
@@ -39,7 +39,6 @@ pub(crate) async fn connect_async(
            resolver
                .resolve_str(domain)
                .await?
-                .into_iter()
                .map(|a| SocketAddr::new(a, port))
                .collect()
        }
@@ -54,7 +54,7 @@ pub enum GatewayClientError {

    #[cfg(not(target_arch = "wasm32"))]
    #[error("resolution failed: {0}")]
-    ResolutionFailed(#[from] nym_http_api_client::HickoryDnsError),
+    ResolutionFailed(#[from] nym_http_api_client::ResolveError),

    #[error("No shared key was provided or obtained")]
    NoSharedKeyAvailable,
@@ -168,6 +168,14 @@ pub enum CredentialProxyError {
        device_id: String,
        credential_id: String,
    },
+
+    #[error(
+        "the attestation check url has not been provided through either the CLI nor the default .env config"
+    )]
+    AttestationCheckUrlNotSet,
+
+    #[error("the provided attestation check url is malformed: {source}")]
+    MalformedAttestationCheckUrl { source: url::ParseError },
 }

 impl From<NymAPIError> for CredentialProxyError {
@@ -32,7 +32,7 @@ thiserror = { workspace = true }
 tracing = { workspace = true }
 itertools = { workspace = true }
 inventory = { workspace = true }
-
+tokio = { workspace = true, features = ["rt", "macros", "time"] }
 # used for decoding text responses (they were already implicitly included)
 bytes = { workspace = true }
 encoding_rs = { workspace = true }
@@ -52,5 +52,4 @@ workspace = true
 features = ["tokio"]

 [dev-dependencies]
-tokio = { workspace = true, features = ["rt", "macros"] }
-
+tracing-subscriber.workspace = true
@@ -30,19 +30,26 @@
 use crate::ClientBuilder;

 use std::{
-    net::SocketAddr,
+    collections::HashMap,
+    net::{IpAddr, SocketAddr},
+    str::FromStr,
    sync::{Arc, LazyLock},
+    time::Duration,
 };

 use hickory_resolver::{
-    ResolveError, TokioResolver,
-    config::{LookupIpStrategy, NameServerConfigGroup, ResolverConfig, ServerOrderingStrategy},
-    lookup_ip::{LookupIp, LookupIpIntoIter},
+    TokioResolver,
+    config::{LookupIpStrategy, NameServerConfigGroup, ResolverConfig},
+    lookup_ip::LookupIpIntoIter,
    name_server::TokioConnectionProvider,
 };
 use once_cell::sync::OnceCell;
 use reqwest::dns::{Addrs, Name, Resolve, Resolving};
-use tracing::warn;
+use tracing::*;
+
+mod constants;
+mod static_resolver;
+pub use static_resolver::*;

 impl ClientBuilder {
    /// Override the DNS resolver implementation used by the underlying http client.
@@ -59,10 +66,6 @@ impl ClientBuilder {
    }
 }

-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.
@@ -72,11 +75,24 @@ static SHARED_RESOLVER: LazyLock<HickoryDnsResolver> = LazyLock::new(|| {
 });

 #[derive(Debug, thiserror::Error)]
-#[error("hickory-dns resolver error: {hickory_error}")]
+#[allow(missing_docs)]
 /// Error occurring while resolving a hostname into an IP address.
-pub struct HickoryDnsError {
-    #[from]
-    hickory_error: ResolveError,
+pub enum ResolveError {
+    #[error("invalid name: {0}")]
+    InvalidNameError(String),
+    #[error("hickory-dns resolver error: {0}")]
+    ResolveError(#[from] hickory_resolver::ResolveError),
+    #[error("high level lookup timed out")]
+    Timeout,
+    #[error("hostname not found in static lookup table")]
+    StaticLookupMiss,
+}
+
+impl ResolveError {
+    /// Returns true if the error is a timeout.
+    pub fn is_timeout(&self) -> bool {
+        matches!(self, ResolveError::Timeout)
+    }
 }

 /// Wrapper around an `AsyncResolver`, which implements the `Resolve` trait.
@@ -87,69 +103,116 @@ pub struct HickoryDnsError {
 /// 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)]
+#[derive(Debug, 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.
    state: Arc<OnceCell<TokioResolver>>,
    fallback: Option<Arc<OnceCell<TokioResolver>>>,
+    static_base: Option<Arc<OnceCell<StaticResolver>>>,
    dont_use_shared: bool,
+    /// Overall timeout for dns lookup associated with any individual host resolution. For example,
+    /// use of retries, server_ordering_strategy, etc. ends absolutely if this timeout is reached.
+    overall_dns_timeout: Duration,
+}
+
+impl Default for HickoryDnsResolver {
+    fn default() -> Self {
+        Self {
+            state: Default::default(),
+            fallback: Default::default(),
+            static_base: Default::default(),
+            dont_use_shared: Default::default(),
+            overall_dns_timeout: Duration::from_secs(10),
+        }
+    }
 }

 impl Resolve for HickoryDnsResolver {
    fn resolve(&self, name: Name) -> Resolving {
        let resolver = self.state.clone();
        let maybe_fallback = self.fallback.clone();
+        let maybe_static = self.static_base.clone();
        let independent = self.dont_use_shared;
+        let overall_dns_timeout = self.overall_dns_timeout;
        Box::pin(async move {
-            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())
-                }
-            })?;
+            resolve(
+                name,
+                resolver,
+                maybe_fallback,
+                maybe_static,
+                independent,
+                overall_dns_timeout,
+            )
+            .await
+            .map_err(|e| Box::new(e) as Box<dyn std::error::Error + Send + Sync>)
+        })
+    }
+}

-            // 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) => {
-                    if let Some(ref fallback) = maybe_fallback {
-                        // on failure use the fall back system configured DNS resolver
-                        if !e.is_no_records_found() {
-                            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
-                                    .as_ref()
-                                    .ok_or(e)? // if the shared resolver has no fallback return the original error
-                                    .get_or_try_init(new_resolver_system)?
-                                    .clone())
-                            }
-                        })?;
-
-                        resolver.lookup_ip(name.as_str()).await?
-                    } else {
-                        return Err(e.into());
-                    }
-                }
-            };
+async fn resolve(
+    name: Name,
+    resolver: Arc<OnceCell<TokioResolver>>,
+    maybe_fallback: Option<Arc<OnceCell<TokioResolver>>>,
+    maybe_static: Option<Arc<OnceCell<StaticResolver>>>,
+    independent: bool,
+    overall_dns_timeout: Duration,
+) -> Result<Addrs, ResolveError> {
+    let resolver = resolver.get_or_try_init(|| HickoryDnsResolver::new_resolver(independent))?;

+    // Attempt a lookup using the primary resolver
+    let resolve_fut = tokio::time::timeout(overall_dns_timeout, resolver.lookup_ip(name.as_str()));
+    let primary_err = match resolve_fut.await {
+        Err(_) => ResolveError::Timeout,
+        Ok(Ok(lookup)) => {
            let addrs: Addrs = Box::new(SocketAddrs {
                iter: lookup.into_iter(),
            });
-            Ok(addrs)
-        })
+            return Ok(addrs);
+        }
+        Ok(Err(e)) => {
+            // on failure use the fall back system configured DNS resolver
+            if !e.is_no_records_found() {
+                warn!("primary DNS failed w/ error: {e}");
+            }
+            e.into()
+        }
+    };
+
+    // If the primary resolver encountered an error, attempt a lookup using the fallback
+    // resolver if one is configured.
+    if let Some(ref fallback) = maybe_fallback {
+        let resolver =
+            fallback.get_or_try_init(|| HickoryDnsResolver::new_resolver_system(independent))?;
+
+        let resolve_fut =
+            tokio::time::timeout(overall_dns_timeout, resolver.lookup_ip(name.as_str()));
+        if let Ok(Ok(lookup)) = resolve_fut.await {
+            let addrs: Addrs = Box::new(SocketAddrs {
+                iter: lookup.into_iter(),
+            });
+            return Ok(addrs);
+        }
    }
+
+    // If no record has been found and a static map of fallback addresses is configured
+    // check the table for our entry
+    if let Some(ref static_resolver) = maybe_static {
+        debug!("checking static");
+        let resolver =
+            static_resolver.get_or_init(|| HickoryDnsResolver::new_static_fallback(independent));
+
+        if let Ok(addrs) = resolver.resolve(name).await {
+            return Ok(addrs);
+        }
+    }
+
+    Err(primary_err)
+}
+
+struct SocketAddrs {
+    iter: LookupIpIntoIter,
 }

 impl Iterator for SocketAddrs {
@@ -162,28 +225,22 @@ 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(|| 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) => {
-                if let Some(ref fallback) = self.fallback {
-                    // on failure use the fall back system configured DNS resolver
-                    if !e.is_no_records_found() {
-                        warn!("primary DNS failed w/ error {e}: using system fallback");
-                    }
-
-                    let resolver = fallback.get_or_try_init(|| self.new_resolver_system())?;
-                    resolver.lookup_ip(name).await?
-                } else {
-                    return Err(e.into());
-                }
-            }
-        };
-
-        Ok(lookup)
+    pub async fn resolve_str(
+        &self,
+        name: &str,
+    ) -> Result<impl Iterator<Item = IpAddr> + use<>, ResolveError> {
+        let n =
+            Name::from_str(name).map_err(|_| ResolveError::InvalidNameError(name.to_string()))?;
+        resolve(
+            n,
+            self.state.clone(),
+            self.fallback.clone(),
+            self.static_base.clone(),
+            self.dont_use_shared,
+            self.overall_dns_timeout,
+        )
+        .await
+        .map(|addrs| addrs.map(|socket_addr| socket_addr.ip()))
    }

    /// Create a (lazy-initialized) resolver that is not shared across threads.
@@ -194,16 +251,20 @@ impl HickoryDnsResolver {
        }
    }

-    fn new_resolver(&self) -> Result<TokioResolver, HickoryDnsError> {
-        if self.dont_use_shared {
+    fn new_resolver(dont_use_shared: bool) -> Result<TokioResolver, ResolveError> {
+        // 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 dont_use_shared {
            new_resolver()
        } else {
            Ok(SHARED_RESOLVER.state.get_or_try_init(new_resolver)?.clone())
        }
    }

-    fn new_resolver_system(&self) -> Result<TokioResolver, HickoryDnsError> {
-        if self.dont_use_shared || SHARED_RESOLVER.fallback.is_none() {
+    fn new_resolver_system(dont_use_shared: bool) -> Result<TokioResolver, ResolveError> {
+        // 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 dont_use_shared || SHARED_RESOLVER.fallback.is_none() {
            new_resolver_system()
        } else {
            Ok(SHARED_RESOLVER
@@ -215,8 +276,18 @@ impl HickoryDnsResolver {
        }
    }

+    fn new_static_fallback(dont_use_shared: bool) -> StaticResolver {
+        if !dont_use_shared && let Some(ref shared_resolver) = SHARED_RESOLVER.static_base {
+            shared_resolver
+                .get_or_init(new_default_static_fallback)
+                .clone()
+        } else {
+            new_default_static_fallback()
+        }
+    }
+
    /// Enable fallback to the system default resolver if the primary (DoX) resolver fails
-    pub fn enable_system_fallback(&mut self) -> Result<(), HickoryDnsError> {
+    pub fn enable_system_fallback(&mut self) -> Result<(), ResolveError> {
        self.fallback = Some(Default::default());
        let _ = self
            .fallback
@@ -231,22 +302,51 @@ impl HickoryDnsResolver {
    pub fn disable_system_fallback(&mut self) {
        self.fallback = None;
    }
+
+    /// Get the current map of hostname to address in use by the fallback static lookup if one
+    /// exists.
+    pub fn get_static_fallbacks(&self) -> Option<HashMap<String, Vec<IpAddr>>> {
+        Some(self.static_base.as_ref()?.get()?.get_addrs())
+    }
+
+    /// Set (or overwrite) the map of addresses used in the fallback static hostname lookup
+    pub fn set_static_fallbacks(&mut self, addrs: HashMap<String, Vec<IpAddr>>) {
+        let cell = OnceCell::new();
+        cell.set(StaticResolver::new(addrs))
+            .expect("infallible assign");
+        self.static_base = Some(Arc::new(cell));
+    }
 }

 /// Create a new resolver with a custom DoT based configuration. The options are overridden to look
 /// up for both IPv4 and IPv6 addresses to work with "happy eyeballs" algorithm.
-fn new_resolver() -> Result<TokioResolver, HickoryDnsError> {
+///
+/// Timeout Defaults to 5 seconds
+/// Number of retries after lookup failure before giving up Defaults to 2
+///
+/// Caches successfully resolved addresses for 30 minutes to prevent continual use of remote lookup.
+/// This resolver is intended to be used for OUR API endpoints that do not rapidly rotate IPs.
+fn new_resolver() -> Result<TokioResolver, ResolveError> {
+    info!("building new configured resolver");
+
    let mut name_servers = NameServerConfigGroup::quad9_tls();
    name_servers.merge(NameServerConfigGroup::quad9_https());
    name_servers.merge(NameServerConfigGroup::cloudflare_tls());
    name_servers.merge(NameServerConfigGroup::cloudflare_https());

+    configure_and_build_resolver(name_servers)
+}
+
+fn configure_and_build_resolver(
+    name_servers: NameServerConfigGroup,
+) -> Result<TokioResolver, ResolveError> {
    let config = ResolverConfig::from_parts(None, Vec::new(), name_servers);
    let mut resolver_builder =
        TokioResolver::builder_with_config(config, TokioConnectionProvider::default());

    resolver_builder.options_mut().ip_strategy = LookupIpStrategy::Ipv4AndIpv6;
-    resolver_builder.options_mut().server_ordering_strategy = ServerOrderingStrategy::RoundRobin;
+    // Cache successful responses for queries received by this resolver for 30 min minimum.
+    resolver_builder.options_mut().positive_min_ttl = Some(Duration::from_secs(1800));

    Ok(resolver_builder.build())
 }
@@ -254,20 +354,27 @@ fn new_resolver() -> Result<TokioResolver, HickoryDnsError> {
 /// Create a new resolver with the default configuration, which reads from the system DNS config
 /// (i.e. `/etc/resolve.conf` in unix). The options are overridden to look up for both IPv4 and IPv6
 /// addresses to work with "happy eyeballs" algorithm.
-fn new_resolver_system() -> Result<TokioResolver, HickoryDnsError> {
+fn new_resolver_system() -> Result<TokioResolver, ResolveError> {
    let mut resolver_builder = TokioResolver::builder_tokio()?;
    resolver_builder.options_mut().ip_strategy = LookupIpStrategy::Ipv4AndIpv6;

    Ok(resolver_builder.build())
 }

+fn new_default_static_fallback() -> StaticResolver {
+    StaticResolver::new(constants::default_static_addrs())
+}
+
 #[cfg(test)]
 mod test {
    use super::*;
+    use itertools::Itertools;
+    use std::collections::HashMap;

    #[tokio::test]
-    async fn reqwest_hickory_doh() {
-        let resolver = HickoryDnsResolver::default();
+    async fn reqwest_with_custom_dns() {
+        let var_name = HickoryDnsResolver::default();
+        let resolver = var_name;
        let client = reqwest::ClientBuilder::new()
            .dns_resolver(resolver.into())
            .build()
@@ -286,7 +393,7 @@ mod test {
    }

    #[tokio::test]
-    async fn dns_lookup() -> Result<(), HickoryDnsError> {
+    async fn dns_lookup() -> Result<(), ResolveError> {
        let resolver = HickoryDnsResolver::default();

        let domain = "ifconfig.me";
@@ -296,4 +403,124 @@ mod test {

        Ok(())
    }
+
+    #[tokio::test]
+    async fn static_resolver_as_fallback() -> Result<(), ResolveError> {
+        let example_domain = "non-existent.nymvpn.com";
+        let mut resolver = HickoryDnsResolver {
+            ..Default::default()
+        };
+
+        let result = resolver.resolve_str(example_domain).await;
+        assert!(result.is_err()); // should be NXDomain
+
+        resolver.static_base = Some(Default::default());
+
+        let mut addr_map = HashMap::new();
+        let example_ip4: IpAddr = "10.10.10.10".parse().unwrap();
+        let example_ip6: IpAddr = "dead::beef".parse().unwrap();
+        addr_map.insert(example_domain.to_string(), vec![example_ip4, example_ip6]);
+
+        resolver.set_static_fallbacks(addr_map);
+
+        let mut addrs = resolver.resolve_str(example_domain).await?;
+        assert!(addrs.contains(&example_ip4));
+        assert!(addrs.contains(&example_ip6));
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod failure_test {
+    use super::*;
+    use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
+
+    /// IP addresses guaranteed to fail attempts to resolve
+    ///
+    /// Addresses drawn from blocks set off by RFC5737 (ipv4) and RFC3849 (ipv6)
+    const GUARANTEED_BROKEN_IPS_1: &[IpAddr] = &[
+        IpAddr::V4(Ipv4Addr::new(192, 0, 2, 1)),
+        IpAddr::V4(Ipv4Addr::new(198, 51, 100, 1)),
+        IpAddr::V6(Ipv6Addr::new(0x2001, 0x0db8, 0, 0, 0, 0, 0, 0x1111)),
+        IpAddr::V6(Ipv6Addr::new(0x2001, 0x0db8, 0, 0, 0, 0, 0, 0x1001)),
+    ];
+
+    // Create a resolver that behaves the same as the custom configured router, except for the fact
+    // that it is guaranteed to fail.
+    fn build_broken_resolver() -> Result<TokioResolver, ResolveError> {
+        info!("building new faulty resolver");
+
+        let mut broken_ns_group = NameServerConfigGroup::from_ips_tls(
+            GUARANTEED_BROKEN_IPS_1,
+            853,
+            "cloudflare-dns.com".to_string(),
+            true,
+        );
+        let broken_ns_https = NameServerConfigGroup::from_ips_https(
+            GUARANTEED_BROKEN_IPS_1,
+            443,
+            "cloudflare-dns.com".to_string(),
+            true,
+        );
+        broken_ns_group.merge(broken_ns_https);
+
+        configure_and_build_resolver(broken_ns_group)
+    }
+
+    #[tokio::test]
+    async fn dns_lookup_failures() -> Result<(), ResolveError> {
+        let time_start = std::time::Instant::now();
+
+        let r = OnceCell::new();
+        r.set(build_broken_resolver().expect("failed to build resolver"))
+            .expect("broken resolver init error");
+
+        // create a new resolver that won't mess with the shared resolver used by other tests
+        let resolver = HickoryDnsResolver {
+            dont_use_shared: true,
+            state: Arc::new(r),
+            overall_dns_timeout: Duration::from_secs(5),
+            ..Default::default()
+        };
+        build_broken_resolver()?;
+        let domain = "ifconfig.me";
+        let result = resolver.resolve_str(domain).await;
+        assert!(result.is_err_and(|e| matches!(e, ResolveError::Timeout)));
+
+        let duration = time_start.elapsed();
+        assert!(duration < resolver.overall_dns_timeout + Duration::from_secs(1));
+
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn fallback_to_static() -> Result<(), ResolveError> {
+        let r = OnceCell::new();
+        r.set(build_broken_resolver().expect("failed to build resolver"))
+            .expect("broken resolver init error");
+
+        // create a new resolver that won't mess with the shared resolver used by other tests
+        let resolver = HickoryDnsResolver {
+            dont_use_shared: true,
+            state: Arc::new(r),
+            static_base: Some(Default::default()),
+            overall_dns_timeout: Duration::from_secs(5),
+            ..Default::default()
+        };
+        build_broken_resolver()?;
+
+        // successful lookup using fallback to static resolver
+        let domain = "nymvpn.com";
+        let _ = resolver
+            .resolve_str(domain)
+            .await
+            .expect("failed to resolve address in static lookup");
+
+        // unsuccessful lookup - primary times out, and not in
+        let domain = "non-existent.nymtech.net";
+        let result = resolver.resolve_str(domain).await;
+        assert!(result.is_err_and(|e| matches!(e, ResolveError::Timeout)));
+
+        Ok(())
+    }
 }
@@ -0,0 +1,95 @@
+#![allow(missing_docs)]
+
+use std::collections::HashMap;
+use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
+
+pub const NYM_API_DOMAIN: &str = "validator.nymtech.net";
+pub const NYM_API_IPS: &[IpAddr] = &[IpAddr::V4(Ipv4Addr::new(212, 71, 233, 232))];
+
+pub const NYM_VPN_API_DOMAIN: &str = "nymvpn.com";
+pub const NYM_VPN_API_IPS: &[IpAddr] = &[IpAddr::V4(Ipv4Addr::new(76, 76, 21, 21))];
+
+pub const NYM_FRONTDOOR_VERCEL_DOMAIN: &str = "nym-frontdoor.vercel.app";
+pub const NYM_FRONTDOOR_VERCEL_IPS: &[IpAddr] = &[
+    IpAddr::V4(Ipv4Addr::new(64, 29, 17, 195)),
+    IpAddr::V4(Ipv4Addr::new(216, 198, 79, 195)),
+];
+
+pub const NYM_FRONTDOOR_FASTLY_DOMAIN: &str = "nym-frontdoor.global.ssl.fastly.net";
+pub const NYM_FRONTDOOR_FASTLY_IPS: &[IpAddr] = &[
+    IpAddr::V4(Ipv4Addr::new(151, 101, 193, 194)),
+    IpAddr::V4(Ipv4Addr::new(151, 101, 129, 194)),
+    IpAddr::V4(Ipv4Addr::new(151, 101, 1, 194)),
+    IpAddr::V4(Ipv4Addr::new(151, 101, 65, 194)),
+];
+
+pub const NYMVPN_FRONTDOOR_FASTLY_DOMAIN: &str = "nymvpn-frontdoor.global.ssl.fastly.net";
+pub const NYMVPN_FRONTDOOR_FASTLY_IPS: &[IpAddr] = &[
+    IpAddr::V4(Ipv4Addr::new(151, 101, 193, 194)),
+    IpAddr::V4(Ipv4Addr::new(151, 101, 129, 194)),
+    IpAddr::V4(Ipv4Addr::new(151, 101, 1, 194)),
+    IpAddr::V4(Ipv4Addr::new(151, 101, 65, 194)),
+];
+
+pub const YELP_FASTLY_DOMAIN: &str = "yelp.global.ssl.fastly.net";
+pub const YELP_FASTLY_IPS: &[IpAddr] = &[
+    IpAddr::V4(Ipv4Addr::new(151, 101, 193, 194)),
+    IpAddr::V4(Ipv4Addr::new(151, 101, 129, 194)),
+    IpAddr::V4(Ipv4Addr::new(151, 101, 1, 194)),
+    IpAddr::V4(Ipv4Addr::new(151, 101, 65, 194)),
+];
+
+pub const VERCEL_APP_DOMAIN: &str = "vercel.app";
+pub const VERCEL_APP_IPS: &[IpAddr] = &[
+    IpAddr::V4(Ipv4Addr::new(64, 29, 17, 195)),
+    IpAddr::V4(Ipv4Addr::new(216, 198, 79, 195)),
+];
+
+pub const VERCEL_COM_DOMAIN: &str = "vercel.com";
+pub const VERCEL_COM_IPS: &[IpAddr] = &[
+    IpAddr::V4(Ipv4Addr::new(198, 169, 2, 129)),
+    IpAddr::V4(Ipv4Addr::new(198, 169, 1, 193)),
+];
+
+pub const NYM_COM_DOMAIN: &str = "nym.com";
+pub const NYM_COM_IPS: &[IpAddr] = &[IpAddr::V4(Ipv4Addr::new(76, 76, 21, 22))];
+
+pub const NYM_STATS_API_DOMAIN: &str = "nym-statistics-api.nymtech.cc";
+pub const NYM_STATS_API_IPS: &[IpAddr] = &[IpAddr::V4(Ipv4Addr::new(91, 92, 153, 96))];
+
+pub const NYM_RPC_DOMAIN: &str = "rpc.nymtech.net";
+pub const NYM_RPC_IPS: &[IpAddr] = &[
+    IpAddr::V4(Ipv4Addr::new(194, 182, 169, 49)),
+    IpAddr::V4(Ipv4Addr::new(91, 92, 200, 116)),
+    IpAddr::V6(Ipv6Addr::new(
+        0x2a04, 0xc43, 0xe00, 0x6f28, 0x400, 0xd8ff, 0xfe00, 0x1483,
+    )),
+    IpAddr::V6(Ipv6Addr::new(
+        0x2a04, 0xc46, 0xe00, 0x6f28, 0x4b3, 0x68ff, 0xfe00, 0x460,
+    )),
+];
+
+pub fn default_static_addrs() -> HashMap<String, Vec<IpAddr>> {
+    let mut m = HashMap::new();
+    m.insert(NYM_API_DOMAIN.to_string(), NYM_API_IPS.to_vec());
+    m.insert(NYM_VPN_API_DOMAIN.to_string(), NYM_VPN_API_IPS.to_vec());
+    m.insert(
+        NYM_FRONTDOOR_VERCEL_DOMAIN.to_string(),
+        NYM_FRONTDOOR_VERCEL_IPS.to_vec(),
+    );
+    m.insert(
+        NYM_FRONTDOOR_FASTLY_DOMAIN.to_string(),
+        NYM_FRONTDOOR_FASTLY_IPS.to_vec(),
+    );
+    m.insert(
+        NYMVPN_FRONTDOOR_FASTLY_DOMAIN.to_string(),
+        NYMVPN_FRONTDOOR_FASTLY_IPS.to_vec(),
+    );
+    m.insert(YELP_FASTLY_DOMAIN.to_string(), YELP_FASTLY_IPS.to_vec());
+    m.insert(VERCEL_APP_DOMAIN.to_string(), VERCEL_APP_IPS.to_vec());
+    m.insert(VERCEL_COM_DOMAIN.to_string(), VERCEL_COM_IPS.to_vec());
+    m.insert(NYM_COM_DOMAIN.to_string(), NYM_COM_IPS.to_vec());
+    m.insert(NYM_STATS_API_DOMAIN.to_string(), NYM_STATS_API_IPS.to_vec());
+    m.insert(NYM_RPC_DOMAIN.to_string(), NYM_RPC_IPS.to_vec());
+    m
+}
@@ -0,0 +1,89 @@
+use crate::dns::ResolveError;
+
+use std::{
+    collections::HashMap,
+    net::{IpAddr, SocketAddr},
+    sync::{Arc, Mutex},
+};
+
+use reqwest::dns::{Addrs, Name, Resolve, Resolving};
+use tracing::*;
+
+#[derive(Debug, Default, Clone)]
+pub struct StaticResolver {
+    static_addr_map: Arc<Mutex<HashMap<String, Vec<IpAddr>>>>,
+}
+
+impl StaticResolver {
+    pub fn new(static_entries: HashMap<String, Vec<IpAddr>>) -> StaticResolver {
+        debug!("building static resolver");
+        Self {
+            static_addr_map: Arc::new(Mutex::new(static_entries)),
+        }
+    }
+
+    pub fn get_addrs(&self) -> HashMap<String, Vec<IpAddr>> {
+        self.static_addr_map.lock().unwrap().clone()
+    }
+}
+
+impl Resolve for StaticResolver {
+    fn resolve(&self, name: Name) -> Resolving {
+        debug!("looking up {name:?} in static resolver");
+        let addr_map = self.static_addr_map.clone();
+        Box::pin(async move {
+            let addr_map = addr_map.lock().unwrap();
+            let lookup = match addr_map.get(name.as_str()) {
+                None => return Err(ResolveError::StaticLookupMiss.into()),
+                Some(addrs) => addrs,
+            };
+            let addrs: Addrs = Box::new(
+                lookup
+                    .clone()
+                    .into_iter()
+                    .map(|ip_addr| SocketAddr::new(ip_addr, 0)),
+            );
+
+            Ok(addrs)
+        })
+    }
+}
+
+#[cfg(test)]
+mod test {
+    use itertools::Itertools;
+
+    use super::*;
+    use std::error::Error as StdError;
+    use std::str::FromStr;
+
+    #[tokio::test]
+    async fn lookup_using_static_resolver() -> Result<(), Box<dyn StdError + Send + Sync>> {
+        let example_domain = String::from("static.nymvpn.com");
+
+        // lookup for domain for which there is no entry
+        let resolver = StaticResolver::new(HashMap::new());
+
+        let url = reqwest::dns::Name::from_str(&example_domain).unwrap();
+        let result = resolver.resolve(url).await;
+        assert!(result.is_err());
+        match result {
+            Ok(_) => panic!("lookup with empty map should fail"),
+            Err(e) => assert_eq!(e.to_string(), ResolveError::StaticLookupMiss.to_string()),
+        }
+
+        // Successful lookup
+        let mut addr_map = HashMap::new();
+        let example_ip4: IpAddr = "10.10.10.10".parse().unwrap();
+        let example_ip6: IpAddr = "dead::beef".parse().unwrap();
+        addr_map.insert(example_domain.clone(), vec![example_ip4, example_ip6]);
+
+        let url = reqwest::dns::Name::from_str(&example_domain).unwrap();
+        let resolver = StaticResolver::new(addr_map);
+        let mut addrs = resolver.resolve(url).await?;
+        assert!(addrs.contains(&SocketAddr::new(example_ip4, 0)));
+        assert!(addrs.contains(&SocketAddr::new(example_ip6, 0)));
+
+        Ok(())
+    }
+}
@@ -121,4 +121,89 @@ mod tests {
        // println!("{response:?}");
        assert_eq!(response.status(), 200);
    }
+
+    #[tokio::test]
+    async fn fallback_on_failure() {
+        let url1 = Url::new(
+            "https://fake-domain.nymtech.net",
+            Some(vec![
+                "https://fake-front-1.nymtech.net",
+                "https://fake-front-2.nymtech.net",
+            ]),
+        )
+        .unwrap();
+        let url2 = Url::new(
+            "https://validator.global.ssl.fastly.net",
+            Some(vec!["https://yelp.global.ssl.fastly.net"]),
+        )
+        .unwrap(); // fastly
+
+        let client = ClientBuilder::new_with_urls(vec![url1, url2])
+            .expect("bad url")
+            .with_fronting(FrontPolicy::Always)
+            .build()
+            .expect("failed to build client");
+
+        // Check that the initial configuration has the broken domain and front.
+        assert_eq!(
+            client.current_url().as_str(),
+            "https://fake-domain.nymtech.net/",
+        );
+        assert_eq!(
+            client.current_url().front_str(),
+            Some("fake-front-1.nymtech.net"),
+        );
+
+        let result = client
+            .send_request::<_, (), &str, &str>(
+                reqwest::Method::GET,
+                &["api", "v1", "network", "details"],
+                NO_PARAMS,
+                None,
+            )
+            .await;
+        assert!(result.is_err());
+
+        // Check that the host configuration updated the front on error.
+        assert_eq!(
+            client.current_url().as_str(),
+            "https://fake-domain.nymtech.net/",
+        );
+        assert_eq!(
+            client.current_url().front_str(),
+            Some("fake-front-2.nymtech.net"),
+        );
+
+        let result = client
+            .send_request::<_, (), &str, &str>(
+                reqwest::Method::GET,
+                &["api", "v1", "network", "details"],
+                NO_PARAMS,
+                None,
+            )
+            .await;
+        assert!(result.is_err());
+
+        // Check that the host configuration updated the domain and front on error.
+        assert_eq!(
+            client.current_url().as_str(),
+            "https://validator.global.ssl.fastly.net/",
+        );
+        assert_eq!(
+            client.current_url().front_str(),
+            Some("yelp.global.ssl.fastly.net"),
+        );
+
+        let response = client
+            .send_request::<_, (), &str, &str>(
+                reqwest::Method::GET,
+                &["api", "v1", "network", "details"],
+                NO_PARAMS,
+                None,
+            )
+            .await
+            .expect("failed get request");
+
+        assert_eq!(response.status(), 200);
+    }
 }
@@ -179,7 +179,7 @@ mod dns;
 mod path;

 #[cfg(not(target_arch = "wasm32"))]
-pub use dns::{HickoryDnsError, HickoryDnsResolver};
+pub use dns::{HickoryDnsResolver, ResolveError};

 // helper for generating user agent based on binary information
 #[cfg(not(target_arch = "wasm32"))]
@@ -395,6 +395,13 @@ pub enum HttpClientError {
    #[error("failed to resolve request to {url} due to data inconsistency: {details}")]
    InternalResponseInconsistency { url: ::url::Url, details: String },

+    #[cfg(not(target_arch = "wasm32"))]
+    #[error("encountered dns failure: {inner}")]
+    DnsLookupFailure {
+        #[from]
+        inner: ResolveError,
+    },
+
    #[error("Failed to encode bincode: {0}")]
    Bincode(#[from] bincode::Error),

@@ -421,6 +428,8 @@ impl HttpClientError {
            HttpClientError::ReqwestClientError { source } => source.is_timeout(),
            HttpClientError::RequestSendFailure { source, .. } => source.0.is_timeout(),
            HttpClientError::ResponseReadFailure { source, .. } => source.0.is_timeout(),
+            #[cfg(not(target_arch = "wasm32"))]
+            HttpClientError::DnsLookupFailure { inner } => inner.is_timeout(),
            #[cfg(target_arch = "wasm32")]
            HttpClientError::RequestTimeout => true,
            _ => false,
@@ -775,6 +784,7 @@ impl ClientBuilder {
            base_urls: self.urls,
            current_idx: Arc::new(AtomicUsize::new(0)),
            reqwest_client,
+            using_secure_dns: self.use_secure_dns,

            #[cfg(feature = "tunneling")]
            front: self.front,
@@ -795,6 +805,7 @@ pub struct Client {
    base_urls: Vec<Url>,
    current_idx: Arc<AtomicUsize>,
    reqwest_client: reqwest::Client,
+    using_secure_dns: bool,

    #[cfg(feature = "tunneling")]
    front: Option<fronted::Front>,
@@ -852,6 +863,7 @@ impl Client {
            base_urls: vec![new_url],
            current_idx: Arc::new(Default::default()),
            reqwest_client: self.reqwest_client.clone(),
+            using_secure_dns: self.using_secure_dns,

            #[cfg(feature = "tunneling")]
            front: self.front.clone(),
@@ -883,8 +895,34 @@ impl Client {
        self.retry_limit = limit;
    }

+    fn matches_current_host(&self, url: &Url) -> bool {
+        if cfg!(feature = "tunneling") {
+            if let Some(ref front) = self.front
+                && front.is_enabled()
+            {
+                url.host_str() == self.current_url().front_str()
+            } else {
+                url.host_str() == self.current_url().host_str()
+            }
+        } else {
+            url.host_str() == self.current_url().host_str()
+        }
+    }
+
    /// If multiple base urls are available rotate to next (e.g. when the current one resulted in an error)
-    fn update_host(&self) {
+    ///
+    /// Takes an optional URL argument. If this is none, the current host will be updated automatically.
+    /// If a url is provided first check that the CURRENT host matches the hostname in the URL before
+    /// triggering a rotation. This is meant to prevent parallel requests that fail from rotating the host
+    /// multiple times.
+    fn update_host(&self, maybe_url: Option<Url>) {
+        // If a causal url is provided and it doesn't match the hostname currently in use, skip update.
+        if let Some(err_url) = maybe_url
+            && !self.matches_current_host(&err_url)
+        {
+            return;
+        }
+
        #[cfg(feature = "tunneling")]
        if let Some(ref front) = self.front
            && front.is_enabled()
@@ -1048,8 +1086,28 @@ impl ApiClientCore for Client {
                .build()
                .map_err(HttpClientError::reqwest_client_build_error)?;
            self.apply_hosts_to_req(&mut req);
+            let url: Url = req.url().clone().into();
+
+            // try an explicit DNS resolution - if successful then it will be in cache when reqwest
+            // goes to execute the request. If failure then we get to handle the DNS lookup error.
            #[cfg(not(target_arch = "wasm32"))]
-            let url = req.url().clone();
+            if self.using_secure_dns
+                && let Some(hostname) = req.url().domain()
+                // Default here will use a shared resolver instance
+                && let Err(err) = HickoryDnsResolver::default().resolve_str(hostname).await
+            {
+                // on failure update host, but don't trigger fronting enable.
+                self.update_host(Some(url.clone()));
+
+                if attempts < self.retry_limit {
+                    attempts += 1;
+                    warn!(
+                        "Retrying request due to dns error on attempt ({attempts}/{}): {err}",
+                        self.retry_limit
+                    );
+                    continue;
+                }
+            }

            #[cfg(target_arch = "wasm32")]
            let response: Result<Response, HttpClientError> = {
@@ -1067,25 +1125,39 @@ impl ApiClientCore for Client {
            match response {
                Ok(resp) => return Ok(resp),
                Err(err) => {
-                    // if we have multiple urls, update to the next
-                    self.update_host();
+                    // only if there was a network issue should we consider updating the host info
+                    //
+                    // note: for now this includes DNS resolution failure, I am not sure how I would go about
+                    // segregating that based on the interface provided by request for errors.
+                    #[cfg(target_arch = "wasm32")]
+                    let is_network_err = err.is_timeout();
+                    #[cfg(not(target_arch = "wasm32"))]
+                    let is_network_err = err.is_timeout() || err.is_connect();

-                    #[cfg(feature = "tunneling")]
-                    if let Some(ref front) = self.front {
-                        // If fronting is set to be enabled on error, enable domain fronting as we
-                        // have encountered an error.
-                        let was_enabled = front.is_enabled();
-                        front.retry_enable();
-                        if !was_enabled && front.is_enabled() {
-                            tracing::info!(
-                                "Domain fronting activated after connection failure: {err}",
-                            );
+                    if is_network_err {
+                        // if we have multiple urls, update to the next
+                        self.update_host(Some(url.clone()));
+
+                        #[cfg(feature = "tunneling")]
+                        if let Some(ref front) = self.front {
+                            // If fronting is set to be enabled on error, enable domain fronting as we
+                            // have encountered an error.
+                            let was_enabled = front.is_enabled();
+                            front.retry_enable();
+                            if !was_enabled && front.is_enabled() {
+                                tracing::info!(
+                                    "Domain fronting activated after connection failure: {err}",
+                                );
+                            }
                        }
                    }

                    if attempts < self.retry_limit {
-                        warn!("Retrying request due to http error: {err}");
                        attempts += 1;
+                        warn!(
+                            "Retrying request due to http error on attempt ({attempts}/{}): {err}",
+                            self.retry_limit
+                        );
                        continue;
                    }

@@ -1094,7 +1166,7 @@ impl ApiClientCore for Client {
                        if #[cfg(target_arch = "wasm32")] {
                            return Err(err);
                        } else {
-                            return Err(HttpClientError::request_send_error(url, err));
+                            return Err(HttpClientError::request_send_error(url.into(), err));
                        }
                    }
                }
@@ -91,14 +91,15 @@ fn sanitizing_urls() {
 #[tokio::test]
 async fn api_client_retry() -> Result<(), Box<dyn std::error::Error>> {
    let client = ClientBuilder::new_with_urls(vec![
-        "http://broken.nym.test".parse()?,         // This will fail
-        "https://httpbin.org/status/200".parse()?, // This will succeed
+        "http://broken.nym.test".parse()?, // This will fail because of DNS (rotate)
+        "http://127.0.0.1:9".parse()?,     // This will fail because of TCP refused (rotate)
+        "https://httpbin.org/status/200".parse()?, // This should succeed
    ])?
    .with_retries(3)
    .build()?;

    let req = client.create_get_request(&[], NO_PARAMS).unwrap();
-    let resp = client.send(req).await?;
+    let _resp = client.send(req).await?;

    // The main test is that we successfully retried and switched to the working URL
    // We accept any response from the working endpoint since external services can be unreliable
@@ -107,7 +108,9 @@ async fn api_client_retry() -> Result<(), Box<dyn std::error::Error>> {
        "https://httpbin.org/status/200"
    );

-    println!("Response status: {}", resp.status());
+    // // This assert can be unreliable due to factors beyond our control and beyond the scope of
+    // // this test
+    // assert_eq!(_resp.status(), StatusCode::OK);

    Ok(())
 }
@@ -123,7 +126,7 @@ fn host_updating() {
    assert_eq!(current_url.front_str(), None);

    // update the url
-    client.update_host();
+    client.update_host(None);

    // check that the url is still the same since there is one URL
    assert_eq!(client.current_url().as_str(), "http://nym-api1.test/");
@@ -138,13 +141,13 @@ fn host_updating() {
    client.change_base_urls(new_urls);
    assert_eq!(client.current_url().as_str(), "http://nym-api1.test/");

-    client.update_host();
+    client.update_host(None);

    // check that the url got updated now that there are multiple URLs
    assert_eq!(client.current_url().as_str(), "http://nym-api2.test/");
    assert_eq!(client.current_url().front_str(), None);

-    client.update_host();
+    client.update_host(None);
    assert_eq!(client.current_url().as_str(), "http://nym-api1.test/");

    // =======================================
@@ -162,12 +165,33 @@ fn host_updating() {

    assert_eq!(client.current_url().as_str(), "http://nym-api1.test/");

-    client.update_host();
+    client.update_host(None);

    // check that the url got updated now that there are multiple URLs
    assert_eq!(client.current_url().as_str(), "http://nym-api2.test/");
 }

+#[test]
+fn host_updating_url_conditioned() {
+    let url1 = Url::new("http://nym-api1.test", None).unwrap();
+    let url2 = Url::new("http://nym-api2.test", None).unwrap();
+    let urls = vec![url1.clone(), url2.clone()];
+    let client = ClientBuilder::new_with_urls(urls).unwrap().build().unwrap();
+
+    assert_eq!(client.current_url().as_str(), "http://nym-api1.test/");
+
+    // Try to update with a URL that does NOT match current - should result in no change
+    client.update_host(Some(Url::parse("http://example.com").unwrap()));
+
+    // check that the url did NOT get updated
+    assert_eq!(client.current_url().as_str(), "http://nym-api1.test/");
+    assert_eq!(client.current_url().front_str(), None);
+
+    // Try to update with a URL that DOES match current - should result in no change
+    client.update_host(Some(url1));
+    assert_eq!(client.current_url().as_str(), "http://nym-api2.test/");
+}
+
 #[test]
 #[cfg(feature = "tunneling")]
 fn fronted_host_updating() {
@@ -184,7 +208,7 @@ fn fronted_host_updating() {
    assert_eq!(current_url.front_str(), Some("cdn1.test"));

    // update the url
-    client.update_host();
+    client.update_host(None);

    // check that the url is still the same since there is one URL and one front
    let current_url = client.current_url();
@@ -209,7 +233,7 @@ fn fronted_host_updating() {
    assert_eq!(current_url.front_str(), Some("cdn1.test"));

    // update the url - this should keep the same host but change the front
-    client.update_host();
+    client.update_host(None);

    let current_url = client.current_url();
    // check that the url is still the same since there is one URL
@@ -217,7 +241,7 @@ fn fronted_host_updating() {
    assert_eq!(current_url.front_str(), Some("cdn2.test"));

    // update the url - this should wrap around to the first front as the second url is not fronted
-    client.update_host();
+    client.update_host(None);

    let current_url = client.current_url();
    assert_eq!(current_url.as_str(), "http://nym-api.test/");
@@ -54,6 +54,11 @@ pub const NYM_APIS: &[ApiUrlConst] = &[
 ];

 pub const NYM_VPN_API: &str = "https://nymvpn.com/api/";
+
+pub const UPGRADE_MODE_ATTESTATION_URL: &str = "https://nym.com/upgrade-mode/attestation.json";
+pub const UPGRADE_MODE_ATTESTER_ED25519_BS58_PUBKEY: &str =
+    "3bgffBYcfFkTTXc2npNNn9MkddFZ3H2LrPjXDmnJzrqd";
+
 #[cfg(feature = "network")]
 pub const NYM_VPN_APIS: &[ApiUrlConst] = &[
    ApiUrlConst {
@@ -159,6 +164,14 @@ pub fn export_to_env() {
    set_var_to_default(var_names::NYXD_WEBSOCKET, NYXD_WS);
    set_var_to_default(var_names::EXIT_POLICY_URL, EXIT_POLICY_URL);
    set_var_to_default(var_names::NYM_VPN_API, NYM_VPN_API);
+    set_var_to_default(
+        var_names::UPGRADE_MODE_ATTESTATION_URL,
+        UPGRADE_MODE_ATTESTATION_URL,
+    );
+    set_var_to_default(
+        var_names::UPGRADE_MODE_ATTESTER_ED25519_BS58_PUBKEY,
+        UPGRADE_MODE_ATTESTER_ED25519_BS58_PUBKEY,
+    );
 }

 #[cfg(all(feature = "env", feature = "network"))]
@@ -199,4 +212,12 @@ pub fn export_to_env_if_not_set() {
    set_var_conditionally_to_default(var_names::NYM_API, NYM_API);
    set_var_conditionally_to_default(var_names::NYXD_WEBSOCKET, NYXD_WS);
    set_var_conditionally_to_default(var_names::EXIT_POLICY_URL, EXIT_POLICY_URL);
+    set_var_conditionally_to_default(
+        var_names::UPGRADE_MODE_ATTESTATION_URL,
+        UPGRADE_MODE_ATTESTATION_URL,
+    );
+    set_var_conditionally_to_default(
+        var_names::UPGRADE_MODE_ATTESTER_ED25519_BS58_PUBKEY,
+        UPGRADE_MODE_ATTESTER_ED25519_BS58_PUBKEY,
+    );
 }
@@ -25,6 +25,8 @@ pub const NYXD_WEBSOCKET: &str = "NYXD_WS";
 pub const EXIT_POLICY_URL: &str = "EXIT_POLICY";
 pub const NYM_VPN_API: &str = "NYM_VPN_API";
 pub const CLIENT_STATS_COLLECTION_PROVIDER: &str = "CLIENT_STATS_COLLECTION_PROVIDER";
+pub const UPGRADE_MODE_ATTESTATION_URL: &str = "UPGRADE_MODE_ATTESTATION_URL";
+pub const UPGRADE_MODE_ATTESTER_ED25519_BS58_PUBKEY: &str = "UPGRADE_MODE_ATTESTER_ED25519_PUBKEY";

 pub const DKG_TIME_CONFIGURATION: &str = "DKG_TIME_CONFIGURATION";

@@ -0,0 +1,40 @@
+import Box from '@mui/material/Box';
+import { Steps } from 'nextra/components'
+import { Tabs } from 'nextra/components'
+import { GitHubRepoSearch } from '../../code-snippets/mixfetchurl';
+
+# Integration Options
+Developers might want to either integrate a Mixnet client or just to interact with the blockchain. See the relevant section below.
+
+## Integrating Mixnet Functionality
+There are several options available to developers wanting to embed a Nym client in their application code.
+
+<Tabs items={['Rust/Go/C++', 'Typescript/Javascript','Other']}>
+  <Tabs.Tab >
+    <>
+
+    Rust developers can rely on our Rust SDK to import Nym client functionality into their code. This can either be in the form of a standard message-based client, the `socks5` client, or the `TcpProxy` modules.
+
+      We aim to expose at least the majority of this functionality via FFI to Go and C/C++. This is detailed alongside the Rust SDK components in the [Rust SDK docs](./rust).
+
+    </>
+  </Tabs.Tab>
+  <Tabs.Tab>
+  <>
+
+  Typescript and Javascript developers have several options avaliable to them:
+      - [`mixfetch`](./typescript/examples/mix-fetch) is an almost-dropin replacement for the `fetch` library. The best way to integrate Nym's `mixFetch` into your application will be where external network calls and RPC happens, for example, something in the lines of `sendRawTransaction` if you have an ETH-compatible wallet or `JsonRpcClient` if you use CosmJS. Although you can simply search for any JS `fetch` calls in your code (using our tool below) that are easily replaceable with `mixFetch`, keep in mind that `fetch` is not the only way to make `JSONRPC` or `XHR` calls. We advise to approach the integration process in a semantic way, searching for a module that is the common denominator for external communication in the codebase. Usually these are API controllers, middlewares or repositories.
+
+    <GitHubRepoSearch />
+
+    - Otherwise, a well-modularized JS/TS codebase should permit the integration of one of our other SDK components, which will allow more flexibility and control (or if your codebase is not using something that can be covered by `fetch` for networking). Read more about our different SDK components in the [TS SDK overview page](./typescript/overview).
+
+    </ >
+  </Tabs.Tab>
+  <Tabs.Tab> If your app is not written in any of the supported languages, you might still be able to send traffic through a standalone [socks5 client](./clients/socks5) but will have to think about packaging and bundling the client binary with e.g. a `systemd` file for autostart to run the client as a daemon. If you want to discuss FFI options reach out to us via our public dev channel. </Tabs.Tab>
+</Tabs>
+
+## Interacting with Nyx
+If instead of relying on the Mixnet you wish to interact with the Nyx chain, either as a payment processor or to get on-chain events, see [interacting with the chain](./chain).
+
+> Note that depending on your setup, you might already be able to combine interacting with the chain with using the Mixnet: check the options above for more.
@@ -1,5 +1,7 @@
 # Required Application Architecture

+**TODO once you;ve reworked you can probably just remove this**
+
 Due to the fact that there are a lot of components that make up the Nym network (the Mixnet, Blockchain, etc) there is often confusion / misunderstandings about what is required to run application traffic through the Mixnet and take advantage of its various privacy properties.

 ## What do I need?
@@ -1,27 +1,26 @@
-```ts copy filename="mixFetchExample.tsx"
-import React, { useState } from 'react';
-import CircularProgress from '@mui/material/CircularProgress';
-import Button from '@mui/material/Button';
-import TextField from '@mui/material/TextField';
-import Typography from '@mui/material/Typography';
-import Box from '@mui/material/Box';
-import { mixFetch } from '@nymproject/mix-fetch-full-fat';
-import Stack from '@mui/material/Stack';
-import Paper from '@mui/material/Paper';
-import type { SetupMixFetchOps } from '@nymproject/mix-fetch';
+```tsx copy filename="mixFetchExample.tsx"
+import React, { useState } from "react";
+import CircularProgress from "@mui/material/CircularProgress";
+import Button from "@mui/material/Button";
+import TextField from "@mui/material/TextField";
+import Typography from "@mui/material/Typography";
+import Box from "@mui/material/Box";
+import { mixFetch } from "@nymproject/mix-fetch-full-fat";
+import Stack from "@mui/material/Stack";
+import Paper from "@mui/material/Paper";
+import type { SetupMixFetchOps } from "@nymproject/mix-fetch-full-fat";

-const defaultUrl = 'https://nym.com/favicon.svg';
-const args = { mode: 'unsafe-ignore-cors' };
+const defaultUrl = "https://nymtech.net/.wellknown/network-requester/exit-policy.txt";
+const args = { mode: "unsafe-ignore-cors" };

 const mixFetchOptions: SetupMixFetchOps = {
-  preferredGateway: '6Gb7ftQdKveMjPyrxDXeAtfYAX7Zg5mVZHtnRC5MmZ1B', // with WSS
-  preferredNetworkRequester:
-    '8rRGWy54oC8drFL9DepMegBt2DLrsqQwCoHMXt9nsnTo.2XjCPVbb4FpQ9hNRcXwb9mTzEAVVk1zf1tcch3wdtNEA@6Gb7ftQdKveMjPyrxDXeAtfYAX7Zg5mVZHtnRC5MmZ1B',
+  preferredGateway: "2xU4CBE6QiiYt6EyBXSALwxkNvM7gqJfjHXaMkjiFmYW", // with WSS
+  // preferredNetworkRequester:
+  //   "CTDxrcXgrZHWyCWnuCgjpJPghQUcEVz1HkhUr5mGdFnT.3UAww1YWNyVNYNWFQL1LaHYouQtDiXBGK5GiDZgpXkTK@2RFtU5BwxvJJXagAWAEuaPgb5ZVPRoy2542TT93Edw6v",
  mixFetchOverride: {
    requestTimeoutMs: 60_000,
  },
  forceTls: true, // force WSS
-  extra: {},
 };

 export const MixFetch = () => {
@@ -45,7 +44,7 @@ export const MixFetch = () => {
  };

  return (
-    <div style={{ marginTop: '1rem' }}>
+    <div style={{ marginTop: "1rem" }}>
      <Stack direction="row">
        <TextField
          disabled={busy}
@@ -56,7 +55,12 @@ export const MixFetch = () => {
          defaultValue={defaultUrl}
          onChange={(e) => setUrl(e.target.value)}
        />
-        <Button variant="outlined" disabled={busy} sx={{ marginLeft: '1rem' }} onClick={handleFetch}>
+        <Button
+          variant="outlined"
+          disabled={busy}
+          sx={{ marginLeft: "1rem" }}
+          onClick={handleFetch}
+        >
          Fetch
        </Button>
      </Stack>
@@ -1,15 +1,19 @@
 ```ts copy filename="MixnetWASMClientExample.tsx"
-import React, { useEffect, useState } from 'react';
-import { createNymMixnetClient, NymMixnetClient, Payload } from '@nymproject/sdk-full-fat';
-import Box from '@mui/material/Box';
-import CircularProgress from '@mui/material/CircularProgress';
-import Paper from '@mui/material/Paper';
-import Typography from '@mui/material/Typography';
-import Stack from '@mui/material/Stack';
-import TextField from '@mui/material/TextField';
-import Button from '@mui/material/Button';
+import React, { useEffect, useState } from "react";
+import {
+  createNymMixnetClient,
+  NymMixnetClient,
+  Payload,
+} from "@nymproject/sdk-full-fat";
+import Box from "@mui/material/Box";
+import CircularProgress from "@mui/material/CircularProgress";
+import Paper from "@mui/material/Paper";
+import Typography from "@mui/material/Typography";
+import Stack from "@mui/material/Stack";
+import TextField from "@mui/material/TextField";
+import Button from "@mui/material/Button";

-const nymApiUrl = 'https://validator.nymtech.net/api';
+const nymApiUrl = "https://validator.nymtech.net/api";

 export const Traffic = () => {
  const [nym, setNym] = useState<NymMixnetClient>();
@@ -17,27 +21,31 @@ export const Traffic = () => {
  const [recipient, setRecipient] = useState<string>();
  const [payload, setPayload] = useState<Payload>();
  const [receivedMessage, setReceivedMessage] = useState<string>();
+  const [buttonEnabled, setButtonEnabled] = useState<boolean>(false);

  const init = async () => {
    const client = await createNymMixnetClient();
    setNym(client);

+    // start the client and connect to a gateway
    await client?.client.start({
      clientId: crypto.randomUUID(),
      nymApiUrl,
      forceTls: true, // force WSS
    });

+    // check when is connected and set the self address
    client?.events.subscribeToConnected((e) => {
      const { address } = e.args;
      setSelfAddress(address);
    });

+    // show whether the client is ready or not
    client?.events.subscribeToLoaded((e) => {
-      console.log('Client ready: ', e.args);
+      console.log("Client ready: ", e.args);
    });

-
+    // show message payload content when received
    client?.events.subscribeToTextMessageReceivedEvent((e) => {
      console.log(e.args.payload);
      setReceivedMessage(e.args.payload);
@@ -48,7 +56,8 @@ export const Traffic = () => {
    await nym?.client.stop();
  };

-  const send = () => nym.client.send({ payload, recipient });
+  const send = () =>
+    payload && recipient && nym?.client.send({ payload, recipient });

  useEffect(() => {
    init();
@@ -57,9 +66,17 @@ export const Traffic = () => {
    };
  }, []);

+  useEffect(() => {
+    if (recipient && payload) {
+      setButtonEnabled(true);
+    } else {
+      setButtonEnabled(false);
+    }
+  }, [recipient, payload]);
+
  if (!nym || !selfAddress) {
    return (
-      <Box sx={{ display: 'flex' }}>
+      <Box sx={{ display: "flex" }}>
        <CircularProgress />
      </Box>
    );
@@ -67,10 +84,10 @@ export const Traffic = () => {

  return (
    <Box padding={3}>
-      <Paper style={{ marginTop: '1rem', padding: '2rem' }}>
+      <Paper style={{ marginTop: "1rem", padding: "2rem" }}>
        <Stack spacing={3}>
          <Typography variant="body1">My self address is:</Typography>
-          <Typography variant="body1">{selfAddress || 'loading'}</Typography>
+          <Typography variant="body1">{selfAddress || "loading"}</Typography>
          <Typography variant="h5">Communication through the Mixnet</Typography>
          <TextField
            type="text"
@@ -83,15 +100,22 @@ export const Traffic = () => {
            placeholder="Message to send"
            multiline
            rows={4}
-            onChange={(e) => setPayload({ message: e.target.value, mimeType: 'text/plain' })}
+            onChange={(e) =>
+              setPayload({ message: e.target.value, mimeType: "text/plain" })
+            }
            size="small"
          />
-          <Button variant="outlined" onClick={() => send()} disabled={!payload || !recipient} sx={{width: 'fit-content'}}>
+          <Button
+            variant="outlined"
+            onClick={() => send()}
+            disabled={!buttonEnabled}
+            sx={{ width: "fit-content" }}
+          >
            Send
          </Button>
        </Stack>
        {receivedMessage && (
-          <Stack spacing={3} style={{ marginTop: '1rem' }}>
+          <Stack spacing={3} style={{ marginTop: "1rem" }}>
            <Typography variant="h5">Message Received!</Typography>
            <Typography fontFamily="monospace">{receivedMessage}</Typography>
          </Stack>
@@ -9,13 +9,12 @@ import Stack from "@mui/material/Stack";
 import Paper from "@mui/material/Paper";
 import type { SetupMixFetchOps } from "@nymproject/mix-fetch-full-fat";

-const defaultUrl = "https://nym.com/favicon.svg";
+const defaultUrl =
+  "https://nymtech.net/.wellknown/network-requester/exit-policy.txt";
 const args = { mode: "unsafe-ignore-cors" };

 const mixFetchOptions: SetupMixFetchOps = {
-  preferredGateway: "6Gb7ftQdKveMjPyrxDXeAtfYAX7Zg5mVZHtnRC5MmZ1B", // with WSS
-  preferredNetworkRequester:
-    "8rRGWy54oC8drFL9DepMegBt2DLrsqQwCoHMXt9nsnTo.2XjCPVbb4FpQ9hNRcXwb9mTzEAVVk1zf1tcch3wdtNEA@6Gb7ftQdKveMjPyrxDXeAtfYAX7Zg5mVZHtnRC5MmZ1B",
+  preferredGateway: "q2A2cbooyC16YJzvdYaSMH9X3cSiieZNtfBr8cE8Fi1",
  mixFetchOverride: {
    requestTimeoutMs: 60_000,
  },
@@ -0,0 +1,2 @@
+export const ICMP =
+  "ICMP (Internet Control Message Protocol) is a network layer protocol used for sending error messages and operational information regarding network conditions. It is commonly utilized for diagnostic purposes, such as sending ping requests to check the reachability of a host. ICMP helps in managing and controlling network traffic by providing feedback about issues in the communication environment.";
@@ -0,0 +1,3 @@
+export const IPR =
+  "IPR (IP Packet Router) is a component that routes packets to the Internet on behalf of clients within the Nym network. It uses multiplexed streams, NAT, and SURBs for anonymity.";
+
@@ -0,0 +1,93 @@
+import { Callout } from 'nextra/components';
+
+
+## Mixnet: Node Performance Calculation
+
+Performance is a value between `0` and `1`. The final performance number is a result of multiplying [config score](#config-score-calculation) and [routing score](#routing-score-calculation).
+
+<Callout type="info" emoji="📌">
+> **node_performance = config_score \* routing_score**
+</Callout>
+
+Performance value is an average of last 24h.
+
+<Callout>
+All parameters regarding performance score can be browsed or pull live from:
+
+`https://validator.nymtech.net/api/v1/nym-nodes/annotation/<NODE_ID>`
+
+In case you don't know your nodes `NODE_ID`, it's easy to find as long as your node is bonded. Visit [validator.nymtech.net/api/v1/nym-nodes/bonded](https://validator.nymtech.net/api/v1/nym-nodes/bonded) and search your node using `identity_key` or bonding Nyx account address (denoted as `owner`).
+</Callout>
+
+### Config Score Calculation
+
+Config score is in place to ensure that the node configuration is done properly so the node is eligible for taking part in Nym network. The API looks into these paramteres:
+
+1. If the node binary is `nym-node` (not legacy `nym-mixnode` or `nym-gateway`): `1` if `True`, `0` if `False`
+2. If [Terms & Conditions](/operators/nodes/nym-node/setup.mdx#terms--conditions) are accepted: `1` if `True`, `0` if `False`
+3. If the nodes self described endpoint is available: `1` if `True`, `0` if `False`
+4. Version of `nym-node` binary: decreasing weight for outdated versions, as [explained below](#versions-behind-calculation)
+
+**The `config_score` calculation formula:**
+
+<Callout type="info" emoji="📌">
+> **config_score = is_tc_accepted \* is_nym-node_binary \* self_described_api_available \* ( 0.995 ^ ( ( X * versions_behind) ^ 1.65 ) )**
+</Callout>
+
+First three points have binary values of either `0` or `1`, with a following logic:
+
+| **Run `nym-node` binary** | **T&C's accepted** | **Self described available** | **Value** |
+| :--                       | :--                | :--                          | ---:      |
+| **True**                  | **True**           | **True**                     | **1**     |
+| True                      | False              | False                        | 0         |
+| True                      | True               | False                        | 0         |
+| False                     | True               | True                         | 0         |
+| False                     | False              | True                         | 0         |
+| True                      | False              | True                         | 0         |
+| False                     | False              | False                        | 0         |
+| False                     | True               | False                        | 0         |
+
+**Only if ALL conditions above are `True` the node can have any chance to be selected, as otherwise the probability will always be 0.**
+
+<Callout type="info" emoji="ℹ️">
+Besides these values, the API also checks whether the node is bonded in Mixnet smart contract as a Nym Node or legacy node (Mixnode or Gateway). **Only nodes bonded as Nym Node in Mixnet smart contract can be selected to the Rewrded set. Thus, if you haven't migrated your node yet, please [follow these steps](/operators/nodes/nym-node/bonding#migrate-to-nym-node-in-mixnet-smart-contract)!**
+</ Callout>
+
+#### Versions Behind Calculation
+
+From release `2024.14-crunch` (`nym-node v1.2.0`), the `config_score` parameter takes into account also nodes version (denoted as `versions_behind`). The "current version" is the one marked as `Latest` in the [repository](https://github.com/nymtech/nym/releases/). The parameter `versions_behind` indicates the number of versions between the `Latest` version and the version run by the node, and it is factored into the config score with this formula:
+
+<Callout type="info" emoji="📌">
+> **0.995 ^ ( ( X * versions_behind ) ^ 1.65 )**
+>
+> where: <br />
+> **X = 1;       for patches** <br />
+> **X = 10;      for minor versions** <br />
+> **X = 100;     for major versions**
+</Callout>
+
+> The exact parameters are live accessible on [`/v1/status/config-score-details`](https://validator.nymtech.net/api/swagger/index.html#/Status/config_score_details).
+
+Our versioning convention is: `major_version . minor_version . patch`
+
+For example `nym-node` on version `1.2.0` is on 1st major version, 2nd minor and 0 patches.
+
+Note that the `X` multiplier heavily lowers the `config_score` when nodes are outdated with respect to more significant updates. See the the table and graph below:
+
+| **Version behind**  | **Patches (X = 1)** | **Minor versions (X = 10)** | **Major versions (X = 100)** |
+| :--                 | --:       | --: | --: |
+| 0 (current version) | 1.0 | 1.0 | 1.0 |
+| 1 | 0.995 | 0.7994 | 0.0000 |
+| 2 | 0.9844 | 0.4953 | 0.0000 |
+| 3 | 0.9698 | 0.2536 | 0.0000 |
+| 4 | 0.9518 | 0.1102 | 0.0000 |
+| 5 | 0.9311 | 0.0413 | 0.0000 |
+
+
+![](/images/operators/tokenomics/reward_version_graph.png)
+
+As you can see above, the algorithm is designed to give maximum selection score (`1`) to the latest version, while non-upgraded nodes receive a lower score. The score decreases faster when the node has failed to make a major version upgrade, and slower when the node is behind only with minor updates. This scoring de-prioritizes the selection of outdated nodes, even if their saturation and performance are high. Nodes are selected probabilistically in each epoch (60 min), according to their scores, to be part of the Rewarded set. This scoring mechanism gives priority to the operators running up-to-date nodes, ensuring that the network is as updated as possible.
+
+### Routing Score Calculation
+
+Routing score is measured by Nym Network Monitor which sends thousands of packages through different routes every 15 minutes and measures how many were dropped on the way. Test result represents percentage of packets succesfully returned which are then converted into floats bettween `0` and `1`.
@@ -0,0 +1,223 @@
+import { Callout } from 'nextra/components';
+import { Steps } from 'nextra/components';
+import { Green, Yellow, Red, Gray } from 'components/severity.jsx'
+import { IPR } from 'components/operators/snippets/ipr.js';
+import { ICMP } from 'components/operators/snippets/icmp.js';
+
+## WireGuard: Gateways Performance Calculation
+
+> If you are looking for a page with a guide to run your own `gateway-probe` instance, go [here](/operators/performance-and-testing/gateway-probe).
+
+<Callout type="info" emoji="ℹ️">
+**Note that there is only one binary `nym-node` for [all network functionalities](/operators/nodes/nym-node/setup#functionality-mode) (defined by a positional argument `--mode`).**
+
+When we say *Exit Gateway* in connection to Wireguard, we talk about a `nym-node` running in a mode Exit Gateway (`--mode exit-gateway`) with Wireguard enabled. Such node is listed in [NymVPN application](https://nym.com) as an Exit Gateway and an Entry Gateway for both dVPN (2-hop) and Mixnet (5-hop) options. That's because every Exit Gateway can serve as an Entry, not vice versa for Mixnet and every Gateway with Wireguard enabled option (`--wireguard-enabled true`) can always serve as both Entry and Exit for dVPN (provided that they are correctly [configured](/operators/nodes/nym-node/configuration)).
+</Callout>
+
+**Please note that even the most perfectly configured Gateway, running on the strongest machine may not always be listed as a suggested node in the app. If you are interested to learn the details why, check out the [Gateway Probe Details page](/operators/performance-and-testing/gateway-probe-details).**
+
+### Summary
+
+A simplified explanation of node performance measuring is that the [Node Status API](https://node-status.nym.com) runs [gateway probes](/operators/performance-and-testing/gateway-probe) that connect to gateways to:
+
+- Check the configuration of gateways
+  - Checks a list of capabilities (e.g. can route IPv4 traffic in mixnet mode)
+  - Checks a list of configuration (e.g. runs <abbr title={IPR}>IPR</abbr>, has exit policy)
+- Acts like a user:
+  - Registers a mixnet client
+  - Registers a wireguard peer and tops up bandwidth with a zk-nym
+  - Sends <abbr title={ICMP}>ICMP</abbr> ping packets
+  - Downloads files
+
+The results are collected and stored in the [Node Status API](https://node-status.nym.com) and can be also veiwed per node in [Node Status Observatory](https://harbourmaster.nymtech.net).
+
+The [NymVPN API directory](https://nymvpn.com/api/public/v1/directory/gateways) cache uses the output of the gateway probes to calculate and display hints to users about the contention on each gateway and what they might expect if they use the gateway. The section [*Gateway Roles & Requirements* below](#gateway-roles--requirements) explains how are these stats measured and what is their significance.
+
+### Performance Score
+
+Gateways are listed in NymVPN application displaying various stats.
+
+![](/images/operators/nym-vpn-sceenshots/nym-vpn-score1.png)
+
+There are four colored score bars.
+
+![](/images/operators/nym-vpn-sceenshots/nym-vpn-score2.png)
+
+This is how they are defined:
+
+<Steps>
+
+###### 1. Overall performance: 
+
+Calculated by mixnet performance score multiplied by WireGuard performance, this is the formula: 
+<Callout type="info" emoji="📌">
+> **mixnet_performance * (download_speed_score * ping_ips_performance_v4)**
+</Callout>
+- <Green>High</Green>: `> 75%`
+- <Yellow>Medium</Yellow>: `> 50%`
+- <Red>Low</Red>: > `10%`
+- <Gray>Offline</Gray>: `≤ 10%`
+
+- **Download speed scoring:** 
+<Callout type="info" emoji="📌">
+> **\> 5 Mbps = 1.0** <br />
+> **\> 2 Mbps = 0.75** <br />
+> **\> 1 Mbps = 0.5** <br />
+> **\> 0.5 Mbps = 0.25** <br />
+> **otherwise = 0.1**
+</Callout>
+
+###### 2. Server Load:
+
+A load indicator based on ping success
+
+- <Green>Low</Green>: `> 80%` ping success (low load)
+- <Yellow>Medium</Yellow>: `> 40%` ping success (medium load)
+- <Red>High</Red>: `≤ 40%` ping success (node under stress, high load)
+
+###### 3. Uptime:
+
+A routing score of Mixnet (5-hop) is indicated this way:
+- <Green>High</Green>: `> 80%` mixnet packet delivery success
+- <Yellow>Medium</Yellow>: `> 60%` mixnet packet delivery success
+- <Red>Low</Red>: `> 10%` mixnet packet delivery success
+- <Gray>Offline</Gray>: `≤ 10%` mixnet packet delivery success
+
+</Steps>
+
+Note that there are caches in place to keep various dept of details to provide info for different pieces of the software. Their timing differs and it can lead to small discrepancies of outcome in between multiple clients observed by users at the same time.
+
+See the [*Gateway Roles & Requirements*](#gateway-roles--requirements) to understand how these stats get measured.
+
+<Callout>
+You can find more details [directly in the code](https://github.com/nymtech/nym-vpn-client/blob/develop/nym-vpn-app/src/hooks/useScore.ts#L10).
+</Callout>
+
+### Gateway Roles & Requirements
+
+A node configuration break down coming alongside basic [server configuration](/operators/nodes/preliminary-steps/vps-setup) required for the nodes in specific roles:
+
+- **Entry Gateway - Mixnet:**
+    - Node configured (running with `--mode` argument) as `entry-gateway` or `exit-gateway` (as Exit works as Entry too)
+    - `WS/WSS` ports (9000/9001) accessible
+    - [IPv6 configured](/operators/nodes/nym-node/configuration#quick-ipv6-check)
+- **Exit Gateway - Mixnet:**
+    - Node configured (running with `--mode` argument) as `exit-gateway`, that configuration ensures that:
+        - <abbr title={IPR}>IPR</abbr> address present
+        - NR address present
+    - [IPv6 configured](/operators/nodes/nym-node/configuration#quick-ipv6-check)
+    - NymTun configured - using [NetworkTunnelManager](/operators/nodes/nym-node/configuration#routing-configuration)
+
+- **Entry & Exit Gateway - dVPN (WireGuard mode):**
+    - Node configured as Wireguard node: `--wireguard-enabled true`
+    - Authenticator address present
+    - NymWG configured - using [NetworkTunnelManager](/operators/nodes/nym-node/configuration#routing-configuration)
+    - [Metadata port open for WG](/operators/nodes/nym-node/configuration#fixing-metadata-port-showing-not-open-in-probe-results)
+    - Wireguard exit policy [configured](/operators/nodes/nym-node/configuration#wireguard-exit-policy-configuration)
+    - [IPv6 configured](/operators/nodes/nym-node/configuration#quick-ipv6-check)
+    - Recommended: [QUIC bridge setup](/operators/nodes/nym-node/configuration#quic-transport-bridge-deployment)
+
+### How Probe Works
+
+Nym Gateway probe is perfomance measurement program running tests through various routes. Operators can run their [local instance of Gateway probe](/operators/performance-and-testing/gateway-probe) or use visit of our dashboards to conveniently see probe results.
+
+- [Node Status dashboard](https://node-status.nym.com/dvpn): Shows latest probe results on one board
+- [Nym Node Status Observatory](https://harbourmaster.nymtech.net): New version of a good old Nym Harbourmaster, allowing operators preview stats of each node
+
+The following sections explain what is measured in order to collect stats to the [API enpoint](https://nymvpn.com/api/public/v1/directory/gateways) and in the section [*Complete Setup Checklist*](#complete-setup-checklist) below you can see the order of measurements.
+
+#### Entry Gateway - Mixnet (5-hop)
+
+**Tests:**
+
+- `can_connect`: Can connect to client WS/WSS endpoint (ports 9000/9001)
+- `can_route`: Entry gateway correctly forwards packets into the mixnet
+
+**To Pass:**
+
+- Expose correct `WS` and or `WSS` ports (`9000`/ `9001`)
+- Ensure DNS A/AAAA records resolve correctly
+- Verify IPv6 is actually reachable (not just in DNS)
+- Keep node online and monitor packet loss
+
+#### Exit Gateway (IPR) - Mixnet (5-hop)
+
+**Tests:**
+
+- `can_connect`: Can connect to <abbr title={IPR}>IPR</abbr>
+- `can_route_ip_v4`: IPv4 routing works
+- `can_route_ip_external_v4`: IPv4 routing to external internet works
+- `can_route_ip_v6`: IPv6 routing works
+- `can_route_ip_external_v6`: IPv6 routing to external internet works
+
+**To Pass:**
+
+- Ensure upstream routing and NAT allow both IPv4 and IPv6 traffic to external internet
+- Check system firewall rules (bidirectional)
+- Confirm outbound reachability to common external hosts on both stacks
+- Run node with `mode=exit-gateway` - this by default includes entry-gateway mode.
+
+#### Gateways - WireGuard (dVPN / 2-hop)
+
+**Tests:**
+
+- `can_register`: Authentication flow completes successfully
+- `can_handshake`: WireGuard handshake succeeds
+- `can_resolve_dns`: DNS resolution works
+- `can_query_metadata_v4`: Can query metadata endpoint
+- `ping_hosts_performance` / `ping_ips_performance`: Latency and packet loss metrics
+
+**To Pass:**
+
+- Open WireGuard UDP port `51822` (public)
+- Ensure metadata TCP port `51830` is accessible inside the WireGuard tunnel (at `10.1.0.1:51830`) for bandwidth queries/topup
+- Keep QUIC bridge (`UDP 4443`) healthy if deployed
+- Reduce server latency/jitter (depends on provider and location)
+- Ensure DNS resolvers are reliable
+- Pass the `--wireguard-enabled true` flag in the node config
+
+### Probe Freshness
+
+- Probes run continuously; each node is typically tested every ~2 hours
+- If a probe fails or times out, the gateway will have stale probe data until the next successful probe completes
+- `last_updated_utc`: Timestamp indicating when the last successful probe test completed
+
+See [*Complete Setup Checklist*](#complete-setup-checklist) to understand the order of tests.
+
+### Complete Setup Checklist
+
+**If one test fails, the following points don't get checked!**
+
+#### On-Chain & Configuration
+
+- [ ] [Bonded on-chain](/operators/nodes/nym-node/bonding) with [correct role](/operators/nodes/nym-node/setup#functionality-mode) (`exit-gateway`) and correct ports opened exposed
+- [ ] Self-description endpoint is reachable
+- [ ] [T&Cs accepted](/operators/nodes/nym-node/setup#terms--conditions)
+
+#### Network & Ports
+
+- [ ] **Mixnet**: Port `1789` (mixnet) accessible; ports `9000` (`WS`) and `9001` (`WSS`) accessible with valid [TLS for WSS](/operators/nodes/nym-node/configuration/proxy-configuration#reverse-proxy-configuration)
+- [ ] [**QUIC bridge**](/operators/nodes/nym-node/configuration#quic-transport-bridge-deployment) (if used): UDP 4443 with valid addresses and SNI host
+- [ ] [**WireGuard**](/operators/nodes/nym-node/configuration#routing-configuration): `UDP 51822` open (public); `TCP 51830` accessible [inside WireGuard tunnel](/operators/nodes/nym-node/configuration#fixing-metadata-port-showing-not-open-in-probe-results) (`10.1.0.1:51830`); `--wireguard-enabled true` set in node config
+- [ ] **Exit (<abbr title={IPR}>IPR</abbr>)**: [IPv4 and IPv6](/operators/nodes/nym-node/configuration#routing-configuration) routing to external internet configured
+- [ ] **DNS**: A/AAAA records correct; IPv6 actually reachable (test, don't just add DNS)
+
+#### Performance Targets
+
+- [ ] Achieve `≥ 60%` mixnet performance (Medium)
+- [ ] Aim for `≥ 80%` (High) for optimal visibility
+- [ ] Keep latency and packet loss low (excessive load reduces performance scores)
+- [ ] Keep uptime high (network monitor tracks this)
+
+#### Probe Results (Verify All Pass)
+
+- [ ] Entry: `can_connect=true` and `can_route=true`
+- [ ] Exit: `can_connect=true` and all v4/v6 routing flags are `true`
+- [ ] WireGuard: `can_register`, `can_handshake`, `can_resolve_dns`, and `can_query_metadata_v4` all pass; ping metrics good
+
+#### Recommended
+
+- [ ] [WSS enabled](/operators/nodes/nym-node/configuration/proxy-configuration) (connections may fail on clients if only WS is available)
+- [ ] [QUIC bridge](/operators/nodes/nym-node/configuration#quic-transport-bridge-deployment) operational (ensures your node appears when users enable QUIC only filter on the app)
+- [ ] Accurate geo/IP information (country/region/residential filters rely on this)
+- [ ] Stay on most recent supported binary version - [old versions are penalised](/operators/performance-and-testing#versions-behind-calculation)
@@ -12,17 +12,20 @@ Operators can use [Nym Bridge Configuration Tool](https://github.com/nymtech/nym

 **We recommend a more convenient QUIC bridge deployment using a script [`quic_bridge_deployment.sh`](https://github.com/nymtech/nym/blob/develop/scripts/nym-node-setup/quic_bridge_deployment.sh), following the steps below.**

+<Callout type="warning" emoji="⚠️">
+This script assumes that you follow the convention of running a `nym-node` as `root`. In case you run as a [non-root user](/operators/nodes/nym-node/configuration#running-nym-node-as-a-non-root), please follow [manual QUIC bridge setup](https://github.com/nymtech/nym-bridges/blob/main/README.md) and ask for support in the [Matrix channel](https://matrix.to/#/#operators:nymtech.chat).
+</Callout>
+
 <Steps>
 ###### 1. Download [`quic_bridge_deployment.sh`](https://github.com/nymtech/nym/blob/develop/scripts/nym-node-setup/quic_bridge_deployment.sh) script
 - SSH to your server
 - **Run as root**
 - Download the script and make executable
 ```sh
-wget https://raw.githubusercontent.com/nymtech/nym/refs/heads/develop/scripts/nym-node-setup/quic_bridge_deployment.sh && \
+curl -L https://raw.githubusercontent.com/nymtech/nym/refs/heads/develop/scripts/nym-node-setup/quic_bridge_deployment.sh -o quic_bridge_deployment.sh && \
 chmod +x quic_bridge_deployment.sh
 ```

-
 ###### 2. Run the script with `full_bridge_setup` command
 - Optional: open `tmux` in case you will need to run another commands on the VPS
 - Run the script with a command `full_bridge_setup`
@@ -1 +1 @@
-Friday, October 31st 2025, 12:04:05 UTC
+Thursday, November 13th 2025, 11:23:33 UTC
@@ -11,7 +11,7 @@ options:
  --no_routing_history  Display node stats without routing history
  --no_verloc_metrics   Display node stats without verloc metrics
  -m, --markdown        Display results in markdown format
-  -o [OUTPUT], --output [OUTPUT]
+  -o, --output [OUTPUT]
                        Save results to file (in current dir or supply with
                        path without filename)
 ```
@@ -0,0 +1,12 @@
+export const Green = ({ children }) => (
+  <span style={{ color: '#22C55E', fontWeight: 600 }}>{children}</span>
+);
+export const Yellow = ({ children }) => (
+  <span style={{ color: '#FACC15', fontWeight: 600 }}>{children}</span>
+);
+export const Red = ({ children }) => (
+  <span style={{ color: '#EF4444', fontWeight: 600 }}>{children}</span>
+);
+export const Gray = ({ children }) => (
+  <span style={{ color: '#6B7280', fontWeight: 600 }}>{children}</span>
+);
@@ -13,6 +13,7 @@ import TextField from "@mui/material/TextField";
 import Button from "@mui/material/Button";

 const nymApiUrl = "https://validator.nymtech.net/api";
+const preferredGateway = "q2A2cbooyC16YJzvdYaSMH9X3cSiieZNtfBr8cE8Fi1";

 export const Traffic = () => {
  const [nym, setNym] = useState<NymMixnetClient>();
@@ -31,6 +32,7 @@ export const Traffic = () => {
      clientId: crypto.randomUUID(),
      nymApiUrl,
      forceTls: true, // force WSS
+      preferredGateway,
    });

    // check when is connected and set the self address
@@ -1108,22 +1108,22 @@ const config = {
        form-action 'self';
        frame-ancestors 'none';
        upgrade-insecure-requests;
-        connect-src 'self' https://github.com *.vercel.app *.nymtech.net *.nymvpn.com *.nymte.ch *.nyx.network *.nym.com https://nym.com nymvpn.com https://nymvpn.com *.nymtech.cc;
+        connect-src 'self' wss://nym-node-cli.devrel.nymte.ch:9001 https://github.com *.vercel.app *.nymtech.net *.nymvpn.com *.nymte.ch *.nyx.network *.nym.com https://nym.com nymvpn.com https://nymvpn.com *.nymtech.cc;
        frame-src 'self' https://vercel.live *.vercel.app *.nym.com https://nym.com;
        worker-src 'self' blob: https://vercel.live *.vercel.app *.nym.com https://nym.com;
      `;
    return [
      {
-        source: '/(.*)',
+        source: "/(.*)",
        headers: [
          {
-            key: 'Content-Security-Policy',
+            key: "Content-Security-Policy",
            value: csp.replace(/\s{2,}/g, " ").trim(),
-          }
-        ]
-      }
-    ]
-  }
+          },
+        ],
+      },
+    ];
+  },
 };

 module.exports = config;
@@ -38,8 +38,8 @@
    "@nextui-org/accordion": "^2.0.40",
    "@nextui-org/react": "^2.4.8",
    "@nymproject/contract-clients": ">=1.2.4-rc.2 || ^1",
-    "@nymproject/mix-fetch-full-fat": ">=1.2.4-rc.2 || ^1",
-    "@nymproject/sdk-full-fat": ">=1.2.4-rc.2 || ^1",
+    "@nymproject/mix-fetch-full-fat": ">=1.5.1-rc.0 || ^1.4.1",
+    "@nymproject/sdk-full-fat": ">=1.5.1-rc.0 || ^1.4.1",
    "@redocly/cli": "^1.25.15",
    "@types/mdx": "^2.0.13",
    "chain-registry": "^1.19.0",
@@ -11,8 +11,8 @@
    "type": "menu",
    "items": {
      "developers": {
-        "title": "Developer Overview",
-        "href": "/developers/"
+        "title": "Integrations",
+        "href": "/developers/integrations"
      },
      "rust": {
        "title": "Rust SDK",
@@ -1,18 +1,28 @@
 {
  "index": "Introduction",
-  "concepts": "Core Concepts",
-  "binaries": "Binaries",
-  "integrations": "Integration Options",
-  "clients": "Clients",
-  "tools": "Tools",
-  "nymvpncli": "Nym VPN CLI",
-  "chain": "Interacting with Nyx",
  "--": {
-    "type": "separator"
+    "type": "separator",
+    "title": "Mixnet Integrations"
+  },
+  "integrations": "Overview - Start Here!",
+  "native": "Native Apps",
+  "browsers": "Browser Apps",
+  "concepts": "Nym-Specific Concepts for Integrations",
+  "-": {
+    "type": "separator",
+    "title": "SDKs"
  },
  "rust": "Rust SDK",
  "typescript": "Typescript SDK",
  "---": {
+    "type": "separator",
+    "title": "Misc"
+  },
+  "chain": "Interacting with Nyx Blockchain",
+  "tools": "Tools",
+  "nymvpncli": "Nym VPN CLI",
+  "clients": "Standlone Clients",
+  "----": {
    "type": "separator"
  },
  "archive": "Archive",
@@ -0,0 +1,40 @@
+import { Callout } from 'nextra/components';
+
+# Browser-Based Apps
+Browsers are a very restricted environment to work in, with limited options for external communications (websockets, Web Transport API, WebRTC), mixed content restrictions (HTTPS-only), and no access to the file system or any syscalls. These aside, the main issue when trying to capture traffic and send it via a different transport - such as the Mixnet - is the lack of access to browser TLS negotiation from JS or the CA certificate store.
+
+This means that the functionality offered by our current browser-based solutions are quite restricted / specific. There are currently two options for interacting with the Mixnet from the browser: `mixFetch`, and the WASM SDK.
+
+![](/images/developers/nym-browser-arch.png)
+
+Both `mixFetch` and the WASM client are delivered to the client bundled into a web application.
+
+## mixFetch
+Drop-in replacement for browser's `fetch` API that makes HTTP(S) requests via Exit Gateways using the SOCKS Network Requester.
+
+Uses an embedded CA certificate store to establish TLS session between `mixFetch` and the remote host, creating a client-host secure channel from the browser to the host over the Mixnet.
+
+Internally it uses the WASM client.
+
+- [docs](./typescript/start#mixfetch)
+- [example](./typescript/playground/mixfetch)
+
+<Callout type="warning">
+
+    ### Current Limitations of `mixFetch`
+
+    It cannot currently handle concurrent requests, and comes with a pre-bundled CA store. `mixFetchv2` - which will act more like a general-purpose userspace IP stack - is currently in development.
+</Callout>
+
+
+## WASM Client
+Makes Sphinx packets and cover traffic using WASM and sent over a Websocket to the Entry Gateway and receive responses.
+
+This only works in messaging mode (i.e. messages sent either as text or binary data), and currently doesn’t support making IP packets that are routed to the Internet by an Exit Gateway IPR, nor does it currently expose any stream-like API. If you want to send HTTP(S) requests, use `mixFetch`.
+
+Note that the limitations of CSPs and Mixed Content restrictions (i.e HTTPS only) apply to the Websocket connection as normal in browsers or embedded WebViews.
+
+Runs in a web worker to leave UI thread free for the user.
+
+- [docs](./typescript/start#mixnet-client)
+- [example](./typescript/playground/traffic)
@@ -1,5 +1,4 @@
 {
-  "socks5": "Socks5 (standalone)",
-  "webassembly-client": "Webassembly Client",
-  "websocket": "Websocket (standalone)"
+  "socks5": "SOCKS Proxy",
+  "websocket": "Websocket"
 }
@@ -1,6 +0,0 @@
-{
-  "required-architecture": "Required Architecture",
-  "messages": "Message Based Paradigm",
-  "message-queue": "Message Queue",
-  "credentials": "Credentials"
-}
@@ -1,5 +1,11 @@
+import { Callout } from 'nextra/components'
+
 # Message Queue

+<Callout type="info">
+    Although good to understand how the Nym Client works under the hood, this information is only of practical use if you're using the `Mixnet` module of the RustSDK and interacting with the SDK Mixnet Client at a low level. This is all mostly abstracted away with the `MixSocket`, `MixStream`, and `IpMixStream` abstractions.
+</Callout>
+
 ## Sphinx Packet Streams
 Clients, once connected to the Mixnet, **are always sending traffic into the Mixnet**; as well as the packets that you as a developer are sending from your application logic, they send [cover traffic](../../network/concepts/cover-traffic) at a constant rate defined by a Poisson process. This is part of the network's mitigation of timing attacks.

@@ -1,31 +0,0 @@
-# Message-based Paradigm
-
-## Message Format
-For the moment, Mixnet clients work assuming they will be piped atomic messages looking something like this:
-
-```
-MixnetMessage {
-  Message: Message_Bytes,
-  To: Nym_Address,
-  Attached_SURBS: Number_Of_Surbs
-}
-```
-
-That the client will then encrypt as Sphinx packets and send through the Mixnet.
-
-Likewise, they assume that once they have received and decrypted a Sphinx packet, they will kick back a reconstructed message to the rest of your app logic that look something like:
-
-```
-ReconstructedMessage {
-  Message: Message_Bytes,
-  From: SURB_Sender_Tag
-}
-```
-
-This is obviously quite different to e.g. simply being able to read/write from a stream returned from a function call to create a TCP connection, but there are several approaches that developers can take to dealing with this right now.
-
-## Message Abstractions
- Rust/Go (and soon C++) developers can use the `TcpProxy` [stream abstraction](../rust/tcpproxy).
- Developers who are using Typescript/Javascript can also avoid having to deal directly with messages via using [MixFetch](../typescript/examples/mix-fetch).
- As can developers who are bundling and running the standalone [socks5 client](../clients/socks5) using some form of init script.
- There is a seperate pair of binaries which other developers can use to run as a persistent secondary proxy process built using the `TcpProxy` abstraction. These simply expose a `localhost` socket port to pipe traffic to and from in the same way as you would a TCP connection and can be found [here](https://github.com/nymtech/standalone-tcp-proxies).
@@ -1,7 +1,2 @@
 # Introduction
 Nym's developer documentation covering core concepts of integrating with the Mixnet, interacting with the Nyx blockchain, an overview of the avaliable tools, and our SDK docs.
-
-## Where to Start?
-If you are completely new to Nym, it is suggested to start with the top sections covering the core concepts, integration options, and the clients and tools available to you.
-
-If you feel like starting with more practical examples, check out the relevent SDK docs in the sidebar to the left.
@@ -1,40 +1,16 @@
-import Box from '@mui/material/Box';
-import { Steps } from 'nextra/components'
-import { Tabs } from 'nextra/components'
-import { GitHubRepoSearch } from '../../code-snippets/mixfetchurl';
+import { Callout } from 'nextra/components';

-# Integration Options
-Developers might want to either integrate a Mixnet client or just to interact with the blockchain. See the relevant section below.
+# Integrating With Nym
+Any application that wants to integrate with Nym involves sending its application traffic through the Mixnet using one of the available Nym Clients. There is no single solution for this, as different environments offer different access and transport options (e.g. if operating in a web browser, you do not have access to syscalls or sockets, have to deal with content security policies, etc).

-## Integrating Mixnet Functionality
-There are several options available to developers wanting to embed a Nym client in their application code.
+As such, we have several solutions available for developers to choose from depending on the **environment** their application is expected to run in: native apps which are running on a desktop, or webapps running in a browser.

-<Tabs items={['Rust/Go/C++', 'Typescript/Javascript','Other']}>
-  <Tabs.Tab >
-    <>
+<Callout type="info" emoji="ℹ️">
+    The list of current options available to developers to do not cover all environments and setups - we are working on expanding this list and approaching more general solutions, but there is no one-size-fits-all approach when dealing with rerouting network traffic.
+</Callout>

-    Rust developers can rely on our Rust SDK to import Nym client functionality into their code. This can either be in the form of a standard message-based client, the `socks5` client, or the `TcpProxy` modules.
+Integration options are then further subdivided by app **architecture**; whether the application interacts with remote hosts on the public internet running independently of the app (e.g. public blockchain RPC endpoints, third-party APIs) or whether app developers have some control over the versions of the software being run on both sides of an interaction (e.g. peer to peer apps running the same software version, or client-server architectures which are running software written by the same team).

-      We aim to expose at least the majority of this functionality via FFI to Go and C/C++. This is detailed alongside the Rust SDK components in the [Rust SDK docs](./rust).
-
-    </>
-  </Tabs.Tab>
-  <Tabs.Tab>
-  <>
-
-  Typescript and Javascript developers have several options avaliable to them:
-      - [`mixfetch`](./typescript/examples/mix-fetch) is an almost-dropin replacement for the `fetch` library. The best way to integrate Nym's `mixFetch` into your application will be where external network calls and RPC happens, for example, something in the lines of `sendRawTransaction` if you have an ETH-compatible wallet or `JsonRpcClient` if you use CosmJS. Although you can simply search for any JS `fetch` calls in your code (using our tool below) that are easily replaceable with `mixFetch`, keep in mind that `fetch` is not the only way to make `JSONRPC` or `XHR` calls. We advise to approach the integration process in a semantic way, searching for a module that is the common denominator for external communication in the codebase. Usually these are API controllers, middlewares or repositories.
-
-    <GitHubRepoSearch />
-
-    - Otherwise, a well-modularized JS/TS codebase should permit the integration of one of our other SDK components, which will allow more flexibility and control (or if your codebase is not using something that can be covered by `fetch` for networking). Read more about our different SDK components in the [TS SDK overview page](./typescript/overview).
-
-    </ >
-  </Tabs.Tab>
-  <Tabs.Tab> If your app is not written in any of the supported languages, you might still be able to send traffic through a standalone [socks5 client](./clients/socks5) but will have to think about packaging and bundling the client binary with e.g. a `systemd` file for autostart to run the client as a daemon. If you want to discuss FFI options reach out to us via our public dev channel. </Tabs.Tab>
-</Tabs>
-
-## Interacting with Nyx
-If instead of relying on the Mixnet you wish to interact with the Nyx chain, either as a payment processor or to get on-chain events, see [interacting with the chain](./chain).
-
-> Note that depending on your setup, you might already be able to combine interacting with the chain with using the Mixnet: check the options above for more.
+<Callout type="info" emoji="ℹ️">
+    This is because of the different security considerations each option offers. These are detailed in the following pages.
+</Callout>
@@ -0,0 +1,86 @@
+import { Callout } from 'nextra/components';
+
+# Native / Desktop Apps
+
+Developers wanting to integrate into desktop apps & CLIs can use our Rust SDK. There are two broad approaches to using the Mixnet (E2E or as a proxy), with different modules suited for each, each with their own specific usecase and limitations.
+
+## Option 1: Mixnet End-To-End
+You might want to embed Nym Clients in both sides of your app, and have them send all of your app network traffic through the Mixnet: maybe two clients in a peer to peer setup, or a client and a server where it is possible for you as a developer to release both the client and server side code, and have some ability to make sure that it is being run.
+
+![](/images/developers/nym-arch-client-to-client.png)
+
+There are several options available:
+
+{ /* ### Stream Wrapper Module
+Exposes `MixSocket`/`MixStream` abstractions that can be split a reader/writer halves that consumes bytes, with an interface inspired by `std::net::TcpStream`. For developers who just want to read/write bytes to/from the Mixnet working with something socket-like.
+
+- docs TODO LINK
+- example TODO LINK */ }
+
+### Mixnet & Client Pool Modules
+The Mixnet module of the SDK exposes low level connection functionality and the Mixnet Client. The Client Pool is one answer to concurrency, and allows developers to run several Nym Clients at once which can be quickly used.
+
+{ /* This approach might be useful if you want to build custom connection logic, but **`MixSocket`/`MixStream` will probably be sufficient for the majority of usecases** where developers just want to send and receive traffic as streams. */ }
+
+This approach might be useful if you want to build custom connection logic, but the TcpProxy Module will probably be sufficient for the majority of usecases where developers just want to send and receive traffic as streams.
+
+- [docs](./rust/mixnet)
+- [examples](./rust/mixnet/examples)
+
+### TcpProxy Module
+{ /* <Callout type="warning" emoji="⚠️">
+    This module has been superseded by the Stream Wrapper module, and will soon be deprecated. **New features will not be added to it.** The main drawback of this (which is fixed with `MixSocket`/`MixStream`) is that TLS is impossible, as it exposes a localhost port for the consuming process to communicate with.
+</Callout> */ }
+A pair of abstractions built for use in a client-server setup, which both expose a `localhost` TCP Socket which apps can read/write bytes to/from.
+
+- [docs](./rust/tcpproxy)
+- [examples](./rust/tcpproxy/examples/singleconn)
+
+<Callout type="info" emoji="ℹ️">
+    There is a new abstraction coming soon mirroring the interface and use of a TCP Socket, making it easier for developers to use the Mixnet, and also perform TLS through a Mixnet connection. Stay tuned.
+</Callout>
+
+## Option 2: Mixnet-As-Proxy
+For developers who are only able to control the client-side code, and/or need to communicate with a 3rd party service, such as a public blockchain RPC or a remote host they do not control.
+
+![](/images/developers/nym-arch-ip-routing.png)
+
+<Callout type="warning">
+
+    ### Security Considerations
+
+    Since traffic is only packaged as Sphinx until it gets to the Exit Gateway, where it is unwrapped into either HTTPS packets (by a Network Requester) or IP packets (by an IP Packet Router), the last hop between the Gateway and the remote host **travels as normal internet traffic**.
+
+    As such, this option has fewer protections than the E2E option against a global passive adversary, but still grants you timing obfuscation and sender-receiver unlinkability between your client software and whatever service it is interacting with.
+</Callout>
+
+### SOCKS Client
+Developers with apps that support SOCKS4,4a, or 5 can use the Socks Client exposed by the Mixnet module. This uses the Network Requester service of the chosen Exit Gateway to interact with the remote host via the chosen SOCKS proxy protocol. The Network Requester uses SURBs to anonymously reply to the original sender with whatever response it gets from the remote host.
+
+- [docs](./rust/mixnet/examples/socks)
+- [example](./rust/mixnet/examples/socks)
+
+<Callout type="info" emoji="ℹ️">
+    There is a new abstraction coming soon that will allow the SDK to send IP packets, the beginning of a longer project to make a native Rust version of [`mixFetch`](./typescript/start#mixfetch). Stay tuned.
+</Callout>
+
+
+{ /* ### `IPMixStream`
+This is a version of the `MixSocket` that consumes IP packets before wrapping them in Sphinx and forwarding through the Mixnet to the IP Packet Router of the chosen Exit Gateway, where they are unwrapped and treated as normal IP packets. The IPR uses SURBs to anonymously reply to the original sender with whatever response it gets from the remote host.
+
+<Callout type="info" emoji="ℹ️">
+    Currently only consumes IP packets - those who do not want to work with IP packets directly should check `mixtcp` below for doing something with HTTP(S).
+</Callout>
+
+- docs TODO LINK
+- examples TODO LINK
+
+### `MixTCP`
+A proof of concept TCP/IP crate containing a [`smoltcp`](https://docs.rs/smoltcp/latest/smoltcp/index.html) `device` that uses the Mixnet for transport. Examples of using this to make a TLS handshake and perform an HTTPS request can be found linked below.
+
+<Callout type="info" emoji="ℹ️">
+    This crate is currently a proof of concept which is in active development. This crate will become the basis of a general-purpose HTTP-through-Mixnet crate in the near future.
+</Callout>
+
+- docs TODO LINK
+- example TODO LINK */ }
@@ -1,16 +1,3 @@
 # Introduction

-
-import { Callout } from 'nextra/components';
-
-<Callout type="warning">
-  There will be a breaking SDK upgrade in the coming months. This upgrade will make the SDK a lot easier to build with.
-
-This upgrade will affect the interface of the SDK dramatically, and will be coupled with a protocol change - stay tuned for information on early access to the new protocol testnet.
-
-It will also be coupled with the documentation of the SDK on [crates.io](https://crates.io/).
-</Callout>
-
-The Rust SDK allows developers building applications in Rust to import and interact with Nym clients as they would any other dependency, instead of running the client as a separate process on their machine.
-
-Check the [development status](./rust/development-status) page to see the various modules that make up the SDK, and the [FFI](./rust/ffi) page for Go/C++ developers.
+The Rust SDK allows exposes a few different modules, some more plug and play than others. Each of which handles exposes a Nym Client, which handles finding and using a route for packets through the Mixnet, encryption, and cover traffic, all under the hood.
@@ -1,8 +1,7 @@
 {
  "importing": "Importing",
-  "development-status": "Development Status",
-  "mixnet": "Mixnet Module",
  "tcpproxy": "TcpProxy Module",
-  "client-pool": "Client Pool",
+  "mixnet": "Mixnet Module",
+  "client-pool": "Client Pool Module",
  "ffi": "FFI"
 }
@@ -2,15 +2,6 @@

 import { Callout } from 'nextra/components';

-<Callout type="warning">
-  There will be a breaking SDK upgrade in the coming months. This upgrade will make the SDK a lot easier to build with.
-
-This upgrade will affect the interface of the SDK dramatically, and will be coupled with a protocol change - stay tuned for information on early access to the new protocol testnet.
-
-
-It will also be coupled with the documentation of the SDK on [crates.io](https://crates.io/).
-</Callout>
-
 We have a configurable-size Client Pool for processes that require multiple clients in quick succession (this is used by default by the [`TcpProxyClient`](./tcpproxy) for instance)

 This will be useful for developers looking to build connection logic, or just are using raw SDK clients in a sitatuation where there are multiple connections with a lot of churn.
@@ -2,17 +2,6 @@
 # FFI Bindings
 import { Callout } from 'nextra/components';

-<Callout type="warning">
-  There will be a breaking SDK upgrade in the coming months. This upgrade will make the SDK a lot easier to build with.
-
-This upgrade will affect the interface of the SDK dramatically, and will be coupled with a protocol change - stay tuned for information on early access to the new protocol testnet.
-
-It will also be coupled with the documentation of the SDK on [crates.io](https://crates.io/).
-</Callout>
-<Callout type="info" emoji="ℹ️">
-  We are working on the intitial versions of the FFI code to allow developers to experiment and get feedback. Please get in touch if you think the FFI bindings are lacking certain functionality.
-</Callout>
-
 We currently have FFI bindings for Go and C/C++. See the table below to check the coverage of functionality we expect devs would like to see.

 The [`nym/sdk/ffi`](https://github.com/nymtech/nym/tree/master/sdk/ffi) directory has the following structure:
@@ -50,7 +39,7 @@ At the time of writing the following functionality is not exposed to the shared
 - `Socks5::new()`: creation and use of the [socks5/4a/4 proxy client](./mixnet/examples/socks).

 ## TcpProxy Module
-A connection abstraction which exposes a local TCP socket which developers are able to interact with basically as expected, being able to read/write to/from a bytestream, without really having to take into account the workings of the Mixnet/Sphinx/the [message-based](../concepts/messages) format of the underlying client.
+A connection abstraction which exposes a local TCP socket which developers are able to interact with basically as expected, being able to read/write to/from a bytestream, without really having to take into account the workings of the Mixnet/Sphinx/the message-based format of the underlying client.

 <Callout type="info" emoji="ℹ️">
  At the time of writing this functionality is **only** exposed to Go. C/C++ bindings will follow in the future in a larger update to the C FFI.
@@ -1,14 +1,6 @@
 # Installation
 import { Callout } from 'nextra/components';

-<Callout type="warning">
-  There will be a breaking SDK upgrade in the coming months. This upgrade will make the SDK a lot easier to build with.
-
-This upgrade will affect the interface of the SDK dramatically, and will be coupled with a protocol change - stay tuned for information on early access to the new protocol testnet.
-
-It will also be coupled with the documentation of the SDK on [crates.io](https://crates.io/).
-</Callout>
-
 The `nym-sdk` crate is **not yet available via [crates.io](https://crates.io)**. As such, in order to import the crate you must specify the Nym monorepo in your `Cargo.toml` file. Since the `HEAD` of `master` is always the most recent release, we recommend developers use that for their imports, unless they have a reason to pull in a specific historic version of the code.

 ```toml
@@ -1,14 +1,6 @@
 # Mixnet Module
 import { Callout } from 'nextra/components';

-<Callout type="warning">
-  There will be a breaking SDK upgrade in the coming months. This upgrade will make the SDK a lot easier to build with.
-
-This upgrade will affect the interface of the SDK dramatically, and will be coupled with a protocol change - stay tuned for information on early access to the new protocol testnet.
-
-It will also be coupled with the documentation of the SDK on [crates.io](https://crates.io/).
-</Callout>
-
 This module exposes the logic of creating and interacting with clients and Mixnet messages. This is recommended for those wanting to either start playing around with the Mixnet and how it works, or build connection logic.

 > For developers wanting something more 'plug and play' we recommend the [`TcpProxy` module](./tcpproxy).
@@ -1,11 +1,4 @@
 # Builder Patterns
 import { Callout } from 'nextra/components';

-<Callout type="warning">
-  There will be a breaking SDK upgrade in the coming months. This upgrade will make the SDK a lot easier to build with.
-
-This upgrade will affect the interface of the SDK dramatically, and will be coupled with a protocol change - stay tuned for information on early access to the new protocol testnet.
-
-It will also be coupled with the documentation of the SDK on [crates.io](https://crates.io/).
-</Callout>
 Since there are two ways of creating an SDK client - ephemeral and with-storage - then there are two ways of applying the Builder Pattern to client creation.
@@ -1,13 +1,6 @@
 # Mixnet Client Builder with Storage
 import { Callout } from 'nextra/components';

-<Callout type="warning">
-  There will be a breaking SDK upgrade in the coming months. This upgrade will make the SDK a lot easier to build with.
-
-This upgrade will affect the interface of the SDK dramatically, and will be coupled with a protocol change - stay tuned for information on early access to the new protocol testnet.
-
-It will also be coupled with the documentation of the SDK on [crates.io](https://crates.io/).
-</Callout>
 The previous example involves ephemeral keys - if we want to create and then maintain a client identity over time, our code becomes a little more complex as we need to create, store, and conditionally load these keys.

 > You can find this code [here](https://github.com/nymtech/nym/blob/master/sdk/rust/nym-sdk/examples/builder_with_storage.rs).
@@ -1,13 +1,6 @@
 # Mixnet Client Builder
 import { Callout } from 'nextra/components';

-<Callout type="warning">
-  There will be a breaking SDK upgrade in the coming months. This upgrade will make the SDK a lot easier to build with.
-
-This upgrade will affect the interface of the SDK dramatically, and will be coupled with a protocol change - stay tuned for information on early access to the new protocol testnet.
-
-It will also be coupled with the documentation of the SDK on [crates.io](https://crates.io/).
-</Callout>
 You can spin up an ephemeral client like so. This client will not have a persistent identity and its keys will be dropped on restart. Since there is currently no way of reconnecting a client that has been disconnected after use, then treat disconnecting a client the same as dropping its keys entirely.

 > You can find this code [here](https://github.com/nymtech/nym/blob/master/sdk/rust/nym-sdk/examples/builder.rs).
@@ -2,14 +2,6 @@

 import { Callout } from 'nextra/components'

-<Callout type="warning">
-  There will be a breaking SDK upgrade in the coming months. This upgrade will make the SDK a lot easier to build with.
-
-This upgrade will affect the interface of the SDK dramatically, and will be coupled with a protocol change - stay tuned for information on early access to the new protocol testnet.
-
-It will also be coupled with the documentation of the SDK on [crates.io](https://crates.io/).
-</Callout>
-
 <Callout type="warning" emoji="⚠️">
  These examples are **not** the same as using a configurable network: these functions define a subset of nodes to use on a given network, whereas the [testnet](./testnet) example is an example of switching to use a different network entirely. The two can be combined, but if you are looking for how to connect your client to a testnet, see the `testnet` file.
 </Callout>
@@ -1,13 +1,6 @@
 # Custom Topology Provider
 import { Callout } from 'nextra/components';

-<Callout type="warning">
-  There will be a breaking SDK upgrade in the coming months. This upgrade will make the SDK a lot easier to build with.
-
-This upgrade will affect the interface of the SDK dramatically, and will be coupled with a protocol change - stay tuned for information on early access to the new protocol testnet.
-
-It will also be coupled with the documentation of the SDK on [crates.io](https://crates.io/).
-</Callout>
 If you are also running a Validator and Nym API for your network, you can specify that endpoint as such and interact with it as clients usually do (under the hood).

 > You can find this code [here](https://github.com/nymtech/nym/blob/master/sdk/rust/nym-sdk/examples/custom_topology_provider.rs)
@@ -33,7 +26,7 @@ impl MyTopologyProvider {
            .expect("Failed to create API client builder")
            .build::<nym_validator_client::models::RequestError>()
            .expect("Failed to build API client");
-        
+
        MyTopologyProvider {
            validator_client,
        }
@@ -1,13 +1,6 @@
 # Manually Overwrite Topology
 import { Callout } from 'nextra/components';

-<Callout type="warning">
-  There will be a breaking SDK upgrade in the coming months. This upgrade will make the SDK a lot easier to build with.
-
-This upgrade will affect the interface of the SDK dramatically, and will be coupled with a protocol change - stay tuned for information on early access to the new protocol testnet.
-
-It will also be coupled with the documentation of the SDK on [crates.io](https://crates.io/).
-</Callout>
 If you aren't running a Validator and Nym API, and just want to import a specific sub-set of mix nodes, you can simply overwrite the grabbed topology manually.

 > You can find this code [here](https://github.com/nymtech/nym/blob/master/sdk/rust/nym-sdk/examples/manually_overwrite_topology.rs)
@@ -2,13 +2,6 @@

 import { Callout } from 'nextra/components'

-<Callout type="warning">
-  There will be a breaking SDK upgrade in the coming months. This upgrade will make the SDK a lot easier to build with.
-
-This upgrade will affect the interface of the SDK dramatically, and will be coupled with a protocol change - stay tuned for information on early access to the new protocol testnet.
-
-It will also be coupled with the documentation of the SDK on [crates.io](https://crates.io/).
-</Callout>
 Lets look at a very simple example of how you can import and use the websocket client in a piece of Rust code.

 Simply importing the `nym_sdk` crate into your project allows you to create a client and send traffic through the mixnet.
@@ -2,13 +2,6 @@

 import { Callout } from 'nextra/components'

-<Callout type="warning">
-  There will be a breaking SDK upgrade in the coming months. This upgrade will make the SDK a lot easier to build with.
-
-This upgrade will affect the interface of the SDK dramatically, and will be coupled with a protocol change - stay tuned for information on early access to the new protocol testnet.
-
-It will also be coupled with the documentation of the SDK on [crates.io](https://crates.io/).
-</Callout>
 If you are looking at implementing Nym as a transport layer for a crypto wallet or desktop app, this is probably the best place to start if they can speak SOCKS5, 4a, or 4.

 > You can find this code [here](https://github.com/nymtech/nym/blob/master/sdk/rust/nym-sdk/examples/socks5.rs)
@@ -2,13 +2,6 @@

 import { Callout } from 'nextra/components'

-<Callout type="warning">
-  There will be a breaking SDK upgrade in the coming months. This upgrade will make the SDK a lot easier to build with.
-
-This upgrade will affect the interface of the SDK dramatically, and will be coupled with a protocol change - stay tuned for information on early access to the new protocol testnet.
-
-It will also be coupled with the documentation of the SDK on [crates.io](https://crates.io/).
-</Callout>
 If you need to split the different actions of your client across different tasks, you can do so like this. You can think of this analogously to spliting a Tcp Stream into read/write. This functionality is also useful for embedding a sending and receiving client into different tasks.

 > You can find this code [here](https://github.com/nymtech/nym/blob/master/sdk/rust/nym-sdk/examples/parallel_sending_and_receiving.rs)
@@ -2,13 +2,6 @@

 import { Callout } from 'nextra/components'

-<Callout type="warning">
-  There will be a breaking SDK upgrade in the coming months. This upgrade will make the SDK a lot easier to build with.
-
-This upgrade will affect the interface of the SDK dramatically, and will be coupled with a protocol change - stay tuned for information on early access to the new protocol testnet.
-
-It will also be coupled with the documentation of the SDK on [crates.io](https://crates.io/).
-</Callout>
 If you're integrating mixnet functionality into an existing app and want to integrate saving client configs and keys into your existing storage logic, you can manually perform these actions.

 > You can find this code [here](https://github.com/nymtech/nym/blob/master/sdk/rust/nym-sdk/examples/manually_handle_storage.rs)
@@ -2,13 +2,6 @@

 import { Callout } from 'nextra/components'

-<Callout type="warning">
-  There will be a breaking SDK upgrade in the coming months. This upgrade will make the SDK a lot easier to build with.
-
-This upgrade will affect the interface of the SDK dramatically, and will be coupled with a protocol change - stay tuned for information on early access to the new protocol testnet.
-
-It will also be coupled with the documentation of the SDK on [crates.io](https://crates.io/).
-</Callout>
 Both functions used to send messages through the mixnet (`send_message` and `send_plain_message`) send a pre-determined number of SURBs along with their messages by default.

 You can read more about how SURBs function under the hood [here](../../../../network/traffic/anonymous-replies).
@@ -1,13 +1,7 @@
 # Configurable Network
 import { Callout } from 'nextra/components'

-<Callout type="warning">
-  There will be a breaking SDK upgrade in the coming months. This upgrade will make the SDK a lot easier to build with.

-This upgrade will affect the interface of the SDK dramatically, and will be coupled with a protocol change - stay tuned for information on early access to the new protocol testnet.
-
-It will also be coupled with the documentation of the SDK on [crates.io](https://crates.io/).
-</Callout>
 If you want to connect your Mixnet client to a different network than Mainnet, simply pull in a file from [`nym/envs`](https://github.com/nymtech/nym/tree/master/envs) as such:

 ```rust
@@ -1,15 +1,8 @@
 # TcpProxy Module
 import { Callout } from 'nextra/components';

-<Callout type="warning">
-  There will be a breaking SDK upgrade in the coming months. This upgrade will make the SDK a lot easier to build with.
-
-This upgrade will affect the interface of the SDK dramatically, and will be coupled with a protocol change - stay tuned for information on early access to the new protocol testnet.
-
-It will also be coupled with the documentation of the SDK on [crates.io](https://crates.io/).
-</Callout>
 This module exposes the `TcpProxyClient` and the `TcpProxyServer` which can be used to proxy traffic through the Mixnet in a way that is more familiar to developers than the methods exposed by the [`Mixnet` module](./mixnet).

-Both `Client` and `Server` are intended to be initialised and then run in a background thread, exposing a configurable `localhost` socket which developers can read/write/stream to without having to worry about the [message-based](../concepts/messages) nature of sending and receiving traffic to/from the Mixnet.
+Both `Client` and `Server` are intended to be initialised and then run in a background thread, exposing a configurable `localhost` socket which developers can read/write/stream to without having to worry about the message-based nature of sending and receiving traffic to/from the Mixnet.

 > Non-Rust/Go developers who want to experiment with this module can start with the [standalone binaries](../tools/standalone-tcpproxy).
@@ -3,14 +3,6 @@

 import { Callout } from 'nextra/components'

-<Callout type="warning">
-  There will be a breaking SDK upgrade in the coming months. This upgrade will make the SDK a lot easier to build with.
-
-  This upgrade will affect the interface of the SDK dramatically, and will be coupled with a protocol change - stay tuned for information on early access to the new protocol testnet.
-
-  It will also be coupled with the documentation of the SDK on [crates.io](https://crates.io/).
-</Callout>
-
 ## Motivations
 The motivation behind the creation of the `TcpProxy` module is to allow developers to interact with the Mixnet in a way that is far more familiar to them: simply setting up a connection with a transport, being returned a socket, and then being able to stream data to/from it, similar to something like the Tor [`arti`](https://gitlab.torproject.org/tpo/core/arti/-/tree/main/crates/arti-client) client.

@@ -1,13 +1,7 @@
 # Multi Connection Example
 import { Callout } from 'nextra/components'

-<Callout type="warning">
-  There will be a breaking SDK upgrade in the coming months. This upgrade will make the SDK a lot easier to build with.

-This upgrade will affect the interface of the SDK dramatically, and will be coupled with a protocol change - stay tuned for information on early access to the new protocol testnet.
-
-It will also be coupled with the documentation of the SDK on [crates.io](https://crates.io/).
-</Callout>
 This example starts off several Tcp connections on a loop to a remote endpoint: in this case the `TcpListener` behind the `NymProxyServer` instance on the echo server found in
 [`nym/tools/echo-server/`](https://github.com/nymtech/nym/tree/develop/tools/echo-server). It pipes a few messages to it, logs the replies, and keeps track of the number of replies received per connection.

@@ -1,13 +1,7 @@
 # Single Connection Example
 import { Callout } from 'nextra/components'

-<Callout type="warning">
-  There will be a breaking SDK upgrade in the coming months. This upgrade will make the SDK a lot easier to build with.

-This upgrade will affect the interface of the SDK dramatically, and will be coupled with a protocol change - stay tuned for information on early access to the new protocol testnet.
-
-It will also be coupled with the documentation of the SDK on [crates.io](https://crates.io/).
-</Callout>
 This is a basic example which opens a single TCP connection and writes a bunch of messages between a client and some 'echo server' logic, so only uses a single session under the hood and doesn't really show off the message ordering capabilities; this is mainly just a quick introductory illustration on how:
 - the mixnet does message ordering
 - the NymProxyClient and NymProxyServer can be hooked into and used to communicate between two otherwise pretty vanilla TcpStreams
@@ -1,12 +1,5 @@
 # Troubleshooting
 import { Callout } from 'nextra/components'

-<Callout type="warning">
-  There will be a breaking SDK upgrade in the coming months. This upgrade will make the SDK a lot easier to build with.
-
-This upgrade will affect the interface of the SDK dramatically, and will be coupled with a protocol change - stay tuned for information on early access to the new protocol testnet.
-
-It will also be coupled with the documentation of the SDK on [crates.io](https://crates.io/).
-</Callout>
 ## Lots of `duplicate fragment received` messages
 You might see a lot of `WARN` level logs about duplicate fragments in your logs, depending on the log level you're using. This occurs when a packet is retransmitted somewhere in the Mixnet, but then the original makes it to the destination client as well. This is not something to do with your client logic, but instead the state of the Mixnet.
@@ -1,7 +1,7 @@
 # Tools

-There are a few tools available to developers for chain interaction: the `nym-cli` tool, which operates as an easier-to-use wrapper around `nyxd`, to allow operators to script interactions with their infrastructure (and those who prefer CLI tools ;) ).
+There are a few tools available to developers for chain interaction: the `nym-cli` tool, which operates as an easier-to-use wrapper around `nyxd`, to allow operators to script interactions with their infrastructure (and those who prefer CLI tools).

 There is also a basic echo server tool which app developers can use as a quick endpoint for traffic testing. This will be deployed onto a persistent public server in the future so devs dont have to run it themselves.

-Finally, there are a pair of standalone versions of the TcpProxy Rust SDK module for developers to begin experimenting with sending app traffic through them mixnet.
+Finally, there are also a pair of standalone versions of the TcpProxy Rust SDK module for developers to begin experimenting with sending app traffic through them mixnet (**this module will soon be deprecated in place of the `MixSocket`/`MixStream` abstractions**).
@@ -1,16 +1,4 @@

 # Introduction

-import { Callout } from 'nextra/components';
-
-<Callout type="error">
-    The TypeScript SDK is currently not avaliable to use: a network upgrade elsewhere has caused a problem which is not currently fixed. TS SDK Clients are not able to connect to the network.
-
-    When the issue is resolved, this will be reflected in the documentation.
-
-    Thanks for your patience!
-</Callout>
-
-Welcome to the documentation for Nym's TypeScript SDK!
-
-This guide contains information about the various TypeScript SDK modules that facilitate interaction with different components of the Nym stack, including the Nym mixnet, the Nyx blockchain, and Coconut credentials.
+This guide contains information about the various TypeScript SDK modules that facilitate interaction with different components of the Nym stack: the Nym mixnet & the Nyx blockchain.
@@ -1,14 +1,6 @@
 # TS SDK FAQ
 import { Callout } from 'nextra/components'

-<Callout type="error">
-    The TypeScript SDK is currently not avaliable to use: a network upgrade elsewhere has caused a problem which is not currently fixed. TS SDK Clients are not able to connect to the network.
-
-    When the issue is resolved, this will be reflected in the documentation.
-
-    Thanks for your patience!
-</Callout>
-
 ## Why and when does the mixnet client complain about insufficient topology?

 It will in one of the following cases:
@@ -2,14 +2,6 @@

 import { Callout } from 'nextra/components';

-<Callout type="error">
-    The TypeScript SDK is currently not avaliable to use: a network upgrade elsewhere has caused a problem which is not currently fixed. TS SDK Clients are not able to connect to the network.
-
-    When the issue is resolved, this will be reflected in the documentation.
-
-    Thanks for your patience!
-</Callout>
-
 You might need some help bundling packages from the Nym Typescript SDK into your package.

 Here are some things that could go wrong:
@@ -2,14 +2,6 @@ import { Callout } from 'nextra/components';

 # Troubleshooting bundling with ESbuild

-<Callout type="error">
-    The TypeScript SDK is currently not avaliable to use: a network upgrade elsewhere has caused a problem which is not currently fixed. TS SDK Clients are not able to connect to the network.
-
-    When the issue is resolved, this will be reflected in the documentation.
-
-    Thanks for your patience!
-</Callout>
-
 If you've been following the steps outlined in the Examples section, your development environment should be configured as follows:

 #### Environment Setup
@@ -3,14 +3,6 @@ import { Callout } from 'nextra/components';
 # Troubleshooting bundling with Webpack


-<Callout type="error">
-    The TypeScript SDK is currently not avaliable to use: a network upgrade elsewhere has caused a problem which is not currently fixed. TS SDK Clients are not able to connect to the network.
-
-    When the issue is resolved, this will be reflected in the documentation.
-
-    Thanks for your patience!
-</Callout>
-
 ## Webpack > 5 ESM

 For any project using Webpack, you´ll need the following rule in your `webpack.config.js` above version 5:
@@ -2,14 +2,6 @@ import { Callout } from 'nextra/components'

 # Cosmos Kit

-<Callout type="error">
-    The TypeScript SDK is currently not avaliable: a network upgrade elsewhere has caused a problem which is not currently fixed. TS SDK Clients are not able to connect to the network.
-
-    When the issue is resolved, this will be reflected in the documentation.
-
-    Thanks for your patience!
-</Callout>
-
 The wonderful people of Cosmology have made some [fantastic components](https://cosmoskit.com/) that can be used with
 Nym. These include:

@@ -1,13 +1,6 @@
 import { Callout } from 'nextra/components';

 # `mixFetch`
-<Callout type="error">
-    The TypeScript SDK is currently not avaliable to use: a network upgrade elsewhere has caused a problem which is not currently fixed. TS SDK Clients are not able to connect to the network.
-
-    When the issue is resolved, this will be reflected in the documentation.
-
-    Thanks for your patience!
-</Callout>

 An easy way to secure parts or all of your web app is to replace calls to [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch) with `mixFetch`:

@@ -25,7 +18,7 @@ Sounds great, are there any catches? Well, there are a few (for now):
 <Callout type="info" emoji="ℹ️">
  Right now Gateways are not required to run a Secure Websocket (WSS) listener, so only a subset of nodes running in Gateway mode have configured their nodes to do so.

-For the moment you have to select a Gateway that has WSS enabled and Network Requester from [Harbourmaster Gateways for mixFetch list](https://harbourmaster.nymtech.net/).
+For the moment you have to select a Gateway that has WSS from [Harbourmaster Gateways for mixFetch list](https://harbourmaster.nymtech.net/).

 ```
 curl -X 'GET' \
@@ -40,9 +33,7 @@ curl -X 'GET' \
 import type { SetupMixFetchOps } from '@nymproject/mix-fetch';

 const mixFetchOptions: SetupMixFetchOps = {
-  preferredGateway: '23A7CSaBSA2L67PWuFTPXUnYrCdyVcB7ATYsjUsfdftb', // with WSS
-  preferredNetworkRequester:
-    'HuNL1pFprNSKW6jdqppibXP5KNKCNJxDh7ivpYcoULN9.C62NahRTUf6kqpNtDVHXoVriQr6yyaU5LtxdgpbsGrtA@23A7CSaBSA2L67PWuFTPXUnYrCdyVcB7ATYsjUsfdftb',
+  preferredGateway: "q2A2cbooyC16YJzvdYaSMH9X3cSiieZNtfBr8cE8Fi1", // with WSS
  mixFetchOverride: {
    requestTimeoutMs: 60_000,
  },
@@ -1,13 +1,6 @@
 import { Callout } from 'nextra/components'

 # Mixnet Client
-<Callout type="error">
-    The TypeScript SDK is currently not avaliable to use: a network upgrade elsewhere has caused a problem which is not currently fixed. TS SDK Clients are not able to connect to the network.
-
-    When the issue is resolved, this will be reflected in the documentation.
-
-    Thanks for your patience!
-</Callout>
 As you know by now, in order to send or receive messages over the mixnet, you'll need to use the [`SDK Client`](https://www.npmjs.com/package/@nymproject/sdk), which will allow you to create apps that can use the Nym mixnet and Coconut credentials.

 This client is message based - it can only send a one-way message to another client's address.
@@ -1,13 +1,7 @@
 import { Callout } from 'nextra/components'

 # Nym Smart Contract Clients
-<Callout type="error">
-    The TypeScript SDK is currently not avaliable to use: a network upgrade elsewhere has caused a problem which is not currently fixed. TS SDK Clients are not able to connect to the network.

-    When the issue is resolved, this will be reflected in the documentation.
-
-    Thanks for your patience!
-</Callout>
 As previously mentioned, to query or execute on any of the Nym contracts, you'll need to use one of the [`Contract Clients`](https://www.npmjs.com/package/@nymproject/contract-clients), which contains read-only query and signing clients for all of Nym's smart contracts.

 ##### Contract Clients list
@@ -4,14 +4,6 @@ import { Callout } from 'nextra/components'

 The different modules in the Typescript SDK allow developers to start building browser-based applications quickly. Simply import the SDK module of your choice – depending on the component from the Nym architecture you want to use – into your code via NPM, as you would any other TypeScript library.

-<Callout type="error">
-    The TypeScript SDK is currently not avaliable to use: a network upgrade elsewhere has caused a problem which is not currently fixed. TS SDK Clients are not able to connect to the network.
-
-    When the issue is resolved, this will be reflected in the documentation.
-
-    Thanks for your patience!
-</Callout>
-
 <Callout type="info" emoji="ℹ️">
    Other than the `Contract Clients`, SDK modules come in four different flavours (ESM, CJS and full-fat for ESM and CJS).
    This documentation focuses on examples using the `full-fat` versions.
@@ -4,15 +4,6 @@ import { NPMLink } from '../../../components/npm';

 ## SDK overview

-
-<Callout type="error">
-    The TypeScript SDK is currently not avaliable to use: a network upgrade elsewhere has caused a problem which is not currently fixed. TS SDK Clients are not able to connect to the network.
-
-    When the issue is resolved, this will be reflected in the documentation.
-
-    Thanks for your patience!
-</Callout>
-
 The Typescript SDK allows developers to start building browser-based Nym-based applications quickly, by simply importing the SDK modules into their code via NPM as they would any other Typescript library.

 Currently developers can use different packages from the Typescript SDK to run the following entirely in browser:
@@ -6,14 +6,6 @@ import FormattedCosmoskitExampleCode from '../../../../code-examples/sdk/typescr

 import { Callout } from 'nextra/components'

-<Callout type="error">
-    The TypeScript SDK is currently not avaliable to use: a network upgrade elsewhere has caused a problem which is not currently fixed. TS SDK Clients are not able to connect to the network.
-
-    When the issue is resolved, this will be reflected in the documentation.
-
-    Thanks for your patience!
-</Callout>
-
 Below is an example that uses [CosmosKit](https://cosmoskit.com/) to connect and sign a fake transaction with your [Keplr wallet](https://www.keplr.app/) or
 [Ledger hardware wallet](https://www.ledger.com/) to this page:

@@ -6,16 +6,13 @@ import FormattedMixFetchExampleCode from '../../../../code-examples/sdk/typescri
 import { Callout } from 'nextra/components'


-<Callout type="error">
-    The TypeScript SDK is currently not avaliable to use: a network upgrade elsewhere has caused a problem which is not currently fixed. TS SDK Clients are not able to connect to the network.
-
-    When the issue is resolved, this will be reflected in the documentation.
-
-    Thanks for your patience!
-</Callout>
-



 <MixFetch />
+
+<Callout type="info">
+    Open your browser's console to see the connection and send/receive logging for this example.
+</Callout>
+
 <FormattedMixFetchExampleCode />
@@ -7,14 +7,6 @@ import { Callout } from 'nextra/components'



-<Callout type="error">
-    The TypeScript SDK is currently not avaliable to use: a network upgrade elsewhere has caused a problem which is not currently fixed. TS SDK Clients are not able to connect to the network.
-
-    When the issue is resolved, this will be reflected in the documentation.
-
-    Thanks for your patience!
-</Callout>
-
 The Nym Mixnet contract keeps a directory of all mixnodes that can be used to mix traffic.

 Here is a live example of querying the Mixnet Contract for a paged list of mixnodes:
@@ -5,14 +5,11 @@ import Box from '@mui/material/Box';
 import FormattedTrafficExampleCode from '../../../../code-examples/sdk/typescript/traffic-example-code.mdx';


-<Callout type="error">
-    The TypeScript SDK is currently not avaliable to use: a network upgrade elsewhere has caused a problem which is not currently fixed. TS SDK Clients are not able to connect to the network.
-
-    When the issue is resolved, this will be reflected in the documentation.
-
-    Thanks for your patience!
-</Callout>
 Use this tool to experiment with the mixnet: send and receive messages!

+<Callout type="info">
+    Open your browser's console to see the connection and send/receive logging for this example.
+</Callout>
+
 <Traffic />
 <FormattedTrafficExampleCode />
@@ -13,14 +13,6 @@ import FormattedWalletDelegationsCode from '../../../../code-examples/sdk/typesc

 import { Callout } from 'nextra/components'

-<Callout type="error">
-    The TypeScript SDK is currently not avaliable to use: a network upgrade elsewhere has caused a problem which is not currently fixed. TS SDK Clients are not able to connect to the network.
-
-    When the issue is resolved, this will be reflected in the documentation.
-
-    Thanks for your patience!
-</Callout>
-
 Here's a small wallet example using testnet for you to test out!

 <WalletContextProvider>
@@ -3,14 +3,6 @@ import { Callout } from 'nextra/components'

 ## MixFetch

-<Callout type="error">
-    The TypeScript SDK is currently not avaliable to use: a network upgrade elsewhere has caused a problem which is not currently fixed. TS SDK Clients are not able to connect to the network.
-
-    When the issue is resolved, this will be reflected in the documentation.
-
-    Thanks for your patience!
-</Callout>
-
 Use the [`mixFetch`](https://www.npmjs.com/package/@nymproject/mix-fetch) package as a drop-in replacement for `fetch`to send HTTP requests over the Nym mixnet:

 ```ts
@@ -32,7 +32,7 @@ Upcoming:
 ## Nym Clients

 <Callout type="info" emoji="ℹ️">
-  You can read about setting up and using various clients in the [Developer Docs](../../developers/clients).
+  You can read about setting up and using various clients in the [Developer Docs](../../developers/clients/socks5).
 </Callout>

 A large proportion of the Nym Mixnet's functionality is implemented client-side.
@@ -48,4 +48,4 @@ Clients perform the following actions on behalf of users:
 * Send Sphinx packet [cover traffic](../concepts/cover-traffic) when no real messages are being sent
 * Retransmit [un-acknowledged packet sends](../traffic/acks)

-> At the moment due to the fact that Nym clients are [message-based](../../developers/concepts/messages), using the Mixnet requires another client on the 'other side' of the mixet to send packets to, unless you're using the `nymvpn` client (part of the NymVPN app) or the `socks5` client, which operates as a SOCKS4,4a, or 5 proxy and is able to utilise the client embedded within the `nym-node`'s Exit Gateway functionality (prev. this functionality was a standalone service, the Network Requester). In the future we wish to remove this point of friction and have all Nym clients construct IP packets instead, easing the integration burden and abstracting away the message-based nature of client communication.
+> At the moment due to the fact that Nym clients are message-based, using the Mixnet requires another client on the 'other side' of the mixet to send packets to, unless you're using the `nymvpn` client (part of the NymVPN app) or the `socks5` client, which operates as a SOCKS4,4a, or 5 proxy and is able to utilise the client embedded within the `nym-node`'s Exit Gateway functionality (prev. this functionality was a standalone service, the Network Requester). In the future we wish to remove this point of friction and have all Nym clients construct IP packets instead, easing the integration burden and abstracting away the message-based nature of client communication.
@@ -6,6 +6,7 @@
  "sandbox": "Sandbox Testnet",
  "binaries": "Binaries",
  "nodes": "Nodes & Validators Guides",
+  "performance-and-testing": "Performance Measurement",
  "tools": "Tools",
  "troubleshooting": "Troubleshooting",
  "tokenomics": "Tokenomics",
@@ -49,6 +49,76 @@ This page displays a full list of all the changes during our release cycle from

 <VarInfo />

+## `v2025.20-leerdammer`
+
+- [Release Binaries](https://github.com/nymtech/nym/releases/tag/nym-binaries-v2025.20-leerdammer)
+- [`nym-node`](nodes/nym-node.mdx) version `1.21.0`
+
+```sh
+nym-node
+Binary Name:        nym-node
+Build Timestamp:    2025-11-12T08:19:33.288341371Z
+Build Version:      1.21.0
+Commit SHA:         babf113fe5d396fa8a84fa939ad4b1b5b4d38b83
+Commit Date:        2025-11-12T08:39:48.000000000+01:00
+Commit Branch:      HEAD
+rustc Version:      1.88.0
+rustc Channel:      stable
+cargo Profile:      release
+```
+
+### Operators Updates & Tools
+
+- [New **Performance Measurement** page](/operators/performance-and-testing) explaining the logic behind node selection for NymVPN application
+
+- [New **Gateway Probe Details** page](/operators/performance-and-testing/gateway-probe-details) explaining complexity and contradictions when measuring network performance
+
+### Developer Tools
+
+- [Typescript SDK 1.4.1](https://github.com/nymtech/nym/pull/6146): This PR is a new release of the Typescript SDK, `mixFetch` and `WASM` client. It also removes the Harbour Master client from `mixFetch`, replacing it with the Nym API's described endpoint for nym-nodes
+
+- [Overhauled **developer integrations** pages](/developers/integrations) explaining the different restrictions for the different SDK options on offer
+
+- [Fixed `mixFetch` and `WASM Client` playground + examples](/developers/typescript/start): new versions of the Typescript SDK and `mixFetch` have been published, examples and live playground have been updated accordingly
+
+
+### Features
+
+- [Tweak ts sdk actions](https://github.com/nymtech/nym/pull/6185): Using `taskset` to limit the number of of CPUs used by `wasm-pack` and `wasm-opt` commands used by ts linting CI
+
+- [Configurable mixnet client startup timeout](https://github.com/nymtech/nym/pull/6148)
+
+- [QUIC bridge deployment script v2](https://github.com/nymtech/nym/pull/6145): Script helping operators to install, configure and deploy QUIC bridge as systemd service
+
+- [Expose more explicit `new_with_fronted_urls` builder for http API client](https://github.com/nymtech/nym/pull/6136)
+
+- [Domain fronting](https://github.com/nymtech/nym/pull/6134): Enable URL rotation and retries for mixnet gateway [`init`](https://github.com/nymtech/nym/pull/6126) 
+
+
+### Bugfix
+
+- [Add circuit breaker](https://github.com/nymtech/nym/pull/6143): When the mixnet client's `mix_tx` channel closes during network drops, `OutQueueControl` would retry sending packets through the closed channel, flooding logs and hanging the daemon. This affects all clients (VPN, SOCKS5, native clients), not just VPN .. (Read more in the [PR description](https://github.com/nymtech/nym/pull/6143))
+
+- [Update internal owner address in transferred share](https://github.com/nymtech/nym/pull/6139)
+
+- [Update quic_bridge_deployment.sh for IPv4 and .deb package](https://github.com/nymtech/nym/pull/6138): Updated ping commands to explicitly use IPv4 and adjusted file permission checks with sudo. Changed the forward address prompt to specify IPv4 and modified the binary download process to fetch and install the latest `.deb` release URL automatically
+
+- [Update stored epoch share when changing ownership](https://github.com/nymtech/nym/pull/6135)
+
+- [Update stored epoch share when changing announce address](https://github.com/nymtech/nym/pull/6131)
+
+### Refactors & Maintenance
+
+- [Re-merge: disconnect mixnet client if registration fails](https://github.com/nymtech/nym/pull/6169) ([\#6158](https://github.com/nymtech/nym/pull/6158))
+
+- [Resolve `clippy 1.91` warnings](https://github.com/nymtech/nym/pull/6168)
+
+- [Remove unused dependencies](https://github.com/nymtech/nym/pull/6151): Removing the crates that only shows up on the workspace `Cargo.toml`
+
+- [Use typed-builder for registration client builder config](https://github.com/nymtech/nym/pull/6150)
+
+- [tommy is too quick](https://github.com/nymtech/nym/pull/6149)
+
 ## `v2025.19-kase`

 - [Release Binaries](https://github.com/nymtech/nym/releases/tag/nym-binaries-v2025.19-kase)
@@ -2881,7 +2951,7 @@ cargo Profile:      release
 <Callout type="warning" emoji="⚠️">
 After changes coming along with `v2024.13-magura` (`nym-node v1.1.10`), Nym Explorer is no longer picking all values correctly. Instead of fixing this outdated explorer, we are working on a new one, coming out soon.

-[Nym Harbourmaster](https://harbourmaster.nymtech.net) has cache of 90min, expect your values to be updated with delay. We are aware of some issues with Nym Harbourmaster and working hard to resolve them in the upcoming explorer v2. To check your routing values in real time, you can use [`nym-gateway-probe`](nodes/performance-and-testing/gateway-probe).
+[Nym Harbourmaster](https://harbourmaster.nymtech.net) has cache of 90min, expect your values to be updated with delay. We are aware of some issues with Nym Harbourmaster and working hard to resolve them in the upcoming explorer v2. To check your routing values in real time, you can use [`nym-gateway-probe`](performance-and-testing/gateway-probe).
 </Callout>

 ### Operators Updates & Tools
@@ -40,6 +40,9 @@ If you want to explore kickstart options and examples, learn how to integrate wi
 * [Validators](nodes/validator-setup.mdx)
 * [Nym API Setup](nodes/validator-setup/nym-api.mdx)

+**Performance Monitoring**
+* [Performance, probe and measurements](performance-and-testing)
+
 **Tokenomics, rewards and roadmap**
 * [General tokenomics page](tokenomics.mdx)
 * [Nym Node rewards page](tokenomics/mixnet-rewards.mdx)
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
benedettadavico	22793bc45e	update changelog	2025-11-25 15:16:42 +01:00
Simon Wicky	37f3ef58a3	[bugfix] Tunnel not waiting on MixnetClient to shut down cleanly (#6225 ) * return the handlefor a clean shutdown * cargo lock	2025-11-21 16:39:12 +01:00
benedettadavico	1a4d64a0e5	bump versions	2025-11-14 11:23:47 +01:00
benedetta davico	4dcc568ec2	Merge pull request #6204 from nymtech/master merging master to develop to maintain sync	2025-11-14 11:21:13 +01:00
benedetta davico	468835e3a2	Merge pull request #6199 from nymtech/release/2025.20-leerdammer Release/2025.20 leerdammer	2025-11-14 10:36:23 +01:00
benedetta davico	28a866e26d	Merge pull request #6198 from nymtech/release/2025.20-leerdammer Release/2025.20 leerdammer	2025-11-14 10:36:11 +01:00
Jędrzej Stuczyński	350d244032	bugfix: fix credential proxy upgrade mode attestation url arg (#6202 ) this includes bringing over changes introduced in #6174	2025-11-14 08:19:21 +00:00
Jack Wampler	17ca000782	HTTP API resilience enable & domain rotation conditions (#6200 ) * http url fallback conditions * include changes and tests for fronted * Allow for explicit DNS error Handling in HTTP client (#6201) when sending http reqs add manual DNS so we can handle errors directly * Address PR nits --------- Co-authored-by: durch <durch@users.noreply.github.com>	2025-11-14 08:59:36 +01:00
Drazen Urch	aac983d922	Remove debug feature from http-macro spec in gateway probe (#6195 )	2025-11-13 14:18:29 +01:00
mfahampshire	577675bab3	Remove old conceptsoverview page + move index to proper place in sidebar (#6196 )	2025-11-13 11:38:54 +00:00
mfahampshire	ec015618cd	update gw probe to point @ monorepo (#6194 ) * update gw probe to point @ monorepo * add funded nyx account info	2025-11-13 11:02:45 +00:00
mfahampshire	fa40acbeca	fixed broken link (#6193 )	2025-11-12 15:12:38 +00:00
import this	386e1790dd	[DOCs/operators]: Release notes for v2025.20 leerdammer (#6191 ) * release notes * bump up nym-node docs version * add dev tools * scrape stats and clean	2025-11-12 12:32:13 +00:00
mfahampshire	d07f9c8fad	Max/docs new structure (#6188 ) * rework of sdk docs * update integration docs + bit of overall restructure * remove debug logger from tool	2025-11-12 11:03:28 +00:00
Tommy Verrall	0dc071daeb	Merge pull request #6179 from nymtech/dns-debug DNS relibility and troubleshooting	2025-11-12 11:01:20 +01:00
benedettadavico	babf113fe5	update changelog	2025-11-12 08:39:48 +01:00
jmwample	10951d4cd3	clippy, fmt, minor fix	2025-11-11 10:40:25 -07:00
mfahampshire	872c25bfcc	Use hardcoded devrel gw for examples to get around CSP (#6187 ) * Use hardcoded devrel gw for examples to get around CSP * remove comment	2025-11-11 16:22:41 +00:00
jmwample	5acce42c64	add some staic hosts and switch server strategy	2025-11-11 09:14:26 -07:00
mfahampshire	4848d081d0	Max/tweak ts sdk actions (#6185 ) * add taskset to wasm release build commands * bump taskset cores	2025-11-11 10:19:55 +00:00
mfahampshire	b3452ede77	add wss to prod csp (#6183 ) * add wss to csp	2025-11-10 20:48:02 +00:00
import this	a44819b14c	[DOCs/operators]: Cleanup (#6184 ) * cleanup * add ipr abbrs * syntax fix * syntax fix * fix link path * QUIC non-root warning * syntax fix * update stats * address comment * fix url path	2025-11-10 14:20:15 +00:00
mfahampshire	5455110810	removed warning from TSSDK (#6182 ) * removed warning from TSSDK * tweak	2025-11-10 12:21:20 +00:00
Mark Sinclair	a0178d28f7	Typescript SDK 1.4.1 (#6146 ) * wasm: mix-fetch: remove harbour master client and use Nym API client * wasm: mix-fetch: fix up internal tester * Release Typescript SDK v1.4.1 * remove bump version tool from workspace * ts-sdk: contract clients: update and re-run autogen * ts: fix linting errors * update go * pin minimatch typings to fix lint errors * bump versions to rc * Update publish-sdk-npm.yml * Update publish-sdk-npm.yml * Update publish-sdk-npm.yml * Update publish-sdk-npm.yml * try disable typedoc because of minimatch errors * bump versions to rc0 * limit packages published to only wasm clients * TS SDK 1.4.1-rc1 * simplify version dependencies and add dist to dev mode * add back version complexity for CI * TS SDK 1.4.1-rc2 * ts-sdk: fix minimatch dependency and correct casing on `selfAddress` function call * wasm: rename `main` to `main_js` to avoid collision errors in exporting main from tests see https://github.com/wasm-bindgen/wasm-bindgen/issues/2206 * improve wasm js tests * TS SDK 1.4.1-rc3 * update example docs * TS SDK 1.4.1 release * update docs dependencies to SDK 1.4.1 * update yarn lock file after TS SDK 1.4.1 publish * Update ci-lint-typescript.yml * Update ci-lint-typescript.yml * Update ci-nym-wallet-storybook.yml * Bump node tester version and add additional yarn install step to fix linting --------- Co-authored-by: Mark Sinclair <mmsinclair@users.noreply.github.com>	2025-11-07 21:17:42 +00:00
import this	3e42160426	[Docs/operators]: Performance measurement pages (#6177 ) * initialise wg perf docs * fix paths to absolute * fix paths to absolute * vpn coloring guide * improve quic script dwl way * refactor operators menu structure * create probe-details page * wg syntax change * modified time * fix link paths * remove redundancy * fix comments & bump stats	2025-11-07 15:41:59 +00:00
jmwample	2f752a6c42	fix things related to interface changes	2025-11-06 18:37:50 -07:00
Jack Wampler	806f807f02	Implement Static DNS fallback (#6178 )	2025-11-06 16:46:39 -07:00
Jack Wampler	1400db6156	DNS Reliability Fixes (#6175 )	2025-11-06 12:37:27 -07:00
Simon Wicky	673a3e45d3	[bugfix] Distinguish authenticator errors by credential spent (#6176 ) * distinguish authenticator errors by credential spent * nitpicking fixes * fix CI to see those changes * error naming	2025-11-06 18:07:07 +01:00
benedettadavico	0d7487f530	bump versions	2025-10-31 13:24:27 +01:00