Data Observatory (#6172 )

* rename nyxd-scraper to sqlite wip: made storage mostly generic minus modules changed error types to make modules dyn compatible implemented traits for sqlite instance using sqlite instance for rewarder and chain watcher psql scaffolding initial postgres support - missing some proto -> json parsing use postgres in chain scraper added message registry to block processor message content parsing in psql involved addresses adding null value for logs Revert "use postgres in chain scraper" This reverts commit 83c84bfd2d. using SignerInfo proto definitions for db serialisation added ibc messages to MessageRegistry * add the data observatory * add the data observatory * move message parsing and change webhook * handle wasm messages in a module * formatting and clippy * copy shared migrations and add comments to ignore file to explain * update offline queries * change to clap args and use url::Url to parse args * tidy up README, startup info, typos * tidy up validator rewarder * lock file * change webhook module from msg to tx handler * ignore profiler output * add missing things and make clippy happy * updated cosmrs version used by the nym wallet * add glob to workspace dependencies * rename migration files * remove copying from shared migrations * duplicate shared migrations to keep things simple * add check for manual migration sync that will fail on `cargo build` in CI * build.rs checks data observatory migrations have content of all shared scraper migrations and errors on changes or new files * update runner * add reset target to make file * process events and logs * migrations - remove unnecessary columns * update offline queries * chore: run cargo fmt * fix up: inpsect_err instead of map_err --------- Co-authored-by: Jędrzej Stuczyński <jedrzej.stuczynski@gmail.com> Co-authored-by: Mark Sinclair <mmsinclair@users.noreply.github.com> Co-authored-by: benedettadavico <benedetta.davico@gmail.com>
remove run DKG migration (#6253 )
2025-12-02 21:27:22 +00:00 · 2025-11-28 13:16:36 +00:00 · 2025-11-28 02:05:44 -08:00 · 2025-11-27 03:23:28 -08:00 · 2025-11-27 10:28:53 +00:00 · 2025-11-26 13:58:40 +00:00
635 changed files with 27311 additions and 15387 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/**'
@@ -16,7 +16,7 @@ jobs:
        uses: actions/checkout@v4

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

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

      - name: Get version from cargo.toml
-        uses: mikefarah/yq@v4.47.1
+        uses: mikefarah/yq@v4.48.1
        id: get_version
        with:
          cmd: yq -oy '.package.version' ${{ env.WORKING_DIRECTORY }}/Cargo.toml
@@ -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

@@ -31,7 +31,7 @@ jobs:
          components: rustfmt, clippy

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

@@ -14,6 +14,6 @@ jobs:
        with:
          fetch-depth: 0  # Shallow clones should be disabled for a better relevancy of analysis
      - name: SonarQube Scan
-        uses: SonarSource/sonarqube-scan-action@v5
+        uses: SonarSource/sonarqube-scan-action@v6
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
@@ -34,7 +34,7 @@ jobs:
      - name: Setup Pages
        uses: actions/configure-pages@v5
      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@v4
        with:
          # Upload entire repository
          path: './ppa'
@@ -8,6 +8,6 @@ jobs:
    steps:
    - uses: actions/first-interaction@v3
      with:
-        repo-token: ${{ secrets.GITHUB_TOKEN }}
-        issue-message: 'Thank you for raising this issue'
-        pr-message: 'Thank you for making this first PR'
+        repo_token: ${{ secrets.GITHUB_TOKEN }}
+        issue_message: 'Thank you for raising this issue'
+        pr_message: 'Thank you for making this first PR'
@@ -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
@@ -26,7 +26,7 @@ jobs:
          git config --global user.name "Lawrence Stalder"

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

 jobs:
  build-container:
-    runs-on: arc-ubuntu-22.04-dind
+    runs-on: arc-linux-latest-dind
    steps:
      - name: Login to Harbor
        uses: docker/login-action@v3
@@ -26,7 +26,7 @@ jobs:
          git config --global user.name "Lawrence Stalder"

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

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

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

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

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

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

      - name: Get version from cargo.toml
-        uses: mikefarah/yq@v4.47.1
+        uses: mikefarah/yq@v4.48.1
        id: get_version
        with:
          cmd: yq -oy '.package.version' ${{ env.WORKING_DIRECTORY }}/Cargo.toml
@@ -63,3 +63,5 @@ nym-api/redocly/formatted-openapi.json

 **/settings.sql
 **/enter_db.sh
+
+*.profraw
@@ -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])
@@ -87,7 +87,9 @@ members = [
    "common/nymsphinx/params",
    "common/nymsphinx/routing",
    "common/nymsphinx/types",
-    "common/nyxd-scraper",
+    "common/nyxd-scraper-sqlite",
+    "common/nyxd-scraper-psql",
+    "common/nyxd-scraper-shared",
    "common/pemstore",
    "common/registration",
    "common/serde-helpers",
@@ -124,6 +126,7 @@ members = [
    "nym-credential-proxy/nym-credential-proxy",
    "nym-credential-proxy/nym-credential-proxy-requests",
    "nym-credential-proxy/vpn-api-lib-wasm",
+    "nym-data-observatory",
    "nym-ip-packet-client",
    "nym-network-monitor",
    "nym-node",
@@ -150,7 +153,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",
@@ -263,6 +266,7 @@ futures = "0.3.31"
 futures-util = "0.3"
 generic-array = "0.14.7"
 getrandom = "0.2.10"
+glob = "0.3"
 handlebars = "3.5.5"
 hex = "0.4.3"
 hickory-resolver = "0.25"
@@ -347,11 +351,11 @@ tokio-tungstenite = { version = "0.20.1" }
 tokio-util = "0.7.15"
 toml = "0.8.22"
 tower = "0.5.2"
-tower-http = "0.5.2"
+tower-http = "0.6.6"
 tracing = "0.1.41"
 tracing-log = "0.2"
 tracing-opentelemetry = "0.19.0"
-tracing-subscriber = "0.3.19"
+tracing-subscriber = "0.3.20"
 tracing-tree = "0.2.2"
 tracing-indicatif = "0.3.9"
 tracing-test = "0.2.5"
@@ -398,7 +402,9 @@ cw-multi-test = "=2.3.2"
 bip32 = { version = "0.5.3", default-features = false }


-cosmrs = { version = "0.21.1" }
+cosmrs = { version = "0.22.0" }
+cosmos-sdk-proto = { version = "0.27.0" }
+ibc-proto = { version = "0.52.0" }
 tendermint = "0.40.4"
 tendermint-rpc = "0.40.4"
 prost = { version = "0.13", default-features = false }
@@ -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"
@@ -6,7 +6,10 @@ use nym_wireguard_types::PeerPublicKey;

 use crate::{
    AuthenticatorVersion, Error,
-    traits::{FinalMessage, InitMessage, QueryBandwidthMessage, TopUpMessage, Versionable},
+    traits::{
+        FinalMessage, InitMessage, QueryBandwidthMessage, TopUpMessage, UpgradeModeMessage,
+        Versionable,
+    },
    v2, v3, v4, v5, v6,
 };

@@ -18,6 +21,7 @@ pub enum ClientMessage {
    Final(Box<dyn FinalMessage + Send + Sync + 'static>),
    Query(Box<dyn QueryBandwidthMessage + Send + Sync + 'static>),
    TopUp(Box<dyn TopUpMessage + Send + Sync + 'static>),
+    UpgradeModeCheck(Box<dyn UpgradeModeMessage + Send + Sync + 'static>),
 }

 pub struct SerialisedRequest {
@@ -131,6 +135,7 @@ impl ClientMessage {
                );
                Ok(SerialisedRequest::new(req.to_bytes()?, id))
            }
+            _ => Err(Error::UnsupportedMessage),
        }
    }

@@ -189,6 +194,7 @@ impl ClientMessage {
                );
                Ok(SerialisedRequest::new(req.to_bytes()?, id))
            }
+            _ => Err(Error::UnsupportedMessage),
        }
    }

@@ -237,6 +243,7 @@ impl ClientMessage {
                });
                Ok(SerialisedRequest::new(req.to_bytes()?, id))
            }
+            _ => Err(Error::UnsupportedMessage),
        }
    }

@@ -245,6 +252,7 @@ impl ClientMessage {
            registration::{ClientMac, FinalMessage, GatewayClient, InitMessage, IpPair},
            request::AuthenticatorRequest,
            topup::TopUpMessage,
+            upgrade_mode_check::UpgradeModeCheckRequest,
        };
        match self {
            ClientMessage::Initial(init_message) => {
@@ -282,6 +290,22 @@ impl ClientMessage {
                });
                Ok(SerialisedRequest::new(req.to_bytes()?, id))
            }
+            ClientMessage::UpgradeModeCheck(upgrade_mode_check) => {
+                // currently JWT is the only emergency credential option
+                let Some(upgrade_mode_jwt) =
+                    upgrade_mode_check.upgrade_mode_global_attestation_jwt()
+                else {
+                    return Err(Error::conversion(
+                        "no valid known upgrade mode check variants",
+                    ));
+                };
+                let msg = UpgradeModeCheckRequest::UpgradeModeJwt {
+                    token: upgrade_mode_jwt,
+                };
+
+                let (req, id) = AuthenticatorRequest::new_upgrade_mode_check_request(msg);
+                Ok(SerialisedRequest::new(req.to_bytes()?, id))
+            }
        }
    }
 }
@@ -292,7 +316,7 @@ impl ClientMessage {
        match self {
            Self::Final(msg) => msg.credential().is_some(),
            Self::TopUp(_) => true,
-            Self::Initial(_) | Self::Query(_) => false,
+            Self::Initial(_) | Self::Query(_) | Self::UpgradeModeCheck(_) => false,
        }
    }

@@ -302,6 +326,7 @@ impl ClientMessage {
            ClientMessage::Final(msg) => msg.version(),
            ClientMessage::Query(msg) => msg.version(),
            ClientMessage::TopUp(msg) => msg.version(),
+            ClientMessage::UpgradeModeCheck(msg) => msg.version(),
        }
    }

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0

 pub mod client_message;
+pub mod models;
 pub mod request;
 pub mod response;
 pub mod traits;
@@ -0,0 +1,58 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use nym_credentials_interface::{
+    BandwidthCredential, CredentialSpendingData, TicketType, UnknownTicketType,
+};
+use serde::{Deserialize, Serialize};
+
+#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq)]
+pub enum CurrentUpgradeModeStatus {
+    Enabled,
+    Disabled,
+    // everything pre-v6
+    Unknown,
+}
+
+impl CurrentUpgradeModeStatus {
+    pub fn is_enabled(&self) -> bool {
+        matches!(self, CurrentUpgradeModeStatus::Enabled)
+    }
+}
+
+impl From<bool> for CurrentUpgradeModeStatus {
+    fn from(value: bool) -> Self {
+        if value {
+            CurrentUpgradeModeStatus::Enabled
+        } else {
+            CurrentUpgradeModeStatus::Disabled
+        }
+    }
+}
+
+impl From<CurrentUpgradeModeStatus> for Option<bool> {
+    fn from(value: CurrentUpgradeModeStatus) -> Self {
+        match value {
+            CurrentUpgradeModeStatus::Enabled => Some(true),
+            CurrentUpgradeModeStatus::Disabled => Some(false),
+            CurrentUpgradeModeStatus::Unknown => None,
+        }
+    }
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
+pub struct BandwidthClaim {
+    pub credential: BandwidthCredential,
+    pub kind: TicketType,
+}
+
+impl TryFrom<CredentialSpendingData> for BandwidthClaim {
+    type Error = UnknownTicketType;
+
+    fn try_from(credential: CredentialSpendingData) -> Result<Self, Self::Error> {
+        Ok(BandwidthClaim {
+            kind: TicketType::try_from_encoded(credential.payment.t_type)?,
+            credential: BandwidthCredential::from(credential),
+        })
+    }
+}
@@ -4,7 +4,9 @@
 use nym_service_provider_requests_common::{Protocol, ServiceProviderType};
 use nym_sphinx::addressing::Recipient;

-use crate::traits::{FinalMessage, InitMessage, QueryBandwidthMessage, TopUpMessage};
+use crate::traits::{
+    FinalMessage, InitMessage, QueryBandwidthMessage, TopUpMessage, UpgradeModeMessage,
+};
 use crate::{v1, v2, v3, v4, v5, v6};

 #[derive(Debug)]
@@ -33,6 +35,11 @@ pub enum AuthenticatorRequest {
        reply_to: Option<Recipient>,
        request_id: u64,
    },
+    CheckUpgradeMode {
+        msg: Box<dyn UpgradeModeMessage + Send + Sync + 'static>,
+        protocol: Protocol,
+        request_id: u64,
+    },
 }

 impl From<v1::request::AuthenticatorRequest> for AuthenticatorRequest {
@@ -234,6 +241,13 @@ impl From<v6::request::AuthenticatorRequest> for AuthenticatorRequest {
                    request_id: value.request_id,
                }
            }
+            v6::request::AuthenticatorRequestData::CheckUpgradeMode(upgrade_mode_check_msg) => {
+                Self::CheckUpgradeMode {
+                    msg: Box::new(upgrade_mode_check_msg),
+                    protocol: value.protocol,
+                    request_id: value.request_id,
+                }
+            }
        }
    }
 }
@@ -1,9 +1,10 @@
 // Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

+use crate::models::CurrentUpgradeModeStatus;
 use crate::traits::{
-    CurrentUpgradeModeStatus, Id, PendingRegistrationResponse, RegisteredResponse,
-    RemainingBandwidthResponse, TopUpBandwidthResponse, UpgradeModeStatus,
+    Id, PendingRegistrationResponse, RegisteredResponse, RemainingBandwidthResponse,
+    TopUpBandwidthResponse, UpgradeModeStatus,
 };
 use crate::{v2, v3, v4, v5, v6};

@@ -13,6 +14,7 @@ pub enum AuthenticatorResponse {
    Registered(Box<dyn RegisteredResponse + Send + Sync + 'static>),
    RemainingBandwidth(Box<dyn RemainingBandwidthResponse + Send + Sync + 'static>),
    TopUpBandwidth(Box<dyn TopUpBandwidthResponse + Send + Sync + 'static>),
+    UpgradeMode(Box<dyn UpgradeModeStatus + Send + Sync + 'static>),
 }

 impl UpgradeModeStatus for AuthenticatorResponse {
@@ -30,6 +32,9 @@ impl UpgradeModeStatus for AuthenticatorResponse {
            AuthenticatorResponse::TopUpBandwidth(top_up_bandwidth_response) => {
                top_up_bandwidth_response.upgrade_mode_status()
            }
+            AuthenticatorResponse::UpgradeMode(upgrade_mode_response) => {
+                upgrade_mode_response.upgrade_mode_status()
+            }
        }
    }
 }
@@ -47,6 +52,7 @@ impl Id for AuthenticatorResponse {
            AuthenticatorResponse::TopUpBandwidth(top_up_bandwidth_response) => {
                top_up_bandwidth_response.id()
            }
+            AuthenticatorResponse::UpgradeMode(upgrade_mode_response) => upgrade_mode_response.id(),
        }
    }
 }
@@ -139,6 +145,9 @@ impl From<v6::response::AuthenticatorResponse> for AuthenticatorResponse {
            v6::response::AuthenticatorResponseData::TopUpBandwidth(top_up_bandwidth_response) => {
                Self::TopUpBandwidth(Box::new(top_up_bandwidth_response))
            }
+            v6::response::AuthenticatorResponseData::UpgradeMode(upgrade_mode_check_response) => {
+                Self::UpgradeMode(Box::new(upgrade_mode_check_response))
+            }
        }
    }
 }
@@ -1,70 +1,16 @@
 // Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

-use std::fmt;
-use std::net::{Ipv4Addr, Ipv6Addr};
-
 use crate::latest::registration::IpPair;
+use crate::models::{BandwidthClaim, CurrentUpgradeModeStatus};
 use crate::{AuthenticatorVersion, Error, v1, v2, v3, v4, v5, v6};
-use nym_credentials_interface::{
-    BandwidthCredential, CredentialSpendingData, TicketType, UnknownTicketType,
-};
+use nym_credentials_interface::CredentialSpendingData;
 use nym_crypto::asymmetric::x25519;
 use nym_wireguard_types::PeerPublicKey;
-use serde::{Deserialize, Serialize};
+use std::fmt;
+use std::net::{Ipv4Addr, Ipv6Addr};
 use tracing::error;

-#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq)]
-pub enum CurrentUpgradeModeStatus {
-    Enabled,
-    Disabled,
-    // everything pre-v6
-    Unknown,
-}
-
-impl CurrentUpgradeModeStatus {
-    pub fn is_enabled(&self) -> bool {
-        matches!(self, CurrentUpgradeModeStatus::Enabled)
-    }
-}
-
-impl From<bool> for CurrentUpgradeModeStatus {
-    fn from(value: bool) -> Self {
-        if value {
-            CurrentUpgradeModeStatus::Enabled
-        } else {
-            CurrentUpgradeModeStatus::Disabled
-        }
-    }
-}
-
-impl From<CurrentUpgradeModeStatus> for Option<bool> {
-    fn from(value: CurrentUpgradeModeStatus) -> Self {
-        match value {
-            CurrentUpgradeModeStatus::Enabled => Some(true),
-            CurrentUpgradeModeStatus::Disabled => Some(false),
-            CurrentUpgradeModeStatus::Unknown => None,
-        }
-    }
-}
-
-#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
-pub struct BandwidthClaim {
-    pub credential: BandwidthCredential,
-    pub kind: TicketType,
-}
-
-impl TryFrom<CredentialSpendingData> for BandwidthClaim {
-    type Error = UnknownTicketType;
-
-    fn try_from(credential: CredentialSpendingData) -> Result<Self, Self::Error> {
-        Ok(BandwidthClaim {
-            kind: TicketType::try_from_encoded(credential.payment.t_type)?,
-            credential: BandwidthCredential::from(credential),
-        })
-    }
-}
-
 pub trait Versionable {
    fn version(&self) -> AuthenticatorVersion;
 }
@@ -170,7 +116,13 @@ impl Versionable for v6::topup::TopUpMessage {
    }
 }

-pub trait UpgradeModeStatus {
+impl Versionable for v6::upgrade_mode_check::UpgradeModeCheckRequest {
+    fn version(&self) -> AuthenticatorVersion {
+        AuthenticatorVersion::V6
+    }
+}
+
+pub trait UpgradeModeStatus: Id + fmt::Debug {
    fn upgrade_mode_status(&self) -> CurrentUpgradeModeStatus;
 }

@@ -305,6 +257,12 @@ impl UpgradeModeStatus for v6::response::TopUpBandwidthResponse {
    }
 }

+impl UpgradeModeStatus for v6::response::UpgradeModeResponse {
+    fn upgrade_mode_status(&self) -> CurrentUpgradeModeStatus {
+        self.upgrade_mode_enabled.into()
+    }
+}
+
 pub trait InitMessage: Versionable + fmt::Debug {
    fn pub_key(&self) -> PeerPublicKey;
 }
@@ -616,10 +574,32 @@ impl TopUpMessage for v6::topup::TopUpMessage {
    }
 }

+pub trait UpgradeModeMessage: Versionable + fmt::Debug {
+    // the idea is to expose different types of emergency credentials here,
+    // like upgrade mode JWT, emergency threshold credential issued by signers, etc.
+    fn upgrade_mode_global_attestation_jwt(&self) -> Option<String>;
+}
+
+impl UpgradeModeMessage for v6::upgrade_mode_check::UpgradeModeCheckRequest {
+    fn upgrade_mode_global_attestation_jwt(&self) -> Option<String> {
+        use v6::upgrade_mode_check::UpgradeModeCheckRequest;
+
+        match self {
+            UpgradeModeCheckRequest::UpgradeModeJwt { token } => Some(token.clone()),
+        }
+    }
+}
+
 pub trait Id {
    fn id(&self) -> u64;
 }

+impl Id for v1::response::PendingRegistrationResponse {
+    fn id(&self) -> u64 {
+        self.request_id
+    }
+}
+
 impl Id for v2::response::PendingRegistrationResponse {
    fn id(&self) -> u64 {
        self.request_id
@@ -650,6 +630,12 @@ impl Id for v6::response::PendingRegistrationResponse {
    }
 }

+impl Id for v1::response::RegisteredResponse {
+    fn id(&self) -> u64 {
+        self.request_id
+    }
+}
+
 impl Id for v2::response::RegisteredResponse {
    fn id(&self) -> u64 {
        self.request_id
@@ -680,6 +666,12 @@ impl Id for v6::response::RegisteredResponse {
    }
 }

+impl Id for v1::response::RemainingBandwidthResponse {
+    fn id(&self) -> u64 {
+        self.request_id
+    }
+}
+
 impl Id for v2::response::RemainingBandwidthResponse {
    fn id(&self) -> u64 {
        self.request_id
@@ -734,6 +726,12 @@ impl Id for v6::response::TopUpBandwidthResponse {
    }
 }

+impl Id for v6::response::UpgradeModeResponse {
+    fn id(&self) -> u64 {
+        self.request_id
+    }
+}
+
 pub trait PendingRegistrationResponse: Id + UpgradeModeStatus + fmt::Debug {
    fn nonce(&self) -> u64;
    fn verify(&self, gateway_key: &x25519::PrivateKey) -> Result<(), Error>;
@@ -245,7 +245,7 @@ mod tests {
    use x25519_dalek::PublicKey;

    use super::*;
-    use crate::traits::BandwidthClaim;
+    use crate::models::BandwidthClaim;
    use crate::{util::tests::CREDENTIAL_BYTES, v5};

    #[test]
@@ -8,6 +8,7 @@ pub mod registration;
 pub mod request;
 pub mod response;
 pub mod topup;
+pub mod upgrade_mode_check;

 pub const VERSION: u8 = 6;

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0

 use crate::error::Error;
+use crate::models::BandwidthClaim;
 use base64::{Engine, engine::general_purpose};
 use nym_network_defaults::constants::{WG_TUN_DEVICE_IP_ADDRESS_V4, WG_TUN_DEVICE_IP_ADDRESS_V6};
 use nym_wireguard_types::PeerPublicKey;
@@ -11,7 +12,6 @@ use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
 use std::time::SystemTime;
 use std::{fmt, ops::Deref, str::FromStr};

-use crate::traits::BandwidthClaim;
 #[cfg(feature = "verify")]
 use hmac::{Hmac, Mac};
 #[cfg(feature = "verify")]
@@ -5,6 +5,7 @@ use super::{
    PROTOCOL,
    registration::{FinalMessage, InitMessage},
    topup::TopUpMessage,
+    upgrade_mode_check::UpgradeModeCheckRequest,
 };
 use nym_service_provider_requests_common::Protocol;
 use nym_wireguard_types::PeerPublicKey;
@@ -81,6 +82,18 @@ impl AuthenticatorRequest {
        )
    }

+    pub fn new_upgrade_mode_check_request(message: UpgradeModeCheckRequest) -> (Self, u64) {
+        let request_id = generate_random();
+        (
+            Self {
+                protocol: PROTOCOL,
+                data: AuthenticatorRequestData::CheckUpgradeMode(message),
+                request_id,
+            },
+            request_id,
+        )
+    }
+
    pub fn to_bytes(&self) -> Result<Vec<u8>, bincode::Error> {
        use bincode::Options;
        make_bincode_serializer().serialize(self)
@@ -93,6 +106,7 @@ pub enum AuthenticatorRequestData {
    Final(Box<FinalMessage>),
    QueryBandwidth(PeerPublicKey),
    TopUpBandwidth(Box<TopUpMessage>),
+    CheckUpgradeMode(UpgradeModeCheckRequest),
 }

 #[cfg(test)]
@@ -76,6 +76,16 @@ impl AuthenticatorResponse {
        }
    }

+    pub fn new_upgrade_mode_check(request_id: u64, upgrade_mode_enabled: bool) -> Self {
+        Self {
+            protocol: PROTOCOL,
+            data: AuthenticatorResponseData::UpgradeMode(UpgradeModeResponse {
+                request_id,
+                upgrade_mode_enabled,
+            }),
+        }
+    }
+
    pub fn to_bytes(&self) -> Result<Vec<u8>, bincode::Error> {
        use bincode::Options;
        make_bincode_serializer().serialize(self)
@@ -94,6 +104,7 @@ impl AuthenticatorResponse {
            AuthenticatorResponseData::Registered(response) => Some(response.request_id),
            AuthenticatorResponseData::RemainingBandwidth(response) => Some(response.request_id),
            AuthenticatorResponseData::TopUpBandwidth(response) => Some(response.request_id),
+            AuthenticatorResponseData::UpgradeMode(response) => Some(response.request_id),
        }
    }
 }
@@ -104,6 +115,7 @@ pub enum AuthenticatorResponseData {
    Registered(RegisteredResponse),
    RemainingBandwidth(RemainingBandwidthResponse),
    TopUpBandwidth(TopUpBandwidthResponse),
+    UpgradeMode(UpgradeModeResponse),
 }

 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
@@ -133,3 +145,9 @@ pub struct TopUpBandwidthResponse {
    pub reply: RemainingBandwidthData,
    pub upgrade_mode_enabled: bool,
 }
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+pub struct UpgradeModeResponse {
+    pub request_id: u64,
+    pub upgrade_mode_enabled: bool,
+}
@@ -0,0 +1,12 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use serde::{Deserialize, Serialize};
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
+#[non_exhaustive]
+pub enum UpgradeModeCheckRequest {
+    /// Attempt to request upgrade mode recheck via the JWT issued as the result of
+    /// global attestation.json being published
+    UpgradeModeJwt { token: String },
+}
@@ -22,7 +22,7 @@ pub enum AuthenticatorVersion {
    /// introduced in dorina-patched release (1.6.1)
    V5,

-    /// introduced in yet to be named release, currently aiming for Leerdammer (1.22.0)
+    /// introduced in niolo release (1.23.0)
    V6,

    /// an unknown, future, variant that can be present if running outdated software
@@ -32,9 +32,6 @@ pub enum AuthenticatorVersion {
 impl AuthenticatorVersion {
    pub const LATEST: Self = Self::V6;

-    #[deprecated(
-        note = "the final version of V6 won't be known until appropriate release is scheduled. after that happens From<semver::Version> trait will have to be adjusted"
-    )]
    pub const fn release_version(&self) -> semver::Version {
        match self {
            AuthenticatorVersion::V1 => semver::Version::new(1, 1, 5),
@@ -42,7 +39,7 @@ impl AuthenticatorVersion {
            AuthenticatorVersion::V3 => semver::Version::new(1, 1, 10),
            AuthenticatorVersion::V4 => semver::Version::new(1, 2, 0),
            AuthenticatorVersion::V5 => semver::Version::new(1, 6, 1),
-            AuthenticatorVersion::V6 => semver::Version::new(1, 22, 0),
+            AuthenticatorVersion::V6 => semver::Version::new(1, 23, 0),
            AuthenticatorVersion::UNKNOWN => semver::Version::new(0, 0, 0),
        }
    }
@@ -206,8 +203,9 @@ mod tests {
        assert_eq!(AuthenticatorVersion::V5, "1.7.0".into());
        assert_eq!(AuthenticatorVersion::V5, "1.16.11".into());
        assert_eq!(AuthenticatorVersion::V5, "1.17.0".into());
-        assert_eq!(AuthenticatorVersion::V5, "1.20.0".into());
-        assert_eq!(AuthenticatorVersion::V6, "1.21.0".into());
-        assert_eq!(AuthenticatorVersion::V6, "1.22.0".into());
+        assert_eq!(AuthenticatorVersion::V5, "1.22.0".into());
+        assert_eq!(AuthenticatorVersion::V6, "1.23.0".into());
+        assert_eq!(AuthenticatorVersion::V6, "1.23.1".into());
+        assert_eq!(AuthenticatorVersion::V6, "1.24.0".into());
    }
 }
@@ -21,6 +21,9 @@ pub enum BandwidthControllerError {
    #[error("There was a credential storage error - {0}")]
    CredentialStorageError(Box<dyn std::error::Error + Send + Sync>),

+    #[error("retrieved upgrade mode token is not a valid String")]
+    MalformedUpgradeModeToken,
+
    #[error("the credential storage does not contain any usable credentials")]
    NoCredentialsAvailable,

@@ -228,7 +228,10 @@ impl<C, St: Storage> BandwidthController<C, St> {
    where
        <St as Storage>::StorageError: Send + Sync + 'static,
    {
-        self.storage.get_emergency_credential(typ).await
+        self.storage
+            .get_emergency_credential(typ)
+            .await
+            .map_err(BandwidthControllerError::credential_storage_error)
    }
 }

@@ -52,11 +52,8 @@ where
            return Ok(None);
        };
        // upgrade mode credential is just a simple stringified JWT
-        let token = String::from_utf8(emergency_credential.content).map_err(|err| {
-            BandwidthControllerError::CredentialStorageError(Box::new(format!(
-                "malformed upgrade mode token: {err}"
-            )))
-        })?;
+        let token = String::from_utf8(emergency_credential.data.content)
+            .map_err(|_| BandwidthControllerError::MalformedUpgradeModeToken)?;
        Ok(Some(token))
    }
 }
@@ -81,6 +81,10 @@ pub struct CommonClientInitArgs {
    #[cfg_attr(feature = "cli", clap(long, hide = true))]
    pub enabled_credentials_mode: Option<bool>,

+    /// Change the default minimum node performance used during initial node selection filtering.
+    #[cfg_attr(feature = "cli", clap(long, hide = true))]
+    pub minimum_gateway_performance: Option<u8>,
+
    /// Mostly debug-related option to increase default traffic rate so that you would not need to
    /// modify config post init
    #[cfg_attr(feature = "cli", clap(long, hide = true))]
@@ -173,10 +177,14 @@ where
        })?;
        hardcoded_topology.entry_capable_nodes().cloned().collect()
    } else {
+        let minimum_performance = common_args
+            .minimum_gateway_performance
+            .unwrap_or(core.debug.topology.minimum_gateway_performance);
+
        crate::init::helpers::gateways_for_init(
            &core.client.nym_api_urls,
            user_agent,
-            core.debug.topology.minimum_gateway_performance,
+            minimum_performance,
            core.debug.topology.ignore_ingress_epoch_role,
            None,
        )
@@ -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()
        }
@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0

 use crate::error::GatewayClientError;
-use nym_network_defaults::TicketTypeRepr::V1MixnetEntry;
+use nym_credentials_interface::DEFAULT_MIXNET_REQUEST_BANDWIDTH_THRESHOLD;
 use si_scale::helpers::bibytes2;
 use std::time::Duration;

@@ -103,7 +103,7 @@ impl BandwidthTickets {

    // 20% of entry ticket value
    pub const DEFAULT_REMAINING_BANDWIDTH_THRESHOLD: i64 =
-        (V1MixnetEntry.bandwidth_value() / 5) as i64;
+        DEFAULT_MIXNET_REQUEST_BANDWIDTH_THRESHOLD;

    pub const DEFAULT_CUTOFF_REMAINING_BANDWIDTH_THRESHOLD: Option<i64> = None;

@@ -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,
@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0

 use crate::bandwidth::ClientBandwidth;
+use crate::client::config::BandwidthTickets;
 use crate::error::GatewayClientError;
 use crate::packet_router::PacketRouter;
 use crate::traits::GatewayPacketRouter;
@@ -177,7 +178,20 @@ impl PartiallyDelegatedRouter {
                        let available_bi2 = bibytes2(available as f64);
                        let required_bi2 = bibytes2(required as f64);
                        warn!("run out of bandwidth when attempting to send the message! we got {available_bi2} available, but needed at least {required_bi2} to send the previous message");
-                        self.client_bandwidth.update_and_log(available, None);
+                        // if we run out of bandwidth (and tried to send reasonable amount of data),
+                        // the upgrade mode is implicitly disabled, as otherwise we would have been
+                        // to proceed
+                        let upgrade_mode = if available
+                            < BandwidthTickets::DEFAULT_REMAINING_BANDWIDTH_THRESHOLD
+                        {
+                            Some(false)
+                        } else {
+                            // we were attempting to send a lot of data at once
+                            // - we have no certainty about upgrade mode at this point
+                            None
+                        };
+                        self.client_bandwidth
+                            .update_and_log(available, upgrade_mode);
                        // UNIMPLEMENTED: we should stop sending messages until we recover bandwidth
                        Ok(())
                    }
@@ -75,6 +75,7 @@ workspace = true
 features = ["json", "rustls-tls"]

 [dev-dependencies]
+anyhow = { workspace = true }
 bip39 = { workspace = true }
 cosmrs = { workspace = true, features = ["bip32"] }
 ts-rs = { workspace = true }
@@ -7,6 +7,7 @@ use cosmrs::{tx, AccountId, Coin, Denom};
 use nym_validator_client::http_client;
 use nym_validator_client::nyxd::CosmWasmClient;
 use nym_validator_client::signing::direct_wallet::DirectSecp256k1HdWallet;
+use nym_validator_client::signing::signer::OfflineSigner;
 use nym_validator_client::signing::tx_signer::TxSigner;
 use nym_validator_client::signing::SignerData;

@@ -19,8 +20,8 @@ async fn main() {
    let validator = "https://rpc.sandbox.nymtech.net";
    let to_address: AccountId = "n1pefc2utwpy5w78p2kqdsfmpjxfwmn9d39k5mqa".parse().unwrap();

-    let signer = DirectSecp256k1HdWallet::from_mnemonic(prefix, signer_mnemonic);
-    let signer_address = signer.try_derive_accounts().unwrap()[0].address().clone();
+    let signer = DirectSecp256k1HdWallet::checked_from_mnemonic(prefix, signer_mnemonic).unwrap();
+    let signer_address = signer.signer_addresses()[0].clone();

    // local 'client' ONLY signing messages
    let tx_signer = signer;
@@ -57,9 +58,15 @@ async fn main() {
        100000u32,
    );

-    let tx_raw = tx_signer
-        .sign_direct(&signer_address, vec![send_msg], fee, memo, signer_data)
-        .unwrap();
+    let tx_raw = TxSigner::sign_direct(
+        &tx_signer,
+        &signer_address,
+        vec![send_msg],
+        fee,
+        memo,
+        signer_data,
+    )
+    .unwrap();
    let tx_bytes = tx_raw.to_bytes().unwrap();

    // compare balances from before and after the tx
@@ -5,8 +5,7 @@ use crate::nyxd::{self, NyxdClient};
 use crate::signing::direct_wallet::DirectSecp256k1HdWallet;
 use crate::signing::signer::{NoSigner, OfflineSigner};
 use crate::{
-    DirectSigningReqwestRpcValidatorClient, QueryReqwestRpcValidatorClient, ReqwestRpcClient,
-    ValidatorClientError,
+    DirectSigningReqwestRpcValidatorClient, QueryReqwestRpcValidatorClient, ValidatorClientError,
 };
 use nym_api_requests::ecash::models::{
    AggregatedCoinIndicesSignatureResponse, AggregatedExpirationDateSignatureResponse,
@@ -164,7 +163,7 @@ impl Client<HttpRpcClient, DirectSecp256k1HdWallet> {
    ) -> Result<DirectSigningHttpRpcValidatorClient, ValidatorClientError> {
        let rpc_client = http_client(config.nyxd_url.as_str())?;
        let prefix = &config.nyxd_config.chain_details.bech32_account_prefix;
-        let wallet = DirectSecp256k1HdWallet::from_mnemonic(prefix, mnemonic);
+        let wallet = DirectSecp256k1HdWallet::checked_from_mnemonic(prefix, mnemonic)?;

        Ok(Self::new_signing_with_rpc_client(
            config, rpc_client, wallet,
@@ -177,12 +176,13 @@ impl Client<HttpRpcClient, DirectSecp256k1HdWallet> {
    }
 }

-impl Client<ReqwestRpcClient, DirectSecp256k1HdWallet> {
+#[allow(deprecated)]
+impl Client<crate::ReqwestRpcClient, DirectSecp256k1HdWallet> {
    pub fn new_reqwest_signing(
        config: Config,
        mnemonic: bip39::Mnemonic,
    ) -> DirectSigningReqwestRpcValidatorClient {
-        let rpc_client = ReqwestRpcClient::new(config.nyxd_url.clone());
+        let rpc_client = crate::ReqwestRpcClient::new(config.nyxd_url.clone());
        let prefix = &config.nyxd_config.chain_details.bech32_account_prefix;
        let wallet = DirectSecp256k1HdWallet::from_mnemonic(prefix, mnemonic);

@@ -203,9 +203,10 @@ impl Client<HttpRpcClient> {
    }
 }

-impl Client<ReqwestRpcClient> {
+#[allow(deprecated)]
+impl Client<crate::ReqwestRpcClient> {
    pub fn new_reqwest_query(config: Config) -> QueryReqwestRpcValidatorClient {
-        let rpc_client = ReqwestRpcClient::new(config.nyxd_url.clone());
+        let rpc_client = crate::ReqwestRpcClient::new(config.nyxd_url.clone());
        Self::new_with_rpc_client(config, rpc_client)
    }
 }
@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0

 use crate::nym_api;
+use crate::signing::direct_wallet::DirectSecp256k1HdWalletError;
 pub use tendermint_rpc::error::Error as TendermintRpcError;
 use thiserror::Error;

@@ -26,6 +27,12 @@ pub enum ValidatorClientError {

    #[error("No validator API url has been provided")]
    NoAPIUrlAvailable,
+
+    #[error("failed to derive signing accounts: {source}")]
+    AccountDerivationFailure {
+        #[from]
+        source: DirectSecp256k1HdWalletError,
+    },
 }

 impl From<nym_api::error::NymAPIError> for ValidatorClientError {
@@ -12,6 +12,7 @@ pub mod rpc;
 pub mod signing;

 pub use crate::error::ValidatorClientError;
+#[allow(deprecated)]
 pub use crate::rpc::reqwest::ReqwestRpcClient;
 pub use crate::signing::direct_wallet::DirectSecp256k1HdWallet;
 pub use client::{Client, Config, EcashApiClient};
@@ -38,9 +39,13 @@ pub type DirectSigningHttpRpcValidatorClient = Client<HttpRpcClient, DirectSecp2
 #[cfg(feature = "http-client")]
 pub type DirectSigningHttpRpcNyxdClient = nyxd::NyxdClient<HttpRpcClient, DirectSecp256k1HdWallet>;

+#[allow(deprecated)]
 pub type QueryReqwestRpcValidatorClient = Client<ReqwestRpcClient>;
+#[allow(deprecated)]
 pub type QueryReqwestRpcNyxdClient = nyxd::NyxdClient<ReqwestRpcClient>;

+#[allow(deprecated)]
 pub type DirectSigningReqwestRpcValidatorClient = Client<ReqwestRpcClient, DirectSecp256k1HdWallet>;
+#[allow(deprecated)]
 pub type DirectSigningReqwestRpcNyxdClient =
    nyxd::NyxdClient<ReqwestRpcClient, DirectSecp256k1HdWallet>;
@@ -178,7 +178,7 @@ where
            .ok_or_else(|| NyxdError::unavailable_contract_address("dkg contract"))?;

        let fee = fee.unwrap_or(Fee::Auto(Some(self.simulated_gas_multiplier())));
-        let signer_address = &self.signer_addresses()?[0];
+        let signer_address = &self.signer_addresses()[0];

        self.execute(signer_address, dkg_contract_address, &msg, fee, memo, funds)
            .await
@@ -99,7 +99,7 @@ where
            .ok_or_else(|| NyxdError::unavailable_contract_address("coconut bandwidth contract"))?;

        let fee = fee.unwrap_or(Fee::Auto(Some(self.simulated_gas_multiplier())));
-        let signer_address = &self.signer_addresses()?[0];
+        let signer_address = &self.signer_addresses()[0];

        self.execute(
            signer_address,
@@ -95,7 +95,7 @@ where

        let fee = fee.unwrap_or(Fee::Auto(Some(self.simulated_gas_multiplier())));

-        let signer_address = &self.signer_addresses()?[0];
+        let signer_address = &self.signer_addresses()[0];
        self.execute(
            signer_address,
            group_contract_address,
@@ -667,7 +667,7 @@ where
        let fee = fee.unwrap_or(Fee::Auto(Some(self.simulated_gas_multiplier())));
        let memo = msg.default_memo();

-        let signer_address = &self.signer_addresses()?[0];
+        let signer_address = &self.signer_addresses()[0];
        self.execute(
            signer_address,
            mixnet_contract_address,
@@ -133,7 +133,7 @@ where

        let fee = fee.unwrap_or(Fee::Auto(Some(self.simulated_gas_multiplier())));

-        let signer_address = &self.signer_addresses()?[0];
+        let signer_address = &self.signer_addresses()[0];
        self.execute(
            signer_address,
            multisig_contract_address,
@@ -165,7 +165,7 @@ where

        let fee = fee.unwrap_or(Fee::Auto(Some(self.simulated_gas_multiplier())));

-        let signer_address = &self.signer_addresses()?[0];
+        let signer_address = &self.signer_addresses()[0];
        self.execute(
            signer_address,
            performance_contract_address,
@@ -375,7 +375,7 @@ where
        let fee = fee.unwrap_or(Fee::Auto(Some(self.simulated_gas_multiplier())));
        let memo = msg.name().to_string();

-        let signer_address = &self.signer_addresses()?[0];
+        let signer_address = &self.signer_addresses()[0];
        self.execute(
            signer_address,
            vesting_contract_address,
@@ -324,7 +324,7 @@ where
 {
    type Error = S::Error;

-    fn get_accounts(&self) -> Result<Vec<AccountData>, Self::Error> {
+    fn get_accounts(&self) -> &[AccountData] {
        self.signer.get_accounts()
    }

@@ -19,7 +19,7 @@ use crate::signing::signer::NoSigner;
 use crate::signing::signer::OfflineSigner;
 use crate::signing::tx_signer::TxSigner;
 use crate::signing::AccountData;
-use crate::{DirectSigningReqwestRpcNyxdClient, QueryReqwestRpcNyxdClient, ReqwestRpcClient};
+use crate::{DirectSigningReqwestRpcNyxdClient, QueryReqwestRpcNyxdClient};
 use async_trait::async_trait;
 use cosmrs::tendermint::{abci, evidence::Evidence, Genesis};
 use cosmrs::tx::{Raw, SignDoc};
@@ -158,12 +158,13 @@ impl NyxdClient<HttpClient> {
    }
 }

-impl NyxdClient<ReqwestRpcClient> {
+#[allow(deprecated)]
+impl NyxdClient<crate::ReqwestRpcClient> {
    pub fn connect_reqwest(
        config: Config,
        endpoint: Url,
    ) -> Result<QueryReqwestRpcNyxdClient, NyxdError> {
-        let client = ReqwestRpcClient::new(endpoint);
+        let client = crate::ReqwestRpcClient::new(endpoint);

        Ok(NyxdClient {
            client: MaybeSigningClient::new(client, (&config).into()),
@@ -195,18 +196,19 @@ impl NyxdClient<HttpClient, DirectSecp256k1HdWallet> {
        let client = http_client(endpoint)?;

        let prefix = &config.chain_details.bech32_account_prefix;
-        let wallet = DirectSecp256k1HdWallet::from_mnemonic(prefix, mnemonic);
+        let wallet = DirectSecp256k1HdWallet::checked_from_mnemonic(prefix, mnemonic)?;
        Ok(Self::connect_with_signer(config, client, wallet))
    }
 }

-impl NyxdClient<ReqwestRpcClient, DirectSecp256k1HdWallet> {
+#[allow(deprecated)]
+impl NyxdClient<crate::ReqwestRpcClient, DirectSecp256k1HdWallet> {
    pub fn connect_reqwest_with_mnemonic(
        config: Config,
        endpoint: Url,
        mnemonic: bip39::Mnemonic,
    ) -> DirectSigningReqwestRpcNyxdClient {
-        let client = ReqwestRpcClient::new(endpoint);
+        let client = crate::ReqwestRpcClient::new(endpoint);

        let prefix = &config.chain_details.bech32_account_prefix;
        let wallet = DirectSecp256k1HdWallet::from_mnemonic(prefix, mnemonic);
@@ -391,17 +393,12 @@ where
    S: OfflineSigner + Send + Sync,
    NyxdError: From<<S as OfflineSigner>::Error>,
 {
-    pub fn signing_account(&self) -> Result<AccountData, NyxdError> {
+    pub fn signing_account(&self) -> Result<&AccountData, NyxdError> {
        Ok(self.find_account(&self.address())?)
    }

    pub fn address(&self) -> AccountId {
-        match self.client.signer_addresses() {
-            Ok(addresses) => addresses[0].clone(),
-            Err(_) => {
-                panic!("key derivation failure")
-            }
-        }
+        self.client.signer_addresses()[0].clone()
    }

    pub fn mix_coin(&self, amount: u128) -> Coin {
@@ -867,7 +864,7 @@ where
 {
    type Error = S::Error;

-    fn get_accounts(&self) -> Result<Vec<AccountData>, Self::Error> {
+    fn get_accounts(&self) -> &[AccountData] {
        self.client.get_accounts()
    }

@@ -42,12 +42,15 @@ macro_rules! perform_with_compat {
    }};
 }

+// the separate implementation is now completely redundant
+#[deprecated(note = "use HttpClient directly instead")]
 pub struct ReqwestRpcClient {
    compat: CompatMode,
    inner: reqwest::Client,
    url: Url,
 }

+#[allow(deprecated)]
 impl ReqwestRpcClient {
    pub fn new(url: Url) -> Self {
        ReqwestRpcClient {
@@ -131,6 +134,7 @@ impl TendermintRpcErrorMap for reqwest::Error {
    }
 }

+#[allow(deprecated)]
 #[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
 #[cfg_attr(not(target_arch = "wasm32"), async_trait)]
 impl TendermintRpcClient for ReqwestRpcClient {
@@ -2,18 +2,18 @@
 // SPDX-License-Identifier: Apache-2.0

 use crate::signing::signer::{OfflineSigner, SigningError};
-use crate::signing::{AccountData, Secp256k1Derivation};
-use cosmrs::bip32::{DerivationPath, XPrv};
-use cosmrs::crypto::secp256k1::SigningKey;
-use cosmrs::crypto::PublicKey;
+use crate::signing::{
+    derive_extended_private_key, derive_keypair, AccountData, Secp256k1Derivation, Secp256k1Keypair,
+};
+use bip32::XPrv;
+use cosmrs::bip32::DerivationPath;
 use cosmrs::tx;
 use cosmrs::tx::SignDoc;
 use nym_config::defaults;
+use std::borrow::Cow;
 use thiserror::Error;
 use zeroize::{Zeroize, ZeroizeOnDrop, Zeroizing};

-type Secp256k1Keypair = (SigningKey, PublicKey);
-
 #[derive(Debug, Error)]
 pub enum DirectSecp256k1HdWalletError {
    #[error(transparent)]
@@ -36,28 +36,22 @@ pub enum DirectSecp256k1HdWalletError {
 }

 // TODO: maybe lock this one behind feature flag?
-#[derive(Debug, Clone, Zeroize, ZeroizeOnDrop)]
+#[derive(Zeroize, ZeroizeOnDrop)]
 pub struct DirectSecp256k1HdWallet {
    /// Base secret
    secret: bip39::Mnemonic,

-    /// BIP39 seed
-    seed: [u8; 64],
-
-    // An unfortunate result of immature rust async story is that async traits (only available in the separate package)
-    // can't yet figure out everything and if we stored our derived account data on the struct,
-    // that would include the secret key which is a dyn EcdsaSigner and hence not Sync making the wallet
-    // not Sync and if used on the signing client in an async trait, it wouldn't be Send
-    /// Derivation instructions
+    /// Derived accounts
    #[zeroize(skip)]
-    accounts: Vec<Secp256k1Derivation>,
+    // unfortunately `dyn EcdsaSigner` does not guarantee Zeroize
+    accounts: Vec<AccountData>,
 }

 impl OfflineSigner for DirectSecp256k1HdWallet {
    type Error = DirectSecp256k1HdWalletError;

-    fn get_accounts(&self) -> Result<Vec<AccountData>, Self::Error> {
-        self.try_derive_accounts()
+    fn get_accounts(&self) -> &[AccountData] {
+        &self.accounts
    }

    fn sign_direct_with_account(
@@ -77,55 +71,27 @@ impl DirectSecp256k1HdWallet {
    }

    /// Restores a wallet from the given BIP39 mnemonic using default options.
+    #[deprecated(
+        note = "this function can potentially panic if accounts can't be derived correctly. please use .checked_from_mnemonic() instead"
+    )]
    pub fn from_mnemonic(prefix: &str, mnemonic: bip39::Mnemonic) -> Self {
+        // unfortunately due to backwards compatibility requirements,
+        // we can't change signature of this method
+        #[allow(deprecated)]
        DirectSecp256k1HdWalletBuilder::new(prefix).build(mnemonic)
    }

+    /// Restores a wallet from the given BIP39 mnemonic using default options.
+    pub fn checked_from_mnemonic(
+        prefix: &str,
+        mnemonic: bip39::Mnemonic,
+    ) -> Result<Self, DirectSecp256k1HdWalletError> {
+        DirectSecp256k1HdWalletBuilder::new(prefix).try_build(mnemonic)
+    }
+
    pub fn generate(prefix: &str, word_count: usize) -> Result<Self, DirectSecp256k1HdWalletError> {
        let mneomonic = bip39::Mnemonic::generate(word_count)?;
-        Ok(Self::from_mnemonic(prefix, mneomonic))
-    }
-
-    fn derive_keypair(
-        &self,
-        hd_path: &DerivationPath,
-    ) -> Result<Secp256k1Keypair, DirectSecp256k1HdWalletError> {
-        let extended_private_key = XPrv::derive_from_path(self.seed, hd_path)?;
-
-        let private_key: SigningKey = extended_private_key.into();
-        let public_key = private_key.public_key();
-
-        Ok((private_key, public_key))
-    }
-
-    pub fn derive_extended_private_key(
-        &self,
-        hd_path: &DerivationPath,
-    ) -> Result<XPrv, DirectSecp256k1HdWalletError> {
-        Ok(XPrv::derive_from_path(self.seed, hd_path)?)
-    }
-
-    pub fn try_derive_accounts(&self) -> Result<Vec<AccountData>, DirectSecp256k1HdWalletError> {
-        let mut accounts = Vec::with_capacity(self.accounts.len());
-        for derivation_info in &self.accounts {
-            let keypair = self.derive_keypair(&derivation_info.hd_path)?;
-
-            // it seems this can only fail if the provided account prefix is invalid
-            let address = keypair
-                .1
-                .account_id(&derivation_info.prefix)
-                .map_err(
-                    |source| DirectSecp256k1HdWalletError::AccountDerivationError { source },
-                )?;
-
-            accounts.push(AccountData {
-                address,
-                public_key: keypair.1,
-                private_key: keypair.0,
-            })
-        }
-
-        Ok(accounts)
+        Self::checked_from_mnemonic(prefix, mneomonic)
    }

    pub fn secret(&self) -> &bip39::Mnemonic {
@@ -142,6 +108,43 @@ impl DirectSecp256k1HdWallet {
    pub fn mnemonic_string(&self) -> Zeroizing<String> {
        Zeroizing::new(self.secret.to_string())
    }
+
+    pub fn account_seed<'a, P: Into<Cow<'a, str>>>(
+        &self,
+        bip39_password: P,
+    ) -> Zeroizing<[u8; 64]> {
+        Zeroizing::new(self.secret.to_seed(bip39_password))
+    }
+
+    /// Derive an extended private key from the stored account secret assuming no bip39 password
+    #[deprecated(
+        note = "use derive_extended_private_key_with_password to ensure correct derivation if used bip39 password"
+    )]
+    pub fn derive_extended_private_key(
+        &self,
+        hd_path: &DerivationPath,
+    ) -> Result<XPrv, DirectSecp256k1HdWalletError> {
+        let seed = self.account_seed("");
+        derive_extended_private_key(seed, hd_path)
+    }
+
+    pub fn derive_keypair<'a, P: Into<Cow<'a, str>>>(
+        &self,
+        hd_path: &DerivationPath,
+        bip39_password: P,
+    ) -> Result<Secp256k1Keypair, DirectSecp256k1HdWalletError> {
+        let seed = self.account_seed(bip39_password);
+        derive_keypair(seed, hd_path)
+    }
+
+    pub fn derive_extended_private_key_with_password<'a, P: Into<Cow<'a, str>>>(
+        &self,
+        hd_path: &DerivationPath,
+        bip39_password: P,
+    ) -> Result<XPrv, DirectSecp256k1HdWalletError> {
+        let seed = self.account_seed(bip39_password);
+        derive_extended_private_key(seed, hd_path)
+    }
 }

 #[must_use]
@@ -188,23 +191,39 @@ impl DirectSecp256k1HdWalletBuilder {
        self
    }

+    #[deprecated(
+        note = "this function can potentially panic if accounts can't be derived correctly. please use .try_build() instead"
+    )]
    pub fn build(self, mnemonic: bip39::Mnemonic) -> DirectSecp256k1HdWallet {
-        let seed = mnemonic.to_seed(&self.bip39_password);
+        // unfortunately due to backwards compatibility requirements,
+        // we can't change signature of this method
+        #[allow(clippy::expect_used)]
+        self.try_build(mnemonic)
+            .expect("account derivation failure")
+    }
+
+    pub fn try_build(
+        self,
+        mnemonic: bip39::Mnemonic,
+    ) -> Result<DirectSecp256k1HdWallet, DirectSecp256k1HdWalletError> {
+        let seed = Zeroizing::new(mnemonic.to_seed(&self.bip39_password));
        let prefix = self.prefix.clone();
        let accounts = self
            .hd_paths
            .iter()
-            .map(|hd_path| Secp256k1Derivation {
-                hd_path: hd_path.clone(),
-                prefix: prefix.clone(),
+            .map(|hd_path| {
+                Secp256k1Derivation {
+                    hd_path: hd_path.clone(),
+                    prefix: prefix.clone(),
+                }
+                .try_derive_account(&seed)
            })
-            .collect();
+            .collect::<Result<_, _>>()?;

-        DirectSecp256k1HdWallet {
+        Ok(DirectSecp256k1HdWallet {
            accounts,
-            seed,
            secret: mnemonic,
-        }
+        })
    }
 }

@@ -215,7 +234,7 @@ mod tests {
    use super::*;

    #[test]
-    fn generating_account_addresses() {
+    fn generating_account_addresses() -> anyhow::Result<()> {
        // test vectors produced from our js wallet
        let mnemonics = ["crush minute paddle tobacco message debate cabin peace bar jacket execute twenty winner view sure mask popular couch penalty fragile demise fresh pizza stove",
            "acquire rebel spot skin gun such erupt pull swear must define ill chief turtle today flower chunk truth battle claw rigid detail gym feel",
@@ -230,11 +249,10 @@ mod tests {
            "n17n9flp6jflljg6fp05dsy07wcprf2uuu8g40rf",
        ];
        for (idx, mnemonic) in mnemonics.iter().enumerate() {
-            let wallet = DirectSecp256k1HdWallet::from_mnemonic(&prefix, mnemonic.parse().unwrap());
-            assert_eq!(
-                wallet.try_derive_accounts().unwrap()[0].address,
-                addrs[idx].parse().unwrap()
-            )
+            let wallet =
+                DirectSecp256k1HdWallet::checked_from_mnemonic(&prefix, mnemonic.parse()?)?;
+            assert_eq!(wallet.signer_addresses()[0], addrs[idx].parse().unwrap());
        }
+        Ok(())
    }
 }
@@ -1,6 +1,8 @@
 // Copyright 2023 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

+use crate::signing::direct_wallet::DirectSecp256k1HdWalletError;
+use bip32::XPrv;
 use cosmrs::bip32::DerivationPath;
 use cosmrs::crypto::secp256k1::SigningKey;
 use cosmrs::crypto::PublicKey;
@@ -12,14 +14,64 @@ pub mod direct_wallet;
 pub mod signer;
 pub mod tx_signer;

+pub(crate) type Secp256k1Keypair = (SigningKey, PublicKey);
+
 /// Derivation information required to derive a keypair and an address from a mnemonic.
 #[derive(Debug, Clone)]
-struct Secp256k1Derivation {
+pub(crate) struct Secp256k1Derivation {
    hd_path: DerivationPath,
    prefix: String,
 }

-// TODO: is this struct going to be derivable with other signer types?
+impl Secp256k1Derivation {
+    pub(crate) fn try_derive_account<S>(
+        &self,
+        seed: S,
+    ) -> Result<AccountData, DirectSecp256k1HdWalletError>
+    where
+        S: AsRef<[u8]>,
+    {
+        let keypair = derive_keypair(seed, &self.hd_path)?;
+
+        // it seems this can only fail if the provided account prefix is invalid
+        let address = keypair
+            .1
+            .account_id(&self.prefix)
+            .map_err(|source| DirectSecp256k1HdWalletError::AccountDerivationError { source })?;
+
+        Ok(AccountData {
+            address,
+            public_key: keypair.1,
+            private_key: keypair.0,
+        })
+    }
+}
+
+pub fn derive_keypair<S>(
+    seed: S,
+    hd_path: &DerivationPath,
+) -> Result<Secp256k1Keypair, DirectSecp256k1HdWalletError>
+where
+    S: AsRef<[u8]>,
+{
+    let extended_private_key = derive_extended_private_key(seed, hd_path)?;
+
+    let private_key: SigningKey = extended_private_key.into();
+    let public_key = private_key.public_key();
+
+    Ok((private_key, public_key))
+}
+
+pub fn derive_extended_private_key<S>(
+    seed: S,
+    hd_path: &DerivationPath,
+) -> Result<XPrv, DirectSecp256k1HdWalletError>
+where
+    S: AsRef<[u8]>,
+{
+    Ok(XPrv::derive_from_path(seed, hd_path)?)
+}
+
 pub struct AccountData {
    pub address: AccountId,

@@ -33,23 +33,18 @@ pub enum SignerType {
 pub trait OfflineSigner {
    type Error: From<SigningError>;

-    // I really dislike existence of this function because it makes you re-derive your key **twice** for each contract transaction
-    fn signer_addresses(&self) -> Result<Vec<AccountId>, Self::Error> {
-        let derived_addresses = self
-            .get_accounts()?
-            .into_iter()
-            .map(|account| account.address)
-            .collect();
-        Ok(derived_addresses)
+    fn signer_addresses(&self) -> Vec<AccountId> {
+        self.get_accounts()
+            .iter()
+            .map(|account| account.address.clone())
+            .collect()
    }

-    fn get_accounts(&self) -> Result<Vec<AccountData>, Self::Error>;
+    fn get_accounts(&self) -> &[AccountData];

-    fn find_account(&self, signer_address: &AccountId) -> Result<AccountData, Self::Error> {
-        // TODO: we could really use some zeroize action here
-        let accounts = self.get_accounts()?;
-        accounts
-            .into_iter()
+    fn find_account(&self, signer_address: &AccountId) -> Result<&AccountData, Self::Error> {
+        self.get_accounts()
+            .iter()
            .find(|account| &account.address == signer_address)
            .ok_or_else(|| {
                SigningError::AccountNotFound {
@@ -76,7 +71,7 @@ pub trait OfflineSigner {
        message: M,
    ) -> Result<Signature, Self::Error> {
        let signer = self.find_account(signer_address)?;
-        self.sign_raw_with_account(&signer, message)
+        self.sign_raw_with_account(signer, message)
    }

    fn sign_direct(
@@ -85,7 +80,7 @@ pub trait OfflineSigner {
        sign_doc: SignDoc,
    ) -> Result<tx::Raw, Self::Error> {
        let signer = self.find_account(signer_address)?;
-        self.sign_direct_with_account(&signer, sign_doc)
+        self.sign_direct_with_account(signer, sign_doc)
    }

    // unless explicitly defined, each signing method is unsupported
@@ -122,7 +117,7 @@ pub struct NoSigner;
 // impl OfflineSigner for NoSigner {
 //     type Error = SignerUnavailable;
 //
-//     fn get_accounts(&self) -> Result<Vec<AccountData>, Self::Error> {
+//     fn get_accounts(&self) -> &[AccountData] {
 //         return Err(SignerUnavailable);
 //     }
 // }
@@ -50,7 +50,7 @@ pub trait TxSigner: OfflineSigner {
        )
        .map_err(|source| SigningError::SignDocFailure { source })?;

-        self.sign_direct_with_account(&account_from_signer, sign_doc)
+        self.sign_direct_with_account(account_from_signer, sign_doc)
    }
 }

@@ -3,6 +3,7 @@

 use clap::Parser;
 use nym_validator_client::signing::direct_wallet::DirectSecp256k1HdWallet;
+use nym_validator_client::signing::signer::OfflineSigner;

 #[derive(Debug, Parser)]
 pub struct Args {
@@ -15,9 +16,10 @@ pub fn create_account(args: Args, prefix: &str) {
    let word_count = args.word_count.unwrap_or(24);
    let mnemonic = bip39::Mnemonic::generate(word_count).expect("failed to generate mnemonic!");

-    let wallet = DirectSecp256k1HdWallet::from_mnemonic(prefix, mnemonic);
+    let wallet = DirectSecp256k1HdWallet::checked_from_mnemonic(prefix, mnemonic)
+        .expect("failed to derive accounts!");

    // Output address and mnemonics into separate lines for easier parsing
    println!("{}", wallet.mnemonic_string().as_str());
-    println!("{}", wallet.try_derive_accounts().unwrap()[0].address());
+    println!("{}", wallet.signer_addresses()[0]);
 }
@@ -1,13 +1,13 @@
 // Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

+use crate::context::QueryClient;
+use crate::utils::show_error;
 use clap::Parser;
 use log::{error, info};
 use nym_validator_client::nyxd::{AccountId, CosmWasmClient};
 use nym_validator_client::signing::direct_wallet::DirectSecp256k1HdWallet;
-
-use crate::context::QueryClient;
-use crate::utils::show_error;
+use nym_validator_client::signing::signer::OfflineSigner;

 #[derive(Debug, Parser)]
 pub struct Args {
@@ -50,20 +50,19 @@ pub async fn get_pubkey(
 }

 pub fn get_pubkey_from_mnemonic(address: AccountId, prefix: &str, mnemonic: bip39::Mnemonic) {
-    let wallet = DirectSecp256k1HdWallet::from_mnemonic(prefix, mnemonic);
-    match wallet.try_derive_accounts() {
-        Ok(accounts) => match accounts.iter().find(|a| *a.address() == address) {
-            Some(account) => {
-                println!("{}", account.public_key().to_string());
-            }
-            None => {
-                error!("Could not derive key that matches {address}")
-            }
-        },
-        Err(e) => {
-            error!("Failed to derive accounts. {e}");
+    let wallet = match DirectSecp256k1HdWallet::checked_from_mnemonic(prefix, mnemonic) {
+        Ok(wallet) => wallet,
+        Err(err) => {
+            error!("Failed to derive accounts. {err}");
+            return;
        }
-    }
+    };
+
+    let Ok(account) = wallet.find_account(&address) else {
+        error!("Could not derive key that matches {address}");
+        return;
+    };
+    println!("{}", account.public_key().to_string());
 }

 pub async fn get_pubkey_from_chain(address: AccountId, client: &QueryClient) {
@@ -36,32 +36,35 @@ pub fn sign(args: Args, prefix: &str, mnemonic: Option<bip39::Mnemonic>) {
        return;
    }

-    let wallet =
-        DirectSecp256k1HdWallet::from_mnemonic(prefix, mnemonic.expect("mnemonic not set"));
-    match wallet.try_derive_accounts() {
-        Ok(accounts) => match accounts.first() {
-            Some(account) => {
-                let msg = args.message.into_bytes();
-                match wallet.sign_raw_with_account(account, msg) {
-                    Ok(signature) => {
-                        let output = SignatureOutputJson {
-                            account_id: account.address().to_string(),
-                            public_key: account.public_key(),
-                            signature_as_hex: signature.to_string(),
-                        };
-                        println!("{}", json!(output));
-                    }
-                    Err(e) => {
-                        error!("Failed to sign message. {e}");
-                    }
+    let wallet = match DirectSecp256k1HdWallet::checked_from_mnemonic(
+        prefix,
+        mnemonic.expect("mnemonic not set"),
+    ) {
+        Ok(wallet) => wallet,
+        Err(err) => {
+            error!("Could not derive an account key from the mnemonic: {err}");
+            return;
+        }
+    };
+    match wallet.get_accounts().first() {
+        Some(account) => {
+            let msg = args.message.into_bytes();
+            match wallet.sign_raw_with_account(account, msg) {
+                Ok(signature) => {
+                    let output = SignatureOutputJson {
+                        account_id: account.address().to_string(),
+                        public_key: account.public_key(),
+                        signature_as_hex: signature.to_string(),
+                    };
+                    println!("{}", json!(output));
+                }
+                Err(e) => {
+                    error!("Failed to sign message. {e}");
                }
            }
-            None => {
-                error!("Could not derive an account key from the mnemonic",)
-            }
-        },
-        Err(e) => {
-            error!("Failed to derive accounts. {e}");
+        }
+        None => {
+            error!("Could not derive an account key from the mnemonic",)
        }
    }
 }
@@ -1,6 +1,7 @@
 // Copyright 2025 Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: GPL-3.0-only

+use nym_crypto::asymmetric::ed25519;
 use nym_ecash_signer_check::SignerCheckError;
 use nym_validator_client::coconut::EcashApiError;
 use nym_validator_client::nym_api::{EpochId, error::NymAPIError};
@@ -168,6 +169,24 @@ 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 attester public key is malformed: {source}")]
+    MalformedAttestationCheckUrl { source: url::ParseError },
+
+    #[error(
+        "the attester public key has not been provided through either the CLI nor the default .env config"
+    )]
+    AttesterPublicKeyNotSet,
+
+    #[error("the provided attester public key is malformed: {source}")]
+    MalformedAttesterPublicKey {
+        source: ed25519::Ed25519RecoveryError,
+    },
 }

 impl From<NymAPIError> for CredentialProxyError {
@@ -14,6 +14,7 @@ bincode = { workspace = true, optional = true }
 log = { workspace = true }
 thiserror = { workspace = true }
 serde = { workspace = true, features = ["derive"], optional = true }
+time = { workspace = true }
 tokio = { workspace = true, features = ["sync"] }
 zeroize = { workspace = true, features = ["zeroize_derive"] }

@@ -5,10 +5,13 @@

 CREATE TABLE emergency_credential
 (
-    type       TEXT NOT NULL,
-
+    id         INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
+    type       TEXT    NOT NULL,
    -- don't define any strict schema on the content as it might be implementation-dependant
-    content    BLOB NOT NULL,
-
+    content    BLOB    NOT NULL,
    expiration TIMESTAMP WITHOUT TIME ZONE
-);
+);
+
+-- no point in allowing duplicate data
+CREATE UNIQUE INDEX emergency_credential_unique_type_content
+    ON emergency_credential (type, content);
@@ -2,8 +2,8 @@
 // SPDX-License-Identifier: Apache-2.0

 use crate::models::{
-    BasicTicketbookInformation, EmergencyCredential, RetrievedPendingTicketbook,
-    RetrievedTicketbook,
+    BasicTicketbookInformation, EmergencyCredential, EmergencyCredentialContent,
+    RetrievedPendingTicketbook, RetrievedTicketbook,
 };
 use nym_compact_ecash::scheme::coin_indices_signatures::AnnotatedCoinIndexSignature;
 use nym_compact_ecash::scheme::expiration_date_signatures::AnnotatedExpirationDateSignature;
@@ -25,6 +25,12 @@ pub struct MemoryEcachTicketbookManager {
    inner: Arc<RwLock<EcashCredentialManagerInner>>,
 }

+#[derive(Default)]
+struct InternalIdCounters {
+    next_ticketbook_id: i64,
+    next_emergency_credential_id: i64,
+}
+
 #[derive(Default)]
 struct EcashCredentialManagerInner {
    ticketbooks: HashMap<i64, RetrievedTicketbook>,
@@ -33,13 +39,21 @@ struct EcashCredentialManagerInner {
    coin_indices_sigs: HashMap<u64, Vec<AnnotatedCoinIndexSignature>>,
    expiration_date_sigs: HashMap<(u64, Date), Vec<AnnotatedExpirationDateSignature>>,
    emergency_credentials: HashMap<String, Vec<EmergencyCredential>>,
-    _next_id: i64,
+
+    // internal counters emulating assignment of an increasing id to new inserted database entries
+    internal_counters: InternalIdCounters,
 }

 impl EcashCredentialManagerInner {
-    fn next_id(&mut self) -> i64 {
-        let next = self._next_id;
-        self._next_id += 1;
+    fn next_ticketbook_id(&mut self) -> i64 {
+        let next = self.internal_counters.next_ticketbook_id;
+        self.internal_counters.next_ticketbook_id += 1;
+        next
+    }
+
+    fn next_emergency_credential_id(&mut self) -> i64 {
+        let next = self.internal_counters.next_emergency_credential_id;
+        self.internal_counters.next_emergency_credential_id += 1;
        next
    }
 }
@@ -174,7 +188,7 @@ impl MemoryEcachTicketbookManager {
        used_tickets: u32,
    ) {
        let mut guard = self.inner.write().await;
-        let id = guard.next_id();
+        let id = guard.next_ticketbook_id();

        #[allow(clippy::unwrap_used)]
        let mut nasty_clone = hack_clone_ticketbook(ticketbook);
@@ -288,13 +302,34 @@ impl MemoryEcachTicketbookManager {
        guard.emergency_credentials.get(typ)?.first().cloned()
    }

-    pub(crate) async fn insert_emergency_credential(&self, credential: &EmergencyCredential) {
+    pub(crate) async fn insert_emergency_credential(
+        &self,
+        credential: &EmergencyCredentialContent,
+    ) {
        let mut guard = self.inner.write().await;
+        let id = guard.next_emergency_credential_id();

        guard
            .emergency_credentials
            .entry(credential.typ.clone())
            .or_default()
-            .push(credential.clone());
+            .push(EmergencyCredential {
+                id,
+                data: credential.clone(),
+            });
+    }
+
+    pub(crate) async fn remove_emergency_credential(&self, id: i64) {
+        let mut guard = self.inner.write().await;
+
+        guard.emergency_credentials.retain(|_, credentials| {
+            credentials.retain(|c| c.id != id);
+            !credentials.is_empty()
+        })
+    }
+
+    pub(crate) async fn remove_emergency_credentials_of_type(&self, typ: &str) {
+        let mut guard = self.inner.write().await;
+        guard.emergency_credentials.remove(typ);
    }
 }
@@ -2,9 +2,9 @@
 // SPDX-License-Identifier: Apache-2.0

 use crate::models::{
-    BasicTicketbookInformation, EmergencyCredential, RawCoinIndexSignatures,
-    RawExpirationDateSignatures, RawVerificationKey, StoredIssuedTicketbook,
-    StoredPendingTicketbook,
+    BasicTicketbookInformation, EmergencyCredential, EmergencyCredentialContent,
+    RawCoinIndexSignatures, RawExpirationDateSignatures, RawVerificationKey,
+    StoredIssuedTicketbook, StoredPendingTicketbook,
 };
 use nym_ecash_time::Date;
 use sqlx::{Executor, Sqlite, Transaction};
@@ -317,7 +317,7 @@ impl SqliteEcashTicketbookManager {
                FROM emergency_credential
                WHERE type = ?
                  AND (expiration IS NULL OR expiration > CURRENT_TIMESTAMP)
-                ORDER BY expiration ASC NULLS LAST
+                ORDER BY expiration DESC NULLS LAST
                LIMIT 1
            "#,
        )
@@ -328,13 +328,14 @@ impl SqliteEcashTicketbookManager {

    pub(crate) async fn insert_emergency_credential(
        &self,
-        credential: &EmergencyCredential,
+        credential: &EmergencyCredentialContent,
    ) -> Result<(), sqlx::Error> {
        sqlx::query!(
            r#"
                INSERT INTO emergency_credential
                (type, content, expiration)
                VALUES (?, ?, ?)
+                ON CONFLICT(type, content) DO NOTHING;
            "#,
            credential.typ,
            credential.content,
@@ -344,6 +345,35 @@ impl SqliteEcashTicketbookManager {
        .await?;
        Ok(())
    }
+
+    pub(crate) async fn remove_emergency_credential(&self, id: i64) -> Result<(), sqlx::Error> {
+        sqlx::query!(
+            r#"
+                DELETE FROM emergency_credential
+                WHERE id = ?
+            "#,
+            id
+        )
+        .execute(&*self.connection_pool)
+        .await?;
+        Ok(())
+    }
+
+    pub(crate) async fn remove_emergency_credentials_of_type(
+        &self,
+        typ: &str,
+    ) -> Result<(), sqlx::Error> {
+        sqlx::query!(
+            r#"
+                DELETE FROM emergency_credential
+                WHERE type = ?
+            "#,
+            typ
+        )
+        .execute(&*self.connection_pool)
+        .await?;
+        Ok(())
+    }
 }

 pub(crate) async fn get_next_unspent_ticketbook<'a, E>(
@@ -4,8 +4,8 @@
 use crate::backends::memory::MemoryEcachTicketbookManager;
 use crate::error::StorageError;
 use crate::models::{
-    BasicTicketbookInformation, EmergencyCredential, RetrievedPendingTicketbook,
-    RetrievedTicketbook,
+    BasicTicketbookInformation, EmergencyCredential, EmergencyCredentialContent,
+    RetrievedPendingTicketbook, RetrievedTicketbook,
 };
 use crate::storage::Storage;
 use async_trait::async_trait;
@@ -231,13 +231,28 @@ impl Storage for EphemeralStorage {

    async fn insert_emergency_credential(
        &self,
-        credential: &EmergencyCredential,
+        credential: &EmergencyCredentialContent,
    ) -> Result<(), Self::StorageError> {
        self.storage_manager
            .insert_emergency_credential(credential)
            .await;
        Ok(())
    }
+
+    async fn remove_emergency_credential(&self, id: i64) -> Result<(), Self::StorageError> {
+        self.storage_manager.remove_emergency_credential(id).await;
+        Ok(())
+    }
+
+    async fn remove_emergency_credentials_of_type(
+        &self,
+        typ: &str,
+    ) -> Result<(), Self::StorageError> {
+        self.storage_manager
+            .remove_emergency_credentials_of_type(typ)
+            .await;
+        Ok(())
+    }
 }

 #[cfg(test)]
@@ -3,7 +3,7 @@

 use nym_credentials::{IssuanceTicketBook, IssuedTicketBook};
 use nym_ecash_time::Date;
-use sqlx::types::time::OffsetDateTime;
+use time::OffsetDateTime;
 use zeroize::{Zeroize, ZeroizeOnDrop};

 pub struct RetrievedTicketbook {
@@ -83,6 +83,14 @@ pub struct RawVerificationKey {
 #[derive(Clone, Debug)]
 #[cfg_attr(not(target_arch = "wasm32"), derive(sqlx::FromRow))]
 pub struct EmergencyCredential {
+    pub id: i64,
+    #[cfg_attr(not(target_arch = "wasm32"), sqlx(flatten))]
+    pub data: EmergencyCredentialContent,
+}
+
+#[derive(Clone, Debug)]
+#[cfg_attr(not(target_arch = "wasm32"), derive(sqlx::FromRow))]
+pub struct EmergencyCredentialContent {
    #[cfg_attr(not(target_arch = "wasm32"), sqlx(rename = "type"))]
    pub typ: String,
    pub content: Vec<u8>,
@@ -3,7 +3,7 @@

 mod legacy_helpers;

-use crate::models::EmergencyCredential;
+use crate::models::{EmergencyCredential, EmergencyCredentialContent};
 use crate::{
    backends::sqlite::{
        get_next_unspent_ticketbook, increase_used_ticketbook_tickets, SqliteEcashTicketbookManager,
@@ -412,11 +412,26 @@ impl Storage for PersistentStorage {

    async fn insert_emergency_credential(
        &self,
-        credential: &EmergencyCredential,
+        credential: &EmergencyCredentialContent,
    ) -> Result<(), Self::StorageError> {
        self.storage_manager
            .insert_emergency_credential(credential)
            .await?;
        Ok(())
    }
+
+    async fn remove_emergency_credential(&self, id: i64) -> Result<(), Self::StorageError> {
+        self.storage_manager.remove_emergency_credential(id).await?;
+        Ok(())
+    }
+
+    async fn remove_emergency_credentials_of_type(
+        &self,
+        typ: &str,
+    ) -> Result<(), Self::StorageError> {
+        self.storage_manager
+            .remove_emergency_credentials_of_type(typ)
+            .await?;
+        Ok(())
+    }
 }
@@ -2,8 +2,8 @@
 // SPDX-License-Identifier: Apache-2.0

 use crate::models::{
-    BasicTicketbookInformation, EmergencyCredential, RetrievedPendingTicketbook,
-    RetrievedTicketbook,
+    BasicTicketbookInformation, EmergencyCredential, EmergencyCredentialContent,
+    RetrievedPendingTicketbook, RetrievedTicketbook,
 };
 use async_trait::async_trait;
 use nym_compact_ecash::VerificationKeyAuth;
@@ -119,6 +119,13 @@ pub trait Storage: Clone + Send + Sync {

    async fn insert_emergency_credential(
        &self,
-        credential: &EmergencyCredential,
+        credential: &EmergencyCredentialContent,
+    ) -> Result<(), Self::StorageError>;
+
+    async fn remove_emergency_credential(&self, id: i64) -> Result<(), Self::StorageError>;
+
+    async fn remove_emergency_credentials_of_type(
+        &self,
+        typ: &str,
    ) -> Result<(), Self::StorageError>;
 }
@@ -26,6 +26,7 @@ tracing = { workspace = true }
 nym-api-requests = { path = "../../nym-api/nym-api-requests" }
 nym-credentials = { path = "../credentials" }
 nym-credentials-interface = { path = "../credentials-interface" }
+nym-crypto = { path = "../crypto", features = ["asymmetric"] }
 nym-ecash-contract-common = { path = "../cosmwasm-smart-contracts/ecash-contract" }
 nym-gateway-requests = { path = "../gateway-requests" }
 nym-gateway-storage = { path = "../gateway-storage" }
@@ -13,6 +13,7 @@ use tracing::*;

 pub use client_bandwidth::*;
 pub use error::*;
+pub use upgrade_mode::UpgradeModeState;

 pub mod bandwidth_storage_manager;
 mod client_bandwidth;
@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0

 use futures::channel::mpsc::{UnboundedReceiver, UnboundedSender};
+use nym_crypto::asymmetric::ed25519;
 use nym_upgrade_mode_check::{
    CREDENTIAL_PROXY_JWT_ISSUER, UpgradeModeAttestation, validate_upgrade_mode_jwt,
 };
@@ -11,7 +12,7 @@ use std::time::Duration;
 use thiserror::Error;
 use time::OffsetDateTime;
 use tokio::sync::{Notify, RwLock};
-use tracing::{debug, error};
+use tracing::{debug, error, info};

 #[derive(Debug, Error)]
 pub enum UpgradeModeEnableError {
@@ -100,6 +101,10 @@ impl UpgradeModeDetails {
        }
    }

+    pub fn state(&self) -> &UpgradeModeState {
+        &self.state
+    }
+
    pub fn enabled(&self) -> bool {
        self.state.upgrade_mode_enabled()
    }
@@ -137,11 +142,11 @@ impl UpgradeModeDetails {
        }

        // first validate whether the received JWT is even valid
-        // note: we expect the token has been signed by our credential proxy
-        // (in the future, we won't care about it, and we'll have proper key discovery endpoint. 2026™️)
        let attestation = validate_upgrade_mode_jwt(&token, Some(CREDENTIAL_PROXY_JWT_ISSUER))?;

        // send request to revalidate internal state
+        // this will, among other things, pull fresh attestation from the configured endpoint
+        // and also verify required signatures (and pubkeys)
        self.request_recheck().await;

        // not strictly necessary, but check if provided attestation actually matches the one retrieved
@@ -155,6 +160,7 @@ impl UpgradeModeDetails {

        // note: if attestation has been returned, it means we're definitely in upgrade mode
        // (otherwise it wouldn't have existed in the state)
+        info!("managed to initialise upgrade mode through received JWT");

        Ok(())
    }
@@ -186,9 +192,10 @@ impl UpgradeModeStatus {
 }

 impl UpgradeModeState {
-    pub fn new_empty() -> UpgradeModeState {
+    pub fn new(attester_public_key: ed25519::PublicKey) -> UpgradeModeState {
        UpgradeModeState {
            inner: Arc::new(UpgradeModeStateInner {
+                expected_attester_public_key: attester_public_key,
                expected_attestation: RwLock::new(None),
                last_queried_ts: AtomicI64::new(OffsetDateTime::UNIX_EPOCH.unix_timestamp()),
                status: UpgradeModeStatus(Arc::new(AtomicBool::new(false))),
@@ -196,22 +203,34 @@ impl UpgradeModeState {
        }
    }

+    pub fn attester_pubkey(&self) -> ed25519::PublicKey {
+        self.inner.expected_attester_public_key
+    }
+
    pub async fn attestation(&self) -> Option<UpgradeModeAttestation> {
        self.inner.expected_attestation.read().await.clone()
    }

-    pub async fn set_expected_attestation(
+    pub async fn try_set_expected_attestation(
        &self,
        expected_attestation: Option<UpgradeModeAttestation>,
    ) {
-        let mut guard = self.inner.expected_attestation.write().await;
        // make sure to only enable upgrade mode flag AFTER we have written the expected value
        // (or still hold the exclusive lock as in this instance)
-        if expected_attestation.is_some() {
+        let mut guard = self.inner.expected_attestation.write().await;
+
+        // ensure that the attestation had been signed with the expected key
+        if let Some(attestation) = expected_attestation.as_ref() {
+            if attestation.content.attester_public_key != self.inner.expected_attester_public_key {
+                self.update_last_queried(OffsetDateTime::now_utc());
+                return;
+            }
+
            self.enable_upgrade_mode()
        } else {
            self.disable_upgrade_mode()
        }
+
        self.update_last_queried(OffsetDateTime::now_utc());
        *guard = expected_attestation;
    }
@@ -256,6 +275,9 @@ impl UpgradeModeState {
 }

 struct UpgradeModeStateInner {
+    /// Expected public key of the entity issuing upgrade mode attestations.
+    expected_attester_public_key: ed25519::PublicKey,
+
    /// Contents of the published upgrade mode attestation, as queried by this node
    expected_attestation: RwLock<Option<UpgradeModeAttestation>>,

@@ -30,7 +30,14 @@ pub use nym_compact_ecash::{
 };
 pub use nym_ecash_time::{EcashTime, ecash_today};
 pub use nym_network_defaults::TicketTypeRepr;
-pub use nym_upgrade_mode_check::UpgradeModeAttestation;
+use nym_network_defaults::TicketTypeRepr::V1MixnetEntry;
+
+/// Default bandwidth amount under which [mixnet] clients will attempt to send additional zk-nyms
+/// to increase their allowance.
+// currently defined as 20% of entry ticket value
+// clients are, of course, free to override this value
+pub const DEFAULT_MIXNET_REQUEST_BANDWIDTH_THRESHOLD: i64 =
+    (V1MixnetEntry.bandwidth_value() / 5) as i64;

 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
 pub enum BandwidthCredential {
@@ -13,7 +13,7 @@ use thiserror::Error;
 use time::OffsetDateTime;

 // specific errors (that should not be nested!!) for clients to match on
-#[derive(Debug, Copy, Clone, Error, Serialize, Deserialize)]
+#[derive(Debug, Copy, Clone, Error, Serialize, Deserialize, PartialEq)]
 #[serde(rename_all = "snake_case")]
 pub enum SimpleGatewayRequestsError {
    #[error("insufficient bandwidth available to process the request. required: {required}B, available: {available}B")]
@@ -46,8 +46,7 @@ impl SensitiveServerResponse {
    }
 }

-#[derive(Serialize, Deserialize, Debug)]
-#[serde(tag = "type", rename_all = "camelCase")]
+#[derive(Serialize, Deserialize, Debug, PartialEq)]
 pub struct BandwidthResponse {
    pub available_total: i64,

@@ -57,8 +56,7 @@ pub struct BandwidthResponse {
    pub upgrade_mode: bool,
 }

-#[derive(Serialize, Deserialize, Debug)]
-#[serde(tag = "type", rename_all = "camelCase")]
+#[derive(Serialize, Deserialize, Debug, PartialEq)]
 pub struct SendResponse {
    pub remaining_bandwidth: i64,

@@ -68,7 +66,7 @@ pub struct SendResponse {
    pub upgrade_mode: bool,
 }

-#[derive(Serialize, Deserialize, Debug)]
+#[derive(Serialize, Deserialize, Debug, PartialEq)]
 #[serde(tag = "type", rename_all = "camelCase")]
 #[non_exhaustive]
 pub enum ServerResponse {
@@ -166,3 +164,79 @@ impl TryFrom<String> for ServerResponse {
        serde_json::from_str(&msg)
    }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn server_response_serde_compat() {
+        // make sure new serialisation is identical and compatible
+        #[derive(Serialize, Deserialize, Debug, PartialEq)]
+        #[serde(tag = "type", rename_all = "camelCase")]
+        #[non_exhaustive]
+        pub enum OldServerResponse {
+            Bandwidth { available_total: i64 },
+            Send { remaining_bandwidth: i64 },
+        }
+
+        // OLD => NEW
+        let old_bandwidth = OldServerResponse::Bandwidth {
+            available_total: 100,
+        };
+        let old_send = OldServerResponse::Send {
+            remaining_bandwidth: 100,
+        };
+
+        let old_bandwidth_str = serde_json::to_string(&old_bandwidth).unwrap();
+        let old_send_str = serde_json::to_string(&old_send).unwrap();
+
+        let recovered_bandwidth = ServerResponse::try_from(old_bandwidth_str).unwrap();
+        assert_eq!(
+            recovered_bandwidth,
+            ServerResponse::Bandwidth(BandwidthResponse {
+                available_total: 100,
+                upgrade_mode: false
+            })
+        );
+
+        let recovered_send = ServerResponse::try_from(old_send_str).unwrap();
+        assert_eq!(
+            recovered_send,
+            ServerResponse::Send(SendResponse {
+                remaining_bandwidth: 100,
+                upgrade_mode: false
+            })
+        );
+
+        // NEW => OLD
+        let new_bandwidth = ServerResponse::Bandwidth(BandwidthResponse {
+            available_total: 100,
+            upgrade_mode: false,
+        });
+        let new_send = ServerResponse::Send(SendResponse {
+            remaining_bandwidth: 100,
+            upgrade_mode: false,
+        });
+
+        let new_bandwidth_str = serde_json::to_string(&new_bandwidth).unwrap();
+        let new_send_str = serde_json::to_string(&new_send).unwrap();
+
+        let recovered_bandwidth: OldServerResponse =
+            serde_json::from_str(&new_bandwidth_str).unwrap();
+        assert_eq!(
+            recovered_bandwidth,
+            OldServerResponse::Bandwidth {
+                available_total: 100
+            }
+        );
+
+        let recovered_send: OldServerResponse = serde_json::from_str(&new_send_str).unwrap();
+        assert_eq!(
+            recovered_send,
+            OldServerResponse::Send {
+                remaining_bandwidth: 100
+            }
+        );
+    }
+}
@@ -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/");
@@ -55,7 +55,10 @@ pub const NYM_APIS: &[ApiUrlConst] = &[

 pub const NYM_VPN_API: &str = "https://nymvpn.com/api/";

-pub const UPGRADE_MOST_ATTESTATION_URL: &str = "https://nym.com/upgrade-mode/attestation.json";
+pub const UPGRADE_MODE_ATTESTATION_URL: &str =
+    "https://nymtech.net/.wellknown/upgrade-mode/attestation.json";
+pub const UPGRADE_MODE_ATTESTER_ED25519_BS58_PUBKEY: &str =
+    "3bgffBYcfFkTTXc2npNNn9MkddFZ3H2LrPjXDmnJzrqd";

 #[cfg(feature = "network")]
 pub const NYM_VPN_APIS: &[ApiUrlConst] = &[
@@ -163,8 +166,12 @@ pub fn export_to_env() {
    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_MOST_ATTESTATION_URL,
-        UPGRADE_MOST_ATTESTATION_URL,
+        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,
    );
 }

@@ -207,7 +214,11 @@ pub fn export_to_env_if_not_set() {
    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_MOST_ATTESTATION_URL,
-        UPGRADE_MOST_ATTESTATION_URL,
+        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,7 +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_MOST_ATTESTATION_URL: &str = "UPGRADE_MOST_ATTESTATION_URL";
+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,27 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "\n        INSERT INTO transaction\n        (hash, height, index, success, messages, memo, signatures, signer_infos, fee, gas_wanted, gas_used, raw_log, logs, events)\n        VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14)\n        ON CONFLICT (hash) DO UPDATE\n            SET height = excluded.height,\n                index = excluded.index,\n                success = excluded.success,\n                messages = excluded.messages,\n                memo = excluded.memo,\n                signatures = excluded.signatures,\n                signer_infos = excluded.signer_infos,\n                fee = excluded.fee,\n                gas_wanted = excluded.gas_wanted,\n                gas_used = excluded.gas_used,\n                raw_log = excluded.raw_log,\n                logs = excluded.logs,\n                events = excluded.events\n        ",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Left": [
+        "Text",
+        "Int8",
+        "Int4",
+        "Bool",
+        "Jsonb",
+        "Text",
+        "TextArray",
+        "Jsonb",
+        "Jsonb",
+        "Int8",
+        "Int8",
+        "Text",
+        "Jsonb",
+        "Jsonb"
+      ]
+    },
+    "nullable": []
+  },
+  "hash": "08f4e54ac24fccd54f4208797b3749e457f8cd4ba3d7d906a7ab3bf5b4e7dc9c"
+}
@@ -0,0 +1,15 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "\n            INSERT INTO validator (consensus_address, consensus_pubkey)\n            VALUES ($1, $2)\n            ON CONFLICT DO NOTHING\n        ",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Left": [
+        "Text",
+        "Text"
+      ]
+    },
+    "nullable": []
+  },
+  "hash": "0d3709efacf763b06bf14803bb803b5ee5b27879b0026bb0480b3f2722318a75"
+}
@@ -0,0 +1,14 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "DELETE FROM pre_commit WHERE height < $1",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Left": [
+        "Int8"
+      ]
+    },
+    "nullable": []
+  },
+  "hash": "1c2fb0e9ffceca21ef8dbea19b116422b1f723d0a316314b50c43c8b29f8891d"
+}
@@ -0,0 +1,20 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "\n                SELECT height\n                FROM block\n                ORDER BY height ASC\n                LIMIT 1\n            ",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "height",
+        "type_info": "Int8"
+      }
+    ],
+    "parameters": {
+      "Left": []
+    },
+    "nullable": [
+      false
+    ]
+  },
+  "hash": "2561fb016951ea4cd29e43fb9a4a93e944b0d44ed1f7c1036f306e34372da11c"
+}
@@ -0,0 +1,14 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "UPDATE metadata SET last_processed_height = GREATEST(last_processed_height, $1)",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Left": [
+        "Int8"
+      ]
+    },
+    "nullable": []
+  },
+  "hash": "2679cdf11fa66c7920678cde860c57402119ec7c3aae731b0da831327301466f"
+}
@@ -0,0 +1,14 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "UPDATE pruning SET last_pruned_height = $1",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Left": [
+        "Int8"
+      ]
+    },
+    "nullable": []
+  },
+  "hash": "36ba5941aca6e7b604a10b8b0aba70635028f392fe794d6131827b083e1755e1"
+}
--- a/Show More
+++ b/Show More